StaticShadowDepthMapMaxSamples

StaticShadowDepthMapMaxSamples

#Overview

name: StaticShadowDepthMapMaxSamples

The value of this variable can be defined or overridden in .ini config files. 1 .ini config file referencing this setting variable.

It is referenced in 9 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of StaticShadowDepthMapMaxSamples is to limit the maximum number of samples generated for static shadow depth maps in Unreal Engine’s lighting system. This variable is used to control memory usage and performance when generating shadow maps for static lighting.

This setting variable is primarily used in the GPULightmass plugin and the UnrealLightmass program, which are both part of Unreal Engine’s lighting and global illumination system. It’s specifically used in the rendering of static shadow depth maps for different types of lights, including directional, spot, point, and rect lights.

The value of this variable is typically set in the Lightmass configuration file (Lightmass.ini) under the [DevOptions.StaticShadows] section. It’s read during the scene export process in the Lightmass exporter.

StaticShadowDepthMapMaxSamples interacts with other variables such as ShadowMapSizeX and ShadowMapSizeY. When the product of these two size variables exceeds StaticShadowDepthMapMaxSamples, the shadow map size is adjusted to fit within the maximum sample limit while maintaining the aspect ratio.

Developers should be aware that this variable directly impacts the quality and memory usage of static shadows. A higher value allows for more detailed shadow maps but increases memory consumption and potentially rendering time. Conversely, a lower value reduces memory usage but may result in lower quality shadows.

Best practices when using this variable include:

  1. Balancing shadow quality with performance and memory constraints.
  2. Considering the scale and complexity of your scene when setting this value.
  3. Testing different values to find the optimal balance for your specific project.
  4. Being mindful of platform limitations, especially for projects targeting mobile or lower-end hardware.
  5. Coordinating this setting with other shadow-related variables to achieve the desired visual quality and performance.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseLightmass.ini:151, section: [DevOptions.StaticShadows]

#References in C++ code

#Callsites

This variable is referenced in the following C++ source code:

#Loc: <Workspace>/Engine/Plugins/Experimental/GPULightmass/Source/GPULightmass/Private/Scene/Lights.cpp:415

Scope (from outer to inner):

file
namespace    GPULightmass
function     void FDirectionalLightRenderState::RenderStaticShadowDepthMap

