bFilterShadowFactor

bFilterShadowFactor

#Overview

name: bFilterShadowFactor

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

#Summary

#Usage in the C++ source code

The purpose of bFilterShadowFactor is to control whether shadow factors should be filtered in the static lighting calculations within Unreal Engine 5. This setting is primarily used in the static lighting and shadow generation system.

Based on the callsites, this variable is primarily used in the Lightmass system, which is Unreal Engine’s global illumination and static lighting solution. It’s referenced in both the UnrealEd module (for exporting scene settings) and the UnrealLightmass program (for actual lighting calculations).

The value of this variable is set from the configuration file (GLightmassIni) in the FLightmassExporter::WriteSceneSettings function. It’s read from the “DevOptions.StaticShadows” section with the key “bFilterShadowFactor”.

This variable interacts closely with other shadow-related settings, particularly ShadowFactorGradientTolerance, which is used when bFilterShadowFactor is true to determine the threshold for filtering penumbras.

Developers should be aware that enabling this option (setting it to true) will cause the engine to perform an additional filtering pass on shadow factors. This can help to smooth out sharp shadow transitions that might not be accurately captured in the lightmap resolution, potentially improving the visual quality of static shadows.

Best practices when using this variable include:

  1. Consider the performance impact: Enabling shadow factor filtering will increase lightmap generation time.
  2. Use in conjunction with ShadowFactorGradientTolerance: Adjust this value to fine-tune the filtering process.
  3. Test with and without filtering: Compare the results to determine if the visual improvement justifies the additional computation time.
  4. Be aware of the interaction with lightmap resolution: Higher resolution lightmaps might benefit less from this filtering.
  5. Consider the scene complexity: Scenes with many complex shadows might benefit more from this filtering.

Developers should experiment with this setting to find the right balance between visual quality and build time for their specific project needs.

#Setting Variables

#References In INI files

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

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

		VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.StaticShadows"), TEXT("NumPenumbraShadowRays"), Scene.ShadowSettings.NumPenumbraShadowRays, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.StaticShadows"), TEXT("NumBounceShadowRays"), Scene.ShadowSettings.NumBounceShadowRays, GLightmassIni));
		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));

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

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingSystem::CalculateDirectAreaLightingTextureMapping

Source code excerpt:


	// Optional shadow factor filter pass
	if (bShadowFactorFilterPassEnabled && Scene.ShadowSettings.bFilterShadowFactor)
	{
		// 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] = {

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

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingSystem::CalculateDirectAreaLightingTextureMapping

Source code excerpt:

				float ShadowFactor;
				bool bIsMapped;
				if (Scene.ShadowSettings.bFilterShadowFactor)
				{
					bIsMapped = FilteredShadowFactorData(X, Y).bIsMapped;
					ShadowFactor = FilteredShadowFactorData(X, Y).Visibility;
				}
				else
				{

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FStaticShadowSettings

Source code excerpt:

	 * filtering, meant to catch shadow transitions sharper than can be captured in the lightmap.
	 */
	bool bFilterShadowFactor;
	float ShadowFactorGradientTolerance;

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

	/**