r.Lumen.Reflections.SampleSceneColorRelativeDepthThickness

r.Lumen.Reflections.SampleSceneColorRelativeDepthThickness

#Overview

name: r.Lumen.Reflections.SampleSceneColorRelativeDepthThickness

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

• type: Var
• help: Depth threshold that controls how close ray hits have to be to the depth buffer, before sampling SceneColor is allowed.

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.Reflections.SampleSceneColorRelativeDepthThickness is to control the depth threshold for sampling scene color in Lumen reflections. It is part of Unreal Engine 5’s Lumen global illumination and reflection system.

This setting variable is primarily used in the Lumen reflection tracing subsystem of Unreal Engine 5’s rendering module. Based on the callsites, it’s utilized in both the software-based reflection tracing (LumenReflectionTracing.cpp) and hardware ray tracing (LumenReflectionHardwareRayTracing.cpp) implementations.

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

The associated variable GLumenReflectionSampleSceneColorRelativeDepthThreshold directly interacts with r.Lumen.Reflections.SampleSceneColorRelativeDepthThickness. They share the same value, with GLumenReflectionSampleSceneColorRelativeDepthThreshold being the C++ variable that holds the actual value used in the code.

Developers must be aware that this variable affects the quality and performance of Lumen reflections. It determines how close ray hits need to be to the depth buffer before sampling the scene color is allowed. A smaller value will result in more precise reflections but may increase the computational cost.

Best practices when using this variable include:

1. Adjusting it carefully to balance between reflection quality and performance.
2. Testing different values in various scenarios to find the optimal setting for your specific use case.
3. Considering its impact on different hardware configurations, as it’s marked with ECVF_Scalability.

Regarding the associated variable GLumenReflectionSampleSceneColorRelativeDepthThreshold:

• Its purpose is to store the actual value of the depth threshold used in the reflection tracing calculations.
• It’s used directly in the rendering code to compute the RelativeDepthThickness parameter for both software and hardware-based reflection tracing.
• The value is set from the console variable r.Lumen.Reflections.SampleSceneColorRelativeDepthThickness.
• It interacts with the view matrices to calculate the final depth threshold used in the shaders.
• Developers should be aware that modifying this variable directly in code would bypass the console variable system, which is generally not recommended unless there’s a specific need for programmatic control.
• Best practice is to adjust the r.Lumen.Reflections.SampleSceneColorRelativeDepthThickness console variable rather than modifying GLumenReflectionSampleSceneColorRelativeDepthThreshold directly.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

float GLumenReflectionSampleSceneColorRelativeDepthThreshold = .05f;
FAutoConsoleVariableRef GVarLumenReflectionSampleSceneColorRelativeDepthThreshold(
	TEXT("r.Lumen.Reflections.SampleSceneColorRelativeDepthThickness"),
	GLumenReflectionSampleSceneColorRelativeDepthThreshold,
	TEXT("Depth threshold that controls how close ray hits have to be to the depth buffer, before sampling SceneColor is allowed."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenReflectionsDistantScreenTraces = 1;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenReflectionHardwareRayTracing.cpp:397

Scope (from outer to inner):

file
function     void DispatchRayGenOrComputeShader

Source code excerpt:

		}

		extern float GLumenReflectionSampleSceneColorRelativeDepthThreshold;
		Parameters->RelativeDepthThickness = GLumenReflectionSampleSceneColorRelativeDepthThreshold * View.ViewMatrices.GetPerProjectionDepthThicknessScale();
		Parameters->SampleSceneColorNormalTreshold = LumenReflections::GetSampleSceneColorNormalTreshold();
		Parameters->SampleSceneColor = bSampleSceneColorAtHit ? 1 : 0;

		Parameters->NearFieldLightingMode = static_cast<int32>(Lumen::GetHardwareRayTracingLightingMode(View, bLumenGIEnabled));
		Parameters->UseReflectionCaptures = Lumen::UseReflectionCapturesForHitLighting();
		Parameters->FarFieldBias = LumenHardwareRayTracing::GetFarFieldBias();

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

Scope: file

Source code excerpt:

);

float GLumenReflectionSampleSceneColorRelativeDepthThreshold = .05f;
FAutoConsoleVariableRef GVarLumenReflectionSampleSceneColorRelativeDepthThreshold(
	TEXT("r.Lumen.Reflections.SampleSceneColorRelativeDepthThickness"),
	GLumenReflectionSampleSceneColorRelativeDepthThreshold,
	TEXT("Depth threshold that controls how close ray hits have to be to the depth buffer, before sampling SceneColor is allowed."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenReflectionsDistantScreenTraces = 1;
FAutoConsoleVariableRef CVarLumenReflectionsDistantScreenTraces(

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

Scope (from outer to inner):

file
function     void TraceReflections

Source code excerpt:

			}

			PassParameters->RelativeDepthThickness = GLumenReflectionSampleSceneColorRelativeDepthThreshold * View.ViewMatrices.GetPerProjectionDepthThicknessScale();
			PassParameters->SampleSceneColorNormalTreshold = LumenReflections::GetSampleSceneColorNormalTreshold();

			PassParameters->DistantScreenTraceFurthestHZBTexture = View.HZB;
			PassParameters->DistantScreenTraceSlopeCompareTolerance = GLumenReflectionDistantScreenTraceSlopeCompareTolerance;
			PassParameters->DistantScreenTraceMaxTraceDistance = GLumenReflectionDistantScreenTraceMaxTraceDistance;