@woosh/meep-engine 2.157.0 → 2.158.0

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

@@ -0,0 +1,92 @@
+import { clamp } from "../../../../core/math/clamp.js";
+
+/**
+ * Trilinearly sample a cell-centered scalar at a fractional position,
+ * EXCLUDING solid cells from the interpolation: solid taps contribute zero
+ * weight and the remaining weights are renormalized. This is the
+ * free-boundary-aware sampling of Bridson §3.x — without it, a back-trace
+ * landing NEAR a wall blends the frozen in-wall value into the fluid, which
+ * reads as dye bleeding out of (or being eaten by) walls.
+ *
+ * When every tap is solid (a trace clipped into a fully walled corner) there
+ * is nothing valid to interpolate; `fallback` — typically the destination
+ * cell's own previous value, i.e. "no transport this step" — is returned.
+ *
+ * Positions clamp to the cell lattice exactly like
+ * {@link scs3d_sample_linear}; with a zero-filled `solid` grid the result
+ * matches that sampler up to floating-point reassociation (the weights sum
+ * to 1 and renormalization divides by it).
+ *
+ * @param {Float32Array} data    Cell-centered scalar field.
+ * @param {Uint8Array} solid     Cell-centered solid flags.
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @param {number} fallback      Returned when no fluid tap is available.
+ * @return {number}
+ */
+export function v3_grid_sample_scalar_masked(data, solid, res_x, res_y, res_z, x, y, z, fallback) {
+    const x_max = res_x - 1;
+    const y_max = res_y - 1;
+    const z_max = res_z - 1;
+
+    const x_clamped = clamp(x, 0, x_max);
+    const y_clamped = clamp(y, 0, y_max);
+    const z_clamped = clamp(z, 0, z_max);
+
+    const x0 = x_clamped | 0;
+    const y0 = y_clamped | 0;
+    const z0 = z_clamped | 0;
+
+    const f_x = x_clamped - x0;
+    const f_y = y_clamped - y0;
+    const f_z = z_clamped - z0;
+
+    const x1 = x_clamped === x0 ? x0 : x0 + 1;
+    const y1 = y_clamped === y0 ? y0 : y0 + 1;
+    const z1 = z_clamped === z0 ? z0 : z0 + 1;
+
+    const slice = res_x * res_y;
+    const z0_off = z0 * slice;
+    const z1_off = z1 * slice;
+    const y0_off = y0 * res_x;
+    const y1_off = y1 * res_x;
+
+    const c000 = z0_off + y0_off + x0;
+    const c100 = z0_off + y0_off + x1;
+    const c010 = z0_off + y1_off + x0;
+    const c110 = z0_off + y1_off + x1;
+    const c001 = z1_off + y0_off + x0;
+    const c101 = z1_off + y0_off + x1;
+    const c011 = z1_off + y1_off + x0;
+    const c111 = z1_off + y1_off + x1;
+
+    const gx = 1 - f_x;
+    const gy = 1 - f_y;
+    const gz = 1 - f_z;
+
+    // Per-tap trilinear weight, zeroed when the tap cell is solid.
+    const w000 = solid[c000] !== 0 ? 0 : gx * gy * gz;
+    const w100 = solid[c100] !== 0 ? 0 : f_x * gy * gz;
+    const w010 = solid[c010] !== 0 ? 0 : gx * f_y * gz;
+    const w110 = solid[c110] !== 0 ? 0 : f_x * f_y * gz;
+    const w001 = solid[c001] !== 0 ? 0 : gx * gy * f_z;
+    const w101 = solid[c101] !== 0 ? 0 : f_x * gy * f_z;
+    const w011 = solid[c011] !== 0 ? 0 : gx * f_y * f_z;
+    const w111 = solid[c111] !== 0 ? 0 : f_x * f_y * f_z;
+
+    const total = w000 + w100 + w010 + w110 + w001 + w101 + w011 + w111;
+    if (total <= 0) {
+        return fallback;
+    }
+
+    const sum = w000 * data[c000] + w100 * data[c100]
+        + w010 * data[c010] + w110 * data[c110]
+        + w001 * data[c001] + w101 * data[c101]
+        + w011 * data[c011] + w111 * data[c111];
+
+    return sum / total;
+}

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

