r.Lumen.ScreenProbeGather.ScreenTraces.HZBTraversal.RelativeDepthThickness

r.Lumen.ScreenProbeGather.ScreenTraces.HZBTraversal.RelativeDepthThickness

#Overview

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

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.Lumen.ScreenProbeGather.ScreenTraces.HZBTraversal.RelativeDepthThickness is to determine the depth thickness of objects hit by Hierarchical Z-Buffer (HZB) tracing in Lumen’s screen probe gathering process. It sets a relative depth threshold for object detection during the tracing operation.

This setting variable is primarily used in the Lumen subsystem of Unreal Engine’s rendering module. Specifically, it’s utilized in the screen probe tracing functionality of Lumen, which is part of the global illumination system.

The value of this variable is set through the Unreal Engine console variable system. It’s initialized with a default value of 0.02f and can be modified at runtime using console commands or through project settings.

The associated variable GLumenScreenProbeGatherRelativeDepthThickness directly interacts with this console variable. They share the same value, with GLumenScreenProbeGatherRelativeDepthThickness being the C++ variable that holds the actual value used in the code.

Developers must be aware that this variable affects the accuracy and performance of the HZB tracing in Lumen’s screen probe gathering. A higher value may result in thicker object detection, potentially capturing more detail but at the cost of performance. Conversely, a lower value may improve performance but might miss finer details in the scene.

Best practices when using this variable include:

  1. Adjusting it based on the specific needs of the scene and the desired balance between accuracy and performance.
  2. Testing different values to find the optimal setting for your project.
  3. Considering the impact on different hardware configurations, as this setting can affect performance across various systems.

Regarding the associated variable GLumenScreenProbeGatherRelativeDepthThickness:

The purpose of GLumenScreenProbeGatherRelativeDepthThickness is to store and provide the actual value used in the Lumen screen probe tracing calculations. It directly corresponds to the console variable r.Lumen.ScreenProbeGather.ScreenTraces.HZBTraversal.RelativeDepthThickness.

This variable is used in the Lumen subsystem of the rendering module, specifically in the screen probe tracing functionality.

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

It interacts directly with the console variable r.Lumen.ScreenProbeGather.ScreenTraces.HZBTraversal.RelativeDepthThickness, reflecting any changes made to the console variable.

Developers should be aware that this variable is used in actual calculations within the rendering code, specifically in the TraceScreenProbes function where it’s multiplied by the view’s per-projection depth thickness scale.

Best practices for using this variable include:

  1. Avoiding direct modification of GLumenScreenProbeGatherRelativeDepthThickness in code, instead using the console variable to ensure consistency.
  2. Considering its impact when optimizing Lumen performance or adjusting visual quality.
  3. Monitoring its usage in profiling to understand its impact on rendering performance.

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

Scope: file

Source code excerpt:

float GLumenScreenProbeGatherRelativeDepthThickness = .02f;
FAutoConsoleVariableRef GVarLumenScreenProbeGatherRelativeDepthThickness(
	TEXT("r.Lumen.ScreenProbeGather.ScreenTraces.HZBTraversal.RelativeDepthThickness"),
	GLumenScreenProbeGatherRelativeDepthThickness,
	TEXT("Determines depth thickness of objects hit by HZB tracing, as a relative depth threshold."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GLumenScreenProbeGatherHistoryDepthTestRelativeThickness = .01f;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

float GLumenScreenProbeGatherRelativeDepthThickness = .02f;
FAutoConsoleVariableRef GVarLumenScreenProbeGatherRelativeDepthThickness(
	TEXT("r.Lumen.ScreenProbeGather.ScreenTraces.HZBTraversal.RelativeDepthThickness"),
	GLumenScreenProbeGatherRelativeDepthThickness,
	TEXT("Determines depth thickness of objects hit by HZB tracing, as a relative depth threshold."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GLumenScreenProbeGatherHistoryDepthTestRelativeThickness = .01f;
FAutoConsoleVariableRef GVarLumenScreenProbeGatherHistoryDepthTestRelativeThickness(

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

Scope (from outer to inner):

file
function     void TraceScreenProbes
lambda-function

Source code excerpt:

			PassParameters->LightingChannelsTexture = LightingChannelsTexture;
			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;