@woosh/meep-engine 2.138.20 → 2.140.0

package/src/engine/physics/fluid/solver/v3_grid_apply_scalar_advection.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Semi-Lagrangian advection of a scalar field by a separate velocity field.
+ *
+ * For each cell, traces backward by `(vel_x, vel_y, vel_z) * time_delta` and trilinearly
+ * samples the input scalar at the back-traced position. Unconditionally stable for any
+ * timestep. Used to transport densities, temperatures, or any passive quantity by the
+ * flow.
+ *
+ * @param {Float32Array} output       Destination, mutated. Length = res_x*res_y*res_z.
+ * @param {Float32Array} input        Scalar values to advect. Must not alias `output`.
+ * @param {Float32Array} vel_x        Velocity X component (cell-centered).
+ * @param {Float32Array} vel_y        Velocity Y component (cell-centered).
+ * @param {Float32Array} vel_z        Velocity Z component (cell-centered).
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {number} time_delta
+ * @param {Uint8Array} solid          Required cell flags (zero-filled for a wall-free
+ *                                    domain); solid cells get their input value
+ *                                    passed through unchanged.
+ */
+export function v3_grid_apply_scalar_advection(output: Float32Array, input: Float32Array, vel_x: Float32Array, vel_y: Float32Array, vel_z: Float32Array, res_x: number, res_y: number, res_z: number, time_delta: number, solid: Uint8Array): void;
+//# sourceMappingURL=v3_grid_apply_scalar_advection.d.ts.map

package/src/engine/physics/fluid/solver/v3_grid_apply_scalar_advection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"v3_grid_apply_scalar_advection.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_apply_scalar_advection.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,uDAbW,YAAY,SACZ,YAAY,SACZ,YAAY,SACZ,YAAY,SACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,SACN,UAAU,QAuCpB"}

package/src/engine/physics/fluid/solver/v3_grid_apply_scalar_advection.js

@@ -0,0 +1,60 @@
+import { assert } from "../../../../core/assert.js";
+import { scs3d_sample_linear } from "../../../graphics/texture/3d/scs3d_sample_linear.js";
+
+/**
+ * Semi-Lagrangian advection of a scalar field by a separate velocity field.
+ *
+ * For each cell, traces backward by `(vel_x, vel_y, vel_z) * time_delta` and trilinearly
+ * samples the input scalar at the back-traced position. Unconditionally stable for any
+ * timestep. Used to transport densities, temperatures, or any passive quantity by the
+ * flow.
+ *
+ * @param {Float32Array} output       Destination, mutated. Length = res_x*res_y*res_z.
+ * @param {Float32Array} input        Scalar values to advect. Must not alias `output`.
+ * @param {Float32Array} vel_x        Velocity X component (cell-centered).
+ * @param {Float32Array} vel_y        Velocity Y component (cell-centered).
+ * @param {Float32Array} vel_z        Velocity Z component (cell-centered).
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {number} time_delta
+ * @param {Uint8Array} solid          Required cell flags (zero-filled for a wall-free
+ *                                    domain); solid cells get their input value
+ *                                    passed through unchanged.
+ */
+export function v3_grid_apply_scalar_advection(output, input, vel_x, vel_y, vel_z, res_x, res_y, res_z, time_delta, solid) {
+    assert.notEqual(output, input, "output must not alias input");
+
+    const cell_count = res_x * res_y * res_z;
+
+    assert.greaterThanOrEqual(output.length, cell_count, "output covers grid");
+    assert.greaterThanOrEqual(input.length, cell_count, "input covers grid");
+    assert.greaterThanOrEqual(vel_x.length, cell_count, "vel_x covers grid");
+    assert.greaterThanOrEqual(vel_y.length, cell_count, "vel_y covers grid");
+    assert.greaterThanOrEqual(vel_z.length, cell_count, "vel_z covers grid");
+
+    const slice_size = res_x * res_y;
+
+    for (let z = 0; z < res_z; z++) {
+        const z_off = z * slice_size;
+
+        for (let y = 0; y < res_y; y++) {
+            const y_off = y * res_x;
+
+            for (let x = 0; x < res_x; x++) {
+                const c = z_off + y_off + x;
+
+                if (solid[c] !== 0) {
+                    output[c] = input[c];
+                    continue;
+                }
+
+                const s_x = x - vel_x[c] * time_delta;
+                const s_y = y - vel_y[c] * time_delta;
+                const s_z = z - vel_z[c] * time_delta;
+
+                output[c] = scs3d_sample_linear(input, res_x, res_y, res_z, s_x, s_y, s_z);
+            }
+        }
+    }
+}