@@ -0,0 +1,42 @@
+/**
+ * Unconditionally stable MacCormack advection of a MAC (face-centered)
+ * velocity field — the staggered counterpart of
+ * {@link v3_grid_advect_maccormack_velocity}. Per component lattice:
+ *
+ *     1. forward:  û  = SL(src, back-trace by carrier·dt)
+ *     2. backward: ū  = SL(û, trace by +carrier·dt)
+ *     3. correct:  u* = û + ½·(src − ū)
+ *     4. limit:    clamp to min/max of the 8 src faces around the back-traced
+ *                  position (Selle et al. 2008 monotone limiter; pinned faces
+ *                  participate — they hold valid boundary values)
+ *
+ * Solid handling matches {@link v3_mac_advect_sl_velocity}: PINNED faces pass
+ * their source value through (the projection owns them as boundary
+ * conditions), and every trace — backward in both passes, forward in the
+ * corrector — is CLIPPED against solid cells so momentum is never sampled
+ * from inside a wall or through one.
+ *
+ * The cross-component carrier reconstruction uses the exact fixed 4-tap MAC
+ * averages (face positions are grid-aligned in the cross axes — see the SL
+ * kernel), recomputed per pass; the carrier does not change between passes
+ * so both passes see identical trace vectors.
+ *
+ * Aliasing: per component, `out`, `src` and `fwd` must be distinct, and
+ * outputs must not alias any carrier lattice (cross-component carrier
+ * sampling — see {@link v3_mac_advect_sl_velocity}).
+ *
+ * @param {Float32Array[]} outputs         `[out_u, out_v, out_w]`. Mutated.
+ * @param {Float32Array[]} sources         `[src_u, src_v, src_w]`. Read.
+ * @param {Float32Array[]} carrier         `[car_u, car_v, car_w]`.
+ * @param {Float32Array[]} forward_scratch `[fwd_u, fwd_v, fwd_w]`. Mutated.
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {number} time_delta
+ * @param {Uint8Array} face_solid_x
+ * @param {Uint8Array} face_solid_y
+ * @param {Uint8Array} face_solid_z
+ * @param {Uint8Array} solid  Cell-centered solid flags (trace clipping).
+ */
+export function v3_mac_advect_maccormack_velocity(outputs: Float32Array[], sources: Float32Array[], carrier: Float32Array[], forward_scratch: Float32Array[], res_x: number, res_y: number, res_z: number, time_delta: number, face_solid_x: Uint8Array, face_solid_y: Uint8Array, face_solid_z: Uint8Array, solid: Uint8Array): void;
+//# sourceMappingURL=v3_mac_advect_maccormack_velocity.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"v3_mac_advect_maccormack_velocity.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_mac_advect_maccormack_velocity.js"],"names":[],"mappings":"AAiCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,2DAbW,YAAY,EAAE,WACd,YAAY,EAAE,WACd,YAAY,EAAE,mBACd,YAAY,EAAE,SACd,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,gBACN,UAAU,gBACV,UAAU,gBACV,UAAU,SACV,UAAU,QA0MpB"}

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

