Add joint images

Author: Josef-Friedrich

jbox2d-library/src/main/java/de/pirckheimer_gymnasium/jbox2d/dynamics/World.java

@@ -1041,23 +1041,23 @@ public int getContactCount()
     }
 
     /**
-     * Gets the height of the dynamic tree
+     * Get the height of the dynamic tree.
      */
     public int getTreeHeight()
     {
         return contactManager.broadPhase.getTreeHeight();
     }
 
     /**
-     * Gets the balance of the dynamic tree
+     * Get the balance of the dynamic tree.
      */
     public int getTreeBalance()
     {
         return contactManager.broadPhase.getTreeBalance();
     }
 
     /**
-     * Gets the quality of the dynamic tree
+     * Get the quality of the dynamic tree.
      */
     public float getTreeQuality()
     {

jbox2d-library/src/main/java/de/pirckheimer_gymnasium/jbox2d/dynamics/joints/DistanceJoint.java

@@ -21,28 +21,6 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
-/*
- * JBox2D - A Java Port of Erin Catto's Box2D
- *
- * JBox2D homepage: http://jbox2d.sourceforge.net/
- * Box2D homepage: http://www.box2d.org
- *
- * This software is provided 'as-is', without any express or implied
- * warranty.  In no event will the authors be held liable for any damages
- * arising from the use of this software.
- *
- * Permission is granted to anyone to use this software for any purpose,
- * including commercial applications, and to alter it and redistribute it
- * freely, subject to the following restrictions:
- *
- * 1. The origin of this software must not be misrepresented; you must not
- * claim that you wrote the original software. If you use this software
- * in a product, an acknowledgment in the product documentation would be
- * appreciated but is not required.
- * 2. Altered source versions must be plainly marked as such, and must not be
- * misrepresented as being the original software.
- * 3. This notice may not be removed or altered from any source distribution.
- */
 package de.pirckheimer_gymnasium.jbox2d.dynamics.joints;
 
 import de.pirckheimer_gymnasium.jbox2d.common.MathUtils;
@@ -62,19 +40,73 @@
  * A distance joint constrains two points on two bodies to remain at a fixed
  * distance from each other. You can view this as a massless, rigid rod.
  *
+ * <p>
+ * One of the simplest joint is a distance joint which says that the distance
+ * between two points on two bodies must be constant. When you specify a
+ * distance joint the two bodies should already be in place. Then you specify
+ * the two anchor points in world coordinates. The first anchor point is
+ * connected to body 1, and the second anchor point is connected to body 2.
+ * These points imply the length of the distance constraint.
+ * </p>
+ *
+ * <p>
+ * Here is an example of a distance joint definition. In this case we decide to
+ * allow the bodies to collide.
+ * </p>
+ *
+ * <p>
+ * The distance joint can also be made soft, like a spring-damper connection.
+ * </p>
+ *
+ * <p>
+ * Softness is achieved by tuning two constants in the definition: stiffness and
+ * damping. It can be non-intuitive setting these values directly since they
+ * have units in terms on Newtons.
+ * </p>
+ *
+ * <p>
+ * Think of the frequency as the frequency of a harmonic oscillator (like a
+ * guitar string). The frequency is specified in Hertz. Typically the frequency
+ * should be less than a half the frequency of the time step. So if you are
+ * using a 60Hz time step, the frequency of the distance joint should be less
+ * than 30Hz. The reason is related to the Nyquist frequency.
+ * </p>
+ *
+ * <p>
+ * The damping ratio is non-dimensional and is typically between 0 and 1, but
+ * can be larger. At 1, the damping is critical (all oscillations should
+ * vanish).
+ * </p>
+ *
+ * <p>
+ * It is also possible to define a minimum and maximum length for the distance
+ * joint.
+ * </p>
+ *
  * @author Daniel Murphy
  */
 public class DistanceJoint extends Joint
 {
+    /**
+     * The mass-spring-damper frequency in Hertz.
+     */
     private float frequencyHz;
 
+    /**
+     * The damping ratio. 0 = no damping, 1 = critical damping.
+     */
     private float dampingRatio;
 
     private float bias;
 
-    // Solver shared
+    /**
+     * The local anchor point relative to body1's origin.
+     */
     private final Vec2 localAnchorA;
 
+    /**
+     * The local anchor point relative to body2's origin.
+     */
     private final Vec2 localAnchorB;
 
     private float gamma;
@@ -278,9 +310,9 @@ public void initVelocityConstraints(final SolverData data)
         {
             impulse = 0.0f;
         }
-//    data.velocities[indexA].v.set(vA);
+        // data.velocities[indexA].v.set(vA);
         data.velocities[indexA].w = wA;
-//    data.velocities[indexB].v.set(vB);
+        // data.velocities[indexB].v.set(vB);
         data.velocities[indexB].w = wB;
     }
 
@@ -309,9 +341,9 @@ public void solveVelocityConstraints(final SolverData data)
         vB.x += invMassB * Px;
         vB.y += invMassB * Py;
         wB += invIB * (rB.x * Py - rB.y * Px);
-//    data.velocities[indexA].v.set(vA);
+        // data.velocities[indexA].v.set(vA);
         data.velocities[indexA].w = wA;
-//    data.velocities[indexB].v.set(vB);
+        // data.velocities[indexB].v.set(vB);
         data.velocities[indexB].w = wB;
         pool.pushVec2(2);
     }
