StaticShadowDepthMapSuperSampleFactor

StaticShadowDepthMapSuperSampleFactor

#Overview

name: StaticShadowDepthMapSuperSampleFactor

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 StaticShadowDepthMapSuperSampleFactor is to control the super-sampling of static shadow depth maps in Unreal Engine’s lighting system. It is used to increase the quality and accuracy of static shadows by performing additional sampling during the shadow map generation process.

This setting variable is primarily used in the GPULightmass plugin and the Lightmass system, which are responsible for global illumination and static lighting calculations in Unreal Engine. It is referenced in various light types, including directional, spot, point, and rect 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 in the Lightmass exporter.

This variable interacts with other shadow-related settings, such as StaticShadowDepthMapTransitionSampleDistanceX, StaticShadowDepthMapTransitionSampleDistanceY, and StaticShadowDepthMapMaxSamples.

Developers should be aware that increasing the StaticShadowDepthMapSuperSampleFactor will result in higher quality static shadows but at the cost of increased build times and memory usage. It’s important to find a balance between shadow quality and performance.

Best practices when using this variable include:

  1. Start with the default value and incrementally increase it if higher quality shadows are needed.
  2. Monitor build times and memory usage when adjusting this value.
  3. Consider using it in conjunction with other shadow quality settings for optimal results.
  4. Be mindful of the trade-off between shadow quality and performance, especially for larger scenes or projects with limited resources.
  5. Document any changes to this setting in your project to ensure consistency across the development team.

#Setting Variables

#References In INI files

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

Scope (from outer to inner):

file
namespace    GPULightmass
function     void FDirectionalLightRenderState::RenderStaticShadowDepthMap

Source code excerpt:

	PassParameters->TLAS = Scene.RayTracingSceneSRV;
	PassParameters->ShadowMapSize = FIntPoint{ShadowMapSizeX, ShadowMapSizeY};
	PassParameters->StaticShadowDepthMapSuperSampleFactor = 1;
	PassParameters->LightSpaceImportanceBoundsMin = FVector3f(LightSpaceImportanceBounds.Min);
	PassParameters->LightSpaceImportanceBoundsMax = FVector3f(LightSpaceImportanceBounds.Max);
	PassParameters->LightToWorld = FMatrix44f(WorldToLight.InverseFast());
	PassParameters->MaxPossibleDistance = LightSpaceImportanceBounds.Max.Z - LightSpaceImportanceBounds.Min.Z;
	PassParameters->DepthMapTexture = GraphBuilder.CreateUAV(DepthMapTexture);

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

Scope (from outer to inner):

file
namespace    GPULightmass
function     void FSpotLightRenderState::RenderStaticShadowDepthMap

Source code excerpt:

	PassParameters->TLAS = Scene.RayTracingSceneSRV;
	PassParameters->ShadowMapSize = FIntPoint{ShadowMapSizeX, ShadowMapSizeY};
	PassParameters->StaticShadowDepthMapSuperSampleFactor = 1;
	PassParameters->LightSpaceImportanceBoundsMin = FVector3f(LightSpaceImportanceBounds.Min);
	PassParameters->LightSpaceImportanceBoundsMax = FVector3f(LightSpaceImportanceBounds.Max);
	PassParameters->LightToWorld = FMatrix44f(LightToWorld);
	PassParameters->WorldToLight = FMatrix44f(WorldToLight);
	PassParameters->MaxPossibleDistance = MaxPossibleDistance;
	PassParameters->DepthMapTexture = GraphBuilder.CreateUAV(DepthMapTexture);

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

Scope (from outer to inner):

file
namespace    GPULightmass
function     void FPointLightRenderState::RenderStaticShadowDepthMap

Source code excerpt:

	PassParameters->TLAS = Scene.RayTracingSceneSRV;
	PassParameters->ShadowMapSize = FIntPoint{ShadowMapSizeX, ShadowMapSizeY};
	PassParameters->StaticShadowDepthMapSuperSampleFactor = 1;
	PassParameters->LightSpaceImportanceBoundsMin = FVector3f{EForceInit::ForceInitToZero};
	PassParameters->LightSpaceImportanceBoundsMax = FVector3f{EForceInit::ForceInitToZero};
	PassParameters->LightToWorld = FTranslationMatrix44f(FVector3f(Position));
	PassParameters->WorldToLight = FTranslationMatrix44f(-FVector3f(Position));
	PassParameters->MaxPossibleDistance = AttenuationRadius;
	PassParameters->DepthMapTexture = GraphBuilder.CreateUAV(DepthMapTexture);

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

Scope (from outer to inner):

file
namespace    GPULightmass
function     void FRectLightRenderState::RenderStaticShadowDepthMap

