documentation and command queue extensions

.github/workflows/test.yml

@@ -0,0 +1,21 @@
+name: Test Swift Package
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: macos-latest
+
+    steps:
+    - uses: actions/checkout@v3
+    - uses: swift-actions/setup-swift@v2
+      with:
+        swift-version: '5.9'
+
+    - name: Build
+      run: swift build
+
+    - name: Run tests
+      run: swift test

.spi.yml

@@ -0,0 +1,7 @@
+version: 1
+builder:
+  configs:
+    - documentation_targets:
+      - MetalTools
+      - MetalComputeTools
+      - MetalRenderingTools

Package.swift

@@ -1,4 +1,4 @@
-// swift-tools-version:5.6
+// swift-tools-version:5.9
 
 import PackageDescription
 
@@ -25,8 +25,8 @@ let package = Package(
     ],
     dependencies: [
         .package(
-            url: "https://github.com/SwiftGFX/SwiftMath.git",
-            .upToNextMajor(from: "3.3.1")
+            url: "https://github.com/computer-graphics-tools/simd-tools.git",
+            .upToNextMinor(from: "0.0.1")
         )
     ],
     targets: [
@@ -40,10 +40,7 @@ let package = Package(
             dependencies: [
                 .target(name: "MetalComputeToolsSharedTypes"),
                 .target(name: "MetalTools"),
-                .product(
-                    name: "SwiftMath",
-                    package: "SwiftMath"
-                )
+                .product(name: "SIMDTools", package: "simd-tools")
             ],
             resources: [
                 .process("Kernels/BitonicSort/BitonicSort.metal"),

README.md

@@ -1,5 +1,12 @@
 # MetalTools
 
+[![Platform Compatibility](https://img.shields.io/badge/Platforms-iOS%20|%20macOS-brightgreen)](https://swift.org/platforms/)
+[![Swift Version](https://img.shields.io/badge/Swift-5.9-orange)](https://swift.org)
+
+<p align="left">
+    <img src="Sources/MetalTools/MetalTools.docc/Resources/table-of-contents-art/[email protected]", width="120">
+</p>
+
 ## Description
 
 MetalTools provides a convenient, Swifty way of working with Metal. This library is heavily used in computer vision startups [ZERO10](https://zero10.ar) and [Prisma](https://prisma-ai.com).

Sources/MetalComputeTools/Kernels/BitonicSort/BitonicSort.swift

@@ -1,14 +1,21 @@
 import MetalTools
 
+/// A class that implements the Bitonic Sort algorithm using Metal.
 final public class BitonicSort {
     // MARK: - Properties
 
     private let firstPass: FirstPass
     private let generalPass: GeneralPass
     private let finalPass: FinalPass
 
-    // MARK: - Init
+    // MARK: - Initialization
 
+    /// Initializes a new BitonicSort instance using a Metal context.
+    ///
+    /// - Parameters:
+    ///   - context: The Metal context to use.
+    ///   - scalarType: The scalar type of the data to be sorted.
+    /// - Throws: An error if initialization fails.
     public convenience init(
         context: MTLContext,
         scalarType: MTLPixelFormat.ScalarType
@@ -19,6 +26,12 @@ final public class BitonicSort {
         )
     }
 
+    /// Initializes a new BitonicSort instance using a Metal library.
+    ///
+    /// - Parameters:
+    ///   - library: The Metal library containing the required kernel functions.
+    ///   - scalarType: The scalar type of the data to be sorted.
+    /// - Throws: An error if initialization fails.
     public init(
         library: MTLLibrary,
         scalarType: MTLPixelFormat.ScalarType
@@ -37,20 +50,32 @@ final public class BitonicSort {
         )
     }
 
-    // MARK: - Encode
+    // MARK: - Encoding
 
+    /// Encodes the sorting operation into a command buffer.
+    ///
+    /// - Parameters:
+    ///   - data: The buffer containing the data to be sorted.
+    ///   - count: The number of elements to sort.
+    ///   - commandBuffer: The command buffer to encode into.
     public func callAsFunction(
         data: MTLBuffer,
         count: Int,
-        in commandeBuffer: MTLCommandBuffer
+        in commandBuffer: MTLCommandBuffer
     ) {
         self.encode(
             data: data,
             count: count,
-            in: commandeBuffer
+            in: commandBuffer
         )
     }
 
+    /// Encodes the sorting operation into a command buffer.
+    ///
+    /// - Parameters:
+    ///   - data: The buffer containing the data to be sorted.
+    ///   - count: The number of elements to sort.
+    ///   - commandBuffer: The command buffer to encode into.
     public func encode(
         data: MTLBuffer,
         count: Int,
@@ -117,6 +142,14 @@ final public class BitonicSort {
         )
     }
 
+    /// Creates a Metal buffer from an array of floating-point values, padding if necessary.
+    ///
+    /// - Parameters:
+    ///   - array: The array of floating-point values to create a buffer from.
+    ///   - device: The Metal device to create the buffer on.
+    ///   - options: Resource options for the buffer.
+    /// - Returns: A tuple containing the created buffer and the padded count.
+    /// - Throws: An error if buffer creation fails.
     public static func buffer<T: FloatingPoint>(
         from array: [T],
         device: MTLDevice,
@@ -130,6 +163,7 @@ final public class BitonicSort {
         )
     }
 
+    // Private helper method for buffer creation
     private static func buffer<T: Numeric>(
         from array: [T],
         paddingValue: T,

Sources/MetalComputeTools/Kernels/BitonicSort/BitonicSortFinalPass.swift

@@ -1,14 +1,24 @@
 import MetalTools
 
 extension BitonicSort {
+    /// Represents the final pass of the Bitonic Sort algorithm.
     final class FinalPass {
         // MARK: - Properties
 
+        /// The compute pipeline state for this pass.
         let pipelineState: MTLComputePipelineState
+
+        /// Indicates whether the device supports non-uniform threadgroups.
         private let deviceSupportsNonuniformThreadgroups: Bool
 
-        // MARK: - Init
+        // MARK: - Initialization
 
+        /// Initializes a new FinalPass instance using a Metal context.
+        ///
+        /// - Parameters:
+        ///   - context: The Metal context to use.
+        ///   - scalarType: The scalar type of the data to be sorted.
+        /// - Throws: An error if initialization fails.
         convenience init(
             context: MTLContext,
             scalarType: MTLPixelFormat.ScalarType
@@ -19,6 +29,12 @@ extension BitonicSort {
             )
         }
 
+        /// Initializes a new FinalPass instance using a Metal library.
+        ///
+        /// - Parameters:
+        ///   - library: The Metal library containing the required kernel functions.
+        ///   - scalarType: The scalar type of the data to be sorted.
+        /// - Throws: An error if initialization fails.
         init(
             library: MTLLibrary,
             scalarType: MTLPixelFormat.ScalarType
@@ -39,8 +55,17 @@ extension BitonicSort {
             )
         }
 
-        // MARK: - Encode
+        // MARK: - Encoding
 
+        /// Encodes the final pass of the sorting operation into a command buffer.
+        ///
+        /// - Parameters:
+        ///   - data: The buffer containing the data to be sorted.
+        ///   - elementStride: The stride between elements in the buffer.
+        ///   - params: Parameters for the sorting operation.
+        ///   - gridSize: The size of the compute grid.
+        ///   - unitSize: The size of each unit in the grid.
+        ///   - commandBuffer: The command buffer to encode into.
         func callAsFunction(
             data: MTLBuffer,
             elementStride: Int,
@@ -59,6 +84,15 @@ extension BitonicSort {
             )
         }
 
+        /// Encodes the final pass of the sorting operation using a compute command encoder.
+        ///
+        /// - Parameters:
+        ///   - data: The buffer containing the data to be sorted.
+        ///   - elementStride: The stride between elements in the buffer.
+        ///   - params: Parameters for the sorting operation.
+        ///   - gridSize: The size of the compute grid.
+        ///   - unitSize: The size of each unit in the grid.
+        ///   - encoder: The compute command encoder to use.
         func callAsFunction(
             data: MTLBuffer,
             elementStride: Int,
@@ -77,6 +111,15 @@ extension BitonicSort {
             )
         }
 
+        /// Encodes the final pass of the sorting operation into a command buffer.
+        ///
+        /// - Parameters:
+        ///   - data: The buffer containing the data to be sorted.
+        ///   - elementStride: The stride between elements in the buffer.
+        ///   - params: Parameters for the sorting operation.
+        ///   - gridSize: The size of the compute grid.
+        ///   - unitSize: The size of each unit in the grid.
+        ///   - commandBuffer: The command buffer to encode into.
         func encode(
             data: MTLBuffer,
             elementStride: Int,
@@ -98,6 +141,15 @@ extension BitonicSort {
             }
         }
 
+        /// Encodes the final pass of the sorting operation using a compute command encoder.
+        ///
+        /// - Parameters:
+        ///   - data: The buffer containing the data to be sorted.
+        ///   - elementStride: The stride between elements in the buffer.
+        ///   - params: Parameters for the sorting operation.
+        ///   - gridSize: The size of the compute grid.
+        ///   - unitSize: The size of each unit in the grid.
+        ///   - encoder: The compute command encoder to use.
         func encode(
             data: MTLBuffer,
             elementStride: Int,