osgBullet Documentation

osgBullet 2.00.02

Introduction

osgBullet is a set of software tools for applications that use both OpenSceneGraph (OSG) and Bullet. The osgBullet library is the result of collaborative work between Paul Martz (Skew Matrix Software), Ames Lab, and ARDEC. It's used as part of the VE-Suite project, as well as other applications and software projects. osgBullet is open source and available under the GNU LGPL v2.1 software license.

osgBullet source and issue tracking are on Google Code.

An osgBullet discussion group is available on Google Groups.

Philosophy

osgBullet is a set of tools to facilitate developing software that uses Bullet for physics simultation and collision detection, and uses OSG for rendering. osgBullet doesn't attempt to wrap either OSG or Bullet. Instead, it allows you (the programmer) direct access to both APIs. osgBullet gets out of your way so that your application can use the full feature set of both OSG and Bullet.

osgBullet plays a key role in this scenario by providing useful tools for applications that use both APIs.

Features

osgBullet's most useful feature is its ability to accomodate Bullet's strict coordinate system and transformation requirements and still support the arbitrary coordinate systems and transformations often encountered in OSG (and other 3D) applications. Bullet collision shapes must be created so that the center of mass corresponds to the coordinate origin, but this is not how most 3D models are built. Bullet doesn't support scaling, but 3D models are often scaled up or down to match a world coordinate system. OSG transformations are hierarchical, but Bullet wants to completely own the local-to-world transformation. All of these issues are handled by the collision shape creation utilities in combination with the MotionState class. osgBullet also provides rigid body creation utilities that wrap collision shape and MotionState creation.

Other features include the following.

• Support for running physics and rendering in separate threads.
• Supports using Bullet for both rigid body dynamics as well as collision detection only.
• A set of osgGA-based GUIEventHandlers for interacting with the physics simulation, including the osgbInteraction::HandNode class to support data glove usage.
• Routines for creating Bullet collision shapes from OSG geometry.
• An OSG-based implementation of btIDebugDraw.
• OSG reference counting for Bullet objects.
• Functions to convert between OSG and Bullet matrices and vectors.

Applications and Examples

• The osgbpp application allows you to preview a physics simultation on a model.
• The centerofmass example demonstrates application-specified center of mass.
• The collision example demonstrates using osgBullet and Bullet for collision detection only.
• The dice example, just for fun.
• The hand physics example demonstrates using the HandNode to interact with the scene.
• The hinge example demonstrates creating a hinge constraint.
• The multithreaded example demonstrates running Bullet in a separate thread.
• The saverestore example demonstrates saving/restoring a physics simultation to/from disk.
• The slider example demonstrates creating a slider constraint.

Libraries

osgbCollision

Collision detection and collision shape support. Facilities for creating Bullet collision shapes from OSG scene graphs, and vice versa.

osgbDynamics

Rigid body dynamics and constraints support.

osgbInteraction

Support for user interaction with the physics simultation, such as dragging objects, resetting the simulation to a save point, and launching models into the scene. An articulatable hand model supports an immersive simultation experience, and includes aupport for the P5 data glove.

osgdb_osgbDynamics

Dot OSG file support for classes and objects in the osgbDynamics library.

Note: This library currently needs to be redesigned. It provides support for, and depends on, all three libraries: osgbCollision, osgbDynamics, and osgbInteraction. This makes it impossible for an app to both use the dot OSG file support, and link with only osgbDynamics (it must also link with osgbInteraction).

osgdb_sgb

Support for .SGB, an osgBullet file format for storing physics state.