Manual: Support Functions

Initialization

void dInitODE ();
int dInitODE2 (unsigned InitFlags);
void dCloseODE ();

Perform library initialization.

• dInitODE2() must be called before the library's first use. InitFlags can be either zero or dInitFlagManualThreadCleanup. It must be called only once until dCloseODE() is called.

• dInitODE() is a short hand for:

    dInitODE2(0);
    dAllocateODEDataForThread(dAllocateMaskAll);

• dCloseODE() performs library cleanup. After that, dInitODE2() must be called before ODE can be used again. Use it only if you are going to use ODE from a single thread.

int dAllocateODEDataForThread (unsigned AllocateFlags);
void dCleanupODEAllDataForThread ();

• dAllocateODEDataForThread() must be called from every thread that will use ODE. AllocateFlags can be either zero or dAllocateFlagCollisionData.

• Use dCleanupODEAllDataForThread () only if the library was initialized with dInitFlagManualThreadCleanup.

Configuration

const char* dGetConfiguration ();

Returns the specific ODE build configuration as a string of tokens. The string can be parsed in a similar way to the OpenGL extension mechanism, the naming convention should be familiar too. The following extensions are reported:

• ODE
• ODE_single_precision
• ODE_double_precision
• ODE_EXT_no_debug
• ODE_EXT_trimesh
• ODE_EXT_opcode
• ODE_EXT_gimpact
• ODE_EXT_malloc_not_alloca
• ODE_OPC_16bit_indices
• ODE_OPC_new_collider

int dCheckConfiguration ( const char* token );

Helper to check for a token in the ODE configuration string. Caution, this function is case sensitive.

Rotation functions

Rigid body orientations are represented with unit quaternions. It consists of four numbers, $[w, x, y, z]$, where:

• $w = \cos( \theta / 2)$
• $(x, y, z) = \vec{u} \sin( \theta /2)$
• $\theta$ is a rotation angle
• $\vec{u}$ is a unit length rotation axis.

Every rigid body also has a 3x3 rotation matrix that is derived from the quaternion; quaternions are convenient for dynamics calculations, but matrices are better for linear transformations. The rotation matrix and the quaternion always match. Geoms have only rotation matrices, as they are not involved in dynamics. Quaternions are the preferred method of transmitting rotations between libraries (e.g. to/from 3D engines), as there are only 2 conventions ([w, x, y, z] and [x, y, z, w]) that are easy to notice when swapped; similarly, Euler angles are undesirable, as there are too many possible conventions, making two independent implementations unlikely to match.

Some information about quaternions:

• q and -q represent the same rotation.
• The inverse of a quaternion [w, x, y, z] is [w, -x, -y, -z].

The following are utility functions for dealing with rotation matrices and quaternions.

void dRSetIdentity (dMatrix3 R);

Set R to the identity matrix (i.e. no rotation).

void dRFromAxisAndAngle (dMatrix3 R, dReal ax, dReal ay, dReal az, dReal angle);

Compute the rotation matrix R as a rotation of angle radians along the axis (ax,ay,az).

void dRFromEulerAngles (dMatrix3 R, dReal phi, dReal theta, dReal psi);

Compute the rotation matrix R from the three Euler rotation angles.

void dRFrom2Axes (dMatrix3 R, dReal ax, dReal ay, dReal az, dReal bx, dReal by, dReal bz);

Compute the rotation matrix R from the two vectors a = [ax, ay, az] and b = [bx, by, bz]. a and b are the desired $x$ and $y$ axes of the rotated coordinate system. If necessary, both vectors will be normalized, and b will be projected so that it is perpendicular to a. The desired $z$ axis is the cross product $a \times b$.

void dQSetIdentity (dQuaternion q);

Set q to the identity rotation (i.e. no rotation).

void dQFromAxisAndAngle (dQuaternion q, dReal ax, dReal ay, dReal az, dReal angle);

Compute q as a rotation of angle radians along the axis (ax,ay,az).

void dQMultiply0 (dQuaternion qa, const dQuaternion qb, const dQuaternion qc);
void dQMultiply1 (dQuaternion qa, const dQuaternion qb, const dQuaternion qc);
void dQMultiply2 (dQuaternion qa, const dQuaternion qb, const dQuaternion qc);
void dQMultiply3 (dQuaternion qa, const dQuaternion qb, const dQuaternion qc);

Set qa = qb*qc. This is that same as qa = rotation qc followed by rotation qb. The 0/1/2/3 versions use inverse of arguments: 0 inverts nothing, 1 uses the inverse of qb, and 2 uses the inverse of qc. Option 3 uses the inverse of both.

void dQtoR (const dQuaternion q, dMatrix3 R);

Convert quaternion q to rotation matrix R.

void dRtoQ (const dMatrix3 R, dQuaternion q);

Convert rotation matrix R to quaternion q.

void dWtoDQ (const dVector3 w, const dQuaternion q, dVector4 dq);

