@woosh/meep-engine 3.41.0 → 3.42.0

package/src/shade/renderer/water/medium/GPUWaterBodies.d.ts

@@ -1,15 +1,23 @@
-/** GPU work over the scene's water table; no per-body render commands or transient body uniforms. */
+/** A view's water bodies: which the view draws and how, and their meshlets in row order. */
 export class GPUWaterBodies {
-    record({ graph, scene }: {
-        graph: any;
-        scene: any;
-    }): void;
-    /** Ordered prefix expansion preserves equal-depth ownership, including after holes and reuse. */
-    meshlets({ graph, view, camera, meshlet_capacity }: {
+    /**
+     * Draw culling over the frame's visible list (WATER_SURFACE_DISTANCE_LOD_PROPOSAL_2026_10_06.md §4.3), each drawn
+     * body's lattice frame at its row, and the drawn bodies' meshlets. The expansion is an ordered prefix scan over the
+     * rows, which preserves equal-depth ownership, including after holes and reuse.
+     *
+     * @returns {{meshlets: number, lod_bodies: number}} resources
+     */
+    meshlets({ graph, view, camera, meshlet_capacity, visible_rows, lod, steep }: {
         graph: any;
         view: any;
         camera: any;
         meshlet_capacity: any;
-    }): any;
+        visible_rows: any;
+        lod: any;
+        steep: any;
+    }): {
+        meshlets: number;
+        lod_bodies: number;
+    };
 }
 //# sourceMappingURL=GPUWaterBodies.d.ts.map

package/src/shade/renderer/water/medium/GPUWaterBodies.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUWaterBodies.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/water/medium/GPUWaterBodies.js"],"names":[],"mappings":"AAUA,qGAAqG;AACrG;IACI;;;aASC;IAED,iGAAiG;IACjG;;;;;YAsCC;CACJ"}
+{"version":3,"file":"GPUWaterBodies.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/water/medium/GPUWaterBodies.js"],"names":[],"mappings":"AAcA,4FAA4F;AAC5F;IACI;;;;;;OAMG;IACH;;;;;;;;QAFa;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAC,CA8ClD;CACJ"}

package/src/shade/renderer/water/medium/GPUWaterBodies.js

@@ -1,42 +1,47 @@
 import { BufferResourceDescriptor } from "../../../device/graph/BufferResourceDescriptor.js";
 import { round_up } from "../../../../core/math/round_up.js";
 import { graph_prefix_scan_csdldf } from "../../gpu_primitive/prefix_sum/v1/graph_prefix_scan_csdldf.js";
-import { INDIRECT_COMPUTE_COMMAND_DESCRIPTOR } from "../../gpu_primitive/indirect/IndirectComputeCommandBuildPass.js";
+import {
+    build_indirect_compute_dispatch_command,
+    INDIRECT_COMPUTE_COMMAND_DESCRIPTOR
+} from "../../gpu_primitive/indirect/IndirectComputeCommandBuildPass.js";
 import { shader_prefix_sum_to_command } from "../../rasterize/expand/mesh/shader_prefix_sum_to_command.js";
 import { shader_increment_count_by_prefix_sum } from "../../rasterize/expand/mesh/shader_increment_count_by_prefix_sum.js";
 import { graph_compute_pass } from "../../shader/graph/compute/graph_compute_pass.js";
-import { shader_water_meshlet_counts, shader_water_meshlets_expand } from "./shader_water_meshlets.js";
-import { shader_water_bodies_derive, WORKGROUP_SIZE } from "./shader_water_bodies_derive.js";
+import { shader_water_meshlets_expand } from "./shader_water_meshlets.js";
+import { shader_water_lod_bodies } from "../surface/lod/shader_water_lod.js";
+import { WATER_LOD_BODY_STRUCT, WATER_LOD_VIEW_STRUCT } from "../surface/lod/WATER_LOD.js";
 
-/** GPU work over the scene's water table; no per-body render commands or transient body uniforms. */
+/** A view's water bodies: which the view draws and how, and their meshlets in row order. */
 export class GPUWaterBodies {
-    record({ graph, scene }) {
-        const table = scene.scene_database.get('water_bodies');
-        const groups = table.dispatch_group_count(WORKGROUP_SIZE);
-        if (groups === 0) { return; }
-        const pass = graph.add('Water / bodies derive', {}, (_data, _resources, { encoder }) => {
-            shader_water_bodies_derive.dispatch({ encoder, bindings: { scene_database: scene.scene_database_buffer },
-                group_count_x: Math.min(groups, 65535), group_count_y: Math.ceil(groups / 65535) });
-        });
-        pass.make_side_effect();
-    }
-
-    /** Ordered prefix expansion preserves equal-depth ownership, including after holes and reuse. */
-    meshlets({ graph, view, camera, meshlet_capacity }) {
+    /**
+     * Draw culling over the frame's visible list (WATER_SURFACE_DISTANCE_LOD_PROPOSAL_2026_10_06.md §4.3), each drawn
+     * body's lattice frame at its row, and the drawn bodies' meshlets. The expansion is an ordered prefix scan over the
+     * rows, which preserves equal-depth ownership, including after holes and reuse.
+     *
+     * @returns {{meshlets: number, lod_bodies: number}} resources
+     */
+    meshlets({ graph, view, camera, meshlet_capacity, visible_rows, lod, steep }) {
         const scene = view.scene, table = scene.scene_database.get('water_bodies');
-        const capacity = table.element_capacity;
+        const capacity = Math.max(table.element_capacity, 1);
         const data = {};
-        const pass = graph.add('Water / meshlet counts', data, (d, resources, { encoder }) => {
-            const groups = table.dispatch_group_count(64);
-            shader_water_meshlet_counts.dispatch({ encoder, bindings: {
-                capacity: round_up(capacity, 4), camera: resources.get(d.camera), scene_database: scene.scene_database_buffer,
-                geometries: scene.geometries.buffer_metadata, counts: resources.get(d.counts),
-            }, group_count_x: Math.min(groups, 65535), group_count_y: Math.ceil(groups / 65535) });
+        const pass = graph.add('Water / lod bodies', data, (d, resources, { encoder }) => {
+            const command = resources.get(d.command);
+            build_indirect_compute_dispatch_command(64, encoder, visible_rows, 0, command, 0, true);
+            shader_water_lod_bodies.dispatchIndirect({ encoder, command, bindings: {
+                capacity: round_up(capacity, 4), lod: encoder.allocateTransientValueBuffer(WATER_LOD_VIEW_STRUCT, lod),
+                camera: resources.get(d.camera), scene_database: scene.scene_database_buffer,
+                geometries: scene.geometries.buffer_metadata, visible_rows, steep,
+                lod_bodies: resources.get(d.lod_bodies), counts: resources.get(d.counts),
+            } });
         });
         data.camera = pass.read(camera);
         // The shared scan reads vec4u blocks, including the padded final block.
         const bytes = 16 + round_up(capacity, 4) * 4;
         data.counts = pass.create('counts', BufferResourceDescriptor.from(bytes, GPUBufferUsage.STORAGE, 0, bytes));
+        data.command = pass.create('Water lod bodies command', INDIRECT_COMPUTE_COMMAND_DESCRIPTOR);
+        data.lod_bodies = pass.create('Water lod bodies', BufferResourceDescriptor.from(capacity * WATER_LOD_BODY_STRUCT.size,
+            GPUBufferUsage.STORAGE));
         const sums = graph_prefix_scan_csdldf({ graph, data: data.counts, element_max_count: capacity });
         const command_data = {};
         const command_pass = graph.add('Water / expand command', command_data, (d, resources, { encoder }) => {
@@ -55,10 +60,10 @@ export class GPUWaterBodies {
         });
         expand_data.command = expand.read(command);
         expand_data.sums = expand.read(sums);
-        expand_data.output = expand.create('meshlets', BufferResourceDescriptor.from(16 + meshlet_capacity * 8,
+        expand_data.output = expand.create('meshlets', BufferResourceDescriptor.from(16 + Math.max(meshlet_capacity, 1) * 8,
             GPUBufferUsage.STORAGE, 0, 16));
         const { output } = graph_compute_pass({ graph, shader: shader_increment_count_by_prefix_sum,
             bindings: { prefix_sums: sums, output: expand_data.output } });
-        return output;
+        return { meshlets: output, lod_bodies: data.lod_bodies };
     }
 }

package/src/shade/renderer/water/medium/shader_water_meshlets.d.ts

@@ -1,4 +1,3 @@
-export const shader_water_meshlet_counts: ComputeShader;
 export const shader_water_meshlets_expand: ComputeShader;
 import { ComputeShader } from "../../shader/ComputeShader.js";
 //# sourceMappingURL=shader_water_meshlets.d.ts.map

package/src/shade/renderer/water/medium/shader_water_meshlets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_water_meshlets.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/water/medium/shader_water_meshlets.js"],"names":[],"mappings":"AAyBA,wDAsBkH;AAOlH,yDAcsF;8BAhExD,+BAA+B"}
+{"version":3,"file":"shader_water_meshlets.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/water/medium/shader_water_meshlets.js"],"names":[],"mappings":"AAgBA,yDAcsF;8BA3BxD,+BAA+B"}

package/src/shade/renderer/water/medium/shader_water_meshlets.js

@@ -1,4 +1,3 @@
-import { CAMERA_UNIFORM_STRUCT } from "../../camera/CAMERA_UNIFORM_STRUCT.js";
 import { GEOMETRY_METADATA_STRUCT } from "../../geometry/GEOMETRY_METADATA_STRUCT.js";
 import { MESHLET_COLLECTION_STRUCT } from "../../rasterize/MESHLET_COLLECTION_STRUCT.js";
 import { COLLECTION_U32_STRUCT_READ } from "../../gpu_primitive/COLLECTION_U32_STRUCT_READ.js";
@@ -6,46 +5,9 @@ import { ComputeShader } from "../../shader/ComputeShader.js";
 import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
 import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
 import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
-import { chunk_scene_database_access } from "../../scene/chunk_scene_database_access.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 { WATER_BODIES_TABLE as table, WATER_WAVES_TABLE } from "./chunk_water_bodies.js";
-import { chunk_aabb3_project } from "../../shader/chunk/geometry/aabb3/chunk_aabb3_project.js";
-import { chunk_aabb3_intersects_frustum } from "../../shader/chunk/geometry/aabb3/chunk_aabb3_intersects_frustum.js";
-import { chunk_array_to_aabb3 } from "../../shader/chunk/geometry/aabb3/chunk_array_to_aabb3.js";
-import { chunk_mat4_linear_determinant } from "../../shader/chunk/geometry/mat4/chunk_mat4_linear_determinant.js";
-import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-
-const pg = table.page_iterator_symbol_prefix(64);
-const counts_resources = new ShaderResourceSetDescriptor();
-counts_resources.setImmediate('capacity', u32);
-counts_resources.createGroup().addUniform('camera', CAMERA_UNIFORM_STRUCT)
-    .addStorageBuffer('scene_database', WebGPUArray.u32)
-    .addStorageBuffer('geometries', WebGPUArray.from(GEOMETRY_METADATA_STRUCT))
-    .addStorageBuffer('counts', COLLECTION_U32_STRUCT_READ, true);
-export const shader_water_meshlet_counts = ComputeShader.from({ label: 'Water / meshlet counts', resources: counts_resources,
-    body: CodeChunk.from(/* language=WGSL */ `
-@compute @workgroup_size(64)
-fn main(@builtin(workgroup_id) group: vec3u, @builtin(local_invocation_index) lane: u32) {
-    if (all(group == vec3u(0)) && lane == 0u) { counts.count = capacity; }
-    if (!${pg}_setup(&scene_database, folded_workgroup_index(group), lane)) { return; }
-    let slot = ${pg}_slot_in_page(lane);
-    if (slot >= ${pg}_ELEMENTS_PER_PAGE || !${pg}_is_occupied(slot)) { return; }
-    let body = ${pg}_read(&scene_database, slot);
-    let geometry = geometries[body.geometry];
-    let node = scene_read_node(&scene_database, body.node);
-    if (abs(mat4_linear_determinant(node.global)) < 1e-20) { return; }
-    var box = geometry.bounding_box;
-    if (body.wave != ~0u) {
-        let displacement = ${WATER_WAVES_TABLE.marshalling_method_read}(&scene_database, body.wave).displacement_bounds;
-        box[1] += displacement.x; box[4] += displacement.y;
-    }
-    let bounds = aabb3_project(array_to_aabb3(box), node.global);
-    if (!aabb3_intersects_frustum(bounds, camera.frustum)) { return; }
-    counts.elements[${pg}_slot_to_index(slot)] = geometry.meshlets_count;
-}
-`, [table.chunk_iterate(64), WATER_WAVES_TABLE.chunk_read, chunk_scene_database_access, chunk_folded_workgroup_index,
-    chunk_aabb3_project, chunk_array_to_aabb3, chunk_aabb3_intersects_frustum, chunk_mat4_linear_determinant]) });
+import { WATER_BODIES_TABLE as table } from "./chunk_water_bodies.js";
 
 const expand_resources = new ShaderResourceSetDescriptor();
 expand_resources.createGroup().addStorageBuffer('prefix_sums', COLLECTION_U32_STRUCT_READ)

package/src/shade/renderer/water/shader_water.d.ts

@@ -1,7 +1,6 @@
 export function create_water_pipeline(): RenderPipelineDescriptor;
 export function create_water_finalize_pipeline_ibl(): RenderPipelineDescriptor;
 export function create_water_finalize_pipeline_brick4(): RenderPipelineDescriptor;
-export const WATER_GRID_STRUCT: WebGPUStruct;
 export const WATER_TRACE_STRUCT: WebGPUStruct;
 /** Optics under IBL (and LPV, which has no transparent variant): the lights and the environment. */
 export const WATER_FINALIZE_RESOURCES_IBL: ShaderResourceSetDescriptor;

package/src/shade/renderer/water/shader_water.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_water.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/water/shader_water.js"],"names":[],"mappings":"AAueA,kEAAuH;AACvH,+EAA+J;AAC/J,kFAAqK;AAlcrK,6CAAqF;AAErF,8CAKwB;AA0BxB,oGAAoG;AACpG,uEAAkE;AAGlE,gGAAgG;AAChG,0EAAqE;AAkHrE,+CA+EmB;AA2LnB,4CAAmG;AACnG,kFAAkF;AAClF,yDAC8G;AAC9G,oCAAoC;AACpC,4DACoH;AACpH,0DAAyC;yCA9cA,8DAA8D;6BAmB1E,gCAAgC;4CAJjB,mDAAmD;0BADrE,iCAAiC;iCAE1B,+BAA+B"}
+{"version":3,"file":"shader_water.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/water/shader_water.js"],"names":[],"mappings":"AAwmBA,kEAAuH;AACvH,+EAA+J;AAC/J,kFAAqK;AA/jBrK,8CAKwB;AAiCxB,oGAAoG;AACpG,uEAAkE;AAGlE,gGAAgG;AAChG,0EAAqE;AAqOrE,+CA+EmB;AA6LnB,4CAAmG;AACnG,kFAAkF;AAClF,yDAC8G;AAC9G,oCAAoC;AACpC,4DACoH;AACpH,0DAAyC;yCA5kBA,8DAA8D;6BAmB1E,gCAAgC;4CAJjB,mDAAmD;0BADrE,iCAAiC;iCAE1B,+BAA+B"}

package/src/shade/renderer/water/shader_water.js

@@ -25,8 +25,12 @@ import { chunk_water_gi_brick4, chunk_water_gi_ibl } from "./chunk_water_gi.js";
 import { WATER_BODIES_TABLE, WATER_WAVES_TABLE } from "./medium/chunk_water_bodies.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 { chunk_lower_bound_branchless } from "../shader/chunk/math/chunk_lower_bound_branchless.js";
-import { chunk_water_tessellation, WATER_TILE_STRUCT, WATER_TESSELLATION_STRUCT, WATER_TILE_CELLS } from "./surface/chunk_water_tessellation.js";
+import { chunk_water_surface_sample } from "./surface/chunk_water_surface_sample.js";
+import { WATER_PARTICLE_ENTRY_STRUCT } from "./surface/particles/WATER_PARTICLE_STRUCT.js";
+import { WATER_LOD_BODY_STRUCT, WATER_LOD_VIEW_STRUCT, WaterLodMode } from "./surface/lod/WATER_LOD.js";
+import { chunk_water_lod_candidate, chunk_water_lod_layout, WATER_LOD_BOUNDARY_FIRST_VERTEX, WATER_LOD_CANDIDATE_STRUCT,
+    WATER_LOD_CELL_LOCAL_BITS, WATER_LOD_LIMITS_STRUCT, WATER_LOD_PATCH_FIRST_VERTEX, WATER_LOD_PATCH_SIDE, WATER_LOD_POLYGON_WORDS,
+    WATER_LOD_TRIANGLE_FIRST_VERTEX, WaterLodList } from "./surface/lod/shader_water_lod.js";
 import { chunk_read_meshlet_vertex_by_draw_index } from "../shader/chunk/geometry/meshlet/chunk_read_meshlet_vertex_by_draw_index.js";
 import { chunk_scene_database_access } from "../scene/chunk_scene_database_access.js";
 import { chunk_mat3_inverse } from "../shader/chunk/geometry/mat3/chunk_mat3_inverse.js";
@@ -37,8 +41,6 @@ import { chunk_water_optics } from "./optics/chunk_water_optics.js";
 import { chunk_water_receiver_radiance, chunk_water_receiver_texel, chunk_water_refraction_confidence,
     chunk_water_transport, WATER_LEVEL_TOLERANCE_DECLARATION } from './chunk_water_transport.js';
 
-export const WATER_GRID_STRUCT = WebGPUStruct.from({ resolution: u32 }, 'WaterGrid');
-
 export const WATER_TRACE_STRUCT = WebGPUStruct.from({
     max_distance: f32, distance_tolerance: f32, max_updates: u32, fallback_steps: u32,
     mode: u32, reflections: u32,
@@ -56,13 +58,20 @@ function water_resources(finalize = false) {
         .addTexture("tHZB")
         .addTexture("tScene")
         .addStorageBuffer('scene_database', WebGPUArray.u32)
-        .addStorageBuffer('water_tiles', WebGPUArray.from(WATER_TILE_STRUCT))
-        .addStorageBuffer('water_tile_sums', COLLECTION_U32_STRUCT_READ)
-        .addUniform('tessellation', WATER_TESSELLATION_STRUCT)
+        // the view's lattice (WATER_SURFACE_DISTANCE_LOD_PROPOSAL_2026_10_06.md §4.3)
+        .addUniform('lod', WATER_LOD_VIEW_STRUCT)
+        .addUniform('lod_limits', WATER_LOD_LIMITS_STRUCT)
+        .addStorageBuffer('water_lod_bodies', WebGPUArray.from(WATER_LOD_BODY_STRUCT))
+        .addStorageBuffer('water_lod_candidates', WebGPUArray.from(WATER_LOD_CANDIDATE_STRUCT))
+        .addStorageBuffer('water_lod_cells', WebGPUArray.u32)
         .addStorageBuffer('meshlet_metadata', WebGPUArray.from(MESHLET_METADATA_STRUCT))
         .addStorageBuffer('meshlet_data', WebGPUArray.from(f32))
-        .addStorageBuffer('wave_state', WebGPUArray.from(f32))
-        .addUniform('wave_grid', WATER_GRID_STRUCT);
+        // the surface interface: the spectral bands and the frame's binned wave particles
+        .addTexture('water_band_displacement', 'float', '2d-array')
+        .addTexture('water_band_derivatives', 'float', '2d-array')
+        .addSampler('water_band_sampler')
+        .addStorageBuffer('water_particle_offsets', COLLECTION_U32_STRUCT_READ)
+        .addStorageBuffer('water_particle_entries', WebGPUArray.from(WATER_PARTICLE_ENTRY_STRUCT));
     if (finalize) {
         group.addTexture('receiver').addTexture('trace_metadata').addTexture('visibility_distance');
     }
@@ -88,79 +97,194 @@ struct WaterVertexOut {
     // makes the position bit-identical across programs.
     @invariant @builtin(position) clip: vec4<f32>,
     @location(0) world: vec3<f32>,
+    // the normal of the waves the mesh carries
     @location(1) normal: vec3<f32>,
-    // slope variance of the waves the surface's mesh does not resolve
+    // slope variance of the wave packets the mesh does not resolve; the bands' is the pixel's to work out
     @location(2) unresolved_variance: f32,
     @location(3) @interpolate(flat) body_index: u32,
     @location(4) rest_normal: vec3<f32>,
+    // where on the body's rest surface this is, metric local xz, and the footprint its waves were filtered to there:
+    // what the pixel samples the bands the mesh could not carry at; 0 where no waves move the surface
+    @location(5) metric: vec2<f32>,
+    @location(6) footprint: f32,
+    @location(7) @interpolate(flat) wave: u32,
+    // the body's metric x and z axes in the world, to tilt the normal along
+    @location(8) @interpolate(flat) axis_x: vec3<f32>,
+    @location(9) @interpolate(flat) axis_z: vec3<f32>,
+    // the metres a pixel spans on the rest surface: its distance times its angle, stretched where the surface is seen
+    // at a slant (the mean of its two axes)
+    @location(10) pixel_footprint: f32,
+}
+
+fn water_vertex_out_none(body_index: u32) -> WaterVertexOut {
+    return WaterVertexOut(vec4f(0, 0, 0, 1), vec3f(0), vec3f(0, 1, 0), 0.0, body_index, vec3f(0, 1, 0), vec2f(0), 0.0, 0u,
+        vec3f(1, 0, 0), vec3f(0, 0, 1), 0.0);
+}
+
+struct WaterPixelSurface {
+    normal: vec3<f32>,
+    variance: f32,
+}
+
+// The surface a pixel shades: the mesh's normal tilted by the bands the pixel resolves and the mesh could not carry;
+// the slope variance of the bands neither resolves, and of the packets the mesh did not draw.
+fn water_pixel_surface(in: WaterVertexOut, pixel_footprint: f32) -> WaterPixelSurface {
+    if (!(in.footprint > 0.0)) { return WaterPixelSurface(in.normal, in.unresolved_variance); }
+    let detail = water_surface_detail(in.wave, in.metric, in.footprint, pixel_footprint);
+    let normal = normalize(in.normal - detail.slope.x * in.axis_x - detail.slope.y * in.axis_z);
+    return WaterPixelSurface(normal, in.unresolved_variance + detail.variance);
+}
+
+// The rest point a vertex of the view's lattice stands for, and how it is drawn.
+struct WaterLodVertex {
+    // local units
+    rest: WaterLodRest,
+    // metric local xz, where the waves are sampled
+    metric: vec2<f32>,
+    // metres between samples the waves are filtered to; 0 for a vertex the waves do not move
+    footprint: f32,
+    present: bool,
 }
 
-fn water_wave_height(row: u32, cell: vec2i) -> f32 {
-    let n = i32(wave_grid.resolution);
-    let c = clamp(cell, vec2i(0), vec2i(n - 1));
-    return wave_state[row * u32(n * n) + u32(c.y * n + c.x)];
+const WATER_LOD_QUAD: array<u32, 6> = array<u32, 6>(0u, 1u, 2u, 0u, 2u, 3u);
+const WATER_LOD_QUAD_REVERSED: array<u32, 6> = array<u32, 6>(0u, 2u, 1u, 0u, 3u, 2u);
+
+// A lattice point of a cell drawn whole: on the triangle's surface, along an authored edge where it lies on one.
+fn water_lod_whole_point(level: u32, point: vec2<i32>, frame: ${WATER_LOD_BODY_STRUCT.wgsl_ref}, tri: WaterLodTriangle) -> WaterLodVertex {
+    var out: WaterLodVertex;
+    let p = water_lod_lattice_point(lod, frame, level, point);
+    out.rest = water_lod_rest(tri, water_lod_edge_bits(tri, p), p, frame.scale);
+    out.metric = p;
+    out.footprint = water_lod_footprint(lod, frame, level, p);
+    out.present = true;
+    return out;
+}
+
+fn water_lod_vertex(list: u32, corner: u32, candidate: ${WATER_LOD_CANDIDATE_STRUCT.wgsl_ref}, place: u32,
+    frame: ${WATER_LOD_BODY_STRUCT.wgsl_ref}, tri: WaterLodTriangle, mirrored: bool, polygon: vec2<u32>) -> WaterLodVertex {
+    var out: WaterLodVertex;
+    let packed = candidate.packed;
+    if (list == ${WaterLodList.Triangle}u) {
+        // the authored triangle itself, wound as authored
+        let k = select(corner, 2u - corner, mirrored);
+        out.rest = WaterLodRest(tri.local[k], tri.normal[k]);
+        out.metric = tri.p[k];
+        out.present = true;
+        return out;
+    }
+    let level = water_lod_candidate_level(packed);
+    if (place >= 256u) { return out; }
+    // the cell's place in its node: quadrant · 64 + row · 8 + column
+    let cell = water_lod_quadrant_origin(candidate.node, place >> 6u) + vec2<i32>(i32(place & 7u), i32((place >> 3u) & 7u));
+    // a cell's corners run counter-clockwise from x towards z; the authored triangle may run the other way, and a
+    // mirroring placement turns both
+    let reversed = tri.ccw == mirrored;
+    if (list == ${WaterLodList.Patch}u) {
+        // the patch's indices run its points row by row; read across instead, they turn every cell the other way
+        var grid = vec2<i32>(i32(corner % ${WATER_LOD_PATCH_SIDE}u), i32(corner / ${WATER_LOD_PATCH_SIDE}u));
+        if (reversed) { grid = grid.yx; }
+        return water_lod_whole_point(level, cell + grid, frame, tri);
+    }
+    if (list == ${WaterLodList.Interior}u) {
+        let k = select(WATER_LOD_QUAD[corner], WATER_LOD_QUAD_REVERSED[corner], reversed);
+        return water_lod_whole_point(level, cell + vec2<i32>(i32(k == 1u || k == 2u), i32(k >= 2u)), frame, tri);
+    }
+    // a boundary cell's point, rebuilt from what the cells pass found it to lie on
+    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 fan = corner / 3u;
+    let at = corner % 3u;
+    var index = 0u;
+    if (at != 0u) { index = select(fan + at, fan + 3u - at, reversed); }
+    let bits = water_lod_polygon_bits(polygon, index);
+    out.metric = water_lod_point(tri, corners, bits);
+    out.rest = water_lod_rest(tri, bits, out.metric, frame.scale);
+    out.footprint = water_lod_footprint(lod, frame, level, out.metric);
+    out.present = true;
+    return out;
 }
 
-// One instance per occupied view tile and source triangle. All overlap candidates survive
-// classification; receiver depth selects the nearest displaced interface.
+// One instance a record of one of the view's lists; the list is told by the draw's first vertex.
 @vertex
 fn vs_main(@builtin(vertex_index) vi: u32, @builtin(instance_index) ii: u32) -> WaterVertexOut {
-    let row = lower_bound_branchless(&water_tile_sums.elements, ii + 1u, water_tile_sums.count);
-    let definition = water_tiles[row];
-    let body = ${WATER_BODIES_TABLE.marshalling_method_read}(&scene_database, definition.body);
-    let header = meshlet_metadata[definition.meshlet];
+    var list = ${WaterLodList.Interior}u;
+    var corner = vi;
+    var candidate: ${WATER_LOD_CANDIDATE_STRUCT.wgsl_ref};
+    var place = 0u;
+    var polygon = vec2<u32>(0u);
+    if (vi >= ${WATER_LOD_PATCH_FIRST_VERTEX}u) {
+        // a patch: its candidate and its quadrant's first cell; the index names the point
+        list = ${WaterLodList.Patch}u; corner = vi - ${WATER_LOD_PATCH_FIRST_VERTEX}u;
+        let record = water_lod_cells[water_lod_patches_base(lod_limits) + ii];
+        candidate = water_lod_candidates[record >> ${WATER_LOD_CELL_LOCAL_BITS}u];
+        place = record & ${(1 << WATER_LOD_CELL_LOCAL_BITS) - 1}u;
+    } else if (vi >= ${WATER_LOD_TRIANGLE_FIRST_VERTEX}u) {
+        // a triangle drawn as itself: its meshlet, then its body row and its triangle
+        list = ${WaterLodList.Triangle}u; corner = vi - ${WATER_LOD_TRIANGLE_FIRST_VERTEX}u;
+        let at = water_lod_triangles_base(lod_limits) + 2u * ii;
+        candidate.meshlet = water_lod_cells[at];
+        candidate.body = water_lod_cells[at + 1u] >> 7u;
+        candidate.packed = water_lod_cells[at + 1u] & 127u;
+    } else {
+        var base = 0u;
+        if (vi >= ${WATER_LOD_BOUNDARY_FIRST_VERTEX}u) {
+            list = ${WaterLodList.Boundary}u; corner = vi - ${WATER_LOD_BOUNDARY_FIRST_VERTEX}u; base = lod_limits.interior;
+            // a fan triangle past the cell's polygon draws nothing, decided before anything else is read
+            let at = water_lod_polygons_base(lod_limits) + ${WATER_LOD_POLYGON_WORDS}u * ii;
+            polygon = vec2<u32>(water_lod_cells[at], water_lod_cells[at + 1u]);
+            if (water_lod_polygon_count(polygon) < corner / 3u + 3u) { return water_vertex_out_none(0u); }
+        }
+        let record = water_lod_cells[base + ii];
+        candidate = water_lod_candidates[record >> ${WATER_LOD_CELL_LOCAL_BITS}u];
+        place = record & ${(1 << WATER_LOD_CELL_LOCAL_BITS) - 1}u;
+    }
+    let body = ${WATER_BODIES_TABLE.marshalling_method_read}(&scene_database, candidate.body);
+    let frame = water_lod_bodies[candidate.body];
     let node = scene_read_node(&scene_database, body.node);
-    var previous = 0u;
-    if (row > 0u) { previous = water_tile_sums.elements[row - 1u]; }
-    let patch_index = ii - previous;
-    let tile = definition.origin + vec2i(i32(patch_index % definition.size.x), i32(patch_index / definition.size.x));
-    let cell = vi / 18u;
-    let lattice = tile * ${WATER_TILE_CELLS} + vec2i(i32(cell % ${WATER_TILE_CELLS}u), i32(cell / ${WATER_TILE_CELLS}u));
-    let pixel = vec2f(lattice) * definition.pixels;
-    let ndc0 = pixel / tessellation.resolution * vec2f(2,-2) + vec2f(-1,1);
-    // Form both endpoints from their integer lattice coordinate. Adding the pitch to
-    // an already rounded pixel coordinate gives neighbouring cells different edges.
-    let ndc1 = (vec2f(lattice + vec2i(1)) * definition.pixels) / tessellation.resolution * vec2f(2,-2) + vec2f(-1,1);
-    let a = read_meshlet_vertex_by_draw_index(header, definition.triangle * 3u);
-    let b = read_meshlet_vertex_by_draw_index(header, definition.triangle * 3u + 1u);
-    let c = read_meshlet_vertex_by_draw_index(header, definition.triangle * 3u + 2u);
-    let simulated = body.wave != ~0u;
-    let ca = tessellation.view_projection_matrix * (node.global * vec4f(water_reference_position(a.position, definition.anchor, simulated), 1));
-    let cb = tessellation.view_projection_matrix * (node.global * vec4f(water_reference_position(b.position, definition.anchor, simulated), 1));
-    let cc = tessellation.view_projection_matrix * (node.global * vec4f(water_reference_position(c.position, definition.anchor, simulated), 1));
-    let polygon = water_cell_polygon(ca, cb, cc, min(ndc0,ndc1), max(ndc0,ndc1));
-    let fan = (vi % 18u) / 3u;
-    if (polygon.count < fan + 3u) { return WaterVertexOut(vec4f(0,0,0,1),vec3f(0),vec3f(0,1,0),0,definition.body,vec3f(0,1,0)); }
-    let corner = select(vi % 3u, 2u - vi % 3u, (node.global_flags & ${NODE3D_GLOBAL_FLAG_MIRRORED}u) != 0u);
-    var index = 0u;
-    if (corner != 0u) { index = fan + corner; }
-    let barycentric = polygon.points[index];
-    var position = water_corner_position(a.position,b.position,c.position,ca,cb,cc,barycentric,
-        polygon.boundaries[index],min(ndc0,ndc1),max(ndc0,ndc1));
-    var normal = normalize(a.normal * barycentric.x + b.normal * barycentric.y + c.normal * barycentric.z);
+    let header = meshlet_metadata[candidate.meshlet];
+    let triangle = water_lod_candidate_triangle(candidate.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 mirrored = (node.global_flags & ${NODE3D_GLOBAL_FLAG_MIRRORED}u) != 0u;
+    let vertex = water_lod_vertex(list, corner, candidate, place, frame, tri, mirrored, polygon);
+    if (!vertex.present) { return water_vertex_out_none(candidate.body); }
+    var position = vertex.rest.position;
+    var normal = normalize(vertex.rest.normal);
     let rest_normal = normal;
     var variance = 0.0;
-    if (body.wave != ~0u) {
-        let params = ${WATER_WAVES_TABLE.marshalling_method_read}(&scene_database, body.wave);
-        let spacing = max((params.extent.zw - params.extent.xy) / f32(wave_grid.resolution - 1u), vec2f(1e-20));
-        let grid = clamp((position.xz - params.extent.xy) / spacing, vec2f(0.0), vec2f(f32(wave_grid.resolution - 1u)));
-        let cell = vec2i(grid);
-        let blend = fract(grid);
-        let h00 = water_wave_height(body.wave, cell);
-        let h10 = water_wave_height(body.wave, cell + vec2i(1, 0));
-        let h01 = water_wave_height(body.wave, cell + vec2i(0, 1));
-        let h11 = water_wave_height(body.wave, cell + vec2i(1, 1));
-        position.y += mix(mix(h00, h10, blend.x), mix(h01, h11, blend.x), blend.y);
-        let slope = vec2f(mix(h10 - h00, h11 - h01, blend.y), mix(h01 - h00, h11 - h10, blend.x)) / spacing;
+    var footprint = 0.0;
+    if (frame.mode != ${WaterLodMode.Hidden}u && any(frame.bounds != vec2<f32>(0.0))) {
+        // a vertex the waves do not move carries none of them: its pixels shade what they resolve
+        footprint = select(1e30, vertex.footprint, vertex.footprint > 0.0);
+        let sum = water_surface_sum(body.wave, vertex.metric, footprint);
+        let surface = water_surface_finish(sum, 1.0);
+        // the metric frame's normal in the local frame is S·n
+        let tilted = surface.normal * frame.scale;
+        let slope = -tilted.xz / tilted.y;
+        if (vertex.footprint > 0.0) { position += surface.offset / frame.scale; }
         normal = normalize(vec3f(normal.x - normal.y * slope.x, normal.y, normal.z - normal.y * slope.y));
-        variance = params.unresolved_variance;
+        if (vertex.footprint <= 0.0) { normal = rest_normal; }
+        variance = sum.particle_variance;
     }
     let world = (node.global * vec4f(position, 1.0)).xyz;
     let linear = mat3x3f(node.global[0].xyz, node.global[1].xyz, node.global[2].xyz);
     let inverse_transpose = transpose(mat3_inverse(linear));
     let normal_ws = normalize(inverse_transpose * normal);
     let rest_normal_ws = normalize(inverse_transpose * rest_normal);
-    return WaterVertexOut(camera.view_projection_matrix * vec4f(world, 1.0), world, normal_ws, variance, definition.body,rest_normal_ws);
+    // a pixel's footprint on the rest surface: distance times angle (an orthographic pixel's own size) across the view,
+    // that over the cosine at which the surface is seen along it; their geometric mean, as anisotropic filtering takes
+    let to_eye = camera.view_matrix_inverse[3].xyz - world;
+    let orthographic = lod.orthographic != 0u;
+    let across = select(length(to_eye) * lod.pixel, lod.pixel, orthographic);
+    let view = select(normalize(to_eye), normalize(camera.view_matrix_inverse[2].xyz), orthographic);
+    let pixel_footprint = across / sqrt(max(abs(dot(view, rest_normal_ws)), 0.05));
+    return WaterVertexOut(camera.view_projection_matrix * vec4f(world, 1.0), world, normal_ws, variance, candidate.body, rest_normal_ws,
+        vertex.metric, footprint, body.wave, normalize(node.global[0].xyz), normalize(node.global[2].xyz), pixel_footprint);
 }
 
 // The interface at one water fragment, in view space. Receivers trace through it and optics
@@ -185,9 +309,9 @@ fn water_interface(world: vec3<f32>, surface_normal: vec3<f32>, ior: f32, above:
     return WaterInterface(origin, normalize(origin), normalize(direction_world_to_view(normal_ws, camera)),
         max(ior, 1.0), min(max(trace.max_distance, 0.1), camera.clip_near_far.y));
 }
-`, [chunk_direction_world_to_view, WATER_BODIES_TABLE.chunk_read, WATER_WAVES_TABLE.chunk_read,
-    chunk_read_meshlet_vertex_by_draw_index, chunk_scene_database_access, chunk_mat3_inverse,
-    chunk_lower_bound_branchless, chunk_water_tessellation]);
+`, [chunk_direction_world_to_view, WATER_BODIES_TABLE.chunk_read, chunk_read_meshlet_vertex_by_draw_index,
+    chunk_scene_database_access, chunk_mat3_inverse, chunk_water_lod_candidate, chunk_water_lod_layout,
+    WATER_LOD_CANDIDATE_STRUCT.declaration_chunk, chunk_water_surface_sample]);
 
 export const chunk_water_screen_ray = CodeChunk.from(/* language=WGSL */ `
 fn water_hzb_mip_size(depth_size: vec2f, hzb_size: vec2f, mip: i32) -> vec2f {
@@ -287,6 +411,7 @@ fn water_receiver_submerged(uv: vec2f, surface: vec3f, normal: vec3f) -> bool {
 
 @fragment
 fn fs_main(in: WaterVertexOut, @builtin(front_facing) above: bool) -> WaterReceiver {
+    let pixel = water_pixel_surface(in, in.pixel_footprint);
     let water = ${WATER_BODIES_TABLE.marshalling_method_read}(&scene_database, in.body_index);
     let coord = vec2<i32>(in.clip.xy);
     let dimensions = vec2f(textureDimensions(tDepth, 0));
@@ -305,7 +430,7 @@ fn fs_main(in: WaterVertexOut, @builtin(front_facing) above: bool) -> WaterRecei
         water_depth = abs(dot(in.world - (camera.view_matrix_inverse * vec4f(behind_vs, 1.0)).xyz, normalize(in.rest_normal)));
     }
     let coverage = smoothstep(0.0, 0.1, water_depth);
-    let surface = water_interface(in.world, in.normal, water.ior, above);
+    let surface = water_interface(in.world, pixel.normal, water.ior, above);
     let interface_normal = direction_view_to_world(surface.normal, camera);
     let limit = surface.limit;
     let direction = refract(surface.incident, surface.normal, 1.0 / surface.ior);
@@ -364,6 +489,7 @@ struct WaterOptics {
 }
 @fragment
 fn fs_main(in: WaterVertexOut, @builtin(front_facing) above: bool) -> WaterOptics {
+    let pixel = water_pixel_surface(in, in.pixel_footprint);
     let water = ${WATER_BODIES_TABLE.marshalling_method_read}(&scene_database, in.body_index);
     let coord = vec2i(in.clip.xy);
     let metadata = textureLoad(trace_metadata, coord, 0);
@@ -372,7 +498,7 @@ fn fs_main(in: WaterVertexOut, @builtin(front_facing) above: bool) -> WaterOptic
     let dimensions = vec2f(textureDimensions(tDepth, 0));
     let uv = in.clip.xy / dimensions;
     let receiver_data = textureLoad(receiver, coord, 0);
-    let surface = water_interface(in.world, in.normal, water.ior, above);
+    let surface = water_interface(in.world, pixel.normal, water.ior, above);
     let interface_normal = direction_view_to_world(surface.normal, camera);
     let body = water;
     let origin = surface.origin;
@@ -384,7 +510,7 @@ fn fs_main(in: WaterVertexOut, @builtin(front_facing) above: bool) -> WaterOptic
     let reflection_direction = reflect(surface.incident, surface.normal);
     // a reflection that misses on screen falls back to the GI mode, as SSR's resolve does
     var reflection = water_gi_specular(in.world, direction_view_to_world(surface.normal, camera),
-        direction_view_to_world(-surface.incident, camera), clamp(sqrt(water.roughness * water.roughness + in.unresolved_variance), 0.0, 1.0));
+        direction_view_to_world(-surface.incident, camera), clamp(sqrt(water.roughness * water.roughness + pixel.variance), 0.0, 1.0));
     if (trace.reflections != 0u && above) {
         let reflected = water_hzb_hit(Ray(ray_at(origin, reflection_direction, 0.02), reflection_direction, limit),
             trace.fallback_steps);
@@ -468,12 +594,15 @@ export const WATER_RESOURCES = resources;
 function water_pipeline(shader, targets, finalize) {
     const code = shader.source;
     const layout = shader.resources.generatePipelineLayout(GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT);
-    // Tile reconstruction spends six storage slots. Lighting spends four in the fragment stage.
-    // Keep their visibility precise so the Brick4 variant fits the guaranteed stage budget.
-    const vertex_only = new Set(['water_tiles', 'water_tile_sums', 'tessellation', 'meshlet_metadata', 'meshlet_data', 'wave_state', 'wave_grid']);
+    // The lattice spends eight storage slots in the vertex stage, the guaranteed budget. Lighting spends four in the
+    // fragment stage. Keep their visibility precise so the Brick4 variant fits it there.
+    const vertex_only = new Set(['lod', 'lod_limits', 'water_lod_bodies', 'water_lod_candidates', 'water_lod_cells',
+        'meshlet_metadata', 'meshlet_data', 'water_band_displacement', 'water_particle_offsets', 'water_particle_entries']);
+    // the fragment stage shades the bands the mesh could not carry
+    const both = new Set(['camera', 'scene_database', 'water_band_derivatives', 'water_band_sampler']);
     shader.resources.groups.forEach((group, gi) => group.resources.forEach((resource, ri) => {
         layout.bindGroupLayouts[gi].entries[ri].visibility = vertex_only.has(resource.name) ? GPUShaderStage.VERTEX
-            : resource.name === 'camera' || resource.name === 'scene_database' ? GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT
+            : both.has(resource.name) ? GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT
             : GPUShaderStage.FRAGMENT;
     }));
     return RenderPipelineDescriptor.from({