package/src/engine/physics/fluid/solver/v3_grid_compute_divergence.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Compute the divergence of a cell-centered velocity field into a scalar field.
+ *
+ *     div(c) ≈ 0.5 * ( u(x+1) - u(x-1) + v(y+1) - v(y-1) + w(z+1) - w(z-1) )
+ *
+ * Boundary cells use one-sided differences (`u(x+1) - u(x)` or `u(x) - u(x-1)`), keeping
+ * the scheme consistent for free outflow. Solid cells get divergence 0 — they are not
+ * fluid and don't participate in the pressure solve.
+ *
+ * Unit assumption: cell spacing h = 1 (positions are in grid units). If you advect with
+ * "world units per second" velocities, convert before calling.
+ *
+ * @param {Float32Array} divergence  Destination, mutated.
+ * @param {Float32Array} vel_x
+ * @param {Float32Array} vel_y
+ * @param {Float32Array} vel_z
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {Uint8Array} solid          Required (zero-filled for a wall-free domain).
+ */
+export function v3_grid_compute_divergence(divergence: Float32Array, vel_x: Float32Array, vel_y: Float32Array, vel_z: Float32Array, res_x: number, res_y: number, res_z: number, solid: Uint8Array): void;
+//# sourceMappingURL=v3_grid_compute_divergence.d.ts.map

package/src/engine/physics/fluid/solver/v3_grid_compute_divergence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"v3_grid_compute_divergence.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_compute_divergence.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,uDATW,YAAY,SACZ,YAAY,SACZ,YAAY,SACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,SACN,UAAU,QA8CpB"}

package/src/engine/physics/fluid/solver/v3_grid_compute_divergence.js

