r.Shadow.MaxNumSpotShadowCacheUpdatesPerFrame

r.Shadow.MaxNumSpotShadowCacheUpdatesPerFrame

#Overview

name: r.Shadow.MaxNumSpotShadowCacheUpdatesPerFrame

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).

• type: Var
• help: Maximum number of spot light shadow cache updates allowed per frame.Only affect updates caused by resolution change. -1 means no limit.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.MaxNumSpotShadowCacheUpdatesPerFrame is to control the maximum number of spot light shadow cache updates allowed per frame in Unreal Engine’s rendering system. This setting specifically affects updates caused by resolution changes and is used to manage performance and resource allocation in the shadow rendering pipeline.

This setting variable is primarily used in the Renderer module of Unreal Engine, specifically within the shadow setup and rendering subsystem. Based on the callsites, it’s clear that this variable is utilized in the ShadowSetup.cpp file, which is part of the core rendering functionality.

The value of this variable is set through the Unreal Engine console variable system. It’s defined using FAutoConsoleVariableRef, which allows it to be modified at runtime through console commands or configuration files.

The associated variable GMaxNumSpotShadowCacheUpdatesPerFrame directly interacts with r.Shadow.MaxNumSpotShadowCacheUpdatesPerFrame. They share the same value, with GMaxNumSpotShadowCacheUpdatesPerFrame being the actual integer variable used in the C++ code to control the behavior.

Developers must be aware that:

1. The default value is -1, which means no limit on spot light shadow cache updates per frame.
2. This setting only affects updates caused by resolution changes, not all shadow updates.
3. It’s marked with ECVF_Scalability and ECVF_RenderThreadSafe flags, indicating it’s related to performance scaling and can be safely modified on the render thread.

Best practices when using this variable include:

1. Setting a reasonable limit based on the target hardware and performance requirements of the game or application.
2. Monitoring performance impact when adjusting this value, especially on lower-end hardware.
3. Consider using different values for different quality settings in the game’s graphics options.

Regarding the associated variable GMaxNumSpotShadowCacheUpdatesPerFrame:

• Its purpose is to provide a C++ accessible integer that reflects the console variable’s value.
• It’s used directly in the ComputeWholeSceneShadowCacheModes function to determine the maximum number of allowed cache updates for spot lights.
• Developers should not modify this variable directly but instead use the console variable system to ensure proper synchronization and thread safety.
• When reading this value in code, be aware that -1 means no limit, so appropriate checks should be made when using it in calculations or comparisons.

#Setting Variables

#References In INI files

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

• INI Section: Android_Vulkan_SM5 DeviceProfile
• Raw value: 1
• Is Array: False

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

int32 GMaxNumSpotShadowCacheUpdatesPerFrame = -1;
FAutoConsoleVariableRef CVarMaxNumSpotShadowCacheUpdatePerFrame(
	TEXT("r.Shadow.MaxNumSpotShadowCacheUpdatesPerFrame"),
	GMaxNumSpotShadowCacheUpdatesPerFrame,
	TEXT("Maximum number of spot light shadow cache updates allowed per frame."
		"Only affect updates caused by resolution change. -1 means no limit."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

int32 GMaxNumSpotShadowCacheUpdatesPerFrame = -1;
FAutoConsoleVariableRef CVarMaxNumSpotShadowCacheUpdatePerFrame(
	TEXT("r.Shadow.MaxNumSpotShadowCacheUpdatesPerFrame"),
	GMaxNumSpotShadowCacheUpdatesPerFrame,
	TEXT("Maximum number of spot light shadow cache updates allowed per frame."
		"Only affect updates caused by resolution change. -1 means no limit."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GWholeSceneShadowCacheMb = 150;

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

Scope (from outer to inner):

file
function     void ComputeWholeSceneShadowCacheModes

Source code excerpt:

	case LightType_Spot:
		NumCachesUpdatedThisFrame = &InOutNumSpotShadowCachesUpdatedThisFrame;
		MaxCacheUpdatesAllowed = static_cast<uint32>(GMaxNumSpotShadowCacheUpdatesPerFrame);
		break;
	default:
		checkf(false, TEXT("Directional light isn't handled here"));
		break;
	}