update comments

Author: ikpil

src/Box2D.NET/B2AABBs.cs

@@ -52,7 +52,6 @@ public static bool b2EnlargeAABB(ref B2AABB a, in B2AABB b)
 
 
         // Ray cast an AABB
-        // From Real-time Collision Detection, p179.
         public static B2CastOutput b2AABB_RayCast(in B2AABB a, in B2Vec2 p1, in B2Vec2 p2)
         {
             // Radius not handled
@@ -169,4 +168,4 @@ public static B2CastOutput b2AABB_RayCast(in B2AABB a, in B2Vec2 p1, in B2Vec2 p
             return output;
         }
     }
-}
+}

src/Box2D.NET/B2ArenaAllocator.cs

@@ -6,6 +6,11 @@
 
 namespace Box2D.NET
 {
+    // This is a stack-like arena allocator used for fast per step allocations.
+    // You must nest allocate/free pairs. The code will B2_ASSERT
+    // if you try to interleave multiple allocate/free pairs.
+    // This allocator uses the heap if space is insufficient.
+    // I could remove the need to free entries individually.
     public class B2ArenaAllocator
     {
         private readonly object _lock;
@@ -75,4 +80,4 @@ public Span<IB2ArenaAllocatable> AsSpan()
             return new Span<IB2ArenaAllocatable>(_allocators);
         }
     }
-}
+}

src/Box2D.NET/B2ArenaAllocators.cs

@@ -94,7 +94,7 @@ public static void b2DestroyArenaAllocator(B2ArenaAllocator allocator)
             alloc.allocation -= entry.size;
             b2Array_Pop(ref alloc.entries);
         }
-
+        // Grow the arena based on usage
         public static void b2GrowArena(B2ArenaAllocator allocator)
         {
             var allocSpan = allocator.AsSpan();
@@ -143,4 +143,4 @@ public static int b2GetMaxArenaAllocation(B2ArenaAllocator allocator)
             return maxAllocation;
         }
     }
-}
+}

src/Box2D.NET/B2Bodies.cs

@@ -30,7 +30,31 @@ namespace Box2D.NET
     // according to substep progress. Contacts have reduced stability when anchors are rotated during substeps, especially for
     // round shapes.
 
-    // 32 bytes
+    // Body State
+    // The body state is designed for fast conversion to and from SIMD via scatter-gather.
+    // Only awake dynamic and kinematic bodies have a body state.
+    // This is used in the performance critical constraint solver
+    //
+    // The solver operates on the body state. The body state array does not hold static bodies. Static bodies are shared
+    // across worker threads. It would be okay to read their states, but writing to them would cause cache thrashing across
+    // workers, even if the values don't change.
+    // This causes some trouble when computing anchors. I rotate joint anchors using the body rotation every sub-step. For static
+    // bodies the anchor doesn't rotate. Body A or B could be static and this can lead to lots of branching. This branching
+    // should be minimized.
+    //
+    // Solution 1:
+    // Use delta rotations. This means anchors need to be prepared in world space. The delta rotation for static bodies will be
+    // identity using a dummy state. Base separation and angles need to be computed. Manifolds will be behind a frame, but that
+    // is probably best if bodies move fast.
+    //
+    // Solution 2:
+    // Use full rotation. The anchors for static bodies will be in world space while the anchors for dynamic bodies will be in local
+    // space. Potentially confusing and bug prone.
+    //
+    // Note:
+    // I rotate joint anchors each sub-step but not contact anchors. Joint stability improves a lot by rotating joint anchors
+    // according to substep progress. Contacts have reduced stability when anchors are rotated during substeps, especially for
+    // round shapes.
     public class B2BodyState
     {
         public B2Vec2 linearVelocity; // 8
@@ -75,4 +99,4 @@ public void CopyFrom(B2BodyState other)
             deltaRotation = other.deltaRotation;
         }
     }
-}
+}

src/Box2D.NET/B2BodyState.cs

@@ -25,7 +25,6 @@ public class B2BroadPhase
         // These are the results from the pair query and are used to create new contacts
         // in deterministic order. There is a move result linked list for each moving shape and
         // these follow the dynamic tree query order for determinism.
-        // todo these could be in the step context
         public ArraySegment<B2MoveResult> moveResults;
         public ArraySegment<B2MovePair> movePairs;
         public int movePairCapacity;

src/Box2D.NET/B2BroadPhase.cs

@@ -65,8 +65,7 @@ public static void b2BufferMove(B2BroadPhase bp, int queryProxy)
         }
 
 
-        // 
-        // static FILE* s_file = NULL;
+        // #include <stdio.h>
         public static void b2CreateBroadPhase(ref B2BroadPhase bp)
         {
             B2_ASSERT((int)B2BodyType.b2_bodyTypeCount == 3, "must be three body types");

src/Box2D.NET/B2BroadPhases.cs

@@ -8,7 +8,7 @@ namespace Box2D.NET
 {
     public static class B2CTZs
     {
-        // uint에 대해 trailing zero count (CTZ)
+        // https://en.wikipedia.org/wiki/Find_first_set
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public static uint b2CTZ32(uint block)
         {
@@ -23,7 +23,7 @@ public static uint b2CTZ32(uint block)
             return count;
         }
 
-        // uint에 대해 leading zero count (CLZ)
+        // This function doesn't need to be fast, so using the Ivy Bridge fallback.
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public static uint b2CLZ32(uint value)
         {
@@ -95,4 +95,4 @@ public static int b2RoundUpPowerOf2(int x)
             return 1 << (32 - (int)b2CLZ32((uint)x - 1));
         }
     }
-}
+}

src/Box2D.NET/B2CTZs.cs

@@ -18,7 +18,7 @@ namespace Box2D.NET
     /// https://en.wikipedia.org/wiki/Polygonal_chain
     /// Must be initialized using b2DefaultChainDef().
     /// @warning Do not use chain shapes unless you understand the limitations. This is an advanced feature.
-    /// @ingroup shape    
+    /// @ingroup shape
     public struct B2ChainDef
     {
         /// Use this to store application specific shape data.

src/Box2D.NET/B2ChainDef.cs

@@ -11,7 +11,7 @@ public struct B2CollisionPlane
         /// The collision plane between the mover and some shape
         public B2Plane plane;
 
-        /// Setting this to float.MaxValue makes the plane as rigid as possible. Lower values can
+        /// Setting this to FLT_MAX makes the plane as rigid as possible. Lower values can
         /// make the plane collision soft. Usually in meters.
         public float pushLimit;