Manual: Data Types and Conventions

From ODE Wiki
Jump to: navigation, search
This article is part
of the ODE Manual
Chapters ...

Install and Use
Data Types and Conventions
Rigid Body Functions
Joint Types and Functions
Support Functions
Collision Detection

The basic data types

The ODE library can be built to use either single or double precision floating point numbers. Single precision is faster and uses less memory, but the simulation will have more numerical error that can result in visible problems. You will get less accuracy and stability with single precision.

(must describe what factors influence accuracy and stability).

The floating point data type is dReal. Other commonly used types are dVector3, dMatrix3, dQuaternion.

The non-scalar floating point types are all implemented as simple arrays of dReals. Their layout conventions are as follows:

Name Implementation Format
dQuaternion dReal[4] [ w, x, y, z ], where w is the real part and (x, y, z) form the vector part.
dVector4 dReal[4] [ x, y, z, 1.0 ]
dVector3 dReal[4] Same as dVector4; the 4th element is there only for better alignment, and should be ignored.
dMatrix4 dReal[4*4] A 4x4 matrix, laid out in row-major order, usually used as a homogeneous transform matrix. This means that the upper-left 3x3 elements are a rotation matrix, the first three elements of the last column are a translation vector, and the last row is simply [ 0, 0, 0, 1 ].
dMatrix3 dReal[3*4] A 3x3 matrix with the elements laid out in row-major order. The last column is ignored and, as dVector3, is used only for better alignment.

Objects and IDs

There are various kinds of object that can be created:

  • World - a dynamics world, that contains all the simulation data.
  • Body - a rigid body; it does not have any shape: it needs one or more dGeoms for that.
  • Joint - a joint.
  • Joint Group - a group of joints, makes it easy to destroy all joints at once.
  • Space - a collision space, used to organize and speed up collision tests.
  • Geom - a shape used to detect collisions.

Functions that deal with these objects take and return object IDs. The object ID types are dWorldID, dBodyID, etc.

Argument conventions

All 3-vectors (x,y,z) supplied to "set" functions are given as individual x,y,z arguments.

All 3-vector result arguments to "get" function are pointers to arrays of dReal.

Larger vectors are always supplied and returned as pointers to arrays of dReal.

All coordinates are in the global frame except where otherwise specified.

C versus C++

The ODE library is written in C++, but its public interface is made of simple C functions, not classes. Why is this?

  • Using a C interface only is simpler - the features of C++ do not help much for ODE.
  • It prevents C++ mangling and runtime-support problems across multiple compilers.
  • The user doesn't have to be familiar with C++ quirks to use ODE.

There's a semi-official C++ wrapper distributed with the library, in the odecpp*.h headers, but it has some design limitations.


The ODE library can be compiled in "debugging" or "release" mode. Debugging mode is slower, but function arguments are checked and many run-time tests are done to ensure internal consistency. Release mode is faster, but no checking is done.