Added ~AsSpan properties for arrays.

Author: thomasvt

Box2dNet/Box2dNet.csproj

@@ -14,7 +14,7 @@
 		<RepositoryUrl>https://github.com/thomasvt/Box2D3Net</RepositoryUrl>
 		<GenerateDocumentationFile>true</GenerateDocumentationFile>
 		<NoWarn>$(NoWarn);1591</NoWarn> <!-- suppress warnings for missing docs -->
-		<Version>3.1.4.0</Version>
+		<Version>3.1.5</Version>
 	</PropertyGroup>
 
 	<ItemGroup>

Box2dNet/IntPtrExtensions.cs

@@ -8,6 +8,7 @@ public static class IntPtrExtensions
         /// <summary>
         /// Gets a readonly span of a native array of which you know the length.
         /// </summary>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public static unsafe ReadOnlySpan<T> NativeArrayAsSpan<T>(this IntPtr intPtr, int count) where T : struct
         {
             return MemoryMarshal.CreateReadOnlySpan(ref Unsafe.AsRef<T>(intPtr.ToPointer()), count);

Box2dNet/Interop/B2Api.ArrayExtensions.cs

@@ -0,0 +1,63 @@
+using System.Numerics;
+
+namespace Box2dNet.Interop
+{
+    public partial struct b2ChainDef
+    {
+        /// <summary>
+        /// Allows to read the points directly from native memory as a span.
+        /// </summary>
+        public ReadOnlySpan<Vector2> pointsAsSpan => points.NativeArrayAsSpan<Vector2>(count);
+
+        /// <summary>
+        /// Allows to read the materials directly from native memory as a span.
+        /// </summary>
+        public ReadOnlySpan<b2SurfaceMaterial> materialsAsSpan => materials.NativeArrayAsSpan<b2SurfaceMaterial>(materialCount);
+    }
+
+    public partial struct b2SensorEvents
+    {
+        /// <summary>
+        /// Allows to read the beginEvents directly from native memory as a span.
+        /// </summary>
+        public ReadOnlySpan<b2SensorBeginTouchEvent> beginEventsAsSpan =>
+            beginEvents.NativeArrayAsSpan<b2SensorBeginTouchEvent>(beginCount);
+
+        /// <summary>
+        /// Allows to read the endEvents directly from native memory as a span.
+        /// </summary>
+        public ReadOnlySpan<b2SensorEndTouchEvent> endEventsAsSpan =>
+            endEvents.NativeArrayAsSpan<b2SensorEndTouchEvent>(endCount);
+
+    }
+
+    public partial struct b2ContactEvents
+    {
+        /// <summary>
+        /// Allows to read the beginEvents directly from native memory as a span.
+        /// </summary>
+        public ReadOnlySpan<b2ContactBeginTouchEvent> beginEventsAsSpan =>
+            beginEvents.NativeArrayAsSpan<b2ContactBeginTouchEvent>(beginCount);
+
+        /// <summary>
+        /// Allows to read the endEvents directly from native memory as a span.
+        /// </summary>
+        public ReadOnlySpan<b2ContactEndTouchEvent> endEventsAsSpan =>
+            endEvents.NativeArrayAsSpan<b2ContactEndTouchEvent>(endCount);
+
+        /// <summary>
+        /// Allows to read the hitEvents directly from native memory as a span.
+        /// </summary>
+        public ReadOnlySpan<b2ContactHitEvent> hitEventsAsSpan =>
+            hitEvents.NativeArrayAsSpan<b2ContactHitEvent>(hitCount);
+    }
+
+    public partial struct b2BodyEvents
+    {
+        /// <summary>
+        /// Allows to read the moveEvents directly from native memory as a span.
+        /// </summary>
+        public ReadOnlySpan<b2BodyMoveEvent> moveEventsAsSpan =>
+            moveEvents.NativeArrayAsSpan<b2BodyMoveEvent>(moveCount);
+    }
+}

README.md

@@ -45,62 +45,55 @@ I am using Box2dNet for my own game so you can expect me to add more convenience
 * the timer functions (b2CreateTimer, ..): use .NET timers :)
 * b2DynamicTree_X: little value for much effort on my side. This is the spatial tree used internally by Box2D. Erin exposed these because people may want to use the tree elsewhere, but you don't need these functions for normal Box2D use.
 
-# Dealing with pointers (IntPtr)
+# Multi-threading support
 
-The largest down-side of PInvoke wrappers is that many C pointers become `IntPtr` in .NET. Because of this, the type that was there in C of the `struct` or `delegate` is lost and replaced by `IntPtr` in C#. 
+Box2dNet comes with .NET integration for the new multi-threaded task system that Box2D uses. 
 
