r.LumenScene.FarField

r.LumenScene.FarField

#Overview

name: r.LumenScene.FarField

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

• type: Var
• help: Enable/Disable Lumen far-field ray tracing.

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.LumenScene.FarField is to enable or disable Lumen far-field ray tracing in Unreal Engine 5’s rendering system. This setting variable is primarily used in the Lumen global illumination system, which is part of UE5’s advanced rendering capabilities.

Based on the callsites, this setting variable is primarily relied upon by the Renderer module, specifically within the Lumen subsystem. It’s also referenced in the Engine module, indicating its importance in the overall rendering pipeline.

The value of this variable is set through a console variable (CVar) system, allowing it to be changed at runtime. It’s initialized with a default value of 0, meaning far-field ray tracing is disabled by default.

This variable interacts closely with other Lumen-related variables, particularly r.Lumen.HardwareRayTracing. Together, they determine how ray tracing is utilized in the Lumen system.

Developers must be aware that changing this variable’s value will trigger a recreation of scene proxies. This is evident from the lambda function attached to the console variable, which creates a FGlobalComponentRecreateRenderStateContext when the value changes.

Best practices when using this variable include:

1. Consider performance implications when enabling far-field ray tracing, as it can be computationally expensive.
2. Use in conjunction with other Lumen settings for optimal results.
3. Be aware that enabling this feature may require additional hardware support, particularly for ray tracing.

Regarding the associated variable CVarLumenFarField:

The purpose of CVarLumenFarField is to serve as the actual console variable object that controls the r.LumenScene.FarField setting. It’s an implementation detail of how the engine manages configurable settings.

This variable is used within the Lumen namespace to determine if far-field tracing should be used. The UseFarField function checks both this variable and the engine show flags to decide whether to enable far-field tracing.

The value of CVarLumenFarField is set through the console variable system, just like r.LumenScene.FarField.

It interacts with engine show flags, specifically LumenFarFieldTraces, to determine the final state of far-field tracing.

Developers should be aware that this variable is checked on the render thread, which is important for thread safety and performance considerations.

Best practices for CVarLumenFarField include:

1. Access its value using GetValueOnRenderThread() when in render thread code.
2. Consider the interaction with engine show flags when determining the actual state of far-field tracing.
3. Be cautious about changing its value frequently, as it triggers scene proxy recreation.

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

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarLumenFarField(
	TEXT("r.LumenScene.FarField"), 0,
	TEXT("Enable/Disable Lumen far-field ray tracing."),
	FConsoleVariableDelegate::CreateLambda([](IConsoleVariable* InVariable)
	{
		// Recreate proxies so that FPrimitiveSceneProxy::UpdateVisibleInLumenScene() can pick up any changed state
		FGlobalComponentRecreateRenderStateContext Context;
	}),

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/PrimitiveSceneProxy.cpp:1611

Scope (from outer to inner):

file
function     void FPrimitiveSceneProxy::UpdateVisibleInLumenScene

Source code excerpt:

#if RHI_RAYTRACING
	static const auto LumenUseHardwareRayTracingCVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.Lumen.HardwareRayTracing"));
	static const auto LumenUseFarFieldCVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.LumenScene.FarField"));
	bLumenUsesHardwareRayTracing = IsRayTracingEnabled()
		&& (GRHISupportsRayTracingShaders || GRHISupportsInlineRayTracing)
		&& LumenUseHardwareRayTracingCVar->GetValueOnAnyThread() != 0;
#endif

	bool bCanBeTraced = false;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarLumenFarField(
	TEXT("r.LumenScene.FarField"), 0,
	TEXT("Enable/Disable Lumen far-field ray tracing."),
	FConsoleVariableDelegate::CreateLambda([](IConsoleVariable* InVariable)
	{
		// Recreate proxies so that FPrimitiveSceneProxy::UpdateVisibleInLumenScene() can pick up any changed state
		FGlobalComponentRecreateRenderStateContext Context;

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

Scope (from outer to inner):

file
namespace    Lumen
function     bool UseFarField

Source code excerpt:

	bool UseFarField(const FSceneViewFamily& ViewFamily)
	{
		return CVarLumenFarField.GetValueOnRenderThread() != 0 
			&& ViewFamily.EngineShowFlags.LumenFarFieldTraces;
	}

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