@@ -0,0 +1,68 @@
+import { assert } from "../../../../core/assert.js";
+
+/**
+ * Compute the divergence of a cell-centered velocity field into a scalar field.
+ *
+ *     div(c) ≈ 0.5 * ( u(x+1) - u(x-1) + v(y+1) - v(y-1) + w(z+1) - w(z-1) )
+ *
+ * Boundary cells use one-sided differences (`u(x+1) - u(x)` or `u(x) - u(x-1)`), keeping
+ * the scheme consistent for free outflow. Solid cells get divergence 0 — they are not
+ * fluid and don't participate in the pressure solve.
+ *
+ * Unit assumption: cell spacing h = 1 (positions are in grid units). If you advect with
+ * "world units per second" velocities, convert before calling.
+ *
+ * @param {Float32Array} divergence  Destination, mutated.
+ * @param {Float32Array} vel_x
+ * @param {Float32Array} vel_y
+ * @param {Float32Array} vel_z
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {Uint8Array} solid          Required (zero-filled for a wall-free domain).
+ */
+export function v3_grid_compute_divergence(divergence, vel_x, vel_y, vel_z, res_x, res_y, res_z, solid) {
+    const cell_count = res_x * res_y * res_z;
+    assert.greaterThanOrEqual(divergence.length, cell_count, "divergence covers grid");
+    assert.greaterThanOrEqual(vel_x.length, cell_count, "vel_x covers grid");
+    assert.greaterThanOrEqual(vel_y.length, cell_count, "vel_y covers grid");
+    assert.greaterThanOrEqual(vel_z.length, cell_count, "vel_z covers grid");
+
+    const slice_size = res_x * res_y;
+    const last_x = res_x - 1;
+    const last_y = res_y - 1;
+    const last_z = res_z - 1;
+
+    for (let z = 0; z < res_z; z++) {
+        const z_off = z * slice_size;
+
+        for (let y = 0; y < res_y; y++) {
+            const y_off = y * res_x;
+
+            for (let x = 0; x < res_x; x++) {
+                const c = z_off + y_off + x;
+
+                if (solid[c] !== 0) {
+                    divergence[c] = 0;
+                    continue;
+                }
+
+                let du, dv, dw;
+
+                if (x === 0)            du = vel_x[c + 1]          - vel_x[c];
+                else if (x === last_x)  du = vel_x[c]              - vel_x[c - 1];
+                else                    du = 0.5 * (vel_x[c + 1]   - vel_x[c - 1]);
+
+                if (y === 0)            dv = vel_y[c + res_x]      - vel_y[c];
+                else if (y === last_y)  dv = vel_y[c]              - vel_y[c - res_x];
+                else                    dv = 0.5 * (vel_y[c + res_x] - vel_y[c - res_x]);
+
+                if (z === 0)            dw = vel_z[c + slice_size] - vel_z[c];
+                else if (z === last_z)  dw = vel_z[c]              - vel_z[c - slice_size];
+                else                    dw = 0.5 * (vel_z[c + slice_size] - vel_z[c - slice_size]);
+
+                divergence[c] = du + dv + dw;
+            }
+        }
+    }
+}

package/src/engine/physics/fluid/solver/v3_grid_compute_solid_neighbour_mask.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Bake a per-cell neighbourhood mask describing which of the 6 cardinal
+ * neighbours of each cell are "fluid" (in-bounds AND non-solid). Consumed by
+ * {@link v3_grid_solve_pressure}, which uses the mask to skip boundary checks
+ * and solid-neighbour checks entirely.
+ *
+ * Encoding (one byte per cell, low 6 bits):
+ *
+ *     bit 0 (= 1)  : -x neighbour is fluid
+ *     bit 1 (= 2)  : +x neighbour is fluid
+ *     bit 2 (= 4)  : -y neighbour is fluid
+ *     bit 3 (= 8)  : +y neighbour is fluid
+ *     bit 4 (= 16) : -z neighbour is fluid
+ *     bit 5 (= 32) : +z neighbour is fluid
+ *
+ * Solid cells themselves are encoded as `mask = 0` (not "their own neighbours
+ * are fluid") so the SOR loop's `mask === 0 → skip` branch covers both
+ * "self-solid" and "fluid but no fluid neighbours" with one comparison.
+ *
+ * O(N) — one byte-write per cell, up to six byte-reads per cell. The output
+ * fully replaces whatever was in `mask` before; no need to zero-init.
+ *
+ * @param {Uint8Array} mask  Destination. Length ≥ res_x*res_y*res_z.
+ * @param {Uint8Array} solid  Source. Length ≥ res_x*res_y*res_z. Non-zero = solid.
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ */
+export function v3_grid_compute_solid_neighbour_mask(mask: Uint8Array, solid: Uint8Array, res_x: number, res_y: number, res_z: number): void;
+//# sourceMappingURL=v3_grid_compute_solid_neighbour_mask.d.ts.map

package/src/engine/physics/fluid/solver/v3_grid_compute_solid_neighbour_mask.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"v3_grid_compute_solid_neighbour_mask.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_compute_solid_neighbour_mask.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,2DANW,UAAU,SACV,UAAU,SACV,MAAM,SACN,MAAM,SACN,MAAM,QAqChB"}

package/src/engine/physics/fluid/solver/v3_grid_compute_solid_neighbour_mask.js

