API reference

aster_blueprint::fluid

Pre-1.0: signatures are not frozen. Generated from rustdoc JSON of the compiled crate; rustdoc JSON format version 60. Only public items are listed.

Real-time 2D fluid simulation kernel (Stam-style "stable fluids").

One [Fluid] owns a fixed cols x rows grid (default 128 x 72) and advances it with a fixed timestep (default 1/60 s): forces and emitters, optional viscosity, a pressure projection with a fixed iteration count, semi-Lagrangian advection (optionally MacCormack-corrected and clamped), vorticity confinement and a dye field (RGB, or one scalar for a colour ramp) with dissipation. Velocity lives on a staggered (MAC) grid, so the projection is exact: the discrete divergence it leaves is the solver residual, with no checkerboard modes. Boundaries are walls or wrap-around, and static obstacles come from a rect/circle list or a boolean mask.

Guarantees:

  • Deterministic: the same config and the same inputs give the same bits ([Fluid::digest]). Only IEEE + - * / sqrt floor are used (no exp/sin/powf, whose results depend on the platform libm), the solver is single-threaded and its sweep order is fixed.
  • No per-step allocation: every buffer is allocated in [Fluid::new].
  • Units are resolution independent: positions are 0..=1 across the domain (x over the width, y over the height), lengths and velocities are in domain widths (a velocity of 0.5 crosses half the width per second), so the same scene looks alike at 64 x 36 and at 256 x 144.

The graph nodes (core.fluid.*.v1, see [crate::fluid_nodes]), the image renderer ([crate::fluid_render]) and the UI helpers (ui::fluid, ui::fluid_emitters) are all thin layers over this kernel. See docs/FLUID.md.

Structs

structaster_blueprint::fluid::Emitter

pub struct Emitter { /* see fields */ }

A continuous source, evaluated at the simulation time of every step: a jet (the velocity inside its radius relaxes towards dir) that also adds dye at rate per second. Position and direction can move with time.

Public fields

fieldtype
xf32
yf32
radiusf32
dir[f32; 2]Jet velocity, widths/s.
color[f32; 3]Dye colour as for [Splat::color].
ratef32Dye added per second at the centre (color * rate * dt per step).
jetf32How fast the velocity inside the radius relaxes to dir, per second.
sweepf32The jet direction swings by up to sweep radians either side, sweep_hz times a second.
sweep_hzf32
orbit[f32; 2]The position circles on an ellipse of radii orbit (widths) at orbit_hz.
orbit_hzf32
phasef32Phase offset in turns (0..1) of both oscillations.

Methods

  • fn at(x: f32, y: f32, radius: f32) -> Self — A white emitter at (x, y) with a jet pointing up.
  • fn dir(self, vx: f32, vy: f32) -> Self
  • fn color(self, r: f32, g: f32, b: f32) -> Self
  • fn rate(self, rate: f32) -> Self
  • fn jet(self, jet: f32) -> Self
  • fn sweep(self, radians: f32, hz: f32) -> Self — Swing the jet direction by radians either side, hz times a second.
  • fn orbit(self, rx: f32, ry: f32, hz: f32) -> Self — Move the source on an ellipse with radii rx, ry (widths), hz turns a second.
  • fn phase(self, turns: f32) -> Self
  • fn at_time(&self, t: f32) -> ([f32; 2], [f32; 2]) — Position and velocity at simulation time t (seconds).

Trait implementations: Clone, Copy, Debug, PartialEq, StructuralPartialEq

structaster_blueprint::fluid::Fluid

pub struct Fluid { /* see fields */ }

A 2D incompressible fluid on a fixed grid. Clone copies the whole state.

Layout: every plane is (cols + 2) x (rows + 2) with a ghost ring. Cell (i, j) (1-based) holds the pressure and the dye at its centre; u[i, j] is the velocity through its right face and v[i, j] through its bottom face (so u[0, j] is the left wall).

