r.LumenScene.FarField.MaxTraceDistance

r.LumenScene.FarField.MaxTraceDistance

#Overview

name: r.LumenScene.FarField.MaxTraceDistance

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

• type: Var
• help: Maximum hit-distance for Lumen far-field ray tracing (Default = 1.0e6).

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.LumenScene.FarField.MaxTraceDistance is to control the maximum hit-distance for Lumen far-field ray tracing in Unreal Engine 5’s rendering system. This setting is specifically related to the Lumen global illumination system, which is part of UE5’s advanced rendering features.

This setting variable is primarily used by the Lumen subsystem within the Renderer module of Unreal Engine 5. It’s particularly relevant to the far-field ray tracing component of Lumen, which handles global illumination calculations for distant objects and surfaces.

The value of this variable is set as a console variable (CVar) with a default value of 1.0e6 (1 million units). It can be modified at runtime through the console or programmatically.

The associated variable CVarLumenFarFieldMaxTraceDistance interacts directly with this setting. It’s the C++ representation of the console variable and is used to retrieve the current value of the setting within the engine’s code.

Developers should be aware that this variable affects the maximum distance that Lumen’s far-field ray tracing will consider. Setting this value too low might result in missing illumination from distant objects, while setting it too high might impact performance unnecessarily.

Best practices when using this variable include:

1. Adjusting it based on the scale of your scene. Larger scenes might require higher values.
2. Balancing it with performance considerations, as larger trace distances can increase computational load.
3. Using it in conjunction with other Lumen settings for optimal results.

Regarding the associated variable CVarLumenFarFieldMaxTraceDistance:

The purpose of CVarLumenFarFieldMaxTraceDistance is to provide programmatic access to the r.LumenScene.FarField.MaxTraceDistance setting within the engine’s C++ code.

This variable is used directly in the Lumen subsystem of the Renderer module. It’s accessed through the GetFarFieldMaxTraceDistance() function, which is likely called during the Lumen rendering process.

The value of this variable is set by the console variable system and can be retrieved using the GetValueOnRenderThread() method, ensuring thread-safe access in the render thread.

No other variables directly interact with CVarLumenFarFieldMaxTraceDistance based on the provided information.

Developers should be aware that this variable provides the actual value used in the rendering calculations, so any runtime changes to the console variable will be reflected through this associated variable.

Best practices for using CVarLumenFarFieldMaxTraceDistance include:

1. Accessing it through the provided GetFarFieldMaxTraceDistance() function rather than directly.
2. Being mindful of potential performance implications when frequently accessing or changing this value.
3. Considering thread safety when accessing this variable, as it’s designed to be used in the render thread.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScene.cpp:34

Scope: file

Source code excerpt:

static TAutoConsoleVariable<float> CVarLumenFarFieldMaxTraceDistance(
	TEXT("r.LumenScene.FarField.MaxTraceDistance"),
	1.0e6f,
	TEXT("Maximum hit-distance for Lumen far-field ray tracing (Default = 1.0e6)."),
	ECVF_Scalability | ECVF_RenderThreadSafe);

static TAutoConsoleVariable<float> CVarLumenFarFieldDitherScale(
	TEXT("r.LumenScene.FarField.FarFieldDitherScale"),

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScene.cpp:33

Scope: file

Source code excerpt:

	ECVF_Scalability | ECVF_RenderThreadSafe);

static TAutoConsoleVariable<float> CVarLumenFarFieldMaxTraceDistance(
	TEXT("r.LumenScene.FarField.MaxTraceDistance"),
	1.0e6f,
	TEXT("Maximum hit-distance for Lumen far-field ray tracing (Default = 1.0e6)."),
	ECVF_Scalability | ECVF_RenderThreadSafe);

static TAutoConsoleVariable<float> CVarLumenFarFieldDitherScale(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScene.cpp:84

Scope (from outer to inner):

file
namespace    Lumen
function     float GetFarFieldMaxTraceDistance

Source code excerpt:

	float GetFarFieldMaxTraceDistance()
	{
		return CVarLumenFarFieldMaxTraceDistance.GetValueOnRenderThread();
	}

	float GetNearFieldMaxTraceDistanceDitherScale(bool bUseFarField)
	{
		return bUseFarField ? CVarLumenFarFieldDitherScale.GetValueOnRenderThread() : 0.0f;
	}