-To help with this, Box2dNet mentions the original C type in the C# generated comments wherever possible. Code completion should therefore show this information. Worst case, you'll have to look in the sources here on gitHub.
+Simply use `B2Api.b2DefaultWorldDef_WithDotNetTpl()` instead of `B2Api.b2DefaultWorldDef` to create your Box2D world:
 
-To help you with IntPtrs, the following sections show solutions for most use cases:
+``` C#
+var worldDef = useMultiThreading
+    ? B2Api.b2DefaultWorldDef_WithDotNetTpl() // <---- this is all it takes for default multi threading
+    : B2Api.b2DefaultWorldDef();
 
-## Callbacks: setting struct.fields that are callback delegates.
+var b2WorldId = B2Api.b2CreateWorld(worldDef);
+```
 
-> As of Box2dNet v3.1.5 all Box2D functions that have callback delegates parameters have a companion overload that takes in the strongly typed delegate. eg. use `b2World_SetPreSolveCallback(b2WorldId worldId, **b2PreSolveFcn fcn**, IntPtr context)`, not `b2World_SetPreSolveCallback(b2WorldId worldId, **IntPtr fcn**, IntPtr context)`
+Note that multithreading incurs quite some overhead so you only gain net-profit when you simulate a lot of bodies. Measure your specific use cases!
 
-Some Box2D struct fields are delegate pointers. These are `IntPtr` and must be set to a pointer to a method with the same definition as the delegate requires.
+> the 'TPL' in `b2DefaultWorldDef_WithDotNetTpl` stands for Task Parallel Library, which is the name of .NET's Task framework.
 
-To do this, you must:
+# Dealing with pointers (IntPtr)
 
-* check the generated comments to find the identifier of the original C delegate type
-* write or generate a method that matches the delegate
-* assign a function pointer retrieved with `Marshal.GetFunctionPointerForDelegate` to the IntPtr struct field.
+The largest down-side of PInvoke wrappers is that many C pointers become `IntPtr` in .NET. Because of this, the type that was there in C of the `struct` or `delegate` is lost and replaced by `IntPtr` in C#. 
 
-Here is an example:
+To help with this, Box2dNet has several helpers to deal with IntPtr, or to remove the need to deal with them at all.
 
-``` C#
-    ...
-    var worldDef = b2DefaultWorldDef();
-    worldDef.enqueueTask = Marshal.GetFunctionPointerForDelegate((b2EnqueueTaskCallback)EnqueueTaskCallback);
-}
+Several situations remain, though, where you need to do it yourself. The following sections show solutions for most of these cases.
 
-private static IntPtr EnqueueTaskCallback(IntPtr /* b2TaskCallback */ task, int itemCount, int minRange, IntPtr taskContext, IntPtr userContext)
-{
-    ...
-}
-```
+The original C type of the pointer is in the generated comments. Code completion should show this information. Worst case, you'll have to look in the sources here on gitHub.
 
 ## Reading native arrays from IntPtr (without copying)
 
-Some structs received from native Box2D contain arrays. To read those arrays Box2dNet provides convenience method `NativeArrayAsSpan` to loop over the native contents without making temporary copies or allocating an iterator.
+Some structs received from native Box2D contain IntPtrs to arrays. Box2dNet provides companion properties called `~AsSpan` for these with which you can read the data directly from native memory, strongly typed (so no allocations for copies or iterators). 
 
-Example: field `IntPtr b2ContactEvents.beginEvents` shows in its comment that you should read it as an array of `b2ContactBeginTouchEvent`:
+> If this companion property is not there, you can convert the IntPtr yourself to a Span using Box2dNet's convenience method `NativeArrayAsSpan(count)` which is simply what the `~AsSpan` does behind the scenes.
+
+Example: struct `b2ContactEvents` contains an array in field `IntPtr beginEvents` which you can read easily using companion `beginEventsAsSpan`:
 
 ``` C#
 var hitEvents = B2Api.b2World_GetContactEvents(b2WorldId);
-// use helper extension method to efficiently read the native hitEvents array with little code:
-foreach (var @event in hitEvents.beginEvents.NativeArrayAsSpan<b2ContactBeginTouchEvent>(hitEvents.beginCount))
+foreach (var @event in **hitEvents.beginEventsAsSpan**)
 {
     Console.WriteLine($"!!!!!!!   HIT detected between {@event.shapeIdA} and {@event.shapeIdB}");
 }
 ```
 
