r.AOGlobalDistanceField.OccupancyRatio

r.AOGlobalDistanceField.OccupancyRatio

#Overview

name: r.AOGlobalDistanceField.OccupancyRatio

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

• type: Var
• help: Expected sparse global distacne field occupancy for the page atlas allocation. 0.25 means 25% - filled and 75% - empty.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.AOGlobalDistanceField.OccupancyRatio is to control the expected sparse global distance field occupancy for the page atlas allocation in Unreal Engine’s rendering system. This setting is specifically related to the Global Distance Field feature, which is used in various rendering techniques, including Ambient Occlusion (AO).

This setting variable is primarily used in the Renderer module of Unreal Engine, specifically within the Global Distance Field subsystem. Based on the callsites, it’s clear that this variable is utilized in the GlobalDistanceField.cpp file.

The value of this variable is set through the console variable system in Unreal Engine. It’s initialized with a default value of 0.3f (30% occupancy) and can be modified at runtime using console commands or through engine configuration files.

The associated variable GGlobalDistanceFieldOccupancyRatio directly interacts with r.AOGlobalDistanceField.OccupancyRatio. They share the same value, with GGlobalDistanceFieldOccupancyRatio being the actual float variable used in the C++ code.

Developers must be aware of the following when using this variable:

1. The value represents a ratio, where 0.25 means 25% filled and 75% empty.
2. It affects memory allocation for the Global Distance Field page atlas.
3. It’s marked with ECVF_Scalability and ECVF_RenderThreadSafe flags, indicating it can be adjusted for different scalability settings and is safe to modify from the render thread.

Best practices when using this variable include:

1. Adjusting it based on the specific needs of your scene. Scenes with more complex geometry might require a higher occupancy ratio.
2. Monitoring performance and memory usage when modifying this value, as it directly impacts the memory allocated for the Global Distance Field.
3. Keeping the value within a reasonable range. The code clamps it between 0.1f and 1.0f when used in calculations.

Regarding the associated variable GGlobalDistanceFieldOccupancyRatio:

• Its purpose is to provide a C++ accessible float value that mirrors the console variable setting.
• It’s used directly in the GetPageAtlasSizeInPages function to calculate the required number of pages for the Global Distance Field.
• Developers should be aware that modifying this variable directly in C++ code will not update the console variable. It’s best to use the console variable system to ensure consistency.
• When reading this value in C++ code, it’s recommended to use FMath::Clamp to ensure it stays within the 0.1f to 1.0f range, as demonstrated in the provided code excerpt.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

float GGlobalDistanceFieldOccupancyRatio = 0.3f;
FAutoConsoleVariableRef CVarAOGlobalDistanceFieldOccupancyRatio(
	TEXT("r.AOGlobalDistanceField.OccupancyRatio"),
	GGlobalDistanceFieldOccupancyRatio,
	TEXT("Expected sparse global distacne field occupancy for the page atlas allocation. 0.25 means 25% - filled and 75% - empty."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GAOGlobalDistanceFieldNumClipmaps = 4;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	);

float GGlobalDistanceFieldOccupancyRatio = 0.3f;
FAutoConsoleVariableRef CVarAOGlobalDistanceFieldOccupancyRatio(
	TEXT("r.AOGlobalDistanceField.OccupancyRatio"),
	GGlobalDistanceFieldOccupancyRatio,
	TEXT("Expected sparse global distacne field occupancy for the page atlas allocation. 0.25 means 25% - filled and 75% - empty."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GAOGlobalDistanceFieldNumClipmaps = 4;
FAutoConsoleVariableRef CVarAOGlobalDistanceFieldNumClipmaps(

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

Scope (from outer to inner):

file
function     FIntVector GlobalDistanceField::GetPageAtlasSizeInPages

Source code excerpt:

		PageTableTextureResolution.X * PageTableTextureResolution.Y * PageTableTextureResolution.Z 
		* (GAOGlobalDistanceFieldCacheMostlyStaticSeparately ? 2 : 1)
		* FMath::Clamp(GGlobalDistanceFieldOccupancyRatio, 0.1f, 1.0f));

	const int32 RequiredNumberOfPagesInZ = FMath::DivideAndRoundUp(RequiredNumberOfPages, GlobalDistanceField::PageAtlasSizeInPagesX * GlobalDistanceField::PageAtlasSizeInPagesY);

	const FIntVector PageAtlasTextureSizeInPages = FIntVector(
		GlobalDistanceField::PageAtlasSizeInPagesX,
		GlobalDistanceField::PageAtlasSizeInPagesY,