@woosh/meep-engine 3.38.0 → 3.39.0

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

@@ -0,0 +1,9 @@
+/**
+ * What water's lighting needs from a medium beyond its coefficients, integrated from the medium's own
+ * phase functions and from the exact Fresnel term rather than tabulated beside them.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_water_medium_derived: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_water_medium_derived.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_water_medium_derived.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/water/medium/chunk_water_medium_derived.js"],"names":[],"mappings":"AAMA;;;;;GAKG;AACH,yCAFU,SAAS,CA4CgF;0BAlDzE,oCAAoC"}

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

@@ -0,0 +1,55 @@
+import { chunk_medium_lobe_phase } from "../../medium/chunk_medium_lobe_phase.js";
+import { MEDIUM_STRUCT } from "../../medium/MEDIUM_STRUCT.js";
+import { chunk_F_dielectric } from "../../shader/chunk/brdf/fresnel/chunk_F_dielectric.js";
+import { PI_DECLARATION } from "../../shader/chunk/math/PI_DECLARATION.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+
+/**
+ * What water's lighting needs from a medium beyond its coefficients, integrated from the medium's own
+ * phase functions and from the exact Fresnel term rather than tabulated beside them.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_water_medium_derived = CodeChunk.from(/* language=WGSL */ `
+const WATER_DERIVE_PANELS: u32 = 64u;
+
+// Simpson weight of node i of WATER_DERIVE_PANELS panels.
+fn water_simpson_weight(i: u32) -> f32 {
+    if (i == 0u || i == WATER_DERIVE_PANELS) { return 1.0; }
+    return select(2.0, 4.0, i % 2u == 1u);
+}
+
+// Fraction of one lobe's scattering sent backwards: the integral of its phase function over the
+// backward hemisphere. That hemisphere holds no forward peak, so Simpson's rule in cos θ over
+// [-1, 0] converges quickly even for a Fournier-Forand lobe.
+fn water_lobe_backscatter_fraction(lobe: MediumPhaseLobe) -> f32 {
+    let h = 1.0 / f32(WATER_DERIVE_PANELS);
+    var sum = 0.0;
+    for (var i = 0u; i <= WATER_DERIVE_PANELS; i++) {
+        let mu = -1.0 + f32(i) * h;
+        sum += water_simpson_weight(i) * medium_lobe_phase(lobe, mu, 0.5 * (1.0 - mu));
+    }
+    return 2.0 * PI * sum * h / 3.0;
+}
+
+// Backscattering coefficient b_b = Σ b_i · B_i of a medium, RGB 1/m.
+fn water_medium_backscattering(medium: ParticipatingMedium) -> vec3<f32> {
+    var result = vec3<f32>(0.0);
+    for (var l = 0u; l < medium.lobe_count; l++) {
+        result += medium.lobes[l].scattering * water_lobe_backscatter_fraction(medium.lobes[l]);
+    }
+    return result;
+}
+
+// Hemispherical Fresnel transmittance into the water for a uniform sky: 2 ∫ (1 − F(μ)) μ dμ over
+// μ in [0, 1], F the exact dielectric reflectance at the given index.
+fn water_diffuse_fresnel_transmittance(ior: f32) -> f32 {
+    let h = 1.0 / f32(WATER_DERIVE_PANELS);
+    var sum = 0.0;
+    for (var i = 0u; i <= WATER_DERIVE_PANELS; i++) {
+        let mu = f32(i) * h;
+        sum += water_simpson_weight(i) * (1.0 - F_dielectric(mu, ior)) * mu;
+    }
+    return 2.0 * sum * h / 3.0;
+}
+`, [MEDIUM_STRUCT.declaration_chunk, chunk_medium_lobe_phase, chunk_F_dielectric, PI_DECLARATION]);

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

