@woosh/meep-engine 3.36.0 → 3.38.0

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

@@ -1,167 +1,255 @@
-import { assert } from "../../../core/assert.js";
-import { TextureViewDescriptor } from "../../descriptor/texture/TextureViewDescriptor.js";
+import { half_to_float_uint16 } from "../../../core/binary/half_to_float_uint16.js";
+import { TextureResourceDescriptor } from "../../device/graph/TextureResourceDescriptor.js";
+import { DEFAULT_DEPTH_TEXTURE_VIEW } from "../depth/DEFAULT_DEPTH_TEXTURE_VIEW.js";
+import { graph_compute_pass } from "../shader/graph/compute/graph_compute_pass.js";
+import { graph_image_pass } from "../shader/graph/graph_image_pass.js";
+import { STATIC_GRAPHICS_ENGINE_ASSETS } from "../STATIC_GRAPHICS_ENGINE_ASSETS.js";
 import { SAMPLER_LINEAR_UPSCALE } from "../texture/SAMPLER_LINEAR_UPSCALE.js";
-import { create_water_pipeline, WATER_DRAW_STRUCT, WATER_RESOURCES } from "./shader_water.js";
+import { create_water_pipeline, create_water_finalize_pipeline, WATER_DRAW_STRUCT, WATER_TRACE_STRUCT,
+    WATER_RESOURCES, WATER_FINALIZE_RESOURCES } from "./shader_water.js";
+import { shader_water_background_copy, shader_water_debug, shader_water_draw,
+    shader_water_occupancy, shader_water_splat, shader_water_confidence_seed,
+    shader_water_confidence_x, shader_water_confidence_y } from "./shader_water_avboit.js";
 
