r.Shadow.Virtual.Cache.StaticSeparate

r.Shadow.Virtual.Cache.StaticSeparate

#Overview

name: r.Shadow.Virtual.Cache.StaticSeparate

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.Virtual.Cache.StaticSeparate is to control the caching behavior of static objects in virtual shadow maps. This setting variable is part of Unreal Engine 5’s rendering system, specifically the virtual shadow mapping feature.

This setting variable is primarily used in the Renderer module of Unreal Engine 5, as evidenced by its definition and usage in the VirtualShadowMapArray.cpp file. It’s also referenced in the MetalRHI module, indicating its relevance to Metal-based rendering on Apple platforms.

The value of this variable is set through a console command, as it’s defined as a TAutoConsoleVariable. By default, it’s set to 1 (enabled).

The associated variable CVarCacheStaticSeparate interacts directly with r.Shadow.Virtual.Cache.StaticSeparate, as they share the same value and purpose.

Developers must be aware of several important aspects when using this variable:

  1. When enabled (set to 1), it caches static objects in separate pages from dynamic objects in virtual shadow maps.
  2. This can improve performance in largely static scenes but doubles the memory cost of the physical page pool.
  3. On Metal-based platforms (Apple devices), this setting is forcibly disabled due to limitations with atomic operations on Texture2DArrays.

Best practices when using this variable include:

  1. Enable it for scenes with a high proportion of static objects to potentially improve performance.
  2. Be mindful of the increased memory usage when enabled, and disable it if memory constraints are an issue.
  3. Consider the trade-off between performance improvement and memory cost based on your specific scene and target hardware.
  4. Be aware that this setting will not take effect on Metal-based platforms.

Regarding the associated variable CVarCacheStaticSeparate:

The purpose of CVarCacheStaticSeparate is identical to r.Shadow.Virtual.Cache.StaticSeparate, as they are directly linked. It’s an internal representation of the console variable used within the C++ code.

This variable is used within the Renderer module, specifically in the virtual shadow mapping system. It’s checked in the FVirtualShadowMapArray::Initialize function to determine whether to enable separate static caching.

The value of CVarCacheStaticSeparate is set through the console variable r.Shadow.Virtual.Cache.StaticSeparate.

Developers should be aware that changes to r.Shadow.Virtual.Cache.StaticSeparate will directly affect CVarCacheStaticSeparate, and vice versa. The same considerations and best practices apply to both variables.

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

Scope: file

Source code excerpt:


TAutoConsoleVariable<int32> CVarCacheStaticSeparate(
	TEXT("r.Shadow.Virtual.Cache.StaticSeparate"),
	1,
	TEXT("When enabled, caches static objects in separate pages from dynamic objects.\n")
	TEXT("This can improve performance in largely static scenes, but doubles the memory cost of the physical page pool."),
	ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Apple/MetalRHI/Private/MetalRHI.cpp:438

Scope: file

Source code excerpt:

		{
			// Switch back to single page allocation for VSM (Metal does not support atomic operations on Texture2DArrays...).
			IConsoleVariable* VSMCacheStaticSeparateCVar = IConsoleManager::Get().FindConsoleVariable(TEXT("r.Shadow.Virtual.Cache.StaticSeparate"));
			if (VSMCacheStaticSeparateCVar != nullptr)
			{
				VSMCacheStaticSeparateCVar->Set(0);
			}
		}
	}

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

TAutoConsoleVariable<int32> CVarCacheStaticSeparate(
	TEXT("r.Shadow.Virtual.Cache.StaticSeparate"),
	1,
	TEXT("When enabled, caches static objects in separate pages from dynamic objects.\n")
	TEXT("This can improve performance in largely static scenes, but doubles the memory cost of the physical page pool."),
	ECVF_RenderThreadSafe
);

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

Scope (from outer to inner):

file
function     void FVirtualShadowMapArray::Initialize

Source code excerpt:

		UniformParameters.MaxPhysicalPages = PhysicalPagesX * PhysicalPagesY;
				
		if (CVarCacheStaticSeparate.GetValueOnRenderThread() != 0)
		{
			#if !DEBUG_ALLOW_STATIC_SEPARATE_WITHOUT_CACHING
			if (CacheManager->IsCacheEnabled())
			#endif
			{
				// Enable separate static caching in the second texture array element