Table of Contents

Class Solver

Namespace
BepuPhysics
Assembly
BepuPhysics.dll

Holds and solves constraints between bodies in a simulation.

public abstract class Solver
Inheritance
Solver
Derived
Inherited Members

Constructors

Solver(Bodies, BufferPool, SolveDescription, int, int, int) 

protected Solver(Bodies bodies, BufferPool pool, SolveDescription solveDescription, int initialCapacity, int initialIslandCapacity, int minimumCapacityPerTypeBatch)

Parameters

bodies Bodies
pool BufferPool
solveDescription SolveDescription
initialCapacity int
initialIslandCapacity int
minimumCapacityPerTypeBatch int

Fields

ConstrainedKinematicHandles

Set of body handles associated with constrained kinematic bodies. These will be integrated during substepping.

public QuickSet<int, PrimitiveComparer<int>> ConstrainedKinematicHandles

Field Value

QuickSet<int, PrimitiveComparer<int>>

HandlePool

Pool to retrieve constraint handles from when creating new constraints.

public IdPool HandlePool

Field Value

IdPool

HandleToConstraint

Mapping from constraint handle (via its internal integer value) to the location of a constraint in memory.

public Buffer<ConstraintLocation> HandleToConstraint

Field Value

Buffer<ConstraintLocation>

Sets

Buffer containing all constraint sets. The first slot is dedicated to the active set; subsequent slots may be occupied by the constraints associated with inactive islands.

public Buffer<ConstraintSet> Sets

Field Value

Buffer<ConstraintSet>

TypeProcessors

Set of processors applied to batches of constraints of particular types, indexed by the constraint type id.

public TypeProcessor[] TypeProcessors

Field Value

TypeProcessor[]

substepCount 

protected int substepCount

Field Value

int

Properties

ActiveSet

Gets a reference to the active set of constraints, stored in the first set slot.

public ref ConstraintSet ActiveSet { get; }

Property Value

ConstraintSet

FallbackBatchThreshold

Gets the maximum number of solver batches to allow before resorting to a fallback solver. If a single body is constrained by more than FallbackBatchThreshold constraints, all constraints beyond FallbackBatchThreshold are placed into a fallback batch. The fallback batch uses a different solver that can handle multiple constraints affecting a single body in a single batch, allowing greater parallelism at the cost of convergence speed.

public int FallbackBatchThreshold { get; }

Property Value

int

MinimumCapacityPerTypeBatch

Gets or sets the minimum amount of space, in constraints, initially allocated in any new type batch.

public int MinimumCapacityPerTypeBatch { get; set; }

Property Value

int

SubstepCount

Gets or sets the number of substeps the solver will simulate per call to Solve.

public int SubstepCount { get; set; }

Property Value

int

VelocityIterationCount

Gets or sets the number of solver velocity iterations to compute per substep.

public int VelocityIterationCount { get; set; }

Property Value

int

VelocityIterationScheduler

Callback executed to determine how many velocity iterations should be used for a given substep. If null, or if it returns a non-positive value, the VelocityIterationCount will be used instead.

public SubstepVelocityIterationScheduler VelocityIterationScheduler { get; set; }

Property Value

SubstepVelocityIterationScheduler

Methods

Add<TDescription>(BodyHandle, BodyHandle, BodyHandle, BodyHandle, in TDescription)

Allocates a four-body constraint slot and sets up a constraint with the specified description.

public ConstraintHandle Add<TDescription>(BodyHandle bodyHandleA, BodyHandle bodyHandleB, BodyHandle bodyHandleC, BodyHandle bodyHandleD, in TDescription description) where TDescription : unmanaged, IFourBodyConstraintDescription<TDescription>

Parameters

bodyHandleA BodyHandle

First body of the constraint.

bodyHandleB BodyHandle

Second body of the constraint.

bodyHandleC BodyHandle

Third body of the constraint.

bodyHandleD BodyHandle

Fourth body of the constraint.

description TDescription

Description of the constraint to add.

Returns

ConstraintHandle

Allocated constraint handle.

Type Parameters

TDescription

Type of the constraint description to add.

Add<TDescription>(BodyHandle, BodyHandle, BodyHandle, in TDescription)

Allocates a three-body constraint slot and sets up a constraint with the specified description.

public ConstraintHandle Add<TDescription>(BodyHandle bodyHandleA, BodyHandle bodyHandleB, BodyHandle bodyHandleC, in TDescription description) where TDescription : unmanaged, IThreeBodyConstraintDescription<TDescription>

Parameters

bodyHandleA BodyHandle

First body of the constraint.

bodyHandleB BodyHandle

Second body of the constraint.

