p.Chaos.XPBDBending.ParallelConstraintCount

p.Chaos.XPBDBending.ParallelConstraintCount

#Overview

name: p.Chaos.XPBDBending.ParallelConstraintCount

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

It is referenced in 7 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of p.Chaos.XPBDBending.ParallelConstraintCount is to determine the threshold for using parallel processing in the XPBD (Extended Position Based Dynamics) bending constraint calculations within Unreal Engine’s Chaos physics system.

This setting variable is primarily used in the Chaos physics system, specifically in the Softs subsystem which handles soft body simulations like cloth. It’s part of the Experimental Chaos module in Unreal Engine 5.

The value of this variable is set through a console variable (CVar) named “p.Chaos.XPBDBending.ParallelConstraintCount”. It’s initialized with a default value of 100 in the source code.

This variable interacts closely with the associated variable Chaos_XPBDBending_ParallelConstraintCount. They share the same value and are used interchangeably in the code.

Developers should be aware that this variable affects performance and simulation accuracy. If the number of constraints exceeds this threshold, the system will use parallel processing for constraint calculations, which can significantly improve performance for complex simulations.

Best practices when using this variable include:

  1. Adjusting it based on the complexity of your soft body simulations and your target hardware capabilities.
  2. Profiling your game to find the optimal value that balances performance and simulation accuracy.
  3. Consider increasing this value on high-end hardware to take advantage of more parallel processing.

Regarding the associated variable Chaos_XPBDBending_ParallelConstraintCount:

Developers should treat both variables as effectively the same, as they’re linked through the console variable system. Adjusting one will affect the other, and they should be considered together when optimizing soft body simulations in Unreal Engine 5’s Chaos physics 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/XPBDBendingConstraints.cpp:22

Scope (from outer to inner):

file
namespace    Chaos::Softs

Source code excerpt:

// @todo(chaos): the parallel threshold (or decision to run parallel) should probably be owned by the solver and passed to the constraint container
int32 Chaos_XPBDBending_ParallelConstraintCount = 100;
FAutoConsoleVariableRef CVarChaosXPBDBendingParallelConstraintCount(TEXT("p.Chaos.XPBDBending.ParallelConstraintCount"), Chaos_XPBDBending_ParallelConstraintCount, TEXT("If we have more constraints than this, use parallel-for in Apply."));

#if !UE_BUILD_SHIPPING
bool bChaos_XPBDBending_SplitLambdaDamping = true;
FAutoConsoleVariableRef CVarChaosXPBDBendingSplitLambdaDamping(TEXT("p.Chaos.XPBDBending.SplitLambdaDamping"), bChaos_XPBDBending_SplitLambdaDamping, TEXT("Use the split two-pass damping model (slower but doesn't make cloth too soft at high damping levels)."));
#endif

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/XPBDAnisotropicBendingConstraints.cpp:22

Scope (from outer to inner):

file
namespace    Chaos::Softs

Source code excerpt:


// @todo(chaos): the parallel threshold (or decision to run parallel) should probably be owned by the solver and passed to the constraint container
extern int32 Chaos_XPBDBending_ParallelConstraintCount;

static int32 Chaos_XPBDBending_ISPC_ParallelBatchSize = 1028;
static int32 Chaos_XPBDBending_ISPC_MinNumParallelBatches = 1028;  // effectively disabled for now
FAutoConsoleVariableRef CVarChaosXPBDBendingISPCParallelBatchSize(TEXT("p.Chaos.XPBDBending.ISPC.ParallelBatchSize"), Chaos_XPBDBending_ISPC_ParallelBatchSize, TEXT("Parallel batch size for ISPC XPBDBending constraints"));
FAutoConsoleVariableRef CVarChaosXPBDBendingISPCMinNumParallelBatches(TEXT("p.Chaos.XPBDBending.ISPC.MinNumParallelBatches"), Chaos_XPBDBending_ISPC_MinNumParallelBatches, TEXT("Min number of batches to invoke parallelFor ISPC XPBDBending constraints"));

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/XPBDAnisotropicBendingConstraints.cpp:341

Scope (from outer to inner):

file
namespace    Chaos::Softs
function     void FXPBDAnisotropicBendingConstraints::InitColor

