@woosh/meep-engine 3.36.0 → 3.38.0

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

@@ -1,246 +1,384 @@
-import { GPUShaderStage } from "../../descriptor/GPUShaderStage.js";
-import { ColorTargetState } from "../../descriptor/pipeline/render/ColorTargetState.js";
-import { RenderPipelineDescriptor } from "../../descriptor/pipeline/render/RenderPipelineDescriptor.js";
-import { CAMERA_UNIFORM_STRUCT } from "../camera/CAMERA_UNIFORM_STRUCT.js";
-import { chunk_get_view_space_depth } from "../shader/chunk/depth/chunk_get_view_space_depth.js";
-import { CodeChunk } from "../shader/compiler/CodeChunk.js";
-import { ShaderResourceSetDescriptor } from "../shader/resource/ShaderResourceSetDescriptor.js";
-import { ShaderDescriptor } from "../shader/ShaderDescriptor.js";
-import { f32, vec2f, vec3f, vec4f } from "../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUStruct } from "../shader/type/WebGPUStruct.js";
-
-/**
- * One water surface. Small, and rewritten per surface per frame rather than tabled — a level has a
- * handful of these, not thousands.
- */
-export const WATER_DRAW_STRUCT = WebGPUStruct.from({
-    /**
-     * World-space extent of the surface, `x0, z0, x1, z1`. The quad is generated from this rather
-     * than from a vertex buffer: the surface is a rectangle at a constant height, and the waves
-     * displace nothing — they only move where the shore line falls.
-     */
-    extent: vec4f,
-
-    /**
-     * Where the water's UV lands in the terrain height map, `offset.xy, scale.xy`.
-     */
-    height_uv: vec4f,
-
-    color_deep: vec3f,
-    color_shore: vec3f,
-
-    /**
-     * The surface's world height.
-     */
-    level: f32,
-
-    /**
-     * Seconds. Waves are a function of it, so it is the only field that must change every frame.
-     */
-    time: f32,
-
-    wave_amplitude: f32,
-    wave_speed: f32,
-    wave_frequency: f32,
-
-    /**
-     * How fast the water goes opaque with the depth of scene behind it.
-     */
-    scattering: f32,
-
-    /**
-     * Water depth over which the shore colour gives way to the deep colour.
-     */
-    shore_transition: vec2f,
-}, "WaterDraw").pack();
-
-const resources = new ShaderResourceSetDescriptor();
-
-resources.createGroup()
-    .addUniform("camera", CAMERA_UNIFORM_STRUCT)
-    .addUniform("water", WATER_DRAW_STRUCT)
-    // Bound as an unfilterable float rather than as `depth`, which is how every other pass in the
-    // engine reads the depth buffer — GTAO, TAA and the volumetrics all declare it this way and take
-    // `.r`. Declaring it `depth` yields a `texture_depth_2d` binding, and the depth this pass sampled
-    // through one did not come back as the scene's.
-    .addTexture("scene_depth")
-    .addTexture("terrain_height", "float")
-    .addSampler("height_sampler");
-
-const body = CodeChunk.from(
-    //language=WGSL
-    `
-struct WaterVertexOut {
-    @builtin(position) clip : vec4<f32>,
-    @location(0) world : vec3<f32>,
-    @location(1) uv : vec2<f32>,
-}
-
-/*
- Two triangles from the vertex index alone. The surface is a rectangle at a constant height, so
- there is no geometry worth uploading, and nothing about it changes between frames except the
- uniform.
-*/
-@vertex
-fn vs_main(@builtin(vertex_index) vi : u32) -> WaterVertexOut {
-    var CORNERS = array<vec2<f32>, 6>(
-        vec2<f32>(0.0, 0.0),
-        vec2<f32>(1.0, 0.0),
-        vec2<f32>(0.0, 1.0),
-        vec2<f32>(1.0, 0.0),
-        vec2<f32>(1.0, 1.0),
-        vec2<f32>(0.0, 1.0),
-    );
-
-    let corner = CORNERS[vi];
-
-    let world = vec3<f32>(
-        mix(water.extent.x, water.extent.z, corner.x),
-        water.level,
-        mix(water.extent.y, water.extent.w, corner.y)
-    );
-
-    var out : WaterVertexOut;
-
-    out.clip = camera.view_projection_matrix * vec4<f32>(world, 1.0);
-    out.world = world;
-    out.uv = corner;
-
-    return out;
-}
-
-/**
- * The terrain under the water, softened. A hard heightmap read makes the shore line crawl along
- * texel edges; the legacy shader blurred it for the same reason, and the softness is the look
- * rather than an approximation of one.
- */
-fn sample_terrain_height(uv : vec2<f32>) -> f32 {
-    let dimensions = vec2<f32>(textureDimensions(terrain_height, 0));
-    let texel = 1.0 / dimensions;
-
-    var total = 0.0;
-
-    for (var y = -1; y <= 1; y = y + 1) {
-        for (var x = -1; x <= 1; x = x + 1) {
-            let offset = vec2<f32>(f32(x), f32(y)) * texel;
-
-            total = total + textureSampleLevel(terrain_height, height_sampler, uv + offset, 0.0).r;
-        }
-    }
-
-    return total / 9.0;
-}
-
-@fragment
-fn fs_main(in : WaterVertexOut) -> @location(0) vec4<f32> {
-    let coord = vec2<i32>(in.clip.xy);
-
-    /*
-     How much scene sits behind the water at this pixel. Both depths go through the camera's own
-     device-to-view parameters, so this is correct under the reverse-Z infinite-far projection Shade
-     draws with — the legacy shader's near/far reconstruction is not, and reproducing its arithmetic
-     here would have put the shore line in the wrong place everywhere.
-    */
-    let scene_view_depth = get_view_space_depth(
-        textureLoad(scene_depth, coord, 0).r,
-        camera
-    );
-
-    let surface_view_depth = get_view_space_depth(in.clip.z, camera);
-
-    let behind = scene_view_depth - surface_view_depth;
-
-    if (!(behind > 0.0)) {
-        // the water surface is behind something opaque — written as a positive test so a depth that
-        // arrives as NaN discards too rather than drawing over the scene
-        discard;
-    }
-
-    let height_uv = in.uv * water.height_uv.zw + water.height_uv.xy;
-
-    let terrain = sample_terrain_height(height_uv);
-
-    let depth = water.level - terrain;
-
-    let hash = (in.world.x + in.world.z) * water.wave_frequency;
-
-    const INVERSE_PI = 0.3183098861837907;
-
-    let wave = sin(hash + water.time * water.wave_speed) * INVERSE_PI;
-
-    let wave_depth = depth + water.wave_amplitude * wave;
-
-    let deep = smoothstep(water.shore_transition.x, water.shore_transition.y, wave_depth);
-
-    var color = mix(
-        vec4<f32>(water.color_shore, 0.8),
-        vec4<f32>(water.color_deep, 1.0),
-        deep
-    );
-
-    // scattering: the more scene there is behind the water, the less of it comes back through
-    color.a = color.a * (1.0 - exp(-behind * water.scattering));
-
-    return color;
-}
-    `, [
-        chunk_get_view_space_depth
-    ]
-);
-
-export const water_shader = ShaderDescriptor.from({
-    label: "Water",
-    resources,
-    body
-});
-
-const WATER_BLEND = {
-    color: {
-        srcFactor: "src-alpha",
-        dstFactor: "one-minus-src-alpha",
-        operation: "add",
-    },
-    alpha: {
-        srcFactor: "one",
-        dstFactor: "one-minus-src-alpha",
-        operation: "add",
-    },
-};
-
-/**
- * Build the water pipeline.
- *
- * **It has no depth attachment, and that is forced rather than chosen.** The shader *samples* scene
- * depth to know how much water the view looks through, and a texture may not be a sampled source
- * and a render attachment in the same pass. So the depth test the hardware would have done is done
- * in the shader instead — which is also why the fragment `discard` there is load-bearing rather
- * than a guard: without it, water would draw over the things standing in it.
- *
- * @param {object} [options]
- * @param {string} [options.color_format]
- * @returns {RenderPipelineDescriptor}
- */
-export function create_water_pipeline({ color_format = "rgba16float" } = {}) {
-    const code = water_shader.source;
-
-    return RenderPipelineDescriptor.from({
-        label: "Water",
-        layout: resources.generatePipelineLayout(GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT),
-        vertex: { module: { code }, entryPoint: "vs_main" },
-        fragment: {
-            module: { code },
-            entryPoint: "fs_main",
-            targets: [ColorTargetState.from({ format: color_format, blend: WATER_BLEND })],
-        },
-        // the surface is a rectangle seen from above or below — the legacy plane was BackSide for
-        // the same reason, and neither side of it should vanish
-        primitive: { topology: "triangle-list", cullMode: "none" },
-    });
-}
-
-/**
- * The pipeline's resource set, for building bind groups.
- *
- * @type {ShaderResourceSetDescriptor}
- */
-export const WATER_RESOURCES = resources;
+import { GPUShaderStage } from "../../descriptor/GPUShaderStage.js";
+import { DepthStencilState } from "../../descriptor/pipeline/render/DepthStencilState.js";
+import { RenderPipelineDescriptor } from "../../descriptor/pipeline/render/RenderPipelineDescriptor.js";
+import { CAMERA_UNIFORM_STRUCT } from "../camera/CAMERA_UNIFORM_STRUCT.js";
+import { chunk_F_Schlick } from "../shader/chunk/brdf/fresnel/chunk_F_Schlick.js";
+import { chunk_dielectric_specular_color } from "../shader/chunk/material/chunk_dielectric_specular_color.js";
+import { chunk_ffx_sssr_advance_ray } from "../shader/chunk/screen_space/chunk_ffx_sssr_advance_ray.js";
+import { chunk_ffx_sssr_load_depth } from "../shader/chunk/screen_space/chunk_ffx_sssr_load_depth.js";
+import { chunk_ffx_sssr_validate_hit } from "../shader/chunk/screen_space/chunk_ffx_sssr_validate_hit.js";
+import { chunk_project_direction } from "../shader/chunk/screen_space/chunk_project_direction.js";
+import { chunk_screen_space_newton_ray } from "../shader/chunk/screen_space/chunk_screen_space_newton_ray.js";
+import { chunk_sample_environment_map } from "../shader/chunk/texture/sample/chunk_sample_environment_map.js";
+import { chunk_texture_sample_bilinear_uv } from "../shader/chunk/texture/sample/chunk_texture_sample_bilinear_uv.js";
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+import { ShaderResourceSetDescriptor } from "../shader/resource/ShaderResourceSetDescriptor.js";
+import { ShaderDescriptor } from "../shader/ShaderDescriptor.js";
+import { f32, u32, vec2f, vec3f, vec4f } from "../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../shader/type/WebGPUStruct.js";
+import { chunk_water_receiver_radiance, chunk_water_refraction_confidence, chunk_water_transport } from './chunk_water_transport.js';
+
+export const WATER_DRAW_STRUCT = WebGPUStruct.from({
+    extent: vec4f, height_uv: vec4f, color_deep: vec3f, color_shore: vec3f,
+    level: f32, time: f32, wave_amplitude: f32, wave_speed: f32, wave_frequency: f32,
+    scattering: f32, shore_transition: vec2f,
+    ior: f32, normal_strength: f32, normal_scale: f32, roughness: f32, extinction: vec3f, surface_id: u32,
+}, "WaterDraw").pack();
+
+export const WATER_TRACE_STRUCT = WebGPUStruct.from({
+    max_distance: f32, distance_tolerance: f32, max_updates: u32, fallback_steps: u32,
+    mode: u32, reflections: u32,
+}, "WaterTrace").pack();
+
+function water_resources(finalize = false) {
+    const resources = new ShaderResourceSetDescriptor();
+    const group = resources.createGroup()
+        .addUniform("camera", CAMERA_UNIFORM_STRUCT)
+        .addUniform("water", WATER_DRAW_STRUCT)
+        .addUniform("trace", WATER_TRACE_STRUCT)
+        .addTexture("tDepth")
+        .addTexture("tNormal", "uint")
+        .addTexture("tHZB")
+        .addTexture("tScene")
+        .addTexture("tEnvironment")
+        .addTexture("terrain_height", "float")
+        .addSampler("height_sampler");
+    if (finalize) { group.addTexture('receiver').addTexture('trace_metadata').addTexture('visibility_distance'); }
+    return resources;
+}
+const resources = water_resources();
+export const WATER_FINALIZE_RESOURCES = water_resources(true);
+
+export const water_transport_fallback = CodeChunk.from(/* language=WGSL */ `
+fn water_bounded_column_path(depth: f32, direction_y: f32, limit: f32) -> f32 {
+    return min(max(depth, 0.0) / max(abs(direction_y), 0.05), limit);
+}
+`);
+
+const surface_body = CodeChunk.from(/* language=WGSL */ `
+struct WaterVertexOut {
+    @builtin(position) clip: vec4<f32>,
+    @location(0) world: vec3<f32>,
+    @location(1) uv: vec2<f32>,
+}
+
+@vertex
+fn vs_main(@builtin(vertex_index) vi: u32) -> WaterVertexOut {
+    var corners = array<vec2<f32>, 6>(vec2f(0,0), vec2f(1,0), vec2f(0,1),
+        vec2f(1,0), vec2f(1,1), vec2f(0,1));
+    let corner = corners[vi];
+    let world = vec3<f32>(mix(water.extent.x, water.extent.z, corner.x), water.level,
+        mix(water.extent.y, water.extent.w, corner.y));
+    return WaterVertexOut(camera.view_projection_matrix * vec4<f32>(world, 1.0), world, corner);
+}
+
+fn sample_terrain_height(uv: vec2<f32>) -> f32 {
+    let texel = 1.0 / vec2<f32>(textureDimensions(terrain_height, 0));
+    var total = 0.0;
+    for (var y = -1; y <= 1; y++) {
+        for (var x = -1; x <= 1; x++) {
+            total += textureSampleLevel(terrain_height, height_sampler, uv + vec2f(f32(x), f32(y)) * texel, 0.0).r;
+        }
+    }
+    return total / 9.0;
+}
+
+fn water_optical_normal(world: vec3<f32>) -> vec3<f32> {
+    let p = world.xz / max(water.normal_scale, 0.01);
+    let t = water.time * water.wave_speed;
+    let slope = vec2f(cos(p.x + p.y * 0.61 + t), cos(p.y - p.x * 0.43 - t * 0.73));
+    return normalize(vec3f(slope.x * water.normal_strength, 1.0, slope.y * water.normal_strength));
+}
+`);
+
+export const chunk_water_screen_ray = CodeChunk.from(/* language=WGSL */ `
+fn water_hzb_mip_size(depth_size: vec2f, hzb_size: vec2f, mip: i32) -> vec2f {
+    if (mip <= 0) { return depth_size; }
+    return max(vec2f(1.0), floor(hzb_size / exp2(f32(mip-1))));
+}
+// Reuse the renderer's FFX cell intersection and depth loads, but walk the actual
+// integer mip grids. Its SSR driver halves floating sizes and assumes power-of-two
+// reductions; Meep's HZB conservatively resamples arbitrary viewport dimensions.
+fn water_hzb_crossing(origin: vec3f, direction: vec3f, budget: u32,
+    valid: ptr<function,bool>, iterations: ptr<function,u32>) -> vec3f {
+    let size = vec2f(textureDimensions(tDepth,0));
+    let pyramid_size = vec2f(textureDimensions(tHZB,0));
+    let last_mip = i32(textureNumLevels(tHZB));
+    let inverse_direction = select(vec3f(F32_MAX), 1.0/direction, abs(direction)>vec3f(1e-12));
+    let floor_offset = select(vec2f(1.0), vec2f(0.0), direction.xy<vec2f(0.0));
+    let uv_offset = select(0.005/size, -0.005/size, direction.xy<vec2f(0.0));
+    var mip = 0;
+    var position = origin;
+    var travel = 0.0;
+    *valid = false;
+    // Water is absent from the opaque depth buffer: skipping the initial pixel
+    // can skip the entire receiver for almost zero projected displacement.
+    for (var i=0u; i<min(budget,128u); i++) {
+        *iterations = i+1u;
+        if (!screen_space_ray_in_bounds(position.xy) || is_background(position.z)) { break; }
+        let resolution = water_hzb_mip_size(size,pyramid_size,mip);
+        let pixel = resolution * position.xy;
+        let depth = ffx_sssr_load_depth(vec2i(pixel),mip);
+        let skipped = ffx_sssr_advance_ray(origin,direction,inverse_direction,pixel,
+            1.0/resolution,floor_offset,uv_offset,depth,&position,&travel);
+        if (!skipped && mip==0) { *valid=true; break; }
+        mip = clamp(mip+select(-1,1,skipped),0,last_mip);
+    }
+    return position;
+}
+// HZB returns a depth-slab crossing, not the intersection of the ray with the
+// receiver's plane. Refine that crossing before using its UV or optical path.
+fn water_exact_receiver(ray: Ray, input: ScreenSpaceRayHit) -> ScreenSpaceRayHit {
+    var hit = input;
+    if (hit.status != 0u) { return hit; }
+    let size = vec2f(textureDimensions(tDepth, 0));
+    let coord = vec2i(hit.uv * size);
+    let p = inv_project_position(vec3f((vec2f(coord)+0.5)/size, textureLoad(tDepth, coord, 0).r),
+        camera.projection_matrix_inverse);
+    let n = (camera.view_matrix * vec4f(decode_g_buffer_normal(textureLoad(tNormal, coord, 0).zw), 0.0)).xyz;
+    let travel = plane_ray_raycast(ray.origin, ray.direction, plane_from_normal_and_point(n,p));
+    // Keep the analytic distance rather than the projection of the texel center onto the ray.
+    if (travel > 1e-4 && travel <= ray.tmax) {
+        hit.distance = travel;
+        hit.uv = project_position(ray.origin + ray.direction*travel, camera.projection_matrix).xy;
+        // Reprojection can change texel ownership at a silhouette. Validate that lookup
+        // again; the analytic travel above already checked the ray's bounded interval.
+        let checked = screen_space_ray_validate(Ray(ray.origin,ray.direction,1e20),hit.uv,tDepth,tNormal,
+            camera.projection_matrix,camera.projection_matrix_inverse,camera.view_matrix,trace.distance_tolerance);
+        hit.status = checked.status;
+        hit.residual = checked.residual;
+    } else { hit.status = 4u; }
+    return hit;
+}
+fn water_refine_receiver(ray: Ray, seed: vec2f) -> ScreenSpaceRayHit {
+    // The traversal already selected the first depth footprint. Intersect its plane
+    // once and validate ownership; another Newton search could jump past that footprint
+    // to a later root and incorrectly turn it into first-hit visibility evidence.
+    return water_exact_receiver(ray, ScreenSpaceRayHit(seed, 0.0, 1e20, 0u, 0u));
+}
+fn water_hzb_hit(ray: Ray, budget: u32) -> ScreenSpaceRayHit {
+    var miss = ScreenSpaceRayHit(vec2f(0.0), 0.0, 1e20, 0u, 5u);
+    if (budget == 0u || !screen_space_ray_projectable(ray.origin, camera.projection_matrix)
+        || !screen_space_ray_projectable(ray.origin + ray.direction, camera.projection_matrix)) { return miss; }
+    let origin = project_position(ray.origin, camera.projection_matrix);
+    let direction = project_direction(ray.origin, ray.direction, origin, camera.projection_matrix);
+    // Only rays advancing into reverse-Z are supported by this adapter.
+    if (direction.z >= -1e-8 || !screen_space_ray_in_bounds(origin.xy)) { return miss; }
+    var valid = false;
+    var iterations = 0u;
+    let candidate = water_hzb_crossing(origin, direction, budget, &valid, &iterations);
+    if (!valid) { miss.iterations = iterations; return miss; }
+    var hit = water_refine_receiver(ray, candidate.xy);
+    hit.iterations = iterations;
+    return hit;
+}
+
+fn water_select_first_receiver(candidate: ScreenSpaceRayHit, first: ScreenSpaceRayHit, tolerance: f32) -> ScreenSpaceRayHit {
+    if (first.status != 0u) { return first; }
+    return ScreenSpaceRayHit(first.uv, first.distance, first.residual, candidate.iterations,
+        select(0u, 6u, first.distance + tolerance < candidate.distance));
+}
+
+fn water_first_receiver(ray: Ray, candidate: ScreenSpaceRayHit, budget: u32) -> ScreenSpaceRayHit {
+    let start = project_position(ray.origin, camera.projection_matrix).xy;
+    // A ray contained in its source pixel sees the same nearest G-buffer surface.
+    let displacement = abs((candidate.uv-start) * vec2f(textureDimensions(tDepth, 0)));
+    let size = vec2f(textureDimensions(tDepth, 0));
+    if (all(displacement < vec2f(0.5)) && all(vec2i(start*size) == vec2i(candidate.uv*size))) { return candidate; }
+    let first = water_hzb_hit(Ray(ray.origin, ray.direction,
+        min(ray.tmax, candidate.distance + trace.distance_tolerance)), budget);
+    // A local root is not visibility evidence. An exhausted traversal uses the control event.
+    return water_select_first_receiver(candidate, first, trace.distance_tolerance);
+}
+`, [chunk_screen_space_newton_ray, chunk_ffx_sssr_advance_ray, chunk_ffx_sssr_load_depth, chunk_project_direction]);
+
+const body = CodeChunk.from(/* language=WGSL */ `
+struct WaterReceiver {
+    @location(0) receiver: vec4<f32>,
+    @location(1) metadata: vec4<f32>,
+    // Receiver UV, bounded path, classified status + Newton updates / 32. Readback is opt-in.
+}
+
+@fragment
+fn fs_main(in: WaterVertexOut) -> WaterReceiver {
+    let coord = vec2<i32>(in.clip.xy);
+    let dimensions = vec2f(textureDimensions(tDepth, 0));
+    let uv = in.clip.xy / dimensions;
+    let scene_depth = textureLoad(tDepth, coord, 0).r;
+    if (scene_depth >= in.clip.z) { discard; }
+    let terrain = sample_terrain_height(in.uv * water.height_uv.zw + water.height_uv.xy);
+    let water_depth = water.level - terrain;
+    if (water_depth <= 0.0) { discard; }
+    let coverage = smoothstep(0.0, 0.1, water_depth);
+    let origin = (camera.view_matrix * vec4f(in.world, 1.0)).xyz;
+    let incident = normalize(origin);
+    var normal_ws = water_optical_normal(in.world);
+    let above = camera.view_matrix_inverse[3].y >= water.level;
+    if (!above) { normal_ws = -normal_ws; }
+    let normal = normalize((camera.view_matrix * vec4f(normal_ws, 0.0)).xyz);
+    let ior = max(water.ior, 1.0);
+    let direction = refract(incident, normal, 1.0 / ior);
+    let limit = min(max(trace.max_distance, 0.1), camera.clip_near_far.y);
+    let ray = Ray(origin, normalize(direction), limit);
+    var hit = ScreenSpaceRayHit(uv, limit, 1e20, 0u, 8u);
+    var newton_updates = 0u;
+    var newton_failure = 0u;
+    var visibility_checked = false;
+    if (above && trace.mode == 0u) {
+        hit = screen_space_newton_ray(ray, uv, tDepth, tNormal, camera.projection_matrix,
+            camera.projection_matrix_inverse, camera.view_matrix, trace.max_updates, trace.distance_tolerance);
+        newton_updates = hit.iterations;
+        newton_failure = hit.status;
+        if (hit.status == 0u) {
+            // Refine against the selected face before bounding first-hit visibility.
+            hit = water_exact_receiver(ray, hit);
+            visibility_checked = true;
+            hit = water_first_receiver(ray, hit, trace.fallback_steps);
+            if (hit.status != 0u && hit.status != 6u) { newton_failure = 5u; }
+        }
+    }
+    // A screen-space receiver must remain below this flat interface.
+    if (hit.status == 0u || hit.status == 6u) {
+        let receiver_coord = vec2i(hit.uv * dimensions);
+        let receiver_depth = textureLoad(tDepth, receiver_coord, 0).r;
+        let receiver_center = (vec2f(receiver_coord) + 0.5) / dimensions;
+        let receiver_vs = inv_project_position(vec3f(receiver_center, receiver_depth), camera.projection_matrix_inverse);
+        let receiver_ws = (camera.view_matrix_inverse * vec4f(receiver_vs, 1.0)).xyz;
+        if (receiver_ws.y > water.level + 0.02) { hit.status = 5u; newton_failure = 5u; }
+    }
+    // Reject foreground receivers before deciding whether traversal is needed.
+    if (above && trace.mode != 2u && (trace.mode == 1u ||
+        (hit.status != 0u && hit.status != 6u && (!visibility_checked || hit.status == 4u)))) {
+        let fallback = water_hzb_hit(ray, trace.fallback_steps);
+        if (fallback.status == 0u) {
+            let coord = vec2i(fallback.uv * dimensions);
+            let p = inv_project_position(vec3f((vec2f(coord) + 0.5) / dimensions,
+                textureLoad(tDepth, coord, 0).r), camera.projection_matrix_inverse);
+            if ((camera.view_matrix_inverse * vec4f(p, 1.0)).y <= water.level + 0.02) {
+                hit = fallback; hit.status = 6u;
+            }
+        }
+    }
+    // Compute the control event for every pixel, independently of Newton/HZB success.
+    let direction_ws = (camera.view_matrix_inverse * vec4f(ray.direction, 0.0)).xyz;
+    var control_path = water_bounded_column_path(water_depth, direction_ws.y, limit);
+    var control_status = select(8u, 9u, !above);
+    if (!is_background(scene_depth)) {
+        let receiver_vs = inv_project_position(vec3f(uv, scene_depth), camera.projection_matrix_inverse);
+        let receiver_ws = (camera.view_matrix_inverse * vec4f(receiver_vs, 1.0)).xyz;
+        if (receiver_ws.y <= water.level + 0.02 || !above) {
+            control_path = min(distance(origin, receiver_vs), limit);
+            control_status = select(7u, 9u, !above);
+        }
+    }
+    if (trace.mode == 2u || !above || (hit.status != 0u && hit.status != 6u)) {
+        // Never use an unvalidated Newton iterate as a color lookup.
+        hit.uv = uv;
+        // A missing screen receiver is missing visibility, not 300 metres of water.
+        // Use the local terrain column for a bounded physical fallback at sky/edges.
+        hit.distance = control_path;
+        hit.status = control_status;
+    }
+    var status = hit.status;
+    if (status == 6u) { status = 8u + newton_failure; }
+    else if (status == 7u) { status = 16u + newton_failure; }
+    else if (status == 8u) { status = 24u + newton_failure; }
+    else if (status == 9u) { status = 31u; }
+    return WaterReceiver(vec4f(hit.uv, hit.distance, f32(status) + f32(newton_updates)/32.0),
+        vec4f(control_path, min(hit.residual, 65504.0), coverage, f32(water.surface_id)));
+}
+`, [surface_body, chunk_water_screen_ray, water_transport_fallback]);
+
+const finalize_body = CodeChunk.from(/* language=WGSL */ `
+struct WaterOptics {
+    @location(0) transmission: vec4f,
+    @location(1) radiance: vec4f,
+    @location(2) background: vec4f,
+}
+@fragment
+fn fs_main(in: WaterVertexOut) -> WaterOptics {
+    let coord = vec2i(in.clip.xy);
+    let metadata = textureLoad(trace_metadata, coord, 0);
+    // Equal-depth surfaces must retain the same deterministic owner as receiver selection.
+    if (metadata.w != f32(water.surface_id)) { discard; }
+    let dimensions = vec2f(textureDimensions(tDepth, 0));
+    let uv = in.clip.xy / dimensions;
+    let receiver_data = textureLoad(receiver, coord, 0);
+    let origin = (camera.view_matrix * vec4f(in.world, 1.0)).xyz;
+    let incident = normalize(origin);
+    let above = camera.view_matrix_inverse[3].y >= water.level;
+    var normal_ws = water_optical_normal(in.world);
+    if (!above) { normal_ws = -normal_ws; }
+    let normal = normalize((camera.view_matrix * vec4f(normal_ws, 0.0)).xyz);
+    let ior = max(water.ior, 1.0);
+    let limit = min(max(trace.max_distance, 0.1), camera.clip_near_far.y);
+    let nov = clamp(dot(-incident, normal), 0.0, 1.0);
+    let f0 = dielectric_specular_color(ior, 0.0, vec3f(1.0));
+    let fresnel = select(F_Schlick(f0, 1.0, nov).r, 0.0, ior <= 1.00001);
+    let reflection_direction = reflect(incident, normal);
+    let reflection_ws = (camera.view_matrix_inverse * vec4f(reflection_direction, 0.0)).xyz;
+    var reflection = sample_environment_map(tEnvironment, reflection_ws, water.roughness);
+    if (trace.reflections != 0u && above) {
+        let reflected = water_hzb_hit(Ray(origin + reflection_direction * 0.02, reflection_direction, limit), trace.fallback_steps);
+        if (reflected.status == 0u) {
+            let reflected_point = origin + reflection_direction * (reflected.distance + 0.02);
+            let projected = project_position(reflected_point, camera.projection_matrix);
+            // Reflection uses the renderer's usual back-face, thickness, self-hit and
+            // vignette validation. Its two-pixel rule must not reject normal-incidence refraction.
+            let confidence = ffx_sssr_validate_hit(vec3f(reflected.uv, projected.z), uv,
+                reflection_direction, dimensions, max(trace.distance_tolerance, 0.02), 0.05);
+            let radiance = water_receiver_radiance(tScene, tDepth, tNormal, reflected.uv,
+                camera.projection_matrix_inverse, camera.view_matrix_inverse, water.level, false);
+            reflection = mix(reflection, radiance.rgb,
+                confidence * min(radiance.a * 2.0, 1.0) * smoothstep(0.05, 0.5, reflected.distance)
+                * smoothstep(1.0, 4.0, length((reflected.uv - uv) * dimensions)));
+        }
+    }
+    let wave = sin((in.world.x + in.world.z) * water.wave_frequency + water.time * water.wave_speed) * 0.318309886;
+    let water_depth = water.level - sample_terrain_height(in.uv * water.height_uv.zw + water.height_uv.xy);
+    let deep = smoothstep(water.shore_transition.x, max(water.shore_transition.y, water.shore_transition.x + 0.001),
+        water_depth + water.wave_amplitude * wave);
+    let body_color = mix(water.color_shore, water.color_deep, deep);
+    let extinction = water.extinction * max(water.scattering, 0.0);
+    let original = textureLoad(tScene, coord, 0);
+    let valid = receiver_data.w < 16.0 && above && trace.mode != 2u;
+    var confidence = select(0.0, water_refraction_confidence(receiver_data.xy, uv, dimensions,
+        texture_sample_bilinear_uv(visibility_distance, uv, 0u).r), valid);
+    // Mayer's fade selects one UV, rather than crossfading two images of the same edge.
+    let lookup = water_refraction_lookup(uv, receiver_data.xy, confidence);
+    let gathered = water_receiver_radiance(tScene, tDepth, tNormal, lookup,
+        camera.projection_matrix_inverse, camera.view_matrix_inverse, water.level, above);
+    var path = metadata.x;
+    var color = original.rgb;
+    if (confidence > 0.0 && gathered.a > 0.0) {
+        path = min(water_receiver_path(tDepth, tNormal, lookup, camera.projection_matrix_inverse,
+            camera.view_matrix, origin), limit);
+        color = gathered.rgb;
+    } else { confidence = 0.0; }
+    let event = water_event(path, extinction, fresnel, reflection, body_color);
+    let optical = water_transport(event, original.rgb, color, metadata.z);
+    return WaterOptics(vec4f(optical.transmission, metadata.z), vec4f(optical.radiance, confidence),
+        vec4f(optical.background, original.a));
+}
+`, [surface_body, chunk_water_screen_ray, chunk_F_Schlick, chunk_dielectric_specular_color,
+    chunk_ffx_sssr_validate_hit, chunk_sample_environment_map, chunk_texture_sample_bilinear_uv,
+    chunk_water_transport, chunk_water_receiver_radiance, chunk_water_refraction_confidence]);
+
+export const water_shader = ShaderDescriptor.from({ label: "Water / receivers", resources, body });
+export const water_finalize_shader = ShaderDescriptor.from({ label: 'Water / coherent optics', resources: WATER_FINALIZE_RESOURCES, body: finalize_body });
+export const WATER_RESOURCES = resources;
+
+/** Nearest-interface selection writes only water-owned depth and optics, never opaque G-buffer. */
+function water_pipeline(shader, targets, finalize) {
+    const code = shader.source;
+    return RenderPipelineDescriptor.from({
+        label: shader.label,
+        layout: shader.resources.generatePipelineLayout(GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT),
+        vertex: { module: { code }, entryPoint: "vs_main" },
+        fragment: { module: { code }, entryPoint: "fs_main", targets: targets.map(format => ({ format })) },
+        depthStencil: DepthStencilState.from({ format: "depth32float", depthWriteEnabled: !finalize, depthCompare: finalize ? 'equal' : 'greater' }),
+        primitive: { topology: "triangle-list", cullMode: "none" },
+    });
+}
+export function create_water_pipeline() { return water_pipeline(water_shader, ['rgba32float', 'rgba32float'], false); }
+export function create_water_finalize_pipeline() { return water_pipeline(water_finalize_shader, ['rgba32float', 'rgba16float', 'rgba16float'], true); }