r.Shadow.CacheWholeSceneShadows

r.Shadow.CacheWholeSceneShadows

#Overview

name: r.Shadow.CacheWholeSceneShadows

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

• type: Var
• help: When enabled, movable point and spot light whole scene shadow depths from static primitives will be cached as an optimization.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.CacheWholeSceneShadows is to enable caching of whole scene shadow depths from static primitives for movable point and spot lights as an optimization in the rendering system.

This setting variable is primarily used in the Renderer module of Unreal Engine, specifically in the shadow rendering subsystem. It affects how the engine handles shadow caching for certain types of lights.

The value of this variable is set through the console variable system in Unreal Engine. It’s initialized with a default value of 1 (enabled) and can be changed at runtime.

The r.Shadow.CacheWholeSceneShadows variable is directly associated with the GCacheWholeSceneShadows variable. They share the same value, and GCacheWholeSceneShadows is used in the actual C++ code to control the behavior.

Developers should be aware that this optimization is specifically for movable point and spot lights, and it only caches shadow depths from static primitives. It’s important to note that this feature requires either geometry shaders or vertex shader layer support on the current shader platform.

Best practices when using this variable include:

1. Keep it enabled (default value of 1) for better performance in scenes with many static objects and movable lights.
2. Consider disabling it if you notice any visual artifacts in shadows, especially in scenes with frequently changing lighting conditions.
3. Be aware that this optimization might increase memory usage due to caching.

Regarding the associated variable GCacheWholeSceneShadows:

• It’s an integer variable used internally in the C++ code to control the caching behavior.
• It’s directly tied to the r.Shadow.CacheWholeSceneShadows console variable.
• It’s used in the ComputeWholeSceneShadowCacheModes function to determine whether to perform the caching optimization.
• Developers working directly with the engine source code should use this variable for conditional logic related to shadow caching.

When modifying or relying on this variable in custom engine modifications, developers should ensure they’re considering the performance implications and potential visual impacts on shadow rendering.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

int32 GCacheWholeSceneShadows = 1;
FAutoConsoleVariableRef CVarCacheWholeSceneShadows(
	TEXT("r.Shadow.CacheWholeSceneShadows"),
	GCacheWholeSceneShadows,
	TEXT("When enabled, movable point and spot light whole scene shadow depths from static primitives will be cached as an optimization."),
	ECVF_Scalability | ECVF_RenderThreadSafe
	);

int32 GMaxNumPointShadowCacheUpdatesPerFrame = -1;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

extern int GEnableNonNaniteVSM;

int32 GCacheWholeSceneShadows = 1;
FAutoConsoleVariableRef CVarCacheWholeSceneShadows(
	TEXT("r.Shadow.CacheWholeSceneShadows"),
	GCacheWholeSceneShadows,
	TEXT("When enabled, movable point and spot light whole scene shadow depths from static primitives will be cached as an optimization."),
	ECVF_Scalability | ECVF_RenderThreadSafe
	);

int32 GMaxNumPointShadowCacheUpdatesPerFrame = -1;
FAutoConsoleVariableRef CVarMaxNumPointShadowCacheUpdatePerFrame(

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

Scope (from outer to inner):

file
function     void ComputeWholeSceneShadowCacheModes

Source code excerpt:

	}

	if (GCacheWholeSceneShadows 
		&& (!bCubeShadowMap || RHISupportsGeometryShaders(GShaderPlatformForFeatureLevel[Scene->GetFeatureLevel()]) || RHISupportsVertexShaderLayer(GShaderPlatformForFeatureLevel[Scene->GetFeatureLevel()])))
	{
		TArray<FCachedShadowMapData>* CachedShadowMapDatas = Scene->GetCachedShadowMapDatas(LightSceneInfo->Id);

		if (CachedShadowMapDatas)
		{