r.LumenScene.DirectLighting.OffscreenShadowing.TraceMeshSDFs

r.LumenScene.DirectLighting.OffscreenShadowing.TraceMeshSDFs

#Overview

name: r.LumenScene.DirectLighting.OffscreenShadowing.TraceMeshSDFs

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

• type: Var
• help: Whether to trace against Mesh Signed Distance Fields for offscreen shadowing, or to trace against the lower resolution Global SDF.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.LumenScene.DirectLighting.OffscreenShadowing.TraceMeshSDFs is to control whether Lumen’s direct lighting system traces against Mesh Signed Distance Fields (SDFs) for offscreen shadowing or uses the lower resolution Global SDF instead.

This setting variable is primarily used by the Lumen rendering system in Unreal Engine 5, specifically for the direct lighting and shadowing calculations. It is part of the Renderer module, as evidenced by its location in the LumenSceneDirectLighting.cpp file.

The value of this variable is set through the Unreal Engine console variable system. It is initialized to 1 (enabled) by default, but can be changed at runtime or through configuration files.

The associated C++ variable GLumenDirectLightingOffscreenShadowingTraceMeshSDFs directly interacts with this console variable. They share the same value, with the console variable acting as an interface for users to modify the setting.

Developers should be aware that this variable affects the quality and performance of offscreen shadowing in Lumen. Tracing against Mesh SDFs can provide more accurate shadows but may be more computationally expensive than using the Global SDF.

Best practices when using this variable include:

1. Consider the performance implications when enabling or disabling this feature, especially on lower-end hardware.
2. Test the visual quality difference between using Mesh SDFs and the Global SDF for your specific scenes.
3. Use this setting in conjunction with other Lumen settings to fine-tune the balance between visual quality and performance.

Regarding the associated variable GLumenDirectLightingOffscreenShadowingTraceMeshSDFs:

This is an integer variable that directly controls the behavior specified by the console variable. It is used in the rendering code to determine whether to trace against Mesh SDFs or the Global SDF for offscreen shadowing.

The variable is checked in the TraceDistanceFieldShadows function, where it influences the decision to trace mesh objects for directional lights. When set to a non-zero value, it allows for more detailed shadowing calculations using Mesh SDFs.

Developers should be aware that modifying this variable directly in code will have the same effect as changing the console variable. However, it’s generally recommended to use the console variable interface for runtime adjustments and debugging, while the C++ variable is used internally by the engine for actual rendering calculations.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenSceneDirectLighting.cpp:22

Scope: file

Source code excerpt:

int32 GLumenDirectLightingOffscreenShadowingTraceMeshSDFs = 1;
FAutoConsoleVariableRef CVarLumenDirectLightingOffscreenShadowingTraceMeshSDFs(
	TEXT("r.LumenScene.DirectLighting.OffscreenShadowing.TraceMeshSDFs"),
	GLumenDirectLightingOffscreenShadowingTraceMeshSDFs,
	TEXT("Whether to trace against Mesh Signed Distance Fields for offscreen shadowing, or to trace against the lower resolution Global SDF."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

static TAutoConsoleVariable<int32> CVarLumenDirectLightingMaxLightsPerTile(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenSceneDirectLighting.cpp:20

Scope: file

Source code excerpt:

	ECVF_Scalability | ECVF_RenderThreadSafe);

int32 GLumenDirectLightingOffscreenShadowingTraceMeshSDFs = 1;
FAutoConsoleVariableRef CVarLumenDirectLightingOffscreenShadowingTraceMeshSDFs(
	TEXT("r.LumenScene.DirectLighting.OffscreenShadowing.TraceMeshSDFs"),
	GLumenDirectLightingOffscreenShadowingTraceMeshSDFs,
	TEXT("Whether to trace against Mesh Signed Distance Fields for offscreen shadowing, or to trace against the lower resolution Global SDF."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

static TAutoConsoleVariable<int32> CVarLumenDirectLightingMaxLightsPerTile(
	TEXT("r.LumenScene.DirectLighting.MaxLightsPerTile"),

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenSceneDirectLighting.cpp:1283

Scope (from outer to inner):

file
function     void TraceDistanceFieldShadows

Source code excerpt:

			&& Light.Type == ELumenLightType::Directional
			&& DoesPlatformSupportDistanceFieldShadowing(View.GetShaderPlatform())
			&& GLumenDirectLightingOffscreenShadowingTraceMeshSDFs != 0;

		const bool bTraceMeshSDFs = bTraceMeshObjects
			&& Lumen::UseMeshSDFTracing(*View.Family)
			&& ObjectBufferParameters.NumSceneObjects > 0;

		const bool bTraceHeighfieldObjects = bTraceMeshObjects