r.Shadow.Virtual.Cache.DebugSkipDynamicPageInvalidation

r.Shadow.Virtual.Cache.DebugSkipDynamicPageInvalidation

#Overview

name: r.Shadow.Virtual.Cache.DebugSkipDynamicPageInvalidation

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.Cache.DebugSkipDynamicPageInvalidation is to control the invalidation of cached pages in virtual shadow maps when geometry moves, specifically for debugging purposes.

This setting variable is used in the rendering system, particularly in the virtual shadow mapping subsystem of Unreal Engine 5. It’s part of the shadow caching mechanism that aims to improve performance by reusing shadow information from previous frames.

The variable is set and used within the Renderer module, specifically in the VirtualShadowMapArray.cpp file. It’s implemented as a console variable (CVar) which allows it to be changed at runtime for debugging purposes.

The value of this variable is checked during the shadow map page allocation process. When set to 0 (default), it allows normal dynamic page invalidation. When set to a non-zero value, it skips the invalidation of cached pages when geometry moves.

This variable interacts closely with the shadow caching system. It’s used in conjunction with other variables related to virtual shadow map allocation and caching.

Developers must be aware that enabling this debug feature (setting it to a non-zero value) will create obvious visual artifacts. The shadows won’t update correctly when objects move, as the cached shadow information isn’t being invalidated.

Best practices for using this variable include:

  1. Only enable it temporarily for debugging purposes.
  2. Be prepared for visual artifacts when enabled.
  3. Always disable it (set to 0) for final builds or when not actively debugging shadow caching issues.

The associated variable CVarDebugSkipDynamicPageInvalidation is the actual console variable object that controls this setting. It’s defined in the same file and is used to set the value of the bDynamicPageInvalidation parameter in the shadow mapping process.

This associated variable is initialized with a default value of 0, meaning dynamic page invalidation is enabled by default. It can be changed at runtime through the console, allowing for on-the-fly debugging of shadow caching issues.

The same considerations and best practices apply to CVarDebugSkipDynamicPageInvalidation as to the r.Shadow.Virtual.Cache.DebugSkipDynamicPageInvalidation setting itself, as they are essentially two sides of the same coin - one being the console command, and the other being the actual variable used in the code.

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

Scope: file

Source code excerpt:


TAutoConsoleVariable<int32> CVarDebugSkipDynamicPageInvalidation(
	TEXT("r.Shadow.Virtual.Cache.DebugSkipDynamicPageInvalidation"),
	0,
	TEXT("Skip invalidation of cached pages when geometry moves for debugging purposes. This will create obvious visual artifacts when disabled."),
	ECVF_RenderThreadSafe
);

TAutoConsoleVariable<int32> CVarNumPageAreaDiagSlots(

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

TAutoConsoleVariable<int32> CVarDebugSkipDynamicPageInvalidation(
	TEXT("r.Shadow.Virtual.Cache.DebugSkipDynamicPageInvalidation"),
	0,
	TEXT("Skip invalidation of cached pages when geometry moves for debugging purposes. This will create obvious visual artifacts when disabled."),
	ECVF_RenderThreadSafe
);

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

Scope (from outer to inner):

file
function     void FVirtualShadowMapArray::BuildPageAllocations

Source code excerpt:

			PassParameters->bDynamicPageInvalidation   = 1;
#if !UE_BUILD_SHIPPING
			PassParameters->bDynamicPageInvalidation   = CVarDebugSkipDynamicPageInvalidation.GetValueOnRenderThread() == 0 ? 1 : 0;
#endif
			PassParameters->bAllocateViaLRU			   = CVarCacheAllocateViaLRU.GetValueOnRenderThread();
		}

		FUpdatePhysicalPages::FPermutationDomain PermutationVector;
		PermutationVector.Set<FUpdatePhysicalPages::FHasCacheDataDim>(bCacheDataAvailable);