@@ -0,0 +1,8 @@
+/**
+ * Total scattering coefficient of a medium, the sum of its lobes', RGB 1/m.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_water_medium_scattering: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_water_medium_scattering.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_water_medium_scattering.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/water/medium/chunk_water_medium_scattering.js"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,4CAFU,SAAS,CAUmB;0BAfZ,oCAAoC"}

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

@@ -0,0 +1,17 @@
+import { MEDIUM_STRUCT } from "../../medium/MEDIUM_STRUCT.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+
+/**
+ * Total scattering coefficient of a medium, the sum of its lobes', RGB 1/m.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_water_medium_scattering = CodeChunk.from(/* language=WGSL */ `
+fn water_medium_scattering(medium: ParticipatingMedium) -> vec3<f32> {
+    var result = vec3<f32>(0.0);
+    for (var l = 0u; l < medium.lobe_count; l++) {
+        result += medium.lobes[l].scattering;
+    }
+    return result;
+}
+`, [MEDIUM_STRUCT.declaration_chunk]);

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

@@ -0,0 +1,8 @@
+/**
+ * Fills the derived fields of every water body from its authored ones, one thread a body.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_water_bodies_derive: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_water_bodies_derive.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_water_bodies_derive.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/water/medium/shader_water_bodies_derive.js"],"names":[],"mappings":"AAWA;;;;GAIG;AACH,yCAFU,aAAa,CAepB;8BA7B2B,+BAA+B"}

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

@@ -0,0 +1,30 @@
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { chunk_water_medium_derived } from "./chunk_water_medium_derived.js";
+import { chunk_water_medium_scattering } from "./chunk_water_medium_scattering.js";
+import { WATER_BODIES_STRUCT, WATER_BODY_CAPACITY } from "./WATER_BODIES_STRUCT.js";
+
+const resources = new ShaderResourceSetDescriptor();
+resources.createGroup()
+    .addStorageBuffer("water_bodies", WATER_BODIES_STRUCT, true);
+
+/**
+ * Fills the derived fields of every water body from its authored ones, one thread a body.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_water_bodies_derive = ComputeShader.from({
+    label: "Water / bodies derive",
+    resources,
+    body: CodeChunk.from(/* language=WGSL */ `
+@compute @workgroup_size(${WATER_BODY_CAPACITY})
+fn main(@builtin(local_invocation_index) i: u32) {
+    if (i >= water_bodies.count) { return; }
+    let medium = water_bodies.bodies[i].medium;
+    water_bodies.bodies[i].backscattering = vec4<f32>(water_medium_backscattering(medium), 0.0);
+    water_bodies.bodies[i].extinction = vec4<f32>(medium.absorption + water_medium_scattering(medium), 0.0);
+    water_bodies.bodies[i].diffuse_transmittance = water_diffuse_fresnel_transmittance(water_bodies.bodies[i].ior);
+}
+`, [chunk_water_medium_derived, chunk_water_medium_scattering]),
+});

package/src/shade/renderer/water/optics/chunk_water_inscatter.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Light the water body sends back towards a viewer above it (WATER_OPTICS_PLAN_2026_10_02.md §4.4):
+ * the column term of Lee et al.'s shallow-water model (1998), with the deep-water reflectance from
+ * QAA (Lee et al. 2002, v6), integrated along the refracted view ray.
+ *
+ * Per channel, with κ = a + b_b and u = b_b / κ:
+ *
+ * - deep-water subsurface remote-sensing reflectance r_rs∞ = (0.089 + 0.1245 u) u, a fit to full
+ *   radiative transfer, so it carries every order of scattering, not one;
+ * - the upwelling light attenuates along the view ray at κ_u = 1.03 √(1 + 2.4 u) κ, Lee's D_u^C κ:
+ *   light scattered forward stays in the upwelling stream, which beam attenuation would throw away;
+ * - each source j — the refracted sun, shadowed by the cascaded shadow map per segment, and the sky the
+ *   active GI mode reports at the surface — feeds the ray r_rs∞ (K_j + κ_u) E_d,j(z) per metre, where
+ *   E_d,j(z) is its plane irradiance at depth decaying at Gordon's K_j. Deep water seen from straight
+ *   above then returns exactly r_rs∞ E_d(0−), and a column of depth H the factor 1 − e^−(K + κ_u) H;
+ * - the upwelling light the surface reflects back down returns again: 1 / (1 − 1.7 r_rs∞).
+ *
+ * The medium's phase functions enter through b_b, which the bodies table integrates from them on the
+ * GPU. The model is gated against the Monte Carlo slab oracle (`water_inscatter_oracle.spec.js`).
+ *
+ * Expects `light_data` and the shadow atlas bindings, and a `water_gi_irradiance` from one of the GI
+ * modules. Returns radiance arriving at the surface from below; the caller takes it out of the water.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_water_inscatter: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_water_inscatter.d.ts.map