bodyHandleC BodyHandle

Third body of the constraint.

description TDescription

Description of the constraint to add.

Returns

ConstraintHandle

Allocated constraint handle.

Type Parameters

TDescription

Type of the constraint description to add.

Add<TDescription>(BodyHandle, BodyHandle, in TDescription)

Allocates a two-body constraint slot and sets up a constraint with the specified description.

public ConstraintHandle Add<TDescription>(BodyHandle bodyHandleA, BodyHandle bodyHandleB, in TDescription description) where TDescription : unmanaged, ITwoBodyConstraintDescription<TDescription>

Parameters

bodyHandleA BodyHandle

First body of the constraint.

bodyHandleB BodyHandle

Second body of the constraint.

description TDescription

Description of the constraint to add.

Returns

ConstraintHandle

Allocated constraint handle.

Type Parameters

TDescription

Type of the constraint description to add.

Add<TDescription>(BodyHandle, in TDescription)

Allocates a one-body constraint slot and sets up a constraint with the specified description.

public ConstraintHandle Add<TDescription>(BodyHandle bodyHandle, in TDescription description) where TDescription : unmanaged, IOneBodyConstraintDescription<TDescription>

Parameters

bodyHandle BodyHandle

Body connected to the constraint.

description TDescription

Description of the constraint to add.

Returns

ConstraintHandle

Allocated constraint handle.

Type Parameters

TDescription

Type of the constraint description to add.

Add<TDescription>(Span<BodyHandle>, in TDescription)

Allocates a constraint slot and sets up a constraint with the specified description.

public ConstraintHandle Add<TDescription>(Span<BodyHandle> bodyHandles, in TDescription description) where TDescription : unmanaged, IConstraintDescription<TDescription>

Parameters

bodyHandles Span<BodyHandle>

Body handles used by the constraint.

description TDescription

Description of the constraint to add.

Returns

ConstraintHandle

Allocated constraint handle.

Type Parameters

TDescription

Type of the constraint description to add.

ApplyDescriptionWithoutWaking<TDescription>(ConstraintHandle, in TDescription)

Applies a description to a constraint slot without waking up the associated island.

public void ApplyDescriptionWithoutWaking<TDescription>(ConstraintHandle constraintHandle, in TDescription description) where TDescription : unmanaged, IConstraintDescription<TDescription>

Parameters

constraintHandle ConstraintHandle

Handle of the constraint being updated.

description TDescription

Description to apply to the slot.

Type Parameters

TDescription

Type of the description to apply.

ApplyDescriptionWithoutWaking<TDescription>(in ConstraintReference, in TDescription)

Applies a description to a constraint slot without waking up the associated island.

public void ApplyDescriptionWithoutWaking<TDescription>(in ConstraintReference constraintReference, in TDescription description) where TDescription : unmanaged, IConstraintDescription<TDescription>

Parameters

constraintReference ConstraintReference

Reference of the constraint being updated.

description TDescription

Description to apply to the slot.

Type Parameters

TDescription

Type of the description to apply.

ApplyDescription<TDescription>(ConstraintHandle, in TDescription)

Applies a description to a constraint slot, waking up the connected bodies if necessary.

public void ApplyDescription<TDescription>(ConstraintHandle constraintHandle, in TDescription description) where TDescription : unmanaged, IConstraintDescription<TDescription>

Parameters

constraintHandle ConstraintHandle

Handle of the constraint being updated.

description TDescription

Description to apply to the slot.

Type Parameters

TDescription

Type of the description to apply.

Clear()

Removes all objects from the solver. This is meant as a fast path to empty a simulation's constraints. It makes no attempt to retain synchronization with other systems which may depend on the existence of constraints, like the per-body constraint lists.

public void Clear()

ConstraintExists(ConstraintHandle)

Gets whether the given constraint handle refers to a constraint in the solver.

public bool ConstraintExists(ConstraintHandle constraintHandle)

Parameters

constraintHandle ConstraintHandle

Constraint handle to check for existence in the solver.

Returns

bool

True if the constraint handle exists in the solver, false otherwise.

CountConstraints()

Gets the total number of constraints across all sets, batches, and types. Requires enumerating all type batches; this can be expensive.

public int CountConstraints()

Returns

int

CountConstraintsInTypeBatch(int, int, int)

Counts the number of constraints in a particular type batch.

public int CountConstraintsInTypeBatch(int setIndex, int batchIndex, int typeBatchIndex)

Parameters

setIndex int

Index of the set containing the type batch.

batchIndex int

Index of the batch containing the type batch.

typeBatchIndex int

Index of the type batch within the batch.

Returns

int

