r.AOUseHistory

r.AOUseHistory

#Overview

name: r.AOUseHistory

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.AOUseHistory is to control the application of a temporal filter to the distance field Ambient Occlusion (AO) in Unreal Engine’s rendering system. This setting is primarily used in the rendering subsystem, specifically for the Ambient Occlusion post-processing effect.

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

The value of this variable is set through the FAutoConsoleVariableRef system, which allows it to be modified at runtime via console commands. It is initialized with a default value of 1 (enabled).

This variable interacts directly with its associated variable GAOUseHistory. They share the same value and are used interchangeably in the code.

Developers must be aware that enabling this variable (set to 1) will reduce flickering in the Ambient Occlusion effect, but it may also introduce trailing artifacts when occluders are moving in the scene. This trade-off should be considered when deciding whether to use the temporal filter.

Best practices when using this variable include:

  1. Testing the visual impact of enabling and disabling the setting in various scenarios to determine the best option for your specific use case.
  2. Considering performance implications, as temporal filtering may have a slight performance cost.
  3. Being mindful of the potential trailing artifacts and adjusting other rendering settings if necessary to mitigate them.

Regarding the associated variable GAOUseHistory:

The purpose of GAOUseHistory is to serve as the internal representation of the r.AOUseHistory console variable within the C++ code. It is used directly in the rendering calculations to determine whether the temporal filter should be applied to the distance field AO.

This variable is used in the DistanceFieldAOUseHistory function to determine if the history should be used for a particular view. It’s important to note that it’s not used for scene capture cubes, as indicated by the condition !View.bIsSceneCaptureCube.

The value of GAOUseHistory is set by the FAutoConsoleVariableRef system, which links it to the r.AOUseHistory console variable.

Developers should be aware that modifying GAOUseHistory directly in code is not recommended, as it should be controlled through the r.AOUseHistory console variable to ensure consistency across the engine.

Best practices for GAOUseHistory include:

  1. Accessing its value through the appropriate engine systems rather than modifying it directly.
  2. Understanding that its value affects the DistanceFieldAOUseHistory function, which likely has implications for other parts of the AO rendering pipeline.
  3. Considering the performance and visual implications of enabling or disabling this feature when optimizing rendering for different platforms or use cases.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

int32 GAOUseHistory = 1;
FAutoConsoleVariableRef CVarAOUseHistory(
	TEXT("r.AOUseHistory"),
	GAOUseHistory,
	TEXT("Whether to apply a temporal filter to the distance field AO, which reduces flickering but also adds trails when occluders are moving."),
	ECVF_RenderThreadSafe
	);

int32 GAOClearHistory = 0;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

#include "DataDrivenShaderPlatformInfo.h"

int32 GAOUseHistory = 1;
FAutoConsoleVariableRef CVarAOUseHistory(
	TEXT("r.AOUseHistory"),
	GAOUseHistory,
	TEXT("Whether to apply a temporal filter to the distance field AO, which reduces flickering but also adds trails when occluders are moving."),
	ECVF_RenderThreadSafe
	);

int32 GAOClearHistory = 0;
FAutoConsoleVariableRef CVarAOClearHistory(

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

Scope (from outer to inner):

file
function     bool DistanceFieldAOUseHistory

Source code excerpt:

	// this for debug purposes by modifying FSceneTextureExtentState::Compute to add some padding to the scene textures).
	//
	return GAOUseHistory && !View.bIsSceneCaptureCube;
}

void UpdateHistory(
	FRDGBuilder& GraphBuilder,
	const FViewInfo& View, 
	const TCHAR* BentNormalHistoryRTName,