@woosh/meep-engine 3.37.0 → 3.39.0

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

@@ -0,0 +1,268 @@
+import { CAMERA_UNIFORM_STRUCT } from "../camera/CAMERA_UNIFORM_STRUCT.js";
+import { chunk_sample_volumetrics } from "../deferred/chunk_sample_volumetrics.js";
+import { AVBOIT_OCCUPANCY_WORDS, AVBOIT_VOXEL_DOWNSCALE } from "../rasterize/native/avboit/AVBOIT_CONSTANTS.js";
+import { AVBOIT_WARP_STRUCT } from "../rasterize/native/avboit/AVBOIT_WARP_STRUCT.js";
+import { AVBOIT_DRAW_TARGETS } from "../rasterize/native/avboit/avboit_draw_fragment_body.js";
+import { chunk_avboit_footprint_bias } from "../rasterize/native/avboit/chunk_avboit_footprint_bias.js";
+import { chunk_avboit_occupancy_mark } from "../rasterize/native/avboit/chunk_avboit_occupancy_mark.js";
+import { chunk_avboit_rgb_contribution } from "../rasterize/native/avboit/chunk_avboit_rgb_contribution.js";
+import { chunk_avboit_sample_transmittance } from "../rasterize/native/avboit/chunk_avboit_sample_transmittance.js";
+import { chunk_avboit_splat_slice } from "../rasterize/native/avboit/chunk_avboit_splat_slice.js";
+import { chunk_avboit_split_counts } from "../rasterize/native/avboit/chunk_avboit_split_counts.js";
+import { chunk_avboit_transmittance_to_extinction } from "../rasterize/native/avboit/chunk_avboit_transmittance_to_extinction.js";
+import { chunk_avboit_view_depth_to_physical } from "../rasterize/native/avboit/chunk_avboit_view_depth_to_physical.js";
+import { chunk_avboit_view_depth_to_virtual } from "../rasterize/native/avboit/chunk_avboit_view_depth_to_virtual.js";
+import { AVBOIT_OCCUPANCY_SETTINGS_STRUCT } from "../rasterize/native/avboit/shader_avboit_occupancy.js";
+import { chunk_get_view_space_depth } from "../shader/chunk/depth/chunk_get_view_space_depth.js";
+import { chunk_is_background } from "../shader/chunk/depth/chunk_is_background.js";
+import { chunk_is_on_screen_i32 } from "../shader/chunk/texture/chunk_is_on_screen_i32.js";
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../shader/ComputeShader.js";
+import { ImageShader } from "../shader/ImageShader.js";
+import { ShaderResourceSetDescriptor } from "../shader/resource/ShaderResourceSetDescriptor.js";
+import { ShaderDescriptor } from "../shader/ShaderDescriptor.js";
+import { atomic_u32, u32, vec2f } from "../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../shader/type/WebGPUStruct.js";
+import { SAMPLER_LINEAR_UPSCALE } from "../texture/SAMPLER_LINEAR_UPSCALE.js";
+import { VIEW_UNIFORM_STRUCT } from "../view/VIEW_UNIFORM_STRUCT.js";
+import { VOLUMETRICS_METADATA_STRUCT } from "../volumetrics/VOLUMETRICS_METADATA_STRUCT.js";
+import { DepthStencilState } from '../../descriptor/pipeline/render/DepthStencilState.js';
+export { chunk_water_refraction_confidence } from './chunk_water_transport.js';
+
+const occupancy_resources = new ShaderResourceSetDescriptor();
+occupancy_resources.createGroup().addUniform("camera", CAMERA_UNIFORM_STRUCT)
+    .addUniform("settings", AVBOIT_OCCUPANCY_SETTINGS_STRUCT)
+    .addTexture("interface_depth").addStorageBuffer("occupancy", WebGPUArray.from(atomic_u32, AVBOIT_OCCUPANCY_WORDS), true);
+
+export const shader_water_occupancy = ComputeShader.from({
+    label: "Water / AVBOIT occupancy", resources: occupancy_resources,
+    body: CodeChunk.from(/* language=WGSL */ `
+var<workgroup> depth_min: atomic<u32>;
+var<workgroup> depth_max: atomic<u32>;
+@compute @workgroup_size(8, 8)
+fn main(@builtin(global_invocation_id) id: vec3u, @builtin(local_invocation_index) index: u32) {
+    if (index == 0u) { atomicStore(&depth_min, bitcast<u32>(1e30)); atomicStore(&depth_max, 0u); }
+    workgroupBarrier();
+    let size = textureDimensions(interface_depth, 0);
+    if (all(id.xy < size)) {
+        let d = textureLoad(interface_depth, id.xy, 0).r;
+        if (d > 0.0) {
+            let z = clamp(get_view_space_depth(d, camera), camera.clip_near_far.x, camera.clip_near_far.y);
+            atomicMin(&depth_min, bitcast<u32>(z)); atomicMax(&depth_max, bitcast<u32>(z));
+        }
+    }
+    workgroupBarrier();
+    if (index == 0u && atomicLoad(&depth_max) != 0u) {
+        avboit_occupancy_mark(bitcast<f32>(atomicLoad(&depth_min)), bitcast<f32>(atomicLoad(&depth_max)),
+            camera.clip_near_far.x, settings.cluster_parameters);
+    }
+}
+`, [chunk_get_view_space_depth, chunk_avboit_occupancy_mark]),
+});
+
+const splat_resources = new ShaderResourceSetDescriptor();
+splat_resources.createGroup().addUniform("camera", CAMERA_UNIFORM_STRUCT)
+    .addStorageBuffer("warp", AVBOIT_WARP_STRUCT).addTexture("interface_depth").addTexture("transmission")
+    .addStorageBuffer("extinction_volume", WebGPUArray.from(atomic_u32), true)
+    .addStorageBuffer("overflow_slice", WebGPUArray.from(atomic_u32), true);
+
+export const shader_water_splat = ComputeShader.from({
+    label: "Water / AVBOIT splat", resources: splat_resources,
+    body: CodeChunk.from(/* language=WGSL */ `
+@compute @workgroup_size(8, 8)
+fn main(@builtin(global_invocation_id) id: vec3u) {
+    if (id.x >= warp.voxel_width || id.y >= warp.voxel_height) { return; }
+    let size = textureDimensions(interface_depth, 0);
+    let lo = id.xy * ${AVBOIT_VOXEL_DOWNSCALE}u;
+    let hi = min(lo + vec2u(${AVBOIT_VOXEL_DOWNSCALE}u), size);
+    var total_t = vec3f(0.0);
+    var samples = 0.0;
+    var nearest = 1e30;
+    for (var y = lo.y; y < hi.y; y++) {
+        for (var x = lo.x; x < hi.x; x++) {
+            let coord = vec2u(x, y);
+            let d = textureLoad(interface_depth, coord, 0).r;
+            var t = vec3f(1.0);
+            if (d > 0.0) {
+                t = textureLoad(transmission, coord, 0).rgb;
+                nearest = min(nearest, get_view_space_depth(d, camera));
+            }
+            total_t += t; samples += 1.0;
+        }
+    }
+    if (nearest == 1e30 || samples == 0.0) { return; }
+    // One area-averaged event, not 64 full-coverage layers. Dry samples retain T=1.
+    let extinction = avboit_transmittance_to_extinction(total_t / samples);
+    let counts = avboit_extinction_to_counts(extinction);
+    let p = avboit_view_depth_to_physical(&warp, nearest) - 0.5;
+    let slice = i32(floor(p));
+    let upper = avboit_split_counts(counts, fract(p));
+    let column = (id.y * warp.voxel_width + id.x) * warp.physical_count;
+    avboit_splat_counts(column, slice, counts - upper, id.xy);
+    avboit_splat_counts(column, slice + 1, upper, id.xy);
+}
+`, [chunk_get_view_space_depth, chunk_avboit_splat_slice, chunk_avboit_split_counts,
+    chunk_avboit_transmittance_to_extinction, chunk_avboit_view_depth_to_physical]),
+});
+
+const draw_resources = new ShaderResourceSetDescriptor();
+draw_resources.createGroup().addUniform("camera", CAMERA_UNIFORM_STRUCT).addUniform("view", VIEW_UNIFORM_STRUCT)
+    .addStorageBuffer("warp", AVBOIT_WARP_STRUCT).addTexture("interface_depth")
+    .addTexture("transmission").addTexture("radiance")
+    .addTexture("tIntegral", "float", "3d").addSampler("sLinear", "filtering", SAMPLER_LINEAR_UPSCALE)
+    .addUniform("volumetrics_metadata", VOLUMETRICS_METADATA_STRUCT)
+    .addTexture("tVolumetrics", "float", "3d").addTexture("tSTBN_vec3", "float", "3d");
+
+export const shader_water_draw = ImageShader.from({
+    descriptor: ShaderDescriptor.from({ label: "Water / AVBOIT draw", resources: draw_resources,
+        body: CodeChunk.from(/* language=WGSL */ `
+struct WaterContribution {
+    @location(0) color: vec4f, @location(1) norm: vec4f,
+    @location(2) extinction: vec4f, @location(3) emission: vec4f,
+}
+@fragment
+fn main(@builtin(position) coord: vec4f) -> WaterContribution {
+    let pixel = vec2u(coord.xy);
+    let d = textureLoad(interface_depth, pixel, 0).r;
+    let z = get_view_space_depth(d, camera);
+    // the water splats into the volume too, and a plane seen at an angle runs through depth across a
+    // voxel (avboit_footprint_bias). Taken before the discard, in uniform control flow; a dry pixel's
+    // virtual coordinate clamps, so the derivative at the shore stays finite and the cap holds it
+    let footprint = avboit_footprint_bias(&warp, fwidth(avboit_view_depth_to_virtual(&warp, z)));
+    if (d <= 0.0) { discard; }
+    let uv = coord.xy / vec2f(textureDimensions(interface_depth, 0));
+    let front = avboit_sample_transmittance(&warp, tIntegral, sLinear, uv, z, footprint);
+    let t = textureLoad(transmission, pixel, 0).rgb;
+    let w = textureLoad(radiance, pixel, 0).rgb;
+    let fog = sample_volumetrics(z, uv, coord.xy);
+    let c = avboit_rgb_contribution(w, t, front, fog);
+    return WaterContribution(c.color, c.norm, c.extinction, c.emission);
+}
+`, [chunk_get_view_space_depth, chunk_avboit_view_depth_to_virtual, chunk_avboit_footprint_bias,
+            chunk_avboit_sample_transmittance, chunk_avboit_rgb_contribution, chunk_sample_volumetrics]),
+    }), targets: AVBOIT_DRAW_TARGETS,
+});
+
+// A depth buffer cannot reveal the receiver hidden behind an emergent object.
+// Fade displacement around those disocclusions instead of exposing a hard control-UV hole.
+// Quarter-resolution conservative seeds and a separable bounded distance transform keep
+// this independent of scene size and avoid a full-resolution neighbourhood search.
+const confidence_seed_resources = new ShaderResourceSetDescriptor();
+confidence_seed_resources.createGroup().addTexture("trace_metadata").addTexture("scene_depth");
+export const shader_water_confidence_seed = ImageShader.from({
+    descriptor: ShaderDescriptor.from({ label: "Water / visibility seeds", resources: confidence_seed_resources,
+        body: CodeChunk.from(/* language=WGSL */ `
+@fragment
+fn main(@builtin(position) coord: vec4f) -> @location(0) vec4f {
+    let tile = vec2u(coord.xy) * 4u;
+    let size = textureDimensions(trace_metadata, 0);
+    var distance = 16.0;
+    for (var y = 0u; y < 4u; y++) {
+        for (var x = 0u; x < 4u; x++) {
+            let pixel = tile + vec2u(x, y);
+            if (all(pixel < size)) {
+                let t = textureLoad(trace_metadata, pixel, 0);
+                // Only actual geometry/sky boundaries seed the spatial fade. Trace budget
+                // or numerical failures must not create moving 64-pixel holes around themselves.
+                if (t.b <= 0.0 || is_background(textureLoad(scene_depth, pixel, 0).r)) { distance = 0.0; }
+            }
+        }
+    }
+    return vec4f(distance, 0.0, 0.0, 1.0);
+}
+`, [chunk_is_background]),
+    }), targets: [{ format: "r16float" }],
+});
+
+function confidence_distance_shader(vertical) {
+    const resources = new ShaderResourceSetDescriptor();
+    resources.createGroup().addTexture("distance_field");
+    return ImageShader.from({ descriptor: ShaderDescriptor.from({
+        label: vertical ? "Water / visibility distance Y" : "Water / visibility distance X", resources,
+        body: CodeChunk.from(/* language=WGSL */ `
+@fragment
+fn main(@builtin(position) coord: vec4f) -> @location(0) vec4f {
+    let pixel = vec2i(coord.xy);
+    let size = vec2i(textureDimensions(distance_field, 0));
+    var distance = 16.0;
+    for (var offset = -16; offset <= 16; offset++) {
+        let sample = pixel + ${vertical ? "vec2i(0, offset)" : "vec2i(offset, 0)"};
+        if (is_on_screen_i32(sample, size)) {
+            let d = textureLoad(distance_field, sample, 0).r;
+            distance = min(distance, ${vertical ? "length(vec2f(d, f32(offset)))" : "d + abs(f32(offset))"});
+        }
+    }
+    return vec4f(distance, 0.0, 0.0, 1.0);
+}
+`, [chunk_is_on_screen_i32]),
+    }), targets: [{ format: "r16float" }] });
+}
+export const shader_water_confidence_x = confidence_distance_shader(false);
+export const shader_water_confidence_y = confidence_distance_shader(true);
+
+// Initialize all three final targets in the same render pass as water shading.
+// This samples opaque HDR and needs no COPY_SRC usage or renderer changes.
+const background_resources = new ShaderResourceSetDescriptor();
+background_resources.createGroup().addTexture('tScene');
+export const shader_water_background_copy = ImageShader.from({
+    descriptor: ShaderDescriptor.from({label: 'Water / background initialization', resources: background_resources,
+        body: CodeChunk.from(/* language=WGSL */ `
+struct WaterBackground {
+    @location(0) transmission: vec4f, @location(1) radiance: vec4f, @location(2) background: vec4f,
+}
+@fragment
+fn main(@builtin(position) coord: vec4f) -> WaterBackground {
+    return WaterBackground(vec4f(1.0,1.0,1.0,0.0), vec4f(0.0), textureLoad(tScene, vec2i(coord.xy), 0));
+}
+`)}), targets: [{format:'rgba32float'}, {format:'rgba16float'}, {format:'rgba16float'}],
+    depthStencil: DepthStencilState.from({format:'depth32float', depthWriteEnabled:false, depthCompare:'always'}),
+});
+
+const debug_resources = new ShaderResourceSetDescriptor();
+debug_resources.createGroup().addUniform("inspection", WebGPUStruct.from({ mode: u32, resolution: vec2f }, "WaterInspection").pack())
+    .addUniform("camera", CAMERA_UNIFORM_STRUCT).addStorageBuffer("warp", AVBOIT_WARP_STRUCT)
+    .addTexture("tIntegral", "float", "3d").addSampler("sLinear", "filtering", SAMPLER_LINEAR_UPSCALE).addTexture("transmission")
+    .addTexture("radiance").addTexture("receiver").addTexture("interface_depth").addTexture("trace_metadata");
+export const shader_water_debug = ImageShader.from({
+    descriptor: ShaderDescriptor.from({ label: "Water / inspection", resources: debug_resources,
+        body: CodeChunk.from(/* language=WGSL */ `
+@fragment
+fn main(@builtin(position) coord: vec4f) -> @location(0) vec4f {
+    let uv = coord.xy / inspection.resolution;
+    let pixel = min(vec2u(uv*vec2f(textureDimensions(transmission,0))), textureDimensions(transmission,0)-1u);
+    let t = textureLoad(transmission, pixel, 0);
+    let r = textureLoad(receiver, pixel, 0);
+    if (t.a <= 0.0) { return vec4f(0.025, 0.025, 0.025, 1.0); }
+    var color = t.rgb;
+    switch (inspection.mode) {
+        case 1u: { color = vec3f(t.a); }
+        case 2u: { color = vec3f(r.xy, 0.0); }
+        case 3u: { color = vec3f(r.z / (r.z + 10.0)); }
+        case 4u: {
+            let code = u32(floor(r.w));
+            var palette = array<vec3f,5>(vec3f(0.1,0.9,0.1),vec3f(0.1,0.7,1.0),
+                vec3f(0.4,0.2,0.8),vec3f(0.8,0.3,0.1),vec3f(0.9,0.1,0.6));
+            color = palette[min(code / 8u, 4u)];
+            if (code == 31u) { color = palette[4]; }
+            color.r = max(color.r, fract(r.w) * 2.0);
+        }
+        case 5u: { color = textureLoad(radiance, pixel, 0).rgb; }
+        case 6u: { color = vec3f(min(textureLoad(trace_metadata, pixel, 0).g, 1.0)); }
+        case 10u: {
+            color = vec3f(textureLoad(radiance, pixel, 0).a);
+        }
+        case 8u, 9u: {
+            let z = get_view_space_depth(textureLoad(interface_depth, pixel, 0).r, camera);
+            // without the draw's footprint (a derivative this switch cannot take): where the water is
+            // seen at an angle this also shows it occluding itself, which the draw looks past
+            let front = avboit_sample_transmittance(&warp, tIntegral, sLinear, uv, z, 0.0);
+            color = select(front, (1.0 - t.rgb) * front, inspection.mode == 9u);
+        }
+        default: {}
+    }
+    return vec4f(color, 1.0);
+}
+`, [chunk_get_view_space_depth, chunk_avboit_sample_transmittance]),
+    }), targets: [{ format: "rgba16float" }],
+});

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

