@zephyr3d/scene 0.9.26 → 0.9.27

package/dist/material/shader/helper.js

@@ -17,6 +17,28 @@ const UNIFORM_NAME_SKYDISTANTLIGHT_LUT = 'Z_UniformSkyDistantLightLUT';
 const UNIFORM_NAME_SHADOW_MAP = 'Z_UniformShadowMap';
 const UNIFORM_NAME_SHADOW_MASK = 'Z_UniformShadowMask';
 const UNIFORM_NAME_SHADOW_MASK_MODE = 'Z_UniformShadowMaskMode';
+const UNIFORM_NAME_CAUSTIC_MAP = 'Z_UniformCausticMap';
+const UNIFORM_NAME_CAUSTIC_HEIGHT_MAP = 'Z_UniformCausticHeightMap';
+/**
+ * Offset added to a surface height before it is stored in the caustic height
+ * map, so that a cleared texel - no surface on that ray - is distinguishable
+ * from a surface at the rest level. A ray with no water on it must read as
+ * dry, not as submerged under a flat surface: on the down-sun side of a
+ * footprint edge, a receiver below the rest level but above a trough would
+ * otherwise be lit through water that is not there. Eight keeps troughs down
+ * to seven metres positive and leaves half floats millimetre precision.
+ * @internal
+ */ const CAUSTIC_HEIGHT_BIAS = 8;
+/**
+ * Water bodies that can cast caustics into one map.
+ *
+ * They share the map and the slice, so this is not a limit on how much water a
+ * scene may hold - only on how many separate surfaces the receiver will test
+ * itself against, which it does per fragment. Four covers a lake with a couple
+ * of pools beside it; beyond that the renderer keeps the largest four, which
+ * are the ones a viewer is most likely to be standing over.
+ */ const MAX_CAUSTIC_WATERS = 4;
+const UNIFORM_NAME_CAUSTIC_PARAMS = 'Z_UniformCausticParams';
 const UNIFORM_NAME_LINEAR_DEPTH_MAP = 'Z_UniformLinearDepth';
 const UNIFORM_NAME_LINEAR_DEPTH_MAP_SIZE = 'Z_UniformLinearDepthSize';
 const UNIFORM_NAME_SCENE_COLOR_MAP = 'Z_UniformSceneColor';
@@ -294,6 +316,9 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
                 }
                 scope[UNIFORM_NAME_SHADOW_MAP] = tex.uniform(0);
             }
+            if (this.usesWaterCaustics(ctx)) {
+                this.declareWaterCausticUniforms(pb);
+            }
             if (ctx.drawEnvLight) {
                 ctx.env.light.envLight.initShaderBindings(pb, ctx);
             }
@@ -304,8 +329,18 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
                 scope[UNIFORM_NAME_LINEAR_DEPTH_MAP_SIZE] = pb.vec2().uniform(0);
             }
             if (ctx.sceneColorTexture) {
-                // Scene color copy: single mip level
-                scope[UNIFORM_NAME_SCENE_COLOR_MAP] = pb.tex2D().uniform(0).withSampler(getSamplerOptions('clamp_linear_nomip'));
+                // Mip-filtered, because the refraction background is read at a LOD and
+                // not only at mip 0: the water picks one from how deep and how turbid
+                // the column it is looking through is. A `nomip` sampler pins mip 0
+                // whatever LOD the shader passes, so this and the copy's level count
+                // have to change together - and each backend only honours one of them.
+                // WebGPU binds the sampler declared here as a static binding the runtime
+                // cannot overwrite; WebGL falls back to the texture's own sampler, whose
+                // mip filter follows its level count.
+                //
+                // Every other reader of this texture passes an explicit LOD 0 (SSR hits,
+                // the sky blend), so none of them changes behaviour.
+                scope[UNIFORM_NAME_SCENE_COLOR_MAP] = pb.tex2D().uniform(0).withSampler(getSamplerOptions('clamp_linear'));
                 scope[UNIFORM_NAME_SCENE_COLOR_MAP_SIZE] = pb.vec2().uniform(0);
             }
             if (ctx.HiZTexture) {
@@ -1091,10 +1126,329 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
             bindGroup.setTexture(UNIFORM_NAME_SHADOW_MASK, ctx.shadowMaskTexture ?? this.getDummyShadowMask(ctx.device), fetchSampler('clamp_nearest'));
         }
         bindGroup.setTexture(UNIFORM_NAME_BAKED_SKY_MAP, ctx.scene.env.sky.getBakedSkyTexture(ctx));
