r.Lumen.Reflections.HierarchicalScreenTraces.HistoryDepthTestRelativeThickness

r.Lumen.Reflections.HierarchicalScreenTraces.HistoryDepthTestRelativeThickness

#Overview

name: r.Lumen.Reflections.HierarchicalScreenTraces.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.Reflections.HierarchicalScreenTraces.HistoryDepthTestRelativeThickness is to define the distance threshold between the Hierarchical Z-Buffer (HZB) trace hit and the previous frame’s scene depth for allowing hits in Lumen’s reflection system. This setting is used as a relative depth threshold in the screen-space reflection tracing process.

This setting variable is primarily used by Unreal Engine’s Lumen global illumination system, specifically in the reflection tracing subsystem. It’s part of the rendering module, as evidenced by its location in the LumenReflectionTracing.cpp file.

The value of this variable is set through the engine’s console variable system, as indicated by the FAutoConsoleVariableRef declaration. This allows the value to be changed at runtime or through configuration files.

The associated variable GLumenReflectionHierarchicalScreenTraceHistoryDepthTestRelativeThickness directly interacts with this console variable. They share the same value, with the console variable controlling the C++ variable.

Developers should be aware that this variable affects the accuracy and performance of Lumen’s screen-space reflection tracing. A larger value will allow for more lenient depth testing, potentially increasing the number of accepted hits but possibly introducing more artifacts. A smaller value will be more strict, potentially reducing artifacts but also reducing the number of valid reflections.

Best practices when using this variable include:

1. Fine-tuning it based on the specific needs of the scene and the desired balance between performance and visual quality.
2. Testing different values to find the optimal setting for your specific use case.
3. Being cautious when adjusting it, as it can have a significant impact on the appearance of reflections in the scene.

Regarding the associated variable GLumenReflectionHierarchicalScreenTraceHistoryDepthTestRelativeThickness: This is the C++ variable that directly holds the value set by the console variable. It’s used in the reflection tracing computations, specifically in setting up the parameters for the reflection tracing shader. The value is multiplied by the view’s per-projection depth thickness scale to convert it to the appropriate scale for the current view.

When working with this variable, developers should remember that it’s tied to the console variable and will be updated whenever the console variable changes. Any direct modifications to this variable in code may be overwritten by console commands or configuration settings.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenReflectionTracing.cpp:47

Scope: file

Source code excerpt:

float GLumenReflectionHierarchicalScreenTraceHistoryDepthTestRelativeThickness = .01f;
FAutoConsoleVariableRef GVarLumenReflectionHierarchicalScreenTraceHistoryDepthTestRelativeThickness(
	TEXT("r.Lumen.Reflections.HierarchicalScreenTraces.HistoryDepthTestRelativeThickness"),
	GLumenReflectionHierarchicalScreenTraceHistoryDepthTestRelativeThickness,
	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 GLumenReflectionHairStrands_VoxelTrace = 1;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenReflectionTracing.cpp:45

Scope: file

Source code excerpt:

);

float GLumenReflectionHierarchicalScreenTraceHistoryDepthTestRelativeThickness = .01f;
FAutoConsoleVariableRef GVarLumenReflectionHierarchicalScreenTraceHistoryDepthTestRelativeThickness(
	TEXT("r.Lumen.Reflections.HierarchicalScreenTraces.HistoryDepthTestRelativeThickness"),
	GLumenReflectionHierarchicalScreenTraceHistoryDepthTestRelativeThickness,
	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 GLumenReflectionHairStrands_VoxelTrace = 1;
FAutoConsoleVariableRef GVarLumenReflectionHairStrands_VoxelTrace(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenReflectionTracing.cpp:906

Scope (from outer to inner):

file
function     void TraceReflections

Source code excerpt:

		PassParameters->MaxHierarchicalScreenTraceIterations = GLumenReflectionHierarchicalScreenTracesMaxIterations;
		PassParameters->RelativeDepthThickness = GLumenReflectionHierarchicalScreenTraceRelativeDepthThreshold * View.ViewMatrices.GetPerProjectionDepthThicknessScale();
		PassParameters->HistoryDepthTestRelativeThickness = GLumenReflectionHierarchicalScreenTraceHistoryDepthTestRelativeThickness * View.ViewMatrices.GetPerProjectionDepthThicknessScale();
		PassParameters->MinimumTracingThreadOccupancy = GLumenReflectionScreenTracesMinimumOccupancy;

		PassParameters->ReflectionTracingParameters = ReflectionTracingParameters;
		PassParameters->ReflectionTileParameters = ReflectionTileParameters;
		PassParameters->IndirectTracingParameters = IndirectTracingParameters;