ClusterUnion.LocalBoneDataMapGrowFactor

ClusterUnion.LocalBoneDataMapGrowFactor

#Overview

name: ClusterUnion.LocalBoneDataMapGrowFactor

This variable is created as a Console Variable (cvar).

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of ClusterUnion.LocalBoneDataMapGrowFactor is to determine the growth factor for pre-allocating memory in the local bones data map used in the Cluster Union system, which is part of Unreal Engine’s physics engine.

This setting variable is primarily used in the Physics Engine subsystem of Unreal Engine, specifically within the Cluster Union component. It’s referenced in the ClusterUnionComponent.cpp file, which suggests it’s integral to the functioning of cluster unions in physics simulations.

The value of this variable is set to a default of 1.2f and can be modified at runtime through the console variable system. It’s defined using FAutoConsoleVariableRef, which allows it to be changed during development or gameplay for tuning purposes.

The LocalBoneDataMapGrowFactor interacts directly with the BoneIDToBoneData map in the SyncClusterUnionFromProxy function. It’s used to calculate the reserve size for this map, which stores bone data for the cluster union.

Developers should be aware that this variable affects memory allocation. A higher value will allocate more memory upfront, potentially reducing reallocation operations but using more memory. A lower value will use less initial memory but might lead to more frequent reallocations if the actual data grows beyond the initial allocation.

Best practices when using this variable include:

  1. Monitoring memory usage and performance to find the optimal value for your specific use case.
  2. Adjusting the value based on the expected number of bones in your cluster unions.
  3. Being cautious about setting extremely high values, as this could lead to unnecessary memory consumption.

Regarding the associated variable LocalBoneDataMapGrowFactor, it’s actually the same variable. The console variable system is referencing this local variable to allow runtime modification. The purpose and usage are identical to what’s described above. It’s worth noting that changes to this variable via the console will affect all instances where it’s 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:33

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:


	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"));

	bool bDirtyRigidStateOnlyIfChanged = false;
	FAutoConsoleVariableRef CVarDirtyRigidStateOnlyIfChanged(TEXT("ClusterUnion.DirtyRigidStateOnlyIfChanged"), bDirtyRigidStateOnlyIfChanged, TEXT("Add a check for changed rigid state before marking it dirty and updating the replicated data. No need to flush an update if there was no change."));

#Associated Variable and Callsites

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

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

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:

	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"));

	bool bDirtyRigidStateOnlyIfChanged = false;
	FAutoConsoleVariableRef CVarDirtyRigidStateOnlyIfChanged(TEXT("ClusterUnion.DirtyRigidStateOnlyIfChanged"), bDirtyRigidStateOnlyIfChanged, TEXT("Add a check for changed rigid state before marking it dirty and updating the replicated data. No need to flush an update if there was no change."));

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

Scope (from outer to inner):

file
function     void UClusterUnionComponent::SyncClusterUnionFromProxy

Source code excerpt:

						if (!ComponentData->BonesData.IsEmpty())
						{
							BoneIDToBoneData.Reserve(ComponentData->BonesData.Num() * LocalBoneDataMapGrowFactor);
						}
					}
				}

				Chaos::FPhysicsObjectHandle Handle = Component->GetPhysicsObjectById(ChildData.BoneId);
				Chaos::FPBDRigidParticle* Particle = Interface->GetRigidParticle(Handle);