r.LumenScene.GlobalSDF.CoveredExpandSurfaceScale

r.LumenScene.GlobalSDF.CoveredExpandSurfaceScale

#Overview

name: r.LumenScene.GlobalSDF.CoveredExpandSurfaceScale

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

• type: Var
• help: Scales the half voxel SDF expand used by the Global SDF to reconstruct surfaces that are thinner than the distance between two voxels, erring on the side of over-occlusion.

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.LumenScene.GlobalSDF.CoveredExpandSurfaceScale is to scale the half voxel SDF (Signed Distance Field) expansion used by the Global SDF in Unreal Engine 5’s Lumen lighting system. This variable specifically affects the reconstruction of surfaces that are thinner than the distance between two voxels, erring on the side of over-occlusion.

This setting variable is primarily used in the rendering system, specifically within the Global Distance Field component of the Lumen scene rendering pipeline. It is part of the Renderer module in Unreal Engine 5.

The value of this variable is set through the FAutoConsoleVariableRef system, which allows it to be modified at runtime via console commands. Its default value is 1.0f.

This variable interacts closely with other Global SDF-related variables, such as GLumenSceneGlobalSDFNotCoveredExpandSurfaceScale, which handles a similar function for non-covered surfaces.

Developers must be aware that modifying this variable will affect the visual quality and performance of the Global SDF rendering. Increasing the value may improve the representation of thin surfaces but could potentially introduce over-occlusion artifacts.

Best practices when using this variable include:

1. Carefully balancing it with other SDF-related variables for optimal visual results.
2. Testing changes thoroughly in various lighting conditions and with different types of geometry.
3. Being mindful of performance implications when adjusting this value, especially on lower-end hardware.

Regarding the associated variable GLumenSceneGlobalSDFCoveredExpandSurfaceScale:

This is the actual float variable that stores the value set by the console variable. It is used directly in the rendering code to apply the scaling factor to the SDF expansion.

The purpose of GLumenSceneGlobalSDFCoveredExpandSurfaceScale is to provide a quick access point for the scaling factor within the rendering pipeline. It is set to the same value as the console variable and is used in multiple places within the Global Distance Field calculation code.

This variable is primarily used in the SetupGlobalDistanceFieldParameters and SetupGlobalDistanceFieldUniformBufferParameters functions, where it’s assigned to shader parameters. This suggests that the value is passed to GPU shaders for use in real-time rendering calculations.

Developers should be aware that changes to the console variable will be reflected in this associated variable, and thus will directly affect the shader calculations in the Global SDF system.

Best practices for this associated variable include ensuring that any manual modifications to it (if allowed in custom code) are synchronized with the console variable to maintain consistency in 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:215

Scope: file

Source code excerpt:

float GLumenSceneGlobalSDFCoveredExpandSurfaceScale = 1.0f;
FAutoConsoleVariableRef CVarLumenSceneGlobalSDFCoveredExpandSurfaceScale(
	TEXT("r.LumenScene.GlobalSDF.CoveredExpandSurfaceScale"),
	GLumenSceneGlobalSDFCoveredExpandSurfaceScale,
	TEXT("Scales the half voxel SDF expand used by the Global SDF to reconstruct surfaces that are thinner than the distance between two voxels, erring on the side of over-occlusion."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GLumenSceneGlobalSDFNotCoveredExpandSurfaceScale = .6f;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

float GLumenSceneGlobalSDFCoveredExpandSurfaceScale = 1.0f;
FAutoConsoleVariableRef CVarLumenSceneGlobalSDFCoveredExpandSurfaceScale(
	TEXT("r.LumenScene.GlobalSDF.CoveredExpandSurfaceScale"),
	GLumenSceneGlobalSDFCoveredExpandSurfaceScale,
	TEXT("Scales the half voxel SDF expand used by the Global SDF to reconstruct surfaces that are thinner than the distance between two voxels, erring on the side of over-occlusion."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GLumenSceneGlobalSDFNotCoveredExpandSurfaceScale = .6f;
FAutoConsoleVariableRef CVarLumenScenGlobalSDFNotCoveredExpandSurfaceScale(

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

Scope (from outer to inner):

file
function     FGlobalDistanceFieldParameters2 SetupGlobalDistanceFieldParameters

Source code excerpt:

	ShaderParameters.NumGlobalSDFClipmaps = ParameterData.NumGlobalSDFClipmaps;

	ShaderParameters.CoveredExpandSurfaceScale = GLumenSceneGlobalSDFCoveredExpandSurfaceScale;
	ShaderParameters.NotCoveredExpandSurfaceScale = GLumenSceneGlobalSDFNotCoveredExpandSurfaceScale;
	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();

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

Scope (from outer to inner):

file
function     void FViewInfo::SetupGlobalDistanceFieldUniformBufferParameters

Source code excerpt:

	ViewUniformShaderParameters.GlobalDistanceFieldMipTexture = OrBlack3DIfNull(GlobalDistanceFieldInfo.ParameterData.MipTexture);

	ViewUniformShaderParameters.CoveredExpandSurfaceScale = GLumenSceneGlobalSDFCoveredExpandSurfaceScale;
	ViewUniformShaderParameters.NotCoveredExpandSurfaceScale = GLumenSceneGlobalSDFNotCoveredExpandSurfaceScale;
	ViewUniformShaderParameters.NotCoveredMinStepScale = GLumenSceneGlobalSDFNotCoveredMinStepScale;
	ViewUniformShaderParameters.DitheredTransparencyStepThreshold = GLumenSceneGlobalSDFDitheredTransparencyStepThreshold;
	ViewUniformShaderParameters.DitheredTransparencyTraceThreshold = GLumenSceneGlobalSDFDitheredTransparencyTraceThreshold;
}