@woosh/meep-engine 3.49.0 → 3.50.0

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

@@ -0,0 +1,349 @@
+import { assert } from "../../../core/assert.js";
+import { ClipmapWindowSet } from "../../../core/geom/clipmap/ClipmapWindowSet.js";
+import { isPowerOfTwo } from "../../../core/math/isPowerOfTwo.js";
+
+/**
+ * Cells a cascade's corner moves in: even for exact restriction, in 4s for the 4-cell bricks of
+ * cell-centred data (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §7, D2).
+ * @type {number}
+ */
+export const FLUID_CASCADE_CORNER_STEP = 4;
+
+/**
+ * Cells past half a corner step the anchor goes from a window's centre before it moves: re-placed past
+ * 2.1 cells (§7).
+ * @type {number}
+ */
+export const FLUID_CASCADE_HYSTERESIS = 0.1;
+
+/**
+ * Parent cells a child's window keeps from every face of its parent's: the published read's edge band
+ * (`chunk_wind_field_sample` blends a cascade with its parent across its outer 5 cells, the face row
+ * and WRF rows 2..5, and takes at most two taps), so no child reaches into its parent's band and a
+ * read never needs a third. Corners on the 4-cell lattice make the kept margin 6 in practice.
+ * @type {number}
+ */
+export const FLUID_CASCADE_NEST_MARGIN = 5;
+
+/**
+ * Smallest window side, cells, that nests: a child covers half its parent, so the other half must
+ * hold the margin on both sides, rounded out to the corner lattice.
+ * @type {number}
+ */
+export const FLUID_CASCADE_NEST_RESOLUTION_MIN = 32;
+
+/**
+ * What {@link FluidCascadePlacement#place} did.
+ * @readonly
+ * @enum {number}
+ */
+export const FluidCascadePlacementResult = Object.freeze({
+    /** The window held. */
+    Held: 0,
+    /** The window moved, and the rest of the stack stayed. */
+    Moved: 1,
+    /** The move would have left a child outside its parent: the whole stack was re-placed. */
+    Jumped: 2,
+});
+
+/**
+ * Round down to a multiple of `step`.
+ */
+function floor_to(value, step) {
+    return Math.floor(value / step) * step;
+}
+
+/**
+ * Round up to a multiple of `step`.
+ */
+function ceil_to(value, step) {
+    return Math.ceil(value / step) * step;
+}
+
+/**
+ * Where the windows of a stack of fluid cascades are (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §7): the
+ * CPU half of `GPUFluidCascadeStack`, on the CPU alone so that placement is pinned without a device.
+ *
+ * Cascade `c` has cells of `cell_size·2^c` and the same resolution N; its window is
+ * `[corner, corner + N)` in its own cells, and world cell `g` of it covers `[g·h_c, (g + 1)·h_c)`, so
+ * the lattices nest: child cells `2G` and `2G + 1` lie in parent cell `G`. Every corner change goes
+ * through S0's window maths: {@link ClipmapWindowSet} places, `window_scroll_regions` (the stack's) says
+ * what a move exposed, and storage wraps, so a window that moves keeps every cell it still holds.
+ *
+ * **Placement** ({@link place}), on a cascade's own step tick, coarsest first:
+ * 1. the hysteretic rule (`ClipmapWindowSet#place`, corners in 4s, moved past 2.1 cells of the anchor);
+ * 2. a jump check: if that leaves the cascade's window not inside its parent's, or its child's window
+ *    not inside its own, the move is a jump and the **whole stack is re-placed**
+ *    ({@link place_all});
+ * 3. the nesting clamp (`ClipmapWindowSet#clamp_corner`): the corner is held so that its window keeps
+ *    {@link FLUID_CASCADE_NEST_MARGIN} parent cells inside its parent's, and so that its child's
+ *    window keeps the margin inside its own. Both ranges hold the corner it had, so both clamps
+ *    together land in both.
+ *
+ * {@link place_all} places every cascade, coarsest first, by the hysteretic rule, and clamps each into
+ * its parent: the first placement, and the answer to a jump.
+ *
+ * {@link begin} remembers every corner, so that after a tick's placements {@link moved} and
+ * {@link previous_corner} say what to fill.
+ *
+ * Nothing here allocates once constructed.
+ */
+export class FluidCascadePlacement {
+    /** @type {ClipmapWindowSet} */
+    #windows;
+
+    /** @type {Int32Array} */
+    #resolution = new Int32Array(3);
+
+    /** @type {number} */
+    #cell_size;
+
+    /** @type {number} */
+    #cascade_count;
+
+    /** Every cascade's corner at {@link begin}, x, y, z a cascade. @type {Int32Array} */
+    #previous;
+
+    #placed = false;
+
+    /**
+     * @param {object} options
+     * @param {number} options.cascade_count 1 to 8
+     * @param {ArrayLike<number>} options.resolution cells on each axis, powers of two; at least
+     *   {@link FLUID_CASCADE_NEST_RESOLUTION_MIN} when there is more than one cascade
+     * @param {number} options.cell_size metres, cascade 0's
+     */
+    constructor({ cascade_count, resolution, cell_size }) {
+        assert.isPositiveInteger(cascade_count, 'cascade_count');
+        assert.lessThanOrEqual(cascade_count, 8, 'cascade_count');
+        assert.isFinite(cell_size, 'cell_size');
+        assert.greaterThan(cell_size, 0, 'cell_size');
+
+        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.ok(cascade_count === 1 || resolution[axis] >= FLUID_CASCADE_NEST_RESOLUTION_MIN, `cascades nest from ${FLUID_CASCADE_NEST_RESOLUTION_MIN} cells an axis`);
+
+            this.#resolution[axis] = resolution[axis];
+        }
+
+        this.#cascade_count = cascade_count;
+        this.#cell_size = cell_size;
+        this.#previous = new Int32Array(3 * cascade_count);
+
+        this.#windows = new ClipmapWindowSet({
+            level_count: cascade_count,
+            dimensions: 3,
+            size: this.#resolution,
+            step: FLUID_CASCADE_CORNER_STEP,
+            hysteresis: FLUID_CASCADE_HYSTERESIS,
+        });
+    }
+
+    /** @returns {number} */
+    get cascade_count() {
+        return this.#cascade_count;
+    }
+
+    /** @returns {Readonly<Int32Array>} */
+    get resolution() {
+        return this.#resolution;
+    }
+
+    /**
+     * Whether the stack has been placed.
+     * @returns {boolean}
+     */
+    get placed() {
+        return this.#placed;
+    }
+
+    /**
+     * A cascade's cell, metres: `cell_size·2^c`.
+     * @param {number} cascade
+     * @returns {number}
+     */
+    cell_size(cascade) {
+        return this.#cell_size * 2 ** cascade;
+    }
+
+    /**
+     * @param {number} cascade
+     * @param {number} axis
+     * @returns {number} the cascade's corner on the axis, in its own cells
+     */
+    corner(cascade, axis) {
+        return this.#windows.corner(cascade, axis);
+    }
+
+    /**
+     * @param {number} cascade
+     * @param {number} axis
+     * @returns {number} the corner it had at the last {@link begin}
+     */
+    previous_corner(cascade, axis) {
+        return this.#previous[3 * cascade + axis];
+    }
+
+    /**
+     * @param {number} cascade
+     * @returns {boolean} whether its corner moved since the last {@link begin}
+     */
+    moved(cascade) {
+        const base = 3 * cascade;
+
+        return this.#previous[base] !== this.corner(cascade, 0)
+            || this.#previous[base + 1] !== this.corner(cascade, 1)
+            || this.#previous[base + 2] !== this.corner(cascade, 2);
+    }
+
+    /**
+     * Remember every corner: what {@link moved} and {@link previous_corner} compare with.
+     */
+    begin() {
+        for (let c = 0; c < this.#cascade_count; c++) {
+            for (let axis = 0; axis < 3; axis++) {
+                this.#previous[3 * c + axis] = this.#placed ? this.corner(c, axis) : 0;
+            }
+        }
+    }
+
+    /**
+     * The range of corners on one axis that keeps a child of corner `child` nested `margin` cells
+     * (its own) inside a parent of corner `parent`, both in the child's cells: `[lo, hi]`, on the
+     * corner lattice.
+     */
+    #nest_low(parent_in_child_cells, margin) {
+        return ceil_to(parent_in_child_cells + margin, FLUID_CASCADE_CORNER_STEP);
+    }
+
+    #nest_high(parent_in_child_cells, n, margin) {
+        return floor_to(parent_in_child_cells + 2 * n - n - margin, FLUID_CASCADE_CORNER_STEP);
+    }
+
+    /**
+     * Whether cascade `child`'s window lies inside cascade `child + 1`'s, margin or not.
+     */
+    #inside_parent(child) {
+        for (let axis = 0; axis < 3; axis++) {
+            const p = 2 * this.corner(child + 1, axis);
+            const c = this.corner(child, axis);
+            const n = this.#resolution[axis];
+
+            if (c < p || c + n > p + 2 * n) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    /**
+     * Hold cascade `c` nested inside its parent, and its child nested inside it.
+     */
+    #clamp(c) {
+        const windows = this.#windows;
+        const margin = 2 * FLUID_CASCADE_NEST_MARGIN;
+
+        for (let axis = 0; axis < 3; axis++) {
+            const n = this.#resolution[axis];
+
+            if (c + 1 < this.#cascade_count) {
+                const p = 2 * this.corner(c + 1, axis);
+
+                windows.clamp_corner(c, axis, this.#nest_low(p, margin), this.#nest_high(p, n, margin));
+            }
+
+            if (c > 0) {
+                // the child's corner in this cascade's cells, and the range of corners that keep it nested
+                const child = this.corner(c - 1, axis);
+                const lo = ceil_to((child + margin - n) / 2, FLUID_CASCADE_CORNER_STEP);
+                const hi = floor_to((child - margin) / 2, FLUID_CASCADE_CORNER_STEP);
+
+                windows.clamp_corner(c, axis, lo, hi);
+            }
+        }
+    }
+
+    /**
+     * Place every cascade, coarsest first, by the hysteretic rule, each child clamped into its parent.
+     *
+     * @param {number} x the anchor, world metres
+     * @param {number} y
+     * @param {number} z
+     */
+    place_all(x, y, z) {
+        assert.isFinite(x, 'x');
+        assert.isFinite(y, 'y');
+        assert.isFinite(z, 'z');
+
+        const windows = this.#windows;
+        const margin = 2 * FLUID_CASCADE_NEST_MARGIN;
+
+        for (let c = this.#cascade_count - 1; c >= 0; c--) {
+            const h = this.cell_size(c);
+
+            windows.place(c, x / h, y / h, z / h);
+
+            if (c + 1 < this.#cascade_count) {
+                for (let axis = 0; axis < 3; axis++) {
+                    const p = 2 * this.corner(c + 1, axis);
+
+                    windows.clamp_corner(c, axis, this.#nest_low(p, margin), this.#nest_high(p, this.#resolution[axis], margin));
+                }
+            }
+        }
+
+        this.#placed = true;
+    }
+
+    /**
+     * Place one cascade on its own step tick: the hysteretic rule, then the jump check, then the
+     * nesting clamp. Before the first {@link place_all} this places the whole stack.
+     *
+     * @param {number} cascade
+     * @param {number} x the anchor, world metres
+     * @param {number} y
+     * @param {number} z
+     * @returns {FluidCascadePlacementResult}
+     */
+    place(cascade, x, y, z) {
+        assert.isNonNegativeInteger(cascade, 'cascade');
+        assert.lessThan(cascade, this.#cascade_count, 'cascade');
+        assert.isFinite(x, 'x');
+        assert.isFinite(y, 'y');
+        assert.isFinite(z, 'z');
+
+        if (!this.#placed) {
+            this.place_all(x, y, z);
+
+            return FluidCascadePlacementResult.Jumped;
+        }
+
+        const windows = this.#windows;
+        const h = this.cell_size(cascade);
+
+        const before_x = this.corner(cascade, 0);
+        const before_y = this.corner(cascade, 1);
+        const before_z = this.corner(cascade, 2);
+
+        windows.place(cascade, x / h, y / h, z / h);
+
+        const leaves_parent = cascade + 1 < this.#cascade_count && !this.#inside_parent(cascade);
+        const leaves_child = cascade > 0 && !this.#inside_parent(cascade - 1);
+
+        if (leaves_parent || leaves_child) {
+            this.place_all(x, y, z);
+
+            return FluidCascadePlacementResult.Jumped;
+        }
+
+        this.#clamp(cascade);
+
+        const moved = this.corner(cascade, 0) !== before_x
+            || this.corner(cascade, 1) !== before_y
+            || this.corner(cascade, 2) !== before_z;
+
+        return moved ? FluidCascadePlacementResult.Moved : FluidCascadePlacementResult.Held;
+    }
+}