r.Lumen.HardwareRayTracing.MaxIterations

r.Lumen.HardwareRayTracing.MaxIterations

#Overview

name: r.Lumen.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.Lumen.HardwareRayTracing.MaxIterations is to limit the number of ray tracing traversal iterations in Lumen’s hardware ray tracing system. This setting is part of Unreal Engine 5’s Lumen global illumination system, specifically for its hardware-accelerated ray tracing component.

This setting variable is primarily used by the Lumen subsystem within Unreal Engine’s rendering module. Based on the callsites, it’s evident that this variable is utilized in the LumenHardwareRayTracingCommon.cpp file, which is part of the Renderer’s private implementation for Lumen.

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 modified at runtime through console commands or configuration files.

The associated variable CVarLumenHardwareRayTracingMaxIterations directly interacts with r.Lumen.HardwareRayTracing.MaxIterations. They share the same value and purpose, with CVarLumenHardwareRayTracingMaxIterations being the actual C++ variable used in the code to access the setting.

Developers must be aware of several important aspects when using this variable:

  1. The setting affects the trade-off between rendering quality and performance. Higher values allow for more accurate ray tracing but may impact performance.
  2. Incomplete misses due to reaching the iteration limit will be treated as hitting a black surface, which can cause over-occlusion.
  3. Incomplete hits will be treated as valid hits, potentially causing light leaking.

Best practices when using this variable include:

  1. Adjust the value based on the specific needs of your scene and target hardware capabilities.
  2. Monitor performance and visual quality when modifying this setting.
  3. Be cautious of setting extremely high values, as it may severely impact performance without significant visual improvements.
  4. Consider scene complexity when adjusting this value, as more complex scenes may require higher iteration counts.

Regarding the associated variable CVarLumenHardwareRayTracingMaxIterations:

This is the actual C++ variable used to access and modify the r.Lumen.HardwareRayTracing.MaxIterations setting. It’s defined as a TAutoConsoleVariable, which means it’s an integer console variable that can be modified at runtime.

The GetMaxTraversalIterations() function in the LumenHardwareRayTracing namespace uses this variable to retrieve the current setting value, ensuring it’s at least 1. This function is likely called by other parts of the Lumen system to determine the maximum number of ray tracing iterations to perform.

When working with CVarLumenHardwareRayTracingMaxIterations, developers should:

  1. Use the GetValueOnRenderThread() method to access its value safely from the render thread.
  2. Be aware that changes to this variable will affect ongoing rendering processes.
  3. Consider exposing this setting in user-facing graphics options if fine-tuning is necessary for different hardware configurations.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenHardwareRayTracingCommon.cpp:66

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarLumenHardwareRayTracingMaxIterations(
	TEXT("r.Lumen.HardwareRayTracing.MaxIterations"),
	8192,
	TEXT("Limit number of ray tracing traversal iterations on supported platfoms.\n"
		"Incomplete misses will be treated as hitting a black surface (can cause overocculsion).\n"
		"Incomplete hits will be treated as a hit (can cause leaking)."),
	ECVF_RenderThreadSafe
);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenHardwareRayTracingCommon.cpp:65

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarLumenHardwareRayTracingMaxIterations(
	TEXT("r.Lumen.HardwareRayTracing.MaxIterations"),
	8192,
	TEXT("Limit number of ray tracing traversal iterations on supported platfoms.\n"
		"Incomplete misses will be treated as hitting a black surface (can cause overocculsion).\n"
		"Incomplete hits will be treated as a hit (can cause leaking)."),
	ECVF_RenderThreadSafe

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenHardwareRayTracingCommon.cpp:180

Scope (from outer to inner):

file
function     uint32 LumenHardwareRayTracing::GetMaxTraversalIterations

Source code excerpt:

uint32 LumenHardwareRayTracing::GetMaxTraversalIterations()
{
	return FMath::Max(CVarLumenHardwareRayTracingMaxIterations.GetValueOnRenderThread(), 1);
}

#if RHI_RAYTRACING

FLumenHardwareRayTracingShaderBase::FLumenHardwareRayTracingShaderBase() = default;
FLumenHardwareRayTracingShaderBase::FLumenHardwareRayTracingShaderBase(const ShaderMetaType::CompiledShaderInitializerType& Initializer)