r.AOGlobalDistanceField.RecacheClipmapsWithPendingStreaming

r.AOGlobalDistanceField.RecacheClipmapsWithPendingStreaming

#Overview

name: r.AOGlobalDistanceField.RecacheClipmapsWithPendingStreaming

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

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.AOGlobalDistanceField.RecacheClipmapsWithPendingStreaming is to control the recaching behavior of global distance field clipmaps when there is pending streaming of Mesh SDFs (Signed Distance Fields).

This setting variable is primarily used in the rendering system, specifically for the global distance field functionality in Unreal Engine 5. It is part of the Renderer module, as evident from its location in the GlobalDistanceField.cpp file.

The Unreal Engine subsystem that relies on this setting variable is the Global Distance Field system, which is a part of the larger rendering subsystem. This system is crucial for various rendering techniques, including ambient occlusion and other global illumination effects.

The value of this variable is set through the Unreal Engine console variable system. It is initialized with a default value of 1 (enabled) and can be changed at runtime using console commands.

This variable interacts closely with the associated variable GAOGlobalDistanceFieldRecacheClipmapsWithPendingStreaming. They share the same value and purpose.

Developers must be aware that this variable affects the accuracy of the Global SDF (Signed Distance Field) around the camera, especially after teleporting or loading a new level. When enabled, it helps to fix inaccuracies in the global distance field that may occur due to incomplete Mesh SDFs during streaming.

Best practices when using this variable include:

  1. Keeping it enabled (default value of 1) for better visual quality, especially in scenarios with frequent level changes or camera teleportation.
  2. Considering performance implications, as recaching clipmaps may have some performance cost.
  3. Testing the visual impact and performance with this setting both enabled and disabled in various scenarios to determine the best configuration for your specific game.

Regarding the associated variable GAOGlobalDistanceFieldRecacheClipmapsWithPendingStreaming:

This is an internal integer variable that directly corresponds to the console variable r.AOGlobalDistanceField.RecacheClipmapsWithPendingStreaming. It serves the same purpose and is used within the C++ code to control the recaching behavior.

The value of GAOGlobalDistanceFieldRecacheClipmapsWithPendingStreaming is set by the console variable system when r.AOGlobalDistanceField.RecacheClipmapsWithPendingStreaming is modified.

This variable is used in the code to determine whether to recache clipmaps with pending streaming. It’s checked in the rendering code to decide if a particular clipmap should be recached based on various conditions, including the current view state and the clipmap index.

Developers should be aware that modifying r.AOGlobalDistanceField.RecacheClipmapsWithPendingStreaming will directly affect the behavior controlled by GAOGlobalDistanceFieldRecacheClipmapsWithPendingStreaming in the C++ code.

Best practices for this associated variable include:

  1. Not modifying it directly in code, but rather using the console variable system to change its value.
  2. Being aware of its impact on the global distance field calculation and potential performance implications when enabled.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

int32 GAOGlobalDistanceFieldRecacheClipmapsWithPendingStreaming = 1;
FAutoConsoleVariableRef CVarAOGlobalDistanceFieldRecacheClipmapsWithPendingStreaming(
	TEXT("r.AOGlobalDistanceField.RecacheClipmapsWithPendingStreaming"),
	GAOGlobalDistanceFieldRecacheClipmapsWithPendingStreaming,
	TEXT("Whether to readback clipmaps cached with incomplete Mesh SDFs due to streaming and recache them on subsequent frames. Fixes innaccurate Global SDF around the camera after teleporting or loading a new level."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GAOGlobalDistanceFieldForceRecacheForStreaming = 0;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

int32 GAOGlobalDistanceFieldRecacheClipmapsWithPendingStreaming = 1;
FAutoConsoleVariableRef CVarAOGlobalDistanceFieldRecacheClipmapsWithPendingStreaming(
	TEXT("r.AOGlobalDistanceField.RecacheClipmapsWithPendingStreaming"),
	GAOGlobalDistanceFieldRecacheClipmapsWithPendingStreaming,
	TEXT("Whether to readback clipmaps cached with incomplete Mesh SDFs due to streaming and recache them on subsequent frames. Fixes innaccurate Global SDF around the camera after teleporting or loading a new level."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GAOGlobalDistanceFieldForceRecacheForStreaming = 0;
FAutoConsoleVariableRef CVarAOGlobalDistanceFieldForceRecacheForStreaming(

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

Scope: file

Source code excerpt:

			{
				PackedClipmap.bRecacheClipmapsWithPendingStreaming =
					GAOGlobalDistanceFieldRecacheClipmapsWithPendingStreaming != 0 &&
					View.ViewState &&
					CacheType == GDF_MostlyStatic &&
					PackedClipmap.Index < 2;

				if (PackedClipmap.bRecacheClipmapsWithPendingStreaming)
				{