@zephyr3d/scene 0.9.26 → 0.10.0

package/dist/render/underwater.js

@@ -0,0 +1,524 @@
+import { Vector4, Vector3, DEPTH_FARTHEST } from '@zephyr3d/base';
+import { ShaderHelper } from '../material/shader/helper.js';
+import { waterScatterPhase } from '../shaders/water_medium.js';
+import { LIGHT_TYPE_DIRECTIONAL } from '../values.js';
+import { interleavedGradientNoise } from '../shaders/noise.js';
+import { SkyRenderer } from './sky.js';
+import { fetchSampler } from '../utility/misc.js';
+import { drawFullscreenQuad } from './fullscreenquad.js';
+
+/**
+ * Which waters each camera is currently inside, and the rest plane of each.
+ *
+ * Written by {@link Water.updatePerCamera}, which runs for every water every
+ * frame whether or not the surface survived culling, so the state survives the
+ * surface leaving the frustum.
+ *
+ * Keyed on the camera so multiple views stay independent. Entries of disposed
+ * waters are pruned on read.
+ *
+ * @internal
+ */ const _submergence = new WeakMap();
+/**
+ * Record whether `camera` is inside `water` this frame.
+ *
+ * @param camera - Camera being updated.
+ * @param water - Water reporting its own state.
+ * @param submerged - Whether the camera is inside this body.
+ * @param surfaceY - World Y of the water's rest plane.
+ * @internal
+ */ function setWaterSubmergence(camera, water, submerged, surfaceY) {
+    let bodies = _submergence.get(camera);
+    if (submerged) {
+        if (!bodies) {
+            bodies = new Map();
+            _submergence.set(camera, bodies);
+        }
+        bodies.set(water, surfaceY);
+    } else if (bodies) {
+        bodies.delete(water);
+    }
+}
+/**
+ * The water the camera is currently inside, or null when it is above all of them.
+ *
+ * When several qualify, the highest wins: it is the last surface the eye crossed
+ * on its way down.
+ *
+ * @param ctx - Frame draw context.
+ * @returns The submerged state, or null.
+ * @internal
+ */ function selectUnderwaterSource(ctx) {
+    const bodies = _submergence.get(ctx.camera);
+    if (!bodies || bodies.size === 0) {
+        return null;
+    }
+    let best = null;
+    let bestY = 0;
+    for (const [water, surfaceY] of bodies){
+        // A node disposed since its last update never clears its own entry.
+        if (water.disposed) {
+            bodies.delete(water);
+            continue;
+        }
+        if (!best || surfaceY > bestY) {
+            best = water;
+            bestY = surfaceY;
+        }
+    }
+    const material = best?.material;
+    if (!best || !material || !material.underwaterEnabled) {
+        return null;
+    }
+    return {
+        water: best,
+        material,
+        surfaceY: bestY,
+        eyeDepth: Math.max(0, bestY - ctx.camera.getWorldPosition().y)
+    };
+}
+/**
+ * Optical depth at which a channel is taken to have died completely.
+ *
+ * exp(-30) is about 1e-13, zero in any scene color format. The path length is
+ * capped at the distance reaching this on the least attenuated channel.
+ * @internal
+ */ const OPTICAL_DEPTH_CAP = 30;
+/**
+ * Global name of the shadow map the receiver helpers sample.
+ *
+ * Must match the name `ShaderHelper` declares and the shadow implementation's
+ * `computeShadow` reads.
+ * @internal
+ */ const SHADOW_MAP_UNIFORM = 'Z_UniformShadowMap';
+/**
+ * Composites the water body a submerged camera is looking through.
+ *
+ * Two draws over the opaque scene, both in place on the scene color target:
+ *
+ * 1. multiply by the medium's transmittance, then
+ * 2. add what the medium scatters back towards the eye.
+ *
+ * Two draws because the transmittance is per channel and a single blend equation
+ * only has a scalar `src-alpha`; the first draw uses `src-color` as the
+ * destination factor.
+ *
+ * The pass runs after the sky and treats a sky pixel as a ray that never left
+ * the water: its path length is the cap, so the horizon is pure medium.
+ *
+ * @internal
+ */ class UnderwaterRenderer {
+    /** Multiplies the scene by the medium transmittance. */ _extinctionProgram;
+    _extinctionBindGroup;
+    _extinctionStates;
+    /**
+   * Adds what the medium scatters towards the eye. Two variants: ambient alone,
+   * and ambient plus a march for the sun shafts. Keyed on the step count as well
+   * as on whether the shafts are on, because the loop is unrolled at that count.
+   */ _inscatterPrograms;
+    _inscatterStates;
+    /** (ambientScale, surfaceY, maxPathLength, godRayIntensity) */ _params;
+    /** (scatterAnisotropy, unused, unused, unused) */ _phaseParams;
+    _extinction;
+    _albedo;
+    _sunDir;
+    _sunColor;
+    /** Shadow receiver uniforms, only touched while the shafts are shadowed. */ _cameraPosition;
+    _cameraParams;
+    _implParams;
+    _cameraForward;
+    /** Reused scratch copy of the cascade matrices for the uniform setter. */ _shadowMatrices;
+    constructor(){
+        this._extinctionProgram = null;
+        this._extinctionBindGroup = null;
+        this._extinctionStates = null;
+        this._inscatterPrograms = new Map();
+        this._inscatterStates = null;
+        this._params = new Vector4();
+        this._phaseParams = new Vector4();
+        this._extinction = new Vector3();
+        this._albedo = new Vector3();
+        this._sunDir = new Vector3();
+        this._sunColor = new Vector3();
+        this._cameraPosition = new Vector4();
+        this._cameraParams = new Vector4();
+        this._implParams = new Vector4();
+        this._cameraForward = new Vector4();
+        this._shadowMatrices = null;
+    }
+    /**
+   * Composite the medium over the opaque scene.
+   *
+   * @param ctx - Frame draw context.
+   * @param state - The water the camera is inside.
+   * @param colorFramebuffer - Color-only target holding the opaque scene and the
+   * sky. The depth attachment is deliberately absent: this pass samples the
+   * scene depth, which it could not do while that texture is still attached.
+   * @param depthTexture - Scene depth attachment, sampled for the path length.
+   */ render(ctx, state, colorFramebuffer, depthTexture) {
+        const device = ctx.device;
+        const material = state.material;
+        // Shafts need the caustic map and its sun; without them only the ambient term
+        // is drawn.
+        const sun = ctx.waterCausticLight;
+        const godRays = material.underwaterGodRays && !!ctx.waterCaustics && !!sun && material.underwaterGodRayIntensity > 0;
+        const steps = godRays ? material.underwaterGodRaySteps : 0;
+        const shadowMapParams = godRays && material.underwaterGodRayShadow ? ctx.shadowMapInfo?.get(sun) ?? null : null;
+        const shadow = shadowMapParams?.shadowMap ? shadowMapParams : null;
+        const { extinctionPass, inscatterPass } = this._prepare(device, steps, shadow);
+        const extinction = material.extinction;
+        this._extinction.set(extinction);
+        this._albedo.set(material.scatterAlbedo);
+        // Far enough that the least attenuated channel has died. A channel with no
+        // extinction at all has no such distance, and the far plane stands in.
+        const minExtinction = Math.min(extinction.x, extinction.y, extinction.z);
+        const far = ctx.camera.getFarPlane();
+        this._params.setXYZW(// The distant-sky LUT is baked exposure-independently, as everywhere else
+        // it is read from.
+        SkyRenderer.getBakeToPreExposedScale(ctx) * material.underwaterAmbientIntensity, state.surfaceY, minExtinction > 0 ? Math.min(far, OPTICAL_DEPTH_CAP / minExtinction) : far, godRays ? material.underwaterGodRayIntensity : 0);
+        this._phaseParams.setXYZW(material.scatterAnisotropy, 0, 0, 0);
+        if (sun) {
+            // Direction the light travels, matching what calculateWaterCaustic
+            // compares its own against.
+            const dir = sun.directionAndCutoff;
+            this._sunDir.setXYZ(dir.x, dir.y, dir.z);
+            const color = sun.diffuseAndIntensity;
+            // Pre-exposed, like every other radiance this pass adds to the scene.
+            const intensity = color.w * ShaderHelper.getPreExposure(ctx);
+            this._sunColor.setXYZ(color.x * intensity, color.y * intensity, color.z * intensity);
+        } else {
+            this._sunDir.setXYZ(0, -1, 0);
+            this._sunColor.setXYZ(0, 0, 0);
+        }
+        // Same rule the post effects use (AbstractPostEffect.needFlip): WebGPU's
+        // render target has the opposite vertical convention to the screen.
+        const flip = device.type === 'webgpu' && colorFramebuffer ? 1 : 0;
+        const nearestSampler = fetchSampler('clamp_nearest_nomip');
+        const skyLut = ctx.scene.env.sky.getSkyDistantLightLUT(ctx);
+        const invProjView = ctx.camera.invViewProjectionMatrix;
+        const cameraPos = ctx.camera.getWorldPosition();
+        const passes = [
+            extinctionPass,
+            inscatterPass
+        ];
+        device.pushDeviceStates();
+        try {
+            device.setFramebuffer(colorFramebuffer);
+            device.setViewport(null);
+            device.setScissor(null);
+            for (const pass of passes){
+                const bindGroup = pass.bindGroup;
+                bindGroup.setTexture('depthTex', depthTexture, nearestSampler);
+                bindGroup.setTexture('skyLut', skyLut, nearestSampler);
+                bindGroup.setValue('invProjViewMatrix', invProjView);
+                bindGroup.setValue('cameraPosition', cameraPos);
+                bindGroup.setValue('mediumExtinction', this._extinction);
+                bindGroup.setValue('mediumAlbedo', this._albedo);
+                bindGroup.setValue('params', this._params);
+                bindGroup.setValue('flip', flip);
+                if (pass === inscatterPass && godRays) {
+                    bindGroup.setValue('sunDirection', this._sunDir);
+                    bindGroup.setValue('sunColor', this._sunColor);
+                    bindGroup.setValue('phaseParams', this._phaseParams);
+                    // Same uniforms the lit materials bind, so the shafts and the caustics
+                    // on the sea bed are reading one map through one projection.
+                    ShaderHelper.setWaterCausticUniforms(bindGroup, ctx);
+                    if (shadow) {
+                        this._setShadowUniforms(bindGroup, ctx, sun, shadow);
+                    }
+                }
+                device.setProgram(pass.program);
+                device.setBindGroup(0, bindGroup);
+                drawFullscreenQuad(pass.states);
+            }
+        } finally{
+            device.popDeviceStates();
+        }
+    }
+    /**
+   * Upload the shadow receiver uniforms the march samples.
+   *
+   * Names and struct layouts match the material light pass's globals, which the
+   * shadow helpers read; see `ShadowMaskRenderer.setUniforms`.
+   * @internal
+   */ _setShadowUniforms(bindGroup, ctx, light, shadowMapParams) {
+        const camera = ctx.camera;
+        const near = camera.getNearPlane();
+        const far = camera.getFarPlane();
+        const cameraPos = camera.getWorldPosition();
+        this._cameraPosition.setXYZW(cameraPos.x, cameraPos.y, cameraPos.z, 0);
+        this._cameraParams.setXYZW(near, far, 1, 1);
+        bindGroup.setValue('camera', {
+            position: this._cameraPosition,
+            params: this._cameraParams,
+            shadowDebugCascades: camera.shadowDebugCascades ? 1 : 0,
+            framestamp: ctx.device.frameInfo.frameCounter
+        });
+        shadowMapParams.impl.getParams(this._implParams);
+        const matrices = shadowMapParams.shadowMatrices;
+        if (!this._shadowMatrices || this._shadowMatrices.length !== matrices.length) {
+            this._shadowMatrices = new Float32Array(matrices.length);
+        }
+        this._shadowMatrices.set(matrices);
+        bindGroup.setValue('light', {
+            sunDir: ctx.sunLight ? ctx.sunLight.directionAndCutoff.xyz().scaleBy(-1) : Vector3.axisPY(),
+            shadowCascades: shadowMapParams.numShadowCascades,
+            positionAndRange: light.positionAndRange,
+            directionAndCutoff: light.directionAndCutoff,
+            diffuseAndIntensity: ShaderHelper.getPreExposedColorIntensity(light, ctx),
+            extraParams: light.extraParams,
+            cascadeDistances: shadowMapParams.cascadeDistances,
+            depthBiasValues: shadowMapParams.depthBiasValues[0],
+            shadowCameraParams: shadowMapParams.cameraParams,
+            depthBiasScales: shadowMapParams.depthBiasScales,
+            implParams: this._implParams,
+            shadowMatrices: this._shadowMatrices,
+            shadowStrength: light.shadow.shadowStrength,
+            envLightStrength: ShaderHelper.getEnvLightLuminance(ctx),
+            envLightSpecularStrength: ctx.env?.light.specularStrength ?? 1
+        });
+        // Camera forward, for the cascade split test, which is measured in view
+        // depth rather than radial distance.
+        camera.worldMatrix.getRow(2, this._cameraForward);
+        this._cameraForward.scaleBy(-1);
+        bindGroup.setValue('cameraForward', this._cameraForward.xyz());
+        bindGroup.setTexture(SHADOW_MAP_UNIFORM, shadowMapParams.shadowMap, shadowMapParams.shadowMapSampler);
+    }
+    /**
+   * Build or fetch the two programs this frame needs.
+   *
+   * @param device - Rendering device.
+   * @param steps - Ray-march steps for the shafts, 0 for the ambient-only variant.
+   * @param shadow - Shadow params for the caustic light when the shafts should be
+   * occluded by geometry, null when they should not.
+   * @internal
+   */ _prepare(device, steps, shadow) {
+        if (!this._extinctionProgram) {
+            this._extinctionProgram = UnderwaterRenderer._createProgram(device, false, 0, null);
+            this._extinctionBindGroup = device.createBindGroup(this._extinctionProgram.bindGroupLayouts[0]);
+            this._extinctionStates = device.createRenderStateSet();
+            this._extinctionStates.useRasterizerState().setCullMode('none');
+            this._extinctionStates.useDepthState().enableTest(false).enableWrite(false);
+            // dst.rgb *= src.rgb (per-channel transmittance).
+            this._extinctionStates.useBlendingState().enable(true).setBlendFuncRGB('zero', 'src-color').setBlendFuncAlpha('zero', 'one');
+        }
+        if (!this._inscatterStates) {
+            this._inscatterStates = device.createRenderStateSet();
+            this._inscatterStates.useRasterizerState().setCullMode('none');
+            this._inscatterStates.useDepthState().enableTest(false).enableWrite(false);
+            // dst.rgb += src.rgb. Alpha is left alone, as in the fog pass, so a dense
+            // medium does not make the canvas transparent.
+            this._inscatterStates.useBlendingState().enable(true).setBlendFuncRGB('one', 'one').setBlendFuncAlpha('zero', 'one');
+        }
+        // The march is unrolled, so the step count is part of the program identity,
+        // as is the shadow hash the receiver code is generated from.
+        const key = `${steps}|${shadow ? shadow.shaderHash : ''}`;
+        let inscatter = this._inscatterPrograms.get(key);
+        if (!inscatter) {
+            const program = UnderwaterRenderer._createProgram(device, true, steps, shadow);
+            inscatter = {
+                program,
+                bindGroup: device.createBindGroup(program.bindGroupLayouts[0])
+            };
+            this._inscatterPrograms.set(key, inscatter);
+        }
+        return {
+            extinctionPass: {
+                program: this._extinctionProgram,
+                bindGroup: this._extinctionBindGroup,
+                states: this._extinctionStates
+            },
+            inscatterPass: {
+                program: inscatter.program,
+                bindGroup: inscatter.bindGroup,
+                states: this._inscatterStates
+            }
+        };
+    }
+    /**
+   * @param device - Rendering device.
+   * @param inscatter - Build the in-scattering half rather than the extinction one.
+   * @param steps - Ray-march steps for the sun shafts; 0 leaves them out entirely.
+   * @param shadowMapParams - Shadow params when the shafts should be occluded by
+   * geometry, null when they should not.
+   * @internal
+   */ static _createProgram(device, inscatter, steps, shadowMapParams) {
+        const godRays = inscatter && steps > 0;
+        const shadow = godRays ? shadowMapParams : null;
+        const numCascades = shadow?.numShadowCascades ?? 0;
+        const program = device.buildRenderProgram({
+            label: inscatter ? 'UnderwaterInscatter' : 'UnderwaterExtinction',
+            vertex (pb) {
+                this.flip = pb.int().uniform(0);
+                this.$inputs.pos = pb.vec2().attrib('position');
+                this.$outputs.uv = pb.vec2();
+                pb.main(function() {
+                    this.$builtins.position = pb.vec4(this.$inputs.pos, DEPTH_FARTHEST, 1);
+                    this.$outputs.uv = pb.add(pb.mul(this.$inputs.pos.xy, 0.5), pb.vec2(0.5));
+                    this.$if(pb.notEqual(this.flip, 0), function() {
+                        this.$builtins.position.y = pb.neg(this.$builtins.position.y);
+                    });
+                });
+            },
+            fragment (pb) {
+                this.depthTex = pb.tex2D().sampleType('unfilterable-float').uniform(0);
+                this.skyLut = pb.tex2D().uniform(0);
+                this.invProjViewMatrix = pb.mat4().uniform(0);
+                this.cameraPosition = pb.vec3().uniform(0);
+                this.mediumExtinction = pb.vec3().uniform(0);
+                this.mediumAlbedo = pb.vec3().uniform(0);
+                /** (ambientScale, surfaceY, maxPathLength, godRayIntensity) */ this.params = pb.vec4().uniform(0);
+                if (godRays) {
+                    /** Direction the sun travels, as `directionAndCutoff.xyz`. */ this.sunDirection = pb.vec3().uniform(0);
+                    /** Pre-exposed sun radiance. */ this.sunColor = pb.vec3().uniform(0);
+                    /** (scatterAnisotropy, unused, unused, unused) */ this.phaseParams = pb.vec4().uniform(0);
+                    // The same caustic uniforms every lit material declares, so the shafts
+                    // read the map through the exact projection the sea bed does.
+                    ShaderHelper.declareWaterCausticUniforms(pb);
+                }
+                if (shadow) {
+                    // Reproduces the material light pass's globals the shadow helpers read
+                    // by name, as ShadowMaskRenderer does.
+                    const cameraStruct = pb.defineStruct([
+                        pb.vec4('position'),
+                        pb.vec4('params'),
+                        pb.float('shadowDebugCascades'),
+                        // Read by the PCSS implementation's temporal jitter.
+                        pb.int('framestamp')
+                    ]);
+                    const lightStruct = pb.defineStruct([
+                        pb.vec3('sunDir'),
+                        pb.int('shadowCascades'),
+                        pb.vec4('positionAndRange'),
+                        pb.vec4('directionAndCutoff'),
+                        pb.vec4('diffuseAndIntensity'),
+                        pb.vec4('extraParams'),
+                        pb.vec4('cascadeDistances'),
+                        pb.vec4('depthBiasValues'),
+                        pb.vec4('shadowCameraParams'),
+                        pb.vec4('depthBiasScales'),
+                        pb.vec4('implParams'),
+                        pb.vec4[16]('shadowMatrices'),
+                        pb.float('shadowStrength'),
+                        pb.float('envLightStrength'),
+                        pb.float('envLightSpecularStrength')
+                    ]);
+                    this.camera = cameraStruct().uniform(0);
+                    this.light = lightStruct().uniform(0);
+                    this.cameraForward = pb.vec3().uniform(0);
+                    const shadowMap = shadow.shadowMap;
+                    const shadowTex = shadowMap.isTextureCube() ? shadowMap.isDepth() ? pb.texCubeShadow() : pb.texCube() : shadowMap.isTexture2D() ? shadowMap.isDepth() ? pb.tex2DShadow() : pb.tex2D() : shadowMap.isDepth() ? pb.tex2DArrayShadow() : pb.tex2DArray();
+                    if (!shadowMap.isDepth() && !device.getDeviceCaps().textureCaps.getTextureFormatInfo(shadowMap.format).filterable) {
+                        shadowTex.sampleType('unfilterable-float');
+                    }
+                    this[SHADOW_MAP_UNIFORM] = shadowTex.uniform(0);
+                    // How much sun reaches a point inside the water column. A point in the
+                    // medium has no surface orientation, so no normal offset and NoL = 1.
+                    pb.func('zUnderwaterShadow', [
+                        pb.vec3('worldPos'),
+                        pb.float('viewDepth')
+                    ], function() {
+                        if (numCascades > 1) {
+                            this.$l.comparison = pb.vec4(pb.greaterThan(pb.vec4(this.viewDepth), this.light.cascadeDistances));
+                            this.$l.cascadeFlags = pb.vec4(pb.float(pb.greaterThan(this.light.shadowCascades, 0)), pb.float(pb.greaterThan(this.light.shadowCascades, 1)), pb.float(pb.greaterThan(this.light.shadowCascades, 2)), pb.float(pb.greaterThan(this.light.shadowCascades, 3)));
+                            this.$l.split = pb.int(pb.dot(this.comparison, this.cascadeFlags));
+                            this.$l.shadowVertex = ShaderHelper.calculateShadowSpaceVertex(this, pb.vec4(this.worldPos, 1), this.split);
+                            this.$l.shadow = shadow.impl.computeShadowCSM(shadow, this, this.shadowVertex, pb.float(1), this.split);
+                        } else {
+                            this.$l.shadowVertex = ShaderHelper.calculateShadowSpaceVertex(this, pb.vec4(this.worldPos, 1));
+                            this.$l.shadow = shadow.impl.computeShadow(shadow, this, this.shadowVertex, pb.float(1));
+                        }
+                        // Fade to unshadowed towards the shadow distance, as the surfaces do.
+                        this.$l.shadowDistance = this.light.shadowCameraParams.w;
+                        this.shadow = pb.mix(this.shadow, 1, pb.smoothStep(pb.mul(this.shadowDistance, 0.8), this.shadowDistance, pb.distance(this.camera.position.xyz, this.worldPos)));
+                        this.shadow = pb.mix(1, this.shadow, this.light.shadowStrength);
+                        this.$return(pb.clamp(this.shadow, 0, 1));
+                    });
+                }
+                this.$outputs.outColor = pb.vec4();
+                pb.main(function() {
+                    this.$l.depthValue = pb.textureSample(this.depthTex, this.$inputs.uv).r;
+                    this.$l.clipSpacePos = pb.vec4(pb.sub(pb.mul(this.$inputs.uv, 2), pb.vec2(1)), ShaderHelper.deviceDepthToClipZ(this, this.depthValue), 1);
+                    this.$l.hPos = pb.mul(this.invProjViewMatrix, this.clipSpacePos);
+                    this.$l.worldPos = pb.div(this.hPos, this.hPos.w).xyz;
+                    this.$l.isSky = ShaderHelper.isFarthestDepth(this, this.depthValue);
+                    // Normalised from the raw difference, not divided by the capped path
+                    // length, so it stays a unit vector and cosTheta stays in [-1, 1].
+                    this.$l.viewDir = pb.normalize(pb.sub(this.worldPos, this.cameraPosition));
+                    // A ray that reached the sky never left the water, so it takes the
+                    // whole cap.
+                    this.$l.pathLength = this.$choice(this.isSky, this.params.z, pb.min(pb.distance(this.worldPos, this.cameraPosition), this.params.z));
+                    this.$l.transmittance = pb.exp(pb.neg(pb.mul(this.mediumExtinction, this.pathLength)));
+                    if (!inscatter) {
+                        this.$outputs.outColor = pb.vec4(this.transmittance, 1);
+                    } else {
+                        // Downwelling sky light, attenuated over the vertical depth averaged
+                        // between the two ends of the path.
+                        this.$l.endY = this.$choice(this.isSky, this.cameraPosition.y, this.worldPos.y);
+                        this.$l.columnDepth = pb.mul(0.5, pb.add(pb.max(pb.sub(this.params.y, this.cameraPosition.y), 0), pb.max(pb.sub(this.params.y, this.endY), 0)));
+                        this.$l.ambient = pb.mul(pb.textureSampleLevel(this.skyLut, pb.vec2(0.5), 0).rgb, this.params.x, pb.exp(pb.neg(pb.mul(this.mediumExtinction, this.columnDepth))));
+                        // Single scattering, the same form getScattering() uses on the surface.
+                        this.$l.inscatter = pb.mul(this.mediumAlbedo, pb.sub(pb.vec3(1), this.transmittance), this.ambient);
+                        if (godRays) {
+                            // Sun shafts: the single scattering integral against the sun,
+                            // marched along the view ray since the sun reaching each point
+                            // depends on the surface overhead.
+                            //
+                            // Scattering angle, constant along the ray; clamped against rounding.
+                            this.$l.cosTheta = pb.clamp(pb.neg(pb.dot(this.sunDirection, this.viewDir)), -1, 1);
+                            this.$l.phase = waterScatterPhase(this, this.cosTheta, this.phaseParams.x);
+                            // Dithered sample offset, trading banding for grain.
+                            this.$l.jitter = interleavedGradientNoise(this, this.$builtins.fragCoord.xy);
+                            // The integral is sigma_s * integral(sunAtP(t) * exp(-sigma_t * t) dt),
+                            // and only `sunAtP` needs sampling - the exponential is analytic.
+                            // So the march estimates the transmittance-weighted *mean* of
+                            // sunAtP and the closed form below supplies the rest.
+                            //
+                            // Samples are importance-sampled by inverting the exponential of
+                            // the *least* attenuated channel: the per-channel correction grows
+                            // like exp((sigma_place - sigma_c) * t), so this keeps every
+                            // exponent non-positive and no weight can run away.
+                            this.$l.sigmaPlace = pb.max(pb.min(pb.min(this.mediumExtinction.x, this.mediumExtinction.y), this.mediumExtinction.z), 1e-3);
+                            // Renormalises the exponential to the finite path, so the samples
+                            // span exactly the visible stretch however short it is.
+                            this.$l.cdfMax = pb.sub(1, pb.exp(pb.neg(pb.mul(this.sigmaPlace, this.pathLength))));
+                            this.$l.shafts = pb.vec3(0);
+                            this.$l.weightSum = pb.vec3(0);
+                            this.$for(pb.int('i'), 0, steps, function() {
+                                this.$l.u = pb.div(pb.add(pb.float(this.i), this.jitter), steps);
+                                this.$l.t = pb.min(pb.div(pb.neg(pb.log(pb.max(pb.sub(1, pb.mul(this.u, this.cdfMax)), 1e-6))), this.sigmaPlace), this.pathLength);
+                                this.$l.samplePos = pb.add(this.cameraPosition, pb.mul(this.viewDir, this.t));
+                                // Sun reaching this point: the caustic map already carries the
+                                // Beer-Lambert transmittance down the sun ray and the focusing
+                                // pattern, so shafts line up with the caustics.
+                                this.$l.sunAtP = ShaderHelper.sampleWaterCaustic(this, this.samplePos, pb.int(LIGHT_TYPE_DIRECTIONAL), this.sunDirection, false);
+                                if (shadow) {
+                                    // Occlusion by geometry under the surface, which the caustic
+                                    // map does not know about.
+                                    this.$l.viewDepth = pb.dot(pb.sub(this.samplePos, this.cameraPosition), this.cameraForward);
+                                    this.sunAtP = pb.mul(this.sunAtP, this.zUnderwaterShadow(this.samplePos, this.viewDepth));
+                                }
+                                // Transmittance back to the eye over the sampling pdf; the pdf's
+                                // constant factors cancel in the ratio below.
+                                this.$l.weight = pb.exp(pb.mul(pb.sub(pb.vec3(this.sigmaPlace), this.mediumExtinction), this.t));
+                                this.shafts = pb.add(this.shafts, pb.mul(this.sunAtP, this.weight));
+                                this.weightSum = pb.add(this.weightSum, this.weight);
+                            });
+                            // Closed form with sunAtP at its sampled mean:
+                            // sigma_s/sigma_t * (1 - exp(-sigma_t * path)), the same
+                            // normalisation as the ambient term.
+                            this.$l.meanSun = pb.div(this.shafts, pb.max(this.weightSum, pb.vec3(1e-6)));
+                            this.inscatter = pb.add(this.inscatter, pb.mul(this.meanSun, this.mediumAlbedo, pb.sub(pb.vec3(1), this.transmittance), this.sunColor, pb.mul(this.phase, this.params.w)));
+                        }
+                        this.$outputs.outColor = pb.vec4(this.inscatter, 1);
+                    }
+                });
+            }
+        });
+        program.name = inscatter ? '@UnderwaterInscatter' : '@UnderwaterExtinction';
+        return program;
+    }
+}
+
+export { UnderwaterRenderer, selectUnderwaterSource, setWaterSubmergence };
+//# sourceMappingURL=underwater.js.map