r.AOObjectDistanceField

r.AOObjectDistanceField

#Overview

name: r.AOObjectDistanceField

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.AOObjectDistanceField is to control whether object distance fields are used in computing ambient occlusion in the rendering system of Unreal Engine 5.

This setting variable is primarily used in the Renderer module of Unreal Engine, specifically in the Distance Field Ambient Occlusion (DFAO) system. It’s referenced in the DistanceFieldAmbientOcclusion.cpp file, which is part of the rendering subsystem.

The value of this variable is set through the Unreal Engine console variable system. It’s initialized to 1 (enabled) by default, but can be changed at runtime using console commands or through project settings.

The r.AOObjectDistanceField variable directly interacts with the GAOObjectDistanceField variable. They share the same value, with GAOObjectDistanceField being the internal C++ variable that the engine code checks when determining whether to use object distance fields for ambient occlusion calculations.

Developers should be aware that this variable affects the quality and performance of ambient occlusion rendering. When enabled (set to 1), it allows for more detailed and accurate ambient occlusion by considering individual object distance fields. When disabled (set to 0), only the global distance field is used, which may be less accurate but potentially more performant.

Best practices when using this variable include:

  1. Consider the performance impact of enabling object distance fields for ambient occlusion, especially on lower-end hardware.
  2. Use in conjunction with the GDistanceFieldAOQuality setting, as object distance fields are only used when the quality is set to 2 or higher.
  3. Test the visual difference and performance impact with this setting enabled and disabled to determine the best configuration for your project.

Regarding the associated variable GAOObjectDistanceField:

The purpose of GAOObjectDistanceField is to serve as the internal C++ representation of the r.AOObjectDistanceField console variable.

This variable is used directly in the rendering code to determine whether object distance fields should be used for ambient occlusion calculations. It’s referenced in the UseAOObjectDistanceField() function, which checks both this variable and the overall distance field AO quality setting.

The value of GAOObjectDistanceField is set by the console variable system when r.AOObjectDistanceField is modified.

GAOObjectDistanceField interacts closely with GDistanceFieldAOQuality. Both need to meet certain conditions for object distance fields to be used in ambient occlusion calculations.

Developers should be aware that modifying GAOObjectDistanceField directly in C++ code is not recommended. Instead, they should use the r.AOObjectDistanceField console variable to ensure proper synchronization between the console variable and the internal C++ variable.

Best practices for GAOObjectDistanceField include:

  1. Avoid modifying it directly in C++ code.
  2. Use the UseAOObjectDistanceField() function when checking whether object distance fields should be used for ambient occlusion in rendering code.
  3. Remember that this setting alone doesn’t guarantee the use of object distance fields; the overall distance field AO quality must also be considered.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

int32 GAOObjectDistanceField = 1;
FAutoConsoleVariableRef CVarAOObjectDistanceField(
	TEXT("r.AOObjectDistanceField"),
	GAOObjectDistanceField,
	TEXT("Determines whether object distance fields are used to compute ambient occlusion.\n")
	TEXT("Only global distance field will be used when this option is disabled.\n"),
	ECVF_RenderThreadSafe
);

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	);

int32 GAOObjectDistanceField = 1;
FAutoConsoleVariableRef CVarAOObjectDistanceField(
	TEXT("r.AOObjectDistanceField"),
	GAOObjectDistanceField,
	TEXT("Determines whether object distance fields are used to compute ambient occlusion.\n")
	TEXT("Only global distance field will be used when this option is disabled.\n"),
	ECVF_RenderThreadSafe
);

int32 GAOGlobalDistanceFieldDetailedNecessityCheck = 1;

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

Scope (from outer to inner):

file
function     bool UseAOObjectDistanceField

Source code excerpt:

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

int32 GDistanceFieldAOTileSizeX = 16;
int32 GDistanceFieldAOTileSizeY = 16;

FDistanceFieldAOParameters::FDistanceFieldAOParameters(float InOcclusionMaxDistance, float InContrast)