@woosh/meep-engine 3.38.0 → 3.39.0

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

@@ -3,27 +3,59 @@ import { TextureResourceDescriptor } from "../../device/graph/TextureResourceDes
 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, create_water_finalize_pipeline, WATER_DRAW_STRUCT, WATER_TRACE_STRUCT,
-    WATER_RESOURCES, WATER_FINALIZE_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";
 
+/**
+ * A surface the water passes can draw: visible, and with its surface interface published by the
+ * producer this frame.
+ * @param {Object} s
+ * @returns {boolean}
+ */
+function water_surface_drawable(s) {
+    return s.visible && s.gpu_surface !== undefined;
+}
+
+/**
+ * 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
+ */
+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 };
+        max_updates: 4, fallback_steps: 48, mode: 0, reflections: 1, debug_view: 0, inscatter_segments: 4 };
+    /**
+     * 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}
+     */
+    bodies = null;
     #pipeline = create_water_pipeline();
-    #finalize_pipeline = create_water_finalize_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;
 
     avboit_is_empty() {
-        return !this.settings.enabled || !this.surfaces.some(s => s.visible && s.height_texture !== null);
+        // 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);
     }
 
     /** Optional single-pixel readback on the next rendered water frame. No per-frame readback. */
@@ -53,11 +85,11 @@ export class GPUWaterRenderer {
     }
 
     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() }))
+        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 };
@@ -75,14 +107,12 @@ export class GPUWaterRenderer {
                 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,
+            const draws = surfaces.map(s => ({ surface: s.gpu_surface, bindings: WATER_RESOURCES.generateBindings({ ...shared,
                 water: encoder.allocateTransientValueBuffer(WATER_DRAW_STRUCT, s),
-                terrain_height: graphics.textures.obtain(s.height_texture).obtainView(),
-            }, encoder));
+                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],
@@ -90,11 +120,11 @@ export class GPUWaterRenderer {
                 depthStencilAttachment: { view: resources.get(data.interface_depth).obtainView(DEFAULT_DEPTH_TEXTURE_VIEW),
                     depthLoadOp: "clear", depthStoreOp: "store", depthClearValue: 0 },
             });
-            for (const bindings of draws) { graphics.setPipelineBindings(render, pipeline, bindings); render.draw(6); }
+            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, environment: environment_texture })) { data[name] = pass.read(handle); }
+            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),
@@ -120,21 +150,38 @@ export class GPUWaterRenderer {
             inputs: { distance_field: horizontal }, output_resolution: visibility_resolution });
         data.visibility_distance = visibility_distance;
         const finalize_data = {};
-        const finalize_pipeline = this.#finalize_pipeline;
+        // 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(), tEnvironment: resources.get(d.environment).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(),
-                height_sampler: graphics.samplers.obtain(SAMPLER_LINEAR_UPSCALE),
+                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),
             };
-            const draws = surfaces.map(s => WATER_FINALIZE_RESOURCES.generateBindings({...shared,
+            if (use_brick4) {
+                shared.brick4 = view_ctx.scene.volumetric_light_map.buffer;
+                shared.view = view_ctx.uniform_buffer.buffer;
+            }
+            const draws = surfaces.map(s => ({ surface: s.gpu_surface, bindings: finalize_resources.generateBindings({...shared,
                 water: encoder.allocateTransientValueBuffer(WATER_DRAW_STRUCT, s),
-                terrain_height: graphics.textures.obtain(s.height_texture).obtainView(),
-            }, encoder));
+                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: [],
@@ -145,12 +192,14 @@ export class GPUWaterRenderer {
             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); }
+            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','environment','receiver','trace_metadata','visibility_distance','interface_depth']) {
+        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),

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]);

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

@@ -1,5 +1,7 @@
+export const WATER_LEVEL_TOLERANCE_DECLARATION: CodeChunk;
 export const chunk_water_refraction_confidence: CodeChunk;
 export const chunk_water_transport: CodeChunk;
+export const chunk_water_receiver_texel: 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

@@ -1 +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"}
+{"version":3,"file":"chunk_water_transport.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/water/chunk_water_transport.js"],"names":[],"mappings":"AAUA,0DAEG;AAEH,0DAeG;AAEH,8CAsBG;AAGH,mDAS6F;AAI7F,sDAmCoE;0BAxG1C,iCAAiC"}

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

