Porting guide for ODE's collision system

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:

• Hierarchical spaces
• The ability to collide spaces with single geoms.
• The ability to collide spaces together.
• Geom groups are now spaces.
• Geoms now have 'category' and 'collide' bits for early culling.
• The behavior of various functions is more well defined.
• Geoms can be disabled/enabled.
• Internally, the collision system is now optimized for larger environments.

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:
   • Geometry groups have a slight behavior change if you want self intersection. It used to be the case that if the user wanted the geoms inside a geometry group to self-intersect then the geoms would have to be inserted into a separate space and dSpaceCollide() called on that. This is no longer the case, as dSpaceCollide() can be called on the geometry group directly.
   • dGeomGetClass() used to return a unique type for geometry groups, but now it returns dSimpleSpaceID.
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.