@woosh/meep-engine 3.37.0 → 3.38.0

package/src/shade/renderer/shader/chunk/screen_space/chunk_screen_space_newton_ray.js

@@ -0,0 +1,101 @@
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+import { chunk_is_background } from "../depth/chunk_is_background.js";
+import { chunk_decode_g_buffer_normal } from "../geometry/normal/chunk_decode_g_buffer_normal.js";
+import { chunk_plane_from_normal_and_point } from "../geometry/plane/chunk_plane_from_normal_and_point.js";
+import { chunk_plane_ray_raycast } from "../geometry/plane/chunk_plane_ray_raycast.js";
+import { RAY_STRUCT } from "../geometry/ray/RAY_STRUCT.js";
+import { chunk_ray_at } from "../geometry/ray/chunk_ray_at.js";
+import { chunk_ray_nearest_point } from "../geometry/ray/chunk_ray_nearest_point.js";
+import { chunk_inv_project_position } from "./chunk_inv_project_position.js";
+import { chunk_project_position } from "./chunk_project_position.js";
+
+/** Mayer et al. 2026 tangent-plane refinement. All arithmetic is in matrix view space. */
+export const chunk_screen_space_newton_ray = CodeChunk.from(/* language=WGSL */ `
+struct ScreenSpaceRayHit {
+    uv: vec2<f32>,
+    distance: f32,
+    residual: f32,
+    iterations: u32,
+    // 0 hit, 1 bounds/clip, 2 sky, 3 parallel/invalid, 4 interval, 5 exhausted/residual
+    status: u32,
+}
+
+fn screen_space_ray_in_bounds(uv: vec2<f32>) -> bool {
+    return all(uv >= vec2<f32>(0.0)) && all(uv < vec2<f32>(1.0));
+}
+
+fn screen_space_ray_projectable(p: vec3<f32>, projection: mat4x4<f32>) -> bool {
+    let clip = projection * vec4<f32>(p, 1.0);
+    return clip.w > 1e-6 && all(abs(clip) < vec4<f32>(1e30));
+}
+
+// Reconstruct the receiver at the subpixel lookup on its local tangent plane.
+// A texel-center position is a different surface point: projecting its nearest
+// point on the ray can exceed one pixel at grazing angles even for an exact hit.
+fn screen_space_ray_validate(
+    ray: Ray, uv: vec2<f32>, depth: texture_2d<f32>, normals: texture_2d<u32>,
+    projection: mat4x4<f32>, inverse_projection: mat4x4<f32>, world_to_view: mat4x4<f32>,
+    distance_tolerance: f32,
+) -> ScreenSpaceRayHit {
+    var hit = ScreenSpaceRayHit(uv, 0.0, 1e20, 0u, 1u);
+    if (!screen_space_ray_in_bounds(uv)) { return hit; }
+    let size = textureDimensions(depth, 0);
+    let coord = vec2<i32>(uv * vec2<f32>(size));
+    let d = textureLoad(depth, coord, 0).r;
+    if (is_background(d)) { hit.status = 2u; return hit; }
+    let center = (vec2<f32>(coord) + 0.5) / vec2<f32>(size);
+    let center_position = inv_project_position(vec3<f32>(center, d), inverse_projection);
+    let normal = (world_to_view * vec4f(decode_g_buffer_normal(textureLoad(normals, coord, 0).zw), 0.0)).xyz;
+    let lookup_ray = inv_project_position(vec3f(uv, d), inverse_projection);
+    let denominator = dot(normal, lookup_ray);
+    if (!(abs(denominator) > 1e-6)) { hit.status = 3u; return hit; }
+    let scale = dot(normal, center_position) / denominator;
+    if (!(scale > 0.0)) { hit.status = 3u; return hit; }
+    let p = lookup_ray * scale;
+    let travel = dot(p - ray.origin, ray.direction);
+    hit.distance = travel;
+    if (!(travel > 1e-4 && travel <= ray.tmax)) { hit.status = 4u; return hit; }
+    let nearest = ray_nearest_point(ray, p);
+    if (!screen_space_ray_projectable(nearest, projection)) { return hit; }
+    let pixel_error = length((project_position(nearest, projection).xy - uv) * vec2<f32>(size));
+    hit.residual = distance(p, nearest);
+    hit.status = 5u;
+    if (pixel_error <= 1.0 && hit.residual <= distance_tolerance) { hit.status = 0u; }
+    return hit;
+}
+
+fn screen_space_newton_ray(
+    ray: Ray, seed_uv: vec2<f32>, depth: texture_2d<f32>, normals: texture_2d<u32>,
+    projection: mat4x4<f32>, inverse_projection: mat4x4<f32>, world_to_view: mat4x4<f32>,
+    max_updates: u32, distance_tolerance: f32,
+) -> ScreenSpaceRayHit {
+    var uv = seed_uv;
+    var hit = ScreenSpaceRayHit(uv, 0.0, 1e20, 0u, 5u);
+    let size = textureDimensions(depth, 0);
+    for (var i = 0u; i < min(max_updates, 16u); i++) {
+        hit.iterations = i + 1u;
+        if (!screen_space_ray_in_bounds(uv)) { hit.status = 1u; return hit; }
+        let coord = vec2<i32>(uv * vec2<f32>(size));
+        let d = textureLoad(depth, coord, 0).r;
+        if (is_background(d)) { hit.status = 2u; return hit; }
+        let center = (vec2<f32>(coord) + 0.5) / vec2<f32>(size);
+        let receiver = inv_project_position(vec3<f32>(center, d), inverse_projection);
+        // .zw is the geometric face normal; .xy includes material normal mapping.
+        let world_normal = decode_g_buffer_normal(textureLoad(normals, coord, 0).zw);
+        let normal = (world_to_view * vec4<f32>(world_normal, 0.0)).xyz;
+        if (!(abs(dot(ray.direction, normal)) > 1e-4)) { hit.status = 3u; return hit; }
+        let plane = plane_from_normal_and_point(normal, receiver);
+        let travel = plane_ray_raycast(ray.origin, ray.direction, plane);
+        if (!(travel > 1e-4 && travel <= ray.tmax)) { hit.status = 4u; return hit; }
+        let next = ray_at(ray.origin, ray.direction, travel);
+        if (!screen_space_ray_projectable(next, projection)) { hit.status = 1u; return hit; }
+        uv = project_position(next, projection).xy;
+        hit = screen_space_ray_validate(ray, uv, depth, normals, projection, inverse_projection, world_to_view, distance_tolerance);
+        hit.iterations = i + 1u;
+        if (hit.status == 0u || hit.status == 1u || hit.status == 2u) { return hit; }
+    }
+    return hit;
+}
+`, [RAY_STRUCT.declaration_chunk, chunk_is_background, chunk_decode_g_buffer_normal,
+    chunk_plane_from_normal_and_point, chunk_plane_ray_raycast, chunk_ray_at,
+    chunk_ray_nearest_point, chunk_inv_project_position, chunk_project_position]);

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

