Features #

• Zero-Jank Architecture: Heavy 3D math and vertex projections run in a background Isolate for sustained 60/120 FPS.
• Hardware-Accelerated Shaders: High-performance GPU fragment shaders for fluid color gradients and shimmer effects.
• 9 Procedural Noise Models: Smooth waves, spiky crystals, cosmic vortex, cellular bubbles, carpet nets, and custom math formulas.
• Fluid Touch Interaction: Natural drag rotation, mouse hover tracking, and tap dispersion with customizable hit testing.
• Zero-Allocation Pipeline: Pre-allocated typed buffers prevent Garbage Collection (GC) pauses during animation.
• Single GPU Draw Call: Flattens and renders thousands of particles in a single call via Canvas.drawRawPoints.

What's New #

• Real 3D Colors (uColor3D): Shader gradients now rotate and turn with the 3D blob in real-time instead of staying fixed like a flat 2D wallpaper.
• Depth Sorting (enableDepthSort): Back-to-front $O(N)$ sorting ensures front particles properly cover rear ones, removing visual glitching.
• Atmospheric Depth-Cueing (enableDepthCueing): Distant particles scale down and softly fade, creating authentic depth and volume.
• Responsive Auto-Fit (autoFit): Automatically resizes the blob to fit any screen, container, or device orientation without manual pixel calculations.
• Fast Web Performance (isComplex): Alternates calculation frames on Flutter Web to keep single-threaded JavaScript smooth and responsive.
• Smart Battery Saver: Automatically sleeps (0% CPU & GPU) when scrolled offscreen, when the app is minimized, or when navigating to another page.

Quick Start #

1. Install #

flutter pub add blob_flutter

2. Import #

import 'package:blob_flutter/blob_flutter.dart';

3. Use #

The simplest way to render a basic Blob:

// 1. Basic Blob with Fixed Radius
BlobFlutter(
  particleCount: 5000,
  radius: 150.0,
  pointSize: 2.0,
  noiseType: BlobNoiseType.harmonic,
  gradient: const LinearGradient(
    colors: [Colors.cyanAccent, Colors.purpleAccent],
  ),
)

// 2. Fully Responsive Blob with 3D Depth Sorting & Depth-Cueing
BlobFlutter(
  particleCount: 5000,
  autoFit: true, // Automatically resizes radius to fit parent bounds
  radiusFactor: 0.85,
  enableDepthSort: true, // Linear O(N) back-to-front depth sorting
  enableDepthCueing: true, // Realistic atmospheric perspective attenuation
  noiseType: BlobNoiseType.harmonic,
  gradient: const LinearGradient(
    colors: [Colors.cyanAccent, Colors.purpleAccent],
  ),
)

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 9 distinct mathematical displacement models using the BlobNoiseType enum:

Custom Procedural Noise & 3D Math Engine #

With BlobNoiseType.custom, you have complete creative freedom to sculpt custom 3D geometries, pulsating crystals, hollow toruses, swirling spirals, or bespoke mathematical motions.

1. Custom Noise Function Signature #

A custom noise function evaluates per-particle displacement in 3D space:

typedef BlobCustomNoiseFunction = double Function(
  double px,        // Particle X on unit sphere (-1.0 to 1.0)
  double py,        // Particle Y on unit sphere (-1.0 to 1.0)
  double pz,        // Particle Z on unit sphere (-1.0 to 1.0)
  double frequency, // noiseFrequency parameter
  double time,      // Animation time in seconds
  double blobiness, // Global deformation multiplier
);

2. Built-in Math Helpers in BlobMath #

BlobMath provides high-performance, allocation-free static utilities for sculpting 3D particles:

• BlobMath.azimuth(px, pz): Azimuthal angle $\phi = \text{atan2}(pz, px) \in [-\pi, \pi]$ (ideal for longitude/spiral twisting).
• BlobMath.elevation(py): Elevation angle $\theta = \text{asin}(py) \in [-\pi/2, \pi/2]$ with safe clamping against NaN.
• BlobMath.distance2D(x, z): Planar radial distance $\sqrt{x^2 + z^2}$ from the Y-axis.
• BlobMath.fastSimplex3D(x, y, z): High-speed Simplex 3D noise for organic, terrain-like surfaces.
• BlobMath.smoothstep(edge0, edge1, x): Hermite interpolation for smooth borders and transitions.
• BlobMath.clampDisplacement(val): Automatic safeguard against NaN or Infinity, clamping values safely to [0.05, 5.0].

