r.Shadow.Virtual.Cache.InvalidateUseHZB

r.Shadow.Virtual.Cache.InvalidateUseHZB

#Overview

name: r.Shadow.Virtual.Cache.InvalidateUseHZB

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.InvalidateUseHZB is to control the use of Hierarchical Z-Buffer (HZB) for instance invalidations in virtual shadow mapping. This setting is part of Unreal Engine 5’s rendering system, specifically related to the virtual shadow map caching mechanism.

This setting variable is primarily used in the Renderer module of Unreal Engine 5, specifically within the virtual shadow maps subsystem. It’s implemented in the VirtualShadowMapCacheManager.cpp file, which suggests it’s closely tied to the management of virtual shadow map caches.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 1, meaning it’s enabled by default. Developers can change this value at runtime using console commands or through project settings.

This variable interacts with another variable named CVarCacheVsmUseHzb, which is the actual TAutoConsoleVariable object that stores and manages the value of r.Shadow.Virtual.Cache.InvalidateUseHZB.

Developers must be aware that when this setting is enabled (set to 1), instance invalidations for virtual shadow maps are tested against the Hierarchical Z-Buffer. This means that instances that are fully occluded will not cause page invalidations in the virtual shadow map cache. This can potentially improve performance by reducing unnecessary cache invalidations.

Best practices when using this variable include:

  1. Keep it enabled (default value of 1) unless specific issues arise.
  2. If experiencing visual artifacts in shadow rendering, particularly for occluded objects, consider disabling this feature to diagnose if it’s the cause.
  3. Profile your game with this setting both enabled and disabled to understand its performance impact in your specific use case.

Regarding the associated variable CVarCacheVsmUseHzb:

The purpose of CVarCacheVsmUseHzb is to provide a programmatic interface for the r.Shadow.Virtual.Cache.InvalidateUseHZB setting within the engine’s code.

This variable is used directly in the Renderer module, specifically in the FVirtualShadowMapArrayCacheManager class. It’s queried during the process of setting invalidation parameters for virtual shadow map pages.

The value of CVarCacheVsmUseHzb is set automatically based on the r.Shadow.Virtual.Cache.InvalidateUseHZB console variable. It’s not typically set directly by developers but rather accessed to retrieve the current setting.

CVarCacheVsmUseHzb interacts closely with HZB-related rendering features. When its value is non-zero, the code uses HZB physical page pools for optimizing shadow map invalidations.

Developers should be aware that this variable is accessed on the render thread, which means changes to its value will be applied on the next frame render.

Best practices for CVarCacheVsmUseHzb include:

  1. Use GetValueOnRenderThread() when accessing its value in render thread code.
  2. Avoid frequent changes to this value, as it could impact rendering performance.
  3. Consider the implications on shadow quality and performance when modifying this setting.

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarCacheVsmUseHzb(
	TEXT("r.Shadow.Virtual.Cache.InvalidateUseHZB"),
	1,
	TEXT(" When enabled, instances invalidations are tested against the HZB. Instances that are fully occluded will not cause page invalidations."),
	ECVF_RenderThreadSafe);

int32 GClipmapPanning = 1;
FAutoConsoleVariableRef CVarEnableClipmapPanning(

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarCacheVsmUseHzb(
	TEXT("r.Shadow.Virtual.Cache.InvalidateUseHZB"),
	1,
	TEXT(" When enabled, instances invalidations are tested against the HZB. Instances that are fully occluded will not cause page invalidations."),
	ECVF_RenderThreadSafe);

int32 GClipmapPanning = 1;

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

Scope (from outer to inner):

file
function     void FVirtualShadowMapArrayCacheManager::SetInvalidateInstancePagesParameters

Source code excerpt:

	PassParameters->PhysicalPageMetaDataOut = GraphBuilder.CreateUAV(GraphBuilder.RegisterExternalBuffer(PhysicalPageMetaData));
	
	const bool bUseHZB = (CVarCacheVsmUseHzb.GetValueOnRenderThread() != 0);
	const TRefCountPtr<IPooledRenderTarget> HZBPhysical = (bUseHZB && HZBPhysicalPagePool) ? HZBPhysicalPagePool : nullptr;
	if (HZBPhysical)
	{
		// Same, since we are not producing a new frame just yet
		PassParameters->HZBPageTable = InvalidationPassCommon.UniformParameters->PageTable;
		PassParameters->HZBPageRectBounds = InvalidationPassCommon.UniformParameters->PageRectBounds;