@woosh/meep-engine 3.40.0 → 3.42.0

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({

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

@@ -0,0 +1,70 @@
+/** Times of its loop the bands are evaluated at once, on a device's first frame with wind, to seed their envelopes. */
+export const WATER_ENVELOPE_SEED_TIMES: 32;
+/** How the surface sampler reads the band tiles: filtered, and periodic. */
+export const WATER_BAND_SAMPLER: Readonly<SamplerDescriptor>;
+/**
+ * The water surface producer (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §3), scheduled by what the frame's view
+ * sees (WATER_SURFACE_DISTANCE_LOD_PROPOSAL_2026_10_06.md §3): a culling pass over every body, then the shared
+ * spectral bands the visible bodies can draw, the wave particles of the bodies simulated this frame, and their
+ * bounds. Recorded once a frame at the head of the frame. What the surface passes bind of it is the surface
+ * interface: the band textures, the particle hash, and the rows.
+ */
+export class GPUWaterSurface {
+    /** Dispatched with the scene when a frame that emitted the queued splashes is submitted. */
+    onInputsConsumed: Signal;
+    /** Most wave particles alive at once over every body of a scene. */
+    particle_capacity: number;
+    /** Whether any body has wind; without it the band tiles are not animated. */
+    windy: boolean;
+    /**
+     * Whether any splash was ever queued. Until one is, the pool is empty and no particle pass is recorded; set by
+     * whoever queues splashes.
+     */
+    splashed: boolean;
+    get displacement(): GPUTextureView;
+    get derivatives(): GPUTextureView;
+    get particle_offsets(): GPUBuffer;
+    get particle_entries(): GPUBuffer;
+    /** @returns {GPUBuffer} per wave row, set by the tessellation when a body has a triangle too steep to displace */
+    get steep(): GPUBuffer;
+    /** @returns {GPUBuffer} per wave row, the culling pass's {@link WaterActivity} bits for the frame */
+    get activity(): GPUBuffer;
+    /** @returns {GPUBuffer} the water_bodies rows the frame's culling pass found visible: a count, then the rows */
+    get visible_rows(): GPUBuffer;
+    get particles(): GPUWaterParticles;
+    /**
+     * Seconds of water time to step at the next recorded frame.
+     * @param {number} dt
+     */
+    advance(dt: number): void;
+    dispose(): void;
+    /**
+     * @param {object} options
+     * @param {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} options.graph
+     * @param {GPUDevice} options.device
+     * @param {object} options.scene GPU scene context
+     * @param {number} options.time water time, seconds
+     * @param {object} options.view the view the frame is recorded for
+     * @param {GPUBuffer} options.view.camera its camera uniforms
+     * @param {ArrayLike<number>} options.view.projection its projection, column-major
+     * @param {number} options.view.height its render target's height, pixels
+     * @param {number} options.pixels the smallest a lattice cell is drawn on screen
+     */
+    record({ graph, device, scene, time, view, pixels }: {
+        graph: import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
+        device: GPUDevice;
+        scene: object;
+        time: number;
+        view: {
+            camera: GPUBuffer;
+            projection: ArrayLike<number>;
+            height: number;
+        };
+        pixels: number;
+    }): void;
+    #private;
+}
+import { SamplerDescriptor } from "../../../descriptor/texture/SamplerDescriptor.js";
+import Signal from "../../../../core/events/signal/Signal.js";
+import { GPUWaterParticles } from "./particles/GPUWaterParticles.js";
+//# sourceMappingURL=GPUWaterSurface.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"GPUWaterSurface.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/water/surface/GPUWaterSurface.js"],"names":[],"mappings":"AAmBA,uHAAuH;AACvH,2CAA4C;AAE5C,4EAA4E;AAC5E,6DAKI;AAEJ;;;;;;GAMG;AACH;IACI,4FAA4F;IAC5F,yBAAgC;IAChC,oEAAoE;IACpE,0BAA0B;IAC1B,6EAA6E;IAC7E,eAAc;IACd;;;OAGG;IACH,kBAAiB;IAejB,mCAA0D;IAC1D,kCAAwD;IACxD,kCAA0D;IAC1D,kCAA0D;IAC1D,kHAAkH;IAClH,uBAAmC;IACnC,qGAAqG;IACrG,0BAAyC;IACzC,gHAAgH;IAChH,8BAA2D;IAC3D,mCAA2C;IAE3C;;;OAGG;IACH,YAFW,MAAM,QAKhB;IAED,gBAWC;IAsBD;;;;;;;;;;;OAWG;IACH;QAVsG,KAAK,EAAhG,OAAO,8DAA8D,EAAE,UAAU;QAC9D,MAAM;QACT,KAAK,EAArB,MAAM;QACU,IAAI,EAApB,MAAM;QACU,IAAI;YACI,MAAM;YACE,UAAU,EAA1C,UAAU,MAAM,CAAC;YACI,MAAM,EAA3B,MAAM;;QACU,MAAM,EAAtB,MAAM;aAsEhB;;CACJ;kCApMiC,kDAAkD;mBAFjE,0CAA0C;kCAI3B,kCAAkC"}