r.AOGlobalDistanceFieldStaggeredUpdates

r.AOGlobalDistanceFieldStaggeredUpdates

#Overview

name: r.AOGlobalDistanceFieldStaggeredUpdates

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.AOGlobalDistanceFieldStaggeredUpdates is to control whether larger clipmaps in the global distance field can be updated less frequently. 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 evidenced by its location in the GlobalDistanceField.cpp file.

The value of this variable is set through the console variable system, allowing it to be changed at runtime. It is initialized with a default value of 1 (true).

The associated variable GAOGlobalDistanceFieldStaggeredUpdates interacts directly with r.AOGlobalDistanceFieldStaggeredUpdates, sharing the same value. This variable is used in the C++ code to control the behavior of global distance field updates.

Developers should be aware that:

  1. This setting affects the update frequency of larger clipmaps in the global distance field.
  2. It can impact performance and visual quality, as less frequent updates may save performance at the cost of potentially outdated distance field information.
  3. The setting is marked with ECVF_Scalability, indicating it’s intended to be used for performance scaling.

Best practices when using this variable include:

  1. Consider the trade-off between performance and visual quality when enabling or disabling staggered updates.
  2. Test the impact of this setting in various scenarios to determine the optimal configuration for your project.
  3. Be mindful of how this setting interacts with other global distance field-related settings.

Regarding the associated variable GAOGlobalDistanceFieldStaggeredUpdates:

The purpose of GAOGlobalDistanceFieldStaggeredUpdates is to provide a C++ accessible way to control the staggered update behavior of the global distance field clipmaps.

This variable is used within the Renderer module to determine how many clipmap updates should occur per frame and to calculate update frequencies for individual clipmaps.

The value of this variable is set by the console variable system, mirroring the value of r.AOGlobalDistanceFieldStaggeredUpdates.

It interacts with other variables like GAOGlobalDistanceFieldClipmapUpdatesPerFrame to control the update behavior of the global distance field.

Developers should be aware that:

  1. This variable directly affects the logic for updating clipmaps in the global distance field system.
  2. Changes to this variable will impact performance and potentially visual quality of ambient occlusion and other effects that rely on the global distance field.

Best practices when using this variable include:

  1. Use it in conjunction with r.AOGlobalDistanceFieldStaggeredUpdates rather than modifying it directly.
  2. Consider the impact on both performance and visual quality when adjusting this setting.
  3. Test thoroughly in various scenarios to ensure the desired balance between performance and quality is achieved.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

int32 GAOGlobalDistanceFieldStaggeredUpdates = 1;
FAutoConsoleVariableRef CVarAOGlobalDistanceFieldStaggeredUpdatess(
	TEXT("r.AOGlobalDistanceFieldStaggeredUpdates"),
	GAOGlobalDistanceFieldStaggeredUpdates,
	TEXT("Whether to allow the larger clipmaps to be updated less frequently."),
	ECVF_Scalability | ECVF_RenderThreadSafe
	);

int32 GAOGlobalDistanceFieldClipmapUpdatesPerFrame = 2;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	);

int32 GAOGlobalDistanceFieldStaggeredUpdates = 1;
FAutoConsoleVariableRef CVarAOGlobalDistanceFieldStaggeredUpdatess(
	TEXT("r.AOGlobalDistanceFieldStaggeredUpdates"),
	GAOGlobalDistanceFieldStaggeredUpdates,
	TEXT("Whether to allow the larger clipmaps to be updated less frequently."),
	ECVF_Scalability | ECVF_RenderThreadSafe
	);

int32 GAOGlobalDistanceFieldClipmapUpdatesPerFrame = 2;
FAutoConsoleVariableRef CVarAOGlobalDistanceFieldClipmapUpdatesPerFrame(

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

Scope (from outer to inner):

file
function     static void GetUpdateFrequencyForClipmap

Source code excerpt:

static void GetUpdateFrequencyForClipmap(int32 ClipmapIndex, int32 NumClipmaps, int32& OutFrequency, int32& OutPhase)
{
	const int32 NumClipmapUpdatesPerFrame = GAOGlobalDistanceFieldStaggeredUpdates ? FMath::Min(GetNumClipmapUpdatesPerFrame(), NumClipmaps) : NumClipmaps;

	if (ClipmapIndex < NumClipmapUpdatesPerFrame - 1)
	{
		// update the first N-1 clipmaps every frame
		OutFrequency = 1;
		OutPhase = 0;

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

Scope (from outer to inner):

file
function     static void ComputeUpdateRegionsAndUpdateViewState

Source code excerpt:

		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++)
		{
			const FGlobalDFCacheType StartCacheType = GAOGlobalDistanceFieldCacheMostlyStaticSeparately ? GDF_MostlyStatic : GDF_Full;