@woosh/meep-engine 3.37.0 → 3.39.0

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

@@ -0,0 +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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,105 @@
+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 {
+    return mix(original, receiver, clamp(confidence, 0.0, 1.0));
+}
+fn water_refraction_confidence(uv: vec2f, original_uv: vec2f, size: vec2f, distance_tiles: f32) -> f32 {
+    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);
+    // 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(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 }
+// 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 = mix(vec3f(1.0), event.transmission, a);
+    let w = a * event.radiance;
+    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. 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 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 = 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 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;
+        }
+    }
+    return vec4f(color / max(weight, 1e-20), weight);
+}
+`, [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");

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