@woosh/meep-engine 3.41.0 → 3.42.0

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

@@ -1,14 +1,68 @@
-/** Storage grows with source primitives; patch instances are expanded by the vertex shader. */
-export function graph_water_tessellation({ graph, scene, camera, meshlets, meshlet_capacity, tessellation }: {
-    graph: any;
-    scene: any;
-    camera: any;
-    meshlets: any;
-    meshlet_capacity: any;
-    tessellation: any;
+/**
+ * Where each list's records start in the cell buffer, and the buffer's words: interior and boundary cells a word each,
+ * triangles drawn as themselves two words each, patches a word each, then each boundary cell's clipped polygon. The
+ * vertex stage finds them by the same arithmetic over the limits (chunk_water_lod_layout).
+ *
+ * @param {{interior: number, boundary: number, triangles: number, patches: number}} limits
+ * @returns {{interior: number, boundary: number, triangles: number, patches: number, polygons: number, words: number}}
+ */
+export function water_lod_cell_layout(limits: {
+    interior: number;
+    boundary: number;
+    triangles: number;
+    patches: number;
 }): {
-    tiles: any;
-    sums: number;
-    count: any;
+    interior: number;
+    boundary: number;
+    triangles: number;
+    patches: number;
+    polygons: number;
+    words: number;
+};
+/**
+ * The view's lattice cut by the drawn bodies' authored triangles (WATER_SURFACE_DISTANCE_LOD_PROPOSAL_2026_10_06.md
+ * §4.3): per triangle, either itself on the triangle list or its candidates; per candidate, its quadrants and rows;
+ * and the patch, interior cell and boundary cell lists, each compacted by an ordered scan so equal-depth ownership
+ * between bodies stays deterministic. Candidates and cells are cut to `limits`; the totals before the cut land in `statistics`, for
+ * the caller to grow its budgets by.
+ *
+ * @param {object} options
+ * @param {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} options.graph
+ * @param {object} options.scene GPU scene context
+ * @param {number} options.camera the view's camera uniform resource
+ * @param {number} options.meshlets the drawn bodies' meshlets resource, from {@link GPUWaterBodies#meshlets}
+ * @param {number} options.lod_bodies the view's per-body lattice frames resource, from the same
+ * @param {number} options.meshlet_capacity every water meshlet the scene holds: the triangle slots there can be
+ * @param {{ranges: number, orthographic: number, level: number, distance: number}} options.lod the view's lattice choice
+ * @param {{candidates: number, interior: number, boundary: number, triangles: number, patches: number}} options.limits budgets
+ * @param {GPUBuffer} options.steep per wave row: set for a body with a triangle too steep for the lattice
+ * @returns {{candidates: number, cells: number, commands: number, statistics: number}} resources
+ */
+export function graph_water_tessellation({ graph, scene, camera, meshlets, lod_bodies, meshlet_capacity, lod, limits, steep }: {
+    graph: import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
+    scene: object;
+    camera: number;
+    meshlets: number;
+    lod_bodies: number;
+    meshlet_capacity: number;
+    lod: {
+        ranges: number;
+        orthographic: number;
+        level: number;
+        distance: number;
+    };
+    limits: {
+        candidates: number;
+        interior: number;
+        boundary: number;
+        triangles: number;
+        patches: number;
+    };
+    steep: GPUBuffer;
+}): {
+    candidates: number;
+    cells: number;
+    commands: number;
+    statistics: number;
 };
 //# sourceMappingURL=graph_water_tessellation.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"graph_water_tessellation.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/water/surface/graph_water_tessellation.js"],"names":[],"mappings":"AAQA,+FAA+F;AAC/F;;;;;;;;;;;EAwBC"}
+{"version":3,"file":"graph_water_tessellation.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/water/surface/graph_water_tessellation.js"],"names":[],"mappings":"AAiCA;;;;;;;GAOG;AACH,8CAHW;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC,GACtE;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAC,CAQrH;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH;IAXsG,KAAK,EAAhG,OAAO,8DAA8D,EAAE,UAAU;IACjE,KAAK,EAArB,MAAM;IACU,MAAM,EAAtB,MAAM;IACU,QAAQ,EAAxB,MAAM;IACU,UAAU,EAA1B,MAAM;IACU,gBAAgB,EAAhC,MAAM;IAC2E,GAAG,EAApF;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAC;IAC+B,MAAM,EAA5G;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAC;IACzE,KAAK;IACtB;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAC,CAsGrF"}

package/src/shade/renderer/water/surface/graph_water_tessellation.js

@@ -1,34 +1,169 @@
+import { assert } from "../../../../core/assert.js";
 import { BufferResourceDescriptor } from "../../../device/graph/BufferResourceDescriptor.js";
 import { GEOMETRY_MESHLET_TRIANGLE_LIMIT } from "../../geometry/meshlet/GEOMETRY_MESHLET_TRIANGLE_LIMIT.js";
 import { graph_prefix_scan_csdldf } from "../../gpu_primitive/prefix_sum/v1/graph_prefix_scan_csdldf.js";
-import { graph_compute_pass } from "../../shader/graph/compute/graph_compute_pass.js";
-import { shader_increment_count_by_prefix_sum } from "../../rasterize/expand/mesh/shader_increment_count_by_prefix_sum.js";
-import { WATER_TILE_STRUCT, WATER_TESSELLATION_STRUCT } from "./chunk_water_tessellation.js";
-import { shader_water_tiles } from "./shader_water_tiles.js";
+import {
+    build_indirect_compute_dispatch_command,
+    INDIRECT_COMPUTE_COMMAND_DESCRIPTOR
+} from "../../gpu_primitive/indirect/IndirectComputeCommandBuildPass.js";
+import { WATER_LOD_VIEW_STRUCT } from "./lod/WATER_LOD.js";
+import {
+    shader_water_lod_candidate_command,
+    shader_water_lod_candidates,
+    shader_water_lod_cells,
+    shader_water_lod_draw_commands,
+    shader_water_lod_flats,
+    shader_water_lod_triangles,
+    WATER_LOD_CANDIDATE_LIMIT,
+    WATER_LOD_CANDIDATE_ROW_WORDS,
+    WATER_LOD_CANDIDATE_STRUCT,
+    WATER_LOD_COMMAND_BYTES,
+    WATER_LOD_LIMITS_STRUCT,
+    WATER_LOD_POLYGON_WORDS,
+    WATER_LOD_STATISTICS_WORDS,
+    WaterLodCommand,
+    WaterLodList
+} from "./lod/shader_water_lod.js";
 
-/** Storage grows with source primitives; patch instances are expanded by the vertex shader. */
-export function graph_water_tessellation({ graph, scene, camera, meshlets, meshlet_capacity, tessellation }) {
-    const capacity = meshlet_capacity * GEOMETRY_MESHLET_TRIANGLE_LIMIT;
-    const data = {};
-    const pass = graph.add('Water / classify view tiles', data, (d, resources, { encoder }) => {
-        const groups = Math.ceil(capacity / 128);
-        shader_water_tiles.dispatch({ encoder, bindings: {
-            capacity, camera: resources.get(d.camera), water_meshlets: resources.get(d.meshlets),
-            tessellation: encoder.allocateTransientValueBuffer(WATER_TESSELLATION_STRUCT, tessellation),
-            scene_database: scene.scene_database_buffer,
-            geometries: scene.geometries.buffer_metadata,
-            meshlet_metadata: scene.geometries.meshlets.buffer_metadata, meshlet_data: scene.geometries.meshlets.buffer_data,
-            counts: resources.get(d.counts), tiles: resources.get(d.tiles),
-        }, group_count_x: Math.min(groups, 65535), group_count_y: Math.ceil(groups / 65535) });
+/** A counts collection of this many elements: its count, padded, then the elements in whole vec4 blocks. */
+function counts_descriptor(elements) {
+    const bytes = 16 + Math.ceil(Math.max(elements, 1) / 4) * 16;
+    return BufferResourceDescriptor.from(bytes, GPUBufferUsage.STORAGE, 0, 16);
+}
+
+/**
+ * Where each list's records start in the cell buffer, and the buffer's words: interior and boundary cells a word each,
+ * triangles drawn as themselves two words each, patches a word each, then each boundary cell's clipped polygon. The
+ * vertex stage finds them by the same arithmetic over the limits (chunk_water_lod_layout).
+ *
+ * @param {{interior: number, boundary: number, triangles: number, patches: number}} limits
+ * @returns {{interior: number, boundary: number, triangles: number, patches: number, polygons: number, words: number}}
+ */
+export function water_lod_cell_layout(limits) {
+    const triangles = limits.interior + limits.boundary;
+    const patches = triangles + 2 * limits.triangles;
+    const polygons = patches + limits.patches;
+    return { interior: 0, boundary: limits.interior, triangles, patches, polygons,
+        words: Math.max(polygons + WATER_LOD_POLYGON_WORDS * limits.boundary, 1) };
+}
+
+/**
+ * The view's lattice cut by the drawn bodies' authored triangles (WATER_SURFACE_DISTANCE_LOD_PROPOSAL_2026_10_06.md
+ * §4.3): per triangle, either itself on the triangle list or its candidates; per candidate, its quadrants and rows;
+ * and the patch, interior cell and boundary cell lists, each compacted by an ordered scan so equal-depth ownership
+ * between bodies stays deterministic. Candidates and cells are cut to `limits`; the totals before the cut land in `statistics`, for
+ * the caller to grow its budgets by.
+ *
+ * @param {object} options
+ * @param {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} options.graph
+ * @param {object} options.scene GPU scene context
+ * @param {number} options.camera the view's camera uniform resource
+ * @param {number} options.meshlets the drawn bodies' meshlets resource, from {@link GPUWaterBodies#meshlets}
+ * @param {number} options.lod_bodies the view's per-body lattice frames resource, from the same
+ * @param {number} options.meshlet_capacity every water meshlet the scene holds: the triangle slots there can be
+ * @param {{ranges: number, orthographic: number, level: number, distance: number}} options.lod the view's lattice choice
+ * @param {{candidates: number, interior: number, boundary: number, triangles: number, patches: number}} options.limits budgets
+ * @param {GPUBuffer} options.steep per wave row: set for a body with a triangle too steep for the lattice
+ * @returns {{candidates: number, cells: number, commands: number, statistics: number}} resources
+ */
+export function graph_water_tessellation({ graph, scene, camera, meshlets, lod_bodies, meshlet_capacity, lod, limits, steep }) {
+    assert.lessThanOrEqual(limits.candidates, WATER_LOD_CANDIDATE_LIMIT, 'candidate budget');
+    const slots = Math.max(meshlet_capacity, 1) * GEOMETRY_MESHLET_TRIANGLE_LIMIT;
+    const layout = water_lod_cell_layout(limits);
+    const geometry_bindings = { scene_database: scene.scene_database_buffer,
+        meshlet_metadata: scene.geometries.meshlets.buffer_metadata, meshlet_data: scene.geometries.meshlets.buffer_data };
+    const limits_value = { ...limits };
+
+    // per triangle slot of the drawn meshlets: drawn as itself, or its candidates
+    const triangles_data = {};
+    const triangles = graph.add('Water / lod triangles', triangles_data, (d, resources, { encoder }) => {
+        const command = resources.get(d.command), list = resources.get(d.meshlets);
+        build_indirect_compute_dispatch_command(1, encoder, list, 0, command, 0, true);
+        shader_water_lod_triangles.dispatchIndirect({ encoder, command, bindings: { ...geometry_bindings,
+            lod: encoder.allocateTransientValueBuffer(WATER_LOD_VIEW_STRUCT, lod), water_meshlets: list,
+            lod_bodies: resources.get(d.lod_bodies), steep, counts: resources.get(d.counts), flats: resources.get(d.flats) } });
+    });
+    triangles_data.meshlets = triangles.read(meshlets);
+    triangles_data.lod_bodies = triangles.read(lod_bodies);
+    triangles_data.command = triangles.create('Water lod triangles command', INDIRECT_COMPUTE_COMMAND_DESCRIPTOR);
+    triangles_data.counts = triangles.create('Water lod triangle counts', counts_descriptor(slots));
+    triangles_data.flats = triangles.create('Water lod flat counts', counts_descriptor(slots));
+    const triangle_sums = graph_prefix_scan_csdldf({ graph, data: triangles_data.counts, element_max_count: slots });
+    const flat_sums = graph_prefix_scan_csdldf({ graph, data: triangles_data.flats, element_max_count: slots });
+
+    // the candidates' dispatch; the flat triangles' records and draw
+    const command_data = {};
+    const candidate_command = graph.add('Water / lod candidate command', command_data, (d, resources, { encoder }) => {
+        const commands = resources.get(d.commands);
+        shader_water_lod_candidate_command.dispatch({ encoder, bindings: {
+            limits: encoder.allocateTransientValueBuffer(WATER_LOD_LIMITS_STRUCT, limits_value),
+            triangle_sums: resources.get(d.sums), flat_sums: resources.get(d.flat_sums), commands, statistics: resources.get(d.statistics) } });
+        shader_water_lod_flats.dispatchIndirect({ encoder, command: commands, command_offset: WaterLodCommand.Flats, bindings: {
+            limits: { base: layout.triangles, budget: limits.triangles }, water_meshlets: resources.get(d.meshlets),
+            flat_sums: resources.get(d.flat_sums), cells: resources.get(d.cells) } });
+    });
+    command_data.sums = candidate_command.read(triangle_sums);
+    command_data.flat_sums = candidate_command.read(flat_sums);
+    command_data.meshlets = candidate_command.read(meshlets);
+    command_data.commands = candidate_command.create('Water lod commands', BufferResourceDescriptor.from(WATER_LOD_COMMAND_BYTES,
+        GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT));
+    command_data.statistics = candidate_command.create('Water lod statistics', BufferResourceDescriptor.from(
+        WATER_LOD_STATISTICS_WORDS * 4, GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC));
+    command_data.cells = candidate_command.create('Water lod cells', BufferResourceDescriptor.from(layout.words * 4, GPUBufferUsage.STORAGE));
+
+    // candidates: quadrants, rows, and how many cells of each list
+    const candidates_data = {};
+    const candidates = graph.add('Water / lod candidates', candidates_data, (d, resources, { encoder }) => {
+        shader_water_lod_candidates.dispatchIndirect({ encoder, command: resources.get(d.commands), command_offset: WaterLodCommand.Candidates,
+            bindings: { ...geometry_bindings, lod: encoder.allocateTransientValueBuffer(WATER_LOD_VIEW_STRUCT, lod),
+                limits: encoder.allocateTransientValueBuffer(WATER_LOD_LIMITS_STRUCT, limits_value), camera: resources.get(d.camera),
+                water_meshlets: resources.get(d.meshlets), lod_bodies: resources.get(d.lod_bodies), triangle_sums: resources.get(d.sums),
+                candidates: resources.get(d.candidates), candidate_rows: resources.get(d.rows),
+                cell_counts: resources.get(d.counts) } });
+    });
+    candidates_data.commands = candidates.read(command_data.commands);
+    candidates_data.camera = candidates.read(camera);
+    candidates_data.meshlets = candidates.read(meshlets);
+    candidates_data.lod_bodies = candidates.read(lod_bodies);
+    candidates_data.sums = candidates.read(triangle_sums);
+    const budget = Math.max(limits.candidates, 1);
+    candidates_data.candidates = candidates.create('Water lod candidates', BufferResourceDescriptor.from(
+        budget * WATER_LOD_CANDIDATE_STRUCT.size, GPUBufferUsage.STORAGE));
+    candidates_data.rows = candidates.create('Water lod candidate rows', BufferResourceDescriptor.from(
+        budget * WATER_LOD_CANDIDATE_ROW_WORDS * 4, GPUBufferUsage.STORAGE));
+    // the interior, boundary and patch counts of every candidate, one region after another, scanned once
+    candidates_data.counts = candidates.create('Water lod cell counts', counts_descriptor(3 * budget));
+    const list_sums = graph_prefix_scan_csdldf({ graph, data: candidates_data.counts, element_max_count: 3 * budget });
+
+    // each list's records; the boundary cells' polygons
+    const lists = [
+        { list: WaterLodList.Interior, base: layout.interior, budget: limits.interior, command: WaterLodCommand.Cells },
+        { list: WaterLodList.Boundary, base: layout.boundary, budget: limits.boundary, command: WaterLodCommand.Cells + 16 },
+        { list: WaterLodList.Patch, base: layout.patches, budget: limits.patches, command: WaterLodCommand.PatchCells },
+    ];
+    const cells_data = {};
+    const cells = graph.add('Water / lod cells', cells_data, (d, resources, { encoder }) => {
+        const commands = resources.get(d.commands);
+        const sums = resources.get(d.sums);
+        const limits_buffer = encoder.allocateTransientValueBuffer(WATER_LOD_LIMITS_STRUCT, limits_value);
+        shader_water_lod_draw_commands.dispatch({ encoder, bindings: { limits: limits_buffer, sums, commands,
+            statistics: resources.get(d.statistics) } });
+        const lod_buffer = encoder.allocateTransientValueBuffer(WATER_LOD_VIEW_STRUCT, lod);
+        lists.forEach(({ list, base, budget, command }) => {
+            shader_water_lod_cells.dispatchIndirect({ encoder, command: commands, command_offset: command,
+                bindings: { meshlet_metadata: geometry_bindings.meshlet_metadata, meshlet_data: geometry_bindings.meshlet_data,
+                    limits: { base, budget, list }, lod: lod_buffer, lod_limits: limits_buffer,
+                    lod_bodies: resources.get(d.lod_bodies), sums, cells: resources.get(d.cells),
+                    candidates: resources.get(d.candidates), candidate_rows: resources.get(d.rows) } });
+        });
     });
-    data.camera = pass.read(camera); data.meshlets = pass.read(meshlets);
-    data.tiles = pass.create('Water triangle tiles', BufferResourceDescriptor.from(capacity * WATER_TILE_STRUCT.size, GPUBufferUsage.STORAGE));
-    const bytes = 16 + capacity * 4;
-    data.counts = pass.create('Water tile counts', BufferResourceDescriptor.from(bytes, GPUBufferUsage.STORAGE, 0, bytes));
-    const sums = graph_prefix_scan_csdldf({ graph, data: data.counts, element_max_count: capacity });
-    const clear = graph.add('Water / patch count', {}, () => {});
-    const count = clear.create('Water patches', BufferResourceDescriptor.from(16, GPUBufferUsage.STORAGE, 0, 16));
-    const { output } = graph_compute_pass({ graph, shader: shader_increment_count_by_prefix_sum,
-        bindings: { prefix_sums: sums, output: count } });
-    return { tiles: data.tiles, sums, count: output };
+    cells_data.commands = cells.write(cells.read(command_data.commands));
+    cells_data.statistics = cells.write(cells.read(command_data.statistics));
+    cells_data.cells = cells.write(cells.read(command_data.cells));
+    cells_data.sums = cells.read(list_sums);
+    cells_data.candidates = cells.read(candidates_data.candidates);
+    cells_data.rows = cells.read(candidates_data.rows);
+    cells_data.lod_bodies = cells.read(lod_bodies);
+    return { candidates: candidates_data.candidates, cells: cells_data.cells, commands: cells_data.commands,
+        statistics: cells_data.statistics };
 }

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

@@ -0,0 +1,51 @@
+/**
+ * A view's lattice choice from its projection, its target's height in pixels and the setting.
+ *
+ * θ, the angle a pixel subtends at unit distance, is 2 / (height · P[1][1]); an orthographic projection gives the world
+ * size of a pixel by the same formula. A cell spans `pixels` on screen where it is smallest, at 0.7 of its level's
+ * range, so R = 1 / (0.7 · pixels · θ), and never below {@link WATER_LOD_RANGE_RATIO_MIN}.
+ *
+ * @param {ArrayLike<number>} projection column-major 4×4
+ * @param {number} height render target height, pixels
+ * @param {number} pixels the smallest a cell is drawn on screen
+ * @returns {{ranges: number, orthographic: number, level: number, distance: number, pixel: number}}
+ */
+export function water_lod_view(projection: ArrayLike<number>, height: number, pixels: number): {
+    ranges: number;
+    orthographic: number;
+    level: number;
+    distance: number;
+    pixel: number;
+};
+/** Levels of the lattice: cells of 2^(L − 10) m, 1 mm at level 0 to 16 km at level 24. */
+export const WATER_LOD_LEVELS: 25;
+/** Exponent of level 0's cell: 2^−10 m. */
+export const WATER_LOD_FINEST_EXPONENT: -10;
+/** Cells a side of a node; a quadrant is half a node. */
+export const WATER_LOD_NODE_CELLS: 16;
+/** Fraction of a level's range at which its odd vertices start to slide onto the coarser grid. */
+export const WATER_LOD_MORPH_START: 0.7;
+/**
+ * Smallest ratio of a level's range to its cell for which adjacent levels meet without cracks: a level's points lie
+ * within r_L + 16√2 s_L of the camera, which must stay inside the next level's unmorphed range, 0.7 · r_{L+1}.
+ */
+export const WATER_LOD_RANGE_RATIO_MIN: 64;
+/**
+ * How one view chooses the lattice (WATER_SURFACE_DISTANCE_LOD_PROPOSAL_2026_10_06.md §4.1): the same for every body.
+ */
+export const WATER_LOD_VIEW_STRUCT: WebGPUStruct;
+/** Lattice modes a drawn body takes. */
+export const WaterLodMode: Readonly<{
+    /** Not drawn by this view. */
+    Hidden: 0;
+    /** No displacement it can show: its authored triangles. */
+    Flat: 1;
+    /** Cut from the lattice. */
+    Lattice: 2;
+}>;
+/**
+ * One drawn body as one view sees it, in its metric local frame (local units times its transform's axis lengths).
+ */
+export const WATER_LOD_BODY_STRUCT: WebGPUStruct;
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+//# sourceMappingURL=WATER_LOD.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"WATER_LOD.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/water/surface/lod/WATER_LOD.js"],"names":[],"mappings":"AAkEA;;;;;;;;;;;GAWG;AACH,2CALW,UAAU,MAAM,CAAC,UACjB,MAAM,UACN,MAAM,GACJ;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAC,CAkBlG;AA1FD,0FAA0F;AAC1F,kCAAmC;AAEnC,2CAA2C;AAC3C,4CAA6C;AAE7C,yDAAyD;AACzD,sCAAuC;AAEvC,kGAAkG;AAClG,wCAAyC;AAEzC;;;GAGG;AACH,2CAA4C;AAE5C;;GAEG;AACH,iDAW0B;AAE1B,wCAAwC;AACxC;IACI,8BAA8B;;IAE9B,2DAA2D;;IAE3D,4BAA4B;;GAE7B;AAEH;;GAEG;AACH,iDAa0B;6BA9DG,sCAAsC"}

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

@@ -0,0 +1,95 @@
+import { assert } from "../../../../../core/assert.js";
+import { f32, u32, vec2f, vec3f } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+
+/** Levels of the lattice: cells of 2^(L − 10) m, 1 mm at level 0 to 16 km at level 24. */
+export const WATER_LOD_LEVELS = 25;
+
+/** Exponent of level 0's cell: 2^−10 m. */
+export const WATER_LOD_FINEST_EXPONENT = -10;
+
+/** Cells a side of a node; a quadrant is half a node. */
+export const WATER_LOD_NODE_CELLS = 16;
+
+/** Fraction of a level's range at which its odd vertices start to slide onto the coarser grid. */
+export const WATER_LOD_MORPH_START = 0.7;
+
+/**
+ * Smallest ratio of a level's range to its cell for which adjacent levels meet without cracks: a level's points lie
+ * within r_L + 16√2 s_L of the camera, which must stay inside the next level's unmorphed range, 0.7 · r_{L+1}.
+ */
+export const WATER_LOD_RANGE_RATIO_MIN = 64;
+
+/**
+ * How one view chooses the lattice (WATER_SURFACE_DISTANCE_LOD_PROPOSAL_2026_10_06.md §4.1): the same for every body.
+ */
+export const WATER_LOD_VIEW_STRUCT = WebGPUStruct.from({
+    /** R: a level's range over its cell. */
+    ranges: f32,
+    /** Non-zero for an orthographic view, which draws one level everywhere. */
+    orthographic: u32,
+    /** The orthographic view's level. */
+    level: u32,
+    /** The distance an orthographic view selects with: 0.6 of its level's range. */
+    distance: f32,
+    /** The angle a pixel subtends at unit distance; for an orthographic view, the size of a pixel. */
+    pixel: f32,
+}, 'WaterLodView').pack();
+
+/** Lattice modes a drawn body takes. */
+export const WaterLodMode = Object.freeze({
+    /** Not drawn by this view. */
+    Hidden: 0,
+    /** No displacement it can show: its authored triangles. */
+    Flat: 1,
+    /** Cut from the lattice. */
+    Lattice: 2,
+});
+
+/**
+ * One drawn body as one view sees it, in its metric local frame (local units times its transform's axis lengths).
+ */
+export const WATER_LOD_BODY_STRUCT = WebGPUStruct.from({
+    /** The camera in the body's metric local frame. */
+    camera: vec3f,
+    /** Distance from the camera to the body's rest height range, metric; zero inside it. */
+    vertical: f32,
+    /** Metres per local unit along each local axis. */
+    scale: vec3f,
+    /** A {@link WaterLodMode}. */
+    mode: u32,
+    /** The body's displacement bounds, metric: vertical, horizontal. */
+    bounds: vec2f,
+    /** The body's rest height range, local units. */
+    rest: vec2f,
+}, 'WaterLodBody').pack();
+
+/**
+ * A view's lattice choice from its projection, its target's height in pixels and the setting.
+ *
+ * θ, the angle a pixel subtends at unit distance, is 2 / (height · P[1][1]); an orthographic projection gives the world
+ * size of a pixel by the same formula. A cell spans `pixels` on screen where it is smallest, at 0.7 of its level's
+ * range, so R = 1 / (0.7 · pixels · θ), and never below {@link WATER_LOD_RANGE_RATIO_MIN}.
+ *
+ * @param {ArrayLike<number>} projection column-major 4×4
+ * @param {number} height render target height, pixels
+ * @param {number} pixels the smallest a cell is drawn on screen
+ * @returns {{ranges: number, orthographic: number, level: number, distance: number, pixel: number}}
+ */
+export function water_lod_view(projection, height, pixels) {
+    assert.greaterThan(height, 0, 'height');
+    assert.greaterThan(pixels, 0, 'pixels');
+    const theta = 2 / (height * Math.abs(projection[5]));
+    assert.isFinite(theta, 'pixel angle');
+    const ranges = Math.max(WATER_LOD_RANGE_RATIO_MIN, 1 / (WATER_LOD_MORPH_START * pixels * theta));
+    // a perspective projection writes −1 (or 1) into w from z; an orthographic one leaves w at 1
+    const orthographic = projection[11] === 0 ? 1 : 0;
+    let level = 0, distance = 0;
+    if (orthographic !== 0) {
+        // the coarsest cell no larger than the target
+        level = Math.min(WATER_LOD_LEVELS - 1, Math.max(0,
+            Math.floor(Math.log2(pixels * theta)) - WATER_LOD_FINEST_EXPONENT));
+        distance = 0.6 * ranges * 2 ** (level + WATER_LOD_FINEST_EXPONENT);
+    }
+    return { ranges, orthographic, level, distance, pixel: theta };
+}

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

@@ -0,0 +1,10 @@
+/**
+ * The distance LOD lattice (WATER_SURFACE_DISTANCE_LOD_PROPOSAL_2026_10_06.md §4.1) as pure functions of a view, a
+ * body and a point of the body's metric local xz. Selection, morph and footprint all derive from one distance, so the
+ * passes that choose cells and the vertex stage that draws them agree to the bit.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_water_lod: CodeChunk;
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_water_lod.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_water_lod.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/water/surface/lod/chunk_water_lod.js"],"names":[],"mappings":"AAUA;;;;;;GAMG;AACH,8BAFU,SAAS,CA+GoE;0BA9H7D,uCAAuC"}

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

@@ -0,0 +1,127 @@
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import {
+    WATER_LOD_BODY_STRUCT,
+    WATER_LOD_FINEST_EXPONENT,
+    WATER_LOD_LEVELS,
+    WATER_LOD_MORPH_START,
+    WATER_LOD_NODE_CELLS,
+    WATER_LOD_VIEW_STRUCT
+} from "./WATER_LOD.js";
+
+/**
+ * The distance LOD lattice (WATER_SURFACE_DISTANCE_LOD_PROPOSAL_2026_10_06.md §4.1) as pure functions of a view, a
+ * body and a point of the body's metric local xz. Selection, morph and footprint all derive from one distance, so the
+ * passes that choose cells and the vertex stage that draws them agree to the bit.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_water_lod = CodeChunk.from(/* language=WGSL */ `
+const WATER_LOD_LEVELS: u32 = ${WATER_LOD_LEVELS}u;
+const WATER_LOD_FINEST_EXPONENT: f32 = ${WATER_LOD_FINEST_EXPONENT}.0;
+const WATER_LOD_NODE_CELLS: i32 = ${WATER_LOD_NODE_CELLS};
+const WATER_LOD_QUADRANT_CELLS: i32 = ${WATER_LOD_NODE_CELLS / 2};
+const WATER_LOD_MORPH_START: f32 = ${WATER_LOD_MORPH_START};
+const WATER_LOD_COARSEST: u32 = ${WATER_LOD_LEVELS - 1}u;
+
+// Edge of a level's cells, metres: a power of two, so a lattice coordinate times it is exact in f32.
+fn water_lod_cell(level: u32) -> f32 {
+    return exp2(f32(level) + WATER_LOD_FINEST_EXPONENT);
+}
+
+fn water_lod_range(view: ${WATER_LOD_VIEW_STRUCT.wgsl_ref}, level: u32) -> f32 {
+    return view.ranges * water_lod_cell(level);
+}
+
+// The distance the lattice is chosen by: from the camera to the point horizontally, and to the body's rest height
+// range vertically. An orthographic view has one distance everywhere.
+fn water_lod_distance(view: ${WATER_LOD_VIEW_STRUCT.wgsl_ref}, body: ${WATER_LOD_BODY_STRUCT.wgsl_ref}, p: vec2<f32>) -> f32 {
+    if (view.orthographic != 0u) { return view.distance; }
+    let d = p - body.camera.xz;
+    return sqrt(dot(d, d) + body.vertical * body.vertical);
+}
+
+// The least distance over the square lo … hi of metric local xz.
+fn water_lod_nearest(view: ${WATER_LOD_VIEW_STRUCT.wgsl_ref}, body: ${WATER_LOD_BODY_STRUCT.wgsl_ref}, lo: vec2<f32>, hi: vec2<f32>) -> f32 {
+    if (view.orthographic != 0u) { return view.distance; }
+    let d = max(max(lo - body.camera.xz, body.camera.xz - hi), vec2<f32>(0.0));
+    return sqrt(dot(d, d) + body.vertical * body.vertical);
+}
+
+// The greatest distance over the square lo … hi.
+fn water_lod_farthest(view: ${WATER_LOD_VIEW_STRUCT.wgsl_ref}, body: ${WATER_LOD_BODY_STRUCT.wgsl_ref}, lo: vec2<f32>, hi: vec2<f32>) -> f32 {
+    if (view.orthographic != 0u) { return view.distance; }
+    let d = max(abs(lo - body.camera.xz), abs(hi - body.camera.xz));
+    return sqrt(dot(d, d) + body.vertical * body.vertical);
+}
+
+// Node n of a level: its corners in metric local xz.
+fn water_lod_node_lo(level: u32, node: vec2<i32>) -> vec2<f32> {
+    return vec2<f32>(node * WATER_LOD_NODE_CELLS) * water_lod_cell(level);
+}
+fn water_lod_node_hi(level: u32, node: vec2<i32>) -> vec2<f32> {
+    return vec2<f32>((node + vec2<i32>(1)) * WATER_LOD_NODE_CELLS) * water_lod_cell(level);
+}
+
+// Quadrant q (0 … 3, x then z) of a node: its first cell.
+fn water_lod_quadrant_origin(node: vec2<i32>, quadrant: u32) -> vec2<i32> {
+    return node * WATER_LOD_NODE_CELLS + vec2<i32>(i32(quadrant & 1u), i32(quadrant >> 1u)) * WATER_LOD_QUADRANT_CELLS;
+}
+
+// CDLOD's rule in closed form: a node exists at its level when it reaches into the level's range; the coarsest level
+// takes whatever is beyond every range.
+fn water_lod_node_exists(view: ${WATER_LOD_VIEW_STRUCT.wgsl_ref}, body: ${WATER_LOD_BODY_STRUCT.wgsl_ref}, level: u32, node: vec2<i32>) -> bool {
+    if (view.orthographic != 0u) { return level == view.level; }
+    if (level >= WATER_LOD_COARSEST) { return true; }
+    return water_lod_nearest(view, body, water_lod_node_lo(level, node), water_lod_node_hi(level, node)) <= water_lod_range(view, level);
+}
+
+// ... and an existing node's quadrant is drawn at its level unless all of it lies beyond the finer level's range.
+fn water_lod_quadrant_drawn(view: ${WATER_LOD_VIEW_STRUCT.wgsl_ref}, body: ${WATER_LOD_BODY_STRUCT.wgsl_ref}, level: u32, node: vec2<i32>, quadrant: u32) -> bool {
+    if (view.orthographic != 0u || level == 0u) { return true; }
+    let cell = water_lod_cell(level);
+    let lo = vec2<f32>(water_lod_quadrant_origin(node, quadrant)) * cell;
+    let hi = vec2<f32>(water_lod_quadrant_origin(node, quadrant) + vec2<i32>(WATER_LOD_QUADRANT_CELLS)) * cell;
+    return water_lod_nearest(view, body, lo, hi) > water_lod_range(view, level - 1u);
+}
+
+// How far a lattice point at this distance has slid towards the next level's grid, 0 … 1.
+fn water_lod_morph(view: ${WATER_LOD_VIEW_STRUCT.wgsl_ref}, level: u32, distance: f32) -> f32 {
+    if (view.orthographic != 0u || level >= WATER_LOD_COARSEST) { return 0.0; }
+    let range = water_lod_range(view, level);
+    return clamp((distance - WATER_LOD_MORPH_START * range) / ((1.0 - WATER_LOD_MORPH_START) * range), 0.0, 1.0);
+}
+
+// A lattice point of a level after its morph, metric local xz: an odd coordinate slides k cells down onto the even
+// one, k taken where the point would be unmorphed. Exact for k = 0 and k = 1, so where two levels meet the finer
+// one's points land on the coarser one's.
+fn water_lod_lattice_point(view: ${WATER_LOD_VIEW_STRUCT.wgsl_ref}, body: ${WATER_LOD_BODY_STRUCT.wgsl_ref}, level: u32, point: vec2<i32>) -> vec2<f32> {
+    let cell = water_lod_cell(level);
+    let k = water_lod_morph(view, level, water_lod_distance(view, body, vec2<f32>(point) * cell));
+    let odd = vec2<f32>(vec2<i32>(point.x & 1, point.y & 1));
+    return (vec2<f32>(point) - odd * k) * cell;
+}
+
+// The spacing the waves are filtered by at a vertex of a cell of this level, from the vertex's own position, so two
+// cells — of one level, or of two meeting levels where the finer is fully morphed and the coarser not at all — that
+// generate the same vertex filter it alike.
+fn water_lod_footprint(view: ${WATER_LOD_VIEW_STRUCT.wgsl_ref}, body: ${WATER_LOD_BODY_STRUCT.wgsl_ref}, level: u32, p: vec2<f32>) -> f32 {
+    return water_lod_cell(level) * (1.0 + water_lod_morph(view, level, water_lod_distance(view, body, p)));
+}
+
+// The levels that can draw points between these distances: a point drawn at level L lies beyond r_{L−1} and within
+// r_L + 16√2 s_L. (x: finest, y: coarsest, inclusive.)
+fn water_lod_level_span(view: ${WATER_LOD_VIEW_STRUCT.wgsl_ref}, nearest: f32, farthest: f32) -> vec2<u32> {
+    if (view.orthographic != 0u) { return vec2<u32>(view.level); }
+    let reach = view.ranges + f32(WATER_LOD_NODE_CELLS) * 1.41421356;
+    let finest = clamp(floor(log2(max(nearest, 1e-30) / reach)) - WATER_LOD_FINEST_EXPONENT, 0.0, f32(WATER_LOD_COARSEST));
+    let coarsest = clamp(ceil(log2(max(2.0 * farthest, 1e-30) / view.ranges)) - WATER_LOD_FINEST_EXPONENT, 0.0, f32(WATER_LOD_COARSEST));
+    return vec2<u32>(u32(finest), u32(max(finest, coarsest)));
+}
+
+// The finest footprint any vertex at least this far away can be drawn with.
+fn water_lod_footprint_min(view: ${WATER_LOD_VIEW_STRUCT.wgsl_ref}, nearest: f32) -> f32 {
+    if (view.orthographic != 0u) { return water_lod_cell(view.level); }
+    let reach = view.ranges + f32(WATER_LOD_NODE_CELLS) * 1.41421356;
+    return max(water_lod_cell(0u), nearest / reach);
+}
+`, [WATER_LOD_VIEW_STRUCT.declaration_chunk, WATER_LOD_BODY_STRUCT.declaration_chunk]);

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

@@ -0,0 +1,17 @@
+/**
+ * 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;
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_water_lod_cell.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_water_lod_cell.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/water/surface/lod/chunk_water_lod_cell.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;GAaG;AACH,mCAFU,SAAS,CAsOG;0BArPI,uCAAuC"}