feat(apple): stage-3 presenter — glass-gated present pacing as a live A/B

Stage-2's present-on-arrival saturates CAMetalLayer's FIFO image queue whenever the stream rate runs at the panel's refresh (iOS always vsync-latches; the macOS 26 compositor latch-paces our out-of-band presents the same way): one early burst fills the queue to maximumDrawableCount and — arrivals then matching latches one-for-one — it never drains. That sticky depth is the measured 29-30 ms display stage on the 120 Hz ProMotion devices, and the full-queue regime is where host<->panel clock drift turns into the reported fixed-interval repeats/drops. The 240 Hz Studio never saturates, which is why it never showed either symptom. Stage-3 is the same pipeline with a PresentGate: at most ONE presented-but-undisplayed drawable in flight; the drawable's presented handler reopens the gate and re-signals the render thread, so the next present always takes the freshest newest-wins ring frame — the hidden queue latency becomes explicit, correct frame drops. A 100 ms stale fallback force-opens a gate whose handler never fires (the "presents aren't damage" hazard class) so a pathological system degrades visibly instead of freezing; the PUNKTFUNK_PRESENT_DEBUG `forced` counter exposes it (0 on healthy systems). Selection: the Settings > Display presenter picker now ships in release builds (stage 2 default / stage 3 experimental; the freeze-prone stage-1 diagnostic stays DEBUG-only), resolved per session with a PUNKTFUNK_PRESENTER=stage1|stage2|stage3 env override for CLI A/B. The pf-present debug line gains gated/forced/inflightMax — inflightMax is the direct image-queue-depth measurement for the A/B. Live-verified both ways against a real host at 1080p120: stage-3 holds 120/120 fps with inflightMax=1, forced=0, glass deltas p50 8.33 ms; stage-2 is behaviorally unchanged (120/120 fps, inflightMax=2 even on the wired 240 Hz setup — the saturation signal in miniature). Unit tests cover the gate (one-in-flight, stale force-open, idempotent release) and the presenter resolution (env override, release stage-1 gating); macOS tests green, iOS/tvOS xcodebuild clean. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-10 02:04:34 +02:00
parent 38b9f310e2
commit 08694b4026
6 changed files with 293 additions and 35 deletions
@@ -30,6 +30,11 @@ public enum DefaultsKey {
    /// discrete channel, and the default N→stereo downmix grabs channels 0/1 (silence when the mic
    /// is higher up), so we fold to mono ourselves. Only meaningful for multi-channel devices.
    public static let micChannel = "punktfunk.micChannel"
+    /// Which presenter runs a session: "stage2" (default — explicit decode + Metal present on
+    /// frame arrival), "stage3" (same pipeline, glass-gated present pacing — the experimental
+    /// low-display-latency A/B; see Stage2Pipeline's PresentPacing), or "stage1" (DEBUG-only
+    /// system-layer fallback). Resolved once per session by SessionPresenter;
+    /// PUNKTFUNK_PRESENTER=stage1|stage2|stage3 overrides it for A/B.
    public static let presenter = "punktfunk.presenter"
    /// macOS: V-Sync the stream's presents — each decoded frame flips on the next display vsync
    /// (evenly paced, no tearing under direct scanout) instead of as soon as the GPU finishes