r.DistanceFieldAO

r.DistanceFieldAO

#Overview

name: r.DistanceFieldAO

The value of this variable can be defined or overridden in .ini config files. 10 .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.DistanceFieldAO is to control whether the distance field ambient occlusion (AO) feature is allowed in Unreal Engine 5. This setting is primarily used for the rendering system, specifically for implementing shadows of Movable sky lights from static meshes.

This setting variable is primarily relied upon by the Renderer module of Unreal Engine 5. It’s used in the distance field ambient occlusion subsystem, which is part of the larger rendering pipeline.

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

The r.DistanceFieldAO variable interacts closely with another variable named GDistanceFieldAO. They share the same value, and GDistanceFieldAO is used internally in the C++ code to check if the distance field AO feature is enabled.

Developers must be aware that this variable affects the rendering quality and performance. Enabling distance field AO can significantly improve the visual quality of shadows from movable sky lights, but it comes at a performance cost.

Best practices when using this variable include:

  1. Consider the target hardware when enabling this feature, as it can be performance-intensive.
  2. Use in conjunction with other distance field settings for optimal results.
  3. Be aware that some hardware (like pre-GCN AMD cards or integrated graphics) may not support this feature or may have issues with it.

Regarding the associated variable GDistanceFieldAO:

The purpose of GDistanceFieldAO is to serve as the internal C++ representation of the r.DistanceFieldAO console variable. It’s used directly in the code to check if the distance field AO feature is enabled.

This variable is primarily used in the Renderer module, specifically in the distance field ambient occlusion subsystem.

The value of GDistanceFieldAO is set automatically by the console variable system when r.DistanceFieldAO is modified.

GDistanceFieldAO interacts with other variables like GDistanceFieldAOQuality to determine if distance field AO should be used and at what quality level.

Developers should be aware that modifying GDistanceFieldAO directly in code is not recommended. Instead, they should use the r.DistanceFieldAO console variable to change this setting.

Best practices for GDistanceFieldAO include:

  1. Use it for conditional checks in rendering code to determine if distance field AO should be applied.
  2. Avoid modifying it directly; use the console variable system instead.
  3. Consider combining checks with other related variables (like GDistanceFieldAOQuality) for more fine-grained control over the feature.

#Setting Variables

#References In INI files

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

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

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

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

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

Location: <Workspace>/Projects/Lyra/Config/DefaultScalability.ini:32, section: [GlobalIlluminationQuality@0]

Location: <Workspace>/Projects/Lyra/Config/DefaultScalability.ini:36, section: [GlobalIlluminationQuality@1]

Location: <Workspace>/Projects/Lyra/Config/DefaultScalability.ini:39, section: [GlobalIlluminationQuality@2]

Location: <Workspace>/Projects/Lyra/Config/DefaultScalability.ini:42, section: [GlobalIlluminationQuality@3]

Location: <Workspace>/Projects/Lyra/Config/DefaultScalability.ini:45, 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:24

Scope: file

Source code excerpt:

int32 GDistanceFieldAO = 1;
FAutoConsoleVariableRef CVarDistanceFieldAO(
	TEXT("r.DistanceFieldAO"),
	GDistanceFieldAO,
	TEXT("Whether the distance field AO feature is allowed, which is used to implement shadows of Movable sky lights from static meshes."),
	ECVF_Scalability | ECVF_RenderThreadSafe
	);

int32 GDistanceFieldAOMultiView = 1;

#Loc: <Workspace>/Engine/Source/Runtime/Apple/MetalRHI/Private/MetalRHI.cpp:502

Scope: file

Source code excerpt:

	if ((GMaxRHIShaderPlatform == SP_METAL_SM5 || GMaxRHIShaderPlatform == SP_METAL_SM6) && !bSupportsDistanceFields && !FParse::Param(FCommandLine::Get(),TEXT("metaldistancefields")))
	{
		static auto CVarDistanceFieldAO = IConsoleManager::Get().FindConsoleVariable(TEXT("r.DistanceFieldAO"));
		if(CVarDistanceFieldAO && CVarDistanceFieldAO->GetInt() != 0)
		{
			CVarDistanceFieldAO->Set(0);
		}
		
		static auto CVarDistanceFieldShadowing = IConsoleManager::Get().FindConsoleVariable(TEXT("r.DistanceFieldShadowing"));

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

DEFINE_LOG_CATEGORY(LogDistanceField);

int32 GDistanceFieldAO = 1;
FAutoConsoleVariableRef CVarDistanceFieldAO(
	TEXT("r.DistanceFieldAO"),
	GDistanceFieldAO,
	TEXT("Whether the distance field AO feature is allowed, which is used to implement shadows of Movable sky lights from static meshes."),
	ECVF_Scalability | ECVF_RenderThreadSafe
	);

int32 GDistanceFieldAOMultiView = 1;
FAutoConsoleVariableRef CVarDistanceFieldAOMultiView(

#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;
}

#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)