@woosh/meep-engine 3.49.0 → 3.50.0

package/src/shade/renderer/fluid/mac/chunk_v3_mac_face_pinned.js

@@ -0,0 +1,38 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+
+/**
+ * Whether a face of a MAC grid is pinned: a cell on either side of it is solid. A pinned face's
+ * normal velocity is a boundary condition, the wall's (0 for a static solid), and every pass carries
+ * it through unchanged.
+ *
+ * Faces are window-local, as in the CPU kernels: u face `(i, j, k)`, `i ∈ [0, nx]`, lies between
+ * cells `(i − 1, j, k)` and `(i, j, k)`, and likewise along y for v and z for w.
+ *
+ * The rule of the CPU's `v3_mac_compute_face_solid`, applied to every face. The CPU leaves the
+ * faces on its domain's edge open whatever their inside cell is; here a face on the window's edge is
+ * an ordinary face between a window cell and a cell outside, which `mac_cell_solid` answers for
+ * (fluid, in the fluid's passes), so an edge face beside a solid cell is pinned.
+ *
+ * ## Seam
+ *
+ * The enclosing shader defines `fn mac_cell_solid(cell: vec3<i32>) -> bool` for any window-local
+ * cell, inside the window or beyond it.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_v3_mac_face_pinned = CodeChunk.from(
+    //language=WGSL
+    `
+fn v3_mac_face_pinned_u(face: vec3<i32>) -> bool {
+    return mac_cell_solid(face - vec3<i32>(1, 0, 0)) || mac_cell_solid(face);
+}
+
+fn v3_mac_face_pinned_v(face: vec3<i32>) -> bool {
+    return mac_cell_solid(face - vec3<i32>(0, 1, 0)) || mac_cell_solid(face);
+}
+
+fn v3_mac_face_pinned_w(face: vec3<i32>) -> bool {
+    return mac_cell_solid(face - vec3<i32>(0, 0, 1)) || mac_cell_solid(face);
+}
+`
+);

package/src/shade/renderer/fluid/mac/chunk_v3_mac_lattice_corners.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `v3_mac_lattice_tap(position)`: the {@link V3_MAC_LATTICE_TAP_STRUCT} of a position in a lattice's
+ * own index space (lattice point `l` at `l`).
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_v3_mac_lattice_tap: CodeChunk;
+/**
+ * `v3_mac_limit(value, corners)`: Selle's monotone limiter, the value clamped to the least and the
+ * greatest of a tap's eight corners. Twin of the CPU's `v3_grid_limit8_at_indices`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_v3_mac_limit: CodeChunk;
+/**
+ * The corners of a tap on the advected field, one concrete function per component:
+ * `v3_mac_source_corners_u(position)`, `_v`, `_w`, `position` in that component's lattice index
+ * space. Eight reads of the seam `fn mac_source_u(face: vec3<i32>) -> f32` (and `_v`, `_w`), which
+ * the enclosing shader defines for any window-local face.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_v3_mac_source_corners: CodeChunk;
+/**
+ * {@link chunk_v3_mac_source_corners} for the predicted field MacCormack corrects with:
+ * `v3_mac_forward_corners_u(position)`, `_v`, `_w`, through the seam
+ * `fn mac_forward_u(face: vec3<i32>) -> f32` (and `_v`, `_w`).
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_v3_mac_forward_corners: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_v3_mac_lattice_corners.d.ts.map

package/src/shade/renderer/fluid/mac/chunk_v3_mac_lattice_corners.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_v3_mac_lattice_corners.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/fluid/mac/chunk_v3_mac_lattice_corners.js"],"names":[],"mappings":"AAqBA;;;;;GAKG;AACH,uCAFU,SAAS,CAkBjB;AAEF;;;;;GAKG;AACH,iCAFU,SAAS,CAkBjB;AAEF;;;;;;;GAOG;AACH,0CAFU,SAAS,CA0EjB;AAEF;;;;;;GAMG;AACH,2CAFU,SAAS,CA0EjB;0BAtOwB,oCAAoC"}

package/src/shade/renderer/fluid/mac/chunk_v3_mac_lattice_corners.js

@@ -0,0 +1,231 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { TEXTURE3D_TRILINEAR_CORNERS_STRUCT } from "../../shader/chunk/texture/TEXTURE3D_TRILINEAR_CORNERS_STRUCT.js";
+import { V3_MAC_LATTICE_TAP_STRUCT } from "./V3_MAC_LATTICE_TAP_STRUCT.js";
+
+/*
+ A manual trilinear tap on a face lattice of the fluid, read through seams: the corner maths of
+ chunk_texture3d_trilinear_corners, with each of the eight corners fetched through the enclosing
+ shader's seam instead of loaded from one texture region, because a corner may lie beyond the window
+ (where the far field or the parent answers) and a toroidal window wraps each corner on its own.
+ The result is the S0 TEXTURE3D_TRILINEAR_CORNERS_STRUCT, so texture3d_trilinear_interpolate blends
+ it, in f32 and with exact weights.
+
+ Two departures from that chunk's corner maths, both the CPU's:
+ - no clamp: the seam decides what a lattice point beyond the window holds (the CPU clamps it, which
+   a spec's seam reproduces);
+ - a corner at weight 0 collapses onto the lower one. It takes no part in the blend either way, but
+   the corners also bound the MacCormack limiter, and the CPU's limiter (and its sampler) leave such
+   a corner out: a trace ending exactly on a lattice plane, as every trace through a still axis does,
+   is bounded by that plane's values alone.
+*/
+
+/**
+ * `v3_mac_lattice_tap(position)`: the {@link V3_MAC_LATTICE_TAP_STRUCT} of a position in a lattice's
+ * own index space (lattice point `l` at `l`).
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_v3_mac_lattice_tap = CodeChunk.from(
+    //language=WGSL
+    `
+fn v3_mac_lattice_tap(position: vec3<f32>) -> ${V3_MAC_LATTICE_TAP_STRUCT.wgsl_ref} {
+    let base = floor(position);
+    let weight = position - base;
+    let lo = vec3<i32>(base);
+
+    // a corner at weight 0 takes no part in the blend, and none in the limiter's bounds
+    let hi = lo + select(vec3<i32>(1), vec3<i32>(0), weight == vec3<f32>(0.0));
+
+    return ${V3_MAC_LATTICE_TAP_STRUCT.wgsl_ref}(lo, hi, weight);
+}
+`, [
+        V3_MAC_LATTICE_TAP_STRUCT.declaration_chunk,
+    ]
+);
+
+/**
+ * `v3_mac_limit(value, corners)`: Selle's monotone limiter, the value clamped to the least and the
+ * greatest of a tap's eight corners. Twin of the CPU's `v3_grid_limit8_at_indices`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_v3_mac_limit = CodeChunk.from(
+    //language=WGSL
+    `
+fn v3_mac_limit(value: f32, corners: ${TEXTURE3D_TRILINEAR_CORNERS_STRUCT.wgsl_ref}) -> f32 {
+    let lower = min(corners.z0, corners.z1);
+    let upper = max(corners.z0, corners.z1);
+
+    return clamp(
+        value,
+        min(min(lower.x, lower.y), min(lower.z, lower.w)),
+        max(max(upper.x, upper.y), max(upper.z, upper.w))
+    );
+}
+`, [
+        TEXTURE3D_TRILINEAR_CORNERS_STRUCT.declaration_chunk,
+    ]
+);
+
+/**
+ * The corners of a tap on the advected field, one concrete function per component:
+ * `v3_mac_source_corners_u(position)`, `_v`, `_w`, `position` in that component's lattice index
+ * space. Eight reads of the seam `fn mac_source_u(face: vec3<i32>) -> f32` (and `_v`, `_w`), which
+ * the enclosing shader defines for any window-local face.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_v3_mac_source_corners = CodeChunk.from(
+    //language=WGSL
+    `
+fn v3_mac_source_corners_u(position: vec3<f32>) -> ${TEXTURE3D_TRILINEAR_CORNERS_STRUCT.wgsl_ref} {
+    let tap = v3_mac_lattice_tap(position);
+    let lo = tap.lo;
+    let hi = tap.hi;
+
+    return ${TEXTURE3D_TRILINEAR_CORNERS_STRUCT.wgsl_ref}(
+        vec4<f32>(
+            mac_source_u(lo),
+            mac_source_u(vec3<i32>(hi.x, lo.y, lo.z)),
+            mac_source_u(vec3<i32>(lo.x, hi.y, lo.z)),
+            mac_source_u(vec3<i32>(hi.x, hi.y, lo.z))
+        ),
+        vec4<f32>(
+            mac_source_u(vec3<i32>(lo.x, lo.y, hi.z)),
+            mac_source_u(vec3<i32>(hi.x, lo.y, hi.z)),
+            mac_source_u(vec3<i32>(lo.x, hi.y, hi.z)),
+            mac_source_u(hi)
+        ),
+        tap.weight
+    );
+}
+
+fn v3_mac_source_corners_v(position: vec3<f32>) -> ${TEXTURE3D_TRILINEAR_CORNERS_STRUCT.wgsl_ref} {
+    let tap = v3_mac_lattice_tap(position);
+    let lo = tap.lo;
+    let hi = tap.hi;
+
+    return ${TEXTURE3D_TRILINEAR_CORNERS_STRUCT.wgsl_ref}(
+        vec4<f32>(
+            mac_source_v(lo),
+            mac_source_v(vec3<i32>(hi.x, lo.y, lo.z)),
+            mac_source_v(vec3<i32>(lo.x, hi.y, lo.z)),
+            mac_source_v(vec3<i32>(hi.x, hi.y, lo.z))
+        ),
+        vec4<f32>(
+            mac_source_v(vec3<i32>(lo.x, lo.y, hi.z)),
+            mac_source_v(vec3<i32>(hi.x, lo.y, hi.z)),
+            mac_source_v(vec3<i32>(lo.x, hi.y, hi.z)),
+            mac_source_v(hi)
+        ),
+        tap.weight
+    );
+}
+
+fn v3_mac_source_corners_w(position: vec3<f32>) -> ${TEXTURE3D_TRILINEAR_CORNERS_STRUCT.wgsl_ref} {
+    let tap = v3_mac_lattice_tap(position);
+    let lo = tap.lo;
+    let hi = tap.hi;
+
+    return ${TEXTURE3D_TRILINEAR_CORNERS_STRUCT.wgsl_ref}(
+        vec4<f32>(
+            mac_source_w(lo),
+            mac_source_w(vec3<i32>(hi.x, lo.y, lo.z)),
+            mac_source_w(vec3<i32>(lo.x, hi.y, lo.z)),
+            mac_source_w(vec3<i32>(hi.x, hi.y, lo.z))
+        ),
+        vec4<f32>(
+            mac_source_w(vec3<i32>(lo.x, lo.y, hi.z)),
+            mac_source_w(vec3<i32>(hi.x, lo.y, hi.z)),
+            mac_source_w(vec3<i32>(lo.x, hi.y, hi.z)),
+            mac_source_w(hi)
+        ),
+        tap.weight
+    );
+}
+`, [
+        TEXTURE3D_TRILINEAR_CORNERS_STRUCT.declaration_chunk,
+        chunk_v3_mac_lattice_tap,
+    ]
+);
+
+/**
+ * {@link chunk_v3_mac_source_corners} for the predicted field MacCormack corrects with:
+ * `v3_mac_forward_corners_u(position)`, `_v`, `_w`, through the seam
+ * `fn mac_forward_u(face: vec3<i32>) -> f32` (and `_v`, `_w`).
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_v3_mac_forward_corners = CodeChunk.from(
+    //language=WGSL
+    `
+fn v3_mac_forward_corners_u(position: vec3<f32>) -> ${TEXTURE3D_TRILINEAR_CORNERS_STRUCT.wgsl_ref} {
+    let tap = v3_mac_lattice_tap(position);
+    let lo = tap.lo;
+    let hi = tap.hi;
+
+    return ${TEXTURE3D_TRILINEAR_CORNERS_STRUCT.wgsl_ref}(
+        vec4<f32>(
+            mac_forward_u(lo),
+            mac_forward_u(vec3<i32>(hi.x, lo.y, lo.z)),
+            mac_forward_u(vec3<i32>(lo.x, hi.y, lo.z)),
+            mac_forward_u(vec3<i32>(hi.x, hi.y, lo.z))
+        ),
+        vec4<f32>(
+            mac_forward_u(vec3<i32>(lo.x, lo.y, hi.z)),
+            mac_forward_u(vec3<i32>(hi.x, lo.y, hi.z)),
+            mac_forward_u(vec3<i32>(lo.x, hi.y, hi.z)),
+            mac_forward_u(hi)
+        ),
+        tap.weight
+    );
+}
+
+fn v3_mac_forward_corners_v(position: vec3<f32>) -> ${TEXTURE3D_TRILINEAR_CORNERS_STRUCT.wgsl_ref} {
+    let tap = v3_mac_lattice_tap(position);
+    let lo = tap.lo;
+    let hi = tap.hi;
+
+    return ${TEXTURE3D_TRILINEAR_CORNERS_STRUCT.wgsl_ref}(
+        vec4<f32>(
+            mac_forward_v(lo),
+            mac_forward_v(vec3<i32>(hi.x, lo.y, lo.z)),
+            mac_forward_v(vec3<i32>(lo.x, hi.y, lo.z)),
+            mac_forward_v(vec3<i32>(hi.x, hi.y, lo.z))
+        ),
+        vec4<f32>(
+            mac_forward_v(vec3<i32>(lo.x, lo.y, hi.z)),
+            mac_forward_v(vec3<i32>(hi.x, lo.y, hi.z)),
+            mac_forward_v(vec3<i32>(lo.x, hi.y, hi.z)),
+            mac_forward_v(hi)
+        ),
+        tap.weight
+    );
+}
+
+fn v3_mac_forward_corners_w(position: vec3<f32>) -> ${TEXTURE3D_TRILINEAR_CORNERS_STRUCT.wgsl_ref} {
+    let tap = v3_mac_lattice_tap(position);
+    let lo = tap.lo;
+    let hi = tap.hi;
+
+    return ${TEXTURE3D_TRILINEAR_CORNERS_STRUCT.wgsl_ref}(
+        vec4<f32>(
+            mac_forward_w(lo),
+            mac_forward_w(vec3<i32>(hi.x, lo.y, lo.z)),
+            mac_forward_w(vec3<i32>(lo.x, hi.y, lo.z)),
+            mac_forward_w(vec3<i32>(hi.x, hi.y, lo.z))
+        ),
+        vec4<f32>(
+            mac_forward_w(vec3<i32>(lo.x, lo.y, hi.z)),
+            mac_forward_w(vec3<i32>(hi.x, lo.y, hi.z)),
+            mac_forward_w(vec3<i32>(lo.x, hi.y, hi.z)),
+            mac_forward_w(hi)
+        ),
+        tap.weight
+    );
+}
+`, [
+        TEXTURE3D_TRILINEAR_CORNERS_STRUCT.declaration_chunk,
+        chunk_v3_mac_lattice_tap,
+    ]
+);

package/src/shade/renderer/fluid/mac/chunk_v3_mac_subtract_pressure_gradient.d.ts

@@ -0,0 +1,30 @@
+/**
+ * A face's velocity after the pressure gradient is taken from it, twin of the CPU's
+ * `v3_mac_subtract_pressure_gradient`, one concrete function per component:
+ *
+ *     u − scale · (p(right cell) − p(left cell))
+ *
+ * and a pinned face's velocity unchanged, since it is the wall's boundary condition.
+ *
+ * Pressure is physical kinematic pressure (m²/s²) and `scale` is `dt/h`. The CPU's projection
+ * potential (grid units, h = 1, no dt) is `q = (dt/h)·p`: the same face velocities come out of
+ * `u − (q_R − q_L)` there.
+ *
+ * A face on the window's edge reads the cell beyond it through the same seams: its pressure is the
+ * Dirichlet ghost the enclosing shader supplies (0 in S1, the CPU's open boundary), and its solid
+ * flag says whether the face is pinned.
+ *
+ * ## Seams
+ *
+ * The enclosing shader defines, for any window-local face or cell:
+ * - `fn mac_velocity_u(face: vec3<i32>) -> f32`, and `_v`, `_w`: the field being projected;
+ * - `fn mac_pressure(cell: vec3<i32>) -> f32`;
+ * - `fn mac_cell_solid(cell: vec3<i32>) -> bool`.
+ *
+ * One face read, two solid tests and two pressure reads a face.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_v3_mac_subtract_pressure_gradient: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_v3_mac_subtract_pressure_gradient.d.ts.map

package/src/shade/renderer/fluid/mac/chunk_v3_mac_subtract_pressure_gradient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_v3_mac_subtract_pressure_gradient.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/fluid/mac/chunk_v3_mac_subtract_pressure_gradient.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,sDAFU,SAAS,CAqCjB;0BAjEwB,oCAAoC"}

package/src/shade/renderer/fluid/mac/chunk_v3_mac_subtract_pressure_gradient.js

@@ -0,0 +1,66 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { chunk_v3_mac_face_pinned } from "./chunk_v3_mac_face_pinned.js";
+
+/**
+ * A face's velocity after the pressure gradient is taken from it, twin of the CPU's
+ * `v3_mac_subtract_pressure_gradient`, one concrete function per component:
+ *
+ *     u − scale · (p(right cell) − p(left cell))
+ *
+ * and a pinned face's velocity unchanged, since it is the wall's boundary condition.
+ *
+ * Pressure is physical kinematic pressure (m²/s²) and `scale` is `dt/h`. The CPU's projection
+ * potential (grid units, h = 1, no dt) is `q = (dt/h)·p`: the same face velocities come out of
+ * `u − (q_R − q_L)` there.
+ *
+ * A face on the window's edge reads the cell beyond it through the same seams: its pressure is the
+ * Dirichlet ghost the enclosing shader supplies (0 in S1, the CPU's open boundary), and its solid
+ * flag says whether the face is pinned.
+ *
+ * ## Seams
+ *
+ * The enclosing shader defines, for any window-local face or cell:
+ * - `fn mac_velocity_u(face: vec3<i32>) -> f32`, and `_v`, `_w`: the field being projected;
+ * - `fn mac_pressure(cell: vec3<i32>) -> f32`;
+ * - `fn mac_cell_solid(cell: vec3<i32>) -> bool`.
+ *
+ * One face read, two solid tests and two pressure reads a face.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_v3_mac_subtract_pressure_gradient = CodeChunk.from(
+    //language=WGSL
+    `
+fn v3_mac_subtract_pressure_gradient_u(face: vec3<i32>, scale: f32) -> f32 {
+    let velocity = mac_velocity_u(face);
+
+    if (v3_mac_face_pinned_u(face)) {
+        return velocity;
+    }
+
+    return velocity - scale * (mac_pressure(face) - mac_pressure(face - vec3<i32>(1, 0, 0)));
+}
+
+fn v3_mac_subtract_pressure_gradient_v(face: vec3<i32>, scale: f32) -> f32 {
+    let velocity = mac_velocity_v(face);
+
+    if (v3_mac_face_pinned_v(face)) {
+        return velocity;
+    }
+
+    return velocity - scale * (mac_pressure(face) - mac_pressure(face - vec3<i32>(0, 1, 0)));
+}
+
+fn v3_mac_subtract_pressure_gradient_w(face: vec3<i32>, scale: f32) -> f32 {
+    let velocity = mac_velocity_w(face);
+
+    if (v3_mac_face_pinned_w(face)) {
+        return velocity;
+    }
+
+    return velocity - scale * (mac_pressure(face) - mac_pressure(face - vec3<i32>(0, 0, 1)));
+}
+`, [
+        chunk_v3_mac_face_pinned,
+    ]
+);

package/src/shade/renderer/fluid/mac/chunk_v3_mac_vorticity_confinement.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The magnitude floor of the confinement's normalised gradient, the CPU's: a cell whose `|∇|ω||` is
+ * below it gets no force.
+ * @type {number}
+ */
+export const V3_MAC_CONFINEMENT_GRADIENT_FLOOR: number;
+/**
+ * Vorticity confinement's per-cell maths (Fedkiw, Stam, Jensen 2001) on a MAC grid, as pure functions:
+ * the WGSL twin of `v3_mac_apply_vorticity_confinement`'s passes 2 and 3, term for term.
+ *
+ * - `v3_mac_cell_velocity(u_low, u_high, v_low, v_high, w_low, w_high) -> vec3<f32>`: a cell's
+ *   velocity at its centre, the mean of its two faces on each axis (pass 1);
+ * - `v3_mac_curl(x_low, x_high, y_low, y_high, z_low, z_high) -> vec3<f32>`: `ω = ∇×v` at a cell by
+ *   central differences of its six neighbours' centre velocities, per cell, not per metre (pass 2);
+ * - `v3_mac_confinement_force(omega, gradient, epsilon_dt) -> vec3<f32>`: half the velocity a cell
+ *   gives each of its six faces, `½·ε·dt·(N × ω)`, `N = ∇|ω| / |∇|ω||` with `gradient` the central
+ *   difference of `|ω|`, per cell; 0 below {@link V3_MAC_CONFINEMENT_GRADIENT_FLOOR} (pass 3).
+ *
+ * Differences are per cell, as the CPU takes them, so on a field in m/s the force carries the cell
+ * size: `ω` per cell is `h·ω` per metre, and `ε·dt·(N × ω)` is Fedkiw's `ε·h·(N × ω)·dt` on every
+ * cascade with its own `h` and `dt`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_v3_mac_vorticity_confinement: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_v3_mac_vorticity_confinement.d.ts.map

package/src/shade/renderer/fluid/mac/chunk_v3_mac_vorticity_confinement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_v3_mac_vorticity_confinement.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/fluid/mac/chunk_v3_mac_vorticity_confinement.js"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,gDAFU,MAAM,CAEuC;AAEvD;;;;;;;;;;;;;;;;;GAiBG;AACH,iDAFU,SAAS,CAuCjB;0BAhEwB,oCAAoC"}

package/src/shade/renderer/fluid/mac/chunk_v3_mac_vorticity_confinement.js

@@ -0,0 +1,65 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+
+/**
+ * The magnitude floor of the confinement's normalised gradient, the CPU's: a cell whose `|∇|ω||` is
+ * below it gets no force.
+ * @type {number}
+ */
+export const V3_MAC_CONFINEMENT_GRADIENT_FLOOR = 1e-10;
+
+/**
+ * Vorticity confinement's per-cell maths (Fedkiw, Stam, Jensen 2001) on a MAC grid, as pure functions:
+ * the WGSL twin of `v3_mac_apply_vorticity_confinement`'s passes 2 and 3, term for term.
+ *
+ * - `v3_mac_cell_velocity(u_low, u_high, v_low, v_high, w_low, w_high) -> vec3<f32>`: a cell's
+ *   velocity at its centre, the mean of its two faces on each axis (pass 1);
+ * - `v3_mac_curl(x_low, x_high, y_low, y_high, z_low, z_high) -> vec3<f32>`: `ω = ∇×v` at a cell by
+ *   central differences of its six neighbours' centre velocities, per cell, not per metre (pass 2);
+ * - `v3_mac_confinement_force(omega, gradient, epsilon_dt) -> vec3<f32>`: half the velocity a cell
+ *   gives each of its six faces, `½·ε·dt·(N × ω)`, `N = ∇|ω| / |∇|ω||` with `gradient` the central
+ *   difference of `|ω|`, per cell; 0 below {@link V3_MAC_CONFINEMENT_GRADIENT_FLOOR} (pass 3).
+ *
+ * Differences are per cell, as the CPU takes them, so on a field in m/s the force carries the cell
+ * size: `ω` per cell is `h·ω` per metre, and `ε·dt·(N × ω)` is Fedkiw's `ε·h·(N × ω)·dt` on every
+ * cascade with its own `h` and `dt`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_v3_mac_vorticity_confinement = CodeChunk.from(
+    //language=WGSL
+    `
+const V3_MAC_CONFINEMENT_GRADIENT_FLOOR: f32 = ${V3_MAC_CONFINEMENT_GRADIENT_FLOOR};
+
+fn v3_mac_cell_velocity(u_low: f32, u_high: f32, v_low: f32, v_high: f32, w_low: f32, w_high: f32) -> vec3<f32> {
+    return vec3<f32>(0.5 * (u_low + u_high), 0.5 * (v_low + v_high), 0.5 * (w_low + w_high));
+}
+
+fn v3_mac_curl(
+    x_low: vec3<f32>, x_high: vec3<f32>,
+    y_low: vec3<f32>, y_high: vec3<f32>,
+    z_low: vec3<f32>, z_high: vec3<f32>
+) -> vec3<f32> {
+    return vec3<f32>(
+        0.5 * ((y_high.z - y_low.z) - (z_high.y - z_low.y)),
+        0.5 * ((z_high.x - z_low.x) - (x_high.z - x_low.z)),
+        0.5 * ((x_high.y - x_low.y) - (y_high.x - y_low.x))
+    );
+}
+
+fn v3_mac_confinement_force(omega: vec3<f32>, gradient: vec3<f32>, epsilon_dt: f32) -> vec3<f32> {
+    let length_g = sqrt(gradient.x * gradient.x + gradient.y * gradient.y + gradient.z * gradient.z);
+
+    if (length_g < V3_MAC_CONFINEMENT_GRADIENT_FLOOR) {
+        return vec3<f32>(0.0);
+    }
+
+    let s = epsilon_dt / length_g;
+
+    return vec3<f32>(
+        0.5 * s * (gradient.y * omega.z - gradient.z * omega.y),
+        0.5 * s * (gradient.z * omega.x - gradient.x * omega.z),
+        0.5 * s * (gradient.x * omega.y - gradient.y * omega.x)
+    );
+}
+`
+);

package/src/shade/renderer/fluid/mac/shader_fluid_mac_advect_correct.d.ts

@@ -0,0 +1,43 @@
+/**
+ * MacCormack's correct pass over one cascade window (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §8,
+ * pass 3): every face takes the predicted value corrected by half the round trip's error, limited to
+ * the source's corners around its back-trace end, into the transient set the projection works on.
+ * Then, on a face that is not pinned, the epilogue (`chunk_fluid_cascade_epilogue`): the atmosphere
+ * identity from the step's start to its end, the vorticity confinement when `step.confinement_dt` is
+ * not 0 (half of each of the face's two cells' force from `shader_fluid_mac_curl`), the relaxation band
+ * toward the parent on rows 2..5 with `step.band`, and the deviation clamp about `v_far` at the step's
+ * end; then the tick's forcing (§8
+ * pass 4: the divergence is of `velocity_mid + forcing`), on a face whose owning cell carries
+ * `FLUID_FORCED_FLAG`. A pinned face is the persistent face, the wall's velocity the forcing wrote.
+ *
+ * Dispatch and face ownership as {@link shader_fluid_mac_advect_predict}: `(nx / 8, ny / 8, nz / 4)`
+ * groups of 8 × 8 × 4, a cell's −x, −y and −z faces, and the +boundary planes from the last tile.
+ *
+ * Bindings:
+ * - `step`: {@link FLUID_MAC_STEP_STRUCT};
+ * - `parent`: {@link FLUID_CASCADE_PARENT_STRUCT}, and `parent_u`, `parent_v`, `parent_w` the parent's
+ *   persistent faces: beyond the window both the source and the predicted field are the parent's
+ *   identity read at the step's start, as the step's ghosts `ghost_u`, `ghost_v`, `ghost_w` hold it
+ *   and past them read again; the band reads the parent itself;
+ * - `source_u`, `source_v`, `source_w`: the persistent velocity the predict pass read, toroidal
+ *   through `step.faces_*`;
+ * - `forward_u`, `forward_v`, `forward_w`: what the predict pass wrote, window-local;
+ * - `solid`: the window-local solid flags, `array<u32>`, `FLUID_SOLID_FLAG` and `FLUID_FORCED_FLAG`;
+ * - `forcing`: the tick's forcing, `array<f32>`, the u faces' lattice, then v's, then w's, each x
+ *   fastest; read only under `FLUID_FORCED_FLAG`, so a step with no forcing binds anything;
+ * - `confinement`: the curl pass's force, `array<f32>` of 3·N, x of every cell, then y, then z, each
+ *   window-local x fastest; read only when `step.confinement_dt` is not 0, so a step without
+ *   confinement binds anything;
+ * - `out_u`, `out_v`, `out_w`: written, `r32float` 3-D storage textures, window-local.
+ *
+ * Reads a face: 9 carrier and 9 source texels, 9 predicted, 2 solid flags, 2 for the two trace ends
+ * and up to 8 for clips, 2 more flags for the epilogue, 1 more and a forcing word for the forcing, 2
+ * confinement words with confinement, and 8 parent texels on a band row. A cell: ~81 texels, ~21
+ * flags, 6 confinement words with confinement, ~24 parent texels on the band's four
+ * rows.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_fluid_mac_advect_correct: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_fluid_mac_advect_correct.d.ts.map

package/src/shade/renderer/fluid/mac/shader_fluid_mac_advect_correct.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_fluid_mac_advect_correct.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/fluid/mac/shader_fluid_mac_advect_correct.js"],"names":[],"mappings":"AAwMA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,8CAFU,aAAa,CAMpB;8BAlP2B,+BAA+B"}