@woosh/meep-engine 3.41.0 → 3.43.0

package/src/shade/renderer/water/surface/lod/shader_water_lod.js

@@ -0,0 +1,727 @@
+import { CAMERA_UNIFORM_STRUCT } from "../../../camera/CAMERA_UNIFORM_STRUCT.js";
+import { GEOMETRY_METADATA_STRUCT } from "../../../geometry/GEOMETRY_METADATA_STRUCT.js";
+import { GEOMETRY_MESHLET_TRIANGLE_LIMIT } from "../../../geometry/meshlet/GEOMETRY_MESHLET_TRIANGLE_LIMIT.js";
+import { MESHLET_METADATA_STRUCT } from "../../../geometry/meshlet/encoding/MESHLET_METADATA_STRUCT.js";
+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 { MESHLET_COLLECTION_STRUCT } from "../../../rasterize/MESHLET_COLLECTION_STRUCT.js";
+import { chunk_scene_database_access } from "../../../scene/chunk_scene_database_access.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { chunk_aabb3_intersects_frustum } from "../../../shader/chunk/geometry/aabb3/chunk_aabb3_intersects_frustum.js";
+import { chunk_aabb3_project } from "../../../shader/chunk/geometry/aabb3/chunk_aabb3_project.js";
+import { chunk_array_to_aabb3 } from "../../../shader/chunk/geometry/aabb3/chunk_array_to_aabb3.js";
+import { chunk_mat3_inverse } from "../../../shader/chunk/geometry/mat3/chunk_mat3_inverse.js";
+import { chunk_mat4_linear_determinant } from "../../../shader/chunk/geometry/mat4/chunk_mat4_linear_determinant.js";
+import { chunk_read_meshlet_vertex_by_draw_index } from "../../../shader/chunk/geometry/meshlet/chunk_read_meshlet_vertex_by_draw_index.js";
+import { chunk_folded_workgroup_index } from "../../../shader/chunk/grid/chunk_folded_workgroup_index.js";
+import { chunk_lower_bound_branchless } from "../../../shader/chunk/math/chunk_lower_bound_branchless.js";
+import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { atomic_u32, f32, u32, vec2i } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { WATER_BODIES_TABLE, WATER_WAVES_TABLE } from "../../medium/chunk_water_bodies.js";
+import { chunk_water_particle } from "../particles/chunk_water_particle.js";
+import { chunk_water_spectrum } from "../spectrum/chunk_water_spectrum.js";
+import { chunk_water_lod_cell } from "./chunk_water_lod_cell.js";
+import { WATER_LOD_BODY_STRUCT, WATER_LOD_VIEW_STRUCT, WaterLodMode } from "./WATER_LOD.js";
+
+/** Vertices a cell of each list draws: an interior cell's quad, a boundary cell's clipped polygon fan, a triangle. */
+export const WATER_LOD_INTERIOR_VERTICES = 6;
+export const WATER_LOD_BOUNDARY_VERTICES = 15;
+export const WATER_LOD_TRIANGLE_VERTICES = 3;
+/** First vertex of each list's draw: the vertex stage tells the lists apart by it. */
+export const WATER_LOD_BOUNDARY_FIRST_VERTEX = 16;
+export const WATER_LOD_TRIANGLE_FIRST_VERTEX = 32;
+/** A patch's base vertex: its indices name its 9 × 9 lattice points from here. */
+export const WATER_LOD_PATCH_FIRST_VERTEX = 64;
+/** Lattice points along a patch's side: a quadrant's 8 cells and their far edge. */
+export const WATER_LOD_PATCH_SIDE = 9;
+
+/**
+ * A quadrant inside its triangle drawn as one indexed patch: its 64 cells as two triangles each, row by row, over its
+ * 9 × 9 lattice points, so the vertex stage runs about once a point rather than six times a cell. Each cell turns as
+ * an interior cell's quad does, its diagonal from its first corner to its third.
+ */
+export const WATER_LOD_PATCH_INDICES = (() => {
+    const side = WATER_LOD_PATCH_SIDE, out = new Uint16Array((side - 1) * (side - 1) * 6);
+    let at = 0;
+    for (let z = 0; z + 1 < side; z++) for (let x = 0; x + 1 < side; x++) {
+        const a = z * side + x, b = a + 1, c = a + side + 1, d = a + side;
+        out.set([a, b, c, a, c, d], at);
+        at += 6;
+    }
+    return out;
+})();
+
+/** Bits of a cell record that hold the cell's place in its candidate's node: quadrant · 64 + row · 8 + column. */
+export const WATER_LOD_CELL_LOCAL_BITS = 8;
+/** Most candidates a frame can hold: the rest of a cell record's bits. */
+export const WATER_LOD_CANDIDATE_LIMIT = 2 ** (32 - WATER_LOD_CELL_LOCAL_BITS);
+
+/** Words a boundary cell's clipped polygon is kept in, beside its record: see water_lod_polygon_pack. */
+export const WATER_LOD_POLYGON_WORDS = 2;
+
+/** Cell lists, in the order their scans, budgets and draws are kept. */
+export const WaterLodList = Object.freeze({ Interior: 0, Boundary: 1, Triangle: 2, Patch: 3 });
+
+/**
+ * One (authored triangle, lattice node) pair the frame considered.
+ * `packed`: bits 0–6 the triangle in its meshlet, bits 8–12 the level,
+ * 16–19 the quadrants drawn, 20–23 those of them inside the triangle.
+ */
+export const WATER_LOD_CANDIDATE_STRUCT = WebGPUStruct.from({
+    meshlet: u32, body: u32, packed: u32, reserved: u32, node: vec2i,
+}, 'WaterLodCandidate');
+
+/**
+ * Budgets a frame's lists are cut to, and so where each list's records start in the cell buffer: interior cells,
+ * boundary cells, triangles drawn as themselves (two words each), patches, then the boundary cells' polygons
+ * ({@link WATER_LOD_POLYGON_WORDS} each).
+ */
+export const WATER_LOD_LIMITS_STRUCT = WebGPUStruct.from({
+    candidates: u32, interior: u32, boundary: u32, triangles: u32, patches: u32,
+}, 'WaterLodLimits').pack();
+
+/**
+ * Words of the per-view statistics, totals before budgets: candidates, interior cells, boundary cells, flat triangles,
+ * patches.
+ */
+export const WATER_LOD_STATISTICS_WORDS = 5;
+
+/**
+ * The cell lists' counts, kept as one collection and scanned once: for the frame's n candidates, the interior counts,
+ * then the boundary counts, then the patch counts. A list's sums are its region of the scan less what came before it.
+ */
+const chunk_water_lod_list_sums = CodeChunk.from(/* language=WGSL */ `
+// A list's region of the counts: interior 0, boundary 1, patches 2.
+fn water_lod_list_region(list: u32) -> u32 { return select(list, 2u, list == ${WaterLodList.Patch}u); }
+
+// The sum before a region's first element, and the region's total.
+fn water_lod_list_span(sums: ptr<storage, array<u32>, read>, count: u32, region: u32) -> vec2<u32> {
+    let n = count / 3u;
+    if (n == 0u) { return vec2<u32>(0u); }
+    let before = select(0u, sums[region * n - 1u], region > 0u);
+    return vec2<u32>(before, sums[(region + 1u) * n - 1u] - before);
+}
+`);
+
+const chunk_water_lod_layout = CodeChunk.from(/* language=WGSL */ `
+fn water_lod_triangles_base(limits: ${WATER_LOD_LIMITS_STRUCT.wgsl_ref}) -> u32 { return limits.interior + limits.boundary; }
+fn water_lod_patches_base(limits: ${WATER_LOD_LIMITS_STRUCT.wgsl_ref}) -> u32 { return water_lod_triangles_base(limits) + 2u * limits.triangles; }
+fn water_lod_polygons_base(limits: ${WATER_LOD_LIMITS_STRUCT.wgsl_ref}) -> u32 { return water_lod_patches_base(limits) + limits.patches; }
+`, [WATER_LOD_LIMITS_STRUCT.declaration_chunk]);
+export { chunk_water_lod_layout };
+
+const chunk_water_lod_candidate = CodeChunk.from(/* language=WGSL */ `
+fn water_lod_candidate_triangle(packed: u32) -> u32 { return packed & 127u; }
+fn water_lod_candidate_level(packed: u32) -> u32 { return (packed >> 8u) & 31u; }
+fn water_lod_candidate_drawn(packed: u32) -> u32 { return (packed >> 16u) & 15u; }
+fn water_lod_candidate_interior(packed: u32) -> u32 { return (packed >> 20u) & 15u; }
+
+// The square of nodes of a level that overlap the triangle's bounds and reach into the level's range. (xy: first
+// node, zw: nodes along x and z.) The two are intersected as node ranges, not as boxes: a node can overlap the
+// bounds at one side and come within range at the other while the bounds themselves stop short of the range. The
+// reach is taken a little long — a thousandth of a node and a few rounding steps of the camera's place — so that a
+// node whose edge lies at it, which water_lod_node_exists keeps, is never cut here; every candidate passes through
+// that test, which decides.
+fn water_lod_node_rect(view: ${WATER_LOD_VIEW_STRUCT.wgsl_ref}, body: ${WATER_LOD_BODY_STRUCT.wgsl_ref}, level: u32,
+    lo: vec2<f32>, hi: vec2<f32>) -> vec4<i32> {
+    let size = water_lod_cell(level) * f32(WATER_LOD_NODE_CELLS);
+    var first = vec2<i32>(floor(lo / size));
+    var last = vec2<i32>(floor(hi / size));
+    if (view.orthographic == 0u && level < WATER_LOD_COARSEST) {
+        let range = water_lod_range(view, level);
+        if (range < body.vertical) { return vec4<i32>(0); }
+        let slack = 1e-3 * size + 2.4e-7 * max(abs(body.camera.x), abs(body.camera.z));
+        let reach = sqrt(range * range - body.vertical * body.vertical) + slack;
+        first = max(first, vec2<i32>(floor((body.camera.xz - vec2<f32>(reach)) / size)));
+        last = min(last, vec2<i32>(floor((body.camera.xz + vec2<f32>(reach)) / size)));
+    }
+    return vec4<i32>(first, max(last - first + vec2<i32>(1), vec2<i32>(0)));
+}
+
+// The triangle's x-interval on the line of constant z in metric xz; (1e30, -1e30) when it misses it.
+fn water_lod_line(tri: WaterLodTriangle, z: f32) -> vec2<f32> {
+    var span = vec2<f32>(1e30, -1e30);
+    for (var e = 0u; e < 3u; e++) {
+        let p = tri.p[e];
+        let q = tri.p[(e + 1u) % 3u];
+        if ((p.y - z) * (q.y - z) > 0.0) { continue; }
+        if (p.y == q.y) { span = vec2<f32>(min(span.x, min(p.x, q.x)), max(span.y, max(p.x, q.x))); continue; }
+        let x = mix(p.x, q.x, (z - p.y) / (q.y - p.y));
+        span = vec2<f32>(min(span.x, x), max(span.y, x));
+    }
+    return span;
+}
+
+// One row of a quadrant cut by a triangle, in absolute lattice columns: the columns whose morphed cells can meet the
+// triangle (x … y), and of those the run lying wholly inside it (z … w, empty as w = z − 1). A morph slides a cell's odd
+// corners down by up to morph cells, the most any point of the quadrant takes, so each cell is taken as its own
+// square grown that far down in x and z: its row as the strip from morph below it to its top. A cell meets the
+// triangle when such a box overlaps the triangle's span over the strip; the triangle is convex, so the box is inside it
+// exactly when its span lies inside the triangle's span on both of the strip's edge lines, taken a thousandth of a
+// cell inwards so that rounding can only send a cell to the clipper, never past it. Where nothing morphs the boxes are
+// the cells themselves, and only cells an authored edge cuts go to the clipper.
+fn water_lod_row_runs(tri: WaterLodTriangle, level: u32, node: vec2<i32>, quadrant: u32, row: u32, morph: f32) -> vec4<i32> {
+    let origin = water_lod_quadrant_origin(node, quadrant);
+    let cell = water_lod_cell(level);
+    let z = origin.y + i32(row);
+    let za = (f32(z) - morph) * cell;
+    let zb = f32(z + 1) * cell;
+    let bottom = water_lod_line(tri, za);
+    let top = water_lod_line(tri, zb);
+    var span = vec2<f32>(min(bottom.x, top.x), max(bottom.y, top.y));
+    for (var k = 0u; k < 3u; k++) {
+        let p = tri.p[k];
+        if (p.y >= za && p.y <= zb) { span = vec2<f32>(min(span.x, p.x), max(span.y, p.x)); }
+    }
+    if (span.x > span.y) { return vec4<i32>(origin.x, origin.x - 1, origin.x, origin.x - 1); }
+    let a = max(origin.x, i32(floor(span.x / cell)));
+    let b = min(origin.x + WATER_LOD_QUADRANT_CELLS - 1, i32(ceil(span.y / cell + morph)) - 1);
+    if (a > b) { return vec4<i32>(a, a - 1, a, a - 1); }
+    let margin = 1e-3 * cell;
+    let inner = vec2<f32>(max(bottom.x, top.x) + margin, min(bottom.y, top.y) - margin);
+    let c = max(a, i32(ceil(inner.x / cell + morph)));
+    let d = min(b, i32(floor(inner.y / cell)) - 1);
+    if (c > d) { return vec4<i32>(a, b, b + 1, b); }
+    return vec4<i32>(a, b, c, d);
+}
+
+// A list's cells of a quadrant cut by a triangle, by row: (interior, boundary) counts of one row.
+fn water_lod_row_counts(runs: vec4<i32>) -> vec2<u32> {
+    let interior = max(runs.w - runs.z + 1, 0);
+    let overlap = max(runs.y - runs.x + 1, 0);
+    return vec2<u32>(u32(interior), u32(overlap - interior));
+}
+
+fn water_lod_triangle_lo(tri: WaterLodTriangle) -> vec2<f32> { return min(min(tri.p[0], tri.p[1]), tri.p[2]); }
+fn water_lod_triangle_hi(tri: WaterLodTriangle) -> vec2<f32> { return max(max(tri.p[0], tri.p[1]), tri.p[2]); }
+
+fn water_lod_triangle_levels(view: ${WATER_LOD_VIEW_STRUCT.wgsl_ref}, body: ${WATER_LOD_BODY_STRUCT.wgsl_ref}, tri: WaterLodTriangle) -> vec2<u32> {
+    let lo = water_lod_triangle_lo(tri);
+    let hi = water_lod_triangle_hi(tri);
+    return water_lod_level_span(view, water_lod_nearest(view, body, lo, hi), water_lod_farthest(view, body, lo, hi));
+}
+
+// A triangle too steep to cut from the horizontal lattice: more than 75° from the body's metric up.
+fn water_lod_steep(a: vec3<f32>, b: vec3<f32>, c: vec3<f32>, scale: vec3<f32>) -> bool {
+    let face = cross((b - a) * scale, (c - a) * scale);
+    return abs(face.y) < 0.25881905 * length(face);
+}
+`, [chunk_water_lod_cell, WATER_LOD_VIEW_STRUCT.declaration_chunk, WATER_LOD_BODY_STRUCT.declaration_chunk]);
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+const bodies_resources = new ShaderResourceSetDescriptor();
+bodies_resources.setImmediate('capacity', u32);
+bodies_resources.createGroup()
+    .addUniform('lod', WATER_LOD_VIEW_STRUCT)
+    .addUniform('camera', CAMERA_UNIFORM_STRUCT)
+    .addStorageBuffer('scene_database', WebGPUArray.u32)
+    .addStorageBuffer('geometries', WebGPUArray.from(GEOMETRY_METADATA_STRUCT))
+    .addStorageBuffer('visible_rows', COLLECTION_U32_STRUCT_READ)
+    .addStorageBuffer('steep', WebGPUArray.u32, true)
+    .addStorageBuffer('lod_bodies', WebGPUArray.from(WATER_LOD_BODY_STRUCT), true)
+    .addStorageBuffer('counts', COLLECTION_U32_STRUCT_READ, true);
+
+/**
+ * The view's draw culling (WATER_SURFACE_DISTANCE_LOD_PROPOSAL_2026_10_06.md §4.3), one thread a body of the culling
+ * pass's visible list: against the view with the body's exact bounds, and for a body drawn, how this view sees it —
+ * the camera in its metric local frame and whether it is cut from the lattice or drawn as its authored triangles —
+ * and its meshlet count at its row, for an ordered expansion. A drawn body's steep flag starts again: its triangles
+ * set it.
+ */
+export const shader_water_lod_bodies = ComputeShader.from({ label: 'Water / lod bodies', resources: bodies_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 == 0u) { counts.count = capacity; }
+    if (index >= visible_rows.count) { return; }
+    let row = visible_rows.elements[index];
+    let body = ${WATER_BODIES_TABLE.marshalling_method_read}(&scene_database, row);
+    var frame: ${WATER_LOD_BODY_STRUCT.wgsl_ref};
+    frame.mode = ${WaterLodMode.Hidden}u;
+    let global = scene_read_node(&scene_database, body.node).global;
+    if (abs(mat4_linear_determinant(global)) < 1e-20) { lod_bodies[row] = frame; return; }
+    let geometry = geometries[body.geometry];
+    let box = geometry.bounding_box;
+    let displacement = ${WATER_WAVES_TABLE.marshalling_method_read_field('displacement_bounds')}(&scene_database, body.wave);
+    var grown = box;
+    grown[1] += displacement.x; grown[4] += displacement.y;
+    grown[0] -= displacement.z; grown[2] -= displacement.z; grown[3] += displacement.z; grown[5] += displacement.z;
+    if (!aabb3_intersects_frustum(aabb3_project(array_to_aabb3(grown), global), camera.frustum)) { lod_bodies[row] = frame; return; }
+
+    let scale = max(vec3<f32>(length(global[0].xyz), length(global[1].xyz), length(global[2].xyz)), vec3<f32>(1e-20));
+    let linear = mat3x3<f32>(global[0].xyz, global[1].xyz, global[2].xyz);
+    let eye = camera.view_matrix_inverse[3].xyz;
+    let local = mat3_inverse(linear) * (eye - global[3].xyz);
+    frame.camera = local * scale;
+    frame.scale = scale;
+    let rest = vec2<f32>(box[1], box[4]) * scale.y;
+    frame.vertical = max(max(frame.camera.y - rest.y, rest.x - frame.camera.y), 0.0);
+    frame.bounds = vec2<f32>(displacement.y, displacement.z);
+    frame.rest = vec2<f32>(box[1], box[4]);
+    // cut from the lattice when something it displaces by can be drawn at its nearest: a band long enough, or a
+    // particle level whose packets can be
+    var lattice = false;
+    if (any(displacement.xyz != vec3<f32>(0.0))) {
+        let nearest = water_lod_nearest(lod, frame, vec2<f32>(box[0], box[2]) * scale.xz, vec2<f32>(box[3], box[5]) * scale.xz);
+        let finest = water_lod_footprint_min(lod, nearest);
+        let weights = ${WATER_WAVES_TABLE.marshalling_method_read_field('weights')}(&scene_database, body.wave);
+        for (var band = 0u; band < WATER_SPECTRUM_BANDS; band++) {
+            lattice = lattice || (weights[band] > 0.0 && water_band_wavelength(band) > 8.0 * finest);
+        }
+        let levels = ${WATER_WAVES_TABLE.marshalling_method_read_field('particle_levels')}(&scene_database, body.wave);
+        for (var level = 0u; level < WATER_PARTICLE_LEVELS; level++) {
+            lattice = lattice || ((levels & (1u << level)) != 0u && water_particle_cell_size(level) > 4.0 * finest);
+        }
+    }
+    frame.mode = select(${WaterLodMode.Flat}u, ${WaterLodMode.Lattice}u, lattice);
+    lod_bodies[row] = frame;
+    steep[body.wave] = 0u;
+    counts.elements[row] = geometry.meshlets_count;
+}
+`, [WATER_BODIES_TABLE.chunk_read, WATER_WAVES_TABLE.chunk_read_field('displacement_bounds'),
+        WATER_WAVES_TABLE.chunk_read_field('weights'), WATER_WAVES_TABLE.chunk_read_field('particle_levels'),
+        chunk_water_lod_candidate, chunk_water_spectrum, chunk_water_particle, chunk_scene_database_access,
+        chunk_mat4_linear_determinant, chunk_mat3_inverse, chunk_aabb3_project, chunk_array_to_aabb3,
+        chunk_aabb3_intersects_frustum, chunk_folded_workgroup_index]) });
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+/** Reads a drawn triangle of the view's meshlet list: its body, its frame and its corners. */
+const chunk_water_lod_source = CodeChunk.from(/* language=WGSL */ `
+struct WaterLodSource {
+    meshlet: u32,
+    triangle: u32,
+    body_row: u32,
+    wave: u32,
+    node: u32,
+    frame: ${WATER_LOD_BODY_STRUCT.wgsl_ref},
+    a: vec3<f32>, b: vec3<f32>, c: vec3<f32>,
+    na: vec3<f32>, nb: vec3<f32>, nc: vec3<f32>,
+    present: bool,
+}
+
+fn water_lod_source(slot: u32) -> WaterLodSource {
+    var source: WaterLodSource;
+    let meshlet_slot = slot / ${GEOMETRY_MESHLET_TRIANGLE_LIMIT}u;
+    source.triangle = slot % ${GEOMETRY_MESHLET_TRIANGLE_LIMIT}u;
+    if (meshlet_slot >= water_meshlets.count) { return source; }
+    let definition = water_meshlets.elements[meshlet_slot];
+    let header = meshlet_metadata[definition.index];
+    source.meshlet = definition.index;
+    source.body_row = definition.mesh;
+    source.present = source.triangle < header.primitive_count;
+    if (!source.present) { return source; }
+    let body = ${WATER_BODIES_TABLE.marshalling_method_read}(&scene_database, definition.mesh);
+    source.wave = body.wave;
+    source.node = body.node;
+    source.frame = lod_bodies[definition.mesh];
+    let a = read_meshlet_vertex_by_draw_index(header, source.triangle * 3u);
+    let b = read_meshlet_vertex_by_draw_index(header, source.triangle * 3u + 1u);
+    let c = read_meshlet_vertex_by_draw_index(header, source.triangle * 3u + 2u);
+    source.a = a.position; source.b = b.position; source.c = c.position;
+    source.na = a.normal; source.nb = b.normal; source.nc = c.normal;
+    return source;
+}
+`, [WATER_LOD_BODY_STRUCT.declaration_chunk, WATER_BODIES_TABLE.chunk_read, chunk_read_meshlet_vertex_by_draw_index]);
+
+const triangles_resources = new ShaderResourceSetDescriptor();
+triangles_resources.createGroup()
+    .addUniform('lod', WATER_LOD_VIEW_STRUCT)
+    .addStorageBuffer('scene_database', WebGPUArray.u32)
+    .addStorageBuffer('water_meshlets', MESHLET_COLLECTION_STRUCT)
+    .addStorageBuffer('meshlet_metadata', WebGPUArray.from(MESHLET_METADATA_STRUCT))
+    .addStorageBuffer('meshlet_data', WebGPUArray.from(f32))
+    .addStorageBuffer('lod_bodies', WebGPUArray.from(WATER_LOD_BODY_STRUCT))
+    .addStorageBuffer('steep', WebGPUArray.from(atomic_u32), true)
+    .addStorageBuffer('counts', COLLECTION_U32_STRUCT_READ, true)
+    .addStorageBuffer('flats', COLLECTION_U32_STRUCT_READ, true);
+
+/**
+ * One workgroup a drawn meshlet, one thread a triangle slot: whether the triangle is drawn as itself — its body is flat
+ * in this view, or it is too steep for the lattice, which also marks its body steep so the next frame keeps it calm —
+ * and otherwise how many candidates it makes: the nodes of each level of its distance range that its bounds overlap
+ * within reach of the level's range.
+ */
+export const shader_water_lod_triangles = ComputeShader.from({ label: 'Water / lod triangles', resources: triangles_resources,
+    body: CodeChunk.from(/* language=WGSL */ `
+@compute @workgroup_size(${GEOMETRY_MESHLET_TRIANGLE_LIMIT})
+fn main(@builtin(workgroup_id) group: vec3u, @builtin(local_invocation_index) lane: u32) {
+    let meshlet_slot = folded_workgroup_index(group);
+    if (meshlet_slot == 0u && lane == 0u) {
+        counts.count = water_meshlets.count * ${GEOMETRY_MESHLET_TRIANGLE_LIMIT}u;
+        flats.count = counts.count;
+    }
+    if (meshlet_slot >= water_meshlets.count) { return; }
+    let slot = meshlet_slot * ${GEOMETRY_MESHLET_TRIANGLE_LIMIT}u + lane;
+    let source = water_lod_source(slot);
+    var candidates = 0u;
+    var flat = 0u;
+    if (source.present) {
+        let steep_triangle = water_lod_steep(source.a, source.b, source.c, source.frame.scale);
+        if (steep_triangle) { atomicOr(&steep[source.wave], 1u); }
+        if (steep_triangle || source.frame.mode != ${WaterLodMode.Lattice}u) {
+            flat = 1u;
+        } else {
+            let tri = water_lod_triangle(source.a, source.b, source.c, source.na, source.nb, source.nc, source.frame.scale);
+            let lo = water_lod_triangle_lo(tri);
+            let hi = water_lod_triangle_hi(tri);
+            let levels = water_lod_triangle_levels(lod, source.frame, tri);
+            // a triangle with no area draws nothing
+            for (var level = levels.x; level <= levels.y && !water_lod_no_area(tri); level++) {
+                let rect = water_lod_node_rect(lod, source.frame, level, lo, hi);
+                candidates += u32(rect.z * rect.w);
+            }
+        }
+    }
+    counts.elements[slot] = candidates;
+    flats.elements[slot] = flat;
+}
+`, [chunk_water_lod_source, chunk_water_lod_candidate, chunk_scene_database_access, chunk_folded_workgroup_index]) });
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+const flats_resources = new ShaderResourceSetDescriptor();
+flats_resources.setImmediate('limits', WebGPUStruct.from({ base: u32, budget: u32 }, 'WaterLodFlatLimits'));
+flats_resources.createGroup()
+    .addStorageBuffer('water_meshlets', MESHLET_COLLECTION_STRUCT)
+    .addStorageBuffer('flat_sums', COLLECTION_U32_STRUCT_READ)
+    .addStorageBuffer('cells', WebGPUArray.u32, true);
+
+/**
+ * One thread a triangle drawn as itself, up to its list's budget: its record, two words at the list's base in the cell
+ * buffer — its meshlet, and its body row and triangle — in the triangles' order.
+ */
+export const shader_water_lod_flats = ComputeShader.from({ label: 'Water / lod flats', resources: flats_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;
+    let total = select(0u, flat_sums.elements[max(flat_sums.count, 1u) - 1u], flat_sums.count > 0u);
+    if (index >= min(total, limits.budget)) { return; }
+    let slot = lower_bound_branchless(&flat_sums.elements, index + 1u, flat_sums.count);
+    let definition = water_meshlets.elements[slot / ${GEOMETRY_MESHLET_TRIANGLE_LIMIT}u];
+    cells[limits.base + 2u * index] = definition.index;
+    cells[limits.base + 2u * index + 1u] = (definition.mesh << 7u) | (slot % ${GEOMETRY_MESHLET_TRIANGLE_LIMIT}u);
+}
+`, [chunk_lower_bound_branchless, chunk_folded_workgroup_index]) });
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+/** Words of a candidate's row record: 32 rows (4 quadrants × 8), 16 bits each. */
+export const WATER_LOD_CANDIDATE_ROW_WORDS = 16;
+
+const candidates_resources = new ShaderResourceSetDescriptor();
+candidates_resources.createGroup()
+    .addUniform('lod', WATER_LOD_VIEW_STRUCT)
+    .addUniform('limits', WATER_LOD_LIMITS_STRUCT)
+    .addUniform('camera', CAMERA_UNIFORM_STRUCT)
+    .addStorageBuffer('scene_database', WebGPUArray.u32)
+    .addStorageBuffer('water_meshlets', MESHLET_COLLECTION_STRUCT)
+    .addStorageBuffer('meshlet_metadata', WebGPUArray.from(MESHLET_METADATA_STRUCT))
+    .addStorageBuffer('meshlet_data', WebGPUArray.from(f32))
+    .addStorageBuffer('lod_bodies', WebGPUArray.from(WATER_LOD_BODY_STRUCT))
+    .addStorageBuffer('triangle_sums', COLLECTION_U32_STRUCT_READ)
+    .addStorageBuffer('candidates', WebGPUArray.from(WATER_LOD_CANDIDATE_STRUCT), true)
+    .addStorageBuffer('candidate_rows', WebGPUArray.u32, true)
+    .addStorageBuffer('cell_counts', COLLECTION_U32_STRUCT_READ, true);
+
+/**
+ * One thread a candidate, up to the frame's budget: which of its node's quadrants the selection rule draws at its
+ * level, that meet the view and the triangle, which of those lie inside the triangle, and so how many patches, interior
+ * cells and boundary cells it draws. A quadrant inside the triangle is a patch. One the triangle only partly covers is
+ * taken row by row — the cells that can meet the triangle, of which the run wholly inside it is interior — and each
+ * row's runs are kept for the cells pass, 16 bits a row: first column, then the counts of the left boundary run, the
+ * inside run and the right boundary run. Its three counts go to their regions of the one collection the lists share.
+ */
+export const shader_water_lod_candidates = ComputeShader.from({ label: 'Water / lod candidates', resources: candidates_resources,
+    body: CodeChunk.from(/* language=WGSL */ `
+fn water_lod_row_word(runs: vec4<i32>, origin: i32) -> u32 {
+    let left = u32(max(runs.z - runs.x, 0));
+    let inside = u32(max(runs.w - runs.z + 1, 0));
+    let right = u32(max(runs.y - runs.w, 0));
+    return u32(clamp(runs.x - origin, 0, 7)) | (left << 3u) | (inside << 7u) | (right << 11u);
+}
+
+@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;
+    let total = select(0u, triangle_sums.elements[max(triangle_sums.count, 1u) - 1u], triangle_sums.count > 0u);
+    let count = min(total, limits.candidates);
+    if (index == 0u) { cell_counts.count = 3u * count; }
+    if (index >= count) { return; }
+    let slot = lower_bound_branchless(&triangle_sums.elements, index + 1u, triangle_sums.count);
+    var local = index;
+    if (slot > 0u) { local = index - triangle_sums.elements[slot - 1u]; }
+    let source = water_lod_source(slot);
+    let frame = source.frame;
+    var candidate: ${WATER_LOD_CANDIDATE_STRUCT.wgsl_ref};
+    candidate.meshlet = source.meshlet;
+    candidate.body = source.body_row;
+    candidate.packed = source.triangle;
+    let tri = water_lod_triangle(source.a, source.b, source.c, source.na, source.nb, source.nc, frame.scale);
+    let lo = water_lod_triangle_lo(tri);
+    let hi = water_lod_triangle_hi(tri);
+    let levels = water_lod_triangle_levels(lod, frame, tri);
+    var level = levels.x;
+    var rect = vec4<i32>(0);
+    for (; level <= levels.y; level++) {
+        rect = water_lod_node_rect(lod, frame, level, lo, hi);
+        let area = u32(rect.z * rect.w);
+        if (local < area) { break; }
+        local -= area;
+    }
+    let node = rect.xy + vec2<i32>(i32(local % u32(max(rect.z, 1))), i32(local / u32(max(rect.z, 1))));
+    candidate.node = node;
+    candidate.packed |= level << 8u;
+    var interior = 0u;
+    var boundary = 0u;
+    var patches = 0u;
+    var words: array<u32, ${WATER_LOD_CANDIDATE_ROW_WORDS}>;
+    if (water_lod_node_exists(lod, frame, level, node)) {
+        let global = scene_read_node(&scene_database, source.node).global;
+        let cell = water_lod_cell(level);
+        for (var quadrant = 0u; quadrant < 4u; quadrant++) {
+            let origin = water_lod_quadrant_origin(node, quadrant);
+            let q_lo = vec2<f32>(origin) * cell;
+            let q_hi = vec2<f32>(origin + vec2<i32>(WATER_LOD_QUADRANT_CELLS)) * cell;
+            if (!water_lod_quadrant_drawn(lod, frame, level, node, quadrant) || !water_lod_triangle_meets_square(tri, q_lo, q_hi)) { continue; }
+            // the quadrant's box in local units, grown by the body's bounds
+            let box_lo = vec3<f32>(q_lo.x / frame.scale.x - frame.bounds.y, frame.rest.x - frame.bounds.x, q_lo.y / frame.scale.z - frame.bounds.y);
+            let box_hi = vec3<f32>(q_hi.x / frame.scale.x + frame.bounds.y, frame.rest.y + frame.bounds.x, q_hi.y / frame.scale.z + frame.bounds.y);
+            if (!aabb3_intersects_frustum(aabb3_project(array_to_aabb3(array<f32, 6>(box_lo.x, box_lo.y, box_lo.z, box_hi.x, box_hi.y, box_hi.z)), global),
+                camera.frustum)) { continue; }
+            candidate.packed |= 1u << (16u + quadrant);
+            if (water_lod_triangle_holds_square(tri, q_lo, q_hi)) {
+                candidate.packed |= 1u << (20u + quadrant);
+                patches++;
+                continue;
+            }
+            // the most any point of the quadrant slides: its farthest corner's
+            let morph = water_lod_morph(lod, level, water_lod_farthest(lod, frame, q_lo, q_hi));
+            for (var row = 0u; row < 8u; row++) {
+                let runs = water_lod_row_runs(tri, level, node, quadrant, row, morph);
+                let counts = water_lod_row_counts(runs);
+                interior += counts.x;
+                boundary += counts.y;
+                let at = quadrant * 8u + row;
+                words[at >> 1u] |= water_lod_row_word(runs, origin.x) << (16u * (at & 1u));
+            }
+        }
+    }
+    candidates[index] = candidate;
+    for (var word = 0u; word < ${WATER_LOD_CANDIDATE_ROW_WORDS}u; word++) {
+        candidate_rows[index * ${WATER_LOD_CANDIDATE_ROW_WORDS}u + word] = words[word];
+    }
+    cell_counts.elements[index] = interior;
+    cell_counts.elements[count + index] = boundary;
+    cell_counts.elements[2u * count + index] = patches;
+}
+`, [chunk_water_lod_source, chunk_water_lod_candidate, WATER_LOD_CANDIDATE_STRUCT.declaration_chunk, chunk_scene_database_access,
+        chunk_lower_bound_branchless, chunk_aabb3_project, chunk_array_to_aabb3, chunk_aabb3_intersects_frustum,
+        chunk_folded_workgroup_index]) });
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+const cells_resources = new ShaderResourceSetDescriptor();
+cells_resources.setImmediate('limits', WebGPUStruct.from({ base: u32, budget: u32, list: u32 }, 'WaterLodCellLimits'));
+cells_resources.createGroup()
+    .addUniform('lod', WATER_LOD_VIEW_STRUCT)
+    .addUniform('lod_limits', WATER_LOD_LIMITS_STRUCT)
+    .addStorageBuffer('meshlet_metadata', WebGPUArray.from(MESHLET_METADATA_STRUCT))
+    .addStorageBuffer('meshlet_data', WebGPUArray.from(f32))
+    .addStorageBuffer('lod_bodies', WebGPUArray.from(WATER_LOD_BODY_STRUCT))
+    .addStorageBuffer('sums', COLLECTION_U32_STRUCT_READ)
+    .addStorageBuffer('candidates', WebGPUArray.from(WATER_LOD_CANDIDATE_STRUCT))
+    .addStorageBuffer('candidate_rows', WebGPUArray.u32)
+    .addStorageBuffer('cells', WebGPUArray.u32, true);
+
+/**
+ * One thread a record of the interior, boundary or patch list, up to its budget: its candidate, and its place in the
+ * candidate's node (quadrant · 64 + row · 8 + column; a patch's first cell), at the list's base in the cell buffer,
+ * from the candidate's quadrant masks and row record: a patch for each quadrant inside the triangle in turn, and of
+ * the others, row by row, the inside run or the left and right boundary runs, in the order the candidate pass counted
+ * them. A boundary cell is clipped here, once, and its polygon kept beside the lists for the vertex stage to rebuild
+ * its points from.
+ */
+export const shader_water_lod_cells = ComputeShader.from({ label: 'Water / lod cells', resources: cells_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;
+    let region = water_lod_list_region(limits.list);
+    let span = water_lod_list_span(&sums.elements, sums.count, region);
+    if (index >= min(span.y, limits.budget)) { return; }
+    // the scan rises through every region, so the first sum past this record's lies in the list's own
+    let position = lower_bound_branchless(&sums.elements, span.x + index + 1u, sums.count);
+    let candidate_index = position - region * (sums.count / 3u);
+    var remaining = span.x + index - select(0u, sums.elements[max(position, 1u) - 1u], position > 0u);
+    let candidate = candidates[candidate_index];
+    let packed = candidate.packed;
+    let interior = limits.list == ${WaterLodList.Interior}u;
+    var place = 256u;
+    if (limits.list == ${WaterLodList.Patch}u) {
+        for (var quadrant = 0u; quadrant < 4u; quadrant++) {
+            if ((water_lod_candidate_interior(packed) & (1u << quadrant)) == 0u) { continue; }
+            if (remaining == 0u) { place = quadrant * 64u; break; }
+            remaining--;
+        }
+        cells[limits.base + index] = (candidate_index << ${WATER_LOD_CELL_LOCAL_BITS}u) | min(place, 255u);
+        return;
+    }
+    for (var quadrant = 0u; quadrant < 4u && place == 256u; quadrant++) {
+        let bit = 1u << quadrant;
+        if ((water_lod_candidate_drawn(packed) & bit) == 0u || (water_lod_candidate_interior(packed) & bit) != 0u) { continue; }
+        for (var row = 0u; row < 8u; row++) {
+            let at = quadrant * 8u + row;
+            let word = (candidate_rows[candidate_index * ${WATER_LOD_CANDIDATE_ROW_WORDS}u + (at >> 1u)] >> (16u * (at & 1u))) & 0xffffu;
+            let first = word & 7u;
+            let left = (word >> 3u) & 15u;
+            let inside = (word >> 7u) & 15u;
+            let right = (word >> 11u) & 15u;
+            if (interior) {
+                if (remaining < inside) { place = at * 8u + first + left + remaining; break; }
+                remaining -= inside;
+            } else {
+                if (remaining < left) { place = at * 8u + first + remaining; break; }
+                remaining -= left;
+                if (remaining < right) { place = at * 8u + first + left + inside + remaining; break; }
+                remaining -= right;
+            }
+        }
+    }
+    cells[limits.base + index] = (candidate_index << ${WATER_LOD_CELL_LOCAL_BITS}u) | min(place, 255u);
+    if (interior || place >= 256u) { return; }
+    // the boundary cell clipped once here, rather than by every vertex of its fan in every pass that draws it
+    let frame = lod_bodies[candidate.body];
+    let header = meshlet_metadata[candidate.meshlet];
+    let triangle = water_lod_candidate_triangle(packed);
+    let a = read_meshlet_vertex_by_draw_index(header, triangle * 3u);
+    let b = read_meshlet_vertex_by_draw_index(header, triangle * 3u + 1u);
+    let c = read_meshlet_vertex_by_draw_index(header, triangle * 3u + 2u);
+    let tri = water_lod_triangle(a.position, b.position, c.position, a.normal, b.normal, c.normal, frame.scale);
+    let level = water_lod_candidate_level(packed);
+    let cell = water_lod_quadrant_origin(candidate.node, place >> 6u) + vec2<i32>(i32(place & 7u), i32((place >> 3u) & 7u));
+    let corners = array<vec2<f32>, 4>(
+        water_lod_lattice_point(lod, frame, level, cell),
+        water_lod_lattice_point(lod, frame, level, cell + vec2<i32>(1, 0)),
+        water_lod_lattice_point(lod, frame, level, cell + vec2<i32>(1, 1)),
+        water_lod_lattice_point(lod, frame, level, cell + vec2<i32>(0, 1)));
+    let words = water_lod_polygon_pack(water_lod_cell_clipped(tri, corners));
+    let at = water_lod_polygons_base(lod_limits) + ${WATER_LOD_POLYGON_WORDS}u * index;
+    cells[at] = words.x;
+    cells[at + 1u] = words.y;
+}
+`, [chunk_water_lod_candidate, chunk_water_lod_layout, chunk_water_lod_list_sums, WATER_LOD_CANDIDATE_STRUCT.declaration_chunk, chunk_lower_bound_branchless,
+        chunk_read_meshlet_vertex_by_draw_index, chunk_folded_workgroup_index]) });
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+/** Byte offsets in the command buffer the commands passes write. */
+export const WaterLodCommand = Object.freeze({
+    /** Dispatches of the cells pass: interior, then boundary, 16 bytes apart. */
+    Cells: 0,
+    /** The flat triangles' dispatch. */
+    Flats: 32,
+    /** Draws of the interior, boundary and triangle lists, 16 bytes apart. */
+    Draws: 48,
+    /** The candidate pass's dispatch. */
+    Candidates: 96,
+    /** The cells pass's dispatch for the patch list. */
+    PatchCells: 112,
+    /** The patches' indexed draw. */
+    PatchDraw: 128,
+});
+export const WATER_LOD_COMMAND_BYTES = 160;
+
+const fold = `
+fn water_lod_dispatch(at: u32, groups: u32) {
+    const LIMIT = ${WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION}u;
+    let rows = (groups + LIMIT - 1u) / LIMIT;
+    commands[at] = min(groups, LIMIT);
+    commands[at + 1u] = max(min(rows, LIMIT), 1u);
+    commands[at + 2u] = max((rows + LIMIT - 1u) / LIMIT, 1u);
+}
+fn water_lod_total(sums_count: u32, last: u32) -> u32 { return select(0u, last, sums_count > 0u); }
+fn water_lod_draw(list: u32, count: u32, vertices: u32, first: u32) {
+    let draw = ${WaterLodCommand.Draws / 4}u + 4u * list;
+    commands[draw] = vertices;
+    commands[draw + 1u] = count;
+    commands[draw + 2u] = first;
+    commands[draw + 3u] = 0u;
+}
+`;
+
+const candidate_command_resources = new ShaderResourceSetDescriptor();
+candidate_command_resources.createGroup()
+    .addUniform('limits', WATER_LOD_LIMITS_STRUCT)
+    .addStorageBuffer('triangle_sums', COLLECTION_U32_STRUCT_READ)
+    .addStorageBuffer('flat_sums', COLLECTION_U32_STRUCT_READ)
+    .addStorageBuffer('commands', WebGPUArray.u32, true)
+    .addStorageBuffer('statistics', WebGPUArray.u32, true);
+
+/**
+ * From the triangles' scans: the candidate pass's dispatch, cut to its budget; the flat triangles' dispatch and draw;
+ * and the frame's candidate and flat triangle totals.
+ */
+export const shader_water_lod_candidate_command = ComputeShader.from({ label: 'Water / lod candidate command',
+    resources: candidate_command_resources, body: CodeChunk.from(/* language=WGSL */ `
+${fold}
+@compute @workgroup_size(1)
+fn main() {
+    let total = water_lod_total(triangle_sums.count, triangle_sums.elements[max(triangle_sums.count, 1u) - 1u]);
+    let flats = water_lod_total(flat_sums.count, flat_sums.elements[max(flat_sums.count, 1u) - 1u]);
+    statistics[0] = total;
+    statistics[3] = flats;
+    water_lod_dispatch(${WaterLodCommand.Candidates / 4}u, (min(total, limits.candidates) + 63u) / 64u);
+    let drawn = min(flats, limits.triangles);
+    water_lod_dispatch(${WaterLodCommand.Flats / 4}u, (drawn + 63u) / 64u);
+    water_lod_draw(${WaterLodList.Triangle}u, drawn, ${WATER_LOD_TRIANGLE_VERTICES}u, ${WATER_LOD_TRIANGLE_FIRST_VERTEX}u);
+}
+`) });
+
+const draw_command_resources = new ShaderResourceSetDescriptor();
+draw_command_resources.createGroup()
+    .addUniform('limits', WATER_LOD_LIMITS_STRUCT)
+    .addStorageBuffer('sums', COLLECTION_U32_STRUCT_READ)
+    .addStorageBuffer('commands', WebGPUArray.u32, true)
+    .addStorageBuffer('statistics', WebGPUArray.u32, true);
+
+/** The interior, boundary and patch lists' cells-pass dispatches and draws, cut to their budgets; their totals. */
+export const shader_water_lod_draw_commands = ComputeShader.from({ label: 'Water / lod draw commands',
+    resources: draw_command_resources, body: CodeChunk.from(/* language=WGSL */ `
+${fold}
+fn water_lod_list(list: u32, total: u32, budget: u32, vertices: u32, first: u32) {
+    statistics[1u + list] = total;
+    let count = min(total, budget);
+    water_lod_dispatch(${WaterLodCommand.Cells / 4}u + 4u * list, (count + 63u) / 64u);
+    water_lod_draw(list, count, vertices, first);
+}
+
+@compute @workgroup_size(1)
+fn main() {
+    water_lod_list(${WaterLodList.Interior}u, water_lod_list_span(&sums.elements, sums.count, 0u).y,
+        limits.interior, ${WATER_LOD_INTERIOR_VERTICES}u, 0u);
+    water_lod_list(${WaterLodList.Boundary}u, water_lod_list_span(&sums.elements, sums.count, 1u).y,
+        limits.boundary, ${WATER_LOD_BOUNDARY_VERTICES}u, ${WATER_LOD_BOUNDARY_FIRST_VERTEX}u);
+    // patches: one instance of the patch's indices each, its points named from the patch base vertex
+    let patches = water_lod_list_span(&sums.elements, sums.count, 2u).y;
+    statistics[4] = patches;
+    let count = min(patches, limits.patches);
+    water_lod_dispatch(${WaterLodCommand.PatchCells / 4}u, (count + 63u) / 64u);
+    let draw = ${WaterLodCommand.PatchDraw / 4}u;
+    commands[draw] = ${WATER_LOD_PATCH_INDICES.length}u;
+    commands[draw + 1u] = count;
+    commands[draw + 2u] = 0u;
+    commands[draw + 3u] = ${WATER_LOD_PATCH_FIRST_VERTEX}u;
+    commands[draw + 4u] = 0u;
+}
+`, [chunk_water_lod_list_sums]) });
+
+export { chunk_water_lod_candidate, chunk_water_lod_source };