@woosh/meep-engine 3.37.0 → 3.39.0

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,33 +1,22 @@
-/**
- * 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 }?: {
-    color_format?: string;
-}): RenderPipelineDescriptor;
-/**
- * One water surface. Small, and rewritten per surface per frame rather than tabled — a level has a
- * handful of these, not thousands.
- */
+export function create_water_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;
+/** 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;
-/**
- * The pipeline's resource set, for building bind groups.
- *
- * @type {ShaderResourceSetDescriptor}
- */
+/** 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";
-import { ShaderDescriptor } from "../shader/ShaderDescriptor.js";
 import { ShaderResourceSetDescriptor } from "../shader/resource/ShaderResourceSetDescriptor.js";
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+import { ShaderDescriptor } from "../shader/ShaderDescriptor.js";
 //# sourceMappingURL=shader_water.d.ts.map

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":"AAiNA;;;;;;;;;;;;GAYG;AACH;IAH4B,YAAY,GAA7B,MAAM;IACJ,wBAAwB,CAkBpC;AAnOD;;;GAGG;AACH,6CAuCuB;AAwIvB,4CAIG;AA8CH;;;;GAIG;AACH,8BAFU,2BAA2B,CAEI;yCAnPA,8DAA8D;6BAO1E,gCAAgC;iCAF5B,+BAA+B;4CADpB,mDAAmD"}
+{"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"}