@@ -0,0 +1,66 @@
+import { assert } from "../../../../core/assert.js";
+
+/**
+ * Bake a per-cell neighbourhood mask describing which of the 6 cardinal
+ * neighbours of each cell are "fluid" (in-bounds AND non-solid). Consumed by
+ * {@link v3_grid_solve_pressure}, which uses the mask to skip boundary checks
+ * and solid-neighbour checks entirely.
+ *
+ * Encoding (one byte per cell, low 6 bits):
+ *
+ *     bit 0 (= 1)  : -x neighbour is fluid
+ *     bit 1 (= 2)  : +x neighbour is fluid
+ *     bit 2 (= 4)  : -y neighbour is fluid
+ *     bit 3 (= 8)  : +y neighbour is fluid
+ *     bit 4 (= 16) : -z neighbour is fluid
+ *     bit 5 (= 32) : +z neighbour is fluid
+ *
+ * Solid cells themselves are encoded as `mask = 0` (not "their own neighbours
+ * are fluid") so the SOR loop's `mask === 0 → skip` branch covers both
+ * "self-solid" and "fluid but no fluid neighbours" with one comparison.
+ *
+ * O(N) — one byte-write per cell, up to six byte-reads per cell. The output
+ * fully replaces whatever was in `mask` before; no need to zero-init.
+ *
+ * @param {Uint8Array} mask  Destination. Length ≥ res_x*res_y*res_z.
+ * @param {Uint8Array} solid  Source. Length ≥ res_x*res_y*res_z. Non-zero = solid.
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ */
+export function v3_grid_compute_solid_neighbour_mask(mask, solid, res_x, res_y, res_z) {
+    const cells = res_x * res_y * res_z;
+    assert.greaterThanOrEqual(mask.length, cells, "mask covers grid");
+    assert.greaterThanOrEqual(solid.length, cells, "solid covers grid");
+
+    const slice = res_x * res_y;
+    const last_x = res_x - 1;
+    const last_y = res_y - 1;
+    const last_z = res_z - 1;
+
+    for (let z = 0; z < res_z; z++) {
+        const z_off = z * slice;
+        const has_zm = z > 0;
+        const has_zp = z < last_z;
+        for (let y = 0; y < res_y; y++) {
+            const y_off = z_off + y * res_x;
+            const has_ym = y > 0;
+            const has_yp = y < last_y;
+            for (let x = 0; x < res_x; x++) {
+                const c = y_off + x;
+                if (solid[c] !== 0) {
+                    mask[c] = 0;
+                    continue;
+                }
+                let m = 0;
+                if (x > 0      && solid[c - 1] === 0)     m |= 1;
+                if (x < last_x && solid[c + 1] === 0)     m |= 2;
+                if (has_ym     && solid[c - res_x] === 0) m |= 4;
+                if (has_yp     && solid[c + res_x] === 0) m |= 8;
+                if (has_zm     && solid[c - slice] === 0) m |= 16;
+                if (has_zp     && solid[c + slice] === 0) m |= 32;
+                mask[c] = m;
+            }
+        }
+    }
+}

package/src/engine/physics/fluid/solver/v3_grid_patch_edges_uniform.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Fill the edges exposed by {@link v3_grid_shift_in_place} (with the same
+ * `(shift_x, shift_y, shift_z)`) by replicating the adjacent valid column / row /
+ * slice — zero-gradient Neumann extrapolation, equivalent to "the field is locally
+ * uniform near the boundary".
+ *
+ * Axes are patched independently in x → y → z order. Corner cells (where two or
+ * three axis-edges meet) are written by every axis they belong to; the final value
+ * comes from the last axis, which sees the previously-patched cells as already-valid
+ * neighbours.
+ *
+ * No-ops:
+ *   - All shifts zero → nothing to patch.
+ *   - `|shift| >= res` on any axis → the shift primitive already zero-filled the
+ *     buffer; nothing to replicate from.
+ *
+ * @param {Float32Array|Uint8Array} buffer
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {number} shift_x  integer; same value passed to v3_grid_shift_in_place
+ * @param {number} shift_y  integer
+ * @param {number} shift_z  integer
+ */
+export function v3_grid_patch_edges_uniform(buffer: Float32Array | Uint8Array, res_x: number, res_y: number, res_z: number, shift_x: number, shift_y: number, shift_z: number): void;
+//# sourceMappingURL=v3_grid_patch_edges_uniform.d.ts.map