@@ -0,0 +1,98 @@
+/**
+ * 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: number): number;
+/**
+ * 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: number;
+    /**
+     * Fixed step, s. Explicit and fixed, so a frame-rate change does not change the waves.
+     * @type {number}
+     */
+    step: number;
+    /**
+     * 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: number;
+    /**
+     * Damping everywhere, 1/s.
+     * @type {number}
+     */
+    damping: number;
+    /**
+     * Simulated time, s.
+     * @returns {number}
+     */
+    get time(): number;
+    /**
+     * @param {number} dt seconds of simulation to add
+     */
+    advance(dt: number): void;
+    /**
+     * Release every GPU resource.
+     */
+    dispose(): void;
+    /**
+     * 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 }: {
+        graph: import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
+        device: GPUDevice;
+        surfaces: any[];
+    }): void;
+    #private;
+}
+/**
+ * What one body holds on the GPU.
+ */
+export type WaterWaveBody = {
+    resolution: number;
+    /**
+     * the two alternating height buffers
+     */
+    state: GPUBuffer[];
+    /**
+     * which of {@link state } holds the current heights
+     */
+    parity: number;
+    vertices: GPUBuffer;
+    written: boolean;
+};
+//# sourceMappingURL=GPUWaterWaveSimulation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"GPUWaterWaveSimulation.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/water/surface/GPUWaterWaveSimulation.js"],"names":[],"mappings":"AA2YA;;;;;;;;GAQG;AACH,qDAHW,MAAM,GACJ,MAAM,CAKlB;AAhYD;;;;;;;;;GASG;AAEH;;;;;;;;;GASG;AACH;IACI;;;OAGG;IACH,YAFU,MAAM,CAEC;IAEjB;;;OAGG;IACH,MAFU,MAAM,CAED;IAEf;;;;OAIG;IACH,qBAFU,MAAM,CAEQ;IAExB;;;OAGG;IACH,SAFU,MAAM,CAED;IAwCf;;;OAGG;IACH,mBAEC;IAED;;OAEG;IACH,YAFW,MAAM,QAQhB;IAED;;OAEG;IACH,gBAaC;IAED;;;;;;;;OAQG;IACH;QAJsG,KAAK,EAAhG,OAAO,8DAA8D,EAAE,UAAU;QAC9D,MAAM;QACP,QAAQ,EAA1B,KAAQ;aAiDlB;;CAgMJ;;;;;gBA9Wa,MAAM;;;;WACN,WAAW;;;;YACX,MAAM;;aAEN,OAAO"}