@@ -0,0 +1,319 @@
+import { assert } from "../../../../core/assert.js";
+import { clamp } from "../../../../core/math/clamp.js";
+import { scs3d_sample_linear } from "../../../graphics/texture/3d/scs3d_sample_linear.js";
+import { v3_mac_clip_trace } from "./v3_mac_clip_trace.js";
+
+const scratch_clip = new Float32Array(3);
+
+/**
+ * Straight-line (loop-free, inlinable) test: is the cell containing the
+ * point solid? Same rounding/clamping as v3_mac_clip_trace. Kernels use this
+ * inline per trace and call the loop-bearing clip helper only on a hit — see
+ * the performance contract on {@link v3_mac_clip_trace}.
+ *
+ * @param {Uint8Array} solid
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {number} px
+ * @param {number} py
+ * @param {number} pz
+ * @return {boolean}
+ */
+function end_in_solid(solid, res_x, res_y, res_z, px, py, pz) {
+    let x = (px + 0.5) | 0;
+    let y = (py + 0.5) | 0;
+    let z = (pz + 0.5) | 0;
+    if (x < 0) x = 0; else if (x >= res_x) x = res_x - 1;
+    if (y < 0) y = 0; else if (y >= res_y) y = res_y - 1;
+    if (z < 0) z = 0; else if (z >= res_z) z = res_z - 1;
+    return solid[z * res_x * res_y + y * res_x + x] !== 0;
+}
+
+
+/**
+ * Unconditionally stable MacCormack advection of a MAC (face-centered)
+ * velocity field — the staggered counterpart of
+ * {@link v3_grid_advect_maccormack_velocity}. Per component lattice:
+ *
+ *     1. forward:  û  = SL(src, back-trace by carrier·dt)
+ *     2. backward: ū  = SL(û, trace by +carrier·dt)
+ *     3. correct:  u* = û + ½·(src − ū)
+ *     4. limit:    clamp to min/max of the 8 src faces around the back-traced
+ *                  position (Selle et al. 2008 monotone limiter; pinned faces
+ *                  participate — they hold valid boundary values)
+ *
+ * Solid handling matches {@link v3_mac_advect_sl_velocity}: PINNED faces pass
+ * their source value through (the projection owns them as boundary
+ * conditions), and every trace — backward in both passes, forward in the
+ * corrector — is CLIPPED against solid cells so momentum is never sampled
+ * from inside a wall or through one.
+ *
+ * The cross-component carrier reconstruction uses the exact fixed 4-tap MAC
+ * averages (face positions are grid-aligned in the cross axes — see the SL
+ * kernel), recomputed per pass; the carrier does not change between passes
+ * so both passes see identical trace vectors.
+ *
+ * Aliasing: per component, `out`, `src` and `fwd` must be distinct, and
+ * outputs must not alias any carrier lattice (cross-component carrier
+ * sampling — see {@link v3_mac_advect_sl_velocity}).
+ *
+ * @param {Float32Array[]} outputs         `[out_u, out_v, out_w]`. Mutated.
+ * @param {Float32Array[]} sources         `[src_u, src_v, src_w]`. Read.
+ * @param {Float32Array[]} carrier         `[car_u, car_v, car_w]`.
+ * @param {Float32Array[]} forward_scratch `[fwd_u, fwd_v, fwd_w]`. Mutated.
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {number} time_delta
+ * @param {Uint8Array} face_solid_x
+ * @param {Uint8Array} face_solid_y
+ * @param {Uint8Array} face_solid_z
+ * @param {Uint8Array} solid  Cell-centered solid flags (trace clipping).
+ */
+export function v3_mac_advect_maccormack_velocity(outputs, sources, carrier, forward_scratch, res_x, res_y, res_z, time_delta, face_solid_x, face_solid_y, face_solid_z, solid) {
+    assert.equal(outputs.length, 3, "outputs is a 3-component array");
+    assert.equal(sources.length, 3, "sources is a 3-component array");
+    assert.equal(carrier.length, 3, "carrier is a 3-component array");
+    assert.equal(forward_scratch.length, 3, "forward_scratch is a 3-component array");
+
+    const out_u = outputs[0], out_v = outputs[1], out_w = outputs[2];
+    const src_u = sources[0], src_v = sources[1], src_w = sources[2];
+    const car_u = carrier[0], car_v = carrier[1], car_w = carrier[2];
+    const fwd_u = forward_scratch[0], fwd_v = forward_scratch[1], fwd_w = forward_scratch[2];
+
+    assert.notEqual(out_u, src_u, "out_u must not alias src_u");
+    assert.notEqual(out_u, fwd_u, "out_u must not alias fwd_u");
+    assert.notEqual(src_u, fwd_u, "src_u must not alias fwd_u");
+
+    const sx = res_x + 1;
+    const sy = res_y + 1;
+    const sz = res_z + 1;
+    const cell_slice = res_x * res_y;
+    const u_slice = sx * res_y;
+    const v_slice = res_x * sy;
+    const last_cx = res_x - 1;
+    const last_cy = res_y - 1;
+    const last_cz = res_z - 1;
+    const dt = time_delta;
+
+    // ─── u (x-faces): face (x,y,z) sits at (x − 0.5, y, z) ──────────────────
+    for (let pass = 0; pass < 2; pass++) {
+        for (let z = 0; z < res_z; z++) {
+            const f_z = z * u_slice;
+            const v_z = z * v_slice;
+            const w_z = z * cell_slice;
+            for (let y = 0; y < res_y; y++) {
+                const f_y = f_z + y * sx;
+                const v_lo = v_z + y * res_x;
+                const v_hi = v_lo + res_x;
+                const w_lo = w_z + y * res_x;
+                const w_hi = w_lo + cell_slice;
+                for (let x = 0; x <= res_x; x++) {
+                    const f = f_y + x;
+                    if (face_solid_x[f] !== 0) {
+                        if (pass === 0) fwd_u[f] = src_u[f];
+                        else out_u[f] = src_u[f];
+                        continue;
+                    }
+                    const xa = x > 0 ? x - 1 : 0;
+                    const xb = x < res_x ? x : last_cx;
+                    const cu = car_u[f];
+                    const cv = 0.25 * (car_v[v_lo + xa] + car_v[v_lo + xb] + car_v[v_hi + xa] + car_v[v_hi + xb]);
+                    const cw = 0.25 * (car_w[w_lo + xa] + car_w[w_lo + xb] + car_w[w_hi + xa] + car_w[w_hi + xb]);
+                    const px = x - 0.5;
+
+                    // Back-trace end (shared by pass A and the limiter).
+                    let bx = px - cu * dt;
+                    let by = y - cv * dt;
+                    let bz = z - cw * dt;
+                    if (end_in_solid(solid, res_x, res_y, res_z, bx, by, bz)) {
+                        v3_mac_clip_trace(scratch_clip, solid, res_x, res_y, res_z, px, y, z, bx, by, bz);
+                        bx = scratch_clip[0]; by = scratch_clip[1]; bz = scratch_clip[2];
+                    }
+
+                    if (pass === 0) {
+                        fwd_u[f] = scs3d_sample_linear(src_u, sx, res_y, res_z, bx + 0.5, by, bz);
+                        continue;
+                    }
+
+                    // Forward probe through the forward result.
+                    let qx = px + cu * dt;
+                    let qy = y + cv * dt;
+                    let qz = z + cw * dt;
+                    if (end_in_solid(solid, res_x, res_y, res_z, qx, qy, qz)) {
+                        v3_mac_clip_trace(scratch_clip, solid, res_x, res_y, res_z, px, y, z, qx, qy, qz);
+                        qx = scratch_clip[0]; qy = scratch_clip[1]; qz = scratch_clip[2];
+                    }
+                    const backward = scs3d_sample_linear(fwd_u, sx, res_y, res_z, qx + 0.5, qy, qz);
+                    const corrected = fwd_u[f] + 0.5 * (src_u[f] - backward);
+
+                    out_u[f] = limit8(corrected, src_u,
+                        bx + 0.5, by, bz,
+                        sx, res_y, res_z, sx, u_slice);
+                }
+            }
+        }
+    }
+
+    // ─── v (y-faces): face (x,y,z) sits at (x, y − 0.5, z) ──────────────────
+    for (let pass = 0; pass < 2; pass++) {
+        for (let z = 0; z < res_z; z++) {
+            const f_z = z * v_slice;
+            const u_z = z * u_slice;
+            const w_z = z * cell_slice;
+            for (let y = 0; y <= res_y; y++) {
+                const f_y = f_z + y * res_x;
+                const ya = y > 0 ? y - 1 : 0;
+                const yb = y < res_y ? y : last_cy;
+                const u_lo = u_z + ya * sx;
+                const u_hi = u_z + yb * sx;
+                const w_lo = w_z + ya * res_x;
+                const w_hi = w_z + yb * res_x;
+                for (let x = 0; x < res_x; x++) {
+                    const f = f_y + x;
+                    if (face_solid_y[f] !== 0) {
+                        if (pass === 0) fwd_v[f] = src_v[f];
+                        else out_v[f] = src_v[f];
+                        continue;
+                    }
+                    const cu = 0.25 * (car_u[u_lo + x] + car_u[u_lo + x + 1] + car_u[u_hi + x] + car_u[u_hi + x + 1]);
+                    const cv = car_v[f];
+                    const cw = 0.25 * (car_w[w_lo + x] + car_w[w_lo + x + cell_slice] + car_w[w_hi + x] + car_w[w_hi + x + cell_slice]);
+                    const py = y - 0.5;
+
+                    let bx = x - cu * dt;
+                    let by = py - cv * dt;
+                    let bz = z - cw * dt;
+                    if (end_in_solid(solid, res_x, res_y, res_z, bx, by, bz)) {
+                        v3_mac_clip_trace(scratch_clip, solid, res_x, res_y, res_z, x, py, z, bx, by, bz);
+                        bx = scratch_clip[0]; by = scratch_clip[1]; bz = scratch_clip[2];
+                    }
+
+                    if (pass === 0) {
+                        fwd_v[f] = scs3d_sample_linear(src_v, res_x, sy, res_z, bx, by + 0.5, bz);
+                        continue;
+                    }
+
+                    let qx = x + cu * dt;
+                    let qy = py + cv * dt;
+                    let qz = z + cw * dt;
+                    if (end_in_solid(solid, res_x, res_y, res_z, qx, qy, qz)) {
+                        v3_mac_clip_trace(scratch_clip, solid, res_x, res_y, res_z, x, py, z, qx, qy, qz);
+                        qx = scratch_clip[0]; qy = scratch_clip[1]; qz = scratch_clip[2];
+                    }
+                    const backward = scs3d_sample_linear(fwd_v, res_x, sy, res_z, qx, qy + 0.5, qz);
+                    const corrected = fwd_v[f] + 0.5 * (src_v[f] - backward);
+
+                    out_v[f] = limit8(corrected, src_v,
+                        bx, by + 0.5, bz,
+                        res_x, sy, res_z, res_x, v_slice);
+                }
+            }
+        }
+    }
+
+    // ─── w (z-faces): face (x,y,z) sits at (x, y, z − 0.5) ──────────────────
+    for (let pass = 0; pass < 2; pass++) {
+        for (let z = 0; z <= res_z; z++) {
+            const f_z = z * cell_slice;
+            const za = z > 0 ? z - 1 : 0;
+            const zb = z < res_z ? z : last_cz;
+            const u_lo = za * u_slice;
+            const u_hi = zb * u_slice;
+            const v_lo = za * v_slice;
+            const v_hi = zb * v_slice;
+            for (let y = 0; y < res_y; y++) {
+                const f_y = f_z + y * res_x;
+                const u_row_lo = u_lo + y * sx;
+                const u_row_hi = u_hi + y * sx;
+                const v_row_lo = v_lo + y * res_x;
+                const v_row_hi = v_hi + y * res_x;
+                for (let x = 0; x < res_x; x++) {
+                    const f = f_y + x;
+                    if (face_solid_z[f] !== 0) {
+                        if (pass === 0) fwd_w[f] = src_w[f];
+                        else out_w[f] = src_w[f];
+                        continue;
+                    }
+                    const cu = 0.25 * (car_u[u_row_lo + x] + car_u[u_row_lo + x + 1] + car_u[u_row_hi + x] + car_u[u_row_hi + x + 1]);
+                    const cv = 0.25 * (car_v[v_row_lo + x] + car_v[v_row_lo + x + res_x] + car_v[v_row_hi + x] + car_v[v_row_hi + x + res_x]);
+                    const cw = car_w[f];
+                    const pz = z - 0.5;
+
+                    let bx = x - cu * dt;
+                    let by = y - cv * dt;
+                    let bz = pz - cw * dt;
+                    if (end_in_solid(solid, res_x, res_y, res_z, bx, by, bz)) {
+                        v3_mac_clip_trace(scratch_clip, solid, res_x, res_y, res_z, x, y, pz, bx, by, bz);
+                        bx = scratch_clip[0]; by = scratch_clip[1]; bz = scratch_clip[2];
+                    }
+
+                    if (pass === 0) {
+                        fwd_w[f] = scs3d_sample_linear(src_w, res_x, res_y, sz, bx, by, bz + 0.5);
+                        continue;
+                    }
+
+                    let qx = x + cu * dt;
+                    let qy = y + cv * dt;
+                    let qz = pz + cw * dt;
+                    if (end_in_solid(solid, res_x, res_y, res_z, qx, qy, qz)) {
+                        v3_mac_clip_trace(scratch_clip, solid, res_x, res_y, res_z, x, y, pz, qx, qy, qz);
+                        qx = scratch_clip[0]; qy = scratch_clip[1]; qz = scratch_clip[2];
+                    }
+                    const backward = scs3d_sample_linear(fwd_w, res_x, res_y, sz, qx, qy, qz + 0.5);
+                    const corrected = fwd_w[f] + 0.5 * (src_w[f] - backward);
+
+                    out_w[f] = limit8(corrected, src_w,
+                        bx, by, bz + 0.5,
+                        res_x, res_y, sz, res_x, cell_slice);
+                }
+            }
+        }
+    }
+}
+
+/**
+ * Clamp `value` to the min/max of the 8 lattice taps around the fractional
+ * position `(lx, ly, lz)` in the lattice's own index space (clamped to its
+ * bounds — the same corner set the trilinear sampler interpolates from).
+ *
+ * @param {number} value
+ * @param {Float32Array} data
+ * @param {number} lx
+ * @param {number} ly
+ * @param {number} lz
+ * @param {number} dim_x
+ * @param {number} dim_y
+ * @param {number} dim_z
+ * @param {number} row    lattice row stride
+ * @param {number} slice  lattice slice stride
+ * @return {number}
+ */
+function limit8(value, data, lx, ly, lz, dim_x, dim_y, dim_z, row, slice) {
+    const bx = clamp(lx, 0, dim_x - 1);
+    const by = clamp(ly, 0, dim_y - 1);
+    const bz = clamp(lz, 0, dim_z - 1);
+    const x0 = bx | 0;
+    const y0 = by | 0;
+    const z0 = bz | 0;
+    const x1 = bx === x0 ? x0 : x0 + 1;
+    const y1 = by === y0 ? y0 : y0 + 1;
+    const z1 = bz === z0 ? z0 : z0 + 1;
+
+    const z0_off = z0 * slice;
+    const z1_off = z1 * slice;
+    const y0_off = y0 * row;
+    const y1_off = y1 * row;
+
+    let mn = data[z0_off + y0_off + x0];
+    let mx = mn;
+    let v = data[z0_off + y0_off + x1]; if (v < mn) mn = v; else if (v > mx) mx = v;
+    v = data[z0_off + y1_off + x0];     if (v < mn) mn = v; else if (v > mx) mx = v;
+    v = data[z0_off + y1_off + x1];     if (v < mn) mn = v; else if (v > mx) mx = v;
+    v = data[z1_off + y0_off + x0];     if (v < mn) mn = v; else if (v > mx) mx = v;
+    v = data[z1_off + y0_off + x1];     if (v < mn) mn = v; else if (v > mx) mx = v;
+    v = data[z1_off + y1_off + x0];     if (v < mn) mn = v; else if (v > mx) mx = v;
+    v = data[z1_off + y1_off + x1];     if (v < mn) mn = v; else if (v > mx) mx = v;
+    return value < mn ? mn : (value > mx ? mx : value);
+}

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

