Zero-Copy Native Texture Ingestion for KMP Compose Multiplatform

--- description: Zero-Copy Native Texture Ingestion for KMP Compose Multiplatform - Enforces hardware-backed zero-copy texture sharing between platform-native rendering pipelines (AVFoundation/Metal on Apple, AHardwareBuffer/Vulkan on Android) and Compose Multiplatform's Skiko rasterization layer. Prohibits CPU heap allocation, readbacks, and synchronous GPU fence stalls to guarantee sustained 60/120 FPS performance. globs: **/src/**/rendering/**/*.kt, **/src/**/graphics/**/*.kt, **/src/**/platform/**/*.kt, **/src/**/ui/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-compose-metal-vulkan-zero-copy-bridge" --- # Zero-Copy Native Texture Ingestion for KMP Compose Multiplatform > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Intermediate CPU Heap Readback and Synchronous GPU Stalls in Texture Render Loops ## System Constraints You are a Principal Graphics and Mobile Runtime Engineer specializing in Kotlin Multiplatform and Skiko rendering internals. Enforce strict zero-copy invariants when bridging native textures into Compose Multiplatform. You must reject any code executing CPU readbacks (e.g., glReadPixels, CVPixelBufferLockBaseAddress with CPU access, Bitmap allocation) or synchronous GPU stalls (glFinish, waitUntilCompleted) across the rendering boundary. Mandate direct hardware-backed external texture importing via AHardwareBuffer on Vulkan/Android and CVMetalTextureCache on Metal/Apple. ## Strict Guidelines - Engineers MUST ALWAYS wrap native GPU textures directly into Skia/Skiko backend texture structures (e.g., org.jetbrains.skia.Image.makeFromTexture or platform Metal/Vulkan equivalents) without copying raw pixel data to the JVM/Native heap. - Engineers MUST NOT call CVPixelBufferLockBaseAddress on Apple platforms or ImageReader.acquireLatestImage() byte-buffer extractors on Android for high-framerate rendering pipelines. - Code MUST use asynchronous GPU fence synchronization primitives (e.g., MTLEvent, VkSemaphore, or EGLSyncKHR) rather than blocking the main/render thread with glFinish() or commandBuffer.waitUntilCompleted(). - Services MUST manage lifetime and recycling of native texture caches (CVMetalTextureCacheRef, VkDeviceMemory bindings) to prevent memory leaks and Vulkan descriptor exhaustion. - Components NEVER reallocate backing textures per-frame; textures MUST be acquired from a double/triple-buffered hardware swapchain or ring buffer pool. ## Bad vs Good Implementations ### Bridging iOS CVPixelBuffer to Skiko Compose Metal Context #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Reading pixel bytes back to the CPU via CVPixelBufferLockBaseAddress and copying them into a Kotlin ByteArray forces a round-trip from GPU memory to CPU heap. This induces excessive GC churn, high bus bandwidth consumption, and frame drops below 60/120 FPS. ```kotlin // BAD: Allocating a CPU heap byte buffer and copying pixel data across the runtime fun renderFrame(pixelBuffer: CVPixelBufferRef, canvas: Canvas) { CVPixelBufferLockBaseAddress(pixelBuffer, 0u) val width = CVPixelBufferGetWidth(pixelBuffer).toInt() val height = CVPixelBufferGetHeight(pixelBuffer).toInt() val bytesPerRow = CVPixelBufferGetBytesPerRow(pixelBuffer).toInt() val srcPtr = CVPixelBufferGetBaseAddress(pixelBuffer) // Allocating a massive ByteArray on the Kotlin heap every frame val byteArray = ByteArray(height * bytesPerRow) memcpy(byteArray.refTo(0), srcPtr, (height * bytesPerRow).toULong()) CVPixelBufferUnlockBaseAddress(pixelBuffer, 0u) // CPU decoding / Skia raster allocation triggers garbage collection and frame stutter val skiaImage = Image.makeFromEncoded(byteArray) canvas.drawImage(skiaImage, 0f, 0f) } ``` #### Production Standard (Correct) > **Standard**: CVMetalTextureCacheCreateTextureFromImage provides direct access to the IOSurface/CVPixelBuffer GPU memory as an MTLTexture. Wrapping this into a Skia BackendTexture executes completely within GPU VRAM with zero heap memory allocation and zero CPU memory copies. ```kotlin // GOOD: Zero-copy texture ingestion using CVMetalTextureCache and Skiko GrDirectContext fun renderFrameZeroCopy( pixelBuffer: CVPixelBufferRef, textureCache: CVMetalTextureCacheRef, skikoGrContext: DirectContext, canvas: Canvas ) { val width = CVPixelBufferGetWidth(pixelBuffer).toULong() val height = CVPixelBufferGetHeight(pixelBuffer).toULong() val textureRef = memScoped { alloc<CVMetalTextureRefVar>() } // Map CVPixelBuffer directly into an MTLTexture without CPU copying val status = CVMetalTextureCacheCreateTextureFromImage( kCFAllocatorDefault, textureCache, pixelBuffer, null, MTLPixelFormatBGRA8Unorm, width, height, 0u, textureRef.ptr ) if (status != kCVReturnSuccess) return val metalTexture = CVMetalTextureGetTexture(textureRef.value) ?: return // Zero-copy wrap native Metal texture into Skia Image via backend texture bridge val backendTexture = BackendTexture.makeMetal(width.toInt(), height.toInt(), false, metalTexture) val skiaImage = Image.makeFromTexture( skikoGrContext, backendTexture, SurfaceOrigin.TOP_LEFT, ColorType.BGRA_8888, ColorAlphaType.PREMUL ) if (skiaImage != null) { canvas.drawImage(skiaImage, 0f, 0f) } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Zero-Copy Native Texture Ingestion for KMP Compose Multiplatform

Zero-Copy Native Texture Ingestion for KMP Compose Multiplatform defines an industrial-grade behavioral standard for mobile engineering. Enforces hardware-backed zero-copy texture sharing between platform-native rendering pipelines (AVFoundation/Metal on Apple, AHardwareBuffer/Vulkan on Android) and Compose Multiplatform's Skiko rasterization layer. Prohibits CPU heap allocation, readbacks, and synchronous GPU fence stalls to guarantee sustained 60/120 FPS performance. 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: Intermediate CPU Heap Readback and Synchronous GPU Stalls in Texture Render Loops 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	Intermediate CPU Heap Readback and Synchronous GPU Stalls in Texture Render Loops	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 wrap native GPU textures directly into Skia/Skiko backend texture structures (e.g., org.jetbrains.skia.Image.makeFromTexture or platform Metal/Vulkan equivalents) without copying raw pixel data to the JVM/Native heap.

Engineers MUST ALWAYS wrap native GPU textures directly into Skia/Skiko backend texture structures (e.g., org.jetbrains.skia.Image.makeFromTexture or platform Metal/Vulkan equivalents) without copying raw pixel data to the JVM/Native heap.

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.