r.AOGlobalDistanceField.Heightfield

r.AOGlobalDistanceField.Heightfield

#Overview

name: r.AOGlobalDistanceField.Heightfield

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

• type: Var
• help: Whether to voxelize Heightfield into the global distance field.\n

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.AOGlobalDistanceField.Heightfield is to control whether Heightfield geometry is voxelized into the global distance field used for Ambient Occlusion (AO) calculations in Unreal Engine’s rendering system.

This setting variable is primarily used by the Renderer module of Unreal Engine, specifically in the global distance field computation subsystem. It’s part of the engine’s advanced rendering features, particularly affecting Ambient Occlusion calculations.

The value of this variable is set through the console variable system. It’s initialized with a default value of 1 (enabled) and can be changed at runtime using console commands or through configuration files.

The associated C++ variable GAOGlobalDistanceFieldHeightfield directly interacts with this setting. They share the same value, and GAOGlobalDistanceFieldHeightfield is used in the actual code logic to determine whether Heightfield voxelization should occur.

Developers must be aware that enabling this feature (setting to 1) will include Heightfield geometry in the global distance field calculations. This can affect performance and memory usage, especially in scenes with complex terrain or large Heightfield assets.

Best practices when using this variable include:

1. Consider disabling it (set to 0) if your scene doesn’t benefit from Heightfield-based AO or if performance is a concern.
2. Test the impact on performance and visual quality when enabling or disabling this feature.
3. Be mindful of the interaction between this setting and other global distance field related settings.

Regarding the associated variable GAOGlobalDistanceFieldHeightfield:

The purpose of GAOGlobalDistanceFieldHeightfield is to provide a C++ accessible representation of the r.AOGlobalDistanceField.Heightfield console variable.

It’s used directly in the Renderer module’s global distance field computation code to conditionally execute Heightfield voxelization and compositing into the global distance field.

The value of this variable is set by the console variable system when r.AOGlobalDistanceField.Heightfield is modified.

This variable directly controls the execution of Heightfield-related code in the global distance field update process. It’s checked in multiple places to determine whether Heightfield processing should occur.

Developers should be aware that this variable directly affects the behavior of the global distance field generation code. Changes to its value will immediately impact the rendering pipeline’s treatment of Heightfield geometry.

Best practices for using GAOGlobalDistanceFieldHeightfield include:

1. Avoid directly modifying this variable in C++ code. Instead, use the console variable system to ensure consistency.
2. When optimizing rendering performance, consider the impact of this variable on your specific use case.
3. In performance-critical code paths, cache the value of this variable locally to avoid repeated global variable access.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

int32 GAOGlobalDistanceFieldHeightfield = 1;
FAutoConsoleVariableRef CVarAOGlobalDistanceFieldHeightfield(
	TEXT("r.AOGlobalDistanceField.Heightfield"),
	GAOGlobalDistanceFieldHeightfield,
	TEXT("Whether to voxelize Heightfield into the global distance field.\n"),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GAOUpdateGlobalDistanceField = 1;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	);

int32 GAOGlobalDistanceFieldHeightfield = 1;
FAutoConsoleVariableRef CVarAOGlobalDistanceFieldHeightfield(
	TEXT("r.AOGlobalDistanceField.Heightfield"),
	GAOGlobalDistanceFieldHeightfield,
	TEXT("Whether to voxelize Heightfield into the global distance field.\n"),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GAOUpdateGlobalDistanceField = 1;
FAutoConsoleVariableRef CVarAOUpdateGlobalDistanceField(

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

Scope: file

Source code excerpt:

		// Composite Heightfields into pages
		if (GAOGlobalDistanceFieldHeightfield != 0)
		{
			const FRDGTextureUAVRef PageAtlasTextureUAV = PageAtlasTexture ? GraphBuilder.CreateUAV(PageAtlasTexture, ERDGUnorderedAccessViewFlags::SkipBarrier) : nullptr;
			const FRDGTextureUAVRef CoverageAtlasTextureUAV = CoverageAtlasTexture ? GraphBuilder.CreateUAV(CoverageAtlasTexture, ERDGUnorderedAccessViewFlags::SkipBarrier) : nullptr;

			for (const FGlobalDistanceFieldPackedClipmap& PackedClipmap : PackedClipmaps)
			{

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

Scope: file

Source code excerpt:

		// Composite heightfields into distance field object grid
		if (GAOGlobalDistanceFieldHeightfield != 0 && PageObjectGridBuffer)
		{
			const FRDGBufferUAVRef PageObjectGridBufferUAV = GraphBuilder.CreateUAV(PageObjectGridBuffer, ERDGUnorderedAccessViewFlags::SkipBarrier);

			for (const FGlobalDistanceFieldPackedClipmap& PackedClipmap : PackedClipmaps)
			{
				if (PackedClipmap.UpdateRegionHeightfield.ComponentDescriptions.Num() > 0)