@woosh/meep-engine 3.37.0 → 3.39.0

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

@@ -0,0 +1,408 @@
+import { assert } from "../../../../core/assert.js";
+import { SAMPLER_LINEAR_UPSCALE } from "../../texture/SAMPLER_LINEAR_UPSCALE.js";
+import { shader_water_surface_write } from "./shader_water_surface_write.js";
+import { shader_water_wave_step } from "./shader_water_wave_step.js";
+import { WATER_WAVE_IMPULSE_LIMIT, WATER_WAVE_PARAMETERS_STRUCT } from "./WATER_WAVE_PARAMETERS_STRUCT.js";
+import { water_surface_grid_indices } from "./water_surface_grid_indices.js";
+
+/**
+ * Bytes of one {@link WATER_SURFACE_VERTEX_STRUCT}: three vec4f.
+ * @type {number}
+ */
+const VERTEX_BYTES = 48;
+
+/**
+ * Forcing amplitude per (m/s)² of wind, m/s² — wind stress grows as the square of its speed.
+ *
+ * Not calibrated to a wave spectrum: chosen so that the playground's 3 m/s breeze gives
+ * centimetre-scale waves. The production simulation, not this constant, is where calibration
+ * belongs.
+ * @type {number}
+ */
+const FORCING_PER_WIND2 = 0.02;
+
+/**
+ * What one body holds on the GPU.
+ *
+ * @typedef {Object} WaterWaveBody
+ * @property {number} resolution
+ * @property {GPUBuffer[]} state the two alternating height buffers
+ * @property {number} parity which of {@link state} holds the current heights
+ * @property {GPUBuffer} vertices
+ * @property {boolean} written
+ */
+
+/**
+ * The primitive surface producer (WATER_OPTICS_PLAN_2026_10_02.md §7.2): a damped linear wave
+ * equation on a regular grid over each water body, written out as the surface interface — a
+ * vertex buffer and a shared index buffer.
+ *
+ * It owns its GPU resources, keyed by device so a restart rebuilds them, and records its work at
+ * the head of a frame's graph: everything that reads the surface is recorded after it, and the graph
+ * runs passes in insertion order. Time advances through {@link advance}, once per tick, and is
+ * consumed by the first view to record, so several views of one frame step the simulation once.
+ */
+export class GPUWaterWaveSimulation {
+    /**
+     * Vertices along each side of a body's grid. Changing it rebuilds every body.
+     * @type {number}
+     */
+    resolution = 512;
+
+    /**
+     * Fixed step, s. Explicit and fixed, so a frame-rate change does not change the waves.
+     * @type {number}
+     */
+    step = 1 / 120;
+
+    /**
+     * Most steps one frame takes; time beyond it is dropped rather than queued, so a stall does not
+     * turn into a burst.
+     * @type {number}
+     */
+    max_steps_per_frame = 8;
+
+    /**
+     * Damping everywhere, 1/s.
+     * @type {number}
+     */
+    damping = 0.08;
+
+    /**
+     * @type {GPUDevice|null}
+     */
+    #device = null;
+
+    /**
+     * @type {Map<Object, WaterWaveBody>}
+     */
+    #bodies = new Map();
+
+    /**
+     * @type {GPUBuffer|null}
+     */
+    #indices = null;
+
+    #index_resolution = 0;
+
+    #index_count = 0;
+
+    /**
+     * Simulated time not yet stepped, s.
+     * @type {number}
+     */
+    #pending = 0;
+
+    /**
+     * Simulated time stepped so far, s.
+     * @type {number}
+     */
+    #time = 0;
+
+    /**
+     * Whether the next record writes the surface: once per tick, even a tick of zero, so a paused
+     * frame's previous positions settle onto its current ones.
+     * @type {boolean}
+     */
+    #write_pending = true;
+
+    /**
+     * Simulated time, s.
+     * @returns {number}
+     */
+    get time() {
+        return this.#time;
+    }
+
+    /**
+     * @param {number} dt seconds of simulation to add
+     */
+    advance(dt) {
+        assert.isFinite(dt, 'dt');
+        assert.greaterThanOrEqual(dt, 0, 'dt');
+
+        this.#pending += dt;
+        this.#write_pending = true;
+    }
+
+    /**
+     * Release every GPU resource.
+     */
+    dispose() {
+        for (const body of this.#bodies.values()) {
+            body.state[0].destroy();
+            body.state[1].destroy();
+            body.vertices.destroy();
+        }
+
+        this.#bodies.clear();
+
+        this.#indices?.destroy();
+        this.#indices = null;
+        this.#index_resolution = 0;
+        this.#device = null;
+    }
+
+    /**
+     * Record this frame's steps and surface writes, and publish each surface's interface on it as
+     * `surface.gpu_surface`.
+     *
+     * @param {Object} options
+     * @param {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} options.graph
+     * @param {GPUDevice} options.device
+     * @param {Object[]} options.surfaces bodies with a terrain height texture, as the water system keeps them
+     */
+    record({ graph, device, surfaces }) {
+        assert.defined(graph, 'graph');
+        assert.defined(device, 'device');
+        assert.isArray(surfaces, 'surfaces');
+
+        if (device !== this.#device) {
+            this.dispose();
+            this.#device = device;
+        }
+
+        this.#release_unused(surfaces);
+
+        if (surfaces.length === 0) {
+            return;
+        }
+
+        this.#ensure_indices(device);
+
+        // the epsilon keeps accumulated rounding — two half steps summing to just under one — from
+        // dropping a step
+        const steps = Math.min(Math.floor(this.#pending / this.step + 1e-6), this.max_steps_per_frame);
+        // time past the frame's limit is dropped, so a stall does not come back as a burst
+        this.#pending = Math.max(0, Math.min(this.#pending - steps * this.step, this.step));
+
+        const write = this.#write_pending;
+        this.#write_pending = false;
+
+        if (steps === 0 && !write) {
+            return;
+        }
+
+        const time_start = this.#time;
+        this.#time += steps * this.step;
+
+        for (let i = 0; i < surfaces.length; i++) {
+            const surface = surfaces[i];
+            const body = this.#ensure_body(device, surface);
+
+            surface.gpu_surface = {
+                vertices: body.vertices,
+                indices: this.#indices,
+                index_count: this.#index_count,
+                resolution: body.resolution,
+            };
+
+            this.#record_body(graph, surface, body, steps, time_start);
+        }
+    }
+
+    /**
+     * @param {Object[]} surfaces
+     */
+    #release_unused(surfaces) {
+        for (const [surface, body] of this.#bodies) {
+            if (surfaces.indexOf(surface) !== -1 && body.resolution === this.resolution) {
+                continue;
+            }
+
+            body.state[0].destroy();
+            body.state[1].destroy();
+            body.vertices.destroy();
+
+            this.#bodies.delete(surface);
+
+            if (surface.gpu_surface !== undefined && surface.gpu_surface.vertices === body.vertices) {
+                surface.gpu_surface = undefined;
+            }
+        }
+    }
+
+    /**
+     * @param {GPUDevice} device
+     */
+    #ensure_indices(device) {
+        if (this.#indices !== null && this.#index_resolution === this.resolution) {
+            return;
+        }
+
+        this.#indices?.destroy();
+
+        const indices = water_surface_grid_indices({ resolution: this.resolution });
+
+        this.#indices = device.createBuffer({
+            label: "Water / surface indices",
+            size: indices.byteLength,
+            usage: GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST,
+        });
+
+        device.queue.writeBuffer(this.#indices, 0, indices);
+
+        this.#index_resolution = this.resolution;
+        this.#index_count = indices.length;
+    }
+
+    /**
+     * @param {GPUDevice} device
+     * @param {Object} surface
+     * @returns {WaterWaveBody}
+     */
+    #ensure_body(device, surface) {
+        const existing = this.#bodies.get(surface);
+
+        if (existing !== undefined) {
+            return existing;
+        }
+
+        const resolution = this.resolution;
+        const vertex_count = resolution * resolution;
+
+        const state_buffer = (label) => device.createBuffer({
+            label,
+            size: vertex_count * 4,
+            usage: GPUBufferUsage.STORAGE,
+        });
+
+        /** @type {WaterWaveBody} */
+        const body = {
+            resolution,
+            state: [state_buffer("Water / wave state A"), state_buffer("Water / wave state B")],
+            parity: 0,
+            vertices: device.createBuffer({
+                label: "Water / surface vertices",
+                size: vertex_count * VERTEX_BYTES,
+                usage: GPUBufferUsage.STORAGE,
+            }),
+            written: false,
+        };
+
+        this.#bodies.set(surface, body);
+
+        return body;
+    }
+
+    /**
+     * @param {Object} surface
+     * @param {WaterWaveBody} body
+     * @param {number} time
+     * @param {number} impulse_count
+     */
+    #parameters(surface, body, time, impulse_count) {
+        const extent = surface.extent;
+        const wind = surface.wind_speed;
+        const direction = surface.wind_direction;
+        const spacing = (extent[2] - extent[0]) / (body.resolution - 1);
+
+        return {
+            extent: Array.from(extent),
+            height_uv: Array.from(surface.height_uv),
+            forcing: [Math.cos(direction), Math.sin(direction), FORCING_PER_WIND2 * wind * wind, 0.5 * wind],
+            impulses: surface.impulses,
+            level: surface.level,
+            spacing,
+            dt: this.step,
+            time,
+            damping: this.damping,
+            sponge_width: Math.max(4, Math.round(body.resolution * 0.04)),
+            sponge_strength: 4,
+            // 2-D CFL: c·dt/dx ≤ 1/√2, with a margin
+            celerity_limit: 0.6 * spacing / this.step,
+            unresolved_variance: wind_unresolved_variance(wind),
+            resolution: body.resolution,
+            impulse_count,
+            first_write: body.written ? 0 : 1,
+        };
+    }
+
+    /**
+     * @param {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} graph
+     * @param {Object} surface
+     * @param {WaterWaveBody} body
+     * @param {number} steps
+     * @param {number} time_start
+     */
+    #record_body(graph, surface, body, steps, time_start) {
+        const groups = Math.ceil(body.resolution / 8);
+        // impulses wait for a frame that steps: a paused frame must not drop them
+        const impulses = steps > 0 ? surface.impulses.splice(0, WATER_WAVE_IMPULSE_LIMIT) : [];
+        const parameters = [];
+
+        for (let s = 0; s < steps; s++) {
+            parameters.push(this.#parameters(surface, body, time_start + s * this.step,
+                s === 0 ? impulses.length : 0));
+        }
+
+        while (impulses.length < WATER_WAVE_IMPULSE_LIMIT) {
+            impulses.push([0, 0, 0, 0]);
+        }
+
+        for (const p of parameters) { p.impulses = impulses; }
+
+        const write_parameters = this.#parameters(surface, body, time_start + steps * this.step, 0);
+        write_parameters.impulses = impulses;
+
+        const start_parity = body.parity;
+        body.parity = (start_parity + steps) % 2;
+        body.written = true;
+
+        const end_parity = body.parity;
+
+        const pass = graph.add("Water / surface update", {}, (data, resources, { encoder, graphics }) => {
+            const terrain_height = graphics.textures.obtain(surface.height_texture).obtainView();
+            const height_sampler = graphics.samplers.obtain(SAMPLER_LINEAR_UPSCALE);
+
+            let parity = start_parity;
+
+            for (let s = 0; s < parameters.length; s++) {
+                shader_water_wave_step.dispatch({
+                    encoder,
+                    bindings: {
+                        params: encoder.allocateTransientValueBuffer(WATER_WAVE_PARAMETERS_STRUCT, parameters[s]),
+                        terrain_height,
+                        height_sampler,
+                        state_current: body.state[parity],
+                        state_previous: body.state[1 - parity],
+                    },
+                    group_count_x: groups,
+                    group_count_y: groups,
+                });
+
+                parity = 1 - parity;
+            }
+
+            shader_water_surface_write.dispatch({
+                encoder,
+                bindings: {
+                    params: encoder.allocateTransientValueBuffer(WATER_WAVE_PARAMETERS_STRUCT, write_parameters),
+                    terrain_height,
+                    height_sampler,
+                    state: body.state[end_parity],
+                    vertices: body.vertices,
+                },
+                group_count_x: groups,
+                group_count_y: groups,
+            });
+        });
+
+        // writes persistent resources that later passes read directly
+        pass.make_side_effect();
+    }
+}
+
+/**
+ * Slope variance of the waves a grid does not resolve, from the wind: the Cox-Munk total,
+ * 0.003 + 5.12e-3·U for wind speed U in m/s (Ocean Optics Web Book, "Cox-Munk sea surface slope
+ * statistics"). The fit's intercept is ramped in below 1 m/s, where it has no data, so still water
+ * is a mirror rather than carrying the open sea's background slopes.
+ *
+ * @param {number} wind_speed m/s
+ * @returns {number}
+ */
+export function wind_unresolved_variance(wind_speed) {
+    const u = Math.max(wind_speed, 0);
+    return 0.003 * Math.min(u, 1) + 5.12e-3 * u;
+}

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

