r.GlobalDistanceField.Debug.ForceMovementUpdate

r.GlobalDistanceField.Debug.ForceMovementUpdate

#Overview

name: r.GlobalDistanceField.Debug.ForceMovementUpdate

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

• type: Var
• help: Whether to force N texel border on X, Y and Z update each frame.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.GlobalDistanceField.Debug.ForceMovementUpdate is to debug and test the Global Distance Field system in Unreal Engine 5’s rendering pipeline. It allows forcing a specific number of texel border updates on X, Y, and Z axes each frame, which can be useful for testing and debugging the Global Distance Field update mechanism.

This setting variable is primarily used by the rendering system, specifically the Global Distance Field subsystem. It is part of the Renderer module in Unreal Engine 5.

The value of this variable is set through the console variable system. It’s defined as an FAutoConsoleVariableRef, which means it can be modified at runtime through console commands or configuration files.

The associated variable GGlobalDistanceFieldDebugForceMovementUpdate interacts directly with this console variable. They share the same value, with the console variable controlling the value of the global variable.

Developers should be aware that:

1. This is a debug feature and should not be enabled in production builds.
2. Forcing movement updates can impact performance, especially if set to a high value.
3. It affects all three axes (X, Y, and Z) equally.

Best practices when using this variable include:

1. Use it only for debugging and testing purposes.
2. Start with small values (e.g., 1 or 2) to observe the effect before increasing.
3. Remember to disable it after debugging to avoid unnecessary performance overhead.
4. Use in conjunction with other Global Distance Field debug tools for comprehensive testing.

Regarding the associated variable GGlobalDistanceFieldDebugForceMovementUpdate:

Its purpose is to store the value set by the console variable in a format accessible to the C++ code. It’s used directly in the Global Distance Field update logic to override the normal movement detection.

This variable is used in the ComputeUpdateRegionsAndUpdateViewState function within the Global Distance Field system. When its value is non-zero, it forces a movement update of the specified magnitude in all directions, regardless of actual camera movement.

Developers should be aware that modifying this variable directly in code is not recommended. Instead, they should use the console variable r.GlobalDistanceField.Debug.ForceMovementUpdate to control its value.

Best practices for this associated variable include:

1. Treat it as read-only in most code contexts.
2. Use it for conditional logic in Global Distance Field update code when debugging.
3. Always check if it’s non-zero before applying forced updates to avoid unnecessary computations.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

int32 GGlobalDistanceFieldDebugForceMovementUpdate = 0;
FAutoConsoleVariableRef CVarGlobalDistanceFieldDebugForceMovementUpdate(
	TEXT("r.GlobalDistanceField.Debug.ForceMovementUpdate"),
	GGlobalDistanceFieldDebugForceMovementUpdate,
	TEXT("Whether to force N texel border on X, Y and Z update each frame."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GGlobalDistanceFieldDebugLogModifiedPrimitives = 0;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

int32 GGlobalDistanceFieldDebugForceMovementUpdate = 0;
FAutoConsoleVariableRef CVarGlobalDistanceFieldDebugForceMovementUpdate(
	TEXT("r.GlobalDistanceField.Debug.ForceMovementUpdate"),
	GGlobalDistanceFieldDebugForceMovementUpdate,
	TEXT("Whether to force N texel border on X, Y and Z update each frame."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GGlobalDistanceFieldDebugLogModifiedPrimitives = 0;
FAutoConsoleVariableRef CVarGlobalDistanceFieldDebugLogModifiedPrimitives(

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

Scope (from outer to inner):

file
function     static void ComputeUpdateRegionsAndUpdateViewState

Source code excerpt:

						FInt64Vector MovementInPages = PageGridCenter - ClipmapViewState.LastPartialUpdateOriginInPages;

						if (GGlobalDistanceFieldDebugForceMovementUpdate != 0)
						{
							MovementInPages = FInt64Vector(GGlobalDistanceFieldDebugForceMovementUpdate, GGlobalDistanceFieldDebugForceMovementUpdate, GGlobalDistanceFieldDebugForceMovementUpdate);
						}

						if (CacheType == GDF_MostlyStatic || !GAOGlobalDistanceFieldCacheMostlyStaticSeparately)
						{
							// Add an update region for each potential axis of camera movement
							AddUpdateBoundsForAxis(MovementInPages, ClipmapBounds, ClipmapPageSize, 0, Clipmap.UpdateBounds);