@woosh/meep-engine 3.41.0 → 3.42.0

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

@@ -0,0 +1,246 @@
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { chunk_water_lod } from "./chunk_water_lod.js";
+
+/**
+ * A lattice cell cut by an authored triangle in the body's metric local xz
+ * (WATER_SURFACE_DISTANCE_LOD_PROPOSAL_2026_10_06.md §4.2).
+ *
+ * Every point is identified by what it lies on — a cell corner, an authored corner, or a cell edge crossing an
+ * authored edge — and its position, rest height and normal are computed from that identity alone, with each edge
+ * taken in a fixed endpoint order (the lesser in x, then z, first). So two triangles sharing an edge, and two cells or
+ * two levels sharing a seam, produce the same f32 vertices whichever way round they walk them.
+ *
+ * Point bits: the authored edges 1 (b–c), 2 (c–a), 4 (a–b); the cell edges 16 (corner 0 → 1), 32 (1 → 2), 64 (2 → 3),
+ * 128 (3 → 0), corners 0 … 3 at (x0, z0), (x1, z0), (x1, z1), (x0, z1).
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_water_lod_cell = CodeChunk.from(/* language=WGSL */ `
+struct WaterLodTriangle {
+    // authored corners, local units
+    local: array<vec3<f32>, 3>,
+    normal: array<vec3<f32>, 3>,
+    // the corners in metric local xz
+    p: array<vec2<f32>, 3>,
+    // per edge, the side of its canonical line the triangle is on: ±1
+    side: vec3<f32>,
+    // whether the corners turn the same way as a cell's, x towards z
+    ccw: bool,
+}
+
+struct WaterLodPolygon {
+    points: array<vec2<f32>, 8>,
+    bits: array<u32, 8>,
+    count: u32,
+}
+
+// Edge t of a triangle joins corners t + 1 and t + 2, in the order their metric positions sort.
+fn water_lod_edge(tri: WaterLodTriangle, t: u32) -> vec2<u32> {
+    let i = (t + 1u) % 3u;
+    let j = (t + 2u) % 3u;
+    let pi = tri.p[i];
+    let pj = tri.p[j];
+    let swap = pi.x > pj.x || (pi.x == pj.x && pi.y > pj.y);
+    return select(vec2<u32>(i, j), vec2<u32>(j, i), swap);
+}
+
+// Where x lies against edge t's canonical line: the same number from either triangle that shares the edge.
+fn water_lod_edge_distance(tri: WaterLodTriangle, t: u32, x: vec2<f32>) -> f32 {
+    let e = water_lod_edge(tri, t);
+    let u = tri.p[e.x];
+    let v = tri.p[e.y];
+    return (v.x - u.x) * (x.y - u.y) - (v.y - u.y) * (x.x - u.x);
+}
+
+fn water_lod_triangle(a: vec3<f32>, b: vec3<f32>, c: vec3<f32>, na: vec3<f32>, nb: vec3<f32>, nc: vec3<f32>, scale: vec3<f32>) -> WaterLodTriangle {
+    var tri: WaterLodTriangle;
+    tri.local = array<vec3<f32>, 3>(a, b, c);
+    tri.normal = array<vec3<f32>, 3>(na, nb, nc);
+    tri.p = array<vec2<f32>, 3>(a.xz * scale.xz, b.xz * scale.xz, c.xz * scale.xz);
+    for (var t = 0u; t < 3u; t++) { tri.side[t] = select(-1.0, 1.0, water_lod_edge_distance(tri, t, tri.p[t]) >= 0.0); }
+    let e1 = tri.p[1] - tri.p[0];
+    let e2 = tri.p[2] - tri.p[0];
+    tri.ccw = e1.x * e2.y - e1.y * e2.x >= 0.0;
+    return tri;
+}
+
+// Whether the triangle covers no area of metric xz as the lattice measures it: a corner on its opposite edge's line.
+// Every edge would then count the triangle on both of its sides, and the triangle would read as a half-plane.
+fn water_lod_no_area(tri: WaterLodTriangle) -> bool {
+    var none = false;
+    for (var t = 0u; t < 3u; t++) { none = none || water_lod_edge_distance(tri, t, tri.p[t]) == 0.0; }
+    return none;
+}
+
+// The authored edges a point lies exactly on.
+fn water_lod_edge_bits(tri: WaterLodTriangle, x: vec2<f32>) -> u32 {
+    var bits = 0u;
+    for (var t = 0u; t < 3u; t++) { if (water_lod_edge_distance(tri, t, x) == 0.0) { bits |= 1u << t; } }
+    return bits;
+}
+
+// Whether a point is inside the triangle, its edges included.
+fn water_lod_inside(tri: WaterLodTriangle, x: vec2<f32>) -> bool {
+    var inside = true;
+    for (var t = 0u; t < 3u; t++) { inside = inside && tri.side[t] * water_lod_edge_distance(tri, t, x) >= 0.0; }
+    return inside;
+}
+
+fn water_lod_corner_bits(k: u32) -> u32 {
+    return (16u << k) | (16u << ((k + 3u) % 4u));
+}
+
+// Whether a point's bits say where it is: a cell corner, an authored corner, or a cell edge crossing an authored edge.
+fn water_lod_identified(bits: u32) -> bool {
+    let authored = bits & 7u;
+    let cell = bits >> 4u;
+    var corner = false;
+    for (var k = 0u; k < 4u; k++) {
+        let pair = water_lod_corner_bits(k) >> 4u;
+        corner = corner || (cell & pair) == pair;
+    }
+    return corner || countOneBits(authored) >= 2u || (authored != 0u && cell != 0u);
+}
+
+// A point from what it lies on, for bits that identify it: a cell corner first, so a cell's own corners keep their
+// places wherever an authored corner also lies.
+fn water_lod_point(tri: WaterLodTriangle, corners: array<vec2<f32>, 4>, bits: u32) -> vec2<f32> {
+    let cell = bits >> 4u;
+    for (var k = 0u; k < 4u; k++) {
+        let corner = water_lod_corner_bits(k) >> 4u;
+        if ((cell & corner) == corner) { return corners[k]; }
+    }
+    let authored = bits & 7u;
+    if (authored == 6u) { return tri.p[0]; }
+    if (authored == 5u) { return tri.p[1]; }
+    if (authored == 3u) { return tri.p[2]; }
+    // a cell edge crossing an authored edge: the cell edge in its canonical order too
+    let e = firstTrailingBit(cell);
+    let t = firstTrailingBit(authored);
+    var p = corners[e];
+    var q = corners[(e + 1u) % 4u];
+    if (p.x > q.x || (p.x == q.x && p.y > q.y)) { let swap = p; p = q; q = swap; }
+    let dp = water_lod_edge_distance(tri, t, p);
+    let dq = water_lod_edge_distance(tri, t, q);
+    if (dp == dq) { return p; }
+    return mix(p, q, dp / (dp - dq));
+}
+
+// The cell with corners morphed, every corner tagged with the authored edges it lies on.
+fn water_lod_cell_polygon(tri: WaterLodTriangle, corners: array<vec2<f32>, 4>) -> WaterLodPolygon {
+    var polygon: WaterLodPolygon;
+    for (var k = 0u; k < 4u; k++) {
+        polygon.points[k] = corners[k];
+        polygon.bits[k] = water_lod_corner_bits(k) | water_lod_edge_bits(tri, corners[k]);
+    }
+    polygon.count = 4u;
+    return polygon;
+}
+
+// Sutherland–Hodgman against the inside of authored edge t. A new point takes what its two neighbours share and
+// the edge, and its position from those alone; where that does not say where it is (two neighbours that share no
+// edge, which only rounding makes), it stands in for the point it was found at. So every point of a clipped cell can
+// be rebuilt from its bits.
+fn water_lod_clip(tri: WaterLodTriangle, corners: array<vec2<f32>, 4>, polygon: WaterLodPolygon, t: u32) -> WaterLodPolygon {
+    var out: WaterLodPolygon;
+    if (polygon.count == 0u) { return out; }
+    var previous = polygon.count - 1u;
+    var d_previous = tri.side[t] * water_lod_edge_distance(tri, t, polygon.points[previous]);
+    for (var i = 0u; i < polygon.count; i++) {
+        let d = tri.side[t] * water_lod_edge_distance(tri, t, polygon.points[i]);
+        if ((d >= 0.0) != (d_previous >= 0.0) && out.count < 8u) {
+            var bits = (polygon.bits[previous] & polygon.bits[i]) | (1u << t);
+            var point = polygon.points[i];
+            if (water_lod_identified(bits)) { point = water_lod_point(tri, corners, bits); } else { bits = polygon.bits[i]; }
+            out.bits[out.count] = bits;
+            out.points[out.count] = point;
+            out.count++;
+        }
+        if (d >= 0.0 && out.count < 8u) {
+            out.bits[out.count] = polygon.bits[i];
+            out.points[out.count] = polygon.points[i];
+            out.count++;
+        }
+        previous = i;
+        d_previous = d;
+    }
+    return out;
+}
+
+fn water_lod_cell_clipped(tri: WaterLodTriangle, corners: array<vec2<f32>, 4>) -> WaterLodPolygon {
+    var polygon = water_lod_cell_polygon(tri, corners);
+    for (var t = 0u; t < 3u; t++) { polygon = water_lod_clip(tri, corners, polygon, t); }
+    return polygon;
+}
+
+// A clipped cell as two words, what its points are rebuilt from: byte 0 its point count, at most the seven a square
+// cut by a triangle can have, then each point's bits a byte.
+fn water_lod_polygon_pack(polygon: WaterLodPolygon) -> vec2<u32> {
+    let count = min(polygon.count, 7u);
+    var words = vec2<u32>(count, 0u);
+    for (var i = 0u; i < count; i++) {
+        let at = i + 1u;
+        let byte = (polygon.bits[i] & 255u) << (8u * (at & 3u));
+        if (at < 4u) { words.x |= byte; } else { words.y |= byte; }
+    }
+    return words;
+}
+
+fn water_lod_polygon_count(words: vec2<u32>) -> u32 { return words.x & 255u; }
+
+fn water_lod_polygon_bits(words: vec2<u32>, i: u32) -> u32 {
+    let at = i + 1u;
+    return (select(words.x, words.y, at >= 4u) >> (8u * (at & 3u))) & 255u;
+}
+
+struct WaterLodRest {
+    // local units
+    position: vec3<f32>,
+    normal: vec3<f32>,
+}
+
+// A point's rest position on the authored surface: an authored corner itself; along its edge, in the edge's canonical
+// order, for a point on one; inside, the triangle's plane.
+fn water_lod_rest(tri: WaterLodTriangle, bits: u32, x: vec2<f32>, scale: vec3<f32>) -> WaterLodRest {
+    let authored = bits & 7u;
+    if (authored == 6u) { return WaterLodRest(tri.local[0], tri.normal[0]); }
+    if (authored == 5u) { return WaterLodRest(tri.local[1], tri.normal[1]); }
+    if (authored == 3u) { return WaterLodRest(tri.local[2], tri.normal[2]); }
+    let xz = x / scale.xz;
+    if (authored != 0u) {
+        let e = water_lod_edge(tri, firstTrailingBit(authored));
+        let u = tri.p[e.x];
+        let span = tri.p[e.y] - u;
+        let along = dot(x - u, span) / max(dot(span, span), 1e-30);
+        return WaterLodRest(vec3<f32>(xz.x, mix(tri.local[e.x].y, tri.local[e.y].y, along), xz.y),
+            mix(tri.normal[e.x], tri.normal[e.y], along));
+    }
+    var weights: vec3<f32>;
+    for (var t = 0u; t < 3u; t++) {
+        weights[t] = water_lod_edge_distance(tri, t, x) / water_lod_edge_distance(tri, t, tri.p[t]);
+    }
+    return WaterLodRest(vec3<f32>(xz.x, dot(weights, vec3<f32>(tri.local[0].y, tri.local[1].y, tri.local[2].y)), xz.y),
+        tri.normal[0] * weights.x + tri.normal[1] * weights.y + tri.normal[2] * weights.z);
+}
+
+// Separating axes in 2D: whether the triangle and the square lo … hi share area. Touching along an edge or at a point
+// draws nothing, so it does not count.
+fn water_lod_triangle_meets_square(tri: WaterLodTriangle, lo: vec2<f32>, hi: vec2<f32>) -> bool {
+    let tri_lo = min(min(tri.p[0], tri.p[1]), tri.p[2]);
+    let tri_hi = max(max(tri.p[0], tri.p[1]), tri.p[2]);
+    if (any(tri_lo >= hi) || any(tri_hi <= lo)) { return false; }
+    let square = array<vec2<f32>, 4>(lo, vec2<f32>(hi.x, lo.y), hi, vec2<f32>(lo.x, hi.y));
+    for (var t = 0u; t < 3u; t++) {
+        var any_inside = false;
+        for (var k = 0u; k < 4u; k++) { any_inside = any_inside || tri.side[t] * water_lod_edge_distance(tri, t, square[k]) > 0.0; }
+        if (!any_inside) { return false; }
+    }
+    return true;
+}
+
+// Whether the whole square lies inside the triangle.
+fn water_lod_triangle_holds_square(tri: WaterLodTriangle, lo: vec2<f32>, hi: vec2<f32>) -> bool {
+    return water_lod_inside(tri, lo) && water_lod_inside(tri, vec2<f32>(hi.x, lo.y))
+        && water_lod_inside(tri, hi) && water_lod_inside(tri, vec2<f32>(lo.x, hi.y));
+}
+`, [chunk_water_lod]);

