---

MdtBcl.h

Go to the documentation of this file.

#ifndef _MDTBCL_H
#define _MDTBCL_H
/*
  Copyright 2000 MathEngine

  $Name: t-release-0-0-5-msvcrt $

  $Id: MdtBcl.h,v 1.21 2000/08/02 20:13:29 lucyb Exp $
*/

/** @file
 * Mdt constraints header File.
 *
 * All angles are specified in radians.
 */

#include "MePrecision.h"

#include "MdtKea.h"
#include "MdtBclLimit.h"
#include "MdtBclContactParams.h"

/*
  Mdt Basic Constraint Library Data Structure Tags
*/

/*
  The first Constraint type MUST be defined as 0, and the others must follow
  in strict ascending sequence, with no gaps, otherwise there will be an
  access violation in MdtWorldStep
*/

/** The enumeration of joint types supported by the MdtBcl module. */

typedef enum
{
    MdtBclBSJOINT = 0,
    MdtBclHINGE,
    MdtBclPRISMATIC,
    MdtBclCARWHEEL,
    MdtBclCONTACT,
    MdtBclFIXEDPATH,
    MdtBclFPFOJOINT,
    MdtBclUNIVERSAL,
    MdtBclLINEAR1,
    MdtBclLINEAR2
}
MdtBclJointType;

/** Flag used to indicate the absence of an attached body */
#define MdtBclNO_BODY           -1

/**
 * Kea parameters structure.
 */
typedef struct
{
    /**
     * Amount of time to evolve system by.
     */
    MeReal stepsize;

    /**
     * Numerical tolerance used by matrix solver.
     *
     * Default = 0.01.
     */
    MeReal epsilon;

    /**
     * Constraint relaxation rate.
     *
     * Default = 0.2.
     */
    MeReal gamma;
}
MdtBclSolverParameters;

/**
 * MdtBcl constraint header struct.
 *
 * Contains data common to all MdtBcl constraints.
 */
typedef struct
{
    /**
     * Data stucture tag.
     */
    int tag;

    /**
     * Length of WHOLE constraint data structure.
     */
    int len;
    /** padding - not used. */
    int pad[2];

    /**
     * Body indices in the immBody array of constrained bodies.
     *
     * Unused bodies or constraints to the world should be set to
     * MdtBclNO_BODY.
     */
    int body[4];
}
MdtBclConstraintHeader;

/**
 * MdtBcl ball and socket constraint structure..
 */
typedef struct
{
    /** Data stucture tag should be MdtBclBSJOINT. */
    MdtBclConstraintHeader head;

    /** Joint position in the first body reference frame.  */
    MeVector3 pos1;
    /** Joint position in the second body reference frame. */
    MeVector3 pos2;

    /** Primary rotation axis 1 (fixed in 1st body ref. frame). */
    MeVector3 axis_n1;
    /** Primary rotation axis 2 (fixed in 2nd body ref. frame). */
    MeVector3 axis_m1;

    /**
     * Secondary rotation axis, orthogonal to axis_n1
     * (fixed in 1st body ref. frame).
     */
    MeVector3 axis_n2;
    /**
     * Secondary rotation axis, orthogonal to axis_m1
     * (fixed in 2nd body ref. frame).
     */
    MeVector3 axis_m2;

    /**
     * This vector is maintained (read-only) in order to
     * ensure smooth rotation when n1 and m1 are nearly parallel
     * or anti-parallel (i.e. theta ~ 0 or theta ~ pi).
     */
    MeVector3 n1_cross_m1;
    /**
     * Optional limits set to motion about the rotation axes.
     *
     * These are (in array order):
     *
     * 0 - rho (twist angle)
     * 1 - theta (cone, or polar, angle)
     * 2 - phi (segment, or longitudinal, angle).
     */
    MdtBclLimit limit[3];
}
MdtBclBSJoint;

/**
 * MdtBcl Contact constraint struct.
 *
 * @see MdtBclContactParams
 */
