Added documentation

Docs/Architecture.md

@@ -6,7 +6,7 @@ For demos and videos go to the [Samples](Samples.md) section.
 
 We use a pretty traditional physics engine setup. We have rigid bodies ([Body](@ref Body)) that have attached collision volumes ([Shape](@ref Shape)). Bodies can either be static (not simulating), dynamic (moved by forces) or kinematic (moved by velocities only). Each moving body has a [MotionProperties](@ref MotionProperties) object that contains information about the movement of the object. Static bodies do not have this to save space (but they can be configured to have it if a static body needs to become dynamic during its lifetime by setting [BodyCreationSettings::mAllowDynamicOrKinematic](@ref BodyCreationSettings::mAllowDynamicOrKinematic)).
 
-Bodies are inserted into the [PhysicsSystem](@ref PhysicsSystem) through the [BodyInterface](@ref BodyInterface). The body interface comes in two flavors: A locking and a non-locking variant. The locking variant uses a mutex array (a fixed size array of mutexes, bodies are associated with a mutex through hashing and multiple bodies use the same mutex, see [MutexArray](@ref MutexArray)) to prevent concurrent access to the same body. The non-locking variant doesn't use mutexes, so requires the user to be careful.
+Bodies are inserted into the [PhysicsSystem](@ref PhysicsSystem) and interacted with through the [BodyInterface](@ref BodyInterface). Jolt is designed to be accessed from multiple threads so the body interface comes in two flavors: A locking and a non-locking variant. The locking variant uses a mutex array (a fixed size array of mutexes, bodies are associated with a mutex through hashing and multiple bodies use the same mutex, see [MutexArray](@ref MutexArray)) to prevent concurrent access to the same body. The non-locking variant doesn't use mutexes, so requires the user to be careful.
 
 In general, body ID's ([BodyID](@ref BodyID)) are used to refer to bodies. You can access a body through the following construct:
 
@@ -29,6 +29,21 @@ When another thread has removed the body between the time the body ID was obtain
 
 You cannot use BodyLockRead to lock multiple bodies (if two threads lock the same bodies in opposite order you'll get a deadlock). Use [BodyLockMultiRead](@ref BodyLockMultiRead) or [BodyLockMultiWrite](@ref BodyLockMultiWrite) to lock them in a consistent order.
 
+Note that a lot of convenience functions are exposed through the BodyInterface, but not all functionality is available, so you may need to lock the body to get the pointer and then call the function directly on the body.
+
+## Body Pointers vs Body ID's
+
+If you're only accessing the physics system from a single thread, you can use Body pointers instead of BodyID's. In this case you can also use the non-locking variant of the body interface.
+
+Note that there are still some restrictions:
+
+* You cannot read from / write to bodies or constraints while PhysicsSystem::Update is running. As soon as the Update starts, all body / constraint mutexes are locked.
+* Collision callbacks (see ContactListener) are called from within the PhysicsSystem::Update call from multiple threads. You can only read the body data during a callback.
+* Activation callbacks (see BodyActivationListener) are called in the same way. Again you should only read the body during the callback and not make any modifications.
+* Step callbacks (see PhysicsStepListener) are also called from PhysicsSystem::Update from multiple threads. You're responsible for making sure that there are no race conditions. In a step listener you can read/write bodies or constraints but you cannot add/remove them. 
+
+If you are accessing the physics system from multiple threads, you should probably use BodyID's and the locking variant of the body interface. It is however still possible to use Body pointers if you're really careful. E.g. if there is a clear owner of a Body and you ensure that this owner does not read/write state during PhysicsSystem::Update or while other threads are reading the Body there will not be any race conditions.
+
 ## Shapes
 
 Each body has a shape attached that determines the collision volume. The following shapes are available (in order of computational complexity):

Jolt/Physics/Body/BodyActivationListener.h

@@ -17,11 +17,11 @@ public:
 	virtual					~BodyActivationListener() = default;
 
 	/// Called whenever a body activates, note this can be called from any thread so make sure your code is thread safe.
-	/// At the time of the callback the body inBodyID will be locked and no bodies can be activated/deactivated from the callback.
+	/// At the time of the callback the body inBodyID will be locked and no bodies can be written/activated/deactivated from the callback.
 	virtual void			OnBodyActivated(const BodyID &inBodyID, uint64 inBodyUserData) = 0;
 
 	/// Called whenever a body deactivates, note this can be called from any thread so make sure your code is thread safe.
-	/// At the time of the callback the body inBodyID will be locked and no bodies can be activated/deactivated from the callback.
+	/// At the time of the callback the body inBodyID will be locked and no bodies can be written/activated/deactivated from the callback.
 	virtual void			OnBodyDeactivated(const BodyID &inBodyID, uint64 inBodyUserData) = 0;
 };
 

Jolt/Physics/Collision/BroadPhase/BroadPhaseQuery.h

@@ -23,7 +23,8 @@ using RayCastBodyCollector = CollisionCollector<BroadPhaseCastResult, CollisionC
 using CastShapeBodyCollector = CollisionCollector<BroadPhaseCastResult, CollisionCollectorTraitsCastShape>;
 using CollideShapeBodyCollector = CollisionCollector<BodyID, CollisionCollectorTraitsCollideShape>;
 
-/// Interface to the broadphase that can perform collision queries. These queries will only test the bounding box of the body to quickly determine a potential set of colliding bodies
+/// Interface to the broadphase that can perform collision queries. These queries will only test the bounding box of the body to quickly determine a potential set of colliding bodies.
+/// The shapes of the bodies are not tested, if you want this then you should use the NarrowPhaseQuery interface.
 class BroadPhaseQuery : public NonCopyable
 {
 public:

Jolt/Physics/Collision/NarrowPhaseQuery.h

@@ -17,7 +17,8 @@ class Shape;
 class CollideShapeSettings;
 class RayCastResult;
 
-/// Class that provides an interface for doing precise collision detection against the broad and then the narrow phase
+/// Class that provides an interface for doing precise collision detection against the broad and then the narrow phase.
+/// Unlike a BroadPhaseQuery, the NarrowPhaseQuery will test against shapes and will return collision information against triangles, spheres etc.
 class NarrowPhaseQuery : public NonCopyable
 {
 public:

Jolt/Physics/PhysicsStepListener.h

@@ -16,8 +16,10 @@ public:
 	virtual					~PhysicsStepListener() = default;
 
 	/// Called before every simulation step (received inCollisionSteps times for every PhysicsSystem::Update(...) call)
-	/// This is called while all bodies and constraints are locked for modifications. Multiple listeners can be executed in parallel and it is the responsibility of the listener
-	/// to avoid race conditions.
+	/// This is called while all body and constraint mutexes are locked. You can read/write bodies and constraints but not add/remove them.
+	/// Multiple listeners can be executed in parallel and it is the responsibility of the listener to avoid race conditions.
+	/// The best way to do this is to have each step listener operate on a subset of the bodies and constraints
+	/// and making sure that these bodies and constraints are not touched by any other step listener.
 	/// Note that this function is not called if there aren't any active bodies or when the physics system is updated with 0 delta time.
 	virtual void			OnStep(float inDeltaTime, PhysicsSystem &inPhysicsSystem) = 0;
 };