r.ManyLights.ScreenTraces.MinimumOccupancy

r.ManyLights.ScreenTraces.MinimumOccupancy

#Overview

name: r.ManyLights.ScreenTraces.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 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.ManyLights.ScreenTraces.MinimumOccupancy is to control the minimum number of threads that should continue tracing before aborting the trace operation in the Many Lights system. This setting is part of the rendering system, specifically for optimizing light tracing performance.

This setting variable is primarily used in the Renderer module of Unreal Engine 5, particularly in the Many Lights subsystem. It’s referenced in the ManyLightsRayTracing.cpp file, which suggests it’s part of the ray tracing implementation for the Many Lights system.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 0 and can be changed at runtime.

The associated variable CVarManyLightsScreenTracesMinimumOccupancy directly interacts with this setting. They share the same value and purpose.

Developers must be aware that this variable is used for scalability purposes. It allows the engine to abandon traces that have a disproportionate cost, which can help in optimizing performance, especially in scenarios with many lights.

Best practices when using this variable include:

1. Carefully tuning the value based on the specific needs of the scene and target hardware.
2. Considering the trade-off between performance and lighting quality.
3. Testing thoroughly with different values to find the optimal balance for your specific use case.

Regarding the associated variable CVarManyLightsScreenTracesMinimumOccupancy:

The purpose of CVarManyLightsScreenTracesMinimumOccupancy is identical to r.ManyLights.ScreenTraces.MinimumOccupancy. It’s the actual console variable that controls the minimum thread occupancy for light tracing.

This variable is used in the same Renderer module and Many Lights subsystem as the setting variable.

The value is set when the engine initializes the console variable system, but it can be changed at runtime through console commands or game code.

This variable directly interacts with the r.ManyLights.ScreenTraces.MinimumOccupancy setting, as they share the same value.

Developers should be aware that this is a scalability setting (ECVF_Scalability) and is render thread safe (ECVF_RenderThreadSafe). Changes to this variable will affect the rendering performance and potentially the visual quality of lighting in the scene.

Best practices include:

1. Using the GetValueOnRenderThread() method to access the value, as seen in the provided code snippet.
2. Considering the impact on different hardware configurations when adjusting this value.
3. Documenting any changes to this value in your project settings or documentation for other team members.

#References in C++ code

#Callsites

This variable is referenced in the following C++ source code:

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ManyLights/ManyLightsRayTracing.cpp:21

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarManyLightsScreenTracesMinimumOccupancy(
	TEXT("r.ManyLights.ScreenTraces.MinimumOccupancy"),
	0,
	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
);

static TAutoConsoleVariable<float> CVarManyLightsScreenTraceRelativeDepthThreshold(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ManyLights/ManyLightsRayTracing.cpp:20

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarManyLightsScreenTracesMinimumOccupancy(
	TEXT("r.ManyLights.ScreenTraces.MinimumOccupancy"),
	0,
	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
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ManyLights/ManyLightsRayTracing.cpp:530

Scope (from outer to inner):

file
function     void ManyLights::RayTraceLightSamples

Source code excerpt:

		PassParameters->RelativeDepthThickness = CVarManyLightsScreenTraceRelativeDepthThreshold.GetValueOnRenderThread() * View.ViewMatrices.GetPerProjectionDepthThicknessScale();
		PassParameters->HistoryDepthTestRelativeThickness = 0.0f;
		PassParameters->MinimumTracingThreadOccupancy = CVarManyLightsScreenTracesMinimumOccupancy.GetValueOnRenderThread();

		FScreenSpaceRayTraceLightSamplesCS::FPermutationDomain PermutationVector;
		PermutationVector.Set<FScreenSpaceRayTraceLightSamplesCS::FDebugMode>(bDebug);
		auto ComputeShader = View.ShaderMap->GetShader<FScreenSpaceRayTraceLightSamplesCS>(PermutationVector);

		FComputeShaderUtils::AddPass(