r.Lumen.ScreenProbeGather.ScreenTraces.HZBTraversal.FullResDepth

r.Lumen.ScreenProbeGather.ScreenTraces.HZBTraversal.FullResDepth

#Overview

name: r.Lumen.ScreenProbeGather.ScreenTraces.HZBTraversal.FullResDepth

The value of this variable can be defined or overridden in .ini config files. 3 .ini config files referencing this setting variable.

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

• type: Var
• help: Whether the HZB traversal should go all the way down to the full resolution depth, which is more accurate but adds incoherency to the inner loop.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.ScreenProbeGather.ScreenTraces.HZBTraversal.FullResDepth is to control the depth resolution used in the Hierarchical Z-Buffer (HZB) traversal during screen probe gathering in Lumen, Unreal Engine 5’s global illumination system.

This setting variable is primarily used in the rendering system, specifically in the Lumen subsystem for global illumination calculations. It is part of the screen probe tracing process, which is a crucial component of Lumen’s real-time global illumination.

The value of this variable is set through the Unreal Engine console variable system. It’s initialized with a default value of 1 (enabled) and can be modified at runtime.

The associated C++ variable GLumenScreenProbeGatherHierarchicalScreenTracesFullResDepth directly interacts with this console variable. They share the same value, allowing the C++ code to access the setting configured through the engine’s console system.

Developers should be aware that enabling this variable (set to 1) makes the HZB traversal go all the way down to the full resolution depth. This provides more accurate results but can introduce incoherency to the inner loop of the tracing algorithm.

Best practices when using this variable include:

1. Consider the trade-off between accuracy and performance. Full resolution depth provides better accuracy but may impact performance.
2. Test the impact of enabling/disabling this setting in various scenes to find the optimal balance for your specific use case.
3. Be mindful of potential visual artifacts or flickering that might occur due to the increased incoherency in the inner loop when enabled.

Regarding the associated variable GLumenScreenProbeGatherHierarchicalScreenTracesFullResDepth:

• It’s a C++ integer variable that directly reflects the value of the console variable.
• It’s used in the TraceScreenProbes function to determine whether to enable full resolution depth tracing in the screen probe tracing compute shader.
• When working with this variable in C++ code, developers should treat it as read-only and modify the value through the engine’s console variable system instead of directly changing the C++ variable.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseScalability.ini:285, section: [GlobalIlluminationQuality@2]

• INI Section: GlobalIlluminationQuality@2
• Raw value: 0
• Is Array: False

Location: <Workspace>/Engine/Config/BaseScalability.ini:308, section: [GlobalIlluminationQuality@3]

• INI Section: GlobalIlluminationQuality@3
• Raw value: 1
• Is Array: False

Location: <Workspace>/Engine/Config/BaseScalability.ini:332, section: [GlobalIlluminationQuality@Cine]

• INI Section: GlobalIlluminationQuality@Cine
• Raw value: 1
• Is Array: False

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

Scope: file

Source code excerpt:

int32 GLumenScreenProbeGatherHierarchicalScreenTracesFullResDepth = 1;
FAutoConsoleVariableRef GVarLumenScreenProbeGatherHierarchicalScreenTracesFullResDepth(
	TEXT("r.Lumen.ScreenProbeGather.ScreenTraces.HZBTraversal.FullResDepth"),
	GLumenScreenProbeGatherHierarchicalScreenTracesFullResDepth,
	TEXT("Whether the HZB traversal should go all the way down to the full resolution depth, which is more accurate but adds incoherency to the inner loop."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenScreenProbeGatherHierarchicalScreenTracesSkipFoliageHits = 1;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

int32 GLumenScreenProbeGatherHierarchicalScreenTracesFullResDepth = 1;
FAutoConsoleVariableRef GVarLumenScreenProbeGatherHierarchicalScreenTracesFullResDepth(
	TEXT("r.Lumen.ScreenProbeGather.ScreenTraces.HZBTraversal.FullResDepth"),
	GLumenScreenProbeGatherHierarchicalScreenTracesFullResDepth,
	TEXT("Whether the HZB traversal should go all the way down to the full resolution depth, which is more accurate but adds incoherency to the inner loop."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenScreenProbeGatherHierarchicalScreenTracesSkipFoliageHits = 1;
FAutoConsoleVariableRef GVarLumenScreenProbeGatherHierarchicalScreenTracesSkipFoliageHits( 

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

Scope (from outer to inner):

file
function     void TraceScreenProbes
lambda-function

Source code excerpt:

			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));
			PermutationVector.Set< FScreenProbeTraceScreenTexturesCS::FHairStrands>(bHasHairStrands);
			PermutationVector.Set< FScreenProbeTraceScreenTexturesCS::FTerminateOnLowOccupancy>(bTerminateOnLowOccupancy);
			PermutationVector.Set< FScreenProbeTraceScreenTexturesCS::FTraceLightSamples>(bTraceLightSamples);

			auto ComputeShader = View.ShaderMap->GetShader<FScreenProbeTraceScreenTexturesCS>(PermutationVector);