package/src/shade/renderer/water/optics/chunk_water_inscatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_water_inscatter.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/water/optics/chunk_water_inscatter.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,oCAFU,SAAS,CAuFmF;0BAnH5E,oCAAoC"}

package/src/shade/renderer/water/optics/chunk_water_inscatter.js

@@ -0,0 +1,123 @@
+import { PI_DECLARATION } from "../../shader/chunk/math/PI_DECLARATION.js";
+import {
+    chunk_directional_lights_iteration_mask
+} from "../../shader/chunk/light/io/chunk_directional_lights_iteration_mask.js";
+import {
+    chunk_get_directional_light_info_by_index
+} from "../../shader/chunk/light/io/chunk_get_directional_light_info_by_index.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { chunk_shadowmap_get_light_visibility } from "../../shadow/map/shader/chunk_shadowmap_get_light_visibility.js";
+import { WATER_BODY_STRUCT } from "../medium/WATER_BODIES_STRUCT.js";
+import { chunk_water_optics } from "./chunk_water_optics.js";
+
+/**
+ * Light the water body sends back towards a viewer above it (WATER_OPTICS_PLAN_2026_10_02.md §4.4):
+ * the column term of Lee et al.'s shallow-water model (1998), with the deep-water reflectance from
+ * QAA (Lee et al. 2002, v6), integrated along the refracted view ray.
+ *
+ * Per channel, with κ = a + b_b and u = b_b / κ:
+ *
+ * - deep-water subsurface remote-sensing reflectance r_rs∞ = (0.089 + 0.1245 u) u, a fit to full
+ *   radiative transfer, so it carries every order of scattering, not one;
+ * - the upwelling light attenuates along the view ray at κ_u = 1.03 √(1 + 2.4 u) κ, Lee's D_u^C κ:
+ *   light scattered forward stays in the upwelling stream, which beam attenuation would throw away;
+ * - each source j — the refracted sun, shadowed by the cascaded shadow map per segment, and the sky the
+ *   active GI mode reports at the surface — feeds the ray r_rs∞ (K_j + κ_u) E_d,j(z) per metre, where
+ *   E_d,j(z) is its plane irradiance at depth decaying at Gordon's K_j. Deep water seen from straight
+ *   above then returns exactly r_rs∞ E_d(0−), and a column of depth H the factor 1 − e^−(K + κ_u) H;
+ * - the upwelling light the surface reflects back down returns again: 1 / (1 − 1.7 r_rs∞).
+ *
+ * The medium's phase functions enter through b_b, which the bodies table integrates from them on the
+ * GPU. The model is gated against the Monte Carlo slab oracle (`water_inscatter_oracle.spec.js`).
+ *
+ * Expects `light_data` and the shadow atlas bindings, and a `water_gi_irradiance` from one of the GI
+ * modules. Returns radiance arriving at the surface from below; the caller takes it out of the water.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_water_inscatter = CodeChunk.from(/* language=WGSL */ `
+// QAA's deep-water subsurface remote-sensing reflectance, per channel, sr^-1.
+fn water_deep_reflectance(absorption: vec3<f32>, backscattering: vec3<f32>) -> vec3<f32> {
+    let u = backscattering / max(absorption + backscattering, vec3<f32>(1e-20));
+    return (0.089 + 0.1245 * u) * u;
+}
+
+// Lee's attenuation of the upwelling light along a view ray, per metre of ray, RGB 1/m.
+fn water_upwelling_attenuation(absorption: vec3<f32>, backscattering: vec3<f32>) -> vec3<f32> {
+    let kappa = absorption + backscattering;
+    let u = backscattering / max(kappa, vec3<f32>(1e-20));
+    return 1.03 * sqrt(1.0 + 2.4 * u) * kappa;
+}
+
+// Radiance the water column sends back up the refracted view ray, arriving at the surface from
+// below, for a ray leaving the surface point origin in direction (both world space, direction
+// pointing down into the water) over path metres, in segments steps.
+//
+// Segment boundaries are spaced evenly in the mean upwelling transmittance, so the near-surface water
+// that carries most of the light gets most of the steps; within a segment each source's decay with
+// depth is integrated in closed form and the sun's shadow taken at its middle.
+fn water_inscatter(body: WaterBody, origin: vec3<f32>, direction: vec3<f32>, path: f32, segments: u32) -> vec3<f32> {
+    let absorption = body.medium.absorption;
+    let backscattering = body.backscattering.xyz;
+    let reflectance = water_deep_reflectance(absorption, backscattering);
+    let upwelling = water_upwelling_attenuation(absorption, backscattering);
+    let up = vec3<f32>(0.0, 1.0, 0.0);
+    let toward_camera = -direction;
+    // depth grows by mu metres per metre of ray
+    let mu = max(-direction.y, 0.0);
+
+    let sky = water_gi_irradiance(origin, up);
+    let sky_decay = water_diffuse_attenuation(absorption, backscattering, WATER_SKY_DISTRIBUTION);
+    let sky_source = reflectance * (sky_decay + upwelling) * sky;
+
+    let mean_upwelling = (upwelling.x + upwelling.y + upwelling.z) / 3.0;
+    let thin = mean_upwelling * path < 1e-4;
+    let span = 1.0 - exp(-mean_upwelling * path);
+
+    var result = vec3<f32>(0.0);
+    var start = 0.0;
+
+    for (var i = 0u; i < segments; i++) {
+        let u = f32(i + 1u) / f32(segments);
+        let end = select(-log(1.0 - u * span) / max(mean_upwelling, 1e-20), u * path, thin);
+        let length = max(end - start, 0.0);
+        let depth = mu * start;
+        let transmittance = exp(-upwelling * start);
+
+        result += transmittance * water_inscatter_segment(
+            sky_source * water_sky_transmittance(depth, body.diffuse_transmittance, absorption, backscattering),
+            upwelling, sky_decay, mu, length);
+
+        let middle = origin + direction * (start + 0.5 * length);
+
+        var directional_bits = directional_lights_iteration_mask(&light_data);
+        while (directional_bits != 0u) {
+            let index = countTrailingZeros(directional_bits);
+            directional_bits &= ~(1u << index);
+
+            let sun = get_directional_light_info_by_index(&light_data, index);
+
+            // sun.direction points towards the light; below the horizon it does not reach the water
+            if (sun.direction.y <= 0.0) { continue; }
+
+            let cos_water = water_refracted_cosine(sun.direction.y, body.ior);
+            let visibility = shadowmap_get_directional_light_visibility(&light_data, index, middle,
+                toward_camera, sun.direction);
+            let decay = water_diffuse_attenuation(absorption, backscattering, 1.0 / max(cos_water, 1e-4));
+            // plane irradiance under the surface: the normal irradiance of the refracted beam times cos θ_w
+            let irradiance = sun.color * water_sun_transmittance(depth, sun.direction.y, body.ior,
+                absorption, backscattering) * cos_water;
+
+            result += transmittance * water_inscatter_segment(
+                reflectance * (decay + upwelling) * irradiance * visibility,
+                upwelling, decay, mu, length);
+        }
+
+        start = end;
+    }
+
+    // what the surface reflects back down returns again
+    return result / (1.0 - 1.7 * reflectance);
+}
+`, [WATER_BODY_STRUCT.declaration_chunk, chunk_water_optics, chunk_directional_lights_iteration_mask,
+    chunk_get_directional_light_info_by_index, chunk_shadowmap_get_light_visibility, PI_DECLARATION]);

