r.DistanceFields.SurfaceBiasExpand

r.DistanceFields.SurfaceBiasExpand

#Overview

name: r.DistanceFields.SurfaceBiasExpand

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

• type: Var
• help: Fraction of a Mesh SDF voxel to expand the surface during intersection. Expanding the surface improves representation quality, at the cost of over-occlusion.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.DistanceFields.SurfaceBiasExpand is to control the expansion of the surface during intersection in Mesh Signed Distance Field (SDF) calculations. This setting is part of Unreal Engine’s rendering system, specifically the distance field rendering subsystem.

This setting variable is primarily used in the Renderer module of Unreal Engine 5, as evidenced by its location in the DistanceFieldObjectManagement.cpp file.

The value of this variable is set through the console variable system. It’s initialized with a default value of 0.25f and can be modified at runtime using console commands.

The variable interacts directly with GMeshSDFSurfaceBiasExpand, which is the associated C++ variable that stores the actual value. When r.DistanceFields.SurfaceBiasExpand is modified, GMeshSDFSurfaceBiasExpand is updated accordingly.

Developers must be aware that changing this variable affects the quality of the distance field representation and the level of occlusion. Increasing the value improves representation quality but may lead to over-occlusion.

Best practices when using this variable include:

1. Adjusting it carefully to balance between representation quality and occlusion.
2. Testing changes in various lighting conditions to ensure optimal results.
3. Being aware that changes to this variable will trigger a recreation of render states for affected components.

Regarding the associated variable GMeshSDFSurfaceBiasExpand:

The purpose of GMeshSDFSurfaceBiasExpand is to store the actual value of the surface bias expansion for Mesh SDF calculations. It’s directly linked to the console variable r.DistanceFields.SurfaceBiasExpand.

This variable is used in the Renderer module, specifically in distance field calculations and object management.

The value of GMeshSDFSurfaceBiasExpand is set initially to 0.25f and can be modified through the associated console variable.

GMeshSDFSurfaceBiasExpand interacts directly with r.DistanceFields.SurfaceBiasExpand. When the console variable is changed, GMeshSDFSurfaceBiasExpand is updated to reflect the new value.

Developers should be aware that this variable is used in critical rendering calculations, specifically in determining the expansion of the surface distance in Mesh SDF computations.

Best practices include:

1. Avoid directly modifying GMeshSDFSurfaceBiasExpand in code; instead, use the console variable for adjustments.
2. Consider the performance implications of changes, as they affect distance field calculations.
3. Monitor the effects of changes on both representation quality and occlusion in various scenarios.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DistanceFieldObjectManagement.cpp:57

Scope: file

Source code excerpt:

float GMeshSDFSurfaceBiasExpand = .25f;
FAutoConsoleVariableRef CVarMeshSDFSurfaceBiasExpand(
	TEXT("r.DistanceFields.SurfaceBiasExpand"),
	GMeshSDFSurfaceBiasExpand,
	TEXT("Fraction of a Mesh SDF voxel to expand the surface during intersection.  Expanding the surface improves representation quality, at the cost of over-occlusion."),
	FConsoleVariableDelegate::CreateLambda([](IConsoleVariable* InVariable)
	{
		FGlobalComponentRecreateRenderStateContext Context;
	}),

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DistanceFieldObjectManagement.cpp:55

Scope: file

Source code excerpt:

);

float GMeshSDFSurfaceBiasExpand = .25f;
FAutoConsoleVariableRef CVarMeshSDFSurfaceBiasExpand(
	TEXT("r.DistanceFields.SurfaceBiasExpand"),
	GMeshSDFSurfaceBiasExpand,
	TEXT("Fraction of a Mesh SDF voxel to expand the surface during intersection.  Expanding the surface improves representation quality, at the cost of over-occlusion."),
	FConsoleVariableDelegate::CreateLambda([](IConsoleVariable* InVariable)
	{
		FGlobalComponentRecreateRenderStateContext Context;
	}),
	ECVF_RenderThreadSafe

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DistanceFieldObjectManagement.cpp:659

Scope (from outer to inner):

file
lambda-function

Source code excerpt:

								// Minimal surface bias which increases chance that ray hit will a surface located between two texels
								float ExpandSurfaceDistance = (GMeshSDFSurfaceBiasExpand * VolumePositionExtent / FVector3f(DistanceFieldData->Mips[0].IndirectionDimensions * DistanceField::UniqueDataBrickSize)).Size();

								const float WSign = DistanceFieldData->bMostlyTwoSided ? -1 : 1;
								UploadObjectData[4] = FVector4f(VolumePositionExtent, WSign * ExpandSurfaceDistance);

								const int32 PrimIdx = PrimAndInst.Primitive->GetIndex();
								const FPrimitiveBounds& PrimBounds = PrimitiveBounds[PrimIdx];