r.DistanceFields.MaxPerMeshResolution

r.DistanceFields.MaxPerMeshResolution

#Overview

name: r.DistanceFields.MaxPerMeshResolution

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

• type: Var
• help: Highest resolution (in one dimension) allowed for a single static mesh asset, used to cap the memory usage of meshes with a large scale.\nChanging this will cause all distance fields to be rebuilt. Large values such as 512 can consume memory very quickly! (64Mb for one asset at 512)

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.DistanceFields.MaxPerMeshResolution is to set the highest resolution (in one dimension) allowed for a single static mesh asset’s distance field. This setting is used to cap the memory usage of meshes with a large scale.

This setting variable is primarily used in the Unreal Engine’s rendering system, specifically for the distance field generation and management. It’s referenced in the Engine module and the MeshUtilities module.

The value of this variable is set through a console variable (CVar) system, which allows it to be changed at runtime or through configuration files. It’s defined with a default value of 256, but can be modified.

This variable interacts with other distance field-related variables, such as r.DistanceFields.DefaultVoxelDensity, which affects the density of voxels in the distance field.

Developers must be aware that:

1. Changing this value will cause all distance fields to be rebuilt.
2. Large values (such as 512) can consume memory very quickly, with one asset potentially using up to 64MB at a resolution of 512.
3. This setting affects the trade-off between distance field quality and memory usage.

Best practices when using this variable include:

1. Choose a value that balances memory usage with the desired distance field quality for your project.
2. Be cautious when increasing this value, as it can significantly impact memory usage.
3. Consider the target hardware when setting this value, especially for projects targeting lower-end devices.
4. Use in conjunction with other distance field settings like voxel density for optimal results.
5. Monitor performance and memory usage when adjusting this value, especially in large scenes with many static meshes.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarDistFieldRes(
	TEXT("r.DistanceFields.MaxPerMeshResolution"),
	256,	
	TEXT("Highest resolution (in one dimension) allowed for a single static mesh asset, used to cap the memory usage of meshes with a large scale.\n")
	TEXT("Changing this will cause all distance fields to be rebuilt.  Large values such as 512 can consume memory very quickly! (64Mb for one asset at 512)"),
	ECVF_ReadOnly);

static TAutoConsoleVariable<float> CVarDistFieldResScale(

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

Scope (from outer to inner):

file
function     void FMeshUtilities::GenerateSignedDistanceFieldVolumeData

Source code excerpt:

		}

		static const auto CVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.DistanceFields.MaxPerMeshResolution"));
		const int32 PerMeshMax = CVar->GetValueOnAnyThread();

		// Meshes with explicit artist-specified scale can go higher
		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"));

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

Scope (from outer to inner):

file
function     FString BuildDistanceFieldDerivedDataKey

Source code excerpt:

FString BuildDistanceFieldDerivedDataKey(const FString& InMeshKey)
{
	static const auto CVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.DistanceFields.MaxPerMeshResolution"));
	const int32 PerMeshMax = CVar->GetValueOnAnyThread();
	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);