r.AOGlobalDistanceFieldForceUpdateOnce

r.AOGlobalDistanceFieldForceUpdateOnce

#Overview

name: r.AOGlobalDistanceFieldForceUpdateOnce

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

• type: Var
• help: Whether to force full global distance field once.

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.AOGlobalDistanceFieldForceUpdateOnce is to force a full update of the global distance field once. This setting is part of the rendering system, specifically related to Ambient Occlusion (AO) and global distance field calculations.

This setting variable is primarily used in the Renderer module of Unreal Engine 5, as evident from its location in the GlobalDistanceField.cpp file within the Runtime/Renderer directory.

The value of this variable is set through a console variable (cvar) system, allowing it to be changed at runtime. It’s initialized to 0 and can be modified using the console command “r.AOGlobalDistanceFieldForceUpdateOnce”.

The associated variable GAOGlobalDistanceFieldForceUpdateOnce directly interacts with this setting. They share the same value and purpose.

Developers should be aware that:

1. This variable is intended for one-time use. After forcing an update, it’s automatically reset to 0.
2. It’s part of the scalability settings and is render thread safe.
3. Using this variable will cause a full update of the global distance field, which can be computationally expensive.

Best practices when using this variable include:

1. Use it sparingly, only when a full update of the global distance field is necessary.
2. Be aware of the performance impact, especially on lower-end hardware.
3. Consider using it for debugging or specific scenarios where you need to ensure the global distance field is fully up-to-date.

Regarding the associated variable GAOGlobalDistanceFieldForceUpdateOnce:

• Its purpose is identical to r.AOGlobalDistanceFieldForceUpdateOnce.
• It’s used internally in the renderer code to check if a full update of the global distance field is required.
• The value is set through the console variable system and is reset to 0 after use.
• Developers should treat it as a read-only variable in their code, as its value is managed by the engine.
• Best practice is to use the console command to modify this value rather than changing it directly in code.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/GlobalDistanceField.cpp:103

Scope: file

Source code excerpt:

int32 GAOGlobalDistanceFieldForceUpdateOnce = 0;
FAutoConsoleVariableRef CVarAOGlobalDistanceFieldForceUpdateOnce(
	TEXT("r.AOGlobalDistanceFieldForceUpdateOnce"),
	GAOGlobalDistanceFieldForceUpdateOnce,
	TEXT("Whether to force full global distance field once."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GAOGlobalDFClipmapDistanceExponent = 2;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/GlobalDistanceField.cpp:101

Scope: file

Source code excerpt:

);

int32 GAOGlobalDistanceFieldForceUpdateOnce = 0;
FAutoConsoleVariableRef CVarAOGlobalDistanceFieldForceUpdateOnce(
	TEXT("r.AOGlobalDistanceFieldForceUpdateOnce"),
	GAOGlobalDistanceFieldForceUpdateOnce,
	TEXT("Whether to force full global distance field once."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GAOGlobalDFClipmapDistanceExponent = 2;
FAutoConsoleVariableRef CVarAOGlobalDFClipmapDistanceExponent(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/GlobalDistanceField.cpp:1090

Scope (from outer to inner):

file
function     static void ComputeUpdateRegionsAndUpdateViewState

Source code excerpt:

				|| ClipmapViewState.LastUsedSceneDataForFullUpdate != &Scene->DistanceFieldSceneData
				|| GAOGlobalDistanceFieldForceFullUpdate
				|| GAOGlobalDistanceFieldForceUpdateOnce
				|| GDFReadbackRequest != nullptr;

			const bool bUpdateRequested = GAOUpdateGlobalDistanceField != 0 && ShouldUpdateClipmapThisFrame(ClipmapIndex, NumClipmaps, GlobalDistanceFieldData.UpdateIndex);

			if (bUpdateRequested && !bUpdatedThisFrame)
			{

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/GlobalDistanceField.cpp:1258

Scope (from outer to inner):

file
function     static void ComputeUpdateRegionsAndUpdateViewState

Source code excerpt:

			ClipmapViewState.CacheMostlyStaticSeparately = GAOGlobalDistanceFieldCacheMostlyStaticSeparately;
		}
		GAOGlobalDistanceFieldForceUpdateOnce = 0;

		ensureMsgf(!GAOGlobalDistanceFieldStaggeredUpdates || NumClipmapUpdateRequests <= GetNumClipmapUpdatesPerFrame(), TEXT("ShouldUpdateClipmapThisFrame needs to be adjusted for the NumClipmaps to even out the work distribution"));
	}
	else
	{
		for (int32 ClipmapIndex = 0; ClipmapIndex < NumClipmaps; ClipmapIndex++)