r.ISMPool.ComponentRecycle

r.ISMPool.ComponentRecycle

#Overview

name: r.ISMPool.ComponentRecycle

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.ISMPool.ComponentRecycle is to control the recycling behavior of Instanced Static Mesh (ISM) components in the Unreal Engine’s Geometry Collection system. This setting variable is primarily used for optimizing memory management and performance in scenarios involving dynamic geometry collections.

This setting variable is primarily used in the Geometry Collection Engine module, which is part of Unreal Engine’s experimental features for handling large numbers of dynamic objects efficiently.

The value of this variable is set through the Unreal Engine’s console variable system. It can be modified at runtime using console commands or through configuration files.

The associated variable GComponentRecycle directly interacts with r.ISMPool.ComponentRecycle. They share the same value, and GComponentRecycle is used within the C++ code to control the recycling behavior.

Developers must be aware that enabling this variable (which is the default behavior) will cause ISM components to be recycled to a free list for reuse when all their instances are removed. This can lead to improved performance and memory usage in scenarios with frequently changing geometry collections.

Best practices when using this variable include:

  1. Leaving it enabled (default) for most use cases to benefit from component recycling.
  2. Monitoring performance and memory usage in scenarios with heavy use of geometry collections.
  3. Consider disabling it if you encounter unexpected behavior or if your specific use case doesn’t benefit from component recycling.

Regarding the associated variable GComponentRecycle:

The purpose of GComponentRecycle is to serve as the internal representation of the r.ISMPool.ComponentRecycle setting within the C++ code.

It is used directly in the GeometryCollectionISMPoolComponent to control the recycling behavior of ISM components.

The value of GComponentRecycle is set by the console variable system and is cached in the FGeometryCollectionISMPool class for efficient access.

GComponentRecycle interacts closely with another variable, GComponentKeepAlive, which controls whether components are kept alive even when empty.

Developers should be aware that changes to GComponentRecycle (via r.ISMPool.ComponentRecycle) may affect performance and memory usage, especially in scenarios with frequent creation and destruction of geometry collection instances.

Best practices for GComponentRecycle include:

  1. Avoiding direct modification of GComponentRecycle in code; instead, use the console variable r.ISMPool.ComponentRecycle to change its value.
  2. Considering the interaction between GComponentRecycle and GComponentKeepAlive when optimizing geometry collection performance.
  3. Profiling your application with different settings to determine the optimal configuration for your specific use case.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/GeometryCollectionEngine/Private/GeometryCollection/GeometryCollectionISMPoolComponent.cpp:25

Scope: file

Source code excerpt:

static bool GComponentRecycle = true;
FAutoConsoleVariableRef CVarISMPoolComponentRecycle(
	TEXT("r.ISMPool.ComponentRecycle"),
	GComponentRecycle,
	TEXT("Recycle ISM components to a free list for reuse when all their instances are removed."));

// Target free list size when recycling ISM components.
// We try to maintain a pool of free components for fast allocation, but want to clean up when numbers get too high.
static int32 GComponentFreeListTargetSize = 50;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/GeometryCollectionEngine/Private/GeometryCollection/GeometryCollectionISMPoolComponent.cpp:23

Scope: file

Source code excerpt:

// But there is more CPU cost to recycling a component then to simply keeping it alive because scene proxy creation and mesh draw command caching isn't cheap.
// The component memory cost is kept bounded when compared to keeping components alive.
static bool GComponentRecycle = true;
FAutoConsoleVariableRef CVarISMPoolComponentRecycle(
	TEXT("r.ISMPool.ComponentRecycle"),
	GComponentRecycle,
	TEXT("Recycle ISM components to a free list for reuse when all their instances are removed."));

// Target free list size when recycling ISM components.
// We try to maintain a pool of free components for fast allocation, but want to clean up when numbers get too high.
static int32 GComponentFreeListTargetSize = 50;
FAutoConsoleVariableRef CVarISMPoolComponentFreeListTargetSize(

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/GeometryCollectionEngine/Private/GeometryCollection/GeometryCollectionISMPoolComponent.cpp:242

Scope (from outer to inner):

file
function     FGeometryCollectionISMPool::FGeometryCollectionISMPool

Source code excerpt:

FGeometryCollectionISMPool::FGeometryCollectionISMPool()
	: bCachedKeepAlive(GComponentKeepAlive)
	, bCachedRecycle(GComponentRecycle)
{
}

FGeometryCollectionISMPool::FISMIndex FGeometryCollectionISMPool::GetOrAddISM(UGeometryCollectionISMPoolComponent* OwningComponent, const FGeometryCollectionStaticMeshInstance& MeshInstance, bool& bOutISMCreated)
{
	FISMIndex* ISMIndexPtr = MeshToISMIndex.Find(MeshInstance);

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/GeometryCollectionEngine/Private/GeometryCollection/GeometryCollectionISMPoolComponent.cpp:558

Scope (from outer to inner):

file
function     void FGeometryCollectionISMPool::Tick

Source code excerpt:

	// Recache component lifecycle state from cvar.
	const bool bRemovedKeepAlive = bCachedKeepAlive && !GComponentKeepAlive;
	const bool bRemovedReycle = bCachedRecycle && !GComponentRecycle;
	bCachedKeepAlive = GComponentKeepAlive;
	bCachedRecycle = GComponentRecycle;

	// If we disabled keep alive behavior since last update then deal with the zombie components.
	if (bRemovedKeepAlive)
	{
		for (int32 ISMIndex = 0; ISMIndex < ISMs.Num(); ++ISMIndex)
		{