r.Lumen.Ortho.OverrideMeshDFTraceDistances

r.Lumen.Ortho.OverrideMeshDFTraceDistances

#Overview

name: r.Lumen.Ortho.OverrideMeshDFTraceDistances

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

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.Ortho.OverrideMeshDFTraceDistances is to control how mesh distance field trace distances are determined in orthographic views when using Lumen, Unreal Engine 5’s global illumination and reflections system.

This setting variable is primarily used by the Lumen subsystem within the Unreal Engine 5 rendering module. It specifically affects the behavior of Lumen’s diffuse indirect lighting and reflection tracing in orthographic views.

The value of this variable is set through the Unreal Engine console variable system. It is initialized with a default value of 1 (enabled) in the source code.

This variable interacts with the View object, particularly checking if the view is orthographic (non-perspective). When enabled, it overrides the mesh distance field trace distances to use the full screen view rect size instead of manually set values.

Developers must be aware that this setting only affects orthographic views and has no impact on perspective views. It’s important to consider the performance implications of using the full screen view rect size for trace distances, as it may increase the computational cost for large orthographic views.

Best practices when using this variable include:

  1. Only modify it if you’re experiencing issues with Lumen’s lighting or reflections in orthographic views.
  2. Monitor performance when enabling this feature, especially for large orthographic views.
  3. Consider disabling it if you need more precise control over trace distances in orthographic views.

The associated variable CVarOrthoOverrideMeshDFTraceDistances is the actual console variable that stores the setting. It is defined as an integer with the same default value (1) and description as r.Lumen.Ortho.OverrideMeshDFTraceDistances. This variable is used internally by the engine to check the current state of the setting and apply the appropriate behavior in the rendering code.

When using CVarOrthoOverrideMeshDFTraceDistances, developers should:

  1. Access its value using GetValueOnRenderThread() or GetValueOnAnyThread() depending on the context.
  2. Be aware that changes to this variable will affect all orthographic views using Lumen.
  3. Consider exposing this setting in user-facing graphics options if fine-tuning of orthographic Lumen behavior is desired.

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarOrthoOverrideMeshDFTraceDistances(
	TEXT("r.Lumen.Ortho.OverrideMeshDFTraceDistances"),
	1,
	TEXT("Use the full screen view rect size in Ortho views to determing the SDF trace distances instead of setting the value manually."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

bool LumenDiffuseIndirect::IsAllowed()

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenReflectionTracing.cpp:731

Scope (from outer to inner):

file
function     void SetupIndirectTracingParametersForReflections

Source code excerpt:

	if(!View.IsPerspectiveProjection())
	{
		const auto CVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.Lumen.Ortho.OverrideMeshDFTraceDistances"));
		if (CVar)
		{
			OrthoOverrideMeshDF = CVar->GetValueOnRenderThread() > 0;
		}
	}

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenVisualize.cpp:625

Scope (from outer to inner):

file
function     void SetupVisualizeParameters

Source code excerpt:

	if (!View.IsPerspectiveProjection())
	{
		const auto CVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.Lumen.Ortho.OverrideMeshDFTraceDistances"));
		if (CVar && CVar->GetValueOnRenderThread() > 0)
		{
			MaxMeshSDFTraceDistance = View.ViewMatrices.GetOrthoDimensions().GetMax();
		}		
	}

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarOrthoOverrideMeshDFTraceDistances(
	TEXT("r.Lumen.Ortho.OverrideMeshDFTraceDistances"),
	1,
	TEXT("Use the full screen view rect size in Ortho views to determing the SDF trace distances instead of setting the value manually."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

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

Scope (from outer to inner):

file
function     void SetupLumenDiffuseTracingParameters

Source code excerpt:

	OutParameters.MinTraceDistance = FMath::Clamp(GLumenDiffuseMinTraceDistance, .01f, 1000.0f);
	OutParameters.MaxTraceDistance = Lumen::GetMaxTraceDistance(View);
	if (!View.IsPerspectiveProjection() && CVarOrthoOverrideMeshDFTraceDistances.GetValueOnAnyThread())
	{
		float TraceSDFDistance = FMath::Clamp(View.ViewMatrices.GetOrthoDimensions().GetMax(), OutParameters.MinTraceDistance, OutParameters.MaxTraceDistance);
		OutParameters.MaxMeshSDFTraceDistance = TraceSDFDistance;
		OutParameters.CardTraceEndDistanceFromCamera = FMath::Max(GDiffuseCardTraceEndDistanceFromCamera, TraceSDFDistance);
	}
	else