r.Shadow.MaxCSMScrollingStaticShadowSubjects

r.Shadow.MaxCSMScrollingStaticShadowSubjects

#Overview

name: r.Shadow.MaxCSMScrollingStaticShadowSubjects

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.MaxCSMScrollingStaticShadowSubjects is to control the maximum number of extra static shadow subjects that need to be drawn when scrolling Cascaded Shadow Maps (CSM) in Unreal Engine 5’s rendering system.

This setting variable is primarily used in the rendering subsystem of Unreal Engine 5, specifically in the shadow rendering module. It’s part of the optimization strategy for Cascaded Shadow Maps, which are used to render shadows for large outdoor environments efficiently.

The value of this variable is set through a console variable (CVar) system in Unreal Engine. It’s initialized with a default value of 5, but can be changed at runtime or through configuration files.

The associated variable CVarCSMScrollingMaxExtraStaticShadowSubjects directly interacts with r.Shadow.MaxCSMScrollingStaticShadowSubjects. They share the same value and purpose.

Developers must be aware that this variable affects the trade-off between performance and shadow quality. A higher value allows for more static shadow subjects to be drawn when scrolling CSM, potentially improving shadow quality but at the cost of performance. Conversely, a lower value may improve performance but could result in popping or other visual artifacts as shadow subjects are culled.

Best practices when using this variable include:

  1. Carefully balancing the value based on the specific needs of your scene and target hardware.
  2. Testing different values to find the optimal balance between shadow quality and performance.
  3. Considering this variable in conjunction with other shadow-related settings for a holistic approach to shadow rendering optimization.

Regarding the associated variable CVarCSMScrollingMaxExtraStaticShadowSubjects:

It serves the same purpose as r.Shadow.MaxCSMScrollingStaticShadowSubjects, controlling the maximum number of extra static shadow subjects drawn when scrolling CSM.

This variable is used in the ComputeViewDependentWholeSceneShadowCacheModes function to determine whether to update the cached shadow map or scroll the existing one. If the number of extra static shadow subjects in the last frame (CachedShadowMapData->LastFrameExtraStaticShadowSubjects) is less than or equal to this value, and other conditions are met, the engine will choose to scroll the shadow map instead of updating it entirely.

Developers should be aware that this variable directly impacts the decision-making process for shadow map updates, which can have significant performance implications. Adjusting this value can help fine-tune the balance between shadow quality and rendering performance, especially in scenes with many static objects casting shadows.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarCSMScrollingMaxExtraStaticShadowSubjects(
	TEXT("r.Shadow.MaxCSMScrollingStaticShadowSubjects"),
	5,
	TEXT("The maximum number of extra static shadow subjects need to be drawed when scrolling CSM."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<bool> CVarCSMScissorOptim(
	TEXT("r.Shadow.CSMScissorOptim"),

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ScenePrivate.h:2715

Scope (from outer to inner):

file
class        class FCachedShadowMapData

Source code excerpt:


	/**
	* The extra static meshes cast shadow in last frame, if it exceeds the r.Shadow.MaxCSMScrollingStaticShadowSubjects, the cached csm should be rebuilt.
	*/
	int32 LastFrameExtraStaticShadowSubjects;

	void InvalidateCachedShadow()
	{
		ShadowMap.Release();

		StaticShadowSubjectPersistentPrimitiveIdMap.SetRange(0, StaticShadowSubjectPersistentPrimitiveIdMap.Num(), false);

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarCSMScrollingMaxExtraStaticShadowSubjects(
	TEXT("r.Shadow.MaxCSMScrollingStaticShadowSubjects"),
	5,
	TEXT("The maximum number of extra static shadow subjects need to be drawed when scrolling CSM."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<bool> CVarCSMScissorOptim(

#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
						{