r.Lumen.HardwareRayTracing.MinTraceDistanceToSampleSurfaceCache

r.Lumen.HardwareRayTracing.MinTraceDistanceToSampleSurfaceCache

#Overview

name: r.Lumen.HardwareRayTracing.MinTraceDistanceToSampleSurfaceCache

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.MinTraceDistanceToSampleSurfaceCache is to set the minimum ray hit distance from which the rendering system can start sampling the surface cache in Lumen’s hardware ray tracing implementation. This setting is used to prevent feedback loops where a surface cache texel might hit itself and propagate lighting incorrectly.

This setting variable is primarily used in the Lumen subsystem of Unreal Engine’s rendering module. Specifically, it’s utilized in the hardware ray tracing component of Lumen, which is part of UE5’s global illumination system.

The value of this variable is set through the console variable system in Unreal Engine. It’s initialized with a default value of 10.0f, but can be modified at runtime or through configuration files.

The associated variable CVarLumenHardwareRayTracingMinTraceDistanceToSampleSurfaceCache directly interacts with this setting. It’s the actual ConsoleVariable object that stores and manages the value of the setting.

Developers should be aware that modifying this value can impact the quality and performance of global illumination in scenes using Lumen with hardware ray tracing. A lower value might lead to more accurate short-range lighting but could potentially introduce artifacts or feedback loops. A higher value might reduce artifacts but could miss out on some short-range lighting details.

Best practices when using this variable include:

  1. Testing different values to find the optimal balance between lighting quality and performance for your specific scene.
  2. Considering the scale of your scene when setting this value, as the appropriate distance may vary depending on the size of objects and spaces in your game.
  3. Monitoring performance impact when adjusting this value, as it may affect ray tracing workload.

Regarding the associated variable CVarLumenHardwareRayTracingMinTraceDistanceToSampleSurfaceCache:

This is the actual ConsoleVariable object that represents r.Lumen.HardwareRayTracing.MinTraceDistanceToSampleSurfaceCache in the engine’s code. It’s used to store, retrieve, and manage the value of the setting.

The purpose of this variable is to provide a programmatic interface to the setting within the engine’s C++ code. It allows the engine to access and modify the setting value at runtime.

This variable is used in the Lumen subsystem of the rendering module, specifically in the hardware ray tracing component.

The value of this variable is set when the ConsoleVariable is initialized, but can be changed at runtime through console commands or configuration files.

Developers should be aware that this is the actual object they would interact with in C++ code if they need to read or modify the setting programmatically.

Best practices include using the provided getter method (GetValueOnRenderThread()) to access the value, as shown in the GetMinTraceDistanceToSampleSurfaceCache() function, to ensure thread-safe access to the variable’s value.

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

Scope: file

Source code excerpt:


TAutoConsoleVariable<float> CVarLumenHardwareRayTracingMinTraceDistanceToSampleSurfaceCache(
	TEXT("r.Lumen.HardwareRayTracing.MinTraceDistanceToSampleSurfaceCache"),
	10.0f,
	TEXT("Ray hit distance from which we can start sampling surface cache in order to fix feedback loop where surface cache texel hits itself and propagates lighting."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

bool LumenHardwareRayTracing::IsInlineSupported()

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

TAutoConsoleVariable<float> CVarLumenHardwareRayTracingMinTraceDistanceToSampleSurfaceCache(
	TEXT("r.Lumen.HardwareRayTracing.MinTraceDistanceToSampleSurfaceCache"),
	10.0f,
	TEXT("Ray hit distance from which we can start sampling surface cache in order to fix feedback loop where surface cache texel hits itself and propagates lighting."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

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

Scope (from outer to inner):

file
function     float LumenHardwareRayTracing::GetMinTraceDistanceToSampleSurfaceCache

Source code excerpt:

float LumenHardwareRayTracing::GetMinTraceDistanceToSampleSurfaceCache()
{
	return CVarLumenHardwareRayTracingMinTraceDistanceToSampleSurfaceCache.GetValueOnRenderThread();
}

Lumen::EHardwareRayTracingLightingMode Lumen::GetHardwareRayTracingLightingMode(const FViewInfo& View, bool bLumenGIEnabled)
{
#if RHI_RAYTRACING