Compose Multiplatform iOS Metal Layer & CADisplayLink Synchronization Standard

--- description: Compose Multiplatform iOS Metal Layer & CADisplayLink Synchronization Standard - Enforces deterministic frame pacing and double/triple-buffered Metal texture presentation between Kotlin Native rendering loops and CADisplayLink. Prohibits blocking the main thread during CAMetalDrawable acquisition and mandates backpressure bounds to eliminate VSync deadline misses and frame hitches. globs: **/iosApp/**/*.{swift,m,mm}, **/shared/src/iosMain/**/*.{kt,swift}, **/compose-ui/src/iosMain/**/*.{kt,swift} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/cmp-ios-metal-displaylink-sync-standard" --- # Compose Multiplatform iOS Metal Layer & CADisplayLink Synchronization Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Unbounded Main-Thread CAMetalDrawable Blocking & Asynchronous Kotlin Draw Loop Race ## System Constraints You are a Principal Mobile Graphics Architect enforcing strict Metal layer frame pacing and CADisplayLink synchronization for Compose Multiplatform on iOS. Your mandate is to prevent UI hitching, eliminate main-thread stalls caused by nextDrawable() contention, and enforce asynchronous frame completion accounting. ## Strict Guidelines - Engineers MUST ALWAYS synchronize Kotlin Native recomposition and layout commits with CADisplayLink target timestamps to maintain exact VSync alignment. - Engineers MUST NEVER synchronously invoke `CAMetalLayer.nextDrawable()` on the main thread while holding open Compose transaction locks or active rendering locks. - Code MUST employ a bounded DispatchSemaphore (maximum 2 or 3 in-flight frames) signaled exclusively inside Metal command buffer `addCompletedHandler` blocks to apply render backpressure. - Engineers MUST explicitly set `CAMetalLayer.presentsWithTransaction = false` unless orchestrating UIKit frame-synchronized transitions. - Components NEVER execute raw Skia canvas draw calls directly inside CADisplayLink callbacks without checking for command buffer pool readiness. ## Bad vs Good Implementations ### Metal Layer Frame Synchronization & Bounded Backpressure #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly calling `metalLayer.nextDrawable()` on the main thread blocks CPU execution until a free drawable is available from the compositor. When the GPU is under load, this causes CADisplayLink deadline misses, skipping entire frames and inducing critical hitching. ```swift // BAD: Synchronously acquiring CAMetalDrawable on main thread inside CADisplayLink // Causes main-thread hitching whenever the GPU is saturated or Compose recomposition stalls class UnsynchronizedComposeView: UIView { var displayLink: CADisplayLink? var metalLayer: CAMetalLayer { layer as! CAMetalLayer } override static var layerClass: AnyClass { CAMetalLayer.self } func startRenderLoop() { displayLink = CADisplayLink(target: self, selector: #selector(renderFrame)) displayLink?.add(to: .main, forMode: .common) } @objc private func renderFrame() { // Synchronously blocks main thread if next drawable is unavailable (GPU bound) guard let drawable = metalLayer.nextDrawable() else { return } // Direct call to Kotlin Compose render engine on the main thread ComposeBridge.render(into: drawable.texture) let commandBuffer = metalLayer.device!.makeCommandQueue()!.makeCommandBuffer()! commandBuffer.present(drawable) commandBuffer.commit() } } ``` #### Production Standard (Correct) > **Standard**: Implements double/triple-buffering using a DispatchSemaphore to throttle in-flight frames without blocking the main run loop. Drops incoming VSync triggers non-destructively when the GPU is saturated, uses explicit presentation timestamps (`atTime: link.targetTimestamp`), and deallocates drawables safely via `addCompletedHandler`. ```swift // GOOD: Bounded in-flight frame tracking with semaphore and scheduled presentation final class SynchronizedComposeView: UIView { private var displayLink: CADisplayLink? private var commandQueue: MTLCommandQueue? private let inFlightSemaphore = DispatchSemaphore(value: 3) // Triple-buffering var metalLayer: CAMetalLayer { layer as! CAMetalLayer } override static var layerClass: AnyClass { CAMetalLayer.self } func setupMetal(device: MTLDevice) { metalLayer.device = device metalLayer.pixelFormat = .bgra8Unorm metalLayer.framebufferOnly = true metalLayer.presentsWithTransaction = false self.commandQueue = device.makeCommandQueue() displayLink = CADisplayLink(target: self, selector: #selector(onDisplayLink(_:))) displayLink?.preferredFrameRateRange = CAFrameRateRange(minimum: 60, maximum: 120, preferred: 120) displayLink?.add(to: .main, forMode: .common) } @objc private func onDisplayLink(_ link: CADisplayLink) { // Non-blocking attempt to acquire pipeline slot guard inFlightSemaphore.wait(timeout: .now()) == .success else { // Drop frame gracefully if GPU is running behind; prevents main thread freeze return } guard let queue = commandQueue, let drawable = metalLayer.nextDrawable(), let commandBuffer = queue.makeCommandBuffer() else { inFlightSemaphore.signal() return } commandBuffer.addCompletedHandler { [weak self] _ in self?.inFlightSemaphore.signal() } // Target presentation time matches VSync deadline commandBuffer.present(drawable, atTime: link.targetTimestamp) // Dispatch Kotlin Skia rendering with valid pipeline lock ComposeBridge.render(to: drawable.texture, commandBuffer: commandBuffer) commandBuffer.commit() } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Compose Multiplatform iOS Metal Layer & CADisplayLink Synchronization Standard

Compose Multiplatform iOS Metal Layer & CADisplayLink Synchronization Standard defines an industrial-grade behavioral standard for mobile engineering. Enforces deterministic frame pacing and double/triple-buffered Metal texture presentation between Kotlin Native rendering loops and CADisplayLink. Prohibits blocking the main thread during CAMetalDrawable acquisition and mandates backpressure bounds to eliminate VSync deadline misses and frame hitches. 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: Unbounded Main-Thread CAMetalDrawable Blocking & Asynchronous Kotlin Draw Loop Race 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	Unbounded Main-Thread CAMetalDrawable Blocking & Asynchronous Kotlin Draw Loop Race	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 synchronize Kotlin Native recomposition and layout commits with CADisplayLink target timestamps to maintain exact VSync alignment.

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.