r.AOGlobalDistanceField

r.AOGlobalDistanceField

#Overview

name: r.AOGlobalDistanceField

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.AOGlobalDistanceField is to control whether a global distance field is used to optimize occlusion cone traces in the Ambient Occlusion (AO) system. This setting is part of the rendering system in Unreal Engine 5, specifically related to global illumination and ambient occlusion calculations.

The Unreal Engine subsystem that relies on this setting variable is primarily the Renderer module, as evidenced by the source files where it’s referenced (GlobalDistanceField.cpp and DistanceFieldAmbientOcclusion.cpp).

The value of this variable is set through a console variable (CVarAOGlobalDistanceField) which allows it to be changed at runtime. It’s initialized with a default value of 1, meaning the global distance field is enabled by default.

This variable interacts closely with GAOGlobalDistanceField, which is the associated internal variable that directly controls the feature. They share the same value, with r.AOGlobalDistanceField being the exposed console variable and GAOGlobalDistanceField being the actual int32 variable used in the code.

Developers must be aware that this setting affects performance and visual quality. Enabling the global distance field (value 1) can improve the quality of ambient occlusion but may have performance implications, especially on lower-end hardware.

Best practices when using this variable include:

  1. Testing performance with and without the global distance field enabled to find the optimal setting for your specific game.
  2. Considering scalability options, as this variable is marked with ECVF_Scalability, indicating it’s intended to be adjusted based on hardware capabilities.
  3. Being cautious when changing this value at runtime, as it may cause visual changes or performance fluctuations.

Regarding the associated variable GAOGlobalDistanceField:

The purpose of GAOGlobalDistanceField is to serve as the internal representation of the r.AOGlobalDistanceField setting. It’s used directly in the code to determine whether the global distance field should be used in various calculations.

This variable is used in the Renderer module, particularly in ambient occlusion and global illumination calculations.

The value of GAOGlobalDistanceField is set indirectly through the r.AOGlobalDistanceField console variable.

It interacts with other variables like GAOGlobalDFStartDistance to determine occlusion distances when the global distance field is enabled.

Developers should be aware that this variable is used in performance-critical rendering code, so changes to its value can have significant impacts on rendering performance and quality.

Best practices for GAOGlobalDistanceField include:

  1. Avoiding direct modification of this variable in code; instead, use the r.AOGlobalDistanceField console variable to change its value.
  2. Considering its impact on related systems, such as the calculation of object and global max occlusion distances.
  3. Using the provided utility functions like UseGlobalDistanceField() to check its state, rather than accessing the variable directly.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

int32 GAOGlobalDistanceField = 1;
FAutoConsoleVariableRef CVarAOGlobalDistanceField(
	TEXT("r.AOGlobalDistanceField"), 
	GAOGlobalDistanceField,
	TEXT("Whether to use a global distance field to optimize occlusion cone traces.\n")
	TEXT("The global distance field is created by compositing object distance fields into clipmaps as the viewer moves through the level."),
	ECVF_Scalability | ECVF_RenderThreadSafe
	);

#Associated Variable and Callsites

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

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

Scope (from outer to inner):

file
function     FDistanceFieldAOParameters::FDistanceFieldAOParameters

Source code excerpt:

	InOcclusionMaxDistance = FMath::Clamp(InOcclusionMaxDistance, 2.0f, 3000.0f);

	if (GAOGlobalDistanceField != 0)
	{
		extern float GAOGlobalDFStartDistance;
		ObjectMaxOcclusionDistance = FMath::Min(InOcclusionMaxDistance, GAOGlobalDFStartDistance);
		GlobalMaxOcclusionDistance = InOcclusionMaxDistance >= GAOGlobalDFStartDistance ? InOcclusionMaxDistance : 0;
	}
	else

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

Scope: file

Source code excerpt:

extern int32 GDistanceFieldOffsetDataStructure;

int32 GAOGlobalDistanceField = 1;
FAutoConsoleVariableRef CVarAOGlobalDistanceField(
	TEXT("r.AOGlobalDistanceField"), 
	GAOGlobalDistanceField,
	TEXT("Whether to use a global distance field to optimize occlusion cone traces.\n")
	TEXT("The global distance field is created by compositing object distance fields into clipmaps as the viewer moves through the level."),
	ECVF_Scalability | ECVF_RenderThreadSafe
	);

float GGlobalDistanceFieldOccupancyRatio = 0.3f;

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

Scope (from outer to inner):

file
function     bool UseGlobalDistanceField

Source code excerpt:

bool UseGlobalDistanceField()
{
	return GAOGlobalDistanceField != 0;
}

bool UseGlobalDistanceField(const FDistanceFieldAOParameters& Parameters)
{
	return UseGlobalDistanceField() && Parameters.GlobalMaxOcclusionDistance > 0;
}

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/GlobalDistanceField.h:18

Scope: file

Source code excerpt:

};

extern int32 GAOGlobalDistanceField;

bool UseGlobalDistanceField();
bool UseGlobalDistanceField(const FDistanceFieldAOParameters& Parameters);

namespace GlobalDistanceField
{