StaticShadowDepthMapTransitionSampleDistanceX

StaticShadowDepthMapTransitionSampleDistanceX

#Overview

name: StaticShadowDepthMapTransitionSampleDistanceX

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 11 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of StaticShadowDepthMapTransitionSampleDistanceX is to control the resolution and quality of static shadow depth maps in Unreal Engine 5’s lighting system. It represents the distance in world space units between dominant light shadow map cells along the X-axis.

This setting variable is primarily used in the GPULightmass plugin and the Unreal Lightmass program, which are both part of Unreal Engine’s global illumination and static lighting calculation system. It affects how static shadows are generated for various types of lights, including directional, spot, point, and rectangular lights.

The value of this variable is typically set in the Lightmass configuration file (GLightmassIni) under the “DevOptions.StaticShadows” section. It is read during the scene export process for lightmap generation.

StaticShadowDepthMapTransitionSampleDistanceX interacts closely with StaticShadowDepthMapTransitionSampleDistanceY, which controls the same property along the Y-axis. Together, these variables determine the overall resolution of the shadow depth map.

Developers should be aware that:

  1. Lower values result in higher resolution shadow maps but increase memory usage and computation time.
  2. The variable is scaled by the scene’s static lighting scale, so changes to the overall lighting scale will affect this value.
  3. It’s used in calculations to determine the size of shadow maps for different light types, which is then clamped to ensure it doesn’t exceed maximum sample limits.

Best practices when using this variable include:

  1. Balancing quality and performance by adjusting this value in conjunction with other shadow-related settings.
  2. Considering the scale of your scene when setting this value, as larger scenes may require larger distances to maintain reasonable performance.
  3. Testing different values to find the optimal balance between shadow quality and lightmap generation time for your specific project.
  4. Ensuring that the X and Y transition sample distances are set appropriately for your scene’s geometry and lighting setup.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseLightmass.ini:147, 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:409

Scope (from outer to inner):

file
namespace    GPULightmass
function     void FDirectionalLightRenderState::RenderStaticShadowDepthMap

Source code excerpt:


	const float ClampedResolutionScale = 1.0f;
	const float StaticShadowDepthMapTransitionSampleDistanceX = 10;
	const float StaticShadowDepthMapTransitionSampleDistanceY = 10;
	
	int32 ShadowMapSizeX = FMath::TruncToInt(FMath::Max(LightSpaceImportanceBounds.GetExtent().X * 2.0f * ClampedResolutionScale / StaticShadowDepthMapTransitionSampleDistanceX, 4.0f));
	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)

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

Scope (from outer to inner):

file
namespace    GPULightmass
function     void FSpotLightRenderState::RenderStaticShadowDepthMap

Source code excerpt:

	
	const float ClampedResolutionScale = 1.0f;
	const float StaticShadowDepthMapTransitionSampleDistanceX = 10;
	const float StaticShadowDepthMapTransitionSampleDistanceY = 10;
	
	int32 ShadowMapSizeX = FMath::TruncToInt(FMath::Max(HalfCrossSectionLength * ClampedResolutionScale / StaticShadowDepthMapTransitionSampleDistanceX, 4.0f));
	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)

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

Scope (from outer to inner):

file
namespace    GPULightmass
function     void FPointLightRenderState::RenderStaticShadowDepthMap

Source code excerpt:


	const float ClampedResolutionScale = 1.0f;
	const float StaticShadowDepthMapTransitionSampleDistanceX = 10;
	const float StaticShadowDepthMapTransitionSampleDistanceY = 10;
	
	int32 ShadowMapSizeX = FMath::TruncToInt(FMath::Max(AttenuationRadius * 4 * ClampedResolutionScale / StaticShadowDepthMapTransitionSampleDistanceX, 4.0f));
	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)

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

Scope (from outer to inner):

file
namespace    GPULightmass
function     void FRectLightRenderState::RenderStaticShadowDepthMap