Source code excerpt:

	int32 ShadowMapSizeY = FMath::TruncToInt(FMath::Max(LightSpaceImportanceBounds.GetExtent().Y * 2.0f * ClampedResolutionScale / StaticShadowDepthMapTransitionSampleDistanceY, 4.0f));

	const uint64 StaticShadowDepthMapMaxSamples = 16777216;
	
	// Clamp the number of dominant shadow samples generated if necessary while maintaining aspect ratio
	if ((uint64)ShadowMapSizeX * (uint64)ShadowMapSizeY > StaticShadowDepthMapMaxSamples)
	{
		const float AspectRatio = ShadowMapSizeX / (float)ShadowMapSizeY;
		ShadowMapSizeY = FMath::TruncToInt(FMath::Sqrt(StaticShadowDepthMapMaxSamples / AspectRatio));
		ShadowMapSizeX = FMath::TruncToInt(StaticShadowDepthMapMaxSamples / (float)ShadowMapSizeY);
	}
	
	FRDGTextureRef DepthMapTexture = GraphBuilder.CreateTexture(
		FRDGTextureDesc::Create2D(
			FIntPoint{ShadowMapSizeX, ShadowMapSizeY},
			PF_R16F,

#Loc: <Workspace>/Engine/Plugins/Experimental/GPULightmass/Source/GPULightmass/Private/Scene/Lights.cpp:523

Scope (from outer to inner):

file
namespace    GPULightmass
function     void FSpotLightRenderState::RenderStaticShadowDepthMap

Source code excerpt:

	int32 ShadowMapSizeY = ShadowMapSizeX;

	const uint64 StaticShadowDepthMapMaxSamples = 16777216;
	
	// Clamp the number of dominant shadow samples generated if necessary while maintaining aspect ratio
	if ((uint64)ShadowMapSizeX * (uint64)ShadowMapSizeY > StaticShadowDepthMapMaxSamples)
	{
		const float AspectRatio = ShadowMapSizeX / (float)ShadowMapSizeY;
		ShadowMapSizeY = FMath::TruncToInt(FMath::Sqrt(StaticShadowDepthMapMaxSamples / AspectRatio));
		ShadowMapSizeX = FMath::TruncToInt(StaticShadowDepthMapMaxSamples / (float)ShadowMapSizeY);
	}
	
	FRDGTextureRef DepthMapTexture = GraphBuilder.CreateTexture(
		FRDGTextureDesc::Create2D(
			FIntPoint{ShadowMapSizeX, ShadowMapSizeY},
			PF_R16F,

#Loc: <Workspace>/Engine/Plugins/Experimental/GPULightmass/Source/GPULightmass/Private/Scene/Lights.cpp:629

Scope (from outer to inner):

file
namespace    GPULightmass
function     void FPointLightRenderState::RenderStaticShadowDepthMap

Source code excerpt:

	int32 ShadowMapSizeY = ShadowMapSizeX;

	const uint64 StaticShadowDepthMapMaxSamples = 16777216;
	
	// Clamp the number of dominant shadow samples generated if necessary while maintaining aspect ratio
	if ((uint64)ShadowMapSizeX * (uint64)ShadowMapSizeY > StaticShadowDepthMapMaxSamples)
	{
		const float AspectRatio = ShadowMapSizeX / (float)ShadowMapSizeY;
		ShadowMapSizeY = FMath::TruncToInt(FMath::Sqrt(StaticShadowDepthMapMaxSamples / AspectRatio));
		ShadowMapSizeX = FMath::TruncToInt(StaticShadowDepthMapMaxSamples / (float)ShadowMapSizeY);
	}
	
	FRDGTextureRef DepthMapTexture = GraphBuilder.CreateTexture(
		FRDGTextureDesc::Create2D(
			FIntPoint{ShadowMapSizeX, ShadowMapSizeY},
			PF_R16F,

#Loc: <Workspace>/Engine/Plugins/Experimental/GPULightmass/Source/GPULightmass/Private/Scene/Lights.cpp:723

Scope (from outer to inner):

file
namespace    GPULightmass
function     void FRectLightRenderState::RenderStaticShadowDepthMap

Source code excerpt:

	int32 ShadowMapSizeY = ShadowMapSizeX;

	const uint64 StaticShadowDepthMapMaxSamples = 16777216;
	
	// Clamp the number of dominant shadow samples generated if necessary while maintaining aspect ratio
	if ((uint64)ShadowMapSizeX * (uint64)ShadowMapSizeY > StaticShadowDepthMapMaxSamples)
	{
		const float AspectRatio = ShadowMapSizeX / (float)ShadowMapSizeY;
		ShadowMapSizeY = FMath::TruncToInt(FMath::Sqrt(StaticShadowDepthMapMaxSamples / AspectRatio));
		ShadowMapSizeX = FMath::TruncToInt(StaticShadowDepthMapMaxSamples / (float)ShadowMapSizeY);
	}
	
	FRDGTextureRef DepthMapTexture = GraphBuilder.CreateTexture(
		FRDGTextureDesc::Create2D(
			FIntPoint{ShadowMapSizeX, ShadowMapSizeY},
			PF_R16F,

#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/Lightmass/Lightmass.cpp:2321

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.StaticShadows"), TEXT("StaticShadowDepthMapTransitionSampleDistanceY"), Scene.ShadowSettings.StaticShadowDepthMapTransitionSampleDistanceY, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.StaticShadows"), TEXT("StaticShadowDepthMapSuperSampleFactor"), Scene.ShadowSettings.StaticShadowDepthMapSuperSampleFactor, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.StaticShadows"), TEXT("StaticShadowDepthMapMaxSamples"), Scene.ShadowSettings.StaticShadowDepthMapMaxSamples, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.StaticShadows"), TEXT("MinUnoccludedFraction"), Scene.ShadowSettings.MinUnoccludedFraction, GLightmassIni));
	}
	{
		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.ImportanceTracing"), TEXT("bUseStratifiedSampling"), bConfigBool, GLightmassIni));
		Scene.ImportanceTracingSettings.bUseStratifiedSampling = bConfigBool;
		VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.ImportanceTracing"), TEXT("NumHemisphereSamples"), Scene.ImportanceTracingSettings.NumHemisphereSamples, GLightmassIni));

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/LightingSystem.cpp:2112

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingSystem::ValidateSettings
function     void FStaticLightingSystem::CalculateStaticShadowDepthMap

Source code excerpt:


		// Clamp the number of dominant shadow samples generated if necessary while maintaining aspect ratio
		if ((uint64)ShadowDepthMap->ShadowMapSizeX * (uint64)ShadowDepthMap->ShadowMapSizeY > (uint64)ShadowSettings.StaticShadowDepthMapMaxSamples)
		{
			const float AspectRatio = ShadowDepthMap->ShadowMapSizeX / (float)ShadowDepthMap->ShadowMapSizeY;
			ShadowDepthMap->ShadowMapSizeY = FMath::TruncToInt(FMath::Sqrt(ShadowSettings.StaticShadowDepthMapMaxSamples / AspectRatio));
			ShadowDepthMap->ShadowMapSizeX = FMath::TruncToInt((float)ShadowSettings.StaticShadowDepthMapMaxSamples / (float)ShadowDepthMap->ShadowMapSizeY);
		}

		// Allocate the shadow map
		ShadowDepthMap->ShadowMap.Empty(ShadowDepthMap->ShadowMapSizeX * ShadowDepthMap->ShadowMapSizeY);
		ShadowDepthMap->ShadowMap.AddZeroed(ShadowDepthMap->ShadowMapSizeX * ShadowDepthMap->ShadowMapSizeY);

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/LightingSystem.cpp:2204

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingSystem::ValidateSettings
function     void FStaticLightingSystem::CalculateStaticShadowDepthMap

Source code excerpt:


		// Clamp the number of dominant shadow samples generated if necessary while maintaining aspect ratio
		if ((uint64)ShadowDepthMap->ShadowMapSizeX * (uint64)ShadowDepthMap->ShadowMapSizeY > (uint64)ShadowSettings.StaticShadowDepthMapMaxSamples)
		{
			const float AspectRatio = ShadowDepthMap->ShadowMapSizeX / (float)ShadowDepthMap->ShadowMapSizeY;
			ShadowDepthMap->ShadowMapSizeY = FMath::TruncToInt(FMath::Sqrt(ShadowSettings.StaticShadowDepthMapMaxSamples / AspectRatio));
			ShadowDepthMap->ShadowMapSizeX = FMath::TruncToInt((float)ShadowSettings.StaticShadowDepthMapMaxSamples / (float)ShadowDepthMap->ShadowMapSizeY);
		}

		ShadowDepthMap->ShadowMap.Empty(ShadowDepthMap->ShadowMapSizeX * ShadowDepthMap->ShadowMapSizeY);
		ShadowDepthMap->ShadowMap.AddZeroed(ShadowDepthMap->ShadowMapSizeX * ShadowDepthMap->ShadowMapSizeY);

		// Calculate the maximum possible distance for quantization

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/LightingSystem.cpp:2291

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingSystem::ValidateSettings
function     void FStaticLightingSystem::CalculateStaticShadowDepthMap

Source code excerpt:


		// Clamp the number of dominant shadow samples generated if necessary while maintaining aspect ratio
		if ((uint64)ShadowDepthMap->ShadowMapSizeX * (uint64)ShadowDepthMap->ShadowMapSizeY > (uint64)ShadowSettings.StaticShadowDepthMapMaxSamples)
		{
			const float AspectRatio = ShadowDepthMap->ShadowMapSizeX / (float)ShadowDepthMap->ShadowMapSizeY;
			ShadowDepthMap->ShadowMapSizeY = FMath::TruncToInt(FMath::Sqrt(ShadowSettings.StaticShadowDepthMapMaxSamples / AspectRatio));
			ShadowDepthMap->ShadowMapSizeX = FMath::TruncToInt((float)ShadowSettings.StaticShadowDepthMapMaxSamples / (float)ShadowDepthMap->ShadowMapSizeY);
		}

		// Allocate the shadow map
		ShadowDepthMap->ShadowMap.Empty(ShadowDepthMap->ShadowMapSizeX * ShadowDepthMap->ShadowMapSizeY);
		ShadowDepthMap->ShadowMap.AddZeroed(ShadowDepthMap->ShadowMapSizeX * ShadowDepthMap->ShadowMapSizeY);

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Public/SceneExport.h:494

Scope (from outer to inner):

file
namespace    Lightmass
class        class FStaticShadowSettings

Source code excerpt:


	/** Maximum number of dominant shadow samples to generate for one dominant light, used to limit memory used. */
	int32 StaticShadowDepthMapMaxSamples;

	/** Fraction of valid lighting samples (mapped texels or vertex samples) that must be unoccluded in a precomputed shadowmap for the shadowmap to be kept. */
	float MinUnoccludedFraction;
};

/**