r.Lumen.ScreenProbeGather.ScreenTraces.HZBTraversal

r.Lumen.ScreenProbeGather.ScreenTraces.HZBTraversal

#Overview

name: r.Lumen.ScreenProbeGather.ScreenTraces.HZBTraversal

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

• type: Var
• help: Whether to use HZB tracing for SSGI instead of fixed step count intersection. HZB tracing is much more accurate, in particular not missing thin features, but is about ~3x slower.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.ScreenProbeGather.ScreenTraces.HZBTraversal is to control whether Hierarchical Z-Buffer (HZB) tracing is used for Screen Space Global Illumination (SSGI) in Unreal Engine’s Lumen lighting system instead of fixed step count intersection.

• This setting variable is primarily used in the Lumen rendering system, specifically for screen probe tracing in the global illumination process.

• The Unreal Engine’s Renderer module relies on this setting variable, as evidenced by its use in the LumenScreenProbeTracing.cpp file.

• The value of this variable is set through the FAutoConsoleVariableRef system, allowing it to be changed at runtime via console commands or configuration files.

• This variable interacts with GLumenScreenProbeGatherHierarchicalScreenTraces, which shares the same value.

• Developers must be aware that enabling HZB tracing (by setting this variable to 1) results in more accurate tracing, particularly for thin features, but at the cost of performance (about 3x slower).

• Best practices when using this variable include:

  1. Enable it for higher quality rendering when performance is not a critical concern.
  2. Disable it for performance-critical scenarios or on lower-end hardware.
  3. Consider the trade-off between accuracy and performance based on the specific needs of the project.

Regarding the associated variable GLumenScreenProbeGatherHierarchicalScreenTraces:

• Its purpose is to store the actual boolean value used in the code to determine whether HZB tracing should be used.

• It is used directly in the Lumen rendering system to control the HZB tracing behavior.

• The value is set by the console variable system and can be modified at runtime.

• It directly influences the shader permutations used for screen probe tracing, as seen in the PermutationVector setup.

• Developers should be aware that this variable directly affects the rendering pipeline and shader compilation.

• Best practices include ensuring consistency between this variable and the console variable, and considering its impact on shader permutations and compilation times.

#References in C++ code

#Callsites

This variable is referenced in the following C++ source code:

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenProbeTracing.cpp:25

Scope: file

Source code excerpt:

int32 GLumenScreenProbeGatherHierarchicalScreenTraces = 1;
FAutoConsoleVariableRef GVarLumenScreenProbeGatherHierarchicalScreenTraces(
	TEXT("r.Lumen.ScreenProbeGather.ScreenTraces.HZBTraversal"),
	GLumenScreenProbeGatherHierarchicalScreenTraces,
	TEXT("Whether to use HZB tracing for SSGI instead of fixed step count intersection.  HZB tracing is much more accurate, in particular not missing thin features, but is about ~3x slower."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenScreenProbeGatherHierarchicalScreenTracesFullResDepth = 1;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenProbeTracing.cpp:23

Scope: file

Source code excerpt:

);

int32 GLumenScreenProbeGatherHierarchicalScreenTraces = 1;
FAutoConsoleVariableRef GVarLumenScreenProbeGatherHierarchicalScreenTraces(
	TEXT("r.Lumen.ScreenProbeGather.ScreenTraces.HZBTraversal"),
	GLumenScreenProbeGatherHierarchicalScreenTraces,
	TEXT("Whether to use HZB tracing for SSGI instead of fixed step count intersection.  HZB tracing is much more accurate, in particular not missing thin features, but is about ~3x slower."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenScreenProbeGatherHierarchicalScreenTracesFullResDepth = 1;
FAutoConsoleVariableRef GVarLumenScreenProbeGatherHierarchicalScreenTracesFullResDepth(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenProbeTracing.cpp:721

Scope (from outer to inner):

file
function     void TraceScreenProbes
lambda-function

Source code excerpt:

				&& RHISupportsWaveOperations(View.GetShaderPlatform());

			const bool bHZBTraversal = GLumenScreenProbeGatherHierarchicalScreenTraces != 0;

			FScreenProbeTraceScreenTexturesCS::FPermutationDomain PermutationVector;
			PermutationVector.Set< FScreenProbeTraceScreenTexturesCS::FRadianceCache >(LumenScreenProbeGather::UseRadianceCache(View) && !bTraceLightSamples);
			PermutationVector.Set< FScreenProbeTraceScreenTexturesCS::FHierarchicalScreenTracing >(bHZBTraversal);
			PermutationVector.Set< FScreenProbeTraceScreenTexturesCS::FTraceFullResDepth >(bHZBTraversal && GLumenScreenProbeGatherHierarchicalScreenTracesFullResDepth != 0);
			PermutationVector.Set< FScreenProbeTraceScreenTexturesCS::FStructuredImportanceSampling >(LumenScreenProbeGather::UseImportanceSampling(View));