p.Chaos.DisableCollisionParallelFor

p.Chaos.DisableCollisionParallelFor

#Overview

name: p.Chaos.DisableCollisionParallelFor

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

It is referenced in 8 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of p.Chaos.DisableCollisionParallelFor is to disable parallel execution for Chaos Collisions in Unreal Engine 5’s physics system. This setting variable is part of the Chaos physics engine, which is an experimental physics simulation framework in Unreal Engine.

This setting variable is primarily used in the Chaos physics subsystem, specifically in the collision detection and processing modules. Based on the callsites, it’s clear that this variable affects the parallelization of collision-related computations in the Chaos framework.

The value of this variable is set through a console variable (CVar) system, as evident from the FAutoConsoleVariableRef declaration. It can be modified at runtime through console commands or programmatically.

The p.Chaos.DisableCollisionParallelFor variable interacts closely with two other variables:

  1. bDisablePhysicsParallelFor
  2. bDisableParticleParallelFor

These variables work together to control different aspects of parallelization in the Chaos physics system.

Developers must be aware that enabling this variable (setting it to true) will disable parallel execution for collision detection and processing. This can significantly impact performance, especially in scenarios with many colliding objects. It should primarily be used for debugging or in situations where parallel execution is causing issues.

Best practices when using this variable include:

  1. Keep it disabled (false) for optimal performance in most cases.
  2. Use it temporarily for debugging collision-related issues.
  3. Consider the impact on performance when enabling it, especially in complex scenes.
  4. Test thoroughly after modifying this setting, as it can affect the behavior and performance of the physics simulation.

Regarding the associated variable bDisableCollisionParallelFor: This is the actual boolean variable that stores the state of the collision parallelization setting. It’s used directly in the code to control the execution of parallel for loops in collision-related computations. The console variable p.Chaos.DisableCollisionParallelFor is linked to this boolean, allowing it to be modified through the console or configuration files. The usage and considerations for bDisableCollisionParallelFor are the same as those for p.Chaos.DisableCollisionParallelFor, as they represent the same setting in different contexts within the engine.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/Framework/Parallel.cpp:20

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

	FAutoConsoleVariableRef CVarDisablePhysicsParallelFor(TEXT("p.Chaos.DisablePhysicsParallelFor"), bDisablePhysicsParallelFor, TEXT("Disable parallel execution in Chaos Evolution"));
	FAutoConsoleVariableRef CVarDisableParticleParallelFor(TEXT("p.Chaos.DisableParticleParallelFor"), bDisableParticleParallelFor, TEXT("Disable parallel execution for Chaos Particles (Collisions, "));
	FAutoConsoleVariableRef CVarDisableCollisionParallelFor(TEXT("p.Chaos.DisableCollisionParallelFor"), bDisableCollisionParallelFor, TEXT("Disable parallel execution for Chaos Collisions (also disabled by DisableParticleParallelFor)"));
	FAutoConsoleVariableRef CVarInnerPhysicsBatchSize(TEXT("p.Chaos.InnerParallelForBatchSize"), InnerParallelForBatchSize, TEXT("Set the batch size threshold for inner parallel fors"));
	FAutoConsoleVariableRef CVarMinRangeBatchSize(TEXT("p.Chaos.MinRangeBatchSize"), MinRangeBatchSize, TEXT("Set the min range batch size for parallel for"));
	FAutoConsoleVariableRef CVarMaxRangeBatchWorkers(TEXT("p.Chaos.MaxNumWorkers"), MaxNumWorkers, TEXT("Set the max number of workers for physics"));
	FAutoConsoleVariableRef CVarSmallBatchSize(TEXT("p.Chaos.SmallBatchSize"), SmallBatchSize, TEXT("Small batch size for chaos parallel loops"));
	FAutoConsoleVariableRef CVarLargeBatchSize(TEXT("p.Chaos.LargeBatchSize"), LargeBatchSize, TEXT("Large batch size for chaos parallel loops"));
#endif

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Programs/HeadlessChaos/Private/HeadlessChaosTestPerf.cpp:117

Scope (from outer to inner):

file
namespace    ChaosTest
function     GTEST_TEST

