r.Shadow.Virtual.MaxPhysicalPages

r.Shadow.Virtual.MaxPhysicalPages

#Overview

name: r.Shadow.Virtual.MaxPhysicalPages

The value of this variable can be defined or overridden in .ini config files. 5 .ini config files referencing this setting variable.

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

• type: Var
• help: Maximum number of physical pages in the pool.\nMore space for pages means more memory usage, but allows for higher resolution shadows.\nIdeally this value is large enough to fit enough pages for all the lights in the scene, but not too large to waste memory.\nEnable \'ShowStats\' to see how many pages are allocated in the pool right now.\nFor more page pool control, see the \'ResolutionLodBias*\', \'DynamicRes.*\' and \'Cache.StaticSeparate\' cvars.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.Virtual.MaxPhysicalPages is to control the maximum number of physical pages in the virtual shadow map pool. This setting is crucial for the rendering system, specifically for the virtual shadow mapping feature in Unreal Engine 5.

This setting variable is primarily used by the Renderer module, particularly in the Virtual Shadow Maps subsystem. It’s referenced in the VirtualShadowMapArray.cpp file, which is part of the virtual shadow mapping implementation.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 2048, but can be changed at runtime or through configuration files.

The associated variable CVarMaxPhysicalPages directly interacts with r.Shadow.Virtual.MaxPhysicalPages. They share the same value and purpose.

Developers must be aware of several things when using this variable:

1. Increasing the value allows for higher resolution shadows but also increases memory usage.
2. The ideal value should be large enough to accommodate pages for all lights in the scene without wasting memory.
3. It directly affects the performance and visual quality of virtual shadow maps.

Best practices when using this variable include:

1. Monitor the actual page usage using the ‘ShowStats’ feature to fine-tune the value.
2. Balance between shadow quality and memory usage based on your project’s requirements.
3. Consider adjusting related settings like ‘ResolutionLodBias*’, ‘DynamicRes.*’, and ‘Cache.StaticSeparate’ for more granular control over the page pool.

Regarding the associated variable CVarMaxPhysicalPages:

• Its purpose is identical to r.Shadow.Virtual.MaxPhysicalPages, serving as the internal representation of the console variable.
• It’s used directly in the code to retrieve the current value of the setting, particularly in the FVirtualShadowMapArray::Initialize function.
• The value is accessed using GetValueOnRenderThread(), indicating it’s designed for use in render thread operations.
• Developers should be aware that changing r.Shadow.Virtual.MaxPhysicalPages will affect this variable, and vice versa.
• Best practices include using this variable for read-only purposes in the rendering code and modifying the value through the r.Shadow.Virtual.MaxPhysicalPages console command or configuration settings.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseScalability.ini:141, section: [ShadowQuality@0]

• INI Section: ShadowQuality@0
• Raw value: 512
• Is Array: False

Location: <Workspace>/Engine/Config/BaseScalability.ini:165, section: [ShadowQuality@1]

• INI Section: ShadowQuality@1
• Raw value: 512
• Is Array: False

Location: <Workspace>/Engine/Config/BaseScalability.ini:192, section: [ShadowQuality@2]

• INI Section: ShadowQuality@2
• Raw value: 2048
• Is Array: False

Location: <Workspace>/Engine/Config/BaseScalability.ini:219, section: [ShadowQuality@3]

• INI Section: ShadowQuality@3
• Raw value: 4096
• Is Array: False

Location: <Workspace>/Engine/Config/BaseScalability.ini:246, section: [ShadowQuality@Cine]

• INI Section: ShadowQuality@Cine
• Raw value: 8192
• 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/VirtualShadowMaps/VirtualShadowMapArray.cpp:63

Scope: file

Source code excerpt:

TAutoConsoleVariable<int32> CVarMaxPhysicalPages(
	TEXT("r.Shadow.Virtual.MaxPhysicalPages"),
	2048,
	TEXT("Maximum number of physical pages in the pool.\n")
	TEXT("More space for pages means more memory usage, but allows for higher resolution shadows.\n")
	TEXT("Ideally this value is large enough to fit enough pages for all the lights in the scene, but not too large to waste memory.\n")
	TEXT("Enable 'ShowStats' to see how many pages are allocated in the pool right now.\n")
	TEXT("For more page pool control, see the 'ResolutionLodBias*', 'DynamicRes.*' and 'Cache.StaticSeparate' cvars."),

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

TAutoConsoleVariable<int32> CVarMaxPhysicalPages(
	TEXT("r.Shadow.Virtual.MaxPhysicalPages"),
	2048,
	TEXT("Maximum number of physical pages in the pool.\n")
	TEXT("More space for pages means more memory usage, but allows for higher resolution shadows.\n")
	TEXT("Ideally this value is large enough to fit enough pages for all the lights in the scene, but not too large to waste memory.\n")
	TEXT("Enable 'ShowStats' to see how many pages are allocated in the pool right now.\n")

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VirtualShadowMaps/VirtualShadowMapArray.cpp:461

Scope (from outer to inner):

file
function     void FVirtualShadowMapArray::Initialize

Source code excerpt:

		const uint32 PhysicalPagesX = FMath::DivideAndRoundDown(GetMax2DTextureDimension(), FVirtualShadowMap::PageSize);
		check(FMath::IsPowerOfTwo(PhysicalPagesX));
		const int32 MaxPhysicalPages = CVarMaxPhysicalPages.GetValueOnRenderThread();
		uint32 PhysicalPagesY = FMath::DivideAndRoundUp((uint32)FMath::Max(1, MaxPhysicalPages), PhysicalPagesX);	

		UniformParameters.MaxPhysicalPages = PhysicalPagesX * PhysicalPagesY;
				
		if (CVarCacheStaticSeparate.GetValueOnRenderThread() != 0)
		{