Skip to content
Projects

schwa/MetalSprockets

View on GitHub

schwa/MetalSprockets has 58 GitHub stars and 1 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-16 20:59 UTC. Last push 2026-11-12.

How these counts are measured

Measured star growth

in 24h
0
in 7 days
Collecting history
in 15 days
Collecting history
in 1 month
Collecting history

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

A declarative, SwiftUI-style framework for Metal render and compute passes.

Creative & Media

README.md

Original

MetalSprockets MetalSprockets

"It's like SwiftUI — but for Metal."

A declarative, composable layer for Metal in Swift.

Documentation


Why MetalSprockets?

Even a simple Metal render pass needs descriptors, pipeline state, and encoder setup. Mixed render and compute passes need more setup.

MetalSprockets applies SwiftUI's result builders, composable trees, and property wrappers to Metal. You build GPU workloads as a tree of Elements. Shader parameters bind by name instead of buffer index. One graph can combine render, compute, mesh, and object shaders.

MetalSprockets supports SwiftUI (RenderView), ARKit, visionOS immersive spaces, and offscreen rendering.


Requirements

  • macOS 26, iOS 26, or visionOS 26 or later
  • Swift 6.2+ and Xcode 26.6+ (CI uses Xcode 26.6; developed with Xcode 27)
  • Apple GPUs only: Intel Macs are not supported.
  • No Simulator: the iOS and visionOS Simulator SDKs have no Metal 4 APIs, so MetalSprockets does not build for the Simulator. Use a device or a Mac.

Installation

Add the dependency to your Package.swift:

let package = Package(
    dependencies: [
        .package(url: "https://github.com/schwa/MetalSprockets", from: "0.1.0")
    ],
    targets: [
        .target(
            name: "MyApp",
            dependencies: [
                .product(name: "MetalSprockets", package: "MetalSprockets"),
                // Optional: for RenderView and visionOS support
                .product(name: "MetalSprocketsUI", package: "MetalSprockets")
            ]
        )
    ]
)

Alternatively, select File ▸ Add Packages… in Xcode. Then paste the repository URL.


Companion repositories


Core concepts

Element is the MetalSprockets equivalent of View. Each element declares a var body: some Element and composes other elements into a tree.

Unlike View.body, Element.body supports throwing getters. For a throwing body, use get throws { }. If the body does not throw, return directly.

struct MyRenderPass: Element {
    var body: some Element {
        get throws {
            try RenderPass {
                try MyPipeline()
            }
        }
    }
}

body uses the @ElementBuilder result builder. It supports if/else and optional chaining. ForEach, Group, and many other combinators work like their SwiftUI counterparts.

The built-in elements map to Metal's structure:

Element Metal equivalent
RenderPass Render command encoder
RenderPipeline Render pipeline state
ComputePass Compute command encoder
ComputePipeline Compute pipeline state
Draw Draw calls on the encoder

State management mirrors SwiftUI's property wrappers, prefixed with MS to avoid collisions:

MetalSprockets SwiftUI equivalent
@MSState @State
@MSBinding @Binding
@MSEnvironment @Environment

Example

A SwiftUI view that runs a compute pass to update particles, then renders a skybox and the particles in a single render pass:

import SwiftUI
import MetalSprockets
import MetalSprocketsUI

struct ContentView: View {
    let library = try! ShaderLibrary(bundle: .main)
    let particleBuffer: MTLBuffer = // ...
    let skyboxMesh: MTKMesh = // ...
    let particleCount = 10_000

    var body: some View {
        RenderView { context, drawableSize in
            let viewProjectionMatrix = // ...

            // Compute pass: update particles on the GPU
            try ComputePass {
                try ComputePipeline(kernel: library.updateParticles) {
                    Dispatch.threads(particleCount, threadsPerThreadgroup: 256)
                }
                .parameter("deltaTime", value: context.frameUniforms.deltaTime)
                .parameter("particles", buffer: particleBuffer)
            }

            // Render pass: draw the scene
            try RenderPass {
                // Skybox
                try RenderPipeline(
                    vertexShader: library.skyboxVertex,
                    fragmentShader: library.skyboxFragment
                ) {
                    Draw { encoder in
                        encoder.draw(skyboxMesh)
                    }
                }
                .parameter("viewProjection", value: viewProjectionMatrix)

                // Particles
                try RenderPipeline(
                    vertexShader: library.particleVertex,
                    fragmentShader: library.particleFragment
                ) {
                    Draw { encoder in
                        encoder.drawPrimitives(
                            primitiveType: .point,
                            vertexStart: 0,
                            vertexCount: particleCount
                        )
                    }
                    .vertexBuffer(particleBuffer, index: 0)
                }
                .parameter("viewProjection", value: viewProjectionMatrix)
                .depthCompare(function: .less, writes: true)
            }
        }
        .metalDepthStencilPixelFormat(.depth32Float)
    }
}

See the Tutorials for step-by-step guides.


Comparison

Both examples render a red triangle. Traditional Metal is on the left. MetalSprockets is on the right.

Traditional Metal vs MetalSprockets


Environment Variables

Set these variables in Xcode's scheme editor or your shell. The values yes, true, 1, and on enable them. Values are case-insensitive.

Variable Description
MS_LOGGING Enable general logging output (alias: LOGGING)
MS_VERBOSE Enable verbose logging (alias: VERBOSE)
MS_METAL_LOGGING Enable logging within Metal shaders (requires Metal logging support at shader compile time)
MS_FATALERROR_ON_THROW Convert thrown errors to fatal errors for easier debugging
MS_RENDERVIEW_LOG_FRAME Log frame rendering information in RenderView
MS_DUMP_SNAPSHOTS Dump system snapshots to JSONL files in $TMPDIR/metal-sprockets_snapshots/ for debugging the element tree

Testing

Run the tests with xcb test. Xcode Debug runs also turn on Metal API validation and GPU frame capture, and some failures happen only under those layers. To run the suite under each layer, use Scripts/test-metal-layers.sh. To run one layer, set its variable for the whole run, for example xcb test -e MTL_DEBUG_LAYER=1 or xcb test -e MTL_CAPTURE_ENABLED=1.


License

MIT — see LICENSE


Links