r.SceneCulling.MinCellSize

r.SceneCulling.MinCellSize

#Overview

name: r.SceneCulling.MinCellSize

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.SceneCulling.MinCellSize is to set the minimum cell size for the scene culling hierarchy in Unreal Engine 5’s rendering system. This setting is crucial for optimizing the scene culling process, which is responsible for determining which objects should be rendered in a given frame.

This setting variable is primarily used by the Renderer subsystem, specifically within the scene culling module. It’s also referenced in the Engine module, particularly in the Instanced Static Mesh component.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 4096.0f, but can be modified at runtime through console commands or configuration files.

The r.SceneCulling.MinCellSize interacts with other variables in the scene culling system, particularly with a maximum cell size variable (referenced as CVarSceneCullingMaxCellSize in the code).

Developers should be aware that this variable is currently marked as read-only (ECVF_ReadOnly flag). This means that while it can be set initially, there’s no implementation to rebuild the entire culling structure if the value changes during runtime.

Best practices for using this variable include:

  1. Carefully consider the trade-off between culling effectiveness and construction cost/memory use when adjusting this value.
  2. Be aware that this value affects the precomputation of keys for static Instanced Static Meshes (ISMs).
  3. Remember that changes to this value may not take effect immediately due to its read-only nature.

Regarding the associated variable CVarSceneCullingMinCellSize:

The purpose of CVarSceneCullingMinCellSize is to provide a programmatic interface to the r.SceneCulling.MinCellSize setting. It’s an auto console variable that directly corresponds to the r.SceneCulling.MinCellSize setting.

This variable is used in the Renderer subsystem, specifically in the scene culling initialization and the spatial hash construction for Instanced Static Meshes.

The value of CVarSceneCullingMinCellSize is set at the same time as r.SceneCulling.MinCellSize, as they represent the same setting.

CVarSceneCullingMinCellSize interacts with the scene culling system and the Instanced Static Mesh rendering system.

Developers should be aware that this variable provides a way to access the minimum cell size setting programmatically within C++ code.

Best practices for using CVarSceneCullingMinCellSize include:

  1. Use GetValueOnAnyThread() when accessing the value, as shown in the provided code snippets.
  2. Be cautious about changing this value at runtime, as the culling structure may not update immediately.
  3. Consider the impact on performance and memory usage when modifying this value.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneCulling/SceneCulling.cpp:134

Scope: file

Source code excerpt:


static TAutoConsoleVariable<float> CVarSceneCullingMinCellSize(
	TEXT("r.SceneCulling.MinCellSize"), 
	4096.0f, 
	TEXT("Set the minimum cell size & level in the hierarchy, rounded to nearest POT. Clamps the level for object footprints.\n")
	TEXT("  This trades culling effectiveness for construction cost and memory use.\n")
	TEXT("  The minimum cell size is (will be) used for precomputing the key for static ISMs.\n")
	TEXT("  Currently read-only as there is implementation to rebuild the whole structure on a change.\n"),
	ECVF_RenderThreadSafe | ECVF_ReadOnly);

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/InstancedStaticMesh/ISMInstanceDataManager.cpp:1128

Scope (from outer to inner):

file
class        class FSpatialHashSortBuilder
function     void BuildOptimizedSpatialHashOrder

Source code excerpt:

		int32 FirstLevel = 0;
		{
			static const auto CVarInstanceHierarchyMinCellSize = IConsoleManager::Get().FindTConsoleVariableDataFloat(TEXT("r.SceneCulling.MinCellSize"));
			if (CVarInstanceHierarchyMinCellSize)
			{
				// TODO: only one code path to compute this value!!!
				FirstLevel = RenderingSpatialHash::CalcLevel(CVarInstanceHierarchyMinCellSize->GetValueOnAnyThread() - 1.0);
			}
		}

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneCulling/SceneCulling.cpp:133

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<float> CVarSceneCullingMinCellSize(
	TEXT("r.SceneCulling.MinCellSize"), 
	4096.0f, 
	TEXT("Set the minimum cell size & level in the hierarchy, rounded to nearest POT. Clamps the level for object footprints.\n")
	TEXT("  This trades culling effectiveness for construction cost and memory use.\n")
	TEXT("  The minimum cell size is (will be) used for precomputing the key for static ISMs.\n")
	TEXT("  Currently read-only as there is implementation to rebuild the whole structure on a change.\n"),

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneCulling/SceneCulling.cpp:2627

Scope (from outer to inner):

file
function     FSceneCulling::FSceneCulling

Source code excerpt:

	: Scene(InScene)
	, bIsEnabled(UseSceneCulling(Scene.GetShaderPlatform()))
	, SpatialHash( CVarSceneCullingMinCellSize.GetValueOnAnyThread(), CVarSceneCullingMaxCellSize.GetValueOnAnyThread())
	, CellHeadersBuffer(16, TEXT("SceneCulling.CellHeaders"))
	, ItemChunksBuffer(16, TEXT("SceneCulling.ItemChunks"))
	, InstanceIdsBuffer(16, TEXT("SceneCulling.Items"))
	, CellBlockDataBuffer(16, TEXT("SceneCulling.CellBlockData"))
	, ExplicitCellBoundsBuffer(16, TEXT("SceneCulling.ExplicitCellBounds"))
{