Number of constraints in the type batch.

Remarks

This handles whether the type batch is in the fallback batch or not. Active fallback batches are not guaranteed to have contiguous constraints, so the ConstraintCount value is an upper bound and there may be gaps.

Dispose()

Returns all pool-retrieved resources to the pool.

public void Dispose()

Remarks

The solver cannot be 'rehydrated' for reuse after a disposal. If you want to return bulk data to the pool while leaving the solver in a usable state, consider using Clear instead.

DisposeConstraintIntegrationResponsibilities() 

public abstract void DisposeConstraintIntegrationResponsibilities()

EnsureSolverCapacities(int, int)

Adjusts the size of the the solvers non-typebatch data structures. An allocation will grow if the given capacity exceeds the currently allocated capacity.

public void EnsureSolverCapacities(int bodyHandleCapacity, int constraintHandleCapacity)

Parameters

bodyHandleCapacity int

Size of the span of body handles to allocate space for. Applies to batch referenced handle sets.

constraintHandleCapacity int

Number of constraint handles to allocate space for. Applies to the handle->constraint mapping table.

EnsureTypeBatchCapacities()

Ensures all existing active type batches meet or exceed the current solver-defined minimum capacities. Type batches with capacities smaller than the minimums will be enlarged.

public void EnsureTypeBatchCapacities()

EnumerateAccumulatedImpulses<TEnumerator>(ConstraintHandle, ref TEnumerator)

Enumerates the accumulated impulses associated with a constraint.

public void EnumerateAccumulatedImpulses<TEnumerator>(ConstraintHandle constraintHandle, ref TEnumerator enumerator) where TEnumerator : IForEach<float>

Parameters

constraintHandle ConstraintHandle

Constraint to enumerate.

enumerator TEnumerator

Enumerator to use.

Type Parameters

TEnumerator

EnumerateConnectedBodyReferences<TEnumerator>(ConstraintHandle, ref TEnumerator)

Enumerates the set of body references associated with an active constraint in order of their references within the constraint. This will report the body reference (body index if awake, handle if asleep) without any encoded kinematicity metadata.

public void EnumerateConnectedBodyReferences<TEnumerator>(ConstraintHandle constraintHandle, ref TEnumerator enumerator) where TEnumerator : IForEach<int>

Parameters

constraintHandle ConstraintHandle

Constraint to enumerate.

enumerator TEnumerator

Enumerator to call for each connected body reference.

Type Parameters

TEnumerator

Type of the enumerator to call on each connected body reference.

EnumerateConnectedBodyReferences<TEnumerator>(ref TypeBatch, int, ref TEnumerator)

Enumerates the set of body references associated with an active constraint in order of their references within the constraint. This will report the body reference (body index if awake, handle if asleep) without any encoded kinematicity metadata.

public void EnumerateConnectedBodyReferences<TEnumerator>(ref TypeBatch typeBatch, int indexInTypeBatch, ref TEnumerator enumerator) where TEnumerator : IForEach<int>

Parameters

typeBatch TypeBatch

Type batch containing the constraint to enumerate.

indexInTypeBatch int

Index of the constraint to enumerate in the type batch.

enumerator TEnumerator

Enumerator to call for each connected body reference.

Type Parameters

TEnumerator

Type of the enumerator to call on each connected body reference.

EnumerateConnectedDynamicBodies<TEnumerator>(ConstraintHandle, ref TEnumerator)

Enumerates the set of dynamic body references associated with a constraint in order of their references within the constraint. This will report the body reference (body index if awake, handle if asleep) without any encoded kinematicity metadata. Kinematic references are skipped.

public void EnumerateConnectedDynamicBodies<TEnumerator>(ConstraintHandle constraintHandle, ref TEnumerator enumerator) where TEnumerator : IForEach<int>

Parameters

constraintHandle ConstraintHandle

Constraint to enumerate.

enumerator TEnumerator

Enumerator to call for each connected dynamic body reference.

Type Parameters

TEnumerator

Type of the enumerator to call on each connected dynamic body reference.

EnumerateConnectedDynamicBodies<TEnumerator>(ref TypeBatch, int, ref TEnumerator)

Enumerates the set of dynamic body references associated with a constraint in order of their references within the constraint. This will report the body reference (body index if awake, handle if asleep) without any encoded kinematicity metadata. Kinematic references are skipped.

public void EnumerateConnectedDynamicBodies<TEnumerator>(ref TypeBatch typeBatch, int indexInTypeBatch, ref TEnumerator enumerator) where TEnumerator : IForEach<int>

Parameters

typeBatch TypeBatch

Type batch containing the constraint to enumerate.

