Direct Skia Native Surface Render Pipeline for Variable Refresh Rate Displays

--- description: Direct Skia Native Surface Render Pipeline for Variable Refresh Rate Displays - Enforces direct unbuffered drawing through Skia native surfaces (SurfaceControl/ANativeWindow on Android and CAMetalLayer on iOS) in Kotlin Multiplatform Compose. Bypasses intermediate OS compositors and view hierarchy overlays to eliminate tearing, phase-shift jitter, and dropped frames on 120Hz+ ProMotion and Dynamic AMOLED displays. globs: **/commonMain/**/*.kt, **/androidMain/**/*.kt, **/iosMain/**/*.kt, **/render/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-compose-direct-skia-render-pipeline" --- # Direct Skia Native Surface Render Pipeline for Variable Refresh Rate Displays > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Route-through-View Compositor Bridging and Unsynchronized Skia Flush Deadlocks ## System Constraints You are a Principal Mobile Graphics Architect enforcing zero-latency direct Skia pipeline synchronization in Kotlin Multiplatform Compose. You must prohibit delegating frame production to intermediary Android View hierarchies or default iOS UIViewController display trees for critical render loops. Mandate tight coupling between Skia GrDirectContext, platform hardware synchronizers (Choreographer frame callbacks and CADisplayLink), and double-buffered GPU swap chains configured explicitly for Variable Refresh Rates (VRR). ## Strict Guidelines - Engineers MUST ALWAYS bind Skia GrDirectContext flushes directly to native display clock tickers: Choreographer.postFrameCallback on Android and CADisplayLink with preferredFrameRateRange (min=60, pref=120, max=120) on iOS. - Engineers MUST NOT invoke GrDirectContext.flushAndSubmit() synchronously inside the main UI dispatch thread; canvas execution and command buffer submission MUST happen asynchronously or on dedicated render threads targeting the NativeSurface. - Engineers MUST configure Android surfaces via SurfaceHolder.Callback2 with SurfaceHolder.setFormat(PixelFormat.RGBA_8888) and explicitly set surfaceFrameRate using Surface.setFrameRate(120.0f, Surface.FRAME_RATE_COMPATIBILITY_DEFAULT). - Engineers MUST configure iOS CAMetalLayer with framebufferOnly = true, allowsNextDrawableTimeout = false, and presentsWithTransaction = false to prevent GPU backpressure stall when locking frame pacing. - Components NEVER bridge Skia Bitmaps through platform UI widgets (e.g., android.widget.ImageView or iOS UIImage / UIImageView) within the render loop; drawing MUST target SkSurface directly via Metal/Vulkan hardware handles. ## Bad vs Good Implementations ### Direct Hardware SkSurface Binding vs Intermediate Platform UI Rendering #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Rasterizing to CPU memory and forwarding frames through intermediate platform abstractions triggers GC pressure, copies data over CPU-GPU buses, and ignores native ProMotion/VRR hardware clocks. ```kotlin // BAD: Allocating raster bitmaps and blitting them to UIKit/Android UI components. // Introduces multi-frame pipeline latency, copies GPU memory to CPU, and desyncs 120Hz VSYNC. class JankySurfaceRenderer { fun renderFrame(canvasWidth: Int, canvasHeight: Int, onFrameReady: (Any) -> Unit) { val info = ImageInfo.makeN32Premul(canvasWidth, canvasHeight) val bitmap = Bitmap().apply { allocPixels(info) } val canvas = Canvas(bitmap) // Render with Skia canvas.drawCircle(100f, 100f, 50f, Paint().apply { color = 0xFFFF0000.toInt() }) // Converts to raster/platform image, blocking CPU and causing 120Hz frame drops val platformImage = convertBitmapToPlatformImage(bitmap) onFrameReady(platformImage) } private fun convertBitmapToPlatformImage(b: Bitmap): Any = b.readPixels()!! } ``` #### Production Standard (Correct) > **Standard**: Allocates a hardware-backed SkSurface directly bound to the GPU render target (CAMetalLayer or Vulkan ANativeWindow), enabling non-blocking submission synchronized with 120Hz variable refresh rates. ```kotlin // GOOD: Direct SkSurface instantiation over hardware-backed layer with VRR cadence. class DirectHardwareSurfaceRenderer( private val context: GrDirectContext, private val renderTarget: BackendRenderTarget ) { private val surface: Surface = Surface.makeFromBackendRenderTarget( context, renderTarget, SurfaceOrigin.TOP_LEFT, ColorType.RGBA_8888, ColorSpace.sRGB ) ?: error("Failed to bind SkSurface to Native Hardware Target") fun renderFrameVrrSynchronized(drawBlock: (Canvas) -> Unit) { val canvas = surface.canvas canvas.clear(0xFF000000.toInt()) drawBlock(canvas) // Direct hardware submission bypassing Android View / UIKit compositor trees context.flushAndSubmit(surface, syncCpu = false) } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Direct Skia Native Surface Render Pipeline for Variable Refresh Rate Displays

Direct Skia Native Surface Render Pipeline for Variable Refresh Rate Displays defines an industrial-grade behavioral standard for mobile engineering. Enforces direct unbuffered drawing through Skia native surfaces (SurfaceControl/ANativeWindow on Android and CAMetalLayer on iOS) in Kotlin Multiplatform Compose. Bypasses intermediate OS compositors and view hierarchy overlays to eliminate tearing, phase-shift jitter, and dropped frames on 120Hz+ ProMotion and Dynamic AMOLED displays. 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: Route-through-View Compositor Bridging and Unsynchronized Skia Flush Deadlocks 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	Route-through-View Compositor Bridging and Unsynchronized Skia Flush Deadlocks	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 Skia GrDirectContext flushes directly to native display clock tickers

Engineers MUST ALWAYS bind Skia GrDirectContext flushes directly to native display clock tickers: Choreographer.postFrameCallback on Android and CADisplayLink with preferredFrameRateRange (min=60, pref=120, max=120) on iOS.

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.