r.ManyLights.HardwareRayTracing.MaxIterations

r.ManyLights.HardwareRayTracing.MaxIterations

#Overview

name: r.ManyLights.HardwareRayTracing.MaxIterations

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

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.ManyLights.HardwareRayTracing.MaxIterations is to limit the number of ray tracing traversal iterations in the Many Lights system, which is part of Unreal Engine’s rendering system. This setting is specifically for hardware ray tracing and aims to improve performance at the potential cost of some visual accuracy.

The Unreal Engine subsystem that relies on this setting variable is the renderer, specifically the Many Lights system within the ray tracing component. This can be seen from the file path “Engine/Source/Runtime/Renderer/Private/ManyLights/ManyLightsRayTracing.cpp”.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 8192, but can be changed at runtime or through configuration files.

This variable interacts with the associated variable CVarManyLightsHardwareRayTracingMaxIterations, which is the actual CVar object that stores and manages the value.

Developers must be aware that while increasing this value may improve visual accuracy, it comes at the cost of performance. Conversely, decreasing it may improve performance but could lead to over-occlusion, where objects may appear more occluded than they should be.

Best practices when using this variable include:

  1. Balancing performance and visual quality based on the target hardware and game requirements.
  2. Testing different values to find the optimal balance for your specific use case.
  3. Considering different values for different quality settings in the game.

Regarding the associated variable CVarManyLightsHardwareRayTracingMaxIterations:

The purpose of CVarManyLightsHardwareRayTracingMaxIterations is to provide a programmatic interface to the r.ManyLights.HardwareRayTracing.MaxIterations setting within the C++ code.

This variable is used directly in the renderer code, specifically in the ManyLights::SetHardwareRayTracingPassParameters function. It’s used to set the MaxTraversalIterations parameter for ray tracing.

The value of this variable is set through the CVar system and can be accessed on the render thread using the GetValueOnRenderThread() method.

This variable directly interacts with the r.ManyLights.HardwareRayTracing.MaxIterations console variable, effectively serving as its C++ representation.

Developers should be aware that this variable is marked with ECVF_Scalability and ECVF_RenderThreadSafe flags, meaning it’s intended to be used for scalability settings and is safe to access from the render thread.

Best practices for using this variable include:

  1. Accessing its value on the render thread when needed for ray tracing operations.
  2. Ensuring that the retrieved value is at least 1 (as seen in the FMath::Max call in the code).
  3. Considering the performance implications when modifying this value, especially in performance-critical sections of the rendering code.

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarManyLightsHardwareRayTracingMaxIterations(
	TEXT("r.ManyLights.HardwareRayTracing.MaxIterations"),
	8192,
	TEXT("Limit number of ray tracing traversal iterations on supported platfoms. Improves performance, but may add over-occlusion."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

// #ml_todo: Separate config cvars from Lumen once we support multiple SBT with same RayTracingPipeline or Global Uniform Buffers in Ray Tracing

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarManyLightsHardwareRayTracingMaxIterations(
	TEXT("r.ManyLights.HardwareRayTracing.MaxIterations"),
	8192,
	TEXT("Limit number of ray tracing traversal iterations on supported platfoms. Improves performance, but may add over-occlusion."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

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

Scope (from outer to inner):

file
function     void ManyLights::SetHardwareRayTracingPassParameters

Source code excerpt:

	checkf(View.HasRayTracingScene(), TEXT("TLAS does not exist. Verify that the current pass is represented in Lumen::AnyLumenHardwareRayTracingPassEnabled()."));
	PassParameters->TLAS = View.GetRayTracingSceneLayerViewChecked(ERayTracingSceneLayer::Base);
	PassParameters->MaxTraversalIterations = FMath::Max(CVarManyLightsHardwareRayTracingMaxIterations.GetValueOnRenderThread(), 1);

	// Inline
	PassParameters->HitGroupData = View.GetPrimaryView()->LumenHardwareRayTracingHitDataBuffer ? GraphBuilder.CreateSRV(View.GetPrimaryView()->LumenHardwareRayTracingHitDataBuffer) : nullptr;
	PassParameters->LumenHardwareRayTracingUniformBuffer = View.GetPrimaryView()->LumenHardwareRayTracingUniformBuffer ? View.GetPrimaryView()->LumenHardwareRayTracingUniformBuffer : nullptr;
	checkf(View.RayTracingSceneInitTask == nullptr, TEXT("RayTracingSceneInitTask must be completed before creating SRV for RayTracingSceneMetadata."));
	PassParameters->RayTracingSceneMetadata = View.GetRayTracingSceneChecked()->GetOrCreateMetadataBufferSRV(GraphBuilder.RHICmdList);