-/**
- * Vertices per surface. Two triangles, generated from the vertex index — the surface is a rectangle
- * at a constant height, so there is nothing to upload.
- *
- * @type {number}
- */
-const VERTICES_PER_SURFACE = 6;
-
-/**
- * Draws water surfaces over a lit frame.
- *
- * **Water is a transparent pass on top of opaque**, which is why it lives here rather than in the
- * material system: it is not shaded, it does not write the G-buffer, and it needs the finished
- * depth of everything behind it in order to know how much water the view is looking through.
- *
- * The pass reads scene depth and writes the frame's colour, so it belongs at
- * {@link FramePhase.AfterLighting} — opaque surfaces lit and composited, transparency not yet run.
- */
+/** Production water channel. Only AVBOIT's shared resolve composites its radiance. */
 export class GPUWaterRenderer {
-    /**
-     * @type {RenderPipelineDescriptor|null}
-     */
-    #pipeline = null;
-
-    /**
-     * @type {string}
-     */
-    #pipeline_color_format = "";
-
-    /**
-     * @param {string} color_format the frame colour this draws over
-     * @returns {RenderPipelineDescriptor}
-     */
-    #obtain_pipeline(color_format) {
-        if (this.#pipeline === null || this.#pipeline_color_format !== color_format) {
-            this.#pipeline = create_water_pipeline({ color_format });
-            this.#pipeline_color_format = color_format;
-        }
-
-        return this.#pipeline;
+    surfaces = [];
+    settings = { enabled: true, max_distance: 300, distance_tolerance: 0.15,
+        max_updates: 4, fallback_steps: 48, mode: 0, reflections: 1, debug_view: 0 };
+    #pipeline = create_water_pipeline();
+    #finalize_pipeline = create_water_finalize_pipeline();
+    #prepared = new WeakMap();
+    #inspection = new WeakMap();
+    #probe = null;
+
+    avboit_is_empty() {
+        return !this.settings.enabled || !this.surfaces.some(s => s.visible && s.height_texture !== null);
     }
 
-    /**
-     * Record the water draws into `graph`, over the colour it is given.
-     *
-     * @param {object} args
-     * @param {FrameGraph} args.graph
-     * @param {WaterSurface[]} args.surfaces
-     * @param {number} args.color colour resource handle to draw over
-     * @param {number} args.depth scene depth — **sampled**, which is why it is not also an
-     * attachment, and why the shader does its own depth test
-     * @param {GPUBuffer} args.camera
-     * @returns {number} the colour handle after the draws
-     */
-    graph_draw({ graph, surfaces, color, depth, camera }) {
-        assert.defined(graph, 'graph');
-        assert.defined(surfaces, 'surfaces');
-
-        const data = {};
-
-        const pass = graph.add('water', data, (data, resources, context) => {
-            this.#execute(data, resources, context, surfaces, camera);
+    /** Optional single-pixel readback on the next rendered water frame. No per-frame readback. */
+    request_probe(uv) {
+        if (this.avboit_is_empty()) { return Promise.reject(new Error("No active water to inspect")); }
+        if (this.#probe !== null) { return Promise.reject(new Error("Water probe already pending")); }
+        if (uv.length !== 2 || !Array.from(uv).every(Number.isFinite)) {
+            return Promise.reject(new Error("Water probe requires two finite UV coordinates"));
+        }
+        return new Promise((resolve, reject) => {
+            const probe = { uv: Array.from(uv),
+                resolve: value => { clearTimeout(timeout); resolve(value); },
+                reject: error => { clearTimeout(timeout); reject(error); } };
+            const timeout = setTimeout(() => {
+                if (this.#probe === probe) { this.#probe = null; }
+                reject(new Error("Water probe timed out; render an active AVBOIT water frame"));
+            }, 10000);
+            this.#probe = probe;
         });
-
-        data.depth = pass.read(depth);
-        data.color = pass.write(pass.read(color));
-
-        return data.color;
     }
 
-    /**
-     * @param data
-     * @param {FramePassResources} resources
-     * @param {GraphicsExecutionContext} context
-     * @param {WaterSurface[]} surfaces
-     * @param {GPUBuffer} camera
-     */
-    #execute(data, resources, context, surfaces, camera) {
-        if (surfaces.length === 0) {
-            return;
-        }
-
-        const encoder = context.encoder;
-        const graphics = context.graphics;
-
-        const color_texture = resources.get(data.color);
-        const depth_texture = resources.get(data.depth);
-
-        const pipeline = this.#obtain_pipeline(color_texture.format);
-
-        const depth_view = depth_texture.obtainView();
-
-        // the height map is read at a coarser rate than its texels and clamped at the shore, which
-        // is what the upscale sampler is
-        const sampler = graphics.samplers.obtain(SAMPLER_LINEAR_UPSCALE);
-
-        /*
-         Every per-draw resource is built before the render pass opens: staging a uniform records a
-         copy onto the command encoder, and the encoder is locked while a render pass is open on it.
-        */
-        const draws = [];
-
-        for (let i = 0; i < surfaces.length; i++) {
-            const surface = surfaces[i];
-
-            if (!surface.visible) {
-                continue;
-            }
-
-            const height = graphics.textures.obtain(surface.height_texture);
+    dispose() {
+        this.#probe?.reject(new Error("Water system stopped"));
+        this.#probe = null;
+        this.#prepared = new WeakMap();
+        this.#inspection = new WeakMap();
+    }
 
-            const water = encoder.allocateTransientValueBuffer(WATER_DRAW_STRUCT, {
-                extent: surface.extent,
-                height_uv: surface.height_uv,
-                color_deep: surface.color_deep,
-                color_shore: surface.color_shore,
-                level: surface.level,
-                time: surface.time,
-                wave_amplitude: surface.wave_amplitude,
-                wave_speed: surface.wave_speed,
-                wave_frequency: surface.wave_frequency,
-                scattering: surface.scattering,
-                shore_transition: surface.shore_transition
+    avboit_prepare({ graph, view_ctx, camera, color_texture, depth_texture, normal_texture,
+        hzb_texture, environment_texture }) {
+        const surfaces = this.surfaces.filter(s => s.visible && s.height_texture !== null)
+            .map(s => ({ ...s, extent: s.extent.slice(), height_uv: s.height_uv.slice(),
+                color_deep: s.color_deep.slice(), color_shore: s.color_shore.slice(),
+                shore_transition: s.shore_transition.slice(), extinction: s.extinction.slice() }))
+            .sort((a, b) => a.entity - b.entity);
+        surfaces.forEach((surface, index) => { surface.surface_id = index + 1; });
+        const settings = { ...this.settings };
+        const probe = this.#probe;
+        this.#probe = null;
+        const resolution = Array.from(view_ctx.resolution);
+        const data = { resolution, frame_time: surfaces[0]?.time ?? 0 };
+        const pipeline = this.#pipeline;
+        const pass = graph.add("Water / receivers", data, (data, resources, context) => {
+            const { encoder, graphics } = context;
+            const shared = {
+                camera: resources.get(data.camera),
+                trace: encoder.allocateTransientValueBuffer(WATER_TRACE_STRUCT, settings),
+                tDepth: resources.get(data.scene_depth).obtainView(DEFAULT_DEPTH_TEXTURE_VIEW),
+                tNormal: resources.get(data.normal).obtainView(),
+                tHZB: resources.get(data.hzb).obtainView(),
+                tScene: resources.get(data.color).obtainView(),
+                tEnvironment: resources.get(data.environment).obtainView(),
+                height_sampler: graphics.samplers.obtain(SAMPLER_LINEAR_UPSCALE),
+            };
+            // Copies/uniform uploads must be encoded before opening the render pass.
+            const draws = surfaces.map(s => WATER_RESOURCES.generateBindings({ ...shared,
+                water: encoder.allocateTransientValueBuffer(WATER_DRAW_STRUCT, s),
+                terrain_height: graphics.textures.obtain(s.height_texture).obtainView(),
+            }, encoder));
+            const render = encoder.constructRenderPass({ label: "Water / receivers", pipeline, bindings: [],
+                colorAttachments: [data.receiver, data.trace_metadata].map(handle => ({
+                    view: resources.get(handle).obtainView(), loadOp: "clear", storeOp: "store", clearValue: [0,0,0,0],
+                })),
+                depthStencilAttachment: { view: resources.get(data.interface_depth).obtainView(DEFAULT_DEPTH_TEXTURE_VIEW),
+                    depthLoadOp: "clear", depthStoreOp: "store", depthClearValue: 0 },
             });
-
-            draws.push(WATER_RESOURCES.generateBindings({
-                camera,
-                water,
-                scene_depth: depth_view,
-                terrain_height: height.obtainView(),
-                height_sampler: sampler
+            for (const bindings of draws) { graphics.setPipelineBindings(render, pipeline, bindings); render.draw(6); }
+            render.end();
+        });
+        for (const [name, handle] of Object.entries({ camera, color: color_texture, scene_depth: depth_texture,
+            normal: normal_texture, hzb: hzb_texture, environment: environment_texture })) { data[name] = pass.read(handle); }
+        const target = (name, format) => pass.create(`Water ${name}`, TextureResourceDescriptor.from({
+            resolution, format, usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING
+                | (probe !== null && format !== "depth32float" ? GPUTextureUsage.COPY_SRC : 0),
+        }));
+        // Keep the accepted UV and both paths at f32 precision through final shading.
+        data.receiver = target("receiver", "rgba32float");
+        data.trace_metadata = target("trace metadata", "rgba32float");
+        data.interface_depth = target("interface depth", "depth32float");
+        let states = this.#prepared.get(graph);
+        if (states === undefined) { states = new Map(); this.#prepared.set(graph, states); }
+        states.set(camera, data);
+        if (settings.debug_view !== 0) {
+            let views = this.#inspection.get(graph);
+            if (views === undefined) { views = new Map(); this.#inspection.set(graph, views); }
+            views.set(view_ctx, { data, mode: settings.debug_view, resolution });
+        }
+        const visibility_resolution = resolution.map(v => Math.ceil(v / 4));
+        const [seeds] = graph_image_pass({ graph, shader: shader_water_confidence_seed,
+            inputs: { trace_metadata: data.trace_metadata, scene_depth: data.scene_depth }, output_resolution: visibility_resolution });
+        const [horizontal] = graph_image_pass({ graph, shader: shader_water_confidence_x,
+            inputs: { distance_field: seeds }, output_resolution: visibility_resolution });
+        const [visibility_distance] = graph_image_pass({ graph, shader: shader_water_confidence_y,
+            inputs: { distance_field: horizontal }, output_resolution: visibility_resolution });
+        data.visibility_distance = visibility_distance;
+        const finalize_data = {};
+        const finalize_pipeline = this.#finalize_pipeline;
+        const finalize = graph.add('Water / coherent optics', finalize_data, (d, resources, {encoder, graphics}) => {
+            const shared = {
+                camera: resources.get(d.camera), trace: encoder.allocateTransientValueBuffer(WATER_TRACE_STRUCT, settings),
+                tDepth: resources.get(d.scene_depth).obtainView(DEFAULT_DEPTH_TEXTURE_VIEW),
+                tNormal: resources.get(d.normal).obtainView(), tHZB: resources.get(d.hzb).obtainView(),
+                tScene: resources.get(d.color).obtainView(), tEnvironment: resources.get(d.environment).obtainView(),
+                receiver: resources.get(d.receiver).obtainView(), trace_metadata: resources.get(d.trace_metadata).obtainView(),
+                visibility_distance: resources.get(d.visibility_distance).obtainView(),
+                height_sampler: graphics.samplers.obtain(SAMPLER_LINEAR_UPSCALE),
+            };
+            const draws = surfaces.map(s => WATER_FINALIZE_RESOURCES.generateBindings({...shared,
+                water: encoder.allocateTransientValueBuffer(WATER_DRAW_STRUCT, s),
+                terrain_height: graphics.textures.obtain(s.height_texture).obtainView(),
             }, encoder));
+            const copy_pipeline = shader_water_background_copy.pipeline;
+            const copy_bindings = shader_water_background_copy.descriptor.resources.generateBindings({tScene: shared.tScene}, encoder);
+            const render = encoder.constructRenderPass({label: 'Water / coherent optics', pipeline: finalize_pipeline, bindings: [],
+                colorAttachments: [d.transmission,d.radiance,d.background].map(handle => ({
+                    view: resources.get(handle).obtainView(), loadOp: 'clear', storeOp: 'store', clearValue: [0,0,0,0],
+                })), depthStencilAttachment: {view: resources.get(d.interface_depth).obtainView(DEFAULT_DEPTH_TEXTURE_VIEW), depthReadOnly: true},
+            });
+            render.setPipeline(graphics.render_pipelines.obtain(copy_pipeline)); render.record_pipeline(copy_pipeline);
+            graphics.setPipelineBindings(render, copy_pipeline, copy_bindings); render.draw(3);
+            render.setPipeline(graphics.render_pipelines.obtain(finalize_pipeline)); render.record_pipeline(finalize_pipeline);
+            for (const bindings of draws) { graphics.setPipelineBindings(render, finalize_pipeline, bindings); render.draw(6); }
+            render.end();
+        });
+        for (const key of ['camera','scene_depth','normal','hzb','color','environment','receiver','trace_metadata','visibility_distance','interface_depth']) {
+            finalize_data[key] = finalize.read(data[key]);
         }
+        const optical_target = (name,format) => finalize.create(`Water ${name}`, TextureResourceDescriptor.from({
+            resolution, format, usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING
+                | (probe !== null ? GPUTextureUsage.COPY_SRC : 0),
+        }));
+        data.transmission = finalize_data.transmission = optical_target('transmission','rgba32float');
+        data.radiance = finalize_data.radiance = optical_target('radiance','rgba16float');
+        const background_color = finalize_data.background = optical_target('background','rgba16float');
+        if (probe !== null) { this.#record_probe(graph, data, resolution, probe); }
+        return { background_color };
+    }
 
-        if (draws.length === 0) {
-            return;
-        }
+    #state(graph, camera) {
+        const data = this.#prepared.get(graph)?.get(camera);
+        if (data === undefined) { throw new Error("Water AVBOIT requires preparation in this graph/view"); }
+        return data;
+    }
 
-        const render_pass = encoder.constructRenderPass({
-            label: "Water",
-            pipeline,
-            // one bind group per surface, so they are set per draw rather than once for the pass
-            bindings: [],
-            colorAttachments: [{
-                loadOp: "load",
-                storeOp: "store",
-                view: color_texture.obtainView(TextureViewDescriptor.from({
-                    mipLevelCount: 1,
-                    baseMipLevel: 0
-                }))
-            }]
-        });
+    avboit_occupancy({ graph, camera, cluster_parameters, occupancy }) {
+        const data = this.#state(graph, camera);
+        const { occupancy: out } = graph_compute_pass({ graph, shader: shader_water_occupancy,
+            bindings: { camera, settings: { cluster_parameters }, interface_depth: data.interface_depth, occupancy },
+            group_count: [Math.ceil(data.resolution[0] / 8), Math.ceil(data.resolution[1] / 8), 1] });
+        return out;
+    }
 
-        for (let i = 0; i < draws.length; i++) {
-            graphics.setPipelineBindings(render_pass, pipeline, draws[i]);
+    avboit_splat({ graph, camera, warp, voxel_resolution, volume }) {
+        const data = this.#state(graph, camera);
+        const out = graph_compute_pass({ graph, shader: shader_water_splat,
+            bindings: { camera, warp, interface_depth: data.interface_depth, transmission: data.transmission,
+                extinction_volume: volume.extinction, overflow_slice: volume.overflow },
+            group_count: [Math.ceil(voxel_resolution[0]/8), Math.ceil(voxel_resolution[1]/8), 1] });
+        return { extinction: out.extinction_volume, overflow: out.overflow_slice, dummy: volume.dummy };
+    }
 
-            render_pass.draw(VERTICES_PER_SURFACE);
+    avboit_draw({ graph, view_ctx, camera, warp, integral, volumetrics_lut, volumetrics_metadata, accumulators }) {
+        const optical = this.#state(graph, camera);
+        // Inspection consumes the same completed shared integral as the production contribution.
+        optical.warp = warp; optical.integral = integral;
+        const data = {};
+        const pass = graph.add("Water / AVBOIT draw", data, (data, resources, { encoder, graphics }) => {
+            shader_water_draw.draw({ encoder, bindings: {
+                camera: resources.get(data.camera), view: view_ctx.uniform_buffer.buffer,
+                warp: resources.get(data.warp), interface_depth: resources.get(data.interface_depth).obtainView(DEFAULT_DEPTH_TEXTURE_VIEW),
+                transmission: resources.get(data.transmission).obtainView(), radiance: resources.get(data.radiance).obtainView(),
+                tIntegral: resources.get(data.integral).obtainView(), sLinear: graphics.samplers.obtain(SAMPLER_LINEAR_UPSCALE),
+                volumetrics_metadata: resources.get(data.volumetrics_metadata), tVolumetrics: resources.get(data.volumetrics_lut).obtainView(),
+                tSTBN_vec3: graphics.textures.obtain(STATIC_GRAPHICS_ENGINE_ASSETS.stbn_vec3).obtainView(),
+            }, colorAttachments: [data.color,data.norm,data.extinction,data.emission].map(handle => ({
+                view: resources.get(handle).obtainView(), loadOp: "load", storeOp: "store",
+            })) });
+        });
+        for (const [key,handle] of Object.entries({camera,warp,integral,volumetrics_lut,volumetrics_metadata,
+            interface_depth: optical.interface_depth, transmission: optical.transmission, radiance: optical.radiance})) {
+            data[key] = pass.read(handle);
         }
+        for (const [key,handle] of Object.entries(accumulators)) { data[key] = pass.write(pass.read(handle)); }
+        this.#prepared.get(graph).delete(camera);
+        return { color: data.color, norm: data.norm, extinction: data.extinction, emission: data.emission };
+    }
+
+    /** Debug presentation only: called after shared resolve, never sampled by production optics. */
+    inspect(graph, view_ctx, output_resolution) {
+        const views = this.#inspection.get(graph);
+        const state = views?.get(view_ctx);
+        if (state === undefined) { return undefined; }
+        views.delete(view_ctx);
+        const { data, mode } = state;
+        const resolution = output_resolution ?? state.resolution;
+        const [color] = graph_image_pass({ graph, shader: shader_water_debug, output_resolution: resolution,
+            inputs: { inspection: { mode, resolution }, camera: data.camera, warp: data.warp, tIntegral: data.integral,
+                transmission: data.transmission, radiance: data.radiance,
+                receiver: data.receiver, interface_depth: data.interface_depth, trace_metadata: data.trace_metadata } });
+        return color;
+    }
 
-        render_pass.end();
+    #record_probe(graph, optical, resolution, probe) {
+        const data = {};
+        const pass = graph.add("Water / pixel probe", data, (data, resources, { encoder, graphics }) => {
+            const buffer = graphics.device.createBuffer({ size: 1024, usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST });
+            const pixel = probe.uv.map((v, i) => Math.min(resolution[i]-1, Math.max(0, Math.floor(v*resolution[i]))));
+            [data.receiver, data.transmission, data.radiance, data.trace_metadata].forEach((handle, i) => {
+                encoder.copyTextureToBuffer({ texture: resources.get(handle).gpu_texture, origin: [...pixel, 0] },
+                    { buffer, offset: i*256, bytesPerRow: 256 }, [1,1,1]);
+            });
+            encoder.done.then(async () => {
+                try {
+                    await buffer.mapAsync(GPUMapMode.READ);
+                    const mapped = buffer.getMappedRange();
+                    const half = offset => Array.from(new Uint16Array(mapped, offset, 4), half_to_float_uint16);
+                    const radiance = half(512);
+                    const confidence = radiance[3];
+                    radiance[3] = new Float32Array(mapped, 768, 4)[1];
+                    probe.resolve({ pixel, resolution, frame_time: optical.frame_time, receiver: Array.from(new Float32Array(mapped, 0, 4)),
+                        transmission: Array.from(new Float32Array(mapped, 256, 4)), radiance, confidence, stale: false });
+                } catch (error) { probe.reject(error); }
+                finally { buffer.destroy(); }
+            });
+        });
+        for (const key of ["receiver", "transmission", "radiance", "trace_metadata"]) { data[key] = pass.read(optical[key]); }
+        pass.make_side_effect();
     }
 }

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

@@ -0,0 +1,5 @@
+export const chunk_water_refraction_confidence: CodeChunk;
+export const chunk_water_transport: CodeChunk;
+export const chunk_water_receiver_radiance: CodeChunk;
+import { CodeChunk } from '../shader/compiler/CodeChunk.js';
+//# sourceMappingURL=chunk_water_transport.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_water_transport.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/water/chunk_water_transport.js"],"names":[],"mappings":"AAKA,0DAeG;AAEH,8CAoBG;AAIH,sDA+CoF;0BA7F1D,iCAAiC"}

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

@@ -0,0 +1,94 @@
+import { CodeChunk } from '../shader/compiler/CodeChunk.js';
+import { chunk_decode_g_buffer_normal } from '../shader/chunk/geometry/normal/chunk_decode_g_buffer_normal.js';
+import { chunk_inv_project_position } from '../shader/chunk/screen_space/chunk_inv_project_position.js';
+import { chunk_is_background } from '../shader/chunk/depth/chunk_is_background.js';
+
+export const chunk_water_refraction_confidence = CodeChunk.from(/* language=WGSL */ `
+fn water_refraction_lookup(original: vec2f, receiver: vec2f, confidence: f32) -> vec2f {
+    return mix(original, receiver, clamp(confidence, 0.0, 1.0));
+}
+fn water_refraction_confidence(uv: vec2f, original_uv: vec2f, size: vec2f, distance_tiles: f32) -> f32 {
+    let displacement = length((uv - original_uv) * size);
+    let fade_width = clamp(displacement, 8.0, 64.0);
+    let visibility = smoothstep(0.0, fade_width, distance_tiles * 4.0);
+    let source_edge = min(min(original_uv.x, original_uv.y), min(1.0-original_uv.x, 1.0-original_uv.y));
+    let receiver_edge = min(min(uv.x, uv.y), min(1.0-uv.x, 1.0-uv.y));
+    // Approaching an off-screen receiver must approach the control lookup continuously,
+    // even while the water fragment itself is far enough from the frame border.
+    return visibility * smoothstep(0.0, clamp(displacement / min(size.x, size.y), 0.01, 0.1),
+        min(source_edge, receiver_edge));
+}
+`);
+
+export const chunk_water_transport = CodeChunk.from(/* language=WGSL */ `
+struct WaterEvent { transmission: vec3f, radiance: vec3f }
+struct WaterTransport { transmission: vec3f, radiance: vec3f, background: vec3f }
+fn water_event(path: f32, extinction: vec3f, fresnel: f32, reflection: vec3f, body: vec3f) -> WaterEvent {
+    let absorption = exp(-max(extinction, vec3f(0.0)) * max(path, 0.0));
+    let raw = (1.0 - fresnel) * absorption;
+    let t = max(raw, vec3f(1e-6));
+    let scale = (1.0 - t) / max(1.0 - raw, vec3f(1e-20));
+    return WaterEvent(t, scale * (fresnel * reflection + (1.0-fresnel) * (1.0-absorption) * body));
+}
+// One selected lookup and its optical event. Only geometric coverage mixes images;
+// fading refraction interpolates the lookup UV before sampling, never two displaced colors.
+fn water_transport(event: WaterEvent, original: vec3f, receiver: vec3f,
+    coverage: f32) -> WaterTransport {
+    let a = clamp(coverage, 0.0, 1.0);
+    let t = (1.0-a) + a * event.transmission;
+    let w = a * event.radiance;
+    let background = ((1.0-a)*original + a*event.transmission*receiver) / t;
+    return WaterTransport(t, w, background);
+}
+`);
+
+// Filtering radiance across a silhouette must not introduce a surface that the ray never hit.
+// The center depth/face normal define receiver ownership; taps must lie on that same local plane.
+export const chunk_water_receiver_radiance = CodeChunk.from(/* language=WGSL */ `
+// Depth is stored at the texel center. Intersect the lookup's camera ray with that
+// local plane so subpixel lookup motion does not quantize water thickness.
+fn water_receiver_path(depth: texture_2d<f32>, normals: texture_2d<u32>, uv: vec2f,
+    inverse_projection: mat4x4f, world_to_view: mat4x4f, origin: vec3f) -> f32 {
+    let size = vec2f(textureDimensions(depth, 0));
+    let coord = clamp(vec2i(uv*size), vec2i(0), vec2i(size)-1);
+    let d = textureLoad(depth, coord, 0).r;
+    let p = inv_project_position(vec3f((vec2f(coord)+0.5)/size,d), inverse_projection);
+    let direction = inv_project_position(vec3f(uv,d), inverse_projection);
+    let n = (world_to_view * vec4f(decode_g_buffer_normal(textureLoad(normals,coord,0).zw),0.0)).xyz;
+    let denominator = dot(n,direction);
+    if (abs(denominator) <= 1e-6) { return distance(origin,p); }
+    return distance(origin, direction * (dot(n,p)/denominator));
+}
+fn water_receiver_radiance(scene: texture_2d<f32>, depth: texture_2d<f32>, normals: texture_2d<u32>,
+    uv: vec2f, inverse_projection: mat4x4f, inverse_view: mat4x4f, level: f32, below_interface: bool) -> vec4f {
+    let size = vec2i(textureDimensions(depth, 0));
+    let center = clamp(vec2i(uv * vec2f(size)), vec2i(0), size-1);
+    let center_depth = textureLoad(depth, center, 0).r;
+    if (is_background(center_depth)) { return vec4f(0.0); }
+    let center_vs = inv_project_position(vec3f((vec2f(center)+0.5)/vec2f(size), center_depth), inverse_projection);
+    let p = (inverse_view * vec4f(center_vs, 1.0)).xyz;
+    let n = decode_g_buffer_normal(textureLoad(normals, center, 0).zw);
+    if (below_interface && p.y > level + 0.02) { return vec4f(0.0); }
+    let texel = uv * vec2f(size) - 0.5;
+    let base = vec2i(floor(texel));
+    let f = fract(texel);
+    var color = vec3f(0.0);
+    var weight = 0.0;
+    for (var y = 0; y < 2; y++) {
+        for (var x = 0; x < 2; x++) {
+            let coord = clamp(base + vec2i(x,y), vec2i(0), size-1);
+            let d = textureLoad(depth, coord, 0).r;
+            if (is_background(d)) { continue; }
+            let tap_vs = inv_project_position(vec3f((vec2f(coord)+0.5)/vec2f(size), d), inverse_projection);
+            let tap = (inverse_view * vec4f(tap_vs, 1.0)).xyz;
+            let tap_n = decode_g_buffer_normal(textureLoad(normals, coord, 0).zw);
+            if ((below_interface && tap.y > level+0.02) || dot(n,tap_n) < 0.95
+                || abs(dot(tap-p,n)) > 0.02) { continue; }
+            let w = select(1.0-f.x, f.x, x == 1) * select(1.0-f.y, f.y, y == 1);
+            color += w * textureLoad(scene, coord, 0).rgb;
+            weight += w;
+        }
+    }
+    return vec4f(color / max(weight, 1e-20), weight);
+}
+`, [chunk_decode_g_buffer_normal, chunk_inv_project_position, chunk_is_background]);

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

@@ -1,33 +1,16 @@
-/**
- * Build the water pipeline.
- *
- * **It has no depth attachment, and that is forced rather than chosen.** The shader *samples* scene
- * depth to know how much water the view looks through, and a texture may not be a sampled source
- * and a render attachment in the same pass. So the depth test the hardware would have done is done
- * in the shader instead — which is also why the fragment `discard` there is load-bearing rather
- * than a guard: without it, water would draw over the things standing in it.
- *
- * @param {object} [options]
- * @param {string} [options.color_format]
- * @returns {RenderPipelineDescriptor}
- */
-export function create_water_pipeline({ color_format }?: {
-    color_format?: string;
-}): RenderPipelineDescriptor;
-/**
- * One water surface. Small, and rewritten per surface per frame rather than tabled — a level has a
- * handful of these, not thousands.
- */
+export function create_water_pipeline(): RenderPipelineDescriptor;
+export function create_water_finalize_pipeline(): RenderPipelineDescriptor;
 export const WATER_DRAW_STRUCT: WebGPUStruct;
+export const WATER_TRACE_STRUCT: WebGPUStruct;
+export const WATER_FINALIZE_RESOURCES: ShaderResourceSetDescriptor;
+export const water_transport_fallback: CodeChunk;
+export const chunk_water_screen_ray: CodeChunk;
 export const water_shader: ShaderDescriptor;
-/**
- * The pipeline's resource set, for building bind groups.
- *
- * @type {ShaderResourceSetDescriptor}
- */
+export const water_finalize_shader: ShaderDescriptor;
 export const WATER_RESOURCES: ShaderResourceSetDescriptor;
 import { RenderPipelineDescriptor } from "../../descriptor/pipeline/render/RenderPipelineDescriptor.js";
 import { WebGPUStruct } from "../shader/type/WebGPUStruct.js";
-import { ShaderDescriptor } from "../shader/ShaderDescriptor.js";
 import { ShaderResourceSetDescriptor } from "../shader/resource/ShaderResourceSetDescriptor.js";
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+import { ShaderDescriptor } from "../shader/ShaderDescriptor.js";
 //# sourceMappingURL=shader_water.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"shader_water.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/water/shader_water.js"],"names":[],"mappings":"AAiNA;;;;;;;;;;;;GAYG;AACH;IAH4B,YAAY,GAA7B,MAAM;IACJ,wBAAwB,CAkBpC;AAnOD;;;GAGG;AACH,6CAuCuB;AAwIvB,4CAIG;AA8CH;;;;GAIG;AACH,8BAFU,2BAA2B,CAEI;yCAnPA,8DAA8D;6BAO1E,gCAAgC;iCAF5B,+BAA+B;4CADpB,mDAAmD"}
+{"version":3,"file":"shader_water.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/water/shader_water.js"],"names":[],"mappings":"AA8XA,kEAAuH;AACvH,2EAAuJ;AA3WvJ,6CAKuB;AAEvB,8CAGwB;AAmBxB,mEAA8D;AAE9D,iDAIG;AAsCH,+CAmGoH;AA8KpH,4CAAmG;AACnG,qDAA2J;AAC3J,0DAAyC;yCA9WA,8DAA8D;6BAe1E,gCAAgC;4CAHjB,mDAAmD;0BADrE,iCAAiC;iCAE1B,+BAA+B"}