package/src/engine/physics/fluid/solver/v3_grid_patch_edges_uniform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"v3_grid_patch_edges_uniform.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_patch_edges_uniform.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,oDARW,YAAY,GAAC,UAAU,SACvB,MAAM,SACN,MAAM,SACN,MAAM,WACN,MAAM,WACN,MAAM,WACN,MAAM,QAehB"}

package/src/engine/physics/fluid/solver/v3_grid_patch_edges_uniform.js

@@ -0,0 +1,113 @@
+/**
+ * Fill the edges exposed by {@link v3_grid_shift_in_place} (with the same
+ * `(shift_x, shift_y, shift_z)`) by replicating the adjacent valid column / row /
+ * slice — zero-gradient Neumann extrapolation, equivalent to "the field is locally
+ * uniform near the boundary".
+ *
+ * Axes are patched independently in x → y → z order. Corner cells (where two or
+ * three axis-edges meet) are written by every axis they belong to; the final value
+ * comes from the last axis, which sees the previously-patched cells as already-valid
+ * neighbours.
+ *
+ * No-ops:
+ *   - All shifts zero → nothing to patch.
+ *   - `|shift| >= res` on any axis → the shift primitive already zero-filled the
+ *     buffer; nothing to replicate from.
+ *
+ * @param {Float32Array|Uint8Array} buffer
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {number} shift_x  integer; same value passed to v3_grid_shift_in_place
+ * @param {number} shift_y  integer
+ * @param {number} shift_z  integer
+ */
+export function v3_grid_patch_edges_uniform(buffer, res_x, res_y, res_z, shift_x, shift_y, shift_z) {
+    if (shift_x === 0 && shift_y === 0 && shift_z === 0) {
+        return;
+    }
+
+    if (Math.abs(shift_x) >= res_x || Math.abs(shift_y) >= res_y || Math.abs(shift_z) >= res_z) {
+        // Full clear from the shift primitive; no valid neighbour to replicate.
+        return;
+    }
+
+    if (shift_x !== 0) patch_x(buffer, res_x, res_y, res_z, shift_x);
+    if (shift_y !== 0) patch_y(buffer, res_x, res_y, res_z, shift_y);
+    if (shift_z !== 0) patch_z(buffer, res_x, res_y, res_z, shift_z);
+}
+
+function patch_x(buf, rx, ry, rz, shift) {
+    const slice = rx * ry;
+    if (shift > 0) {
+        // Exposed: x in [rx - shift, rx). Source: column x = rx - shift - 1.
+        const src_x = rx - shift - 1;
+        const first_exposed = rx - shift;
+        for (let z = 0; z < rz; z++) {
+            const z_off = z * slice;
+            for (let y = 0; y < ry; y++) {
+                const row = z_off + y * rx;
+                const src_value = buf[row + src_x];
+                for (let x = first_exposed; x < rx; x++) {
+                    buf[row + x] = src_value;
+                }
+            }
+        }
+    } else {
+        const n = -shift;
+        // Exposed: x in [0, n). Source: column x = n.
+        for (let z = 0; z < rz; z++) {
+            const z_off = z * slice;
+            for (let y = 0; y < ry; y++) {
+                const row = z_off + y * rx;
+                const src_value = buf[row + n];
+                for (let x = 0; x < n; x++) {
+                    buf[row + x] = src_value;
+                }
+            }
+        }
+    }
+}
+
+function patch_y(buf, rx, ry, rz, shift) {
+    const slice = rx * ry;
+    if (shift > 0) {
+        // Exposed: y in [ry - shift, ry). Source: row y = ry - shift - 1.
+        const src_y = ry - shift - 1;
+        const first_exposed = ry - shift;
+        for (let z = 0; z < rz; z++) {
+            const z_off = z * slice;
+            const src_row = z_off + src_y * rx;
+            for (let y = first_exposed; y < ry; y++) {
+                buf.copyWithin(z_off + y * rx, src_row, src_row + rx);
+            }
+        }
+    } else {
+        const n = -shift;
+        for (let z = 0; z < rz; z++) {
+            const z_off = z * slice;
+            const src_row = z_off + n * rx;
+            for (let y = 0; y < n; y++) {
+                buf.copyWithin(z_off + y * rx, src_row, src_row + rx);
+            }
+        }
+    }
+}
+
+function patch_z(buf, rx, ry, rz, shift) {
+    const slice = rx * ry;
+    if (shift > 0) {
+        // Exposed: z in [rz - shift, rz). Source: slice z = rz - shift - 1.
+        const src_slice_start = (rz - shift - 1) * slice;
+        const first_exposed = rz - shift;
+        for (let z = first_exposed; z < rz; z++) {
+            buf.copyWithin(z * slice, src_slice_start, src_slice_start + slice);
+        }
+    } else {
+        const n = -shift;
+        const src_slice_start = n * slice;
+        for (let z = 0; z < n; z++) {
+            buf.copyWithin(z * slice, src_slice_start, src_slice_start + slice);
+        }
+    }
+}

