BulletIntegration: Usage

[ghost]

I'm having a little bit of trouble figuring out exactly how BulletIntegration works.

I understand:

• [ x] - MotionState is a feature you hang off of an object you want to physic-ify
• [ x] - You can use the simplified converters to convert from Magnum collision shapes to Bullet collision shapes

I don't understand:

• [ ] - How to idiomatically hook these two things together to get a working physics object
• [ ] - Why MotionState doesn't provide some simple helper functions to set common things like restitution and friction, so we don't need to know exactly how Bullet works for simple things

Do we have any examples or anything? I'm sorry if I simply missed them!

[mosra]

There is a very basic bullet example in the magnum-examples repo, which just shows a bunch of boxes and you can throw more boxes on it.

Other than that, @Squareys uses this part of the engine very extensively so he should be able to answer your questions, so mentioning him here :)

[ghost]

@mosra Ah, I must have missed it; I'll take a look at that example, thank you.

@Squareys Yes, any information or examples you can provide would be most appreciated!

As well, would either of you be opposed to adding some common helper "pass through" functions to the MotionState feature? Restitution, Friction, and other common physics attributes would make the API much more attractive, and are unlikely to not be supplied by any alternate physics API (in case an AnyPhysics API is eventually made).

I would definitely be willing to supply a pull request adding these common functions, helping to "Magnum-ify" the physics API a bit.

Edit: As well, having looked at the bullet example, the integration looks a little primitive, with a lot of Bullet specific things needing to be done just to get things up and running. Is there any plan to wrap some of it up into a cleaner, more Magnum-ish interface, or is the idea to provide only a very minimal wrapper?

[Squareys]

@Alicemargatroid Hi! Yes, I use bullet together with Magnum alot.

BulletIntegration is only a very thin layer between bullet and Magnum. The only two things it provides are

• Ability to "attach" a Magnum Object to a bullet physics body using MotionState. The object will always have the same transformation as the bullet object, but not the other way around (I believe it does, actually. But sets the bullet (world) transformation as local transformation, which is not really useful). You then need to affect the btRigidBody you attached it to for example.
• Conversions between Math types, e.g. Vector3 magnum = Vector3(bulletVector) and btVector3 bullet = btVector3(magnumVector).

You use bullet directly, BulletIntegration is simply the connection to Magnum, which you use for rendering. With that, you should look for examples on how to use bullet here, while the example to connect that bullet code is, as @mosra already mentioned, here.

If you need any specific help, just drop me a message on gitter :)

PS: Restitution, friction, mass etc. are physics specific features you would set for the bullet object. PPS:

Is there any plan to wrap some of it up into a cleaner, more Magnum-ish interface, or is the idea to provide only a very minimal wrapper?

No, since magnum is meant to be a graphics engine... (Even though it does have Audio and file loading and everything)... unless you plan it, of course ;)

[ghost]

@Squareys Excellent, thank you for the examples, this will help a lot.

That was, however, my exact thought: Magnum::Audio wraps OpenAL into a much more convenient interface. Wouldn't it be a good idea to do the same with BulletIntegration?

That's why I thought it might be a good idea to provide wrappers in MotionState for certain common operations, such as setting/getting the btMotionState state.

[Squareys]

Wouldn't it be a good idea to do the same with BulletIntegration?

Since OpenAL only has a C API and not C++, it makes a little more sense there. Bullet already provides (only) a C++ API, though. Wrapping that would most likely just add overhead and make adapting to changes harder (I don't even know if Bullet3 is currently compatible with BulletIntegration to begin with). Not to mention, bullet has alot of features, which would probably take alot of time to wrap. Finding a common API for multiple APIs usually leads to restrictions and compromises, which is why Magnum does OpenGL, and doesn't have DirectX or Vulkan "backends", which you may see in other graphics libraries. (There is a entirely new API for Vulkan planned instead, for example.)

My opinion:

• From experience, I'd agree that Bullet API, like probably every other API, takes a little time to get used to, and documentation (apart from the examples) is rather sparse (this wiki may help?).
• Once you got used to it, though, and know where you need to look for how to do stuff (the bullet examples), it's rather simple to get stuff done.
• A Magnum-like API for Bullet's "already C++" API will probably not provide much additional value in this case, so it'll probably not be worth the effort. I think learning the Bullet API is probably alot quicker/easier, etc. I may be wrong, of course ;)
• There are some things that could improve BulletIntegration, of course:
  • Bullet debug renderer, see #11
  • MotionState does not handle parenting, aka. the world transformation of bullet is set as local transformation, which results in offsets. The parent transformation should be subtracted.
  • Utility function to convert magnum MeshData into a bullet collision mesh (I have code to do that already, in case you need it)

I did a full wrapper for Oculus SDK, which turned out to be a huge amount of work, while setting up OpenVR without wrapping it, was trivial in comparison. OvrIntegration still requires work every now and then to adapt to API changes. With this, I would recommend only doing a similarly rudimentary integration for Box2D, aswell. A small amount of effort can already provide alot of convenience. (Conversion for math types is really valuable, even though it may seem like a small thing ;) )

PS:

That's why I thought it might be a good idea to provide wrappers in MotionState for certain common operations, such as setting/getting the btMotionState state.

There is a getter and MotionState inherits from btMotionState? Or did I misunderstand what you meant?

[mosra]

I think this was answered already pretty well, there is an example showing the overall usage, the decision is to not provide a full Bullet wrapper and with #22 being merged there is also finally improved usage documentation of the MotionState wrapper class.