r.Lumen.ScreenProbeGather.ScreenTraces.MinimumOccupancy

r.Lumen.ScreenProbeGather.ScreenTraces.MinimumOccupancy

#Overview

name: r.Lumen.ScreenProbeGather.ScreenTraces.MinimumOccupancy

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.ScreenProbeGather.ScreenTraces.MinimumOccupancy is to control the minimum number of threads still tracing before aborting the trace 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 in the Lumen subsystem, specifically in the screen probe tracing module. It’s part of the renderer module, as evidenced by its location in the “Runtime/Renderer/Private/Lumen” directory.

The value of this variable is set through the Unreal Engine console variable system, as indicated by the FAutoConsoleVariableRef declaration. It can be modified at runtime using console commands or through configuration files.

The associated variable GLumenScreenProbeGatherScreenTracesMinimumOccupancy directly interacts with this setting. They share the same value and are used interchangeably in the code.

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 certain scenarios. The variable is marked with ECVF_Scalability and ECVF_RenderThreadSafe flags, indicating it’s safe to modify on the render thread and is intended for scalability adjustments.

Best practices when using this variable include:

  1. Carefully tuning the value based on the specific needs of your project and target hardware.
  2. Testing thoroughly across different hardware configurations to ensure optimal performance.
  3. Considering the trade-off between image quality and performance when adjusting this value.

Regarding the associated variable GLumenScreenProbeGatherScreenTracesMinimumOccupancy:

The purpose of GLumenScreenProbeGatherScreenTracesMinimumOccupancy is to store the actual value of the minimum occupancy setting within the C++ code. It’s used directly in the rendering logic to determine when to abort tracing.

This variable is used in the Lumen screen probe tracing system, specifically in the TraceScreenProbes function. It’s part of the same renderer module as the console variable.

The value of this variable is set by the console variable system, mirroring the value of r.Lumen.ScreenProbeGather.ScreenTraces.MinimumOccupancy.

It interacts directly with shader parameters, being passed as MinimumTracingThreadOccupancy to the rendering pass.

Developers should be aware that this variable affects the behavior of screen probe tracing, potentially impacting both performance and image quality. It’s used in conjunction with other Lumen settings to determine tracing behavior.

Best practices include monitoring this variable’s impact on performance and image quality, and adjusting it in tandem with other 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:113

Scope: file

Source code excerpt:

int32 GLumenScreenProbeGatherScreenTracesMinimumOccupancy = 0;
FAutoConsoleVariableRef CVarLumenScreenProbeGatherScreenTraceMinimumOccupancy(
	TEXT("r.Lumen.ScreenProbeGather.ScreenTraces.MinimumOccupancy"),
	GLumenScreenProbeGatherScreenTracesMinimumOccupancy,
	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
);

class FClearTracesCS : public FGlobalShader

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

int32 GLumenScreenProbeGatherScreenTracesMinimumOccupancy = 0;
FAutoConsoleVariableRef CVarLumenScreenProbeGatherScreenTraceMinimumOccupancy(
	TEXT("r.Lumen.ScreenProbeGather.ScreenTraces.MinimumOccupancy"),
	GLumenScreenProbeGatherScreenTracesMinimumOccupancy,
	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
);

class FClearTracesCS : public FGlobalShader
{

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

Scope (from outer to inner):

file
function     void TraceScreenProbes
lambda-function

Source code excerpt:

			PassParameters->HistoryDepthTestRelativeThickness = GLumenScreenProbeGatherHistoryDepthTestRelativeThickness * View.ViewMatrices.GetPerProjectionDepthThicknessScale();
			PassParameters->NumThicknessStepsToDetermineCertainty = GLumenScreenProbeGatherHierarchicalScreenTracesSkipFoliageHits ? 0 : GLumenScreenProbeGatherNumThicknessStepsToDetermineCertainty;
			PassParameters->MinimumTracingThreadOccupancy = GLumenScreenProbeGatherScreenTracesMinimumOccupancy;
			PassParameters->SkipFoliageHits = GLumenScreenProbeGatherHierarchicalScreenTracesSkipFoliageHits;

			PassParameters->ScreenProbeParameters = ScreenProbeParameters;
			PassParameters->IndirectTracingParameters = IndirectTracingParameters;
			PassParameters->RadianceCacheParameters = RadianceCacheParameters;

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

Scope (from outer to inner):

file
function     void TraceScreenProbes
lambda-function

Source code excerpt:

			}

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

			const bool bHZBTraversal = GLumenScreenProbeGatherHierarchicalScreenTraces != 0;