r.ISMPool.ComponentKeepAlive

r.ISMPool.ComponentKeepAlive

#Overview

name: r.ISMPool.ComponentKeepAlive

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.ComponentKeepAlive is to control whether Instanced Static Mesh (ISM) components are kept alive when all their instances are removed. This setting is primarily used in the GeometryCollection system, which is part of the experimental GeometryCollectionEngine module in Unreal Engine 5.

The GeometryCollectionEngine module relies on this setting variable to manage the lifecycle of ISM components. Specifically, it’s used in the FGeometryCollectionISMPool class, which handles the pooling and recycling of ISM components.

The value of this variable is set through the Unreal Engine console variable system. It’s initialized with a default value of true, but can be changed at runtime using console commands.

The associated variable GComponentKeepAlive directly interacts with r.ISMPool.ComponentKeepAlive. They share the same value, with GComponentKeepAlive being the actual boolean used in the code logic.

Developers must be aware that this variable affects performance and memory usage. When set to true, it keeps ISM components alive even when they’re empty, which can reduce the high cost associated with repeated registration, scene proxy creation, and mesh draw command creation. However, this may also lead to increased memory usage if many empty components are kept alive.

Best practices when using this variable include:

  1. Consider the trade-off between performance and memory usage for your specific use case.
  2. Monitor the number of ISM components in your scene when this setting is enabled.
  3. Use in conjunction with the component recycling system for optimal performance.

Regarding the associated variable GComponentKeepAlive:

The purpose of GComponentKeepAlive is to directly implement the behavior controlled by r.ISMPool.ComponentKeepAlive within the code.

It’s used in the FGeometryCollectionISMPool class to determine whether to keep ISM components alive when they become empty.

The value of GComponentKeepAlive is set by the console variable system through r.ISMPool.ComponentKeepAlive.

It interacts closely with another variable, GComponentRecycle, which controls whether components should be recycled.

Developers should be aware that changes to GComponentKeepAlive during runtime will affect the behavior of the ISM pool. The FGeometryCollectionISMPool::Tick function checks for changes in this variable and adjusts its behavior accordingly.

Best practices for GComponentKeepAlive include:

  1. Avoid directly modifying this variable in code; instead, use the console variable r.ISMPool.ComponentKeepAlive to change its value.
  2. Consider the implications on performance and memory usage when changing this value, especially in scenes with many ISM components.
  3. Use in conjunction with the component recycling system for best results.

#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:13

Scope: file

Source code excerpt:

static bool GComponentKeepAlive = true;
FAutoConsoleVariableRef CVarISMPoolComponentKeepAlive(
	TEXT("r.ISMPool.ComponentKeepAlive"),
	GComponentKeepAlive,
	TEXT("Keep ISM components alive when all their instances are removed."));

// Use a FreeList to enable recycling of ISM components.
// ISM components aren't unregistered, but their scene proxy is destroyed.
// When recycling a component, a new mesh description can be used.

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

// Don't release ISM components when they empty, but keep them (and their scene proxy) alive.
// This can remove the high cost associated with repeated registration, scene proxy creation and mesh draw command creation.
static bool GComponentKeepAlive = true;
FAutoConsoleVariableRef CVarISMPoolComponentKeepAlive(
	TEXT("r.ISMPool.ComponentKeepAlive"),
	GComponentKeepAlive,
	TEXT("Keep ISM components alive when all their instances are removed."));

// Use a FreeList to enable recycling of ISM components.
// ISM components aren't unregistered, but their scene proxy is destroyed.
// When recycling a component, a new mesh description can be used.
// This removes the high CPU cost of unregister/register.

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

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)
{

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

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)