@woosh/meep-engine 3.49.0 → 3.50.0

package/src/shade/renderer/fluid/pressure/GPUFluidPressureSolve.js

@@ -0,0 +1,605 @@
+import { assert } from "../../../../core/assert.js";
+import { sor_optimal_omega } from "../../../../core/math/linalg/sor_optimal_omega.js";
+import { GRID_TILE_SIZE } from "../../shader/chunk/grid/chunk_grid_tile_window.js";
+import { write_gpu_typed_buffer } from "../../shader/type/serde/write_gpu_typed_buffer.js";
+import {
+    FLUID_MG_SMOOTH_SWEEP_LIMIT,
+    FLUID_MG_SMOOTH_SWEEPS,
+    fluid_mg_edge_weight,
+    fluid_mg_level_sizes,
+    FluidMGColour
+} from "./FLUID_MG.js";
+import { shader_fluid_mg_coarse_weights } from "./shader_fluid_mg_coarse_weights.js";
+import { shader_fluid_mg_coarsest } from "./shader_fluid_mg_coarsest.js";
+import { shader_fluid_mg_level0_weights } from "./shader_fluid_mg_level0_weights.js";
+import { shader_fluid_mg_residual_restrict } from "./shader_fluid_mg_residual_restrict.js";
+import { shader_fluid_mg_smooth } from "./shader_fluid_mg_smooth.js";
+import { FLUID_MG_PASS_STRUCT } from "./FLUID_MG_PASS_STRUCT.js";
+
+/**
+ * @typedef {import("../../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext} ShadeGPUCommandContext
+ */
+
+/**
+ * A solve's inputs, as {@link GPUFluidPressureSolve#record_v_cycles} documents them, with `cycles` for
+ * the V-cycles or `sweeps` for SOR.
+ *
+ * @typedef {{pressure: GPUBuffer, window: {corner: ArrayLike<number>, corner_storage: ArrayLike<number>, size: ArrayLike<number>, period: ArrayLike<number>}, rhs: GPUBuffer, solid: GPUBuffer, h: number, ghost_pressure: GPUBuffer, cycles?: number, sweeps?: number}} FluidPressureSolveInputs
+ */
+
+const ARM_V_CYCLES = 0;
+const ARM_SOR = 1;
+
+const BUFFER_USAGE = () => GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST;
+
+/**
+ * Bytes between two passes' params in the params buffer: WebGPU's floor for
+ * `minUniformBufferOffsetAlignment`, which every device meets.
+ * @type {number}
+ */
+const PARAMS_STRIDE = 256;
+
+/**
+ * Pass parameters as {@link FLUID_MG_PASS_STRUCT} lays them out, held so a frame writes into them
+ * rather than making new ones.
+ */
+function make_pass_values() {
+    return {
+        corner: new Int32Array(3),
+        level: 0,
+        size: new Uint32Array(3),
+        colours: 0,
+        input_corner_storage: new Uint32Array(3),
+        sweeps: 0,
+        input_period: new Uint32Array(3),
+        prolong: 0,
+        output_corner_storage: new Uint32Array(3),
+        omega: 1,
+        output_period: new Uint32Array(3),
+        h2: 0,
+        coarse_size: new Uint32Array(3),
+        edge_weight: 1,
+    };
+}
+
+/**
+ * A window-local, linear buffer as a window: storage corner 0, a period of its size.
+ */
+function set_linear(corner_storage, period, size) {
+    corner_storage.fill(0);
+    period.set(size);
+}
+
+/**
+ * The GPU fluid's pressure solve for one cascade window (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §8):
+ * `Σ_f w_f·(p_nb − p) / H² = f` for the physical kinematic pressure `p` (m²/s²), with `f = div/dt`, a
+ * solid face closed and the window's edge a Dirichlet boundary at the ghost cell's centre. The
+ * cascade's parent's pressure at the ghost cell's centre is the ghost (`chunk_fluid_pressure_ghost`), as
+ * the step's pressure ghosts hold it.
+ *
+ * It owns its level transients, sized by the window and made when the window's size or the device
+ * changes, never per frame. Each `record_*` adds one graph pass that dispatches everything; each
+ * `encode_*` dispatches the same into the encoder of a pass the caller records itself:
+ *
+ * - **Weights**, once a solve: the finest level's words from the solid flags, then each coarse level's
+ *   from the one above (`shader_fluid_mg_level0_weights`, `shader_fluid_mg_coarse_weights`). The SOR
+ *   arm needs the finest only.
+ * - **{@link record_v_cycles}**, V-cycles of `3L − 2` dispatches over `L` levels: on each level above
+ *   the coarsest a smoother of {@link FLUID_MG_SMOOTH_SWEEPS} sweeps and a residual + restriction; the
+ *   coarsest level in one workgroup; then each level back up, one smoother whose load prolongs the
+ *   level below in. At 64×32×64, four levels: 10 dispatches a V-cycle, plus 4 for the weights.
+ * - **{@link record_sor}**, red-black SOR on the finest level at `sor_optimal_omega`, one colour a
+ *   dispatch: `2K` dispatches for `K` sweeps, plus 1 for the weights.
+ *
+ * A smoother never writes the buffer it reads, so the finest level goes pressure → scratch → pressure.
+ *
+ * Non-finite pressure, error and RHS are read as 0, and {@link nonfinite_counter} adds one for each such
+ * value a pass's owning invocation read. It is never reset.
+ *
+ * The window's edge is a Dirichlet boundary at the ghost cell's centre: the cascade's parent's
+ * pressure there, read from `ghost_pressure`, the step's pressure ghosts (`shader_fluid_cascade_ghosts`);
+ * the far field, a parent with no window, reads 0.
+ */
+export class GPUFluidPressureSolve {
+    /** @type {GPUDevice|null} */
+    #device = null;
+    /** @type {number[][]} the cells of every level, finest first */
+    #sizes = [];
+    /**
+     * Per level: its weight words; below the finest its RHS (`f`), its error after the up leg (`a`,
+     * zeroed by the restriction) and after the down leg (`b`).
+     * @type {{words: GPUBuffer, f: GPUBuffer|null, a: GPUBuffer|null, b: GPUBuffer|null, groups: number[]}[]}
+     */
+    #levels = [];
+    /** @type {GPUBuffer|null} the finest level after the down leg */
+    #scratch = null;
+    /** @type {GPUBuffer|null} */
+    #nonfinite = null;
+    /** @type {GPUBuffer|null} every pass's params, one {@link PARAMS_STRIDE} slot each */
+    #params = null;
+    /** @type {ArrayBuffer|null} the bytes {@link #params} is written from */
+    #params_data = null;
+    /** @type {{values: object, binding: GPUBufferBinding}[]} the slots, in the buffer's order */
+    #slots = [];
+
+    /** Held params and bindings, one per dispatch the solve can make. */
+    #weights = [];
+    #down = [];
+    #restrict = [];
+    #up = [];
+    #coarsest = null;
+    #sor = [];
+
+    /**
+     * One `u32`: how many non-finite values the solves recorded so far read and zeroed. Made with the
+     * level transients.
+     * @returns {GPUBuffer|null}
+     */
+    get nonfinite_counter() {
+        return this.#nonfinite;
+    }
+
+    /**
+     * Record V-cycles into a pass of `graph`. Nothing is recorded for 0 cycles.
+     *
+     * @param {object} options
+     * @param {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} options.graph
+     * @param {GPUBuffer} options.pressure the cascade's pressure, read as the warm start and written with
+     *   the answer: `f32` at each storage cell of `window`, x fastest
+     * @param {{corner: ArrayLike<number>, corner_storage: ArrayLike<number>, size: ArrayLike<number>, period: ArrayLike<number>}} options.window
+     *   where the pressure is stored, as {@link GRID_TILE_WINDOW_STRUCT}; its size is the solve's cells,
+     *   powers of two
+     * @param {GPUBuffer} options.rhs `f = div/dt` per cell, window-local and linear
+     * @param {GPUBuffer} options.solid solid flags per cell (bit 0), window-local and linear
+     * @param {number} options.h the cell's size, metres
+     * @param {GPUBuffer} options.ghost_pressure the finest level's Dirichlet ghosts (`chunk_fluid_pressure_ghost`):
+     *   the parent's pressure at every cell one past the window, `array<f32>` over the window grown by
+     *   one cell on every side, x fastest, as `shader_fluid_cascade_ghosts` writes it
+     * @param {number} options.cycles V-cycles
+     */
+    record_v_cycles({ graph, pressure, window, rhs, solid, h, ghost_pressure, cycles }) {
+        assert.isNonNegativeInteger(cycles, 'cycles');
+
+        this.#record(graph, ARM_V_CYCLES, cycles, { pressure, window, rhs, solid, h, ghost_pressure });
+    }
+
+    /**
+     * {@link record_v_cycles} into `encoder` itself, for a caller whose own frame-graph pass records
+     * the solve among its other dispatches, as a cascade's step does. Nothing is encoded for 0 cycles.
+     * `inputs` is read, not kept.
+     *
+     * @param {ShadeGPUCommandContext} encoder the encoder a frame-graph pass's callback was handed
+     * @param {FluidPressureSolveInputs} inputs
+     */
+    encode_v_cycles(encoder, inputs) {
+        assert.defined(encoder, 'encoder');
+        assert.isNonNegativeInteger(inputs.cycles, 'cycles');
+
+        if (this.#validate(inputs.cycles, inputs)) {
+            this.#encode(encoder, ARM_V_CYCLES, inputs.cycles, inputs);
+        }
+    }
+
+    /**
+     * {@link record_sor} into `encoder` itself, as {@link encode_v_cycles}. Nothing is encoded for 0
+     * sweeps.
+     *
+     * @param {ShadeGPUCommandContext} encoder
+     * @param {FluidPressureSolveInputs} inputs
+     */
+    encode_sor(encoder, inputs) {
+        assert.defined(encoder, 'encoder');
+        assert.isNonNegativeInteger(inputs.sweeps, 'sweeps');
+
+        if (this.#validate(inputs.sweeps, inputs)) {
+            this.#encode(encoder, ARM_SOR, inputs.sweeps, inputs);
+        }
+    }
+
+    /**
+     * Record red-black SOR sweeps on the finest level into a pass of `graph`, one colour a dispatch.
+     * Nothing is recorded for 0 sweeps.
+     *
+     * @param {object} options
+     * @param {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} options.graph
+     * @param {GPUBuffer} options.pressure as {@link record_v_cycles}
+     * @param {{corner: ArrayLike<number>, corner_storage: ArrayLike<number>, size: ArrayLike<number>, period: ArrayLike<number>}} options.window
+     * @param {GPUBuffer} options.rhs
+     * @param {GPUBuffer} options.solid
+     * @param {number} options.h
+     * @param {GPUBuffer} options.ghost_pressure
+     * @param {number} options.sweeps red-black sweeps
+     */
+    record_sor({ graph, pressure, window, rhs, solid, h, ghost_pressure, sweeps }) {
+        assert.isNonNegativeInteger(sweeps, 'sweeps');
+
+        this.#record(graph, ARM_SOR, sweeps, { pressure, window, rhs, solid, h, ghost_pressure });
+    }
+
+    #record(graph, arm, count, inputs) {
+        assert.defined(graph, 'graph');
+
+        if (!this.#validate(count, inputs)) {
+            return;
+        }
+
+        const pass = graph.add('Fluid / pressure solve', { solve: this, arm, count, inputs }, GPUFluidPressureSolve.#execute);
+
+        pass.make_side_effect();
+    }
+
+    /**
+     * Check a solve's inputs.
+     *
+     * @param {number} count
+     * @param {FluidPressureSolveInputs} inputs
+     * @returns {boolean} whether there is anything to encode
+     */
+    #validate(count, { pressure, window, rhs, solid, h, ghost_pressure }) {
+        assert.defined(pressure, 'pressure');
+        assert.defined(rhs, 'rhs');
+        assert.defined(solid, 'solid');
+        assert.defined(ghost_pressure, 'ghost_pressure');
+        assert.notEqual(ghost_pressure, pressure, 'the ghosts are not the cascade\'s pressure');
+        assert.isFinite(h, 'h');
+        assert.greaterThan(h, 0, 'h');
+
+        const { size, period } = window;
+        const cells = size[0] * size[1] * size[2];
+
+        for (let axis = 0; axis < 3; axis++) {
+            assert.isPositiveInteger(size[axis], 'window.size');
+            assert.ok((size[axis] & (size[axis] - 1)) === 0, 'window.size is a power of two');
+            assert.lessThanOrEqual(size[axis], period[axis], 'window.size within its period');
+        }
+
+        assert.greaterThanOrEqual(pressure.size, 4 * period[0] * period[1] * period[2], 'pressure covers the period');
+        assert.greaterThanOrEqual(rhs.size, 4 * cells, 'rhs covers the window');
+        assert.greaterThanOrEqual(solid.size, 4 * cells, 'solid covers the window');
+
+        return count > 0;
+    }
+
+    /**
+     * @param {{solve: GPUFluidPressureSolve, arm: number, count: number, inputs: FluidPressureSolveInputs}} data
+     * @param {*} _resources
+     * @param {{encoder: ShadeGPUCommandContext}} context
+     */
+    static #execute(data, _resources, context) {
+        data.solve.#encode(context.encoder, data.arm, data.count, data.inputs);
+    }
+
+    /**
+     * @param {ShadeGPUCommandContext} encoder
+     * @param {number} arm
+     * @param {number} count
+     * @param {FluidPressureSolveInputs} inputs
+     */
+    #encode(encoder, arm, count, inputs) {
+        this.#configure(encoder.device, inputs.window.size);
+        this.#prepare(encoder, inputs);
+
+        const last = this.#levels.length - 1;
+
+        dispatch_levelled(encoder, shader_fluid_mg_level0_weights, this.#weights[0], this.#levels[0].groups);
+
+        if (arm === ARM_SOR) {
+            for (let k = 0; k < count; k++) {
+                dispatch_smooth(encoder, this.#sor[0], this.#levels[0].groups);
+                dispatch_smooth(encoder, this.#sor[1], this.#levels[0].groups);
+            }
+
+            return;
+        }
+
+        for (let l = 1; l <= last; l++) {
+            dispatch_levelled(encoder, shader_fluid_mg_coarse_weights, this.#weights[l], this.#levels[l].groups);
+        }
+
+        for (let cycle = 0; cycle < count; cycle++) {
+            for (let l = 0; l < last; l++) {
+                dispatch_smooth(encoder, this.#down[l], this.#levels[l].groups);
+                dispatch_levelled(encoder, shader_fluid_mg_residual_restrict, this.#restrict[l], this.#levels[l].groups);
+            }
+
+            shader_fluid_mg_coarsest.dispatch({ encoder, bindings: this.#coarsest });
+
+            for (let l = last - 1; l >= 0; l--) {
+                dispatch_smooth(encoder, this.#up[l], this.#levels[l].groups);
+            }
+        }
+    }
+
+    /**
+     * The level transients for a window of `size` cells on `device`, made anew only when either
+     * changed.
+     */
+    #configure(device, size) {
+        const sizes = this.#sizes;
+
+        if (device === this.#device && sizes.length > 0
+            && sizes[0][0] === size[0] && sizes[0][1] === size[1] && sizes[0][2] === size[2]) {
+            return;
+        }
+
+        this.dispose();
+
+        this.#device = device;
+        this.#sizes = fluid_mg_level_sizes(size[0], size[1], size[2]);
+
+        const buffer = (label, cells) => device.createBuffer({ label: `Fluid / pressure / ${label}`, size: 4 * cells, usage: BUFFER_USAGE() });
+
+        this.#levels = this.#sizes.map((s, l) => {
+            const cells = s[0] * s[1] * s[2];
+            const coarse = l > 0;
+
+            return {
+                words: buffer(`level ${l} weights`, cells),
+                f: coarse ? buffer(`level ${l} rhs`, cells) : null,
+                a: coarse ? buffer(`level ${l} error`, cells) : null,
+                b: coarse ? buffer(`level ${l} error (down)`, cells) : null,
+                groups: s.map((n, axis) => Math.ceil(n / GRID_TILE_SIZE[axis])),
+            };
+        });
+
+        const s0 = this.#sizes[0];
+        this.#scratch = buffer('scratch', s0[0] * s0[1] * s0[2]);
+        this.#nonfinite = buffer('non-finite count', 1);
+
+        const last = this.#levels.length - 1;
+
+        // weights per level; down, restrict and up per level above the coarsest; the coarsest; SOR red and black
+        const slot_count = this.#levels.length + 3 * last + 1 + 2;
+
+        this.#params = device.createBuffer({ label: 'Fluid / pressure / pass params', size: slot_count * PARAMS_STRIDE, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
+        this.#params_data = new ArrayBuffer(slot_count * PARAMS_STRIDE);
+        this.#slots = [];
+
+        const params = () => {
+            const slot = { values: make_pass_values(), binding: { buffer: this.#params, offset: this.#slots.length * PARAMS_STRIDE, size: FLUID_MG_PASS_STRUCT.size } };
+
+            this.#slots.push(slot);
+
+            return slot;
+        };
+
+        const smoother = () => ({ slot: params(), params: null, input: null, output: null, rhs: null, words: null, coarse: null, nonfinite: this.#nonfinite, ghost_pressure: null });
+
+        this.#weights = this.#levels.map(() => ({ slot: params(), params: null, solid: null, fine_words: null, words: null }));
+        this.#down = [];
+        this.#restrict = [];
+        this.#up = [];
+
+        for (let l = 0; l < last; l++) {
+            this.#down.push(smoother());
+            this.#restrict.push({ slot: params(), params: null, input: null, rhs: null, words: null, coarse_rhs: null, coarse_error: null, nonfinite: this.#nonfinite, ghost_pressure: null });
+            this.#up.push(smoother());
+        }
+
+        this.#coarsest = { slot: params(), params: null, values: null, rhs: null, words: null, nonfinite: this.#nonfinite, ghost_pressure: null };
+        this.#sor = [smoother(), smoother()];
+
+        for (const bindings of [...this.#weights, ...this.#down, ...this.#restrict, ...this.#up, this.#coarsest, ...this.#sor]) {
+            bindings.params = bindings.slot.binding;
+        }
+
+        assert.equal(this.#slots.length, slot_count, 'slots');
+    }
+
+    /**
+     * Every held pass's params and bindings for this solve's inputs.
+     *
+     * @param {ShadeGPUCommandContext} encoder
+     * @param {FluidPressureSolveInputs} inputs
+     */
+    #prepare(encoder, { pressure, window, rhs, solid, h, ghost_pressure }) {
+        const sizes = this.#sizes;
+        const levels = this.#levels;
+        const last = levels.length - 1;
+
+        for (let l = 0; l <= last; l++) {
+            const weights = this.#weights[l];
+
+            set_level_params(weights.slot.values, sizes, l, h, window);
+            weights.solid = solid;
+            weights.fine_words = l === 0 ? null : levels[l - 1].words;
+            weights.words = levels[l].words;
+        }
+
+        for (let l = 0; l < last; l++) {
+            const level_rhs = l === 0 ? rhs : levels[l].f;
+
+            const down = this.#down[l];
+
+            set_level_params(down.slot.values, sizes, l, h, window);
+            down.input = l === 0 ? pressure : levels[l].a;
+            down.output = l === 0 ? this.#scratch : levels[l].b;
+            down.rhs = level_rhs;
+            down.words = levels[l].words;
+            // a smoother that prolongs nothing binds the RHS in its place, read-only twice
+            down.coarse = level_rhs;
+
+            if (l === 0) {
+                set_pressure_input(down.slot.values, window);
+            }
+
+            const restrict = this.#restrict[l];
+
+            set_level_params(restrict.slot.values, sizes, l, h, window);
+            restrict.input = down.output;
+            restrict.rhs = level_rhs;
+            restrict.words = levels[l].words;
+            restrict.coarse_rhs = levels[l + 1].f;
+            restrict.coarse_error = levels[l + 1].a;
+
+            const up = this.#up[l];
+
+            set_level_params(up.slot.values, sizes, l, h, window);
+            up.slot.values.prolong = 1;
+            up.input = down.output;
+            up.output = l === 0 ? pressure : levels[l].a;
+            up.rhs = level_rhs;
+            up.words = levels[l].words;
+            up.coarse = levels[l + 1].a;
+
+            if (l === 0) {
+                set_pressure_output(up.slot.values, window);
+            }
+        }
+
+        const coarsest = this.#coarsest;
+
+        set_level_params(coarsest.slot.values, sizes, last, h, window);
+        coarsest.values = last === 0 ? pressure : levels[last].a;
+        coarsest.rhs = last === 0 ? rhs : levels[last].f;
+        coarsest.words = levels[last].words;
+
+        if (last === 0) {
+            set_pressure_input(coarsest.slot.values, window);
+        }
+
+        const omega = sor_optimal_omega(sizes[0][0], sizes[0][1], sizes[0][2]);
+
+        for (let colour = 0; colour < 2; colour++) {
+            const sor = this.#sor[colour];
+
+            set_level_params(sor.slot.values, sizes, 0, h, window);
+            sor.slot.values.colours = colour === 0 ? FluidMGColour.Red : FluidMGColour.Black;
+            sor.slot.values.sweeps = 1;
+            sor.slot.values.omega = omega;
+            sor.input = colour === 0 ? pressure : this.#scratch;
+            sor.output = colour === 0 ? this.#scratch : pressure;
+            sor.rhs = rhs;
+            sor.words = levels[0].words;
+            sor.coarse = rhs;
+
+            if (colour === 0) {
+                set_pressure_input(sor.slot.values, window);
+            } else {
+                set_pressure_output(sor.slot.values, window);
+            }
+        }
+
+        // the step's ghosts, for the finest level's Dirichlet boundary; the passes below it bind them unread
+        for (const bindings of [...this.#down, ...this.#restrict, ...this.#up, this.#coarsest, ...this.#sor]) {
+            bindings.ghost_pressure = ghost_pressure;
+        }
+
+        // every slot in one write, recorded in order with the passes, so a second solve recorded into
+        // the same frame cannot overwrite what this one's passes read
+        const slots = this.#slots;
+
+        for (let i = 0; i < slots.length; i++) {
+            write_gpu_typed_buffer(slots[i].values, FLUID_MG_PASS_STRUCT, this.#params_data, i * PARAMS_STRIDE);
+        }
+
+        encoder.writeBuffer(this.#params, 0, this.#params_data, 0, this.#params_data.byteLength);
+    }
+
+    /**
+     * Release the level transients and the counter.
+     */
+    dispose() {
+        for (const level of this.#levels) {
+            level.words.destroy();
+            level.f?.destroy();
+            level.a?.destroy();
+            level.b?.destroy();
+        }
+
+        this.#scratch?.destroy();
+        this.#nonfinite?.destroy();
+        this.#params?.destroy();
+
+        this.#levels = [];
+        this.#sizes = [];
+        this.#scratch = null;
+        this.#nonfinite = null;
+        this.#params = null;
+        this.#params_data = null;
+        this.#slots = [];
+        this.#device = null;
+        this.#weights = [];
+        this.#down = [];
+        this.#restrict = [];
+        this.#up = [];
+        this.#coarsest = null;
+        this.#sor = [];
+    }
+}
+
+/**
+ * A level's pass params as a smoother of both colours at ω = 1 with no prolongation, reading and
+ * writing window-local linear buffers.
+ *
+ * @param {object} params
+ * @param {number[][]} sizes every level's cells
+ * @param {number} l the level
+ * @param {number} h the finest cell's size
+ * @param {{corner: ArrayLike<number>}} window
+ */
+function set_level_params(params, sizes, l, h, window) {
+    const size = sizes[l];
+    const H = h * 2 ** l;
+
+    params.size.set(size);
+    params.level = l;
+    params.h2 = H * H;
+    params.edge_weight = fluid_mg_edge_weight(l);
+    set_linear(params.input_corner_storage, params.input_period, size);
+    set_linear(params.output_corner_storage, params.output_period, size);
+
+    if (l === 0) {
+        params.corner.set(window.corner);
+    } else {
+        params.corner.fill(0);
+    }
+
+    if (l + 1 < sizes.length) {
+        params.coarse_size.set(sizes[l + 1]);
+    } else {
+        params.coarse_size.fill(0);
+    }
+
+    params.colours = FluidMGColour.Both;
+    params.sweeps = FLUID_MG_SMOOTH_SWEEPS;
+    params.omega = 1;
+    params.prolong = 0;
+}
+
+/**
+ * The pass reads the cascade's pressure, through its window.
+ */
+function set_pressure_input(params, window) {
+    params.input_corner_storage.set(window.corner_storage);
+    params.input_period.set(window.period);
+}
+
+/**
+ * The pass writes the cascade's pressure, through its window.
+ */
+function set_pressure_output(params, window) {
+    params.output_corner_storage.set(window.corner_storage);
+    params.output_period.set(window.period);
+}
+
+/**
+ * A pass over a level, one workgroup per 8×8×4 cells.
+ */
+function dispatch_levelled(encoder, shader, bindings, groups) {
+    shader.dispatch({ encoder, bindings, group_count_x: groups[0], group_count_y: groups[1], group_count_z: groups[2] });
+}
+
+/**
+ * A smoother pass. Both colours against one frozen halo diverge for ω > 1, and one colour twice in a
+ * dispatch is not a sweep.
+ */
+function dispatch_smooth(encoder, bindings, groups) {
+    const params = bindings.slot.values;
+
+    assert.ok(params.colours !== FluidMGColour.Both || params.omega === 1, `both colours in one smoother dispatch need omega = 1, not ${params.omega}`);
+    assert.ok(params.colours === FluidMGColour.Both || params.sweeps === 1, 'one colour is one sweep a dispatch');
+    assert.lessThanOrEqual(params.sweeps, FLUID_MG_SMOOTH_SWEEP_LIMIT, 'sweeps');
+
+    dispatch_levelled(encoder, shader_fluid_mg_smooth, bindings, groups);
+}

package/src/shade/renderer/fluid/pressure/chunk_fluid_mg_coarse_word.d.ts

@@ -0,0 +1,18 @@
+/**
+ * A coarse level's weight word, from its eight children's (`chunk_fluid_mg_word`).
+ *
+ * `fn fluid_mg_coarse_word(coarse: vec3<i32>) -> u32` — each face the mean of the four child faces on
+ * that side, rounded up: the open fraction of the coarse face, exact on the first two coarse levels
+ * (quarters, then sixteenths), and never 0 while any of it is open below. A coarse cell whose eight
+ * children are solid is closed on every face.
+ *
+ * ## What the enclosing shader defines
+ *
+ * `fn fluid_mg_read_child_word(cell: vec3<i32>) -> u32` — the word of a cell on the level above, always
+ * inside it: the children are `2·coarse + (k & 1, (k >> 1) & 1, k >> 2)`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_fluid_mg_coarse_word: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_fluid_mg_coarse_word.d.ts.map

package/src/shade/renderer/fluid/pressure/chunk_fluid_mg_coarse_word.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_fluid_mg_coarse_word.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/fluid/pressure/chunk_fluid_mg_coarse_word.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;GAcG;AACH,yCAFU,SAAS,CA+BO;0BA/CA,oCAAoC"}

package/src/shade/renderer/fluid/pressure/chunk_fluid_mg_coarse_word.js

@@ -0,0 +1,48 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { chunk_fluid_mg_word } from "./chunk_fluid_mg_word.js";
+
+/**
+ * A coarse level's weight word, from its eight children's (`chunk_fluid_mg_word`).
+ *
+ * `fn fluid_mg_coarse_word(coarse: vec3<i32>) -> u32` — each face the mean of the four child faces on
+ * that side, rounded up: the open fraction of the coarse face, exact on the first two coarse levels
+ * (quarters, then sixteenths), and never 0 while any of it is open below. A coarse cell whose eight
+ * children are solid is closed on every face.
+ *
+ * ## What the enclosing shader defines
+ *
+ * `fn fluid_mg_read_child_word(cell: vec3<i32>) -> u32` — the word of a cell on the level above, always
+ * inside it: the children are `2·coarse + (k & 1, (k >> 1) & 1, k >> 2)`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_fluid_mg_coarse_word = CodeChunk.from(
+    //language=WGSL
+    `
+// the mean of four child faces' fields, rounded up, placed as the coarse face's field
+fn fluid_mg_coarse_face(a: u32, b: u32, c: u32, d: u32, face: u32) -> u32 {
+    let sum = fluid_mg_face(a, face) + fluid_mg_face(b, face) + fluid_mg_face(c, face) + fluid_mg_face(d, face);
+
+    return ((sum + 3u) >> 2u) << (face * FLUID_MG_FACE_BITS);
+}
+
+fn fluid_mg_coarse_word(coarse: vec3<i32>) -> u32 {
+    let base = coarse * 2;
+
+    let w0 = fluid_mg_read_child_word(base);
+    let w1 = fluid_mg_read_child_word(base + vec3<i32>(1, 0, 0));
+    let w2 = fluid_mg_read_child_word(base + vec3<i32>(0, 1, 0));
+    let w3 = fluid_mg_read_child_word(base + vec3<i32>(1, 1, 0));
+    let w4 = fluid_mg_read_child_word(base + vec3<i32>(0, 0, 1));
+    let w5 = fluid_mg_read_child_word(base + vec3<i32>(1, 0, 1));
+    let w6 = fluid_mg_read_child_word(base + vec3<i32>(0, 1, 1));
+    let w7 = fluid_mg_read_child_word(base + vec3<i32>(1, 1, 1));
+
+    return fluid_mg_coarse_face(w0, w2, w4, w6, 0u)
+        | fluid_mg_coarse_face(w1, w3, w5, w7, 1u)
+        | fluid_mg_coarse_face(w0, w1, w4, w5, 2u)
+        | fluid_mg_coarse_face(w2, w3, w6, w7, 3u)
+        | fluid_mg_coarse_face(w0, w1, w2, w3, 4u)
+        | fluid_mg_coarse_face(w4, w5, w6, w7, 5u);
+}
+`, [chunk_fluid_mg_word]);

package/src/shade/renderer/fluid/pressure/chunk_fluid_mg_level0_word.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The finest level's weight word of a cell, from the solid flags (`chunk_fluid_mg_word`).
+ *
+ * `fn fluid_mg_level0_word(cell: vec3<i32>, size: vec3<u32>) -> u32` — for a window-local cell of a
+ * window of `size` cells: 0 when the cell is solid; otherwise a face is open all over when the cell
+ * beyond it is fluid, and a cell beyond the window is fluid.
+ *
+ * ## What the enclosing shader defines
+ *
+ * `fn fluid_mg_read_solid(cell: vec3<i32>) -> bool` — the solid flag of a window-local cell inside the
+ * window.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_fluid_mg_level0_word: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_fluid_mg_level0_word.d.ts.map