Porting guide for ODE's collision system

ODE's collision system went through a major change around 7/Nov/2002. Now we have two separate collision systems. The user can activate either the old or new collision system when ODE is compiled, by setting the ODE_OLD_COLLISION variable in config/user-settings.

The API of the new collision system is 99% compatible with the old system. The old system will be removed at some point in the future. All applications should be migrated to use the new system.

NOTE, even if the old ODE collision code is used, spaces must still be created with the new API, using a parent argument of 0. This is the only incompatibility with the old code.

New collision features include:

The new API is described in the latest ODE user guide. The old API is described here. Some legacy applications may rely on subtle details of the old system.

Here are the changes that need to be made to old ODE code to get it to work with the new collision system.

  1. The dSimpleSpaceCreate() and dHashSpaceCreate() functions now take a space argument. This argument should be set to 0 to get the old behavior.
  2. Geometry groups are deprecated, as the equivalent functionality can be obtained with a simple-space. However the geometry group API is still supported:
  3. dGeomGetSpaceAABB() is no longer supported. Call dGeomGetAABB() instead.
  4. User defined classes that are created with dCreateGeomClass() have different internal handling. As a consequence, there is a fixed upper limit on the number of classes that can be created this way. This limit is set in include/ode/collision.h as the constant dMaxUserClasses. Note that it may be more convenient to add your geometry classes directly to ODE's source code. This has the advantage that you can use C++ so the implementation will potentially be a bit cleaner. This is also the preferred method if your collision class is generally useful and you want to contribute it to the public source base.