package/src/shade/renderer/water/optics/chunk_water_light_transmittance.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Light reaching a submerged point (WATER_OPTICS_PLAN_2026_10_02.md §4.3): one chunk every pass that
+ * lights a surface or a froxel links, so a floor, a fish and a particle under the same water agree.
+ *
+ * - `water_submersion(position)` finds the body a point is under, its depth below that body's local
+ *   surface, and the shore coverage that fades thin water in without a step.
+ * - `water_refract_directional_light(&light, submersion)` turns the sun into the one a submerged
+ *   point receives: refracted at the surface, so steeper, and attenuated by Gordon's diffuse
+ *   attenuation along the refracted path.
+ * - `water_ambient_transmittance(submersion)` is what the water passes of the sky's diffuse light,
+ *   for the indirect lighting of a submerged point.
+ * - `water_local_light_transmittance(submersion, direction, distance)` is a lamp's light through the
+ *   water between it and the point.
+ *
+ * Expects `water_bodies` (the uniform {@link WATER_BODIES_STRUCT}) and `water_heights` (the bodies'
+ * surface height maps as a `texture_2d_array<f32>`, one layer a body). With no water the table is
+ * empty and every function returns at its first test.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_water_light_transmittance: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_water_light_transmittance.d.ts.map

package/src/shade/renderer/water/optics/chunk_water_light_transmittance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_water_light_transmittance.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/water/optics/chunk_water_light_transmittance.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,8CAFU,SAAS,CAuHsF;0BA7I/E,oCAAoC"}

