r.Shadow.Virtual.UseHZB

r.Shadow.Virtual.UseHZB

#Overview

name: r.Shadow.Virtual.UseHZB

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.UseHZB is to control the use of Hierarchical Z-Buffer (HZB) for occlusion culling in Virtual Shadow Maps, specifically for Nanite-based rendering.

This setting variable is primarily used in the rendering system of Unreal Engine 5, specifically within the Virtual Shadow Map subsystem. It is implemented in the Renderer module, as evident from the file path “Engine/Source/Runtime/Renderer/Private/VirtualShadowMaps/VirtualShadowMapArray.cpp”.

The value of this variable is set through a console variable (CVarShadowsVirtualUseHZB) with three possible options: 0 - Disables HZB occlusion culling 1 - Enables approximate single-pass HZB occlusion culling using the previous frame’s HZB 2 - Enables two-pass occlusion culling (default setting)

This variable interacts directly with the associated variable CVarShadowsVirtualUseHZB, which is used to retrieve the current setting value in the code.

Developers should be aware that this setting is specific to Nanite-based Virtual Shadow Maps. There is a separate flag (r.Shadow.Virtual.NonNanite.UseHZB) for non-Nanite shadow maps with different semantics.

Best practices when using this variable include:

  1. Understanding the performance implications of each setting
  2. Testing thoroughly with different values to find the optimal balance between visual quality and performance for your specific use case
  3. Being aware that changing this setting may affect the visual consistency of shadows between frames, especially when using single-pass HZB occlusion culling

Regarding the associated variable CVarShadowsVirtualUseHZB:

The purpose of CVarShadowsVirtualUseHZB is to provide a programmatic interface to access and modify the r.Shadow.Virtual.UseHZB setting within the engine’s C++ code.

This variable is used within the Renderer module, specifically in the Virtual Shadow Map implementation. It’s primarily accessed in the FVirtualShadowMapArray::Initialize function to determine whether to use HZB occlusion and whether to use two-pass HZB occlusion.

The value of CVarShadowsVirtualUseHZB is set when the r.Shadow.Virtual.UseHZB console variable is modified, either through code or via the console.

CVarShadowsVirtualUseHZB interacts directly with the bUseHzbOcclusion and bUseTwoPassHzbOcclusion boolean variables, which are used to control the behavior of the Virtual Shadow Map system.

Developers should be aware that changes to CVarShadowsVirtualUseHZB will immediately affect the rendering pipeline’s behavior regarding shadow occlusion culling. It’s important to call GetValueOnRenderThread() when accessing this variable to ensure thread-safe behavior.

Best practices for using CVarShadowsVirtualUseHZB include:

  1. Always access the value using GetValueOnRenderThread() in render thread code
  2. Consider the performance implications when changing this value at runtime
  3. Use this variable in conjunction with other shadow-related settings for optimal results

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarShadowsVirtualUseHZB(
	TEXT("r.Shadow.Virtual.UseHZB"),
	2,
	TEXT("Enables HZB for (Nanite) Virtual Shadow Maps - Non-Nanite unfortunately has a separate flag with different semantics: r.Shadow.Virtual.NonNanite.UseHZB.\n")
	TEXT(" 0 - No HZB occlusion culling\n")
	TEXT(" 1 - Approximate Single-pass HZB occlusion culling (using previous frame HZB)\n")
	TEXT(" 2 - Two-pass occlusion culling (default)."),
	ECVF_RenderThreadSafe);

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

#endif // !UE_BUILD_SHIPPING

static TAutoConsoleVariable<int32> CVarShadowsVirtualUseHZB(
	TEXT("r.Shadow.Virtual.UseHZB"),
	2,
	TEXT("Enables HZB for (Nanite) Virtual Shadow Maps - Non-Nanite unfortunately has a separate flag with different semantics: r.Shadow.Virtual.NonNanite.UseHZB.\n")
	TEXT(" 0 - No HZB occlusion culling\n")
	TEXT(" 1 - Approximate Single-pass HZB occlusion culling (using previous frame HZB)\n")
	TEXT(" 2 - Two-pass occlusion culling (default)."),

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

Scope (from outer to inner):

file
function     void FVirtualShadowMapArray::Initialize

Source code excerpt:


	bCullBackfacingPixels = CVarCullBackfacingPixels.GetValueOnRenderThread() != 0;
	bUseHzbOcclusion = CVarShadowsVirtualUseHZB.GetValueOnRenderThread() != 0;
	bUseTwoPassHzbOcclusion = CVarShadowsVirtualUseHZB.GetValueOnRenderThread() == 2;

	UniformParameters.NumFullShadowMaps = 0;
	UniformParameters.NumSinglePageShadowMaps = 0;
	UniformParameters.NumShadowMapSlots = 0;
	UniformParameters.MaxPhysicalPages = 0;
	UniformParameters.StaticCachedArrayIndex = 0;