r.Shadow.CSM.MaxCascades

r.Shadow.CSM.MaxCascades

#Overview

name: r.Shadow.CSM.MaxCascades

The value of this variable can be defined or overridden in .ini config files. 20 .ini config files referencing this setting variable.

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.CSM.MaxCascades is to control the maximum number of cascades used for rendering dynamic directional light shadows in Unreal Engine 5. This setting is part of the rendering system, specifically the shadow rendering subsystem.

The Unreal Engine renderer module relies on this setting variable. It is used in the SceneRendering.cpp file, which is a core part of the rendering pipeline.

The value of this variable is set using a console variable (CVar) system. It’s initialized with a default value of 10, but can be changed at runtime through console commands or project settings.

This variable interacts directly with its associated variable CVarMaxShadowCascades. They share the same value and are used interchangeably in the code.

Developers must be aware that:

  1. This setting affects performance and visual quality. More cascades can provide better shadow quality but at a higher performance cost.
  2. The actual maximum number of cascades is clamped based on the feature level of the rendering hardware. For example, on mobile (SM5 and below), it’s limited to MaxMobileShadowCascadeCount.
  3. This variable is marked with ECVF_Scalability and ECVF_RenderThreadSafe flags, indicating it’s used for scalability settings and is safe to modify on the render thread.

Best practices when using this variable include:

  1. Consider the target hardware when setting this value. Higher-end systems can handle more cascades.
  2. Balance between visual quality and performance based on the specific needs of your project.
  3. Test thoroughly with different cascade counts to find the optimal setting for your scene.

Regarding the associated variable CVarMaxShadowCascades: It’s a TAutoConsoleVariable that directly corresponds to the r.Shadow.CSM.MaxCascades setting. It’s used internally by the engine to store and access the value of this setting. The engine code reads this value, for example in the FViewInfo::Init() function, to set the MaxShadowCascades member variable of the view.

When working with CVarMaxShadowCascades, developers should:

  1. Use GetValueOnAnyThread() to safely read its value from any thread.
  2. Be aware that changes to this variable will affect all views in the scene.
  3. Consider using this variable for dynamic adjustments to shadow quality during runtime, if needed.

#Setting Variables

#References In INI files

<Workspace>/Engine/Config/BaseDeviceProfiles.ini:904, section: [Android_Vulkan_SM5 DeviceProfile]
<Workspace>/Engine/Config/BaseScalability.ini:130, section: [ShadowQuality@0]
<Workspace>/Engine/Config/BaseScalability.ini:154, section: [ShadowQuality@1]
<Workspace>/Engine/Config/BaseScalability.ini:178, section: [ShadowQuality@2]
<Workspace>/Engine/Config/BaseScalability.ini:205, section: [ShadowQuality@3]
<Workspace>/Engine/Config/BaseScalability.ini:232, section: [ShadowQuality@Cine]
<Workspace>/Engine/Config/Android/AndroidScalability.ini:52, section: [ShadowQuality@0]
<Workspace>/Engine/Config/Android/AndroidScalability.ini:61, section: [ShadowQuality@1]
<Workspace>/Engine/Config/Android/AndroidScalability.ini:70, section: [ShadowQuality@2]
<Workspace>/Engine/Config/Android/AndroidScalability.ini:79, section: [ShadowQuality@3]
<Workspace>/Engine/Config/IOS/IOSScalability.ini:52, section: [ShadowQuality@0]
<Workspace>/Engine/Config/IOS/IOSScalability.ini:61, section: [ShadowQuality@1]
<Workspace>/Engine/Config/IOS/IOSScalability.ini:70, section: [ShadowQuality@2]
<Workspace>/Engine/Config/IOS/IOSScalability.ini:79, section: [ShadowQuality@3]
<Workspace>/Projects/Lyra/Config/Android/AndroidScalability.ini:22, section: [ShadowQuality@1]
<Workspace>/Projects/Lyra/Config/Android/AndroidScalability.ini:27, section: [ShadowQuality@2]
<Workspace>/Projects/Lyra/Config/Android/AndroidScalability.ini:32, section: [ShadowQuality@3]
<Workspace>/Projects/Lyra/Config/IOS/IOSScalability.ini:22, section: [ShadowQuality@1]
<Workspace>/Projects/Lyra/Config/IOS/IOSScalability.ini:27, section: [ShadowQuality@2]
<Workspace>/Projects/Lyra/Config/IOS/IOSScalability.ini:32, section: [ShadowQuality@3]

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneRendering.cpp:312

Scope: file

Source code excerpt:

 */
static TAutoConsoleVariable<int32> CVarMaxShadowCascades(
	TEXT("r.Shadow.CSM.MaxCascades"),
	10,
	TEXT("The maximum number of cascades with which to render dynamic directional light shadows."),
	ECVF_Scalability | ECVF_RenderThreadSafe
	);

static TAutoConsoleVariable<float> CVarNormalCurvatureToRoughnessBias(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneRendering.cpp:311

Scope: file

Source code excerpt:

 *   DO NOT READ ON THE RENDERING THREAD. Use FSceneView::MaxShadowCascades.
 */
static TAutoConsoleVariable<int32> CVarMaxShadowCascades(
	TEXT("r.Shadow.CSM.MaxCascades"),
	10,
	TEXT("The maximum number of cascades with which to render dynamic directional light shadows."),
	ECVF_Scalability | ECVF_RenderThreadSafe
	);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneRendering.cpp:969

Scope (from outer to inner):

file
function     void FViewInfo::Init

Source code excerpt:

	const int32 MaxShadowCascadeCountUpperBound = GetFeatureLevel() >= ERHIFeatureLevel::SM5 ? 10 : MaxMobileShadowCascadeCount;

	MaxShadowCascades = FMath::Clamp<int32>(CVarMaxShadowCascades.GetValueOnAnyThread(), 0, MaxShadowCascadeCountUpperBound);

	ShaderMap = GetGlobalShaderMap(FeatureLevel);

	ViewState = (FSceneViewState*)State;
	bHMDHiddenAreaMaskActive = IsHMDHiddenAreaMaskActive();
	bUseComputePasses = IsPostProcessingWithComputeEnabled(FeatureLevel);