@woosh/meep-engine 3.37.0 → 3.39.0

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

@@ -1,33 +1,78 @@
-/**
- * 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 {
+    surfaces: any[];
+    settings: {
+        enabled: boolean;
+        max_distance: number;
+        distance_tolerance: number;
+        max_updates: number;
+        fallback_steps: number;
+        mode: number;
+        reflections: number;
+        debug_view: number;
+        inscatter_segments: number;
+    };
     /**
-     * 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
+     * The frame's water bodies table, recorded by whoever owns the surfaces at the head of the frame;
+     * each drawable surface carries its row as `body_index`.
+     * @type {import("./medium/GPUWaterBodies.js").GPUWaterBodies|null}
      */
-    graph_draw({ graph, surfaces, color, depth, camera }: {
-        graph: FrameGraph;
-        surfaces: WaterSurface[];
-        color: number;
-        depth: number;
-        camera: GPUBuffer;
-    }): number;
+    bodies: import("./medium/GPUWaterBodies.js").GPUWaterBodies | null;
+    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, light_cluster_parameters, light_cluster_lookup, light_cluster_data, shadowmap_atlas, indirect_lighting_mode }: {
+        graph: any;
+        view_ctx: any;
+        camera: any;
+        color_texture: any;
+        depth_texture: any;
+        normal_texture: any;
+        hzb_texture: any;
+        environment_texture: any;
+        light_cluster_parameters: any;
+        light_cluster_lookup: any;
+        light_cluster_data: any;
+        shadowmap_atlas: any;
+        indirect_lighting_mode?: number;
+    }): {
+        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":"AAqCA,sFAAsF;AACtF;IACI,gBAAc;IACd;;;;;;;;;;MACwG;IACxG;;;;OAIG;IACH,QAFU,OAAO,4BAA4B,EAAE,cAAc,GAAC,IAAI,CAEpD;IAQd,2BAGC;IAED,8FAA8F;IAC9F,qCAgBC;IAED,gBAKC;IAED;;;;;;;;;;;;;;;;MA6HC;IAQD;;;;;YAMC;IAED;;;;;;;;;;MAOC;IAED;;;;;;;;;;;;;;MAwBC;IAED,gGAAgG;IAChG,mEAYC;;CA4BJ"}

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

@@ -1,167 +1,304 @@
-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 { ShadeIndirectLightingMode } from "../ShadeIndirectLightingMode.js";
+import { water_missing_receiver_path } from "./water_missing_receiver_path.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 { SHADOWMAP_COMPARE_SAMPLER_DESCRIPTOR } from "../shadow/map/SHADOWMAP_COMPARE_SAMPLER_DESCRIPTOR.js";
+import { create_water_finalize_pipeline_brick4, create_water_finalize_pipeline_ibl, create_water_pipeline,
+    WATER_DRAW_STRUCT, WATER_FINALIZE_RESOURCES_BRICK4, WATER_FINALIZE_RESOURCES_IBL, WATER_RESOURCES,
+    WATER_TRACE_STRUCT } 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}
+ * A surface the water passes can draw: visible, and with its surface interface published by the
+ * producer this frame.
+ * @param {Object} s
+ * @returns {boolean}
  */
-const VERTICES_PER_SURFACE = 6;
+function water_surface_drawable(s) {
+    return s.visible && s.gpu_surface !== undefined;
+}
 
 /**
- * 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.
+ * Draw a surface interface's mesh: the producer's index buffer over its vertex storage buffer.
+ * @param {ShadeGPURenderPassEncoder} render
+ * @param {{indices: GPUBuffer, index_count: number}} surface
  */