Source code excerpt:

	// In dev builds we always color so we can tune the system without restarting. See Apply()
#if UE_BUILD_SHIPPING || UE_BUILD_TEST
	if (Constraints.Num() > Chaos_XPBDBending_ParallelConstraintCount)
#endif
	{
		const TArray<TArray<int32>> ConstraintsPerColor = FGraphColoring::ComputeGraphColoringParticlesOrRange(Constraints, InParticles, ParticleOffset, ParticleOffset + ParticleCount);

		// Reorder constraints based on color so each array in ConstraintsPerColor contains contiguous elements.
		TArray<TVec4<int32>> ReorderedConstraints;

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/XPBDAnisotropicBendingConstraints.cpp:665

Scope (from outer to inner):

file
namespace    Chaos::Softs
function     void FXPBDAnisotropicBendingConstraints::InitColor
function     void FXPBDAnisotropicBendingConstraints::Apply

Source code excerpt:

	const bool DampingHasWeightMap = DampingRatio.HasWeightMap();

	if (ConstraintsPerColorStartIndex.Num() > 0 && Constraints.Num() > Chaos_XPBDBending_ParallelConstraintCount)
	{
		const int32 ConstraintColorNum = ConstraintsPerColorStartIndex.Num() - 1;
#if INTEL_ISPC
		if (bRealTypeCompatibleWithISPC && bChaos_XPBDBending_ISPC_Enabled)
		{
			if (!StiffnessHasWeightMap && !StiffnessWeftHasWeightMap && !StiffnessBiasHasWeightMap &&

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/XPBDBendingConstraints.cpp:21

Scope (from outer to inner):

file
namespace    Chaos::Softs

Source code excerpt:


// @todo(chaos): the parallel threshold (or decision to run parallel) should probably be owned by the solver and passed to the constraint container
int32 Chaos_XPBDBending_ParallelConstraintCount = 100;
FAutoConsoleVariableRef CVarChaosXPBDBendingParallelConstraintCount(TEXT("p.Chaos.XPBDBending.ParallelConstraintCount"), Chaos_XPBDBending_ParallelConstraintCount, TEXT("If we have more constraints than this, use parallel-for in Apply."));

#if !UE_BUILD_SHIPPING
bool bChaos_XPBDBending_SplitLambdaDamping = true;
FAutoConsoleVariableRef CVarChaosXPBDBendingSplitLambdaDamping(TEXT("p.Chaos.XPBDBending.SplitLambdaDamping"), bChaos_XPBDBending_SplitLambdaDamping, TEXT("Use the split two-pass damping model (slower but doesn't make cloth too soft at high damping levels)."));
#endif

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/XPBDBendingConstraints.cpp:34

Scope (from outer to inner):

file
namespace    Chaos::Softs
function     void FXPBDBendingConstraints::InitColor

Source code excerpt:

	// In dev builds we always color so we can tune the system without restarting. See Apply()
#if UE_BUILD_SHIPPING || UE_BUILD_TEST
	if (Constraints.Num() > Chaos_XPBDBending_ParallelConstraintCount)
#endif
	{
		const TArray<TArray<int32>> ConstraintsPerColor = FGraphColoring::ComputeGraphColoringParticlesOrRange(Constraints, InParticles, ParticleOffset, ParticleOffset + ParticleCount);

		// Reorder constraints based on color so each array in ConstraintsPerColor contains contiguous elements.
		TArray<TVec4<int32>> ReorderedConstraints;

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/XPBDBendingConstraints.cpp:247

Scope (from outer to inner):

file
namespace    Chaos::Softs
function     void FXPBDBendingConstraints::InitColor
function     void FXPBDBendingConstraints::Apply

Source code excerpt:

	const bool DampingHasWeightMap = DampingRatio.HasWeightMap();

	if (ConstraintsPerColorStartIndex.Num() > 0 && Constraints.Num() > Chaos_XPBDBending_ParallelConstraintCount)
	{
		const int32 ConstraintColorNum = ConstraintsPerColorStartIndex.Num() - 1;

#if INTEL_ISPC
		if (bRealTypeCompatibleWithISPC && bChaos_XPBDBending_ISPC_Enabled)
		{