@woosh/meep-engine 3.41.0 → 3.43.0

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

@@ -0,0 +1,42 @@
+/** Workgroup size of the culling pass and of the passes over its lists. */
+export const WATER_CULL_WORKGROUP_SIZE: 64;
+/** Bits of a wave row's activity word. */
+export const WaterActivity: Readonly<{
+    /** Its displaced surface may meet the frame's view. */
+    Visible: 1;
+    /** It is simulated this frame: visible, or simulated while hidden. */
+    Active: 2;
+}>;
+/** What the culling pass is told about the frame. */
+export const WATER_CULL_STRUCT: WebGPUStruct;
+/** A list the culling pass appends rows to. */
+export const WATER_LIST_APPEND_STRUCT: WebGPUStruct;
+/** Bytes of a list's header: its count, padded to its elements' alignment. */
+export const WATER_LIST_HEADER_BYTES: 16;
+/**
+ * The frame's culling pass (WATER_SURFACE_DISTANCE_LOD_PROPOSAL_2026_10_06.md §3.1), one thread a water body, before
+ * anything simulates. Against the frustum of the view the frame is recorded for, with a prior bound on the body's
+ * displacement, it decides whether the body is visible and whether it is simulated this frame, and lists it for the
+ * passes that follow. On the way it does the per-body work that used to be passes of its own over every row: weights
+ * when the wind or the fetch changed, the wind's turn for a body that is simulated, optics when they were edited.
+ * A visible body ORs the bands it can draw into the frame's band mask.
+ */
+export const shader_water_cull: ComputeShader;
+/** Commands the finalize pass writes, in order, 16 bytes apart. */
+export const WaterSurfaceCommand: Readonly<{
+    SpectrumRows: 0;
+    SpectrumColumns: 1;
+    Active: 2;
+    Emit: 3;
+}>;
+export const WATER_SURFACE_COMMAND_STRIDE: 16;
+export const WATER_SURFACE_COMMAND_COUNT: 4;
+/**
+ * After the culling pass: which bands this frame's spectrum evaluates — those the visible bodies can draw that do not
+ * already hold this time (all of them once, when a device's envelopes are seeded) — and the indirect commands for the
+ * spectrum and for the passes over the active and emit lists. Commands sit 16 bytes apart.
+ */
+export const shader_water_cull_finalize: ComputeShader;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_water_cull.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_water_cull.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/water/surface/shader_water_cull.js"],"names":[],"mappings":"AAoCA,2EAA2E;AAC3E,2CAA4C;AAE5C,0CAA0C;AAC1C;IACI,uDAAuD;;IAEvD,sEAAsE;;GAEvE;AAEH,qDAAqD;AACrD,6CAOuB;AAEvB,+CAA+C;AAC/C,oDAGE;AAEF,8EAA8E;AAC9E,yCAA0C;AA6C1C;;;;;;;GAOG;AACH,8CAsGiG;AAEjG,mEAAmE;AACnE;;;;;GAKG;AACH,8CAA+C;AAC/C,4CAA6C;AAW7C;;;;GAIG;AACH,uDAuBM;6BA9PuB,mCAAmC;8BAVlC,+BAA+B"}

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