-> Note that you must know the size of the array, which is always provided by Box2D in a sibling field.
-
 ## Pass a reference to a .NET object into native Box2D as IntPtr (eg. UserData)
 
-If you want to pass a .NET object reference into native Box2D, like when tagging a Shape or Body with `userData`, you must pass in an `IntPtr` to the object. But in .NET objects can get relocated by the memory manager.
+If you want to pass a .NET object reference into native Box2D, like when tagging a Shape or Body with `userData`, you must pass in an `IntPtr` to the object. But .NET objects are not guaranteed to stay at the same address in memory.
 
-To solution is to allocate a `NativeHandle` for your .NET object and pass the handle's `IntPtr` to Box2D instead of a direct pointer to the instance. Example:
+The solution is to allocate a `NativeHandle` for your .NET object and pass *that* to Box2D. Example:
 
 ``` C#
 _handle = NativeHandle.Alloc(ball); // allocate a IntPtr handle for the .NET object and return it as IntPtr.
@@ -112,7 +105,7 @@ var circle = new b2Circle() { radius = 1 };
 var b2ShapeId = B2Api.b2CreateCircleShape(b2BodyId, in shapeDef, in circle);
 ```
 
-After this, when Box2D passes the `IntPtr` back to .NET somewhere, for instance when you call `b2X_GetUserData()`, you can get hold of the corresponding .NET object like this:
+After this, when Box2D passes the `IntPtr` back to .NET somewhere (eg. through `b2X_GetUserData()`) you can get hold of the corresponding .NET object like this:
 
 ``` C#
 var userDataIntPtr = B2Api.b2Shape_GetUserData(shapeId);
@@ -126,25 +119,33 @@ When you're fully done with it, eg. when the game object is removed from your ga
 NativeHandle.Free(_handle);
 ```
 
-> A tip to avoid NativeHandle with UserData: abuse the UserData poointer by setting it to your gameobject's numerical ID (a normal int or long). IntPtr is just a numerical value, it doesn't have to be an actual pointer address: `new IntPtr(entity.Id)` works just fine.
+> A tip to avoid needing to use NativeHandle with UserData: abuse the UserData pointer by setting it to your gameobject's numerical ID (a normal int or long). IntPtr is just a numerical value, it doesn't have to be an actual pointer address: `new IntPtr(entity.Id)` works just fine.
 
-# Multi-threading support
+## Callbacks: setting struct.fields that are callback delegates.
 
-Box2dNet comes with .NET integration for the new multi-threaded task system that Box2D uses. 
+> As of Box2dNet v3.1.5 all Box2D functions that have callback delegates parameters have a companion overload that takes in the strongly typed delegate. eg. use `b2World_SetPreSolveCallback(b2WorldId worldId, **b2PreSolveFcn fcn**, IntPtr context)`, not `b2World_SetPreSolveCallback(b2WorldId worldId, **IntPtr fcn**, IntPtr context)`
 
-Simply use `B2Api.b2DefaultWorldDef_WithDotNetTpl()` instead of `B2Api.b2DefaultWorldDef` to create your Box2D world:
+Some Box2D struct fields are delegate pointers. These are `IntPtr` and must be set to a pointer to a method with the same definition as the delegate requires.
 
-``` C#
-var worldDef = useMultiThreading
-    ? B2Api.b2DefaultWorldDef_WithDotNetTpl() // <---- this is all it takes for default multi threading
-    : B2Api.b2DefaultWorldDef();
+To do this, you must:
 
-var b2WorldId = B2Api.b2CreateWorld(worldDef);
-```
+* check the generated comments to find the identifier of the original C delegate type
+* write or generate a method that matches the delegate
+* assign a function pointer retrieved with `Marshal.GetFunctionPointerForDelegate` to the IntPtr struct field.
 
-Note that multithreading incurs quite some overhead so you only gain net-profit when you simulate a lot of bodies. Measure your specific use cases!
+Here is an example:
 
-> the 'TPL' in `b2DefaultWorldDef_WithDotNetTpl` stands for Task Parallel Library, which is the name of .NET's Task framework.
+``` C#
+    ...
+    var worldDef = b2DefaultWorldDef();
+    worldDef.enqueueTask = Marshal.GetFunctionPointerForDelegate((b2EnqueueTaskCallback)EnqueueTaskCallback);
+}
+
+private static IntPtr EnqueueTaskCallback(IntPtr /* b2TaskCallback */ task, int itemCount, int minRange, IntPtr taskContext, IntPtr userContext)
+{
+    ...
+}
+```
 
 # Samples