@@ -0,0 +1,12 @@
+/**
+ * One vertex of a water surface: what every surface producer writes and the water draws read.
+ *
+ * This and a producer-owned index buffer are the whole surface interface
+ * (WATER_OPTICS_PLAN_2026_10_02.md §7.2). A producer that is not a height field writes the same
+ * record, so the draws never learn which producer ran.
+ *
+ * @type {WebGPUStruct}
+ */
+export const WATER_SURFACE_VERTEX_STRUCT: WebGPUStruct;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+//# sourceMappingURL=WATER_SURFACE_VERTEX_STRUCT.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"WATER_SURFACE_VERTEX_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/water/surface/WATER_SURFACE_VERTEX_STRUCT.js"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AACH,0CAFU,YAAY,CAgBG;6BAzBI,mCAAmC"}

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

@@ -0,0 +1,27 @@
+import { vec4f } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+
+/**
+ * One vertex of a water surface: what every surface producer writes and the water draws read.
+ *
+ * This and a producer-owned index buffer are the whole surface interface
+ * (WATER_OPTICS_PLAN_2026_10_02.md §7.2). A producer that is not a height field writes the same
+ * record, so the draws never learn which producer ran.
+ *
+ * @type {WebGPUStruct}
+ */
+export const WATER_SURFACE_VERTEX_STRUCT = WebGPUStruct.from({
+    /**
+     * World position in `xyz`. `w` is the slope variance of the waves this mesh does not resolve,
+     * which the shading adds to its roughness.
+     */
+    position: vec4f,
+    /**
+     * Last frame's world position in `xyz`, for motion vectors. `w` is unused.
+     */
+    previous: vec4f,
+    /**
+     * Unit world normal in `xyz`. `w` is unused.
+     */
+    normal: vec4f,
+}, "WaterSurfaceVertex");

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

