p.Chaos.AccelerationStructureUseDirtyTreeInsteadOfGrid

p.Chaos.AccelerationStructureUseDirtyTreeInsteadOfGrid

#Overview

name: p.Chaos.AccelerationStructureUseDirtyTreeInsteadOfGrid

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 p.Chaos.AccelerationStructureUseDirtyTreeInsteadOfGrid is to control the acceleration structure used for dirty elements in the Chaos physics system of Unreal Engine 5. Specifically, it determines whether to use a dynamic tree structure instead of a 2D grid for handling dirty elements in the spatial acceleration structure.

This setting variable is primarily used in the Chaos physics system, which is part of Unreal Engine’s experimental physics implementation. It is referenced in the PBDRigidsEvolution.cpp file, which is part of the Chaos module.

The value of this variable is set through a console variable (CVar) system. It is initialized with a default value of 1, meaning the dynamic tree structure is used by default. Developers can change this value at runtime using the console command system.

This variable interacts closely with other acceleration structure-related variables, such as AccelerationStructureUseDynamicTree and GAccelerationStructureCacheOverlappingLeaves. These variables work together to configure the behavior of the spatial acceleration structure in the Chaos physics system.

Developers must be aware that changing this variable affects the performance and behavior of the physics simulation, particularly for scenes with many dynamic objects. Using a dynamic tree structure (value = 1) may provide better performance for certain types of simulations, but it could also increase memory usage.

Best practices when using this variable include:

  1. Profiling the performance impact in your specific use case before changing the default value.
  2. Consider the trade-offs between using a dynamic tree (potentially faster for certain scenarios) vs. a 2D grid (potentially more memory-efficient).
  3. Test thoroughly after changing this value, as it can significantly impact physics behavior and performance.

Regarding the associated variable AccelerationStructureUseDirtyTreeInsteadOfGrid:

This is the actual integer variable that stores the value controlled by the p.Chaos.AccelerationStructureUseDirtyTreeInsteadOfGrid console variable. It is used directly in the code to determine whether to use a dirty tree or a grid in the acceleration structure.

The purpose and considerations for this variable are the same as those for the console variable. It’s important to note that this variable is used in the creation of the acceleration structure (specifically in the CreateAccelerationPerBucket_Threaded function), where it determines whether to use a dirty tree in the AABBTreeType construction.

Developers should be aware that this variable is declared with the CHAOS_API macro, making it accessible from other parts of the engine that use the Chaos module. Changes to this variable will affect all systems that rely on this acceleration structure configuration.

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

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:


	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;
	FAutoConsoleVariableRef CVarAccelerationStructureCacheOverlappingLeaves(TEXT("p.Chaos.AccelerationStructureCacheOverlappingLeaves"), GAccelerationStructureCacheOverlappingLeaves, TEXT("Set to 1: Cache the overlapping leaves for faster overlap query, any other value will disable the feature"));

	CHAOS_API int32 AccelerationStructureTimeSlicingMaxQueueSizeBeforeForce = 1000;

#Associated Variable and Callsites

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

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

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

	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;
	FAutoConsoleVariableRef CVarAccelerationStructureCacheOverlappingLeaves(TEXT("p.Chaos.AccelerationStructureCacheOverlappingLeaves"), GAccelerationStructureCacheOverlappingLeaves, TEXT("Set to 1: Cache the overlapping leaves for faster overlap query, any other value will disable the feature"));

	CHAOS_API int32 AccelerationStructureTimeSlicingMaxQueueSizeBeforeForce = 1000;

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

Scope (from outer to inner):

file
namespace    Chaos
function     virtual TUniquePtr<ISpatialAcceleration<FAccelerationStructureHandle, FReal, 3>> CreateAccelerationPerBucket_Threaded

Source code excerpt:

						return MakeUnique<AABBDynamicTreeType>(Particles, BroadPhaseConfig.MaxChildrenInLeaf, BroadPhaseConfig.MaxTreeDepth, BroadPhaseConfig.MaxPayloadSize, ForceFullBuild ? 0 : BroadPhaseConfig.IterationsPerTimeSlice, true, bBuildOverlapCache);
					}
					return MakeUnique<AABBTreeType>(Particles, BroadPhaseConfig.MaxChildrenInLeaf, BroadPhaseConfig.MaxTreeDepth, BroadPhaseConfig.MaxPayloadSize, ForceFullBuild ? 0 : BroadPhaseConfig.IterationsPerTimeSlice, false, AccelerationStructureUseDirtyTreeInsteadOfGrid == 1, bBuildOverlapCache);
				}
				else if (BroadPhaseConfig.BroadphaseType == FBroadPhaseConfig::TreeOfGridAndGrid || BroadPhaseConfig.BroadphaseType == FBroadPhaseConfig::TreeOfGrid)
				{
					return MakeUnique<AABBTreeOfGridsType>(Particles, BroadPhaseConfig.AABBMaxChildrenInLeaf, BroadPhaseConfig.AABBMaxTreeDepth, BroadPhaseConfig.MaxPayloadSize);
				}
			}