package/src/engine/physics/fluid/solver/v3_grid_shift_in_place.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Shifts `buffer` contents in place by `(shift_x, shift_y, shift_z)` grid cells.
+ *
+ * Direction convention: the cell at position `(i, j, k)` after the shift contains the
+ * value previously at `(i + shift_x, j + shift_y, k + shift_z)`. Equivalent semantics:
+ * the grid moved by `(shift_x, shift_y, shift_z)` cells in world space and the fluid
+ * data (which is anchored to world space, not to the moving grid) follows.
+ *
+ * Cells whose source would have been outside the grid are NOT touched here — they
+ * still contain whatever stale data the underlying axis copy left behind. Patch them
+ * separately via {@link v3_grid_patch_edges_uniform}, which knows the same
+ * `(shift_x, shift_y, shift_z)` and writes a Neumann zero-gradient extrapolation into
+ * the exposed cells.
+ *
+ * If `|shift|` on any axis is `>= res` on that axis, no valid source data remains
+ * after the shift. The buffer is zero-filled and the patcher will leave it that way.
+ *
+ * Each axis is shifted independently via `TypedArray.copyWithin`, which handles
+ * overlapping source/destination correctly (`memmove`-like semantics).
+ *
+ * @param {Float32Array|Uint8Array} buffer
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {number} shift_x  integer
+ * @param {number} shift_y  integer
+ * @param {number} shift_z  integer
+ */
+export function v3_grid_shift_in_place(buffer: Float32Array | Uint8Array, res_x: number, res_y: number, res_z: number, shift_x: number, shift_y: number, shift_z: number): void;
+//# sourceMappingURL=v3_grid_shift_in_place.d.ts.map

package/src/engine/physics/fluid/solver/v3_grid_shift_in_place.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"v3_grid_shift_in_place.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_shift_in_place.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,+CARW,YAAY,GAAC,UAAU,SACvB,MAAM,SACN,MAAM,SACN,MAAM,WACN,MAAM,WACN,MAAM,WACN,MAAM,QAkChB"}

package/src/engine/physics/fluid/solver/v3_grid_shift_in_place.js

