---

Features

• Zero-Jank Architecture: Offloads heavy 3D math and vertex projections to a persistent background Isolate.
• GPU Fragment Shaders: Hardware-accelerated per-pixel color gradients (Linear, Radial, Sweep) via custom GLSL.
• 8 Procedural Noise Models: Smooth liquid waves, crystalline spikes, cellular bubbles, and more.
• Fluid Touch Interaction: Natural multi-touch drag rotation, hover tracking, and tap dispersion.
• Zero-Allocation Pipeline: Pre-allocated buffers ensure zero heap object allocations during the render loop.
• Ultra-Fast Path Engine: Automatically switches to an unbranched, zero-overhead projection pipeline during non-interactive frames, eliminating tens of thousands of redundant pointer and dispersion checks per frame.
• Resource-Conscious Engineering: Crafted with rigorous mathematical precision to respect developers and end-user devices—maximizing performance while preventing battery drain and memory thrashing.
• Error Handling: Robust error handling to prevent crashes and provide meaningful error messages.

---

Quick Start

1. Install

Add blob_flutter to your pubspec.yaml dependencies:

dependencies:
  blob_flutter: ^1.0.0

2. Import

import 'package:blob_flutter/blob_flutter.dart';

3. Use

The simplest way to render a basic Blob:

BlobFlutter(
  particleCount: 5000,
  radius: 150.0,
  pointSize: 2.0,
  noiseType: BlobNoiseType.harmonic,
  gradient: const LinearGradient(
    colors: [Colors.cyanAccent, Colors.purpleAccent],
    begin: Alignment.topLeft,
    end: Alignment.bottomRight,
  ),
)

---

Controller Usage

For dynamic runtime control, use the BlobController. It allows you to morph geometry, change colors, and tweak physics on the fly.

class MyBlob extends StatefulWidget {
  @override
  _MyBlobState createState() => _MyBlobState();
}

class _MyBlobState extends State<MyBlob> {
  late BlobController _controller;

  @override
  void initState() {
    super.initState();
    _controller = BlobController(
      particleCount: 5000,
      radius: 150.0,
      noiseType: BlobNoiseType.simplex,
      dampingFactor: 0.95,
      isColorAnimated: true,
    );
  }

  @override
  void dispose() {
    _controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return GestureDetector(
      onDoubleTap: () => _controller.setNoiseType(BlobNoiseType.spiky),
      child: BlobFlutter(
        controller: _controller,
      ),
    );
  }
}

---

Procedural Noise Algorithms

Choose from 8 distinct mathematical displacement models using the BlobNoiseType enum:

Algorithm	Visual Characteristics	Best For
harmonic	Smooth, organic, fluid liquid blob motion.	Liquid effects, calm assistants
spiky	Sharp peaks, crystalline spikes, urchin geometry.	Audio visualizers, energetic UI
fractal	Multi-octave turbulent cloud and terrain details.	Complex, textured surfaces
cellular	Segmented clusters, biological cells, bubbles.	Organic, microscopic visuals
vortex	Swirling cyclone, spiral galaxy, tornado.	Loading spinners, portals
sphericalHarmonics	Acoustic cymatics, nodal patterns, quantum fields.	High-tech, futuristic UI
simplex	Omni-directional, artifact-free smooth flow.	Clean, continuous deformation
wave	Flat full square carpet/net with undulating wave ripples.	Floating wave nets, square carpets, audio grids

---

Customization Properties

Widget Properties (BlobFlutter)

Configure the initial state of your blob directly in the widget.

Property	Type	Default	Description
particleCount	int	5000	Total number of particles on the sphere (higher counts increase density but may affect performance).
radius	double	150.0	Base radius in logical pixels.
pointSize	double	2.0	Diameter of each rendered particle.
rotationX / rotationY	double	0.0	Initial base 3D orientation angles (pitch & yaw) in radians.
noiseType	Enum	harmonic	Procedural 3D noise algorithm used.
controller	BlobController?	null	External controller for runtime manipulation.
gradient	Gradient	Linear	Color gradient (Linear, Radial, or Sweep).
autoPlay	bool	true	Whether the animation loop starts automatically. Set to false for battery savings on static views or widget tests.

Controller Properties (BlobController)

Manipulate the blob dynamically at runtime using the controller methods.

Setter Method	Valid Range	Description
pause()	-	Stops the animation ticker completely (0% CPU/battery usage).
resume()	-	Resumes the animation loop if paused.
isPaused	true/false	Getter checking whether the animation loop is currently paused.
setParticleCount(val)	10 - 100000	Dynamically sets particle count (reallocates buffers).
setBlobiness(val)	0.0 - 5.0	Amplitude of noise displacement.
setSpeed(val)	0.0 - 10.0	Playback speed of the animation.
setRotationX(val) / setRotationY(val)	double (radians)	Sets persistent 3D orientation pitch & yaw angles.
setRotation({x, y})	double? (radians)	Sets both 3D orientation angles simultaneously.
setDispersion(val)	0.0 - 3.0	Outward radial displacement.
setNoiseFrequency(val)	0.1 - 5.0	Density of the noise ripples.
setNoiseType(type)	Enum	Changes the deformation algorithm.
setIsRainbowMode(bool)	true/false	Cycles colors through the HSV spectrum.
zoomIn(val) / zoomOut	-	Scales the blob size dynamically.

(Check the source code for a complete list of advanced physics and shader properties).

---

Architecture & Performance

BlobFlutter is built with deep respect for both developers and end-user hardware. Every mathematical model, buffer allocation, and render pass is calculated with exacting precision to deliver sustained 60 / 120 FPS while safeguarding device resources, thermals, and battery life:

1. Persistent Worker Isolate: 3D math, trigonometric deformations, and matrix rotations execute in a dedicated background worker (BlobWorker). The UI receives data via zero-copy TransferableTypedData.
2. Single GPU Draw Call: Particle coordinates are flattened and drawn directly to graphics hardware using Canvas.drawRawPoints.
3. Zero Heap Allocation: Coordinate caches and calculation buffers are pre-allocated during initialization, avoiding Garbage Collector (GC) stutters.
4. Hardware Shaders: Complex color interpolation and organic shimmer waves run entirely on the GPU via custom GLSL shaders (ui.FragmentProgram).
5. Resource-Conscious Loop: Calculations and render cycles are strictly optimized so device CPU/GPU cycles are never wasted on redundant processing.
6. Ultra-Fast Path for Automatic Frames: During steady-state animations (when no pointers or radial dispersions are active), the math loop transitions into an unbranched, streamlined execution path. By bypassing over 18,000 conditional pointer and touch checks per frame, single-threaded environments like Flutter Web and mobile CPU architectures achieve peak JIT optimization, lower thermals, and a rock-solid, sustained 60/120 FPS.

---

Error Handling

BlobFlutter provides actionable console diagnostics with automatic CPU fallback if shaders are unavailable. Catch issues programmatically or render custom fallback interfaces via onError and errorBuilder.

---