r.LumenScene.GlobalSDF.DitheredTransparencyTraceThreshold

r.LumenScene.GlobalSDF.DitheredTransparencyTraceThreshold

#Overview

name: r.LumenScene.GlobalSDF.DitheredTransparencyTraceThreshold

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.LumenScene.GlobalSDF.DitheredTransparencyTraceThreshold is to control the per-trace stochastic semi-transparency threshold for the Lumen Scene Global SDF (Signed Distance Field) system, specifically for tracing users that have dithered transparency enabled in regions of space containing only Two Sided Mesh SDFs.

This setting variable is primarily used in the rendering system, specifically in the Global Distance Field module of Unreal Engine 5. It is part of the Lumen global illumination system, which relies on distance fields for real-time lighting calculations.

The value of this variable is set through the Unreal Engine console variable system. It is initialized with a default value of 0.9f and can be modified at runtime.

The associated variable GLumenSceneGlobalSDFDitheredTransparencyTraceThreshold directly interacts with this console variable. They share the same value, with the console variable acting as an interface for runtime modification.

Developers must be aware that this variable affects the quality and performance of the Lumen lighting system, particularly in scenes with semi-transparent objects. The documentation notes that setting this value to anything less than 1 causes leaking, which could result in visual artifacts.

Best practices when using this variable include:

  1. Keeping the value at or close to the default (0.9) unless specific visual issues need to be addressed.
  2. Testing thoroughly when modifying this value, as it can impact both visual quality and performance.
  3. Being cautious about setting values below 1, as it may introduce light leaking artifacts.

Regarding the associated variable GLumenSceneGlobalSDFDitheredTransparencyTraceThreshold:

The purpose of this variable is to store and provide access to the dithered transparency trace threshold value within the rendering code.

It is used in the Global Distance Field module of the rendering system, specifically in functions that set up Global Distance Field parameters and View Uniform Shader Parameters.

The value of this variable is set by the console variable r.LumenScene.GlobalSDF.DitheredTransparencyTraceThreshold.

This variable interacts directly with shader parameters and view uniform shader parameters, influencing how the engine handles semi-transparent objects in the global distance field calculations.

Developers should be aware that modifications to this variable will affect the Lumen lighting system’s behavior for semi-transparent objects.

Best practices include ensuring that any code that needs to access this threshold value uses this variable rather than hardcoded values, maintaining consistency throughout the rendering pipeline.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/GlobalDistanceField.cpp:254

Scope: file

Source code excerpt:

float GLumenSceneGlobalSDFDitheredTransparencyTraceThreshold = .9f;
FAutoConsoleVariableRef CVarLumenSceneGlobalSDFDitheredTransparencyTraceThreshold(
	TEXT("r.LumenScene.GlobalSDF.DitheredTransparencyTraceThreshold"),
	GLumenSceneGlobalSDFDitheredTransparencyTraceThreshold,
	TEXT("Per-trace stochastic semi-transparency threshold, for tracing users that have dithered transparency enabled, for regions of space that only contain Two Sided Mesh SDFs.  Anything less than 1 causes leaking."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

TAutoConsoleVariable<bool> CVarGlobalDistanceFieldDebugShowStats(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/GlobalDistanceField.cpp:252

Scope: file

Source code excerpt:

);

float GLumenSceneGlobalSDFDitheredTransparencyTraceThreshold = .9f;
FAutoConsoleVariableRef CVarLumenSceneGlobalSDFDitheredTransparencyTraceThreshold(
	TEXT("r.LumenScene.GlobalSDF.DitheredTransparencyTraceThreshold"),
	GLumenSceneGlobalSDFDitheredTransparencyTraceThreshold,
	TEXT("Per-trace stochastic semi-transparency threshold, for tracing users that have dithered transparency enabled, for regions of space that only contain Two Sided Mesh SDFs.  Anything less than 1 causes leaking."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

TAutoConsoleVariable<bool> CVarGlobalDistanceFieldDebugShowStats(
	TEXT("r.GlobalDistanceField.Debug.ShowStats"),

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/GlobalDistanceField.cpp:335

Scope (from outer to inner):

file
function     FGlobalDistanceFieldParameters2 SetupGlobalDistanceFieldParameters

Source code excerpt:

	ShaderParameters.NotCoveredMinStepScale = GLumenSceneGlobalSDFNotCoveredMinStepScale;
	ShaderParameters.DitheredTransparencyStepThreshold = GLumenSceneGlobalSDFDitheredTransparencyStepThreshold;
	ShaderParameters.DitheredTransparencyTraceThreshold = GLumenSceneGlobalSDFDitheredTransparencyTraceThreshold;
	ShaderParameters.GlobalDistanceFieldCoverageAtlasTextureSampler = TStaticSamplerState<SF_Trilinear, AM_Wrap, AM_Wrap, AM_Wrap>::GetRHI();
	ShaderParameters.GlobalDistanceFieldPageAtlasTextureSampler = TStaticSamplerState<SF_Trilinear, AM_Wrap, AM_Wrap, AM_Wrap>::GetRHI();
	ShaderParameters.GlobalDistanceFieldMipTextureSampler = TStaticSamplerState<SF_Trilinear, AM_Clamp, AM_Clamp, AM_Clamp>::GetRHI();

	return ShaderParameters;
}

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/GlobalDistanceField.cpp:1363

Scope (from outer to inner):

file
function     void FViewInfo::SetupGlobalDistanceFieldUniformBufferParameters

Source code excerpt:

	ViewUniformShaderParameters.NotCoveredMinStepScale = GLumenSceneGlobalSDFNotCoveredMinStepScale;
	ViewUniformShaderParameters.DitheredTransparencyStepThreshold = GLumenSceneGlobalSDFDitheredTransparencyStepThreshold;
	ViewUniformShaderParameters.DitheredTransparencyTraceThreshold = GLumenSceneGlobalSDFDitheredTransparencyTraceThreshold;
}

void ReadbackDistanceFieldClipmap(FRHICommandListImmediate& RHICmdList, FGlobalDistanceFieldInfo& GlobalDistanceFieldInfo)
{
	FGlobalDistanceFieldReadback* Readback = GDFReadbackRequest;
	GDFReadbackRequest = nullptr;