Given an existing orientation q and an angular velocity vector w, return in dq the resulting $\operatorname{d}q/\operatorname{d}t$.

Mass functions

The mass parameters of a rigid body are described by a dMass structure:

typedef struct dMass {
    dReal mass; // total mass of the rigid body
    dVector3 c; // center of gravity position in body frame (x,y,z)
    dMatrix3 I; // 3x3 inertia tensor in body frame, about POR
} dMass;

The following functions operate on this structure:

void dMassSetZero (dMass *);

Set all the mass parameters to zero.

void dMassSetParameters (dMass *, dReal themass,
                         dReal cgx, dReal cgy, dReal cgz,
                         dReal I11, dReal I22, dReal I33,
                         dReal I12, dReal I13, dReal I23);

Set the mass parameters to the given values. themass is the mass of the body. (cx,cy,cz) is the center of gravity position in the body frame. The Ixx values are the elements of the inertia matrix: ( I11 I12 I13 ) ( I12 I22 I23 ) ( I13 I23 I33 )

void dMassSetSphere (dMass *, dReal density, dReal radius);
void dMassSetSphereTotal (dMass *, dReal total_mass, dReal radius);

Set the mass parameters to represent a sphere of the given radius and density, with the center of mass at (0,0,0) relative to the body. The first function accepts the density of the sphere, the second accepts the total mass of the sphere.

void dMassSetCapsule (dMass *, dReal density, int direction, dReal radius, dReal length);
void dMassSetCapsuleTotal (dMass *, dReal total_mass, int direction, dReal radius, dReal length);

Set the mass parameters to represent a capsule of the given parameters and density, with the center of mass at (0,0,0) relative to the body. The radius of the cylinder (and the spherical cap) is radius. The length of the cylinder (not counting the spherical cap) is length. The cylinder's long axis is oriented along the body's x, y or z axis according to the value of direction (1=x, 2=y, 3=z). The first function accepts the density of the object, the second accepts its total mass.

void dMassSetCylinder (dMass *, dReal density, int direction, dReal radius, dReal length);
void dMassSetCylinderTotal (dMass *, dReal total_mass, int direction, dReal radius, dReal length);

Set the mass parameters to represent a flat-ended cylinder of the given parameters and density, with the center of mass at (0,0,0) relative to the body. The radius of the cylinder is radius. The length of the cylinder is length. The cylinder's long axis is oriented along the body's x, y or z axis according to the value of direction (1=x, 2=y, 3=z). The first function accepts the density of the object, the second accepts its total mass.

void dMassSetBox (dMass *, dReal density, dReal lx, dReal ly, dReal lz);
void dMassSetBoxTotal (dMass *, dReal total_mass, dReal lx, dReal ly, dReal lz);

Set the mass parameters to represent a box of the given dimensions and density, with the center of mass at (0,0,0) relative to the body. The side lengths of the box along the x, y and z axes are lx, ly and lz. The first function accepts the density of the object, the second accepts its total mass.

void dMassSetTrimesh (dMass *, dReal density, dGeomID g)

Set the mass parameters to represent an arbitrary trimesh of the given geometry and density, location of a trimesh geometry center of mass and set the inertia matrix.

void dMassAdjust (dMass *, dReal newmass);

Given mass parameters for some object, adjust them so the total mass is now newmass. This is useful when using the above functions to set the mass parameters for certain objects - they take the object density, not the total mass.

void dMassTranslate (dMass *, dReal x, dReal y, dReal z);

Given mass parameters for some object, adjust them to represent the object displaced by (x,y,z) relative to the body frame.

void dMassRotate (dMass *, const dMatrix3 R);

Given mass parameters for some object, adjust them to represent the object rotated by R relative to the body frame.

void dMassAdd (dMass *a, const dMass *b);

Add the mass b to the mass a.

Math functions

(There are quite a lot of these, but they're not standardized enough to document yet).

Export functions

Functions used to print the state of a world.

void dWorldExportDIF (dWorldID w, FILE *file, const char *prefix)

Set file to a file descriptor to print to a file or to stdout to print to the standard output (console).

Error and memory functions

The following is taken directly from ode/error.h, version .11:

All user defined error functions have this type. error and debug functions should not return:

typedef void dMessageFunction (int errnum, const char *msg, va_list ap);

Set a new error, debug or warning handler. if fn is 0, the default handlers are used:

void dSetErrorHandler (dMessageFunction *fn);
void dSetDebugHandler (dMessageFunction *fn);
void dSetMessageHandler (dMessageFunction *fn);

Return the current error, debug or warning handler. if the return value is 0, the default handlers are in place:

dMessageFunction *dGetErrorHandler(void);
dMessageFunction *dGetDebugHandler(void);
dMessageFunction *dGetMessageHandler(void);

Generate a fatal error, debug trap or a message:

ODE_API void dError (int num, const char *msg, ...);
ODE_API void dDebug (int num, const char *msg, ...);
ODE_API void dMessage (int num, const char *msg, ...);