r.Lumen.TraceDistanceScale

r.Lumen.TraceDistanceScale

#Overview

name: r.Lumen.TraceDistanceScale

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.TraceDistanceScale is to scale the tracing distance for all tracing methods and Lumen features in Unreal Engine 5’s rendering system. This setting variable is specifically used for scalability purposes within the Lumen global illumination system.

This setting variable is primarily used in the Lumen subsystem, which is part of Unreal Engine 5’s rendering module. Based on the callsites, it’s clear that this variable is utilized in the LumenDiffuseIndirect.cpp file, which is responsible for handling diffuse indirect lighting calculations in Lumen.

The value of this variable is set through the console variable system in Unreal Engine. It’s declared as an FAutoConsoleVariableRef, which means it can be adjusted at runtime through console commands or configuration files.

The r.Lumen.TraceDistanceScale variable interacts directly with the GLumenTraceDistanceScale global variable. They share the same value, with GLumenTraceDistanceScale being the C++ variable that’s actually used in the code calculations.

Developers should be aware that this variable affects all tracing methods and Lumen features. Changing this value will have a global impact on the Lumen system’s performance and visual quality. It’s important to note that this variable is marked with ECVF_Scalability and ECVF_RenderThreadSafe flags, indicating it’s intended for scalability adjustments and is safe to modify from the render thread.

Best practices when using this variable include:

  1. Use it for performance optimization, especially on lower-end hardware.
  2. Be cautious when increasing the value, as it may significantly impact performance.
  3. Test thoroughly across different hardware configurations when adjusting this value.

Regarding the associated variable GLumenTraceDistanceScale:

The purpose of GLumenTraceDistanceScale is to store the actual scaling factor used in the Lumen tracing calculations. It’s the C++ representation of the r.Lumen.TraceDistanceScale console variable.

This variable is used directly in the Lumen subsystem of the rendering module. Specifically, it’s used in the GetMaxTraceDistance function within the Lumen namespace.

The value of GLumenTraceDistanceScale is set by the r.Lumen.TraceDistanceScale console variable. Any changes to r.Lumen.TraceDistanceScale will directly affect GLumenTraceDistanceScale.

GLumenTraceDistanceScale interacts with the View.FinalPostProcessSettings.LumenMaxTraceDistance setting in the GetMaxTraceDistance function. The final trace distance is calculated by multiplying these two values and clamping the result.

Developers should be aware that modifying GLumenTraceDistanceScale directly in code is not recommended. Instead, they should use the r.Lumen.TraceDistanceScale console variable to ensure proper synchronization.

Best practices for GLumenTraceDistanceScale include:

  1. Avoid modifying it directly in code; use r.Lumen.TraceDistanceScale instead.
  2. Be aware of its impact on the maximum trace distance calculation.
  3. Consider its interaction with other Lumen settings when optimizing performance and quality.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenDiffuseIndirect.cpp:87

Scope: file

Source code excerpt:

float GLumenTraceDistanceScale = 1.0f;
FAutoConsoleVariableRef CVarTraceDistanceScale(
	TEXT("r.Lumen.TraceDistanceScale"),
	GLumenTraceDistanceScale,
	TEXT("Scales the tracing distance for all tracing methods and Lumen features, used by scalability."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

// Project setting driven by RendererSettings

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenDiffuseIndirect.cpp:85

Scope: file

Source code excerpt:

	);

float GLumenTraceDistanceScale = 1.0f;
FAutoConsoleVariableRef CVarTraceDistanceScale(
	TEXT("r.Lumen.TraceDistanceScale"),
	GLumenTraceDistanceScale,
	TEXT("Scales the tracing distance for all tracing methods and Lumen features, used by scalability."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

// Project setting driven by RendererSettings
int32 GLumenTraceMeshSDFs = 1;

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenDiffuseIndirect.cpp:209

Scope (from outer to inner):

file
function     float Lumen::GetMaxTraceDistance

Source code excerpt:

float Lumen::GetMaxTraceDistance(const FViewInfo& View)
{
	return FMath::Clamp(View.FinalPostProcessSettings.LumenMaxTraceDistance * GLumenTraceDistanceScale, .01f, Lumen::MaxTraceDistance);
}

bool Lumen::ShouldPrecachePSOs(EShaderPlatform Platform)
{
	return DoesPlatformSupportLumenGI(Platform) && CVarLumenGlobalIllumination.GetValueOnAnyThread();
}