p.Chaos.XPBDSpring.SplitDamping
p.Chaos.XPBDSpring.SplitDamping
#Overview
name: p.Chaos.XPBDSpring.SplitDamping
This variable is created as a Console Variable (cvar).
- type:
Var - help:
Test xpbd spring split damping mode. 0 = single lambda, 1 = interleaved with damping after (non-ispc only), 2 interleaved with damping before (non-ispc only), 3 = two passes damping after (non-ispc only), 4 = two passes damping before (default).
It is referenced in 24 C++ source files.
#Summary
#Usage in the C++ source code
The purpose of p.Chaos.XPBDSpring.SplitDamping is to control the damping mode for XPBD (Extended Position Based Dynamics) spring constraints in Unreal Engine’s Chaos physics system. This setting variable is specifically used for testing different damping modes in the spring constraint solver.
-
The Chaos physics system, part of Unreal Engine’s experimental features, relies on this setting variable.
-
The value of this variable is set through a console variable (CVar) named “p.Chaos.XPBDSpring.SplitDamping”. It can be changed at runtime through the console or configuration files.
-
This variable interacts closely with Chaos_XPBDSpring_SplitDampingMode, which stores the actual integer value representing the damping mode.
-
Developers must be aware that this variable affects the behavior of spring constraints in the physics simulation. Different modes can result in varying levels of stability and performance.
-
Best practices include:
- Testing different modes to find the best balance between stability and performance for your specific use case.
- Being cautious when changing this value in shipping builds, as it can significantly impact simulation behavior.
The associated variable Chaos_XPBDSpring_SplitDampingMode is an integer that directly represents the chosen damping mode. It’s used throughout the code to determine the specific damping behavior to apply. The modes are:
0 = Single lambda 1 = Interleaved with damping after (non-ISPC only) 2 = Interleaved with damping before (non-ISPC only) 3 = Two passes damping after (non-ISPC only) 4 = Two passes damping before (default)
This variable is crucial in controlling the spring constraint solver’s behavior and should be handled with care, especially when optimizing physics simulations in Unreal Engine projects using the Chaos 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/XPBDSpringConstraints.cpp:33
Scope (from outer to inner):
file
namespace Chaos::Softs
Source code excerpt:
int32 Chaos_XPBDSpring_SplitDampingMode = (int32)EXPBDSplitDampingMode::TwoPassBefore;
FAutoConsoleVariableRef CVarChaosXPBDSpringSplitDamping(TEXT("p.Chaos.XPBDSpring.SplitDamping"), Chaos_XPBDSpring_SplitDampingMode, TEXT("Test xpbd spring split damping mode. 0 = single lambda, 1 = interleaved with damping after (non-ispc only), 2 interleaved with damping before (non-ispc only), 3 = two passes damping after (non-ispc only), 4 = two passes damping before (default)."));
#endif
template<typename SolverParticlesOrRange>
void FXPBDSpringConstraints::InitColor(const SolverParticlesOrRange& Particles)
{
// In dev builds we always color so we can tune the system without restarting. See Apply()
#Associated Variable and Callsites
This variable is associated with another variable named Chaos_XPBDSpring_SplitDampingMode. They share the same value. See the following C++ source code.
#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/XPBDAnisotropicSpringConstraints.cpp:373
Scope (from outer to inner):
file
function void FXPBDAnisotropicEdgeSpringConstraints::Apply
Source code excerpt:
if (bRealTypeCompatibleWithISPC && bChaos_XPBDSpring_ISPC_Enabled)
{
const bool bSingleLambda = Chaos_XPBDSpring_SplitDampingMode == (int32)EXPBDSplitDampingMode::SingleLambda;
if (!StiffnessHasWeightMap && !StiffnessWeftHasWeightMap && !StiffnessBiasHasWeightMap && !DampingHasWeightMap)
{
const FSolverVec3 ExpStiffnessValue((FSolverReal)StiffnessWeft, (FSolverReal)StiffnessWarp, (FSolverReal)StiffnessBias);
const FSolverReal DampingRatioValue = (FSolverReal)DampingRatio;
if (ExpStiffnessValue.Max() <= MinStiffness)
#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/XPBDAnisotropicSpringConstraints.cpp:539
Scope (from outer to inner):
file
function void FXPBDAnisotropicEdgeSpringConstraints::Apply
Source code excerpt:
if (DampingNoMap > 0 || DampingHasWeightMap)
{
if (Chaos_XPBDSpring_SplitDampingMode == (int32)EXPBDSplitDampingMode::TwoPassBefore)
{
for (int32 ConstraintColorIndex = 0; ConstraintColorIndex < ConstraintColorNum; ++ConstraintColorIndex)
{
const int32 ColorStart = ConstraintsPerColorStartIndex[ConstraintColorIndex];
const int32 ColorSize = ConstraintsPerColorStartIndex[ConstraintColorIndex + 1] - ColorStart;
PhysicsParallelFor(ColorSize, [this, &Particles, Dt, ColorStart, StiffnessHasWeightMap, StiffnessNoMap, StiffnessWeftHasWeightMap, StiffnessWeftNoMap, StiffnessBiasHasWeightMap, StiffnessBiasNoMap, DampingHasWeightMap, DampingNoMap](const int32 Index)
#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/XPBDAnisotropicSpringConstraints.cpp:562
Scope (from outer to inner):
file
function void FXPBDAnisotropicEdgeSpringConstraints::Apply
Source code excerpt:
// Stretch part (possibly with damping depending on split mode)
switch (Chaos_XPBDSpring_SplitDampingMode)
{
case (int32)EXPBDSplitDampingMode::TwoPassBefore: // fallthrough
case (int32)EXPBDSplitDampingMode::TwoPassAfter: // fallthrough
default:
{
// Do a pass with stretch only
#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/XPBDAnisotropicSpringConstraints.cpp:659
Scope (from outer to inner):
file
function void FXPBDAnisotropicEdgeSpringConstraints::Apply
Source code excerpt:
break;
}
if (Chaos_XPBDSpring_SplitDampingMode == (int32)EXPBDSplitDampingMode::TwoPassAfter)
{
for (int32 ConstraintColorIndex = 0; ConstraintColorIndex < ConstraintColorNum; ++ConstraintColorIndex)
{
const int32 ColorStart = ConstraintsPerColorStartIndex[ConstraintColorIndex];
const int32 ColorSize = ConstraintsPerColorStartIndex[ConstraintColorIndex + 1] - ColorStart;
PhysicsParallelFor(ColorSize, [this, &Particles, Dt, ColorStart, StiffnessHasWeightMap, StiffnessNoMap, StiffnessWeftHasWeightMap, StiffnessWeftNoMap, StiffnessBiasHasWeightMap, StiffnessBiasNoMap, DampingHasWeightMap, DampingNoMap](const int32 Index)
#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/XPBDAnisotropicSpringConstraints.cpp:713
Scope (from outer to inner):
file
function void FXPBDAnisotropicEdgeSpringConstraints::Apply
Source code excerpt:
if (DampingNoMap > 0 || DampingHasWeightMap)
{
if (Chaos_XPBDSpring_SplitDampingMode == (int32)EXPBDSplitDampingMode::TwoPassBefore)
{
for (int32 ConstraintIndex = 0; ConstraintIndex < Constraints.Num(); ++ConstraintIndex)
{
constexpr bool bDampingBefore = true;
constexpr bool bSingleLambda = false;
constexpr bool bSeparateStretch = false;
#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/XPBDAnisotropicSpringConstraints.cpp:730
Scope (from outer to inner):
file
function void FXPBDAnisotropicEdgeSpringConstraints::Apply
Source code excerpt:
// Stretch part (possibly with damping depending on split mode)
switch (Chaos_XPBDSpring_SplitDampingMode)
{
case (int32)EXPBDSplitDampingMode::TwoPassBefore: // fallthrough
case (int32)EXPBDSplitDampingMode::TwoPassAfter: // fallthrough
default:
{
// Do a pass with stretch only
#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/XPBDAnisotropicSpringConstraints.cpp:803
Scope (from outer to inner):
file
function void FXPBDAnisotropicEdgeSpringConstraints::Apply
Source code excerpt:
break;
}
if (Chaos_XPBDSpring_SplitDampingMode == (int32)EXPBDSplitDampingMode::TwoPassAfter)
{
for (int32 ConstraintIndex = 0; ConstraintIndex < Constraints.Num(); ++ConstraintIndex)
{
constexpr bool bDampingBefore = false;
constexpr bool bSingleLambda = false;
constexpr bool bSeparateStretch = false;
#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/XPBDAnisotropicSpringConstraints.cpp:1266
Scope (from outer to inner):
file
function void FXPBDAnisotropicAxialSpringConstraints::InitColor
function void FXPBDAnisotropicAxialSpringConstraints::Apply
Source code excerpt:
if (bRealTypeCompatibleWithISPC && bChaos_XPBDSpring_ISPC_Enabled)
{
const bool bSingleLambda = Chaos_XPBDSpring_SplitDampingMode == (int32)EXPBDSplitDampingMode::SingleLambda;
if (!StiffnessHasWeightMap && !StiffnessWeftHasWeightMap && !StiffnessBiasHasWeightMap && !DampingHasWeightMap)
{
const FSolverVec3 ExpStiffnessValue((FSolverReal)StiffnessWeft, (FSolverReal)StiffnessWarp, (FSolverReal)StiffnessBias);
const FSolverReal DampingRatioValue = (FSolverReal)DampingRatio;
if (ExpStiffnessValue.Max() <= MinStiffness)
#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/XPBDAnisotropicSpringConstraints.cpp:1438
Scope (from outer to inner):
file
function void FXPBDAnisotropicAxialSpringConstraints::InitColor
function void FXPBDAnisotropicAxialSpringConstraints::Apply
Source code excerpt:
if (DampingNoMap > 0 || DampingHasWeightMap)
{
if (Chaos_XPBDSpring_SplitDampingMode == (int32)EXPBDSplitDampingMode::TwoPassBefore)
{
for (int32 ConstraintColorIndex = 0; ConstraintColorIndex < ConstraintColorNum; ++ConstraintColorIndex)
{
const int32 ColorStart = ConstraintsPerColorStartIndex[ConstraintColorIndex];
const int32 ColorSize = ConstraintsPerColorStartIndex[ConstraintColorIndex + 1] - ColorStart;
PhysicsParallelFor(ColorSize, [this, &Particles, Dt, ColorStart, StiffnessHasWeightMap, StiffnessNoMap, StiffnessWeftHasWeightMap, StiffnessWeftNoMap, StiffnessBiasHasWeightMap, StiffnessBiasNoMap, DampingHasWeightMap, DampingNoMap](const int32 Index)
#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/XPBDAnisotropicSpringConstraints.cpp:1461
Scope (from outer to inner):
file
function void FXPBDAnisotropicAxialSpringConstraints::InitColor
function void FXPBDAnisotropicAxialSpringConstraints::Apply
Source code excerpt:
// Stretch part (possibly with damping depending on split mode)
switch (Chaos_XPBDSpring_SplitDampingMode)
{
case (int32)EXPBDSplitDampingMode::TwoPassBefore: // fallthrough
case (int32)EXPBDSplitDampingMode::TwoPassAfter: // fallthrough
default:
{
// Do a pass with stretch only
#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/XPBDAnisotropicSpringConstraints.cpp:1558
Scope (from outer to inner):
file
function void FXPBDAnisotropicAxialSpringConstraints::InitColor
function void FXPBDAnisotropicAxialSpringConstraints::Apply
Source code excerpt:
break;
}
if (Chaos_XPBDSpring_SplitDampingMode == (int32)EXPBDSplitDampingMode::TwoPassAfter)
{
for (int32 ConstraintColorIndex = 0; ConstraintColorIndex < ConstraintColorNum; ++ConstraintColorIndex)
{
const int32 ColorStart = ConstraintsPerColorStartIndex[ConstraintColorIndex];
const int32 ColorSize = ConstraintsPerColorStartIndex[ConstraintColorIndex + 1] - ColorStart;
PhysicsParallelFor(ColorSize, [this, &Particles, Dt, ColorStart, StiffnessHasWeightMap, StiffnessNoMap, StiffnessWeftHasWeightMap, StiffnessWeftNoMap, StiffnessBiasHasWeightMap, StiffnessBiasNoMap, DampingHasWeightMap, DampingNoMap](const int32 Index)
#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/XPBDAnisotropicSpringConstraints.cpp:1612
Scope (from outer to inner):
file
function void FXPBDAnisotropicAxialSpringConstraints::InitColor
function void FXPBDAnisotropicAxialSpringConstraints::Apply
Source code excerpt:
if (DampingNoMap > 0 || DampingHasWeightMap)
{
if (Chaos_XPBDSpring_SplitDampingMode == (int32)EXPBDSplitDampingMode::TwoPassBefore)
{
for (int32 ConstraintIndex = 0; ConstraintIndex < Constraints.Num(); ++ConstraintIndex)
{
constexpr bool bDampingBefore = true;
constexpr bool bSingleLambda = false;
constexpr bool bSeparateStretch = false;
#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/XPBDAnisotropicSpringConstraints.cpp:1629
Scope (from outer to inner):
file
function void FXPBDAnisotropicAxialSpringConstraints::InitColor
function void FXPBDAnisotropicAxialSpringConstraints::Apply
Source code excerpt:
// Stretch part (possibly with damping depending on split mode)
switch (Chaos_XPBDSpring_SplitDampingMode)
{
case (int32)EXPBDSplitDampingMode::TwoPassBefore: // fallthrough
case (int32)EXPBDSplitDampingMode::TwoPassAfter: // fallthrough
default:
{
// Do a pass with stretch only
#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/XPBDAnisotropicSpringConstraints.cpp:1702
Scope (from outer to inner):
file
function void FXPBDAnisotropicAxialSpringConstraints::InitColor
function void FXPBDAnisotropicAxialSpringConstraints::Apply
Source code excerpt:
break;
}
if (Chaos_XPBDSpring_SplitDampingMode == (int32)EXPBDSplitDampingMode::TwoPassAfter)
{
for (int32 ConstraintIndex = 0; ConstraintIndex < Constraints.Num(); ++ConstraintIndex)
{
constexpr bool bDampingBefore = false;
constexpr bool bSingleLambda = false;
constexpr bool bSeparateStretch = false;
#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/XPBDInternal.h:13
Scope (from outer to inner):
file
namespace Chaos::Softs
Source code excerpt:
};
#if UE_BUILD_SHIPPING
const int32 Chaos_XPBDSpring_SplitDampingMode = (int32)EXPBDSplitDampingMode::TwoPassBefore;
#else
extern int32 Chaos_XPBDSpring_SplitDampingMode;
#endif
} // End namespace Chaos::Softs
#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/XPBDSpringConstraints.cpp:32
Scope (from outer to inner):
file
namespace Chaos::Softs
Source code excerpt:
FAutoConsoleVariableRef CVarChaosXPBDSpringParallelConstraintCount(TEXT("p.Chaos.XPBDSpring.ParallelConstraintCount"), Chaos_XPBDSpring_ParallelConstraintCount, TEXT("If we have more constraints than this, use parallel-for in Apply."));
int32 Chaos_XPBDSpring_SplitDampingMode = (int32)EXPBDSplitDampingMode::TwoPassBefore;
FAutoConsoleVariableRef CVarChaosXPBDSpringSplitDamping(TEXT("p.Chaos.XPBDSpring.SplitDamping"), Chaos_XPBDSpring_SplitDampingMode, TEXT("Test xpbd spring split damping mode. 0 = single lambda, 1 = interleaved with damping after (non-ispc only), 2 interleaved with damping before (non-ispc only), 3 = two passes damping after (non-ispc only), 4 = two passes damping before (default)."));
#endif
template<typename SolverParticlesOrRange>
void FXPBDSpringConstraints::InitColor(const SolverParticlesOrRange& Particles)
{
// In dev builds we always color so we can tune the system without restarting. See Apply()
#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/XPBDSpringConstraints.cpp:132
Scope (from outer to inner):
file
namespace Chaos::Softs
function void FXPBDSpringConstraints::Apply
Source code excerpt:
if (bRealTypeCompatibleWithISPC && bChaos_XPBDSpring_ISPC_Enabled)
{
const bool bSingleLambda = Chaos_XPBDSpring_SplitDampingMode == (int32)EXPBDSplitDampingMode::SingleLambda;
if (!StiffnessHasWeightMap && !DampingHasWeightMap)
{
const FSolverReal ExpStiffnessValue = (FSolverReal)Stiffness;
const FSolverReal DampingRatioValue = (FSolverReal)DampingRatio;
if (ExpStiffnessValue < MinStiffness)
{
#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/XPBDSpringConstraints.cpp:271
Scope (from outer to inner):
file
namespace Chaos::Softs
function void FXPBDSpringConstraints::Apply
Source code excerpt:
if (DampingNoMap > 0 || DampingHasWeightMap)
{
if (Chaos_XPBDSpring_SplitDampingMode == (int32)EXPBDSplitDampingMode::TwoPassBefore)
{
for (int32 ConstraintColorIndex = 0; ConstraintColorIndex < ConstraintColorNum; ++ConstraintColorIndex)
{
const int32 ColorStart = ConstraintsPerColorStartIndex[ConstraintColorIndex];
const int32 ColorSize = ConstraintsPerColorStartIndex[ConstraintColorIndex + 1] - ColorStart;
PhysicsParallelFor(ColorSize, [this, &Particles, Dt, ColorStart, StiffnessHasWeightMap, StiffnessNoMap, DampingHasWeightMap, DampingNoMap](const int32 Index)
#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/XPBDSpringConstraints.cpp:292
Scope (from outer to inner):
file
namespace Chaos::Softs
function void FXPBDSpringConstraints::Apply
Source code excerpt:
// Stretch part (possibly with damping depending on split mode)
switch (Chaos_XPBDSpring_SplitDampingMode)
{
case (int32)EXPBDSplitDampingMode::TwoPassBefore: // fallthrough
case (int32)EXPBDSplitDampingMode::TwoPassAfter: // fallthrough
default:
{
// Do a pass with stretch only
#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/XPBDSpringConstraints.cpp:381
Scope (from outer to inner):
file
namespace Chaos::Softs
function void FXPBDSpringConstraints::Apply
Source code excerpt:
break;
}
if (Chaos_XPBDSpring_SplitDampingMode == (int32)EXPBDSplitDampingMode::TwoPassAfter)
{
for (int32 ConstraintColorIndex = 0; ConstraintColorIndex < ConstraintColorNum; ++ConstraintColorIndex)
{
const int32 ColorStart = ConstraintsPerColorStartIndex[ConstraintColorIndex];
const int32 ColorSize = ConstraintsPerColorStartIndex[ConstraintColorIndex + 1] - ColorStart;
PhysicsParallelFor(ColorSize, [this, &Particles, Dt, ColorStart, StiffnessHasWeightMap, StiffnessNoMap, DampingHasWeightMap, DampingNoMap](const int32 Index)
#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/XPBDSpringConstraints.cpp:429
Scope (from outer to inner):
file
namespace Chaos::Softs
function void FXPBDSpringConstraints::Apply
Source code excerpt:
if (DampingNoMap > 0 || DampingHasWeightMap)
{
if (Chaos_XPBDSpring_SplitDampingMode == (int32)EXPBDSplitDampingMode::TwoPassBefore)
{
for (int32 ConstraintIndex = 0; ConstraintIndex < Constraints.Num(); ++ConstraintIndex)
{
constexpr bool bDampingBefore = true;
constexpr bool bSingleLambda = false;
constexpr bool bSeparateStretch = false;
#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/XPBDSpringConstraints.cpp:444
Scope (from outer to inner):
file
namespace Chaos::Softs
function void FXPBDSpringConstraints::Apply
Source code excerpt:
// Stretch part (possibly with damping depending on split mode)
switch (Chaos_XPBDSpring_SplitDampingMode)
{
case (int32)EXPBDSplitDampingMode::TwoPassBefore: // fallthrough
case (int32)EXPBDSplitDampingMode::TwoPassAfter: // fallthrough
default:
{
// Do a pass with stretch only
#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/XPBDSpringConstraints.cpp:509
Scope (from outer to inner):
file
namespace Chaos::Softs
function void FXPBDSpringConstraints::Apply
Source code excerpt:
break;
}
if (Chaos_XPBDSpring_SplitDampingMode == (int32)EXPBDSplitDampingMode::TwoPassAfter)
{
for (int32 ConstraintIndex = 0; ConstraintIndex < Constraints.Num(); ++ConstraintIndex)
{
constexpr bool bDampingBefore = false;
constexpr bool bSingleLambda = false;
constexpr bool bSeparateStretch = false;