a.CacheLocalSpaceBounds

a.CacheLocalSpaceBounds

#Overview

name: a.CacheLocalSpaceBounds

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

It is referenced in 6 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of a.CacheLocalSpaceBounds is to control how bounds are calculated and cached for skeletal mesh components and cloth components in Unreal Engine 5. It determines whether local-space bounds or world-space bounds are computed and stored.

This setting variable is primarily used by the rendering and physics systems within Unreal Engine. Specifically, it affects the SkeletalMeshComponent and ChaosClothComponent, which are part of the Engine and ChaosClothAsset modules respectively.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 1, meaning local-space bounds calculation is enabled by default.

The associated variable CVarCacheLocalSpaceBounds directly interacts with a.CacheLocalSpaceBounds. They share the same value and purpose, with CVarCacheLocalSpaceBounds being the actual console variable implementation.

Developers must be aware that this variable affects performance and accuracy trade-offs. When set to 1 (default), local-space bounds are calculated and cached, which can be more efficient for objects that don’t change their local bounds often. When set to 0, world-space bounds are calculated, which might be more accurate for dynamically deforming meshes but potentially more expensive.

Best practices when using this variable include:

  1. Leave it at the default value (1) unless you have specific reasons to change it.
  2. If dealing with highly dynamic meshes that frequently change shape in world space, consider setting it to 0 for more accurate bounds calculations.
  3. Profile your application with both settings to determine which provides the best performance for your specific use case.

Regarding the associated variable CVarCacheLocalSpaceBounds:

The purpose of CVarCacheLocalSpaceBounds is to provide a console-accessible way to control the a.CacheLocalSpaceBounds setting at runtime.

It’s used in the same subsystems as a.CacheLocalSpaceBounds, primarily affecting skeletal mesh and cloth components.

The value is typically set through the console or configuration files, but can also be queried and set programmatically.

It directly interacts with a.CacheLocalSpaceBounds, effectively controlling the same behavior.

Developers should be aware that changes to this variable will immediately affect the bounds calculation behavior for relevant components.

Best practices include using this variable for debugging or performance testing, and considering exposing it as a configurable option if your game benefits from allowing users to tweak this setting.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Components/SkeletalMeshComponent.cpp:81

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarCacheLocalSpaceBounds(
	TEXT("a.CacheLocalSpaceBounds"),
	1,
	TEXT("If 1 (default) local-space bounds are calculated and cached, otherwise worldspace bounds are built and cached (and inverse transformed to produce local bounds)."));

DECLARE_CYCLE_STAT_EXTERN(TEXT("Anim Instance Spawn Time"), STAT_AnimSpawnTime, STATGROUP_Anim, );
DEFINE_STAT(STAT_AnimSpawnTime);
DEFINE_STAT(STAT_PostAnimEvaluation);

#Loc: <Workspace>/Engine/Plugins/ChaosClothAsset/Source/ChaosClothAssetEngine/Private/ChaosClothAsset/ClothComponent.cpp:291

Scope (from outer to inner):

file
function     FBoxSphereBounds UChaosClothComponent::CalcBounds

Source code excerpt:

	else  // Calculate new bounds
	{
		const IConsoleVariable* const CVarCacheLocalSpaceBounds = IConsoleManager::Get().FindConsoleVariable(TEXT("a.CacheLocalSpaceBounds"));
		const bool bCacheLocalSpaceBounds = CVarCacheLocalSpaceBounds ? (CVarCacheLocalSpaceBounds->GetInt() != 0) : true;

		const FTransform CachedBoundsTransform = bCacheLocalSpaceBounds ? FTransform::Identity : LocalToWorld;

		if (ClothSimulationProxy)
		{

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Classes/Components/SkinnedMeshComponent.h:1564

Scope: file

Source code excerpt:

	ENGINE_API virtual void DeallocateTransformData();

	/** Bounds cached, so they're computed just once, either in local or worldspace depending on cvar 'a.CacheLocalSpaceBounds'. */
	UPROPERTY(Transient)
	mutable FBoxSphereBounds CachedWorldOrLocalSpaceBounds;
	UPROPERTY(Transient)
	mutable FMatrix CachedWorldToLocalTransform;

public:

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Plugins/ChaosClothAsset/Source/ChaosClothAssetEngine/Private/ChaosClothAsset/ClothComponent.cpp:291

Scope (from outer to inner):

file
function     FBoxSphereBounds UChaosClothComponent::CalcBounds

Source code excerpt:

	else  // Calculate new bounds
	{
		const IConsoleVariable* const CVarCacheLocalSpaceBounds = IConsoleManager::Get().FindConsoleVariable(TEXT("a.CacheLocalSpaceBounds"));
		const bool bCacheLocalSpaceBounds = CVarCacheLocalSpaceBounds ? (CVarCacheLocalSpaceBounds->GetInt() != 0) : true;

		const FTransform CachedBoundsTransform = bCacheLocalSpaceBounds ? FTransform::Identity : LocalToWorld;

		if (ClothSimulationProxy)
		{
			NewBounds = ClothSimulationProxy->CalculateBounds_AnyThread().TransformBy(CachedBoundsTransform);

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Components/SkeletalMeshComponent.cpp:80

Scope: file

Source code excerpt:

#endif

static TAutoConsoleVariable<int32> CVarCacheLocalSpaceBounds(
	TEXT("a.CacheLocalSpaceBounds"),
	1,
	TEXT("If 1 (default) local-space bounds are calculated and cached, otherwise worldspace bounds are built and cached (and inverse transformed to produce local bounds)."));

DECLARE_CYCLE_STAT_EXTERN(TEXT("Anim Instance Spawn Time"), STAT_AnimSpawnTime, STATGROUP_Anim, );
DEFINE_STAT(STAT_AnimSpawnTime);

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Components/SkeletalMeshComponent.cpp:2962

Scope (from outer to inner):

file
function     FBoxSphereBounds USkeletalMeshComponent::CalcBounds

Source code excerpt:

		}

		const bool bCacheLocalSpaceBounds = CVarCacheLocalSpaceBounds.GetValueOnAnyThread() != 0;
		
		const FTransform CachedBoundsTransform = bCacheLocalSpaceBounds ? FTransform::Identity : LocalToWorld;

		FBoxSphereBounds NewBounds = CalcMeshBound((FVector3f)RootBoneOffset, bHasValidBodies, CachedBoundsTransform);

		if (bIncludeComponentLocationIntoBounds)