r.Shadow.CSMScrollingOverlapAreaThrottle

r.Shadow.CSMScrollingOverlapAreaThrottle

#Overview

name: r.Shadow.CSMScrollingOverlapAreaThrottle

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

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.CSMScrollingOverlapAreaThrottle is to control the minimum ratio of the overlap area for Cascaded Shadow Map (CSM) scrolling in Unreal Engine’s rendering system. This variable is used to optimize shadow rendering performance and quality.

This setting variable is primarily used by the rendering system, specifically in the shadow setup and management subsystem of Unreal Engine 5. It is part of the Renderer module, as evidenced by its location in the ShadowSetup.cpp file within the Runtime/Renderer/Private directory.

The value of this variable is set as a console variable with a default value of 0.75f. It can be modified at runtime through the console or configuration files.

This variable interacts closely with another variable called CVarCSMScrollingMaxExtraStaticShadowSubjects, which controls the maximum number of extra static shadow subjects allowed during CSM scrolling.

Developers should be aware that this variable affects the trade-off between shadow quality and rendering performance. A higher value will result in more frequent shadow map updates, potentially improving quality but at the cost of performance. A lower value will allow more shadow map scrolling, which can be more efficient but may lead to lower quality in some cases.

Best practices when using this variable include:

  1. Adjusting it in conjunction with CVarCSMScrollingMaxExtraStaticShadowSubjects for optimal balance.
  2. Testing different values in various scenes to find the best compromise between quality and performance.
  3. Considering scene-specific requirements, as different types of environments may benefit from different settings.

Regarding the associated variable CVarCSMScrollingOverlapAreaThrottle:

This is the actual console variable that stores the value of r.Shadow.CSMScrollingOverlapAreaThrottle. It is defined using TAutoConsoleVariable, which allows it to be easily accessed and modified at runtime.

The purpose of CVarCSMScrollingOverlapAreaThrottle is the same as r.Shadow.CSMScrollingOverlapAreaThrottle - to control the minimum ratio of the overlap area for CSM scrolling.

This variable is used directly in the ComputeViewDependentWholeSceneShadowCacheModes function to determine whether to update the cached shadow map or scroll the existing one. It’s compared against the OverlappedAreaRatio to make this decision.

Developers should be aware that modifying this variable will directly affect the shadow caching behavior in the engine. It’s important to profile and test changes to ensure they don’t negatively impact performance or visual quality.

Best practices for using CVarCSMScrollingOverlapAreaThrottle include:

  1. Using the console command system to experiment with different values in real-time.
  2. Documenting any changes made to this variable in project settings or configuration files.
  3. Considering the impact on different hardware configurations, as optimal values may vary depending on the target platform.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadowSetup.cpp:370

Scope: file

Source code excerpt:


static TAutoConsoleVariable<float> CVarCSMScrollingOverlapAreaThrottle(
	TEXT("r.Shadow.CSMScrollingOverlapAreaThrottle"),
	0.75f,
	TEXT("The minimum ratio of the overlap area for CSM scrolling."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarCSMScrollingMaxExtraStaticShadowSubjects(
	TEXT("r.Shadow.MaxCSMScrollingStaticShadowSubjects"),

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadowSetup.cpp:369

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<float> CVarCSMScrollingOverlapAreaThrottle(
	TEXT("r.Shadow.CSMScrollingOverlapAreaThrottle"),
	0.75f,
	TEXT("The minimum ratio of the overlap area for CSM scrolling."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarCSMScrollingMaxExtraStaticShadowSubjects(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadowSetup.cpp:3841

Scope (from outer to inner):

file
function     void ComputeViewDependentWholeSceneShadowCacheModes

Source code excerpt:


						// if the overlapped area of the cached shadow map and the current shadow map smaller than a throttle or the extra draw calls of the static meshes when scrolling the shadow are greater than a throttle, update the cached shadow map, otherwise scroll the shadow map instead.
						if (OverlappedAreaRatio > CVarCSMScrollingOverlapAreaThrottle.GetValueOnAnyThread() && CachedShadowMapData->LastFrameExtraStaticShadowSubjects <= CVarCSMScrollingMaxExtraStaticShadowSubjects.GetValueOnAnyThread())
						{
							OutNumShadowMaps = 1;
							OutCacheModes[0] = SDCM_CSMScrolling;
						}
						else
						{