@zephyr3d/scene 0.9.26 → 0.9.27

package/dist/render/water_caustics.js

@@ -0,0 +1,1380 @@
+import { Vector4, Vector3, Matrix4x4, REVERSE_Z } from '@zephyr3d/base';
+import { drawFullscreenQuad } from './fullscreenquad.js';
+import { fetchSampler } from '../utility/misc.js';
+import { MAX_CAUSTIC_WATERS, ShaderHelper, CAUSTIC_HEIGHT_BIAS } from '../material/shader/helper.js';
+
+/** Index of refraction of water relative to air. */ const WATER_IOR = 1.333;
+/** Air-to-water eta used when refracting the sun ray at the surface. */ const WATER_ETA = 1 / WATER_IOR;
+/**
+ * Minimum |sin(sun elevation)| for caustics to be generated. The photon sweep
+ * degenerates below this, and real caustics vanish there too, so the pass
+ * simply switches off.
+ */ const MIN_SUN_ELEVATION = 0.15;
+/**
+ * Fixed-point steps taken to land a photon on the scene rather than on the
+ * focal plane. Two suffice for a receiver flat over the distance the guess
+ * moves; the third covers a steep slope. Beyond that the sequence has either
+ * converged or is oscillating between two surfaces.
+ */ const SCENE_DEPTH_ITERATIONS = 3;
+/**
+ * Photons per covered map texel the automatic grid size solves for.
+ *
+ * Measured against a converged (16x denser) map: four lands within about 4% of
+ * it, for a quarter of the photons full convergence would need.
+ */ const PHOTONS_PER_TEXEL = 4;
+/** Automatic edge fade width, as a fraction of the map half-extent. */ const AUTO_FADE_FRACTION = 0.2;
+/** Floor in meters under the automatic fade width. */ const AUTO_FADE_MIN_DISTANCE = 3;
+/** Bounds on the share of the map half-extent the fade may consume. */ const MIN_FADE_FRACTION = 0.001;
+const MAX_FADE_FRACTION = 0.9;
+/**
+ * Largest ratio between the fitted slice's two half-extents. The map is square,
+ * so an anisotropic slice resolves the pattern at different frequencies along
+ * each axis.
+ */ const MAX_SLICE_ASPECT = 2;
+/**
+ * Steps per octave the fitted half-extents are quantised to. Four costs at most
+ * 19% of linear resolution against a perfect fit, and keeps a level change small
+ * enough to pass as a slight change in sharpness rather than a pop.
+ */ const SLICE_QUANTISE_STEPS = 4;
+/** Smallest half-extent in meters a fitted slice may shrink to. */ const MIN_SLICE_EXTENT = 0.5;
+/**
+ * Divisions of the half-extent the slice centre snaps to under a warp.
+ *
+ * A whole-texel shift is exact only on a linear map; under a warp it is a
+ * different number of texels at each position, so the map has to be resampled
+ * whenever the centre moves. Snapping coarsely holds the centre still for many
+ * frames and pays for one resample, which the resolve's neighbourhood clamp
+ * absorbs.
+ */ const WARPED_CENTER_SNAP_DIVISIONS = 8;
+/**
+ * How far past the map border the photon grid is laid out, as a fraction of the
+ * half-extent, on the sides where the range - not the water - is what bounds it.
+ *
+ * Horizontal displacement carries a photon across the border in either
+ * direction, so a grid cut exactly at the border loses the photons that would
+ * have arrived from outside while still losing the ones that leave; the border
+ * ring then holds a density no interior texel does. Launching from a margin
+ * outside feeds the border from both sides.
+ *
+ * Only the launch area grows - `_gridFraction` scales the per-photon weight and
+ * the solved grid size by it - so density per texel is unchanged and the cost is
+ * photon count. At the default warp this margin buys about 11% more photons.
+ */ const GRID_BORDER_MARGIN = 0.15;
+/**
+ * Concentrates a map coordinate towards the centre. CPU twin of
+ * `ShaderHelper.warpCausticNDC`; see it for the reasoning.
+ *
+ * @internal
+ */ function warpCausticNDC(ndc, strength) {
+    return ndc * (1 + strength) / (1 + strength * Math.abs(ndc));
+}
+/**
+ * Rounds a fitted half-extent up onto a discrete ladder below `range`.
+ *
+ * The ladder is geometric and anchored at `range`, so water that fills the range
+ * lands exactly on a level.
+ *
+ * @internal
+ */ function quantiseSliceExtent(half, range) {
+    if (!(half > 0) || half >= range) {
+        return range;
+    }
+    const steps = Math.floor(Math.log2(range / half) * SLICE_QUANTISE_STEPS);
+    return range / Math.pow(2, steps / SLICE_QUANTISE_STEPS);
+}
+/**
+ * Vertices per side of the grid the height map rasterises the surface with.
+ *
+ * Laid out in warped map space over the body's footprint, so each cell covers a
+ * few map texels at most and the linear height across a cell is well inside what
+ * a wave of any visible wavelength needs.
+ */ const HEIGHT_GRID_SIZE = 256;
+/**
+ * Shader for the photon splat pass.
+ *
+ * Everything happens in the vertex stage: one vertex is one photon, and the
+ * position it emits is where that photon lands. The fragment stage only deposits
+ * the weight, which additive blending accumulates.
+ *
+ * Returned as a descriptor rather than a built program so it can be compiled
+ * against a bare {@link ProgramBuilder} in tests, without a device.
+ *
+ * @param waveGenerator - Supplies the surface displacement and normal.
+ * @internal
+ */ function createCausticSplatShader(waveGenerator, sceneDepth) {
+    const setupUniforms = (scope)=>{
+        const pb = scope.$builder;
+        scope.causticFrameX = pb.vec4().uniform(0);
+        scope.causticFrameY = pb.vec4().uniform(0);
+        scope.causticCenter = pb.vec4().uniform(0);
+        scope.causticLightDir = pb.vec4().uniform(0);
+        scope.causticRegion = pb.vec4().uniform(0);
+        /** Map-NDC rectangle the photon grid is laid out over: (minX, minY, maxX, maxY). */ scope.causticGridBounds = pb.vec4().uniform(0);
+        scope.causticSplatParams = pb.vec4().uniform(0);
+        /** (grid size, 1 / grid size, 0, 0) */ scope.causticPhotonParams = pb.vec4().uniform(0);
+        if (sceneDepth) {
+            // The sun's own shadow cascade, reused as a light-space depth map of the
+            // scene: already orthographic, along the light, covering what the light
+            // reaches, and costing no extra geometry pass.
+            scope.causticSceneMatrix = pb.mat4().uniform(0);
+            scope.causticSceneMatrixInv = pb.mat4().uniform(0);
+            /** (cascade layer, 0, 0, 0) */ scope.causticSceneParams = pb.vec4().uniform(0);
+            // Sampled for its stored depth, not compared against a reference, so this
+            // takes an ordinary sampler rather than the comparison one the lighting
+            // pass binds to the same texture.
+            scope.causticSceneDepth = pb.tex2DArrayShadow().uniform(0);
+        }
+        // FBM and Gerstner animate from camera.elapsedTime, which this pass has to
+        // supply itself - it is not one of the engine's camera passes.
+        ShaderHelper.declareStandaloneCameraTime(scope, 0);
+        waveGenerator.setupUniforms(scope, 0);
+    };
+    return {
+        vertex (pb) {
+            // Photon ordinal, one vertex per photon. The grid coordinate is derived
+            // from it here rather than stored, so the buffer outlives any one grid
+            // size - see _updatePhotonLayout.
+            this.$inputs.photonIndex = pb.float().attrib('position');
+            this.$outputs.photonWeight = pb.float();
+            setupUniforms(this);
+            pb.main(function() {
+                // Per-axis: the slice is fitted to the water, so its two half-extents
+                // are independent and the map is only square in texels.
+                this.$l.invRadius = pb.vec2(this.causticFrameX.w, this.causticFrameY.w);
+                this.$l.radius = pb.div(pb.vec2(1), this.invRadius);
+                this.$l.focalDepth = this.causticSplatParams.y;
+                this.$l.eta = this.causticSplatParams.z;
+                this.$l.L = this.causticLightDir.xyz;
+                this.$l.waterLevel = this.causticCenter.w;
+                // Grid position on the orthographic slice through the map centre.
+                //
+                // The grid spans only the part of the slice the water can actually cast
+                // through, not the whole map: spread over the whole map, a pool covering
+                // a tenth of it would leave most of the lit area with no photon at all,
+                // and a caustic value of zero puts the sun out.
+                //
+                // Laid out in warped map space and unwarped to reach the plane, so the
+                // grid is uniform in texels rather than in meters. That is what keeps
+                // photon (i,j) on texel (i,j) for calm water under any warp strength,
+                // and with it the map's normalisation to 1.0.
+                //
+                // Ordinal to grid coordinate: row is the quotient, column the remainder.
+                this.$l.gridSize = this.causticPhotonParams.x;
+                this.$l.invGrid = this.causticPhotonParams.y;
+                this.$l.photonRow = pb.floor(pb.mul(this.$inputs.photonIndex, this.invGrid));
+                this.$l.photonCol = pb.sub(this.$inputs.photonIndex, pb.mul(this.photonRow, this.gridSize));
+                this.$l.photonUV = pb.mul(pb.add(pb.vec2(this.photonCol, this.photonRow), pb.vec2(0.5)), this.invGrid);
+                this.$l.warpedNDC = pb.mix(this.causticGridBounds.xy, this.causticGridBounds.zw, this.photonUV);
+                this.$l.ndc = ShaderHelper.unwarpCausticNDC(this, this.warpedNDC, this.causticSplatParams.x);
+                this.$l.planePos = pb.add(this.causticCenter.xyz, pb.mul(this.causticFrameX.xyz, pb.mul(this.ndc.x, this.radius.x)), pb.mul(this.causticFrameY.xyz, pb.mul(this.ndc.y, this.radius.y)));
+                // Sweep along the light direction onto the undisturbed water plane.
+                this.$l.sweep = pb.div(pb.sub(this.waterLevel, this.planePos.y), this.L.y);
+                this.$l.surfaceXZ = pb.add(this.planePos, pb.mul(this.L, this.sweep));
+                this.$l.outside = pb.or(pb.any(pb.lessThan(this.surfaceXZ.xz, this.causticRegion.xy)), pb.any(pb.greaterThan(this.surfaceXZ.xz, this.causticRegion.zw)));
+                // Displaced surface point and the detail normal that bends the ray. Both
+                // wave generators sample with an explicit LOD, which is what makes this
+                // legal in a vertex shader.
+                //
+                // The photon is launched from the rest point and lands wherever the
+                // surface carried it, so the refraction is right. What it is not is
+                // uniform in world xz - the horizontal displacement bunches the launch
+                // points by the surface Jacobian, over-weighting compressed crests by
+                // 1/J. Inverting the displacement per photon would fix that, but the
+                // inversion only converges where the surface does not fold, and a choppy
+                // FFT folds exactly at the crests it would matter for.
+                this.$l.surfacePos = pb.vec3();
+                this.$l.coarseNormal = pb.vec3();
+                waveGenerator.calcVertexPositionAndNormal(this, this.surfaceXZ, this.surfacePos, this.coarseNormal);
+                this.$l.normal = waveGenerator.calcFragmentNormal(this, this.surfaceXZ.xz, this.coarseNormal);
+                // Refract, then subtract the deflection a flat surface would have
+                // produced. Calm water then leaves the ray parallel to L, which lands
+                // photon (i,j) back on texel (i,j) and normalises the map to 1.
+                this.$l.refracted = pb.refract(this.L, this.normal, this.eta);
+                this.$l.refractedFlat = pb.refract(this.L, pb.vec3(0, 1, 0), this.eta);
+                this.$l.dir = pb.normalize(pb.add(pb.sub(this.refracted, this.refractedFlat), this.L));
+                // Intersect the horizontal focal plane below the surface. The ray always
+                // travels downwards here, but clamp anyway so a grazing ray cannot
+                // produce an enormous or negative step.
+                this.$l.invDirY = pb.min(this.dir.y, -1e-4);
+                this.$l.targetY = pb.sub(this.waterLevel, this.focalDepth);
+                this.$l.hitT = pb.div(pb.sub(this.targetY, this.surfacePos.y), this.invDirY);
+                this.$l.hitPos = pb.add(this.surfacePos, pb.mul(this.dir, pb.max(this.hitT, 0)));
+                if (sceneDepth) {
+                    // Land the photon on the scene rather than on a plane through it.
+                    //
+                    // Fixed-point iteration, not a ray march: read the height of the scene
+                    // under the current guess, re-intersect the ray with a horizontal
+                    // plane at that height, repeat. Each step is one texture fetch and the
+                    // sequence converges in two or three for any receiver that is smooth
+                    // over the distance the guess moves. A march would need an order of
+                    // magnitude more fetches, which the photon count cannot afford - at
+                    // the default density a full-coverage 1024 map launches four million.
+                    //
+                    // Where the assumption fails - a silhouette, an overhang - the
+                    // iteration lands on one of the two surfaces rather than diverging,
+                    // because every step is still a valid intersection of the ray with
+                    // some horizontal plane.
+                    this.$l.probe = this.hitPos;
+                    this.$l.layer = pb.int(this.causticSceneParams.x);
+                    for(let i = 0; i < SCENE_DEPTH_ITERATIONS; i++){
+                        this.$l[`clip${i}`] = pb.mul(this.causticSceneMatrix, pb.vec4(this.probe, 1));
+                        this.$l[`ndc${i}`] = pb.div(this[`clip${i}`].xyz, this[`clip${i}`].w);
+                        this.$l[`uv${i}`] = pb.add(pb.mul(this[`ndc${i}`].xy, 0.5), pb.vec2(0.5));
+                        // Outside the cascade there is nothing to intersect against; keep
+                        // whatever the previous step produced, which for the first step is
+                        // the focal plane hit the flat path would have used.
+                        this.$l[`inside${i}`] = pb.and(pb.all(pb.greaterThanEqual(this[`uv${i}`], pb.vec2(0))), pb.all(pb.lessThanEqual(this[`uv${i}`], pb.vec2(1))));
+                        // texelFetch rather than a filtered sample: the value is a depth,
+                        // and averaging two depths across a silhouette names a surface that
+                        // is not there. WebGPU only - GLSL ES 3.0 forbids texelFetch on a
+                        // shadow-sampler texture, which is what gates this whole path.
+                        this.$l[`depth${i}`] = pb.textureArrayLoad(this.causticSceneDepth, pb.ivec2(pb.mul(this[`uv${i}`], this.causticSceneParams.y)), this.layer, pb.int(0));
+                        // Back to a world position. The cascade is orthographic, so the
+                        // stored depth and the sample's uv are enough to place the point.
+                        this.$l[`sceneNDC${i}`] = pb.vec3(this[`ndc${i}`].xy, REVERSE_Z ? this[`depth${i}`] : pb.sub(pb.mul(this[`depth${i}`], 2), 1));
+                        this.$l[`sceneClip${i}`] = pb.mul(this.causticSceneMatrixInv, pb.vec4(this[`sceneNDC${i}`], 1));
+                        this.$l[`scenePos${i}`] = pb.div(this[`sceneClip${i}`].xyz, this[`sceneClip${i}`].w);
+                        // Re-intersect at the height just read. Only accept it while it is
+                        // below the *displaced* surface at this photon's entry: a scene
+                        // point above that is not something the photon passed through. The
+                        // rest level is the wrong bar - it would drop every photon landing
+                        // on a receiver that pokes above the rest plane under a passing
+                        // crest, cutting the caustics off along a flat line.
+                        this.$l[`t${i}`] = pb.div(pb.sub(this[`scenePos${i}`].y, this.surfacePos.y), this.invDirY);
+                        this.$l[`next${i}`] = pb.add(this.surfacePos, pb.mul(this.dir, pb.max(this[`t${i}`], 0)));
+                        // mix rather than select: the builder has no vec3 select.
+                        this.probe = pb.mix(this.probe, this[`next${i}`], pb.float(pb.and(this[`inside${i}`], pb.lessThan(this[`scenePos${i}`].y, this.surfacePos.y))));
+                    }
+                    this.hitPos = this.probe;
+                }
+                // Project the hit back into the map. frameX/frameY are perpendicular to
+                // L and to each other, so this is just two dot products.
+                this.$l.rel = pb.sub(this.hitPos, this.causticCenter.xyz);
+                this.$l.hitNDC = pb.mul(pb.vec2(pb.dot(this.rel, this.causticFrameX.xyz), pb.dot(this.rel, this.causticFrameY.xyz)), this.invRadius);
+                // Into warped space, where the map's texels live.
+                this.$l.hitWarped = ShaderHelper.warpCausticNDC(this, this.hitNDC, this.causticSplatParams.x);
+                this.$outputs.photonWeight = this.causticSplatParams.w;
+                // No per-backend y flip. A fragment written at clip y lands on the same
+                // texture row on both backends, so the map the receiver samples with
+                // `ndc * 0.5 + 0.5` is the one this writes at clip `ndc`.
+                this.$builtins.position = pb.vec4(this.hitWarped, 0, 1);
+                if (pb.getDevice().type !== 'webgpu') {
+                    // GLSL leaves gl_PointSize undefined unless it is written, and an
+                    // undefined size rasterises nothing at all. WebGPU points are always
+                    // one pixel.
+                    this.$builtins.pointSize = 1;
+                }
+                this.$if(this.outside, function() {
+                    // Park the photon outside the clip volume so it is discarded. Keep
+                    // w at 1: a zero w would divide to NaN instead of clipping.
+                    this.$builtins.position = pb.vec4(-2, -2, 0, 1);
+                });
+            });
+        },
+        fragment (pb) {
+            this.$outputs.outColor = pb.vec4();
+            pb.main(function() {
+                this.$outputs.outColor = pb.vec4(this.$inputs.photonWeight, 0, 0, 1);
+            });
+        }
+    };
+}
+/**
+ * Shader for the displaced surface height map.
+ *
+ * Rasterises the water surface itself into the light-space slice, one body per
+ * draw. A grid is laid out over the body's footprint in warped map space; each
+ * vertex sweeps its grid point along the light onto the rest plane, lets the
+ * wave generator carry it to where that bit of surface is, and projects the
+ * displaced point back into the map as its clip position. The fragment writes
+ * its height above the rest plane, offset by `CAUSTIC_HEIGHT_BIAS`, into this
+ * body's channel - selected with a colour write mask, so where the surface
+ * overlaps itself in the light's view the last triangle wins rather than the two
+ * heights adding. The target is cleared first, and a texel the surface never
+ * reaches stays at zero, which the receiver reads as "no water on this ray".
+ *
+ * Rasterising is what makes the horizontal displacement a non-issue: sampling
+ * the generator at the map position would return the surface that *started*
+ * there, and inverting that displacement only converges where the surface does
+ * not fold. It also makes the footprint edge right - a receiver whose sun ray
+ * crosses the rest plane outside the footprint finds an empty texel and stays
+ * dry, where a flat stored height would put it under water that does not exist.
+ *
+ * The receiver looks this up with the very uv it uses for the caustic pattern:
+ * its fragment and the ray's crossing of the rest plane lie on one light ray,
+ * and the map's projection is invariant along the light.
+ *
+ * Everything runs in the vertex stage; the generators sample with an explicit
+ * LOD, which is what makes that legal.
+ *
+ * @param waveGenerator - Supplies the surface displacement of this body.
+ * @internal
+ */ function createCausticHeightShader(waveGenerator) {
+    return {
+        vertex (pb) {
+            // Vertex ordinal; the grid coordinate is derived from it.
+            this.$inputs.vertexIndex = pb.float().attrib('position');
+            this.$outputs.height = pb.float();
+            this.$outputs.inside = pb.float();
+            this.causticFrameX = pb.vec4().uniform(0);
+            this.causticFrameY = pb.vec4().uniform(0);
+            /** (slice centre.xyz, this body's rest level) */ this.causticCenter = pb.vec4().uniform(0);
+            this.causticLightDir = pb.vec4().uniform(0);
+            this.causticRegion = pb.vec4().uniform(0);
+            /** Map-NDC rectangle the grid is laid out over: (minX, minY, maxX, maxY). */ this.causticGridBounds = pb.vec4().uniform(0);
+            /** (warp strength, grid size, 1 / (grid size + 1), 1 / grid size) */ this.causticHeightParams = pb.vec4().uniform(0);
+            ShaderHelper.declareStandaloneCameraTime(this, 0);
+            waveGenerator.setupUniforms(this, 0);
+            pb.main(function() {
+                this.$l.invRadius = pb.vec2(this.causticFrameX.w, this.causticFrameY.w);
+                this.$l.radius = pb.div(pb.vec2(1), this.invRadius);
+                this.$l.L = this.causticLightDir.xyz;
+                this.$l.waterLevel = this.causticCenter.w;
+                // Ordinal to grid coordinate, (gridSize + 1) vertices per side. Half a
+                // vertex up before the floor: the reciprocal is inexact, and an ordinal
+                // that is an exact multiple of the row length must not round down into
+                // the previous row.
+                this.$l.row = pb.floor(pb.mul(pb.add(this.$inputs.vertexIndex, 0.5), this.causticHeightParams.z));
+                this.$l.col = pb.sub(this.$inputs.vertexIndex, pb.mul(this.row, pb.add(this.causticHeightParams.y, 1)));
+                this.$l.gridUV = pb.mul(pb.vec2(this.col, this.row), this.causticHeightParams.w);
+                // Grid point to the slice, through the warp the map's texels live under.
+                this.$l.warpedNDC = pb.mix(this.causticGridBounds.xy, this.causticGridBounds.zw, this.gridUV);
+                this.$l.ndc = ShaderHelper.unwarpCausticNDC(this, this.warpedNDC, this.causticHeightParams.x);
+                this.$l.planePos = pb.add(this.causticCenter.xyz, pb.mul(this.causticFrameX.xyz, pb.mul(this.ndc.x, this.radius.x)), pb.mul(this.causticFrameY.xyz, pb.mul(this.ndc.y, this.radius.y)));
+                // Along the light onto the rest plane: the rest point of this vertex.
+                this.$l.sweep = pb.div(pb.sub(this.waterLevel, this.planePos.y), this.L.y);
+                this.$l.surfaceXZ = pb.add(this.planePos, pb.mul(this.L, this.sweep));
+                // Outside the footprint there is no surface. Resolved per vertex and
+                // interpolated, which fades the edge over one grid cell.
+                this.$outputs.inside = pb.float(pb.and(pb.all(pb.greaterThanEqual(this.surfaceXZ.xz, this.causticRegion.xy)), pb.all(pb.lessThanEqual(this.surfaceXZ.xz, this.causticRegion.zw))));
+                // Where the surface carried this rest point, and how high it is there.
+                this.$l.surfacePos = pb.vec3();
+                this.$l.surfaceNormal = pb.vec3();
+                waveGenerator.calcVertexPositionAndNormal(this, this.surfaceXZ, this.surfacePos, this.surfaceNormal);
+                this.$outputs.height = pb.sub(this.surfacePos.y, this.waterLevel);
+                // The displaced point back into the map, exactly as the splat projects a
+                // photon hit: two dot products, then the warp.
+                this.$l.rel = pb.sub(this.surfacePos, this.causticCenter.xyz);
+                this.$l.hitNDC = pb.mul(pb.vec2(pb.dot(this.rel, this.causticFrameX.xyz), pb.dot(this.rel, this.causticFrameY.xyz)), this.invRadius);
+                this.$l.hitWarped = ShaderHelper.warpCausticNDC(this, this.hitNDC, this.causticHeightParams.x);
+                // The receiver reads the map at `v = 0.5 + 0.5 * ndc.y`. On WebGL a
+                // fragment at clip y lands on that row; on WebGPU clip +1 is the first
+                // row, so the surface is drawn upside down to land where the receiver
+                // looks. The splat needs no such flip because its map reaches the
+                // receiver through the blur and resolve quads, each of which flips it
+                // once more on WebGPU; this map goes straight.
+                this.$builtins.position = pb.getDevice().type === 'webgpu' ? pb.vec4(this.hitWarped.x, pb.neg(this.hitWarped.y), 0, 1) : pb.vec4(this.hitWarped, 0, 1);
+            });
+        },
+        fragment (pb) {
+            this.$outputs.outColor = pb.vec4();
+            pb.main(function() {
+                // Outside the footprint nothing is written at all, so the texel keeps
+                // reading as "no surface" rather than as a surface at height zero.
+                this.$if(pb.lessThan(this.$inputs.inside, 0.5), function() {
+                    pb.discard();
+                });
+                // Every channel; the colour mask keeps all but this body's.
+                this.$outputs.outColor = pb.vec4(pb.add(this.$inputs.height, CAUSTIC_HEIGHT_BIAS));
+            });
+        }
+    };
+}
+/**
+ * Shader for the caustic map blur.
+ *
+ * Four bilinear taps at the texel corners average a 2x2 neighbourhood. The
+ * weights sum to one, so the "calm water reads 1.0" normalisation established by
+ * the accumulation pass survives any number of iterations.
+ *
+ * @internal
+ */ function createCausticBlurShader() {
+    return {
+        vertex (pb) {
+            this.$inputs.pos = pb.vec2().attrib('position');
+            this.$outputs.uv = pb.vec2();
+            pb.main(function() {
+                this.$builtins.position = pb.vec4(this.$inputs.pos, 0, 1);
+                this.$outputs.uv = pb.add(pb.mul(this.$inputs.pos, 0.5), pb.vec2(0.5));
+            });
+        },
+        fragment (pb) {
+            this.causticSrc = pb.tex2D().uniform(0);
+            this.causticTexelSize = pb.vec4().uniform(0);
+            this.$outputs.outColor = pb.vec4();
+            pb.main(function() {
+                this.$l.o = pb.mul(this.causticTexelSize.xy, 0.5);
+                this.$l.sum = pb.add(pb.textureSampleLevel(this.causticSrc, pb.add(this.$inputs.uv, pb.vec2(this.o.x, this.o.y)), 0), pb.textureSampleLevel(this.causticSrc, pb.add(this.$inputs.uv, pb.vec2(pb.neg(this.o.x), this.o.y)), 0), pb.textureSampleLevel(this.causticSrc, pb.add(this.$inputs.uv, pb.vec2(this.o.x, pb.neg(this.o.y))), 0), pb.textureSampleLevel(this.causticSrc, pb.add(this.$inputs.uv, pb.vec2(pb.neg(this.o.x), pb.neg(this.o.y))), 0));
+                this.$outputs.outColor = pb.vec4(pb.mul(this.sum.x, 0.25), 0, 0, 1);
+            });
+        }
+    };
+}
+/**
+ * Shader for the temporal resolve.
+ *
+ * Reprojection is exact and matrix-free. Both frames parameterise the map as an
+ * orthographic slice perpendicular to the light, so a texel maps to a world
+ * point with two scaled axes, and that point maps into the previous frame with
+ * two dot products. Photons travel along the light and the slice is normal to
+ * it, so the plane the point is taken on does not matter.
+ *
+ * Map NDC relates to texture coordinate by the receiver's `ndc * 0.5 + 0.5`
+ * (see `ShaderHelper.calculateWaterCaustic`), which is what makes this
+ * independent of the clip-space y flip the splat has to apply.
+ *
+ * @internal
+ */ function createCausticResolveShader() {
+    return {
+        vertex (pb) {
+            this.$inputs.pos = pb.vec2().attrib('position');
+            this.$outputs.uv = pb.vec2();
+            pb.main(function() {
+                this.$builtins.position = pb.vec4(this.$inputs.pos, 0, 1);
+                this.$outputs.uv = pb.add(pb.mul(this.$inputs.pos, 0.5), pb.vec2(0.5));
+            });
+        },
+        fragment (pb) {
+            this.causticCurrent = pb.tex2D().uniform(0);
+            this.causticHistory = pb.tex2D().uniform(0);
+            this.causticFrameX = pb.vec4().uniform(0);
+            this.causticFrameY = pb.vec4().uniform(0);
+            this.causticCenter = pb.vec4().uniform(0);
+            this.causticPrevFrameX = pb.vec4().uniform(0);
+            this.causticPrevFrameY = pb.vec4().uniform(0);
+            this.causticPrevCenter = pb.vec4().uniform(0);
+            /** (blend weight, texel size, warp, previous frame's warp) */ this.causticResolveParams = pb.vec4().uniform(0);
+            this.$outputs.outColor = pb.vec4();
+            pb.main(function() {
+                this.$l.texel = this.causticResolveParams.y;
+                this.$l.current = pb.textureSampleLevel(this.causticCurrent, this.$inputs.uv, 0).x;
+                // Range the current frame supports around this texel. The reprojected
+                // value is clamped into it, which is what lets a long blend coexist with
+                // an animated pattern: where the waves have moved on, the neighbourhood
+                // no longer covers the old value.
+                this.$l.mn = this.current;
+                this.$l.mx = this.current;
+                for(let dy = -1; dy <= 1; dy++){
+                    for(let dx = -1; dx <= 1; dx++){
+                        if (dx === 0 && dy === 0) {
+                            continue;
+                        }
+                        this.$l.s = pb.textureSampleLevel(this.causticCurrent, pb.add(this.$inputs.uv, pb.mul(pb.vec2(dx, dy), this.texel)), 0).x;
+                        this.mn = pb.min(this.mn, this.s);
+                        this.mx = pb.max(this.mx, this.s);
+                    }
+                }
+                // This texel's world point on the slice, then where the previous frame
+                // put that same point. Texels are laid out in warped space, so this
+                // leaves it to reach the world and re-enters it to land on the history:
+                // the two frames may differ in slice and in warp strength alike.
+                this.$l.warpedNDC = pb.sub(pb.mul(this.$inputs.uv, 2), pb.vec2(1));
+                this.$l.ndc = ShaderHelper.unwarpCausticNDC(this, this.warpedNDC, this.causticResolveParams.z);
+                this.$l.radius = pb.div(pb.vec2(1), pb.vec2(this.causticFrameX.w, this.causticFrameY.w));
+                this.$l.world = pb.add(this.causticCenter.xyz, pb.mul(this.causticFrameX.xyz, pb.mul(this.ndc.x, this.radius.x)), pb.mul(this.causticFrameY.xyz, pb.mul(this.ndc.y, this.radius.y)));
+                this.$l.rel = pb.sub(this.world, this.causticPrevCenter.xyz);
+                this.$l.prevNDC = pb.mul(pb.vec2(pb.dot(this.rel, this.causticPrevFrameX.xyz), pb.dot(this.rel, this.causticPrevFrameY.xyz)), pb.vec2(this.causticPrevFrameX.w, this.causticPrevFrameY.w));
+                this.$l.prevWarped = ShaderHelper.warpCausticNDC(this, this.prevNDC, this.causticResolveParams.w);
+                this.$l.prevUV = pb.add(pb.mul(this.prevWarped, 0.5), pb.vec2(0.5));
+                // Ground the camera has just scrolled into has no history at all.
+                this.$l.inside = pb.and(pb.all(pb.greaterThanEqual(this.prevUV, pb.vec2(0))), pb.all(pb.lessThanEqual(this.prevUV, pb.vec2(1))));
+                this.$l.history = pb.textureSampleLevel(this.causticHistory, this.prevUV, 0).x;
+                this.$l.blend = pb.mul(this.causticResolveParams.x, pb.float(this.inside));
+                this.$outputs.outColor = pb.vec4(pb.mix(this.current, pb.clamp(this.history, this.mn, this.mx), this.blend), 0, 0, 1);
+            });
+        }
+    };
+}
+/**
+ * Renders the water caustic map.
+ *
+ * One photon is emitted per texel of a uniform grid laid out on the same
+ * orthographic light-space slice the map covers. Each photon is refracted at the
+ * water surface, intersected with the scene (or a horizontal focal plane) below
+ * it, and splatted additively at the hit position. Because the grid and the map
+ * share a parameterisation, and the mean deflection of a flat surface is removed
+ * from the refracted direction, calm water maps photon `(i,j)` onto texel
+ * `(i,j)` and the map converges to a uniform 1.0 - which the receiver treats as
+ * "no caustics".
+ *
+ * @internal
+ */ class WaterCausticsRenderer {
+    /** Splat programs keyed by the wave generator's shader hash. */ _splatPrograms;
+    /** Height-map programs keyed by the wave generator's shader hash. */ _heightPrograms;
+    /** One per water slot, differing only in which channel they let through. */ _heightStates;
+    _heightParams;
+    /** The surface grid the height map is rasterised with; built once. */ _heightLayout;
+    _heightVertexBuffer;
+    _heightIndexBuffer;
+    _heightIndexCount;
+    _blurProgram;
+    _blurBindGroup;
+    _resolveProgram;
+    _resolveBindGroup;
+    _resolveStates;
+    /**
+   * Slice parameters the last map committed as history was built with, per
+   * camera.
+   *
+   * Per camera because the history textures are, and this has to describe the
+   * exact map the resolve is about to reproject; one shared entry would make a
+   * second viewport reproject through the first one's slice.
+   */ _prevSlices;
+    _resolveParams;
+    _photonLayout;
+    /** Photons the buffer can serve; it grows and is never rebuilt smaller. */ _photonCapacity;
+    _photonBuffer;
+    _photonParams;
+    _photonCount;
+    _splatStates;
+    _blurStates;
+    _uniforms;
+    _tmpRight;
+    _tmpUp;
+    _tmpDir;
+    _tmpCenter;
+    _splatParams;
+    _blurTexelSize;
+    /** Map-NDC rectangle the photon grid covers, and the map fraction it is. */ _gridBounds;
+    _gridFraction;
+    /** Furthest the fitted slice reaches from the camera, for cascade selection. */ _sliceReach;
+    /** Slice frame and extents, kept for the per-body grid fit. */ _sliceRight;
+    _sliceUp;
+    _sliceCenterR;
+    _sliceCenterU;
+    _sliceHalfR;
+    _sliceHalfU;
+    _splatCenter;
+    _sceneMatrixT;
+    _sceneMatrix;
+    _sceneMatrixInv;
+    _sceneDepthParams;
+    /** Warp strength the current slice was built with; 0 when the map is linear. */ _warp;
+    constructor(){
+        this._splatPrograms = new Map();
+        this._heightPrograms = new Map();
+        this._heightStates = [];
+        this._heightParams = new Vector4();
+        this._heightLayout = null;
+        this._heightVertexBuffer = null;
+        this._heightIndexBuffer = null;
+        this._heightIndexCount = 0;
+        this._blurProgram = null;
+        this._blurBindGroup = null;
+        this._resolveProgram = null;
+        this._resolveBindGroup = null;
+        this._resolveStates = null;
+        this._prevSlices = new WeakMap();
+        this._resolveParams = new Vector4();
+        this._photonLayout = null;
+        this._photonCapacity = 0;
+        this._photonBuffer = null;
+        this._photonParams = new Vector4();
+        this._photonCount = 0;
+        this._splatStates = null;
+        this._blurStates = null;
+        this._uniforms = {
+            frameX: new Vector4(),
+            frameY: new Vector4(),
+            center: new Vector4(),
+            lightDir: new Vector4(),
+            params: new Vector4(),
+            extinction: new Vector4(),
+            waterCount: 0,
+            waterRegions: new Float32Array(MAX_CAUSTIC_WATERS * 4),
+            waterMedia: new Float32Array(MAX_CAUSTIC_WATERS * 4)
+        };
+        this._tmpRight = new Vector3();
+        this._tmpUp = new Vector3();
+        this._tmpDir = new Vector3();
+        this._tmpCenter = new Vector3();
+        this._splatParams = new Vector4();
+        this._blurTexelSize = new Vector4();
+        this._gridBounds = new Vector4(-1, -1, 1, 1);
+        this._gridFraction = 1;
+        this._sliceReach = 1;
+        this._sliceRight = new Vector3();
+        this._sliceUp = new Vector3();
+        this._sliceCenterR = 0;
+        this._sliceCenterU = 0;
+        this._sliceHalfR = 1;
+        this._sliceHalfU = 1;
+        this._splatCenter = new Vector4();
+        this._sceneMatrixT = new Matrix4x4();
+        this._sceneMatrix = new Matrix4x4();
+        this._sceneMatrixInv = new Matrix4x4();
+        this._sceneDepthParams = new Vector4();
+        this._warp = 0;
+    }
+    /** Parameters of the map produced by the last successful {@link render}. */ get uniforms() {
+        return this._uniforms;
+    }
+    /**
+   * Storage format for the caustic map. Single channel when the device can both
+   * render to and filter it, which the additive accumulation and the bilinear
+   * sampling need.
+   */ static getMapFormat(device) {
+        const info = device.getDeviceCaps().textureCaps.getTextureFormatInfo('r16f');
+        return info.renderable && info.filterable ? 'r16f' : 'rgba16f';
+    }
+    /**
+   * Storage format for the displaced surface height map. One channel per water
+   * slot, so always four wide; half floats carry a wave height to well under a
+   * millimetre at any plausible level.
+   */ static getHeightMapFormat() {
+        return 'rgba16f';
+    }
+    /**
+   * Whether caustics can be produced for this water surface and light.
+   *
+   * @param water - Water surface the photons are refracted through.
+   * @param light - Directional light the photons come from.
+   * @returns True when {@link render} would produce a usable map.
+   */ static canRender(water, light) {
+        const material = water.material;
+        if (!material?.causticsEnabled || !material.waveGenerator || !light.isDirectionLight()) {
+            return false;
+        }
+        // Sun too close to the horizon: the swept photon grid degenerates.
+        return -light.directionAndCutoff.y >= MIN_SUN_ELEVATION;
+    }
+    /**
+   * Builds the caustic map for one water surface.
+   *
+   * @param ctx - Draw context; supplies the device and the camera the map is centred on.
+   * @param water - Water surface to refract through.
+   * @param light - Directional light acting as the photon source.
+   * @param map - Accumulation target; also the result when nothing resolves after it.
+   * @param scratch - Ping-pong target for the blur, and the temporal resolve's
+   * output. Same size and format as `map`.
+   * @param heights - Target for the displaced surface height map, in
+   * {@link getHeightMapFormat} and the same size as `map`. Filled by this call
+   * and read by the light pass alongside the map.
+   * @param history - Previous frame's resolved map, or null when there is none
+   * to reproject. Ignored unless the material asks for temporal accumulation.
+   * @param createFramebuffer - Wraps a target texture into a framebuffer.
+   * @returns The texture holding the finished map, which is `map` or `scratch`
+   * depending on whether the temporal resolve ran.
+   */ render(ctx, waters, light, map, scratch, heights, history, createFramebuffer) {
+        const device = ctx.device;
+        this._updateUniforms(ctx, waters, light, map.width);
+        const sceneDepth = this._anySceneDepth(waters) ? this._resolveSceneDepth(ctx, light) : null;
+        // The height map first: it depends on the slice alone, and the receiver
+        // needs it whatever the splat produces.
+        device.pushDeviceStates();
+        device.setFramebuffer(createFramebuffer(heights));
+        device.setViewport(null);
+        device.setScissor(null);
+        device.clearFrameBuffer(Vector4.zero(), null, null);
+        this._ensureHeightGrid(device);
+        for(let i = 0; i < waters.length; i++){
+            this._renderHeightsOne(device, ctx, waters[i], i);
+        }
+        device.popDeviceStates();
+        device.pushDeviceStates();
+        device.setFramebuffer(createFramebuffer(map));
+        // The viewport and scissor survive a framebuffer change, and this pass runs
+        // straight after the shadow maps, whose targets are a different size.
+        device.setViewport(null);
+        device.setScissor(null);
+        device.clearFrameBuffer(Vector4.zero(), null, null);
+        device.setRenderStates(this._getSplatStates(device));
+        // One draw per water body, accumulating into the one map. They share the
+        // slice, so a receiver still resolves the pattern with a single lookup; the
+        // footprint, surface height and wave generator are per-draw state.
+        for(let i = 0; i < waters.length; i++){
+            this._splatOne(device, ctx, waters[i], i, map, sceneDepth);
+        }
+        device.popDeviceStates();
+        return this._postProcess(device, waters[0].material, map, scratch, history, ctx, createFramebuffer);
+    }
+    /**
+   * Writes one body's displaced surface height into its channel of the height
+   * map. Per body for the same reason the splat is: each has its own wave
+   * generator, rest level and footprint.
+   * @internal
+   */ _renderHeightsOne(device, ctx, water, index) {
+        const material = water.material;
+        const waveGenerator = material.waveGenerator;
+        // The grid covers this body's footprint, like the photon grid does; a body
+        // the map does not reach has nothing to draw.
+        this._updateGridBounds(water);
+        if (!(this._gridFraction > 0)) {
+            return;
+        }
+        const info = this._getHeightProgram(device, waveGenerator);
+        // A bind group per slot; see _getSplatBindGroup.
+        const bindGroup = this._getSplatBindGroup(device, info, index);
+        bindGroup.setValue('causticFrameX', this._uniforms.frameX);
+        bindGroup.setValue('causticFrameY', this._uniforms.frameY);
+        this._splatCenter.setXYZW(this._uniforms.center.x, this._uniforms.center.y, this._uniforms.center.z, water.worldMatrix.m13);
+        bindGroup.setValue('causticCenter', this._splatCenter);
+        bindGroup.setValue('causticLightDir', this._uniforms.lightDir);
+        bindGroup.setValue('causticRegion', material.region);
+        bindGroup.setValue('causticGridBounds', this._gridBounds);
+        this._heightParams.setXYZW(this._warp, HEIGHT_GRID_SIZE, 1 / (HEIGHT_GRID_SIZE + 1), 1 / HEIGHT_GRID_SIZE);
+        bindGroup.setValue('causticHeightParams', this._heightParams);
+        ShaderHelper.setStandaloneCameraTime(bindGroup, ctx);
+        waveGenerator.applyWaterBindGroup(bindGroup);
+        // Channel i for slot i, which is how the receiver picks it back out.
+        device.setRenderStates(this._getHeightStates(device, index));
+        device.setProgram(info.program);
+        device.setBindGroup(0, bindGroup);
+        device.setVertexLayout(this._heightLayout);
+        device.draw('triangle-list', 0, this._heightIndexCount);
+    }
+    /**
+   * Builds the surface grid once: vertex ordinals, and the index list that
+   * stitches a (HEIGHT_GRID_SIZE + 1)^2 lattice of them into triangles.
+   * @internal
+   */ _ensureHeightGrid(device) {
+        if (this._heightLayout) {
+            return;
+        }
+        const side = HEIGHT_GRID_SIZE + 1;
+        const ordinals = new Float32Array(side * side);
+        for(let i = 0; i < ordinals.length; i++){
+            ordinals[i] = i;
+        }
+        const indices = new Uint32Array(HEIGHT_GRID_SIZE * HEIGHT_GRID_SIZE * 6);
+        let n = 0;
+        for(let row = 0; row < HEIGHT_GRID_SIZE; row++){
+            for(let col = 0; col < HEIGHT_GRID_SIZE; col++){
+                const a = row * side + col;
+                const b = a + 1;
+                const c = a + side;
+                const d = c + 1;
+                indices[n++] = a;
+                indices[n++] = b;
+                indices[n++] = d;
+                indices[n++] = a;
+                indices[n++] = d;
+                indices[n++] = c;
+            }
+        }
+        const vertexBuffer = device.createVertexBuffer('position_f32', ordinals);
+        const indexBuffer = device.createIndexBuffer(indices);
+        this._heightVertexBuffer = vertexBuffer;
+        this._heightIndexBuffer = indexBuffer;
+        this._heightLayout = device.createVertexLayout({
+            vertexBuffers: [
+                {
+                    buffer: vertexBuffer
+                }
+            ],
+            indexBuffer
+        });
+        this._heightIndexCount = indices.length;
+    }
+    /** @internal */ _splatOne(device, ctx, water, index, map, sceneDepth) {
+        const material = water.material;
+        const waveGenerator = material.waveGenerator;
+        // Photons are laid out over this body's own footprint, so the grid bounds
+        // and the fraction of the map they cover are per body, not per map.
+        this._updateGridBounds(water);
+        if (!(this._gridFraction > 0)) {
+            return;
+        }
+        const photonGrid = this._resolvePhotonGrid(material.causticsPhotonResolution, map.width);
+        this._updatePhotonLayout(device, photonGrid);
+        // Scene-depth intersection is per material, but the program is per draw, so
+        // a body that has it off simply compiles the flat variant.
+        const useSceneDepth = !!sceneDepth && material.causticsSceneDepth;
+        const splat = this._getSplatProgram(device, waveGenerator, useSceneDepth);
+        // A bind group per slot; see _getSplatBindGroup.
+        const bindGroup = this._getSplatBindGroup(device, splat, index);
+        if (useSceneDepth) {
+            bindGroup.setValue('causticSceneMatrix', sceneDepth.matrix);
+            bindGroup.setValue('causticSceneMatrixInv', sceneDepth.matrixInv);
+            this._sceneDepthParams.setXYZW(sceneDepth.layer, sceneDepth.size, 0, 0);
+            bindGroup.setValue('causticSceneParams', this._sceneDepthParams);
+            // Point sampling: the stored value is a depth, and averaging two depths
+            // across a silhouette names a surface that is not there.
+            bindGroup.setTexture('causticSceneDepth', sceneDepth.texture, fetchSampler('clamp_nearest_nomip'));
+        }
+        bindGroup.setValue('causticFrameX', this._uniforms.frameX);
+        bindGroup.setValue('causticFrameY', this._uniforms.frameY);
+        // The slice centre is shared, but the water level in w is this body's.
+        this._splatCenter.setXYZW(this._uniforms.center.x, this._uniforms.center.y, this._uniforms.center.z, water.worldMatrix.m13);
+        bindGroup.setValue('causticCenter', this._splatCenter);
+        bindGroup.setValue('causticLightDir', this._uniforms.lightDir);
+        bindGroup.setValue('causticRegion', material.region);
+        bindGroup.setValue('causticGridBounds', this._gridBounds);
+        // A photon grid denser than the map deposits more than one photon per texel;
+        // scale the deposit so a flat surface still integrates to exactly 1. The
+        // grid fraction is part of that: concentrating the same photons onto a
+        // smaller part of the map raises the density there by exactly its inverse.
+        const photonWeight = this._gridFraction * map.width * map.height / (photonGrid * photonGrid);
+        this._splatParams.setXYZW(this._warp, material.causticsDepth, WATER_ETA, photonWeight);
+        bindGroup.setValue('causticSplatParams', this._splatParams);
+        this._photonParams.setXYZW(photonGrid, 1 / photonGrid, 0, 0);
+        bindGroup.setValue('causticPhotonParams', this._photonParams);
+        ShaderHelper.setStandaloneCameraTime(bindGroup, ctx);
+        waveGenerator.applyWaterBindGroup(bindGroup);
+        device.setProgram(splat.program);
+        device.setBindGroup(0, bindGroup);
+        device.setVertexLayout(this._photonLayout);
+        device.draw('point-list', 0, this._photonCount);
+    }
+    /**
+   * Blur and temporal resolve, which run once over the finished map rather than
+   * per water body.
+   *
+   * The settings come from one body's material because the map is one texture.
+   * The largest body supplies them, which is the one the viewer is most likely
+   * under.
+   * @internal
+   */ _postProcess(device, material, map, scratch, history, ctx, createFramebuffer) {
+        // Ping-pong between the two targets. The count is rounded up to an even
+        // number by the material so the last pass always lands back in `map`.
+        const blurPasses = Math.max(0, Math.min(material.causticsBlurPasses, 4));
+        for(let i = 0; i < blurPasses; i++){
+            const src = i % 2 === 0 ? map : scratch;
+            const dst = i % 2 === 0 ? scratch : map;
+            this._blur(device, src, createFramebuffer(dst));
+        }
+        // The blur always lands back in `map`, so `scratch` is free to take the
+        // resolve. Doing it the other way round would make the resolve read and
+        // write one texture.
+        const strength = material.causticsTemporalStrength;
+        if (strength <= 0) {
+            // Nothing is committed as history this frame, so the recorded slice has to
+            // keep describing whichever map the history slot still holds.
+            return map;
+        }
+        const camera = ctx.camera;
+        const previous = this._prevSlices.get(camera);
+        // No history on the first frame, after a resize, or after the pass was off
+        // for a while. The current map stands on its own and becomes the history.
+        const resolved = history && previous ? scratch : map;
+        if (resolved === scratch) {
+            this._resolve(device, map, history, previous, strength, createFramebuffer(scratch));
+        }
+        this._rememberSlice(camera);
+        return resolved;
+    }
+    /**
+   * Shadow cascade to read the scene depth from, or null when this backend or
+   * this light cannot supply one.
+   * @internal
+   */ _resolveSceneDepth(ctx, light) {
+        // WebGPU only. Reading a raw depth out of the shadow map needs a texel
+        // fetch, and GLSL ES 3.0 does not allow one on a shadow-sampler texture.
+        // WebGL2 keeps the focal plane.
+        if (ctx.device.type !== 'webgpu') {
+            return null;
+        }
+        const params = ctx.shadowMapInfo?.get(light);
+        const shadowMap = params?.shadowMap;
+        // Only the cascaded native-depth path. A packed RGBA map stores an encoded
+        // distance rather than a sampled depth, and a non-array map has no cascade
+        // to select; both fall back to the plane.
+        if (!params || !shadowMap?.isTexture2DArray() || !shadowMap.isDepth()) {
+            return null;
+        }
+        // The cascade that covers the slice most tightly: the smallest one whose
+        // split distance clears the slice's reach. Falling off the end means the
+        // slice outruns the shadow map and the last cascade is all there is.
+        const count = Math.max(1, Math.min(params.numShadowCascades, 4));
+        const reach = Math.max(1, this._sliceReach);
+        let layer = count - 1;
+        for(let i = 0; i < count; i++){
+            if (params.cascadeDistances[i] >= reach) {
+                layer = i;
+                break;
+            }
+        }
+        // shadowMatrices holds each cascade's view-projection transposed, four vec4
+        // rows per cascade, which is the layout the lighting pass dots against.
+        this._sceneMatrixT.set(params.shadowMatrices.subarray(layer * 16, layer * 16 + 16));
+        Matrix4x4.transpose(this._sceneMatrixT, this._sceneMatrix);
+        Matrix4x4.invert(this._sceneMatrix, this._sceneMatrixInv);
+        return {
+            texture: shadowMap,
+            layer,
+            size: shadowMap.width,
+            matrix: this._sceneMatrix,
+            matrixInv: this._sceneMatrixInv
+        };
+    }
+    /**
+   * Photon grid edge length for this frame.
+   *
+   * Auto solves the grid for a fixed density in photons per covered map texel:
+   * the grid covers `gridFraction` of the map, so the target is reached at
+   * `grid = size * sqrt(target * gridFraction)`. Fixing the grid instead leaves
+   * the density swinging with the water's footprint.
+   *
+   * @param requested - Material setting; 0 asks for the automatic size.
+   * @param mapSize - Edge length of the caustic map.
+   * @internal
+   */ _resolvePhotonGrid(requested, mapSize) {
+        if (requested > 0) {
+            return Math.max(8, Math.min(requested, 4096));
+        }
+        const grid = Math.round(mapSize * Math.sqrt(PHOTONS_PER_TEXEL * this._gridFraction));
+        return Math.max(8, Math.min(grid, 4096));
+    }
+    /**
+   * Records the slice the map just produced was built with, for the next frame's
+   * reprojection.
+   * @internal
+   */ _rememberSlice(camera) {
+        let slice = this._prevSlices.get(camera);
+        if (!slice) {
+            slice = {
+                frameX: new Vector4(),
+                frameY: new Vector4(),
+                center: new Vector4(),
+                warp: 0
+            };
+            this._prevSlices.set(camera, slice);
+        }
+        slice.frameX.set(this._uniforms.frameX);
+        slice.frameY.set(this._uniforms.frameY);
+        slice.center.set(this._uniforms.center);
+        slice.warp = this._warp;
+    }
+    /** @internal */ _resolve(device, current, history, previous, strength, dst) {
+        const program = this._getResolveProgram(device);
+        const bindGroup = this._resolveBindGroup;
+        device.pushDeviceStates();
+        device.setFramebuffer(dst);
+        device.setViewport(null);
+        device.setScissor(null);
+        device.setProgram(program);
+        bindGroup.setTexture('causticCurrent', current, fetchSampler('clamp_linear_nomip'));
+        bindGroup.setTexture('causticHistory', history, fetchSampler('clamp_linear_nomip'));
+        bindGroup.setValue('causticFrameX', this._uniforms.frameX);
+        bindGroup.setValue('causticFrameY', this._uniforms.frameY);
+        bindGroup.setValue('causticCenter', this._uniforms.center);
+        bindGroup.setValue('causticPrevFrameX', previous.frameX);
+        bindGroup.setValue('causticPrevFrameY', previous.frameY);
+        bindGroup.setValue('causticPrevCenter', previous.center);
+        this._resolveParams.setXYZW(strength, 1 / current.width, this._warp, previous.warp);
+        bindGroup.setValue('causticResolveParams', this._resolveParams);
+        device.setBindGroup(0, bindGroup);
+        drawFullscreenQuad(this._getResolveStates(device));
+        device.popDeviceStates();
+    }
+    /** @internal */ _getResolveProgram(device) {
+        if (!this._resolveProgram) {
+            this._resolveProgram = device.buildRenderProgram(createCausticResolveShader());
+            this._resolveProgram.name = '@Water_CausticResolve';
+            this._resolveBindGroup = device.createBindGroup(this._resolveProgram.bindGroupLayouts[0]);
+        }
+        return this._resolveProgram;
+    }
+    /** @internal */ _getResolveStates(device) {
+        if (!this._resolveStates) {
+            this._resolveStates = device.createRenderStateSet();
+            this._resolveStates.useRasterizerState().setCullMode('none');
+            this._resolveStates.useDepthState().enableTest(false).enableWrite(false);
+        }
+        return this._resolveStates;
+    }
+    /** Releases the GPU objects owned by this renderer. */ dispose() {
+        for (const info of this._splatPrograms.values()){
+            for (const bindGroup of info.bindGroups){
+                bindGroup?.dispose();
+            }
+            info.program.dispose();
+        }
+        this._splatPrograms.clear();
+        for (const info of this._heightPrograms.values()){
+            for (const bindGroup of info.bindGroups){
+                bindGroup?.dispose();
+            }
+            info.program.dispose();
+        }
+        this._heightPrograms.clear();
+        this._heightStates.length = 0;
+        // The layout does not own its buffers; see _updatePhotonLayout.
+        this._heightLayout?.dispose();
+        this._heightLayout = null;
+        this._heightVertexBuffer?.dispose();
+        this._heightVertexBuffer = null;
+        this._heightIndexBuffer?.dispose();
+        this._heightIndexBuffer = null;
+        this._heightIndexCount = 0;
+        this._blurBindGroup?.dispose();
+        this._blurBindGroup = null;
+        this._resolveProgram?.dispose();
+        this._resolveProgram = null;
+        this._resolveBindGroup?.dispose();
+        this._resolveBindGroup = null;
+        this._resolveStates = null;
+        this._blurProgram?.dispose();
+        this._blurProgram = null;
+        this._photonLayout?.dispose();
+        this._photonLayout = null;
+        // Disposing the layout releases its vertex array object, not the buffer it
+        // was built over.
+        this._photonBuffer?.dispose();
+        this._photonBuffer = null;
+        this._photonCapacity = 0;
+        this._photonCount = 0;
+        this._splatStates = null;
+        this._blurStates = null;
+    }
+    /** @internal */ _blur(device, src, dst) {
+        const program = this._getBlurProgram(device);
+        device.pushDeviceStates();
+        device.setFramebuffer(dst);
+        device.setProgram(program);
+        this._blurBindGroup.setTexture('causticSrc', src, fetchSampler('clamp_linear_nomip'));
+        this._blurTexelSize.setXYZW(1 / src.width, 1 / src.height, 0, 0);
+        this._blurBindGroup.setValue('causticTexelSize', this._blurTexelSize);
+        device.setBindGroup(0, this._blurBindGroup);
+        drawFullscreenQuad(this._getBlurStates(device));
+        device.popDeviceStates();
+    }
+    /**
+   * Recomputes the orthographic light-space slice the map covers.
+   * @internal
+   */ _updateUniforms(ctx, waters, light, mapSize) {
+        // Slice-wide settings come from the first body, which the caller has sorted
+        // largest first. They describe the map, not the water, so one body has to
+        // win: a range or a warp per body would ask one texture for two resolutions.
+        const material = waters[0].material;
+        const dir = this._tmpDir;
+        dir.set(light.directionAndCutoff.xyz());
+        dir.inplaceNormalize();
+        // Two axes perpendicular to the light direction. Any pair will do; picking a
+        // world axis that is not parallel to the light keeps the cross products stable.
+        const seed = Math.abs(dir.y) > 0.99 ? Vector3.axisPZ() : Vector3.axisPY();
+        Vector3.cross(seed, dir, this._tmpRight);
+        this._tmpRight.inplaceNormalize();
+        Vector3.cross(dir, this._tmpRight, this._tmpUp);
+        this._tmpUp.inplaceNormalize();
+        const right = this._tmpRight;
+        const up = this._tmpUp;
+        const waterLevel = waters[0].worldMatrix.m13;
+        const range = Math.max(1, material.causticsRange);
+        const camera = ctx.camera.getWorldPosition();
+        const center = this._tmpCenter.setXYZ(camera.x, waterLevel, camera.z);
+        const cameraRight = Vector3.dot(center, right);
+        const cameraUp = Vector3.dot(center, up);
+        // The component along the light direction is arbitrary: both the projection
+        // into the map and the photon sweep are invariant along it.
+        const alongDir = Vector3.dot(center, dir);
+        // Water region in light space. A world-axis-aligned rectangle projects to a
+        // parallelogram here, so its bounds come from the four corners; the map is a
+        // box in these coordinates, which is why the fit is against the AABB.
+        //
+        // Over every body at once, so the slice covers all of them. Bodies far
+        // apart make the union mostly empty, but `causticsRange` already bounds how
+        // much of that reaches the map.
+        let regionMinR = Infinity;
+        let regionMaxR = -Infinity;
+        let regionMinU = Infinity;
+        let regionMaxU = -Infinity;
+        for (const body of waters){
+            const region = body.material.region;
+            // Each body's own height, since the projection is taken on its surface.
+            const level = body.worldMatrix.m13;
+            for (const [x, z] of [
+                [
+                    region.x,
+                    region.y
+                ],
+                [
+                    region.z,
+                    region.y
+                ],
+                [
+                    region.x,
+                    region.w
+                ],
+                [
+                    region.z,
+                    region.w
+                ]
+            ]){
+                const r = x * right.x + level * right.y + z * right.z;
+                const v = x * up.x + level * up.y + z * up.z;
+                regionMinR = Math.min(regionMinR, r);
+                regionMaxR = Math.max(regionMaxR, r);
+                regionMinU = Math.min(regionMinU, v);
+                regionMaxU = Math.max(regionMaxU, v);
+            }
+        }
+        // Fit the slice to what the water can actually cast into, instead of always
+        // spending the map on a camera-centred square of `range`, which leaves most
+        // of it permanently zero for a pool far smaller than the range.
+        // `causticsRange` becomes a cap on how far from the camera the map reaches
+        // rather than its literal half-extent.
+        let loR = Math.max(regionMinR, cameraRight - range);
+        let hiR = Math.min(regionMaxR, cameraRight + range);
+        let loU = Math.max(regionMinU, cameraUp - range);
+        let hiU = Math.min(regionMaxU, cameraUp + range);
+        if (hiR <= loR || hiU <= loU) {
+            // The water casts nowhere within range. Nothing will be drawn, but the
+            // slice still has to be finite: the receiver projects through it whatever
+            // the map holds, and the grid bounds below have to come out empty rather
+            // than inverted.
+            loR = cameraRight - range;
+            hiR = cameraRight + range;
+            loU = cameraUp - range;
+            hiU = cameraUp + range;
+        }
+        let halfR = Math.max(MIN_SLICE_EXTENT, (hiR - loR) * 0.5);
+        let halfU = Math.max(MIN_SLICE_EXTENT, (hiU - loU) * 0.5);
+        // The map is square, so an anisotropic slice gives its two axes different
+        // world texel sizes, which reads as directional smearing. Capping the ratio
+        // keeps most of the fit while bounding that, and bounds the same asymmetry
+        // in the edge fade, whose band is a share of each axis.
+        halfR = Math.max(halfR, halfU / MAX_SLICE_ASPECT);
+        halfU = Math.max(halfU, halfR / MAX_SLICE_ASPECT);
+        // Quantise so the extent holds still while the camera moves: texel snapping
+        // below only stops the map crawling if the texel size itself is stable, and
+        // a continuously shrinking slice resamples the temporal history every frame.
+        // The two common cases - a pool wholly inside the range, a sea wholly
+        // covering it - sit on a fixed level and never change at all.
+        halfR = Math.min(range, quantiseSliceExtent(halfR, range));
+        halfU = Math.min(range, quantiseSliceExtent(halfU, range));
+        // Warping only pays where the range, not the water, is what bounds the map.
+        // A slice already fitted to a pool has every texel on water the camera can
+        // see, and concentrating them further would just blur its far side.
+        const rangeLimited = regionMinR < cameraRight - range || regionMaxR > cameraRight + range || regionMinU < cameraUp - range || regionMaxU > cameraUp + range;
+        const warp = rangeLimited ? material.causticsWarp : 0;
+        // Snap the centre so the map does not crawl as the camera moves. Whole
+        // texels when the map is linear, which is exact; a coarse ladder under a
+        // warp, where no shift is exact and the goal is instead to shift rarely.
+        const snapR = warp > 0 ? halfR / WARPED_CENTER_SNAP_DIVISIONS : 2 * halfR / mapSize;
+        const snapU = warp > 0 ? halfU / WARPED_CENTER_SNAP_DIVISIONS : 2 * halfU / mapSize;
+        const centerR = Math.round((loR + hiR) * 0.5 / snapR) * snapR;
+        const centerU = Math.round((loU + hiU) * 0.5 / snapU) * snapU;
+        center.setXYZ(right.x * centerR + up.x * centerU + dir.x * alongDir, right.y * centerR + up.y * centerU + dir.y * alongDir, right.z * centerR + up.z * centerU + dir.z * alongDir);
+        const u = this._uniforms;
+        u.frameX.setXYZW(right.x, right.y, right.z, 1 / halfR);
+        u.frameY.setXYZW(up.x, up.y, up.z, 1 / halfU);
+        u.center.setXYZW(center.x, center.y, center.z, waterLevel);
+        u.lightDir.setXYZW(dir.x, dir.y, dir.z, 1 / Math.max(-dir.y, MIN_SUN_ELEVATION));
+        // Edge fade, expressed to the receiver as the distance from the map centre
+        // the fade begins at, in units of the map half-extent. Resolving it here
+        // keeps the shader free of the extents and lets the auto width put a floor
+        // in meters under a band the map fraction alone would collapse.
+        //
+        // Only a border the range put there needs fading. Where the fit stopped at
+        // the water instead, the border already coincides with the region the
+        // receiver gates on, so a band there is at best a no-op and at worst eats
+        // caustics from the last few meters of a pool the map now fits exactly.
+        const minHalf = Math.min(halfR, halfU);
+        const fadeDistance = !rangeLimited ? 0 : material.causticsFadeDistance > 0 ? material.causticsFadeDistance : Math.max(AUTO_FADE_MIN_DISTANCE, AUTO_FADE_FRACTION * minHalf);
+        const fadeFraction = Math.max(MIN_FADE_FRACTION, Math.min(MAX_FADE_FRACTION, fadeDistance / minHalf));
+        u.params.setXYZW(material.causticsIntensity, material.causticsDepth, material.causticsDefocus, 1 - fadeFraction);
+        u.extinction.setXYZW(0, 0, 0, warp);
+        this._warp = warp;
+        // Retained for the per-body grid fit, which runs per draw rather than here.
+        this._sliceRight = right;
+        this._sliceUp = up;
+        this._sliceCenterR = centerR;
+        this._sliceCenterU = centerU;
+        this._sliceHalfR = halfR;
+        this._sliceHalfU = halfU;
+        // How far the slice reaches from the camera, which is what decides how
+        // coarse a shadow cascade has to be to contain it.
+        this._sliceReach = Math.hypot(halfR, halfU);
+        // The per-body table the receiver searches. Footprint and surface height
+        // decide which body is above a given point; the medium is what attenuates
+        // the light once one is.
+        u.waterCount = Math.min(waters.length, MAX_CAUSTIC_WATERS);
+        for(let i = 0; i < u.waterCount; i++){
+            const body = waters[i];
+            const region = body.material.region;
+            u.waterRegions[i * 4 + 0] = region.x;
+            u.waterRegions[i * 4 + 1] = region.y;
+            u.waterRegions[i * 4 + 2] = region.z;
+            u.waterRegions[i * 4 + 3] = region.w;
+            const ext = body.material.extinction;
+            u.waterMedia[i * 4 + 0] = ext.x;
+            u.waterMedia[i * 4 + 1] = ext.y;
+            u.waterMedia[i * 4 + 2] = ext.z;
+            u.waterMedia[i * 4 + 3] = body.worldMatrix.m13;
+        }
+    }
+    /**
+   * Map-NDC bounds of one body's footprint, so its photon grid covers just that.
+   *
+   * Projecting into the slice is invariant along the light and the slice is
+   * normal to it, so a point on the water plane and the photon it launches share
+   * a map position: the body's light-space bounds carry over directly. Clamped
+   * to the map, because photons outside it are rasterised away and the fraction
+   * has to describe what is left. Warped, because the grid is laid out in the
+   * space the map's texels live in - the warp is monotone and separable, so
+   * warping the interval's ends gives the warped interval exactly.
+   * @internal
+   */ _updateGridBounds(water) {
+        const region = water.material.region;
+        const level = water.worldMatrix.m13;
+        const right = this._sliceRight;
+        const up = this._sliceUp;
+        let minR = Infinity;
+        let maxR = -Infinity;
+        let minU = Infinity;
+        let maxU = -Infinity;
+        for (const [x, z] of [
+            [
+                region.x,
+                region.y
+            ],
+            [
+                region.z,
+                region.y
+            ],
+            [
+                region.x,
+                region.w
+            ],
+            [
+                region.z,
+                region.w
+            ]
+        ]){
+            const r = x * right.x + level * right.y + z * right.z;
+            const v = x * up.x + level * up.y + z * up.z;
+            minR = Math.min(minR, r);
+            maxR = Math.max(maxR, r);
+            minU = Math.min(minU, v);
+            maxU = Math.max(maxU, v);
+        }
+        const warp = this._warp;
+        // Clamped to the map plus a margin, but never past the water itself. Where
+        // the footprint ends inside the map the bound stays on the water, because a
+        // photon launched off the water is killed by the region test and would only
+        // dilute the weight the fraction below hands out. Where the water carries on
+        // past the border, the margin lets the displaced surface throw photons back
+        // in across it - see GRID_BORDER_MARGIN.
+        const m = 1 + GRID_BORDER_MARGIN;
+        const lo = (v)=>Math.max(-1.15, Math.min(m, v));
+        const minX = warpCausticNDC(lo((minR - this._sliceCenterR) / this._sliceHalfR), warp);
+        const maxX = warpCausticNDC(lo((maxR - this._sliceCenterR) / this._sliceHalfR), warp);
+        const minY = warpCausticNDC(lo((minU - this._sliceCenterU) / this._sliceHalfU), warp);
+        const maxY = warpCausticNDC(lo((maxU - this._sliceCenterU) / this._sliceHalfU), warp);
+        this._gridBounds.setXYZW(minX, minY, maxX, maxY);
+        // Share of the map the grid covers, which is what keeps calm water at 1.0:
+        // the same photon count spread over a smaller area has to deposit
+        // proportionally less each.
+        this._gridFraction = Math.max(0, (maxX - minX) * (maxY - minY) / 4);
+    }
+    /** @internal */ _updatePhotonLayout(device, gridSize) {
+        this._photonCount = gridSize * gridSize;
+        if (this._photonCapacity >= this._photonCount) {
+            return;
+        }
+        // Grow only, and never rebuild for a size change.
+        //
+        // The buffer holds each photon's ordinal, and the shader divides that
+        // by the grid size to place it.
+        const capacity = Math.max(this._photonCount, this._photonCapacity * 2);
+        const indices = new Float32Array(capacity);
+        for(let i = 0; i < capacity; i++){
+            indices[i] = i;
+        }
+        // WebGL2 refuses to draw without a bound vertex layout, so the ordinal is
+        // materialised as an attribute rather than read from the vertex index.
+        const buffer = device.createVertexBuffer('position_f32', indices);
+        this._photonLayout?.dispose();
+        this._photonBuffer?.dispose();
+        this._photonBuffer = buffer;
+        this._photonLayout = device.createVertexLayout({
+            vertexBuffers: [
+                {
+                    buffer
+                }
+            ]
+        });
+        this._photonCapacity = capacity;
+    }
+    /** @internal */ _getSplatStates(device) {
+        if (!this._splatStates) {
+            this._splatStates = device.createRenderStateSet();
+            this._splatStates.useRasterizerState().setCullMode('none');
+            this._splatStates.useDepthState().enableTest(false).enableWrite(false);
+            // Photon accumulation: every splat adds to whatever is already there.
+            this._splatStates.useBlendingState().enable(true).setBlendFunc('one', 'one').setBlendEquation('add', 'add');
+        }
+        return this._splatStates;
+    }
+    /** @internal */ _getHeightStates(device, slot) {
+        let states = this._heightStates[slot];
+        if (!states) {
+            states = device.createRenderStateSet();
+            states.useRasterizerState().setCullMode('none');
+            states.useDepthState().enableTest(false).enableWrite(false);
+            // Plain overwrite into this slot's channel only. Blending would add the
+            // heights wherever the surface overlaps itself in the light's view.
+            states.useColorState().setColorMask(slot === 0, slot === 1, slot === 2, slot === 3);
+            this._heightStates[slot] = states;
+        }
+        return states;
+    }
+    /** @internal */ _getHeightProgram(device, waveGenerator) {
+        const key = waveGenerator.getHash();
+        let info = this._heightPrograms.get(key);
+        if (info) {
+            return info;
+        }
+        const program = device.buildRenderProgram(createCausticHeightShader(waveGenerator));
+        program.name = '@Water_CausticHeight';
+        info = {
+            program,
+            bindGroups: []
+        };
+        this._heightPrograms.set(key, info);
+        return info;
+    }
+    /** @internal */ _getBlurStates(device) {
+        if (!this._blurStates) {
+            this._blurStates = device.createRenderStateSet();
+            this._blurStates.useRasterizerState().setCullMode('none');
+            this._blurStates.useDepthState().enableTest(false).enableWrite(false);
+        }
+        return this._blurStates;
+    }
+    /** @internal */ _getSplatProgram(device, waveGenerator, sceneDepth) {
+        const key = `${waveGenerator.getHash()}:${sceneDepth ? 1 : 0}`;
+        let info = this._splatPrograms.get(key);
+        if (info) {
+            return info;
+        }
+        const program = device.buildRenderProgram(createCausticSplatShader(waveGenerator, sceneDepth));
+        program.name = `@Water_CausticSplat${sceneDepth ? '_SceneDepth' : ''}`;
+        info = {
+            program,
+            bindGroups: []
+        };
+        this._splatPrograms.set(key, info);
+        return info;
+    }
+    /**
+   * The bind group for one water slot of a splat program.
+   * @internal
+   */ _getSplatBindGroup(device, info, slot) {
+        let bindGroup = info.bindGroups[slot];
+        if (!bindGroup) {
+            bindGroup = device.createBindGroup(info.program.bindGroupLayouts[0]);
+            info.bindGroups[slot] = bindGroup;
+        }
+        return bindGroup;
+    }
+    /**
+   * Whether any body asks for the scene-depth intersection, which decides
+   * whether the shadow cascade needs resolving at all.
+   * @internal
+   */ _anySceneDepth(waters) {
+        return waters.some((w)=>w.material.causticsSceneDepth);
+    }
+    /** @internal */ _getBlurProgram(device) {
+        if (!this._blurProgram) {
+            this._blurProgram = device.buildRenderProgram(createCausticBlurShader());
+            this._blurProgram.name = '@Water_CausticBlur';
+            this._blurBindGroup = device.createBindGroup(this._blurProgram.bindGroupLayouts[0]);
+        }
+        return this._blurProgram;
+    }
+}
+
+export { WaterCausticsRenderer, createCausticBlurShader, createCausticHeightShader, createCausticResolveShader, createCausticSplatShader };
+//# sourceMappingURL=water_caustics.js.map