Source code excerpt:


	const float ClampedResolutionScale = 1.0f;
	const float StaticShadowDepthMapTransitionSampleDistanceX = 10;
	const float StaticShadowDepthMapTransitionSampleDistanceY = 10;
	
	int32 ShadowMapSizeX = FMath::TruncToInt(FMath::Max(AttenuationRadius * 4 * ClampedResolutionScale / StaticShadowDepthMapTransitionSampleDistanceX, 4.0f));
	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)

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

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

		VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.StaticShadows"), TEXT("ApproximateHighResTexelsPerMaxTransitionDistance"), Scene.ShadowSettings.ApproximateHighResTexelsPerMaxTransitionDistance, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.StaticShadows"), TEXT("MinDistanceFieldUpsampleFactor"), Scene.ShadowSettings.MinDistanceFieldUpsampleFactor, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.StaticShadows"), TEXT("StaticShadowDepthMapTransitionSampleDistanceX"), Scene.ShadowSettings.StaticShadowDepthMapTransitionSampleDistanceX, GLightmassIni));
		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));
	}
	{

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/ImportExport/LightmassScene.cpp:524

Scope (from outer to inner):

file
namespace    Lightmass
function     void FScene::ApplyStaticLightingScale

Source code excerpt:

	VolumeDistanceFieldSettings.VolumeMaxDistance *= SceneConstants.StaticLightingLevelScale;
	ShadowSettings.MaxTransitionDistanceWorldSpace *= SceneConstants.StaticLightingLevelScale;
	ShadowSettings.StaticShadowDepthMapTransitionSampleDistanceX *= SceneConstants.StaticLightingLevelScale;
	ShadowSettings.StaticShadowDepthMapTransitionSampleDistanceY *= SceneConstants.StaticLightingLevelScale;
	IrradianceCachingSettings.RecordRadiusScale *= SceneConstants.StaticLightingLevelScale;
	IrradianceCachingSettings.MaxRecordRadius *= SceneConstants.StaticLightingLevelScale;

	// Photon mapping does not scale down properly, so this is disabled
	/*

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

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingSystem::ValidateSettings

Source code excerpt:

	// Round up to nearest odd number
	ShadowSettings.MinDistanceFieldUpsampleFactor = FMath::Clamp(ShadowSettings.MinDistanceFieldUpsampleFactor - ShadowSettings.MinDistanceFieldUpsampleFactor % 2 + 1, 1, 17);
	ShadowSettings.StaticShadowDepthMapTransitionSampleDistanceX = FMath::Max(ShadowSettings.StaticShadowDepthMapTransitionSampleDistanceX, DELTA);
	ShadowSettings.StaticShadowDepthMapTransitionSampleDistanceY = FMath::Max(ShadowSettings.StaticShadowDepthMapTransitionSampleDistanceY, DELTA);

	InScene.IrradianceCachingSettings.InterpolationMaxAngle = FMath::Clamp(InScene.IrradianceCachingSettings.InterpolationMaxAngle, 0.0f, 90.0f);
	InScene.IrradianceCachingSettings.PointBehindRecordMaxAngle = FMath::Clamp(InScene.IrradianceCachingSettings.PointBehindRecordMaxAngle, 0.0f, 90.0f);
	InScene.IrradianceCachingSettings.DistanceSmoothFactor = FMath::Max(InScene.IrradianceCachingSettings.DistanceSmoothFactor, 1.0f);
	InScene.IrradianceCachingSettings.AngleSmoothFactor = FMath::Max(InScene.IrradianceCachingSettings.AngleSmoothFactor, 1.0f);

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

Scope (from outer to inner):

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

Source code excerpt:

		const FBox3f LightSpaceImportanceBounds = ImportanceVolume.GetBox().TransformBy(ShadowDepthMap->WorldToLight);

		ShadowDepthMap->ShadowMapSizeX = FMath::TruncToInt(FMath::Max(LightSpaceImportanceBounds.GetExtent().X * 2.0f * ClampedResolutionScale / ShadowSettings.StaticShadowDepthMapTransitionSampleDistanceX, 4.0f));
		ShadowDepthMap->ShadowMapSizeX = ShadowDepthMap->ShadowMapSizeX == appTruncErrorCode ? INT_MAX : ShadowDepthMap->ShadowMapSizeX;
		ShadowDepthMap->ShadowMapSizeY = FMath::TruncToInt(FMath::Max(LightSpaceImportanceBounds.GetExtent().Y * 2.0f * ClampedResolutionScale / ShadowSettings.StaticShadowDepthMapTransitionSampleDistanceY, 4.0f));
		ShadowDepthMap->ShadowMapSizeY = ShadowDepthMap->ShadowMapSizeY == appTruncErrorCode ? INT_MAX : ShadowDepthMap->ShadowMapSizeY;

		// Clamp the number of dominant shadow samples generated if necessary while maintaining aspect ratio
		if ((uint64)ShadowDepthMap->ShadowMapSizeX * (uint64)ShadowDepthMap->ShadowMapSizeY > (uint64)ShadowSettings.StaticShadowDepthMapMaxSamples)

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

Scope (from outer to inner):

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

Source code excerpt:

		const FVector4f LightSpaceImportanceBoundMax = FVector4f(HalfCrossSectionLength, HalfCrossSectionLength, SpotLight->Radius);

		ShadowDepthMap->ShadowMapSizeX = FMath::TruncToInt(FMath::Max(HalfCrossSectionLength * ClampedResolutionScale / ShadowSettings.StaticShadowDepthMapTransitionSampleDistanceX, 4.0f));
		ShadowDepthMap->ShadowMapSizeX = ShadowDepthMap->ShadowMapSizeX == appTruncErrorCode ? INT_MAX : ShadowDepthMap->ShadowMapSizeX;
		ShadowDepthMap->ShadowMapSizeY = ShadowDepthMap->ShadowMapSizeX;

		// Clamp the number of dominant shadow samples generated if necessary while maintaining aspect ratio
		if ((uint64)ShadowDepthMap->ShadowMapSizeX * (uint64)ShadowDepthMap->ShadowMapSizeY > (uint64)ShadowSettings.StaticShadowDepthMapMaxSamples)
		{

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

Scope (from outer to inner):

file
function     void FStaticLightingSystem::ValidateSettings
function     void FStaticLightingSystem::CalculateStaticShadowDepthMap

Source code excerpt:

	else if (PointLight)
	{
		ShadowDepthMap->ShadowMapSizeX = FMath::TruncToInt(FMath::Max(PointLight->Radius * 4 * ClampedResolutionScale / ShadowSettings.StaticShadowDepthMapTransitionSampleDistanceX, 4.0f));
		ShadowDepthMap->ShadowMapSizeX = ShadowDepthMap->ShadowMapSizeX == appTruncErrorCode ? INT_MAX : ShadowDepthMap->ShadowMapSizeX;
		ShadowDepthMap->ShadowMapSizeY = ShadowDepthMap->ShadowMapSizeX;

		// Clamp the number of dominant shadow samples generated if necessary while maintaining aspect ratio
		if ((uint64)ShadowDepthMap->ShadowMapSizeX * (uint64)ShadowDepthMap->ShadowMapSizeY > (uint64)ShadowSettings.StaticShadowDepthMapMaxSamples)
		{

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FStaticShadowSettings

Source code excerpt:


	/** Distance in world space units between dominant light shadow map cells. */
	float StaticShadowDepthMapTransitionSampleDistanceX;
	float StaticShadowDepthMapTransitionSampleDistanceY;

	/** Amount to super sample dominant shadow map generation, in each dimension.  Larger factors increase build time but produce a more conservative shadow map. */
	int32 StaticShadowDepthMapSuperSampleFactor;

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