@woosh/meep-engine 3.40.0 → 3.42.0

package/src/shade/renderer/water/surface/particles/shader_water_particles.js

@@ -0,0 +1,502 @@
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { WebGPUArray } from "../../../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { WGSLAttribute } from "../../../shader/type/WGSLAttribute.js";
+import { WGSLAttributes } from "../../../shader/type/WGSLAttributes.js";
+import { WGSLStructField } from "../../../shader/type/WGSLStructField.js";
+import { atomic_u32, f32, u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { COLLECTION_U32_STRUCT_READ } from "../../../gpu_primitive/COLLECTION_U32_STRUCT_READ.js";
+import { GEOMETRY_METADATA_STRUCT } from "../../../geometry/GEOMETRY_METADATA_STRUCT.js";
+import { MESHLET_METADATA_STRUCT } from "../../../geometry/meshlet/encoding/MESHLET_METADATA_STRUCT.js";
+import { BVH2_NODE_STRUCT } from "../../../shader/chunk/bvh/BVH2_NODE_STRUCT.js";
+import { chunk_folded_workgroup_index } from "../../../shader/chunk/grid/chunk_folded_workgroup_index.js";
+import { chunk_scene_database_access, chunk_scene_database_access_rw } from "../../../scene/chunk_scene_database_access.js";
+import { WaterActivity } from "../shader_water_cull.js";
+import { WATER_WAVES_TABLE as waves } from "../../medium/chunk_water_bodies.js";
+import { WATER_PARTICLE_BODY_BOUNDS_STRIDE } from "../shader_water_waves_combine.js";
+import { WATER_PARTICLE_ENTRY_STRUCT, WATER_PARTICLE_STRUCT } from "./WATER_PARTICLE_STRUCT.js";
+import { WATER_WAVE_IMPULSE_LIMIT } from "../WATER_WAVE_RECORD_STRUCT.js";
+import { chunk_water_particle } from "./chunk_water_particle.js";
+import { chunk_water_particle_step } from "./chunk_water_particle_step.js";
+
+/** A particle array with its live count in front, as the indirect commands read it. */
+export const WATER_PARTICLE_ARRAY_STRUCT = WebGPUStruct.fromFields(
+    WGSLStructField.from("count", u32),
+    WGSLStructField.from("elements", WebGPUArray.from(WATER_PARTICLE_STRUCT), WGSLAttribute.from(WGSLAttributes.Align, 16)),
+);
+
+/** The same array where emitters append by an atomic count. */
+export const WATER_PARTICLE_ARRAY_APPEND_STRUCT = WebGPUStruct.fromFields(
+    WGSLStructField.from("count", atomic_u32),
+    WGSLStructField.from("elements", WebGPUArray.from(WATER_PARTICLE_STRUCT), WGSLAttribute.from(WGSLAttributes.Align, 16)),
+);
+
+/** Bucket counts while binning: the table size in front, atomic counters behind. */
+export const WATER_PARTICLE_BUCKETS_STRUCT = WebGPUStruct.fromFields(
+    WGSLStructField.from("count", u32),
+    WGSLStructField.from("elements", WebGPUArray.from(atomic_u32), WGSLAttribute.from(WGSLAttributes.Align, 16)),
+);
+
+/** Smallest hash table, so an idle frame scans little. */
+export const WATER_PARTICLE_TABLE_MIN = 1024;
+
+/** Bucket entries one particle can take: the 2×2 cells its support overlaps. */
+export const WATER_PARTICLE_CORNERS = 4;
+
+/** Buckets ordered by particle; a crowded bucket past this keeps its arrival order. */
+export const WATER_PARTICLE_RANK_LIMIT = 64;
+
+/**
+ * Packets a crowded cell keeps: where more crowd a cell, each is drawn by its share of the cell's summed steepness
+ * times this, so about this many stay, the steepest whole. Well under the surface sampler's gather budget and the rank
+ * limit, so a point reads all of its cell and every bucket keeps the particles' order.
+ */
+export const WATER_PARTICLE_CELL_SHARE = 16;
+
+/** Width of the ramp a thinned packet fades over, a fraction of its share. */
+export const WATER_PARTICLE_THINNING_RAMP = 0.25;
+
+/** Fixed-point scale of a packet's steepness in its cells' sums. */
+const WATER_PARTICLE_WEIGHT_SCALE = 1 << 20;
+
+const STRIDE = WATER_PARTICLE_BODY_BOUNDS_STRIDE;
+
+/** The step's settings: one immediate per entry point. */
+export const WATER_PARTICLE_STEP_STRUCT = WebGPUStruct.from({ dt: f32, capacity: u32 }, 'WaterParticleStepSettings');
+
+/** The pool's limits for the frame's finalize. */
+export const WATER_PARTICLE_LIMITS_STRUCT = WebGPUStruct.from({ capacity: u32, table_limit: u32 }, 'WaterParticleLimits');
+
+const update_resources = new ShaderResourceSetDescriptor();
+update_resources.setImmediate('frame', WATER_PARTICLE_STEP_STRUCT);
+update_resources.createGroup()
+    .addStorageBuffer('particles', WATER_PARTICLE_ARRAY_STRUCT, true)
+    .addStorageBuffer('children', COLLECTION_U32_STRUCT_READ, true)
+    .addStorageBuffer('activity', WebGPUArray.u32)
+    .addStorageBuffer('scene_database', WebGPUArray.u32)
+    .addStorageBuffer('geometries', WebGPUArray.from(GEOMETRY_METADATA_STRUCT))
+    .addStorageBuffer('blas_lookup', WebGPUArray.u32)
+    .addStorageBuffer('blas_data', WebGPUArray.from(BVH2_NODE_STRUCT))
+    .addStorageBuffer('meshlet_metadata', WebGPUArray.from(MESHLET_METADATA_STRUCT))
+    .addStorageBuffer('meshlet_data', WebGPUArray.from(f32));
+
+/**
+ * Advance every live particle of a body simulated this frame in place and count what it leaves: 0, 1 or 3. A paused
+ * body's particles stand still and leave themselves.
+ */
+export const shader_water_particles_update = ComputeShader.from({ label: 'Water / particles update', resources: update_resources,
+    body: CodeChunk.from(/* language=WGSL */ `
+@compute @workgroup_size(64)
+fn main(@builtin(workgroup_id) group: vec3u, @builtin(local_invocation_index) lane: u32) {
+    let i = folded_workgroup_index(group) * 64u + lane;
+    let count = min(particles.count, frame.capacity);
+    if (i >= count) { return; }
+    var particle = particles.elements[i];
+    var left = 0u;
+    let node = ${waves.marshalling_method_read_field('node')}(&scene_database, particle.body);
+    if ((activity[particle.body] & ${WaterActivity.Active}u) == 0u) {
+        left = 1u;
+    } else if (node != 0u && node != ~0u) {
+        let global = scene_read_node(&scene_database, node).global;
+        let scale = max(vec2<f32>(length(global[0].xyz), length(global[2].xyz)), vec2<f32>(1e-20));
+        let threshold = water_particle_threshold(${waves.marshalling_method_read_field('slope_variance')}(&scene_database, particle.body),
+            count, frame.capacity);
+        let advanced = water_particle_advance(particle, frame.dt, ${waves.marshalling_method_read_field('geometry')}(&scene_database, particle.body),
+            scale, ${waves.marshalling_method_read_field('wind')}(&scene_database, particle.body).w, threshold);
+        particle = advanced.particle;
+        left = advanced.children;
+    }
+    particles.elements[i] = particle;
+    children.elements[i] = left;
+}
+`, [chunk_water_particle_step, chunk_scene_database_access, waves.chunk_read_field('node'), waves.chunk_read_field('slope_variance'),
+        waves.chunk_read_field('geometry'), waves.chunk_read_field('wind'), chunk_folded_workgroup_index]) });
+
+const split_resources = new ShaderResourceSetDescriptor();
+split_resources.setImmediate('capacity', u32);
+split_resources.createGroup()
+    .addStorageBuffer('particles', WATER_PARTICLE_ARRAY_STRUCT)
+    .addStorageBuffer('children', COLLECTION_U32_STRUCT_READ)
+    .addStorageBuffer('next', WATER_PARTICLE_ARRAY_STRUCT, true);
+
+/**
+ * Write what each particle leaves into the next array at its scanned offset, in order: a split particle's
+ * three at θ − β/3, θ, θ + β/3 with β/3 each. Past capacity, the tail is dropped.
+ */
+export const shader_water_particles_split = ComputeShader.from({ label: 'Water / particles split', resources: split_resources,
+    body: CodeChunk.from(/* language=WGSL */ `
+@compute @workgroup_size(64)
+fn main(@builtin(workgroup_id) group: vec3u, @builtin(local_invocation_index) lane: u32) {
+    let i = folded_workgroup_index(group) * 64u + lane;
+    let count = min(particles.count, capacity);
+    if (i >= count) { return; }
+    let end = children.elements[i];
+    var start = 0u;
+    if (i > 0u) { start = children.elements[i - 1u]; }
+    let particle = particles.elements[i];
+    if (end - start == 1u) {
+        if (start < capacity) { next.elements[start] = particle; }
+        return;
+    }
+    for (var k = start; k < end && k < capacity; k++) {
+        var child = particle;
+        child.dispersion = particle.dispersion / 3.0;
+        child.angle = particle.angle + (f32(k - start) - 1.0) * child.dispersion;
+        next.elements[k] = child;
+    }
+}
+`, [WATER_PARTICLE_STRUCT.declaration_chunk, chunk_folded_workgroup_index]) });
+
+const total_resources = new ShaderResourceSetDescriptor();
+total_resources.setImmediate('capacity', u32);
+total_resources.createGroup()
+    .addStorageBuffer('children', COLLECTION_U32_STRUCT_READ)
+    .addStorageBuffer('next', WATER_PARTICLE_ARRAY_STRUCT, true);
+
+/** The next array's count: everything the scan placed, up to capacity. */
+export const shader_water_particles_total = ComputeShader.from({ label: 'Water / particles total', resources: total_resources,
+    body: CodeChunk.from(/* language=WGSL */ `
+@compute @workgroup_size(1)
+fn main() {
+    let total = select(0u, children.elements[max(children.count, 1u) - 1u], children.count > 0u);
+    next.count = min(total, capacity);
+}
+`, [WATER_PARTICLE_STRUCT.declaration_chunk]) });
+
+const emit_resources = new ShaderResourceSetDescriptor();
+emit_resources.setImmediate('capacity', u32);
+emit_resources.createGroup()
+    .addStorageBuffer('scene_database', WebGPUArray.u32, true)
+    .addStorageBuffer('emit_rows', COLLECTION_U32_STRUCT_READ)
+    .addStorageBuffer('steep', WebGPUArray.from(u32))
+    .addStorageBuffer('activity', WebGPUArray.u32)
+    .addStorageBuffer('particle_bounds', WebGPUArray.u32, true)
+    .addStorageBuffer('next', WATER_PARTICLE_ARRAY_APPEND_STRUCT, true);
+
+/**
+ * Each queued splash of a row on the culling pass's emit list becomes a ring
+ * (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §5.3): packets of the splash's radius r, two radii out from its centre,
+ * a front's width apart, ridge height strength·r/c (a vertical velocity over the time a crest takes to cross the
+ * packet), no steeper than 0.1. The row's queue is spent. A paused body's ring stands still with its other particles,
+ * which this frame's binning does not visit, so the ring's bound is added to the body's own here.
+ */
+export const shader_water_particles_emit = ComputeShader.from({ label: 'Water / particles emit', resources: emit_resources,
+    body: CodeChunk.from(/* language=WGSL */ `
+@compute @workgroup_size(64)
+fn main(@builtin(workgroup_id) group: vec3u, @builtin(local_invocation_index) lane: u32) {
+    let index = folded_workgroup_index(group) * 64u + lane;
+    if (index >= emit_rows.count) { return; }
+    let row = emit_rows.elements[index];
+    let wave = ${waves.marshalling_method_read_rw}(&scene_database, row);
+    ${waves.marshalling_method_write_field('impulse_count')}(&scene_database, row, 0u);
+    if (wave.node == 0u || wave.node == ~0u || steep[row] != 0u) { return; }
+    let global = scene_read_node_rw(&scene_database, wave.node).global;
+    let scale = vec2<f32>(length(global[0].xyz), length(global[2].xyz));
+    let paused = (activity[row] & ${WaterActivity.Active}u) == 0u;
+    var held = 0.0;
+    for (var j = 0u; j < min(wave.impulse_count, ${WATER_WAVE_IMPULSE_LIMIT}u); j++) {
+        let impulse = wave.impulses[j];
+        let radius = clamp(impulse.z, 1e-3, 16.0);
+        let height = clamp(impulse.w * radius / water_particle_phase_speed(radius), -0.1 * radius, 0.1 * radius);
+        let reach = 2.0 * radius;
+        let count = u32(ceil(WATER_TAU * reach / (2.0 * radius)));
+        let dispersion = WATER_TAU / f32(count);
+        let age = reach / water_particle_group_speed(radius);
+        let base = atomicAdd(&next.count, count);
+        // a ring that does not fit whole is not emitted: an arc of it would break its front's partition of unity.
+        // The slots it took up to capacity hold flat packets, which the next step drops.
+        let ridge = select(0.0, height, base + count <= capacity);
+        for (var k = 0u; k < count; k++) {
+            if (base + k >= capacity) { break; }
+            next.elements[base + k] = ${WATER_PARTICLE_STRUCT.wgsl_ref}(impulse.xy * scale, f32(k) * dispersion, age, ridge, radius, dispersion, row);
+        }
+        held += f32(count) * abs(ridge);
+    }
+    if (paused && held > 0.0) {
+        // level 0's slot, and its bit, so that the culling pass, which reads the slots only of the levels set, counts it
+        let at = row * ${STRIDE}u;
+        particle_bounds[at] |= 1u;
+        particle_bounds[at + 1u] = bitcast<u32>(bitcast<f32>(particle_bounds[at + 1u]) + held);
+    }
+}
+`, [waves.chunk_read_rw, waves.wgsl_gen_write_field_code('impulse_count'), chunk_water_particle, chunk_scene_database_access_rw,
+        chunk_folded_workgroup_index]) });
+
+const finalize_resources = new ShaderResourceSetDescriptor();
+finalize_resources.setImmediate('limits', WATER_PARTICLE_LIMITS_STRUCT);
+finalize_resources.createGroup()
+    .addStorageBuffer('next', WATER_PARTICLE_ARRAY_STRUCT, true)
+    .addStorageBuffer('offsets', COLLECTION_U32_STRUCT_READ, true);
+
+/**
+ * The live count, clamped to capacity (emitters append past it), and the frame's hash table size: twice the
+ * entries the particles can take, a power of two, at least ${WATER_PARTICLE_TABLE_MIN}.
+ */
+export const shader_water_particles_finalize = ComputeShader.from({ label: 'Water / particles finalize', resources: finalize_resources,
+    body: CodeChunk.from(/* language=WGSL */ `
+@compute @workgroup_size(1)
+fn main() {
+    let live = min(next.count, limits.capacity);
+    next.count = live;
+    let wanted = max(2u * ${WATER_PARTICLE_CORNERS}u * live, ${WATER_PARTICLE_TABLE_MIN}u);
+    offsets.count = min(1u << (32u - countLeadingZeros(wanted - 1u)), limits.table_limit);
+}
+`, [WATER_PARTICLE_STRUCT.declaration_chunk]) });
+
+/**
+ * A live particle's place in the hash this frame: its kernel at this time, its level and the cells its
+ * support overlaps (one or two a side, the level's cell being at least the support's diameter).
+ */
+const chunk_water_particle_cells = CodeChunk.from(/* language=WGSL */ `
+struct WaterParticleCells {
+    entry: ${WATER_PARTICLE_ENTRY_STRUCT.wgsl_ref},
+    level: u32,
+    first: vec2<i32>,
+    span: vec2<u32>,
+}
+
+fn water_particle_cells(particle: ${WATER_PARTICLE_STRUCT.wgsl_ref}, source: u32) -> WaterParticleCells {
+    var cells: WaterParticleCells;
+    let position = water_particle_position(particle);
+    let width = water_particle_width(particle);
+    let support = water_particle_support(particle.radius, width);
+    cells.level = water_particle_level(support);
+    let size = water_particle_cell_size(cells.level);
+    cells.first = vec2<i32>(floor((position - vec2<f32>(support)) / size));
+    let last = vec2<i32>(floor((position + vec2<f32>(support)) / size));
+    cells.span = vec2<u32>(clamp(last - cells.first, vec2<i32>(0), vec2<i32>(1))) + vec2<u32>(1u);
+    cells.entry = ${WATER_PARTICLE_ENTRY_STRUCT.wgsl_ref}(position, cells.first, particle.angle, particle.amplitude, particle.radius,
+        width, water_particle_phase(particle), (particle.body << 4u) | cells.level, source, 0u);
+    return cells;
+}
+
+fn water_particle_corner_cell(cells: WaterParticleCells, corner: u32) -> vec2<i32> {
+    return cells.first + vec2<i32>(i32(corner & 1u), i32(corner >> 1u));
+}
+
+fn water_particle_has_corner(cells: WaterParticleCells, corner: u32) -> bool {
+    return all(vec2<u32>(corner & 1u, corner >> 1u) < cells.span);
+}
+
+// A packet's claim on its cells: its steepness, fixed point.
+fn water_particle_weight(particle: ${WATER_PARTICLE_STRUCT.wgsl_ref}) -> u32 {
+    return u32(min(abs(particle.amplitude) / max(particle.radius, 1e-6), 1.0) * ${WATER_PARTICLE_WEIGHT_SCALE}.0);
+}
+
+// A number in [0, 1) that stays with a packet while it travels: from its front's centre and direction.
+fn water_particle_lot(particle: ${WATER_PARTICLE_STRUCT.wgsl_ref}) -> f32 {
+    let bits = pcg3d(vec3<u32>(bitcast<u32>(particle.origin.x), bitcast<u32>(particle.origin.y), bitcast<u32>(particle.angle)));
+    return f32(bits.x >> 8u) * (1.0 / 16777216.0);
+}
+
+// How much of a packet its crowd leaves drawn, from its share of the most crowded of its cells: all of it from a share
+// of one, and below that, all of it while its lot is under its share, fading to none a ramp of that share above. So a
+// cell keeps about its share whatever its crowd.
+fn water_particle_visibility(share: f32, lot: f32) -> f32 {
+    return clamp((share - lot) / (${WATER_PARTICLE_THINNING_RAMP} * share) + 1.0, 0.0, 1.0);
+}
+`, [chunk_water_particle]);
+
+const weigh_resources = new ShaderResourceSetDescriptor();
+weigh_resources.createGroup()
+    .addStorageBuffer('next', WATER_PARTICLE_ARRAY_STRUCT)
+    .addStorageBuffer('activity', WebGPUArray.u32)
+    .addStorageBuffer('offsets', COLLECTION_U32_STRUCT_READ)
+    .addStorageBuffer('bucket_weight', WebGPUArray.from(atomic_u32), true);
+
+/**
+ * Each particle of a body simulated this frame adds its steepness to every cell its support overlaps: how crowded a
+ * cell is, for the bin pass to thin it by.
+ */
+export const shader_water_particles_weigh = ComputeShader.from({ label: 'Water / particles weigh', resources: weigh_resources,
+    body: CodeChunk.from(/* language=WGSL */ `
+@compute @workgroup_size(64)
+fn main(@builtin(workgroup_id) group: vec3u, @builtin(local_invocation_index) lane: u32) {
+    let i = folded_workgroup_index(group) * 64u + lane;
+    if (i >= next.count) { return; }
+    let particle = next.elements[i];
+    if ((activity[particle.body] & ${WaterActivity.Active}u) == 0u) { return; }
+    let cells = water_particle_cells(particle, i);
+    let weight = water_particle_weight(particle);
+    for (var corner = 0u; corner < ${WATER_PARTICLE_CORNERS}u; corner++) {
+        if (!water_particle_has_corner(cells, corner)) { continue; }
+        atomicAdd(&bucket_weight[water_particle_bucket(particle.body, cells.level, water_particle_corner_cell(cells, corner), offsets.count)], weight);
+    }
+}
+`, [chunk_water_particle_cells, chunk_folded_workgroup_index]) });
+
+const bin_resources = new ShaderResourceSetDescriptor();
+bin_resources.createGroup()
+    .addStorageBuffer('next', WATER_PARTICLE_ARRAY_STRUCT)
+    .addStorageBuffer('activity', WebGPUArray.u32)
+    .addStorageBuffer('buckets', WATER_PARTICLE_BUCKETS_STRUCT, true)
+    .addStorageBuffer('slots', WebGPUArray.u32, true)
+    .addStorageBuffer('bucket_amplitude', WebGPUArray.from(atomic_u32), true)
+    .addStorageBuffer('body_bounds', WebGPUArray.from(atomic_u32), true)
+    .addStorageBuffer('bucket_weight', WebGPUArray.u32)
+    .addStorageBuffer('visible', WebGPUArray.from(f32), true);
+
+/**
+ * Enter each particle of a body simulated this frame in every hash cell its support overlaps: count it into the cell's
+ * bucket, keep its slot there, raise the bucket's largest |a| to its own, and mark its level on its body. One atomic
+ * each: no compare-exchange loop a crowded bucket would serialize. A paused body's particles take no slot: nothing
+ * draws them this frame.
+ *
+ * Where cells are crowded (the weigh pass), a particle is drawn by how much its most crowded cell leaves it
+ * ({@link WATER_PARTICLE_CELL_SHARE}): one decision for all its cells, so the surface stays continuous across them, and
+ * from its own lot, so it does not change with the order particles arrive in. One left out takes no slot.
+ */
+export const shader_water_particles_bin = ComputeShader.from({ label: 'Water / particles bin', resources: bin_resources,
+    body: CodeChunk.from(/* language=WGSL */ `
+@compute @workgroup_size(64)
+fn main(@builtin(workgroup_id) group: vec3u, @builtin(local_invocation_index) lane: u32) {
+    let i = folded_workgroup_index(group) * 64u + lane;
+    if (i >= next.count) { return; }
+    let particle = next.elements[i];
+    if ((activity[particle.body] & ${WaterActivity.Active}u) == 0u) {
+        for (var corner = 0u; corner < ${WATER_PARTICLE_CORNERS}u; corner++) { slots[i * ${WATER_PARTICLE_CORNERS}u + corner] = ~0u; }
+        return;
+    }
+    let cells = water_particle_cells(particle, i);
+    let weight = f32(water_particle_weight(particle));
+    var share = 1e30;
+    for (var corner = 0u; corner < ${WATER_PARTICLE_CORNERS}u; corner++) {
+        if (!water_particle_has_corner(cells, corner)) { continue; }
+        let total = f32(bucket_weight[water_particle_bucket(particle.body, cells.level, water_particle_corner_cell(cells, corner), buckets.count)]);
+        if (total > 0.0) { share = min(share, ${WATER_PARTICLE_CELL_SHARE}.0 * weight / total); }
+    }
+    let visibility = water_particle_visibility(share, water_particle_lot(particle));
+    visible[i] = visibility;
+    if (!(visibility > 0.0)) {
+        for (var corner = 0u; corner < ${WATER_PARTICLE_CORNERS}u; corner++) { slots[i * ${WATER_PARTICLE_CORNERS}u + corner] = ~0u; }
+        return;
+    }
+    atomicOr(&body_bounds[particle.body * ${STRIDE}u], 1u << cells.level);
+    for (var corner = 0u; corner < ${WATER_PARTICLE_CORNERS}u; corner++) {
+        var slot = ~0u;
+        if (water_particle_has_corner(cells, corner)) {
+            let bucket = water_particle_bucket(particle.body, cells.level, water_particle_corner_cell(cells, corner), buckets.count);
+            slot = atomicAdd(&buckets.elements[bucket], 1u);
+            // non-negative floats order as their bits do
+            atomicMax(&bucket_amplitude[bucket], bitcast<u32>(abs(particle.amplitude) * visibility));
+        }
+        slots[i * ${WATER_PARTICLE_CORNERS}u + corner] = slot;
+    }
+}
+`, [chunk_water_particle_cells, chunk_folded_workgroup_index]) });
+
+const scatter_resources = new ShaderResourceSetDescriptor();
+scatter_resources.createGroup()
+    .addStorageBuffer('next', WATER_PARTICLE_ARRAY_STRUCT)
+    .addStorageBuffer('offsets', COLLECTION_U32_STRUCT_READ)
+    .addStorageBuffer('slots', WebGPUArray.u32)
+    .addStorageBuffer('visible', WebGPUArray.from(f32))
+    .addStorageBuffer('staging', WebGPUArray.from(WATER_PARTICLE_ENTRY_STRUCT), true);
+
+/** Each entry to its bucket's range, in arrival order, at the height its crowd leaves it; the rank pass orders it. */
+export const shader_water_particles_scatter = ComputeShader.from({ label: 'Water / particles scatter', resources: scatter_resources,
+    body: CodeChunk.from(/* language=WGSL */ `
+@compute @workgroup_size(64)
+fn main(@builtin(workgroup_id) group: vec3u, @builtin(local_invocation_index) lane: u32) {
+    let i = folded_workgroup_index(group) * 64u + lane;
+    if (i >= next.count) { return; }
+    let particle = next.elements[i];
+    let cells = water_particle_cells(particle, i);
+    for (var corner = 0u; corner < ${WATER_PARTICLE_CORNERS}u; corner++) {
+        let slot = slots[i * ${WATER_PARTICLE_CORNERS}u + corner];
+        if (slot == ~0u) { continue; }
+        let cell = water_particle_corner_cell(cells, corner);
+        let bucket = water_particle_bucket(particle.body, cells.level, cell, offsets.count);
+        var start = 0u;
+        if (bucket > 0u) { start = offsets.elements[bucket - 1u]; }
+        var entry = cells.entry;
+        entry.cell = cell;
+        entry.amplitude *= visible[i];
+        staging[start + slot] = entry;
+    }
+}
+`, [chunk_water_particle_cells, chunk_folded_workgroup_index]) });
+
+const rank_resources = new ShaderResourceSetDescriptor();
+rank_resources.createGroup()
+    .addStorageBuffer('next', WATER_PARTICLE_ARRAY_STRUCT)
+    .addStorageBuffer('offsets', COLLECTION_U32_STRUCT_READ)
+    .addStorageBuffer('slots', WebGPUArray.u32)
+    .addStorageBuffer('staging', WebGPUArray.from(WATER_PARTICLE_ENTRY_STRUCT))
+    .addStorageBuffer('entries', WebGPUArray.from(WATER_PARTICLE_ENTRY_STRUCT), true);
+
+/**
+ * Order every bucket by particle index then cell, so a gather that runs out of budget drops the same
+ * entries every frame (the particle array keeps its order from frame to frame). A bucket of more than
+ * ${WATER_PARTICLE_RANK_LIMIT} keeps its arrival order: a fixed budget of comparisons per entry.
+ */
+export const shader_water_particles_rank = ComputeShader.from({ label: 'Water / particles rank', resources: rank_resources,
+    body: CodeChunk.from(/* language=WGSL */ `
+fn water_entry_before(a: ${WATER_PARTICLE_ENTRY_STRUCT.wgsl_ref}, b: ${WATER_PARTICLE_ENTRY_STRUCT.wgsl_ref}) -> bool {
+    if (a.source != b.source) { return a.source < b.source; }
+    if (a.cell.x != b.cell.x) { return a.cell.x < b.cell.x; }
+    return a.cell.y < b.cell.y;
+}
+
+@compute @workgroup_size(64)
+fn main(@builtin(workgroup_id) group: vec3u, @builtin(local_invocation_index) lane: u32) {
+    let i = folded_workgroup_index(group) * 64u + lane;
+    if (i >= next.count) { return; }
+    let particle = next.elements[i];
+    let cells = water_particle_cells(particle, i);
+    for (var corner = 0u; corner < ${WATER_PARTICLE_CORNERS}u; corner++) {
+        let slot = slots[i * ${WATER_PARTICLE_CORNERS}u + corner];
+        if (slot == ~0u) { continue; }
+        let bucket = water_particle_bucket(particle.body, cells.level, water_particle_corner_cell(cells, corner), offsets.count);
+        var start = 0u;
+        if (bucket > 0u) { start = offsets.elements[bucket - 1u]; }
+        let end = offsets.elements[bucket];
+        let entry = staging[start + slot];
+        var rank = slot;
+        if (end - start <= ${WATER_PARTICLE_RANK_LIMIT}u) {
+            rank = 0u;
+            for (var j = start; j < end; j++) { rank += select(0u, 1u, water_entry_before(staging[j], entry)); }
+        }
+        entries[start + rank] = entry;
+    }
+}
+`, [chunk_water_particle_cells, chunk_folded_workgroup_index]) });
+
+const bounds_resources = new ShaderResourceSetDescriptor();
+bounds_resources.createGroup()
+    .addStorageBuffer('next', WATER_PARTICLE_ARRAY_STRUCT)
+    .addStorageBuffer('activity', WebGPUArray.u32)
+    .addStorageBuffer('offsets', COLLECTION_U32_STRUCT_READ)
+    .addStorageBuffer('bucket_amplitude', WebGPUArray.u32)
+    .addStorageBuffer('body_bounds', WebGPUArray.from(atomic_u32), true);
+
+/**
+ * Each body's bound per level: the largest of count × max |a| over the buckets its particles are in, which is
+ * at least the bucket's Σ|a|. Every particle that reaches a point is in that point's cell's bucket, and neither
+ * its height nor its horizontal displacement exceeds |a|, so the bound holds everywhere; a hash collision only
+ * adds to it.
+ */
+export const shader_water_particles_bounds = ComputeShader.from({ label: 'Water / particles bounds', resources: bounds_resources,
+    body: CodeChunk.from(/* language=WGSL */ `
+@compute @workgroup_size(64)
+fn main(@builtin(workgroup_id) group: vec3u, @builtin(local_invocation_index) lane: u32) {
+    let i = folded_workgroup_index(group) * 64u + lane;
+    if (i >= next.count) { return; }
+    let particle = next.elements[i];
+    // a paused body keeps the bounds its particles last had
+    if ((activity[particle.body] & ${WaterActivity.Active}u) == 0u) { return; }
+    let cells = water_particle_cells(particle, i);
+    var largest = 0.0;
+    for (var corner = 0u; corner < ${WATER_PARTICLE_CORNERS}u; corner++) {
+        if (!water_particle_has_corner(cells, corner)) { continue; }
+        let bucket = water_particle_bucket(particle.body, cells.level, water_particle_corner_cell(cells, corner), offsets.count);
+        var start = 0u;
+        if (bucket > 0u) { start = offsets.elements[bucket - 1u]; }
+        largest = max(largest, f32(offsets.elements[bucket] - start) * bitcast<f32>(bucket_amplitude[bucket]));
+    }
+    // non-negative floats order as their bits do
+    atomicMax(&body_bounds[particle.body * ${STRIDE}u + 1u + cells.level], bitcast<u32>(largest));
+}
+`, [chunk_water_particle_cells, chunk_folded_workgroup_index]) });

package/src/shade/renderer/water/surface/shader_water_cull.d.ts

@@ -0,0 +1,42 @@
+/** Workgroup size of the culling pass and of the passes over its lists. */
+export const WATER_CULL_WORKGROUP_SIZE: 64;
+/** Bits of a wave row's activity word. */
+export const WaterActivity: Readonly<{
+    /** Its displaced surface may meet the frame's view. */
+    Visible: 1;
+    /** It is simulated this frame: visible, or simulated while hidden. */
+    Active: 2;
+}>;
+/** What the culling pass is told about the frame. */
+export const WATER_CULL_STRUCT: WebGPUStruct;
+/** A list the culling pass appends rows to. */
+export const WATER_LIST_APPEND_STRUCT: WebGPUStruct;
+/** Bytes of a list's header: its count, padded to its elements' alignment. */
+export const WATER_LIST_HEADER_BYTES: 16;
+/**
+ * The frame's culling pass (WATER_SURFACE_DISTANCE_LOD_PROPOSAL_2026_10_06.md §3.1), one thread a water body, before
+ * anything simulates. Against the frustum of the view the frame is recorded for, with a prior bound on the body's
+ * displacement, it decides whether the body is visible and whether it is simulated this frame, and lists it for the
+ * passes that follow. On the way it does the per-body work that used to be passes of its own over every row: weights
+ * when the wind or the fetch changed, the wind's turn for a body that is simulated, optics when they were edited.
+ * A visible body ORs the bands it can draw into the frame's band mask.
+ */
+export const shader_water_cull: ComputeShader;
+/** Commands the finalize pass writes, in order, 16 bytes apart. */
+export const WaterSurfaceCommand: Readonly<{
+    SpectrumRows: 0;
+    SpectrumColumns: 1;
+    Active: 2;
+    Emit: 3;
+}>;
+export const WATER_SURFACE_COMMAND_STRIDE: 16;
+export const WATER_SURFACE_COMMAND_COUNT: 4;
+/**
+ * After the culling pass: which bands this frame's spectrum evaluates — those the visible bodies can draw that do not
+ * already hold this time (all of them once, when a device's envelopes are seeded) — and the indirect commands for the
+ * spectrum and for the passes over the active and emit lists. Commands sit 16 bytes apart.
+ */
+export const shader_water_cull_finalize: ComputeShader;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_water_cull.d.ts.map

package/src/shade/renderer/water/surface/shader_water_cull.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_water_cull.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/water/surface/shader_water_cull.js"],"names":[],"mappings":"AAoCA,2EAA2E;AAC3E,2CAA4C;AAE5C,0CAA0C;AAC1C;IACI,uDAAuD;;IAEvD,sEAAsE;;GAEvE;AAEH,qDAAqD;AACrD,6CAOuB;AAEvB,+CAA+C;AAC/C,oDAGE;AAEF,8EAA8E;AAC9E,yCAA0C;AA6C1C;;;;;;;GAOG;AACH,8CAsGiG;AAEjG,mEAAmE;AACnE;;;;;GAKG;AACH,8CAA+C;AAC/C,4CAA6C;AAW7C;;;;GAIG;AACH,uDAuBM;6BA9PuB,mCAAmC;8BAVlC,+BAA+B"}