Methods

  • fn new(cfg: FluidConfig) -> Result<Self, FluidError> — A still, empty fluid.
  • fn config(&self) -> &FluidConfig
  • fn cols(&self) -> usize
  • fn rows(&self) -> usize
  • fn time(&self) -> f64 — Simulated seconds.
  • fn steps(&self) -> u64 — Steps taken.
  • fn clock_us(&self) -> u64 — Microsecond clock position reached by [Fluid::advance_to].
  • fn set_clock_us(&mut self, us: u64) — Re-anchor the microsecond clock (used when a sim is created mid-timeline).
  • fn retune(&mut self, cfg: &FluidConfig) -> bool — Adopt the tunable fields of cfg (everything but the grid size, boundary and dye mode). Returns false, changing nothing, when cfg needs a different grid.
  • fn clear(&mut self) — Clear velocity, pressure and dye (obstacles stay).
  • fn set_obstacles(&mut self, list: &[Obstacle]) — Replace the obstacles by a rect/circle list (empty = none).
  • fn set_obstacle_mask(&mut self, mask: &[bool]) -> Result<(), FluidError> — Replace the obstacles by a mask of cols * rows entries, row-major, top row first.
  • fn is_solid(&self, col: usize, row: usize) -> bool — Whether the cell at zero-based (col, row) is solid.
  • fn splat(&mut self, s: &Splat) — Add an instantaneous [Splat].
  • fn stroke(&mut self, st: &Stroke) — Drag through the fluid from from to to (both 0..=1): dye and momentum are laid along the segment. The velocity inside the stroke relaxes towards delta * force (widths/s per width dragged), so overlapping samples do not add up.
  • fn step(&mut self) — One fixed step with no emitters.
  • fn step_with(&mut self, emitters: &[Emitter]) — One fixed step; emitters act at the current simulation time.
  • fn advance_to(&mut self, target_us: u64, emitters: &[Emitter], max_steps: usize) -> usize — Advance to the microsecond clock position target_us in whole fixed steps, at most max_steps of them; if the sim is further behind than that it skips ahead instead of spiralling. Returns the steps taken.
  • fn project(&mut self) — Pressure projection: make the velocity divergence free (fixed iterations sweeps).
  • fn max_divergence(&self) -> f32 — Largest |div u| over the fluid cells (1/s): what the projection leaves behind. Small next to the speeds in the field for a converged solve.
  • fn max_speed(&self) -> f32 — Largest face speed in widths/s.
  • fn total_dye(&self) -> f64 — Sum of all dye over the fluid cells and channels.
  • fn total_momentum(&self) -> [f64; 2] — Sum of the face velocities in widths/s over the domain (momentum up to the cell mass).
  • fn velocity_at(&self, x: f32, y: f32) -> [f32; 2] — Velocity at (x, y) (0..=1, bilinear) in widths/s.
  • fn speed_at(&self, x: f32, y: f32) -> f32 — Speed at (x, y) in widths/s.
  • fn dye_at(&self, x: f32, y: f32) -> [f32; 3] — Dye colour at (x, y) (linear, 0..MAX_DYE; scalar mode repeats the one channel).
  • fn density_at(&self, x: f32, y: f32) -> f32 — Mean dye density at (x, y).
  • fn digest(&self) -> u64 — A 64-bit FNV-1a hash of the whole simulation state (velocity, dye, pressure, time). Equal digests mean equal bits; used by the determinism tests.

Trait implementations: Clone, Debug

structaster_blueprint::fluid::FluidConfig

pub struct FluidConfig { /* see fields */ }

Simulation parameters. Build with [FluidConfig::default] and struct update.

Public fields

fieldtype
colsusize
rowsusize
dtf32Fixed step in seconds. Default 1/60.
iterationsusizePressure solver sweeps per projection (red-black Gauss-Seidel). Default 20.
viscosityf32Velocity diffusion in cells^2/s (implicit). 0 skips the pass.
diffusionf32Dye diffusion in cells^2/s (implicit). 0 skips the pass.
vorticityf32Vorticity confinement strength. 0 off, 0.3..2 keeps swirls alive, above ~3 it turns noisy.
velocity_decayf32Velocity damping per second (v /= 1 + decay * dt). Default 0.15.
dissipationf32Dye fade per second (d /= 1 + k * dt). Default 0.35; 0 keeps all the dye.
gravity[f32; 2]Constant acceleration in widths/s^2.
buoyancyf32Acceleration against gravity.y-up per unit of dye density, in widths/s^2 (positive = dye rises, smoke). 0 off.
boundaryBoundary
maccormackboolMacCormack (BFECC-style) dye advection: much sharper dye, clamped to the local min/max so it cannot overshoot.
maccormack_velocityboolMacCormack for the velocity too: livelier swirls, but it can leave a faint serration at sharp jet edges. Off by default.
dyeDyeMode
max_speedf32Speed limit in widths/s (keeps explicit forces from blowing up).

