r.ManyLights.ScreenTraces.MaxIterations

r.ManyLights.ScreenTraces.MaxIterations

#Overview

name: r.ManyLights.ScreenTraces.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.ManyLights.ScreenTraces.MaxIterations is to control the maximum number of iterations for HZB (Hierarchical Z-Buffer) tracing in the ManyLights system of Unreal Engine’s rendering pipeline.

This setting variable is primarily used by the rendering system, specifically in the ManyLights module, which is responsible for efficiently handling a large number of light sources in a scene.

Based on the callsites, this variable is used in the Renderer module, particularly in the ManyLightsRayTracing.cpp file. This suggests that it’s part of the ray tracing implementation for the ManyLights system.

The value of this variable is set as a console variable (CVar) with a default value of 50. It can be modified at runtime through the console or configuration files.

The associated variable CVarManyLightsScreenTracesMaxIterations directly interacts with r.ManyLights.ScreenTraces.MaxIterations. They share the same value and purpose.

Developers should be aware that this variable affects the performance and quality trade-off in the ManyLights system. A higher value may result in more accurate lighting but at the cost of increased processing time.

Best practices when using this variable include:

1. Adjusting it based on the specific needs of the scene and target hardware.
2. Monitoring performance impact when modifying this value.
3. Consider using it in conjunction with other ManyLights settings for optimal results.

Regarding the associated variable CVarManyLightsScreenTracesMaxIterations:

This is the actual C++ variable that stores the console variable. It’s used in the RayTraceLightSamples function to set the MaxHierarchicalScreenTraceIterations parameter for the ray tracing pass.

Developers should note that changes to this variable will take effect on the render thread, as indicated by the GetValueOnRenderThread() call.

When working with this variable, it’s important to consider its impact on both visual quality and performance, and to test thoroughly on various hardware configurations to ensure a good balance is maintained.

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

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarManyLightsScreenTracesMaxIterations(
	TEXT("r.ManyLights.ScreenTraces.MaxIterations"),
	50,
	TEXT("Max iterations for HZB tracing."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

static TAutoConsoleVariable<int32> CVarManyLightsScreenTracesMinimumOccupancy(

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarManyLightsScreenTracesMaxIterations(
	TEXT("r.ManyLights.ScreenTraces.MaxIterations"),
	50,
	TEXT("Max iterations for HZB tracing."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

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

Scope (from outer to inner):

file
function     void ManyLights::RayTraceLightSamples

Source code excerpt:

		PassParameters->RWLightSampleRayDistance = GraphBuilder.CreateUAV(LightSampleRayDistance);
		PassParameters->HZBScreenTraceParameters = SetupHZBScreenTraceParameters(GraphBuilder, View, SceneTextures, /*bBindLumenHistory*/ false);
		PassParameters->MaxHierarchicalScreenTraceIterations = CVarManyLightsScreenTracesMaxIterations.GetValueOnRenderThread();
		PassParameters->RelativeDepthThickness = CVarManyLightsScreenTraceRelativeDepthThreshold.GetValueOnRenderThread() * View.ViewMatrices.GetPerProjectionDepthThicknessScale();
		PassParameters->HistoryDepthTestRelativeThickness = 0.0f;
		PassParameters->MinimumTracingThreadOccupancy = CVarManyLightsScreenTracesMinimumOccupancy.GetValueOnRenderThread();

		FScreenSpaceRayTraceLightSamplesCS::FPermutationDomain PermutationVector;
		PermutationVector.Set<FScreenSpaceRayTraceLightSamplesCS::FDebugMode>(bDebug);