@@ -350,9 +382,9 @@ public boolean solvePositionConstraints(final SolverData data)
         cB.x += invMassB * Px;
         cB.y += invMassB * Py;
         aB += invIB * (rB.x * Py - rB.y * Px);
-//    data.positions[indexA].c.set(cA);
+        // data.positions[indexA].c.set(cA);
         data.positions[indexA].a = aA;
-//    data.positions[indexB].c.set(cB);
+        // data.positions[indexB].c.set(cB);
         data.positions[indexB].a = aB;
         pool.pushVec2(3);
         pool.pushRot(2);

jbox2d-library/src/main/java/de/pirckheimer_gymnasium/jbox2d/dynamics/joints/Joint.java

@@ -33,6 +33,23 @@
  * The base joint class. Joints are used to constrain two bodies together in
  * various fashions. Some joints also feature limits and motors.
  *
+ * <p>Joints are used to constrain bodies to the world or to each other. Typical
+ * examples in games include ragdolls, teeters, and pulleys. Joints can be
+ * combined in many different ways to create interesting motions.</p>
+ *
+ * <p>Some joints provide limits so you can control the range of motion. Some joint
+ * provide motors which can be used to drive the joint at a prescribed speed
+ * until a prescribed force/torque is exceeded.</p>
+ *
+ * <p>Joint motors can be used in many ways. You can use motors to control position
+ * by specifying a joint velocity that is proportional to the difference between
+ * the actual and desired position. You can also use motors to simulate joint
+ * friction: set the joint velocity to zero and provide a small, but significant
+ * maximum motor force/torque. Then the motor will attempt to keep the joint
+ * from moving until the load becomes too strong.</p>
+ *
+ * https://box2d.org/documentation/md__d_1__git_hub_box2d_docs_dynamics.html#autotoc_md81
+ *
  * @author Daniel Murphy
  */
 public abstract class Joint

jbox2d-library/src/main/java/de/pirckheimer_gymnasium/jbox2d/dynamics/joints/JointDef.java

@@ -28,6 +28,46 @@
 /**
  * Joint definitions are used to construct joints.
  *
+ * <p>
+ * Each joint type has a definition that derives from {@link JointDef}. All
+ * joints are connected between two different bodies. One body may static.
+ * Joints between static and/or kinematic bodies are allowed, but have no effect
+ * and use some processing time.
+ * </p>
+ *
+ * <p>
+ * You can specify user data for any joint type and you can provide a flag to
+ * prevent the attached bodies from colliding with each other. This is actually
+ * the default behavior and you must set the
+ * {@link JointDef#collideConnectedcollideConnected} Boolean to allow collision
+ * between to connected bodies.
+ * </p>
+ *
+ * <p>
+ * Many joint definitions require that you provide some geometric data. Often a
+ * joint will be defined by anchor points. These are points fixed in the
+ * attached bodies. jbox2d requires these points to be specified in local
+ * coordinates. This way the joint can be specified even when the current body
+ * transforms violate the joint constraint - a common occurrence when a game
+ * is saved and reloaded. Additionally, some joint definitions need to know the
+ * default relative angle between the bodies. This is necessary to constrain
+ * rotation correctly.
+ * </p>
+ *
+ * <p>
+ * Initializing the geometric data can be tedious, so many joints have
+ * initialization functions that use the current body transforms to remove much
+ * of the work. However, these initialization functions should usually only be
+ * used for prototyping. Production code should define the geometry directly.
+ * This will make joint behavior more robust.
+ * </p>
+ *
+ * <p>
+ * The rest of the joint definition data depends on the joint type.
+ * </p>
+ *
+ * https://box2d.org/documentation/md__d_1__git_hub_box2d_docs_dynamics.html#autotoc_md82
+ *
  * @author Daniel Murphy
  */
 public class JointDef

misc/images/joints/README.md

@@ -0,0 +1,9 @@
+https://box2d.org/documentation_v3/distance_joint.svg
+https://box2d.org/documentation_v3/prismatic_joint.svg
+https://box2d.org/documentation_v3/revolute_joint.svg
+https://box2d.org/documentation_v3/wheel_joint.svg
+https://box2d.org/documentation/distance_joint.gif
+https://box2d.org/documentation/gear_joint.gif
+https://box2d.org/documentation/prismatic_joint.gif
+https://box2d.org/documentation/pulley_joint.gif
+https://box2d.org/documentation/revolute_joint.gif