Added more documentation on scaling shapes

Docs/Architecture.md

@@ -211,6 +211,26 @@ will return a box of size 2x2x2 centered around the origin, so in order to get i
 
 Note that when you work with interface of [BroadPhaseQuery](@ref BroadPhaseQuery), [NarrowPhaseQuery](@ref NarrowPhaseQuery) or [TransformedShape](@ref TransformedShape) this transformation is done for you.
 
+### Scaling Shapes {#scaling-shapes}
+
+Shapes can be scaled using the [ScaledShape](@ref ScaledShape) class. You can scale a shape like:
+
+	JPH::RefConst<Shape> my_scaled_shape = new JPH::ScaledShape(my_non_scaled_shape, JPH::Vec3(x_scale, y_scale, z_scale));
+
+Not all scales are valid for every shape. Use Shape::IsValidScale to check if a scale is valid for a particular shape (the documentation for this function also lists the rules for all shape types).
+
+A safer way of scaling shapes is provided by the Shape::ScaleShape function:
+
+	JPH::Shape::ShapeResult my_scaled_shape = my_non_scaled_shape->ScaleShape(JPH::Vec3(x_scale, y_scale, z_scale));
+
+This function will check if a scale is valid for a particular shape and if a scale is not valid, it will produce the closest scale that is valid. 
+For example, if you scale a CompoundShape that has rotated sub shapes, a non-uniform scale would cause shearing. In that case the Shape::ScaleShape function will create a new compound shape and scale the sub shapes (losing the shear) rather than creating a ScaledShape around the entire CompoundShape.
+
+Updating scaling after a body is created is also possible, but should be done with care. Imagine a sphere in a pipe, scaling the sphere so that it becomes bigger than the pipe creates an impossible situation as there is no way to resolve the collision anymore. 
+Please take a look at the [DynamicScaledShape](https://github.com/jrouwe/JoltPhysics/blob/master/Samples/Tests/ScaledShapes/DynamicScaledShape.cpp) demo. The reason that no ScaledShape::SetScale function exists is to ensure thread safety when collision queries are being executed while shapes are modified.
+
+Note that there are many functions that take a scale in Jolt (e.g. CollisionDispatch::sCollideShapeVsShape), usually the shape is scaled relative to its center of mass. The Shape::ScaleShape function scales the shape relative to the origin of the shape.
+
 ### Creating Custom Shapes {#creating-custom-shapes}
 
 If the defined Shape classes are not sufficient, or if your application can make a more efficient implementation because it has specific domain knowledge, it is possible to create a custom collision shape:

Jolt/Physics/Collision/CastConvexVsTriangles.h

@@ -16,7 +16,7 @@ public:
 	/// Constructor
 	/// @param inShapeCast The shape to cast against the triangles and its start and direction
 	/// @param inShapeCastSettings Settings for performing the cast
-	/// @param inScale Local space scale for the shape to cast against.
+	/// @param inScale Local space scale for the shape to cast against (scales relative to its center of mass).
 	/// @param inCenterOfMassTransform2 Is the center of mass transform of shape 2 (excluding scale), this is used to provide a transform to the shape cast result so that local quantities can be transformed into world space.
 	/// @param inSubShapeIDCreator1 Class that tracks the current sub shape ID for the casting shape
 	/// @param ioCollector The collector that receives the results.

Jolt/Physics/Collision/CastSphereVsTriangles.h

@@ -15,7 +15,7 @@ public:
 	/// Constructor
 	/// @param inShapeCast The sphere to cast against the triangles and its start and direction
 	/// @param inShapeCastSettings Settings for performing the cast
-	/// @param inScale Local space scale for the shape to cast against.
+	/// @param inScale Local space scale for the shape to cast against (scales relative to its center of mass).
 	/// @param inCenterOfMassTransform2 Is the center of mass transform of shape 2 (excluding scale), this is used to provide a transform to the shape cast result so that local quantities can be transformed into world space.
 	/// @param inSubShapeIDCreator1 Class that tracks the current sub shape ID for the casting shape
 	/// @param ioCollector The collector that receives the results.

Jolt/Physics/Collision/CollideConvexVsTriangles.h

@@ -19,7 +19,7 @@ class JPH_EXPORT CollideConvexVsTriangles
 public:
 	/// Constructor
 	/// @param inShape1 The convex shape to collide against triangles
-	/// @param inScale1 Local space scale for the convex object
+	/// @param inScale1 Local space scale for the convex object (scales relative to its center of mass)
 	/// @param inScale2 Local space scale for the triangles
 	/// @param inCenterOfMassTransform1 Transform that takes the center of mass of 1 into world space
 	/// @param inCenterOfMassTransform2 Transform that takes the center of mass of 2 into world space

Jolt/Physics/Collision/CollideSphereVsTriangles.h

@@ -18,7 +18,7 @@ class JPH_EXPORT CollideSphereVsTriangles
 public:
 	/// Constructor
 	/// @param inShape1 The sphere to collide against triangles
-	/// @param inScale1 Local space scale for the sphere
+	/// @param inScale1 Local space scale for the sphere (scales relative to its center of mass)
 	/// @param inScale2 Local space scale for the triangles
 	/// @param inCenterOfMassTransform1 Transform that takes the center of mass of 1 into world space
 	/// @param inCenterOfMassTransform2 Transform that takes the center of mass of 2 into world space

Jolt/Physics/Collision/CollisionDispatch.h

@@ -21,8 +21,8 @@ public:
 	/// Collide 2 shapes and pass any collision on to ioCollector
 	/// @param inShape1 The first shape
 	/// @param inShape2 The second shape
-	/// @param inScale1 Local space scale of shape 1
-	/// @param inScale2 Local space scale of shape 2
+	/// @param inScale1 Local space scale of shape 1 (scales relative to its center of mass)
+	/// @param inScale2 Local space scale of shape 2 (scales relative to its center of mass)
 	/// @param inCenterOfMassTransform1 Transform to transform center of mass of shape 1 into world space
 	/// @param inCenterOfMassTransform2 Transform to transform center of mass of shape 2 into world space
 	/// @param inSubShapeIDCreator1 Class that tracks the current sub shape ID for shape 1
@@ -44,7 +44,7 @@ public:
 	/// @param inShapeCastLocal The shape to cast against the other shape and its start and direction.
 	/// @param inShapeCastSettings Settings for performing the cast
 	/// @param inShape The shape to cast against.
-	/// @param inScale Local space scale for the shape to cast against.
+	/// @param inScale Local space scale for the shape to cast against (scales relative to its center of mass).
 	/// @param inShapeFilter allows selectively disabling collisions between pairs of (sub) shapes.
 	/// @param inCenterOfMassTransform2 Is the center of mass transform of shape 2 (excluding scale), this is used to provide a transform to the shape cast result so that local hit result quantities can be transformed into world space.
 	/// @param inSubShapeIDCreator1 Class that tracks the current sub shape ID for the casting shape

Jolt/Physics/Collision/Shape/Shape.h

@@ -247,7 +247,7 @@ public:
 	/// @param inSubShapeID Sub shape ID of target shape
 	/// @param inDirection Direction that the face should be facing (in local space to this shape)
 	/// @param inCenterOfMassTransform Transform to transform outVertices with
-	/// @param inScale Scale of this shape
+	/// @param inScale Scale in local space of the shape (scales relative to its center of mass)
 	/// @param outVertices Resulting face. The returned face can be empty if the shape doesn't have polygons to return (e.g. because it's a sphere). The face will be returned in world space.
 	virtual void					GetSupportingFace([[maybe_unused]] const SubShapeID &inSubShapeID, [[maybe_unused]] Vec3Arg inDirection, [[maybe_unused]] Vec3Arg inScale, [[maybe_unused]] Mat44Arg inCenterOfMassTransform, [[maybe_unused]] SupportingFace &outVertices) const { /* Nothing */ }
 
@@ -258,14 +258,14 @@ public:
 	/// @param inSubShapeID Sub shape ID that indicates the path to the leaf shape
 	/// @param inPositionCOM The position of the center of mass of this shape
 	/// @param inRotation The orientation of this shape
-	/// @param inScale Scale of this shape
+	/// @param inScale Scale in local space of the shape (scales relative to its center of mass)
 	/// @param outRemainder The remainder of the sub shape ID after removing the sub shape
 	/// @return Direct child sub shape and its transform, note that the body ID and sub shape ID will be invalid
 	virtual TransformedShape		GetSubShapeTransformedShape(const SubShapeID &inSubShapeID, Vec3Arg inPositionCOM, QuatArg inRotation, Vec3Arg inScale, SubShapeID &outRemainder) const;
 
 	/// Gets the properties needed to do buoyancy calculations for a body using this shape
 	/// @param inCenterOfMassTransform Transform that takes this shape (centered around center of mass) to world space (or a desired other space)
-	/// @param inScale Scale in local space of the shape
+	/// @param inScale Scale in local space of the shape (scales relative to its center of mass)
 	/// @param inSurface The surface plane of the liquid relative to inCenterOfMassTransform
 	/// @param outTotalVolume On return this contains the total volume of the shape
 	/// @param outSubmergedVolume On return this contains the submerged volume of the shape
@@ -308,7 +308,7 @@ public:
 
 	/// Collides all vertices of a soft body with this shape and updates SoftBodyVertex::mCollisionPlane, SoftBodyVertex::mCollidingShapeIndex and SoftBodyVertex::mLargestPenetration if a collision with more penetration was found.
 	/// @param inCenterOfMassTransform Center of mass transform for this shape relative to the vertices.
-	/// @param inScale The scale to use for this shape
+	/// @param inScale Scale in local space of the shape (scales relative to its center of mass)
 	/// @param ioVertices The vertices of the soft body
 	/// @param inNumVertices The number of vertices in ioVertices
 	/// @param inDeltaTime Delta time of this time step (can be used to extrapolate the position using the velocity of the particle)

Jolt/Physics/Collision/ShapeCast.h

@@ -59,7 +59,7 @@ struct ShapeCastT
 	}
 
 	const Shape *				mShape;								///< Shape that's being cast (cannot be mesh shape). Note that this structure does not assume ownership over the shape for performance reasons.
-	const Vec3					mScale;								///< Scale in local space of the shape being cast
+	const Vec3					mScale;								///< Scale in local space of the shape being cast (scales relative to its center of mass)
 	const Mat					mCenterOfMassStart;					///< Start position and orientation of the center of mass of the shape (construct using sFromWorldTransform if you have a world transform for your shape)
 	const Vec3					mDirection;							///< Direction and length of the cast (anything beyond this length will not be reported as a hit)
 	const AABox					mShapeWorldBounds;					///< Cached shape's world bounds, calculated in constructor