r.HFShadowAverageObjectsPerCullTile

r.HFShadowAverageObjectsPerCullTile

#Overview

name: r.HFShadowAverageObjectsPerCullTile

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.HFShadowAverageObjectsPerCullTile is to determine the memory allocation for height field object culling data structures in the distance field shadowing system. This setting is part of Unreal Engine’s rendering system, specifically for optimizing shadow rendering using height fields.

This setting variable is primarily used in the Renderer module of Unreal Engine, particularly in the distance field shadowing subsystem. It’s referenced in the DistanceFieldShadowing.cpp file, which is responsible for handling distance field-based shadow calculations.

The value of this variable is set through the Unreal Engine console variable system. It’s initialized with a default value of 16 and can be modified at runtime using the console command “r.HFShadowAverageObjectsPerCullTile”.

This variable interacts closely with GAverageHeightFieldObjectsPerShadowCullTile, which is the associated C++ variable that shares the same value. It’s also used in conjunction with GAverageObjectsPerShadowCullTile for non-height field objects.

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

Best practices when using this variable include:

  1. Monitoring memory usage and adjusting the value based on the specific needs of the scene.
  2. Balancing between memory efficiency and visual quality.
  3. Testing with different values to find the optimal setting for specific scenes or use cases.
  4. Considering the target hardware capabilities when setting this value.

Regarding the associated variable GAverageHeightFieldObjectsPerShadowCullTile:

The purpose of GAverageHeightFieldObjectsPerShadowCullTile is to store the actual value used in the engine’s C++ code for memory allocation in height field object culling data structures.

This variable is used in the Renderer module, specifically in the distance field shadowing system. It’s defined in DistanceFieldShadowing.cpp and referenced in DistanceFieldLightingShared.h.

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

It interacts with the MaxNumObjectsPerTile variable in the CullDistanceFieldObjectsForLight function, determining the size of the ShadowTileArrayData buffer.

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

Best practices for this variable include:

  1. Using the console variable r.HFShadowAverageObjectsPerCullTile to modify its value rather than changing the C++ code directly.
  2. Considering its impact on memory allocation and performance when optimizing rendering.
  3. Using it in conjunction with other distance field shadowing parameters 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:120

Scope: file

Source code excerpt:

int32 GAverageHeightFieldObjectsPerShadowCullTile = 16;
FAutoConsoleVariableRef CVarAverageHeightFieldObjectsPerShadowCullTile(
	TEXT("r.HFShadowAverageObjectsPerCullTile"),
	GAverageHeightFieldObjectsPerShadowCullTile,
	TEXT("Determines how much memory should be allocated in height field object culling data structures.  Too much = memory waste, too little = flickering due to buffer overflow."),
	ECVF_RenderThreadSafe | ECVF_ReadOnly);

int32 GDFShadowCompactCulledObjects = 1;
static FAutoConsoleVariableRef CVarCompactCulledObjects(

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

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:118

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

int32 GAverageHeightFieldObjectsPerShadowCullTile = 16;
FAutoConsoleVariableRef CVarAverageHeightFieldObjectsPerShadowCullTile(
	TEXT("r.HFShadowAverageObjectsPerCullTile"),
	GAverageHeightFieldObjectsPerShadowCullTile,
	TEXT("Determines how much memory should be allocated in height field object culling data structures.  Too much = memory waste, too little = flickering due to buffer overflow."),
	ECVF_RenderThreadSafe | ECVF_ReadOnly);

int32 GDFShadowCompactCulledObjects = 1;
static FAutoConsoleVariableRef CVarCompactCulledObjects(
	TEXT("r.DFShadowCompactCulledObjects"),

#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;