r.Shadow.Virtual.AllocatePagePoolAsReservedResource

r.Shadow.Virtual.AllocatePagePoolAsReservedResource

#Overview

name: r.Shadow.Virtual.AllocatePagePoolAsReservedResource

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.Virtual.AllocatePagePoolAsReservedResource is to control how the Virtual Shadow Map (VSM) page pool is allocated in memory. It is part of the rendering system, specifically focusing on shadow rendering optimization.

This setting variable is primarily used in the Virtual Shadow Maps subsystem of Unreal Engine’s rendering module. It’s referenced in the VirtualShadowMapCacheManager.cpp file, which suggests it’s closely tied to the management of virtual shadow map caches.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 1, meaning it’s enabled by default. Developers can change this value at runtime using console commands.

This variable interacts closely with its associated variable CVarVSMReservedResource. They share the same value and purpose, with CVarVSMReservedResource being the actual console variable object used in the code.

Developers must be aware that this variable affects memory allocation strategies for the VSM page pool. When enabled (set to 1), it allocates the VSM page pool as a reserved/virtual texture, backed by multiple small physical memory allocations. This approach is designed to reduce memory fragmentation.

Best practices when using this variable include:

  1. Consider the target platform’s memory management capabilities. The reserved resource allocation method may be more beneficial on some platforms than others.
  2. Monitor performance and memory usage when changing this setting, as it can impact both rendering efficiency and memory consumption.
  3. Be cautious when changing this value at runtime, as it may cause reallocation of resources which could lead to temporary performance hitches.

Regarding the associated variable CVarVSMReservedResource:

The purpose of CVarVSMReservedResource is identical to r.Shadow.Virtual.AllocatePagePoolAsReservedResource. It’s the actual console variable object used in the C++ code to control the VSM page pool allocation strategy.

This variable is used in the same Virtual Shadow Maps subsystem and is defined in the VirtualShadowMapCacheManager.cpp file.

The value of CVarVSMReservedResource is set through the console variable system, with the same default value of 1.

It directly interacts with the rendering code, influencing how the PhysicalPagePool for virtual shadow maps is created. When enabled, it adds the TexCreate_ReservedResource and TexCreate_ImmediateCommit flags to the texture creation process.

Developers should be aware that this variable’s value is checked on the render thread (GetValueOnRenderThread()), which means changes to it will be applied on the next render frame.

Best practices for CVarVSMReservedResource are the same as for r.Shadow.Virtual.AllocatePagePoolAsReservedResource, given they represent the same setting. Additionally, developers should ensure that any code relying on this setting is properly synchronized with the render thread to avoid potential race conditions.

#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:85

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarVSMReservedResource(
	TEXT("r.Shadow.Virtual.AllocatePagePoolAsReservedResource"),
	1,
	TEXT("Allocate VSM page pool as a reserved/virtual texture, backed by N small physical memory allocations to reduce fragmentation."),
	ECVF_RenderThreadSafe
);

static TAutoConsoleVariable<float> CVarVSMDynamicResolutionMaxLodBias(

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarVSMReservedResource(
	TEXT("r.Shadow.Virtual.AllocatePagePoolAsReservedResource"),
	1,
	TEXT("Allocate VSM page pool as a reserved/virtual texture, backed by N small physical memory allocations to reduce fragmentation."),
	ECVF_RenderThreadSafe
);

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

Scope (from outer to inner):

file
function     void FVirtualShadowMapArrayCacheManager::SetPhysicalPoolSize

Source code excerpt:

	// Using ReservedResource|ImmediateCommit flags hint to the RHI that the resource can be allocated using N small physical memory allocations,
	// instead of a single large contighous allocation. This helps Windows video memory manager page allocations in and out of local memory more efficiently.
	ETextureCreateFlags RequestedCreateFlags = (CVarVSMReservedResource.GetValueOnRenderThread() && GRHIGlobals.ReservedResources.Supported)
		? (TexCreate_ReservedResource | TexCreate_ImmediateCommit)
		: TexCreate_None;

	if (!PhysicalPagePool 
		|| PhysicalPagePool->GetDesc().Extent != RequestedSize 
		|| PhysicalPagePool->GetDesc().ArraySize != RequestedArraySize