perf(apple): windowed macOS presents — off-main transactional commit, surface prototype, safe-present setting

Task 1 (latency): the transactional present now commits from the RENDER thread inside an explicit CATransaction + flush() instead of hopping to main. The present harness (2026-07-21, 240 Hz Studio, full-size window) measured the main hop batching presents at runloop-iteration rate when main is busy — an active implicit transaction NESTS the explicit one — which is the field's presents=55 @ fps=240 / display_p50 18.6 ms. Off-main commits measured immune to main churn: glass p50 ~10 ms, cadence a clean 4.17 ms at 240. flush() is load-bearing: without it the render thread's own implicit transaction (drawableSize/colour writes) swallows the explicit commit and NOTHING reaches glass — the harness reproduced the exact freeze (every present dropped). Legacy main-hop kept as PUNKTFUNK_TXN_PRESENT=main for field A/B. New pf-windowed Console line (subsystem io.unom.punktfunk, category presenter) decomposes the issue side per second. Task 1 lever D: the f407f418 IOSurface contents-swap path is resurrected format-aware as WindowedPresentMode.surface — bgra8 SDR / rgba16Float+PQ-tagged HDR pool, swap committed off-main from the completion handler; EDR anchored by the metal layer underneath. Env-only prototype (PUNKTFUNK_WINDOWED_PRESENT=surface) until the HDR composite is eyeballed on glass. Task 2 (setting): punktfunk.windowedSafePresent (default ON = transactional mitigation; OFF = the fast async path whose panic the saga is about — the caption says so in plain words). Rows in the touch Settings (Presentation) and gamepad settings, macOS-only. PUNKTFUNK_WINDOWED_PRESENT=async|transaction|surface overrides for dev A/B. maximumDrawableCount stays 3 — the harness measured 2 starving the render loop (172/s) and worsening glass p50. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-21 15:58:47 +02:00
parent 71faf38a85
commit 0e60e58cab
8 changed files with 478 additions and 52 deletions
@@ -70,6 +70,16 @@ public enum DefaultsKey {
    /// (lowest latency — the default, OFF). Resolved once per session;
    /// PUNKTFUNK_PRESENT_MODE=immediate|vsync overrides it for A/B. See Stage2Pipeline's header.
    public static let vsync = "punktfunk.vsync"
+    /// macOS: present WINDOWED sessions in lockstep with the system compositor (the DCP
+    /// "mismatched swapID's" kernel-panic mitigation — see SessionPresenter.windowedPresentMode
+    /// and the MetalVideoPresenter saga notes). ON/unset (the default): windowed presents ride
+    /// a Core Animation transaction — validated panic-free on the 240 Hz repro machine, at a
+    /// small display-latency cost vs the raw path. OFF: windowed sessions keep the fast async
+    /// image queue — ON AFFECTED SETUPS (high-refresh displays) THAT PATH KERNEL-PANICS THE
+    /// WHOLE MAC, which is why the default is ON. Fullscreen always presents async (fast path)
+    /// regardless. Resolved once per session; PUNKTFUNK_WINDOWED_PRESENT=async|transaction|
+    /// surface overrides it for dev A/B.
+    public static let windowedSafePresent = "punktfunk.windowedSafePresent"
    /// Allow variable refresh rate: hand the display link a wide frame-rate RANGE (low floor,
    /// preferred = stream rate) so a ProMotion / adaptive-sync display can vary its physical
    /// refresh to match the stream. On by default; a no-op on fixed-refresh displays. When off,