@@ -2,6 +2,15 @@ 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';
+import { chunk_screen_space_newton_ray } from '../shader/chunk/screen_space/chunk_screen_space_newton_ray.js';
+import { chunk_texel_coordinate_to_uv } from '../shader/chunk/texture/chunk_texel_coordinate_to_uv.js';
+import { chunk_get_bilinear_filter_uv } from '../shader/chunk/texture/sample/chunk_get_bilinear_filter_uv.js';
+
+// How far above the water level a screen-space receiver may lie and still count as submerged.
+// Receiver selection and the optics' color gather must agree on it.
+export const WATER_LEVEL_TOLERANCE_DECLARATION = CodeChunk.from(/* language=WGSL */ `
+const WATER_LEVEL_TOLERANCE: f32 = 0.02;
+`);
 
 export const chunk_water_refraction_confidence = CodeChunk.from(/* language=WGSL */ `
 fn water_refraction_lookup(original: vec2f, receiver: vec2f, confidence: f32) -> vec2f {
@@ -11,79 +20,80 @@ fn water_refraction_confidence(uv: vec2f, original_uv: vec2f, size: vec2f, dista
     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));
+    // Distance from the frame border of whichever of source and receiver is nearer to it.
+    let edge = min(min(original_uv, 1.0 - original_uv), min(uv, 1.0 - uv));
     // 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));
+        min(edge.x, edge.y));
 }
 `);
 
 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));
+// The water's own event at one pixel, before coverage: the fraction of the radiance behind it that
+// it transmits, and the radiance it sends towards the camera itself. A transmittance under the floor
+// AVBOIT can encode is raised to it, and the radiance scaled with the lost throughput so the shared
+// normalization still returns it whole.
+fn water_event(transmission: vec3f, radiance: vec3f) -> WaterEvent {
+    let t = max(transmission, vec3f(1e-6));
+    let scale = (1.0 - t) / max(1.0 - transmission, vec3f(1e-20));
+    return WaterEvent(t, select(scale, vec3f(1.0), transmission >= vec3f(1e-6)) * radiance);
 }
 // 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 t = mix(vec3f(1.0), event.transmission, a);
     let w = a * event.radiance;
