r.Lumen.ScreenProbeGather.ScreenTraces.HZBTraversal.HistoryDepthTestRelativeThickness

r.Lumen.ScreenProbeGather.ScreenTraces.HZBTraversal.HistoryDepthTestRelativeThickness

#Overview

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

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

• type: Var
• help: Distance between HZB trace hit and previous frame scene depth from which to allow hits, as a relative depth threshold.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.ScreenProbeGather.ScreenTraces.HZBTraversal.HistoryDepthTestRelativeThickness is to control the distance threshold between the HZB (Hierarchical Z-Buffer) trace hit and the previous frame’s scene depth for allowing hits in Lumen’s screen probe gathering process. This setting is part of Unreal Engine 5’s Lumen global illumination system, specifically for the screen probe tracing component.

This setting variable is primarily used in the rendering system, particularly in the Lumen subsystem of Unreal Engine 5. Based on the callsites, it’s clear that this variable is utilized in the LumenScreenProbeTracing module.

The value of this variable is set through the console variable system, as indicated by the FAutoConsoleVariableRef declaration. It can be modified at runtime or through configuration files.

The associated variable GLumenScreenProbeGatherHistoryDepthTestRelativeThickness directly interacts with this setting. They share the same value, and the console variable is used to modify the associated variable.

Developers must be aware that this variable affects the accuracy and performance of screen probe tracing in Lumen. A smaller value will result in more precise depth testing but may increase the likelihood of rejecting valid hits, while a larger value may allow more hits but could introduce artifacts.

Best practices when using this variable include:

1. Fine-tuning the value based on the specific needs of the scene and performance requirements.
2. Considering the scale of the scene when adjusting this value, as it’s a relative threshold.
3. Testing thoroughly with different scenes to ensure a good balance between accuracy and performance.

Regarding the associated variable GLumenScreenProbeGatherHistoryDepthTestRelativeThickness:

• Its purpose is to store the actual value used in the screen probe tracing calculations.
• It’s used directly in the TraceScreenProbes function, where it’s multiplied by the view’s depth thickness scale to determine the final depth test threshold.
• The value is set by the console variable and can be modified at runtime.
• Developers should be aware that changing this variable will directly affect the behavior of screen probe tracing in Lumen.
• Best practices include monitoring its impact on visual quality and performance when modifying its value, and considering its interaction with other Lumen 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/Lumen/LumenScreenProbeTracing.cpp:65

Scope: file

Source code excerpt:

float GLumenScreenProbeGatherHistoryDepthTestRelativeThickness = .01f;
FAutoConsoleVariableRef GVarLumenScreenProbeGatherHistoryDepthTestRelativeThickness(
	TEXT("r.Lumen.ScreenProbeGather.ScreenTraces.HZBTraversal.HistoryDepthTestRelativeThickness"),
	GLumenScreenProbeGatherHistoryDepthTestRelativeThickness,
	TEXT("Distance between HZB trace hit and previous frame scene depth from which to allow hits, as a relative depth threshold."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenScreenProbeGatherNumThicknessStepsToDetermineCertainty = 4;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

float GLumenScreenProbeGatherHistoryDepthTestRelativeThickness = .01f;
FAutoConsoleVariableRef GVarLumenScreenProbeGatherHistoryDepthTestRelativeThickness(
	TEXT("r.Lumen.ScreenProbeGather.ScreenTraces.HZBTraversal.HistoryDepthTestRelativeThickness"),
	GLumenScreenProbeGatherHistoryDepthTestRelativeThickness,
	TEXT("Distance between HZB trace hit and previous frame scene depth from which to allow hits, as a relative depth threshold."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenScreenProbeGatherNumThicknessStepsToDetermineCertainty = 4;
FAutoConsoleVariableRef GVarLumenScreenProbeGatherNumThicknessStepsToDetermineCertainty(

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

Scope (from outer to inner):

file
function     void TraceScreenProbes
lambda-function

Source code excerpt:

			PassParameters->MaxHierarchicalScreenTraceIterations = GLumenScreenProbeGatherHierarchicalScreenTracesMaxIterations;
			PassParameters->RelativeDepthThickness = GLumenScreenProbeGatherRelativeDepthThickness * View.ViewMatrices.GetPerProjectionDepthThicknessScale();
			PassParameters->HistoryDepthTestRelativeThickness = GLumenScreenProbeGatherHistoryDepthTestRelativeThickness * View.ViewMatrices.GetPerProjectionDepthThicknessScale();
			PassParameters->NumThicknessStepsToDetermineCertainty = GLumenScreenProbeGatherHierarchicalScreenTracesSkipFoliageHits ? 0 : GLumenScreenProbeGatherNumThicknessStepsToDetermineCertainty;
			PassParameters->MinimumTracingThreadOccupancy = GLumenScreenProbeGatherScreenTracesMinimumOccupancy;
			PassParameters->SkipFoliageHits = GLumenScreenProbeGatherHierarchicalScreenTracesSkipFoliageHits;

			PassParameters->ScreenProbeParameters = ScreenProbeParameters;
			PassParameters->IndirectTracingParameters = IndirectTracingParameters;