KMP Compose Multiplatform Metal Swapchain and Texture Allocation Guardrail

--- description: KMP Compose Multiplatform Metal Swapchain and Texture Allocation Guardrail - Enforces pre-allocated, unmanaged Metal texture pools and stable native handles for Skiko rendering pipelines on iOS. Prevents transient CAMetalDrawable allocations within the Kotlin/Native memory manager sweep path, eliminating frame-pacing drops and GC-induced display stutter. globs: **/iosMain/**/*.kt, **/iosApp/**/*.swift, **/commonMain/**/ui/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-compose-metal-swapchain-allocation-guardrail" --- # KMP Compose Multiplatform Metal Swapchain and Texture Allocation Guardrail > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Allocating Ephemeral Metal Textures or Skia Surfaces Inside Compose Draw Scopes Subject to Kotlin/Native GC Sweeps ## System Constraints You are a Principal Mobile Architect specializing in Compose Multiplatform, Skiko, and Apple Metal graphics pipelines. Enforce zero-allocation per-frame graphics pipelines on iOS. Ensure that all Skia surfaces, Metal textures, and CAMetalLayer swapchain resources bypass the Kotlin/Native garbage collector sweep window through native memory pinning, off-heap pooling, and lifecycle stabilization. ## Strict Guidelines - Engineers MUST ALWAYS pre-allocate Metal textures and Skia off-screen render targets in fixed-capacity ring buffers or texture pools during initialization, never inside DrawScope or Modifier.drawWithContent. - Engineers MUST NOT allow transient native wrappers (e.g., CPointer, SkBitmap, SkSurface) to be instantiated and dropped within rapid invalidation loops where Kotlin/Native concurrent GC sweeps cause frame stutter. - Custom Metal render passes MUST hold texture backing stores outside the Kotlin heap using native C interop arenas or Swift-managed lifecycle containers with StableRef pinning. - Render pipelines SHOULD configure CAMetalLayer.presentsWithTransaction and maximumDrawableCount = 3 to maintain double/triple buffering symmetry without triggering Skiko redraw stalls. - Components NEVER capture dynamic Kotlin objects across the Metal command buffer completion handlers without explicit StableRef tracking to avoid premature deallocation during active GPU execution. ## Bad vs Good Implementations ### Skiko Metal Surface Allocation in Custom Draw Pipeline #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Creating native graphics objects inside DrawScope forces per-frame allocation of Kotlin/Native wrapper objects. Although .close() is called, the wrapper shells trigger frequent GC sweeps in Kotlin/Native, stalling Skiko's Metal present loop and dropping frames. ```kotlin // BAD: Re-creating Skia surface or texture on every draw frame inside Compose @Composable fun MetalFilterEffect(modifier: Modifier = Modifier) { Canvas(modifier = modifier) { // Allocating new native SkImage/SkSurface wrappers on every frame in Compose heap val surface = org.jetbrains.skia.Surface.makeRasterN32Premul( size.width.toInt(), size.height.toInt() ) try { val canvas = surface.canvas // Rendering operations... drawContext.canvas.nativeCanvas.drawImage(surface.makeImageSnapshot(), 0f, 0f) } finally { // Kotlin/Native GC sweep window must still reclaim native pointer shells, // leading to periodic 16ms+ micro-stutters during 120Hz ProMotion render. surface.close() } } } ``` #### Production Standard (Correct) > **Standard**: Reusing pre-allocated surfaces via a pooled buffer eliminates native wrapper allocation during the frame loop. Kotlin/Native GC remains idle, allowing Skiko and Metal to maintain uninterrupted 120Hz frame pacing on iOS. ```kotlin // GOOD: Pre-allocated off-heap texture target pinned across recompositions @Composable fun MetalFilterEffect(modifier: Modifier = Modifier) { val texturePool = remember { PinnedMetalSurfacePool(maxBuffers = 3) } DisposableEffect(Unit) { onDispose { texturePool.release() } } Canvas(modifier = modifier) { val width = size.width.toInt().coerceAtLeast(1) val height = size.height.toInt().coerceAtLeast(1) // Acquire pre-allocated native surface held outside K/N GC sweep path texturePool.acquire(width, height) { nativeSurface -> val canvas = nativeSurface.canvas // Render with zero GC heap pressure drawContext.canvas.nativeCanvas.drawImage(nativeSurface.makeImageSnapshot(), 0f, 0f) } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: KMP Compose Multiplatform Metal Swapchain and Texture Allocation Guardrail

KMP Compose Multiplatform Metal Swapchain and Texture Allocation Guardrail defines an industrial-grade behavioral standard for mobile engineering. Enforces pre-allocated, unmanaged Metal texture pools and stable native handles for Skiko rendering pipelines on iOS. Prevents transient CAMetalDrawable allocations within the Kotlin/Native memory manager sweep path, eliminating frame-pacing drops and GC-induced display stutter. 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: Allocating Ephemeral Metal Textures or Skia Surfaces Inside Compose Draw Scopes Subject to Kotlin/Native GC Sweeps 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	Allocating Ephemeral Metal Textures or Skia Surfaces Inside Compose Draw Scopes Subject to Kotlin/Native GC Sweeps	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 pre-allocate Metal textures and Skia off-screen render targets in fixed-capacity ring buffers or texture pools during initialization, never inside DrawScope or Modifier.drawWithContent.

Engineers MUST ALWAYS pre-allocate Metal textures and Skia off-screen render targets in fixed-capacity ring buffers or texture pools during initialization, never inside DrawScope or Modifier.drawWithContent.

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.