r.DistanceFields.ReverseAtlasAllocationOrder

r.DistanceFields.ReverseAtlasAllocationOrder

#Overview

name: r.DistanceFields.ReverseAtlasAllocationOrder

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

• type: Var
• help: ``

It is referenced in 6 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.DistanceFields.ReverseAtlasAllocationOrder is to control the order of allocation in the distance field atlas. This setting is part of Unreal Engine’s rendering system, specifically related to distance field management.

This setting variable is primarily used in the Renderer module of Unreal Engine 5. It’s referenced in the DistanceFieldObjectManagement and DistanceFieldStreaming components of the rendering system.

The value of this variable is set through the console variable system. It’s associated with the C++ variable GDFReverseAtlasAllocationOrder, which shares the same value.

The variable interacts with other distance field-related systems, particularly in the process of updating distance field object buffers and the distance field atlas. It affects the order in which elements are added to the atlas, which can impact rendering performance and memory usage.

Developers should be aware that changing this variable triggers a recreation of render states for global components. This is evident from the console variable delegate that creates an FGlobalComponentRecreateRenderStateContext when the value changes.

Best practices when using this variable include:

1. Be cautious when changing its value, as it affects rendering performance.
2. Monitor performance metrics when adjusting this setting to ensure optimal results.
3. Consider the impact on memory usage and allocation patterns when modifying this value.

Regarding the associated variable GDFReverseAtlasAllocationOrder:

The purpose of GDFReverseAtlasAllocationOrder is to serve as the C++ representation of the r.DistanceFields.ReverseAtlasAllocationOrder console variable. It directly controls the behavior of distance field atlas allocation in the engine’s rendering code.

This variable is used in the Renderer module, specifically in the distance field management and streaming systems.

Its value is set by the console variable system and can be modified at runtime.

GDFReverseAtlasAllocationOrder interacts with GDFPreviousReverseAtlasAllocationOrder to track changes in the allocation order between updates.

Developers should be aware that this variable directly affects the rendering pipeline and should be modified with caution.

Best practices for using GDFReverseAtlasAllocationOrder include:

1. Use it in conjunction with performance profiling tools to optimize distance field rendering.
2. Consider its impact on both CPU and GPU performance when adjusting its value.
3. Be mindful of its effects on memory usage and allocation patterns in the distance field atlas.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

int32 GDFReverseAtlasAllocationOrder = 0;
FAutoConsoleVariableRef CVarDFReverseAtlasAllocationOrder(
	TEXT("r.DistanceFields.ReverseAtlasAllocationOrder"),
	GDFReverseAtlasAllocationOrder,
	TEXT(""),
	FConsoleVariableDelegate::CreateLambda([](IConsoleVariable* InVariable)
	{
		FGlobalComponentRecreateRenderStateContext Context;
	}),

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

int32 GDFReverseAtlasAllocationOrder = 0;
FAutoConsoleVariableRef CVarDFReverseAtlasAllocationOrder(
	TEXT("r.DistanceFields.ReverseAtlasAllocationOrder"),
	GDFReverseAtlasAllocationOrder,
	TEXT(""),
	FConsoleVariableDelegate::CreateLambda([](IConsoleVariable* InVariable)
	{
		FGlobalComponentRecreateRenderStateContext Context;
	}),
	ECVF_RenderThreadSafe

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

Scope (from outer to inner):

file
function     void FDistanceFieldSceneData::UpdateDistanceFieldObjectBuffers

Source code excerpt:

		ProcessDistanceFieldObjectRemoves(*this, DistanceFieldAssetRemoves);

		if ((PendingAddOperations.Num() > 0 || PendingUpdateOperations.Num() > 0) && GDFReverseAtlasAllocationOrder == GDFPreviousReverseAtlasAllocationOrder)
		{
			TArray<FMatrix> InstanceLocalToPrimitiveTransforms;
			int32 OriginalNumObjects = NumObjectsInBuffer;
			for (FPrimitiveSceneInfo* PrimitiveSceneInfo : PendingAddOperations)
			{
				ProcessPrimitiveUpdate(

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

Scope (from outer to inner):

file
function     void FDistanceFieldSceneData::UpdateDistanceFieldObjectBuffers

Source code excerpt:

		}

		GDFPreviousReverseAtlasAllocationOrder = GDFReverseAtlasAllocationOrder;

		// Upload buffer changes
		if (HasPendingUploads())
		{
			QUICK_SCOPE_CYCLE_COUNTER(STAT_UploadDistanceFieldObjectDataAndBounds);

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

Scope: file

Source code excerpt:

CSV_DEFINE_CATEGORY(DistanceField, true);

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);

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

Scope (from outer to inner):

file
function     void FDistanceFieldSceneData::UpdateDistanceFieldAtlas

Source code excerpt:

	for (int32 MipAddIndex = 0; MipAddIndex < DistanceFieldAssetMipAdds.Num(); MipAddIndex++)
	{
		const int32 Index = GDFReverseAtlasAllocationOrder ? DistanceFieldAssetMipAdds.Num() - MipAddIndex - 1 : MipAddIndex;
		FSetElementId AssetSetId = DistanceFieldAssetMipAdds[Index].AssetId;
		FDistanceFieldAssetState& AssetState = AssetStateArray[AssetSetId];

		const int32 ReversedMipIndex = DistanceFieldAssetMipAdds[Index].ReversedMipIndex;

		// Shader requires sequential reversed mips starting from 0