r.AOQuality

r.AOQuality

#Overview

name: r.AOQuality

The value of this variable can be defined or overridden in .ini config files. 4 .ini config files referencing this setting variable.

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

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.AOQuality is to control the quality of distance field ambient occlusion (AO) in Unreal Engine’s rendering system. This setting variable allows developers to adjust the trade-off between visual quality and performance for the AO effect.

The Unreal Engine subsystem that relies on this setting variable is the Renderer module, specifically the distance field ambient occlusion component. This can be seen from the file path where the variable is defined: “Engine/Source/Runtime/Renderer/Private/DistanceFieldAmbientOcclusion.cpp”.

The value of this variable is set through the console variable system, as indicated by the FAutoConsoleVariableRef declaration. It can be changed at runtime using console commands or through configuration files.

The r.AOQuality variable interacts directly with the GDistanceFieldAOQuality variable. They share the same value, with GDistanceFieldAOQuality being the actual integer used in the code logic.

Developers must be aware that this variable has three possible values: 0: AO is off 1: Medium quality AO 2: High quality AO (default)

The best practices when using this variable include:

  1. Consider the performance impact when setting to higher values, especially on less powerful hardware.
  2. Use it in conjunction with other AO-related settings for optimal results.
  3. Test different values to find the best balance between visual quality and performance for your specific game or application.

Regarding the associated variable GDistanceFieldAOQuality:

The purpose of GDistanceFieldAOQuality is to serve as the internal representation of the AO quality setting. It’s used directly in the code to determine the behavior of the distance field AO system.

This variable is used in various parts of the renderer code to enable or disable certain features based on the quality setting. For example:

Developers should be aware that changing GDistanceFieldAOQuality directly in code is not recommended. Instead, they should use the r.AOQuality console variable to ensure proper synchronization between the two variables.

Best practices for using GDistanceFieldAOQuality include:

  1. Always check its value before enabling AO-related features in your custom rendering code.
  2. Be mindful of its performance implications, especially when using the highest quality setting.
  3. Consider offering user-facing graphics options that indirectly control this setting for better player experience across different hardware configurations.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseScalability.ini:266, section: [GlobalIlluminationQuality@1]

Location: <Workspace>/Engine/Config/BaseScalability.ini:272, section: [GlobalIlluminationQuality@2]

Location: <Workspace>/Engine/Config/BaseScalability.ini:295, section: [GlobalIlluminationQuality@3]

Location: <Workspace>/Engine/Config/BaseScalability.ini:319, section: [GlobalIlluminationQuality@Cine]

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

int32 GDistanceFieldAOQuality = 2;
FAutoConsoleVariableRef CVarDistanceFieldAOQuality(
	TEXT("r.AOQuality"),
	GDistanceFieldAOQuality,
	TEXT("Defines the distance field AO method which allows to adjust for quality or performance.\n")
	TEXT(" 0:off, 1:medium, 2:high (default)"),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

int32 GDistanceFieldAOQuality = 2;
FAutoConsoleVariableRef CVarDistanceFieldAOQuality(
	TEXT("r.AOQuality"),
	GDistanceFieldAOQuality,
	TEXT("Defines the distance field AO method which allows to adjust for quality or performance.\n")
	TEXT(" 0:off, 1:medium, 2:high (default)"),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GDistanceFieldAOApplyToStaticIndirect = 0;

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DistanceFieldAmbientOcclusion.cpp:132

Scope (from outer to inner):

file
function     bool UseDistanceFieldAO

Source code excerpt:

bool UseDistanceFieldAO()
{
	return GDistanceFieldAO && GDistanceFieldAOQuality >= 1;
}

bool UseAOObjectDistanceField()
{
	return GAOObjectDistanceField && GDistanceFieldAOQuality >= 2;
}

int32 GDistanceFieldAOTileSizeX = 16;
int32 GDistanceFieldAOTileSizeY = 16;

FDistanceFieldAOParameters::FDistanceFieldAOParameters(float InOcclusionMaxDistance, float InContrast)

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DistanceFieldAmbientOcclusion.cpp:674

Scope (from outer to inner):

file
function     bool SupportsDistanceFieldAO

Source code excerpt:

bool SupportsDistanceFieldAO(ERHIFeatureLevel::Type FeatureLevel, EShaderPlatform ShaderPlatform)
{
	return GDistanceFieldAO && GDistanceFieldAOQuality > 0
		// Pre-GCN AMD cards have a driver bug that prevents the global distance field from being generated correctly
		// Better to disable entirely than to display garbage
		&& !GRHIDeviceIsAMDPreGCNArchitecture
		// Intel HD 4000 hangs in the RHICreateTexture3D call to allocate the large distance field atlas, and virtually no Intel cards can afford it anyway
		&& !GRHIDeviceIsIntegrated
		&& DoesPlatformSupportDistanceFieldAO(ShaderPlatform)

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

Scope (from outer to inner):

file
function     bool UseAOHistoryStabilityPass

Source code excerpt:

bool UseAOHistoryStabilityPass()
{
	extern int32 GDistanceFieldAOQuality;
	return GAOHistoryStabilityPass && GDistanceFieldAOQuality >= 2;
}

bool ShouldCompileDFLightingPostShaders(EShaderPlatform ShaderPlatform)
{
	return ShouldCompileDistanceFieldShaders(ShaderPlatform) && !IsMobilePlatform(ShaderPlatform);
}