r.Shadow.Virtual.DynamicRes.MaxPagePoolLoadFactor

r.Shadow.Virtual.DynamicRes.MaxPagePoolLoadFactor

#Overview

name: r.Shadow.Virtual.DynamicRes.MaxPagePoolLoadFactor

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

• type: Var
• help: If allocation exceeds this factor of total page pool capacity, shadow resolution will be biased downwards. 0 = disabled

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.Virtual.DynamicRes.MaxPagePoolLoadFactor is to control the dynamic resolution of virtual shadow maps based on the page pool allocation. It sets a threshold for when the shadow resolution should be adjusted downwards to manage memory usage.

This setting variable is primarily used by the rendering system, specifically the virtual shadow mapping subsystem within Unreal Engine 5. Based on the callsites, it’s part of the Renderer module and is utilized in the VirtualShadowMapCacheManager.

The value of this variable is set as a console variable with a default value of 0.85 (85%). It can be modified at runtime through the console or configuration files.

The variable interacts with other virtual shadow map-related variables, particularly those controlling dynamic resolution. It works in conjunction with CVarVSMDynamicResolutionMaxLodBias to determine when and how to adjust shadow resolution.

Developers must be aware that this variable directly impacts the trade-off between shadow quality and memory usage. A lower value will cause the engine to reduce shadow resolution more aggressively, potentially improving performance but at the cost of visual quality.

Best practices for using this variable include:

1. Adjusting it based on the target hardware capabilities and the game’s visual requirements.
2. Monitoring its effects on both visual quality and performance.
3. Using it in conjunction with other virtual shadow map settings for optimal results.

Regarding the associated variable CVarVSMDynamicResolutionMaxPagePoolLoadFactor:

This is the actual console variable object that stores and manages the r.Shadow.Virtual.DynamicRes.MaxPagePoolLoadFactor setting. It’s defined using TAutoConsoleVariable, which allows for runtime modification and thread-safe access.

The purpose of CVarVSMDynamicResolutionMaxPagePoolLoadFactor is to provide a programmatic interface for getting and setting the MaxPagePoolLoadFactor value within the engine’s code.

This variable is used directly in the VirtualShadowMapCacheManager to retrieve the current setting value on the render thread. It’s crucial for the dynamic resolution system of virtual shadow maps.

Developers should be aware that changes to this variable will take effect on the render thread, which may not be immediate depending on the current engine state.

Best practices for using CVarVSMDynamicResolutionMaxPagePoolLoadFactor include:

1. Accessing its value using GetValueOnRenderThread() when in render thread code.
2. Considering thread safety when modifying or reading this value from different engine subsystems.
3. Using it in conjunction with other virtual shadow map console variables for comprehensive control over the shadow mapping system.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VirtualShadowMaps/VirtualShadowMapCacheManager.cpp:100

Scope: file

Source code excerpt:

static TAutoConsoleVariable<float> CVarVSMDynamicResolutionMaxPagePoolLoadFactor(
	TEXT("r.Shadow.Virtual.DynamicRes.MaxPagePoolLoadFactor"),
	0.85f,
	TEXT("If allocation exceeds this factor of total page pool capacity, shadow resolution will be biased downwards. 0 = disabled"),
	ECVF_RenderThreadSafe
);

namespace Nanite

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VirtualShadowMaps/VirtualShadowMapCacheManager.cpp:99

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<float> CVarVSMDynamicResolutionMaxPagePoolLoadFactor(
	TEXT("r.Shadow.Virtual.DynamicRes.MaxPagePoolLoadFactor"),
	0.85f,
	TEXT("If allocation exceeds this factor of total page pool capacity, shadow resolution will be biased downwards. 0 = disabled"),
	ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VirtualShadowMaps/VirtualShadowMapCacheManager.cpp:518

Scope (from outer to inner):

file
function     FVirtualShadowMapArrayCacheManager::FVirtualShadowMapArrayCacheManager
lambda-function

Source code excerpt:

			const uint32 FramesBeforeResolutionUp = 10;

			const float MaxPageAllocation = CVarVSMDynamicResolutionMaxPagePoolLoadFactor.GetValueOnRenderThread();
			const float MaxLodBias = CVarVSMDynamicResolutionMaxLodBias.GetValueOnRenderThread();
			
			if (MaxPageAllocation > 0.0f)
			{
				const uint32 SceneFrameNumber = Scene->GetFrameNumberRenderThread();