@woosh/meep-engine 3.55.0 → 3.57.0

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

@@ -1,222 +1,257 @@
-import { chunk_grid3d_to_index } from "../../shader/chunk/grid/chunk_grid3d_to_index.js";
-import { chunk_grid_tile_window, GRID_TILE_SIZE } from "../../shader/chunk/grid/chunk_grid_tile_window.js";
-import { chunk_index_to_grid3d } from "../../shader/chunk/grid/chunk_index_to_grid3d.js";
-import { ComputeShader } from "../../shader/ComputeShader.js";
-import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
-import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
-import { f32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
-import { chunk_fluid_forcing_flags } from "../forcing/FLUID_FORCING.js";
-import { chunk_v3_mac_vorticity_confinement } from "./chunk_v3_mac_vorticity_confinement.js";
-import { FLUID_MAC_STEP_STRUCT } from "./FLUID_MAC_STEP_STRUCT.js";
-
-/**
- * The block of cells a curl workgroup holds the centre velocity of: its tile and two cells around it,
- * since a tile cell's force reads `|ω|` one cell out, and `ω` there reads the velocity one further.
- * @type {number[]}
- */
-const BLOCK = GRID_TILE_SIZE.map(n => n + 4);
-
-const BLOCK_CELLS = BLOCK[0] * BLOCK[1] * BLOCK[2];
-
-const resources = new ShaderResourceSetDescriptor();
-
-resources.createGroup()
-    .addUniform("step", FLUID_MAC_STEP_STRUCT)
-    .addTexture("source_u", "unfilterable-float", "3d")
-    .addTexture("source_v", "unfilterable-float", "3d")
-    .addTexture("source_w", "unfilterable-float", "3d")
-    .addStorageBuffer("solid", WebGPUArray.from(u32), false)
-    // the force, x of every cell, then y, then z, each window-local x fastest
-    .addStorageBuffer("confinement", WebGPUArray.from(f32), true);
-
-const body = CodeChunk.from(
-    //language=WGSL
-    `
-const FLUID_CURL_BLOCK_CELLS = ${BLOCK_CELLS}u;
-const FLUID_CURL_BLOCK_ROUNDS = ${Math.ceil(BLOCK_CELLS / (GRID_TILE_SIZE[0] * GRID_TILE_SIZE[1] * GRID_TILE_SIZE[2]))}u;
-
-// the centre velocity over the block, a component an array: 3 × ${BLOCK_CELLS} × 4 bytes
-var<workgroup> fluid_curl_u: array<f32, FLUID_CURL_BLOCK_CELLS>;
-var<workgroup> fluid_curl_v: array<f32, FLUID_CURL_BLOCK_CELLS>;
-var<workgroup> fluid_curl_w: array<f32, FLUID_CURL_BLOCK_CELLS>;
-// |ω| over the tile and one cell around it
-var<workgroup> fluid_curl_magnitude: array<f32, GRID_TILE_HALO_CELLS>;
-
-// where a tile-local cell, -2 to the tile's size + 1 on each axis, is in the block
-fn fluid_curl_block_index(local: vec3<i32>) -> u32 {
-    return grid3d_to_index(vec3<u32>(local + vec3<i32>(2)), vec2<u32>(${BLOCK[0]}u, ${BLOCK[1]}u));
-}
-
-fn fluid_curl_velocity(local: vec3<i32>) -> vec3<f32> {
-    let index = fluid_curl_block_index(local);
-
-    return vec3<f32>(fluid_curl_u[index], fluid_curl_v[index], fluid_curl_w[index]);
-}
-
-fn fluid_curl_magnitude_at(local: vec3<i32>) -> f32 {
-    return fluid_curl_magnitude[grid_tile_halo_index(local)];
-}
-
-// a window-local cell inside the window
-fn fluid_curl_cell_solid(cell: vec3<i32>) -> bool {
-    return (solid[grid3d_to_index(vec3<u32>(cell), step.cells.size.xy)] & FLUID_SOLID_FLAG) != 0u;
-}
-
-// a cell the curl is taken at, as the CPU takes it: inside the window, off its edge ring, fluid
-fn fluid_curl_interior(cell: vec3<i32>) -> bool {
-    let last = vec3<i32>(step.cells.size) - vec3<i32>(1);
-
-    if (any(cell < vec3<i32>(1)) || any(cell >= last)) {
-        return false;
-    }
-
-    return !fluid_curl_cell_solid(cell);
-}
-
-// the persistent velocity, toroidal through its windows; a window-local face inside the window
-fn fluid_curl_face_u(face: vec3<i32>) -> f32 {
-    return textureLoad(source_u, grid_tile_window_storage(face, step.faces_u.corner_storage, step.faces_u.period), 0).r;
-}
-
-fn fluid_curl_face_v(face: vec3<i32>) -> f32 {
-    return textureLoad(source_v, grid_tile_window_storage(face, step.faces_v.corner_storage, step.faces_v.period), 0).r;
-}
-
-fn fluid_curl_face_w(face: vec3<i32>) -> f32 {
-    return textureLoad(source_w, grid_tile_window_storage(face, step.faces_w.corner_storage, step.faces_w.period), 0).r;
-}
-
-fn fluid_curl_omega(local: vec3<i32>) -> vec3<f32> {
-    return v3_mac_curl(
-        fluid_curl_velocity(local - vec3<i32>(1, 0, 0)), fluid_curl_velocity(local + vec3<i32>(1, 0, 0)),
-        fluid_curl_velocity(local - vec3<i32>(0, 1, 0)), fluid_curl_velocity(local + vec3<i32>(0, 1, 0)),
-        fluid_curl_velocity(local - vec3<i32>(0, 0, 1)), fluid_curl_velocity(local + vec3<i32>(0, 0, 1))
-    );
-}
-
-@compute @workgroup_size(${GRID_TILE_SIZE.join(', ')})
-fn main(
-    @builtin(workgroup_id) group: vec3<u32>,
-    @builtin(local_invocation_id) local_id: vec3<u32>,
-    @builtin(local_invocation_index) lane: u32,
-) {
-    let origin = vec3<i32>(group) * GRID_TILE_SIZE;
-    let size = step.cells.size;
-
-    // the centre velocity over the block: 0 beyond the window and in a solid, as the CPU's pass 1
-    for (var round = 0u; round < FLUID_CURL_BLOCK_ROUNDS; round++) {
-        let index = round * GRID_TILE_THREADS + lane;
-
-        if (index < FLUID_CURL_BLOCK_CELLS) {
-            let cell = origin + vec3<i32>(index_to_grid3d(index, vec2<u32>(${BLOCK[0]}u, ${BLOCK[1]}u))) - vec3<i32>(2);
-
-            var velocity = vec3<f32>(0.0);
-
-            if (grid_tile_window_contains(cell, size) && !fluid_curl_cell_solid(cell)) {
-                velocity = v3_mac_cell_velocity(
-                    fluid_curl_face_u(cell), fluid_curl_face_u(cell + vec3<i32>(1, 0, 0)),
-                    fluid_curl_face_v(cell), fluid_curl_face_v(cell + vec3<i32>(0, 1, 0)),
-                    fluid_curl_face_w(cell), fluid_curl_face_w(cell + vec3<i32>(0, 0, 1))
-                );
-            }
-
-            fluid_curl_u[index] = velocity.x;
-            fluid_curl_v[index] = velocity.y;
-            fluid_curl_w[index] = velocity.z;
-        }
-    }
-
-    workgroupBarrier();
-
-    // |ω| over the tile and one cell around it: 0 where the CPU takes no curl
-    for (var round = 0u; round < GRID_TILE_LOAD_ROUNDS; round++) {
-        let index = round * GRID_TILE_THREADS + lane;
-
-        if (index < GRID_TILE_HALO_CELLS) {
-            let local = grid_tile_halo_local(index);
-
-            var magnitude = 0.0;
-
-            if (fluid_curl_interior(origin + local)) {
-                magnitude = length(fluid_curl_omega(local));
-            }
-
-            fluid_curl_magnitude[index] = magnitude;
-        }
-    }
-
-    workgroupBarrier();
-
-    // the cell's force: N × ω, N the normalised gradient of |ω|, half of it a face
-    let local = vec3<i32>(local_id);
-    let cell = origin + local;
-
-    var force = vec3<f32>(0.0);
-
-    if (fluid_curl_interior(cell)) {
-        let gradient = 0.5 * vec3<f32>(
-            fluid_curl_magnitude_at(local + vec3<i32>(1, 0, 0)) - fluid_curl_magnitude_at(local - vec3<i32>(1, 0, 0)),
-            fluid_curl_magnitude_at(local + vec3<i32>(0, 1, 0)) - fluid_curl_magnitude_at(local - vec3<i32>(0, 1, 0)),
-            fluid_curl_magnitude_at(local + vec3<i32>(0, 0, 1)) - fluid_curl_magnitude_at(local - vec3<i32>(0, 0, 1))
-        );
-
-        force = v3_mac_confinement_force(fluid_curl_omega(local), gradient, step.confinement_dt);
-    }
-
-    let count = size.x * size.y * size.z;
-    let index = grid3d_to_index(vec3<u32>(cell), size.xy);
-
-    confinement[index] = force.x;
-    confinement[count + index] = force.y;
-    confinement[2u * count + index] = force.z;
-}
-`, [
-        chunk_grid_tile_window,
-        chunk_grid3d_to_index,
-        chunk_index_to_grid3d,
-        chunk_v3_mac_vorticity_confinement,
-        chunk_fluid_forcing_flags,
-    ]
-);
-
-/**
- * Pass 1 of a cascade step (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §8), recorded only when the step
- * has vorticity confinement: the curl of the step's start velocity, and from it the confinement force
- * of every cell, which the correct pass adds to its faces after the atmosphere identity. The WGSL twin
- * of `v3_mac_apply_vorticity_confinement`'s three passes, the scatter to faces left to the correct pass
- * as a gather (`fluid_mac_confinement_*`), so a face takes half of each of its two cells' force.
- *
- * A tile pass: 8 × 8 × 4 cells a workgroup, dispatched `(nx / 8, ny / 8, nz / 4)`, two barriers. The
- * workgroup holds the centre velocity of its tile and two cells around it, 12 × 12 × 8 (3 × 4,608
- * bytes), and `|ω|` of its tile and one cell around it (2,400 bytes): 16,224 of the 16,384 bytes a
- * workgroup may have.
- *
- * 1. Every cell of the block takes its centre velocity, the mean of its two faces on each axis, from
- *    the persistent velocity through its toroidal windows; 0 beyond the window and in a solid.
- * 2. Every cell of the tile and its one-cell ring takes `|ω|`, `ω = ∇×v` by central differences, per
- *    cell; 0 on the window's edge ring, beyond it and in a solid, where the CPU takes no curl.
- * 3. Each invocation's cell, inside that ring and fluid, takes `½·ε·dt·(N × ω)` with
- *    `N = ∇|ω| / |∇|ω||` (`chunk_v3_mac_vorticity_confinement`), 0 below the CPU's floor; every other
- *    cell 0.
- *
- * `ε·dt` is `step.confinement_dt`, with the cascade's own `dt`; the differences are per cell, so the
- * force carries the cascade's `h` as the CPU's does (Fedkiw's `ε·h·(N × ω)`).
- *
- * Bindings:
- * - `step`: {@link FLUID_MAC_STEP_STRUCT};
- * - `source_u`, `source_v`, `source_w`: the persistent velocity, toroidal through `step.faces_*`;
- * - `solid`: the window-local solid flags, `array<u32>`, `FLUID_SOLID_FLAG`;
- * - `confinement`: written, `array<f32>` of 3·N, the force's x of every cell, then y, then z, each
- *   window-local x fastest.
- *
- * Reads a cell: 2.25 block cells of six face texels and a flag, 2.3 ring cells of six workgroup
- * velocities, one flag, then its own twelve velocities and six magnitudes.
- *
- * @type {ComputeShader}
- */
-export const shader_fluid_mac_curl = ComputeShader.from({
-    label: "Fluid / MAC curl",
-    body,
-    resources,
-});
+import { chunk_grid3d_to_index } from "../../shader/chunk/grid/chunk_grid3d_to_index.js";
+import { chunk_grid_tile_window, GRID_TILE_SIZE } from "../../shader/chunk/grid/chunk_grid_tile_window.js";
+import { chunk_index_to_grid3d } from "../../shader/chunk/grid/chunk_index_to_grid3d.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { f32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { chunk_fluid_forcing_flags } from "../forcing/FLUID_FORCING.js";
+import { chunk_v3_mac_vorticity_confinement } from "./chunk_v3_mac_vorticity_confinement.js";
+import { FLUID_MAC_STEP_STRUCT } from "./FLUID_MAC_STEP_STRUCT.js";
+
+/**
+ * The block of cells a curl workgroup holds the centre velocity of: its tile and two cells around it,
+ * since a tile cell's force reads `|ω|` one cell out, and `ω` there reads the velocity one further.
+ * @type {number[]}
+ */
+const BLOCK = GRID_TILE_SIZE.map(n => n + 4);
+
+const BLOCK_CELLS = BLOCK[0] * BLOCK[1] * BLOCK[2];
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.createGroup()
+    .addUniform("step", FLUID_MAC_STEP_STRUCT)
+    .addTexture("source_u", "unfilterable-float", "3d")
+    .addTexture("source_v", "unfilterable-float", "3d")
+    .addTexture("source_w", "unfilterable-float", "3d")
+    .addStorageBuffer("solid", WebGPUArray.from(u32), false)
+    // the force, x of every cell, then y, then z, each window-local x fastest
+    .addStorageBuffer("confinement", WebGPUArray.from(f32), true);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+const FLUID_CURL_BLOCK_CELLS = ${BLOCK_CELLS}u;
+const FLUID_CURL_BLOCK_ROUNDS = ${Math.ceil(BLOCK_CELLS / (GRID_TILE_SIZE[0] * GRID_TILE_SIZE[1] * GRID_TILE_SIZE[2]))}u;
+const FLUID_CURL_BLOCK_STRIDE_Y = ${BLOCK[0]}u;
+const FLUID_CURL_BLOCK_STRIDE_Z = ${BLOCK[0] * BLOCK[1]}u;
+const FLUID_CURL_HALO_STRIDE_Y = 10u;
+const FLUID_CURL_HALO_STRIDE_Z = 100u;
+const FLUID_CURL_EXCLUDED_BITS = 0x80000000u;
+
+// the centre velocity over the block, a component an array: 3 × ${BLOCK_CELLS} × 4 bytes
+var<workgroup> fluid_curl_u: array<f32, FLUID_CURL_BLOCK_CELLS>;
+var<workgroup> fluid_curl_v: array<f32, FLUID_CURL_BLOCK_CELLS>;
+var<workgroup> fluid_curl_w: array<f32, FLUID_CURL_BLOCK_CELLS>;
+// |ω| over the tile and one cell around it
+var<workgroup> fluid_curl_magnitude: array<f32, GRID_TILE_HALO_CELLS>;
+
+// where a tile-local cell, -2 to the tile's size + 1 on each axis, is in the block
+fn fluid_curl_block_index(local: vec3<i32>) -> u32 {
+    return grid3d_to_index(vec3<u32>(local + vec3<i32>(2)), vec2<u32>(${BLOCK[0]}u, ${BLOCK[1]}u));
+}
+
+// a window-local cell inside the window
+fn fluid_curl_cell_solid(cell: vec3<i32>) -> bool {
+    return (solid[grid3d_to_index(vec3<u32>(cell), step.cells.size.xy)] & FLUID_SOLID_FLAG) != 0u;
+}
+
+// whether a block-staged cell is interior to the window (off its edge ring) and fluid; solid cells
+// staged FLUID_CURL_EXCLUDED_BITS (-0.0) into fluid_curl_u during phase 1 so phase 2 never re-reads
+// the global solid buffer
+fn fluid_curl_interior_staged(block_idx: u32, cell: vec3<i32>, last: vec3<i32>) -> bool {
+    if (any(cell < vec3<i32>(1)) || any(cell >= last)) {
+        return false;
+    }
+
+    return bitcast<u32>(fluid_curl_u[block_idx]) != FLUID_CURL_EXCLUDED_BITS;
+}
+
+fn fluid_curl_omega_indexed(idx: u32) -> vec3<f32> {
+    let x_low = vec3<f32>(0.0, fluid_curl_v[idx - 1u], fluid_curl_w[idx - 1u]);
+    let x_high = vec3<f32>(0.0, fluid_curl_v[idx + 1u], fluid_curl_w[idx + 1u]);
+    let y_low = vec3<f32>(fluid_curl_u[idx - FLUID_CURL_BLOCK_STRIDE_Y], 0.0, fluid_curl_w[idx - FLUID_CURL_BLOCK_STRIDE_Y]);
+    let y_high = vec3<f32>(fluid_curl_u[idx + FLUID_CURL_BLOCK_STRIDE_Y], 0.0, fluid_curl_w[idx + FLUID_CURL_BLOCK_STRIDE_Y]);
+    let z_low = vec3<f32>(fluid_curl_u[idx - FLUID_CURL_BLOCK_STRIDE_Z], fluid_curl_v[idx - FLUID_CURL_BLOCK_STRIDE_Z], 0.0);
+    let z_high = vec3<f32>(fluid_curl_u[idx + FLUID_CURL_BLOCK_STRIDE_Z], fluid_curl_v[idx + FLUID_CURL_BLOCK_STRIDE_Z], 0.0);
+
+    return v3_mac_curl(x_low, x_high, y_low, y_high, z_low, z_high);
+}
+
+// maps lane in 0..255 to the 256 6-face exterior halo cells around the 8x8x4 interior tile:
+// 2*(8*4) x-faces + 2*(8*4) y-faces + 2*(8*8) z-faces = 64 + 64 + 128 = 256 cells
+fn fluid_curl_face_halo_local(lane: u32) -> vec3<i32> {
+    if (lane < 64u) {
+        return vec3<i32>(
+            select(-1, 8, (lane & 32u) != 0u),
+            i32(lane & 7u),
+            i32((lane >> 3u) & 3u)
+        );
+    }
+
+    if (lane < 128u) {
+        return vec3<i32>(
+            i32(lane & 7u),
+            select(-1, 8, (lane & 32u) != 0u),
+            i32((lane >> 3u) & 3u)
+        );
+    }
+
+    return vec3<i32>(
+        i32(lane & 7u),
+        i32((lane >> 3u) & 7u),
+        select(-1, 4, (lane & 64u) != 0u)
+    );
+}
+
+@compute @workgroup_size(${GRID_TILE_SIZE.join(', ')})
+fn main(
+    @builtin(workgroup_id) group: vec3<u32>,
+    @builtin(local_invocation_id) local_id: vec3<u32>,
+    @builtin(local_invocation_index) lane: u32,
+) {
+    let origin = vec3<i32>(group) * GRID_TILE_SIZE;
+    let size = step.cells.size;
+    let last = vec3<i32>(size) - vec3<i32>(1);
+
+    // the centre velocity over the block: 0 beyond the window and in a solid, as the CPU's pass 1.
+    // Cells with L1 distance > 2 from the 8x8x4 interior tile are never read by the 6-point curl stencil
+    // on the interior + 6-face halo cells, so they skip global solid/texture reads.
+    for (var round = 0u; round < FLUID_CURL_BLOCK_ROUNDS; round++) {
+        let index = round * GRID_TILE_THREADS + lane;
+
+        if (index < FLUID_CURL_BLOCK_CELLS) {
+            let block_local = vec3<i32>(index_to_grid3d(index, vec2<u32>(${BLOCK[0]}u, ${BLOCK[1]}u))) - vec3<i32>(2);
+            let dist_out = max(vec3<i32>(0), max(-block_local, block_local - vec3<i32>(7, 7, 3)));
+            let cell = origin + block_local;
+
+            var ux = bitcast<f32>(FLUID_CURL_EXCLUDED_BITS);
+            var uy = 0.0;
+            var uz = 0.0;
+
+            if ((dist_out.x + dist_out.y + dist_out.z) <= 2 && grid_tile_window_contains(cell, size) && !fluid_curl_cell_solid(cell)) {
+                let u0 = grid_tile_window_storage(cell, step.faces_u.corner_storage, step.faces_u.period);
+                let u1 = vec3<u32>(select(u0.x + 1u, 0u, u0.x + 1u == step.faces_u.period.x), u0.y, u0.z);
+                let v0 = grid_tile_window_storage(cell, step.faces_v.corner_storage, step.faces_v.period);
+                let v1 = vec3<u32>(v0.x, select(v0.y + 1u, 0u, v0.y + 1u == step.faces_v.period.y), v0.z);
+                let w0 = grid_tile_window_storage(cell, step.faces_w.corner_storage, step.faces_w.period);
+                let w1 = vec3<u32>(w0.x, w0.y, select(w0.z + 1u, 0u, w0.z + 1u == step.faces_w.period.z));
+
+                let velocity = v3_mac_cell_velocity(
+                    textureLoad(source_u, u0, 0).r, textureLoad(source_u, u1, 0).r,
+                    textureLoad(source_v, v0, 0).r, textureLoad(source_v, v1, 0).r,
+                    textureLoad(source_w, w0, 0).r, textureLoad(source_w, w1, 0).r
+                );
+                ux = select(velocity.x, 0.0, velocity.x == 0.0);
+                uy = velocity.y;
+                uz = velocity.z;
+            }
+
+            fluid_curl_u[index] = ux;
+            fluid_curl_v[index] = uy;
+            fluid_curl_w[index] = uz;
+        }
+    }
+
+    workgroupBarrier();
+
+    let local = vec3<i32>(local_id);
+    let cell = origin + local;
+    let own_block_idx = fluid_curl_block_index(local);
+    let own_halo_idx = grid_tile_halo_index(local);
+    let interior = fluid_curl_interior_staged(own_block_idx, cell, last);
+
+    var omega = vec3<f32>(0.0);
+    var own_magnitude = 0.0;
+
+    if (interior) {
+        omega = fluid_curl_omega_indexed(own_block_idx);
+        own_magnitude = length(omega);
+    }
+
+    fluid_curl_magnitude[own_halo_idx] = own_magnitude;
+
+    // |ω| over the 256 6-face exterior halo cells around the 8x8x4 tile (1 cell per lane, 0 loops)
+    let halo_local = fluid_curl_face_halo_local(lane);
+    let halo_block_idx = fluid_curl_block_index(halo_local);
+    var halo_magnitude = 0.0;
+
+    if (fluid_curl_interior_staged(halo_block_idx, origin + halo_local, last)) {
+        halo_magnitude = length(fluid_curl_omega_indexed(halo_block_idx));
+    }
+
+    fluid_curl_magnitude[grid_tile_halo_index(halo_local)] = halo_magnitude;
+
+    workgroupBarrier();
+
+    // the cell's force: N × ω, N the normalised gradient of |ω|, half of it a face
+    var force = vec3<f32>(0.0);
+
+    if (interior) {
+        let gradient = 0.5 * vec3<f32>(
+            fluid_curl_magnitude[own_halo_idx + 1u] - fluid_curl_magnitude[own_halo_idx - 1u],
+            fluid_curl_magnitude[own_halo_idx + FLUID_CURL_HALO_STRIDE_Y] - fluid_curl_magnitude[own_halo_idx - FLUID_CURL_HALO_STRIDE_Y],
+            fluid_curl_magnitude[own_halo_idx + FLUID_CURL_HALO_STRIDE_Z] - fluid_curl_magnitude[own_halo_idx - FLUID_CURL_HALO_STRIDE_Z]
+        );
+
+        force = v3_mac_confinement_force(omega, gradient, step.confinement_dt);
+    }
+
+    let count = size.x * size.y * size.z;
+    let index = grid3d_to_index(vec3<u32>(cell), size.xy);
+
+    confinement[index] = force.x;
+    confinement[count + index] = force.y;
+    confinement[2u * count + index] = force.z;
+}
+`, [
+        chunk_grid_tile_window,
+        chunk_grid3d_to_index,
+        chunk_index_to_grid3d,
+        chunk_v3_mac_vorticity_confinement,
+        chunk_fluid_forcing_flags,
+    ]
+);
+
+/**
+ * Pass 1 of a cascade step (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §8), recorded only when the step
+ * has vorticity confinement: the curl of the step's start velocity, and from it the confinement force
+ * of every cell, which the correct pass adds to its faces after the atmosphere identity. The WGSL twin
+ * of `v3_mac_apply_vorticity_confinement`'s three passes, the scatter to faces left to the correct pass
+ * as a gather (`fluid_mac_confinement_*`), so a face takes half of each of its two cells' force.
+ *
+ * A tile pass: 8 × 8 × 4 cells a workgroup, dispatched `(nx / 8, ny / 8, nz / 4)`, two barriers. The
+ * workgroup holds the centre velocity of its tile and two cells around it, 12 × 12 × 8 (3 × 4,608
+ * bytes), and `|ω|` of its tile and one cell around it (2,400 bytes): 16,224 of the 16,384 bytes a
+ * workgroup may have.
+ *
+ * 1. Every cell of the block takes its centre velocity, the mean of its two faces on each axis, from
+ *    the persistent velocity through its toroidal windows; 0 beyond the window and in a solid (encoded
+ *    as `-0.0` in `fluid_curl_u` so subsequent phases check solidness from workgroup memory without
+ *    re-reading `solid`).
+ * 2. Every interior cell evaluates its `ω = ∇×v` once (holding `ω` in registers across the second
+ *    barrier) and writes `|ω|` to the tile, while the 344 exterior halo cells evaluate `|ω|` in two
+ *    rounds; 0 on the window's edge ring, beyond it and in a solid, where the CPU takes no curl.
+ * 3. Each invocation's cell, inside that ring and fluid, takes `½·ε·dt·(N × ω)` with
+ *    `N = ∇|ω| / |∇|ω||` (`chunk_v3_mac_vorticity_confinement`), 0 below the CPU's floor; every other
+ *    cell 0.
+ *
+ * `ε·dt` is `step.confinement_dt`, with the cascade's own `dt`; the differences are per cell, so the
+ * force carries the cascade's `h` as the CPU's does (Fedkiw's `ε·h·(N × ω)`).
+ *
+ * Bindings:
+ * - `step`: {@link FLUID_MAC_STEP_STRUCT};
+ * - `source_u`, `source_v`, `source_w`: the persistent velocity, toroidal through `step.faces_*`;
+ * - `solid`: the window-local solid flags, `array<u32>`, `FLUID_SOLID_FLAG`;
+ * - `confinement`: written, `array<f32>` of 3·N, the force's x of every cell, then y, then z, each
+ *   window-local x fastest.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_fluid_mac_curl = ComputeShader.from({
+    label: "Fluid / MAC curl",
+    body,
+    resources,
+});

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

@@ -1,12 +1,12 @@
 /**
- * The right-hand side of the pressure solve over one cascade window
- * (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §8, pass 4): `f = div/dt` at every cell, `div` the MAC
- * divergence over h, and 0 in a solid cell. Pinned faces are read at their value, the wall's
- * velocity.
+ * The right-hand side and finest-level multigrid weights of the pressure solve over one cascade window
+ * (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §8, pass 4): `f = div/dt` and `fluid_mg_level0_word` at
+ * every cell, `div` the MAC divergence over h, and 0 in a solid cell. Pinned faces are read at their
+ * value, the wall's velocity.
  *
  * One invocation a cell, in 8 × 8 × 4 workgroups over the window, dispatched `(nx / 8, ny / 8, nz / 4)`.
- * Each reads its cell's six faces straight from the textures and its solid flag: 6 texels and 1 flag a
- * cell. Every face a window cell reads lies inside the window.
+ * Each reads its cell's six faces straight from the textures and its solid flags: 6 texels and up to 7
+ * flags a cell. Every face a window cell reads lies inside the window.
  *
  * Direct reads, not a tile in workgroup memory: an LDS tile with a one-cell halo (3 × 600 texels a
  * workgroup, 7.0 a cell) measured 2× slower on an RTX 4090 (D3D12, paired, 200 dispatches an arm, the
@@ -17,7 +17,8 @@
  * - `velocity_u`, `velocity_v`, `velocity_w`: the advected velocity, `r32float` 3-D textures,
  *   window-local; beyond the window the far field;
  * - `solid`: the window-local solid flags, `array<u32>`, bit 0;
- * - `rhs`: written, `array<f32>`, window-local, x fastest.
+ * - `rhs`: written, `array<f32>`, window-local, x fastest;
+ * - `words`: written, `array<u32>`, the finest level's weight words, window-local, x fastest.
  *
  * @type {ComputeShader}
  */

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

@@ -1 +1 @@
-{"version":3,"file":"shader_fluid_mac_divergence.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/fluid/mac/shader_fluid_mac_divergence.js"],"names":[],"mappings":"AAgEA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,0CAFU,aAAa,CAMpB;8BAxF2B,+BAA+B"}
+{"version":3,"file":"shader_fluid_mac_divergence.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/fluid/mac/shader_fluid_mac_divergence.js"],"names":[],"mappings":"AA0FA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,0CAFU,aAAa,CAMpB;8BAnH2B,+BAA+B"}