Source code excerpt:

	PassParameters->TLAS = Scene.RayTracingSceneSRV;
	PassParameters->ShadowMapSize = FIntPoint{ShadowMapSizeX, ShadowMapSizeY};
	PassParameters->StaticShadowDepthMapSuperSampleFactor = 1;
	PassParameters->LightSpaceImportanceBoundsMin = FVector3f{EForceInit::ForceInitToZero};
	PassParameters->LightSpaceImportanceBoundsMax = FVector3f{EForceInit::ForceInitToZero};
	PassParameters->LightToWorld = FTranslationMatrix44f(FVector3f(Position));
	PassParameters->WorldToLight = FTranslationMatrix44f(-FVector3f(Position));
	PassParameters->MaxPossibleDistance = AttenuationRadius;
	PassParameters->DepthMapTexture = GraphBuilder.CreateUAV(DepthMapTexture);

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

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

		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));
	}
	{
		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.ImportanceTracing"), TEXT("bUseStratifiedSampling"), bConfigBool, GLightmassIni));
		Scene.ImportanceTracingSettings.bUseStratifiedSampling = bConfigBool;

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

Scope (from outer to inner):

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

Source code excerpt:

					float MaxSampleDistance = 0.0f;
					// Super sample each cell
					for (int32 SubSampleY = 0; SubSampleY < ShadowSettings.StaticShadowDepthMapSuperSampleFactor; SubSampleY++)
					{
						const float YFraction = (Y + SubSampleY / (float)ShadowSettings.StaticShadowDepthMapSuperSampleFactor) / (float)(ShadowDepthMap->ShadowMapSizeY - 1);
						for (int32 SubSampleX = 0; SubSampleX < ShadowSettings.StaticShadowDepthMapSuperSampleFactor; SubSampleX++)
						{
							const float XFraction = (X + SubSampleX / (float)ShadowSettings.StaticShadowDepthMapSuperSampleFactor) / (float)(ShadowDepthMap->ShadowMapSizeX - 1);
							// Construct a ray in light space along the direction of the light, starting at the minimum light space Z going to the maximum.
							const FVector4f LightSpaceStartPosition(
								LightSpaceImportanceBounds.Min.X + XFraction * (LightSpaceImportanceBounds.Max.X - LightSpaceImportanceBounds.Min.X),
								LightSpaceImportanceBounds.Min.Y + YFraction * (LightSpaceImportanceBounds.Max.Y - LightSpaceImportanceBounds.Min.Y),
								LightSpaceImportanceBounds.Min.Z);
							const FVector4f LightSpaceEndPosition(LightSpaceStartPosition.X, LightSpaceStartPosition.Y, LightSpaceImportanceBounds.Max.Z);

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

Scope (from outer to inner):

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

Source code excerpt:

				float MaxSampleDistance = 0.0f;
				// Super sample each cell
				for (int32 SubSampleY = 0; SubSampleY < ShadowSettings.StaticShadowDepthMapSuperSampleFactor; SubSampleY++)
				{
					const float YFraction = (Y + SubSampleY / (float)ShadowSettings.StaticShadowDepthMapSuperSampleFactor) / (float)(ShadowDepthMap->ShadowMapSizeY - 1);
					for (int32 SubSampleX = 0; SubSampleX < ShadowSettings.StaticShadowDepthMapSuperSampleFactor; SubSampleX++)
					{
						const float XFraction = (X + SubSampleX / (float)ShadowSettings.StaticShadowDepthMapSuperSampleFactor) / (float)(ShadowDepthMap->ShadowMapSizeX - 1);
						// Construct a ray in light space along the direction of the light, starting at the light and going to the maximum light space Z.
						const FVector4f LightSpaceStartPosition(0,0,0);
						const FVector4f LightSpaceEndPosition(
							LightSpaceImportanceBoundMin.X + XFraction * (LightSpaceImportanceBoundMax.X - LightSpaceImportanceBoundMin.X),
							LightSpaceImportanceBoundMin.Y + YFraction * (LightSpaceImportanceBoundMax.Y - LightSpaceImportanceBoundMin.Y),
							LightSpaceImportanceBoundMax.Z);

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

Scope (from outer to inner):

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

Source code excerpt:

				float MaxSampleDistance = 0.0f;
				// Super sample each cell
				for (int32 SubSampleY = 0; SubSampleY < ShadowSettings.StaticShadowDepthMapSuperSampleFactor; SubSampleY++)
				{
					const float YFraction = (Y + SubSampleY / (float)ShadowSettings.StaticShadowDepthMapSuperSampleFactor) / (float)(ShadowDepthMap->ShadowMapSizeY - 1);
					const float Phi = YFraction * PI;
					const float SinPhi = FMath::Sin(Phi);

					for (int32 SubSampleX = 0; SubSampleX < ShadowSettings.StaticShadowDepthMapSuperSampleFactor; SubSampleX++)
					{
						const float XFraction = (X + SubSampleX / (float)ShadowSettings.StaticShadowDepthMapSuperSampleFactor) / (float)(ShadowDepthMap->ShadowMapSizeX - 1);
						const float Theta = XFraction * 2 * PI;
						const FVector3f Direction(FMath::Cos(Theta) * SinPhi, FMath::Sin(Theta) * SinPhi, FMath::Cos(Phi));

						const FVector4f WorldSpaceStartPosition = PointLight->Position;
						const FVector4f WorldSpaceEndPosition = PointLight->Position + Direction * PointLight->Radius;
						const FLightRay LightRay(

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FStaticShadowSettings

Source code excerpt:


	/** 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. */
	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;