-    let background = ((1.0-a)*original + a*event.transmission*receiver) / t;
+    let background = mix(original, event.transmission * receiver, a) / t;
     return WaterTransport(t, w, background);
 }
 `);
 
+// One G-buffer texel in world space: its stored depth, texel-center position and face normal.
+export const chunk_water_receiver_texel = CodeChunk.from(/* language=WGSL */ `
+struct WaterReceiverTexel { depth: f32, position: vec3f, normal: vec3f }
+fn water_receiver_texel(depth: texture_2d<f32>, normals: texture_2d<u32>, coord: vec2i,
+    inverse_projection: mat4x4f, inverse_view: mat4x4f) -> WaterReceiverTexel {
+    let d = textureLoad(depth, coord, 0).r;
+    let center = texel_coordinate_to_uv(vec2f(coord), textureDimensions(depth, 0));
+    let position = inverse_view * vec4f(inv_project_position(vec3f(center, d), inverse_projection), 1.0);
+    return WaterReceiverTexel(d, position.xyz, decode_g_buffer_normal(textureLoad(normals, coord, 0).zw));
+}
+`, [chunk_decode_g_buffer_normal, chunk_inv_project_position, chunk_texel_coordinate_to_uv]);
+
 // 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.
+// Depth is stored at the texel center. Reconstruct the lookup on that texel's tangent
+// 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));
+    let receiver = screen_space_ray_load_receiver(uv, depth, normals, inverse_projection, world_to_view);
+    return distance(origin, screen_space_ray_lookup_position(uv, receiver, inverse_projection).xyz);
 }
 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);
+    let center = water_receiver_texel(depth, normals, clamp(vec2i(uv * vec2f(size)), vec2i(0), size-1),
+        inverse_projection, inverse_view);
+    if (is_background(center.depth)
+        || (below_interface && center.position.y > level + WATER_LEVEL_TOLERANCE)) { return vec4f(0.0); }
+    let bilinear = get_bilinear_filter_uv(uv, vec2u(size));
+    let base = vec2i(bilinear.origin);
+    let f = bilinear.weights;
     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 tap = water_receiver_texel(depth, normals, coord, inverse_projection, inverse_view);
+            if (is_background(tap.depth) || (below_interface && tap.position.y > level + WATER_LEVEL_TOLERANCE)
+                || dot(center.normal, tap.normal) < 0.95
+                || abs(dot(tap.position - center.position, center.normal)) > 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;
@@ -91,4 +101,5 @@ fn water_receiver_radiance(scene: texture_2d<f32>, depth: texture_2d<f32>, norma
     }
     return vec4f(color / max(weight, 1e-20), weight);
 }
-`, [chunk_decode_g_buffer_normal, chunk_inv_project_position, chunk_is_background]);
+`, [chunk_is_background, chunk_screen_space_newton_ray, chunk_get_bilinear_filter_uv,
+    chunk_water_receiver_texel, WATER_LEVEL_TOLERANCE_DECLARATION]);

package/src/shade/renderer/water/medium/GPUWaterBodies.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The frame's water bodies on the GPU, as {@link WATER_BODIES_STRUCT}: one uniform buffer every
+ * consumer of the water medium binds.
+ *
+ * Rebuilt each frame from the surfaces in entity order — the order the water passes draw in — and
+ * each surface is told its row as `surface.body_index`. The derived fields are then integrated on
+ * the GPU, in a pass recorded at the head of the frame, so everything recorded after reads them.
+ */
+export class GPUWaterBodies {
+    /**
+     * The table, or null before the first record.
+     * @returns {GPUBuffer|null}
+     */
+    get buffer(): any;
+    dispose(): void;
+    /**
+     * @param {Object} options
+     * @param {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} options.graph
+     * @param {GPUDevice} options.device
+     * @param {Object[]} options.surfaces
+     */
+    record({ graph, device, surfaces }: {
+        graph: import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
+        device: GPUDevice;
+        surfaces: any[];
+    }): void;
+    #private;
+}
+//# sourceMappingURL=GPUWaterBodies.d.ts.map

package/src/shade/renderer/water/medium/GPUWaterBodies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GPUWaterBodies.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/water/medium/GPUWaterBodies.js"],"names":[],"mappings":"AAaA;;;;;;;GAOG;AACH;IAaI;;;OAGG;IACH,kBAEC;IAED,gBAIC;IAED;;;;;OAKG;IACH;QAJsG,KAAK,EAAhG,OAAO,8DAA8D,EAAE,UAAU;QAC9D,MAAM;QACP,QAAQ,EAA1B,KAAQ;aA8DlB;;CACJ"}

package/src/shade/renderer/water/medium/GPUWaterBodies.js

@@ -0,0 +1,116 @@
+import { assert } from "../../../../core/assert.js";
+import { write_gpu_typed_buffer } from "../../shader/type/serde/write_gpu_typed_buffer.js";
+import { shader_water_bodies_derive } from "./shader_water_bodies_derive.js";
+import { WATER_BODIES_STRUCT, WATER_BODY_CAPACITY } from "./WATER_BODIES_STRUCT.js";
+
+/**
+ * An empty medium record, for the table's unused slots.
+ */
+const EMPTY_MEDIUM = Object.freeze({
+    absorption: [0, 0, 0], priority: 0, lobe_count: 0,
+    lobes: [0, 1, 2, 3].map(() => ({ scattering: [0, 0, 0], kind: 0, p0: 0, p1: 0 })),
+});
+
+/**
+ * The frame's water bodies on the GPU, as {@link WATER_BODIES_STRUCT}: one uniform buffer every
+ * consumer of the water medium binds.
+ *
+ * Rebuilt each frame from the surfaces in entity order — the order the water passes draw in — and
+ * each surface is told its row as `surface.body_index`. The derived fields are then integrated on
+ * the GPU, in a pass recorded at the head of the frame, so everything recorded after reads them.
+ */
+export class GPUWaterBodies {
+    /**
+     * @type {GPUDevice|null}
+     */
+    #device = null;
+
+    /**
+     * @type {GPUBuffer|null}
+     */
+    #buffer = null;
+
+    #bytes = new ArrayBuffer(WATER_BODIES_STRUCT.size);
+
+    /**
+     * The table, or null before the first record.
+     * @returns {GPUBuffer|null}
+     */
+    get buffer() {
+        return this.#buffer;
+    }
+
+    dispose() {
+        this.#buffer?.destroy();
+        this.#buffer = null;
+        this.#device = null;
+    }
+
+    /**
+     * @param {Object} options
+     * @param {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} options.graph
+     * @param {GPUDevice} options.device
+     * @param {Object[]} options.surfaces
+     */
+    record({ graph, device, surfaces }) {
+        assert.defined(graph, 'graph');
+        assert.defined(device, 'device');
+        assert.isArray(surfaces, 'surfaces');
+
+        if (device !== this.#device) {
+            this.dispose();
+            this.#device = device;
+            this.#buffer = device.createBuffer({
+                label: "Water / bodies",
+                size: WATER_BODIES_STRUCT.size,
+                usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+            });
+        }
+
+        const ordered = surfaces.slice().sort((a, b) => a.entity - b.entity);
+
+        assert.lessThanOrEqual(ordered.length, WATER_BODY_CAPACITY, `at most ${WATER_BODY_CAPACITY} water bodies`);
+
+        const bodies = [];
+
+        for (let i = 0; i < WATER_BODY_CAPACITY; i++) {
+            const surface = ordered[i];
+
+            if (surface === undefined) {
+                bodies.push({
+                    medium: EMPTY_MEDIUM, ior: 1,
+                    backscattering: [0, 0, 0, 0], extinction: [0, 0, 0, 0], diffuse_transmittance: 0,
+                });
+                continue;
+            }
+
+            surface.body_index = i;
+
+            bodies.push({
+                medium: surface.medium.to_gpu_record(),
+                ior: surface.ior,
+                backscattering: [0, 0, 0, 0],
+                extinction: [0, 0, 0, 0],
+                diffuse_transmittance: 0,
+            });
+        }
+
+        write_gpu_typed_buffer({ count: ordered.length, bodies }, WATER_BODIES_STRUCT, this.#bytes, 0);
+
+        device.queue.writeBuffer(this.#buffer, 0, this.#bytes);
+
+        if (ordered.length === 0) {
+            // an empty table, still valid to bind; nothing to derive
+            return;
+        }
+
+        const buffer = this.#buffer;
+
+        const pass = graph.add("Water / bodies derive", {}, (data, resources, { encoder }) => {
+            shader_water_bodies_derive.dispatch({ encoder, bindings: { water_bodies: buffer } });
+        });
+
+        // fills a persistent buffer that later passes bind directly
+        pass.make_side_effect();
+    }
+}

package/src/shade/renderer/water/medium/WATER_BODIES_STRUCT.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Most water bodies a frame carries.
+ * @type {number}
+ */
+export const WATER_BODY_CAPACITY: number;
+/**
+ * One body of water as the water passes read it (WATER_OPTICS_PLAN_2026_10_02.md §7.2): its optics,
+ * and nothing about where it is — where a body's water is, is its mesh. The authored part is written
+ * from the CPU each frame; the derived part is integrated on the GPU from the medium's own phase
+ * functions right after, so the two can never disagree with what the path tracer samples.
+ *
+ * @type {WebGPUStruct}
+ */
+export const WATER_BODY_STRUCT: WebGPUStruct;
+/**
+ * Every body of a frame, as the uniform `water_bodies`. Uniform rather than storage because the water
+ * optics pass binds it beside the light group, whose storage buffers spend the stage's budget.
+ *
+ * @type {WebGPUStruct}
+ */
+export const WATER_BODIES_STRUCT: WebGPUStruct;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+//# sourceMappingURL=WATER_BODIES_STRUCT.d.ts.map

package/src/shade/renderer/water/medium/WATER_BODIES_STRUCT.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WATER_BODIES_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/water/medium/WATER_BODIES_STRUCT.js"],"names":[],"mappings":"AAKA;;;GAGG;AACH,kCAFU,MAAM,CAEsB;AAEtC;;;;;;;GAOG;AACH,gCAFU,YAAY,CAaN;AAEhB;;;;;GAKG;AACH,kCAFU,YAAY,CAKJ;6BAtCW,mCAAmC"}

package/src/shade/renderer/water/medium/WATER_BODIES_STRUCT.js

@@ -0,0 +1,42 @@
+import { MEDIUM_STRUCT } from "../../medium/MEDIUM_STRUCT.js";
+import { f32, u32, vec4f } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+
+/**
+ * Most water bodies a frame carries.
+ * @type {number}
+ */
+export const WATER_BODY_CAPACITY = 16;
+
+/**
+ * One body of water as the water passes read it (WATER_OPTICS_PLAN_2026_10_02.md §7.2): its optics,
+ * and nothing about where it is — where a body's water is, is its mesh. The authored part is written
+ * from the CPU each frame; the derived part is integrated on the GPU from the medium's own phase
+ * functions right after, so the two can never disagree with what the path tracer samples.
+ *
+ * @type {WebGPUStruct}
+ */
+export const WATER_BODY_STRUCT = WebGPUStruct.from({
+    /** what fills the body: absorption and scattering lobes, RGB 1/m */
+    medium: MEDIUM_STRUCT,
+    /** index of refraction relative to the air above */
+    ior: f32,
+    /** derived: backscattering b_b = Σ b_i · B_i, RGB 1/m, in xyz */
+    backscattering: vec4f,
+    /** derived: beam attenuation c = a + Σ b_i, RGB 1/m, in xyz; per-pixel code reads it rather than walk the lobes */
+    extinction: vec4f,
+    /** derived: hemispherical Fresnel transmittance into the water for a uniform sky */
+    diffuse_transmittance: f32,
+}, "WaterBody");
+
+/**
+ * Every body of a frame, as the uniform `water_bodies`. Uniform rather than storage because the water
+ * optics pass binds it beside the light group, whose storage buffers spend the stage's budget.
+ *
+ * @type {WebGPUStruct}
+ */
+export const WATER_BODIES_STRUCT = WebGPUStruct.from({
+    count: u32,
+    bodies: WebGPUArray.from(WATER_BODY_STRUCT, WATER_BODY_CAPACITY),
+}, "WaterBodies");