r.AOGlobalDistanceField.NumClipmaps

r.AOGlobalDistanceField.NumClipmaps

#Overview

name: r.AOGlobalDistanceField.NumClipmaps

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

• type: Var
• help: Num clipmaps in the global distance field. Setting this to anything other than 4 is currently only supported by Lumen.

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.AOGlobalDistanceField.NumClipmaps is to control the number of clipmaps in the global distance field, which is a crucial component of the rendering system in Unreal Engine 5, particularly for ambient occlusion and global illumination effects.

This setting variable is primarily used in the Renderer module of Unreal Engine 5, specifically within the global distance field and distance field streaming subsystems. It’s particularly important for the Lumen global illumination system.

The value of this variable is set through a console variable (CVar) system, which allows it to be adjusted at runtime. It’s initialized with a default value of 4, but can be changed using the console command or through engine configuration files.

The associated variable GAOGlobalDistanceFieldNumClipmaps directly interacts with r.AOGlobalDistanceField.NumClipmaps. They share the same value, with GAOGlobalDistanceFieldNumClipmaps being the actual integer variable used in the C++ code.

Developers must be aware that changing this value to anything other than 4 is currently only fully supported by the Lumen system. Modifying this value can have significant impacts on rendering performance and quality, as it directly affects the resolution and extent of the global distance field.

Best practices when using this variable include:

1. Keeping it at the default value of 4 unless specifically needed for Lumen.
2. When adjusting, consider the performance implications, as more clipmaps will require more memory and processing power.
3. Test thoroughly across different hardware configurations when changing this value, as its impact may vary depending on the system specifications.

Regarding the associated variable GAOGlobalDistanceFieldNumClipmaps:

The purpose of GAOGlobalDistanceFieldNumClipmaps is to store and provide access to the number of clipmaps in the global distance field within the C++ code of the engine.

This variable is used in various parts of the rendering system, including distance field streaming and global distance field generation. It’s particularly important in determining the extent of clipmaps and in setting up rendering parameters.

The value of GAOGlobalDistanceFieldNumClipmaps is set by the CVar system, mirroring the value of r.AOGlobalDistanceField.NumClipmaps.

It interacts closely with other rendering parameters, such as those used in distance field streaming and global distance field generation.

Developers should be aware that this variable is used in performance-critical rendering code, and its value can affect both rendering quality and performance.

Best practices include:

1. Avoid directly modifying this variable in code; instead, use the CVar system to ensure consistency.
2. When reading this value, be aware of the rendering thread safety implications, as it’s marked with ECVF_RenderThreadSafe.
3. Consider the cascading effects of this value on other parts of the rendering system when making adjustments.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

int32 GAOGlobalDistanceFieldNumClipmaps = 4;
FAutoConsoleVariableRef CVarAOGlobalDistanceFieldNumClipmaps(
	TEXT("r.AOGlobalDistanceField.NumClipmaps"), 
	GAOGlobalDistanceFieldNumClipmaps,
	TEXT("Num clipmaps in the global distance field.  Setting this to anything other than 4 is currently only supported by Lumen."),
	ECVF_Scalability | ECVF_RenderThreadSafe
	);

int32 GAOGlobalDistanceFieldHeightfield = 1;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DistanceFieldStreaming.cpp:1239

Scope (from outer to inner):

file
function     void FDistanceFieldSceneData::GenerateStreamingRequests

Source code excerpt:

			PassParameters->DistanceFieldObjectBuffers = DistanceField::SetupObjectBufferParameters(GraphBuilder, *this);
			PassParameters->DebugForceNumMips = FMath::Clamp(CVarDebugForceNumMips.GetValueOnRenderThread(), 0, DistanceField::NumMips);
			extern int32 GAOGlobalDistanceFieldNumClipmaps;
			// Request Mesh SDF mips based off of the Global SDF clipmaps
			PassParameters->Mip1WorldTranslatedCenter = FVector3f(View.ViewMatrices.GetViewOrigin() + View.ViewMatrices.GetPreViewTranslation());
			PassParameters->Mip1WorldExtent = FVector3f(GlobalDistanceField::GetClipmapExtent(GAOGlobalDistanceFieldNumClipmaps - 1, Scene, bLumenEnabled));
			PassParameters->Mip2WorldTranslatedCenter = FVector3f(View.ViewMatrices.GetViewOrigin() + View.ViewMatrices.GetPreViewTranslation());
			PassParameters->Mip2WorldExtent = FVector3f(GlobalDistanceField::GetClipmapExtent(FMath::Max<int32>(GAOGlobalDistanceFieldNumClipmaps / 2 - 1, 0), Scene, bLumenEnabled));
			PassParameters->PreViewTranslationHigh = PreViewTranslation.High;
			PassParameters->PreViewTranslationLow = PreViewTranslation.Low;

			auto ComputeShader = GlobalShaderMap->GetShader<FComputeDistanceFieldAssetWantedMipsCS>();

			FComputeShaderUtils::AddPass(

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

Scope: file

Source code excerpt:

);

int32 GAOGlobalDistanceFieldNumClipmaps = 4;
FAutoConsoleVariableRef CVarAOGlobalDistanceFieldNumClipmaps(
	TEXT("r.AOGlobalDistanceField.NumClipmaps"), 
	GAOGlobalDistanceFieldNumClipmaps,
	TEXT("Num clipmaps in the global distance field.  Setting this to anything other than 4 is currently only supported by Lumen."),
	ECVF_Scalability | ECVF_RenderThreadSafe
	);

int32 GAOGlobalDistanceFieldHeightfield = 1;
FAutoConsoleVariableRef CVarAOGlobalDistanceFieldHeightfield(

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

Scope (from outer to inner):

file
function     int32 GlobalDistanceField::GetNumGlobalDistanceFieldClipmaps

Source code excerpt:

int32 GlobalDistanceField::GetNumGlobalDistanceFieldClipmaps(bool bLumenEnabled, float LumenSceneViewDistance)
{
	int32 WantedClipmaps = GAOGlobalDistanceFieldNumClipmaps;

	if (bLumenEnabled)
	{
		if (GlobalDistanceField::GetClipmapExtent(WantedClipmaps + 1, nullptr, true) <= LumenSceneViewDistance)
		{
			WantedClipmaps += 2;