r.Lumen.TraceMeshSDFs

r.Lumen.TraceMeshSDFs

#Overview

name: r.Lumen.TraceMeshSDFs

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.TraceMeshSDFs is to control whether Lumen should trace against Mesh Signed Distance Fields (SDFs) in its software ray tracing mode. This setting is part of the Lumen global illumination system in Unreal Engine 5’s rendering pipeline.

This setting variable is primarily used by the Lumen subsystem within the Renderer module of Unreal Engine 5. It affects the accuracy and performance of Lumen’s software ray tracing capabilities.

The value of this variable is set in multiple places:

  1. It can be configured through the project settings in the Renderer Settings category.
  2. It’s initialized as a console variable with a default value of 1 (enabled).
  3. It can be changed at runtime through the console or scalability settings.

The variable interacts with another variable called GLumenAllowTracingMeshSDFs, which is driven by scalability settings. Both variables need to be non-zero for Mesh SDF tracing to be enabled.

Developers must be aware that:

  1. Enabling this feature increases accuracy but can significantly impact performance in scenes with high instance density (overlapping meshes).
  2. When disabled, Lumen falls back to using the lower resolution Global Signed Distance Field instead.
  3. This setting affects the Software Ray Tracing mode of Lumen, not the hardware-accelerated ray tracing.

Best practices when using this variable include:

  1. Enable it for higher quality rendering when performance allows.
  2. Consider disabling it in scenes with many overlapping meshes to improve performance.
  3. Use in conjunction with scalability settings to adjust based on hardware capabilities.

Regarding the associated variable GLumenTraceMeshSDFs: The purpose of GLumenTraceMeshSDFs is to store the actual value of the r.Lumen.TraceMeshSDFs setting. It’s used internally by the rendering system to quickly check if Mesh SDF tracing should be performed.

This variable is set directly by the console variable system when r.Lumen.TraceMeshSDFs is changed. It’s used in the Lumen::UseMeshSDFTracing function to determine if Mesh SDF tracing should be used for a given view.

Developers should not modify GLumenTraceMeshSDFs directly, but instead use the r.Lumen.TraceMeshSDFs console variable or project settings to control this feature. The variable is designed to be read-only from the perspective of most code, serving as a fast access point for the current setting value.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Classes/Engine/RendererSettings.h:516

Scope (from outer to inner):

file
class        class URendererSettings : public UDeveloperSettings

Source code excerpt:

	UPROPERTY(config, EditAnywhere, Category=Lumen, meta=(
		EditCondition = "bGenerateMeshDistanceFields",
		ConsoleVariable="r.Lumen.TraceMeshSDFs", DisplayName = "Software Ray Tracing Mode",
		ToolTip="Controls which tracing method Lumen uses when using Software Ray Tracing."))
	TEnumAsByte<ELumenSoftwareTracingMode::Type> LumenSoftwareTracingMode;

	UPROPERTY(config, EditAnywhere, Category = Lumen, meta = (
		ConsoleVariable = "r.Lumen.Reflections.HardwareRayTracing.Translucent.Refraction.EnableForProject", DisplayName = "Ray Traced Translucent Refractions",
		ToolTip = "Whether to use Lumen refraction tracing from surfaces when using harware ray tracing and hit lighting. This will require shader recompilation to compile of translucent card capture Lumen shaders. Increases GPU cost when enabled."))

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

Scope: file

Source code excerpt:

int32 GLumenTraceMeshSDFs = 1;
FAutoConsoleVariableRef CVarLumenTraceMeshSDFs(
	TEXT("r.Lumen.TraceMeshSDFs"),
	GLumenTraceMeshSDFs,
	TEXT("Whether Lumen should trace against Mesh Signed Distance fields.  When enabled, Lumen's Software Tracing will be more accurate, but scenes with high instance density (overlapping meshes) will have high tracing costs.  When disabled, lower resolution Global Signed Distance Field will be used instead."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

// Scalability setting driven by scalability ini

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:


// Project setting driven by RendererSettings
int32 GLumenTraceMeshSDFs = 1;
FAutoConsoleVariableRef CVarLumenTraceMeshSDFs(
	TEXT("r.Lumen.TraceMeshSDFs"),
	GLumenTraceMeshSDFs,
	TEXT("Whether Lumen should trace against Mesh Signed Distance fields.  When enabled, Lumen's Software Tracing will be more accurate, but scenes with high instance density (overlapping meshes) will have high tracing costs.  When disabled, lower resolution Global Signed Distance Field will be used instead."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

// Scalability setting driven by scalability ini
int32 GLumenAllowTracingMeshSDFs = 1;

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

Scope (from outer to inner):

file
function     bool Lumen::UseMeshSDFTracing

Source code excerpt:

bool Lumen::UseMeshSDFTracing(const FSceneViewFamily& ViewFamily)
{
	return GLumenTraceMeshSDFs != 0 
		&& GLumenAllowTracingMeshSDFs != 0
		&& ViewFamily.EngineShowFlags.LumenDetailTraces;
}

bool Lumen::UseGlobalSDFTracing(const FSceneViewFamily& ViewFamily)
{