Update documentation for 3.1 release (#898)

enable more warnings
release notes
improve character sample onGround logic

Author: erincatto

.clang-format

@@ -7,13 +7,11 @@
 Language: Cpp
 BasedOnStyle: Microsoft
 
-# BreakBeforeBraces: Allman 
 BreakBeforeBraces: Custom
 BraceWrapping:
   AfterCaseLabel: true
   AfterUnion: true
   BeforeWhile: true
-# BreakBeforeBinaryOperators: All
 
 ColumnLimit: 130
 PointerAlignment: Left
@@ -33,13 +31,9 @@ IncludeCategories:
 
 IndentExternBlock: NoIndent
 IndentCaseLabels: true
-#IndentPPDirectives: None
 IndentAccessModifiers: false
 AccessModifierOffset: -4
 
-# AlignArrayOfStructures: Left
-# AlignAfterOpenBracket: BlockIndent
-
 SpacesInParens: Custom
 SpacesInParensOptions:
   Other: true

docs/CMakeLists.txt

@@ -45,8 +45,10 @@ doxygen_add_docs(doc
                 "collision.md"
                 "simulation.md"
                 "loose_ends.md"
+                "character.md"
                 "reading.md"
                 "faq.md"
                 "migration.md"
+                "release_notes_v310.md"
                 ALL
                 COMMENT "Generate HTML documentation")

docs/FAQ.md

@@ -9,23 +9,23 @@ should be included if possible. Support is [appreciated](https://github.com/spon
 Box2D [logo](https://box2d.org/images/logo.svg).
 
 ## What platforms does Box2D support?
-Box2D is developed using C17. Ports and bindings are likely available for most languages and platforms.
+Box2D is developed using C. Ports and bindings are likely available for most languages and platforms.
 
-Erin Catto maintains the C17 version, but provides no support for other languages. Other languages are supported
+Erin Catto maintains the C version, but provides no support for other languages. Other languages are supported
 by the community and possibly by the authors of those ports.
 
 ## Who makes it?
-Erin Catto is the creator and sole contributor of the C17 version of Box2D, with various others supporting the ports. Box2D is an open source project, and accepts community feedback.
+Erin Catto is the creator and sole contributor of the C version of Box2D, with various others supporting the ports. Box2D is an open source project, and accepts community feedback.
 
 ## How do I get help?
 You should read the documentation and the rest of this FAQ first. Also, you should study the examples included in the source distribution. Then you can visit the [Discord](https://discord.gg/aM4mRKxW) to ask any remaining questions.
 
-Please to not message or email Erin Catto for support. It is best to ask questions on the Discord server so that everyone can benefit from the discussion.
+Please to not message or email Erin Catto directly for support. It is best to ask questions on the Discord server so that everyone can benefit from the discussion.
 
 ## Documentation
 
 ### Why isn't a feature documented?
-If you grab the latest code from the git master branch you will likely find features that are not documented in the manual. New features are added to the manual after they are mature and a new point release is imminent. However, all major features added to Box2D are accompanied by example code in the samples application to test the feature and show the intended usage.
+If you grab the latest code from the git main branch you will likely find features that are not documented in the manual. New features are added to the manual after they are mature and a new point release is imminent. However, all major features added to Box2D are accompanied by example code in the samples application to test the feature and show the intended usage.
 
 ## Prerequisites
 
@@ -106,9 +106,9 @@ For the same input, and same binary, Box2D will reproduce any simulation. Box2D
 
 Box2D is also deterministic under multithreading. A simulation using two threads will give the same result as eight threads.
 
-However, people often want more stringent determinism. People often want to know if Box2D can produce identical results on different binaries and on different platforms. Currently this is not provided, but the situation may improve in a future update.
+Box2D has cross-platform determinism as of version 3.1.
 
-todo update here on cross-platform determinism
+However, Box2D does not have rollback determinism.
 
 ### But I really want determinism
 This naturally leads to the question of fixed-point math. Box2D does not support fixed-point math. In the past Box2D was ported to the NDS in fixed-point and apparently it worked okay. Fixed-point math is slower and more tedious to develop, so I have chosen not to use fixed-point for the development of Box2D.

docs/character.md

@@ -0,0 +1,41 @@
+# Character mover
+
+> **Caution**:
+> The character mover feature is new to version 3.1 and should be considered experimental.
+
+Box2D provides a few structures and functions you can use to build a character mover.
+
+These features support a `geometric` character mover. This is like
+a `kinematic` mover except the character mover is not a rigid body and does
+not exist in the simulation world. This is done to achieve features that
+would be difficult with a kinematic body.
+
+This type of mover may not be suitable for your game. It is less physical than a rigid body, but
+it gives you more control over the movement. It is the type of mover you might find
+in a first-person shooter or a game with platforming elements.
+
+The mover is assumed to be a capsule. Using a capsule helps keep movement smooth. The capsule should
+have a significant radius. It does not have to be a vertical capsule, but that is likely
+to be the easiest setup. There is no explicit handling of rotation. But slow rotation can
+work with this system.
+
+Let's review the features. First there are a couple world query functions.
+
+`b2World_CastMover()` is a custom shape cast that tries to avoid getting stuck when shapes start out touching.
+The feature is called _encroachment_. Since the capsule has a significant radius it can move closer
+to a surface it is touching without the inner line segment generating an overlap, which would cause
+the shape cast to fail. Due to the internal use of GJK, encroachment has little cost. The idea with encroachment is that
+the mover is trying to slide along a surface and we don't want to stop that even if there is some small movement into the surface.
+
+`b2World_CollideMover()` complements the cast function. This function generates collision planes for touching and/or overlapped surfaces. The character mover is assumed to have a fixed rotation, so it doesn't need contact manifolds or contact points. It just needs collision planes. Each plane is returned with the `b2Plane` and a `b2ShapeId` for each shape the mover is touching.
+
+Once you have some collision planes from `b2World_CollideMover()`, you can process and filter them to generate an array of `b2CollisionPlane`. These collision planes can then be sent to `b2SolvePlanes()` to generate a new position for the mover
+that attempts to find the optimal new position given the current position.
+
+These collision planes support *soft collision* using a `pushLimit`. This push limit is a distance value. A rigid surface will have a push limit of `FLT_MAX`. However, you may want some surfaces to have a limited effect on the character. For example, you may want the mover to push through other players or enemies yet still resolve the collision so they are not overlapped. Another example is a door or elevator that could otherwise push the mover through the floor.
+
+Finally after calling `b2SolverPlanes()` you can call `b2ClipVector()` to clip your velocity vector so the mover will not keep trying to push into a wall, which could lead to a huge velocity accumulation otherwise.
+
+The `Mover` sample shows all these functions being used together. It also includes other common character features such as acceleration and friction, jumping, and a pogo stick.
+
+![Character Mover](images/mover.png)

docs/collision.md

@@ -1,14 +1,14 @@
 # Collision
 Box2D provides geometric types and functions. These include:
-- raw geometry: circles, capsules, segments, and convex polygons
+- primitives: circles, capsules, segments, and convex polygons
 - convex hull and related helper functions
 - mass and bounding box computation
 - local ray and shape casts
 - contact manifolds
 - shape distance
-- generic shape cast
 - time of impact
 - dynamic bounding volume tree
+- character movement solver
 
 The collision interface is designed to be usable outside of rigid body simulation.
 For example, you can use the dynamic tree for other aspects of your game besides physics.
@@ -25,7 +25,7 @@ primitives that can be later attached to rigid bodies.
 Box2D shape primitives support several operations:
 - Test a point for overlap with the primitive
 - Perform a ray cast against the primitive
-- Compute the primitive's AABB
+- Compute the primitive's bounding box
 - Compute the mass properties of the primitive
 
 ### Circles
@@ -78,7 +78,7 @@ The polygon members are public, but you should use initialization
 functions to create a polygon. The initialization functions create
 normal vectors and perform validation.
 
-Polygons in Box2D have a maximum of 8 vertices, as controlled by #b2_maxPolygonVertices.
+Polygons in Box2D have a maximum of 8 vertices, as controlled by #B2_MAX_POLYGON_VERTICES.
 If you have more complex shapes, I recommend to use multiple polygons.
 
 There are a few ways to create polygons. You can attempt to create them manually,
@@ -97,19 +97,21 @@ This corresponds with circles and capsules using radii instead of diameters.
 Box2D also supports rounded polygons. These are convex polygons with a thick rounded skin.
 
 ```c
-b2Polygon roundedBox = b2MakeRoundedBox(0.5f, 1.0f, 0.25f);
+float radius = 0.25f;
+b2Polygon roundedBox = b2MakeRoundedBox(0.5f, 1.0f, radius);
 ```
 
 If you want a box that is not centered on the body origin, you can use an offset box.
 
 ```c
 b2Vec2 center = {1.0f, 0.0f};
 float angle = b2_pi / 4.0f;
-b2Polygon offsetBox = b2MakeOffsetBox(0.5f, 1.0f, center, angle);
+b2Rot rotation = b2MakeRot(angle);
+b2Polygon offsetBox = b2MakeOffsetBox(0.5f, 1.0f, center, rotation);
 ```
 
 If you want a more general convex polygon, you can compute the hull using `b2ComputeHull()`. Then you can
-create a polygon from the hull. You can make this rounded or not.
+create a polygon from the hull. You can make this rounded as well.
 
 ```c
 b2Vec2 points[] = {{-1.0f, 0.0f}, {1.0f, 0.0f}, {0.0f, 1.0f}};
@@ -210,7 +212,7 @@ You can cast a ray at a shape to get the point of first intersection and normal
 > consistent with Box2D treating convex shapes as solid. 
 
 ```c
-b2RayCastInput input;
+b2RayCastInput input = {0};
 input.origin = (b2Vec2){0.0f, 0.0f};
 input.translation = (b2Vec2){1.0f, 0.0f};
 input.maxFraction = 1.0f;
@@ -226,7 +228,7 @@ if (output.hit == true)
 You can also cast a shape at another shape. This uses an abstract way of describing the moving shape. It is represented as a point cloud with a radius. This implies a convex shape even if the input data is not convex. The internal algorithm (GJK) will essentially only use the convex portion.
 
 ```c
-b2ShapeCastInput input;
+b2ShapeCastInput input = {0};
 input.points[0] = (b2Vec2){1.0f, 0.0f};
 input.points[1] = (b2Vec2){2.0f, -3.0f};
 input.radius = 0.2f;

docs/extra.css

@@ -20,7 +20,7 @@ body {
 }
 
 div.contents {
-    max-width: 900px;
+    max-width: 1000px;
 }
 
 /* this works with doxygen /image */

docs/foundation.md

@@ -54,9 +54,18 @@ So when you design your game loop, you should let Box2D *go wide* and use multip
 In a multithreaded environment you must be careful to avoid [race conditions](https://en.wikipedia.org/wiki/Race_condition). Modifying the world while it is simulating will lead to unpredictable behavior and this is never safe. It is also not safe to read data from a Box2D world while it is simulating. Box2D may move data structures to improve cache performance. So it is very likely that you will read garbage data.
 
 > **Caution**:
-> Do not read or write the Box2D world during `b2World_Step()`
+> Do not perform read or write operations on a Box2D world during `b2World_Step()`
 
 > **Caution**:
 > Do not write to the Box2D world from multiple threads
 
 It *is safe* to do ray-casts, shape-casts, and overlap tests from multiple threads outside of `b2World_Step()`. Generally, any read-only operation is safe to do multithreaded outside of `b2World_Step()`. This can be very useful if you have multithreaded game logic.
+
+## Multithreading Multiple Worlds
+Some applications may wish to create multiple Box2D worlds and simulate them on different threads. This works fine because Box2D has very limited use of globals.
+
+There are a few caveats:
+- You will get a race condition if you create or destroy Box2D worlds from multiple threads. You should use a mutex to guard this.
+- If you will simulate multiple Box2D worlds simultaneously, then they should probably not use a task system. Otherwise you're likely to get preemption.
+- Any callbacks you hook up to Box2D must be thread-safe, such as memory allocators.
+- All of the limitations for single world simulation still apply.

docs/hello.md

@@ -80,7 +80,7 @@ meters, kilograms, and seconds. So you can consider the extents to be in
 meters. Box2D generally works best when objects are the size of typical
 real world objects. For example, a barrel is about 1 meter tall. Due to
 the limitations of floating point arithmetic, using Box2D to model the
-movement of glaciers or dust particles is not a good idea.
+movement of glaciers or dust particles might not work well.
 
 I'll finish the ground body in step 4 by creating the shape. For this step
 I need to create a shape definition which works fine with the default value.
@@ -104,8 +104,8 @@ don't move a shape around on the body. Moving or modifying a shape that
 is on a body is possible with certain functions, but it should not be part
 of normal simulation. The reason is simple: a body with
 morphing shapes is not a rigid body, but Box2D is a rigid body engine.
-Many of the algorithms in Box2D are based on the rigid body model.
-If this is violated you may get unexpected behavior.
+Many of the algorithms in Box2D are based on the rigid body model and optimized with
+that in mind. If this is violated you may get unexpected behavior.
 
 ## Creating a Dynamic Body
 I can use the same technique to create a
@@ -139,12 +139,12 @@ b2Polygon dynamicBox = b2MakeBox(1.0f, 1.0f);
 
 Next I create a shape definition for the box. Notice that I set
 density to 1. The default density is 1, so this is unnecessary. Also,
-the friction on the shape is set to 0.3.
+the friction on the surface material is set to 0.3.
 
 ```c
 b2ShapeDef shapeDef = b2DefaultShapeDef();
 shapeDef.density = 1.0f;
-shapeDef.friction = 0.3f;
+shapeDef.material.friction = 0.3f;
 ```
 
 > **Caution**:
@@ -204,10 +204,10 @@ simulation. For this example, I will use 4 sub-steps.
 int subStepCount = 4;
 ```
 
-Note that the time step and the sub-step count are related. As the time-step
+Note that the time step and the sub-step count are related. As the time step
 decreases, the size of the sub-steps also decreases. For example, at 60Hz
 time step and 4 sub-steps, the sub-steps operate at 240Hz. With 8 sub-steps
-the sub-step is 480Hz!
+the sub-step is 480Hz.
 
 We are now ready to begin the simulation loop. In your game the
 simulation loop can be merged with your game loop. In each pass through
@@ -231,6 +231,10 @@ for (int i = 0; i < 90; ++i)
 }
 ```
 
+Notice that the rotation of the body is returned in a `b2Rot` struct (short for rotation). This
+struct holds the rotation in a format that is fast for simulation. You may use `b2Rot_GetAngle`
+to get the rotation in radians.
+
 The output shows the box falling and landing on the ground box. Your
 output should look like this: