Compose Multiplatform Skiko Render Buffer Preallocation Invariant

--- description: Compose Multiplatform Skiko Render Buffer Preallocation Invariant - Enforces deterministic off-screen texture buffer reuse and bounds pre-allocation across Skiko Metal (iOS) and OpenGL/DirectX (desktop) targets. Eliminates main-thread frame pacing anomalies and JNI/interop garbage generation caused by dynamic image/surface allocations during active render draw loops. globs: **/*Visualizer*.kt, **/*Canvas*.kt, **/*Render*.kt, **/skiko/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/compose-skiko-render-buffer-preallocation-standard" --- # Compose Multiplatform Skiko Render Buffer Preallocation Invariant > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: On-demand allocate-and-destroy cycles of org.jetbrains.skia.Image or Surface instances inside drawBehind, Canvas, or custom SkikoLayer render loops. ## System Constraints You are a Principal Engineer enforcing the Compose Multiplatform Skiko Render Buffer Preallocation Invariant. You must reject any on-demand buffer, bitmap, or surface allocations inside compose draw phases or Skiko frame callbacks. Enforce bounded object pools and pre-sized native textures with explicit deallocation hooks. ## Strict Guidelines - Engineers MUST ALWAYS pre-allocate off-screen org.jetbrains.skia.Surface or org.jetbrains.skia.Bitmap instances within a remember or disposable lifecycle block outside the draw pass. - Engineers MUST NOT invoke Surface.makeRaster, Surface.makeRenderTarget, Image.makeFromBitmap, or Skia native texture factories inside DrawScope, Canvas, or Skiko render loop lambdas. - Code SHOULD dynamically resize cached buffer textures strictly upon container dimension changes (e.g., onSizeChanged) rather than on individual frame draw evaluations. - Services MUST recycle or release GPU-backed native buffers via AutoCloseable.close() or explicit Dispose callbacks before re-allocating or re-assigning pooled texture slots. - Components NEVER trigger synchronous native JNI/Cinterop allocations while rendering on 120Hz ProMotion (iOS) or high-refresh rate desktop Skiko targets. ## Bad vs Good Implementations ### Skiko Off-Screen Buffer Lifecycle in High-Frequency Canvas #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Creating native Skia surfaces and capturing snapshots inside the hot draw path causes massive JNI/cinterop memory churn, frame drops, and Metal resource exhaustion on iOS. ```kotlin @Composable fun WaveformVisualizer(pcmData: FloatArray, modifier: Modifier = Modifier) { Canvas(modifier = modifier.fillMaxSize()) { // CRITICAL DEFECT: Allocating a native Skia Surface on every frame tick (120Hz/60Hz) // triggers native heap churn, GC thrashing, and Metal command buffer stalls. val surface = Surface.makeRasterN32Premul(size.width.toInt(), size.height.toInt()) val canvas = surface.canvas canvas.clear(Color.TRANSPARENT) drawWaveform(canvas, pcmData) val image = surface.makeImageSnapshot() // Triggers secondary native texture copy drawImage(image.toComposeImageBitmap()) surface.close() image.close() } } ``` #### Production Standard (Correct) > **Standard**: Allocates native Skia surfaces strictly when viewport dimensions mutate, binds disposal to the Compose lifecycle, and eliminates per-frame texture creations by rendering directly to the native target canvas. ```kotlin @Composable fun WaveformVisualizer(pcmData: FloatArray, modifier: Modifier = Modifier) { var viewportSize by remember { mutableStateOf(IntSize.Zero) } // Pre-allocated managed buffer retained across frames val pooledBuffer = remember(viewportSize) { if (viewportSize.width > 0 && viewportSize.height > 0) { Surface.makeRasterN32Premul(viewportSize.width, viewportSize.height) } else null } DisposableEffect(pooledBuffer) { onDispose { pooledBuffer?.close() } } Canvas( modifier = modifier .fillMaxSize() .onSizeChanged { viewportSize = it } ) { val surface = pooledBuffer ?: return@Canvas val canvas = surface.canvas canvas.clear(Color.TRANSPARENT) drawWaveform(canvas, pcmData) // Draws directly into hardware Canvas avoiding intermediate snapshot allocations drawIntoCanvas { nativeCanvas -> surface.draw(nativeCanvas.nativeCanvas, 0f, 0f, null) } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Compose Multiplatform Skiko Render Buffer Preallocation Invariant

Compose Multiplatform Skiko Render Buffer Preallocation Invariant defines an industrial-grade behavioral standard for mobile engineering. Enforces deterministic off-screen texture buffer reuse and bounds pre-allocation across Skiko Metal (iOS) and OpenGL/DirectX (desktop) targets. Eliminates main-thread frame pacing anomalies and JNI/interop garbage generation caused by dynamic image/surface allocations during active render draw loops. 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: On-demand allocate-and-destroy cycles of org.jetbrains.skia.Image or Surface instances inside drawBehind, Canvas, or custom SkikoLayer 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	On-demand allocate-and-destroy cycles of org.jetbrains.skia.Image or Surface instances inside drawBehind, Canvas, or custom SkikoLayer 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 pre-allocate off-screen org.jetbrains.skia.Surface or org.jetbrains.skia.Bitmap instances within a remember or disposable lifecycle block outside the draw pass.

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.