r.Shadow.CSMCaching

r.Shadow.CSMCaching

#Overview

name: r.Shadow.CSMCaching

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.CSMCaching is to control Cascaded Shadow Map (CSM) caching in Unreal Engine 5’s rendering system. This setting variable is used to enable or disable the caching of CSMs, which can potentially improve performance by reducing the frequency of shadow map rendering.

This setting variable is primarily used in the Renderer module of Unreal Engine 5, specifically in the shadow rendering and setup subsystems. The code references are found in ShadowSetup.cpp and ShadowDepthRendering.cpp, which are part of the core rendering pipeline.

The value of this variable is set through the console variable system. It’s defined as a TAutoConsoleVariable with two possible values: 0: Render CSM every frame (caching disabled) 1: Enable CSM caching (default)

The associated variable CVarCSMCaching interacts directly with r.Shadow.CSMCaching. They share the same value and are used interchangeably in the code.

Developers must be aware that enabling CSM caching (value 1) can improve performance but may lead to less frequent updates of shadow maps. This could result in slight visual artifacts or less accurate shadows in scenes with rapidly changing lighting conditions.

Best practices when using this variable include:

  1. Use the default value (1) for most scenarios to benefit from improved performance.
  2. Consider disabling caching (value 0) in scenes with dynamic lighting that requires frequent shadow updates.
  3. Test thoroughly with both settings to ensure the visual quality meets the project’s requirements.
  4. Be aware that this setting may interact with other shadow-related variables and rendering features, so it should be considered as part of the overall rendering configuration.

Regarding the associated variable CVarCSMCaching:

The purpose of CVarCSMCaching is to provide a programmatic way to access the r.Shadow.CSMCaching setting within the C++ code. It’s used in the same context as r.Shadow.CSMCaching and serves as an interface for the engine’s code to query and utilize the CSM caching setting.

CVarCSMCaching is used in the Renderer module, specifically in shadow-related computations and setup procedures. It’s typically accessed using GetValueOnAnyThread() to determine whether CSM caching is enabled.

The value of CVarCSMCaching is set automatically based on the r.Shadow.CSMCaching console variable. Developers don’t need to set it directly, as it reflects the state of r.Shadow.CSMCaching.

When using CVarCSMCaching, developers should be aware that it’s a thread-safe way to access the CSM caching setting, which is important in the multi-threaded rendering pipeline of Unreal Engine.

Best practices for using CVarCSMCaching include:

  1. Use it to conditionally execute code paths based on whether CSM caching is enabled.
  2. Remember that its value can change at runtime, so always query it when needed rather than caching its value for extended periods.
  3. Consider the performance implications of frequently querying 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/ShadowSetup.cpp:363

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarCSMCaching(
	TEXT("r.Shadow.CSMCaching"),
	0,
	TEXT("0: Render CSM every frame.\n")
	TEXT("1: Enable CSM caching. (default)"),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<float> CVarCSMScrollingOverlapAreaThrottle(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadowDepthRendering.cpp:154

Scope (from outer to inner):

file
function     void SetupShadowDepthPassUniformBuffer

Source code excerpt:

	FShadowDepthPassUniformParameters& ShadowDepthPassParameters)
{
	static const auto CSMCachingCVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.Shadow.CSMCaching"));
	const bool bCSMCachingEnabled = CSMCachingCVar && CSMCachingCVar->GetValueOnAnyThread() != 0;

	SetupSceneTextureUniformParameters(GraphBuilder, View.GetSceneTexturesChecked(), View.FeatureLevel, ESceneTextureSetupMode::None, ShadowDepthPassParameters.SceneTextures);

	ShadowDepthPassParameters.ProjectionMatrix = FTranslationMatrix44f(FVector3f(ShadowInfo->PreShadowTranslation - View.ViewMatrices.GetPreViewTranslation())) * ShadowInfo->TranslatedWorldToClipOuterMatrix;		// LWC_TDOO: Precision loss?
	ShadowDepthPassParameters.ViewMatrix = FMatrix44f(ShadowInfo->TranslatedWorldToView);	// LWC_TODO: Precision loss

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarCSMCaching(
	TEXT("r.Shadow.CSMCaching"),
	0,
	TEXT("0: Render CSM every frame.\n")
	TEXT("1: Enable CSM caching. (default)"),
	ECVF_RenderThreadSafe);

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

Scope (from outer to inner):

file
function     void ComputeViewDependentWholeSceneShadowCacheModes

Source code excerpt:

	EShadowDepthCacheMode* OutCacheModes)
{
	if (CVarCSMCaching.GetValueOnAnyThread() == 1 && !UseVirtualShadowMaps(Scene->GetShaderPlatform(), Scene->GetFeatureLevel()))
	{
		TArray<FCachedShadowMapData>* CachedShadowMapDatas = Scene->GetCachedShadowMapDatas(LightSceneInfo->Id);

		checkSlow(ProjectedShadowInitializer.CascadeSettings.ShadowSplitIndex >= 0);
		FCachedShadowMapData* CachedShadowMapData = (CachedShadowMapDatas && CachedShadowMapDatas->Num() > ProjectedShadowInitializer.CascadeSettings.ShadowSplitIndex) ? &(*CachedShadowMapDatas)[ProjectedShadowInitializer.CascadeSettings.ShadowSplitIndex] : nullptr;