@@ -1,33 +1,66 @@
-/**
- * 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 {
-    /**
-     * 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 }: {
-        graph: FrameGraph;
-        surfaces: WaterSurface[];
-        color: number;
-        depth: number;
-        camera: GPUBuffer;
-    }): number;
+    surfaces: any[];
+    settings: {
+        enabled: boolean;
+        max_distance: number;
+        distance_tolerance: number;
+        max_updates: number;
+        fallback_steps: number;
+        mode: number;
+        reflections: number;
+        debug_view: number;
+    };
+    avboit_is_empty(): boolean;
+    /** Optional single-pixel readback on the next rendered water frame. No per-frame readback. */
+    request_probe(uv: any): Promise<any>;
+    dispose(): void;
+    avboit_prepare({ graph, view_ctx, camera, color_texture, depth_texture, normal_texture, hzb_texture, environment_texture }: {
+        graph: any;
+        view_ctx: any;
+        camera: any;
+        color_texture: any;
+        depth_texture: any;
+        normal_texture: any;
+        hzb_texture: any;
+        environment_texture: any;
+    }): {
+        background_color: any;
+    };
+    avboit_occupancy({ graph, camera, cluster_parameters, occupancy }: {
+        graph: any;
+        camera: any;
+        cluster_parameters: any;
+        occupancy: any;
+    }): any;
+    avboit_splat({ graph, camera, warp, voxel_resolution, volume }: {
+        graph: any;
+        camera: any;
+        warp: any;
+        voxel_resolution: any;
+        volume: any;
+    }): {
+        extinction: any;
+        overflow: any;
+        dummy: any;
+    };
+    avboit_draw({ graph, view_ctx, camera, warp, integral, volumetrics_lut, volumetrics_metadata, accumulators }: {
+        graph: any;
+        view_ctx: any;
+        camera: any;
+        warp: any;
+        integral: any;
+        volumetrics_lut: any;
+        volumetrics_metadata: any;
+        accumulators: any;
+    }): {
+        color: any;
+        norm: any;
+        extinction: any;
+        emission: any;
+    };
+    /** Debug presentation only: called after shared resolve, never sampled by production optics. */
+    inspect(graph: any, view_ctx: any, output_resolution: any): number;
     #private;
 }
 //# sourceMappingURL=GPUWaterRenderer.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"GPUWaterRenderer.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/water/GPUWaterRenderer.js"],"names":[],"mappings":"AAaA;;;;;;;;;GASG;AACH;IAwBI;;;;;;;;;;;OAWG;IACH;QAR4B,KAAK;QACD,QAAQ,EAA7B,cAAc;QACD,KAAK,EAAlB,MAAM;QACO,KAAK,EAAlB,MAAM;QAEU,MAAM;QACpB,MAAM,CAgBlB;;CA6FJ"}
+{"version":3,"file":"GPUWaterRenderer.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/water/GPUWaterRenderer.js"],"names":[],"mappings":"AAaA,sFAAsF;AACtF;IACI,gBAAc;IACd;;;;;;;;;MACiF;IAOjF,2BAEC;IAED,8FAA8F;IAC9F,qCAgBC;IAED,gBAKC;IAED;;;;;;;;;;;MA4GC;IAQD;;;;;YAMC;IAED;;;;;;;;;;MAOC;IAED;;;;;;;;;;;;;;MAwBC;IAED,gGAAgG;IAChG,mEAYC;;CA4BJ"}

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"}