Compose Multiplatform SKIKO Metal Render-Thread CADisplayLink Synchronization Standard

--- description: Compose Multiplatform SKIKO Metal Render-Thread CADisplayLink Synchronization Standard - Mandates deterministic vsync synchronization between Apple Metal command buffers in SKIKO and UIKit run loops using CADisplayLink. Enforces strict frame-pacing and buffer locks to eliminate visual tearing and render-thread contention across native interoperability boundaries. globs: **/*Ios.kt, **/*Native.kt, **/skiko/**/*.kt, **/metal/**/*.kt, **/*.ios.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/compose-skiko-metal-render-synchronization-standard" --- # Compose Multiplatform SKIKO Metal Render-Thread CADisplayLink Synchronization Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Unsynchronized Main-Thread Render Loops and Ad-Hoc Timers Leading to Metal Buffer Contention and Frame Tearing ## System Constraints You are a Principal Engineer enforcing the Compose Multiplatform SKIKO Metal Render-Thread Synchronization Standard. Mandate that all Metal drawing passes and Skia canvas rendering cycles bind directly to platform-native vsync pulses (CADisplayLink) on iOS. Strictly prevent unbounded coroutines or decoupled dispatch queues from pumping render frames out of sync with the display refresh rate. ## Strict Guidelines - Engineers MUST ALWAYS bind SKIKO rendering triggers directly to a CADisplayLink registered with NSRunLoop.mainRunLoop in NSRunLoopCommonModes to prevent frame drops during UIKit scroll interactions. - Engineers MUST NEVER dispatch Metal draw passes via unthrottled coroutine frame loops (e.g., while(isActive) { delay(16); needRedraw() }) across the Kotlin/Native boundary. - Code MUST release or present CAMetalDrawable instances immediately after encoding to prevent exhaustion of the Metal drawable triple-buffer pool. - Services MUST ensure that interoperability layers (e.g., UIKitView inside Compose) synchronize their layout and commit phases within the same CATransaction to eliminate tearing during gestures. - Components NEVER invoke blocking synchronization primitives (such as MTLCommandBuffer.waitUntilCompleted() or thread-blocking locks) inside the CADisplayLink frame dispatch callback. ## Bad vs Good Implementations ### CADisplayLink Vsync Synchronization for SKIKO Metal Pipeline #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Driving Compose canvas updates using an arbitrary coroutine delay decouples rendering from the hardware refresh rate (ignoring ProMotion 120Hz and 60Hz limits), desynchronizes with the UIKit run loop during scrolling gestures, and triggers frame tearing or lock contention on the Metal command queue. ```kotlin // ANTI-PATTERN: Coroutine-driven frame loop decoupled from iOS vsync pipeline. // Causes jitter, frame drops during UIKit gestures, and Metal drawable starvation. class CoroutineRenderPump(private val layer: SkiaLayer) { private val scope = CoroutineScope(Dispatchers.Main) fun start() { scope.launch { while (isActive) { // Arbitrary 60Hz timing ignores variable refresh rates (ProMotion 120Hz) // and loses synchronization during native UI gestures. delay(16) layer.needRedraw() } } } } ``` #### Production Standard (Correct) > **Standard**: Binding to CADisplayLink using NSRunLoopCommonModes guarantees that frame callbacks match display vsync cycles (adapting natively to 60Hz or 120Hz ProMotion screens) and maintains draw cycle alignment even while native UIKit views are performing continuous scroll tracking. ```kotlin // PRODUCTION STANDARD: Deterministic CADisplayLink frame synchronization. // Binds directly to the Metal drawable lifecycle and common run loop modes. import platform.QuartzCore.CADisplayLink import platform.Foundation.NSRunLoop import platform.Foundation.NSRunLoopCommonModes import platform.darwin.NSObject class MetalVsyncSynchronizer( private val onVsyncFrame: (timestamp: Double, targetTimestamp: Double) -> Unit ) : NSObject() { private var displayLink: CADisplayLink? = null fun start() { stop() val link = CADisplayLink.displayLinkWithTarget( target = this, selector = platform.objc.sel_registerName("onDisplayLinkStep:") ) // Bind to common modes to ensure rendering continues during UIScrollView tracking link.addToRunLoop(NSRunLoop.mainRunLoop, NSRunLoopCommonModes) displayLink = link } @OptIn(kotlinx.cinterop.BetaInteropApi::class) @platform.objc.ObjCAction fun onDisplayLinkStep(link: CADisplayLink) { // Pass deterministic hardware timestamps to throttle SKIKO redraw passes onVsyncFrame(link.timestamp, link.targetTimestamp) } fun stop() { displayLink?.invalidate() displayLink = null } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Compose Multiplatform SKIKO Metal Render-Thread CADisplayLink Synchronization Standard

Compose Multiplatform SKIKO Metal Render-Thread CADisplayLink Synchronization Standard defines an industrial-grade behavioral standard for mobile engineering. Mandates deterministic vsync synchronization between Apple Metal command buffers in SKIKO and UIKit run loops using CADisplayLink. Enforces strict frame-pacing and buffer locks to eliminate visual tearing and render-thread contention across native interoperability boundaries. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Unsynchronized Main-Thread Render Loops and Ad-Hoc Timers Leading to Metal Buffer Contention and Frame Tearing Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Unsynchronized Main-Thread Render Loops and Ad-Hoc Timers Leading to Metal Buffer Contention and Frame Tearing	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS bind SKIKO rendering triggers directly to a CADisplayLink registered with NSRunLoop.mainRunLoop in NSRunLoopCommonModes to prevent frame drops during UIKit scroll interactions.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.