package/src/shade/renderer/water/surface/lod/shader_water_lod.d.ts

@@ -0,0 +1,118 @@
+/** 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: Uint16Array;
+/** 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: number;
+/** 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: Readonly<{
+    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;
+/**
+ * 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;
+/**
+ * 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 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;
+/**
+ * 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;
+/**
+ * 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;
+/** Words of a candidate's row record: 32 rows (4 quadrants × 8), 16 bits each. */
+export const WATER_LOD_CANDIDATE_ROW_WORDS: 16;
+/**
+ * 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;
+/**
+ * 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;
+/** Byte offsets in the command buffer the commands passes write. */
+export const WaterLodCommand: Readonly<{
+    /** 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;
+/**
+ * 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;
+/** 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;
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+export const chunk_water_lod_layout: CodeChunk;
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+export const chunk_water_lod_candidate: CodeChunk;
+/** Reads a drawn triangle of the view's meshlet list: its body, its frame and its corners. */
+export const chunk_water_lod_source: CodeChunk;
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=shader_water_lod.d.ts.map

package/src/shade/renderer/water/surface/lod/shader_water_lod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_water_lod.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/water/surface/lod/shader_water_lod.js"],"names":[],"mappings":"AA8BA,sHAAsH;AACtH,4CAA6C;AAC7C,6CAA8C;AAC9C,4CAA6C;AAC7C,sFAAsF;AACtF,iDAAkD;AAClD,iDAAkD;AAClD,kFAAkF;AAClF,8CAA+C;AAC/C,oFAAoF;AACpF,qCAAsC;AAEtC;;;;GAIG;AACH,kDASK;AAEL,kHAAkH;AAClH,0CAA2C;AAC3C,0EAA0E;AAC1E,+CAA+E;AAE/E,yGAAyG;AACzG,wCAAyC;AAEzC,wEAAwE;AACxE;;;;;GAA+F;AAE/F;;;;GAIG;AACH,sDAEwB;AAExB;;;;GAIG;AACH,mDAE4B;AAE5B;;;GAGG;AACH,2CAA4C;AA0I5C;;;;;;GAMG;AACH,oDAuD0E;AAsD1E;;;;;GAKG;AACH,uDAkCsH;AAWtH;;;GAGG;AACH,mDAYoE;AAIpE,kFAAkF;AAClF,+CAAgD;AAiBhD;;;;;;;GAOG;AACH,wDAqF0C;AAiB1C;;;;;;;GAOG;AACH,mDAqEmF;AAInF,oEAAoE;AACpE;IACI,6EAA6E;;IAE7E,oCAAoC;;IAEpC,0EAA0E;;IAE1E,qCAAqC;;IAErC,oDAAoD;;IAEpD,iCAAiC;;GAElC;AACH,0CAA2C;AA4B3C;;;GAGG;AACH,+DAcM;AASN,mHAAmH;AACnH,2DA4BmC;6BA7rBN,sCAAsC;AAuFnE,+CAIgD;8BAxGlB,kCAAkC;AA2GhE,kDAgG6G;AAkF7G,8FAA8F;AAC9F,+CAmCsH;0BAhU5F,uCAAuC"}