@@ -0,0 +1,269 @@
+import { CAMERA_UNIFORM_STRUCT } from "../../camera/CAMERA_UNIFORM_STRUCT.js";
+import { GEOMETRY_METADATA_STRUCT } from "../../geometry/GEOMETRY_METADATA_STRUCT.js";
+import { COLLECTION_U32_STRUCT_READ } from "../../gpu_primitive/COLLECTION_U32_STRUCT_READ.js";
+import { chunk_scene_database_access_rw } from "../../scene/chunk_scene_database_access.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { chunk_aabb3_intersects_frustum } from "../../shader/chunk/geometry/aabb3/chunk_aabb3_intersects_frustum.js";
+import { chunk_aabb3_project } from "../../shader/chunk/geometry/aabb3/chunk_aabb3_project.js";
+import { chunk_array_to_aabb3 } from "../../shader/chunk/geometry/aabb3/chunk_array_to_aabb3.js";
+import { chunk_mat4_linear_determinant } from "../../shader/chunk/geometry/mat4/chunk_mat4_linear_determinant.js";
+import { chunk_folded_workgroup_index } from "../../shader/chunk/grid/chunk_folded_workgroup_index.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { atomic_u32, f32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { WGSLAttribute } from "../../shader/type/WGSLAttribute.js";
+import { WGSLAttributes } from "../../shader/type/WGSLAttributes.js";
+import { WGSLStructField } from "../../shader/type/WGSLStructField.js";
+import { chunk_water_medium_derived } from "../medium/chunk_water_medium_derived.js";
+import { chunk_water_medium_scattering } from "../medium/chunk_water_medium_scattering.js";
+import { WATER_BODIES_TABLE, WATER_WAVES_TABLE } from "../medium/chunk_water_bodies.js";
+import { chunk_water_lod } from "./lod/chunk_water_lod.js";
+import { WATER_LOD_VIEW_STRUCT } from "./lod/WATER_LOD.js";
+import { WATER_PARTICLE_LEVELS } from "./particles/chunk_water_particle.js";
+import { chunk_water_waves_derive } from "./shader_water_waves_derive.js";
+import { WATER_PARTICLE_BODY_BOUNDS_STRIDE } from "./shader_water_waves_combine.js";
+import {
+    WATER_BAND_REQUESTS_STRUCT,
+    WATER_BAND_STATE_ATOMIC_STRUCT,
+    WATER_BAND_STATE_STRUCT,
+    WATER_SPECTRUM_ALL_BANDS
+} from "./spectrum/WATER_BAND_STATE.js";
+import { chunk_water_spectrum } from "./spectrum/chunk_water_spectrum.js";
+import { WATER_SPECTRUM_COLUMN_GROUPS_PER_BAND, WATER_SPECTRUM_ROW_GROUPS_PER_BAND } from "./spectrum/shader_water_spectrum.js";
+import { WATER_WAVE_IMPULSE_LIMIT } from "./WATER_WAVE_RECORD_STRUCT.js";
+
+/** Workgroup size of the culling pass and of the passes over its lists. */
+export const WATER_CULL_WORKGROUP_SIZE = 64;
+
+/** Bits of a wave row's activity word. */
+export const WaterActivity = Object.freeze({
+    /** Its displaced surface may meet the frame's view. */
+    Visible: 1,
+    /** It is simulated this frame: visible, or simulated while hidden. */
+    Active: 2,
+});
+
+/** What the culling pass is told about the frame. */
+export const WATER_CULL_STRUCT = WebGPUStruct.from({
+    /** Seconds the frame steps. */
+    dt: f32,
+    /** Non-zero when the frame steps the simulation: splashes are emitted. */
+    stepping: u32,
+    /** Non-zero when the frame bins wave particles: active bodies' particle bounds start again from zero. */
+    binning: u32,
+}, 'WaterCull').pack();
+
+/** A list the culling pass appends rows to. */
+export const WATER_LIST_APPEND_STRUCT = WebGPUStruct.fromFields(
+    WGSLStructField.from("count", atomic_u32),
+    WGSLStructField.from("elements", WebGPUArray.from(u32), WGSLAttribute.from(WGSLAttributes.Align, 16)),
+);
+
+/** Bytes of a list's header: its count, padded to its elements' alignment. */
+export const WATER_LIST_HEADER_BYTES = 16;
+
+/**
+ * The prior bound of WATER_SURFACE_DISTANCE_LOD_PROPOSAL_2026_10_06.md §3.1: what a body's displaced surface can reach
+ * this frame before its bands and particles are evaluated, metric local. Ambient waves by twice their bands'
+ * envelopes, particles by the bounds their last binning left (exact for a paused body, whose particles stand still),
+ * and each queued splash by its ring: seven packets, each at most a tenth of its radius high.
+ */
+const chunk_water_cull_bound = CodeChunk.from(/* language=WGSL */ `
+const WATER_RING_BOUND: f32 = 0.7;
+
+// Σ weight × envelope, height then horizontal
+fn water_cull_ambient(weights: array<f32, WATER_SPECTRUM_BANDS>, blend: f32) -> vec2<f32> {
+    var sum = vec2<f32>(0.0);
+    for (var band = 0u; band < WATER_SPECTRUM_BANDS; band++) {
+        sum += weights[band] * vec2<f32>(bitcast<f32>(band_state.envelope[2u * band]), bitcast<f32>(band_state.envelope[2u * band + 1u]));
+    }
+    // during a turn of the wind two orientations show, weighted by the sine and cosine of the blend's quarter turn
+    let turning = blend < 1.0;
+    return sum * select(1.0, sin(1.57079633 * blend) + cos(1.57079633 * blend), turning);
+}
+`);
+
+const resources = new ShaderResourceSetDescriptor();
+resources.createGroup()
+    .addUniform('cull', WATER_CULL_STRUCT)
+    .addUniform('lod', WATER_LOD_VIEW_STRUCT)
+    .addUniform('camera', CAMERA_UNIFORM_STRUCT)
+    .addStorageBuffer('scene_database', WebGPUArray.u32, true)
+    .addStorageBuffer('geometries', WebGPUArray.from(GEOMETRY_METADATA_STRUCT))
+    .addStorageBuffer('band_state', WATER_BAND_STATE_STRUCT)
+    .addStorageBuffer('band_requests', WATER_BAND_REQUESTS_STRUCT, true)
+    .addStorageBuffer('particle_bounds', WebGPUArray.u32, true)
+    .addStorageBuffer('steep', WebGPUArray.u32)
+    .addStorageBuffer('activity', WebGPUArray.u32, true)
+    .addStorageBuffer('visible_rows', WATER_LIST_APPEND_STRUCT, true)
+    .addStorageBuffer('active_rows', WATER_LIST_APPEND_STRUCT, true)
+    .addStorageBuffer('emit_rows', WATER_LIST_APPEND_STRUCT, true);
+
+const bodies = WATER_BODIES_TABLE, waves = WATER_WAVES_TABLE;
+const pg = bodies.page_iterator_symbol_prefix(64, true);
+const read = field => `${waves.marshalling_method_read_field(field, true)}(&scene_database, row)`;
+const body = field => `${bodies.marshalling_method_read_field(field, true)}(&scene_database, body_row)`;
+const STRIDE = WATER_PARTICLE_BODY_BOUNDS_STRIDE;
+
+/**
+ * The frame's culling pass (WATER_SURFACE_DISTANCE_LOD_PROPOSAL_2026_10_06.md §3.1), one thread a water body, before
+ * anything simulates. Against the frustum of the view the frame is recorded for, with a prior bound on the body's
+ * displacement, it decides whether the body is visible and whether it is simulated this frame, and lists it for the
+ * passes that follow. On the way it does the per-body work that used to be passes of its own over every row: weights
+ * when the wind or the fetch changed, the wind's turn for a body that is simulated, optics when they were edited.
+ * A visible body ORs the bands it can draw into the frame's band mask.
+ */
+export const shader_water_cull = ComputeShader.from({ label: 'Water / cull', resources,
+    body: CodeChunk.from(/* language=WGSL */ `
+@compute @workgroup_size(64)
+fn main(@builtin(workgroup_id) group: vec3u, @builtin(local_invocation_index) lane: u32) {
+    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_row = ${pg}_slot_to_index(slot);
+    // a hidden body costs this thread: read what deciding takes, and the whole row only when its optics changed
+    if (${body('dirty')} != 0u) {
+        var body = ${bodies.marshalling_method_read_rw}(&scene_database, body_row);
+        body.backscattering = vec4f(water_medium_backscattering(body.medium), 0.0);
+        body.extinction = vec4f(body.medium.absorption + water_medium_scattering(body.medium), 0.0);
+        body.diffuse_transmittance = water_diffuse_fresnel_transmittance(body.ior);
+        body.dirty = 0u;
+        ${bodies.marshalling_method_write}(&scene_database, body_row, body);
+    }
+    let row = ${body('wave')};
+    let node = ${body('node')};
+    activity[row] = 0u;
+    if (node == 0u || node == ~0u) { return; }
+    let global = scene_read_node_rw(&scene_database, node).global;
+    if (abs(mat4_linear_determinant(global)) < 1e-20) { return; }
+    let scale = max(vec3<f32>(length(global[0].xyz), length(global[1].xyz), length(global[2].xyz)), vec3<f32>(1e-20));
+    let box = geometries[${body('geometry')}].bounding_box;
+
+    // weights, when the wind or the fetch they were derived for changed; none without wind
+    let wind = ${read('wind')};
+    let direction = wind.xy / max(length(wind.xy), 1e-20);
+    let fetch = water_waves_fetch(box, scale, direction, ${read('upwind_fetch')});
+    var weights: array<f32, WATER_SPECTRUM_BANDS>;
+    if (any(${read('derived_for')} != vec2<f32>(wind.z, fetch))) {
+        let derived = water_waves_derive(wind.z, fetch);
+        weights = derived.weights;
+        ${waves.marshalling_method_write_field('weights')}(&scene_database, row, weights);
+        ${waves.marshalling_method_write_field('slope_variance')}(&scene_database, row, derived.slope_variance);
+        ${waves.marshalling_method_write_field('derived_for')}(&scene_database, row, vec2<f32>(wind.z, fetch));
+    } else if (wind.z > 0.0) {
+        weights = ${read('weights')};
+    }
+
+    // the prior bound, metric; a steep body is kept calm
+    var vertical = 0.0;
+    var horizontal = 0.0;
+    let queued = min(${read('impulse_count')}, ${WATER_WAVE_IMPULSE_LIMIT}u);
+    if (steep[row] == 0u) {
+        var particles = 0.0;
+        let base = row * ${STRIDE}u;
+        if (particle_bounds[base] != 0u) {
+            for (var level = 0u; level < ${WATER_PARTICLE_LEVELS}u; level++) { particles += bitcast<f32>(particle_bounds[base + 1u + level]); }
+        }
+        if (queued > 0u) {
+            let impulses = ${read('impulses')};
+            for (var j = 0u; j < queued; j++) { particles += WATER_RING_BOUND * clamp(impulses[j].z, 1e-3, 16.0); }
+        }
+        var ambient = vec2<f32>(0.0);
+        if (wind.z > 0.0) { ambient = water_cull_ambient(weights, ${read('wind_blend')}); }
+        vertical = 2.0 * ambient.x + particles;
+        horizontal = 2.0 * ambient.y + particles;
+    }
+    var grown = box;
+    let up = vertical / scale.y;
+    let side = horizontal / min(scale.x, scale.z);
+    grown[1] -= up; grown[4] += up;
+    grown[0] -= side; grown[2] -= side; grown[3] += side; grown[5] += side;
+    let is_visible = aabb3_intersects_frustum(aabb3_project(array_to_aabb3(grown), global), camera.frustum);
+    let is_active = is_visible || ${read('simulate_hidden')} != 0u;
+
+    if (is_visible && wind.z > 0.0) {
+        // the bands this body can draw: waves longer than 8 of the finest cells it can be drawn with
+        let rest = aabb3_project(array_to_aabb3(box), global);
+        let eye = camera.view_matrix_inverse[3].xyz;
+        let nearest = length(max(max(rest.min - eye, eye - rest.max), vec3<f32>(0.0)));
+        let finest = 8.0 * water_lod_footprint_min(lod, nearest);
+        var mask = 0u;
+        for (var band = 0u; band < WATER_SPECTRUM_BANDS; band++) {
+            if (weights[band] > 0.0 && water_band_wavelength(band) > finest) { mask |= 1u << band; }
+        }
+        if (mask != 0u) { atomicOr(&band_requests.needed, mask); }
+    }
+    if (is_active) {
+        let turn = water_wind_turn(WaterWindTurn(${read('wind_from')}, ${read('wind_to')}, ${read('wind_blend')}),
+            direction, select(0.0, cull.dt, cull.stepping != 0u));
+        ${waves.marshalling_method_write_field('wind_from')}(&scene_database, row, turn.previous);
+        ${waves.marshalling_method_write_field('wind_to')}(&scene_database, row, turn.current);
+        ${waves.marshalling_method_write_field('wind_blend')}(&scene_database, row, turn.blend);
+        // this frame's binning rebuilds the bounds of the bodies it bins; a paused body keeps its own
+        if (cull.binning != 0u) {
+            for (var word = 0u; word < ${STRIDE}u; word++) { particle_bounds[row * ${STRIDE}u + word] = 0u; }
+        }
+        active_rows.elements[atomicAdd(&active_rows.count, 1u)] = row;
+    }
+    if (is_visible) { visible_rows.elements[atomicAdd(&visible_rows.count, 1u)] = body_row; }
+    if (cull.stepping != 0u && queued != 0u) { emit_rows.elements[atomicAdd(&emit_rows.count, 1u)] = row; }
+    activity[row] = select(0u, ${WaterActivity.Visible}u, is_visible) | select(0u, ${WaterActivity.Active}u, is_active);
+}
+`, [bodies.chunk_iterate(64, true), bodies.chunk_write, bodies.chunk_read_rw,
+        ...['dirty', 'wave', 'node', 'geometry'].map(field => bodies.chunk_read_field(field, true)), ...['wind', 'upwind_fetch', 'weights', 'derived_for', 'wind_blend',
+        'impulses', 'impulse_count', 'simulate_hidden', 'wind_from', 'wind_to'].map(field => waves.chunk_read_field(field, true)),
+        ...['weights', 'slope_variance', 'derived_for', 'wind_from', 'wind_to', 'wind_blend'].map(field => waves.wgsl_gen_write_field_code(field)),
+        chunk_water_cull_bound, chunk_water_spectrum, chunk_water_waves_derive, chunk_water_lod, chunk_water_medium_derived,
+        chunk_water_medium_scattering, chunk_scene_database_access_rw, chunk_folded_workgroup_index, chunk_aabb3_project,
+        chunk_array_to_aabb3, chunk_aabb3_intersects_frustum, chunk_mat4_linear_determinant]) });
+
+/** Commands the finalize pass writes, in order, 16 bytes apart. */
+export const WaterSurfaceCommand = Object.freeze({
+    SpectrumRows: 0,
+    SpectrumColumns: 1,
+    Active: 2,
+    Emit: 3,
+});
+export const WATER_SURFACE_COMMAND_STRIDE = 16;
+export const WATER_SURFACE_COMMAND_COUNT = 4;
+
+const finalize_resources = new ShaderResourceSetDescriptor();
+finalize_resources.setImmediate('frame', WebGPUStruct.from({ fresh: u32, seed: u32 }, 'WaterCullFinalize'));
+finalize_resources.createGroup()
+    .addStorageBuffer('band_state', WATER_BAND_STATE_ATOMIC_STRUCT, true)
+    .addStorageBuffer('band_requests', WATER_BAND_REQUESTS_STRUCT, true)
+    .addStorageBuffer('active_rows', COLLECTION_U32_STRUCT_READ)
+    .addStorageBuffer('emit_rows', COLLECTION_U32_STRUCT_READ)
+    .addStorageBuffer('commands', WebGPUArray.u32, true);
+
+/**
+ * After the culling pass: which bands this frame's spectrum evaluates — those the visible bodies can draw that do not
+ * already hold this time (all of them once, when a device's envelopes are seeded) — and the indirect commands for the
+ * spectrum and for the passes over the active and emit lists. Commands sit 16 bytes apart.
+ */
+export const shader_water_cull_finalize = ComputeShader.from({ label: 'Water / cull finalize', resources: finalize_resources,
+    body: CodeChunk.from(/* language=WGSL */ `
+// a dispatch of groups workgroups along x, at word index · ${WATER_SURFACE_COMMAND_STRIDE / 4}
+fn water_command(index: u32, groups: u32) {
+    let at = index * ${WATER_SURFACE_COMMAND_STRIDE / 4}u;
+    commands[at] = groups;
+    commands[at + 1u] = 1u;
+    commands[at + 2u] = 1u;
+}
+
+@compute @workgroup_size(1)
+fn main() {
+    let valid = select(atomicLoad(&band_state.valid), 0u, frame.fresh != 0u);
+    let needed = select(atomicExchange(&band_requests.needed, 0u), ${WATER_SPECTRUM_ALL_BANDS}u, frame.seed != 0u);
+    let todo = needed & ~valid;
+    atomicStore(&band_state.todo, todo);
+    atomicStore(&band_state.valid, valid | todo);
+    let bands = countOneBits(todo);
+    water_command(${WaterSurfaceCommand.SpectrumRows}u, bands * ${WATER_SPECTRUM_ROW_GROUPS_PER_BAND}u);
+    water_command(${WaterSurfaceCommand.SpectrumColumns}u, bands * ${WATER_SPECTRUM_COLUMN_GROUPS_PER_BAND}u);
+    water_command(${WaterSurfaceCommand.Active}u, (active_rows.count + ${WATER_CULL_WORKGROUP_SIZE - 1}u) / ${WATER_CULL_WORKGROUP_SIZE}u);
+    water_command(${WaterSurfaceCommand.Emit}u, (emit_rows.count + ${WATER_CULL_WORKGROUP_SIZE - 1}u) / ${WATER_CULL_WORKGROUP_SIZE}u);
+}
+`) });

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

