r.DistanceFields.BrickAtlasSizeXYInBricks

r.DistanceFields.BrickAtlasSizeXYInBricks

#Overview

name: r.DistanceFields.BrickAtlasSizeXYInBricks

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

• type: Var
• help: Controls the allocation granularity of the atlas, which grows in Z.

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.DistanceFields.BrickAtlasSizeXYInBricks is to control the allocation granularity of the distance field atlas in Unreal Engine 5’s rendering system. This setting specifically affects the X and Y dimensions of the brick atlas used for distance field calculations.

This setting variable is primarily used in the rendering subsystem of Unreal Engine 5, specifically in the distance field streaming and management module. Based on the callsites, it’s clear that this variable is crucial for the Distance Field Streaming component of the renderer.

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

This variable interacts closely with other distance field-related variables, particularly CVarMaxAtlasDepthInBricks (r.DistanceFields.BrickAtlasMaxSizeZ). Together, these variables define the three-dimensional structure of the distance field atlas.

Developers must be aware that this variable directly impacts the memory usage and performance of distance field calculations. A larger value will increase the granularity of the atlas, potentially improving quality but at the cost of higher memory usage.

Best practices when using this variable include:

1. Balancing between quality and performance based on target hardware capabilities.
2. Considering the relationship between this variable and CVarMaxAtlasDepthInBricks to optimize the overall atlas size.
3. Monitoring performance and memory usage when adjusting this value.

Regarding the associated variable CVarBrickAtlasSizeXYInBricks:

The purpose of CVarBrickAtlasSizeXYInBricks is to provide a programmatic way to access and modify the r.DistanceFields.BrickAtlasSizeXYInBricks setting within the C++ code of the engine.

This variable is used in the same subsystem (rendering, specifically distance field streaming) as r.DistanceFields.BrickAtlasSizeXYInBricks.

The value of CVarBrickAtlasSizeXYInBricks is set when the console variable r.DistanceFields.BrickAtlasSizeXYInBricks is initialized.

It interacts directly with r.DistanceFields.BrickAtlasSizeXYInBricks, essentially serving as its in-code representation.

Developers should be aware that changes to r.DistanceFields.BrickAtlasSizeXYInBricks will be reflected in CVarBrickAtlasSizeXYInBricks, and vice versa.

Best practices include using CVarBrickAtlasSizeXYInBricks.GetValueOnRenderThread() to safely access the current value of this setting in render thread code, as demonstrated in the provided code snippets.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarBrickAtlasSizeXYInBricks(
	TEXT("r.DistanceFields.BrickAtlasSizeXYInBricks"),
	128,	
	TEXT("Controls the allocation granularity of the atlas, which grows in Z."),
	ECVF_RenderThreadSafe | ECVF_ReadOnly);

static TAutoConsoleVariable<int32> CVarMaxAtlasDepthInBricks(
	TEXT("r.DistanceFields.BrickAtlasMaxSizeZ"),

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

extern int32 GDFReverseAtlasAllocationOrder;

static TAutoConsoleVariable<int32> CVarBrickAtlasSizeXYInBricks(
	TEXT("r.DistanceFields.BrickAtlasSizeXYInBricks"),
	128,	
	TEXT("Controls the allocation granularity of the atlas, which grows in Z."),
	ECVF_RenderThreadSafe | ECVF_ReadOnly);

static TAutoConsoleVariable<int32> CVarMaxAtlasDepthInBricks(

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

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

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

Scope (from outer to inner):

file
function     FRDGTexture* FDistanceFieldSceneData::ResizeBrickAtlasIfNeeded

Source code excerpt:

	check(GraphBuilder.RHICmdList.GetGPUMask() == FRHIGPUMask::All());

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

	if (DesiredZSizeInBricks <= CVarMaxAtlasDepthInBricks.GetValueOnRenderThread())
	{
		DesiredZSizeInBricks = FMath::RoundUpToPowerOfTwo(DesiredZSizeInBricks);
	}

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

Scope (from outer to inner):

file
function     void FDistanceFieldSceneData::ListMeshDistanceFields

Source code excerpt:

	const FIntVector IndirectionAtlasSize = IndirectionAtlas ? IndirectionAtlas->GetDesc().GetSize() : FIntVector::ZeroValue;
	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,