@woosh/meep-engine 3.49.0 → 3.50.0

package/src/shade/renderer/fluid/forcing/GPUFluidForcing.js

@@ -0,0 +1,1487 @@
+import { assert } from "../../../../core/assert.js";
+import { BufferResourceDescriptor } from "../../../device/graph/BufferResourceDescriptor.js";
+import { GPUDatabase } from "../../buffer/table/GPUDatabase.js";
+import { generate_record_writer } from "../../buffer/table/serde/generate_record_writer.js";
+import { bvh_buffer_size } from "../../gpu_primitive/bvh/BVH_BUFFER_LAYOUT.js";
+import { enquire_bvh_build_lbvh_pipelines, graph_bvh_build_lbvh } from "../../gpu_primitive/bvh/graph_bvh_build_lbvh.js";
+import { enquire_bvh_refit_lbvh_pipelines, graph_bvh_refit_lbvh } from "../../gpu_primitive/bvh/graph_bvh_refit_lbvh.js";
+import { WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION } from "../../gpu_primitive/indirect/WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION.js";
+import { SORT_TILE_SIZE } from "../../gpu_primitive/sort/defs.js";
+import { fluid_cascade_window_place, fluid_cascade_window_value } from "../fluid_cascade_window.js";
+import { GPU_FLUID_CASCADE_STACK_LIMIT } from "../GPUFluidCascadeStack.js";
+import {
+    FLUID_DATABASE_INITIAL_SIZE,
+    FLUID_DATABASE_SPEC,
+    FLUID_EFFECTOR_TABLE,
+    FLUID_OBSTACLE_PLANE_TABLE,
+    FLUID_OBSTACLE_TABLE
+} from "./FLUID_DATABASE_SPEC.js";
+import {
+    FLUID_FORCING_BRICK,
+    FLUID_FORCING_REBUILD_AGE,
+    FLUID_FORCING_SURVIVOR_STRIDE
+} from "./FLUID_FORCING.js";
+import { FLUID_FORCING_APPLY_STRUCT } from "./FLUID_FORCING_APPLY_STRUCT.js";
+import { FLUID_FORCING_EXTRACT_STRUCT } from "./FLUID_FORCING_EXTRACT_STRUCT.js";
+import { FLUID_FORCING_QUERY_STRUCT } from "./FLUID_FORCING_QUERY_STRUCT.js";
+import { FLUID_OBSTACLE_PLANE_STRUCT } from "./FLUID_OBSTACLE_PLANE_STRUCT.js";
+import { shader_fluid_forcing_apply } from "./shader_fluid_forcing_apply.js";
+import { FLUID_FORCING_COMMAND_WORDS, shader_fluid_forcing_command } from "./shader_fluid_forcing_command.js";
+import { shader_fluid_forcing_extract } from "./shader_fluid_forcing_extract.js";
+import { shader_fluid_forcing_query } from "./shader_fluid_forcing_query.js";
+import { FLUID_EFFECTOR_RECORD_STRUCT } from "../../../../engine/physics/fluid/effector/record/FLUID_EFFECTOR_RECORD_STRUCT.js";
+import { FLUID_OBSTACLE_RECORD_STRUCT } from "../../../../engine/physics/fluid/obstacle/FLUID_OBSTACLE_RECORD_STRUCT.js";
+import { fluid_obstacle_record_extent } from "../../../../engine/physics/fluid/obstacle/fluid_obstacle_record_extent.js";
+
+/**
+ * @typedef {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} FrameGraph
+ * @typedef {import("../../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry} PipelineEnquiry
+ * @typedef {import("../GPUFluidCascade.js").GPUFluidCascade} GPUFluidCascade
+ * @typedef {import("../../../../engine/physics/fluid/effector/record/fluid_effector_record_create.js").FluidEffectorRecord} FluidEffectorRecord
+ * @typedef {import("../../../../engine/physics/fluid/obstacle/fluid_obstacle_record_create.js").FluidObstacleRecord} FluidObstacleRecord
+ */
+
+const EFFECTOR_WRITER = generate_record_writer(FLUID_EFFECTOR_RECORD_STRUCT);
+const OBSTACLE_WRITER = generate_record_writer(FLUID_OBSTACLE_RECORD_STRUCT);
+const PLANE_WRITER = generate_record_writer(FLUID_OBSTACLE_PLANE_STRUCT);
+
+/**
+ * The centroid bound before anything has been merged into it: +inf for the minima, -inf for the
+ * maxima, as exact bit patterns (the TLAS's seed).
+ * @type {Uint32Array}
+ */
+const SCENE_BOUNDS_SEED = Uint32Array.from([
+    0x7F800000, 0x7F800000, 0x7F800000,
+    0xFF800000, 0xFF800000, 0xFF800000,
+]);
+
+/** `root = BVH_NULL_NODE`: an empty tree. */
+const EMPTY_TREE = Uint32Array.from([0xffffffff]);
+
+/** Bytes of a brick list's header: its count, then the elements from the next 16-byte boundary. */
+const LIST_HEADER_BYTES = 16;
+
+/**
+ * The smallest buffer a brick list binds: the header and one element, rounded up to the struct's
+ * 16-byte alignment, which is what WebGPU's minimum binding size for it is.
+ */
+const LIST_MINIMUM_BYTES = 32;
+
+/** Words of the drop counters. */
+const STATISTICS_WORDS = 4;
+
+/*
+ The transients' roles, each a descriptor kept while its size holds (GPUFluidForcing#descriptor), so a
+ frame at a fixed row count and resolution makes none. A tree keeps its own leaf transients' descriptors
+ (FluidForcingTree#descriptors), since the trees of one frame differ in size.
+*/
+const ROLE_LEAF_BOUNDS = 0;
+const ROLE_LEAF_PAYLOAD = 1;
+const ROLE_SCENE_BOUNDS = 2;
+const ROLE_LIST = 3;
+const ROLE_SURVIVORS = 4;
+const ROLE_COMMANDS = 5;
+const ROLE_FORCING = 6;
+
+/**
+ * One LBVH of the forcing: the leaves the brick queries of one cascade level search, and the tree over
+ * them, kept across frames for its refit.
+ */
+class FluidForcingTree {
+    /**
+     * The level whose resolved set this tree holds: cascade `level`, cell `h₀·2^level`.
+     * @type {number}
+     */
+    level = 0;
+
+    /** Leaf → row: obstacle rows ascending, then effector rows ascending. @type {Uint32Array} */
+    rows = new Uint32Array(0);
+    count = 0;
+    obstacle_count = 0;
+
+    /** Bumped whenever {@link rows} changes. */
+    list_version = 0;
+    /** The forcing's sets version and finest cell {@link rows} was listed for. */
+    listed_sets = -1;
+    listed_cell = 0;
+
+    /** @type {GPUBuffer} */
+    rows_buffer = null;
+    /** The list version {@link rows_buffer} holds. */
+    rows_gpu_version = -1;
+
+    /** The tree: `{root, nodes}` over the leaves. @type {GPUBuffer} */
+    nodes = null;
+    nodes_descriptor = null;
+    nodes_described = null;
+
+    /** Leaves the tree in {@link nodes} was built over, -1 for none. */
+    tree_leaf_count = -1;
+    /** The list version it was built for. */
+    tree_version = -1;
+    /** Frames it was refit since it was built. */
+    age = 0;
+
+    /** What the frame {@link frame} did to it: 'none', 'build' or 'refit'. */
+    update = 'none';
+    /** The forcing's frame it was last recorded in. */
+    frame = -1;
+    /** The tree as a resource of that frame's graph, -1 for an empty tree. */
+    frame_nodes = -1;
+
+    /** Its leaf transients' descriptors, by role. @type {BufferResourceDescriptor[]} */
+    descriptors = [];
+}
+
+/**
+ * # The GPU fluid's forcing
+ *
+ * What turns the scene's local fluid effectors and obstacles into what a cascade step reads
+ * (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §10): the fluid database, an LBVH over its rows for each
+ * resolution of cascade that steps, and per tick a brick query and the forcing of each stepping
+ * cascade.
+ *
+ * ## Rows: the host API
+ *
+ * One {@link GPUDatabase} of {@link FLUID_DATABASE_SPEC}. A row is written whole, through a generated
+ * writer, when its caller says it changed (an effector's `write_gpu_record` and an obstacle's
+ * `fluid_obstacle_write_gpu_shape` / `_motion` compare every field while they assign it), and the
+ * database uploads only what was written, before the frame's first extraction reads it.
+ *
+ *     add_effector(record) → row          set_effector(row, record)        remove_effector(row)
+ *     add_obstacles(records) → first      set_obstacle(row, record)        remove_obstacles(first, count)
+ *     add_planes(count) → first           planes, set_planes(first, count) remove_planes(first, count)
+ *
+ * A collider is a run of obstacle rows (`add_run`), and its hulls' planes a run of plane rows, which
+ * its records name in core's layout: `fluid_obstacle_write_gpu_shape(record, forcing.planes, first +
+ * cursor, shape, i)` writes a hull's planes into {@link planes}, the CPU mirror of the plane table
+ * indexed by row, and names them there; {@link set_planes} then uploads the rows. A record's `node`
+ * is its caller's to set, the scene's `transforms` row that poses it (0 for none).
+ *
+ * ## The resolution cull is the trees
+ *
+ * Cascade `c` of cell `h_c` resolves an obstacle at least `h_c/2` wide, by the record's own extent
+ * (`fluid_obstacle_record_extent`, kept per row as its record is written), and every effector. Its
+ * brick queries search a tree of exactly those leaves, so an obstacle too small for a cascade never
+ * takes a place on a coarse query's frontier and crowds out one that is not. The sets are nested,
+ * finest largest; a cascade whose set is the finer one's shares that one's tree.
+ *
+ * ## Once a frame: {@link record_frame}; per tick, the trees the tick needs
+ *
+ * {@link record_frame} takes the frame's numbers. The first tick of the frame that steps a cascade of
+ * a level records that level's tree, L1 and L2, before its queries; a later tick of the frame reuses it,
+ * and a level no tick steps builds nothing.
+ *
+ * - **The leaf list**, rebuilt on the CPU when the rows or an obstacle's extent changed: the level's
+ *   obstacle rows ascending, then every effector row ascending, so the tree's leaf order, its Morton
+ *   tie-break and every brick's survivors follow the rows.
+ * - **L1** (`shader_fluid_forcing_extract`): the database's uploads (the frame's first extraction),
+ *   then one thread a leaf, its world box clipped into the frame's clip box, and the centroids' bound.
+ * - **L2**: `graph_bvh_build_lbvh`, at most one sort tile of leaves (1,024) the one-dispatch build,
+ *   every frame. Above that the 19-dispatch build on a frame whose list changed (so whose count may
+ *   have) or every {@link FLUID_FORCING_REBUILD_AGE}th frame of that tree, and otherwise
+ *   `graph_bvh_refit_lbvh` through the stored tree. Each tree keeps its own cadence. Runtime facts
+ *   only: a count, a list version, an age.
+ *
+ * ## Per tick, called by `GPUFluidCascadeStack#record_tick`: Q1–Q3
+ *
+ * - {@link record_queries}: the trees, then Q1, every brick of the tick's stepping cascades queries its
+ *   cascade's tree in one dispatch (`shader_fluid_forcing_query`), and Q2, the forcing's indirect
+ *   commands (`shader_fluid_forcing_command`);
+ * - {@link record_forcing}, once for each stepping cascade, before its step: Q3
+ *   (`shader_fluid_forcing_apply`) over the bricks its query listed, writing the cascade's solid
+ *   flags, the wall's velocity into its pinned faces, and the tick's forcing, which it returns for
+ *   the step.
+ *
+ * ## With no rows
+ *
+ * Nothing is recorded: no upload, no tree, no query, and the steps read their cascades' own flags
+ * with no forcing. The one exception is the tick after the last row went: a cascade whose flags the
+ * forcing wrote has them cleared once, before its next step.
+ *
+ * At a fixed row count and resolution this class makes no object per frame or tick: its trees, pass
+ * records, bindings and transient descriptors are retained and rewritten. What a frame still
+ * allocates (measured with the sampling heap profiler, SoftwareGPUDevice, 16 rows, one tick with
+ * two stepping cascades): ~0.4 KB here, the f64 stores into the retained records, and ~0.9 KB in
+ * `graph_bvh_build_lbvh`'s recorder for each tree, beside what the frame graph and the bindings
+ * allocate for every pass.
+ */
+export class GPUFluidForcing {
+
+    /**
+     * Offer the pipelines the forcing dispatches — see {@link PipelineEnquiry}.
+     *
+     * @param {PipelineEnquiry} enquiry
+     */
+    static enquirePipelines(enquiry) {
+        GPUDatabase.enquirePipelines(enquiry);
+        enquiry.compute.push(shader_fluid_forcing_extract.pipeline);
+        enquire_bvh_build_lbvh_pipelines(enquiry);
+        enquire_bvh_refit_lbvh_pipelines(enquiry);
+        enquiry.compute.push(shader_fluid_forcing_query.pipeline);
+        enquiry.compute.push(shader_fluid_forcing_command.pipeline);
+        enquiry.compute.push(shader_fluid_forcing_apply.pipeline);
+    }
+
+    /** @type {GPUDevice} */
+    #device;
+
+    /** @type {GPUDatabase} */
+    #database;
+
+    /** @type {Float32Array} */
+    #planes = new Float32Array(0);
+
+    /** The staging record {@link set_planes} writes through. */
+    #plane_record = { plane: new Float32Array(4) };
+
+    /**
+     * Each obstacle row's extent (`fluid_obstacle_record_extent`), metres, indexed by row.
+     * @type {Float64Array}
+     */
+    #obstacle_extent = new Float64Array(0);
+
+    /** Bumped by every add and remove of an effector or obstacle row, and by an obstacle's extent changing. */
+    #sets_version = 0;
+
+    /** The sets version and finest cell {@link #owners} were worked out for. */
+    #owned_sets = -1;
+    #owned_cell = 0;
+
+    /**
+     * Per level, the level whose tree it queries: the finest level resolving the same leaves.
+     * @type {Int32Array}
+     */
+    #owners = new Int32Array(GPU_FLUID_CASCADE_STACK_LIMIT);
+
+    /** Per level, how many obstacles it resolves. @type {Int32Array} */
+    #resolved = new Int32Array(GPU_FLUID_CASCADE_STACK_LIMIT);
+
+    /**
+     * The trees, by the level that owns them; made when first needed.
+     * @type {FluidForcingTree[]}
+     */
+    #trees = [];
+
+    /** Counts {@link record_frame} calls: which frame a tree was recorded in. */
+    #frame_serial = 0;
+
+    /** A tree with no leaves, bound for a level that resolves nothing. @type {GPUBuffer} */
+    #empty_tree;
+
+    /** @type {GPUBuffer} */
+    #statistics;
+
+    /** Stand-ins for a tick's second slot, when it steps one cascade. @type {GPUBuffer} */
+    #empty_list;
+    /** @type {GPUBuffer} */
+    #empty_bricks;
+
+    /**
+     * Cascades whose solid flags the forcing has written since they were last cleared.
+     * @type {Set<GPUFluidCascade>}
+     */
+    #written = new WeakSet();
+
+    /** Transient descriptors by role, kept while their size holds. @type {BufferResourceDescriptor[]} */
+    #descriptors = [];
+
+    /** The frame {@link record_frame} recorded, which every tick of it queries. */
+    #frame = {
+        graph: null,
+        scene_database: null,
+        clip_low: new Float64Array(3),
+        clip_high: new Float64Array(3),
+        dilation: 0,
+        sweep_time: 0,
+        inverse_frame_dt: 0,
+    };
+
+    /** The tick {@link record_queries} recorded, which {@link record_forcing} reads. */
+    #tick = {
+        graph: null,
+        cascades: [null, null],
+        trees: [null, null],
+        lists: [-1, -1],
+        survivors: -1,
+        commands: -1,
+    };
+
+    /** Pass records not in a graph: a recorded pass holds one until it has run. */
+    #free_extracts = [];
+    #free_queries = [];
+    #free_commands = [];
+    #free_applies = [];
+    #free_clears = [];
+
+    #destroyed = false;
+
+    /**
+     * @param {object} options
+     * @param {GPUDevice} options.device
+     */
+    constructor({ device }) {
+        assert.defined(device, 'device');
+
+        this.#device = device;
+
+        this.#database = new GPUDatabase({
+            device,
+            definition: FLUID_DATABASE_SPEC,
+            label: 'Fluid / forcing',
+            initial_data_size_bytes: FLUID_DATABASE_INITIAL_SIZE,
+        });
+
+        this.#empty_tree = device.createBuffer({
+            label: 'Fluid / forcing / no tree',
+            // a root word and one node: what a tree binding's minimum size is
+            size: bvh_buffer_size(1),
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+        });
+
+        device.queue.writeBuffer(this.#empty_tree, 0, EMPTY_TREE);
+
+        this.#statistics = device.createBuffer({
+            label: 'Fluid / forcing / statistics',
+            size: 4 * STATISTICS_WORDS,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST,
+        });
+
+        this.#empty_list = device.createBuffer({
+            label: 'Fluid / forcing / no list',
+            size: LIST_MINIMUM_BYTES,
+            usage: GPUBufferUsage.STORAGE,
+        });
+
+        this.#empty_bricks = device.createBuffer({
+            label: 'Fluid / forcing / no bricks',
+            size: 4,
+            usage: GPUBufferUsage.STORAGE,
+        });
+    }
+
+    /**
+     * The descriptor of a transient of `role`, `size` bytes, from `kept` (by role): the one kept for
+     * the role while its size holds, a new one when it moves. A role's usage and clear range never
+     * change.
+     *
+     * @param {BufferResourceDescriptor[]} kept
+     * @param {number} role
+     * @param {number} size
+     * @param {number} usage
+     * @param {number} clear_size bytes cleared from 0 when the pool reuses the buffer
+     * @returns {BufferResourceDescriptor}
+     */
+    static #descriptor(kept, role, size, usage, clear_size) {
+        const descriptor = kept[role];
+
+        if (descriptor !== undefined && descriptor.size === size) {
+            return descriptor;
+        }
+
+        const made = BufferResourceDescriptor.from(size, usage, 0, clear_size);
+
+        kept[role] = made;
+
+        return made;
+    }
+
+    /**
+     * The fluid database.
+     * @returns {GPUDatabase}
+     */
+    get database() {
+        return this.#database;
+    }
+
+    /**
+     * Rows of the effector table.
+     * @returns {number}
+     */
+    get effector_count() {
+        return this.#database.get(FLUID_EFFECTOR_TABLE).count;
+    }
+
+    /**
+     * Rows of the obstacle table.
+     * @returns {number}
+     */
+    get obstacle_count() {
+        return this.#database.get(FLUID_OBSTACLE_TABLE).count;
+    }
+
+    /**
+     * Every obstacle and effector row: the leaves of the finest tree, before its resolution cull.
+     * @returns {number}
+     */
+    get leaf_count() {
+        return this.effector_count + this.obstacle_count;
+    }
+
+    /**
+     * What the last {@link record_frame}'s frame did to the tree cascade `level` queries (the stack's
+     * cascade `level`, whose cell is `2^level` times the frame's `cell_size`): `'build'`, `'refit'`, or
+     * `'none'` when no tick of the frame stepped a cascade that queries it, or it holds no leaves.
+     *
+     * @param {number} level
+     * @returns {string}
+     */
+    tree_update(level) {
+        assert.isNonNegativeInteger(level, 'level');
+        assert.lessThan(level, GPU_FLUID_CASCADE_STACK_LIMIT, 'level');
+
+        if (this.#owned_sets === -1) {
+            return 'none';
+        }
+
+        const tree = this.#trees[this.#owners[level]];
+
+        if (tree === undefined || tree.frame !== this.#frame_serial) {
+            return 'none';
+        }
+
+        return tree.update;
+    }
+
+    /**
+     * What the brick queries could not keep, accumulated since creation, four u32: obstacle candidates
+     * past `FLUID_FORCING_OBSTACLE_LIMIT`, effector candidates past `FLUID_FORCING_EFFECTOR_LIMIT`,
+     * candidates past the query's list, nodes the query never tested.
+     * @returns {GPUBuffer}
+     */
+    get statistics() {
+        return this.#statistics;
+    }
+
+    /**
+     * The CPU mirror of the plane table, four floats a row, `(nx, ny, nz, offset)`, indexed by row:
+     * what `fluid_obstacle_write_gpu_shape` writes a hull's planes into. Replaced, not grown in place,
+     * by {@link add_planes}: read it after.
+     * @returns {Float32Array}
+     */
+    get planes() {
+        return this.#planes;
+    }
+
+    /**
+     * Add an effector row.
+     *
+     * @param {FluidEffectorRecord} record
+     * @returns {number} its row
+     */
+    add_effector(record) {
+        assert.notOk(this.#destroyed, 'destroyed');
+
+        this.#sets_version++;
+
+        return this.#database.get(FLUID_EFFECTOR_TABLE).add_record(record, EFFECTOR_WRITER);
+    }
+
+    /**
+     * Write an effector row whole, for the next frame's upload.
+     *
+     * @param {number} row
+     * @param {FluidEffectorRecord} record
+     */
+    set_effector(row, record) {
+        const table = this.#database.get(FLUID_EFFECTOR_TABLE);
+
+        assert.ok(table.occupancy.get(row), 'the effector row is not in the table');
+
+        table.set_record(row, record, EFFECTOR_WRITER);
+    }
+
+    /**
+     * @param {number} row
+     */
+    remove_effector(row) {
+        const table = this.#database.get(FLUID_EFFECTOR_TABLE);
+
+        assert.ok(table.occupancy.get(row), 'the effector row is not in the table');
+
+        table.remove(row);
+
+        this.#sets_version++;
+    }
+
+    /**
+     * Add a collider's obstacle records as a run of consecutive rows.
+     *
+     * @param {FluidObstacleRecord[]} records at least one
+     * @returns {number} the run's first row
+     */
+    add_obstacles(records) {
+        assert.notOk(this.#destroyed, 'destroyed');
+        assert.greaterThan(records.length, 0, 'records');
+
+        this.#sets_version++;
+
+        const first = this.#database.get(FLUID_OBSTACLE_TABLE).add_run_records(records, OBSTACLE_WRITER);
+        const end = first + records.length;
+
+        if (this.#obstacle_extent.length < end) {
+            const grown = new Float64Array(Math.max(end, 2 * this.#obstacle_extent.length));
+            grown.set(this.#obstacle_extent);
+            this.#obstacle_extent = grown;
+        }
+
+        for (let i = 0; i < records.length; i++) {
+            this.#obstacle_extent[first + i] = fluid_obstacle_record_extent(records[i]);
+        }
+
+        return first;
+    }
+
+    /**
+     * Write an obstacle row whole, for the next frame's upload.
+     *
+     * @param {number} row
+     * @param {FluidObstacleRecord} record
+     */
+    set_obstacle(row, record) {
+        const table = this.#database.get(FLUID_OBSTACLE_TABLE);
+
+        assert.ok(table.occupancy.get(row), 'the obstacle row is not in the table');
+
+        table.set_record(row, record, OBSTACLE_WRITER);
+
+        const extent = fluid_obstacle_record_extent(record);
+
+        if (extent !== this.#obstacle_extent[row]) {
+            // which cascades resolve it may have moved
+            this.#obstacle_extent[row] = extent;
+            this.#sets_version++;
+        }
+    }
+
+    /**
+     * @param {number} first
+     * @param {number} count
+     */
+    remove_obstacles(first, count) {
+        const table = this.#database.get(FLUID_OBSTACLE_TABLE);
+
+        for (let i = 0; i < count; i++) {
+            assert.ok(table.occupancy.get(first + i), 'the obstacle row is not in the table');
+
+            table.remove(first + i);
+        }
+
+        this.#sets_version++;
+    }
+
+    /**
+     * Take a run of plane rows, zero, for a collider's hulls; {@link planes} grows to hold them.
+     *
+     * @param {number} count at least one
+     * @returns {number} the run's first row
+     */
+    add_planes(count) {
+        assert.notOk(this.#destroyed, 'destroyed');
+        assert.isPositiveInteger(count, 'count');
+
+        const record = this.#plane_record;
+        record.plane.fill(0);
+
+        const values = new Array(count).fill(record);
+        const first = this.#database.get(FLUID_OBSTACLE_PLANE_TABLE).add_run_records(values, PLANE_WRITER);
+
+        const needed = 4 * (first + count);
+
+        if (this.#planes.length < needed) {
+            const grown = new Float32Array(Math.max(needed, 2 * this.#planes.length));
+            grown.set(this.#planes);
+            this.#planes = grown;
+        }
+
+        this.#planes.fill(0, 4 * first, needed);
+
+        return first;
+    }
+
+    /**
+     * Upload plane rows from {@link planes}.
+     *
+     * @param {number} first
+     * @param {number} count
+     */
+    set_planes(first, count) {
+        const table = this.#database.get(FLUID_OBSTACLE_PLANE_TABLE);
+        const record = this.#plane_record;
+        const mirror = this.#planes;
+
+        for (let i = 0; i < count; i++) {
+            const row = first + i;
+
+            assert.ok(table.occupancy.get(row), 'the plane row is not in the table');
+
+            record.plane[0] = mirror[4 * row];
+            record.plane[1] = mirror[4 * row + 1];
+            record.plane[2] = mirror[4 * row + 2];
+            record.plane[3] = mirror[4 * row + 3];
+
+            table.set_record(row, record, PLANE_WRITER);
+        }
+    }
+
+    /**
+     * @param {number} first
+     * @param {number} count
+     */
+    remove_planes(first, count) {
+        const table = this.#database.get(FLUID_OBSTACLE_PLANE_TABLE);
+
+        for (let i = 0; i < count; i++) {
+            assert.ok(table.occupancy.get(first + i), 'the plane row is not in the table');
+
+            table.remove(first + i);
+        }
+    }
+
+    /**
+     * Which level's tree each level queries, worked out again when the sets or the finest cell moved:
+     * level `l` resolves the obstacles at least `cell·2^l / 2` wide, and shares the tree of the finest
+     * level that resolves the same count of them (the sets are nested, so the same count is the same
+     * set).
+     *
+     * @param {number} cell metres, cascade 0's cell
+     */
+    #refresh_owners(cell) {
+        if (this.#owned_sets === this.#sets_version && this.#owned_cell === cell) {
+            return;
+        }
+
+        const obstacles = this.#database.get(FLUID_OBSTACLE_TABLE);
+        const extent = this.#obstacle_extent;
+        const resolved = this.#resolved;
+        const owners = this.#owners;
+
+        resolved.fill(0);
+
+        for (let row = obstacles.occupancy.nextSetBit(0); row !== -1; row = obstacles.occupancy.nextSetBit(row + 1)) {
+            const e = extent[row];
+
+            for (let level = 0; level < GPU_FLUID_CASCADE_STACK_LIMIT; level++) {
+                if (e < 0.5 * cell * 2 ** level) {
+                    break;
+                }
+
+                resolved[level]++;
+            }
+        }
+
+        for (let level = 0; level < GPU_FLUID_CASCADE_STACK_LIMIT; level++) {
+            owners[level] = level > 0 && resolved[level] === resolved[level - 1] ? owners[level - 1] : level;
+        }
+
+        this.#owned_sets = this.#sets_version;
+        this.#owned_cell = cell;
+    }
+
+    /**
+     * The tree of an owning level, its leaf list rebuilt when the sets or the finest cell moved since
+     * it was listed: the level's obstacle rows ascending, then every effector row ascending. Its list
+     * version moves only when the list it holds did.
+     *
+     * @param {number} level an owning level
+     * @param {number} cell metres, cascade 0's cell
+     * @returns {FluidForcingTree}
+     */
+    #listed_tree(level, cell) {
+        let tree = this.#trees[level];
+
+        if (tree === undefined) {
+            tree = new FluidForcingTree();
+            tree.level = level;
+
+            tree.rows_buffer = this.#device.createBuffer({
+                label: `Fluid / forcing / leaf rows ${level}`,
+                size: 1024,
+                usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+            });
+
+            tree.nodes = this.#device.createBuffer({
+                label: `Fluid / forcing / tree ${level}`,
+                size: 1024,
+                usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC,
+            });
+
+            this.#trees[level] = tree;
+        }
+
+        if (tree.listed_sets === this.#sets_version && tree.listed_cell === cell) {
+            return tree;
+        }
+
+        const obstacles = this.#database.get(FLUID_OBSTACLE_TABLE);
+        const effectors = this.#database.get(FLUID_EFFECTOR_TABLE);
+
+        const count = this.#resolved[level] + effectors.count;
+
+        let rows = tree.rows;
+        let changed = count !== tree.count;
+
+        if (rows.length < count) {
+            rows = tree.rows = new Uint32Array(Math.max(count, 2 * rows.length));
+            changed = true;
+        }
+
+        const threshold = 0.5 * cell * 2 ** level;
+        const extent = this.#obstacle_extent;
+
+        let n = 0;
+
+        for (let row = obstacles.occupancy.nextSetBit(0); row !== -1; row = obstacles.occupancy.nextSetBit(row + 1)) {
+            if (extent[row] < threshold) {
+                continue;
+            }
+
+            if (rows[n] !== row) {
+                rows[n] = row;
+                changed = true;
+            }
+
+            n++;
+        }
+
+        const obstacle_count = n;
+
+        for (let row = effectors.occupancy.nextSetBit(0); row !== -1; row = effectors.occupancy.nextSetBit(row + 1)) {
+            if (rows[n] !== row) {
+                rows[n] = row;
+                changed = true;
+            }
+
+            n++;
+        }
+
+        assert.equal(n, count, 'every resolved obstacle and every effector is a leaf');
+
+        if (obstacle_count !== tree.obstacle_count) {
+            changed = true;
+        }
+
+        tree.count = n;
+        tree.obstacle_count = obstacle_count;
+        tree.listed_sets = this.#sets_version;
+        tree.listed_cell = cell;
+
+        if (changed) {
+            tree.list_version++;
+        }
+
+        return tree;
+    }
+
+    /**
+     * Record the frame's numbers, before any tick of it, for the trees its ticks record. Call once a
+     * frame that records ticks; with no rows, the frame's ticks record no tree and no query.
+     *
+     * @param {object} options
+     * @param {FrameGraph} options.graph
+     * @param {GPUDatabase} options.scene_database the scene's database, whose `transforms` the rows'
+     *   nodes are; its buffer is read when the graph runs
+     * @param {ArrayLike<number>} options.bounds world metres, `[x0, y0, z0, x1, y1, z1]`: the union of
+     *   the coarsest windows of the stacks the frame steps. Every leaf is clipped to it grown by its
+     *   own extent on every side, so a placement during the frame's ticks stays inside, and a plane, a
+     *   heightmap's box or a far row stays finite
+     * @param {number} options.sweep_time seconds: the longest step of the frame's stepping cascades,
+     *   `dt·2^c` over its ticks, which a wake's box is swept back over
+     * @param {number} options.inverse_frame_dt `1 / (frame_dt · fixedStepTimeScale)`, 0 when no game
+     *   time passed: what a wake's node velocity is taken with
+     * @param {number} options.cell_size metres: the finest cascade cell of the frame, cascade 0's, by
+     *   which every obstacle box is dilated on its + sides, and against which a cascade's level is
+     *   counted
+     */
+    record_frame({ graph, scene_database, bounds, sweep_time, inverse_frame_dt, cell_size }) {
+        assert.notOk(this.#destroyed, 'destroyed');
+        assert.defined(graph, 'graph');
+        assert.defined(scene_database, 'scene_database');
+        assert.isFinite(sweep_time, 'sweep_time');
+        assert.greaterThanOrEqual(sweep_time, 0, 'sweep_time');
+        assert.isFinite(inverse_frame_dt, 'inverse_frame_dt');
+        assert.greaterThanOrEqual(inverse_frame_dt, 0, 'inverse_frame_dt');
+        assert.isFinite(cell_size, 'cell_size');
+        assert.greaterThan(cell_size, 0, 'cell_size');
+
+        // a new frame: every tree is recorded again by the first tick that needs it
+        this.#frame_serial++;
+
+        const frame = this.#frame;
+        frame.graph = null;
+
+        if (this.leaf_count === 0) {
+            return;
+        }
+
+        for (let axis = 0; axis < 3; axis++) {
+            const low = bounds[axis];
+            const high = bounds[axis + 3];
+
+            assert.isFinite(low, 'bounds');
+            assert.isFinite(high, 'bounds');
+            assert.lessThanOrEqual(low, high, 'bounds');
+
+            const extent = high - low;
+
+            frame.clip_low[axis] = low - extent;
+            frame.clip_high[axis] = high + extent;
+        }
+
+        frame.graph = graph;
+        frame.scene_database = scene_database;
+        frame.dilation = cell_size;
+        frame.sweep_time = sweep_time;
+        frame.inverse_frame_dt = inverse_frame_dt;
+    }
+
+    /**
+     * The tree a cascade's queries search this frame, recorded into the frame's graph by the first
+     * tick that asks for it: L1 and L2 over its level's leaves. An empty tree records nothing.
+     *
+     * @param {GPUFluidCascade} cascade
+     * @returns {FluidForcingTree}
+     */
+    #frame_tree(cascade) {
+        const frame = this.#frame;
+        const cell = frame.dilation;
+
+        const level = Math.round(Math.log2(cascade.cell_size / cell));
+
+        assert.isNonNegativeInteger(level, 'a cascade\'s cell is cascade 0\'s times a power of two');
+        assert.lessThan(level, GPU_FLUID_CASCADE_STACK_LIMIT, 'level');
+        assert.equal(cell * 2 ** level, cascade.cell_size, 'a cascade\'s cell is cascade 0\'s times a power of two');
+
+        this.#refresh_owners(cell);
+
+        const tree = this.#listed_tree(this.#owners[level], cell);
+
+        if (tree.frame === this.#frame_serial) {
+            return tree;
+        }
+
+        tree.frame = this.#frame_serial;
+        tree.frame_nodes = -1;
+        tree.update = 'none';
+
+        const leaf_count = tree.count;
+
+        if (leaf_count === 0) {
+            return tree;
+        }
+
+        const graph = frame.graph;
+        const device = this.#device;
+
+        // the leaf list, uploaded in the extraction when it moved
+        const rows_size = 4 * leaf_count;
+
+        if (tree.rows_buffer.size < rows_size) {
+            tree.rows_buffer.destroy();
+            tree.rows_buffer = device.createBuffer({
+                label: `Fluid / forcing / leaf rows ${tree.level}`,
+                size: Math.max(rows_size, 2 * tree.rows_buffer.size),
+                usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+            });
+            tree.rows_gpu_version = -1;
+        }
+
+        // the tree; a new buffer holds no tree to refit
+        const tree_size = bvh_buffer_size(leaf_count);
+
+        if (tree.nodes.size < tree_size) {
+            tree.nodes.destroy();
+            tree.nodes = device.createBuffer({
+                label: `Fluid / forcing / tree ${tree.level}`,
+                size: Math.max(tree_size, 2 * tree.nodes.size),
+                usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC,
+            });
+            tree.tree_leaf_count = -1;
+        }
+
+        const extract = this.#free_extracts.pop() ?? {
+            forcing: this,
+            tree: null,
+            scene_database: null,
+            upload_leaves: false,
+            leaf_bounds: -1,
+            leaf_payload: -1,
+            scene_bounds: -1,
+            settings: {
+                clip_low: new Float32Array(3),
+                leaf_count: 0,
+                clip_high: new Float32Array(3),
+                obstacle_leaf_count: 0,
+                dilation: 0,
+                sweep_time: 0,
+                inverse_frame_dt: 0,
+            },
+        };
+
+        const settings = extract.settings;
+
+        settings.clip_low.set(frame.clip_low);
+        settings.clip_high.set(frame.clip_high);
+        settings.leaf_count = leaf_count;
+        settings.obstacle_leaf_count = tree.obstacle_count;
+        settings.dilation = cell;
+        settings.sweep_time = frame.sweep_time;
+        settings.inverse_frame_dt = frame.inverse_frame_dt;
+
+        extract.tree = tree;
+        extract.scene_database = frame.scene_database;
+        extract.upload_leaves = tree.rows_gpu_version !== tree.list_version;
+        tree.rows_gpu_version = tree.list_version;
+
+        const pass = graph.add('Fluid / forcing / extract', extract, GPUFluidForcing.#execute_extract);
+
+        const kept = tree.descriptors;
+
+        extract.leaf_bounds = pass.create('Fluid / forcing / leaf bounds', GPUFluidForcing.#descriptor(kept, ROLE_LEAF_BOUNDS, 24 * leaf_count, GPUBufferUsage.STORAGE, 0));
+        extract.leaf_payload = pass.create('Fluid / forcing / leaf payload', GPUFluidForcing.#descriptor(kept, ROLE_LEAF_PAYLOAD, 4 * leaf_count, GPUBufferUsage.STORAGE, 0));
+        extract.scene_bounds = pass.create('Fluid / forcing / centroid bounds', GPUFluidForcing.#descriptor(kept, ROLE_SCENE_BOUNDS, SCENE_BOUNDS_SEED.byteLength, GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST, 0));
+
+        // it uploads the database, which is not the graph's
+        pass.make_side_effect();
+
+        if (tree.nodes_described !== tree.nodes) {
+            tree.nodes_descriptor = BufferResourceDescriptor.fromBuffer(tree.nodes);
+            tree.nodes_described = tree.nodes;
+        }
+
+        const nodes = graph.import_resource(`Fluid / forcing / tree ${tree.level}`, tree.nodes_descriptor, tree.nodes);
+
+        const rebuild = leaf_count <= SORT_TILE_SIZE
+            || tree.tree_leaf_count !== leaf_count
+            || tree.tree_version !== tree.list_version
+            || tree.age + 1 >= FLUID_FORCING_REBUILD_AGE;
+
+        if (rebuild) {
+            tree.frame_nodes = graph_bvh_build_lbvh({
+                graph,
+                leaf_bounds: extract.leaf_bounds,
+                leaf_payload: extract.leaf_payload,
+                scene_bounds: extract.scene_bounds,
+                element_count: leaf_count,
+                nodes,
+            }).nodes;
+
+            tree.tree_leaf_count = leaf_count;
+            tree.tree_version = tree.list_version;
+            tree.age = 0;
+            tree.update = 'build';
+        } else {
+            tree.frame_nodes = graph_bvh_refit_lbvh({
+                graph,
+                leaf_bounds: extract.leaf_bounds,
+                element_count: leaf_count,
+                nodes,
+            }).nodes;
+
+            tree.age++;
+            tree.update = 'refit';
+        }
+
+        return tree;
+    }
+
+    /**
+     * @param {object} record
+     * @param {FramePassResources} resources
+     * @param {{encoder: ShadeGPUCommandContext}} context
+     */
+    static #execute_extract(record, resources, context) {
+        const forcing = record.forcing;
+
+        try {
+            if (!forcing.#destroyed) {
+                forcing.#encode_extract(context.encoder, resources, record);
+            }
+        } finally {
+            record.tree = null;
+            record.scene_database = null;
+            forcing.#free_extracts.push(record);
+        }
+    }
+
+    /** Bindings of the extraction, rebound for every tree. */
+    #extract_dispatch = {
+        encoder: null,
+        thread_count_x: 0,
+        bindings: { settings: null, fluid_database: null, scene_database: null, leaf_rows: null, leaf_bounds: null, leaf_payload: null, scene_bounds: null },
+    };
+
+    #encode_extract(encoder, resources, record) {
+        const database = this.#database;
+        const tree = record.tree;
+
+        // the rows first: the extraction and every query of the frame read what this uploads; the
+        // frame's first extraction finds them pending
+        if (database.has_pending_upload) {
+            database.update(encoder);
+        }
+
+        if (record.upload_leaves) {
+            encoder.writeBuffer(tree.rows_buffer, 0, tree.rows.buffer, 0, 4 * record.settings.leaf_count);
+        }
+
+        const scene_bounds = resources.get(record.scene_bounds);
+
+        // seeded rather than cleared: the merge is a min/max, and zero is not an identity for either
+        encoder.writeBuffer(scene_bounds, 0, SCENE_BOUNDS_SEED.buffer, 0, SCENE_BOUNDS_SEED.byteLength);
+
+        const dispatch = this.#extract_dispatch;
+        const b = dispatch.bindings;
+
+        b.settings = encoder.allocateTransientValueBuffer(FLUID_FORCING_EXTRACT_STRUCT, record.settings, GPUBufferUsage.UNIFORM);
+        b.fluid_database = database.buffer;
+        b.scene_database = record.scene_database.buffer;
+        b.leaf_rows = tree.rows_buffer;
+        b.leaf_bounds = resources.get(record.leaf_bounds);
+        b.leaf_payload = resources.get(record.leaf_payload);
+        b.scene_bounds = scene_bounds;
+
+        dispatch.encoder = encoder;
+        dispatch.thread_count_x = record.settings.leaf_count;
+
+        shader_fluid_forcing_extract.dispatchThreads(dispatch);
+
+        dispatch.encoder = null;
+        b.settings = b.fluid_database = b.scene_database = b.leaf_rows = b.leaf_bounds = b.leaf_payload = b.scene_bounds = null;
+    }
+
+    /**
+     * Record Q1 and Q2 of a tick into `graph`, after its placement and fills: the trees the stepping
+     * cascades search, if the frame has not recorded them yet, then every brick of the stepping
+     * cascades queries its cascade's tree, and the forcing's commands are written. `second` is the
+     * ruler's coarse cascade, `null` on a tick that steps cascade 0 alone; both share a resolution.
+     * With no rows, nothing is queried; a stepping cascade whose flags the forcing wrote then has them
+     * cleared.
+     *
+     * @param {object} options
+     * @param {FrameGraph} options.graph the graph {@link record_frame} recorded into this frame
+     * @param {GPUFluidCascade} options.first cascade 0, slot 0
+     * @param {GPUFluidCascade|null} options.second the tick's coarse cascade, slot 1, or `null`
+     */
+    record_queries({ graph, first, second }) {
+        assert.notOk(this.#destroyed, 'destroyed');
+        assert.defined(graph, 'graph');
+        assert.defined(first, 'first');
+        assert.ok(second === null || second.resolution.every((n, axis) => n === first.resolution[axis]), 'the stepping cascades share a resolution');
+
+        const tick = this.#tick;
+        tick.graph = null;
+        tick.cascades[0] = first;
+        tick.cascades[1] = second;
+
+        const frame = this.#frame;
+
+        if (frame.graph === null) {
+            // no rows this frame: what the forcing left in a stepping cascade is cleared, once
+            this.#record_clear(graph, first);
+
+            if (second !== null) {
+                this.#record_clear(graph, second);
+            }
+
+            return;
+        }
+
+        assert.equal(frame.graph, graph, 'the tick is recorded into the graph record_frame recorded into this frame');
+
+        // the trees go into the graph before the queries that read them
+        const tree_0 = this.#frame_tree(first);
+        const tree_1 = second === null ? null : this.#frame_tree(second);
+
+        tick.trees[0] = tree_0;
+        tick.trees[1] = tree_1;
+
+        const resolution = first.resolution;
+        const bricks_x = resolution[0] / FLUID_FORCING_BRICK;
+        const bricks_y = resolution[1] / FLUID_FORCING_BRICK;
+        const bricks_z = resolution[2] / FLUID_FORCING_BRICK;
+        const brick_count = bricks_x * bricks_y * bricks_z;
+        const slots = second === null ? 1 : 2;
+        const query_count = slots * brick_count;
+
+        const query = this.#free_queries.pop() ?? {
+            forcing: this,
+            nodes: [-1, -1],
+            lists: [-1, -1],
+            survivors: -1,
+            bricks: [null, null],
+            group_count_x: 1,
+            group_count_y: 1,
+            settings: {
+                corner_0: new Int32Array(3),
+                cell_size_0: 1,
+                corner_1: new Int32Array(3),
+                cell_size_1: 1,
+                bricks: new Uint32Array(3),
+                brick_count: 0,
+                query_count: 0,
+                obstacle_leaf_count_0: 0,
+                obstacle_leaf_count_1: 0,
+            },
+        };
+
+        const settings = query.settings;
+
+        settings.corner_0.set(first.corner);
+        settings.cell_size_0 = first.cell_size;
+        settings.obstacle_leaf_count_0 = tree_0.obstacle_count;
+
+        if (second !== null) {
+            settings.corner_1.set(second.corner);
+            settings.cell_size_1 = second.cell_size;
+            settings.obstacle_leaf_count_1 = tree_1.obstacle_count;
+        } else {
+            settings.corner_1.fill(0);
+            settings.cell_size_1 = first.cell_size;
+            settings.obstacle_leaf_count_1 = 0;
+        }
+
+        settings.bricks[0] = bricks_x;
+        settings.bricks[1] = bricks_y;
+        settings.bricks[2] = bricks_z;
+        settings.brick_count = brick_count;
+        settings.query_count = query_count;
+
+        query.bricks[0] = first.solid_bricks;
+        query.bricks[1] = second === null ? this.#empty_bricks : second.solid_bricks;
+
+        // one workgroup a query, folded onto x, then y
+        const width = WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION;
+        query.group_count_x = Math.min(query_count, width);
+        query.group_count_y = Math.ceil(query_count / width);
+
+        const pass = graph.add('Fluid / forcing / brick query', query, GPUFluidForcing.#execute_query);
+
+        const list_size = Math.max(LIST_MINIMUM_BYTES, LIST_HEADER_BYTES + 4 * brick_count);
+        // the count is zero at the start of every tick; the elements are written before they are read
+        const list_descriptor = GPUFluidForcing.#descriptor(this.#descriptors, ROLE_LIST, list_size, GPUBufferUsage.STORAGE, 4);
+
+        // a shared tree is read once; an empty one is no resource of the graph
+        query.nodes[0] = tree_0.frame_nodes === -1 ? -1 : pass.read(tree_0.frame_nodes);
+        query.nodes[1] = tree_1 === null || tree_1.frame_nodes === -1
+            ? -1
+            : tree_1 === tree_0 ? query.nodes[0] : pass.read(tree_1.frame_nodes);
+
+        query.lists[0] = pass.create('Fluid / forcing / bricks 0', list_descriptor);
+        query.lists[1] = second === null ? -1 : pass.create('Fluid / forcing / bricks 1', list_descriptor);
+        query.survivors = pass.create('Fluid / forcing / survivors', GPUFluidForcing.#descriptor(this.#descriptors, ROLE_SURVIVORS, 4 * FLUID_FORCING_SURVIVOR_STRIDE * query_count, GPUBufferUsage.STORAGE, 0));
+
+        // it writes the cascades' brick words and the drop counters
+        pass.make_side_effect();
+
+        const command = this.#free_commands.pop() ?? { forcing: this, lists: [-1, -1], commands: -1 };
+
+        const command_pass = graph.add('Fluid / forcing / commands', command, GPUFluidForcing.#execute_command);
+
+        command.lists[0] = command_pass.read(query.lists[0]);
+        command.lists[1] = second === null ? -1 : command_pass.read(query.lists[1]);
+        command.commands = command_pass.create('Fluid / forcing / commands', GPUFluidForcing.#descriptor(this.#descriptors, ROLE_COMMANDS, 4 * 2 * FLUID_FORCING_COMMAND_WORDS, GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT, 0));
+
+        tick.graph = graph;
+        tick.lists[0] = query.lists[0];
+        tick.lists[1] = query.lists[1];
+        tick.survivors = query.survivors;
+        tick.commands = command.commands;
+    }
+
+    /**
+     * Clear a cascade's solid flags and brick words, if the forcing wrote them since they were last
+     * cleared.
+     *
+     * @param {FrameGraph} graph
+     * @param {GPUFluidCascade} cascade
+     */
+    #record_clear(graph, cascade) {
+        if (!this.#written.has(cascade)) {
+            return;
+        }
+
+        this.#written.delete(cascade);
+
+        const record = this.#free_clears.pop() ?? { forcing: this, cascade: null };
+        record.cascade = cascade;
+
+        graph.add('Fluid / forcing / clear', record, GPUFluidForcing.#execute_clear).make_side_effect();
+    }
+
+    static #execute_clear(record, _resources, context) {
+        const forcing = record.forcing;
+
+        try {
+            const cascade = record.cascade;
+
+            if (!forcing.#destroyed) {
+                context.encoder.clearBuffer(cascade.solid);
+                context.encoder.clearBuffer(cascade.solid_bricks);
+            }
+        } finally {
+            record.cascade = null;
+            forcing.#free_clears.push(record);
+        }
+    }
+
+    /** Bindings of the query, rebound for every tick. */
+    #query_dispatch = {
+        encoder: null,
+        group_count_x: 1,
+        group_count_y: 1,
+        group_count_z: 1,
+        bindings: { settings: null, tree_0: null, tree_1: null, list_0: null, list_1: null, survivors: null, bricks_0: null, bricks_1: null, statistics: null },
+    };
+
+    static #execute_query(record, resources, context) {
+        const forcing = record.forcing;
+
+        try {
+            if (!forcing.#destroyed) {
+                const encoder = context.encoder;
+                const dispatch = forcing.#query_dispatch;
+                const b = dispatch.bindings;
+
+                b.settings = encoder.allocateTransientValueBuffer(FLUID_FORCING_QUERY_STRUCT, record.settings, GPUBufferUsage.UNIFORM);
+                b.tree_0 = record.nodes[0] === -1 ? forcing.#empty_tree : resources.get(record.nodes[0]);
+                // a lone cascade's second slot is never queried
+                b.tree_1 = record.nodes[1] === -1 ? forcing.#empty_tree : resources.get(record.nodes[1]);
+                b.list_0 = resources.get(record.lists[0]);
+                b.list_1 = record.lists[1] === -1 ? forcing.#empty_list : resources.get(record.lists[1]);
+                b.survivors = resources.get(record.survivors);
+                b.bricks_0 = record.bricks[0];
+                b.bricks_1 = record.bricks[1];
+                b.statistics = forcing.#statistics;
+
+                dispatch.encoder = encoder;
+                dispatch.group_count_x = record.group_count_x;
+                dispatch.group_count_y = record.group_count_y;
+
+                shader_fluid_forcing_query.dispatch(dispatch);
+
+                dispatch.encoder = null;
+                b.settings = b.tree_0 = b.tree_1 = b.list_0 = b.list_1 = b.survivors = b.bricks_0 = b.bricks_1 = b.statistics = null;
+            }
+        } finally {
+            record.bricks[0] = record.bricks[1] = null;
+            forcing.#free_queries.push(record);
+        }
+    }
+
+    /** Bindings of the commands, rebound for every tick. */
+    #command_dispatch = {
+        encoder: null,
+        group_count_x: 1,
+        group_count_y: 1,
+        group_count_z: 1,
+        bindings: { list_0: null, list_1: null, commands: null },
+    };
+
+    static #execute_command(record, resources, context) {
+        const forcing = record.forcing;
+
+        try {
+            if (!forcing.#destroyed) {
+                const dispatch = forcing.#command_dispatch;
+                const b = dispatch.bindings;
+
+                b.list_0 = resources.get(record.lists[0]);
+                b.list_1 = record.lists[1] === -1 ? forcing.#empty_list : resources.get(record.lists[1]);
+                b.commands = resources.get(record.commands);
+
+                dispatch.encoder = context.encoder;
+
+                shader_fluid_forcing_command.dispatch(dispatch);
+
+                dispatch.encoder = null;
+                b.list_0 = b.list_1 = b.commands = null;
+            }
+        } finally {
+            forcing.#free_commands.push(record);
+        }
+    }
+
+    /**
+     * Record Q3 for one stepping cascade of the tick {@link record_queries} recorded, before that
+     * cascade's step (after its restriction): its solid flags, the wall's velocity at every face it
+     * pins, and the tick's forcing.
+     *
+     * @param {object} options
+     * @param {FrameGraph} options.graph
+     * @param {GPUFluidCascade} options.cascade the tick's `first` (slot 0) or `second` (slot 1)
+     * @param {number} options.dt seconds, the cascade's step, `dt·2^c`
+     * @returns {number|null} the forcing, a buffer resource of `graph` for the cascade's
+     *   `record_step`; `null` when nothing was recorded (no rows)
+     */
+    record_forcing({ graph, cascade, dt }) {
+        assert.notOk(this.#destroyed, 'destroyed');
+        assert.isFinite(dt, 'dt');
+        assert.greaterThan(dt, 0, 'dt');
+
+        const tick = this.#tick;
+
+        if (tick.graph === null) {
+            return null;
+        }
+
+        assert.equal(tick.graph, graph, 'the forcing is recorded into the tick\'s graph');
+
+        const slot = tick.cascades[0] === cascade ? 0 : 1;
+
+        assert.equal(tick.cascades[slot], cascade, 'the cascade steps on the tick');
+
+        const resolution = cascade.resolution;
+        const nx = resolution[0], ny = resolution[1], nz = resolution[2];
+
+        const apply = this.#free_applies.pop() ?? {
+            forcing: this,
+            cascade: null,
+            tree: null,
+            slot: 0,
+            list: -1,
+            survivors: -1,
+            commands: -1,
+            output: -1,
+            settings: {
+                cells: fluid_cascade_window_value(),
+                faces_u: fluid_cascade_window_value(),
+                faces_v: fluid_cascade_window_value(),
+                faces_w: fluid_cascade_window_value(),
+                bricks: new Uint32Array(3),
+                query_base: 0,
+                cell_size: 1,
+                dt: 0,
+                inverse_frame_dt: 0,
+                forcing_v: 0,
+                forcing_w: 0,
+            },
+        };
+
+        const settings = apply.settings;
+        const corner = cascade.corner;
+
+        fluid_cascade_window_place(settings.cells, corner, resolution, -1);
+        fluid_cascade_window_place(settings.faces_u, corner, resolution, 0);
+        fluid_cascade_window_place(settings.faces_v, corner, resolution, 1);
+        fluid_cascade_window_place(settings.faces_w, corner, resolution, 2);
+
+        settings.bricks[0] = nx / FLUID_FORCING_BRICK;
+        settings.bricks[1] = ny / FLUID_FORCING_BRICK;
+        settings.bricks[2] = nz / FLUID_FORCING_BRICK;
+        settings.query_base = slot * settings.bricks[0] * settings.bricks[1] * settings.bricks[2];
+        settings.cell_size = cascade.cell_size;
+        settings.dt = dt;
+        settings.inverse_frame_dt = this.#frame.inverse_frame_dt;
+
+        const faces_u = (nx + 1) * ny * nz;
+        const faces_v = nx * (ny + 1) * nz;
+        const faces_w = nx * ny * (nz + 1);
+
+        settings.forcing_v = faces_u;
+        settings.forcing_w = faces_u + faces_v;
+
+        apply.cascade = cascade;
+        apply.tree = tick.trees[slot];
+        apply.slot = slot;
+
+        const pass = graph.add('Fluid / forcing / apply', apply, GPUFluidForcing.#execute_apply);
+
+        apply.list = pass.read(tick.lists[slot]);
+        apply.survivors = pass.read(tick.survivors);
+        apply.commands = pass.read(tick.commands);
+        apply.output = pass.create('Fluid / forcing / forcing', GPUFluidForcing.#descriptor(this.#descriptors, ROLE_FORCING, 4 * (faces_u + faces_v + faces_w), GPUBufferUsage.STORAGE, 0));
+
+        // it writes the cascade's flags and persistent faces
+        pass.make_side_effect();
+
+        this.#written.add(cascade);
+
+        return apply.output;
+    }
+
+    /** Bindings of the forcing, rebound for every cascade. */
+    #apply_dispatch = {
+        encoder: null,
+        command: null,
+        command_offset: 0,
+        bindings: {
+            settings: null, fluid_database: null, scene_database: null, list: null, survivors: null, leaf_rows: null,
+            solid: null, forcing: null, out_u: null, out_v: null, out_w: null,
+        },
+    };
+
+    static #execute_apply(record, resources, context) {
+        const forcing = record.forcing;
+
+        try {
+            const cascade = record.cascade;
+
+            if (!forcing.#destroyed) {
+                const encoder = context.encoder;
+                const dispatch = forcing.#apply_dispatch;
+                const b = dispatch.bindings;
+                const velocity = cascade.velocity;
+
+                b.settings = encoder.allocateTransientValueBuffer(FLUID_FORCING_APPLY_STRUCT, record.settings, GPUBufferUsage.UNIFORM);
+                b.fluid_database = forcing.#database.buffer;
+                b.scene_database = forcing.#frame.scene_database.buffer;
+                b.list = resources.get(record.list);
+                b.survivors = resources.get(record.survivors);
+                // the survivors are leaves of the slot's tree
+                b.leaf_rows = record.tree.rows_buffer;
+                b.solid = cascade.solid;
+                b.forcing = resources.get(record.output);
+                b.out_u = velocity.u;
+                b.out_v = velocity.v;
+                b.out_w = velocity.w;
+
+                dispatch.encoder = encoder;
+                dispatch.command = resources.get(record.commands);
+                dispatch.command_offset = 4 * FLUID_FORCING_COMMAND_WORDS * record.slot;
+
+                shader_fluid_forcing_apply.dispatchIndirect(dispatch);
+
+                dispatch.encoder = null;
+                dispatch.command = null;
+
+                b.settings = b.fluid_database = b.scene_database = b.list = b.survivors = b.leaf_rows = null;
+                b.solid = b.forcing = b.out_u = b.out_v = b.out_w = null;
+            }
+        } finally {
+            record.cascade = null;
+            record.tree = null;
+            forcing.#free_applies.push(record);
+        }
+    }
+
+    /**
+     * Release the database, the trees and the buffers. Passes recorded into a graph that has not run
+     * yet encode nothing.
+     */
+    destroy() {
+        if (this.#destroyed) {
+            return;
+        }
+
+        this.#destroyed = true;
+
+        this.#database.destroy();
+
+        for (const tree of this.#trees) {
+            if (tree === undefined) {
+                continue;
+            }
+
+            tree.rows_buffer.destroy();
+            tree.nodes.destroy();
+        }
+
+        this.#empty_tree.destroy();
+        this.#statistics.destroy();
+        this.#empty_list.destroy();
+        this.#empty_bricks.destroy();
+
+        this.#written = new WeakSet();
+    }
+}