r.AOGlobalDistanceField.DetailedNecessityCheck

r.AOGlobalDistanceField.DetailedNecessityCheck

#Overview

name: r.AOGlobalDistanceField.DetailedNecessityCheck

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.AOGlobalDistanceField.DetailedNecessityCheck is to control whether a detailed necessity check is performed in the FSceneRenderer::ShouldPrepareGlobalDistanceField() function. This setting variable is related to the rendering system, specifically the Ambient Occlusion (AO) and Global Distance Field functionality in Unreal Engine 5.

This setting variable is primarily used in the Renderer module of Unreal Engine 5. It affects the decision-making process for preparing the global distance field, which is an important component in rendering ambient occlusion and other distance field-based effects.

The value of this variable is set using the FAutoConsoleVariableRef system, which allows it to be changed at runtime through console commands. It is initialized with a default value of 1 (true).

The associated variable GAOGlobalDistanceFieldDetailedNecessityCheck directly interacts with r.AOGlobalDistanceField.DetailedNecessityCheck. They share the same value and are used interchangeably in the code.

Developers must be aware that this variable affects the performance and accuracy trade-off in the global distance field preparation process. When set to 1 (true), it performs a more detailed check, which may be more accurate but potentially more computationally expensive.

Best practices when using this variable include:

  1. Leave it at the default value (1) unless there’s a specific performance issue related to global distance field preparation.
  2. If disabling the detailed check (setting to 0), thoroughly test the visual quality of ambient occlusion and other distance field-based effects to ensure they’re not negatively impacted.
  3. Consider the impact on both performance and visual quality when adjusting this setting.

Regarding the associated variable GAOGlobalDistanceFieldDetailedNecessityCheck:

The purpose of GAOGlobalDistanceFieldDetailedNecessityCheck is to serve as the actual storage for the r.AOGlobalDistanceField.DetailedNecessityCheck setting within the C++ code.

This variable is used directly in the Renderer module, specifically in the FSceneRenderer::ShouldPrepareGlobalDistanceField() function. It determines whether a more detailed check should be performed when deciding if the global distance field needs to be prepared.

The value of this variable is set through the FAutoConsoleVariableRef system, which links it to the r.AOGlobalDistanceField.DetailedNecessityCheck console variable.

It interacts directly with the r.AOGlobalDistanceField.DetailedNecessityCheck console variable, as they share the same value.

Developers should be aware that this variable directly affects the logic in ShouldPrepareGlobalDistanceField(). When it’s false (0), the function may decide to prepare the global distance field more often, potentially impacting performance but ensuring the distance field is always available when needed.

Best practices for using this variable include:

  1. Avoid modifying it directly in code; instead, use the console variable r.AOGlobalDistanceField.DetailedNecessityCheck to change its value.
  2. When debugging issues related to global distance field preparation, consider the value of this variable and how it affects the preparation logic.
  3. If adjusting this variable for performance reasons, carefully balance the trade-off between performance and the availability of up-to-date global distance field data.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

int32 GAOGlobalDistanceFieldDetailedNecessityCheck = 1;
FAutoConsoleVariableRef CVarAOGlobalDistanceFieldDetailedCheck(
	TEXT("r.AOGlobalDistanceField.DetailedNecessityCheck"),
	GAOGlobalDistanceFieldDetailedNecessityCheck,
	TEXT("Whether to perform detailed necessity check in FSceneRenderer::ShouldPrepareGlobalDistanceField()."),
	ECVF_RenderThreadSafe
);

bool UseDistanceFieldAO()

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

int32 GAOGlobalDistanceFieldDetailedNecessityCheck = 1;
FAutoConsoleVariableRef CVarAOGlobalDistanceFieldDetailedCheck(
	TEXT("r.AOGlobalDistanceField.DetailedNecessityCheck"),
	GAOGlobalDistanceFieldDetailedNecessityCheck,
	TEXT("Whether to perform detailed necessity check in FSceneRenderer::ShouldPrepareGlobalDistanceField()."),
	ECVF_RenderThreadSafe
);

bool UseDistanceFieldAO()
{

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

Scope (from outer to inner):

file
function     bool FSceneRenderer::ShouldPrepareGlobalDistanceField

Source code excerpt:


	const bool bShouldPrepareForMaterialsOrNiagara = 
		!GAOGlobalDistanceFieldDetailedNecessityCheck
		|| Views[0].PrevViewInfo.bUsesGlobalDistanceField // use previous frame relevance because this frame relevance flags haven't been calculate yet
		|| ((FXSystem != nullptr) && FXSystem->UsesGlobalDistanceField());

	if (ViewFamily.EngineShowFlags.PathTracing)
	{
		return bShouldPrepareForMaterialsOrNiagara;