p.Chaos.LargeBatchSize

p.Chaos.LargeBatchSize

#Overview

name: p.Chaos.LargeBatchSize

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.LargeBatchSize is to set the large batch size for Chaos parallel loops in Unreal Engine 5’s physics system. This setting variable is used to control the granularity of work distribution in parallel processing tasks within the Chaos physics engine.

This setting variable is primarily used in the Chaos physics subsystem, which is part of Unreal Engine’s experimental physics framework. It is referenced in the Chaos namespace, indicating its specific use within this physics module.

The value of this variable is set through a console variable (CVar) system, as seen in the FAutoConsoleVariableRef CVarLargeBatchSize declaration. This allows for runtime modification of the value, which can be useful for performance tuning.

The p.Chaos.LargeBatchSize variable interacts closely with its associated variable LargeBatchSize. They share the same value, with p.Chaos.LargeBatchSize being the console-accessible name and LargeBatchSize being the actual variable used in the code.

Developers should be aware that this variable directly impacts the performance of parallel physics calculations. A larger batch size can reduce overhead in task distribution but may lead to less even work distribution among worker threads. Conversely, a smaller batch size can improve load balancing but increase overhead.

Best practices when using this variable include:

  1. Experiment with different values to find the optimal balance for your specific use case.
  2. Consider the complexity and number of physics objects in your scene when adjusting this value.
  3. Use profiling tools to measure the impact of changes to this variable on overall physics performance.
  4. Be cautious when modifying this value at runtime, as it can have significant performance implications.

Regarding the associated variable LargeBatchSize:

The purpose of LargeBatchSize is to serve as the internal representation of the large batch size for Chaos parallel loops. It is used directly in the code to control the granularity of parallel tasks.

This variable is used within the Chaos physics subsystem, specifically in parallel processing functions like InnerPhysicsParallelFor and in collision event registration.

The value of LargeBatchSize is set through the p.Chaos.LargeBatchSize console variable, allowing for easy runtime modification.

LargeBatchSize interacts closely with p.Chaos.LargeBatchSize, as well as other variables like SmallBatchSize and MaxNumWorkers, which together control the parallelization behavior of the Chaos physics system.

Developers should be aware that modifying LargeBatchSize directly in code is not recommended, as it may be overwritten by the console variable system. Instead, they should use the p.Chaos.LargeBatchSize console variable to adjust this value.

Best practices for LargeBatchSize include:

  1. Use the console variable p.Chaos.LargeBatchSize to modify this value rather than changing it directly in code.
  2. Consider the relationship between LargeBatchSize and SmallBatchSize when tuning performance.
  3. Monitor the impact of changes to this variable on physics performance, especially in scenes with many physics objects.

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

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

	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
}

void Chaos::InnerPhysicsParallelFor(int32 Num, TFunctionRef<void(int32)> InCallable, bool bForceSingleThreaded)
{
	int32 NumWorkers = int32(LowLevelTasks::FScheduler::Get().GetNumWorkers());

#Associated Variable and Callsites

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

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

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

	CHAOS_API int32 MaxNumWorkers = 100;
	CHAOS_API int32 SmallBatchSize = 10;
	CHAOS_API int32 LargeBatchSize = 100;
	
#if !UE_BUILD_SHIPPING
	CHAOS_API bool bDisablePhysicsParallelFor = false;
	CHAOS_API bool bDisableParticleParallelFor = false;
	CHAOS_API bool bDisableCollisionParallelFor = false;

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

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

	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
}

void Chaos::InnerPhysicsParallelFor(int32 Num, TFunctionRef<void(int32)> InCallable, bool bForceSingleThreaded)
{
	int32 NumWorkers = int32(LowLevelTasks::FScheduler::Get().GetNumWorkers());

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/EventDefaults.cpp:174

Scope (from outer to inner):

file
namespace    Chaos
function     void FEventDefaults::RegisterCollisionEvent
lambda-function

Source code excerpt:

							}
						}
					}, Chaos::LargeBatchSize);
					for (int32 Index = 0; Index < CollisionHandles.Num(); ++Index)
					{
						if (ValidArray[Index])
						{
							const Chaos::FPBDCollisionConstraintHandle* ContactHandle = CollisionHandles[Index];
							ValidCollisionHandles[NumValidCollisions] = ContactHandle;

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

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

	CHAOS_API extern int32 MaxNumWorkers;
	CHAOS_API extern int32 SmallBatchSize;
	CHAOS_API extern int32 LargeBatchSize;
#if UE_BUILD_SHIPPING
	const bool bDisablePhysicsParallelFor = false;
	const bool bDisableParticleParallelFor = false;
	const bool bDisableCollisionParallelFor = false;
#else
	CHAOS_API extern bool bDisablePhysicsParallelFor;