Documentation?

[Eon]

I feel a bit stupid and I'm wondering how everyone else on this forum seems to be getting stuff done. I don't know if my browser is blocking stuff or what, but this physics library seems to me to be mostly undocumented.

I have a fairly good understanding of vector math and physics and I successfully implemented the hello world app in C++ in Visual Studio 2010 (Bullet 2.81), even though my object didn't bounce as in your graph until I set the restitution on both the ground and the fall object. But I can't get much further.

I don't know what units are used and I don't know what different things like "angular sleeping threshold" means or which object's friction is used during contact. I'm having a hard time simulating a bouncing, then rolling ball. There are also many implementation subtleties; trial and error is taking very long. I use Google mostly to find stuff, but the class documentation looks like trimmed source code. Is this how it should appear (even if only for now)?

[Mako_energy02]

You aren't stupid, and most of us just stumble around until we get something that closely matches our expectations. Bullet is in fact mostly undocumented; much to the dismay of virtually everyone that posts here. There is a steep learning curve to bullet as a result and you have to do some tinkering and carefully read posts on these forums to get an understanding of Bullet.

As for the specific things you mentioned:
Angular Sleeping Threshold - I'll admit this is a new term for me, but based on things I've tinkered with in the past I would assume it's the amount of rotation needed in a simulation step to keep a body from being deactivated (deactivated meaning it's skipped for processing until a force is acted upon it, it's a simple optimization).

Friction - The friction of both objects is used while objects are colliding. Restitution works the same way. Think of it like this...a surface tipped up at a 45 degree angle that is made of rubber won't do much to stop a cube coated in teflon. If however it was made of wood or rubber, that would change the behavior. The friction of objects matters.

Bouncing - You seem to have already found Restitution, but there are some quirks to this in bullet. Depending on the collision shape used bouncing may behave in odd ways. In general it's best to stick to shapes that are very simple when you want objects to bounce, such as boxes and spheres. Otherwise artifacts such as objects being shot off at odd angles can sometimes occur. I'm not entirely sure what you mean by rolling. I mean, I understand the word, but I'm not sure I have a clear picture of the behavior you want.

Implementation Subtleties - There are countless subtleties to using bullet but they are far from impossible to work with. I may be able provide more advice in this regard if you could narrow down the issue/complaint you have.

[Erwin Coumans]

The starting point for Bullet documentation is the user guide PDF files. They are included in the Bullet SDK:

See https://bullet.googlecode.com/svn/trunk ... Manual.pdf and
https://bullet.googlecode.com/svn/trunk ... kstart.pdf

Secondly, you are supposed to learn from the Bullet demos. That should help you getting started.

Then there is the wiki, the doxygen docs and this forum as last option, but you should read the manual and demos first.
If you are not comfortable with reading C++ in the demos or SDK, Bullet is likely not your best choice for physics engine.

To answer your friction and restitution (bounce) question here:

friction and restitution is simply multiplying the values from each body, here is the code in src\BulletCollision\CollisionDispatch\btManifoldResult.cpp:

Code: Select all

inline btScalar	calculateCombinedRollingFriction(const btCollisionObject* body0,const btCollisionObject* body1)
{
	btScalar friction = body0->getRollingFriction() * body1->getRollingFriction();

	const btScalar MAX_FRICTION  = btScalar(10.);
	if (friction < -MAX_FRICTION)
		friction = -MAX_FRICTION;
	if (friction > MAX_FRICTION)
		friction = MAX_FRICTION;
	return friction;

}


///User can override this material combiner by implementing gContactAddedCallback and setting body0->m_collisionFlags |= btCollisionObject::customMaterialCallback;
btScalar	btManifoldResult::calculateCombinedFriction(const btCollisionObject* body0,const btCollisionObject* body1)
{
	btScalar friction = body0->getFriction() * body1->getFriction();

	const btScalar MAX_FRICTION  = btScalar(10.);
	if (friction < -MAX_FRICTION)
		friction = -MAX_FRICTION;
	if (friction > MAX_FRICTION)
		friction = MAX_FRICTION;
	return friction;

}

You can override the friction and restitution values using a contact added callback.
Thanks!
Erwin

[Jyavoc]

True, demos are the best way to learn, hands down -- to actually learn something, experience is the best. But when wanting to look up one function, or the nuance of a function, would it really hurt to have a succinct documentation? It would aid in the expansion of the userbase, and I can't think of a single reason against documentation other than "it takes time away from coding."

I'm still integrating myself into Bullet (and not being a physics-buff, back into physics as a whole), so I'd be horrid writing documentation now, but once I get the hang of Bullet, wouldn't having true documentation only be a boon?

[adi1133]

I agree bullet lacks proper documentation compared to other opensource projects :/

[Jyavoc]

I don't criticize it (logically -- when I'm angry that something doesn't work, maybe); I'm not a paragon of writing documentation. Compared to writing code, it seems so... redundant. But as I know that I'll never be knowledgeable enough in physics to write the code, there are certainly other ways that I could contribute. Granted, I've a bit more to do before I write anything. But with opensource projects, to idly criticize something and not just do it is only a fault of oneself, not the programmers.

[DannyChapman]

But with opensource projects, to idly criticize something and not just do it is only a fault of oneself, not the programmers.

No - I disagree with this! People make projects free and/or opensource for a number of reasons - e.g. they're enthusiastic about what they do as a hobby, or they've learnt loads from the "community" and want to give something back, or they want to make contacts and get stimulating ideas, or they want to make a name for themselves etc etc. There are different ways to help them succeed in what they're trying to do. Contributing code is one way - but just using the code/project and providing feedback is in many ways an important contribution too.

In my opinion, decent documentation and a _much_ cleaner API would help people to use Bullet. It feels like 90% of the effort has been on functionality, and very little on usability. At the moment, that's the only "contribution"* I can make, because I'm flat out on my own project (http://rowlhouse.co.uk/PicaSim/), which uses Bullet. Still very grateful for it, though - it works very well!

- Danny

* I have got a couple of tweaks I've made locally:

1. An additional bounding volume test, without which collisions with heightmaps are incredibly slow (using Bullet 2.79)

2. Supporting additional angular momentum - for gyroscopic elements (e.g. a propeller) that are "embedded" within a rigid body.

I'm quite happy to share these tweaks if anyone wants them...