feat(sokol): Metal/IOSurface producer for macOS (#125)

[apotema]

Summary

Slice 2 of the sokol PIE viewport work (after #124's GL slice). Closes #125. Emits a Metal/IOSurface readback path alongside the GL block, sharing the existing module-scope state and Preview lifecycle while being gated by a mutually exclusive _sokol_preview_metal_enabled comptime flag (.macos/.ios only).

Path A vs Path B — which and why

Path B (Metal blit + CPU copy + engine's existing publishFrameIOSurface(rgba)). Path A (render-to-IOSurface as swapchain override) was deferred for the reasons the ticket called out:

• Path A needs the engine to expose IOSurfaceRefs per ring slot so we can bind them as MTLTexture render targets via [MTLDevice newTextureWithDescriptor:iosurface:plane:]. That's a real engine API extension, not a wiring detail.
• Path A also needs to wrestle sokol's swapchain config to either redirect into our textures or run an offscreen render pass we copy into the drawable for the on-screen window — both intrusive.
• Path B works with zero engine API changes today. The double-swizzle (producer BGRA→RGBA, engine RGBA→BGRA) is a known wart but the cost is one cache-friendly pass over the staging buffer per frame at ~ms scale on 1080p — invisible compared to a GPU blit + waitUntilCompleted.

The implementation:

• libobjc bridging: selectors + typed @extern objc_msgSend wrappers cached in a comptime-gated _SokolPreviewMetal struct namespace. Non-Darwin builds carry zero objc references at link time.
• Blit copyFromTexture: from the swapchain drawable → managed-storage staging MTLTexture, synchronizeResource: (macOS only — iOS shared storage no-ops), waitUntilCompleted, getBytes:.
• BGRA8 → RGBA8 swizzle, then Preview.publishFrameIOSurface (labelle-engine#547) which swizzles back into the IOSurface ring.
• Placed after window.endFrame() (post sg.commit()) so the swapchain texture is in a readable state — GL stays pre-endFrame() (different sokol-gfx semantics). A new {{preview_readback_post}} template slot in desktop.txt + mobile.txt carries the post-commit block.

Engine-API gaps encountered

None blocking. The engine's Preview.beginFrameStreamIOSurface / publishFrameIOSurface(rgba) / endFrameStreamIOSurface triple is sufficient for Path B as-shipped.

A non-blocking nice-to-have is filed for follow-up:

• Preview.publishFrameIOSurfaceBgra(bgra) — accept BGRA8 directly, no producer-side swizzle. Metal swapchains are BGRA8 natively; the existing API forces a double-swizzle.

Stub flagged for upstream sokol

window.metalCurrentDrawable currently returns null with a documented limitation:

The pinned sokol-zig (pb1HKxTaNgA8rXBh41wxEucgmR4YPuoOXGeXbFyGPvTK) has replaced the legacy sapp_metal_get_current_drawable accessor (cached frame drawable) with a struct-returning sapp_get_swapchain() whose macOS implementation calls [CAMetalLayer nextDrawable] on every call. Invoking it from our readback would acquire a fresh empty drawable, not the one sokol-gfx just rendered into via sglue_swapchain() → defeating the entire pipeline.

The fix lives upstream: expose the currently-acquired drawable from sokol-gfx's per-frame cache (the equivalent of the legacy accessor). Until that lands, all the wiring is in place and the entire blit chain gates on this returning non-null — so today the macOS readback cleanly no-ops (control plane still emits hello/heartbeat/bye via the existing Preview triple). Flipping the stub once upstream resolves the gap is a single-line change.

Test additions

• sokol emits Metal/IOSurface readback block alongside GL block (slice 2 / #125) — new dedicated test asserting:
  • _sokol_preview_metal_enabled gate + .macos, .ios => true switch
  • _SokolPreviewMetal namespace + selectors + msgSend cluster
  • MTLPixelFormatBGRA8Unorm, blitCommandEncoder, copyFromTexture:sourceSlice:sourceLevel:, getBytes:bytesPerRow:fromRegion:mipmapLevel:
  • window.metalDevice() / window.metalCurrentDrawable() wrappers used (legacy C symbols not referenced)
  • Module-scope state names don't collide with the GL block (_preview_mtl_* vs _preview_*)
  • IOSurface lifecycle (beginFrameStreamIOSurface → publishFrameIOSurface → endFrameStreamIOSurface)
  • Source-order: beginFrameStreamIOSurface before first publishFrameIOSurface, Metal readback after window.endFrame(), endFrameStreamIOSurface before sendBye(.normal)
  • GL block from feat(sokol): GLCORE/GLES3 PBO readback + publishFrame (#122 slice 1) #124 still emits unchanged (regression lock for slice 1)
  • AST parses cleanly
• Extended raylib desktop still emits its own PBO readback and non-loop, non-sokol backends do not pull in any preview pixel publish path to also lock out _sokol_preview_metal_enabled, _SokolPreviewMetal, _p.publishFrameIOSurface(, and window.metalDevice() from those code paths.

What I verified locally

• zig build (Zig 0.16) — clean.
• zig build test --summary all — 300/304 tests pass, 4 pre-existing skips (none touched by this PR).
• Regenerated examples/sokol/.labelle/sokol_desktop/main.zig via the assembler binary and ran zig build in that directory on macOS arm64 — links cleanly against IOSurface, CoreFoundation, Metal, AppKit, libobjc.
• otool -L on the resulting binary confirms framework deps land as expected.

Test plan

• zig build test passes locally
• Generated sokol-on-macOS example compiles and links
• E2E: launch a generated sokol-macOS game against the editor's iosurface consumer and confirm graceful no-op (current state) — this only needs the control plane to stay healthy; pixel publish gated on the stub.
• Follow-up PR: flip window.metalCurrentDrawable to return the cached drawable once upstream sokol surfaces it.

Out of scope

• D3D11 / Windows (slice 3 — sokol slice 3: D3D11 staging-texture readback (Windows) #126)
• iOS-specific UX (touch, lifecycle)
• The render-to-IOSurface FBO path (Path A, deferred per ticket guidance)
• The publishFrameIOSurfaceBgra engine API addition (filed as engine follow-up)
• Resolving the metalCurrentDrawable upstream sokol API gap

🤖 Generated with Claude Code

[cursor]

PR Summary

Medium Risk
Adds a new Metal readback path (libobjc calls, swapchain drawable access, and new framework link deps) that changes generated game code and build/link behavior on Darwin targets; main risk is build/link/runtime issues specific to macOS/iOS preview mode.

Overview
Enables a new Darwin-only Play-in-Editor preview pixel publish path for sokol by generating a Metal-based swapchain readback that blits the current drawable into a staging texture, copies bytes to CPU, swizzles BGRA→RGBA, and publishes via Preview.publishFrameIOSurface.

Updates the sokol backend to expose window.metalDevice() and window.metalCurrentDrawable() (requiring a pinned sokol-zig fork), adds a post-window.endFrame() template slot ({{preview_readback_post}}) to run the Metal readback after sg.commit(), and links IOSurface/CoreFoundation frameworks on .macos/.ios. Adds/extends generator tests to assert the new Metal block is emitted for sokol and does not leak into non-sokol templates.

^{Reviewed by Cursor Bugbot for commit 4584c6a. Bugbot is set up for automated code reviews on this repo. Configure here.}

[gemini-code-assist]

Code Review

This pull request introduces a Metal/IOSurface readback path for the Sokol backend on macOS and iOS, facilitating frame capture on Darwin platforms. It implements Objective-C runtime bridging to blit swapchain textures to staging textures and read pixels back to the CPU, alongside updates to the build system for framework linking and new lifecycle hooks in the code generation templates. A review comment identifies an improvement opportunity to reset module-scope state variables during cleanup to prevent potential issues during application re-initialization.

[gemini-code-assist]

The cleanup block should reset the module-scope state variables (_preview_mtl_last_w, _preview_mtl_last_h, and _preview_mtl_initialized) to their initial values. If the application is re-initialized within the same process (e.g., during tests), failing to reset these will cause the resize logic to be skipped, leading to null pointer dereferences when attempting to use the command queue or staging texture.

        if (_preview_mtl_pixel_buf.len != 0) {
            _preview_allocator.free(_preview_mtl_pixel_buf);
            _preview_mtl_pixel_buf = &[_]u8{};
        }
        _preview_mtl_last_w = 0;
        _preview_mtl_last_h = 0;
        _preview_mtl_initialized = false;

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 4584c6a. Configure here.}

[cursor]

Staging texture released before replacement is validated

Low Severity

In the Metal resize path, the old staging texture is unconditionally released before the replacement is confirmed valid. If createStagingTexture returns null, the old texture is already freed and _preview_mtl_staging_texture is null. Because the failure prevents _preview_mtl_last_w/h from updating, the resize block retries correctly on subsequent frames at the new size — but if the window returns to its original dimensions, dims match the stale _preview_mtl_last_w/h, the resize block is never re-entered, and readback is permanently broken (staging texture is null, pixel buffer may be empty). The GL path avoids this because it reuses PBOs in place via bufferData rather than freeing GPU resources before replacement.

 

^{Reviewed by Cursor Bugbot for commit 4584c6a. Configure here.}

[cursor]

Dependency URL uses branch ref instead of commit

Low Severity

The sokol dependency URL was changed from a pinned commit hash to a branch reference (refs/heads/feat/expose-cached-metal-drawable). While the .hash field ensures reproducibility for existing builds, the branch head can change if the fork is rebased or force-pushed, causing a hash mismatch and a confusing build failure for anyone running zig fetch. The previous dependency used a stable commit-SHA URL — this regresses that pattern.

 

^{Reviewed by Cursor Bugbot for commit 4584c6a. Configure here.}