BulletIntegration: improve MotionState documentation

[xqms]

The documentation gives the impression that SceneGraph changes are automatically propagated to the Bullet world - this is not the case. The SceneGraph transforms are only used for initialization.

Reference: https://github.com/bulletphysics/bullet3/blob/c993175a5859e48783cf2c490947d826be5649b2/src/BulletDynamics/Dynamics/btRigidBody.cpp#L67 (try searching the file for other occurences of MotionState::getWorldTransform() - the only other occurrence is for kinematic objects)

This modifies the documentation accordingly and adds a snippet on how to manually sync SceneGraph -> Bullet.

[mosra]

Thanks! Yeah, this was my (wrong) impression too (and also the wrong answer whenever somebody asked).

Kinematic objects ... wouldn't it then make more sense to make given rigid body kinematic instead? I would assume changing transformations for non-kinematic objects in such an "underhanded" way might make Bullet upset. Or is there an use-case where one would want a to update position of a non-kinematic object?

So instead I would suggest that the users make the body kinematic if they need two-way updates.

[xqms]

My understanding of kinematic bodies is that they do not perform full dynamic simulation, i.e. bullet does not change their poses and assumes they are static. That would be a pretty severe constraint.

My use case is that I create a Scenegraph with a connected bullet world, and then initialize the poses. In that case a one-time manual sync is best.

[mosra]

bullet does not change their poses and assumes they are static

Ah! Didn't know that, sorry. Yeah, then this makes sense. Found this on SO, too.

Merged in e92ba9068704cfbaa8918334e10f2478bda3258d and I'm also mentioning the kinematic bodies there now, in case that would fit someone's use case. Hopefully the wording makes sense, I kinda fail at English today :)