typedef struct
{
    /** Data stucture tag should be MdtBclCONTACT. */
    MdtBclConstraintHeader head;

    /*
      Contact Geometry (different every time)
    */

    /** Position of contact (world reference frame). */
    MeVector3 cpos;
    /** Unit normal at contact (world reference frame). */
    MeVector3 normal;

    /** Penetration depth of bodies at contact. */
    MeReal penetration;

    /** Padding - not used. */
    int pad[3];

    /**
     * Principal friction direction.
     *
     * World reference frame, unit length and perpendicular to normal.
     */
    MeVector3 direction;

    /** Friction and restitution prarmeters. */
    MdtBclContactParams params;
}
MdtBclContact;

/**
 * MdtBcl Hinge constraint structure.
 *
 * A hinge constraint limits a body to rotate about one axis relative to
 * its parent.
 */
typedef struct
{
    /** Data stucture tag should be MdtBclHINGE. */
    MdtBclConstraintHeader head;

    /** Position of joint (first body reference frame). */
    MeVector3 pos1;
    /** Position of joint (second body reference frame). */
    MeVector3 pos2;
    /** Hinge axis (first body reference frame). */
    MeVector3 axis1;
    /** Hinge axis (second body reference frame). */
    MeVector3 axis2;

    /** Optional limits set to motion about the hinge axis. */
    MdtBclLimit limit;

    /**
     * Reference axis perpendicular to raxis_b and hinge axis
     * in first body reference frame.
     */
    MeVector3 raxis_a;
    /**
     * Reference axis perpendicular to raxis_a and hinge axis
     * in first body reference frame.
     */
    MeVector3 raxis_b;
    /**
     * Reference axis perpendicular to raxis_b and hinge axis
     * in second body reference frame.
     */
    MeVector3 raxis_a2;
}
MdtBclHinge;

/**
 * MdtBcl Prismatic constraint structure.
 *
 * A prismatic constraint fixes the orientation of two bodies, and limits
 * their position along a line.
 */
typedef struct
{
    /** Data stucture tag should be MdtBclPRISMATIC. */
    MdtBclConstraintHeader head;

    /** Sliding axis (first body reference frame). */
    MeVector3 axis1;
    /** Initial position of first body (inertial reference frame). */
    MeVector3 pos1;

    /** Optional limits set to motion along the sliding axis. */
    MdtBclLimit limit;
}
MdtBclPrismatic;

/**
 * MdtBcl Car Wheel constraint structure.
 *
 * A hinge that can be steered along a steering axis, is powered along
 * the hinge and steering axes, and has suspension along the steering
 * axis. Body 1 is the chassis and body 2 is the wheel. The connection
 * point for the wheel body is its center of mass.
 */
typedef struct
{
    /** Data stucture tag should be MdtBclCARWHEEL. */
    MdtBclConstraintHeader head;

    /*
      Car wheel constraint.
    */

    /** Connection point relative to chassis. */
    MeVector3 pos1;
    /** Steering axis in the chassis frame. */
    MeVector3 saxis1;
    /** Hinge axis in the chassis frame. */
    MeVector3 haxis1;
    /** Hinge axis in the wheel frame. */
    MeVector3 haxis2;

    /*
      Other parameters.
    */

    /** Proportional (spring) constant for suspension.
      * Typical values are usually in the range 1-10.
      */
    MeReal skp;
    /** Derivative (damping) constant for suspension.
      * Typical values are usually in the range 1-10.
      */
    MeReal skd;
    /** Steering desired angular velocity, in radians per second. */
    MeReal svel;
    /** Maximum steering motor torque (in Nm). */
    MeReal sfmax;
    /** Hinge desired angular velocity, in radians per second. */
    MeReal hvel;
    /** Maximum hinge motor torque (in Nm). */
    MeReal hfmax;
    /** 1 if steering axis locked at angle = 0. */
    int slock;

    /** Suspension hi limit (in meters), relative to the attachment point. */
    MeReal shi;
    /** Suspension low limit (in meters), relative to the attachment point. */
    MeReal slo;
    /** Suspension reference point (in meters), relative to the attachment
      * point. This is the `resting' position of the suspension. */
    MeReal sref;
    /** Suspension limit softness. */
    MeReal slsoft;

    /** PADDING - unused. */
    int pad[2];
}
MdtBclCarWheel;


/**
 * Fixed Path constraint data structure.
 *
 * A fixed path constraint is used to kinematically control the movement
 * of a dynamic body.  This means a dynamic body may be forced to
 * animate (translation only for this constraint type) and the resulting
 * forces are passed on to other constrained bodies.
 */
