p.Chaos.Collision.UnionBVH.NumShapes

p.Chaos.Collision.UnionBVH.NumShapes

#Overview

name: p.Chaos.Collision.UnionBVH.NumShapes

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

It is referenced in 7 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of p.Chaos.Collision.UnionBVH.NumShapes is to control the creation of Bounding Volume Hierarchies (BVH) for collision detection in Unreal Engine’s Chaos physics system. It sets the minimum number of shapes required in a geometry hierarchy before a BVH is created around it.

This setting variable is primarily used in the Chaos physics system, which is part of Unreal Engine’s experimental features. It’s specifically utilized in the collision detection subsystem of Chaos.

The value of this variable is set through the Unreal Engine console variable system. It’s defined as an FAutoConsoleVariableRef, which allows it to be adjusted at runtime.

The associated variable ChaosUnionBVHMinShapes directly interacts with p.Chaos.Collision.UnionBVH.NumShapes. They share the same value and are used interchangeably in the code.

Developers must be aware that this variable significantly impacts the performance and accuracy of collision detection in complex geometries. Setting it too low might create unnecessary BVHs, while setting it too high might reduce collision detection efficiency for moderately complex objects.

Best practices when using this variable include:

  1. Adjusting it based on the complexity of your game’s geometries.
  2. Profiling performance with different values to find the optimal setting for your specific use case.
  3. Considering it in conjunction with p.Chaos.Collision.UnionBVH.MaxDepth for optimal BVH configuration.

Regarding the associated variable ChaosUnionBVHMinShapes:

The purpose of ChaosUnionBVHMinShapes is identical to p.Chaos.Collision.UnionBVH.NumShapes. It’s used internally in the Chaos physics system to determine when to create a BVH for a group of shapes.

This variable is used in various parts of the Chaos system, including the ConvexOptimizer and ImplicitObjectUnion classes. It’s particularly important in functions that build or simplify collision structures.

The value of ChaosUnionBVHMinShapes is set by the console variable p.Chaos.Collision.UnionBVH.NumShapes.

It interacts closely with ChaosUnionBVHMaxDepth, which sets the maximum depth of the created BVHs.

Developers should be aware that this variable directly affects the creation of BVHs in the Chaos system and can have significant performance implications.

Best practices for ChaosUnionBVHMinShapes are the same as for p.Chaos.Collision.UnionBVH.NumShapes, as they are effectively the same variable.

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

Scope (from outer to inner):

file
namespace    Chaos
namespace    CVars

Source code excerpt:

		// If a geometry hierarchy has more shapes than this, create a BVH around it
		int32 ChaosUnionBVHMinShapes = 10;
		FAutoConsoleVariableRef CVarChaosUnionBVHMinShapes(TEXT("p.Chaos.Collision.UnionBVH.NumShapes"), ChaosUnionBVHMinShapes, TEXT("If a geometry hierarchy has this many shapes, wrap it in a BVH for collision detection (negative to disable BVH)"));

		// 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.

#Associated Variable and Callsites

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

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

Scope (from outer to inner):

file
namespace    Chaos
namespace    CVars

Source code excerpt:

	
	extern int32 ChaosUnionBVHMaxDepth;
	extern int32 ChaosUnionBVHMinShapes;
}

namespace Private
{

FConvexOptimizer::FConvexOptimizer() :

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

Scope (from outer to inner):

file
namespace    Chaos
namespace    Private
function     void FConvexOptimizer::BuildUnionConnectivity

Source code excerpt:

	TUniquePtr<Private::FImplicitBVH> LocalBVH = nullptr;

	if(NumTriboxes > CVars::ChaosUnionBVHMinShapes)
	{
		TArray<Private::FImplicitBVHObject> ImplicitObjects;
		ImplicitObjects.Reserve(NumTriboxes);

		for (int32 RootIndex = 0; RootIndex < NumTriboxes; ++RootIndex)
		{

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

Scope (from outer to inner):

file
namespace    Chaos
namespace    CVars

Source code excerpt:


		// If a geometry hierarchy has more shapes than this, create a BVH around it
		int32 ChaosUnionBVHMinShapes = 10;
		FAutoConsoleVariableRef CVarChaosUnionBVHMinShapes(TEXT("p.Chaos.Collision.UnionBVH.NumShapes"), ChaosUnionBVHMinShapes, TEXT("If a geometry hierarchy has this many shapes, wrap it in a BVH for collision detection (negative to disable BVH)"));

		// 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.

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

Scope (from outer to inner):

file
namespace    Chaos
function     void FImplicitObjectUnion::CreateBVH

Source code excerpt:

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