p.Chaos.AccelerationStructureCacheOverlappingLeaves

p.Chaos.AccelerationStructureCacheOverlappingLeaves

#Overview

name: p.Chaos.AccelerationStructureCacheOverlappingLeaves

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

• type: Var
• help: Set to 1: Cache the overlapping leaves for faster overlap query, any other value will disable the feature

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of p.Chaos.AccelerationStructureCacheOverlappingLeaves is to control the caching of overlapping leaves in the acceleration structure of the Chaos physics system in Unreal Engine 5. This setting is specifically for optimizing overlap queries in the physics simulation.

This setting variable is primarily used in the Chaos physics module, which is part of Unreal Engine’s experimental physics system. Based on the callsites, it’s clear that this variable is used within the PBDRigidsEvolution (Position Based Dynamics Rigids Evolution) component of the Chaos system.

The value of this variable is set through a console variable, which means it can be adjusted at runtime. It’s initialized with a default value of 1, enabling the feature by default.

The associated variable GAccelerationStructureCacheOverlappingLeaves directly interacts with p.Chaos.AccelerationStructureCacheOverlappingLeaves. They share the same value, with GAccelerationStructureCacheOverlappingLeaves being the actual variable used in the code logic.

Developers must be aware that:

1. This variable affects performance and accuracy of physics simulations, particularly overlap queries.
2. It’s part of an experimental system, so its behavior might change in future engine versions.
3. The feature is enabled by default (set to 1), but can be disabled by setting it to any other value.

Best practices when using this variable include:

1. Test your game’s performance with this feature both enabled and disabled to determine the optimal setting for your specific use case.
2. Monitor physics performance when adjusting this setting, as it may have different impacts depending on the complexity of your physics simulations.
3. Be cautious when disabling this feature, as it may affect the accuracy of overlap queries in your game.

Regarding the associated variable GAccelerationStructureCacheOverlappingLeaves:

• Its purpose is identical to p.Chaos.AccelerationStructureCacheOverlappingLeaves, serving as the in-code representation of the setting.
• It’s used directly in the Chaos physics system to determine whether to cache overlapping leaves.
• The value is set through the console variable system, allowing for runtime adjustments.
• It interacts with the AccelerationStructureUseDynamicTree variable, as seen in one of the code snippets.
• Developers should be aware that this variable directly affects the behavior of the InternalAcceleration->CacheOverlappingLeaves() function call.
• Best practices include using this variable consistently throughout the codebase when checking for this feature, rather than directly accessing the console 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/PBDRigidsEvolution.cpp:47

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

	/** 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;
	FAutoConsoleVariableRef CVarAccelerationStructureTimeSlicingMaxQueueSizeBeforeForce(TEXT("p.Chaos.AccelerationStructureTimeSlicingMaxQueueSizeBeforeForce"), AccelerationStructureTimeSlicingMaxQueueSizeBeforeForce, TEXT("If the update queue reaches this limit, time slicing will be disabled, and the acceleration structure will be built at once"));

	CHAOS_API int32 AccelerationStructureTimeSlicingMaxBytesCopy = 100000;
	FAutoConsoleVariableRef CVarAccelerationStructureTimeSlicingMaxBytesCopy(TEXT("p.Chaos.AccelerationStructureTimeSlicingMaxBytesCopy"), AccelerationStructureTimeSlicingMaxBytesCopy, TEXT("The Maximum number of bytes to copy to the external acceleration structure during Copy Time Slicing"));

#Associated Variable and Callsites

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

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

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

	/** 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;
	FAutoConsoleVariableRef CVarAccelerationStructureTimeSlicingMaxQueueSizeBeforeForce(TEXT("p.Chaos.AccelerationStructureTimeSlicingMaxQueueSizeBeforeForce"), AccelerationStructureTimeSlicingMaxQueueSizeBeforeForce, TEXT("If the update queue reaches this limit, time slicing will be disabled, and the acceleration structure will be built at once"));

	CHAOS_API int32 AccelerationStructureTimeSlicingMaxBytesCopy = 100000;
	FAutoConsoleVariableRef CVarAccelerationStructureTimeSlicingMaxBytesCopy(TEXT("p.Chaos.AccelerationStructureTimeSlicingMaxBytesCopy"), AccelerationStructureTimeSlicingMaxBytesCopy, TEXT("The Maximum number of bytes to copy to the external acceleration structure during Copy Time Slicing"));

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

Scope (from outer to inner):

file
namespace    Chaos
function     void FPBDRigidsEvolutionBase::ComputeIntermediateSpatialAcceleration

Source code excerpt:

					CopyUnBuiltDynamicAccelerationStructures(SpatialAccelerationCache, InternalAcceleration, AsyncInternalAcceleration, AsyncExternalAcceleration);

					if(GAccelerationStructureCacheOverlappingLeaves)
					{
						// Caching of the overlapping leaves
						InternalAcceleration->CacheOverlappingLeaves();
					}
				}
				if (AccelerationStructureSplitStaticAndDynamic == 1)

#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();
				}
			}