@@ -0,0 +1,107 @@
+import { assert } from "../../../../core/assert.js";
+
+/**
+ * Shifts `buffer` contents in place by `(shift_x, shift_y, shift_z)` grid cells.
+ *
+ * Direction convention: the cell at position `(i, j, k)` after the shift contains the
+ * value previously at `(i + shift_x, j + shift_y, k + shift_z)`. Equivalent semantics:
+ * the grid moved by `(shift_x, shift_y, shift_z)` cells in world space and the fluid
+ * data (which is anchored to world space, not to the moving grid) follows.
+ *
+ * Cells whose source would have been outside the grid are NOT touched here — they
+ * still contain whatever stale data the underlying axis copy left behind. Patch them
+ * separately via {@link v3_grid_patch_edges_uniform}, which knows the same
+ * `(shift_x, shift_y, shift_z)` and writes a Neumann zero-gradient extrapolation into
+ * the exposed cells.
+ *
+ * If `|shift|` on any axis is `>= res` on that axis, no valid source data remains
+ * after the shift. The buffer is zero-filled and the patcher will leave it that way.
+ *
+ * Each axis is shifted independently via `TypedArray.copyWithin`, which handles
+ * overlapping source/destination correctly (`memmove`-like semantics).
+ *
+ * @param {Float32Array|Uint8Array} buffer
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {number} shift_x  integer
+ * @param {number} shift_y  integer
+ * @param {number} shift_z  integer
+ */
+export function v3_grid_shift_in_place(buffer, res_x, res_y, res_z, shift_x, shift_y, shift_z) {
+    assert.isInteger(shift_x, "shift_x");
+    assert.isInteger(shift_y, "shift_y");
+    assert.isInteger(shift_z, "shift_z");
+
+    if (shift_x === 0 && shift_y === 0 && shift_z === 0) {
+        return;
+    }
+
+    const cell_count = res_x * res_y * res_z;
+    assert.greaterThanOrEqual(buffer.length, cell_count, "buffer covers grid");
+
+    // Any axis shift exceeding the grid leaves no valid source data on that axis,
+    // and therefore on the whole buffer (every cell's source maps outside).
+    if (Math.abs(shift_x) >= res_x || Math.abs(shift_y) >= res_y || Math.abs(shift_z) >= res_z) {
+        for (let i = 0; i < cell_count; i++) {
+            buffer[i] = 0;
+        }
+        return;
+    }
+
+    const slice = res_x * res_y;
+
+    if (shift_x !== 0) {
+        shift_axis_x(buffer, res_x, res_y, res_z, shift_x, slice);
+    }
+    if (shift_y !== 0) {
+        shift_axis_y(buffer, res_x, res_y, res_z, shift_y, slice);
+    }
+    if (shift_z !== 0) {
+        shift_axis_z(buffer, res_x, res_y, res_z, shift_z, slice);
+    }
+}
+
+function shift_axis_x(buf, rx, ry, rz, shift, slice) {
+    const n = Math.abs(shift);
+    for (let z = 0; z < rz; z++) {
+        const z_off = z * slice;
+        for (let y = 0; y < ry; y++) {
+            const row = z_off + y * rx;
+            if (shift > 0) {
+                // dst x in [0, rx - n) ← src x in [n, rx).
+                buf.copyWithin(row, row + n, row + rx);
+            } else {
+                // dst x in [n, rx) ← src x in [0, rx - n).
+                buf.copyWithin(row + n, row, row + rx - n);
+            }
+        }
+    }
+}
+
+function shift_axis_y(buf, rx, ry, rz, shift, slice) {
+    const n = Math.abs(shift);
+    const row_size = rx;
+    for (let z = 0; z < rz; z++) {
+        const z_off = z * slice;
+        if (shift > 0) {
+            // dst y in [0, ry - n) ← src y in [n, ry).
+            buf.copyWithin(z_off, z_off + n * row_size, z_off + ry * row_size);
+        } else {
+            // dst y in [n, ry) ← src y in [0, ry - n).
+            buf.copyWithin(z_off + n * row_size, z_off, z_off + (ry - n) * row_size);
+        }
+    }
+}
+
+function shift_axis_z(buf, rx, ry, rz, shift, slice) {
+    const n = Math.abs(shift);
+    const total = rx * ry * rz;
+    if (shift > 0) {
+        // dst z in [0, rz - n) ← src z in [n, rz).
+        buf.copyWithin(0, n * slice, total);
+    } else {
+        // dst z in [n, rz) ← src z in [0, rz - n).
+        buf.copyWithin(n * slice, 0, total - n * slice);
+    }
+}

