r.DistanceFields.BrickAtlasMaxSizeZ

r.DistanceFields.BrickAtlasMaxSizeZ

#Overview

name: r.DistanceFields.BrickAtlasMaxSizeZ

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

• type: Var
• help: Target for maximum depth of the Mesh Distance Field atlas, in 8^3 bricks. 32 => 128 * 128 * 32 * 8^3 = 256Mb. Actual atlas size can go over since mip2 is always loaded.

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.DistanceFields.BrickAtlasMaxSizeZ is to set the target maximum depth of the Mesh Distance Field atlas in 8^3 bricks. This setting is primarily used for the rendering system, specifically for distance field-related operations.

• This setting variable is mainly used in the Renderer module of Unreal Engine 5, particularly in the distance field streaming system.

• The value of this variable is set as a console variable with a default value of 32. It can be changed at runtime through the console or configuration files.

• This variable interacts closely with CVarMaxAtlasDepthInBricks, which is an associated variable that shares the same value. It’s also used in conjunction with other distance field-related variables like CVarBrickAtlasMaxSizeXYInBricks.

• Developers should be aware that this setting directly impacts the memory usage of the distance field atlas. The default value of 32 results in an atlas size of approximately 256MB (128 * 128 * 32 * 8^3).

• Best practices when using this variable include:

  1. Adjusting it based on the project’s specific needs and available memory.
  2. Monitoring performance and memory usage when changing this value.
  3. Considering the trade-off between atlas size and rendering quality/performance.

Regarding the associated variable CVarMaxAtlasDepthInBricks:

• Its purpose is the same as r.DistanceFields.BrickAtlasMaxSizeZ, serving as the C++ representation of the console variable.

• It’s used in the Renderer module, specifically in the DistanceFieldStreaming.cpp file.

• Its value is set by the console variable r.DistanceFields.BrickAtlasMaxSizeZ.

• This variable is used in several key functions related to distance field streaming and atlas management, such as processing streaming requests, resizing the brick atlas, and listing mesh distance fields.

• Developers should be aware that this variable directly affects the memory allocation and management of the distance field atlas.

• Best practices include using this variable for runtime checks and calculations related to the distance field atlas size and capacity.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DistanceFieldStreaming.cpp:35

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarMaxAtlasDepthInBricks(
	TEXT("r.DistanceFields.BrickAtlasMaxSizeZ"),
	32,	
	TEXT("Target for maximum depth of the Mesh Distance Field atlas, in 8^3 bricks.  32 => 128 * 128 * 32 * 8^3 = 256Mb.  Actual atlas size can go over since mip2 is always loaded."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarTextureUploadLimitKBytes(
	TEXT("r.DistanceFields.TextureUploadLimitKBytes"),

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DistanceFieldStreaming.cpp:34

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe | ECVF_ReadOnly);

static TAutoConsoleVariable<int32> CVarMaxAtlasDepthInBricks(
	TEXT("r.DistanceFields.BrickAtlasMaxSizeZ"),
	32,	
	TEXT("Target for maximum depth of the Mesh Distance Field atlas, in 8^3 bricks.  32 => 128 * 128 * 32 * 8^3 = 256Mb.  Actual atlas size can go over since mip2 is always loaded."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarTextureUploadLimitKBytes(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DistanceFieldStreaming.cpp:802

Scope (from outer to inner):

file
function     void FDistanceFieldSceneData::ProcessStreamingRequestsFromGPU

Source code excerpt:

	const int32 BrickAtlasSizeXYInBricks = CVarBrickAtlasSizeXYInBricks.GetValueOnRenderThread();
	const int32 NumBricksBeforeDroppingMips = FMath::Max((CVarMaxAtlasDepthInBricks.GetValueOnRenderThread() - 1) * BrickAtlasSizeXYInBricks * BrickAtlasSizeXYInBricks, 0);
	int32 NumAllocatedDistanceFieldBricks = DistanceFieldAtlasBlockAllocator.GetAllocatedSize() * GDistanceFieldBlockAllocatorSizeInBricks;

	for (const FDistanceFieldReadRequest& ReadRequest : ReadRequests)
	{
		// Account for size that will be added when all async read requests complete
		NumAllocatedDistanceFieldBricks += ReadRequest.NumDistanceFieldBricks;

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DistanceFieldStreaming.cpp:992

Scope (from outer to inner):

file
function     FRDGTexture* FDistanceFieldSceneData::ResizeBrickAtlasIfNeeded

Source code excerpt:

	int32 DesiredZSizeInBricks = FMath::DivideAndRoundUp(DistanceFieldAtlasBlockAllocator.GetMaxSize() * GDistanceFieldBlockAllocatorSizeInBricks, BrickAtlasSizeXYInBricks * BrickAtlasSizeXYInBricks);

	if (DesiredZSizeInBricks <= CVarMaxAtlasDepthInBricks.GetValueOnRenderThread())
	{
		DesiredZSizeInBricks = FMath::RoundUpToPowerOfTwo(DesiredZSizeInBricks);
	}
	else
	{
		DesiredZSizeInBricks = FMath::DivideAndRoundUp(DesiredZSizeInBricks, 4) * 4;

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DistanceFieldStreaming.cpp:1761

Scope (from outer to inner):

file
function     void FDistanceFieldSceneData::ListMeshDistanceFields

Source code excerpt:

	const SIZE_T IndirectionTextureBytes = IndirectionAtlasSize.X * IndirectionAtlasSize.Y * IndirectionAtlasSize.Z * GPixelFormats[PF_A2B10G10R10].BlockBytes;
	const int32 BrickAtlasSizeXYInBricks = CVarBrickAtlasSizeXYInBricks.GetValueOnRenderThread();
	const float MaxAtlasSizeMb = CVarMaxAtlasDepthInBricks.GetValueOnRenderThread() * BrickAtlasSizeXYInBricks * BrickAtlasSizeXYInBricks * BrickSizeBytes / 1024.0f / 1024.0f;

	UE_LOG(LogDistanceField, Log,
		TEXT("Mesh Distance Field Atlas %ux%ux%u = %.1fMb (%.1fMb target max), with %.1fMb free, %.1fMb block allocator waste, Indirection Table %.1fMb, Indirection Texture %.1fMb"), 
		AtlasDimensions.X,
		AtlasDimensions.Y,
		AtlasDimensions.Z,