r.Lumen.ScreenProbeGather.HardwareRayTracing.Retrace.FarField

r.Lumen.ScreenProbeGather.HardwareRayTracing.Retrace.FarField

#Overview

name: r.Lumen.ScreenProbeGather.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.ScreenProbeGather.HardwareRayTracing.Retrace.FarField is to control whether a second trace should be fired for far-field contribution in Lumen’s screen probe gathering process when using hardware ray tracing.

This setting variable is primarily used by the Lumen rendering system, which is part of Unreal Engine’s global illumination solution. Specifically, it’s used in the screen probe gathering process that utilizes hardware ray tracing.

The value of this variable is set through a console variable (CVar) system. It’s defined with a default value of 1 (enabled) and can be changed at runtime.

This variable interacts with another variable named CVarLumenScreenProbeGatherHardwareRayTracingRetraceFarField. They share the same value and are essentially two ways to access the same setting.

Developers should be aware that this variable only has an effect when hardware ray tracing is enabled (RHI_RAYTRACING is defined) and when the Lumen system is using far-field contributions. If either of these conditions is not met, changing this variable will have no effect.

Best practices when using this variable include:

  1. Only modify it if you understand the performance implications of enabling/disabling far-field retracing.
  2. Test thoroughly after changing this setting, as it can affect the visual quality and performance of the global illumination.
  3. Consider exposing this setting in a debug menu for easier tweaking during development.

Regarding the associated variable CVarLumenScreenProbeGatherHardwareRayTracingRetraceFarField:

This is the actual CVar that stores the setting. It’s an integer variable that determines whether the second trace for far-field contribution should be fired.

It’s used in the UseFarField function within the LumenScreenProbeGather namespace. This function checks both whether far-field should be used for the view family and whether this CVar is enabled.

Developers should note that this variable is marked as ECVF_RenderThreadSafe, meaning it can be safely accessed from the render thread. When modifying this variable, ensure that changes are made in a thread-safe manner.

The best practice when using this associated variable is to access it using GetValueOnRenderThread() when in render thread code, as demonstrated in the UseFarField function.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenProbeHardwareRayTracing.cpp:36

Scope: file

Source code excerpt:


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

#endif // RHI_RAYTRACING

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenProbeHardwareRayTracing.cpp:35

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarLumenScreenProbeGatherHardwareRayTracingRetraceFarField(
	TEXT("r.Lumen.ScreenProbeGather.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/LumenScreenProbeHardwareRayTracing.cpp:63

Scope (from outer to inner):

file
namespace    LumenScreenProbeGather
function     bool UseFarField

Source code excerpt:

	{
#if RHI_RAYTRACING
		return Lumen::UseFarField(ViewFamily) && CVarLumenScreenProbeGatherHardwareRayTracingRetraceFarField.GetValueOnRenderThread();
#else
		return false;
#endif
	}

	enum class ERayTracingPass