typedef struct
{
    /** Data stucture tag should be MdtBclFIXEDPATH. */
    MdtBclConstraintHeader head;

    /*
      Ball And Socket data:
    */

    /** Position of joint (1st body reference frame). */
    MeVector3 pos1;
    /** Position of joint (2nd body reference frame). */
    MeVector3 pos2;

    /*
      Kinematic data for fixed path:
    */

    /** Kinematic velocity of 1st body (1st body reference frame). */
    MeVector3 vel1;
    /** Kinematic velocity of 2nd body (2nd body reference frame). */
    MeVector3 vel2;
}
MdtBclFixedPath;

/**
 * Fixed Path, Fixed Orientation constraint data structure.
 *
 * A fixed path constraint is used to kinematically control the movement
 * of a dynamic body.  This means a dynamic body may be forced to
 * animate (translation or rotation) and the resulting forces are passed
 * on to other constrained bodies.
 */
typedef struct
{
    /** Data stucture tag should be MdtBclFPFOJOINT. */
    MdtBclConstraintHeader head;

    /*
      Ball And Socket data:
    */

    /** Position of joint (1st body reference frame). */
    MeVector3 pos1;
    /** Position of joint (2nd body reference frame). */
    MeVector3 pos2;
    /** Invariant relative orientation of the bodies. */
    MeVector3 rel_ori;
}
MdtBclFPFOJoint;

/**
 * Universal Joint constraint data structure.
 */
typedef struct
{
    /** Data stucture tag should be MdtBclUNIVERSAL. */
    MdtBclConstraintHeader head;

    /*
      Ball And Socket data:
    */

    /** Position of joint (1st body reference frame). */
    MeVector3 pos1;
    /** Position of joint (2nd body reference frame). */
    MeVector3 pos2;

    /*
      Body-frame fixed axes:
    */

    /** Joint axis 1 (fixed in 1st body ref. frame). */
    MeVector3 axis1;
    /** Joint axis 2 (fixed in 2nd body ref. frame). */
    MeVector3 axis2;
    /**
     * Dot product of the initial orientations of the two axes in the
     * inertial reference frame: invariant for this joint.
     */
    MeReal axis1_dot_axis2;

    /** padding - not used. */
    int pad[3];
}
MdtBclUniversal;

/**
 * Linear1 constraint data structure.
 *
 * Constrains one body to lie in plane relative to the other, and does
 * not constraint orientation.
 */
typedef struct
{
    /** Data stucture tag should be MdtBclLINEAR1. */
    MdtBclConstraintHeader head;

    /*
      Ball And Socket data:
    */

    /** Position of joint (1st body reference frame). */
    MeVector3 pos1;
    /** Position of joint (2nd body reference frame). */
    MeVector3 pos2;

    /**
     * Dot product of the separation vector of the two bodies and the
     * normal vector (fixed in the body[1] reference frame): invariant
     * for this joint.
     */
    MeReal displacement;

    /** padding - not used. */
    int pad[3];
}
MdtBclLinear1;

/**
 * Linear2 constraint data structure.
 *
 * Constrains one body to lie along a line relative to the other, and
 * does not constrain orientation.
 */
typedef struct
{
    /** Data stucture tag - should be MdtBclLINEAR2. */
    MdtBclConstraintHeader head;

    /*
      Linear2 data:
    */

    /** Position of joint (1st body reference frame). */
    MeVector3 pos1;
    /** Position of joint (2nd body reference frame). */
    MeVector3 pos2;

    /**
     * Vector fixed in the body[1] reference frame (or the inertial
     * frame, if no second body) on which the joint position is
     * constrained to lie.
     */
    MeVector3 direction;
    /**
     * A vector fixed in 2nd body reference frame which is perpendicular
     * to the joint direction.
     */
    MeVector3 vec1;
    /**
     * A vector fixed in 2nd body reference frame which is perpendicular
     * to both the joint direction and vec1.
     */
    MeVector3 vec2;
}
MdtBclLinear2;

