@woosh/meep-engine 3.49.0 → 3.50.0

package/src/shade/renderer/fluid/GPUFluidCascade.js

@@ -0,0 +1,1217 @@
+import { assert } from "../../../core/assert.js";
+import { isPowerOfTwo } from "../../../core/math/isPowerOfTwo.js";
+import { FluidAtmosphere } from "../../../engine/physics/fluid/FluidAtmosphere.js";
+import { BufferResourceDescriptor } from "../../device/graph/BufferResourceDescriptor.js";
+import { TextureResourceDescriptor } from "../../device/graph/TextureResourceDescriptor.js";
+import { FLUID_CASCADE_PARENT_STRUCT, fluid_cascade_parent_value } from "./coupling/FLUID_CASCADE_PARENT_STRUCT.js";
+import { FLUID_CASCADE_FILL_BOX_LIMIT, FLUID_CASCADE_FILL_BRICK, FLUID_CASCADE_FILL_STRUCT } from "./coupling/FLUID_CASCADE_FILL_STRUCT.js";
+import { shader_fluid_cascade_fill } from "./coupling/shader_fluid_cascade_fill.js";
+import { FLUID_CASCADE_FEEDBACK_MARGIN, FLUID_CASCADE_RESTRICT_STRUCT } from "./coupling/FLUID_CASCADE_RESTRICT_STRUCT.js";
+import { shader_fluid_cascade_restrict } from "./coupling/shader_fluid_cascade_restrict.js";
+import { fluid_cascade_ghost_shell_size, fluid_cascade_pressure_ghost_count } from "./coupling/FLUID_CASCADE_GHOSTS.js";
+import { GRID_TILE_SIZE } from "../shader/chunk/grid/chunk_grid_tile_window.js";
+import { WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION } from "../gpu_primitive/indirect/WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION.js";
+import { fluid_cascade_window_empty, fluid_cascade_window_place, fluid_cascade_window_value } from "./fluid_cascade_window.js";
+import { FluidMacPasses } from "./mac/FluidMacPasses.js";
+import { FluidMacVelocitySet } from "./mac/FluidMacVelocitySet.js";
+import { GPUFluidPressureSolve } from "./pressure/GPUFluidPressureSolve.js";
+import { FLUID_FORCING_BRICK_CELLS } from "./forcing/FLUID_FORCING.js";
+
+/**
+ * @typedef {import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} FrameGraph
+ * @typedef {import("../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext} ShadeGPUCommandContext
+ */
+
+/**
+ * How a cascade's step solves for pressure (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §8, D5).
+ * @readonly
+ * @enum {number}
+ */
+export const GPUFluidCascadePressureArm = Object.freeze({
+    /** {@link GPUFluidPressureSolve#encode_v_cycles}: the count is V-cycles. */
+    VCycles: 0,
+    /** {@link GPUFluidPressureSolve#encode_sor}: the count is red-black sweeps. */
+    SOR: 1,
+});
+
+/**
+ * V-cycles a step runs by default: the fewest that hold the CPU fluid's projection gate
+ * (`GPUFluidCascade.quality.slow.spec.js`, 16³, max |div| of a random field). One V-cycle a step left
+ * 1.62× the divergence of `FluidSimulator` with one projection after advection after the first step
+ * and 4.96× after ten, against the gate's 1.25; two left 0.40× and 0.34×. On an RTX 4090 the second
+ * costs 10 dispatches and 38 µs at 64×32×64 (a step 77 µs against 115), 72 µs at 128×32×128 (173
+ * against 245).
+ *
+ * The arm is the V-cycle on measurement: from a cold start at 64×32×64, with the coarsest level still
+ * at 32 sweeps, it reached a tenth of the residual in 59 µs (1 cycle, 14 dispatches) against SOR's
+ * 173 µs (26 sweeps, 53), and a hundredth in 110 against 327 (2 cycles; 49 sweeps), open or with
+ * obstacles.
+ * @type {number}
+ */
+export const GPU_FLUID_CASCADE_V_CYCLES = 2;
+
+/**
+ * Most cells a cascade has on an axis.
+ * @type {number}
+ */
+export const GPU_FLUID_CASCADE_RESOLUTION_LIMIT = 256;
+
+/**
+ * The largest exponent a frame conversion grows a deviation by: `e^x` is held at `e^64` past it.
+ *
+ * A value stored as of one instant is read as of another through `e^(−(Λ(t_read) − Λ(t_stored)))`
+ * (§6). Read at a later instant that is at most 1; read at an EARLIER one, as a cascade reads a parent
+ * that stepped since it did, it exceeds 1, by how much the drag acted between the two records. The
+ * device then multiplies back down by the step's own `e^(−ΔΛ)`. Past `e^64` (6e27, which keeps a
+ * deviation of 1e10 m/s finite in f32) the deviation being carried has decayed below 1.6e-28 of
+ * itself, under any f32 velocity's resolution, so holding the factor there changes nothing a read
+ * can see, and an infinity never reaches the device.
+ * @type {number}
+ */
+export const GPU_FLUID_CASCADE_GROWTH_EXPONENT_LIMIT = 64;
+
+/**
+ * How much of a deviation from the far field stored as of `Λ = from` is left as of `Λ = to`:
+ * `e^(from − to)`, its exponent held at {@link GPU_FLUID_CASCADE_GROWTH_EXPONENT_LIMIT}.
+ *
+ * @param {number} from
+ * @param {number} to
+ * @returns {number}
+ */
+export function gpu_fluid_cascade_frame_keep(from, to) {
+    return Math.exp(Math.min(GPU_FLUID_CASCADE_GROWTH_EXPONENT_LIMIT, from - to));
+}
+
+/**
+ * The far field's velocity and `Λ` from a {@link FluidAtmosphere} record, checking that it carries
+ * no body force: `force` is a CPU-field term and not part of the far field (§6), so the GPU fluid
+ * drops it, and says so in development.
+ *
+ * @param {Float64Array|number[]} atmosphere
+ * @param {number} offset
+ * @param {Float32Array} out_far_velocity receives `v_far`, rounded to f32
+ * @returns {number} `Λ`
+ */
+function read_far_field(atmosphere, offset, out_far_velocity) {
+    assert.equal(atmosphere[offset + FluidAtmosphere.FORCE_X], 0, 'a body force reaches the GPU fluid, which drops it');
+    assert.equal(atmosphere[offset + FluidAtmosphere.FORCE_Y], 0, 'a body force reaches the GPU fluid, which drops it');
+    assert.equal(atmosphere[offset + FluidAtmosphere.FORCE_Z], 0, 'a body force reaches the GPU fluid, which drops it');
+
+    out_far_velocity[0] = atmosphere[offset + FluidAtmosphere.VELOCITY_X];
+    out_far_velocity[1] = atmosphere[offset + FluidAtmosphere.VELOCITY_Y];
+    out_far_velocity[2] = atmosphere[offset + FluidAtmosphere.VELOCITY_Z];
+
+    for (let axis = 0; axis < 3; axis++) {
+        assert.isFinite(out_far_velocity[axis], 'v_far');
+    }
+
+    const lambda = atmosphere[offset + FluidAtmosphere.LAMBDA];
+
+    assert.isFinite(lambda, 'Λ');
+
+    return lambda;
+}
+
+/**
+ * A {@link FLUID_CASCADE_FILL_STRUCT} value, filled in place.
+ */
+function fill_value() {
+    return {
+        cells: fluid_cascade_window_value(),
+        faces_u: fluid_cascade_window_value(),
+        faces_v: fluid_cascade_window_value(),
+        faces_w: fluid_cascade_window_value(),
+        box0: new Int32Array(3),
+        box1: new Int32Array(3),
+        box2: new Int32Array(3),
+        box0_bricks: new Uint32Array(3),
+        box1_bricks: new Uint32Array(3),
+        box2_bricks: new Uint32Array(3),
+        box_end: new Uint32Array(3),
+    };
+}
+
+/**
+ * A {@link FLUID_CASCADE_RESTRICT_STRUCT} value, filled in place.
+ */
+function restrict_value() {
+    return {
+        child_u: fluid_cascade_window_value(),
+        child_v: fluid_cascade_window_value(),
+        child_w: fluid_cascade_window_value(),
+        faces_u: fluid_cascade_window_value(),
+        faces_v: fluid_cascade_window_value(),
+        faces_w: fluid_cascade_window_value(),
+        box: new Int32Array(3),
+        keep: 1,
+        box_size: new Uint32Array(3),
+        child_offset: new Int32Array(3),
+        child_far_velocity: new Float32Array(3),
+        far_velocity: new Float32Array(3),
+    };
+}
+
+/**
+ * One cascade window of the GPU fluid (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §7, §8), and the step
+ * that advances it.
+ *
+ * The window is N = `resolution` cells of `cell_size` metres, powers of two (32 to 256 on an axis in
+ * production; a spec runs smaller), with world cell `corner` at window-local 0. World cell `g` of a
+ * cascade covers `[g·h, (g + 1)·h)` on each axis, so cascades of every cell size share the world's
+ * origin, and a cascade of twice the cell holds child cells `2G` and `2G + 1` in its cell `G`.
+ *
+ * **What it keeps between steps:**
+ * - {@link velocity}, A: three toroidal `r32float` face textures (`FluidMacVelocitySet`);
+ * - {@link pressure}: kinematic pressure, m²/s², `array<f32>` of N cells, toroidal, the solve's warm
+ *   start;
+ * - {@link solid}: window-local solid flags, all fluid at creation: `FLUID_SOLID_FLAG`, and
+ *   `FLUID_FORCED_FLAG` where the tick's forcing was written for the cell's faces. A step reads these
+ *   unless it is handed another buffer. `GPUFluidForcing` writes them before each step of the
+ *   cascade, with {@link solid_bricks} saying which bricks it last wrote;
+ * - **its read record**: the instant its velocity was last brought to, `t_s`, with `v_far(t_s)`
+ *   ({@link read_far_velocity}, rounded to f32 as the device holds it) and `Λ(t_s)`
+ *   ({@link read_lambda}), on the CPU. The velocity is a deviation from `v_far(t_s)`, so every read of
+ *   it at an instant `t` is `v_far(t) + (v − v_far(t_s))·e^(−(Λ(t) − Λ(t_s)))` (§6); {@link update_read}
+ *   computes that factor, {@link read_keep}, on the CPU, and the device never sees `Λ`.
+ *
+ * It is created at the far field of a {@link FluidAtmosphere} record: velocity `v_far`, pressure 0,
+ * the read record that instant.
+ *
+ * **One step** ({@link record_step}) is one frame-graph pass, in the order of §8, from `t₀`, its read
+ * record, to `t₁`, the atmosphere it is handed:
+ *
+ *     ghosts             parent → G: its identity read at the faces and its pressure at the cells
+ *                        just past the window, once (shader_fluid_cascade_ghosts)
+ *     curl               A → C, the vorticity confinement's force per cell (shader_fluid_mac_curl),
+ *                        only for a step with confinement
+ *     advect predict     A → F
+ *     advect correct     A + F → B, then per face the atmosphere identity, the confinement from C,
+ *                        the relaxation band and the deviation clamp (chunk_fluid_cascade_epilogue),
+ *                        and the tick's forcing where the flags say it was written
+ *     divergence         B → rhs = div/dt
+ *     pressure solve     rhs → pressure (V-cycles or SOR)
+ *     gradient           B + pressure → A
+ *
+ * and moves the read record to `t₁`. Beyond the window, velocity is the parent's identity read at
+ * `t₀` and pressure the parent's: a `parent` cascade's, of twice the cell and the same resolution, or
+ * the far field's (`v_far(t₀)`, 0), a parent with no window. The step's passes read it from G, the
+ * step's ghosts, which hold it as of the step's start for every face a trace can reach and every
+ * ghost cell; a trace past the shell reads the parent itself.
+ *
+ * F and B (three textures each), G (three shell textures and a buffer), the RHS and C are the step's
+ * transients: the pass creates them in the frame graph, which pools them, so the steps of every
+ * cascade of one resolution share one set of memory. The pressure solve keeps its level buffers itself (`GPUFluidPressureSolve`).
+ *
+ * At 64×32×64 a step dispatches the ghosts, 4 MAC passes, the solve's 4 weight passes and 10 a
+ * V-cycle: 29 at {@link GPU_FLUID_CASCADE_V_CYCLES}, and the curl with confinement.
+ *
+ * A face with a solid cell on either side is pinned: every pass carries its value in A through, so A
+ * holds the wall's velocity there. Whoever writes the solid flags writes that velocity too: the
+ * forcing writes it into A at every face it pins, before the step, so a face that just became pinned
+ * carries the wall and never the fluid value it held.
+ *
+ * **Placement** ({@link place}) moves the window's corner and writes nothing: storage wraps, so every
+ * value still inside the window stays where it is, and what the move exposed holds stale values until
+ * {@link record_fill} writes it from the parent (one dispatch, `shader_fluid_cascade_fill`).
+ *
+ * **Feedback** ({@link record_restrict}): before a cascade steps, its child's interior is restricted
+ * into it, each parent face the mean of the four child faces on it (one dispatch,
+ * `shader_fluid_cascade_restrict`). A step records the corner, and its parent's, as they are
+ * when the step is recorded, so several ticks may be recorded into one graph.
+ *
+ * Nothing is allocated per step once the first has been recorded: the step's parameters and the
+ * solve's inputs live in retained records, and several steps may be recorded into one graph.
+ */
+export class GPUFluidCascade {
+    /** @type {Uint32Array} */
+    #resolution = new Uint32Array(3);
+    /** @type {Int32Array} */
+    #corner = new Int32Array(3);
+    /** @type {number} */
+    #cell_size = 1;
+
+    /** @type {FluidMacVelocitySet} */
+    #velocity;
+    /** @type {GPUBuffer} */
+    #pressure;
+    /** @type {GPUBuffer} */
+    #solid;
+    /** @type {GPUBuffer} */
+    #solid_bricks;
+
+    /**
+     * Bound where a step's forcing would be when it has none; never read, since no cell then carries
+     * `FLUID_FORCED_FLAG`.
+     * @type {GPUBuffer}
+     */
+    #no_forcing;
+
+    /**
+     * Bound where a step's confinement force would be when it has none; never read, since the step's
+     * `confinement_dt` is then 0.
+     * @type {GPUBuffer}
+     */
+    #no_confinement;
+
+    /**
+     * Stand-ins for the far field's faces and pressure, bound where a parent cascade's would be. The
+     * far field is a parent with no window, so they are never read.
+     * @type {GPUTexture[]}
+     */
+    #far_field_faces;
+    /** @type {GPUTextureView[]} */
+    #far_field_views;
+    /** @type {GPUBuffer} */
+    #far_field_pressure;
+
+    #mac = new FluidMacPasses();
+    #solve = new GPUFluidPressureSolve();
+
+    /** The read record: `t_s` and `Λ(t_s)`, f64. */
+    #read_time = 0;
+    #read_lambda = 0;
+    /** `v_far(t_s)`, as the device holds it. */
+    #read_far_velocity = new Float32Array(3);
+    /** `e^(−(Λ(t) − Λ(t_s)))` at the last {@link update_read}. */
+    #read_keep = 1;
+
+    /** Scratch for an atmosphere's `v_far`. */
+    #far_scratch = new Float32Array(3);
+
+    /** The window as the published field reads it, rewritten on every query. */
+    #cells_window = fluid_cascade_window_value();
+    #faces_windows = [fluid_cascade_window_value(), fluid_cascade_window_value(), fluid_cascade_window_value()];
+
+    /**
+     * Where the pressure is stored, as the solve reads it: period N, so the storage corner is the
+     * corner modulo N. Rewritten for every step from the corner it recorded.
+     */
+    #pressure_window = fluid_cascade_window_value();
+
+    /** The solve's inputs, rewritten for every step. */
+    #solve_inputs = { pressure: null, window: null, rhs: null, solid: null, h: 1, ghost_pressure: null, cycles: 0, sweeps: 0 };
+
+    /** The transients' views as the MAC passes take a velocity set, rebound for every step. */
+    #forward = { u: null, v: null, w: null };
+    #advected = { u: null, v: null, w: null };
+
+    /** What the step's passes bind of the parent, rebound for every step. */
+    #parent_bindings = { uniform: null, u: null, v: null, w: null, pressure: null };
+
+    /** The step's ghosts' views and buffer, rebound for every step. */
+    #ghosts = { u: null, v: null, w: null, pressure: null };
+
+    /** The transients, as the frame graph pools them: u, v and w faces, then the RHS. */
+    #transient_faces;
+    /** @type {BufferResourceDescriptor} */
+    #transient_rhs;
+    /** The confinement force of a step with confinement, three floats a cell. @type {BufferResourceDescriptor} */
+    #transient_confinement;
+    /** The ghosts' transients: the u, v and w shells, then the pressure ghosts. */
+    #transient_ghost_faces;
+    /** @type {BufferResourceDescriptor} */
+    #transient_ghost_pressure;
+
+    /**
+     * Step records not in a graph: a recorded step holds one until its pass has run.
+     * @type {object[]}
+     */
+    #free_records = [];
+
+    /**
+     * Fill records not in a graph, likewise.
+     * @type {object[]}
+     */
+    #free_fills = [];
+
+    /**
+     * Restriction records not in a graph, likewise.
+     * @type {object[]}
+     */
+    #free_restrictions = [];
+
+    #destroyed = false;
+
+    /**
+     * @param {object} options
+     * @param {GPUDevice} options.device
+     * @param {ArrayLike<number>} options.resolution cells on each axis, powers of two
+     * @param {number} options.cell_size metres
+     * @param {ArrayLike<number>} options.corner the world cell at window-local (0, 0, 0)
+     * @param {Float64Array|number[]} options.atmosphere a {@link FluidAtmosphere} record, world units:
+     *   the velocity starts at its `v_far`, and the read record is its instant
+     * @param {number} options.atmosphere_offset where the record starts in `atmosphere`
+     */
+    constructor({ device, resolution, cell_size, corner, atmosphere, atmosphere_offset }) {
+        assert.defined(device, 'device');
+        assert.isFinite(cell_size, 'cell_size');
+        assert.greaterThan(cell_size, 0, 'cell_size');
+        assert.isNonNegativeInteger(atmosphere_offset, 'atmosphere_offset');
+
+        for (let axis = 0; axis < 3; axis++) {
+            assert.isPositiveInteger(resolution[axis], 'resolution');
+            assert.ok(isPowerOfTwo(resolution[axis]), 'resolution is a power of two on each axis');
+            assert.lessThanOrEqual(resolution[axis], GPU_FLUID_CASCADE_RESOLUTION_LIMIT, 'resolution');
+            assert.isInteger(corner[axis], 'corner');
+        }
+
+        this.#resolution.set(resolution);
+        this.#corner.set(corner);
+        this.#cell_size = cell_size;
+
+        this.#read_lambda = read_far_field(atmosphere, atmosphere_offset, this.#read_far_velocity);
+        this.#read_time = atmosphere[atmosphere_offset + FluidAtmosphere.TIME];
+
+        const [nx, ny, nz] = this.#resolution;
+        const cells = nx * ny * nz;
+
+        this.#velocity = new FluidMacVelocitySet(device, this.#resolution, 'Fluid / cascade / velocity', GPUTextureUsage.COPY_DST);
+
+        this.#pressure = device.createBuffer({
+            label: 'Fluid / cascade / pressure',
+            size: 4 * cells,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST,
+        });
+
+        this.#solid = device.createBuffer({
+            label: 'Fluid / cascade / solid',
+            size: 4 * cells,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+        });
+
+        this.#solid_bricks = device.createBuffer({
+            label: 'Fluid / cascade / solid bricks',
+            size: 4 * (cells / FLUID_FORCING_BRICK_CELLS),
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+        });
+
+        this.#no_forcing = device.createBuffer({
+            label: 'Fluid / cascade / no forcing',
+            size: 4,
+            usage: GPUBufferUsage.STORAGE,
+        });
+
+        this.#no_confinement = device.createBuffer({
+            label: 'Fluid / cascade / no confinement',
+            size: 4,
+            usage: GPUBufferUsage.STORAGE,
+        });
+
+        this.#far_field_faces = ['u', 'v', 'w'].map(name => device.createTexture({
+            label: `Fluid / cascade / far field ${name}`,
+            size: [1, 1, 1],
+            dimension: '3d',
+            format: 'r32float',
+            usage: GPUTextureUsage.TEXTURE_BINDING,
+        }));
+
+        this.#far_field_views = this.#far_field_faces.map(texture => texture.createView());
+
+        this.#far_field_pressure = device.createBuffer({
+            label: 'Fluid / cascade / far field pressure',
+            size: 4,
+            usage: GPUBufferUsage.STORAGE,
+        });
+
+        // a new texture is 0, so only a component the far field moves is written
+        const textures = this.#velocity.textures;
+
+        for (let component = 0; component < 3; component++) {
+            const value = this.#read_far_velocity[component];
+
+            if (value === 0) {
+                continue;
+            }
+
+            const texture = textures[component];
+            const data = new Float32Array(texture.width * texture.height * texture.depthOrArrayLayers).fill(value);
+
+            device.queue.writeTexture(
+                { texture },
+                data,
+                { bytesPerRow: 4 * texture.width, rowsPerImage: texture.height },
+                [texture.width, texture.height, texture.depthOrArrayLayers]
+            );
+        }
+
+        // the MAC passes need a whole tile on each axis
+        this.#mac.place(this.#resolution, this.#corner);
+
+        const inputs = this.#solve_inputs;
+        inputs.pressure = this.#pressure;
+        inputs.window = this.#pressure_window;
+        inputs.h = cell_size;
+
+        const faces = resolution_of => TextureResourceDescriptor.from({
+            resolution: resolution_of,
+            dimension: '3d',
+            format: 'r32float',
+            usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.STORAGE_BINDING,
+        });
+
+        this.#transient_faces = [
+            faces([nx + 1, ny, nz]),
+            faces([nx, ny + 1, nz]),
+            faces([nx, ny, nz + 1]),
+        ];
+
+        this.#transient_rhs = BufferResourceDescriptor.from(4 * cells, GPUBufferUsage.STORAGE);
+        this.#transient_confinement = BufferResourceDescriptor.from(3 * 4 * cells, GPUBufferUsage.STORAGE);
+
+        this.#transient_ghost_faces = [0, 1, 2].map(component => faces(fluid_cascade_ghost_shell_size(this.#resolution, component)));
+        this.#transient_ghost_pressure = BufferResourceDescriptor.from(4 * fluid_cascade_pressure_ghost_count(this.#resolution), GPUBufferUsage.STORAGE);
+    }
+
+    /**
+     * Cells on each axis.
+     * @returns {Readonly<Uint32Array>}
+     */
+    get resolution() {
+        return this.#resolution;
+    }
+
+    /**
+     * The world cell at window-local (0, 0, 0).
+     * @returns {Readonly<Int32Array>}
+     */
+    get corner() {
+        return this.#corner;
+    }
+
+    /**
+     * A cell's edge, metres.
+     * @returns {number}
+     */
+    get cell_size() {
+        return this.#cell_size;
+    }
+
+    /**
+     * The persistent velocity, A: u, v and w faces, toroidal through the window, each a deviation from
+     * {@link read_far_velocity}.
+     * @returns {FluidMacVelocitySet}
+     */
+    get velocity() {
+        return this.#velocity;
+    }
+
+    /**
+     * The persistent pressure, m²/s², `array<f32>` of N cells, toroidal with period N.
+     * @returns {GPUBuffer}
+     */
+    get pressure() {
+        return this.#pressure;
+    }
+
+    /**
+     * The cascade's own solid flags, `array<u32>` of N cells, window-local, x fastest; all fluid unless
+     * written. What a step reads when it is handed no other.
+     * @returns {GPUBuffer}
+     */
+    get solid() {
+        return this.#solid;
+    }
+
+    /**
+     * Which bricks of {@link solid} hold anything, one u32 a brick of `FLUID_FORCING_BRICK`³ cells,
+     * window-local, x fastest: 1 where the forcing last wrote the brick's flags, so that the next
+     * forcing of this cascade clears them if nothing meets the brick then. All 0 at creation. The
+     * forcing's (`GPUFluidForcing`), beside the flags it writes.
+     * @returns {GPUBuffer}
+     */
+    get solid_bricks() {
+        return this.#solid_bricks;
+    }
+
+    /**
+     * How many non-finite values the pressure solves read and zeroed; made by the first step.
+     * @returns {GPUBuffer|null}
+     */
+    get nonfinite_counter() {
+        return this.#solve.nonfinite_counter;
+    }
+
+    /**
+     * The read record's instant `t_s`, seconds, as the atmosphere records count them.
+     * @returns {number}
+     */
+    get read_time() {
+        return this.#read_time;
+    }
+
+    /**
+     * `Λ(t_s)`.
+     * @returns {number}
+     */
+    get read_lambda() {
+        return this.#read_lambda;
+    }
+
+    /**
+     * `v_far(t_s)`, m/s, rounded to f32: what the stored velocity is a deviation from.
+     * @returns {Readonly<Float32Array>}
+     */
+    get read_far_velocity() {
+        return this.#read_far_velocity;
+    }
+
+    /**
+     * `k = e^(−(Λ(t) − Λ(t_s)))` for the instant of the last {@link update_read}, in [0, 1]: a read of
+     * the stored velocity `v` at that instant is `v_far(t) + (v − v_far(t_s))·k`. 1 until the first.
+     * @returns {number}
+     */
+    get read_keep() {
+        return this.#read_keep;
+    }
+
+    /**
+     * Compute {@link read_keep} for the instant a {@link FluidAtmosphere} record describes: what a
+     * reader of the cascade takes, each frame, as one number. A record before the cascade's own reads
+     * 1.
+     *
+     * @param {Float64Array|number[]} atmosphere
+     * @param {number} offset
+     */
+    update_read(atmosphere, offset) {
+        const lambda = atmosphere[offset + FluidAtmosphere.LAMBDA];
+
+        assert.isFinite(lambda, 'Λ');
+
+        this.#read_keep = Math.exp(Math.min(0, this.#read_lambda - lambda));
+    }
+
+    /**
+     * Where the pressure is stored now, as a {@link GRID_TILE_WINDOW_STRUCT} value: period N, the
+     * storage corner the corner modulo N. A retained object, rewritten on every call.
+     * @returns {{corner: Int32Array, corner_storage: Uint32Array, size: Uint32Array, period: Uint32Array}}
+     */
+    get cells_window() {
+        fluid_cascade_window_place(this.#cells_window, this.#corner, this.#resolution, -1);
+
+        return this.#cells_window;
+    }
+
+    /**
+     * Where a component's faces are stored now: period N plus one along its own axis. A retained
+     * object, rewritten on every call.
+     *
+     * @param {number} component 0, 1 or 2 for u, v or w
+     * @returns {{corner: Int32Array, corner_storage: Uint32Array, size: Uint32Array, period: Uint32Array}}
+     */
+    faces_window(component) {
+        assert.ok(component === 0 || component === 1 || component === 2, 'component');
+
+        const window = this.#faces_windows[component];
+
+        fluid_cascade_window_place(window, this.#corner, this.#resolution, component);
+
+        return window;
+    }
+
+    /**
+     * Move the window: `corner` becomes the world cell at window-local 0. Nothing is written; the
+     * storage wraps, so values still inside the window keep their place, and the cells the move exposed
+     * hold what the cells it left held until a fill writes them.
+     *
+     * @param {ArrayLike<number>} corner
+     */
+    place(corner) {
+        assert.notOk(this.#destroyed, 'the cascade is destroyed');
+
+        for (let axis = 0; axis < 3; axis++) {
+            assert.isInteger(corner[axis], 'corner');
+
+            this.#corner[axis] = corner[axis];
+        }
+    }
+
+    /**
+     * Fill a {@link FLUID_CASCADE_PARENT_STRUCT} value and its bindings with what this cascade reads
+     * beyond its window as of its read record: `parent`'s identity read at `t_s`, or the far field's
+     * (a parent with no window, beside this cascade's own stand-ins). What its step, its fill and its
+     * publish (`FluidWindPublish`) read there.
+     *
+     * @param {object} out the value
+     * @param {{u: GPUTextureView|null, v: GPUTextureView|null, w: GPUTextureView|null, pressure: GPUBuffer|null}} out_bindings
+     * @param {GPUFluidCascade|null} parent a cascade of twice the cell and the same resolution, or `null`
+     */
+    describe_parent(out, out_bindings, parent) {
+        out.read_far_velocity.set(this.#read_far_velocity);
+
+        if (parent === null) {
+            out.origin.fill(0);
+            out.keep = 1;
+            fluid_cascade_window_empty(out.cells);
+            fluid_cascade_window_empty(out.faces_u);
+            fluid_cascade_window_empty(out.faces_v);
+            fluid_cascade_window_empty(out.faces_w);
+            out.far_velocity.set(this.#read_far_velocity);
+
+            out_bindings.u = this.#far_field_views[0];
+            out_bindings.v = this.#far_field_views[1];
+            out_bindings.w = this.#far_field_views[2];
+            out_bindings.pressure = this.#far_field_pressure;
+
+            return;
+        }
+
+        assert.notOk(parent.#destroyed, 'the parent is destroyed');
+        assert.notEqual(parent, this, 'a cascade is not its own parent');
+
+        for (let axis = 0; axis < 3; axis++) {
+            assert.equal(parent.#resolution[axis], this.#resolution[axis], 'a parent has the child\'s resolution');
+
+            out.origin[axis] = 2 * parent.#corner[axis];
+        }
+
+        assert.equal(parent.#cell_size, 2 * this.#cell_size, 'a parent\'s cell is twice the child\'s');
+
+        out.keep = gpu_fluid_cascade_frame_keep(parent.#read_lambda, this.#read_lambda);
+
+        fluid_cascade_window_place(out.cells, parent.#corner, parent.#resolution, -1);
+        fluid_cascade_window_place(out.faces_u, parent.#corner, parent.#resolution, 0);
+        fluid_cascade_window_place(out.faces_v, parent.#corner, parent.#resolution, 1);
+        fluid_cascade_window_place(out.faces_w, parent.#corner, parent.#resolution, 2);
+        out.far_velocity.set(parent.#read_far_velocity);
+
+        const velocity = parent.#velocity;
+        out_bindings.u = velocity.u;
+        out_bindings.v = velocity.v;
+        out_bindings.w = velocity.w;
+        out_bindings.pressure = parent.#pressure;
+    }
+
+    /**
+     * Record one step into `graph`, from the read record to the instant `atmosphere` describes, and
+     * move the read record there. Nothing is recorded for `dt = 0`, and the record stays.
+     *
+     * @param {object} options
+     * @param {FrameGraph} options.graph
+     * @param {number} options.dt seconds, the step the advection and the solve take
+     * @param {Float64Array|number[]} options.atmosphere a {@link FluidAtmosphere} record, world units:
+     *   `t₁`, at or after the read record
+     * @param {number} options.atmosphere_offset where the record starts in `atmosphere`
+     * @param {GPUFluidCascade|null} options.parent what lies beyond the window: a cascade of twice the
+     *   cell and the same resolution, or `null` for the far field
+     * @param {boolean} options.relaxation_band whether rows 2..5 relax toward the parent (§9)
+     * @param {GPUBuffer} [options.solid] the window's solid flags, `array<u32>`, bit 0; {@link solid} by default
+     * @param {number|null} [options.forcing] the tick's forcing for this cascade, a buffer resource of
+     *   `graph` that `GPUFluidForcing` wrote, read under `FLUID_FORCED_FLAG` of `solid`; `null`, the
+     *   default, for none
+     * @param {number} [options.vorticity_confinement] its strength ε, per second, ≥ 0, as
+     *   `FluidSimulator#vorticity_confinement` reads it: the step records the curl pass and the correct
+     *   pass adds `ε·dt·(N × ω)`, ω per cell. 0, the default, records no curl pass
+     * @param {GPUFluidCascadePressureArm} [options.arm]
+     * @param {number} [options.count] V-cycles under {@link GPUFluidCascadePressureArm.VCycles}, red-black
+     *   sweeps under {@link GPUFluidCascadePressureArm.SOR}
+     */
+    record_step({
+                    graph,
+                    dt,
+                    atmosphere,
+                    atmosphere_offset,
+                    parent,
+                    relaxation_band,
+                    solid = this.#solid,
+                    forcing = null,
+                    vorticity_confinement = 0,
+                    arm = GPUFluidCascadePressureArm.VCycles,
+                    count = GPU_FLUID_CASCADE_V_CYCLES,
+                }) {
+        assert.notOk(this.#destroyed, 'the cascade is destroyed');
+        assert.defined(graph, 'graph');
+        assert.isFinite(dt, 'dt');
+        assert.greaterThanOrEqual(dt, 0, 'dt');
+        assert.isNonNegativeInteger(atmosphere_offset, 'atmosphere_offset');
+        assert.ok(parent === null || parent instanceof GPUFluidCascade, 'parent is a cascade or null');
+        assert.isBoolean(relaxation_band, 'relaxation_band');
+        assert.defined(solid, 'solid');
+        assert.greaterThanOrEqual(solid.size, this.#solid.size, 'solid covers the window');
+        assert.ok(forcing === null || Number.isInteger(forcing), 'forcing is a graph resource or null');
+        assert.isFinite(vorticity_confinement, 'vorticity_confinement');
+        assert.greaterThanOrEqual(vorticity_confinement, 0, 'vorticity_confinement');
+        assert.ok(arm ===GPUFluidCascadePressureArm.VCycles || arm === GPUFluidCascadePressureArm.SOR, 'arm');
+        assert.isNonNegativeInteger(count, 'count');
+
+        const far_end = this.#far_scratch;
+        const lambda_end = read_far_field(atmosphere, atmosphere_offset, far_end);
+        const time_end = atmosphere[atmosphere_offset + FluidAtmosphere.TIME];
+
+        assert.greaterThanOrEqual(time_end, this.#read_time, 'the step ends at or after the read record');
+        assert.greaterThanOrEqual(lambda_end, this.#read_lambda, 'Λ does not fall');
+
+        if (dt === 0) {
+            return;
+        }
+
+        const record = this.#free_records.pop() ?? {
+            cascade: this,
+            dt: 0,
+            corner: new Int32Array(3),
+            far_start: new Float32Array(3),
+            far_end: new Float32Array(3),
+            keep: 1,
+            band: false,
+            parent: fluid_cascade_parent_value(),
+            parent_bindings: { u: null, v: null, w: null, pressure: null },
+            solid: null,
+            forcing: null,
+            confinement: 0,
+            curl: -1,
+            arm: 0,
+            count: 0,
+            forward: [0, 0, 0],
+            advected: [0, 0, 0],
+            ghosts: [0, 0, 0],
+            ghost_pressure: 0,
+            rhs: 0,
+        };
+
+        record.dt = dt;
+        record.corner.set(this.#corner);
+        record.far_start.set(this.#read_far_velocity);
+        record.far_end.set(far_end);
+        record.keep = Math.exp(Math.min(0, this.#read_lambda - lambda_end));
+        record.band = relaxation_band;
+        record.solid = solid;
+        record.confinement = vorticity_confinement;
+        record.arm = arm;
+        record.count = count;
+
+        this.describe_parent(record.parent, record.parent_bindings, parent);
+
+        // the step brings the velocity to t₁
+        this.#read_time = time_end;
+        this.#read_lambda = lambda_end;
+        this.#read_far_velocity.set(far_end);
+
+        const pass = graph.add('Fluid / cascade step', record, GPUFluidCascade.#execute);
+
+        const faces = this.#transient_faces;
+
+        record.forward[0] = pass.create('Fluid / cascade / forward u', faces[0]);
+        record.forward[1] = pass.create('Fluid / cascade / forward v', faces[1]);
+        record.forward[2] = pass.create('Fluid / cascade / forward w', faces[2]);
+        record.advected[0] = pass.create('Fluid / cascade / advected u', faces[0]);
+        record.advected[1] = pass.create('Fluid / cascade / advected v', faces[1]);
+        record.advected[2] = pass.create('Fluid / cascade / advected w', faces[2]);
+        record.rhs = pass.create('Fluid / cascade / rhs', this.#transient_rhs);
+
+        const shells = this.#transient_ghost_faces;
+
+        record.ghosts[0] = pass.create('Fluid / cascade / ghost u', shells[0]);
+        record.ghosts[1] = pass.create('Fluid / cascade / ghost v', shells[1]);
+        record.ghosts[2] = pass.create('Fluid / cascade / ghost w', shells[2]);
+        record.ghost_pressure = pass.create('Fluid / cascade / ghost pressure', this.#transient_ghost_pressure);
+
+        // the confinement force, only for a step that has confinement
+        record.curl = vorticity_confinement > 0 ? pass.create('Fluid / cascade / confinement', this.#transient_confinement) : -1;
+
+        record.forcing = forcing === null ? null : pass.read(forcing);
+
+        // the step writes the cascade's own state, which is not the graph's
+        pass.make_side_effect();
+    }
+
+    /**
+     * Record a fill into `graph`: the cells a placement exposed take the parent's identity read as of
+     * the read record, faces and pressure (§7, §8 pass 0). One dispatch over the boxes' bricks; nothing
+     * for no box.
+     *
+     * @param {object} options
+     * @param {FrameGraph} options.graph
+     * @param {ArrayLike<number>} options.boxes world cells of this cascade, six a box as
+     *   `window_scroll_regions` writes them (smallest cell on x, y, z, then one past the largest), every
+     *   one inside the window and on the 4-cell lattice
+     * @param {number} options.box_count 0 to 3
+     * @param {GPUFluidCascade|null} options.parent the parent to fill from, or `null` for the far field
+     */
+    record_fill({ graph, boxes, box_count, parent }) {
+        assert.notOk(this.#destroyed, 'the cascade is destroyed');
+        assert.defined(graph, 'graph');
+        assert.isNonNegativeInteger(box_count, 'box_count');
+        assert.lessThanOrEqual(box_count, FLUID_CASCADE_FILL_BOX_LIMIT, 'box_count');
+        assert.ok(parent === null || parent instanceof GPUFluidCascade, 'parent is a cascade or null');
+
+        if (box_count === 0) {
+            return;
+        }
+
+        const record = this.#free_fills.pop() ?? {
+            cascade: this,
+            fill: fill_value(),
+            parent: fluid_cascade_parent_value(),
+            parent_bindings: { u: null, v: null, w: null, pressure: null },
+            group_count_x: 1,
+            group_count_y: 1,
+        };
+
+        const fill = record.fill;
+        const corner = this.#corner;
+        const resolution = this.#resolution;
+
+        fluid_cascade_window_place(fill.cells, corner, resolution, -1);
+        fluid_cascade_window_place(fill.faces_u, corner, resolution, 0);
+        fluid_cascade_window_place(fill.faces_v, corner, resolution, 1);
+        fluid_cascade_window_place(fill.faces_w, corner, resolution, 2);
+
+        const origins = [fill.box0, fill.box1, fill.box2];
+        const counts = [fill.box0_bricks, fill.box1_bricks, fill.box2_bricks];
+        let total = 0;
+
+        for (let b = 0; b < FLUID_CASCADE_FILL_BOX_LIMIT; b++) {
+            const origin = origins[b];
+            const count = counts[b];
+
+            if (b >= box_count) {
+                origin.fill(0);
+                count.fill(0);
+                fill.box_end[b] = total;
+
+                continue;
+            }
+
+            let bricks = 1;
+
+            for (let axis = 0; axis < 3; axis++) {
+                const min = boxes[6 * b + axis] - corner[axis];
+                const size = boxes[6 * b + 3 + axis] - boxes[6 * b + axis];
+
+                assert.isInteger(min, 'box');
+                assert.greaterThanOrEqual(min, 0, 'a box lies inside the window');
+                assert.lessThanOrEqual(min + size, resolution[axis], 'a box lies inside the window');
+                assert.greaterThan(size, 0, 'a box is not empty');
+                assert.equal(min % FLUID_CASCADE_FILL_BRICK, 0, 'a box sits on the brick lattice');
+                assert.equal(size % FLUID_CASCADE_FILL_BRICK, 0, 'a box is whole bricks');
+
+                origin[axis] = min;
+                count[axis] = size / FLUID_CASCADE_FILL_BRICK;
+                bricks *= count[axis];
+            }
+
+            total += bricks;
+            fill.box_end[b] = total;
+        }
+
+        // the live count, folded onto x, then y
+        const width = WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION;
+        record.group_count_x = Math.min(total, width);
+        record.group_count_y = Math.ceil(total / width);
+
+        this.describe_parent(record.parent, record.parent_bindings, parent);
+
+        graph.add('Fluid / cascade fill', record, GPUFluidCascade.#execute_fill).make_side_effect();
+    }
+
+    /**
+     * Record the feedback of `child` into this cascade (§8 pass 7, §9), as it must run before this
+     * cascade steps: every face of the parent cells whose children lie
+     * {@link FLUID_CASCADE_FEEDBACK_MARGIN} child cells or more inside the child's window takes the mean
+     * of the four child faces on it, carried from the child's record to this cascade's. One dispatch.
+     *
+     * The child's corner must lie on the even cells of its lattice, so the two lattices' faces coincide,
+     * and its interior inside this window: the nesting a stack keeps.
+     *
+     * @param {object} options
+     * @param {FrameGraph} options.graph
+     * @param {GPUFluidCascade} options.child a cascade of half the cell and the same resolution
+     */
+    record_restrict({ graph, child }) {
+        assert.notOk(this.#destroyed, 'the cascade is destroyed');
+        assert.defined(graph, 'graph');
+        assert.ok(child instanceof GPUFluidCascade, 'child is a cascade');
+        assert.notOk(child.#destroyed, 'the child is destroyed');
+        assert.equal(this.#cell_size, 2 * child.#cell_size, 'a parent\'s cell is twice the child\'s');
+
+        const record = this.#free_restrictions.pop() ?? {
+            cascade: this,
+            child: null,
+            value: restrict_value(),
+            group_count_x: 1,
+            group_count_y: 1,
+            group_count_z: 1,
+        };
+
+        const value = record.value;
+        const resolution = this.#resolution;
+
+        for (let axis = 0; axis < 3; axis++) {
+            const n = resolution[axis];
+
+            assert.equal(child.#resolution[axis], n, 'a child has the parent\'s resolution');
+
+            const offset = 2 * this.#corner[axis] - child.#corner[axis];
+
+            assert.equal(offset % 2, 0, 'the child\'s corner is on the even cells');
+
+            const min = (FLUID_CASCADE_FEEDBACK_MARGIN - offset) / 2;
+            const size = (n - 2 * FLUID_CASCADE_FEEDBACK_MARGIN) / 2;
+
+            assert.greaterThanOrEqual(size, 1, 'the child has an interior to feed back');
+            assert.greaterThanOrEqual(min, 0, 'the child\'s interior lies inside the parent');
+            assert.lessThanOrEqual(min + size, n, 'the child\'s interior lies inside the parent');
+
+            value.child_offset[axis] = offset;
+            value.box[axis] = min;
+            value.box_size[axis] = size;
+        }
+
+        fluid_cascade_window_place(value.child_u, child.#corner, resolution, 0);
+        fluid_cascade_window_place(value.child_v, child.#corner, resolution, 1);
+        fluid_cascade_window_place(value.child_w, child.#corner, resolution, 2);
+        fluid_cascade_window_place(value.faces_u, this.#corner, resolution, 0);
+        fluid_cascade_window_place(value.faces_v, this.#corner, resolution, 1);
+        fluid_cascade_window_place(value.faces_w, this.#corner, resolution, 2);
+
+        value.child_far_velocity.set(child.#read_far_velocity);
+        value.far_velocity.set(this.#read_far_velocity);
+        value.keep = gpu_fluid_cascade_frame_keep(child.#read_lambda, this.#read_lambda);
+
+        record.child = child;
+        record.group_count_x = Math.ceil(value.box_size[0] / GRID_TILE_SIZE[0]);
+        record.group_count_y = Math.ceil(value.box_size[1] / GRID_TILE_SIZE[1]);
+        record.group_count_z = Math.ceil(value.box_size[2] / GRID_TILE_SIZE[2]);
+
+        graph.add('Fluid / cascade restrict', record, GPUFluidCascade.#execute_restrict).make_side_effect();
+    }
+
+    /** The restriction's bindings, rebound for every restriction. */
+    #restrict_bindings = { restriction: null, child_u: null, child_v: null, child_w: null, out_u: null, out_v: null, out_w: null };
+
+    #restrict_dispatch = { encoder: null, bindings: null, group_count_x: 1, group_count_y: 1, group_count_z: 1 };
+
+    /**
+     * @param {object} record
+     * @param {*} _resources
+     * @param {{encoder: ShadeGPUCommandContext}} context
+     */
+    static #execute_restrict(record, _resources, context) {
+        const cascade = record.cascade;
+
+        try {
+            if (!cascade.#destroyed && !record.child.#destroyed) {
+                cascade.#encode_restrict(context.encoder, record);
+            }
+        } finally {
+            record.child = null;
+            cascade.#free_restrictions.push(record);
+        }
+    }
+
+    /**
+     * @param {ShadeGPUCommandContext} encoder
+     * @param {object} record
+     */
+    #encode_restrict(encoder, record) {
+        const b = this.#restrict_bindings;
+        const child = record.child.#velocity;
+
+        b.restriction = encoder.allocateTransientValueBuffer(FLUID_CASCADE_RESTRICT_STRUCT, record.value, GPUBufferUsage.UNIFORM);
+        b.child_u = child.u;
+        b.child_v = child.v;
+        b.child_w = child.w;
+        b.out_u = this.#velocity.u;
+        b.out_v = this.#velocity.v;
+        b.out_w = this.#velocity.w;
+
+        const dispatch = this.#restrict_dispatch;
+        dispatch.encoder = encoder;
+        dispatch.bindings = b;
+        dispatch.group_count_x = record.group_count_x;
+        dispatch.group_count_y = record.group_count_y;
+        dispatch.group_count_z = record.group_count_z;
+
+        shader_fluid_cascade_restrict.dispatch(dispatch);
+
+        dispatch.encoder = null;
+        dispatch.bindings = null;
+        b.restriction = b.child_u = b.child_v = b.child_w = null;
+    }
+
+    /** The fill's bindings, rebound for every fill. */
+    #fill_bindings = {
+        fill: null, parent: null, parent_u: null, parent_v: null, parent_w: null, parent_pressure: null,
+        velocity_u: null, velocity_v: null, velocity_w: null, pressure: null,
+    };
+
+    #fill_dispatch = { encoder: null, bindings: null, group_count_x: 1, group_count_y: 1, group_count_z: 1 };
+
+    /**
+     * @param {object} record
+     * @param {*} _resources
+     * @param {{encoder: ShadeGPUCommandContext}} context
+     */
+    static #execute_fill(record, _resources, context) {
+        const cascade = record.cascade;
+
+        try {
+            if (!cascade.#destroyed) {
+                cascade.#encode_fill(context.encoder, record);
+            }
+        } finally {
+            record.parent_bindings.u = record.parent_bindings.v = record.parent_bindings.w = null;
+            record.parent_bindings.pressure = null;
+            cascade.#free_fills.push(record);
+        }
+    }
+
+    /**
+     * @param {ShadeGPUCommandContext} encoder
+     * @param {object} record
+     */
+    #encode_fill(encoder, record) {
+        const b = this.#fill_bindings;
+
+        b.fill = encoder.allocateTransientValueBuffer(FLUID_CASCADE_FILL_STRUCT, record.fill, GPUBufferUsage.UNIFORM);
+        b.parent = encoder.allocateTransientValueBuffer(FLUID_CASCADE_PARENT_STRUCT, record.parent, GPUBufferUsage.UNIFORM);
+        b.parent_u = record.parent_bindings.u;
+        b.parent_v = record.parent_bindings.v;
+        b.parent_w = record.parent_bindings.w;
+        b.parent_pressure = record.parent_bindings.pressure;
+        b.velocity_u = this.#velocity.u;
+        b.velocity_v = this.#velocity.v;
+        b.velocity_w = this.#velocity.w;
+        b.pressure = this.#pressure;
+
+        const dispatch = this.#fill_dispatch;
+        dispatch.encoder = encoder;
+        dispatch.bindings = b;
+        dispatch.group_count_x = record.group_count_x;
+        dispatch.group_count_y = record.group_count_y;
+
+        shader_fluid_cascade_fill.dispatch(dispatch);
+
+        dispatch.encoder = null;
+        dispatch.bindings = null;
+        b.fill = b.parent = b.parent_u = b.parent_v = b.parent_w = b.parent_pressure = null;
+    }
+
+    /**
+     * @param {object} record
+     * @param {import("../../../engine/graphics/render/frame_graph/FramePassResources.js").FramePassResources} resources
+     * @param {{encoder: ShadeGPUCommandContext}} context
+     */
+    static #execute(record, resources, context) {
+        const cascade = record.cascade;
+
+        try {
+            cascade.#encode_step(context.encoder, resources, record);
+        } finally {
+            record.solid = null;
+            record.forcing = null;
+            record.parent_bindings.u = record.parent_bindings.v = record.parent_bindings.w = null;
+            record.parent_bindings.pressure = null;
+            cascade.#free_records.push(record);
+        }
+    }
+
+    /**
+     * @param {ShadeGPUCommandContext} encoder
+     * @param {import("../../../engine/graphics/render/frame_graph/FramePassResources.js").FramePassResources} resources
+     * @param {object} record
+     */
+    #encode_step(encoder, resources, record) {
+        if (this.#destroyed) {
+            // destroyed after the step was recorded and before its graph ran: the step is dropped
+            return;
+        }
+
+        const forward = this.#forward;
+        forward.u = resources.get(record.forward[0]).obtainView();
+        forward.v = resources.get(record.forward[1]).obtainView();
+        forward.w = resources.get(record.forward[2]).obtainView();
+
+        const advected = this.#advected;
+        advected.u = resources.get(record.advected[0]).obtainView();
+        advected.v = resources.get(record.advected[1]).obtainView();
+        advected.w = resources.get(record.advected[2]).obtainView();
+
+        const ghosts = this.#ghosts;
+        ghosts.u = resources.get(record.ghosts[0]).obtainView();
+        ghosts.v = resources.get(record.ghosts[1]).obtainView();
+        ghosts.w = resources.get(record.ghosts[2]).obtainView();
+        ghosts.pressure = resources.get(record.ghost_pressure);
+
+        const rhs = resources.get(record.rhs);
+        const solid = record.solid;
+        const forcing = record.forcing === null ? this.#no_forcing : resources.get(record.forcing);
+        const velocity = this.#velocity;
+        const mac = this.#mac;
+
+        // the window as it was when the step was recorded
+        mac.place(this.#resolution, record.corner);
+        fluid_cascade_window_place(this.#pressure_window, record.corner, this.#resolution, -1);
+
+        mac.set_step(this.#cell_size, record.dt, record.far_start, record.far_end, record.keep, record.band, record.confinement);
+
+        const parent = this.#parent_bindings;
+        parent.uniform = encoder.allocateTransientValueBuffer(FLUID_CASCADE_PARENT_STRUCT, record.parent, GPUBufferUsage.UNIFORM);
+        parent.u = record.parent_bindings.u;
+        parent.v = record.parent_bindings.v;
+        parent.w = record.parent_bindings.w;
+        parent.pressure = record.parent_bindings.pressure;
+
+        mac.record_ghosts(encoder, parent, ghosts);
+
+        let confinement = this.#no_confinement;
+
+        if (record.curl !== -1) {
+            confinement = resources.get(record.curl);
+            mac.record_curl(encoder, velocity, solid, confinement);
+        }
+
+        mac.record_advect(encoder, velocity, forward, advected, solid, forcing, confinement, parent, ghosts);
+        mac.record_divergence(encoder, advected, solid, rhs);
+
+        const inputs = this.#solve_inputs;
+        inputs.rhs = rhs;
+        inputs.solid = solid;
+        inputs.ghost_pressure = ghosts.pressure;
+
+        if (record.arm === GPUFluidCascadePressureArm.VCycles) {
+            inputs.cycles = record.count;
+            this.#solve.encode_v_cycles(encoder, inputs);
+        } else {
+            inputs.sweeps = record.count;
+            this.#solve.encode_sor(encoder, inputs);
+        }
+
+        inputs.rhs = null;
+        inputs.solid = null;
+        inputs.ghost_pressure = null;
+
+        mac.record_gradient(encoder, advected, this.#pressure, solid, velocity, ghosts);
+
+        parent.uniform = parent.u = parent.v = parent.w = parent.pressure = null;
+        ghosts.u = ghosts.v = ghosts.w = ghosts.pressure = null;
+        forward.u = forward.v = forward.w = null;
+        advected.u = advected.v = advected.w = null;
+    }
+
+    /**
+     * Release everything the cascade made. A step recorded into a graph that has not run yet encodes
+     * nothing; work already submitted keeps what it holds, as WebGPU keeps a destroyed resource for
+     * the commands that use it. Nothing may be recorded after.
+     */
+    destroy() {
+        if (this.#destroyed) {
+            return;
+        }
+
+        this.#destroyed = true;
+
+        this.#velocity.destroy();
+        this.#pressure.destroy();
+        this.#solid.destroy();
+        this.#solid_bricks.destroy();
+        this.#no_forcing.destroy();
+        this.#no_confinement.destroy();
+        this.#far_field_pressure.destroy();
+
+        for (const texture of this.#far_field_faces) {
+            texture.destroy();
+        }
+
+        this.#solve.dispose();
+    }
+}