Prepare for 2.4.1 release (#657)

- Updated change log and docs

CHANGELOG.md

@@ -1,3 +1,21 @@
+# Changes for version 2.4.1
+
+## API Changes
+- Extended distance joint to have a minimum and maximum limit.
+- Removed rope joint. Use the distance joint instead.
+- B2_USER_SETTINGS and b2_user_settings.h can control user data, length units, and maximum polygon vertices.
+- Default user data is now uintptr_t instead of void*
+- b2FixtureDef::restitutionThreshold lets you set the restitution velocity threshold per fixture.
+
+## BREAKING Changes
+- BREAKING: distance joint 0 stiffness now means the spring is turned off rather than making the joint rigid.
+- BREAKING: distance joint minimum and maximum must be set correctly to get old behavior.
+
+## Infrastructure
+- Library installation function available in CMake.
+- Shared library (DLL) option available.
+- Bug fixes
+
 # Changes for version 2.4.0
 
 ## Infrastructure

CMakeLists.txt

@@ -1,7 +1,7 @@
 cmake_minimum_required(VERSION 3.8)
 
 # https://cmake.org/cmake/help/latest/command/project.html
-project(box2d VERSION 2.4.0)
+project(box2d VERSION 2.4.1)
 
 # set(CMAKE_CONFIGURATION_TYPES "Debug;RelWithDebInfo" CACHE STRING "" FORCE)
 

docs/dynamics.md

@@ -248,7 +248,7 @@ object type for all body user data.
 
 ```cpp
 b2BodyDef bodyDef;
-bodyDef.userData = &myActor;
+bodyDef.userData.pointer = reinterpret_cast<uintptr_t>(&myActor);
 ```
 
 ### Body Factory
@@ -779,6 +779,9 @@ float dampingRatio = 0.5f;
 b2LinearStiffness(jointDef.stiffness, jointDef.damping, frequencyHz, dampingRatio, jointDef.bodyA, jointDef.bodyB);
 ```
 
+It is also possible to define a minimum and maximum length for the distance joint.
+See `b2DistanceJointDef` for details.
+
 ### Revolute Joint
 A revolute joint forces two bodies to share a common anchor point, often
 called a hinge point. The revolute joint has a single degree of freedom:
@@ -1183,7 +1186,7 @@ bodies.
 ```cpp
 b2Fixture* fixtureA = myContact->GetFixtureA();
 b2Body* bodyA = fixtureA->GetBody();
-MyActor* actorA = (MyActor*)bodyA->GetUserData();
+MyActor* actorA = (MyActor*)bodyA->GetUserData().pointer;
 ```
 
 You can disable a contact. This only works inside the
@@ -1520,7 +1523,7 @@ following code is broken:
 ```cpp
 for (b2Body* b = myWorld->GetBodyList(); b; b = b->GetNext())
 {
-    GameActor* myActor = (GameActor*)b->GetUserData();
+    GameActor* myActor = (GameActor*)b->GetUserData().pointer;
     if (myActor->IsDead())
     {
         myWorld->DestroyBody(b); // ERROR: now GetNext returns garbage.
@@ -1540,7 +1543,7 @@ while (node)
     b2Body* b = node;
     node = node->GetNext();
 
-    GameActor* myActor = (GameActor*)b->GetUserData();
+    GameActor* myActor = (GameActor*)b->GetUserData().pointer;
     if (myActor->IsDead())
     {
         myWorld->DestroyBody(b);
@@ -1560,7 +1563,7 @@ while (node)
     b2Body* b = node;
     node = node->GetNext();
 
-    GameActor* myActor = (GameActor*)b->GetUserData();
+    GameActor* myActor = (GameActor*)b->GetUserData().pointer;
     if (myActor->IsDead())
     {
         bool otherBodiesDestroyed = GameCrazyBodyDestroyer(b);

docs/loose_ends.md

@@ -2,7 +2,7 @@
 
 ## User Data
 The `b2Fixture`, `b2Body`, and `b2Joint` classes allow you to attach user data
-as a void pointer. This is handy when you are examining Box2D data
+as a uintptr_t. This is handy when you are examining Box2D data
 structures and you want to determine how they relate to the objects in
 your game engine.
 
@@ -13,10 +13,12 @@ you can get the body. If you have the body, you can get the actor.
 ```cpp
 GameActor* actor = GameCreateActor();
 b2BodyDef bodyDef;
-bodyDef.userData = actor;
+bodyDef.userData.pointer = reinterpret_cast<uintptr_t>(actor);
 actor->body = myWorld->CreateBody(&bodyDef);
 ```
 
+You can also use this to hold an integral value rather than a pointer.
+
 Here are some examples of cases where you would need the user data:
 -   Applying damage to an actor using a collision result.
 -   Playing a scripted event if the player is inside an axis-aligned box.
@@ -30,7 +32,7 @@ bodies. Don't store an actor pointer on one body, and a foo pointer on
 another body. Casting an actor pointer to a foo pointer may lead to a
 crash.
 
-User data pointers are null by default.
+User data pointers are 0 by default.
 
 For fixtures you might consider defining a user data structure that lets
 you store game specific information, such as material type, effects
@@ -48,7 +50,7 @@ myData->materialIndex = 2;
 
 b2FixtureDef fixtureDef;
 fixtureDef.shape = &someShape;
-fixtureDef.userData = myData;
+fixtureDef.userData.pointer = reinterpret_cast<uintptr_t>(myData);
 
 b2Fixture* fixture = body->CreateFixture(&fixtureDef);
 // ...
@@ -57,6 +59,11 @@ delete fixture->GetUserData();
 body->DestroyFixture(fixture);
 ```
 
+## Custom User Data
+You can define custom data structures that are embedded in the Box2D data
+structures. This is done by defining `B2_USER_SETTINGS` and providing the
+file `b2_user_settings.h`. See `b2_settings.h` for details.
+
 ## Implicit Destruction
 Box2D doesn't use reference counting. So if you destroy a body it is
 really gone. Accessing a pointer to a destroyed body has undefined

docs/overview.md

@@ -161,11 +161,16 @@ need to store a physics offset when translating between game units and Box2D uni
 
 Box2D uses radians for angles. The body rotation is stored in radians
 and may grow unbounded. Consider normalizing the angle of your bodies if
-the magnitude of the angle becomes too large (use b2Body::SetAngle).
+the magnitude of the angle becomes too large (use `b2Body::SetTransform`).
 
 > **Caution**:
 > Box2D uses radians, not degrees.
 
+## Changing the length units
+Advanced users may change the length unit modifying `b2_lengthUnitsPerMeter`.
+You can avoid merge conflicts by defining `B2_USER_SETTINGS` and providing
+`b2_user_settings.h`. See the file `b2_settings.h` for details.
+
 ## Factories and Definitions
 Fast memory management plays a central role in the design of the Box2D
 API. So when you create a b2Body or a b2Joint, you need to call the