Methods

  • fn sized(cols: usize, w: f64, h: f64) -> Self — A grid of cols cells wide whose height follows the aspect ratio w : h (square cells), e.g. FluidConfig::sized(128, 16.0, 9.0) is 128 x 72.
  • fn validate(&self) -> Result<(), FluidError> — Check every field; the refusal names the field.

Trait implementations: Clone, Debug, Default, PartialEq, StructuralPartialEq

structaster_blueprint::fluid::Splat

pub struct Splat { /* see fields */ }

An instantaneous blob of dye and momentum.

Public fields

fieldtype
xf32Centre, 0..=1 across the domain.
yf32
radiusf32Radius in domain widths (compact support: nothing outside it).
velocity[f32; 2]Velocity added at the centre, widths/s.
color[f32; 3]Dye colour (linear light, 1.0 = full). In [DyeMode::Scalar] only color[0] counts.
amountf32Dye multiplier (color * amount is deposited at the centre).

Methods

  • fn at(x: f32, y: f32, radius: f32) -> Self — A splat of radius at (x, y) with no velocity and white dye.
  • fn velocity(self, vx: f32, vy: f32) -> Self
  • fn color(self, r: f32, g: f32, b: f32) -> Self
  • fn amount(self, a: f32) -> Self

Trait implementations: Clone, Copy, Debug, PartialEq, StructuralPartialEq

structaster_blueprint::fluid::Stroke

pub struct Stroke { /* see fields */ }

A pointer drag through the fluid, see [Fluid::stroke].

Public fields

fieldtype
from[f32; 2]
to[f32; 2]
radiusf32Radius in domain widths.
color[f32; 3]
amountf32Dye multiplier per stroke sample.
forcef32Velocity (widths/s) per domain width dragged. 40 makes a quick drag a brisk jet.

Trait implementations: Clone, Copy, Debug, PartialEq, StructuralPartialEq

Enums

enumaster_blueprint::fluid::Boundary

pub enum Boundary { Wall, Wrap }

Edge behaviour of the domain.

Variants

  • Wall — Solid walls: nothing flows through the edge, dye piles up against it.
  • Wrap — The domain is periodic: what leaves on one side enters on the other.

Trait implementations: Clone, Copy, Debug, Eq, PartialEq, StructuralPartialEq

enumaster_blueprint::fluid::DyeMode

pub enum DyeMode { Rgb, Scalar }

What the dye field stores.

Variants

  • Rgb — Three channels (red, green, blue light). Splat colours mix.
  • Scalar — One density channel, coloured at render time by a ramp. Cheaper to render than the multi-channel form.

Trait implementations: Clone, Copy, Debug, Eq, PartialEq, StructuralPartialEq

enumaster_blueprint::fluid::FluidError

pub enum FluidError { Size, Param, Mask }

A refusal: the config or an input is outside what the kernel admits.

Variants

  • Size — cols/rows outside MIN_SIDE..=MAX_SIDE or too many cells.
  • Param — A numeric parameter is NaN/infinite or out of range.
  • Mask — An obstacle mask does not have cols * rows entries.

Trait implementations: Clone, Debug, Display, Error, PartialEq, StructuralPartialEq

enumaster_blueprint::fluid::Obstacle

pub enum Obstacle { Rect, Circle }

A static solid region. Coordinates as for [Splat]; radius/w/h in domain widths for circles, 0..=1 fractions of the width/height for rects.

Variants

  • Rect
  • Circle

Trait implementations: Clone, Copy, Debug, PartialEq, StructuralPartialEq

Functions

fnaster_blueprint::fluid::sin_approx

pub fn sin_approx(x: f32) -> f32

Portable sin (parabola + one refinement; max error ~0.001). exp/sin from libm differ between platforms, this does not.

Constants

constaster_blueprint::fluid::MAX_CELLS

pub const MAX_CELLS: usize

Largest grid (cells). 512 x 512 is about 20 MB of working buffers.

constaster_blueprint::fluid::MAX_DYE

pub const MAX_DYE: f32

Dye is clamped to this density after every step (keeps floats tame).

constaster_blueprint::fluid::MAX_SIDE

pub const MAX_SIDE: usize

Largest grid side in cells.

constaster_blueprint::fluid::MIN_SIDE

pub const MIN_SIDE: usize

Smallest grid side in cells.