p.Chaos.AccelerationStructureUseDynamicTree

p.Chaos.AccelerationStructureUseDynamicTree

#Overview

name: p.Chaos.AccelerationStructureUseDynamicTree

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

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of p.Chaos.AccelerationStructureUseDynamicTree is to control the use of a dynamic BVH (Bounding Volume Hierarchy) tree structure for dynamic objects in the Chaos physics system of Unreal Engine 5.

This setting variable is primarily used in the Chaos physics subsystem, which is part of the Experimental module in Unreal Engine 5. It specifically affects the spatial acceleration structure used for collision detection and physics simulations.

The value of this variable is set through a console variable (CVar) system, allowing it to be changed at runtime. It’s initialized with a default value of 1, meaning the dynamic BVH tree is enabled by default.

This variable interacts closely with several other variables in the Chaos system, such as:

  1. AccelerationStructureUseDirtyTreeInsteadOfGrid
  2. GAccelerationStructureCacheOverlappingLeaves
  3. AccelerationStructureSplitStaticAndDynamic

Developers should be aware that this variable significantly impacts the performance and behavior of the physics simulation, particularly for scenes with many dynamic objects. Enabling it (value set to 1) uses a more sophisticated data structure for managing dynamic objects, which can improve performance in certain scenarios but may have overhead in others.

Best practices when using this variable include:

  1. Profiling your specific use case to determine if the dynamic tree provides better performance than the alternative.
  2. Consider the nature of your scene - if you have many dynamic objects that frequently change position, the dynamic tree may be beneficial.
  3. Be aware of how this setting interacts with other acceleration structure settings in the Chaos system.

Regarding the associated variable AccelerationStructureUseDynamicTree:

The purpose of AccelerationStructureUseDynamicTree is the same as p.Chaos.AccelerationStructureUseDynamicTree. It’s the actual integer variable that stores the state (0 or 1) of whether to use the dynamic BVH tree.

This variable is used directly in the code to determine the behavior of the acceleration structure. For example, in the IsDynamicTree function, it’s checked to determine if a dynamic tree should be used for a given spatial acceleration index.

The value of this variable is set through the console variable system, linked to p.Chaos.AccelerationStructureUseDynamicTree.

It interacts with the same variables as p.Chaos.AccelerationStructureUseDynamicTree, as it’s the actual storage for the setting.

Developers should be aware that changing this variable directly in code (rather than through the console variable system) may lead to inconsistent behavior, as other parts of the system may still refer to the console variable.

Best practices include using the console variable (p.Chaos.AccelerationStructureUseDynamicTree) to modify this setting rather than changing the AccelerationStructureUseDynamicTree variable directly, to ensure consistency across the entire system.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/PBDRigidsEvolution.cpp:40

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:


	CHAOS_API int32 AccelerationStructureUseDynamicTree = 1;
	FAutoConsoleVariableRef CVarAccelerationStructureUseDynamicTree(TEXT("p.Chaos.AccelerationStructureUseDynamicTree"), AccelerationStructureUseDynamicTree, TEXT("Use a dynamic BVH tree structure for dynamic objects"));

	CHAOS_API int32 AccelerationStructureUseDirtyTreeInsteadOfGrid = 1;
	FAutoConsoleVariableRef CVarAccelerationStructureUseDirtyTreeInsteadOfGrid(TEXT("p.Chaos.AccelerationStructureUseDirtyTreeInsteadOfGrid"), AccelerationStructureUseDirtyTreeInsteadOfGrid, TEXT("Use a dynamic tree structure for dirty elements instead of a 2D grid"));

	/** Console variable to enable the caching of the overlapping leaves if the dynamic tree is enable */
	CHAOS_API int32 GAccelerationStructureCacheOverlappingLeaves = 1;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/PBDRigidsEvolution.cpp:39

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

	FAutoConsoleVariableRef CVarAccelerationStructureSplitStaticAndDynamic(TEXT("p.Chaos.AccelerationStructureSplitStaticDynamic"), AccelerationStructureSplitStaticAndDynamic, TEXT("Set to 1: Sort Dynamic and Static bodies into seperate acceleration structures, any other value will disable the feature"));

	CHAOS_API int32 AccelerationStructureUseDynamicTree = 1;
	FAutoConsoleVariableRef CVarAccelerationStructureUseDynamicTree(TEXT("p.Chaos.AccelerationStructureUseDynamicTree"), AccelerationStructureUseDynamicTree, TEXT("Use a dynamic BVH tree structure for dynamic objects"));

	CHAOS_API int32 AccelerationStructureUseDirtyTreeInsteadOfGrid = 1;
	FAutoConsoleVariableRef CVarAccelerationStructureUseDirtyTreeInsteadOfGrid(TEXT("p.Chaos.AccelerationStructureUseDirtyTreeInsteadOfGrid"), AccelerationStructureUseDirtyTreeInsteadOfGrid, TEXT("Use a dynamic tree structure for dirty elements instead of a 2D grid"));

	/** Console variable to enable the caching of the overlapping leaves if the dynamic tree is enable */
	CHAOS_API int32 GAccelerationStructureCacheOverlappingLeaves = 1;

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/PBDRigidsEvolution.cpp:76

Scope (from outer to inner):

file
namespace    Chaos
function     static bool IsDynamicTree

Source code excerpt:

		static bool IsDynamicTree(FSpatialAccelerationIdx SpatialAccelerationIdx)
		{
			return AccelerationStructureUseDynamicTree && (SpatialAccelerationIdx.InnerIdx == ESpatialAccelerationCollectionBucketInnerIdx::Dynamic || SpatialAccelerationIdx.InnerIdx == ESpatialAccelerationCollectionBucketInnerIdx::DynamicQueryOnly);
		}

		TUniquePtr<ISpatialAccelerationCollection<FAccelerationStructureHandle, FReal, 3>> CreateEmptyCollection() override
		{
			TConstParticleView<FSpatialAccelerationCache> Empty;

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/PBDRigidsEvolution.cpp:789

Scope (from outer to inner):

file
namespace    Chaos
function     void FPBDRigidsEvolutionBase::ComputeIntermediateSpatialAcceleration

Source code excerpt:

				// The old InternalAcceleration is now in AsyncInternalAcceleration, and the constituent structures will be reused if no changes have been detected

				if (AccelerationStructureUseDynamicTree)
				{
					// Dynamic Acceleration structures were not built by the async task, so copy them where required
					CopyUnBuiltDynamicAccelerationStructures(SpatialAccelerationCache, InternalAcceleration, AsyncInternalAcceleration, AsyncExternalAcceleration);

					if(GAccelerationStructureCacheOverlappingLeaves)
					{

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/PBDRigidsEvolution.cpp:818

Scope (from outer to inner):

file
namespace    Chaos
function     void FPBDRigidsEvolutionBase::ComputeIntermediateSpatialAcceleration

Source code excerpt:

				FlushInternalAccelerationQueue();

				if (GAccelerationStructureCacheOverlappingLeaves  && AccelerationStructureUseDynamicTree)
				{
					// Caching of the overlapping leaves
					InternalAcceleration->CacheOverlappingLeaves();
				}
			}