r.Shadow.Virtual.Cache.StaticSeparate.FramesStaticThreshold

r.Shadow.Virtual.Cache.StaticSeparate.FramesStaticThreshold

#Overview

name: r.Shadow.Virtual.Cache.StaticSeparate.FramesStaticThreshold

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

• type: Var
• help: Number of frames without an invalidation before an object will transition to static caching.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.Virtual.Cache.StaticSeparate.FramesStaticThreshold is to control the transition of objects from dynamic to static caching in the virtual shadow map system. It specifically sets the number of frames an object must remain unchanged before it is considered for static caching.

This setting variable is primarily used in the rendering system, specifically in the virtual shadow map subsystem of Unreal Engine 5. Based on the callsites, it’s evident that this variable is utilized within the VirtualShadowMapCacheManager module.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 100 frames, but can be adjusted at runtime through console commands or project settings.

The associated variable CVarFramesStaticThreshold directly interacts with r.Shadow.Virtual.Cache.StaticSeparate.FramesStaticThreshold. They share the same value and purpose.

Developers must be aware that this variable affects the performance and memory usage of the virtual shadow map system. A lower value will cause objects to transition to static caching more quickly, potentially saving performance but using more memory. A higher value will keep objects in dynamic caching longer, which might be more memory-efficient but could impact performance.

Best practices when using this variable include:

1. Carefully balancing between performance and memory usage based on the specific needs of the project.
2. Monitoring the impact of changes to this value on both rendering performance and memory consumption.
3. Considering the nature of the scene - scenes with many static objects might benefit from a lower threshold, while highly dynamic scenes might perform better with a higher threshold.
4. Using profiling tools to determine the optimal value for specific scenarios.

Regarding the associated variable CVarFramesStaticThreshold, it serves as the direct interface for accessing and modifying the r.Shadow.Virtual.Cache.StaticSeparate.FramesStaticThreshold value within the C++ code. It’s used in the UpdateCachePrimitiveAsDynamic function to determine when primitives should transition from dynamic to static caching. The same considerations and best practices apply to this variable as they do to r.Shadow.Virtual.Cache.StaticSeparate.FramesStaticThreshold.

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

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarFramesStaticThreshold(
	TEXT("r.Shadow.Virtual.Cache.StaticSeparate.FramesStaticThreshold"),
	100,
	TEXT("Number of frames without an invalidation before an object will transition to static caching."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarVSMReservedResource(
	TEXT("r.Shadow.Virtual.AllocatePagePoolAsReservedResource"),

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarFramesStaticThreshold(
	TEXT("r.Shadow.Virtual.Cache.StaticSeparate.FramesStaticThreshold"),
	100,
	TEXT("Number of frames without an invalidation before an object will transition to static caching."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarVSMReservedResource(

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

Scope (from outer to inner):

file
function     void FVirtualShadowMapArrayCacheManager::UpdateCachePrimitiveAsDynamic

Source code excerpt:

	const uint32 SceneFrameNumber = Scene->GetFrameNumberRenderThread();
	const uint32 FramesStaticThreshold = CVarFramesStaticThreshold.GetValueOnRenderThread();

	// Update the cache states of things that are being invalidated
	for (TConstSetBitIterator<> BitIt(InvalidatingPrimitiveCollector.InvalidatedPrimitives); BitIt; ++BitIt)
	{
		int32 PersistentPrimitiveIndex = BitIt.GetIndex();
		// Any invalidations mean we set this primitive to dynamic. We already added an invalidation otherwise