Physics.Solvers.Contact

This is the backbone of the physics engine. The functions here find contacts between objects and generate and solve constraints for these contacts. It exploits temporal coherence of the scene by caching constraint solutions between frames. This way, it can accumulate stability over time instead of requiring many solver iterations each frame.

The functions in this module are designed to be used in this order:

1. prepareFrame - Which contacts are creating constraints for us to solve this frame?
2. applyCachedSlns - Build this frame's Lagrangian and constraint caches. Apply relevant Lagrangians from the previous frame.
3. improveWorld - Iteratively solve the constraints and update the cached Lagrangians. (Can do this step multiple times.)

The cache of Lagrangians should be retained for the next frame's applyCachedSlns.

Documentation

prepareFrame

Arguments

:: PhysicsWorld k w o

=> Descending (k, k)

broadphase-filtered pairs of shapes to check for contact

-> w

the world

-> Descending (ObjectFeatureKey k, Flipping Contact')

list of contacts between shapes (in descending order of ObjectFeatureKey because the caches are ordered)

Calculate all contacts for the current frame.

applySln

Arguments

:: ContactResult Lagrangian

the solution

-> ContactResult Constraint

the constraint

-> (PhysicalObj, PhysicalObj)

-> (PhysicalObj, PhysicalObj)

Update a pair of shapes based on the solution to their constraint.

applyCachedSlns

Arguments

:: (Unbox k, PhysicsWorld k w o)

=> ContactBehavior

-> Double

dt

-> Descending (ObjectFeatureKey k, Flipping Contact')

list of contacts between shapes

-> MVector s (ObjectFeatureKey k, ContactResult Lagrangian)

list of constraint solutions from the previous frame

-> w

the world

-> ST s (MVector s (ObjectFeatureKey k, ContactResult Lagrangian), Vector (ContactResult Constraint), w)

(this frame's constraint solutions, this frame's constraints, the updated world)

Calculate all new constraints from the contacts. Apply cached lagrangians using new constraints. Build new lagrangians cache with either zero or previously cached value.

TODO: reader monad for stuff that's const between frames (beh, dt)

improveSln

Arguments

:: (Unbox k, Contactable o)

=> SolutionProcessor (Double, Double) (ContactResult Lagrangian)

-> ObjectFeatureKey k

identifies the contact: which objects, and which features within the objects

-> Int

index in the solution/constraint caches

-> MVector s (ObjectFeatureKey k, ContactResult Lagrangian)

solution cache

-> Vector (ContactResult Constraint)

constraint cache

-> (o, o)

pair of objects

-> ST s (o, o)

updated pair of objects

Solve the constraints for a given contact. (And apply the solution.)

improveWorld' :: (Unbox k, PhysicsWorld k w o) => SolutionProcessor (Double, Double) (ContactResult Lagrangian) -> ObjectFeatureKey k -> Int -> MVector s (ObjectFeatureKey k, ContactResult Lagrangian) -> Vector (ContactResult Constraint) -> w -> ST s w

Wraps improveSln to operate on the world instead of a pair of objects.

improveWorld :: (Unbox k, PhysicsWorld k w o) => SolutionProcessor (Double, Double) (ContactResult Lagrangian) -> Descending (ObjectFeatureKey k, Flipping Contact') -> MVector s (ObjectFeatureKey k, ContactResult Lagrangian) -> Vector (ContactResult Constraint) -> w -> ST s w

Run improveSln on every constraint in the world.