@woosh/meep-engine 3.49.0 → 3.50.0

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

@@ -0,0 +1,287 @@
+import { chunk_fluid_effector_record_resolve } from "../../../../engine/physics/fluid/effector/record/chunk_fluid_effector_record_resolve.js";
+import { FLUID_EFFECTOR_RECORD_STRUCT } from "../../../../engine/physics/fluid/effector/record/FLUID_EFFECTOR_RECORD_STRUCT.js";
+import { FLUID_OBSTACLE_RECORD_STRUCT } from "../../../../engine/physics/fluid/obstacle/FLUID_OBSTACLE_RECORD_STRUCT.js";
+import { WebGPUExtensionType } from "../../../descriptor/WebGPUExtensionType.js";
+import { COLLECTION_U32_STRUCT_READ } from "../../gpu_primitive/COLLECTION_U32_STRUCT_READ.js";
+import { TRANSFORMS_TABLE } from "../../scene/chunk_scene_database_access.js";
+import { chunk_folded_workgroup_index } from "../../shader/chunk/grid/chunk_folded_workgroup_index.js";
+import { chunk_grid3d_to_index } from "../../shader/chunk/grid/chunk_grid3d_to_index.js";
+import { chunk_grid_tile_window } 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_cell } from "./chunk_fluid_forcing_cell.js";
+import {
+    FLUID_EFFECTOR_DESCRIPTOR,
+    FLUID_OBSTACLE_DESCRIPTOR,
+    FLUID_OBSTACLE_PLANE_DESCRIPTOR
+} from "./FLUID_DATABASE_SPEC.js";
+import { FLUID_FORCING_BRICK } from "./FLUID_FORCING.js";
+import { FLUID_FORCING_APPLY_STRUCT } from "./FLUID_FORCING_APPLY_STRUCT.js";
+
+/**
+ * Cells of the block a forcing workgroup tests for solids: its brick and the layer before it on every
+ * axis, whose cells pin the brick's −faces.
+ * @type {number}
+ */
+const SOLID_BLOCK = FLUID_FORCING_BRICK + 1;
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.createGroup()
+    .addUniform("settings", FLUID_FORCING_APPLY_STRUCT)
+    .addStorageBuffer("fluid_database", WebGPUArray.from(u32), false)
+    .addStorageBuffer("scene_database", WebGPUArray.from(u32), false)
+    .addStorageBuffer("list", COLLECTION_U32_STRUCT_READ, false)
+    .addStorageBuffer("survivors", WebGPUArray.from(u32), false)
+    .addStorageBuffer("leaf_rows", WebGPUArray.from(u32), false)
+    // the cascade's solid flags, window-local
+    .addStorageBuffer("solid", WebGPUArray.from(u32), true)
+    // the tick's forcing: u faces, then v from settings.forcing_v, then w from settings.forcing_w
+    .addStorageBuffer("forcing", WebGPUArray.from(f32), true)
+    // the cascade's persistent faces, toroidal, where a pinned face takes its wall's velocity
+    .addStorageTexture("out_u", "r32float", "3d", "write-only")
+    .addStorageTexture("out_v", "r32float", "3d", "write-only")
+    .addStorageTexture("out_w", "r32float", "3d", "write-only");
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+const SOLID_BLOCK: u32 = ${SOLID_BLOCK}u;
+const SOLID_BLOCK_CELLS: u32 = ${SOLID_BLOCK ** 3}u;
+
+var<workgroup> fluid_forcing_obstacles: array<${FLUID_OBSTACLE_RECORD_STRUCT.wgsl_ref}, FLUID_FORCING_OBSTACLE_LIMIT>;
+var<workgroup> fluid_forcing_globals: array<mat4x4<f32>, FLUID_FORCING_OBSTACLE_LIMIT>;
+var<workgroup> fluid_forcing_effectors: array<${FLUID_EFFECTOR_RECORD_STRUCT.wgsl_ref}, FLUID_FORCING_EFFECTOR_LIMIT>;
+// the slot of the obstacle each cell of the block is solid in, or FLUID_FORCING_NONE
+var<workgroup> fluid_forcing_solid_slot: array<u32, SOLID_BLOCK_CELLS>;
+
+fn fluid_forcing_obstacle(slot: u32) -> ${FLUID_OBSTACLE_RECORD_STRUCT.wgsl_ref} {
+    return fluid_forcing_obstacles[slot];
+}
+
+fn fluid_forcing_obstacle_global(slot: u32) -> mat4x4<f32> {
+    return fluid_forcing_globals[slot];
+}
+
+fn fluid_forcing_effector(slot: u32) -> ${FLUID_EFFECTOR_RECORD_STRUCT.wgsl_ref} {
+    return fluid_forcing_effectors[slot];
+}
+
+fn shape_record_plane(index: u32) -> vec4<f32> {
+    return ${FLUID_OBSTACLE_PLANE_DESCRIPTOR.marshalling_method_read_field('plane')}(&fluid_database, index);
+}
+
+// the slot a brick-local cell (-1 to 3 on each axis) is solid in
+fn fluid_forcing_block_slot(local: vec3<i32>) -> u32 {
+    return fluid_forcing_solid_slot[grid3d_to_index(vec3<u32>(local + vec3<i32>(1)), vec2<u32>(SOLID_BLOCK, SOLID_BLOCK))];
+}
+
+fn fluid_forcing_face_world(face: vec3<f32>) -> vec3<f32> {
+    return fluid_forcing_world(settings.cells.corner, settings.cell_size, face);
+}
+
+// A face between the cells whose solids are minus and plus: pinned when either is solid, and then it
+// takes the wall's velocity in the persistent faces, the solid cell's obstacle's, the + side's when
+// both are; otherwise its forcing is what the effectors deposit there.
+fn fluid_forcing_face_u(face: vec3<i32>, minus: u32, plus: u32, effector_count: u32) {
+    let x = fluid_forcing_face_world(vec3<f32>(face) - vec3<f32>(0.5, 0.0, 0.0));
+    let index = grid3d_to_index(vec3<u32>(face), settings.faces_u.size.xy);
+    let wall = select(minus, plus, plus != FLUID_FORCING_NONE);
+
+    if (wall != FLUID_FORCING_NONE) {
+        let velocity = fluid_forcing_wall_velocity(wall, x);
+
+        textureStore(out_u, grid_tile_window_storage(face, settings.faces_u.corner_storage, settings.faces_u.period), vec4<f32>(velocity.x, 0.0, 0.0, 0.0));
+        forcing[index] = 0.0;
+    } else {
+        forcing[index] = fluid_forcing_deposit(x, settings.dt, settings.cell_size, effector_count).x;
+    }
+}
+
+fn fluid_forcing_face_v(face: vec3<i32>, minus: u32, plus: u32, effector_count: u32) {
+    let x = fluid_forcing_face_world(vec3<f32>(face) - vec3<f32>(0.0, 0.5, 0.0));
+    let index = settings.forcing_v + grid3d_to_index(vec3<u32>(face), settings.faces_v.size.xy);
+    let wall = select(minus, plus, plus != FLUID_FORCING_NONE);
+
+    if (wall != FLUID_FORCING_NONE) {
+        let velocity = fluid_forcing_wall_velocity(wall, x);
+
+        textureStore(out_v, grid_tile_window_storage(face, settings.faces_v.corner_storage, settings.faces_v.period), vec4<f32>(velocity.y, 0.0, 0.0, 0.0));
+        forcing[index] = 0.0;
+    } else {
+        forcing[index] = fluid_forcing_deposit(x, settings.dt, settings.cell_size, effector_count).y;
+    }
+}
+
+fn fluid_forcing_face_w(face: vec3<i32>, minus: u32, plus: u32, effector_count: u32) {
+    let x = fluid_forcing_face_world(vec3<f32>(face) - vec3<f32>(0.0, 0.0, 0.5));
+    let index = settings.forcing_w + grid3d_to_index(vec3<u32>(face), settings.faces_w.size.xy);
+    let wall = select(minus, plus, plus != FLUID_FORCING_NONE);
+
+    if (wall != FLUID_FORCING_NONE) {
+        let velocity = fluid_forcing_wall_velocity(wall, x);
+
+        textureStore(out_w, grid_tile_window_storage(face, settings.faces_w.corner_storage, settings.faces_w.period), vec4<f32>(velocity.z, 0.0, 0.0, 0.0));
+        forcing[index] = 0.0;
+    } else {
+        forcing[index] = fluid_forcing_deposit(x, settings.dt, settings.cell_size, effector_count).z;
+    }
+}
+
+@compute @workgroup_size(${FLUID_FORCING_BRICK}, ${FLUID_FORCING_BRICK}, ${FLUID_FORCING_BRICK})
+fn main(
+    @builtin(workgroup_id) workgroup_id: vec3<u32>,
+    @builtin(local_invocation_id) local: vec3<u32>,
+    @builtin(local_invocation_index) lane: u32,
+) {
+    let entry = folded_workgroup_index(workgroup_id);
+
+    if (entry >= list.count) {
+        return;
+    }
+
+    let query = list.elements[entry];
+    let base = query * FLUID_FORCING_SURVIVOR_STRIDE;
+    let header = survivors[base];
+    let obstacle_count = header & 0xffffu;
+    let effector_count = header >> 16u;
+
+    // the brick's survivors into workgroup memory, posed: obstacles on lanes 0..23, effectors on 32..47
+    if (lane < obstacle_count) {
+        let row = leaf_rows[survivors[base + 1u + lane]];
+        let record = ${FLUID_OBSTACLE_DESCRIPTOR.marshalling_method_read}(&fluid_database, row);
+
+        fluid_forcing_obstacles[lane] = record;
+        fluid_forcing_globals[lane] = ${TRANSFORMS_TABLE.marshalling_method_read_field('global')}(&scene_database, record.node);
+    }
+
+    if (lane >= 32u && lane - 32u < effector_count) {
+        let slot = lane - 32u;
+        let row = leaf_rows[survivors[base + 1u + FLUID_FORCING_OBSTACLE_LIMIT + slot]];
+        let record = ${FLUID_EFFECTOR_DESCRIPTOR.marshalling_method_read}(&fluid_database, row);
+
+        fluid_forcing_effectors[slot] = fluid_effector_record_resolve(
+            record,
+            ${TRANSFORMS_TABLE.marshalling_method_read_field('global')}(&scene_database, record.node),
+            ${TRANSFORMS_TABLE.marshalling_method_read_field('prev_global')}(&scene_database, record.node),
+            settings.inverse_frame_dt
+        );
+    }
+
+    workgroupBarrier();
+
+    let origin = vec3<i32>(index_to_grid3d(query - settings.query_base, settings.bricks.xy) * FLUID_FORCING_BRICK);
+
+    // the solid test at every cell centre of the brick and the layer before it; a cell before the
+    // window is fluid, as every pass of the step reads it
+    for (var round = 0u; round < 2u; round++) {
+        let k = round * FLUID_FORCING_BRICK_CELLS + lane;
+
+        if (k < SOLID_BLOCK_CELLS) {
+            let cell = origin - vec3<i32>(1) + vec3<i32>(index_to_grid3d(k, vec2<u32>(SOLID_BLOCK, SOLID_BLOCK)));
+
+            var slot = FLUID_FORCING_NONE;
+
+            if (all(cell >= vec3<i32>(0))) {
+                slot = fluid_forcing_solid(fluid_forcing_face_world(vec3<f32>(cell)), obstacle_count);
+            }
+
+            fluid_forcing_solid_slot[k] = slot;
+        }
+    }
+
+    workgroupBarrier();
+
+    let brick_local = vec3<i32>(local);
+    let cell = origin + brick_local;
+    let flags = grid3d_to_index(vec3<u32>(cell), settings.cells.size.xy);
+
+    // listed only to clear what an earlier tick left: fluid, and no forcing to read
+    if (obstacle_count + effector_count == 0u) {
+        solid[flags] = 0u;
+
+        return;
+    }
+
+    let own = fluid_forcing_block_slot(brick_local);
+
+    solid[flags] = FLUID_FORCED_FLAG | select(0u, FLUID_SOLID_FLAG, own != FLUID_FORCING_NONE);
+
+    // the cell's -x, -y and -z faces
+    fluid_forcing_face_u(cell, fluid_forcing_block_slot(brick_local - vec3<i32>(1, 0, 0)), own, effector_count);
+    fluid_forcing_face_v(cell, fluid_forcing_block_slot(brick_local - vec3<i32>(0, 1, 0)), own, effector_count);
+    fluid_forcing_face_w(cell, fluid_forcing_block_slot(brick_local - vec3<i32>(0, 0, 1)), own, effector_count);
+
+    // the +boundary face planes, owned by the window's last cells; the cell beyond is fluid
+    let last = vec3<i32>(settings.cells.size) - vec3<i32>(1);
+
+    if (cell.x == last.x) {
+        fluid_forcing_face_u(cell + vec3<i32>(1, 0, 0), own, FLUID_FORCING_NONE, effector_count);
+    }
+    if (cell.y == last.y) {
+        fluid_forcing_face_v(cell + vec3<i32>(0, 1, 0), own, FLUID_FORCING_NONE, effector_count);
+    }
+    if (cell.z == last.z) {
+        fluid_forcing_face_w(cell + vec3<i32>(0, 0, 1), own, FLUID_FORCING_NONE, effector_count);
+    }
+}
+`, [
+    chunk_folded_workgroup_index,
+    chunk_index_to_grid3d,
+    chunk_grid3d_to_index,
+    chunk_grid_tile_window,
+    chunk_fluid_forcing_cell,
+    chunk_fluid_effector_record_resolve,
+    FLUID_OBSTACLE_DESCRIPTOR.chunk_read,
+    FLUID_EFFECTOR_DESCRIPTOR.chunk_read,
+    FLUID_OBSTACLE_PLANE_DESCRIPTOR.chunk_read_field('plane'),
+    TRANSFORMS_TABLE.chunk_read_field('global'),
+    TRANSFORMS_TABLE.chunk_read_field('prev_global'),
+]);
+
+body.addExtension(WebGPUExtensionType.Subgroups);
+
+/**
+ * Q3 of a tick, the forcing (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §10), for one stepping
+ * 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.
+ * 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
+ *    the wall's velocity (`fluid_forcing_wall_velocity`, the solid cell's obstacle, the + side's when
+ *    both are) **in the cascade's persistent faces**, before the step reads them, with forcing 0;
+ *    any other face's forcing is the effectors' deposit over `dt_c` on `h_c`
+ *    (`fluid_forcing_deposit`).
+ *
+ * Writing the wall's velocity into the persistent faces is what makes a face that just became pinned
+ * carry the wall, never the fluid value it held: advection reads it as a boundary value and every pass
+ * carries it through. A brick listed only because its flags held an earlier tick's has no survivors
+ * and writes its cells' flags to 0, which is also what leaves no reader of this tick's forcing there.
+ *
+ * Per invocation: two solid tests of at most 24 fields (768 hull planes at worst), three to six faces
+ * of at most 16 kernels. Workgroup memory: 24 records and matrices, 16 records, 125 slots, 4,724
+ * bytes.
+ *
+ * Bindings: `settings` ({@link FLUID_FORCING_APPLY_STRUCT}); `fluid_database` and `scene_database`;
+ * `list`, `survivors` and `leaf_rows` from the tick's query and the frame's leaf list; `solid`, the
+ * cascade's flags; `forcing`, the tick's; `out_u`, `out_v`, `out_w`, the cascade's persistent faces.
+ * Seven storage buffers and three storage textures.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_fluid_forcing_apply = ComputeShader.from({
+    label: "Fluid / forcing / apply",
+    resources,
+    body,
+});

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

@@ -0,0 +1,18 @@
+/**
+ * Words of one indirect dispatch command, `(x, y, z)`; a slot's command is at its index times this.
+ * @type {number}
+ */
+export const FLUID_FORCING_COMMAND_WORDS: number;
+/**
+ * Q2 of a tick (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §10): the forcing's indirect commands, one
+ * thread. Slot `s`'s command, at word `3·s`, is one workgroup for each brick its stepping cascade's
+ * brick query listed, folded over x, then y, then z against
+ * `WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION` as `IndirectComputeCommandBuildPass` folds,
+ * so the forcing finds its brick with `folded_workgroup_index` and never reads `num_workgroups`. A
+ * list of nothing is a command of `(0, 1, 1)`, which dispatches nothing.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_fluid_forcing_command: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_fluid_forcing_command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_fluid_forcing_command.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/fluid/forcing/shader_fluid_forcing_command.js"],"names":[],"mappings":"AAQA;;;GAGG;AACH,0CAFU,MAAM,CAE6B;AAqC7C;;;;;;;;;GASG;AACH,2CAFU,aAAa,CAMpB;8BA7D2B,+BAA+B"}

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

@@ -0,0 +1,64 @@
+import { COLLECTION_U32_STRUCT_READ } from "../../gpu_primitive/COLLECTION_U32_STRUCT_READ.js";
+import { WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION } from "../../gpu_primitive/indirect/WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+
+/**
+ * Words of one indirect dispatch command, `(x, y, z)`; a slot's command is at its index times this.
+ * @type {number}
+ */
+export const FLUID_FORCING_COMMAND_WORDS = 3;
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.createGroup()
+    .addStorageBuffer("list_0", COLLECTION_U32_STRUCT_READ, false)
+    .addStorageBuffer("list_1", COLLECTION_U32_STRUCT_READ, false)
+    .addStorageBuffer("commands", WebGPUArray.from(u32), true);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+// the width chunk_folded_workgroup_index strides by
+const LIMIT = ${WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION}u;
+
+fn divide_round_up(value: u32, divisor: u32) -> u32 {
+    return (value + divisor - 1u) / divisor;
+}
+
+// a workgroup a listed brick, folded: x to the limit, then rows of x, then slices of x·y
+fn fluid_forcing_write_command(slot: u32, groups: u32) {
+    let rows = divide_round_up(groups, LIMIT);
+    let slices = divide_round_up(rows, LIMIT);
+    let word = slot * ${FLUID_FORCING_COMMAND_WORDS}u;
+
+    commands[word] = min(groups, LIMIT);
+    commands[word + 1u] = min(max(rows, 1u), LIMIT);
+    commands[word + 2u] = max(slices, 1u);
+}
+
+@compute @workgroup_size(1, 1, 1)
+fn main() {
+    fluid_forcing_write_command(0u, list_0.count);
+    fluid_forcing_write_command(1u, list_1.count);
+}
+`);
+
+/**
+ * Q2 of a tick (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §10): the forcing's indirect commands, one
+ * thread. Slot `s`'s command, at word `3·s`, is one workgroup for each brick its stepping cascade's
+ * brick query listed, folded over x, then y, then z against
+ * `WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION` as `IndirectComputeCommandBuildPass` folds,
+ * so the forcing finds its brick with `folded_workgroup_index` and never reads `num_workgroups`. A
+ * list of nothing is a command of `(0, 1, 1)`, which dispatches nothing.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_fluid_forcing_command = ComputeShader.from({
+    label: "Fluid / forcing / commands",
+    resources,
+    body,
+});

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

@@ -0,0 +1,22 @@
+export const FLUID_FORCING_EXTRACT_WORKGROUP_SIZE: 64;
+/**
+ * L1 of the GPU fluid's acceleration structure (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §10), once a
+ * frame: the leaves {@link graph_bvh_build_lbvh} builds over, from the fluid database's rows.
+ *
+ * One thread a leaf of the CPU-compacted leaf → row list, obstacle rows first, then effector rows,
+ * each ascending (the TLAS's `#refresh_rows`, so the build's tie-breaking by leaf index is the rows'
+ * order). Leaf `i` reads its record and its node's pose from the scene's `transforms`, boxes it
+ * (`chunk_fluid_forcing_leaf`: an obstacle's solid region dilated a cell on its + sides; an effector's
+ * reach, a wake swept back over the frame's longest step), clips it into the frame's clip box, and
+ * writes the box and payload `i`. The centroids' bound is reduced into `scene_bounds` by a subgroup
+ * min/max, a pass over the workgroup's subgroups and one atomic each word, the TLAS's extraction
+ * (`shader_bvh_extract_instance_leaves`); `scene_bounds` is seeded with ±inf before.
+ *
+ * A pure function per leaf apart from the reduction: reads a leaf, 1 row word, a record (12 or 20
+ * words) and one or two matrices.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_fluid_forcing_extract: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_fluid_forcing_extract.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_fluid_forcing_extract.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/fluid/forcing/shader_fluid_forcing_extract.js"],"names":[],"mappings":"AAeA,sDAAuD;AAkIvD;;;;;;;;;;;;;;;;;GAiBG;AACH,2CAFU,aAAa,CAMpB;8BAjK2B,+BAA+B"}

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

@@ -0,0 +1,168 @@
+import { chunk_fluid_effector_record_resolve } from "../../../../engine/physics/fluid/effector/record/chunk_fluid_effector_record_resolve.js";
+import { WebGPUExtensionType } from "../../../descriptor/WebGPUExtensionType.js";
+import { TRANSFORMS_TABLE } from "../../scene/chunk_scene_database_access.js";
+import { chunk_atomic_max_f32_storage } from "../../shader/chunk/atomic/chunk_atomic_max_f32_storage.js";
+import { chunk_atomic_min_f32_storage } from "../../shader/chunk/atomic/chunk_atomic_min_f32_storage.js";
+import { F32_MAX_DEFINITION } from "../../shader/chunk/math/F32_MAX_DEFINITION.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { atomic_u32, f32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { chunk_fluid_forcing_leaf } from "./chunk_fluid_forcing_leaf.js";
+import { FLUID_EFFECTOR_DESCRIPTOR, FLUID_OBSTACLE_DESCRIPTOR } from "./FLUID_DATABASE_SPEC.js";
+import { FLUID_FORCING_EXTRACT_STRUCT } from "./FLUID_FORCING_EXTRACT_STRUCT.js";
+
+export const FLUID_FORCING_EXTRACT_WORKGROUP_SIZE = 64;
+
+/**
+ * Subgroup size is a runtime value of at least 4, so a workgroup splits into at most this many
+ * subgroups.
+ * @type {number}
+ */
+const MAX_SUBGROUPS = FLUID_FORCING_EXTRACT_WORKGROUP_SIZE / 4;
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.createGroup()
+    .addUniform("settings", FLUID_FORCING_EXTRACT_STRUCT)
+    .addStorageBuffer("fluid_database", WebGPUArray.from(u32), false)
+    .addStorageBuffer("scene_database", WebGPUArray.from(u32), false)
+    // the CPU-compacted leaf → row list: obstacle rows ascending, then effector rows ascending
+    .addStorageBuffer("leaf_rows", WebGPUArray.from(u32), false)
+    .addStorageBuffer("leaf_bounds", WebGPUArray.from(f32), true)
+    .addStorageBuffer("leaf_payload", WebGPUArray.from(u32), true)
+    // six words holding f32 bit patterns, seeded to +/-inf before this pass runs
+    .addStorageBuffer("scene_bounds", WebGPUArray.from(atomic_u32), true);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+const WORKGROUP_SIZE = ${FLUID_FORCING_EXTRACT_WORKGROUP_SIZE}u;
+
+var<workgroup> wg_low: array<vec3<f32>, ${MAX_SUBGROUPS}>;
+var<workgroup> wg_high: array<vec3<f32>, ${MAX_SUBGROUPS}>;
+
+fn fluid_forcing_leaf_box(leaf: u32) -> FluidForcingBox {
+    let row = leaf_rows[leaf];
+
+    if (leaf < settings.obstacle_leaf_count) {
+        let record = ${FLUID_OBSTACLE_DESCRIPTOR.marshalling_method_read}(&fluid_database, row);
+        let global = ${TRANSFORMS_TABLE.marshalling_method_read_field('global')}(&scene_database, record.node);
+
+        return fluid_forcing_obstacle_box(record, global, settings.dilation);
+    }
+
+    let record = ${FLUID_EFFECTOR_DESCRIPTOR.marshalling_method_read}(&fluid_database, row);
+    let global = ${TRANSFORMS_TABLE.marshalling_method_read_field('global')}(&scene_database, record.node);
+    let prev_global = ${TRANSFORMS_TABLE.marshalling_method_read_field('prev_global')}(&scene_database, record.node);
+
+    return fluid_forcing_effector_box(
+        fluid_effector_record_resolve(record, global, prev_global, settings.inverse_frame_dt),
+        settings.sweep_time
+    );
+}
+
+@compute @workgroup_size(WORKGROUP_SIZE, 1, 1)
+fn main(
+    @builtin(global_invocation_id) gid: vec3<u32>,
+    @builtin(local_invocation_index) thread_id: u32,
+    @builtin(subgroup_invocation_id) lane_id: u32,
+    @builtin(subgroup_size) lane_count: u32,
+) {
+    let i = gid.x;
+
+    // threads past the end bring the identity to the reduction, which every lane reaches
+    var low = vec3<f32>(F32_MAX);
+    var high = vec3<f32>(-F32_MAX);
+
+    if (i < settings.leaf_count) {
+        let box = fluid_forcing_box_clip(fluid_forcing_leaf_box(i), settings.clip_low, settings.clip_high);
+
+        let destination = i * 6u;
+
+        leaf_bounds[destination] = box.low.x;
+        leaf_bounds[destination + 1u] = box.low.y;
+        leaf_bounds[destination + 2u] = box.low.z;
+        leaf_bounds[destination + 3u] = box.high.x;
+        leaf_bounds[destination + 4u] = box.high.y;
+        leaf_bounds[destination + 5u] = box.high.z;
+
+        // the payload is the leaf: the queries sort by it, and a refit rewrites the leaf through it
+        leaf_payload[i] = i;
+
+        // the Morton pass quantises centroids, so their bound is the one it needs
+        let centroid = (box.low + box.high) * 0.5;
+
+        low = centroid;
+        high = centroid;
+    }
+
+    // subgroups first, workgroup memory only across subgroup boundaries (the TLAS's extraction)
+    let subgroup_low = subgroupMin(low);
+    let subgroup_high = subgroupMax(high);
+
+    let subgroup_id = thread_id / lane_count;
+    let subgroup_count = WORKGROUP_SIZE / lane_count;
+
+    if (lane_id == 0u) {
+        wg_low[subgroup_id] = subgroup_low;
+        wg_high[subgroup_id] = subgroup_high;
+    }
+
+    workgroupBarrier();
+
+    if (thread_id == 0u) {
+        var group_low = wg_low[0];
+        var group_high = wg_high[0];
+
+        for (var s = 1u; s < subgroup_count; s += 1u) {
+            group_low = min(group_low, wg_low[s]);
+            group_high = max(group_high, wg_high[s]);
+        }
+
+        atomic_min_f32_storage(&scene_bounds[0], group_low.x);
+        atomic_min_f32_storage(&scene_bounds[1], group_low.y);
+        atomic_min_f32_storage(&scene_bounds[2], group_low.z);
+        atomic_max_f32_storage(&scene_bounds[3], group_high.x);
+        atomic_max_f32_storage(&scene_bounds[4], group_high.y);
+        atomic_max_f32_storage(&scene_bounds[5], group_high.z);
+    }
+}
+`, [
+    chunk_fluid_forcing_leaf,
+    chunk_fluid_effector_record_resolve,
+    FLUID_OBSTACLE_DESCRIPTOR.chunk_read,
+    FLUID_EFFECTOR_DESCRIPTOR.chunk_read,
+    TRANSFORMS_TABLE.chunk_read_field('global'),
+    TRANSFORMS_TABLE.chunk_read_field('prev_global'),
+    chunk_atomic_min_f32_storage,
+    chunk_atomic_max_f32_storage,
+    F32_MAX_DEFINITION,
+]);
+
+body.addExtension(WebGPUExtensionType.Subgroups);
+
+/**
+ * L1 of the GPU fluid's acceleration structure (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §10), once a
+ * frame: the leaves {@link graph_bvh_build_lbvh} builds over, from the fluid database's rows.
+ *
+ * One thread a leaf of the CPU-compacted leaf → row list, obstacle rows first, then effector rows,
+ * each ascending (the TLAS's `#refresh_rows`, so the build's tie-breaking by leaf index is the rows'
+ * order). Leaf `i` reads its record and its node's pose from the scene's `transforms`, boxes it
+ * (`chunk_fluid_forcing_leaf`: an obstacle's solid region dilated a cell on its + sides; an effector's
+ * reach, a wake swept back over the frame's longest step), clips it into the frame's clip box, and
+ * writes the box and payload `i`. The centroids' bound is reduced into `scene_bounds` by a subgroup
+ * min/max, a pass over the workgroup's subgroups and one atomic each word, the TLAS's extraction
+ * (`shader_bvh_extract_instance_leaves`); `scene_bounds` is seeded with ±inf before.
+ *
+ * A pure function per leaf apart from the reduction: reads a leaf, 1 row word, a record (12 or 20
+ * words) and one or two matrices.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_fluid_forcing_extract = ComputeShader.from({
+    label: "Fluid / forcing / extract leaves",
+    resources,
+    body,
+});

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

@@ -0,0 +1,31 @@
+/**
+ * Q1 of a tick (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §10): every brick of every stepping cascade
+ * asks its cascade's LBVH of the frame which leaves meet it, one workgroup a brick, one dispatch for
+ * the tick.
+ *
+ * Query `q` is brick `q mod B` of stepping slot `q / B` (`B` bricks a window; at most two slots, cascade
+ * 0 and the ruler's coarse cascade). Its box is the brick's cells grown by the kernel floor, two of
+ * the cascade's cells (`fluid_forcing_brick_box`), and `chunk_bvh_query_aabb_cooperative` walks the
+ * slot's tree (`tree_0` or `tree_1`) a level at a time in workgroup memory, so a thread's work is
+ * bounded by the tree's depth. The resolution cull is the tree itself: a slot's tree holds the
+ * effectors and only the obstacles its cascade resolves (`GPUFluidForcing`), so no leaf is filtered
+ * here and an obstacle too small for the cascade never takes a place on the frontier. The candidates
+ * come back sorted by leaf, so obstacles (the first leaves) come first and each kind by row; the brick
+ * keeps the first
+ * `FLUID_FORCING_OBSTACLE_LIMIT` obstacles and the first `FLUID_FORCING_EFFECTOR_LIMIT` effectors in
+ * `survivors[q·FLUID_FORCING_SURVIVOR_STRIDE ...]`, and what it could not keep is added to
+ * `statistics`.
+ *
+ * A brick that kept anything, or whose cascade's solid flags still hold what an earlier tick wrote
+ * there (`bricks_s`, one word a brick the cascade keeps), is appended to its slot's list
+ * (`collection_u32_append`, one atomic a subgroup), with its survivor header; the forcing then runs
+ * over exactly those, and writes a held brick's flags to nothing.
+ *
+ * Per invocation: the query's 204 node reads at most and its sort, eight candidate reads for the
+ * split, two survivor writes.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_fluid_forcing_query: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_fluid_forcing_query.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_fluid_forcing_query.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/fluid/forcing/shader_fluid_forcing_query.js"],"names":[],"mappings":"AA+KA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,yCAFU,aAAa,CAMpB;8BAtM2B,+BAA+B"}