package/src/shade/renderer/water/optics/chunk_water_light_transmittance_dry.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The dry twin of {@link chunk_water_light_transmittance}: the same functions, for a scene with no
+ * water, where every point is dry and every light passes untouched.
+ *
+ * A pass that lights surfaces links one of the two, chosen on the CPU by whether the scene has a
+ * water body this frame. The water functions are inlined into the shading loops, and the compiler
+ * budgets registers for them whether or not a body exists to take the branch; this twin compiles them
+ * out, so a dry scene pays nothing for water. Measured on the deferred shading pass with an empty
+ * water table: 186 µs with the water module linked, 170 µs with this one (RTX 4090, the water
+ * playground).
+ *
+ * Reads no bindings; a pass may still declare the water ones, which go unused.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_water_light_transmittance_dry: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_water_light_transmittance_dry.d.ts.map

package/src/shade/renderer/water/optics/chunk_water_light_transmittance_dry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_water_light_transmittance_dry.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/water/optics/chunk_water_light_transmittance_dry.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;GAcG;AACH,kDAFU,SAAS,CAyB2B;0BAxCpB,oCAAoC"}

package/src/shade/renderer/water/optics/chunk_water_optics.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Light in a body of water: the shared pieces every consumer of the water medium uses — deferred
+ * and forward lighting of submerged surfaces, the froxel lighting, and the water's own in-scatter
+ * (WATER_OPTICS_PLAN_2026_10_02.md §4).
+ *
+ * Coefficients are RGB in 1/m: `absorption` a, `backscattering` b_b. Depths and lengths are metres.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_water_optics: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_water_optics.d.ts.map

package/src/shade/renderer/water/optics/chunk_water_optics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_water_optics.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/water/optics/chunk_water_optics.js"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AACH,iCAFU,SAAS,CAgEM;0BA1EC,oCAAoC"}

package/src/shade/renderer/water/optics/chunk_water_optics.js

