r.Lumen.Reflections.HierarchicalScreenTraces.MaxIterations

r.Lumen.Reflections.HierarchicalScreenTraces.MaxIterations

#Overview

name: r.Lumen.Reflections.HierarchicalScreenTraces.MaxIterations

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

• type: Var
• help: Max iterations for HZB tracing.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.Reflections.HierarchicalScreenTraces.MaxIterations is to control the maximum number of iterations for Hierarchical Z-Buffer (HZB) tracing in Lumen’s reflection system. This setting is part of Unreal Engine 5’s Lumen global illumination and reflection system.

This setting variable is primarily used by the Lumen reflection subsystem within Unreal Engine 5’s rendering module. It specifically affects the screen-space reflection tracing process.

The value of this variable is set through the engine’s console variable system. It’s defined as an FAutoConsoleVariableRef, which means it can be adjusted at runtime through console commands or configuration files.

The associated variable GLumenReflectionHierarchicalScreenTracesMaxIterations directly interacts with this setting. They share the same value, with GLumenReflectionHierarchicalScreenTracesMaxIterations being the C++ variable used in the rendering code.

Developers should be aware that this variable affects the performance and quality trade-off of Lumen’s screen-space reflections. A higher value may provide more accurate reflections but at the cost of increased computational load.

Best practices when using this variable include:

1. Adjusting it based on the specific needs of your scene and target hardware.
2. Testing different values to find the optimal balance between visual quality and performance.
3. Considering lowering this value for performance-critical scenarios or on lower-end hardware.

Regarding the associated variable GLumenReflectionHierarchicalScreenTracesMaxIterations:

This is an integer variable used directly in the rendering code to control the maximum number of iterations for HZB tracing. It’s set to an initial value of 50 but can be modified through the console variable system.

The variable is used in the TraceReflections function within the Lumen reflection tracing system. It’s passed to the shader parameters (PassParameters->MaxHierarchicalScreenTraceIterations) for the reflection tracing compute shader.

Developers should note that this variable directly impacts the behavior of the screen-space reflection tracing. Modifying it will affect both the quality of reflections and the performance of the reflection rendering pass.

When working with this variable, developers should:

1. Consider the impact on both visual quality and performance when adjusting its value.
2. Test thoroughly across various scenes and viewing conditions to ensure desired results.
3. Be aware that very high values might lead to diminishing returns in terms of reflection quality while significantly impacting performance.

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

Scope: file

Source code excerpt:

int32 GLumenReflectionHierarchicalScreenTracesMaxIterations = 50;
FAutoConsoleVariableRef CVarLumenReflectionHierarchicalScreenTracesMaxIterations(
	TEXT("r.Lumen.Reflections.HierarchicalScreenTraces.MaxIterations"),
	GLumenReflectionHierarchicalScreenTracesMaxIterations,
	TEXT("Max iterations for HZB tracing."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenReflectionScreenTracesMinimumOccupancy = 0;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

int32 GLumenReflectionHierarchicalScreenTracesMaxIterations = 50;
FAutoConsoleVariableRef CVarLumenReflectionHierarchicalScreenTracesMaxIterations(
	TEXT("r.Lumen.Reflections.HierarchicalScreenTraces.MaxIterations"),
	GLumenReflectionHierarchicalScreenTracesMaxIterations,
	TEXT("Max iterations for HZB tracing."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenReflectionScreenTracesMinimumOccupancy = 0;
FAutoConsoleVariableRef CVarLumenReflectionHierarchicalScreenTracesMinimumOccupancy(

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

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;