3. Usage Examples #

Via BlobController:

final controller = BlobController(
  noiseType: BlobNoiseType.custom,
  customNoise: (px, py, pz, f, time, blobiness) {
    final double phi = BlobMath.azimuth(px, pz);
    return 1.0 + sin(phi * 4.0 + time) * 0.3 * blobiness;
  },
);

// Switch or update dynamically at runtime:
controller.setCustomNoise((px, py, pz, f, time, blobiness) {
  return 1.0 + BlobMath.fastSimplex3D(px * f, py * f, pz * f + time) * 0.35 * blobiness;
});

Via BlobFlutter Widget:

BlobFlutter(
  noiseType: BlobNoiseType.custom,
  customNoise: (px, py, pz, f, time, blobiness) {
    final double r = BlobMath.distance2D(px, pz);
    return 1.0 + cos(r * 8.0 * f - time * 3.0) * 0.25 * blobiness;
  },
)

4. Golden Rules for Glitch-Free Shapes #

1. The 1.0 Anchor: Displacements scale the unit sphere. Always write equations relative to 1.0 (e.g. 1.0 + (wave * blobiness)).
2. Safe from NaN & Isolate Closures: Custom noise closures run synchronously on the main thread (<0.5ms for 3,000 particles), allowing you to write any lambda or closure without Isolate serialization errors. All returns are automatically protected from NaN and Infinity.
3. Zero Heap Allocations: The function is invoked per-particle every frame. Keep all calculations on double primitives without instantiating objects or collections.

5. Practical Shape Recipes #

// 1. Classic 5-Point 3D Star
controller.setCustomNoise((px, py, pz, f, time, blobiness) {
  final double angle = atan2(py, px) + time * 0.4;
  final double star2D = max(0.0, cos(5.0 * angle));
  final double sharpPoints = pow(star2D, 2.5).toDouble();
  final double zProfile = max(0.0, 1.0 - pz.abs() * 2.0);
  return (0.45 + sharpPoints * zProfile * 1.5) * blobiness;
});


// 2. Saturn Planet & Glowing Equatorial Ring
controller.setCustomNoise((px, py, pz, f, time, blobiness) {
  final double yDist = py.abs();
  final double ring = yDist < 0.15 ? pow(0.9 - yDist / 0.35, 5.0).toDouble() * 1.5 : 0.0;
  return (0.55 + ring) * blobiness;
});

Customization Properties #

Widget Properties (BlobFlutter) #

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

Controller Properties (BlobController) #

Manipulate the blob dynamically at runtime using the controller methods.

(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. True 3D Object-Space Fragment Shaders (blob.frag): Rather than projecting flat 2D color coordinates across screen pixels, the GLSL fragment program reconstructs the 3D surface normal $\vec{n} = (\hat{p}_x, \hat{p}_y, \hat{p}_z)$ for each point and multiplies by the inverse pitch/yaw rotation matrix ($R^T$). Colors rotate synchronously with the 3D object in space.
3. $O(N)$ Linear Depth Bucket Sorting: To preserve 60/120 FPS without Garbage Collection pauses, the worker isolate sorts particles using a 64-bin linear bucket sort ($O(N)$ vs $O(N \log N)$ quicksort). Combined with 4-strata atmospheric depth-cueing in BlobPainter, particles render back-to-front with depth-dependent scale and opacity.
4. Single GPU Draw Call: Particle coordinates are flattened and drawn directly to graphics hardware using Canvas.drawRawPoints.
5. Zero Heap Allocation: Coordinate caches, depth sorting bins, and calculation buffers are pre-allocated during initialization, avoiding Garbage Collector (GC) stutters.
6. Web Temporal Striding (isComplex): On Flutter Web, where Dart executes on a single JavaScript event loop, temporal interleaving splits particle computations across alternating odd/even frames, reducing CPU execution time by 50% without visual stutter.
7. Ultra-Fast Path Engine: During steady-state animations (when no pointers or radial dispersions are active), the math loop transitions into an unbranched, streamlined execution path, eliminating redundant pointer and touch checks per frame.
8. Multi-Tier Zero-Battery Lifecycle: Tickers and isolate computations automatically shut down (0% CPU/GPU usage) when scrolled offscreen, when the app enters the background, or when navigating to another route via ModalRoute / RouteObserver.

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.