-export class GPUWaterRenderer {
-    /**
-     * @type {RenderPipelineDescriptor|null}
-     */
-    #pipeline = null;
-
-    /**
-     * @type {string}
-     */
-    #pipeline_color_format = "";
+function water_surface_draw(render, surface) {
+    render.setIndexBuffer(surface.indices, "uint32");
+    render.drawIndexed(surface.index_count);
+}
 
+/** Production water channel. Only AVBOIT's shared resolve composites its radiance. */
+export class GPUWaterRenderer {
+    surfaces = [];
+    settings = { enabled: true, max_distance: 300, distance_tolerance: 0.15,
+        max_updates: 4, fallback_steps: 48, mode: 0, reflections: 1, debug_view: 0, inscatter_segments: 4 };
     /**
-     * @param {string} color_format the frame colour this draws over
-     * @returns {RenderPipelineDescriptor}
+     * The frame's water bodies table, recorded by whoever owns the surfaces at the head of the frame;
+     * each drawable surface carries its row as `body_index`.
+     * @type {import("./medium/GPUWaterBodies.js").GPUWaterBodies|null}
      */
-    #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;
-        }
+    bodies = null;
+    #pipeline = create_water_pipeline();
+    #finalize_pipeline_ibl = create_water_finalize_pipeline_ibl();
+    #finalize_pipeline_brick4 = create_water_finalize_pipeline_brick4();
+    #prepared = new WeakMap();
+    #inspection = new WeakMap();
+    #probe = null;
 
-        return this.#pipeline;
+    avboit_is_empty() {
+        // the authored state: whether there is water at all, not whether its surface was produced yet
+        return !this.settings.enabled || !this.surfaces.some(s => s.visible);
     }
 
-    /**
-     * 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;
+    dispose() {
+        this.#probe?.reject(new Error("Water system stopped"));
+        this.#probe = null;
+        this.#prepared = new WeakMap();
+        this.#inspection = new WeakMap();
     }
 
-    /**
-     * @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;
+    avboit_prepare({ graph, view_ctx, camera, color_texture, depth_texture, normal_texture,
+        hzb_texture, environment_texture, light_cluster_parameters, light_cluster_lookup, light_cluster_data,
+        shadowmap_atlas, indirect_lighting_mode = ShadeIndirectLightingMode.IBL }) {
+        const surfaces = this.surfaces.filter(water_surface_drawable)
+            .map(s => ({ ...s, missing_receiver_path: water_missing_receiver_path({ medium: s.medium,
+                max_distance: this.settings.max_distance }) }))
+            .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(),
+            };
+            // Copies/uniform uploads must be encoded before opening the render pass.
+            const draws = surfaces.map(s => ({ surface: s.gpu_surface, bindings: WATER_RESOURCES.generateBindings({ ...shared,
+                water: encoder.allocateTransientValueBuffer(WATER_DRAW_STRUCT, s),
+                surface_vertices: s.gpu_surface.vertices,
+            }, 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 },
+            });
+            for (const draw of draws) { graphics.setPipelineBindings(render, pipeline, draw.bindings); water_surface_draw(render, draw.surface); }
+            render.end();
+        });
+        for (const [name, handle] of Object.entries({ camera, color: color_texture, scene_depth: depth_texture,
+            normal: normal_texture, hzb: hzb_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 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 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 = {};
+        // the optics read the GI mode the meshes in this frame are lit by: a reflection or a sky that
+        // misses on screen falls back to it, as SSR's resolve does
+        const use_brick4 = indirect_lighting_mode === ShadeIndirectLightingMode.Brick4;
+        const finalize_pipeline = use_brick4 ? this.#finalize_pipeline_brick4 : this.#finalize_pipeline_ibl;
+        const finalize_resources = use_brick4 ? WATER_FINALIZE_RESOURCES_BRICK4 : WATER_FINALIZE_RESOURCES_IBL;
+        const bodies = this.bodies;
+        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(),
+                receiver: resources.get(d.receiver).obtainView(), trace_metadata: resources.get(d.trace_metadata).obtainView(),
+                visibility_distance: resources.get(d.visibility_distance).obtainView(),
+                water_bodies: bodies?.buffer,
+                // the lights, as the transparent meshes bind them
+                light_data: view_ctx.scene.lights.buffer_data,
+                tEnvironment: resources.get(d.environment).obtainView(),
+                cluster_parameters: resources.get(d.light_cluster_parameters),
+                cluster_lookup: resources.get(d.light_cluster_lookup),
+                cluster_data: resources.get(d.light_cluster_data),
+                shadowmapAtlas: resources.get(d.shadowmap_atlas).obtainView(),
+                sCompareLinear: graphics.samplers.obtain(SHADOWMAP_COMPARE_SAMPLER_DESCRIPTOR),
+            };
+            if (use_brick4) {
+                shared.brick4 = view_ctx.scene.volumetric_light_map.buffer;
+                shared.view = view_ctx.uniform_buffer.buffer;
             }
-
-            const height = graphics.textures.obtain(surface.height_texture);
-
-            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
+            const draws = surfaces.map(s => ({ surface: s.gpu_surface, bindings: finalize_resources.generateBindings({...shared,
+                water: encoder.allocateTransientValueBuffer(WATER_DRAW_STRUCT, s),
+                surface_vertices: s.gpu_surface.vertices,
+            }, 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},
             });
-
-            draws.push(WATER_RESOURCES.generateBindings({
-                camera,
-                water,
-                scene_depth: depth_view,
-                terrain_height: height.obtainView(),
-                height_sampler: sampler
-            }, encoder));
+            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 draw of draws) { graphics.setPipelineBindings(render, finalize_pipeline, draw.bindings); water_surface_draw(render, draw.surface); }
+            render.end();
+        });
+        for (const key of ['camera','scene_depth','normal','hzb','color','receiver','trace_metadata','visibility_distance','interface_depth']) {
+            finalize_data[key] = finalize.read(data[key]);
         }
+        for (const [key, handle] of Object.entries({ environment: environment_texture, light_cluster_parameters,
+            light_cluster_lookup, light_cluster_data, shadowmap_atlas })) { finalize_data[key] = finalize.read(handle); }
+        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 };
+    }
 
-        render_pass.end();
+    /** 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;
+    }
+
+    #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_gi.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The environment map: irradiance as its roughness-1 level × π, specular from its prefiltered levels.
+ * Expects `tEnvironment`.
+ * @type {CodeChunk}
+ */
+export const chunk_water_gi_ibl: CodeChunk;
+/**
+ * Brick4, the volumetric directional light map: position-dependent, so water under a bridge receives
+ * less sky and reflects the bridge's light rather than the sky. Expects `brick4` and `view`.
+ * @type {CodeChunk}
+ */
+export const chunk_water_gi_brick4: CodeChunk;
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_water_gi.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_water_gi.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/water/chunk_water_gi.js"],"names":[],"mappings":"AAqBA;;;;GAIG;AACH,iCAFU,SAAS,CAUoC;AAEvD;;;;GAIG;AACH,oCAFU,SAAS,CAgBwB;0BAlDjB,iCAAiC"}

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

@@ -0,0 +1,56 @@
+import { chunk_get_ibl_irradiance } from "../deferred/indirect/chunk_get_ibl_irradiance.js";
+import { chunk_get_ibl_radiance } from "../deferred/indirect/chunk_get_ibl_radiance.js";
+import {
+    chunk_brick4_sample_forward_indirect
+} from "../global_illumination/brick4/gpu/draw/chunk_brick4_sample_forward_indirect.js";
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+
+/*
+ What the engine's indirect lighting says at a point on the water, one module per indirect-lighting
+ mode, as SSR's resolve and the transparent mesh draw are split (WATER_OPTICS_PLAN_2026_10_02.md
+ §5.4). Each defines the same two functions, so the water's optics body is written once and composed
+ with either:
+
+ - water_gi_irradiance(position, normal): plane irradiance on a surface facing normal — the sky light
+   that enters the water;
+ - water_gi_specular(position, normal, view_direction, roughness): the radiance a reflection that
+   missed on screen falls back to. view_direction points from the surface to the camera.
+
+ LPV has no transparent variant: like the transparent meshes, water uses the IBL module under it.
+*/
+
+/**
+ * The environment map: irradiance as its roughness-1 level × π, specular from its prefiltered levels.
+ * Expects `tEnvironment`.
+ * @type {CodeChunk}
+ */
+export const chunk_water_gi_ibl = CodeChunk.from(/* language=WGSL */ `
+fn water_gi_irradiance(position: vec3<f32>, normal: vec3<f32>) -> vec3<f32> {
+    return get_ibl_irradiance(normal);
+}
+
+fn water_gi_specular(position: vec3<f32>, normal: vec3<f32>, view_direction: vec3<f32>, roughness: f32) -> vec3<f32> {
+    return get_ibl_radiance(view_direction, normal, roughness);
+}
+`, [chunk_get_ibl_irradiance, chunk_get_ibl_radiance]);
+
+/**
+ * Brick4, the volumetric directional light map: position-dependent, so water under a bridge receives
+ * less sky and reflects the bridge's light rather than the sky. Expects `brick4` and `view`.
+ * @type {CodeChunk}
+ */
+export const chunk_water_gi_brick4 = CodeChunk.from(/* language=WGSL */ `
+fn water_gi_irradiance(position: vec3<f32>, normal: vec3<f32>) -> vec3<f32> {
+    var radiance: vec3<f32>;
+    var irradiance: vec3<f32>;
+    brick4_sample_forward_indirect(position, normal, normal, normal, 1.0, &radiance, &irradiance);
+    return irradiance;
+}
+
+fn water_gi_specular(position: vec3<f32>, normal: vec3<f32>, view_direction: vec3<f32>, roughness: f32) -> vec3<f32> {
+    var radiance: vec3<f32>;
+    var irradiance: vec3<f32>;
+    brick4_sample_forward_indirect(position, view_direction, normal, normal, roughness, &radiance, &irradiance);
+    return radiance;
+}
+`, [chunk_brick4_sample_forward_indirect]);