ShadowFactorGradientTolerance

ShadowFactorGradientTolerance

#Overview

name: ShadowFactorGradientTolerance

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

#Summary

#Usage in the C++ source code

The purpose of ShadowFactorGradientTolerance is to control the filtering of shadow factors in static lighting calculations within Unreal Engine 5. This setting is specifically used in the static shadow rendering system.

This setting variable is primarily relied upon by the Lightmass subsystem, which is responsible for global illumination and static lighting calculations in Unreal Engine. It’s used in both the editor (UnrealEd) and the standalone Lightmass program.

The value of this variable is set in the Lightmass configuration file (GLightmassIni). It’s read from the “DevOptions.StaticShadows” section with the key “ShadowFactorGradientTolerance”.

ShadowFactorGradientTolerance interacts with other shadow-related settings, such as bFilterShadowFactor and bAllowSignedDistanceFieldShadows. It’s used as a threshold value in the shadow factor filtering process.

Developers must be aware that this variable affects the quality and performance of static shadow calculations. A lower tolerance value will result in more accurate but potentially noisier shadows, while a higher value will produce smoother but potentially less accurate shadows.

Best practices when using this variable include:

  1. Experiment with different values to find the right balance between shadow quality and performance for your specific project.
  2. Consider the overall lighting strategy of your scene when adjusting this value.
  3. Use this in conjunction with other shadow settings for optimal results.
  4. Be mindful of performance implications when lowering the tolerance, as it may increase computation time during lightmap generation.
  5. Document any custom values used in your project for consistency across the development team.

#Setting Variables

#References In INI files

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

#References in C++ code

#Callsites

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

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

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.StaticShadows"), TEXT("bFilterShadowFactor"), bConfigBool, GLightmassIni));
		Scene.ShadowSettings.bFilterShadowFactor = bConfigBool;
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.StaticShadows"), TEXT("ShadowFactorGradientTolerance"), Scene.ShadowSettings.ShadowFactorGradientTolerance, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.StaticShadows"), TEXT("bAllowSignedDistanceFieldShadows"), bConfigBool, GLightmassIni));
		Scene.ShadowSettings.bAllowSignedDistanceFieldShadows = bConfigBool;
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.StaticShadows"), TEXT("MaxTransitionDistanceWorldSpace"), Scene.ShadowSettings.MaxTransitionDistanceWorldSpace, GLightmassIni));
		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));

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/TextureMapping.cpp:1552

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingSystem::CalculateDirectAreaLightingTextureMapping

Source code excerpt:

	{
		// Filter in texture space across nearest neighbors
		const float ThresholdForFilteringPenumbra = Scene.ShadowSettings.ShadowFactorGradientTolerance;
		const int32 KernelSizeX = 3; // Expected to be odd
		const int32 KernelSizeY = 3; // Expected to be odd
		const float FilterKernel3x3[KernelSizeX * KernelSizeY] = {
			.5f * 0.150f, .5f * 0.332f, .5f * 0.150f,
			.5f * 0.332f, .5f * 1.000f, .5f * 0.332f,
			.5f * 0.150f, .5f * 0.332f, .5f * 0.150f,

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FStaticShadowSettings

Source code excerpt:

	 */
	bool bFilterShadowFactor;
	float ShadowFactorGradientTolerance;

	/** Whether to allow signed distance field shadows, or fall back on area shadows. */
	bool bAllowSignedDistanceFieldShadows;

	/** 
	 * Maximum world space distance stored from a texel to the shadow transition.