r.AOClearHistory

r.AOClearHistory

#Overview

name: r.AOClearHistory

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.AOClearHistory is to control whether the Ambient Occlusion (AO) history should be cleared in the rendering pipeline. This setting is part of the rendering system, specifically related to the Distance Field Ambient Occlusion (DFAO) post-processing effect.

The Unreal Engine renderer subsystem relies on this setting variable, as evidenced by its usage in the DistanceFieldLightingPost.cpp file, which is part of the Renderer module.

The value of this variable is set through the console variable system (CVarAOClearHistory), which allows it to be changed at runtime. It’s initialized to 0 by default, meaning the AO history is not cleared unless explicitly set.

This variable interacts directly with its associated variable GAOClearHistory. They share the same value, with r.AOClearHistory being the console-accessible name and GAOClearHistory being the actual C++ variable used in the code.

Developers must be aware that clearing the AO history can affect the stability and consistency of the ambient occlusion effect between frames. It’s typically used for debugging or when sudden changes in lighting or geometry require a reset of the AO calculation.

Best practices when using this variable include:

  1. Leaving it at its default value (0) for normal operation to maintain temporal stability in the AO effect.
  2. Setting it to 1 temporarily when debugging AO issues or when major scene changes occur that require a fresh AO calculation.
  3. Being cautious about frequently toggling this value, as it can lead to visual inconsistencies in the rendered output.

Regarding the associated variable GAOClearHistory:

The purpose of GAOClearHistory is to serve as the internal C++ representation of the r.AOClearHistory console variable. It’s used directly in the rendering code to determine whether the AO history should be cleared.

This variable is used in the UpdateHistory function within the DistanceFieldLightingPost.cpp file. It’s checked alongside other conditions (like camera cuts or transform resets) to determine if the AO history should be preserved or discarded.

The value of GAOClearHistory is set through the console variable system, mirroring the value of r.AOClearHistory.

GAOClearHistory interacts primarily with the r.AOClearHistory console variable, as they are directly linked.

Developers should be aware that modifying GAOClearHistory directly in C++ code is not recommended, as it may lead to inconsistencies with the console variable system. Instead, they should use the r.AOClearHistory console command to change this setting.

Best practices for GAOClearHistory include:

  1. Treating it as a read-only variable in most cases, using it for condition checks in rendering code.
  2. Relying on the console variable system (r.AOClearHistory) for any runtime modifications to this setting.
  3. Considering the performance implications of frequently checking this variable in rendering loops.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DistanceFieldLightingPost.cpp:24

Scope: file

Source code excerpt:

int32 GAOClearHistory = 0;
FAutoConsoleVariableRef CVarAOClearHistory(
	TEXT("r.AOClearHistory"),
	GAOClearHistory,
	TEXT(""),
	ECVF_RenderThreadSafe
	);

int32 GAOHistoryStabilityPass = 1;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DistanceFieldLightingPost.cpp:22

Scope: file

Source code excerpt:

	);

int32 GAOClearHistory = 0;
FAutoConsoleVariableRef CVarAOClearHistory(
	TEXT("r.AOClearHistory"),
	GAOClearHistory,
	TEXT(""),
	ECVF_RenderThreadSafe
	);

int32 GAOHistoryStabilityPass = 1;
FAutoConsoleVariableRef CVarAOHistoryStabilityPass(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DistanceFieldLightingPost.cpp:329

Scope (from outer to inner):

file
function     void UpdateHistory

Source code excerpt:

			&& !View.bCameraCut 
			&& !View.bPrevTransformsReset
			&& !GAOClearHistory
			// If the scene render targets reallocate, toss the history so we don't read uninitialized data
			&& (*BentNormalHistoryState)->GetDesc().Extent == AOBufferSize)
		{
			FRDGTextureRef BentNormalHistoryTexture = GraphBuilder.RegisterExternalTexture(*BentNormalHistoryState);

			ETextureCreateFlags HistoryPassOutputFlags = ETextureCreateFlags(UseAOHistoryStabilityPass() ? GFastVRamConfig.DistanceFieldAOHistory : TexCreate_None);