r.DistanceFields.DefaultVoxelDensity

r.DistanceFields.DefaultVoxelDensity

#Overview

name: r.DistanceFields.DefaultVoxelDensity

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

• type: Var
• help: Determines how the default scale of a mesh converts into distance field voxel dimensions.\nChanging this will cause all distance fields to be rebuilt. Large values can consume memory very quickly!

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.DistanceFields.DefaultVoxelDensity is to determine how the default scale of a mesh converts into distance field voxel dimensions in Unreal Engine 5’s rendering system. This setting variable is crucial for the generation and management of distance fields, which are used in various rendering techniques such as global illumination, ambient occlusion, and soft shadows.

This setting variable is primarily used in the rendering subsystem of Unreal Engine 5, specifically in the distance field generation and management modules. It is referenced in the RendererSettings, DistanceFieldAtlas, and MeshUtilities modules.

The value of this variable is set through the engine’s configuration system. It can be modified in the project settings under the Rendering category, or through the console variable system using the command “r.DistanceFields.DefaultVoxelDensity”.

This variable interacts with other distance field-related variables and systems, such as DistanceFieldResolutionScale and the overall distance field generation process.

Developers must be aware of several important aspects when using this variable:

1. Changing this value will cause all distance fields to be rebuilt, which can be a time-consuming process.
2. Large values can consume memory very quickly, potentially leading to performance issues or out-of-memory errors.
3. Modifying this setting requires restarting the editor for the changes to take effect.

Best practices when using this variable include:

1. Keep the value within the recommended range (0.05 to 0.4) to balance quality and performance.
2. Be cautious when increasing the value, as it can significantly impact memory usage.
3. Consider the target hardware when setting this value, as lower-end devices may struggle with higher voxel densities.
4. Test thoroughly after changing this value to ensure it doesn’t negatively impact performance or visual quality across different scenes and use cases.
5. Document any changes to this variable in your project, as it can have far-reaching effects on the rendering pipeline.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Classes/Engine/RendererSettings.h:567

Scope (from outer to inner):

file
class        class URendererSettings : public UDeveloperSettings

Source code excerpt:

	UPROPERTY(config, EditAnywhere, Category=SoftwareRayTracing, meta=(
		EditCondition = "bGenerateMeshDistanceFields",
		ConsoleVariable="r.DistanceFields.DefaultVoxelDensity",
		ClampMin = ".05", ClampMax = ".4",
		ToolTip="Determines how the default scale of a mesh converts into distance field voxel dimensions. Changing this will cause all distance fields to be rebuilt.  Large values can consume memory very quickly!  Changing this setting requires restarting the editor.",
		ConfigRestartRequired=true))
	float DistanceFieldVoxelDensity;

	UPROPERTY(config, EditAnywhere, Category = Nanite, meta = (

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/DistanceFieldAtlas.cpp:72

Scope: file

Source code excerpt:

static TAutoConsoleVariable<float> CVarDistFieldResScale(
	TEXT("r.DistanceFields.DefaultVoxelDensity"),
	.2f,	
	TEXT("Determines how the default scale of a mesh converts into distance field voxel dimensions.\n")
	TEXT("Changing this will cause all distance fields to be rebuilt.  Large values can consume memory very quickly!"),
	ECVF_ReadOnly);

static int32 GHeightFieldAtlasTileSize = 64;

#Loc: <Workspace>/Engine/Source/Developer/MeshUtilities/Private/MeshDistanceFieldUtilities.cpp:307

Scope (from outer to inner):

file
function     void FMeshUtilities::GenerateSignedDistanceFieldVolumeData

Source code excerpt:

		const int32 MaxNumBlocksOneDim = FMath::Min<int32>(FMath::DivideAndRoundNearest(DistanceFieldResolutionScale <= 1 ? PerMeshMax / 2 : PerMeshMax, DistanceField::UniqueDataBrickSize), DistanceField::MaxIndirectionDimension - 1);

		static const auto CVarDensity = IConsoleManager::Get().FindTConsoleVariableDataFloat(TEXT("r.DistanceFields.DefaultVoxelDensity"));
		const float VoxelDensity = CVarDensity->GetValueOnAnyThread();

		const float NumVoxelsPerLocalSpaceUnit = VoxelDensity * DistanceFieldResolutionScale;
		FBox3f LocalSpaceMeshBounds(Bounds.GetBox());

		// Make sure the mesh bounding box has positive extents to handle planes

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/DistanceFieldAtlas.cpp:136

Scope (from outer to inner):

file
function     FString BuildDistanceFieldDerivedDataKey

Source code excerpt:

	const FString PerMeshMaxString = PerMeshMax == 128 ? TEXT("") : FString::Printf(TEXT("_%u"), PerMeshMax);

	static const auto CVarDensity = IConsoleManager::Get().FindTConsoleVariableDataFloat(TEXT("r.DistanceFields.DefaultVoxelDensity"));
	const float VoxelDensity = CVarDensity->GetValueOnAnyThread();
	const FString VoxelDensityString = VoxelDensity == .1f ? TEXT("") : FString::Printf(TEXT("_%.3f"), VoxelDensity);

	static UE::DerivedData::FCacheBucket LegacyBucket(TEXTVIEW("LegacyDIST"), TEXTVIEW("DistanceField"));
	return FDerivedDataCacheInterface::BuildCacheKey(
		TEXT("DIST"),