r.Shadow.Virtual.Cache.MaxPageAgeSinceLastRequest

r.Shadow.Virtual.Cache.MaxPageAgeSinceLastRequest

#Overview

name: r.Shadow.Virtual.Cache.MaxPageAgeSinceLastRequest

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

• type: Var
• help: The maximum number of frames to allow cached pages that aren\'t requested in the current frame to live. 0=disabled.

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.Virtual.Cache.MaxPageAgeSinceLastRequest is to control the caching behavior of virtual shadow map pages in Unreal Engine 5’s rendering system. Specifically, it determines how long unused pages are kept in the cache before they are considered for removal or invalidation.

Key points about this setting variable:

1. It is part of the virtual shadow mapping system, which is a rendering optimization technique used in UE5.

2. The Renderer module, specifically the VirtualShadowMaps subsystem, relies on this variable.

3. The value is set through a console variable, allowing runtime adjustment.

4. It represents the number of frames that a cached page can remain unused before it’s considered for removal.

5. The default value is 3 frames, providing a balance between cache efficiency and memory usage.

6. Setting it to 0 disables this caching mechanism entirely.

7. It interacts with the scene frame number and the last referenced frame number of cache entries.

8. Developers should be aware that increasing this value will keep unused pages in memory longer, potentially increasing memory usage but reducing recomputation of shadow data.

9. Conversely, decreasing this value may free up memory more quickly but could lead to more frequent recomputation of shadow data.

Best practices when using this variable:

1. Monitor performance and memory usage when adjusting this value.
2. Consider project-specific needs - games with rapidly changing scenes might benefit from lower values, while more static scenes could use higher values.
3. Use in conjunction with other virtual shadow map settings for optimal performance.

The associated variable GVSMMaxPageAgeSinceLastRequest is the internal representation of this console variable. It’s used directly in the code to implement the caching logic. The same considerations apply to this variable as to the console variable itself.

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

Scope: file

Source code excerpt:

int32 GVSMMaxPageAgeSinceLastRequest = 3;
FAutoConsoleVariableRef CVarVSMMaxPageAgeSinceLastRequest(
	TEXT("r.Shadow.Virtual.Cache.MaxPageAgeSinceLastRequest"),
	GVSMMaxPageAgeSinceLastRequest,
	TEXT("The maximum number of frames to allow cached pages that aren't requested in the current frame to live. 0=disabled."),
	ECVF_RenderThreadSafe
);

static TAutoConsoleVariable<int32> CVarFramesStaticThreshold(

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

extern int32 GForceInvalidateDirectionalVSM;
extern int32 GVSMMaxPageAgeSinceLastRequest;
extern TAutoConsoleVariable<float> CVarNaniteMaxPixelsPerEdge;
extern TAutoConsoleVariable<float> CVarNaniteMinPixelsPerEdgeHW;

int32 GVSMShowLightDrawEvents = 0;
FAutoConsoleVariableRef CVarVSMShowLightDrawEvents(
	TEXT("r.Shadow.Virtual.ShowLightDrawEvents"),

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

Scope (from outer to inner):

file
function     void FVirtualShadowMapArray::BuildPageAllocations

Source code excerpt:

			PassParameters->OutPageFlags			   = GraphBuilder.CreateUAV(PageFlagsRDG);
			PassParameters->PrevPhysicalPageLists      = GraphBuilder.CreateSRV(GraphBuilder.RegisterExternalBuffer(CacheManager->GetPrevBuffers().PhysicalPageLists));
			PassParameters->MaxPageAgeSinceLastRequest = GVSMMaxPageAgeSinceLastRequest;
			PassParameters->bDynamicPageInvalidation   = 1;
#if !UE_BUILD_SHIPPING
			PassParameters->bDynamicPageInvalidation   = CVarDebugSkipDynamicPageInvalidation.GetValueOnRenderThread() == 0 ? 1 : 0;
#endif
			PassParameters->bAllocateViaLRU			   = CVarCacheAllocateViaLRU.GetValueOnRenderThread();
		}

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

Scope: file

Source code excerpt:

// We give a little leeway here as occasionally the scene frame number is incremented multiple times between frames
int32 GVSMMaxPageAgeSinceLastRequest = 3;
FAutoConsoleVariableRef CVarVSMMaxPageAgeSinceLastRequest(
	TEXT("r.Shadow.Virtual.Cache.MaxPageAgeSinceLastRequest"),
	GVSMMaxPageAgeSinceLastRequest,
	TEXT("The maximum number of frames to allow cached pages that aren't requested in the current frame to live. 0=disabled."),
	ECVF_RenderThreadSafe
);

static TAutoConsoleVariable<int32> CVarFramesStaticThreshold(
	TEXT("r.Shadow.Virtual.Cache.StaticSeparate.FramesStaticThreshold"),

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

Scope (from outer to inner):

file
function     void FVirtualShadowMapArrayCacheManager::UpdateUnreferencedCacheEntries

Source code excerpt:

			check(CacheEntry->ShadowMapEntries.Last().CurrentVirtualShadowMapId < VirtualShadowMapArray.GetNumShadowMapSlots());
		}
		else if (int32(SceneFrameNumber - CacheEntry->LastReferencedFrameNumber) <= GVSMMaxPageAgeSinceLastRequest)
		{
			// Not active this render, but still recent enough to keep it and its pages alive
			int PrevBaseVirtualShadowMapId = CacheEntry->ShadowMapEntries[0].CurrentVirtualShadowMapId;
			bool bIsSinglePage = FVirtualShadowMapArray::IsSinglePage(PrevBaseVirtualShadowMapId);

			// Keep the entry, reallocate new VSM IDs