ode4j

A Java 3D Physics Engine & Library

Documentation

Performance & Multi-Threading

• When profiling any of the included demos, you will see that most of the time is spent in OpenGL calls (at least on my SUSE 11.1 64bit system / ATI Radeon HD 3850).
• As far as I can tell, this is not a problem with lwjgl, but could be fixed by optimizing 'drawstuff'.
• To profile ode4j, please use applications that do not use drawstuff. To profile the existing demos, drawstuff can be disabled by calling DS_API.dsSetOutputNull() at the beginning of any demo.
• ode4j is in certain cases faster that ODE. I have investigated this only briefly, but I have the impression that Java can draw its advantage from using the garbage collector for arrays. This means de-allocation in Java occurs in a 2nd thread in parallel to computations, while in C/C++ de-allocation (which is expensive) occurs in the main thread.

• Any particular world should not be used be more then one thread at a time, reading or writing
• Multiple worlds can be used in concurrently by multiple threads as long as every world is only access by a single thread at a given time
• A world can be passed around (and then used) between threads simply by passing on the reference (this is unlike ODE in C/C++)
• The method OdeHelper.allocateODEDataForThread(int) does not need to be called as it does nothing (and never did). Actually it will be removed in one of the next releases.
• OdeHelper.init2(...) needs to be called only once per application, not for every thread (in fact, calling it multiple times should fail).
• OdeHelper.init2(...) needs to have returned before any thread uses ode4j.
  
• A future release may introduce more powerful multi-threading.
  

Differences to ODE for C/C++

• API: The preferred API of the ODE projects appears to be the C API (it is more complete and contains all the documentation). The preferred API in ode4j is the OO-API.
• Class names all start with a 'D' rather than 'd'.
• The d***ID types have not been ported. Simply use the according D*** interfaces. Also, the type hierarchy has changed, the D*** classes are now interfaces that are implemented by the according Dx*** classes.
  
• Main access points in ode4j are OdeHelper (initialisation methods and a factory for creating most classes), OdeConfig (for configuration) and OdeConstants (providing many of the contants used in ode4j).
• Some of the math has been moved inside the DVector3 and DMatrix3 classes.
• ode4j provides DVector3C and DMatrix3C interfaces that provide immutable encapsulation.
  

• All global methods have the leading 'd' removed and the 2nd letter lowercased. Most of the global methods can be found in OdeHelper. For example: dInitOde2(...) -> OdeHelper.initOde2(...).
• All 'create' methods have the 'create' moved to the beginning: OdeHelper.createMass().
• To find the Java method name for a global C method, one can usually remove the dClassName from the beginning and remove the first argument, for example dJointAttach( myJoint, b1, b2 ) becomes myJoint.attach( b1, b2 ). This is also valid when looking for C++ function names in ODE itself.
  Another example: dJointSetPistonAnchor ( piston, ... ); becomes piston.setAnchor ( ... ); .
  
• Unlike ODE, the preferred policy for getting complex values from an object is not to pass in an empty array:
  DVector3 result = new DVector3();
box.getSides( result );
  but to return an immutable object:
  DVector3C result = box.getLengths(); //The trailing 'C' on DVector3C and other classes indicates and constant / immutable object.
  In many cases this avoids creating unnecessary temporary objects and also makes the code more compact. It also avoids a possible spelling mistake, when typing 'g' instead of 's' (get <-> set).
  

Migration Guide