Trait XpbdConstraint

pub trait XpbdConstraint<const ENTITY_COUNT: usize>: MapEntities {
    // Required methods
    fn entities(&self) -> [Entity; ENTITY_COUNT];
    fn solve(
        &mut self,
        bodies: [&mut RigidBodyQueryItem<'_>; ENTITY_COUNT],
        dt: Scalar,
    );
    fn clear_lagrange_multipliers(&mut self);

    // Provided methods
    fn compute_lagrange_update_with_gradients(
        &self,
        lagrange: Scalar,
        c: Scalar,
        gradients: &[Vector],
        inverse_masses: &[Scalar],
        compliance: Scalar,
        dt: Scalar,
    ) -> Scalar { ... }
    fn compute_lagrange_update(
        &self,
        lagrange: Scalar,
        c: Scalar,
        inverse_masses: &[Scalar],
        compliance: Scalar,
        dt: Scalar,
    ) -> Scalar { ... }
}

A trait for all XPBD constraints.

Required Methods

fn entities(&self) -> [Entity; ENTITY_COUNT]

The entities participating in the constraint.

fn solve( &mut self, bodies: [&mut RigidBodyQueryItem<'_>; ENTITY_COUNT], dt: Scalar, )

Solves the constraint.

There are two main steps to solving a constraint:

1. Compute the generalized inverse masses, gradients and the Lagrange multiplier update.
2. Apply corrections along the gradients using the Lagrange multiplier update.

XpbdConstraint provides the compute_lagrange_update method for all constraints. It requires the gradients and inverse masses of the participating entities.

For constraints between two bodies, you can implement PositionConstraint. and AngularConstraint to get the associated compute_generalized_inverse_mass, apply_positional_correction and apply_angular_correction methods. Otherwise you must implement the generalized inverse mass computations and correction applying logic yourself.

You can find a working example of a custom constraint here.

fn clear_lagrange_multipliers(&mut self)

Sets the constraint’s Lagrange multipliers to 0.

Provided Methods

fn compute_lagrange_update_with_gradients( &self, lagrange: Scalar, c: Scalar, gradients: &[Vector], inverse_masses: &[Scalar], compliance: Scalar, dt: Scalar, ) -> Scalar

Computes how much a constraint’s Lagrange multiplier changes when projecting the constraint for all participating particles.

c is a scalar value returned by the constraint function. When it is zero, the constraint is satisfied.

Each particle should have a corresponding gradient in gradients. A gradient is a vector that refers to the direction in which c increases the most.

See the constraint theory for more information.

fn compute_lagrange_update( &self, lagrange: Scalar, c: Scalar, inverse_masses: &[Scalar], compliance: Scalar, dt: Scalar, ) -> Scalar

Computes how much a constraint’s Lagrange multiplier changes when projecting the constraint for all participating particles. The constraint gradients are assumed to be unit-length.

c is a scalar value returned by the constraint function. When it is zero, the constraint is satisfied.

See the constraint theory for more information.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl XpbdConstraint<2> for DistanceJoint

impl XpbdConstraint<2> for FixedJoint

impl XpbdConstraint<2> for PrismaticJoint

impl XpbdConstraint<2> for RevoluteJoint