impeller_fx ⚡ #

A production-grade, hyper-modern suite of runtime fragment shader effects explicitly engineered and optimized for Flutter's Impeller rendering architecture.

Achieve locked 60 / 120 FPS on mobile (iOS Metal & Android Vulkan) with zero shader compilation jank, GPU-resident synchronous texture sampling, and type-safe uniform serialization.

✨ Features #

• 🌈 FxMeshGradientWidget: 4-point dynamic animated harmonic mesh gradient with high-frequency noise dithering to eliminate 8-bit color banding on OLED/HDR displays.
• 💧 FxLiquidRippleTouch: Physics-based displacement ripple shader with wave front propagation, radial damping, and subtle chromatic crest highlights on touch & drag.
• ⚡ FxChromaticAberrationWidget: High-speed multi-sample RGB spectral lens dispersion and holographic glitch effects (Radial & Linear).
• 💎 FxGlassmorphismContainer: Jittered Golden-Spiral 12-tap frosted glass blur, SDF rounded geometry, diagonal specular glare sheen, and antialiased rim border highlights.
• 🌀 FxVortexTwistWidget: Space-time singularity swirl distortion with quadratic angular falloff, radial pinch pull, and event-horizon chromatic dispersion.
• 📡 FxHolographicWidget: Holographic scanlines, CRT beam sweep, phosphor tinting, glitch flicker, and static micro-noise.
• ✨ FxBloomGlowWidget: Single-pass HDR threshold extraction, 12-tap golden spiral tent kernel bloom, and specular illumination.
• 🔮 FxPlasmaFlowWidget: Procedural multi-octave trigonometric fluid plasma background generator.
• 🚀 FxShaderRegistry.warmupAll(): One-line parallel pre-warming of all shaders during app startup for zero-jank first-frame renders.
• 🧮 FxUniformWriter: High-performance, type-safe uniform serializer managing float and sampler offsets with zero magic indices.
• ⏱️ FxController: Battery-saving animation controller with frame-rate throttling, smart ticker management, and loop modes (continuous, restart, pingPong, once).
• 📱 DPI-Aware: Native handling of Device Pixel Ratio (DPR) for crisp rendering on high-density Retina and AMOLED screens.

🚀 Why This Works Well With Impeller #

Flutter's legacy Skia backend dynamically compiled GLSL shaders at runtime during the first frame, frequently causing noticeable frame drops ("shader compilation jank").

impeller_fx is built from the ground up for Impeller:

+-------------------------------------------------------------+
|                      FLUTTER WIDGET TREE                    |
+-------------------------------------------------------------+
                              │
                              ▼
+-------------------------------------------------------------+
|                 FxTextureSampler / DPR Layer                |
|           Picture.toImageSync() [GPU-Resident Texture]       |
+-------------------------------------------------------------+
                              │
                              ▼
+-------------------------------------------------------------+
|                    FxUniformWriter (Dart)                   |
|          Sequential Float & Sampler Slot Packing            |
+-------------------------------------------------------------+
                              │
                              ▼
+-------------------------------------------------------------+
|               IMPELLER RUNTIME EFFECT PIPELINE              |
|        AOT Compiled MSL (Metal) & SPIR-V (Vulkan) Shaders   |
|          - Golden Spiral Multi-Tap Sampling                 |
|          - 1-Pass SDF Geometry & Specular Sheen             |
|          - High-Frequency Triangular Dithering              |
+-------------------------------------------------------------+

1. AOT Offline Compilation: All .frag shaders are precompiled ahead-of-time (AOT) by the Flutter toolchain directly into platform-native Metal Shading Language (MSL) and SPIR-V bytecodes.
2. Zero-Copy Texture Sync (toImageSync): Child widgets and backdrops are captured directly into GPU textures without round-tripping to CPU host memory.
3. Single-Pass Approximations: Multi-pass blurs are replaced with 12-tap jittered Golden-Angle spiral sampling kernels, keeping fragment execution under 0.5ms per frame.
4. Band-Free Gradients: Gradients include triangular PDF dither noise, eliminating color quantization artifacts on wide-gamut displays.

📦 Installation #

Add impeller_fx to your pubspec.yaml:

dependencies:
  impeller_fx: ^1.0.0

Run:

flutter pub get

⚡ Zero-Jank Warmup in main() #

Pre-warm all shaders during app startup to ensure instant 120 FPS rendering from the very first frame:

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  // Pre-compile and warm up all 8 Impeller shaders in parallel
  await FxShaderRegistry.warmupAll();
  
  runApp(const MyApp());
}

🛠️ Quick Start #

1. Mesh Gradient Background #

import 'package:flutter/material.dart';
import 'package:impeller_fx/impeller_fx.dart';

