ClusterUnion.PreAllocateLocalBoneDataMap

ClusterUnion.PreAllocateLocalBoneDataMap

#Overview

name: ClusterUnion.PreAllocateLocalBoneDataMap

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 ClusterUnion.PreAllocateLocalBoneDataMap is to control memory allocation for the local map used to cache updated bone data in the Cluster Union system. This setting is part of Unreal Engine’s physics engine, specifically related to the ClusterUnionComponent.

The Unreal Engine subsystem that relies on this setting variable is the physics engine, particularly the ClusterUnionComponent within the Engine module. This can be seen from the file path “Engine/Source/Runtime/Engine/Private/PhysicsEngine/ClusterUnionComponent.cpp”.

The value of this variable is set using an FAutoConsoleVariableRef, which allows it to be modified at runtime through console commands. By default, it is set to true.

This variable interacts with another variable called LocalBoneDataMapGrowFactor, which determines the growth factor applied when preallocating the local bones data map.

Developers must be aware that this variable affects memory usage and potentially performance. When set to true, it reserves an expected size for the local map used to cache updated bone data, which can improve performance by reducing memory reallocations but may use more memory upfront.

Best practices when using this variable include:

  1. Keep it enabled (true) for better performance in most cases.
  2. If memory is a concern, consider disabling it (false) and monitor the impact on performance.
  3. Use in conjunction with LocalBoneDataMapGrowFactor to fine-tune memory allocation behavior.

Regarding the associated variable bPreAllocateLocalBoneDataMap:

The purpose of bPreAllocateLocalBoneDataMap is the same as ClusterUnion.PreAllocateLocalBoneDataMap. It’s the actual boolean variable that controls the preallocation behavior.

This variable is used within the UClusterUnionComponent::SyncClusterUnionFromProxy function to determine whether to preallocate memory for the MappedData and BoneIDToBoneData containers.

The value of this variable is set at the beginning of the ClusterUnionComponent.cpp file and can be modified through the console variable system.

It interacts directly with the LocalBoneDataMapGrowFactor variable when determining the size of preallocation.

Developers should be aware that this variable directly affects the memory allocation strategy in the SyncClusterUnionFromProxy function.

Best practices for using this variable are the same as those for ClusterUnion.PreAllocateLocalBoneDataMap, as they are essentially the same setting, with one being the console-accessible version and the other being the actual variable used in the code.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/PhysicsEngine/ClusterUnionComponent.cpp:30

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:


	bool bPreAllocateLocalBoneDataMap = true;
	FAutoConsoleVariableRef CVarPreAllocateLocalBoneDataMap(TEXT("ClusterUnion.PreAllocateLocalBoneDataMap"), bPreAllocateLocalBoneDataMap, TEXT("If true, it will reserve an expected size for the local map used to cache updated bone data"));

	float LocalBoneDataMapGrowFactor = 1.2f;
	FAutoConsoleVariableRef CVarLocalBoneDataMapGrowFactor(TEXT("ClusterUnion.LocalBoneDataMapGrowFactor"), LocalBoneDataMapGrowFactor, TEXT("Grow factor to apply to the size of bone data array of pre-existing component when preallocating the local bones data map"));

	bool bApplyReplicatedRigidStateOnCreatePhysicsState = true;
	FAutoConsoleVariableRef CVarApplyReplicatedRigidStateOnCreatePhysicsState(TEXT("ClusterUnion.ApplyReplicatedRigidStateOnCreatePhysicsState"), bApplyReplicatedRigidStateOnCreatePhysicsState, TEXT("When physics state is created, apply replicated rigid state. Useful because sometimes the initial OnRep will have been called before a proxy exists, so initial properties will be unset"));

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/PhysicsEngine/ClusterUnionComponent.cpp:29

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:

	FAutoConsoleVariableRef CVarUseLocalRoleForAuthorityCheck(TEXT("ClusterUnion.UseLocalRoleForAuthorityCheck"), bUseLocalRoleForAuthorityCheck, TEXT("If true, we will only check this component's owner local role to determine authority"));

	bool bPreAllocateLocalBoneDataMap = true;
	FAutoConsoleVariableRef CVarPreAllocateLocalBoneDataMap(TEXT("ClusterUnion.PreAllocateLocalBoneDataMap"), bPreAllocateLocalBoneDataMap, TEXT("If true, it will reserve an expected size for the local map used to cache updated bone data"));

	float LocalBoneDataMapGrowFactor = 1.2f;
	FAutoConsoleVariableRef CVarLocalBoneDataMapGrowFactor(TEXT("ClusterUnion.LocalBoneDataMapGrowFactor"), LocalBoneDataMapGrowFactor, TEXT("Grow factor to apply to the size of bone data array of pre-existing component when preallocating the local bones data map"));

	bool bApplyReplicatedRigidStateOnCreatePhysicsState = true;
	FAutoConsoleVariableRef CVarApplyReplicatedRigidStateOnCreatePhysicsState(TEXT("ClusterUnion.ApplyReplicatedRigidStateOnCreatePhysicsState"), bApplyReplicatedRigidStateOnCreatePhysicsState, TEXT("When physics state is created, apply replicated rigid state. Useful because sometimes the initial OnRep will have been called before a proxy exists, so initial properties will be unset"));

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/PhysicsEngine/ClusterUnionComponent.cpp:964

Scope (from outer to inner):

file
function     void UClusterUnionComponent::SyncClusterUnionFromProxy

Source code excerpt:

	TMap<FMappedComponentKey, FLocalBonesToTransformMap> MappedData;

	if (bPreAllocateLocalBoneDataMap)
	{
		MappedData.Reserve(PerComponentData.Num());
	}

	{
		FLockedReadPhysicsObjectExternalInterface Interface = FPhysicsObjectExternalInterface::LockRead(GetWorld()->GetPhysicsScene());

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/PhysicsEngine/ClusterUnionComponent.cpp:983

Scope (from outer to inner):

file
function     void UClusterUnionComponent::SyncClusterUnionFromProxy

Source code excerpt:

				// If we added new entry, and it is for an existing component, preallocate the local map using the
				// existing size as a base
				if (bPreAllocateLocalBoneDataMap && PrevMappedDataNum < MappedData.Num())
				{
					if (FClusteredComponentData* ComponentData = PerComponentData.Find(WrappedComponentKey.ComponentKey))
					{
						if (!ComponentData->BonesData.IsEmpty())
						{
							BoneIDToBoneData.Reserve(ComponentData->BonesData.Num() * LocalBoneDataMapGrowFactor);