p.Chaos.Collision.UnionBVH.MaxDepth

p.Chaos.Collision.UnionBVH.MaxDepth

#Overview

name: p.Chaos.Collision.UnionBVH.MaxDepth

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 p.Chaos.Collision.UnionBVH.MaxDepth is to control the maximum depth of the Bounding Volume Hierarchy (BVH) used in the Chaos physics engine’s collision system. This setting is specifically used for wrapping shape hierarchies in the Union BVH structure.

This setting variable is primarily used by the Chaos physics engine, which is part of Unreal Engine’s experimental physics system. It is utilized in the collision detection and object organization subsystems within Chaos.

The value of this variable is set through the Unreal Engine’s console variable system. It’s defined and initialized in the Chaos namespace, specifically in the CVars (Console Variables) sub-namespace.

The associated variable ChaosUnionBVHMaxDepth directly interacts with p.Chaos.Collision.UnionBVH.MaxDepth. They share the same value, with ChaosUnionBVHMaxDepth being the actual integer variable used in the code, while p.Chaos.Collision.UnionBVH.MaxDepth is the console variable name used for external access and modification.

Developers must be aware that this variable affects the performance and accuracy of collision detection in the Chaos physics system. A higher maximum depth allows for more detailed subdivision of the collision space but may increase computational cost.

Best practices when using this variable include:

  1. Balancing between performance and accuracy based on the specific needs of the project.
  2. Testing different values to find the optimal setting for the particular scene or game.
  3. Considering the complexity of the objects in the scene when adjusting this value.

Regarding the associated variable ChaosUnionBVHMaxDepth:

The purpose of ChaosUnionBVHMaxDepth is to store the actual integer value used in the code for the maximum BVH depth. It’s used directly in the implementation of the BVH creation and management functions.

This variable is used in various parts of the Chaos physics engine, particularly in the ImplicitObjectUnion and ConvexOptimizer classes.

The value of ChaosUnionBVHMaxDepth is set initially to 14, but can be modified through the console variable system.

ChaosUnionBVHMaxDepth interacts closely with other Chaos physics variables, such as ChaosUnionBVHMinShapes, which determines the minimum number of shapes required to create a BVH node.

Developers should be aware that modifying ChaosUnionBVHMaxDepth directly in the code will affect all instances where the BVH is used in the Chaos system, potentially impacting performance and collision detection accuracy across the entire game.

Best practices for using ChaosUnionBVHMaxDepth include:

  1. Avoiding direct modification in code unless absolutely necessary, preferring to use the console variable for runtime adjustments.
  2. Considering the relationship between this variable and other BVH-related settings when making changes.
  3. Profiling the performance impact of different values in various scenarios to determine the optimal setting 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/Chaos/Private/Chaos/ImplicitObjectUnion.cpp:25

Scope (from outer to inner):

file
namespace    Chaos
namespace    CVars

Source code excerpt:

		// Maximum BVH depth. In general we want the BVH to generate leafs with a single item in them
		int32 ChaosUnionBVHMaxDepth = 14;
		FAutoConsoleVariableRef CVarChaosUnionBVHMaxDepth(TEXT("p.Chaos.Collision.UnionBVH.MaxDepth"), ChaosUnionBVHMaxDepth, TEXT("The allowed depth of the BVH when used to wrap a shape hiererchy"));

		// A common case if objects arranged in a regular grid which is bad for the splitting algorithm.
		// This prevents objects exactly in the middle of the bounds of a cell from being assigned to 
		// a random child. See FImplicitBVH::Partition.
		FRealSingle ChaosUnionBVHSplitBias = 0.1f;
		FAutoConsoleVariableRef CVarChaosUnionBVHSplitBias(TEXT("p.Chaos.Collision.UnionBVH.SplitBias"), ChaosUnionBVHSplitBias, TEXT(""));

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/ConvexOptimizer.cpp:35

Scope (from outer to inner):

file
namespace    Chaos
namespace    CVars

Source code excerpt:

	FAutoConsoleVariableRef CVarChaosConvexEnableMerging(TEXT("p.Chaos.Convex.EnableMerging"), ChaosConvexEnableMerging, TEXT("Boolean to check if we are merging (bottom-up) or splitting (top-bottom) the convexes"));
	
	extern int32 ChaosUnionBVHMaxDepth;
	extern int32 ChaosUnionBVHMinShapes;
}

namespace Private
{

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/ConvexOptimizer.cpp:147

Scope (from outer to inner):

file
namespace    Chaos
namespace    Private
function     void FConvexOptimizer::SimplifyRootConvexes

Source code excerpt:

			BVH.Reset();
		}
		BVH = FImplicitBVH::TryMakeFromLeaves(MoveTemp(CollisionObjects->ImplicitObjects), CVars::ChaosUnionBVHMinShapes, CVars::ChaosUnionBVHMaxDepth);
	}
}

FORCEINLINE void InvalidateCachedTriboxes(FConvexOptimizer::FTriboxNodes& RootTriboxes)
{
	for(auto& RootTribox : RootTriboxes)

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/ConvexOptimizer.cpp:334

Scope (from outer to inner):

file
namespace    Chaos
namespace    Private
function     void FConvexOptimizer::BuildUnionConnectivity

Source code excerpt:

			}
		}
		LocalBVH = FImplicitBVH::TryMakeFromLeaves(MoveTemp(ImplicitObjects), CVars::ChaosUnionBVHMinShapes, CVars::ChaosUnionBVHMaxDepth);
	}

	auto AddUnionEdges = [this, &UnionGeometry](const int32 RootIndexA, const int32 RootIndexB, const FAABB3& LocalBoundsA, FTriboxNode* RootTriboxA)
	{
		if (auto* RootTriboxB = RootTriboxes.Find(UnionGeometry->GetObjects()[RootIndexB]))
		{

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/ImplicitObjectUnion.cpp:24

Scope (from outer to inner):

file
namespace    Chaos
namespace    CVars

Source code excerpt:


		// Maximum BVH depth. In general we want the BVH to generate leafs with a single item in them
		int32 ChaosUnionBVHMaxDepth = 14;
		FAutoConsoleVariableRef CVarChaosUnionBVHMaxDepth(TEXT("p.Chaos.Collision.UnionBVH.MaxDepth"), ChaosUnionBVHMaxDepth, TEXT("The allowed depth of the BVH when used to wrap a shape hiererchy"));

		// A common case if objects arranged in a regular grid which is bad for the splitting algorithm.
		// This prevents objects exactly in the middle of the bounds of a cell from being assigned to 
		// a random child. See FImplicitBVH::Partition.
		FRealSingle ChaosUnionBVHSplitBias = 0.1f;
		FAutoConsoleVariableRef CVarChaosUnionBVHSplitBias(TEXT("p.Chaos.Collision.UnionBVH.SplitBias"), ChaosUnionBVHSplitBias, TEXT(""));

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/ImplicitObjectUnion.cpp:168

Scope (from outer to inner):

file
namespace    Chaos
function     void FImplicitObjectUnion::CreateBVH

Source code excerpt:

	{
		const int32 MinBVHShapes = CVars::ChaosUnionBVHMinShapes;
		const int32 MaxBVHDepth = CVars::ChaosUnionBVHMaxDepth;
		
		BVH = Private::FImplicitBVH::TryMake(MakeArrayView(MObjects), MinBVHShapes, MaxBVHDepth);
		Flags.bHasBVH = BVH.IsValid();
	}
}