@@ -0,0 +1,14 @@
+/**
+ * Most impulses one body applies in one step.
+ * @type {number}
+ */
+export const WATER_WAVE_IMPULSE_LIMIT: number;
+/**
+ * Per-body, per-step inputs of the primitive wave producer: its grid, the terrain it floods, the
+ * step and the forcing.
+ *
+ * @type {WebGPUStruct}
+ */
+export const WATER_WAVE_PARAMETERS_STRUCT: WebGPUStruct;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+//# sourceMappingURL=WATER_WAVE_PARAMETERS_STRUCT.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"WATER_WAVE_PARAMETERS_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/water/surface/WATER_WAVE_PARAMETERS_STRUCT.js"],"names":[],"mappings":"AAIA;;;GAGG;AACH,uCAFU,MAAM,CAE2B;AAE3C;;;;;GAKG;AACH,2CAFU,YAAY,CAkCI;6BA9CG,mCAAmC"}

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

@@ -0,0 +1,49 @@
+import { f32, u32, vec4f } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+
+/**
+ * Most impulses one body applies in one step.
+ * @type {number}
+ */
+export const WATER_WAVE_IMPULSE_LIMIT = 16;
+
+/**
+ * Per-body, per-step inputs of the primitive wave producer: its grid, the terrain it floods, the
+ * step and the forcing.
+ *
+ * @type {WebGPUStruct}
+ */
+export const WATER_WAVE_PARAMETERS_STRUCT = WebGPUStruct.from({
+    /** world-space grid rectangle: min x, min z, max x, max z */
+    extent: vec4f,
+    /** terrain height texture coordinates of the grid: `uv * zw + xy` */
+    height_uv: vec4f,
+    /** wind direction x, z (unit); forcing amplitude, m/s²; forcing drift speed, m/s */
+    forcing: vec4f,
+    /** queued impulses: world x, world z, radius m, velocity kick m/s */
+    impulses: WebGPUArray.from(vec4f, WATER_WAVE_IMPULSE_LIMIT),
+    /** rest height of the surface */
+    level: f32,
+    /** distance between neighbouring vertices, m */
+    spacing: f32,
+    /** step, s */
+    dt: f32,
+    /** simulated time, s */
+    time: f32,
+    /** damping rate everywhere, 1/s */
+    damping: f32,
+    /** border band of extra damping, vertices */
+    sponge_width: f32,
+    /** damping at the border, 1/s */
+    sponge_strength: f32,
+    /** largest celerity the step stays stable at, m/s */
+    celerity_limit: f32,
+    /** slope variance of the waves the grid does not resolve */
+    unresolved_variance: f32,
+    /** vertices along each side */
+    resolution: u32,
+    impulse_count: u32,
+    /** 1 on the first write after the body's buffers were created, so `previous` starts at `position` */
+    first_write: u32,
+}, "WaterWaveParameters");

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

