r.AOGlobalDistanceField.AverageCulledObjectsPerCell

r.AOGlobalDistanceField.AverageCulledObjectsPerCell

#Overview

name: r.AOGlobalDistanceField.AverageCulledObjectsPerCell

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

• type: Var
• help: Average expected number of objects per cull grid cell, used to preallocate memory for the cull grid.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.AOGlobalDistanceField.AverageCulledObjectsPerCell is to set the average expected number of objects per cull grid cell in the Ambient Occlusion (AO) Global Distance Field system. This setting is used to preallocate memory for the cull grid, which is a part of the rendering system in Unreal Engine 5.

This setting variable is primarily used in the Renderer module of Unreal Engine 5, specifically within the Global Distance Field system. The Global Distance Field is a key component of the engine’s rendering pipeline, used for various effects including ambient occlusion.

The value of this variable is set through a console variable (CVarAOGlobalDistanceFieldAverageCulledObjectsPerCell) with a default value of 512. It can be modified at runtime through console commands or project settings.

The associated variable CVarAOGlobalDistanceFieldAverageCulledObjectsPerCell directly interacts with this setting. They share the same value and purpose.

Developers must be aware that this variable affects memory allocation for the cull grid. Setting it too low might result in insufficient memory allocation, while setting it too high could waste memory. It’s important to balance this setting based on the scene complexity and available memory.

Best practices when using this variable include:

1. Adjusting it based on the average scene complexity in your game.
2. Monitoring performance and memory usage when changing this value.
3. Consider scaling this value based on the target platform’s capabilities.

Regarding the associated variable CVarAOGlobalDistanceFieldAverageCulledObjectsPerCell:

• Its purpose is identical to r.AOGlobalDistanceField.AverageCulledObjectsPerCell.
• It’s used in the Renderer module, specifically in the Global Distance Field system.
• The value is set when the console variable is initialized and can be modified at runtime.
• It directly interacts with r.AOGlobalDistanceField.AverageCulledObjectsPerCell, sharing the same value.
• Developers should be aware that this is the actual variable used in the code to retrieve the setting’s value.
• Best practices include using this variable to read the current setting value in C++ code, rather than directly accessing the r.AOGlobalDistanceField.AverageCulledObjectsPerCell setting.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarAOGlobalDistanceFieldAverageCulledObjectsPerCell(
	TEXT("r.AOGlobalDistanceField.AverageCulledObjectsPerCell"),
	512,
	TEXT("Average expected number of objects per cull grid cell, used to preallocate memory for the cull grid."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GAOGlobalDistanceFieldMipFactor = 4;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarAOGlobalDistanceFieldAverageCulledObjectsPerCell(
	TEXT("r.AOGlobalDistanceField.AverageCulledObjectsPerCell"),
	512,
	TEXT("Average expected number of objects per cull grid cell, used to preallocate memory for the cull grid."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

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

Scope (from outer to inner):

file
function     class FInitPageFreeListCS : public FGlobalShader { /*ARE_GLOBAL_SHADER
class        class FInitPageFreeListCS : public FGlobalShader
function     for

Source code excerpt:

		for (FGlobalDistanceFieldPackedClipmap& PackedClipmap : PackedClipmaps)
		{
			const uint32 AverageCulledObjectsPerPage = FMath::Clamp(CVarAOGlobalDistanceFieldAverageCulledObjectsPerCell.GetValueOnRenderThread(), 1, 8192);
			PackedClipmap.CullGridAllocator = GraphBuilder.CreateBuffer(FRDGBufferDesc::CreateStructuredDesc(sizeof(uint32), 1), TEXT("GlobalDistanceField.CullGridAllocator"));
			PackedClipmap.CullGridObjectHeader = GraphBuilder.CreateBuffer(FRDGBufferDesc::CreateStructuredDesc(sizeof(uint32), 2 * PackedClipmap.CullGridSize), TEXT("GlobalDistanceField.CullGridObjectHeader"));
			PackedClipmap.CullGridObjectArray = GraphBuilder.CreateBuffer(FRDGBufferDesc::CreateStructuredDesc(sizeof(uint32), PackedClipmap.CullGridSize * AverageCulledObjectsPerPage), TEXT("GlobalDistanceField.CullGridObjectArray"));

			AddClearUAVPass(GraphBuilder, GraphBuilder.CreateUAV(PackedClipmap.CullGridAllocator, PF_R32_UINT), 0);
			AddClearUAVPass(GraphBuilder, GraphBuilder.CreateUAV(PackedClipmap.CullGridObjectHeader, PF_R32_UINT), 0);