r.AOAverageObjectsPerCullTile

r.AOAverageObjectsPerCullTile

#Overview

name: r.AOAverageObjectsPerCullTile

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.AOAverageObjectsPerCullTile is to control the memory allocation for distance field object culling data structures in Unreal Engine’s rendering system. It specifically determines the average number of distance field objects expected per cull tile.

This setting variable is primarily used by the rendering subsystem, particularly in the distance field ambient occlusion (AO) and object culling modules. Based on the callsites, it’s utilized in the DistanceFieldObjectCulling.cpp and DistanceFieldAmbientOcclusion.cpp files, which are part of the Renderer module.

The value of this variable is set through the Unreal Engine console variable system, as evidenced by the FAutoConsoleVariableRef declaration. It can be adjusted at runtime, but it’s marked as read-only for the render thread, meaning changes will only take effect after a certain delay.

The associated variable GAverageDistanceFieldObjectsPerCullTile directly interacts with r.AOAverageObjectsPerCullTile. They share the same value, with GAverageDistanceFieldObjectsPerCullTile being the actual integer variable used in the code.

Developers must be aware that this variable affects memory allocation. Setting it too high can result in memory waste, while setting it too low can cause visual flickering due to buffer overflow. The default value is 512, which should be a good starting point for most scenarios.

Best practices when using this variable include:

  1. Monitor performance and memory usage when adjusting this value.
  2. Increase the value if you notice flickering in scenes with many objects.
  3. Decrease the value if memory usage is unnecessarily high and you’re not experiencing any visual artifacts.
  4. Consider the complexity and object density of your scenes when tuning this value.

Regarding the associated variable GAverageDistanceFieldObjectsPerCullTile:

The purpose of GAverageDistanceFieldObjectsPerCullTile is to serve as the actual integer variable that stores the value set by r.AOAverageObjectsPerCullTile. It’s used directly in the code for memory allocation calculations.

This variable is used in the same subsystems as r.AOAverageObjectsPerCullTile, namely the rendering system’s distance field ambient occlusion and object culling modules.

Its value is set indirectly through r.AOAverageObjectsPerCullTile via the console variable system.

GAverageDistanceFieldObjectsPerCullTile directly interacts with buffer allocation sizes, particularly in the AllocateTileIntersectionBuffers function.

Developers should be aware that modifying this variable directly in the code is not recommended, as it’s meant to be controlled through the console variable system.

Best practices for GAverageDistanceFieldObjectsPerCullTile are the same as for r.AOAverageObjectsPerCullTile, focusing on balancing memory usage and visual quality.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

int32 GAverageDistanceFieldObjectsPerCullTile = 512;
FAutoConsoleVariableRef CVarMaxDistanceFieldObjectsPerCullTile(
	TEXT("r.AOAverageObjectsPerCullTile"),
	GAverageDistanceFieldObjectsPerCullTile,
	TEXT("Determines how much memory should be allocated in distance field object culling data structures.  Too much = memory waste, too little = flickering due to buffer overflow."),
	ECVF_RenderThreadSafe | ECVF_ReadOnly
	);

class FCullObjectsForViewCS : public FGlobalShader

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DistanceFieldAmbientOcclusion.cpp:646

Scope (from outer to inner):

file
function     void AllocateTileIntersectionBuffers

Source code excerpt:

	OutParameters.CulledTilesStartOffsetArray = GraphBuilder.CreateSRV(CulledTilesStartOffsetArray);

	extern int32 GAverageDistanceFieldObjectsPerCullTile;

	FRDGBufferRef CulledTileDataArray = GraphBuilder.CreateBuffer(
		FRDGBufferDesc::CreateBufferDesc(b16BitCulledTileIndexBuffer ? sizeof(uint16) : sizeof(uint32), GAverageDistanceFieldObjectsPerCullTile * TileCount * CulledTileDataStride),
		TEXT("CulledTileDataArray"));
	OutParameters.RWCulledTileDataArray = GraphBuilder.CreateUAV(CulledTileDataArray, b16BitCulledTileIndexBuffer ? PF_R16_UINT : PF_R32_UINT);
	OutParameters.CulledTileDataArray = GraphBuilder.CreateSRV(CulledTileDataArray, b16BitCulledTileIndexBuffer ? PF_R16_UINT : PF_R32_UINT);

	OutObjectTilesIndirectArguments = GraphBuilder.CreateBuffer(FRDGBufferDesc::CreateIndirectDesc<FRHIDispatchIndirectParameters>(), TEXT("ObjectTilesIndirectArguments"));
	OutParameters.RWObjectTilesIndirectArguments = GraphBuilder.CreateUAV(OutObjectTilesIndirectArguments, PF_R32_UINT);

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

Scope: file

Source code excerpt:

	);

int32 GAverageDistanceFieldObjectsPerCullTile = 512;
FAutoConsoleVariableRef CVarMaxDistanceFieldObjectsPerCullTile(
	TEXT("r.AOAverageObjectsPerCullTile"),
	GAverageDistanceFieldObjectsPerCullTile,
	TEXT("Determines how much memory should be allocated in distance field object culling data structures.  Too much = memory waste, too little = flickering due to buffer overflow."),
	ECVF_RenderThreadSafe | ECVF_ReadOnly
	);

class FCullObjectsForViewCS : public FGlobalShader
{