package/src/engine/physics/fluid/solver/v3_grid_solve_pressure.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Solve the pressure Poisson equation `∇²p = div(v)` by red-black Successive
+ * Over-Relaxation (SOR), gated by a pre-baked per-cell neighbour mask.
+ *
+ * Per cell, the update is:
+ *
+ *     p_jacobi(c) = ( sum_of_fluid_neighbour_pressures - div(c) ) / count
+ *     p(c) = (1 - ω) * p(c) + ω * p_jacobi(c)
+ *
+ * "Which neighbours count as fluid" is determined entirely by `neighbour_mask`,
+ * a Uint8Array allocated and populated by {@link FluidField} via
+ * {@link FluidField.recomputeSolidNeighbourMask}. The encoding is:
+ *
+ *     bit 0 (= 1)  : -x neighbour is fluid
+ *     bit 1 (= 2)  : +x neighbour is fluid
+ *     bit 2 (= 4)  : -y neighbour is fluid
+ *     bit 3 (= 8)  : +y neighbour is fluid
+ *     bit 4 (= 16) : -z neighbour is fluid
+ *     bit 5 (= 32) : +z neighbour is fluid
+ *
+ * Solid cells encode as `mask = 0`, so the inner loop's `mask === 0 ? skip` covers
+ * both self-solid AND fluid-with-no-fluid-neighbours in one comparison. This
+ * eliminates six boundary checks plus six solid-neighbour checks per cell per
+ * iteration, replacing them with a single mask read and six bit-tests on a
+ * register-resident value. Boundary handling (cells at x=0, x=last, etc.) is
+ * implicit — the recompute step writes 0 into the boundary-facing bit, so the
+ * SOR loop never reads out-of-range memory.
+ *
+ * Cells are visited in two passes per iteration: first "red" (`(x+y+z) % 2 === 0`)
+ * then "black". Adjacent cells have opposite colour, so each pass reads only
+ * cells of the other colour and writes are independent — same in-place red-black
+ * scheme as the un-masked variant.
+ *
+ * @param {Float32Array|Float16Array} pressure  Mutated in place. Pre-fill with 0
+ *     or with the previous step's solution to warm-start.
+ * @param {Float32Array|Float16Array} divergence  From
+ *     {@link v3_grid_compute_divergence}. Same dtype as pressure.
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {number} iterations  Number of red-black sweeps.
+ * @param {number} omega  SOR relaxation factor in (0, 2). Near-optimal values
+ *     come from {@link optimal_sor_omega}.
+ * @param {Uint8Array} neighbour_mask  Length ≥ res_x*res_y*res_z. Each byte
+ *     encodes the fluid-neighbour bitmask (see above). MUST be recomputed
+ *     whenever the underlying solid mask changes.
+ */
+export function v3_grid_solve_pressure(pressure: Float32Array | Float16Array, divergence: Float32Array | Float16Array, res_x: number, res_y: number, res_z: number, iterations: number, omega: number, neighbour_mask: Uint8Array): void;
+//# sourceMappingURL=v3_grid_solve_pressure.d.ts.map

package/src/engine/physics/fluid/solver/v3_grid_solve_pressure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"v3_grid_solve_pressure.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_solve_pressure.js"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,iDAdW,YAAY,eAAa,cAEzB,YAAY,eAAa,SAEzB,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,SACN,MAAM,kBAEN,UAAU,QA+DpB"}