r.Shadow.CSMSplitPenumbraScale

r.Shadow.CSMSplitPenumbraScale

#Overview

name: r.Shadow.CSMSplitPenumbraScale

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

• type: Var
• help: Scale applied to the penumbra size of Cascaded Shadow Map splits, useful for minimizing the transition between splits

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.CSMSplitPenumbraScale is to control the scale applied to the penumbra size of Cascaded Shadow Map (CSM) splits. This setting is part of the rendering system, specifically for shadow rendering optimization.

This setting variable is primarily used in the Renderer module of Unreal Engine, as evidenced by its location in the ShadowRendering.cpp file. It’s particularly relevant to the Cascaded Shadow Map system, which is a technique used for rendering large-scale shadows efficiently.

The value of this variable is set to a default of 0.5f in the C++ code, but it can be modified at runtime through the console variable system. It’s defined as a TAutoConsoleVariable, which means it can be changed during gameplay or development without recompiling the engine.

The associated variable CVarCSMSplitPenumbraScale interacts directly with r.Shadow.CSMSplitPenumbraScale, as they share the same value. This variable is used to retrieve the current value of the setting in the render thread.

Developers should be aware that modifying this variable will affect the visual quality and performance of shadow rendering, particularly in scenes with large view distances. Increasing the value will make the transition between shadow cascades less noticeable but may impact performance.

Best practices when using this variable include:

1. Experimenting with different values to find the right balance between visual quality and performance for your specific scene.
2. Consider the target hardware when adjusting this value, as higher values may be more demanding on less powerful systems.
3. Use in conjunction with other shadow-related settings for optimal results.

Regarding the associated variable CVarCSMSplitPenumbraScale:

The purpose of CVarCSMSplitPenumbraScale is to provide a thread-safe way to access the value of r.Shadow.CSMSplitPenumbraScale in the render thread.

This variable is used directly in the shadow rendering code to adjust the kernel size for shadow penumbra calculations. It’s accessed using the GetValueOnRenderThread() method, ensuring thread-safe access to the current value.

The value of CVarCSMSplitPenumbraScale is set automatically when r.Shadow.CSMSplitPenumbraScale is modified, as they are effectively the same variable exposed through different interfaces.

Developers should be aware that this variable is intended for use in render thread operations and should not be accessed from other threads without proper synchronization.

Best practices for using CVarCSMSplitPenumbraScale include:

1. Always access it using GetValueOnRenderThread() when in render thread code.
2. Avoid caching its value for extended periods, as it can be changed at runtime.
3. Consider the performance implications of frequently accessing this value in performance-critical code paths.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadowRendering.cpp:51

Scope: file

Source code excerpt:

static TAutoConsoleVariable<float> CVarCSMSplitPenumbraScale(
	TEXT("r.Shadow.CSMSplitPenumbraScale"),
	0.5f,
	TEXT("Scale applied to the penumbra size of Cascaded Shadow Map splits, useful for minimizing the transition between splits"),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarCSMDepthBoundsTest(
	TEXT("r.Shadow.CSMDepthBoundsTest"),

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadowRendering.cpp:50

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<float> CVarCSMSplitPenumbraScale(
	TEXT("r.Shadow.CSMSplitPenumbraScale"),
	0.5f,
	TEXT("Scale applied to the penumbra size of Cascaded Shadow Map splits, useful for minimizing the transition between splits"),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarCSMDepthBoundsTest(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadowRendering.cpp:1385

Scope: file

Source code excerpt:

			{
				// adjust kernel size so that the penumbra size of distant splits will better match up with the closer ones
				const float SizeScale = CascadeSettings.ShadowSplitIndex / FMath::Max(0.001f, CVarCSMSplitPenumbraScale.GetValueOnRenderThread());
			}
			else if (LocalQuality > 2 && !bWholeSceneShadow)
			{
				static auto CVarPreShadowResolutionFactor = IConsoleManager::Get().FindTConsoleVariableDataFloat(TEXT("r.Shadow.PreShadowResolutionFactor"));
				const int32 TargetResolution = bPreShadow ? FMath::TruncToInt(512 * CVarPreShadowResolutionFactor->GetValueOnRenderThread()) : 512;