@@ -0,0 +1,15 @@
+/** Words a wave row owns in the particle bounds buffer: its occupied-level mask, then a bound per level. */
+export const WATER_PARTICLE_BODY_BOUNDS_STRIDE: number;
+/**
+ * The displacement bounds of each body simulated this frame (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §6), one
+ * thread a row of the culling pass's active list: the weighted sum of its bands' envelopes — each band's largest
+ * extremum at any time evaluated, so at least this frame's, since bilinear filtering cannot leave a tile's texel range —
+ * times sin + cos of a wind turn's blend while one is under way, plus the body's particle bounds, each a level's
+ * largest bound on Σ|a| over the cells the body occupies. Both bound height and horizontal displacement alike.
+ *
+ * The bounds only cull now, so they follow the waves as they are. A body the tessellation found steep (a waterfall)
+ * is kept calm: it is drawn as its authored triangles.
+ */
+export const shader_water_waves_combine: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_water_waves_combine.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_water_waves_combine.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/water/surface/shader_water_waves_combine.js"],"names":[],"mappings":"AAaA,4GAA4G;AAC5G,uDAA2E;AAY3E;;;;;;;;;GASG;AACH,uDAoCgG;8BAxElE,+BAA+B"}

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

@@ -0,0 +1,73 @@
+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 { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { COLLECTION_U32_STRUCT_READ } from "../../gpu_primitive/COLLECTION_U32_STRUCT_READ.js";
+import { chunk_folded_workgroup_index } from "../../shader/chunk/grid/chunk_folded_workgroup_index.js";
+import { chunk_scene_database_access_rw } from "../../scene/chunk_scene_database_access.js";
+import { WATER_WAVES_TABLE as table } from "../medium/chunk_water_bodies.js";
+import { chunk_water_spectrum } from "./spectrum/chunk_water_spectrum.js";
+import { WATER_BAND_STATE_STRUCT } from "./spectrum/WATER_BAND_STATE.js";
+import { WATER_PARTICLE_LEVELS } from "./particles/chunk_water_particle.js";
+
+/** Words a wave row owns in the particle bounds buffer: its occupied-level mask, then a bound per level. */
+export const WATER_PARTICLE_BODY_BOUNDS_STRIDE = 1 + WATER_PARTICLE_LEVELS;
+
+const resources = new ShaderResourceSetDescriptor();
+resources.createGroup()
+    .addStorageBuffer('scene_database', WebGPUArray.u32, true)
+    .addStorageBuffer('active_rows', COLLECTION_U32_STRUCT_READ)
+    .addStorageBuffer('band_state', WATER_BAND_STATE_STRUCT)
+    .addStorageBuffer('particle_bounds', WebGPUArray.from(u32))
+    .addStorageBuffer('steep', WebGPUArray.from(u32));
+
+const field = name => table.marshalling_method_read_field(name, true);
+
+/**
+ * The displacement bounds of each body simulated this frame (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §6), one
+ * thread a row of the culling pass's active list: the weighted sum of its bands' envelopes — each band's largest
+ * extremum at any time evaluated, so at least this frame's, since bilinear filtering cannot leave a tile's texel range —
+ * times sin + cos of a wind turn's blend while one is under way, plus the body's particle bounds, each a level's
+ * largest bound on Σ|a| over the cells the body occupies. Both bound height and horizontal displacement alike.
+ *
+ * The bounds only cull now, so they follow the waves as they are. A body the tessellation found steep (a waterfall)
+ * is kept calm: it is drawn as its authored triangles.
+ */
+export const shader_water_waves_combine = ComputeShader.from({ label: 'Water / waves combine', resources,
+    body: CodeChunk.from(/* language=WGSL */ `
+@compute @workgroup_size(64)
+fn main(@builtin(workgroup_id) group: vec3u, @builtin(local_invocation_index) lane: u32) {
+    let index = folded_workgroup_index(group) * 64u + lane;
+    if (index >= active_rows.count) { return; }
+    let row = active_rows.elements[index];
+    let node = ${field('node')}(&scene_database, row);
+    var bounds = vec4<f32>(0.0);
+    var levels = 0u;
+    if (node != 0u && node != ~0u && steep[row] == 0u) {
+        let global = scene_read_node_rw(&scene_database, node).global;
+        let scale = max(vec3<f32>(length(global[0].xyz), length(global[1].xyz), length(global[2].xyz)), vec3<f32>(1e-20));
+        let weights = ${field('weights')}(&scene_database, row);
+        var height = 0.0;
+        var horizontal = 0.0;
+        for (var band = 0u; band < WATER_SPECTRUM_BANDS; band++) {
+            height += weights[band] * bitcast<f32>(band_state.envelope[2u * band]);
+            horizontal += weights[band] * bitcast<f32>(band_state.envelope[2u * band + 1u]);
+        }
+        // during a turn of the wind two independent orientations show, weighted by the sine and cosine of the
+        // blend's quarter turn, and both can peak at one point
+        let blend = ${field('wind_blend')}(&scene_database, row);
+        let both = select(1.0, sin(1.57079633 * blend) + cos(1.57079633 * blend), blend < 1.0);
+        let base = row * ${WATER_PARTICLE_BODY_BOUNDS_STRIDE}u;
+        levels = particle_bounds[base];
+        var particles = 0.0;
+        for (var level = 0u; level < ${WATER_PARTICLE_LEVELS}u; level++) { particles += bitcast<f32>(particle_bounds[base + 1u + level]); }
+        let vertical = (both * height + particles) / scale.y;
+        bounds = vec4<f32>(-vertical, vertical, (both * horizontal + particles) / min(scale.x, scale.z), 0.0);
+    }
+    ${table.marshalling_method_write_field('displacement_bounds')}(&scene_database, row, bounds);
+    ${table.marshalling_method_write_field('particle_levels')}(&scene_database, row, levels);
+}
+`, [...['node', 'weights', 'wind_blend'].map(name => table.chunk_read_field(name, true)),
+        table.wgsl_gen_write_field_code('displacement_bounds'), table.wgsl_gen_write_field_code("particle_levels"),
+        chunk_scene_database_access_rw, chunk_water_spectrum, chunk_folded_workgroup_index]) });

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

@@ -0,0 +1,11 @@
+/** Seconds a change of wind direction takes to turn the waves. */
+export const WATER_WIND_TURN_SECONDS: 4;
+/**
+ * A body's ambient waves from its wind and its fetch, as weights on the shared spectral bands
+ * (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §4.2).
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_water_waves_derive: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=shader_water_waves_derive.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_water_waves_derive.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/water/surface/shader_water_waves_derive.js"],"names":[],"mappings":"AAGA,kEAAkE;AAClE,wCAAyC;AAEzC;;;;;GAKG;AACH,uCAFU,SAAS,CAmEO;0BA7EA,oCAAoC"}

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

@@ -0,0 +1,78 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { chunk_water_jonswap } from "./spectrum/chunk_water_jonswap.js";
+
+/** Seconds a change of wind direction takes to turn the waves. */
+export const WATER_WIND_TURN_SECONDS = 4;
+
+/**
+ * A body's ambient waves from its wind and its fetch, as weights on the shared spectral bands
+ * (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §4.2).
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_water_waves_derive = CodeChunk.from(/* language=WGSL */ `
+// How far the wind crosses the body along a unit direction of its metric local xz: the chord through the
+// centre of the ellipse inscribed in its box, so a square does not gain fetch at 45° and a long narrow lake
+// is long only along its length, plus the authored open water beyond it.
+fn water_waves_fetch(box: array<f32, 6>, scale: vec3<f32>, direction: vec2<f32>, upwind: f32) -> f32 {
+    let semi = 0.5 * vec2<f32>(box[3] - box[0], box[5] - box[2]) * scale.xz;
+    // the point t·direction lies on the ellipse where t² ((dx / a)² + (dz / b)²) = 1
+    let crossing = length(semi.yx * direction);
+    let chord = select(0.0, 2.0 * semi.x * semi.y / crossing, crossing > 0.0);
+    return chord + max(upwind, 0.0);
+}
+
+struct WaterWavesDerived {
+    weights: array<f32, WATER_SPECTRUM_BANDS>,
+    slope_variance: f32,
+}
+
+// Each band's weight is the sea's saturation projected onto the band's hat, weighted as the band's height
+// variance is (k⁻² per unit log k), so a body's variance in each octave is its spectrum's wherever the peak
+// falls between nodes. Eight midpoint samples over the hat's two octaves.
+fn water_waves_derive(wind_speed: f32, fetch: f32) -> WaterWavesDerived {
+    var derived: WaterWavesDerived;
+    if (!(wind_speed > 0.0) || !(fetch > 0.0)) { return derived; }
+    let sea = water_jonswap(wind_speed, fetch);
+    var slope = 0.0;
+    for (var band = 0u; band < WATER_SPECTRUM_BANDS; band++) {
+        let node = WATER_TAU / water_band_wavelength(band);
+        var projected = 0.0;
+        var norm = 0.0;
+        for (var i = 0u; i < 8u; i++) {
+            let u = -1.0 + (f32(i) + 0.5) * 0.25;
+            let weight = (1.0 - abs(u)) * exp2(-2.0 * u);
+            projected += weight * water_jonswap_saturation(sea, node * exp2(u));
+            norm += weight;
+        }
+        let saturation = projected / norm;
+        derived.weights[band] = sqrt(saturation);
+        // a band's unit-saturation slope variance is ∫ hat d(ln k) = ln 2
+        slope += saturation * 0.69314718;
+    }
+    derived.slope_variance = slope;
+    return derived;
+}
+
+struct WaterWindTurn {
+    previous: vec2<f32>,
+    current: vec2<f32>,
+    blend: f32,
+}
+
+// Follow the authored direction: a change starts a turn from the direction the waves show, which then advances
+// by dt / ${WATER_WIND_TURN_SECONDS} s. A change during a turn waits for it to finish, so a wind that keeps turning
+// is followed one turn behind, and an orientation only ever leaves the waves at no weight. A row seen for the
+// first time starts settled.
+fn water_wind_turn(last: WaterWindTurn, authored: vec2<f32>, dt: f32) -> WaterWindTurn {
+    var turn = last;
+    if (all(turn.current == vec2<f32>(0.0))) { return WaterWindTurn(authored, authored, 1.0); }
+    if (turn.blend >= 1.0 && dot(turn.current, authored) < 0.99999) {
+        turn.previous = turn.current;
+        turn.current = authored;
+        turn.blend = 0.0;
+    }
+    turn.blend = min(turn.blend + max(dt, 0.0) / ${WATER_WIND_TURN_SECONDS}.0, 1.0);
+    return turn;
+}
+`, [chunk_water_jonswap]);

