Bullet 2.74 Physics SDK Manual
This draft documentation is work-in-progress
Check out the Wiki and forums at http://bulletphysics.com
© 2009 Erwin Coumans
All Rights Reserved.
http://bulletphysics.com
©Erwin Coumans Bullet 2.74 Physics SDK Manual
- 2 -
Table of Contents
1 Introduction .................................................................................................................................................................................... 4
Decription of the library .......................................................................................................................................................... 4
New in Bullet 2.74 .................................................................................................................................................................. 4
Upcoming plans ..................................................................................................................................................................... 4
Main Features ........................................................................................................................................................................ 4
Contact and Support .............................................................................................................................................................. 4
2 Quickstart ....................................................................................................................................................................................... 5
Step 1: Download ................................................................................................................................................................... 5
Step 2: Building ...................................................................................................................................................................... 5
Step 3: Testing demos............................................................................................................................................................ 5
Step 4: Integrating Bullet physics in your application .............................................................................................................. 5
Step 5 : Integrate only the Collision Detection Library............................................................................................................. 6
Step 6 : Use snippets only, like the GJK Closest Point calculation. ......................................................................................... 6
3 Library Overview............................................................................................................................................................................ 7
Introduction ............................................................................................................................................................................ 7
Software Design..................................................................................................................................................................... 7
Rigid Body Physics Pipeline ................................................................................................................................................... 8
Integration overview ............................................................................................................................................................... 8
Basic Data Types and Math Library ...................................................................................................................................... 10
Memory Management, Alignment, Containers ...................................................................................................................... 10
Timing and Performance Profiling..........................................................................................................................................11
Debug Drawing .................................................................................................................................................................... 12
4 Bullet Collision Detection............................................................................................................................................................ 13
Collision Detection ............................................................................................................................................................... 13
Collision Shapes .................................................................................................................................................................. 14
Convex Primitives ................................................................................................................................................................ 14
Compound Shapes .............................................................................................................................................................. 15
Convex Hull Shapes............................................................................................................................................................. 15
Concave Triangle Meshes .................................................................................................................................................... 15
Convex Decomposition ........................................................................................................................................................ 15
Height field........................................................................................................................................................................... 15
btStaticPlaneShape.............................................................................................................................................................. 16
Scaling of Collision Shapes .................................................................................................................................................. 16
Collision Margin.................................................................................................................................................................... 16
Collision Matrix..................................................................................................................................................................... 17
Registering custom collision shapes and algorithms............................................................................................................. 17
5 Collision Filtering (selective collisions) ..................................................................................................................................... 18
Filtering collisions using masks ............................................................................................................................................ 18
Filtering Collisions Using a Broadphase Filter Callback ........................................................................................................ 19
Filtering Collisions Using a Custom NearCallback ................................................................................................................ 19
Deriving your own class from btCollisionDispatcher.............................................................................................................. 20
6 Rigid Body Dynamics .................................................................................................................................................................. 21
Introduction .......................................................................................................................................................................... 21
Static, Dynamic and Kinematic Rigid Bodies ........................................................................................................................ 21
Center of mass World Transform.......................................................................................................................................... 22
What's a MotionState?.......................................................................................................................................................... 22
Interpolation ......................................................................................................................................................................... 22
So how do I use one?........................................................................................................................................................... 23
DefaultMotionState....................................................................................................................................................... 23
Ogre3d Motion State example.................................................................................................................................... 23
Kinematic Bodies ................................................................................................................................................................. 24
Simulation frames and interpolation frames.......................................................................................................................... 25
7 Constraints ................................................................................................................................................................................... 26
Point to Point Constraint....................................................................................................................................................... 26
Hinge Constraint .................................................................................................................................................................. 26
Slider Constraint................................................................................................................................................................... 27
Cone Twist Constraint .......................................................................................................................................................... 27
Generic 6 Dof Constraint...................................................................................................................................................... 27
8 Actions: Vehicles & Character Controller................................................................................................................................... 29
Action Interface .................................................................................................................................................................... 29
Raycast Vehicle.................................................................................................................................................................... 29
Character Controller............................................................................................................................................................. 29
9 Soft Body Dynamics .................................................................................................................................................................... 30
Introduction .......................................................................................................................................................................... 30
Construction from a triangle mesh........................................................................................................................................ 30
Collision clusters .................................................................................................................................................................. 30
http://bulletphysics.com
©Erwin Coumans Bullet 2.74 Physics SDK Manual
- 3 -
Applying forces to a Soft body.............................................................................................................................................. 31
Soft body constraints............................................................................................................................................................ 31
10 Bullet Demo Description ............................................................................................................................................................ 32
AllBulletDemos..................................................................................................................................................................... 32
CCD Physics Demo.............................................................................................................................................................. 32
COLLADA Physics Viewer Demo ......................................................................................................................................... 32
BSP Demo ........................................................................................................................................................................... 32
Vehicle Demo....................................................................................................................................................................... 33
Fork Lift Demo...................................................................................................................................................................... 33
11 Advanced Low Level Technical Demos..................................................................................................................................... 34
Collision Interfacing Demo.................................................................................................................................................... 34
Collision Demo..................................................................................................................................................................... 34
User Collision Algorithm ....................................................................................................................................................... 34
Gjk Convex Cast / Sweep Demo .......................................................................................................................................... 34
Continuous Convex Collision................................................................................................................................................ 34
Raytracer Demo................................................................................................................................................................... 34
Simplex Demo...................................................................................................................................................................... 35
12 General Tips................................................................................................................................................................................ 36
Avoid very small and very large collision shapes .................................................................................................................. 36
Avoid large mass ratios (differences).................................................................................................................................... 36
Combine multiple static triangle meshes into one ................................................................................................................. 36
Use the default internal fixed timestep.................................................................................................................................. 36
For ragdolls use btConeTwistConstraint ............................................................................................................................... 36
Don’t set the collision margin to zero .................................................................................................................................... 36
Use less then 100 vertices in a convex mesh ....................................................................................................................... 37
Avoid huge or degenerate triangles in a triangle mesh ......................................................................................................... 37
Per triangle friction and restitution value............................................................................................................................... 38
Custom Constraint Solver..................................................................................................................................................... 38
Custom Friction Model ......................................................................................................................................................... 38
13 Parallelism: SPU, CUDA, OpenCL ............................................................................................................................................. 39
Cell SPU / SPURS optimized version................................................................................................................................... 39
Unified multi threading.......................................................................................................................................................... 39
Win32 Threads, pthreads, sequential thread support............................................................................................................ 39
IBM Cell SDK 3.1, libspe2 SPU optimized version................................................................................................................ 39
btCudaBroadphase .............................................................................................................................................................. 40
14 Further documentation and references..................................................................................................................................... 41
Online resources.................................................................................................................................................................. 41
Authoring Tools .................................................................................................................................................................... 41
Books................................................................................................................................................................................... 41
Contributions and people...................................................................................................................................................... 42
http://bulletphysics.com
©Erwin Coumans Bullet 2.74 Physics SDK Manual
- 4 -
1 Introduction
Decription of the library
Bullet Physics is a professional open source collision detection, rigid body and soft body dynamics
library. The library is free for commercial use under the ZLib license from http://bulletphysics.com
New in Bullet 2.74
SIMD constraint optimizations and debug visualization of joint frame and limits. Also
many bugfixes, improved COLLADA converter, Actions and single-shot contact generation
Upcoming plans
OpenCL, CUDA and Larrabee optimizations, and fracture of rigid bodies. See also
http://code.google.com/p/bullet/issues/list
Main Features
Open source C++ code under Zlib license and free for any commercial use on all platforms
including PLAYSTATION 3, XBox 360, Wii, PC, Linux, Mac OSX and iPhone
Discrete and continuous collision detection including ray and convex sweep test. Collision
shapes include concave and convex meshes and all basic primitives
Fast and stable rigid body dynamics constraint solver, vehicle dynamica, character
controller and slider, hinge, generic 6DOF and cone twist constraint for ragdolls
Soft Body dynamics for cloth, rope and deformable volumes with two-way interaction with
rigid bodies, including constraint support
Maya Dynamica plugin, Blender integration, COLLADA physics import/export support
Contact and Support
Public forum for support and feedback is available at http://bulletphysics.com
PLAYSTATION 3 licensed developers can download an optimized version for Cell SPU
through Sony PS3 Devnet from https://ps3.scedev.net/projects/spubullet
http://bulletphysics.com
©Erwin Coumans Bullet 2.74 Physics SDK Manual
- 5 -
2 Quickstart
Step 1: Download
Windows developers should download the zipped sources from of Bullet from
http://bulletphysics.com
. Mac OS X, Linux and other developers should download the gzipped tar
archive.
Step 2: Building
Bullet should compile out-of-the-box for all platforms, and includes all dependencies.
Windows Visual Studio projectfiles for all versions are available in Bullet/msvc. The
main Workspace/Solution is located in
Bullet/msvc/8/wksbullet.sln
CMake adds support for many other build environments and platforms, including XCode
for Mac OSX, KDevelop for Linux and Unix Makefiles. Download and install Cmake from
http://www.cmake.org. Run cmake without arguments to see the list of build system
generators for your platform. For example to generate Mac OSX Xcode project files , run
cmake . –G Xcode
or to generate Linux/Unix Makefiles, run
cmake . –G “Unix Makefiles”
or for Microsoft Visual Studio 8 2005, use
cmake . –G “Visual Studio 8 2005”
Autoconf/automake generates both Makefile and Jamfile. Run ./autogen.sh,
./configure and then make or jam.
Step 3: Testing demos
Try to run and experiment with Demos/AllBulletDemos executable as a starting point. Bullet can
be used in several ways, as full rigid body simulation, as collision detector library or low level /
snippets such as GJK closest point calculation. The dependencies can be seen in the doxygen
documentation under ‘Directories’.
Step 4: Integrating Bullet physics in your application
Check out CcdPhysicsDemo how to create a btDiscreteDynamicsWorld , btCollisionShape,
btMotionState and btRigidBody. Each frame call the stepSimulation on the dynamics
world, and synchronize the world transform for your graphics object. Requirements:
#include “btBulletDynamicsCommon.h” in your source file