@@ -0,0 +1,15 @@
+/**
+ * The primitive surface producer's physics, as pure functions so each is testable alone.
+ *
+ * A damped linear wave equation on a height field, `h_tt = c² ∇²h − γ h_t + f`, stepped by
+ * leapfrog. The celerity is the shallow-water one, `c = √(g·d)`, so waves slow down and turn in
+ * shallows and reflect from the shore. That is right for long waves and wrong for deep-water wind
+ * waves, whose speed depends on their wavelength rather than on depth: a stated limit of a
+ * primitive simulation, which the production simulation replaces behind the surface interface
+ * (WATER_OPTICS_PLAN_2026_10_02.md §7.2).
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_water_wave: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_water_wave.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_water_wave.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/water/surface/chunk_water_wave.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,+BAFU,SAAS,CAmChB;0BA/CuB,oCAAoC"}

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

@@ -0,0 +1,48 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+
+/**
+ * The primitive surface producer's physics, as pure functions so each is testable alone.
+ *
+ * A damped linear wave equation on a height field, `h_tt = c² ∇²h − γ h_t + f`, stepped by
+ * leapfrog. The celerity is the shallow-water one, `c = √(g·d)`, so waves slow down and turn in
+ * shallows and reflect from the shore. That is right for long waves and wrong for deep-water wind
+ * waves, whose speed depends on their wavelength rather than on depth: a stated limit of a
+ * primitive simulation, which the production simulation replaces behind the surface interface
+ * (WATER_OPTICS_PLAN_2026_10_02.md §7.2).
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_water_wave = CodeChunk.from(/* language=WGSL */ `
+const WATER_WAVE_GRAVITY: f32 = 9.81;
+
+// Squared celerity of a long wave over water depth metres deep, capped so an explicit step of the
+// size the producer takes stays stable (2-D CFL: c·dt/dx ≤ 1/√2).
+fn water_wave_celerity2(depth: f32, celerity_limit: f32) -> f32 {
+    return min(WATER_WAVE_GRAVITY * max(depth, 0.0), celerity_limit * celerity_limit);
+}
+
+// One leapfrog step of h_tt = c² ∇²h − γ h_t + f: the next height from the current one, the
+// previous one, the current height's Laplacian, c², the damping rate γ (1/s), the forcing f (m/s²)
+// and the step dt (s).
+fn water_wave_step(h: f32, h_previous: f32, laplacian: f32, celerity2: f32, damping: f32,
+    force: f32, dt: f32) -> f32 {
+    return h + (h - h_previous) * max(1.0 - damping * dt, 0.0) + dt * dt * (celerity2 * laplacian + force);
+}
+
+// Extra damping in a band along the grid's border, rising quadratically to strength at the edge,
+// so waves leave the domain instead of reflecting off the end of the grid.
+fn water_wave_sponge(cell: vec2<u32>, resolution: u32, width: f32, strength: f32) -> f32 {
+    let last = f32(resolution - 1u);
+    let p = vec2<f32>(cell);
+    let edge = min(min(p.x, p.y), min(last - p.x, last - p.y));
+    let s = clamp(1.0 - edge / max(width, 1.0), 0.0, 1.0);
+    return strength * s * s;
+}
+
+// Unit normal of a height field from central differences of its heights at the four neighbours,
+// spacing metres apart.
+fn water_wave_normal(left: f32, right: f32, down: f32, up: f32, spacing: f32) -> vec3<f32> {
+    let slope = vec2<f32>(right - left, up - down) / (2.0 * spacing);
+    return normalize(vec3<f32>(-slope.x, 1.0, -slope.y));
+}
+`);

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

