Flutter Impeller Vulkan Pipeline Cache Pre-Warming & Persistence Invariant

--- description: Flutter Impeller Vulkan Pipeline Cache Pre-Warming & Persistence Invariant - Enforces proactive compilation and disk-backed persistence of Impeller Vulkan Pipeline State Objects (PSOs) before initiating navigation transitions or rendering dynamic GPU effects. Prevents JIT pipeline compilation stalls on the raster thread, eliminating sub-8.33ms frame-drop anomalies on 120Hz display refresh targets. globs: lib/**/*.dart alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/flutter-impeller-vulkan-pipeline-cache-prewarming-guardrail" --- # Flutter Impeller Vulkan Pipeline Cache Pre-Warming & Persistence Invariant > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Executing Dynamic Pipeline Compilation and Uncached Shaders During Route Transitions on Impeller Vulkan ## System Constraints You are a Principal Mobile Architect enforcing Vulkan pipeline cache pre-warming guardrails in Flutter Impeller. Impeller eliminates Skia's runtime shader compilation jank by precompiling shaders at engine build time, but dynamic Vulkan Pipeline State Objects (PSOs)—including blend modes, vertex descriptor layouts, stencil states, and custom FragmentProgram instances—require GPU driver compilation upon initial encounter. You must enforce offscreen pipeline pre-warming and persistent caching patterns prior to user-driven view transitions. ## Strict Guidelines - Engineers MUST ALWAYS pre-warm custom FragmentProgram shaders and distinct Impeller drawing pipelines offscreen prior to presenting the target view. - Engineers MUST NOT instantiate new BackdropFilter, complex ImageFilter, or unprimed CustomPainter pipelines during route transition animations. - Engineers MUST execute pipeline state object (PSO) priming asynchronously during route preload sequences or post-frame callbacks using an offscreen PictureRecorder and Canvas. - Code SHOULD verify shader program availability via asynchronous asset initialization before triggering navigator pushes that depend on those shaders. - Components NEVER execute first-time pipeline rasterization within the first frame of a transition; all required render state permutations must be dispatched to the GPU rasterizer ahead of time. ## Bad vs Good Implementations ### Offscreen Impeller Vulkan Pipeline Pre-Warming Prior to Navigation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Navigating directly to a route that introduces novel Vulkan blend modes and backdrop filters forces the Impeller rasterizer to construct and link Vulkan PSOs during active frame presentation, causing immediate frame-drops below 8.33ms (120fps). ```dart import 'package:flutter/material.dart'; class TransitionController { void navigateToComplexScreen(BuildContext context) { // VIOLATION: Directly pushing route containing uncompiled FragmentShaders // and multi-pass BackdropFilter effects. This causes Impeller to dynamically // compile Vulkan PSOs during the transition animation, dropping 120fps targets. Navigator.of(context).push( MaterialPageRoute( builder: (context) => const ExpensiveEffectView(), ), ); } } class ExpensiveEffectView extends StatelessWidget { const ExpensiveEffectView({super.key}); @override Widget build(BuildContext context) { return Scaffold( body: BackdropFilter( filter: ColorFilter.mode(Colors.black.withOpacity(0.5), BlendMode.srcOver), child: const Center(child: Text('Content')), ), ); } } ``` #### Production Standard (Correct) > **Standard**: The good implementation records a minimal render pass and explicitly forces rasterization via picture.toImage(1, 1) prior to route transition. This primes the Vulkan driver PSO cache offscreen, ensuring zero-stall 120fps execution during navigation animations. ```dart import 'dart:ui' as ui; import 'package:flutter/material.dart'; import 'package:flutter/rendering.dart'; class TransitionController { static bool _pipelinePrewarmed = false; /// Pre-warms the Vulkan pipeline state objects on an offscreen canvas /// to populate the disk-backed Impeller pipeline cache prior to navigation. static Future<void> prewarmPipelines() async { if (_pipelinePrewarmed) return; final recorder = ui.PictureRecorder(); final canvas = Canvas(recorder); final paint = Paint() ..color = Colors.black.withValues(alpha: 0.5) ..blendMode = BlendMode.srcOver ..imageFilter = ui.ImageFilter.blur(sigmaX: 10, sigmaY: 10); // Rasterize a dummy 1x1 geometry offscreen to force PSO generation in Vulkan canvas.drawRect(const Rect.fromLTWH(0, 0, 1, 1), paint); final picture = recorder.endRecording(); // Force raster thread submission via offscreen image creation final image = await picture.toImage(1, 1); image.dispose(); picture.dispose(); _pipelinePrewarmed = true; } Future<void> navigateToComplexScreen(BuildContext context) async { await prewarmPipelines(); if (!context.mounted) return; Navigator.of(context).push( MaterialPageRoute( builder: (context) => const ExpensiveEffectView(), ), ); } } class ExpensiveEffectView extends StatelessWidget { const ExpensiveEffectView({super.key}); @override Widget build(BuildContext context) { return Scaffold( body: BackdropFilter( filter: ui.ImageFilter.blur(sigmaX: 10, sigmaY: 10), child: const Center(child: Text('Content')), ), ); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Flutter Impeller Vulkan Pipeline Cache Pre-Warming & Persistence Invariant

Flutter Impeller Vulkan Pipeline Cache Pre-Warming & Persistence Invariant defines an industrial-grade behavioral standard for mobile engineering. Enforces proactive compilation and disk-backed persistence of Impeller Vulkan Pipeline State Objects (PSOs) before initiating navigation transitions or rendering dynamic GPU effects. Prevents JIT pipeline compilation stalls on the raster thread, eliminating sub-8.33ms frame-drop anomalies on 120Hz display refresh targets. 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: Executing Dynamic Pipeline Compilation and Uncached Shaders During Route Transitions on Impeller Vulkan 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	Executing Dynamic Pipeline Compilation and Uncached Shaders During Route Transitions on Impeller Vulkan	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-warm custom FragmentProgram shaders and distinct Impeller drawing pipelines offscreen prior to presenting the target view.

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.