r.Shadow.Virtual.Cache.ClipmapPanning

r.Shadow.Virtual.Cache.ClipmapPanning

#Overview

name: r.Shadow.Virtual.Cache.ClipmapPanning

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.ClipmapPanning is to enable support for panning cached clipmap pages for directional lights in the virtual shadow map system. This setting allows for the re-use of cached shadow data when the camera moves, which can improve performance and reduce computation overhead.

This setting variable is primarily used in the rendering subsystem of Unreal Engine 5, specifically within the virtual shadow map implementation. It’s part of the advanced shadow rendering features that UE5 offers.

The value of this variable is set through the console variable system in Unreal Engine. It’s defined as an FAutoConsoleVariableRef, which means it can be changed at runtime through console commands or configuration files.

The associated variable GClipmapPanning directly interacts with r.Shadow.Virtual.Cache.ClipmapPanning. They share the same value, and GClipmapPanning is used in the actual C++ code to control the behavior of the clipmap panning feature.

Developers must be aware that this variable affects the caching behavior of virtual shadow maps for directional lights. When enabled (which is the default state), it allows for more efficient use of shadow map data as the camera moves through the scene. Disabling it may lead to more frequent shadow map updates and potentially lower performance.

Best practices when using this variable include:

  1. Keeping it enabled for most scenarios, as suggested by the comment in the code.
  2. Only disabling it for debugging purposes when investigating issues related to shadow caching.
  3. Monitoring performance when modifying this setting, as it can have a significant impact on shadow rendering efficiency.

Regarding the associated variable GClipmapPanning:

The purpose of GClipmapPanning is to serve as the actual flag used in the C++ code to control the clipmap panning feature. It’s the internal representation of the r.Shadow.Virtual.Cache.ClipmapPanning console variable.

This variable is used directly in the rendering code, specifically in the FVirtualShadowMapCacheEntry::UpdateClipmapLevel function. When GClipmapPanning is set to 0, it disables the clipmap panning feature, causing the shadow cache to be invalidated when the page space location changes.

The value of GClipmapPanning is set by the console variable system, mirroring the value of r.Shadow.Virtual.Cache.ClipmapPanning.

Developers should be aware that modifying GClipmapPanning directly in code is not recommended. Instead, they should use the console variable r.Shadow.Virtual.Cache.ClipmapPanning to control this feature.

Best practices for GClipmapPanning include:

  1. Avoiding direct manipulation in code; use the console variable instead.
  2. Understanding that a value of 1 enables clipmap panning, while 0 disables it.
  3. Being cautious when disabling this feature, as it may impact performance and shadow quality in large, open environments where the camera moves frequently.

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

Scope: file

Source code excerpt:

int32 GClipmapPanning = 1;
FAutoConsoleVariableRef CVarEnableClipmapPanning(
	TEXT("r.Shadow.Virtual.Cache.ClipmapPanning"),
	GClipmapPanning,
	TEXT("Enable support for panning cached clipmap pages for directional lights, allowing re-use of cached data when the camera moves. Keep this enabled outside of debugging."),
	ECVF_RenderThreadSafe
);

static int32 GVSMCacheDeformableMeshesInvalidate = 1;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

int32 GClipmapPanning = 1;
FAutoConsoleVariableRef CVarEnableClipmapPanning(
	TEXT("r.Shadow.Virtual.Cache.ClipmapPanning"),
	GClipmapPanning,
	TEXT("Enable support for panning cached clipmap pages for directional lights, allowing re-use of cached data when the camera moves. Keep this enabled outside of debugging."),
	ECVF_RenderThreadSafe
);

static int32 GVSMCacheDeformableMeshesInvalidate = 1;
FAutoConsoleVariableRef CVarCacheInvalidateOftenMoving(

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

Scope (from outer to inner):

file
function     void FVirtualShadowMapCacheEntry::UpdateClipmapLevel

Source code excerpt:

	bool bCacheValid = (PrevVirtualShadowMapId != INDEX_NONE);
	
	if (bCacheValid && GClipmapPanning == 0)
	{
		if (PageSpaceLocation.X != PrevPageSpaceLocation.X ||
			PageSpaceLocation.Y != PrevPageSpaceLocation.Y)
		{
			bCacheValid = false;
			//UE_LOG(LogRenderer, Display, TEXT("Invalidated clipmap level (VSM %d) with page space location %d,%d (Prev %d, %d)"),