@@ -0,0 +1,75 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { chunk_F_dielectric } from "../../shader/chunk/brdf/fresnel/chunk_F_dielectric.js";
+
+/**
+ * Light in a body of water: the shared pieces every consumer of the water medium uses — deferred
+ * and forward lighting of submerged surfaces, the froxel lighting, and the water's own in-scatter
+ * (WATER_OPTICS_PLAN_2026_10_02.md §4).
+ *
+ * Coefficients are RGB in 1/m: `absorption` a, `backscattering` b_b. Depths and lengths are metres.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_water_optics = CodeChunk.from(/* language=WGSL */ `
+// Gordon 1989: K/D0 = 1.0395 (a + b_b). D0 is the downwelling distribution function: 1 / cos of
+// the refracted solar zenith for a direct sun, 1.197 for an overcast sky.
+const WATER_GORDON_K: f32 = 1.0395;
+const WATER_SKY_DISTRIBUTION: f32 = 1.197;
+
+// The integral of e^(−x t) over t in [0, length]: (1 − e^(−x·length)) / x, per channel. Stable as
+// x → 0, where it tends to length, and right for x < 0 too, which a view looking up through light
+// decaying with depth produces.
+fn water_segment_integral(x: vec3<f32>, length: f32) -> vec3<f32> {
+    let y = x * length;
+    let series = length * (1.0 - y * 0.5 + y * y / 6.0);
+    let closed = (1.0 - exp(-y)) / select(x, vec3<f32>(1.0), x == vec3<f32>(0.0));
+    return select(closed, series, abs(y) < vec3<f32>(1e-3));
+}
+
+// Diffuse attenuation coefficient K_d for the given downwelling distribution function D0.
+fn water_diffuse_attenuation(absorption: vec3<f32>, backscattering: vec3<f32>, distribution: f32) -> vec3<f32> {
+    return WATER_GORDON_K * (absorption + backscattering) * distribution;
+}
+
+// Cosine of the refracted zenith under the surface, for a direction cos_air from the zenith above it.
+fn water_refracted_cosine(cos_air: f32, ior: f32) -> f32 {
+    let sin2_water = max(0.0, 1.0 - cos_air * cos_air) / (ior * ior);
+    return sqrt(max(0.0, 1.0 - sin2_water));
+}
+
+// What the sun's light is multiplied by at depth metres under a flat surface, for shading with the
+// REFRACTED sun direction. Fresnel transmittance into the water, the beam's compression
+// cos θ_air / cos θ_water (its plane irradiance is unchanged by refraction, its normal irradiance is
+// not), and Gordon's attenuation along the refracted slant path.
+fn water_sun_transmittance(depth: f32, cos_sun_air: f32, ior: f32, absorption: vec3<f32>,
+    backscattering: vec3<f32>) -> vec3<f32> {
+    let cos_air = clamp(cos_sun_air, 0.0, 1.0);
+    let cos_water = max(water_refracted_cosine(cos_air, ior), 1e-4);
+    let transmitted = 1.0 - F_dielectric(cos_air, ior);
+    let k = water_diffuse_attenuation(absorption, backscattering, 1.0 / cos_water);
+    return transmitted * (cos_air / cos_water) * exp(-k * max(depth, 0.0));
+}
+
+// What the sky's diffuse light is multiplied by at depth metres: the hemispherical Fresnel
+// transmittance of a uniform sky, and Gordon's attenuation with an overcast distribution function.
+fn water_sky_transmittance(depth: f32, diffuse_transmittance: f32, absorption: vec3<f32>,
+    backscattering: vec3<f32>) -> vec3<f32> {
+    let k = water_diffuse_attenuation(absorption, backscattering, WATER_SKY_DISTRIBUTION);
+    return diffuse_transmittance * exp(-k * max(depth, 0.0));
+}
+
+// Radiance leaving the water towards a viewer cos_view_air from the normal above it, per unit of
+// radiance arriving at the surface from below: Fresnel transmittance and the n² law. Radiance divided
+// by n² is what refraction conserves, so crossing into the thinner medium divides by n².
+fn water_exit_factor(cos_view_air: f32, ior: f32) -> f32 {
+    return (1.0 - F_dielectric(clamp(cos_view_air, 0.0, 1.0), ior)) / (ior * ior);
+}
+
+// One segment of single scattering along the refracted view ray, from its start t_i to t_i + length:
+// the source there (σ_s·phase·irradiance, per metre) decays with depth at rate decay, depth grows at
+// mu metres per metre of ray, and the view is attenuated at beam. Returns the radiance the segment
+// sends back to its start; multiply by the transmittance from the surface to the start.
+fn water_inscatter_segment(source: vec3<f32>, beam: vec3<f32>, decay: vec3<f32>, mu: f32, length: f32) -> vec3<f32> {
+    return source * water_segment_integral(beam + decay * mu, length);
+}
+`, [chunk_F_dielectric]);

package/src/shade/renderer/water/optics/chunk_water_receiver_downwelling.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Light reaching a submerged receiver (WATER_OPTICS_PLAN_2026_10_02.md §4.3), applied by the water
+ * optics pass to the receiver it sees through the surface. Surface shading stays unaware of water:
+ * the opaque scene is shaded dry, and the water scales what it sees of a receiver by how much of the
+ * light that receiver was shaded with survives the water above it.
+ *
+ * The ratio is of the receiver's irradiance under the water to its irradiance dry, from what the
+ * water pass can rebuild at the receiver — its position, G-buffer normal and depth below the
+ * surface, the shadow map and the GI mode:
+ *
+ * - dry: each directional light × its shadow × n·l, plus the GI mode's irradiance on n;
+ * - wet: each light refracted at the surface, so steeper, with the Fresnel transmittance, the beam's
+ *   compression and Gordon's attenuation along its refracted path (water_sun_transmittance) × its
+ *   shadow × n·l_refracted, plus the GI irradiance through the diffuse transmittance and the overcast
+ *   attenuation (water_sky_transmittance).
+ *
+ * Stated limits: light the receiver had from lamps and its own emission is scaled by the same ratio,
+ * and a highlight keeps its dry direction, scaled.
+ *
+ * Expects `light_data` and the shadow atlas bindings, and a `water_gi_irradiance` from one of the GI
+ * modules.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_water_receiver_downwelling: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_water_receiver_downwelling.d.ts.map