#ifdef __cplusplus
extern "C"
{
#endif

/*
  Basic Constraint Library Add... Functions

  Functions for adding a constraint to the MdtKeaConstraints
  structure. Converts constraints from the geometric data
  structures above, into matrix rows to be passed to the solver.
*/

void    MdtBclAddBSJoint(MdtKeaConstraints *const clist,
            void *const constraint,
            const MdtKeaTransformation *const tlist,
            MdtKeaBody *const blist,
            const MdtBclSolverParameters *const params);

void    MdtBclAddHinge(MdtKeaConstraints *const clist,
            void *const constraint,
            const MdtKeaTransformation *const tlist,
            MdtKeaBody *const blist,
            const MdtBclSolverParameters *const params);

void    MdtBclAddPrismatic(MdtKeaConstraints *const clist,
            void *const constraint,
            const MdtKeaTransformation *const tlist,
            MdtKeaBody *const blist,
            const MdtBclSolverParameters *const params);

void    MdtBclAddCarWheel(MdtKeaConstraints *const clist,
            void *const constraint,
            const MdtKeaTransformation *const tlist,
            MdtKeaBody *const blist,
            const MdtBclSolverParameters *const params);

void    MdtBclAddContact(MdtKeaConstraints *const clist,
            void *const constraint,
            const MdtKeaTransformation *const tlist,
            MdtKeaBody *const blist,
            const MdtBclSolverParameters *const params);

void    MdtBclAddFixedPath(MdtKeaConstraints *const clist,
            void *const constraint,
            const MdtKeaTransformation *const tlist,
            MdtKeaBody *const blist,
            const MdtBclSolverParameters *const params);

void    MdtBclAddFPFOJoint(MdtKeaConstraints *const clist,
            void *const constraint,
            const MdtKeaTransformation *const tlist,
            MdtKeaBody *const blist,
            const MdtBclSolverParameters *const params);

void    MdtBclAddUniversal(MdtKeaConstraints *const clist,
            void *const constraint,
            const MdtKeaTransformation *const tlist,
            MdtKeaBody *const blist,
            const MdtBclSolverParameters *const params);

void    MdtBclAddLinear1(MdtKeaConstraints *const clist,
            void *const constraint,
            const MdtKeaTransformation *const tlist,
            MdtKeaBody *const blist,
            const MdtBclSolverParameters *const params);

void    MdtBclAddLinear2(MdtKeaConstraints *const clist,
            void *const constraint,
            const MdtKeaTransformation *const tlist,
            MdtKeaBody *const blist,
            const MdtBclSolverParameters *const params);

void    MdtBclInitConstraintRowList(MdtKeaConstraints *const clist);
void    MdtBclEndPartition(MdtKeaConstraints  *const clist);
void    MdtBclStartPartition(MdtKeaConstraints *const clist);
void    MdtBclEndConstraint(MdtKeaConstraints  *const clist,
            const unsigned rows_added);

/*
  The following are useful macros for finding the maximum number of
  constraint rows that can be added by a type of constraints.

  This can be used to provide an upper bound on the amount of memory to
  allocate fo constraint input. Some rows may be actuation or limits.
*/

/**
 * Maximum rows added by a Ball And Socket Joint constraint.
 */
#define MdtBclGETMAXROWSBSJOINT         (6)
/**
 * Maximum rows added by a Hinge constraint.
 */
#define MdtBclGETMAXROWSHINGE           (6)
/**
 * Maximum rows added by a Prismatic constraint.
 */
#define MdtBclGETMAXROWSPRISMATIC       (6)
/**
 * Maximum rows added by a Car Wheel constraint.
 */
#define MdtBclGETMAXROWSCARWHEEL        (6)
/**
 * Maximum rows added by a Contact constraint.
 */
#define MdtBclGETMAXROWSCONTACT         (3)
/**
 * Maximum rows added by a Fixed Path constraint.
 */
#define MdtBclGETMAXROWSFIXEDPATH       (3)
/**
 * Maximum rows added by a Fixed Path Fixed Orientation constraint.
 */
#define MdtBclGETMAXROWSFPFOJOINT       (6)
/**
 * Maximum rows added by a Universal Joint constraint.
 */
#define MdtBclGETMAXROWSUNIVERSAL       (4)
/**
 * Maximum rows added by a Linear1 constraint.
 */
#define MdtBclGETMAXROWSLINEAR1         (1)
/**
 * Maximum rows added by a Linear2 constraint.
 */
#define MdtBclGETMAXROWSLINEAR2         (2)

#ifdef __cplusplus
}
#endif

#endif

---