r.Lumen.Visualize.HardwareRayTracing.Retrace.FarField

r.Lumen.Visualize.HardwareRayTracing.Retrace.FarField

#Overview

name: r.Lumen.Visualize.HardwareRayTracing.Retrace.FarField

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.Visualize.HardwareRayTracing.Retrace.FarField is to control whether a second trace will be fired for far-field contribution in Lumen’s hardware ray tracing visualization system. This setting is part of Unreal Engine 5’s Lumen global illumination system, specifically for its visualization and debugging features.

This setting variable is primarily used in the Renderer module, specifically within the Lumen subsystem. It’s part of the hardware ray tracing visualization functionality of Lumen.

The value of this variable is set through the console variable system in Unreal Engine. It’s defined as a TAutoConsoleVariable with a default value of 1, meaning the second trace for far-field contribution is enabled by default.

The associated variable CVarLumenVisualizeHardwareRayTracingRetraceFarField directly interacts with this setting. It’s the C++ representation of the console variable and is used to access the current value of the setting in the code.

Developers should be aware that this variable affects the visualization of hardware ray tracing in Lumen, specifically for far-field contributions. Changing this value will impact the visual debugging output of the Lumen system, which could be crucial for identifying and solving rendering issues related to global illumination.

Best practices when using this variable include:

  1. Only modify it when specifically debugging far-field contributions in Lumen’s hardware ray tracing.
  2. Be aware that enabling this (value 1) may have a performance impact due to the additional ray trace.
  3. Use in conjunction with other Lumen visualization tools for a comprehensive understanding of the rendering process.

Regarding the associated variable CVarLumenVisualizeHardwareRayTracingRetraceFarField:

The purpose of this variable is to provide programmatic access to the r.Lumen.Visualize.HardwareRayTracing.Retrace.FarField setting within the C++ code.

It’s used in the Renderer module, specifically in the LumenVisualize namespace. This variable is crucial for the internal workings of the Lumen visualization system.

The value of this variable is set by the console variable system, mirroring the value of r.Lumen.Visualize.HardwareRayTracing.Retrace.FarField.

It interacts directly with the UseFarField function in the LumenVisualize namespace, which determines whether far-field calculations should be included in the visualization.

Developers should be aware that this variable is used in render-thread-safe contexts, as indicated by the ECVF_RenderThreadSafe flag.

Best practices for using this variable include:

  1. Access its value using the GetValueOnRenderThread() method when in render thread contexts.
  2. Be cautious about caching its value, as it can be changed at runtime through the console.
  3. Consider the performance implications when enabling far-field retracing in visualizations.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenVisualizeHardwareRayTracing.cpp:67

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarLumenVisualizeHardwareRayTracingRetraceFarField(
	TEXT("r.Lumen.Visualize.HardwareRayTracing.Retrace.FarField"),
	1,
	TEXT("Determines whether a second trace will be fired for far-field contribution (default = 1"),
	ECVF_RenderThreadSafe
);

static TAutoConsoleVariable<int32> CVarLumenVisualizeHardwareRayTracingCompact(

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarLumenVisualizeHardwareRayTracingRetraceFarField(
	TEXT("r.Lumen.Visualize.HardwareRayTracing.Retrace.FarField"),
	1,
	TEXT("Determines whether a second trace will be fired for far-field contribution (default = 1"),
	ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenVisualizeHardwareRayTracing.cpp:121

Scope (from outer to inner):

file
namespace    LumenVisualize
function     bool UseFarField

Source code excerpt:

	bool UseFarField(const FSceneViewFamily& ViewFamily)
	{
		return Lumen::UseFarField(ViewFamily) && CVarLumenVisualizeHardwareRayTracingRetraceFarField.GetValueOnRenderThread() != 0;
	}

	bool IsHitLightingForceEnabled(const FViewInfo& View, bool bLumenGIEnabled)
	{
		return Lumen::GetHardwareRayTracingLightingMode(View, bLumenGIEnabled) != Lumen::EHardwareRayTracingLightingMode::LightingFromSurfaceCache;
	}