r.Shadow.Virtual.DistantLightForceCacheFootprintFraction

r.Shadow.Virtual.DistantLightForceCacheFootprintFraction

#Overview

name: r.Shadow.Virtual.DistantLightForceCacheFootprintFraction

This variable is created as a Console Variable (cvar).

• type: Var
• help: Fraction of footprint size below which start force-caching lights that are invalidated (i.e., are moving or re-added)\n Larger values may improve performance but may also produce more visible artifacts\n The base footprint is based on the page size.\n 0.0 == Never force-cache (default), 1.0 == Always force-cache.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.Virtual.DistantLightForceCacheFootprintFraction is to control the caching behavior of distant light shadows in Unreal Engine’s virtual shadow map system. It is used to determine when to force-cache lights that have been invalidated (due to movement or being re-added to the scene).

This setting variable is primarily used in the rendering system, specifically in the shadow rendering subsystem of Unreal Engine 5. The main module that relies on this variable is the Renderer module, as evidenced by its usage in the ShadowSceneRenderer.cpp file.

The value of this variable is set through a console variable (CVarDistantLightForceCacheFootprintFraction) with a default value of 0.0f. It can be adjusted at runtime through console commands or in-game settings.

The associated variable CVarDistantLightForceCacheFootprintFraction directly interacts with r.Shadow.Virtual.DistantLightForceCacheFootprintFraction. They share the same value and purpose.

Developers must be aware of the following when using this variable:

1. It affects performance and visual quality of distant light shadows.
2. The value ranges from 0.0 to 1.0, where 0.0 means never force-cache, and 1.0 means always force-cache.
3. Larger values may improve performance but could introduce more visible artifacts.
4. The base footprint for calculations is based on the shadow map page size.

Best practices when using this variable include:

1. Start with the default value (0.0) and adjust gradually if needed.
2. Monitor performance and visual quality when changing this value.
3. Use in conjunction with other shadow-related settings for optimal results.
4. Consider the trade-off between performance improvement and potential visual artifacts.

Regarding the associated variable CVarDistantLightForceCacheFootprintFraction:

• Its purpose is identical to r.Shadow.Virtual.DistantLightForceCacheFootprintFraction.
• It is used in the same Renderer module and shadow rendering subsystem.
• The value is set through the console variable definition and can be accessed in C++ code using GetValueOnRenderThread() method.
• It directly interacts with r.Shadow.Virtual.DistantLightForceCacheFootprintFraction, as they share the same value.
• Developers should treat it as the C++ representation of the console variable and use it to access the current value in code.
• Best practices include using FMath::Clamp when reading the value to ensure it stays within the valid range of 0.0 to 1.0.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Shadows/ShadowSceneRenderer.cpp:40

Scope: file

Source code excerpt:

static TAutoConsoleVariable<float> CVarDistantLightForceCacheFootprintFraction(
	TEXT("r.Shadow.Virtual.DistantLightForceCacheFootprintFraction"),
	0.0f,
	TEXT("Fraction of footprint size below which start force-caching lights that are invalidated (i.e., are moving or re-added)\n")
	TEXT("  Larger values may improve performance but may also produce more visible artifacts\n")
	TEXT("  The base footprint is based on the page size.\n")
	TEXT("  0.0 == Never force-cache (default), 1.0 == Always force-cache."),
	ECVF_Scalability | ECVF_RenderThreadSafe

#Associated Variable and Callsites

This variable is associated with another variable named CVarDistantLightForceCacheFootprintFraction. They share the same value. See the following C++ source code.

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Shadows/ShadowSceneRenderer.cpp:39

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<float> CVarDistantLightForceCacheFootprintFraction(
	TEXT("r.Shadow.Virtual.DistantLightForceCacheFootprintFraction"),
	0.0f,
	TEXT("Fraction of footprint size below which start force-caching lights that are invalidated (i.e., are moving or re-added)\n")
	TEXT("  Larger values may improve performance but may also produce more visible artifacts\n")
	TEXT("  The base footprint is based on the page size.\n")
	TEXT("  0.0 == Never force-cache (default), 1.0 == Always force-cache."),

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Shadows/ShadowSceneRenderer.cpp:248

Scope (from outer to inner):

file
function     TSharedPtr<FVirtualShadowMapPerLightCacheEntry> FShadowSceneRenderer::AddLocalLightShadow

Source code excerpt:

	TSharedPtr<FVirtualShadowMapPerLightCacheEntry> PerLightCacheEntry = CacheManager->FindCreateLightCacheEntry(LightSceneInfo->Id, 0, NumMaps);
			
	const float DistantLightForceCacheFootprintFraction = FMath::Clamp(CVarDistantLightForceCacheFootprintFraction.GetValueOnRenderThread(), 0.0f, 1.0f);
	bool bShouldForceTimeSliceDistantUpdate = (bIsDistantLight && MaxScreenRadius <= BiasedFootprintThreshold * DistantLightForceCacheFootprintFraction);
	LocalLightShadowFrameSetup.PerLightCacheEntry = PerLightCacheEntry;
	bool bIsCached = PerLightCacheEntry->UpdateLocal(ProjectedShadowInitializer, bIsDistantLight, CacheManager->IsCacheEnabled(), !bShouldForceTimeSliceDistantUpdate);

	if (bIsCached && bIsDistantLight && PerLightCacheEntry->Prev.ScheduledFrameNumber == Scene.GetFrameNumber())
	{