How it works
A small stable-fluids wake carries two numbers per texel, how much dye is there and how old it is, so its colour is literally its history: white-hot where the cursor just passed, cooling through the palette as it curls away. That HDR light then goes through the stack a film camera would add: a mip-chain bloom that stays steady on hair-thin strands, a light behind the cursor that escapes only through the gaps in the wake as shafts, spectral fringes that spike with speed, lens dirt, grain and a filmic tonemap. Every post pass can be switched off from the stage or the panel, and the View menu shows each buffer on its own.
Pipeline (per frame)
Sizes for a 2560×1440 canvas. S = sim grid 228×128, D = dye 1820×1024, F = canvas.
FIXED 60 Hz STEP (a 120 Hz screen runs it every other frame)
pointer ─▶ brush spring (ω 52 rad/s, 4 sub-steps) ─▶ 4 short segments along a smooth curve
├─[grip splat] bbox quad, blend SRC_ALPHA: v = mix(v, 0.7·v_brush, w·0.34) ─────▶ vel S RG16F
├─[dye splat] bbox quad, blend ONE,ONE: swept-Gaussian (erf) × filaments ──▶ dye D RG16F
│ .r = d (density) .g = d·age (new dye adds age 0)
├─[curl] vel ─▶ curl S R16F
├─[vorticity] ε·ω·(N.y, −N.x) ─▶ vel
├─[viscosity ×6] Jacobi (I − ν·dt·∇²) v = v₀, ν 40 ─▶ visc
├─[divergence] ½ central differences, open edges ─▶ div S R16F
├─[pressure ×16] red-black SOR ω 1.8, warm start ×0.8, p = 0 outside ─▶ p S R16F
├─[gradient] v = visc − ½∇p ─▶ vel
├─[MacCormack ×2] dye ─A▶ tmp ─B▶ dye: clamp to the 4 source texels, ×e^(−fade·dt), g += d·dt
└─[advect vel] semi-Lagrangian, ×e^(−0.55·dt)
EVERY RENDERED FRAME
├─[emission] dye ─▶ B0 F/4 640×360 RGBA16F
│ 16-tap supersample → 4 boxes, Karis 1/(1+luma) → soft knee → sanitise
├─[down ×5] 13-tap COD:AW kernel ─▶ 320×180 … 20×11 (levels from resolution)
├─[up ×5] 3×3 tent, blend lerp(radius): 20×11 ─▶ … ─▶ 320×180 ─▶ B0 (= the bloom)
├─[ray mask] dye ─▶ R0 F/4 640×360: gaps only = clear texel (4 taps) × wake around it
│ (8-tap ring, 1.2 brush widths) × hollow light field at the smoothed pointer
├─[rays ×2] radial blur toward the light: 28 long taps, jittered start ─▶ F/4,
│ then 28 short ─▶ F/4
└─[composite] ─▶ canvas F 2560×1440 (RGBA8, opaque)
emission: 5–8 jittered spectral taps on E/(1+E) (lens + fluid-velocity
offset, none across the white-hot head) + bloom (lens R/B split)
+ rays (soft contrast) + dirt × wide mip ─▶ exposure ─▶ vignette
─▶ hue-preserving ACES (per-channel on the hot head) ─▶ sRGB
─▶ clear zone behind the copy ─▶ screen over page colour
─▶ 24 Hz grain ─▶ TPDF dither
31 draws per sim step + 15 per frame ≈ 46 draws at 60 Hz
The ideas that matter
- Age is a second dye channel. Every texel stores
dandd·age. A splat adds density with age 0, and the second MacCormack pass addsd·dtto the age channel every step. Where a fresh stroke crosses old dye, the mixture's average age drops and it reheats. This is the research notes'd·birthTimetrick, rebased so there is no clock: a birth time would wrap and lose precision in half floats, while an age never grows past the dye's few seconds of life. - Deposit is an exact swept Gaussian. Each segment of the brush path adds
exp(−q²/σ²)·½[erf(s/σ) − erf((s−L)/σ)], the closed-form exposure of a Gaussian brush dragged along a line. Line integrals add, so consecutive segments tile with no bump at the joints, and density per unit of path is the same at any speed or frame rate. A cursor resting in one place deposits nothing, so it never builds a blob. - Light without haze, white only at the head. Emission is cut with a narrow
smoothstep(0.07, 0.2, d), so faint dye disappears instead of fogging. Inside the cut, brightness follows strand crests, so each strand has a bright core and a dimmer rim, like a neon tube. Only about the first 0.15 s of a stroke (at the default age span) is the hot colour, and the head gets a 3.4× HDR flash that decays over the same time: enough to bloom past white, while the cooling colour shows right behind it. The tonemap is mostly hue-preserving: the brightest channel goes through the ACES curve and the colour is scaled with it, so a bright cyan stays cyan. Per-channel ACES, which bleaches bright colour toward white, is blended back in only where the dye is white-hot or the light is far above 1. - Bloom that doesn't shimmer. Thin, bright, moving filaments are the classic way to make bloom flicker: a sub-pixel strand lands in a texel one frame and between texels the next. The prefilter therefore supersamples emission on a 4×4 grid over each quarter-resolution texel and combines the four 2×2 boxes with Karis weights
1/(1+luma), so no single hot sample can dominate. The chain below it uses Jimenez's 13-tap downsample and a 3×3 tent upsample, lerped level by level (radius), so the result is an energy-normalised multi-scale blur. The Prefilter control swaps in a single tap for comparison. To measure it: View set to Bloom, radius 0 (so the buffer is the prefilter level itself), Width at its minimum so the strands are thinner than a bloom texel, then a slow drag of 0.7 CSS px per frame while 30 consecutive frames of the canvas centre are read back. The mean absolute second difference between frames was 0.38–0.39% of the signal with Karis 16-tap and 0.42–0.54% with a single tap, so about a quarter less frame-to-frame jitter. At the default width the two are hard to tell apart; the supersampling matters most on hair-thin strands. The mip count comes from the resolution (Froyok's point), so the haze covers the same share of the screen on a phone and on a 5K display. - God-rays come only through the gaps. The screen-space radial blur (Mitchell, GPU Gems 3) turns every lit texel into a streak pointing away from the light. Feed it a whole light disc and you get a fog ball. Feed it only the openings in the wake and you get shafts. The ray mask therefore lights a texel only if it is clear itself (four rotated-grid taps of the dye) and has wake around it (eight taps on a ring 1.2 brush widths out), inside a light field on a lazier spring behind the brush. Open space has no wake around it and stays dark, and dye is opaque, so what streams out are the slits between filaments and the holes inside curls (Pavel Dobryakov's sunrays mask, with the light moved to the pointer and the open sky taken out). The field is hollow at its centre, because a gap right at the light would scatter evenly in every direction and read as a glow. One long pass with a per-pixel jittered start and one short box pass spanning one long-pass step give smooth streaks with no dotted moiré. A soft contrast curve,
r²/(r + 0.12), drops the faint scatter and keeps the shafts. The light follows cursor activity, fading in within 0.12 s and out over 0.8 s. - Aberration is spectral, and it's earned. Taps along the offset, weighted by red, green and blue bells and renormalised per channel, give smooth prism fringes with no tint on flat areas. Short fringes take 5 taps, long ones up to 8, with a static per-pixel jitter so a long fringe never breaks into stepped copies. Each tap is soft-compressed to
E/(1+E)before weighting and expanded after, so a 6× white tap can't pile into one channel and paint an orange flame on the leading edge. The white-hot head itself is never split: its fringes start where it has cooled. The offset has two parts: a lens term that grows with distance cubed from the centre, and the fluid's own velocity. The velocity term has a dead zone, so drifting old dye stays clean, and it is capped in CSS pixels. Both grow with a smoothed cursor-speed "spike" that fades over 0.45 s, so a fast flick flares and then settles. - Lens dirt only where there's light. The dirt texture (bokeh discs, hexagonal aperture ghosts, dust and finger smears) is drawn once with Canvas2D from a seeded random generator, so it needs no network. It is lit only by a wide bloom mip, so specks appear as the haze passes over them and a dark screen never looks dirty.
- The page colour stays exact, on average. Vignette and tonemap apply to the light only. The tonemapped light is then screened over the preset's background colour, so where there is no light the canvas averages exactly the CSS
--bgof the article below. Per pixel, grain and dither add ±1–3 LSB. Grain is keyed to 1.5 CSS pixels at 24 Hz and weighted toward the mid-tones, and a triangular dither of ±1 LSB removes banding from the dark haze. - The copy keeps a clear zone. The tight bounds of the headline, paragraph and pass chips are measured from the DOM on load and on resize. The composite turns the tonemapped light down to 38% inside that box, with a soft feather of 0.08 screen heights, so a stroke dragged under the text stays visible without burning out the words. The intro stroke and the gallery stroke keep to the other side of the stage anyway.
- The fluid is tuned for a wake, not smoke. Grip splats blend velocity toward 70% of the brush's speed instead of adding force, so dye is left behind as a trail rather than fired forward as a jet. Implicit viscosity keeps the swirls big and lazy. The projection is the standard collocated scheme of GPU Gems ch. 38: ½ central differences for divergence and gradient, with the compact 5-point Laplacian in the solve. Red-black SOR converges it 2 to 4 times faster per pass than Jacobi. The edges are open, so the wake flows off-screen instead of bouncing back. MacCormack advection with a min/max clamp keeps the filaments separate for their whole life. The step is fixed at 60 Hz, so a 120 Hz display looks identical. The ghost stroke surges through the centre of its figure-eight at four times the speed it has at the lobe tips, so each tip rolls the jet it just fired into eddies, and it crosses its own wake about 1.9 s in to show the reheat.
Parameters
Presets
Performance & compatibility
- GPU time at 2560×1440 (1280×720 at 2×, M-series Mac, Chrome on ANGLE-Metal, timed with
EXT_disjoint_timer_query_webgl2during the harness sweep): the quietest full harness run read a mean of 4.5 ms and a p95 of 7.0 ms. The GPU was shared with other effects being verified for every measurement of this version, so treat that as an upper bound. Other runs read means of 5.3–10 ms, with p95 up to 17 ms when three harnesses overlapped. JS costs 0.07–0.1 ms per frame, with no allocation in the frame loop. In six alternating runs in one session, the best full-stack mean was 5.8 ms and the best with all four post passes off was 3.7 ms (the sim, the dye advection and the composite). So bloom, god-rays, aberration and dirt together cost roughly 2 ms. - What scales it: the composite and the god-ray passes scale with canvas pixels (the mask and both blurs run at a quarter of its size). Dye advection scales with dye resolution, which is capped at 1024 on the short side, 720 on touch devices and 400 in the gallery thumbnail. The sim grid stays at 128 on the short side whatever the screen size. Draw count is the real cost on tile-based GPUs, which is why the prefilter and first downsample are a single pass.
- Requirements: WebGL2 with
EXT_color_buffer_float(RG16F, R16F and RGBA16F render targets with blending). Without them the page shows its poster frame and a short explanation instead of a broken canvas. - Mobile: at 390×844 the canvas is 780×1688 (DPR capped at 2), the dye is 720×1558, the pressure solve drops to 12 passes and the bloom chain to 4 levels. In phone emulation on the shared desktop GPU, the median GPU frame read 5.5–9 ms (one outlier at 14 ms) while other effects were being verified, and the harness's touch-drag run measured 46–48 fps. It has not been timed on a physical phone. Touch drags drive the brush; the canvas sits under the page content and never captures clicks.
- Lifecycle: rendering stops once the thickest dye (capped at d = 2.2) has faded below the alpha cut, about 8 s after the last stroke at the default Fade, and never sooner than 7 s after the last movement. It also pauses off-screen and in hidden tabs. A resize resamples the dye and velocity into the new targets, so the wake survives it.
- Reduced motion: it renders one still from 150 steps of the ghost stroke, with the hot head, bloom and rays, and offers "Play anyway". Changing a colour or post control re-renders the still.
- Dark backgrounds only, by design: bloom and god-rays add light. On a light page they wash out to pastel, so all three presets are dark. For light pages use a surface-shaded fluid from the library instead.
References & credits
- Written from scratch for this library; no third-party code is included. Research notes:
research/distortion-glass-post.md(bloom, chromatic aberration, grain) andresearch/eulerian-fluids.md(solver, MacCormack, the Prism Wake candidate). - Jorge Jimenez, "Next Generation Post Processing in Call of Duty: Advanced Warfare", SIGGRAPH 2014: the 13-tap downsample and firefly handling. iryoku.com. Slides, no software licence (ideas only).
- Brian Karis, "Tone mapping" (2013): the luma-weighted average used against fireflies. graphicrants.blogspot.com. Blog post, no software licence (ideas only).
- LearnOpenGL, "Physically Based Bloom" (2022 guest article): the progressive tent upsample. Its code is CC BY-NC 4.0; only the ideas were used. learnopengl.com
- Froyok, "Custom bloom post-process in Unreal Engine" (2021): the lerp ("scatter") composite and mip count from resolution. froyok.fr. Blog post, no software licence (ideas only).
- keijiro/KinoBloom: the soft-knee threshold curve. github.com/keijiro/KinoBloom (MIT).
- Kenny Mitchell, "Volumetric Light Scattering as a Post-Process", GPU Gems 3 ch. 13: the radial-blur god-ray. developer.nvidia.com. Book chapter, no software licence (ideas only).
- Pavel Dobryakov, WebGL-Fluid-Simulation: the sunrays occlusion trick and the bloom-on-fluid structure. github.com/PavelDoGreat/WebGL-Fluid-Simulation (MIT).
- Krzysztof Narkowicz, "ACES Filmic Tone Mapping Curve" (2016): the tonemap fit. knarkowicz.wordpress.com. Blog post, no software licence stated; only the published fit coefficients are used.
- Mark Jarzynski and Marc Olano, "Hash Functions for GPU Rendering", JCGT 2020: the pcg2d hash behind the grain, dither and aberration jitter. jcgt.org. Paper under CC BY-ND 3.0; the hash is reimplemented from its description.
- Jos Stam, "Stable Fluids" (SIGGRAPH 1999), dgp.toronto.edu. Mark Harris, "Fast Fluid Dynamics Simulation on the GPU", GPU Gems ch. 38, developer.nvidia.com. Fedkiw, Stam and Jensen, "Visual Simulation of Smoke" (2001), for vorticity confinement, web.stanford.edu. Papers and a book chapter, no software licence (ideas only).
- Selle, Fedkiw, Kim, Liu and Rossignac, "An Unconditionally Stable MacCormack Method" (2008): the advection scheme and clamp limiter. yingjie.math.gatech.edu. Paper, no software licence (ideas only).
- Sergei Winitzki, "Uniform approximations for transcendental functions" (ICCSA 2003, LNCS 2667), doi.org/10.1007/3-540-44839-X_82: the global Padé form of the erf used in the swept-brush deposit. The constant a = 0.147 comes from his 2008 note "A handy approximation for the error function and its inverse". Paper and note, no software licence (a published formula).