package/src/shade/renderer/water/optics/chunk_water_receiver_downwelling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_water_receiver_downwelling.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/water/optics/chunk_water_receiver_downwelling.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,+CAFU,SAAS,CAwCmE;0BAnE5D,oCAAoC"}

package/src/shade/renderer/water/optics/chunk_water_receiver_downwelling.js

@@ -0,0 +1,74 @@
+import {
+    chunk_directional_lights_iteration_mask
+} from "../../shader/chunk/light/io/chunk_directional_lights_iteration_mask.js";
+import {
+    chunk_get_directional_light_info_by_index
+} from "../../shader/chunk/light/io/chunk_get_directional_light_info_by_index.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { chunk_shadowmap_get_light_visibility } from "../../shadow/map/shader/chunk_shadowmap_get_light_visibility.js";
+import { WATER_BODY_STRUCT } from "../medium/WATER_BODIES_STRUCT.js";
+import { chunk_water_optics } from "./chunk_water_optics.js";
+
+/**
+ * Light reaching a submerged receiver (WATER_OPTICS_PLAN_2026_10_02.md §4.3), applied by the water
+ * optics pass to the receiver it sees through the surface. Surface shading stays unaware of water:
+ * the opaque scene is shaded dry, and the water scales what it sees of a receiver by how much of the
+ * light that receiver was shaded with survives the water above it.
+ *
+ * The ratio is of the receiver's irradiance under the water to its irradiance dry, from what the
+ * water pass can rebuild at the receiver — its position, G-buffer normal and depth below the
+ * surface, the shadow map and the GI mode:
+ *
+ * - dry: each directional light × its shadow × n·l, plus the GI mode's irradiance on n;
+ * - wet: each light refracted at the surface, so steeper, with the Fresnel transmittance, the beam's
+ *   compression and Gordon's attenuation along its refracted path (water_sun_transmittance) × its
+ *   shadow × n·l_refracted, plus the GI irradiance through the diffuse transmittance and the overcast
+ *   attenuation (water_sky_transmittance).
+ *
+ * Stated limits: light the receiver had from lamps and its own emission is scaled by the same ratio,
+ * and a highlight keeps its dry direction, scaled.
+ *
+ * Expects `light_data` and the shadow atlas bindings, and a `water_gi_irradiance` from one of the GI
+ * modules.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_water_receiver_downwelling = CodeChunk.from(/* language=WGSL */ `
+// What survives of a submerged receiver's light, per channel, in [0, 1]. receiver and normal are world
+// space, depth the metres of water above the receiver, toward_camera a unit vector from the receiver
+// towards the camera (the shadow lookup's cascade blend).
+fn water_receiver_downwelling(body: WaterBody, receiver: vec3<f32>, normal: vec3<f32>, depth: f32,
+    toward_camera: vec3<f32>) -> vec3<f32> {
+    let absorption = body.medium.absorption;
+    let backscattering = body.backscattering.xyz;
+    let up = vec3<f32>(0.0, 1.0, 0.0);
+
+    let sky = water_gi_irradiance(receiver, normal);
+    var dry = sky;
+    var wet = sky * water_sky_transmittance(depth, body.diffuse_transmittance, absorption, backscattering);
+
+    var directional_bits = directional_lights_iteration_mask(&light_data);
+    while (directional_bits != 0u) {
+        let index = countTrailingZeros(directional_bits);
+        directional_bits &= ~(1u << index);
+
+        let sun = get_directional_light_info_by_index(&light_data, index);
+
+        // sun.direction points towards the light; below the horizon it lights neither
+        if (sun.direction.y <= 0.0) { continue; }
+
+        let visibility = shadowmap_get_directional_light_visibility(&light_data, index, receiver,
+            toward_camera, normal);
+        let refracted = -refract(-sun.direction, up, 1.0 / body.ior);
+
+        dry += sun.color * visibility * max(dot(normal, sun.direction), 0.0);
+        wet += sun.color * visibility * max(dot(normal, refracted), 0.0)
+            * water_sun_transmittance(depth, sun.direction.y, body.ior, absorption, backscattering);
+    }
+
+    // a channel nothing lit dry has nothing for the water to take
+    return select(clamp(wet / max(dry, vec3<f32>(1e-30)), vec3<f32>(0.0), vec3<f32>(1.0)), vec3<f32>(1.0),
+        dry <= vec3<f32>(0.0));
+}
+`, [WATER_BODY_STRUCT.declaration_chunk, chunk_water_optics, chunk_directional_lights_iteration_mask,
+    chunk_get_directional_light_info_by_index, chunk_shadowmap_get_light_visibility]);

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