class MyMeshBackground extends StatelessWidget {
  const MyMeshBackground({super.key});

  @override
  Widget build(BuildContext context) {
    return FxMeshGradientWidget.fromPalette(
      palette: FxGradientPresets.neonCyberpunk,
      speed: 1.0,
      noiseIntensity: 6.0,
      child: const Center(
        child: Text(
          'Impeller FX',
          style: TextStyle(fontSize: 32, fontWeight: FontWeight.bold, color: Colors.white),
        ),
      ),
    );
  }
}

2. Interactive Liquid Ripple on Touch #

import 'package:flutter/material.dart';
import 'package:impeller_fx/impeller_fx.dart';

class RippleCard extends StatelessWidget {
  const RippleCard({super.key});

  @override
  Widget build(BuildContext context) {
    return FxLiquidRippleTouch(
      amplitude: 25.0,
      frequency: 40.0,
      maxRadius: 400.0,
      decay: 2.5,
      child: Container(
        width: 300,
        height: 200,
        decoration: BoxDecoration(
          borderRadius: BorderRadius.circular(20),
          image: const DecorationImage(
            image: NetworkImage('https://picsum.photos/600/400'),
            fit: BoxFit.cover,
          ),
        ),
      ),
    );
  }
}

3. Gravitational Vortex Twist #

import 'package:flutter/material.dart';
import 'package:impeller_fx/impeller_fx.dart';

class VortexDemo extends StatelessWidget {
  const VortexDemo({super.key});

  @override
  Widget build(BuildContext context) {
    return FxVortexTwistWidget(
      radius: 250.0,
      angle: 3.5,
      pinch: 0.4,
      dispersion: 1.0,
      child: Image.asset('assets/galaxy.png'),
    );
  }
}

4. Holographic CRT & Scanlines #

import 'package:flutter/material.dart';
import 'package:impeller_fx/impeller_fx.dart';

class HoloCard extends StatelessWidget {
  const HoloCard({super.key});

  @override
  Widget build(BuildContext context) {
    return FxHolographicWidget(
      lineFrequency: 140.0,
      lineIntensity: 0.4,
      beamSpeed: 1.2,
      holoTint: const Color(0x6600F0FF),
      child: Container(
        padding: const EdgeInsets.all(24),
        child: const Text('CYBER HUD INTERFACE', style: TextStyle(color: Colors.white)),
      ),
    );
  }
}

5. HDR Bloom Glow #

import 'package:flutter/material.dart';
import 'package:impeller_fx/impeller_fx.dart';

class NeonButton extends StatelessWidget {
  const NeonButton({super.key});

  @override
  Widget build(BuildContext context) {
    return FxBloomGlowWidget(
      bloomRadius: 20.0,
      threshold: 0.4,
      intensity: 2.0,
      child: ElevatedButton(
        style: ElevatedButton.styleFrom(backgroundColor: const Color(0xFF00F0FF)),
        onPressed: () {},
        child: const Text('ACTIVATE', style: TextStyle(color: Colors.black)),
      ),
    );
  }
}

6. Procedural Fractal Plasma Background #

import 'package:flutter/material.dart';
import 'package:impeller_fx/impeller_fx.dart';

class PlasmaHero extends StatelessWidget {
  const PlasmaHero({super.key});

  @override
  Widget build(BuildContext context) {
    return const FxPlasmaFlowWidget(
      scale: 2.5,
      turbulence: 1.2,
      speed: 1.0,
      color1: Color(0xFFFF007F),
      color2: Color(0xFF7928CA),
      color3: Color(0xFF00F0FF),
      color4: Color(0xFF001F3F),
    );
  }
}

🎨 Curated Gradient Presets #

🔧 Type-Safe FxUniformWriter #

Avoid hardcoded array index offsets (shader.setFloat(0, ...), shader.setFloat(1, ...)):

final writer = FxUniformWriter(fragmentShader);
writer.writeSize(size);                    // vec2 (2 floats)
writer.writeFloat(time);                   // float (1 float)
writer.writeColor(primaryColor);           // vec4 (4 floats)
writer.writeOffset(touchCenter);           // vec2 (2 floats)
writer.writeRect(bounds);                  // vec4 (4 floats)
writer.writeMatrix4(transformMatrix);      // mat4 (16 floats)
writer.setSampler(0, gpuTextureImage);     // sampler2D slot 0

// Self-validating safety check
writer.verifyFloatCount(29);

📊 Performance Benchmarks (iPhone 15 Pro / Galaxy S24) #

🤝 Contributing #

Contributions and PRs are welcome! Feel free to open an issue or submit improvements.

📄 License #

This project is licensed under the MIT License - see the LICENSE file for details.