indexInTypeBatch int

Index of the constraint to enumerate in the type batch.

enumerator TEnumerator

Enumerator to call for each connected dynamic body reference.

Type Parameters

TEnumerator

Type of the enumerator to call on each connected dynamic body reference.

EnumerateConnectedRawBodyReferences<TEnumerator>(ConstraintHandle, ref TEnumerator)

Enumerates the set of body references associated with a constraint in order of their references within the constraint. This will report the raw body reference (body index if awake, handle if asleep) and any encoded metadata, like whether the body is kinematic.

public void EnumerateConnectedRawBodyReferences<TEnumerator>(ConstraintHandle constraintHandle, ref TEnumerator enumerator) where TEnumerator : IForEach<int>

Parameters

constraintHandle ConstraintHandle

Constraint to enumerate.

enumerator TEnumerator

Enumerator to call for each connected body reference.

Type Parameters

TEnumerator

Type of the enumerator to call on each connected body reference.

EnumerateConnectedRawBodyReferences<TEnumerator>(ref TypeBatch, int, ref TEnumerator)

Enumerates the set of body references associated with a constraint in order of their references within the constraint. This will report the raw body reference (body index if awake, handle if asleep) and any encoded metadata, like whether the body is kinematic.

public void EnumerateConnectedRawBodyReferences<TEnumerator>(ref TypeBatch typeBatch, int indexInTypeBatch, ref TEnumerator enumerator) where TEnumerator : IForEach<int>

Parameters

typeBatch TypeBatch

Type batch containing the constraint to enumerate.

indexInTypeBatch int

Index of the constraint to enumerate in the type batch.

enumerator TEnumerator

Enumerator to call for each connected body reference.

Type Parameters

TEnumerator

Type of the enumerator to call on each connected body reference.

GetAccumulatedImpulseMagnitude(ConstraintHandle)

Gathers the magnitude of the accumulated impulse for a given constraint.

public float GetAccumulatedImpulseMagnitude(ConstraintHandle constraintHandle)

Parameters

constraintHandle ConstraintHandle

Constraint to look up the accumulated impulses of.

Returns

float

Magnitude of the accumulated impulses associated with the given constraint.

GetAccumulatedImpulseMagnitudeSquared(ConstraintHandle)

Gathers the squared magnitude of the accumulated impulse for a given constraint.

public float GetAccumulatedImpulseMagnitudeSquared(ConstraintHandle constraintHandle)

Parameters

constraintHandle ConstraintHandle

Constraint to look up the accumulated impulses of.

Returns

float

Squared magnitude of the accumulated impulses associated with the given constraint.

GetConstraintReference(ConstraintHandle)

Gets a direct reference to the constraint associated with a handle. The reference is temporary; any constraint removals that affect the referenced type batch may invalidate the index.

public ConstraintReference GetConstraintReference(ConstraintHandle handle)

Parameters

handle ConstraintHandle

Handle index of the constraint.

Returns

ConstraintReference

Temporary direct reference to the type batch and index in the type batch associated with the constraint handle. May be invalidated by constraint removals.

GetDescription<TConstraintDescription>(ConstraintHandle, out TConstraintDescription)

Gets the constraint description associated with a constraint handle.

public void GetDescription<TConstraintDescription>(ConstraintHandle handle, out TConstraintDescription description) where TConstraintDescription : unmanaged, IConstraintDescription<TConstraintDescription>

Parameters

handle ConstraintHandle

Handle of the constraint to retrieve.

description TConstraintDescription

Retrieved description of the constraint.

Type Parameters

TConstraintDescription

Type of the constraint description to retrieve.

GetDescription<TConstraintDescription>(ConstraintReference, out TConstraintDescription)

Gets the constraint description associated with a constraint reference.

public void GetDescription<TConstraintDescription>(ConstraintReference constraintReference, out TConstraintDescription description) where TConstraintDescription : unmanaged, IConstraintDescription<TConstraintDescription>

Parameters

constraintReference ConstraintReference

Reference to the constraint to retrieve.

description TConstraintDescription

Retrieved description of the constraint.

Type Parameters

TConstraintDescription

Type of the constraint description to retrieve.

GetMinimumCapacityForType(int)

Gets the minimum initial capacity for a given type. The returned value is the larger of MinimumCapacityPerTypeBatch and the value set by SetMinimumCapacityForType for the given type id.

public int GetMinimumCapacityForType(int typeId)

Parameters

typeId int

Type id to retrieve the minm

Returns

int

Larger of MinimumCapacityPerTypeBatch and the given type's minimum set by SetMinimumCapacityForType.

OnSubstepEnded(int) 

