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 floorare used (noexp/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..=1across the domain (xover the width,yover the height), lengths and velocities are in domain widths (a velocity of0.5crosses 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
| field | type | |
|---|---|---|
x | f32 | |
y | f32 | |
radius | f32 | |
dir | [f32; 2] | Jet velocity, widths/s. |
color | [f32; 3] | Dye colour as for [Splat::color]. |
rate | f32 | Dye added per second at the centre (color * rate * dt per step). |
jet | f32 | How fast the velocity inside the radius relaxes to dir, per second. |
sweep | f32 | The jet direction swings by up to sweep radians either side, sweep_hz times a second. |
sweep_hz | f32 | |
orbit | [f32; 2] | The position circles on an ellipse of radii orbit (widths) at orbit_hz. |
orbit_hz | f32 | |
phase | f32 | Phase 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) -> Selffn color(self, r: f32, g: f32, b: f32) -> Selffn rate(self, rate: f32) -> Selffn jet(self, jet: f32) -> Selffn sweep(self, radians: f32, hz: f32) -> Self— Swing the jet direction byradianseither side,hztimes a second.fn orbit(self, rx: f32, ry: f32, hz: f32) -> Self— Move the source on an ellipse with radiirx,ry(widths),hzturns a second.fn phase(self, turns: f32) -> Selffn at_time(&self, t: f32) -> ([f32; 2], [f32; 2])— Position and velocity at simulation timet(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) -> &FluidConfigfn cols(&self) -> usizefn rows(&self) -> usizefn 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 ofcfg(everything but the grid size, boundary and dye mode). Returnsfalse, changing nothing, whencfgneeds 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 ofcols * rowsentries, 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 fromfromtoto(both0..=1): dye and momentum are laid along the segment. The velocity inside the stroke relaxes towardsdelta * 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;emittersact at the current simulation time.fn advance_to(&mut self, target_us: u64, emitters: &[Emitter], max_steps: usize) -> usize— Advance to the microsecond clock positiontarget_usin whole fixed steps, at mostmax_stepsof 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 (fixediterationssweeps).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
| field | type | |
|---|---|---|
cols | usize | |
rows | usize | |
dt | f32 | Fixed step in seconds. Default 1/60. |
iterations | usize | Pressure solver sweeps per projection (red-black Gauss-Seidel). Default 20. |
viscosity | f32 | Velocity diffusion in cells^2/s (implicit). 0 skips the pass. |
diffusion | f32 | Dye diffusion in cells^2/s (implicit). 0 skips the pass. |
vorticity | f32 | Vorticity confinement strength. 0 off, 0.3..2 keeps swirls alive, above ~3 it turns noisy. |
velocity_decay | f32 | Velocity damping per second (v /= 1 + decay * dt). Default 0.15. |
dissipation | f32 | Dye fade per second (d /= 1 + k * dt). Default 0.35; 0 keeps all the dye. |
gravity | [f32; 2] | Constant acceleration in widths/s^2. |
buoyancy | f32 | Acceleration against gravity.y-up per unit of dye density, in widths/s^2 (positive = dye rises, smoke). 0 off. |
boundary | Boundary | |
maccormack | bool | MacCormack (BFECC-style) dye advection: much sharper dye, clamped to the local min/max so it cannot overshoot. |
maccormack_velocity | bool | MacCormack for the velocity too: livelier swirls, but it can leave a faint serration at sharp jet edges. Off by default. |
dye | DyeMode | |
max_speed | f32 | Speed limit in widths/s (keeps explicit forces from blowing up). |
Methods
fn sized(cols: usize, w: f64, h: f64) -> Self— A grid ofcolscells wide whose height follows the aspect ratiow : 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
| field | type | |
|---|---|---|
x | f32 | Centre, 0..=1 across the domain. |
y | f32 | |
radius | f32 | Radius 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. |
amount | f32 | Dye multiplier (color * amount is deposited at the centre). |
Methods
fn at(x: f32, y: f32, radius: f32) -> Self— A splat ofradiusat(x, y)with no velocity and white dye.fn velocity(self, vx: f32, vy: f32) -> Selffn color(self, r: f32, g: f32, b: f32) -> Selffn 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
| field | type | |
|---|---|---|
from | [f32; 2] | |
to | [f32; 2] | |
radius | f32 | Radius in domain widths. |
color | [f32; 3] | |
amount | f32 | Dye multiplier per stroke sample. |
force | f32 | Velocity (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/rowsoutsideMIN_SIDE..=MAX_SIDEor too many cells.Param— A numeric parameter is NaN/infinite or out of range.Mask— An obstacle mask does not havecols * rowsentries.
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
RectCircle
Trait implementations: Clone, Copy, Debug, PartialEq, StructuralPartialEq
Functions
fnaster_blueprint::fluid::sin_approx
pub fn sin_approx(x: f32) -> f32Portable 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: usizeLargest grid (cells). 512 x 512 is about 20 MB of working buffers.
constaster_blueprint::fluid::MAX_DYE
pub const MAX_DYE: f32Dye is clamped to this density after every step (keeps floats tame).
constaster_blueprint::fluid::MAX_SIDE
pub const MAX_SIDE: usizeLargest grid side in cells.
constaster_blueprint::fluid::MIN_SIDE
pub const MIN_SIDE: usizeSmallest grid side in cells.