r.Shadow.WholeSceneShadowCacheMb

r.Shadow.WholeSceneShadowCacheMb

#Overview

name: r.Shadow.WholeSceneShadowCacheMb

The value of this variable can be defined or overridden in .ini config files. 1 .ini config file 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.WholeSceneShadowCacheMb is to control the amount of memory that can be allocated for caching whole scene shadows in Unreal Engine 5’s rendering system.

This setting variable is primarily used by the Renderer module of Unreal Engine 5, specifically in the shadow rendering subsystem. It’s defined in the ShadowSetup.cpp file, which is part of the core rendering pipeline.

The value of this variable is set through the Unreal Engine console variable system. It’s initialized with a default value of 150 MB, but can be modified at runtime or through configuration files.

The variable r.Shadow.WholeSceneShadowCacheMb is directly associated with the C++ variable GWholeSceneShadowCacheMb. They share the same value, with the console variable acting as an interface for runtime modification.

Developers must be aware that this variable affects memory usage and rendering performance. Setting it too high might consume excessive memory, while setting it too low could reduce shadow quality or increase rendering time due to less caching.

Best practices when using this variable include:

  1. Adjusting it based on the target hardware capabilities.
  2. Monitoring performance and memory usage when modifying this value.
  3. Considering the complexity of your scene and the importance of shadow quality in your game.

Regarding the associated variable GWholeSceneShadowCacheMb:

The purpose of GWholeSceneShadowCacheMb is to store the actual memory limit for whole scene shadow caching within the C++ code.

This variable is used directly in the rendering code, specifically in the TryToCacheShadowMap function in ShadowSetup.cpp. It determines whether additional shadow maps can be cached based on the current cached shadow maps size.

The value of GWholeSceneShadowCacheMb is set by the console variable r.Shadow.WholeSceneShadowCacheMb, allowing for runtime configuration.

Developers should be aware that modifying GWholeSceneShadowCacheMb directly in the code is not recommended, as it will be overwritten by the console variable. Instead, they should use the r.Shadow.WholeSceneShadowCacheMb console variable to adjust this setting.

Best practices for GWholeSceneShadowCacheMb include:

  1. Treating it as a read-only variable in most cases.
  2. Using it for comparisons in rendering code to determine caching behavior.
  3. Ensuring that any code referencing this variable can handle potential runtime changes to its value.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseDeviceProfiles.ini:899, section: [Android_Vulkan_SM5 DeviceProfile]

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

int32 GWholeSceneShadowCacheMb = 150;
FAutoConsoleVariableRef CVarWholeSceneShadowCacheMb(
	TEXT("r.Shadow.WholeSceneShadowCacheMb"),
	GWholeSceneShadowCacheMb,
	TEXT("Amount of memory that can be spent caching whole scene shadows.  ShadowMap allocations in a single frame can cause this to be exceeded."),
	ECVF_Scalability | ECVF_RenderThreadSafe
	);

int32 GCachedShadowsCastFromMovablePrimitives = 1;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

int32 GWholeSceneShadowCacheMb = 150;
FAutoConsoleVariableRef CVarWholeSceneShadowCacheMb(
	TEXT("r.Shadow.WholeSceneShadowCacheMb"),
	GWholeSceneShadowCacheMb,
	TEXT("Amount of memory that can be spent caching whole scene shadows.  ShadowMap allocations in a single frame can cause this to be exceeded."),
	ECVF_Scalability | ECVF_RenderThreadSafe
	);

int32 GCachedShadowsCastFromMovablePrimitives = 1;
FAutoConsoleVariableRef CVarCachedWholeSceneShadowsCastFromMovablePrimitives(

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

Scope (from outer to inner):

file
function     void TryToCacheShadowMap

Source code excerpt:

void TryToCacheShadowMap(const FScene* Scene, int64 CachedShadowMapsSize, int32& OutNumShadowMaps, EShadowDepthCacheMode* OutCacheModes, uint32& NumCachesUpdatedThisFrame, CacheLambdaType&& CacheLambda, UnCacheLambdaType&& UnCacheLambda)
{
	if (CachedShadowMapsSize < static_cast<int64>(GWholeSceneShadowCacheMb) * 1024 * 1024)
	{
		OutNumShadowMaps = 2;
		// Note: ShadowMap with static primitives rendered first so movable shadowmap can composite
		OutCacheModes[0] = SDCM_StaticPrimitivesOnly;
		OutCacheModes[1] = SDCM_MovablePrimitivesOnly;
		++NumCachesUpdatedThisFrame;