r.Shadow.Virtual.ForceFullHZBUpdate

r.Shadow.Virtual.ForceFullHZBUpdate

#Overview

name: r.Shadow.Virtual.ForceFullHZBUpdate

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.ForceFullHZBUpdate is to control the update behavior of the Hierarchical Z-Buffer (HZB) in Unreal Engine 5’s virtual shadow mapping system.

This setting variable is primarily used in the rendering system, specifically within the virtual shadow mapping subsystem. Based on the callsites, it is part of the Renderer module in Unreal Engine 5.

The value of this variable is set through a console variable (CVar) named CVarShadowsVirtualForceFullHZBUpdate. It is initialized with a default value of 0, meaning that by default, full HZB updates are not forced every frame.

The variable interacts with the virtual shadow mapping system, particularly in the FVirtualShadowMapArray::UpdateHZB function. It is used to determine whether a full HZB update should be performed every frame or if updates should only be applied to dirty pages.

Developers must be aware that enabling this variable (setting it to 1) will force a full HZB update every frame, which may have performance implications. This should be used cautiously and primarily for debugging or specific optimization scenarios.

Best practices when using this variable include:

  1. Keep it disabled (0) for normal operation to allow for optimized partial updates.
  2. Enable it temporarily for debugging or when investigating shadow-related issues.
  3. Monitor performance when enabled, as it may impact rendering efficiency.

Regarding the associated variable CVarShadowsVirtualForceFullHZBUpdate:

This is the actual console variable that controls the behavior described above. It is defined as a TAutoConsoleVariable, which means it can be changed at runtime through console commands.

The purpose of CVarShadowsVirtualForceFullHZBUpdate is to provide a way to toggle the full HZB update behavior dynamically during development or gameplay.

It is used in the Renderer module, specifically in the virtual shadow mapping system.

The value of this variable can be set through the Unreal Engine console or through code using the console variable system.

Developers should be aware that changes to this variable will take effect on the render thread, as indicated by the ECVF_RenderThreadSafe flag.

Best practices for using CVarShadowsVirtualForceFullHZBUpdate include:

  1. Use it in conjunction with performance profiling tools to understand its impact.
  2. Document its usage in project-specific rendering guidelines.
  3. Consider exposing it as a debug option in development builds for easier testing and optimization.

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarShadowsVirtualForceFullHZBUpdate(
	TEXT("r.Shadow.Virtual.ForceFullHZBUpdate"),
	0,
	TEXT("Forces full HZB update every frame rather than just dirty pages.\n"),
	ECVF_RenderThreadSafe);


static TAutoConsoleVariable<int32> CVarVirtualShadowSinglePassBatched(

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarShadowsVirtualForceFullHZBUpdate(
	TEXT("r.Shadow.Virtual.ForceFullHZBUpdate"),
	0,
	TEXT("Forces full HZB update every frame rather than just dirty pages.\n"),
	ECVF_RenderThreadSafe);

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

Scope (from outer to inner):

file
function     void FVirtualShadowMapArray::UpdateHZB

Source code excerpt:

		PassParameters->OutPhysicalPageMetaData = GraphBuilder.CreateUAV(PhysicalPageMetaDataRDG);
		PassParameters->bFirstBuildThisFrame = !bHZBBuiltThisFrame;
		PassParameters->bForceFullHZBUpdate = CVarShadowsVirtualForceFullHZBUpdate.GetValueOnRenderThread();
		FSelectPagesForHZBAndUpdateDirtyFlagsCS::FPermutationDomain PermutationVector;
		SetStatsArgsAndPermutation<FSelectPagesForHZBAndUpdateDirtyFlagsCS>(StatsBufferUAV, PassParameters, PermutationVector);
		auto ComputeShader = GetGlobalShaderMap(Scene.GetFeatureLevel())->GetShader<FSelectPagesForHZBAndUpdateDirtyFlagsCS>(PermutationVector);

		FComputeShaderUtils::AddPass(
			GraphBuilder,