r.DistanceFields.DefragmentIndirectionAtlas

r.DistanceFields.DefragmentIndirectionAtlas

#Overview

name: r.DistanceFields.DefragmentIndirectionAtlas

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

• type: Var
• help: Whether to defragment the Distance Field indirection atlas when it requires resizing.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.DistanceFields.DefragmentIndirectionAtlas is to control whether the Distance Field indirection atlas should be defragmented when it requires resizing. This setting is part of Unreal Engine’s rendering system, specifically related to the Distance Field feature.

The Unreal Engine subsystem that relies on this setting variable is the Renderer module, as evidenced by its location in the DistanceFieldStreaming.cpp file within the Renderer/Private directory.

The value of this variable is set using a console variable (CVar) system. It is initialized with a default value of 1, meaning defragmentation is enabled by default. Developers can change this value at runtime using console commands or through configuration files.

This variable interacts with the associated variable CVarDefragmentIndirectionAtlas. They share the same value and purpose, with CVarDefragmentIndirectionAtlas being the actual TAutoConsoleVariable instance used in the code.

Developers must be aware that this variable affects the performance and memory usage of the Distance Field system. Enabling defragmentation (value 1) can help optimize memory usage but may introduce some overhead during the resizing process.

Best practices when using this variable include:

1. Keep it enabled (value 1) for most production scenarios to maintain optimal memory usage.
2. Consider disabling it (value 0) temporarily for debugging or if experiencing performance issues specifically related to Distance Field atlas resizing.
3. Monitor performance metrics when changing this value to ensure it doesn’t negatively impact your specific use case.

Regarding the associated variable CVarDefragmentIndirectionAtlas:

The purpose of CVarDefragmentIndirectionAtlas is the same as r.DistanceFields.DefragmentIndirectionAtlas. It is the actual console variable instance used in the code to control the defragmentation behavior of the Distance Field indirection atlas.

This variable is used directly in the Renderer module, specifically in the FDistanceFieldSceneData::ResizeIndirectionAtlasIfNeeded function. It determines whether defragmentation should occur when the indirection atlas needs resizing.

The value of CVarDefragmentIndirectionAtlas is set through the console variable system and can be accessed using the GetValueOnRenderThread() method.

Developers should be aware that this variable is marked as ECVF_RenderThreadSafe, meaning it can be safely accessed from the render thread. However, changes to this variable will only take effect on the render thread, which may not be immediate depending on the current execution context.

Best practices for using CVarDefragmentIndirectionAtlas include:

1. Use GetValueOnRenderThread() when accessing the value to ensure thread-safe behavior.
2. Consider the performance implications of enabling or disabling defragmentation in your specific use case.
3. Use this variable in conjunction with other Distance Field-related settings to fine-tune the rendering performance and memory usage of your project.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarDefragmentIndirectionAtlas(
	TEXT("r.DistanceFields.DefragmentIndirectionAtlas"),
	1,
	TEXT("Whether to defragment the Distance Field indirection atlas when it requires resizing."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarResizeAtlasEveryFrame(
	TEXT("r.DistanceFields.Debug.ResizeAtlasEveryFrame"),

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe | ECVF_ReadOnly);

static TAutoConsoleVariable<int32> CVarDefragmentIndirectionAtlas(
	TEXT("r.DistanceFields.DefragmentIndirectionAtlas"),
	1,
	TEXT("Whether to defragment the Distance Field indirection atlas when it requires resizing."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarResizeAtlasEveryFrame(

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

Scope (from outer to inner):

file
function     bool FDistanceFieldSceneData::ResizeIndirectionAtlasIfNeeded

Source code excerpt:

	const FIntVector CurrentSize = IndirectionAtlas ? IndirectionAtlas->GetDesc().GetSize() : FIntVector::ZeroValue;
	FIntVector DesiredSize = CalculateDesiredSize(CurrentSize, IndirectionAtlasLayout.GetSize());
	const bool bDefragment = (CurrentSize != DesiredSize) && CVarDefragmentIndirectionAtlas.GetValueOnRenderThread() != 0;
	TArray<FDistanceFieldAssetMipRelocation> Relocations;

	if (bDefragment)
	{
		CSV_EVENT(DistanceField, TEXT("DefragmentIndirectionAtlas"));