package/src/shade/renderer/water/surface/spectrum/GPUWaterSpectrum.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The shared ambient-wave basis on the device: the bands a frame asks for animated to the frame's time, as two
+ * `rgba16float` array textures (displacement and derivatives, one layer a band), and the band state — which bands
+ * hold which time, and each band's envelope (WATER_SURFACE_DISTANCE_LOD_PROPOSAL_2026_10_06.md §3.1).
+ * One instance serves every water body of a device; its cost is a band's worth of work for each band a body in
+ * view can draw, whatever the number of bodies.
+ */
+export class GPUWaterSpectrum {
+    /** @returns {GPUTextureView} (Dx, h, Dz, ∂Dx/∂z) per band layer */
+    get displacement(): GPUTextureView;
+    /** @returns {GPUTextureView} (∂h/∂x, ∂h/∂z, ∂Dx/∂x, ∂Dz/∂z) per band layer */
+    get derivatives(): GPUTextureView;
+    /** @returns {GPUBuffer} {@link WATER_BAND_STATE_STRUCT}: band masks and envelopes */
+    get band_state(): GPUBuffer;
+    /** @returns {GPUBuffer} {@link WATER_BAND_REQUESTS_STRUCT}: the bands the frame's visible bodies ask for */
+    get band_requests(): GPUBuffer;
+    dispose(): void;
+    /**
+     * Allocate on first use for a device, so the views exist before the frame's passes bind them.
+     * @param {GPUDevice} device
+     */
+    prepare(device: GPUDevice): void;
+    /**
+     * Animate the bands in the band state's `todo` mask to `time` seconds, dispatched from the commands the culling
+     * pass's finalize wrote.
+     * @param {import("../../../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext} encoder
+     * @param {number} time
+     * @param {GPUBuffer} commands
+     * @param {number} rows_offset byte offset of the row pass's command
+     * @param {number} columns_offset byte offset of the column pass's command
+     */
+    encode(encoder: import("../../../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext, time: number, commands: GPUBuffer, rows_offset: number, columns_offset: number): void;
+    #private;
+}
+//# sourceMappingURL=GPUWaterSpectrum.d.ts.map

package/src/shade/renderer/water/surface/spectrum/GPUWaterSpectrum.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GPUWaterSpectrum.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/water/surface/spectrum/GPUWaterSpectrum.js"],"names":[],"mappings":"AASA;;;;;;GAMG;AACH;IAWI,mEAAmE;IACnE,mCAAsD;IACtD,8EAA8E;IAC9E,kCAAoD;IACpD,qFAAqF;IACrF,4BAA6C;IAC7C,4GAA4G;IAC5G,+BAAmD;IA4BnD,gBASC;IAED;;;OAGG;IACH,iCAGC;IAED;;;;;;;;OAQG;IACH,gBANW,OAAO,8CAA8C,EAAE,sBAAsB,QAC7E,MAAM,oCAEN,MAAM,kBACN,MAAM,QAYhB;;CACJ"}

package/src/shade/renderer/water/surface/spectrum/GPUWaterSpectrum.js

@@ -0,0 +1,103 @@
+import { assert } from "../../../../../core/assert.js";
+import {
+    shader_water_spectrum_columns,
+    shader_water_spectrum_rows,
+    WATER_SPECTRUM_ROW_VALUE_COUNT
+} from "./shader_water_spectrum.js";
+import { WATER_BAND_REQUESTS_STRUCT, WATER_BAND_STATE_STRUCT } from "./WATER_BAND_STATE.js";
+import { WATER_SPECTRUM_BAND_COUNT, WATER_SPECTRUM_LOOP_SECONDS, WATER_SPECTRUM_TILE_SIZE } from "./WATER_SPECTRUM.js";
+
+/**
+ * The shared ambient-wave basis on the device: the bands a frame asks for animated to the frame's time, as two
+ * `rgba16float` array textures (displacement and derivatives, one layer a band), and the band state — which bands
+ * hold which time, and each band's envelope (WATER_SURFACE_DISTANCE_LOD_PROPOSAL_2026_10_06.md §3.1).
+ * One instance serves every water body of a device; its cost is a band's worth of work for each band a body in
+ * view can draw, whatever the number of bodies.
+ */
+export class GPUWaterSpectrum {
+    #device = null;
+    #rows = null;
+    #displacement = null;
+    #derivatives = null;
+    #displacement_view = null;
+    #derivatives_view = null;
+    #storage_views = null;
+    #band_state = null;
+    #band_requests = null;
+
+    /** @returns {GPUTextureView} (Dx, h, Dz, ∂Dx/∂z) per band layer */
+    get displacement() { return this.#displacement_view; }
+    /** @returns {GPUTextureView} (∂h/∂x, ∂h/∂z, ∂Dx/∂x, ∂Dz/∂z) per band layer */
+    get derivatives() { return this.#derivatives_view; }
+    /** @returns {GPUBuffer} {@link WATER_BAND_STATE_STRUCT}: band masks and envelopes */
+    get band_state() { return this.#band_state; }
+    /** @returns {GPUBuffer} {@link WATER_BAND_REQUESTS_STRUCT}: the bands the frame's visible bodies ask for */
+    get band_requests() { return this.#band_requests; }
+
+    /**
+     * @param {GPUDevice} device
+     */
+    #allocate(device) {
+        if (this.#device === device) { return; }
+        this.dispose();
+        this.#device = device;
+        this.#rows = device.createBuffer({ label: 'Water / spectrum rows', size: WATER_SPECTRUM_ROW_VALUE_COUNT * 16,
+            usage: GPUBufferUsage.STORAGE });
+        const texture = label => device.createTexture({ label,
+            size: [WATER_SPECTRUM_TILE_SIZE, WATER_SPECTRUM_TILE_SIZE, WATER_SPECTRUM_BAND_COUNT],
+            format: 'rgba16float', dimension: '2d',
+            usage: GPUTextureUsage.STORAGE_BINDING | GPUTextureUsage.TEXTURE_BINDING });
+        this.#displacement = texture('Water / spectrum displacement');
+        this.#derivatives = texture('Water / spectrum derivatives');
+        this.#displacement_view = this.#displacement.createView({ dimension: '2d-array' });
+        this.#derivatives_view = this.#derivatives.createView({ dimension: '2d-array' });
+        this.#storage_views = [this.#displacement.createView({ dimension: '2d-array' }),
+            this.#derivatives.createView({ dimension: '2d-array' })];
+        // zero on creation: no band valid, no envelope yet
+        this.#band_state = device.createBuffer({ label: 'Water / spectrum band state', size: WATER_BAND_STATE_STRUCT.size,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC });
+        this.#band_requests = device.createBuffer({ label: 'Water / spectrum band requests', size: WATER_BAND_REQUESTS_STRUCT.size,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST });
+    }
+
+    dispose() {
+        this.#rows?.destroy();
+        this.#displacement?.destroy();
+        this.#derivatives?.destroy();
+        this.#band_state?.destroy();
+        this.#band_requests?.destroy();
+        this.#device = null;
+        this.#rows = this.#displacement = this.#derivatives = this.#band_state = this.#band_requests = null;
+        this.#displacement_view = this.#derivatives_view = this.#storage_views = null;
+    }
+
+    /**
+     * Allocate on first use for a device, so the views exist before the frame's passes bind them.
+     * @param {GPUDevice} device
+     */
+    prepare(device) {
+        assert.defined(device, 'device');
+        this.#allocate(device);
+    }
+
+    /**
+     * Animate the bands in the band state's `todo` mask to `time` seconds, dispatched from the commands the culling
+     * pass's finalize wrote.
+     * @param {import("../../../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext} encoder
+     * @param {number} time
+     * @param {GPUBuffer} commands
+     * @param {number} rows_offset byte offset of the row pass's command
+     * @param {number} columns_offset byte offset of the column pass's command
+     */
+    encode(encoder, time, commands, rows_offset, columns_offset) {
+        assert.isFinite(time, 'time');
+        assert.notNull(this.#device, 'prepare() first');
+        // the phase is taken from the time within the loop, so f32 keeps it exact however long the run
+        const loop_fraction = (time % WATER_SPECTRUM_LOOP_SECONDS) / WATER_SPECTRUM_LOOP_SECONDS;
+        const rows = this.#rows, band_state = this.#band_state;
+        shader_water_spectrum_rows.dispatchIndirect({ encoder, command: commands, command_offset: rows_offset,
+            bindings: { rows, loop_fraction, band_state } });
+        shader_water_spectrum_columns.dispatchIndirect({ encoder, command: commands, command_offset: columns_offset,
+            bindings: { rows, displacement: this.#storage_views[0], derivatives: this.#storage_views[1], band_state } });
+    }
+}