@@ -0,0 +1,9 @@
+/**
+ * Grid addressing, terrain lookup and forcing of the primitive wave producer. Expects `params`
+ * ({@link WATER_WAVE_PARAMETERS_STRUCT}), `terrain_height` and `height_sampler` bound.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_water_wave_grid: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_water_wave_grid.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_water_wave_grid.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/water/surface/chunk_water_wave_grid.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,oCAFU,SAAS,CAuCG;0BA9CI,oCAAoC"}

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

@@ -0,0 +1,47 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { chunk_srdnoise2 } from "../../shader/chunk/noise/psrdnoise/chunk_srdnoise2.js";
+
+/**
+ * Grid addressing, terrain lookup and forcing of the primitive wave producer. Expects `params`
+ * ({@link WATER_WAVE_PARAMETERS_STRUCT}), `terrain_height` and `height_sampler` bound.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_water_wave_grid = CodeChunk.from(/* language=WGSL */ `
+// Spatial scale of the wind's pressure pattern, m.
+const WATER_WAVE_FORCING_SCALE: f32 = 6.0;
+
+fn water_wave_grid_uv(cell: vec2<u32>) -> vec2<f32> {
+    return vec2<f32>(cell) / f32(params.resolution - 1u);
+}
+
+fn water_wave_world(cell: vec2<u32>) -> vec2<f32> {
+    return mix(params.extent.xy, params.extent.zw, water_wave_grid_uv(cell));
+}
+
+fn water_wave_terrain(cell: vec2<u32>) -> f32 {
+    let uv = water_wave_grid_uv(cell) * params.height_uv.zw + params.height_uv.xy;
+    return textureSampleLevel(terrain_height, height_sampler, uv, 0.0).r;
+}
+
+// Clamped at the grid's edge, which reflects; the sponge band absorbs before waves get there.
+fn water_wave_index(cell: vec2<i32>) -> u32 {
+    let n = i32(params.resolution);
+    let c = clamp(cell, vec2<i32>(0), vec2<i32>(n - 1));
+    return u32(c.y * n + c.x);
+}
+
+// Wind: a pressure pattern drifting downwind, plus this step's impulses as velocity kicks spread
+// over one step.
+fn water_wave_force(world: vec2<f32>) -> f32 {
+    let drift = params.forcing.xy * params.forcing.w * params.time;
+    var force = params.forcing.z * srdnoise2((world - drift) / WATER_WAVE_FORCING_SCALE, 0.0).x;
+    for (var i = 0u; i < params.impulse_count; i++) {
+        let impulse = params.impulses[i];
+        let r = max(impulse.z, 1e-3);
+        let d = world - impulse.xy;
+        force += impulse.w / params.dt * exp(-dot(d, d) / (r * r));
+    }
+    return force;
+}
+`, [chunk_srdnoise2]);

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

@@ -0,0 +1,10 @@
+/**
+ * Writes the surface interface from the primitive producer's heights: the vertex record every
+ * water draw reads. A dry vertex sits at the rest level, under the terrain, where the opaque depth
+ * hides it.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_water_surface_write: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_water_surface_write.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_water_surface_write.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/water/surface/shader_water_surface_write.js"],"names":[],"mappings":"AAkBA;;;;;;GAMG;AACH,yCAFU,aAAa,CA2BpB;8BAlD2B,+BAA+B"}