@@ -0,0 +1,53 @@
+/**
+ * Semi-Lagrangian advection of a cell-centered scalar by a MAC velocity
+ * field, solid-aware on both ends of the trace:
+ *
+ *   - the back-trace segment is CLIPPED against solid cells
+ *     ({@link v3_mac_clip_trace}) so a trace can neither sample inside a wall
+ *     nor tunnel through a thin one into a disconnected pocket;
+ *   - the sample at the (clipped) source position uses solid-MASKED
+ *     interpolation ({@link v3_grid_sample_scalar_masked}) so taps inside
+ *     walls — frozen values from whenever the cell solidified — contribute
+ *     nothing. Without this, walls slowly leak their frozen contents into
+ *     passing fluid and absorb dye from it (the stage-5 scalar-mass defect).
+ *
+ * The carrier velocity at each cell center is the average of the cell's two
+ * faces per axis (exact on the staggered layout). Solid destination cells
+ * pass their value through unchanged.
+ *
+ * @param {Float32Array} output  Cell-centered destination. Mutated.
+ * @param {Float32Array} input   Cell-centered source. Must not alias output.
+ * @param {Float32Array} vel_u   x-face velocities, (res_x+1)·res_y·res_z.
+ * @param {Float32Array} vel_v   y-face velocities.
+ * @param {Float32Array} vel_w   z-face velocities.
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {number} time_delta
+ * @param {Uint8Array} solid
+ */
+export function v3_mac_advect_sl_scalar(output: Float32Array, input: Float32Array, vel_u: Float32Array, vel_v: Float32Array, vel_w: Float32Array, res_x: number, res_y: number, res_z: number, time_delta: number, solid: Uint8Array): void;
+/**
+ * Unconditionally stable MacCormack advection of a cell-centered scalar by a
+ * MAC velocity field — forward + backward semi-Lagrangian passes, error
+ * correction, and Selle's monotone min-max limiter. Solid-aware throughout:
+ * both passes clip their traces and sample solid-masked (see
+ * {@link v3_mac_advect_sl_scalar}), and the limiter takes its extrema over
+ * the FLUID corners around the back-traced position only — when none are
+ * fluid the corrected value is discarded in favour of the first-order
+ * forward result.
+ *
+ * @param {Float32Array} output           Destination. Mutated.
+ * @param {Float32Array} input            Source. NOT mutated.
+ * @param {Float32Array} forward_scratch  Working buffer for the forward pass.
+ * @param {Float32Array} vel_u
+ * @param {Float32Array} vel_v
+ * @param {Float32Array} vel_w
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {number} time_delta
+ * @param {Uint8Array} solid
+ */
+export function v3_mac_advect_maccormack_scalar(output: Float32Array, input: Float32Array, forward_scratch: Float32Array, vel_u: Float32Array, vel_v: Float32Array, vel_w: Float32Array, res_x: number, res_y: number, res_z: number, time_delta: number, solid: Uint8Array): void;
+//# sourceMappingURL=v3_mac_advect_scalar.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"v3_mac_advect_scalar.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_mac_advect_scalar.js"],"names":[],"mappings":"AAiCA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,gDAXW,YAAY,SACZ,YAAY,SACZ,YAAY,SACZ,YAAY,SACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,SACN,UAAU,QA4CpB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wDAZW,YAAY,SACZ,YAAY,mBACZ,YAAY,SACZ,YAAY,SACZ,YAAY,SACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,SACN,UAAU,QA8GpB"}