r.DFShadowAverageObjectsPerCullTile

r.DFShadowAverageObjectsPerCullTile

#Overview

name: r.DFShadowAverageObjectsPerCullTile

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.DFShadowAverageObjectsPerCullTile is to control the memory allocation for distance field object culling data structures in the shadow rendering system of Unreal Engine 5.

This setting variable is primarily used in the rendering system, specifically for distance field shadowing. It is part of the Renderer module in Unreal Engine 5.

The value of this variable is set through the Unreal Engine console system, as evidenced by the FAutoConsoleVariableRef declaration. It’s initialized with a default value of 128.

This console variable interacts directly with the associated variable GAverageObjectsPerShadowCullTile. They share the same value, and changes to the console variable will affect the associated variable.

Developers must be aware that this variable affects memory usage and rendering quality. Setting it too high may result in memory waste, while setting it too low could cause flickering due to buffer overflow.

Best practices when using this variable include:

  1. Adjusting it based on the specific needs of your scene and the number of objects typically present.
  2. Monitoring performance and visual quality when changing this value.
  3. Finding a balance between memory usage and visual stability.

Regarding the associated variable GAverageObjectsPerShadowCullTile:

The purpose of GAverageObjectsPerShadowCullTile is to store the actual value used in the rendering calculations for the average number of objects per shadow cull tile.

This variable is used directly in the rendering code, specifically in the CullDistanceFieldObjectsForLight function, to determine the size of buffer allocations for shadow tile array data.

The value of this variable is set by the r.DFShadowAverageObjectsPerCullTile console variable.

It interacts with other variables like GAverageHeightFieldObjectsPerShadowCullTile when dealing with heightfield objects.

Developers should be aware that this variable directly affects memory allocation in the rendering pipeline. Changes to this value will impact both performance and visual quality.

Best practices for using this variable include:

  1. Monitoring its value in relation to the console variable to ensure they remain in sync.
  2. Considering its impact on memory usage when optimizing rendering performance.
  3. Adjusting it in conjunction with other related variables for optimal results.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DistanceFieldShadowing.cpp:83

Scope: file

Source code excerpt:

int32 GAverageObjectsPerShadowCullTile = 128;
FAutoConsoleVariableRef CVarAverageObjectsPerShadowCullTile(
	TEXT("r.DFShadowAverageObjectsPerCullTile"),
	GAverageObjectsPerShadowCullTile,
	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
	);

int32 GDFShadowAsyncCompute = 0;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DistanceFieldLightingShared.h:26

Scope: file

Source code excerpt:

extern int32 GDistanceFieldAOTileSizeX;
extern int32 GDistanceFieldAOTileSizeY;
extern int32 GAverageObjectsPerShadowCullTile;
extern int32 GAverageHeightFieldObjectsPerShadowCullTile;

extern bool UseDistanceFieldAO();
extern bool UseAOObjectDistanceField();

enum EDistanceFieldPrimitiveType

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DistanceFieldShadowing.cpp:81

Scope: file

Source code excerpt:

	);

int32 GAverageObjectsPerShadowCullTile = 128;
FAutoConsoleVariableRef CVarAverageObjectsPerShadowCullTile(
	TEXT("r.DFShadowAverageObjectsPerCullTile"),
	GAverageObjectsPerShadowCullTile,
	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
	);

int32 GDFShadowAsyncCompute = 0;
static FAutoConsoleVariableRef CVarDFShadowAsyncCompute(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DistanceFieldShadowing.cpp:632

Scope (from outer to inner):

file
function     void CullDistanceFieldObjectsForLight

Source code excerpt:

		LightTileIntersectionParameters.ShadowTileNumCulledObjects = GraphBuilder.CreateSRV(ShadowTileNumCulledObjects, PF_R32_UINT);

		const uint32 MaxNumObjectsPerTile = bIsHeightfield ? GAverageHeightFieldObjectsPerShadowCullTile : GAverageObjectsPerShadowCullTile;
		FRDGBufferRef ShadowTileArrayData = GraphBuilder.CreateBuffer(FRDGBufferDesc::CreateBufferDesc(b16BitObjectIndices ? sizeof(uint16) : sizeof(uint32), MaxNumObjectsPerTile * LightTileDimensions.X * LightTileDimensions.Y), TEXT("ShadowTileArrayData"));
		LightTileIntersectionParameters.RWShadowTileArrayData = GraphBuilder.CreateUAV(ShadowTileArrayData, b16BitObjectIndices ? PF_R16_UINT : PF_R32_UINT);
		LightTileIntersectionParameters.ShadowTileArrayData = GraphBuilder.CreateSRV(ShadowTileArrayData, b16BitObjectIndices ? PF_R16_UINT : PF_R32_UINT);
		LightTileIntersectionParameters.ShadowTileListGroupSize = LightTileDimensions;
		LightTileIntersectionParameters.ShadowMaxObjectsPerTile = MaxNumObjectsPerTile;