@@ -1,12 +1,18 @@
 export function create_water_pipeline(): RenderPipelineDescriptor;
-export function create_water_finalize_pipeline(): RenderPipelineDescriptor;
+export function create_water_finalize_pipeline_ibl(): RenderPipelineDescriptor;
+export function create_water_finalize_pipeline_brick4(): RenderPipelineDescriptor;
 export const WATER_DRAW_STRUCT: WebGPUStruct;
 export const WATER_TRACE_STRUCT: WebGPUStruct;
-export const WATER_FINALIZE_RESOURCES: ShaderResourceSetDescriptor;
-export const water_transport_fallback: CodeChunk;
+/** Optics under IBL (and LPV, which has no transparent variant): the lights and the environment. */
+export const WATER_FINALIZE_RESOURCES_IBL: ShaderResourceSetDescriptor;
+/** Optics under Brick4: the lights, and the light map with the view its sampling jitters by. */
+export const WATER_FINALIZE_RESOURCES_BRICK4: ShaderResourceSetDescriptor;
 export const chunk_water_screen_ray: CodeChunk;
 export const water_shader: ShaderDescriptor;
-export const water_finalize_shader: ShaderDescriptor;
+/** The optics pass under IBL, and under LPV, which has no transparent variant. */
+export const water_finalize_shader_ibl: ShaderDescriptor;
+/** The optics pass under Brick4. */
+export const water_finalize_shader_brick4: ShaderDescriptor;
 export const WATER_RESOURCES: ShaderResourceSetDescriptor;
 import { RenderPipelineDescriptor } from "../../descriptor/pipeline/render/RenderPipelineDescriptor.js";
 import { WebGPUStruct } from "../shader/type/WebGPUStruct.js";

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

@@ -1 +1 @@
-{"version":3,"file":"shader_water.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/water/shader_water.js"],"names":[],"mappings":"AA8XA,kEAAuH;AACvH,2EAAuJ;AA3WvJ,6CAKuB;AAEvB,8CAGwB;AAmBxB,mEAA8D;AAE9D,iDAIG;AAsCH,+CAmGoH;AA8KpH,4CAAmG;AACnG,qDAA2J;AAC3J,0DAAyC;yCA9WA,8DAA8D;6BAe1E,gCAAgC;4CAHjB,mDAAmD;0BADrE,iCAAiC;iCAE1B,+BAA+B"}
+{"version":3,"file":"shader_water.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/water/shader_water.js"],"names":[],"mappings":"AAmZA,kEAAuH;AACvH,+EAA+J;AAC/J,kFAAqK;AArXrK,6CAOuB;AAEvB,8CAKwB;AAsBxB,oGAAoG;AACpG,uEAAkE;AAGlE,gGAAgG;AAChG,0EAAqE;AAkDrE,+CA+EmB;AAoLnB,4CAAmG;AACnG,kFAAkF;AAClF,yDAC8G;AAC9G,oCAAoC;AACpC,4DACoH;AACpH,0DAAyC;yCAnYA,8DAA8D;6BAmB1E,gCAAgC;4CAJjB,mDAAmD;0BADrE,iCAAiC;iCAE1B,+BAA+B"}