Compose Multiplatform Skiko VSYNC Native Frame-Pacing & Triple-Buffer Synchronization

--- description: Compose Multiplatform Skiko VSYNC Native Frame-Pacing & Triple-Buffer Synchronization - Enforces synchronous triple-buffered GPU presentation across iOS (Metal/CADisplayLink) and Android (Choreographer/Vulkan/EGL) runtimes in Compose Multiplatform. Eliminates micro-stutter, frame drops, and ProMotion refresh rate mismatches by locking Skiko canvas renders to hardware VSYNC pulses with strict backpressure signaling. globs: **/iosMain/**/*.kt, **/androidMain/**/*.kt, **/commonMain/**/*.kt, **/iosApp/**/*.swift alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/compose-multiplatform-skiko-vsync-frame-pacing" --- # Compose Multiplatform Skiko VSYNC Native Frame-Pacing & Triple-Buffer Synchronization > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Decoupled Coroutine Animation Loops and Unbounded Metal/SurfaceView Canvas Drawing Causing Presentation Micro-Stutter ## System Constraints You are a Principal Mobile Architect enforcing Compose Multiplatform Skiko Vsync Native Frame-Pacing Guardrails. Mandate that all rendering passes in Skiko and Compose Multiplatform are synchronized to the host OS VSYNC hardware clock using CADisplayLink on iOS (with explicit ProMotion 120Hz CAFrameRateRange configuration) and Choreographer on Android. Eliminate software polling loops, unthrottled Coroutine frame pumps, and unsynchronized triple-buffer command buffer commits that induce display jitter and thermal throttling. ## Strict Guidelines - Engineers MUST ALWAYS bind custom Skiko rendering pipelines and render triggers directly to CADisplayLink on iOS and android.view.Choreographer on Android. - Engineers MUST NOT drive high-frequency Skiko canvas invalidations or manual animations using standard coroutine delays (e.g., delay(16)), fixed tickers, or dispatchers detached from the platform display pipeline. - iOS Skiko layer configurations MUST configure CAFrameRateRange to explicitly support ProMotion variable refresh rates (minimum: 60, preferred: 120, maximum: 120) to prevent 60Hz lock-in. - Metal presentation passes MUST enforce a triple-buffering synchronization semaphore (DispatchSemaphore with value 3) to prevent GPU resource starvation and CPU-GPU pipeline stall bubbles. - Android SurfaceView and SkiaLayer integrations MUST route through HardwareRenderer or Choreographer.postFrameCallback to synchronize with EGL/Vulkan buffer swaps. - Components NEVER trigger synchronous render redraws outside of designated frame callbacks or invalidated state nodes within Compose Multiplatform layout passes. ## Bad vs Good Implementations ### Configuring Hardware-Synchronized Skiko VSYNC Loop with Metal Triple-Buffering on iOS #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Driving Compose/Skiko rendering with Coroutine delay(16) causes phase drift against the hardware display refresh, resulting in frame tears, micro-stutter, and total failure to take advantage of ProMotion (120Hz) displays on modern iOS hardware. ```kotlin // BAD: Decoupled coroutine-based render pump bypassing CADisplayLink hardware sync package org.company.app.graphics import kotlinx.coroutines.* import org.jetbrains.skiko.SkiaLayer class UnsynchronizedFramePacer(private val layer: SkiaLayer) { private val scope = CoroutineScope(Dispatchers.Default + SupervisorJob()) fun startRendering() { scope.launch { while (isActive) { // Fixed 60 FPS estimate; ignores iOS ProMotion 120Hz and causes dropped frames layer.needRedraw() delay(16L) } } } } ``` #### Production Standard (Correct) > **Standard**: Locks the Skiko redraw pump directly to the hardware display refresh via CADisplayLink, registers ProMotion 120Hz support via CAFrameRateRange, and limits inflight frames with a triple-buffering semaphore to prevent CPU-GPU stalls. ```kotlin // GOOD: Hardware VSYNC locked pacing via CADisplayLink with CAFrameRateRange & semaphore sync package org.company.app.graphics import kotlinx.cinterop.* import platform.Foundation.NSRunLoop import platform.Foundation.NSRunLoopCommonModes import platform.QuartzCore.CADisplayLink import platform.QuartzCore.CAFrameRateRange import platform.darwin.NSObject import platform.darwin.dispatch_semaphore_create import platform.darwin.dispatch_semaphore_signal import platform.darwin.dispatch_semaphore_wait import platform.darwin.DISPATCH_TIME_FOREVER import org.jetbrains.skiko.SkiaLayer class MetalSynchronizedFramePacer( private val layer: SkiaLayer ) : NSObject() { // Invariant: Hardware triple-buffering guard (max 3 inflight frames) private val frameSemaphore = dispatch_semaphore_create(3L) private var displayLink: CADisplayLink? = null @OptIn(ExperimentalForeignApi::class) fun startRendering() { val link = CADisplayLink.displayLinkWithTarget( target = this, selector = platform.objc.sel_registerName("onVsyncPulse:") ) // Explicit ProMotion configuration: 60Hz min, 120Hz preferred & max val range = cValue<CAFrameRateRange> { minimum = 60.0f maximum = 120.0f preferred = 120.0f } link.preferredFrameRateRange = range link.addToRunLoop(NSRunLoop.mainRunLoop, NSRunLoopCommonModes) displayLink = link } @OptIn(ExperimentalForeignApi::class) fun onVsyncPulse(link: CADisplayLink) { // Wait for buffer availability before dispatching draw pass to prevent pipeline stalls if (dispatch_semaphore_wait(frameSemaphore, DISPATCH_TIME_FOREVER) == 0L) { layer.needRedraw() // In real pipeline, signal on Metal command buffer completedHandler dispatch_semaphore_signal(frameSemaphore) } } fun stopRendering() { displayLink?.invalidate() displayLink = null } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Compose Multiplatform Skiko VSYNC Native Frame-Pacing & Triple-Buffer Synchronization

Compose Multiplatform Skiko VSYNC Native Frame-Pacing & Triple-Buffer Synchronization defines an industrial-grade behavioral standard for mobile engineering. Enforces synchronous triple-buffered GPU presentation across iOS (Metal/CADisplayLink) and Android (Choreographer/Vulkan/EGL) runtimes in Compose Multiplatform. Eliminates micro-stutter, frame drops, and ProMotion refresh rate mismatches by locking Skiko canvas renders to hardware VSYNC pulses with strict backpressure signaling. 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: Decoupled Coroutine Animation Loops and Unbounded Metal/SurfaceView Canvas Drawing Causing Presentation Micro-Stutter 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	Decoupled Coroutine Animation Loops and Unbounded Metal/SurfaceView Canvas Drawing Causing Presentation Micro-Stutter	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 custom Skiko rendering pipelines and render triggers directly to CADisplayLink on iOS and android.view.Choreographer on Android.

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.