protected void OnSubstepEnded(int substepIndex)

Parameters

substepIndex int

OnSubstepStarted(int) 

protected void OnSubstepStarted(int substepIndex)

Parameters

substepIndex int

PrepareConstraintIntegrationResponsibilities(IThreadDispatcher) 

public abstract IndexSet PrepareConstraintIntegrationResponsibilities(IThreadDispatcher threadDispatcher = null)

Parameters

threadDispatcher IThreadDispatcher

Returns

IndexSet

Register<TDescription>()

Registers a constraint type with the solver, creating a type processor for the type internally and allowing constraints of that type to be added to the solver.

public void Register<TDescription>() where TDescription : unmanaged, IConstraintDescription<TDescription>

Type Parameters

TDescription

Type of the constraint to register with the solver.

Remarks

RegisterDefaults(Solver, NarrowPhase) is called during simuation creation and registers all the built in types. Calling Register<TDescription>() manually is only necessary if custom types are used.

Exceptions

ArgumentException

Fired when another constraint type of the same id has already been registered.

Remove(ConstraintHandle)

Removes the constraint associated with the given handle. Note that this may invalidate any outstanding direct constraint references by reordering the constraints within the TypeBatch subject to removal.

public void Remove(ConstraintHandle handle)

Parameters

handle ConstraintHandle

Handle of the constraint to remove from the solver.

ResetPerTypeInitialCapacities()

Resets all per-type initial capacities to zero. Leaves the minimum capacity across all constraints unchanged.

public void ResetPerTypeInitialCapacities()

ResizeSolverCapacities(int, int)

Adjusts the size of the the solvers non-typebatch data structures. An allocation is allowed to shrink if it fits both all existing entries and the given capacity. An allocation will grow if the given capacity exceeds the currently allocated capacity.

public void ResizeSolverCapacities(int bodyHandleCapacity, int constraintHandleCapacity)

Parameters

bodyHandleCapacity int

Size of the span of body handles to allocate space for. Applies to batch referenced handle sets.

constraintHandleCapacity int

Number of constraint handles to allocate space for. Applies to the handle->constraint mapping table.

ResizeTypeBatchCapacities()

Applies the current solver-defined minimum capacities to existing type batches. Type batches with capacities larger than the minimums and counts less than the minimums may be shrunk. Type batches with capacities smaller than the minimums will be enlarged.

public void ResizeTypeBatchCapacities()

ScaleAccumulatedImpulses(ref ConstraintSet, float)

Scales the accumulated impulses associated with a constraint set by a given scale.

public void ScaleAccumulatedImpulses(ref ConstraintSet set, float scale)

Parameters

set ConstraintSet

Set to scale.

scale float

Scale to apply to accumulated impulses.

ScaleAccumulatedImpulses(float)

Scales all accumulated impulses in all constraint sets.

public void ScaleAccumulatedImpulses(float scale)

Parameters

scale float

Scale to apply to accumulated impulses.

ScaleActiveAccumulatedImpulses(float)

Scales all accumulated impulses in the active set.

public void ScaleActiveAccumulatedImpulses(float scale)

Parameters

scale float

Scale to apply to accumulated impulses.

SetMinimumCapacityForType(int, int)

Sets the minimum capacity initially allocated to a new type batch of the given type.

public void SetMinimumCapacityForType(int typeId, int minimumInitialCapacityForType)

Parameters

typeId int

Id of the constraint type to check the initial capacity of.

minimumInitialCapacityForType int

Minimum capacity to use for the type.

Solve(float, IThreadDispatcher) 

public abstract void Solve(float dt, IThreadDispatcher threadDispatcher = null)

Parameters

dt float
threadDispatcher IThreadDispatcher

Events

SubstepEnded

Event invoked when the solver completes a substep. If the solver is executing on multiple threads, this will be invoked within the multithreaded dispatch on worker thread 0.

public event Solver.SubstepEvent SubstepEnded

Event Type

Solver.SubstepEvent

Remarks

Take care when attempting to dispatch multithreaded operations from within this event. If using the same BepuUtilities.IThreadDispatcher instance as the solver, the dispatcher implementation must be reentrant. The demos implementation is not.

SubstepStarted

Event invoked when the solver begins a substep. If the solver is executing on multiple threads, this will be invoked within the multithreaded dispatch on worker thread 0.

public event Solver.SubstepEvent SubstepStarted

Event Type

Solver.SubstepEvent

Remarks

Take care when attempting to dispatch multithreaded operations from within this event. If using the same BepuUtilities.IThreadDispatcher instance as the solver, the dispatcher implementation must be reentrant. The demos implementation is not.

Edit this page