r.AOGlobalDistanceField.MipFactor

r.AOGlobalDistanceField.MipFactor

#Overview

name: r.AOGlobalDistanceField.MipFactor

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.MipFactor is to control the resolution divider for the mip map of a distance field clipmap in the Ambient Occlusion (AO) Global Distance Field system.

This setting variable is primarily used in the rendering system, specifically in the Global Distance Field functionality of Unreal Engine 5. It is part of the Renderer module, as evidenced by its location in the GlobalDistanceField.cpp file within the Runtime/Renderer/Private directory.

The value of this variable is set through the console variable system (CVarAOGlobalDistanceFieldMipFactor) and is associated with the GAOGlobalDistanceFieldMipFactor variable. It’s initialized with a default value of 4.

The variable interacts directly with the GetMipFactor() function in the GlobalDistanceField class, where its value is clamped between 1 and 8. This function is then used in GetClipmapMipResolution() to calculate the mip resolution of the clipmap.

Developers must be aware that this variable affects the performance and quality trade-off in the Global Distance Field system. A higher value will result in lower resolution mip maps, potentially improving performance at the cost of visual quality.

Best practices when using this variable include:

  1. Adjusting it based on the target hardware capabilities and performance requirements.
  2. Testing different values to find the optimal balance between performance and visual quality for your specific use case.
  3. Considering the impact on memory usage, as lower mip factors will result in higher resolution mip maps and thus higher memory consumption.

Regarding the associated variable GAOGlobalDistanceFieldMipFactor:

This is an integer variable that directly stores the value set by the r.AOGlobalDistanceField.MipFactor console variable. It’s used internally in the engine code to actually apply the mip factor setting.

The GAOGlobalDistanceFieldMipFactor variable is accessed in the GetMipFactor() function of the GlobalDistanceField class, where it’s clamped to ensure it stays within a valid range (1 to 8).

Developers should be aware that modifying GAOGlobalDistanceFieldMipFactor directly in code is not recommended. Instead, they should use the console variable r.AOGlobalDistanceField.MipFactor to change this setting, as it ensures proper synchronization and allows for runtime adjustments.

Best practices for GAOGlobalDistanceFieldMipFactor include:

  1. Treating it as a read-only variable in most scenarios.
  2. Using the associated console variable for any modifications.
  3. Being aware of its impact on the Global Distance Field system when reading or using its value in custom rendering code.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

int32 GAOGlobalDistanceFieldMipFactor = 4;
FAutoConsoleVariableRef CVarAOGlobalDistanceFieldMipFactor(
	TEXT("r.AOGlobalDistanceField.MipFactor"),
	GAOGlobalDistanceFieldMipFactor,
	TEXT("Resolution divider for the mip map of a distance field clipmap."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GAOGlobalDistanceFieldRecacheClipmapsWithPendingStreaming = 1;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

int32 GAOGlobalDistanceFieldMipFactor = 4;
FAutoConsoleVariableRef CVarAOGlobalDistanceFieldMipFactor(
	TEXT("r.AOGlobalDistanceField.MipFactor"),
	GAOGlobalDistanceFieldMipFactor,
	TEXT("Resolution divider for the mip map of a distance field clipmap."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GAOGlobalDistanceFieldRecacheClipmapsWithPendingStreaming = 1;
FAutoConsoleVariableRef CVarAOGlobalDistanceFieldRecacheClipmapsWithPendingStreaming(

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

Scope (from outer to inner):

file
function     int32 GlobalDistanceField::GetMipFactor

Source code excerpt:

int32 GlobalDistanceField::GetMipFactor()
{
	return FMath::Clamp(GAOGlobalDistanceFieldMipFactor, 1, 8);
}

int32 GlobalDistanceField::GetClipmapMipResolution(bool bLumenEnabled)
{
	return FMath::DivideAndRoundUp(GlobalDistanceField::GetClipmapResolution(bLumenEnabled), GetMipFactor());
}