r.AOHistoryWeight

r.AOHistoryWeight

#Overview

name: r.AOHistoryWeight

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.AOHistoryWeight is to control the amount of temporal smoothing applied to the Ambient Occlusion (AO) effect in Unreal Engine’s rendering system. This variable is part of the rendering subsystem, specifically related to the Distance Field Ambient Occlusion (DFAO) feature.

The r.AOHistoryWeight setting is used in the following Unreal Engine subsystems:

  1. Renderer module, particularly in the Distance Field Lighting post-processing.

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

The associated variable GAOHistoryWeight interacts directly with r.AOHistoryWeight. They share the same value, with GAOHistoryWeight being the C++ variable used in the rendering code.

Developers should be aware of the following when using this variable:

  1. Higher values increase stability but may cause more streaking under occluder movement.
  2. Lower values reduce streaking but may introduce more temporal instability.
  3. The default value is 0.85, which provides a balance between stability and responsiveness.

Best practices when using this variable include:

  1. Adjust the value based on the specific needs of your scene. Scenes with more dynamic objects might benefit from lower values to reduce streaking.
  2. Use in conjunction with other AO settings for optimal results.
  3. Test different values to find the best balance between stability and responsiveness for your specific use case.

Regarding the associated variable GAOHistoryWeight:

The purpose of GAOHistoryWeight is to provide a C++ accessible version of the r.AOHistoryWeight console variable. It is used directly in the rendering code to apply the temporal smoothing to the AO effect.

GAOHistoryWeight is used in the same subsystems as r.AOHistoryWeight, primarily in the Renderer module’s Distance Field Lighting post-processing.

The value of GAOHistoryWeight is set automatically by the console variable system when r.AOHistoryWeight is changed.

Developers should be aware that modifying GAOHistoryWeight directly in code will not persist, as it will be overwritten by the console variable system. Always use r.AOHistoryWeight to make persistent changes.

Best practices for GAOHistoryWeight are the same as for r.AOHistoryWeight, as they represent the same value in different contexts (console variable vs. C++ variable).

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

float GAOHistoryWeight = .85f;
FAutoConsoleVariableRef CVarAOHistoryWeight(
	TEXT("r.AOHistoryWeight"),
	GAOHistoryWeight,
	TEXT("Amount of last frame's AO to lerp into the final result.  Higher values increase stability, lower values have less streaking under occluder movement."),
	ECVF_RenderThreadSafe
	);

float GAOHistoryDistanceThreshold = 30;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	);

float GAOHistoryWeight = .85f;
FAutoConsoleVariableRef CVarAOHistoryWeight(
	TEXT("r.AOHistoryWeight"),
	GAOHistoryWeight,
	TEXT("Amount of last frame's AO to lerp into the final result.  Higher values increase stability, lower values have less streaking under occluder movement."),
	ECVF_RenderThreadSafe
	);

float GAOHistoryDistanceThreshold = 30;
FAutoConsoleVariableRef CVarAOHistoryDistanceThreshold(

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

Scope (from outer to inner):

file
function     void UpdateHistory

Source code excerpt:

				PassParameters->VelocityTextureSampler = TStaticSamplerState<SF_Bilinear, AM_Clamp, AM_Clamp, AM_Clamp>::GetRHI();

				PassParameters->HistoryWeight = GAOHistoryWeight;
				PassParameters->HistoryDistanceThreshold = GAOHistoryDistanceThreshold;
				PassParameters->UseHistoryFilter = UseAOHistoryStabilityPass() ? 1.0f : 0.0f;

				{
					const float InvBufferSizeX = 1.0f / AOBufferSize.X;
					const float InvBufferSizeY = 1.0f / AOBufferSize.Y;

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

Scope (from outer to inner):

file
function     void UpdateHistory

Source code excerpt:

				PassParameters->BentNormalAOTexelSize = FVector2f(1.0f / AOBufferSize.X, 1.0f / AOBufferSize.Y);
				PassParameters->MaxSampleBufferUV = MaxSampleBufferUV;
				PassParameters->HistoryWeight = GAOHistoryWeight;
				PassParameters->RenderTargets[0] = FRenderTargetBinding(BentNormalHistoryTexture, ERenderTargetLoadAction::ELoad);

				ClearUnusedGraphResources(PixelShader, PassParameters);

				GraphBuilder.AddPass(
					RDG_EVENT_NAME("UpdateHistoryStability"),