+        if (this.usesWaterCaustics(ctx)) {
+            this.setWaterCausticUniforms(bindGroup, ctx);
+        }
         if (ctx.drawEnvLight) {
             ctx.env.light.envLight.updateBindGroup(bindGroup, ctx);
         }
     }
+    /**
+   * Whether the pass being built modulates its light with the water caustic map.
+   *
+   * True for every light pass of a frame that produced a map; which light the
+   * caustics actually attach to is decided per-fragment by
+   * {@link ShaderHelper.calculateWaterCaustic}. Both the shader variant hash and
+   * the global bind group hash fold this in, so a program that declares the
+   * caustic uniforms is always paired with a bind group that supplies them.
+   *
+   * Deliberately a function of the draw context alone, with no material input.
+   * The caustic uniforms sit in the global bind group, whose layout is built
+   * once per {@link DrawContext.renderPassHash} and shared by every material in
+   * the pass, so the declarations have to be uniform across the pass. A material
+   * that must not receive caustics - water itself - opts out of the sampling
+   * instead, through `receivesWaterCaustics()`; the uniforms stay declared and
+   * simply go unread.
+   *
+   * @param ctx - Current draw context.
+   * @returns True when the caustic uniforms take part in this pass.
+   * @internal
+   */ static usesWaterCaustics(ctx) {
+        return !!ctx.waterCaustics && !!ctx.waterCausticLight && ctx.renderPass.type === RENDER_PASS_TYPE_LIGHT;
+    }
+    /**
+   * Declares the global uniforms {@link ShaderHelper.calculateWaterCaustic} reads.
+   *
+   * Split out of the global uniform setup so a test can build a program that
+   * exercises the sampling code without standing up a whole light pass.
+   *
+   * @param pb - Program builder whose global scope receives the uniforms.
+   * @internal
+   */ /**
+   * Warps a linear caustic-map coordinate so texels concentrate near the centre.
+   *
+   * The map covers a fixed footprint, so its world texel size is the range
+   * divided by the resolution and a range large enough to light the scene is
+   * already too coarse to resolve a caustic cell. This trades the edge of the
+   * map, which is far from the camera, for the middle, which is not:
+   *
+   * ```
+   * warp(u)   = u (1 + k) / (1 + k |u|)
+   * unwarp(w) = w / ((1 + k) - k |w|)
+   * ```
+   *
+   * Texel density is `1 + k` times uniform at the centre and `1 / (1 + k)` times
+   * it at the border, and `k = 0` is exactly the identity, so the pass can apply
+   * this unconditionally. Both ends of `[-1, 1]` are fixed points, which is what
+   * lets the warp sit inside the existing parameterisation without moving the
+   * footprint the receiver gates on. The first derivative is continuous at the
+   * centre; the second flips sign there, which is not visible in a pattern this
+   * noisy.
+   *
+   * Applied per axis rather than radially: the photon grid, the map and the blur
+   * are all axis-aligned, so a separable warp keeps photon `(i,j)` on texel
+   * `(i,j)` for calm water and leaves the map's normalisation to 1.0 intact.
+   *
+   * @param scope - Current shader scope.
+   * @param ndc - Linear map coordinate in `[-1, 1]`.
+   * @param strength - Warp strength `k`; 0 is the identity.
+   * @returns The warped coordinate, also in `[-1, 1]`.
+   * @internal
+   */ static warpCausticNDC(scope, ndc, strength) {
+        const pb = scope.$builder;
+        const funcName = 'Z_warpCausticNDC';
+        pb.func(funcName, [
+            pb.vec2('ndc'),
+            pb.float('k')
+        ], function() {
+            this.$return(pb.div(pb.mul(this.ndc, pb.add(this.k, 1)), pb.add(pb.vec2(1), pb.mul(pb.abs(this.ndc), this.k))));
+        });
+        return pb.getGlobalScope()[funcName](ndc, strength);
+    }
+    /**
+   * Inverse of {@link ShaderHelper.warpCausticNDC}.
+   *
+   * The denominator is `1` at the border and `1 + k` at the centre, so it stays
+   * positive for any input the passes feed it - all of which come from `[-1, 1]`.
+   *
+   * @param scope - Current shader scope.
+   * @param warped - Warped map coordinate in `[-1, 1]`.
+   * @param strength - Warp strength `k`; 0 is the identity.
+   * @returns The linear coordinate the warp came from.
+   * @internal
+   */ static unwarpCausticNDC(scope, warped, strength) {
+        const pb = scope.$builder;
+        const funcName = 'Z_unwarpCausticNDC';
+        pb.func(funcName, [
+            pb.vec2('warped'),
+            pb.float('k')
+        ], function() {
+            this.$return(pb.div(this.warped, pb.sub(pb.vec2(pb.add(this.k, 1)), pb.mul(pb.abs(this.warped), this.k))));
+        });
+        return pb.getGlobalScope()[funcName](warped, strength);
+    }
+    /** @internal */ static declareWaterCausticUniforms(pb) {
+        const scope = pb.getGlobalScope();
+        const causticStruct = pb.defineStruct([
+            pb.vec4('frameX'),
+            pb.vec4('frameY'),
+            pb.vec4('center'),
+            pb.vec4('lightDir'),
+            pb.vec4('params'),
+            pb.vec4('extinction'),
+            // Per water body, because the slice is shared but the water is not: each
+            // has its own surface height, footprint and medium, and none of the three
+            // means anything until a receiver has resolved which water is above it.
+            pb.int('waterCount'),
+            pb.vec4[MAX_CAUSTIC_WATERS]('waterRegions'),
+            // (sigma_t.xyz, surface height)
+            pb.vec4[MAX_CAUSTIC_WATERS]('waterMedia')
+        ]);
+        scope[UNIFORM_NAME_CAUSTIC_PARAMS] = causticStruct().uniform(0);
+        // The map is single mip and read bilinearly; clamping keeps receivers
+        // outside the covered area reading the border rather than wrapping.
+        scope[UNIFORM_NAME_CAUSTIC_MAP] = pb.tex2D().uniform(0).withSampler(getSamplerOptions('clamp_linear_nomip'));
+        // Displaced surface height per water slot, on the same slice as the map.
+        // Read with the map's uv, so it shares the map's sampling.
+        scope[UNIFORM_NAME_CAUSTIC_HEIGHT_MAP] = pb.tex2D().uniform(0).withSampler(getSamplerOptions('clamp_linear_nomip'));
+    }
+    /**
+   * Attenuation the water caustics apply to one light at a world position.
+   *
+   * Returns the product of two effects: the caustic pattern focused by the waves,
+   * and the Beer-Lambert transmittance of the water column the light travelled
+   * through to reach the point. The result is 1 for any light that is not the
+   * caustic light, above the surface, and outside the water region, so the caller
+   * can multiply unconditionally.
+   *
+   * The caustic light is identified at runtime by comparing directions rather
+   * than by which pass is running. Shadow-casting lights reach the opaque queue
+   * through the clustered path when the screen-space shadow mask is on (the
+   * default) and through a per-light additive pass when it is off; only a runtime
+   * test covers both. Two directional lights pointing the same way would both
+   * pick up the caustics, but they are physically the same light.
+   *
+   * @param scope - Current shader scope.
+   * @param worldPos - World position of the shaded fragment.
+   * @param lightType - The light's type constant.
+   * @param lightDirection - Direction the light travels, i.e. `directionAndCutoff.xyz`.
+   * @param ctx - Current draw context.
+   * @returns A `vec3` multiplier, or null when this pass has no caustics.
+   */ static calculateWaterCaustic(scope, worldPos, lightType, lightDirection, ctx) {
+        if (!this.usesWaterCaustics(ctx)) {
+            return null;
+        }
+        return this.sampleWaterCaustic(scope, worldPos, lightType, lightDirection);
+    }
+    /**
+   * {@link ShaderHelper.calculateWaterCaustic} without the pass gate.
+   *
+   * The gate asks whether the *light pass* has caustics, which is the right
+   * question for a material and the wrong one for a standalone full-screen pass
+   * that declared the same uniforms itself. Such a pass has already decided it
+   * has a map; this is the sampling half on its own.
+   *
+   * @param scope - Current shader scope.
+   * @param worldPos - World position of the shaded fragment.
+   * @param lightType - The light's type constant.
+   * @param lightDirection - Direction the light travels, i.e. `directionAndCutoff.xyz`.
+   * @param defocus - Whether to fade the pattern's contrast by how far the point
+   * is from the map's focal depth. True for a receiver surface, which is what
+   * that fade describes. False for a point inside the water column: see the
+   * comment on the term itself.
+   * @returns A `vec3` multiplier.
+   * @internal
+   */ static sampleWaterCaustic(scope, worldPos, lightType, lightDirection, defocus = true) {
+        const pb = scope.$builder;
+        const funcName = defocus ? 'Z_calculateWaterCaustic' : 'Z_calculateWaterCausticVolume';
+        pb.func(funcName, [
+            pb.vec3('worldPos'),
+            pb.int('lightType'),
+            pb.vec3('lightDirection')
+        ], function() {
+            this.$l.cu = this[UNIFORM_NAME_CAUSTIC_PARAMS];
+            // Only the one light the map was built for casts caustics.
+            this.$if(pb.or(pb.notEqual(this.lightType, LIGHT_TYPE_DIRECTIONAL), pb.lessThan(pb.dot(this.lightDirection, this.cu.lightDir.xyz), 0.999)), function() {
+                this.$return(pb.vec3(1));
+            });
+            // Project into the map: frameX/frameY are orthonormal and perpendicular to
+            // the light, so the same two dot products the splat pass used invert it.
+            this.$l.rel = pb.sub(this.worldPos, this.cu.center.xyz);
+            // Per-axis inverse extents: the slice is fitted to the water, so it is
+            // only square in texels, not in meters.
+            this.$l.mapNDC = pb.mul(pb.vec2(pb.dot(this.rel, this.cu.frameX.xyz), pb.dot(this.rel, this.cu.frameY.xyz)), pb.vec2(this.cu.frameX.w, this.cu.frameY.w));
+            // Texels are concentrated towards the middle of the map, so the lookup
+            // goes through the same warp the splat laid the photons out under.
+            this.$l.warpedNDC = ShaderHelper.warpCausticNDC(this, this.mapNDC, this.cu.extinction.w);
+            this.$l.uv = pb.add(pb.mul(this.warpedNDC, 0.5), pb.vec2(0.5));
+            // The displaced surface height of each water slot on this fragment's own
+            // sun ray, biased by CAUSTIC_HEIGHT_BIAS. The height map rasterises the
+            // displaced surface into the same light-space slice as the pattern, so
+            // the texel under this uv holds the surface the ray through this fragment
+            // passed through - no entry point has to be estimated. Beyond the map the
+            // sampler would repeat its border, which is some other ray's wave; the
+            // surface is taken as flat there.
+            this.$l.insideMap = pb.all(pb.lessThanEqual(pb.abs(this.mapNDC), pb.vec2(1)));
+            // How far this fragment is towards the map border, and how much the map is
+            // therefore trusted. Hoisted above the water loop because the wave height
+            // is faded by it too, not just the pattern.
+            //
+            // Measured on the linear coordinate, not the warped one. The warp fixes
+            // both ends of [-1, 1], so the border is in the same world place either
+            // way, but the band between them is not: warping it would make its world
+            // width depend on the warp strength, and the CPU sized it in meters.
+            //
+            // Distance is measured under an L4 norm rather than per-axis. A per-axis
+            // fade is a rectangle in light space, and the sun tilts that rectangle, so
+            // its border lands on the sea bed as straight lines - which the eye picks
+            // out of a caustic pattern however wide the gradient is. An L2 circle has
+            // no straight part anywhere but discards the 21% of the map outside its
+            // inscribed disc; L4 gives up 7% instead and still curves everywhere.
+            this.$l.ndcSq = pb.mul(this.mapNDC, this.mapNDC);
+            this.$l.edgeDist = pb.sqrt(pb.sqrt(pb.dot(this.ndcSq, this.ndcSq)));
+            this.$l.edge = pb.sub(1, pb.smoothStep(this.cu.params.w, 1, this.edgeDist));
+            this.$l.waveHeights = pb.textureSampleLevel(this[UNIFORM_NAME_CAUSTIC_HEIGHT_MAP], this.uv, 0);
+            // Find the water above this point. Several can qualify - a pool inside a
+            // lake, water on terraces - and the one that matters is the lowest of
+            // them, because that is the last surface the sun crossed on its way here.
+            this.$l.depth = pb.float(-1);
+            this.$l.medium = pb.vec3(0);
+            this.$for(pb.int('i'), 0, MAX_CAUSTIC_WATERS, function() {
+                this.$if(pb.greaterThanEqual(this.i, this.cu.waterCount), function() {
+                    this.$break();
+                });
+                this.$l.slotMedium = this.cu.waterMedia.at(this.i);
+                // Where the sun ray that lights this point crossed that water's rest
+                // plane, for the footprint test. The splat pass clips photons by that
+                // same crossing, so the receiver must ask the same question: a point
+                // under the footprint that the sun reaches from outside it saw no water
+                // at all, and a point beyond the footprint that the sun reaches through
+                // it did. Testing the point's own xz gets both wrong by the offset
+                // depth / tan(elevation). Only the footprint is decided here; the depth
+                // itself comes from the height map, which needs no crossing point.
+                this.$l.slotFlat = pb.sub(this.slotMedium.w, this.worldPos.y);
+                this.$l.slotPath = pb.mul(this.slotFlat, this.cu.lightDir.w);
+                this.$l.slotEntry = pb.sub(this.worldPos.xz, pb.mul(this.cu.lightDir.xz, this.slotPath));
+                this.$l.slotRegion = this.cu.waterRegions.at(this.i);
+                this.$if(pb.and(pb.all(pb.greaterThanEqual(this.slotEntry, this.slotRegion.xy)), pb.all(pb.lessThanEqual(this.slotEntry, this.slotRegion.zw))), function() {
+                    // Depth under the *displaced* surface on this ray, which is what
+                    // the splat refracted the photons through. Gating on the rest plane
+                    // instead cut the caustics off at a flat line across any receiver
+                    // that pokes above it under a crest. Slot i lives in channel i.
+                    this.$l.slotMask = pb.vec4(pb.float(pb.equal(this.i, 0)), pb.float(pb.equal(this.i, 1)), pb.float(pb.equal(this.i, 2)), pb.float(pb.equal(this.i, 3)));
+                    this.$l.slotSample = pb.dot(this.waveHeights, this.slotMask);
+                    // A cleared texel inside the map means this ray never meets that
+                    // body's surface - it crosses the rest plane beyond the footprint,
+                    // or the surface is on the far side of the receiver - and the
+                    // receiver is dry as far as this body is concerned. Outside the map
+                    // nothing is known and the surface is taken as flat.
+                    this.$l.slotCovered = pb.or(pb.not(this.insideMap), pb.greaterThan(this.slotSample, 0.5));
+                    this.$if(this.slotCovered, function() {
+                        // Faded into the rest plane over the same band the pattern fades
+                        // on, rather than switched off at the border. Beyond the map the
+                        // surface is taken as flat, and exp(-sigma * depth) is convex, so
+                        // a hard switch makes the wavy side systematically brighter than
+                        // the flat side - E[exp(-sigma*w)] > 1 - and the step lands as a
+                        // mean brightness seam that grows with both the swell and the
+                        // turbidity. Ramping the wave to zero puts the two sides on the
+                        // same value at the border.
+                        this.$l.slotWave = pb.mul(pb.sub(this.slotSample, CAUSTIC_HEIGHT_BIAS), pb.float(this.insideMap), this.edge);
+                        this.$l.slotDepth = pb.sub(pb.add(this.slotMedium.w, this.slotWave), this.worldPos.y);
+                        this.$if(pb.greaterThan(this.slotDepth, 0), function() {
+                            this.$if(pb.or(pb.lessThan(this.depth, 0), pb.lessThan(this.slotDepth, this.depth)), function() {
+                                this.depth = this.slotDepth;
+                                this.medium = this.slotMedium.xyz;
+                            });
+                        });
+                    });
+                });
+            });
+            this.$if(pb.lessThanEqual(this.depth, 0), function() {
+                this.$return(pb.vec3(1));
+            });
+            this.$l.pathLength = pb.mul(this.depth, this.cu.lightDir.w);
+            this.$l.transmittance = pb.exp(pb.neg(pb.mul(this.medium, this.pathLength)));
+            this.$l.pattern = pb.textureSampleLevel(this[UNIFORM_NAME_CAUSTIC_MAP], this.uv, 0).x;
+            if (defocus) {
+                // Receivers away from the focal plane see a defocused, lower-contrast
+                // pattern rather than a displaced one.
+                this.$l.defocus = pb.div(1, pb.add(1, pb.mul(pb.abs(pb.sub(this.depth, this.cu.params.y)), this.cu.params.z)));
+            } else {
+                // A point inside the water column is not a receiver, and has no depth of
+                // its own to be out of focus at - the volumetric march visits every
+                // depth along the ray. Charging it the receiver's fade makes the light
+                // shafts fade according to where the *sea bed* was told to be sharpest:
+                // the open-ocean preset focuses the map at 26m for its bed, which at the
+                // default defocus leaves a point 2m down at 26% contrast, and the shafts
+                // dissolve into grain. The shafts instead take the pattern as the map
+                // holds it and fade with the edge and the transmittance like everything
+                // else in the column.
+                this.$l.defocus = pb.float(1);
+            }
+            this.$l.weight = pb.mul(this.cu.params.x, this.defocus, this.edge);
+            this.$l.caustic = pb.add(1, pb.mul(pb.sub(this.pattern, 1), this.weight));
+            // Soften the waterline so the transmittance does not switch on abruptly.
+            this.$l.submerged = pb.smoothStep(0, 0.05, this.depth);
+            this.$return(pb.mix(pb.vec3(1), pb.mul(pb.vec3(this.caustic), this.transmittance), this.submerged));
+        });
+        return pb.getGlobalScope()[funcName](worldPos, lightType, lightDirection);
+    }
+    /** @internal */ static setWaterCausticUniforms(bindGroup, ctx) {
+        const uniforms = ctx.waterCausticUniforms;
+        bindGroup.setValue(UNIFORM_NAME_CAUSTIC_PARAMS, {
+            frameX: uniforms.frameX,
+            frameY: uniforms.frameY,
+            center: uniforms.center,
+            lightDir: uniforms.lightDir,
+            params: uniforms.params,
+            extinction: uniforms.extinction,
+            waterCount: uniforms.waterCount,
+            waterRegions: uniforms.waterRegions,
+            waterMedia: uniforms.waterMedia
+        });
+        bindGroup.setTexture(UNIFORM_NAME_CAUSTIC_MAP, ctx.waterCausticTexture, fetchSampler('clamp_linear_nomip'));
+        bindGroup.setTexture(UNIFORM_NAME_CAUSTIC_HEIGHT_MAP, ctx.waterCausticHeightTexture, fetchSampler('clamp_linear_nomip'));
+    }
     /** @internal */ static setLightUniformsShadow(bindGroup, ctx, light) {
         const shadowMapParams = ctx.shadowMapInfo.get(light);
         this._lightUniformShadow.sunDir = ctx.sunLight ? ctx.sunLight.directionAndCutoff.xyz().scaleBy(-1) : this.defaultSunDir;
@@ -1114,6 +1468,9 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
         this._lightUniformShadow.envLightSpecularStrength = ctx.env?.light.specularStrength ?? 1;
         bindGroup.setValue('light', this._lightUniformShadow);
         bindGroup.setTexture(UNIFORM_NAME_SHADOW_MAP, shadowMapParams.shadowMap, shadowMapParams.shadowMapSampler);
+        if (this.usesWaterCaustics(ctx)) {
+            this.setWaterCausticUniforms(bindGroup, ctx);
+        }
         bindGroup.setTexture(UNIFORM_NAME_BAKED_SKY_MAP, ctx.scene.env.sky.getBakedSkyTexture(ctx));
         if (ctx.drawEnvLight) {
             ctx.env.light.envLight.updateBindGroup(bindGroup, ctx);
@@ -1235,6 +1592,50 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
         return scope.camera.elapsedTime;
     }
     /**
+   * Declares the one camera field {@link ShaderHelper.getElapsedTime} reads.
+   *
+   * Wave generators animate off `camera.elapsedTime`, which the light and depth
+   * passes provide as part of the full camera struct. A standalone program that
+   * drives a wave generator - the caustics splat pass - has no such struct, so it
+   * declares that single field under the same name. Any generator that starts
+   * reading a second camera field will need it added here.
+   *
+   * The three padding floats round the struct up to 16 bytes. std140 aligns a
+   * struct to a vec4 boundary, so a lone float leaves the GLSL block larger than
+   * the buffer the engine sizes from the struct's own members - WebGL2 then
+   * rejects every draw with "uniform buffer that is too small" and rasterises
+   * nothing, while WebGPU is unaffected.
+   *
+   * @param scope - Global scope of the standalone program.
+   * @param uniformGroup - Bind group the uniform belongs to.
+   * @internal
+   */ static declareStandaloneCameraTime(scope, uniformGroup) {
+        const pb = scope.$builder;
+        scope.camera = pb.defineStruct([
+            pb.float('elapsedTime'),
+            pb.float('_pad0'),
+            pb.float('_pad1'),
+            pb.float('_pad2')
+        ])().uniform(uniformGroup);
+    }
+    /**
+   * Uploads the value declared by {@link ShaderHelper.declareStandaloneCameraTime}.
+   *
+   * Must be the same clock the light pass uses, or a wave generator's caustics
+   * would animate out of step with the surface they are refracted through.
+   *
+   * @param bindGroup - Bind group of the standalone program.
+   * @param ctx - Current draw context.
+   * @internal
+   */ static setStandaloneCameraTime(bindGroup, ctx) {
+        bindGroup.setValue('camera', {
+            elapsedTime: ctx.device.frameInfo.elapsedOverall * 0.001,
+            _pad0: 0,
+            _pad1: 0,
+            _pad2: 0
+        });
+    }
+    /**
    * Gets the elapsed time since last frame in seconds
    * @param scope - Current shader scope
    * @returns The elapsed time since last frame in seconds
@@ -1865,5 +2266,5 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
     }
 }
 
-export { ShaderHelper };
+export { CAUSTIC_HEIGHT_BIAS, MAX_CAUSTIC_WATERS, ShaderHelper };
 //# sourceMappingURL=helper.js.map