Source code excerpt:

		//bDisablePhysicsParallelFor = true;
		//bDisableParticleParallelFor = true;
		//bDisableCollisionParallelFor = true;

		double MinTime = DBL_MAX;
		double MaxTime = DBL_MIN;
		double TotalTime = 0.;

		const int NumSamples = 1;

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/Framework/Parallel.cpp:16

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

	CHAOS_API bool bDisablePhysicsParallelFor = false;
	CHAOS_API bool bDisableParticleParallelFor = false;
	CHAOS_API bool bDisableCollisionParallelFor = false;

	FAutoConsoleVariableRef CVarDisablePhysicsParallelFor(TEXT("p.Chaos.DisablePhysicsParallelFor"), bDisablePhysicsParallelFor, TEXT("Disable parallel execution in Chaos Evolution"));
	FAutoConsoleVariableRef CVarDisableParticleParallelFor(TEXT("p.Chaos.DisableParticleParallelFor"), bDisableParticleParallelFor, TEXT("Disable parallel execution for Chaos Particles (Collisions, "));
	FAutoConsoleVariableRef CVarDisableCollisionParallelFor(TEXT("p.Chaos.DisableCollisionParallelFor"), bDisableCollisionParallelFor, TEXT("Disable parallel execution for Chaos Collisions (also disabled by DisableParticleParallelFor)"));
	FAutoConsoleVariableRef CVarInnerPhysicsBatchSize(TEXT("p.Chaos.InnerParallelForBatchSize"), InnerParallelForBatchSize, TEXT("Set the batch size threshold for inner parallel fors"));
	FAutoConsoleVariableRef CVarMinRangeBatchSize(TEXT("p.Chaos.MinRangeBatchSize"), MinRangeBatchSize, TEXT("Set the min range batch size for parallel for"));
	FAutoConsoleVariableRef CVarMaxRangeBatchWorkers(TEXT("p.Chaos.MaxNumWorkers"), MaxNumWorkers, TEXT("Set the max number of workers for physics"));
	FAutoConsoleVariableRef CVarSmallBatchSize(TEXT("p.Chaos.SmallBatchSize"), SmallBatchSize, TEXT("Small batch size for chaos parallel loops"));
	FAutoConsoleVariableRef CVarLargeBatchSize(TEXT("p.Chaos.LargeBatchSize"), LargeBatchSize, TEXT("Large batch size for chaos parallel loops"));
#endif

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Public/Chaos/Collision/SpatialAccelerationBroadPhase.h:377

Scope (from outer to inner):

file
namespace    Chaos
class        class FSpatialAccelerationBroadPhase
function     void ProduceOverlaps

Source code excerpt:

					AssignMidPhases(BroadphaseContexts[ContextIndex]);
				};
				PhysicsParallelFor(NumActiveBroadphaseContexts, AssignMidPhasesWorker, bDisableCollisionParallelFor);

				// Merge all the midphases from each worker into the primary allocator
				Allocator->ProcessNewMidPhases();
			}

			// Run some error checks in non-shipping builds

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Public/Chaos/Collision/SpatialAccelerationBroadPhase.h:418

Scope (from outer to inner):

file
namespace    Chaos
class        class FSpatialAccelerationBroadPhase
function     void ProduceCollisions

Source code excerpt:

				ProcessMidPhases(Dt, BroadphaseContexts[ContextIndex]);
			};
			PhysicsParallelFor(NumActiveBroadphaseContexts, ProcessMidPhasesWorker, bDisableCollisionParallelFor);
		}

		/** @brief This function is the outer loop of collision detection. It loops over the
		 * particles view and do the broadphase + narrowphase collision detection
		 * @param OverlapView View to consider for the outer loop
		 * @param Dt Current simulation time step

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Public/Chaos/Collision/SpatialAccelerationBroadPhase.h:485

Scope (from outer to inner):

file
namespace    Chaos
class        class FSpatialAccelerationBroadPhase
function     void ComputeParticlesOverlaps

Source code excerpt:

					ProduceParticleOverlaps<bOnlyRigid>(Dt, Particle1.Handle(), InSpatialAcceleration, BroadphaseContexts[ContextIndex]);
				};
				OverlapView.ParallelFor(ContextCreator, ProduceOverlapsWorker, bDisableCollisionParallelFor);
			}
		}

		template<typename T_SPATIALACCELERATION>
		void ProduceOverlaps(
			FReal Dt,

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Public/Chaos/Collision/SpatialAccelerationBroadPhase.h:502

Scope (from outer to inner):

file
namespace    Chaos
class        class FSpatialAccelerationBroadPhase
function     void ProduceOverlaps

Source code excerpt:

			// visiting pairs that cannot collide (e.g., kinemtic-kinematic, or kinematic-sleeping for
			// stationary kinematics)
			const bool bDisableParallelFor = bDisableCollisionParallelFor;
			if(!bNeedsResim)
			{
				const TParticleView<TPBDRigidParticles<FReal, 3>>& DynamicSleepingView = Particles.GetNonDisabledDynamicView();
				const TParticleView<TPBDRigidParticles<FReal, 3>>& DynamicMovingKinematicView = Particles.GetActiveDynamicMovingKinematicParticlesView();

				// Usually we ignore sleeping particles in the outer loop and iterate over awake-dynamics and moving-kinematics.

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Public/Chaos/Framework/Parallel.h:20

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

	const bool bDisablePhysicsParallelFor = false;
	const bool bDisableParticleParallelFor = false;
	const bool bDisableCollisionParallelFor = false;
#else
	CHAOS_API extern bool bDisablePhysicsParallelFor;
	CHAOS_API extern bool bDisableParticleParallelFor;
	CHAOS_API extern bool bDisableCollisionParallelFor;
#endif
}