r.Lumen.Reflections.HierarchicalScreenTraces.MinimumOccupancy

r.Lumen.Reflections.HierarchicalScreenTraces.MinimumOccupancy

#Overview

name: r.Lumen.Reflections.HierarchicalScreenTraces.MinimumOccupancy

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

• type: Var
• help: Minimum number of threads still tracing before aborting the trace. Can be used for scalability to abandon traces that have a disproportionate cost.

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.Reflections.HierarchicalScreenTraces.MinimumOccupancy is to control the minimum number of threads still tracing before aborting the trace 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 in the Lumen reflection tracing subsystem, which is part of the rendering module in Unreal Engine 5. It’s specifically utilized in the reflection tracing process to manage performance and scalability.

The value of this variable is set through the Unreal Engine 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 GLumenReflectionScreenTracesMinimumOccupancy directly interacts with this console variable. They share the same value, with the console variable controlling the runtime value of the C++ variable.

Developers must be aware that this variable is used for scalability purposes. It allows the engine to abandon traces that have a disproportionate cost, potentially improving performance in scenarios where certain reflection traces are too expensive to compute fully.

Best practices when using this variable include:

1. Adjusting it based on the target hardware capabilities and performance requirements.
2. Using it in conjunction with other Lumen reflection settings for optimal balance between visual quality and performance.
3. Testing thoroughly across different scenes and viewing conditions to ensure it doesn’t negatively impact visual quality.

Regarding the associated variable GLumenReflectionScreenTracesMinimumOccupancy:

• Its purpose is to store the actual value used in the reflection tracing computations.
• It’s used directly in the TraceReflections function to set the MinimumTracingThreadOccupancy parameter for the reflection tracing pass.
• It’s also used to determine whether to terminate tracing on low occupancy, which is conditional on several factors including hardware support for wave operations.

Developers should be aware that changes to the console variable will directly affect this C++ variable, and thus the behavior of the reflection tracing system. They should monitor its impact on both performance and visual quality when adjusting it.

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

Scope: file

Source code excerpt:

int32 GLumenReflectionScreenTracesMinimumOccupancy = 0;
FAutoConsoleVariableRef CVarLumenReflectionHierarchicalScreenTracesMinimumOccupancy(
	TEXT("r.Lumen.Reflections.HierarchicalScreenTraces.MinimumOccupancy"),
	GLumenReflectionScreenTracesMinimumOccupancy,
	TEXT("Minimum number of threads still tracing before aborting the trace.  Can be used for scalability to abandon traces that have a disproportionate cost."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GLumenReflectionHierarchicalScreenTraceRelativeDepthThreshold = .005f;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

int32 GLumenReflectionScreenTracesMinimumOccupancy = 0;
FAutoConsoleVariableRef CVarLumenReflectionHierarchicalScreenTracesMinimumOccupancy(
	TEXT("r.Lumen.Reflections.HierarchicalScreenTraces.MinimumOccupancy"),
	GLumenReflectionScreenTracesMinimumOccupancy,
	TEXT("Minimum number of threads still tracing before aborting the trace.  Can be used for scalability to abandon traces that have a disproportionate cost."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GLumenReflectionHierarchicalScreenTraceRelativeDepthThreshold = .005f;
FAutoConsoleVariableRef GVarLumenReflectionHierarchicalScreenTraceRelativeDepthThreshold(

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

Scope (from outer to inner):

file
function     void TraceReflections

Source code excerpt:

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

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

		const bool bHasHairStrands = HairStrands::HasViewHairStrandsData(View) && GLumenReflectionHairStrands_ScreenTrace > 0;

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

Scope (from outer to inner):

file
function     void TraceReflections

Source code excerpt:

		PassParameters->Substrate = Substrate::BindSubstrateGlobalUniformParameters(View);

		const bool bTerminateOnLowOccupancy = GLumenReflectionScreenTracesMinimumOccupancy > 0
			&& GRHISupportsWaveOperations 
			&& GRHIMinimumWaveSize <= 32 
			&& GRHIMaximumWaveSize >= 32
			&& RHISupportsWaveOperations(View.GetShaderPlatform());

		FReflectionTraceScreenTexturesCS::FPermutationDomain PermutationVector;