@woosh/meep-engine 3.38.0 → 3.40.0

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

@@ -0,0 +1,124 @@
+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 into the water) over path metres, in segments steps. up is the authored/displaced
+// interface normal; the column model uses its local tangent plane along this ray.
+//
+// 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>, up: 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 toward_camera = -direction;
+    // depth grows by mu metres per metre of ray
+    let mu = max(-dot(direction, up), 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
+            let cosine = dot(sun.direction, up);
+            if (cosine <= 0.0) { continue; }
+
+            let cos_water = water_refracted_cosine(cosine, 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, cosine, 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_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,CAyCmE;0BApE5D,oCAAoC"}

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

@@ -0,0 +1,75 @@
+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, up the surface's outward normal, depth the normal distance below its tangent plane,
+// 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>, up: vec3<f32>, depth: f32,
+    toward_camera: vec3<f32>) -> vec3<f32> {
+    let absorption = body.medium.absorption;
+    let backscattering = body.backscattering.xyz;
+
+    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
+        let cosine = dot(sun.direction, up);
+        if (cosine <= 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, cosine, 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 const WATER_DRAW_STRUCT: WebGPUStruct;
+export function create_water_finalize_pipeline_ibl(): RenderPipelineDescriptor;
+export function create_water_finalize_pipeline_brick4(): RenderPipelineDescriptor;
+export const WATER_GRID_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":"AAueA,kEAAuH;AACvH,+EAA+J;AAC/J,kFAAqK;AAlcrK,6CAAqF;AAErF,8CAKwB;AA0BxB,oGAAoG;AACpG,uEAAkE;AAGlE,gGAAgG;AAChG,0EAAqE;AAkHrE,+CA+EmB;AA2LnB,4CAAmG;AACnG,kFAAkF;AAClF,yDAC8G;AAC9G,oCAAoC;AACpC,4DACoH;AACpH,0DAAyC;yCA9cA,8DAA8D;6BAmB1E,gCAAgC;4CAJjB,mDAAmD;0BADrE,iCAAiC;iCAE1B,+BAA+B"}