Real-Time Physics Simulation Forum

SteveBaker wrote:There are some annoying uglinesses in the Bullet API that really need fixing.

FIRSTLY:

The one that upsets me the most is that global variables and classes don't have a single prefix (eg OpenGL functions all start 'gl') - which means that Bullet pollutes the namespace HORRIBLY. In large applications, this can be a serious pain in the butt.

SECONDLY:
The second one is that there is no consistancy of member function naming. For example:
class CollisionShape has: 'IsConvex' and 'CalculateLocalInertia' - but 'setLocalScaling' - it's really hard to write code when there is no standard about whether functions start with uppercase or lowercase. Worse still is 'GetAabb' - where 'AABB' is an acronym and would usually be capitalised. We even have 'setLocalScaling' and 'SetMargin'!!

This also makes it very tiresome to write code that uses Bullet. The library needs some standards about function and class naming - and it needs to be MUCH more careful about namespace pollution.

THIRDLY:
In order to use Bullet, I have to include dozens and dozens of header files (sometimes these have to be included in a very specific order - which is *NASTY*) and I have to link to half a dozen separate libraries. I think we should have:

#include <Bullet/Bullet.h>
...and be able to link to libBullet.so and nothing else.

Jack wrote:Perhaps it would be great to wrap BULLET into COM (at least for Windows platform)...... :roll: Similar to DirectX :roll:

Erwin Coumans wrote:It would be great to add some wrappers, in the Extras folder, it's just a matter of time and priorities.

Python bindings, Java, C#/XNA (already started), and perhaps COM.

Erwin Coumans wrote: I agree with you, and I wanted to fix this for a while, but want to choose a good point in time. Because changing the API requires changings other peoples code-bases.

So to reply on FIRST: indeed, a prefix for the classes should be great. I want to avoid global variables if possible, it's pure lazyness in most cases (or for quick debugging). Preferable we use different prefixes for Collision Detection and Dynamics, the collision detection can be used independent of the dynamics. We could go for namespaces too, but lots of people have troubles using them properly, and I don't want to keep on doing support for that. In Havok we used lower-case prefix 'hk' for all classes, like hkConvexShape, so would could use blConvexShape.

On the naming, I prefer using capitals for the method and class names, to avoid confusion with variable names.

Ideally I want a C interface-API going along with the library. That hides most internals, and focusses on the usage. We can add a C-layer (bullet.h) on top of Bullet similar to ODE or Solid (see http://www.dtecta.com).

  class blBoxShape
  {
  #ifndef MODERN_BULLET_API
    inline void setLocalScaling ( const SimdVector3& scaling) { SetLocalScaling ( scaling ) ; }
  #endif
  } ;
  #ifndef MODERN_BULLET_API
    typedef blBoxShape BoxShape ;
  #endif

Those things can generally be generated automatically these days. Packages like SWIG can generate wrappers for almost any language from C++ headers.

Dragonlord wrote:It's really best to cleanup the API right now as the longer you wait the messier it gets to repair it. Furthermore you tend to push it away and away every time ( god how I know this myself ).

What goes for naming don't use namespaces. They are a pain in the ass and not good to work with. a prefix like "bl" is the best thing to do as most of the GPL stuff I know works like that and it's very good to work with it.

The last thing is this header file thing. I don't really care what you do but don't "hide" things from developers using multiple "sabot" include files. If it's an open source type project always make all headers open and provide one huge include file for the lazy bums out there. Anything else makes it trickier for the more advanced users to work with. Furthermore there is nothing wrong with cross references from a .cpp to another directory as long as the .h files always work with base interfaces.

- Pl?ss Roland

Erwin Coumans wrote:

Those things can generally be generated automatically these days. Packages like SWIG can generate wrappers for almost any language from C++ headers.

No, I don't want to expose all internal C++ classes. I know swig and other tools, but that's not the direction I want to go. Please look at Solid library for what I mean, or ODE. You can download Solid at http://www.dtecta.com . This C-API only exposes the necessary bits for the user, it is the 'high level api' that is enough for 95% of the users. I don't want to expose them to C++ classes or concepts like PersistentManifold, Dispatcher etc.

Still, I prefer developers to know what they include, in most cases the depencies are very minimal. If possible don't include a headerfile, but just use a forward declaration.

   #include <Bullet/Bullet.h>

  #include <Bullet/BulletMath.h>
  #include <Bullet/BulletCollision.h>
  #include <Bullet/BulletPhysics.h>

  -l bullet

  -l bulletmath  -l bulletcollision  -l bulletphysics

Also, such future grouping headerfile should NEVER be used in Bullet internally. It completely messes up the dependencies :)

You prefer it because you live and breathe the internals of this library. The vast majority of end users most definitely won't prefer it. They want it to be a neat little black box that quietly gets on and does the physics - with the minimum possible amount of interface.

//create/destroy methods
btCollisionShape btCreateCollisionShape(..)
btDestroyCollisionShape(btCollisionShape);
btCollisionObject CreateCollisionObject(btCollisionShape, btMotionState)
btDestroyCollisionObject(btCollisionObject);
btPhysicsWorld btCreatePhysicsWorld();
btDestroyPhysicsWorld(btPhysicsWorld world);
btRigidBody btCreateRigidBody();
btRigidBody btDestroyRigidBody(btRigidBody);

//queries and stepping the world
btStepSimulation(btPhysicsWorld world,btScalar timestep);
/ray cast
btTestRay(btCollisionWorld world,btVector3 from,btVector3 to);
//single object-object collision query
btGetDistance(btCollisionObject obj0,btCollisionObject obj1);
//some stuff for callbacks etc.
btGetTimeOfImpact(btCollisionObject obj0,btCollisionObject obj1);

Dirk wrote: IMO the API has also to many unnecessary indirections (layers). I totally understand that you implemtented it this way in order to try different things out or in order to compare BULLET e.g. against SOLID. Maybe you consider a 2.0 version of BULLET which uses a more slender API. While using a wrapper like SOLID makes it easier for clients to use BULLET it will become very difficult to maintain the core API for you. Honestly I only see three modules/layers for a physic system, namely a math, collision and physic library. You maybe want to consider this as well.

Erwin Coumans wrote: * Issue0: there is no easy distribution, with a a single API include file (and precompiled library). Right now, developers have to include zillions of headerfiles. I've seen this issue in other physics libraries too...
* Issue1: the naming of internal source code, use prefixes and consistent method capitulization

Both need and will be address. I had them in the planning, but didn't expect it was needed so urgently. There is a lot of other work needed in the library:

* constraint motors and limits
* memory management/referencing
* etc etc etc, see the Bullet todo list (sticky in this forum)