r.Lumen.ScreenProbeGather.ScreenTraces.HZBTraversal.MaxIterations

r.Lumen.ScreenProbeGather.ScreenTraces.HZBTraversal.MaxIterations

#Overview

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

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.MaxIterations is to control the maximum number of iterations for Hierarchical Z-Buffer (HZB) tracing in Lumen’s screen probe gathering process. This setting is part of the Lumen global illumination system in Unreal Engine 5’s rendering pipeline.

This setting variable is primarily used by the Lumen subsystem within the Renderer module of Unreal Engine 5. Specifically, it’s utilized in the screen probe tracing functionality of Lumen.

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

The associated variable GLumenScreenProbeGatherHierarchicalScreenTracesMaxIterations directly interacts with this setting. They share the same value, and the console variable acts as an interface to modify the C++ variable.

Developers should be aware that this variable affects the performance and quality trade-off in Lumen’s screen probe gathering process. A higher value may provide more accurate results but at the cost of increased computation time.

Best practices when using this variable include:

  1. Adjusting it based on the specific needs of your scene and target hardware.
  2. Balancing it with other Lumen settings for optimal performance and visual quality.
  3. Testing different values to find the sweet spot between performance and visual fidelity for your specific use case.

Regarding the associated variable GLumenScreenProbeGatherHierarchicalScreenTracesMaxIterations:

The purpose of this variable is to store the actual value used in the C++ code for the maximum number of HZB tracing iterations.

It’s used directly in the Lumen screen probe tracing process, specifically in the TraceScreenProbes function where it’s passed as a parameter to control the maximum iterations for hierarchical screen tracing.

The value of this variable is set by the console variable system and can be modified at runtime through the r.Lumen.ScreenProbeGather.ScreenTraces.HZBTraversal.MaxIterations command.

This variable interacts closely with other Lumen screen probe gathering parameters, such as RelativeDepthThickness and HistoryDepthTestRelativeThickness.

Developers should be aware that modifying this variable will directly impact the behavior of the screen probe tracing algorithm. It’s crucial to consider the performance implications when adjusting this value.

Best practices for using this variable include:

  1. Profiling the impact of different values on both visual quality and performance.
  2. Considering scene complexity when setting this value - more complex scenes might benefit from higher values, while simpler scenes might perform well with lower values.
  3. Coordinating changes to this variable with adjustments to other related 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:49

Scope: file

Source code excerpt:

int32 GLumenScreenProbeGatherHierarchicalScreenTracesMaxIterations = 50;
FAutoConsoleVariableRef GVarLumenScreenProbeGatherHierarchicalScreenTracesMaxIterations(
	TEXT("r.Lumen.ScreenProbeGather.ScreenTraces.HZBTraversal.MaxIterations"),
	GLumenScreenProbeGatherHierarchicalScreenTracesMaxIterations,
	TEXT("Max iterations for HZB tracing."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GLumenScreenProbeGatherRelativeDepthThickness = .02f;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

int32 GLumenScreenProbeGatherHierarchicalScreenTracesMaxIterations = 50;
FAutoConsoleVariableRef GVarLumenScreenProbeGatherHierarchicalScreenTracesMaxIterations(
	TEXT("r.Lumen.ScreenProbeGather.ScreenTraces.HZBTraversal.MaxIterations"),
	GLumenScreenProbeGatherHierarchicalScreenTracesMaxIterations,
	TEXT("Max iterations for HZB tracing."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GLumenScreenProbeGatherRelativeDepthThickness = .02f;
FAutoConsoleVariableRef GVarLumenScreenProbeGatherRelativeDepthThickness(

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

Scope (from outer to inner):

file
function     void TraceScreenProbes
lambda-function

Source code excerpt:

			PassParameters->FurthestHZBTexture = View.HZB;
			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;