Real-Time Physics Simulation Forum

I've been busy with conferences and research towards Bullet 3.x recently. You can check out my experiments at https://github.com/erwincoumans

Some of the work includes compatibility with the Sony Physics Effects 2.x library, Finite Element Method/FEM based simulation and also support for premake4 build system, some OpenCL and DirectCompute acceleration, Gwen GUI system and mobile platforms such as Android and iPhone.

Due to this, I didn't spend much time in the forums and on fixing Bullet 2.x issues. I'll prepare some Bullet 2.89 bugfix release in a month or two.

Also there has been a lot of forum spam recently, so I added some more difficult to guess questions at registration, hopefully that helps.
Thanks,
Erwin

Good to know. FEM-based simulation gets me fairly excited!
As a side note, a professor around there proposed some time ago the "cell method". Some years ago I tried to play a bit with it but didn't understand much. I'd like somebody to have a look and perhaps have some thoughts about that to share.

That would be fantastic! If another release with bug fixes were to come out fairly soon I would be able to adopt it into our project before it ships.

Great news! Bullet is a very good simulation engine. On the other hand, the documentation is lacking. I think there should be some effort to document the API and internals, and add some extra comments to the code before any new features are added.
Bullet is IMHO severely undervalued and overlooked because of this lack of documentation.

I agree with the above completely. Along that line of thought, I would really love it if the next couple updates just address bugs and problems with existing features. Maybe before 3.x comes out with a bunch of new features we can get a more solid 2.x version distributed. As a third party game developer the lack of documentation and (moreso) comments is annoying but workable with a little digging, however having to fix bugs that are in the library yourself constantly in order to develop with Bullet is holding it back even more IMO.

Love Bullet though, its a great system and I will continue to assist with patches and such as much as I can.

kc297 wrote:On the other hand, the documentation is lacking. I think there should be some effort to document the API and internals, and add some extra comments to the code before any new features are added. Bullet is IMHO severely undervalued and overlooked because of this lack of documentation.

I am inclined to agree with this. I'd say most users don't use a lot of Bullet's features (or don't use them *correctly*) because there is very little documentation, so they either don't know about them or don't know what they're for. This also deters newcomers or those not willing or able to pore over the code and understand it (which even for an experienced programmer can be a bit daunting at times). So I think it gets to a point where the trade-off between adding new features and documenting previous ones starts to lean towards the latter, in terms of usability and attractiveness of Bullet to users (especially new ones).

Of course, I understand that there is still motivation to work on lots of bug fixes and add some wanted/exciting/useful (OpenCL! ) new features that I'm sure many users also request. And documenting code can be a bit tedious...

Would it make sense to have some sort or public wiki, where users (or a select set of users/moderators) can edit pages for each bullet class? With the apparent interest and involvement of people on on the forums, bits of comments for classes, their data members and functions could build up fairly nicely (I, for one, would be happy to make the occasional contribution). Of course, I realize that sometimes only the original code authors (ie. primarily Erwin and a handful of others) might really know how to properly use some of the code (and user interpretations may be incorrect), and as various codebase changes are made, some documentation can become obsolete or incorrect that the documentation contributors are unaware of. Still, it could be a big help (if even just in the interim in place of more thoroughly developed official documentation), in contrast to people asking the same questions over and over in the forums (or having to search for pre-existing questions) about the same classes, data members, functions, etc.

dphil wrote:Would it make sense to have some sort or public wiki, where users (or a select set of users/moderators) can edit pages for each bullet class?

The thing is though that there is a wiki, it's just that nobody ever bothers to update it. But the project uses doxygen, so there is really no need to have a page for each class.

Of course the doxygen is ideal - if it's fleshed out a lot more. I'm just trying to think of an alternative for the community to get involved to relieve some pressure/effort on Erwin. If he was comfortable opening up the source code to more people for in-line documentation, that works too. But I'm not sure that's an option.

All I want is comments in the headers. I don't want to have to look up a function in an external program, a brief description of what the func does before the func defintion in the header, unless of course its completely obvious what it does. And of course detailed comments of what the parameters do and how to use them. A good example is the parameters for the setLimit\setParam funcs in all of the constraint classes. I've had to wade through source and search through the forum to find out what they do, and even then its not entirely clear how they should be used.

I would be more then happy to submit patches to headers that does the above for the funcs that I've figured out and feel need them. Erwin would obviously read all of these patches before adding them so he could make any corrections as need be.

Having worked with the bullet library for about two weeks full-time I'd also like to chime in to the need for professional level documentation. The odd comment here and there is just not sufficient. Every class, method and member should have proper Doxygen compatible documentation. Please take a look at the Qt documentation for reference. It's brilliant. I'd like to think that the time spent by the developers on documentation would save an immense amount of time the users spend on getting their head around the library. I don't think users should reverse-engineer documentation Wiki-style as the developer(s) know the code base inside out.

Maybe one can join the documentation efforts and knowledge gained by users/devs?

If anyone has added some Doxygen comments flying around, I'd be happy to add them to https://github.com/martinfelis/bulletphysics2.

Wouldn't it be better to supply the additional doxygen commented parts as patch suggestions to Erwin?

It should be fairly easy:

1. Get the SVN repo of Bullet (not the zip)
2. Make the comment/doxygen additions (trying to make them as extensive as might be needed)
3. Create an svn patch.
4. Post it under googlecode issue at: http://code.google.com/p/bullet/issues/detail?id=42

This way the documentation can take shape in a somewhat more organised fashion, and Erwin can check each submitted patch on correctness and completeness and make corrections if needed before it is commited to the main lead. I think this might be preferable to having a separate repo.

more discussion on the documentation can be found here ( as well as a proposal(?) of the guidelines of commenting ).
http://bulletphysics.org/Bullet/phpBB3/ ... 108#p18108

Well there you go. No suprise this topic has been raised before and we've all been discussing it in the wrong place. Everyone who has commented on this issue should follow the link above and read on from that post (the stuff before it is pretty old and not as relevant).

I tried to get Havok (the free version thing for indie devs), quite surprised to see that when the download started, it was a 1.1GB file at 20ko/s. Open source is still important to me, but still a physics is a ton of work... Everybody needs a little money to live

Still I'm still eager to see the doc grow.

Cheers !

@gokoon: Why did you post that here?

This was an old topic that need not be revived...