@woosh/meep-engine 3.56.0 → 3.57.0

package/src/shade/renderer/fluid/coupling/shader_fluid_cascade_ghosts.js

@@ -1,101 +1,108 @@
-import { chunk_grid_tile_window } from "../../shader/chunk/grid/chunk_grid_tile_window.js";
-import { ComputeShader } from "../../shader/ComputeShader.js";
-import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
-import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
-import { f32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
-import { FLUID_MAC_STEP_STRUCT } from "../mac/FLUID_MAC_STEP_STRUCT.js";
-import { FLUID_CASCADE_GHOST_DEPTH } from "./FLUID_CASCADE_GHOSTS.js";
-import { chunk_fluid_cascade_parent_pressure, chunk_fluid_cascade_parent_velocity } from "./chunk_fluid_cascade_parent.js";
-import { FLUID_CASCADE_PARENT_STRUCT } from "./FLUID_CASCADE_PARENT_STRUCT.js";
-
-const resources = new ShaderResourceSetDescriptor();
-
-resources.createGroup()
-    .addUniform("step", FLUID_MAC_STEP_STRUCT)
-    .addUniform("parent", FLUID_CASCADE_PARENT_STRUCT)
-    .addTexture("parent_u", "unfilterable-float", "3d")
-    .addTexture("parent_v", "unfilterable-float", "3d")
-    .addTexture("parent_w", "unfilterable-float", "3d")
-    .addStorageBuffer("parent_pressure", WebGPUArray.from(f32), false)
-    .addStorageTexture("ghost_u", "r32float", "3d", "write-only")
-    .addStorageTexture("ghost_v", "r32float", "3d", "write-only")
-    .addStorageTexture("ghost_w", "r32float", "3d", "write-only")
-    .addStorageBuffer("ghost_pressure", WebGPUArray.from(f32), true);
-
-const body = CodeChunk.from(
-    //language=WGSL
-    `
-const FLUID_CASCADE_GHOST_DEPTH = ${FLUID_CASCADE_GHOST_DEPTH};
-
-@compute @workgroup_size(4, 4, 4)
-fn main(@builtin(global_invocation_id) id: vec3<u32>) {
-    let offset = step.cells.corner - parent.origin;
-
-    // the velocity ghosts: shell texel t holds window-local face t - depth, of every face past the window
-    let face = vec3<i32>(id) - vec3<i32>(FLUID_CASCADE_GHOST_DEPTH);
-    let reach = vec3<u32>(2u * u32(FLUID_CASCADE_GHOST_DEPTH));
-
-    if (all(id < step.faces_u.size + reach) && !grid_tile_window_contains(face, step.faces_u.size)) {
-        textureStore(ghost_u, id, vec4<f32>(fluid_parent_face_u(face, offset), 0.0, 0.0, 0.0));
-    }
-
-    if (all(id < step.faces_v.size + reach) && !grid_tile_window_contains(face, step.faces_v.size)) {
-        textureStore(ghost_v, id, vec4<f32>(fluid_parent_face_v(face, offset), 0.0, 0.0, 0.0));
-    }
-
-    if (all(id < step.faces_w.size + reach) && !grid_tile_window_contains(face, step.faces_w.size)) {
-        textureStore(ghost_w, id, vec4<f32>(fluid_parent_face_w(face, offset), 0.0, 0.0, 0.0));
-    }
-
-    // the pressure ghosts: element t, x fastest over the window and a cell each side, of cell t - 1
-    let n = step.cells.size + vec3<u32>(2u);
-    let cell = vec3<i32>(id) - vec3<i32>(1);
-
-    if (all(id < n) && !grid_tile_window_contains(cell, step.cells.size)) {
-        ghost_pressure[id.x + n.x * (id.y + n.y * id.z)] = fluid_parent_pressure(cell + offset);
-    }
-}
-`, [
-        chunk_grid_tile_window,
-        chunk_fluid_cascade_parent_velocity,
-        chunk_fluid_cascade_parent_pressure,
-    ]
-);
-
-/**
- * A step's ghosts (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §7, §9, D3): the parent's identity read,
- * evaluated once at every face of a shell `FLUID_CASCADE_GHOST_DEPTH` faces deep around the
- * window, and the parent's pressure at the centre of every cell one past it, into transients the
- * step's passes read with one texel or element where the parent read takes eight.
- *
- * Read as of the cascade's record, the step's start, as the seams read the parent. A per-step cache:
- * the persistent textures still hold no ghost, and the toroidal windows are the window's alone.
- *
- * Measured on an RTX 4090 at 64×32×64 against the seams reading the parent per tap (four cascades,
- * the stacks driven alike, their recorded ticks replayed paired and interleaved, p10 of 200; the four
- * cascades' state after 32 ticks bit for bit the same): a tick that steps cascade 0 alone
- * 246.8 → 144.4 µs, one with a coarse step 489.5 → 291.8. Of cascade 0's step, predict 45 → 16 µs,
- * correct 89 → 27, the smoother 63 → 53, residual and restriction 22 → 18, the gradient 6 → 4, for
- * this pass's 9.
- *
- * One invocation a texel of the largest face shell, 4 × 4 × 4 a workgroup, dispatched
- * `ceil((N + 1 + 2·depth) / 4)` on each axis; an invocation inside the window writes nothing.
- *
- * Bindings:
- * - `step`: {@link FLUID_MAC_STEP_STRUCT}, the window;
- * - `parent`: {@link FLUID_CASCADE_PARENT_STRUCT}, `parent_u`, `parent_v`, `parent_w` and
- *   `parent_pressure`, the parent;
- * - `ghost_u`, `ghost_v`, `ghost_w`: written, `r32float` 3-D storage textures of the face lattices
- *   grown by the depth on every side, window-local face `f` at texel `f + depth`;
- * - `ghost_pressure`: written, `array<f32>` over the window grown by one cell on every side, x fastest.
- *
- * Two storage buffers and three storage textures.
- *
- * @type {ComputeShader}
- */
-export const shader_fluid_cascade_ghosts = ComputeShader.from({
-    label: "Fluid / cascade ghosts",
-    body,
-    resources,
-});
+import { chunk_grid_tile_window } from "../../shader/chunk/grid/chunk_grid_tile_window.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { f32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { FLUID_MAC_STEP_STRUCT } from "../mac/FLUID_MAC_STEP_STRUCT.js";
+import { FLUID_CASCADE_GHOST_DEPTH } from "./FLUID_CASCADE_GHOSTS.js";
+import { chunk_fluid_cascade_parent_pressure, chunk_fluid_cascade_parent_velocity } from "./chunk_fluid_cascade_parent.js";
+import { FLUID_CASCADE_PARENT_STRUCT } from "./FLUID_CASCADE_PARENT_STRUCT.js";
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.createGroup()
+    .addUniform("step", FLUID_MAC_STEP_STRUCT)
+    .addUniform("parent", FLUID_CASCADE_PARENT_STRUCT)
+    .addTexture("parent_u", "unfilterable-float", "3d")
+    .addTexture("parent_v", "unfilterable-float", "3d")
+    .addTexture("parent_w", "unfilterable-float", "3d")
+    .addStorageBuffer("parent_pressure", WebGPUArray.from(f32), false)
+    .addStorageTexture("ghost_u", "r32float", "3d", "write-only")
+    .addStorageTexture("ghost_v", "r32float", "3d", "write-only")
+    .addStorageTexture("ghost_w", "r32float", "3d", "write-only")
+    .addStorageBuffer("ghost_pressure", WebGPUArray.from(f32), true);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+const FLUID_CASCADE_GHOST_DEPTH = ${FLUID_CASCADE_GHOST_DEPTH};
+
+@compute @workgroup_size(4, 4, 4)
+fn main(@builtin(global_invocation_id) id: vec3<u32>) {
+    // the velocity ghosts: shell texel t holds window-local face t - depth, of every face past the window.
+    // Pressure ghosts also use cell = face (t - depth), so any invocation inside step.cells.size is inside
+    // all three face lattices and the pressure window, and exits immediately.
+    let face = vec3<i32>(id) - vec3<i32>(FLUID_CASCADE_GHOST_DEPTH);
+
+    if (grid_tile_window_contains(face, step.cells.size)) {
+        return;
+    }
+
+    let offset = step.cells.corner - parent.origin;
+    let reach = vec3<u32>(2u * u32(FLUID_CASCADE_GHOST_DEPTH));
+
+    if (all(id < step.faces_u.size + reach) && !grid_tile_window_contains(face, step.faces_u.size)) {
+        textureStore(ghost_u, id, vec4<f32>(fluid_parent_face_u(face, offset), 0.0, 0.0, 0.0));
+    }
+
+    if (all(id < step.faces_v.size + reach) && !grid_tile_window_contains(face, step.faces_v.size)) {
+        textureStore(ghost_v, id, vec4<f32>(fluid_parent_face_v(face, offset), 0.0, 0.0, 0.0));
+    }
+
+    if (all(id < step.faces_w.size + reach) && !grid_tile_window_contains(face, step.faces_w.size)) {
+        textureStore(ghost_w, id, vec4<f32>(fluid_parent_face_w(face, offset), 0.0, 0.0, 0.0));
+    }
+
+    // the pressure ghosts: element p_id = face + 1, x fastest over the window and a cell each side
+    let p_coord = face + vec3<i32>(1);
+    let n = step.cells.size + vec3<u32>(2u);
+
+    if (all(p_coord >= vec3<i32>(0)) && all(vec3<u32>(p_coord) < n)) {
+        let p_id = vec3<u32>(p_coord);
+        ghost_pressure[p_id.x + n.x * (p_id.y + n.y * p_id.z)] = fluid_parent_pressure(face + offset);
+    }
+}
+`, [
+        chunk_grid_tile_window,
+        chunk_fluid_cascade_parent_velocity,
+        chunk_fluid_cascade_parent_pressure,
+    ]
+);
+
+/**
+ * A step's ghosts (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §7, §9, D3): the parent's identity read,
+ * evaluated once at every face of a shell `FLUID_CASCADE_GHOST_DEPTH` faces deep around the
+ * window, and the parent's pressure at the centre of every cell one past it, into transients the
+ * step's passes read with one texel or element where the parent read takes eight.
+ *
+ * Read as of the cascade's record, the step's start, as the seams read the parent. A per-step cache:
+ * the persistent textures still hold no ghost, and the toroidal windows are the window's alone.
+ *
+ * Measured on an RTX 4090 at 64×32×64 against the seams reading the parent per tap (four cascades,
+ * the stacks driven alike, their recorded ticks replayed paired and interleaved, p10 of 200; the four
+ * cascades' state after 32 ticks bit for bit the same): a tick that steps cascade 0 alone
+ * 246.8 → 144.4 µs, one with a coarse step 489.5 → 291.8. Of cascade 0's step, predict 45 → 16 µs,
+ * correct 89 → 27, the smoother 63 → 53, residual and restriction 22 → 18, the gradient 6 → 4, for
+ * this pass's 9.
+ *
+ * One invocation a texel of the largest face shell, 4 × 4 × 4 a workgroup, dispatched
+ * `ceil((N + 1 + 2·depth) / 4)` on each axis; an invocation inside the window writes nothing.
+ *
+ * Bindings:
+ * - `step`: {@link FLUID_MAC_STEP_STRUCT}, the window;
+ * - `parent`: {@link FLUID_CASCADE_PARENT_STRUCT}, `parent_u`, `parent_v`, `parent_w` and
+ *   `parent_pressure`, the parent;
+ * - `ghost_u`, `ghost_v`, `ghost_w`: written, `r32float` 3-D storage textures of the face lattices
+ *   grown by the depth on every side, window-local face `f` at texel `f + depth`;
+ * - `ghost_pressure`: written, `array<f32>` over the window grown by one cell on every side, x fastest.
+ *
+ * Two storage buffers and three storage textures.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_fluid_cascade_ghosts = ComputeShader.from({
+    label: "Fluid / cascade ghosts",
+    body,
+    resources,
+});

package/src/shade/renderer/fluid/forcing/chunk_fluid_forcing_query_select.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_fluid_forcing_query_select.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/fluid/forcing/chunk_fluid_forcing_query_select.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,+CAFU,SAAS,CAuCjB;0BAlEwB,oCAAoC"}
+{"version":3,"file":"chunk_fluid_forcing_query_select.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/fluid/forcing/chunk_fluid_forcing_query_select.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,+CAFU,SAAS,CAyCjB;0BApEwB,oCAAoC"}

package/src/shade/renderer/fluid/forcing/chunk_fluid_forcing_query_select.js

@@ -1,67 +1,69 @@
-import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
-import { chunk_fluid_forcing_constants } from "./FLUID_FORCING.js";
-
-/**
- * The per-invocation decisions of a brick query (`shader_fluid_forcing_query`, Q1), as pure functions
- * the emulator runs:
- *
- * - `fluid_forcing_brick_box(corner, cell_size, brick) -> array<f32, 6>`: the query box of brick
- *   `brick` (in bricks) of a window whose world cell `corner` sits at window-local 0: its cells, world
- *   cell `g` covering `[g·h, (g + 1)·h)`, grown by `FLUID_FORCING_QUERY_GROWTH_CELLS` cells on every
- *   side, the kernel floor.
- * - `fluid_forcing_obstacle_split(count, obstacle_leaf_count) -> u32`: how many of the first `count`
- *   candidates, ascending, are obstacle leaves (below `obstacle_leaf_count`): a binary search over
- *   them, eight steps, which a candidate list of at most 128 needs.
- * - `fluid_forcing_survivor_header(obstacles, effectors) -> u32`: the counts a brick keeps, the low and
- *   high 16 bits of its survivor header.
- *
- * Survivors are the lowest leaves, which are the lowest rows: the leaf list holds obstacle rows
- * ascending and then effector rows ascending, so taking the first `FLUID_FORCING_OBSTACLE_LIMIT`
- * obstacle candidates and the first `FLUID_FORCING_EFFECTOR_LIMIT` effector ones is "by row index",
- * whatever order the traversal found them in, and stable under motion.
- *
- * ## Seam
- *
- * The enclosing shader defines `fn fluid_forcing_candidate(index: u32) -> u32`, the query's sorted
- * candidate list.
- *
- * @type {CodeChunk}
- */
-export const chunk_fluid_forcing_query_select = CodeChunk.from(
-    //language=WGSL
-    `
-fn fluid_forcing_brick_box(corner: vec3<i32>, cell_size: f32, brick: vec3<u32>) -> array<f32, 6> {
-    let first = vec3<f32>(corner + vec3<i32>(brick * FLUID_FORCING_BRICK));
-
-    let low = (first - vec3<f32>(FLUID_FORCING_QUERY_GROWTH_CELLS)) * cell_size;
-    let high = (first + vec3<f32>(f32(FLUID_FORCING_BRICK) + FLUID_FORCING_QUERY_GROWTH_CELLS)) * cell_size;
-
-    return array<f32, 6>(low.x, low.y, low.z, high.x, high.y, high.z);
-}
-
-fn fluid_forcing_obstacle_split(count: u32, obstacle_leaf_count: u32) -> u32 {
-    var low = 0u;
-    var high = count;
-
-    for (var step = 0u; step < 8u; step++) {
-        if (low < high) {
-            let middle = (low + high) >> 1u;
-
-            if (fluid_forcing_candidate(middle) < obstacle_leaf_count) {
-                low = middle + 1u;
-            } else {
-                high = middle;
-            }
-        }
-    }
-
-    return low;
-}
-
-fn fluid_forcing_survivor_header(obstacles: u32, effectors: u32) -> u32 {
-    return obstacles | (effectors << 16u);
-}
-`, [
-        chunk_fluid_forcing_constants,
-    ]
-);
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { chunk_fluid_forcing_constants } from "./FLUID_FORCING.js";
+
+/**
+ * The per-invocation decisions of a brick query (`shader_fluid_forcing_query`, Q1), as pure functions
+ * the emulator runs:
+ *
+ * - `fluid_forcing_brick_box(corner, cell_size, brick) -> array<f32, 6>`: the query box of brick
+ *   `brick` (in bricks) of a window whose world cell `corner` sits at window-local 0: its cells, world
+ *   cell `g` covering `[g·h, (g + 1)·h)`, grown by `FLUID_FORCING_QUERY_GROWTH_CELLS` cells on every
+ *   side, the kernel floor.
+ * - `fluid_forcing_obstacle_split(count, obstacle_leaf_count) -> u32`: how many of the first `count`
+ *   candidates, ascending, are obstacle leaves (below `obstacle_leaf_count`): a binary search over
+ *   them, eight steps, which a candidate list of at most 128 needs.
+ * - `fluid_forcing_survivor_header(obstacles, effectors) -> u32`: the counts a brick keeps, the low and
+ *   high 16 bits of its survivor header.
+ *
+ * Survivors are the lowest leaves, which are the lowest rows: the leaf list holds obstacle rows
+ * ascending and then effector rows ascending, so taking the first `FLUID_FORCING_OBSTACLE_LIMIT`
+ * obstacle candidates and the first `FLUID_FORCING_EFFECTOR_LIMIT` effector ones is "by row index",
+ * whatever order the traversal found them in, and stable under motion.
+ *
+ * ## Seam
+ *
+ * The enclosing shader defines `fn fluid_forcing_candidate(index: u32) -> u32`, the query's sorted
+ * candidate list.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_fluid_forcing_query_select = CodeChunk.from(
+    //language=WGSL
+    `
+fn fluid_forcing_brick_box(corner: vec3<i32>, cell_size: f32, brick: vec3<u32>) -> array<f32, 6> {
+    let first = vec3<f32>(corner + vec3<i32>(brick * FLUID_FORCING_BRICK));
+
+    let low = (first - vec3<f32>(FLUID_FORCING_QUERY_GROWTH_CELLS)) * cell_size;
+    let high = (first + vec3<f32>(f32(FLUID_FORCING_BRICK) + FLUID_FORCING_QUERY_GROWTH_CELLS)) * cell_size;
+
+    return array<f32, 6>(low.x, low.y, low.z, high.x, high.y, high.z);
+}
+
+fn fluid_forcing_obstacle_split(count: u32, obstacle_leaf_count: u32) -> u32 {
+    var low = 0u;
+    var high = count;
+
+    for (var step = 0u; step < 8u; step++) {
+        if (low < high) {
+            let middle = (low + high) >> 1u;
+
+            if (fluid_forcing_candidate(middle) < obstacle_leaf_count) {
+                low = middle + 1u;
+            } else {
+                high = middle;
+            }
+        } else {
+            break;
+        }
+    }
+
+    return low;
+}
+
+fn fluid_forcing_survivor_header(obstacles: u32, effectors: u32) -> u32 {
+    return obstacles | (effectors << 16u);
+}
+`, [
+        chunk_fluid_forcing_constants,
+    ]
+);

package/src/shade/renderer/fluid/forcing/shader_fluid_forcing_apply.d.ts

@@ -3,12 +3,13 @@
  * cascade: one workgroup of 4×4×4 for each brick its query listed, dispatched indirectly from Q2's
  * command, the brick found by `folded_workgroup_index`.
  *
- * 1. **The survivors, posed:** the brick's obstacle records with their nodes' `global`, and its
- *    effector records brought to the world (`fluid_effector_record_resolve` with the node's `global`
- *    and `prev_global`), into workgroup memory; one barrier.
- * 2. **The solid test** (`fluid_forcing_solid`) at the centre of every cell of the brick and the layer
- *    before it on each axis (125 cells, two rounds), recording the solid's obstacle; a cell before the
- *    window is fluid, as the step reads it. One barrier.
+ * 1. **The survivors, posed:** the brick's obstacle records with their nodes' `global` (rotation
+ *    columns pre-normalised), and its effector records brought to the world
+ *    (`fluid_effector_record_resolve` with the node's `global` and `prev_global`), into workgroup
+ *    memory; one barrier.
+ * 2. **The solid test** (`fluid_forcing_solid_prenorm`) at the centre of every cell of the brick and
+ *    the layer before it on each axis (125 cells, two rounds), recording the solid's obstacle; a cell
+ *    before the window is fluid, as the step reads it. One barrier.
  * 3. **Per cell:** its solid flags, `FLUID_FORCED_FLAG` with `FLUID_SOLID_FLAG` where solid; then each
  *    of its −x, −y, −z faces, and the window's last cells their +boundary faces: a face with a solid
  *    cell on either side is pinned, as every pass of the step will find it from the flags, and takes

package/src/shade/renderer/fluid/forcing/shader_fluid_forcing_apply.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_fluid_forcing_apply.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/fluid/forcing/shader_fluid_forcing_apply.js"],"names":[],"mappings":"AAuPA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,yCAFU,aAAa,CAMpB;8BApR2B,+BAA+B"}
+{"version":3,"file":"shader_fluid_forcing_apply.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/fluid/forcing/shader_fluid_forcing_apply.js"],"names":[],"mappings":"AA4SA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,yCAFU,aAAa,CAMpB;8BA1U2B,+BAA+B"}