@zephyr3d/scene 0.9.25 → 0.9.27

package/dist/render/rendergraph/forward_plus_builder.js

@@ -1,17 +1,18 @@
-import { REVERSE_Z, Vector4, DEPTH_CLEAR_VALUE, DEPTH_COMPARE_DEFAULT } from '@zephyr3d/base';
+import { Vector4, DEPTH_CLEAR_VALUE, DEPTH_COMPARE_DEFAULT } from '@zephyr3d/base';
 import { RenderQueue } from '../render_queue.js';
 import { LightPass } from '../lightpass.js';
 import { ShadowMapPass } from '../shadowmap_pass.js';
 import { DepthPass } from '../depthpass.js';
 import { ClusteredLight } from '../cluster_light.js';
 import { ShadowMaskRenderer } from '../shadow_mask_pass.js';
-import { buildHiZ } from '../hzb.js';
+import { getHiZFormat, buildHiZ } from '../hzb.js';
 import '../primitive.js';
 import '@zephyr3d/device';
 import { CopyBlitter } from '../../blitter/copy.js';
 import { fetchSampler } from '../../utility/misc.js';
 import { MaterialVaryingFlags } from '../../values.js';
-import { ShaderHelper } from '../../material/shader/helper.js';
+import { ShaderHelper, MAX_CAUSTIC_WATERS } from '../../material/shader/helper.js';
+import { REFRACT_BLUR_MAX_LOD } from '../../material/water.js';
 import { PostEffectLayer, AbstractPostEffect } from '../../posteffect/posteffect.js';
 import { RenderGraph } from './rendergraph.js';
 import { RenderGraphExecutor } from './executor.js';
@@ -31,12 +32,16 @@ import '../../shapes/torus.js';
 import '../../shapes/plane.js';
 import '../../shapes/sphere.js';
 import '../../shapes/tetrahedron.js';
+import { WaterCausticsRenderer } from '../water_caustics.js';
+import { UnderwaterRenderer, selectUnderwaterSource } from '../underwater.js';
 
 const _scenePass = new LightPass();
 const _depthPass = new DepthPass();
 const _shadowMapPass = new ShadowMapPass();
 const _clusters = [];
 const _shadowMaskRenderer = new ShadowMaskRenderer();
+const _waterCausticsRenderer = new WaterCausticsRenderer();
+const _underwaterRenderer = new UnderwaterRenderer();
 const _devicePoolAllocator = new DevicePoolAllocator();
 const _textureAffinityCaches = new WeakMap();
 function getTextureAffinityCache(camera, device) {
@@ -210,6 +215,21 @@ function getSSSLightingTextureFormat(ctx, attachmentCount, surfaceAttachmentCoun
 function getFullMipLevelCount(width, height) {
     return Math.max(1, Math.floor(Math.log2(Math.max(1, width, height))) + 1);
 }
+/**
+ * Levels the scene colour copy is allocated with.
+ *
+ * Deep enough to serve the refraction blur, which clamps its own LOD, and no
+ * deeper: the coarsest levels of a full chain are averages of the whole frame,
+ * which is not a plausible answer for "what is behind this water", and every
+ * level costs bandwidth to generate on each grab. Capped against the full chain
+ * so a small render target stays legal.
+ *
+ * Derived from the water material's clamp rather than restated, so the two
+ * cannot drift: a level count one short of it would leave the sampler asking for
+ * a level that does not exist.
+ */ function getSceneColorMipLevelCount(width, height) {
+    return Math.min(REFRACT_BLUR_MAX_LOD + 1, getFullMipLevelCount(width, height));
+}
 function hasSurfaceMRT(ctx) {
     return !!(ctx.materialFlags & SURFACE_MRT_FLAGS);
 }
@@ -244,10 +264,16 @@ function getLightPassColorAttachments(ctx, colorAttachment) {
     const skinSSS = camera.skinSSS && renderQueueHasActiveSkinSSS(renderQueue);
     const needSceneColor = renderQueue.needSceneColor();
     const needSceneColorWithDepth = renderQueue.needSceneColorWithDepth();
+    // Requested by materials rather than by a post effect, so it is resolved here
+    // instead of in resolveFrameResourceRequirements. WebGL1 has no Hi-Z at all,
+    // and a material asking for one there would turn a missing feature into a
+    // thrown frame; the material is expected to shade without it.
+    const needHiZNearest = (renderQueue.needHiZNearest() || camera.HiZNearest) && deviceType !== 'webgl';
     return {
         depthPrepass: true,
         motionVectors: false,
-        hiZ: false,
+        hiZ: needHiZNearest,
+        hiZNearest: needHiZNearest,
         sceneNormal: false,
         sceneRoughness: false,
         shadowMask: false,
@@ -266,7 +292,10 @@ function getLightPassColorAttachments(ctx, colorAttachment) {
 function resolveFrameResourceRequirements(ctx, options, requirements) {
     const deviceType = ctx.device.type;
     options.motionVectors ||= !!requirements.motionVector;
-    options.hiZ ||= !!requirements.hiZ;
+    options.hiZNearest ||= !!requirements.hiZNearest;
+    // The nearest channel lives on the same pyramid, so asking for it is asking
+    // for the pyramid.
+    options.hiZ ||= !!requirements.hiZ || options.hiZNearest;
     options.sceneNormal ||= !!requirements.sceneNormal;
     options.sceneRoughness ||= !!requirements.sceneRoughness;
     options.shadowMask ||= !!requirements.shadowMask;
@@ -401,6 +430,152 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
         });
     }
 };
+/**
+ * Picks the water surface and light the caustic map is built from.
+ *
+ * Only one pair is handled per frame: the caustics ride on a single light's
+ * additive pass, and a second water body would need a second map. The largest
+ * visible water surface wins, which is the one a camera near several of them is
+ * most likely to be looking through.
+ * @internal
+ */ function selectWaterCausticSource(ctx, renderQueue) {
+    if (ctx.device.type === 'webgl' || renderQueue.waters.length === 0) {
+        return null;
+    }
+    // The caustic light must own an additive shadow pass, because that is the pass
+    // the caustic uniforms are declared and bound on.
+    const candidate = renderQueue.sunLight ?? renderQueue.primaryDirectionalLight;
+    const light = candidate && candidate.castShadow && renderQueue.shadowedLights.indexOf(candidate) >= 0 ? candidate : null;
+    if (!light) {
+        return null;
+    }
+    const waters = renderQueue.waters.filter((water)=>WaterCausticsRenderer.canRender(water, light));
+    if (waters.length === 0) {
+        return null;
+    }
+    // Largest first, which decides both what survives the cap and which body's
+    // settings describe the shared map. Area is a stand-in for "the one the viewer
+    // is most likely to be over"; a camera-distance sort would swap the map's
+    // whole configuration as the viewer walks between two pools, and swapping it
+    // discards the temporal history every time.
+    waters.sort((a, b)=>{
+        const ra = a.material.region;
+        const rb = b.material.region;
+        const areaA = Math.max(0, ra.z - ra.x) * Math.max(0, ra.w - ra.y);
+        const areaB = Math.max(0, rb.z - rb.x) * Math.max(0, rb.w - rb.y);
+        return areaB - areaA;
+    });
+    return {
+        waters: waters.slice(0, MAX_CAUSTIC_WATERS),
+        light
+    };
+}
+/** @internal */ const WaterCausticsModule = {
+    type: 'WaterCaustics',
+    writes: [
+        FrameResources.WaterCaustics
+    ],
+    prepare: ({ ctx, renderQueue })=>({
+            enabled: !!selectWaterCausticSource(ctx, renderQueue)
+        }),
+    setup (fg) {
+        const { graph, ctx, renderQueue, ordering, blackboard } = fg;
+        const source = selectWaterCausticSource(ctx, renderQueue);
+        // Map-wide settings come from the largest body; see selectWaterCausticSource.
+        const material = source.waters[0].material;
+        const size = material.causticsResolution;
+        const format = WaterCausticsRenderer.getMapFormat(ctx.device);
+        const history = fg.history;
+        const temporal = material.causticsTemporalStrength > 0;
+        const mapDesc = {
+            format,
+            sizeMode: 'absolute',
+            width: size,
+            height: size
+        };
+        const mapSize = {
+            width: size,
+            height: size
+        };
+        // Null on the first frame, after a resize, and whenever the map format
+        // changes; the renderer falls back to the current frame alone.
+        const previousHandle = temporal && history ? history.importPreviousIfCompatible(graph, RGHistoryResources.WATER_CAUSTICS, mapDesc, mapSize) : null;
+        const result = graph.addPass('WaterCaustics', (builder)=>{
+            // The wave textures the splat pass samples are updated by the scene, not by
+            // the graph, so chain after the passes that have already run rather than
+            // declaring a resource dependency on them.
+            ordering.chainInto(builder);
+            ordering.emit(builder, 'WaterCausticsDone');
+            // The map leaves the graph through the draw context rather than through a
+            // handle a later pass samples, so nothing would otherwise keep this alive.
+            builder.sideEffect();
+            // Fixed-size, unlike almost every other graph texture: the map covers a
+            // world-space footprint, not the screen.
+            const mapHandle = builder.createTexture({
+                format,
+                sizeMode: 'absolute',
+                width: size,
+                height: size,
+                label: 'waterCaustics',
+                allocationKey: 'ForwardPlus.WaterCaustics'
+            });
+            const scratchHandle = builder.createTexture({
+                format,
+                sizeMode: 'absolute',
+                width: size,
+                height: size,
+                label: 'waterCausticsScratch',
+                allocationKey: 'ForwardPlus.WaterCausticsScratch'
+            });
+            // The displaced surface height along each map ray, which the receiver
+            // gates its depth on. Same slice and size as the map so it shares the
+            // map's uv; four channels, one per water slot.
+            const heightHandle = builder.createTexture({
+                format: WaterCausticsRenderer.getHeightMapFormat(),
+                sizeMode: 'absolute',
+                width: size,
+                height: size,
+                label: 'waterCausticHeights',
+                allocationKey: 'ForwardPlus.WaterCausticHeights'
+            });
+            if (previousHandle) {
+                builder.read(previousHandle);
+            }
+            builder.setExecute((rgCtx)=>{
+                const map = rgCtx.getTexture(mapHandle);
+                const scratch = rgCtx.getTexture(scratchHandle);
+                const heights = rgCtx.getTexture(heightHandle);
+                const previous = previousHandle ? rgCtx.getTexture(previousHandle) : null;
+                const resolved = _waterCausticsRenderer.render(ctx, source.waters, source.light, map, scratch, heights, previous, (texture)=>rgCtx.createFramebuffer({
+                        width: texture.width,
+                        height: texture.height,
+                        colorAttachments: texture,
+                        depthAttachment: null
+                    }));
+                if (temporal && history) {
+                    // Commit whichever texture the renderer settled on, so the next frame
+                    // reprojects the map that was actually shown rather than the
+                    // pre-resolve one.
+                    history.queueRetainedCommit(RGHistoryResources.WATER_CAUSTICS, mapDesc, mapSize, resolved);
+                }
+                // Publish only after the map exists: the light pass keys its shader
+                // variant on this flag and binds the texture in the same step.
+                ctx.waterCaustics = true;
+                ctx.waterCausticLight = source.light;
+                ctx.waterCausticTexture = resolved;
+                ctx.waterCausticHeightTexture = heights;
+                ctx.waterCausticUniforms = _waterCausticsRenderer.uniforms;
+            });
+            return {
+                mapHandle,
+                scratchHandle
+            };
+        });
+        // Which target holds the result depends on whether the resolve ran. Both are
+        // declared by this pass, so either is a valid handle for consumers to read.
+        blackboard.set(FrameResources.WaterCaustics, temporal && previousHandle ? result.scratchHandle : result.mapHandle);
+    }
+};
 /** @internal */ const DepthPrepassModule = {
     type: 'DepthPrepass',
     writes: [
@@ -462,6 +637,11 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
                 builder.addSubpass('SkyMotionVectors', (rgCtx)=>{
                     renderSkyMotionVectors(ctx, rgCtx, skyMotionVectorFramebufferHandle);
                 });
+                // After the sky, which writes at the far plane: a blended surface in
+                // front of empty background has to replace what the sky put there.
+                builder.addSubpass('TransparentMotionVectors', (rgCtx)=>{
+                    renderTransparentMotionVectors(frame, rgCtx, skyMotionVectorFramebufferHandle);
+                });
             }
             return {
                 depthHandle,
@@ -575,7 +755,7 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
             enabled: options.hiZ
         }),
     setup (fg) {
-        const { graph, ctx, frame, blackboard } = fg;
+        const { graph, ctx, frame, blackboard, options } = fg;
         const depthPassResult = requireBuildState(fg, 'depth', 'DepthPrepass', 'HiZ');
         const preLightTransmissionDepthToken = fg.state.preLightTransmissionDepthToken;
         //const hiZWidth = nextPowerOf2(ctx.renderWidth);
@@ -588,11 +768,14 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
                 builder.read(preLightTransmissionDepthToken);
             }
             hiZHandle = builder.createTexture({
-                format: REVERSE_Z ? 'r16f' : 'r32f',
+                format: getHiZFormat(options.hiZNearest),
                 label: 'hiZ',
                 sizeMode: 'backbuffer-relative',
                 mipLevels: getFullMipLevelCount(ctx.renderWidth, ctx.renderHeight),
-                allocationKey: 'ForwardPlus.HiZ'
+                // Keyed on the channel count: a one- and a two-channel pyramid are
+                // different textures, and pooling them under one key would hand a
+                // consumer a pyramid with no nearest channel in it.
+                allocationKey: `ForwardPlus.HiZ${options.hiZNearest ? '.MinMax' : ''}`
             });
             const hiZFramebufferHandle = builder.createFramebuffer({
                 label: 'HiZFramebuffer',
@@ -628,6 +811,7 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
         const depthPassResult = requireBuildState(fg, 'depth', 'DepthPrepass', 'SSSProfile');
         const preLightTransmissionDepthToken = fg.state.preLightTransmissionDepthToken;
         const shadowMaskHandle = blackboard.get(FrameResources.ShadowMask);
+        const waterCausticsHandle = blackboard.get(FrameResources.WaterCaustics);
         const renderDepthAttachment = fg.state.renderDepthAttachment;
         const sssProfileResult = graph.addPass('SSSProfile', (builder)=>{
             builder.read(blackboard.expect(FrameResources.LinearDepth));
@@ -638,6 +822,12 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
             if (shadowMaskHandle) {
                 builder.read(shadowMaskHandle);
             }
+            if (waterCausticsHandle) {
+                // Same reason as the shadow mask: the map reaches the shader through
+                // ctx.waterCausticTexture, so only a declared read stops the executor
+                // from recycling it while this pass is still sampling it.
+                builder.read(waterCausticsHandle);
+            }
             const profileHandle = builder.createTexture({
                 format: 'rgba16f',
                 label: 'sssProfile',
@@ -686,6 +876,7 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
         const depthPassResult = requireBuildState(fg, 'depth', 'DepthPrepass', 'SceneColorGrab');
         const preLightTransmissionDepthToken = fg.state.preLightTransmissionDepthToken;
         const shadowMaskHandle = blackboard.get(FrameResources.ShadowMask);
+        const waterCausticsHandle = blackboard.get(FrameResources.WaterCaustics);
         const renderDepthAttachment = fg.state.renderDepthAttachment;
         const grabResult = graph.addPass('SceneColorGrab', (builder)=>{
             builder.read(blackboard.expect(FrameResources.LinearDepth));
@@ -696,9 +887,34 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
             if (shadowMaskHandle) {
                 builder.read(shadowMaskHandle);
             }
+            if (waterCausticsHandle) {
+                // Same reason as the shadow mask: the map reaches the shader through
+                // ctx.waterCausticTexture, so only a declared read stops the executor
+                // from recycling it while this pass is still sampling it.
+                builder.read(waterCausticsHandle);
+            }
+            // A few mip levels, because the refraction background is sampled at a LOD
+            // and not only at mip 0: water picks one from how deep and how turbid the
+            // column is, so a stone under clear shallows stays sharp while the same
+            // stone under metres of silt smears. With a single-level texture the
+            // sampler returned mip 0 whatever LOD was asked for, and the blur did
+            // nothing.
+            //
+            // Nothing here generates the chain - both backends do it when the
+            // framebuffer is unbound, for any colour attachment with more than one
+            // level (WebGL `framebuffer_webgl.ts` unbind, WebGPU `renderpass_webgpu.ts`
+            // end), and `generateMipmaps` defaults to true on colour attachments. The
+            // level count is the whole precondition.
+            //
+            // Not the full chain down to 1x1. The consumer clamps its LOD, and the
+            // coarsest levels of a full chain average across the whole frame - a
+            // sample from one stops being "what is behind the water" and becomes the
+            // mean of the image. Generating them would cost bandwidth every frame to
+            // produce levels nothing may read.
             const copyHandle = builder.createTexture({
                 format: ctx.colorFormat,
                 label: 'sceneColorCopy',
+                mipLevels: getSceneColorMipLevelCount(ctx.renderWidth, ctx.renderHeight),
                 allocationKey: 'ForwardPlus.SceneColorCopy'
             });
             // Isolate depth when SSR inserts transmission depth before LightPass.
@@ -739,6 +955,7 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
         const { graph, ctx, frame, blackboard, options, backbuffer } = fg;
         const depthPassResult = requireBuildState(fg, 'depth', 'DepthPrepass', 'LightPass');
         const shadowMaskHandle = blackboard.get(FrameResources.ShadowMask);
+        const waterCausticsHandle = blackboard.get(FrameResources.WaterCaustics);
         const preLightTransmissionDepthToken = fg.state.preLightTransmissionDepthToken;
         const hiZHandle = blackboard.get(FrameResources.HiZ);
         const sssProfileHandle = blackboard.get(FrameResources.SSSProfile);
@@ -809,6 +1026,12 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
             if (shadowMaskHandle) {
                 builder.read(shadowMaskHandle);
             }
+            if (waterCausticsHandle) {
+                // Same reason as the shadow mask: the map reaches the shader through
+                // ctx.waterCausticTexture, so only a declared read stops the executor
+                // from recycling it while this pass is still sampling it.
+                builder.read(waterCausticsHandle);
+            }
             if (preLightTransmissionDepthToken) {
                 builder.read(preLightTransmissionDepthToken);
             }
@@ -996,6 +1219,68 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
         }
     }
 };
+/** @internal */ const UnderwaterModule = {
+    type: 'Underwater',
+    reads: [
+        {
+            resource: FrameResources.SceneColor,
+            version: 'current'
+        }
+    ],
+    writes: [
+        FrameResources.SceneColor
+    ],
+    prepare: ({ ctx })=>({
+            enabled: !!ctx.underwater
+        }),
+    setup (fg) {
+        const { graph, ctx, frame, blackboard } = fg;
+        const depthPassResult = requireBuildState(fg, 'depth', 'DepthPrepass', 'Underwater');
+        const lightPassResult = requireBuildState(fg, 'lightPass', 'LightPass', 'Underwater');
+        const sceneColorHandle = blackboard.expect(FrameResources.SceneColor);
+        const waterCausticsHandle = blackboard.get(FrameResources.WaterCaustics);
+        const state = ctx.underwater;
+        // After the sky, before the transparent pass: the medium has to cover the
+        // sky - that is what the horizon fades into underwater - and the opaque
+        // scene is the only thing the depth buffer describes, so it is also the only
+        // thing this can reach. Transparent geometry is on its own, exactly as it is
+        // for atmospheric fog.
+        const underwaterColorHandle = graph.addPass('Underwater', (builder)=>{
+            builder.read(sceneColorHandle);
+            builder.read(depthPassResult.depthFramebufferHandle);
+            if (lightPassResult.sceneColorFramebufferHandle) {
+                builder.read(lightPassResult.sceneColorFramebufferHandle);
+            }
+            if (waterCausticsHandle) {
+                // The light shafts sample the caustic map, which reaches the shader
+                // through ctx.waterCausticTexture rather than through a handle. Same
+                // lifetime argument as the shadow mask in CompositeTail: only a declared
+                // read stops the executor returning it to the pool after LightPass.
+                builder.read(waterCausticsHandle);
+            }
+            const out = builder.write(sceneColorHandle);
+            builder.setExecute((rgCtx)=>{
+                const colorTexture = rgCtx.getTexture(sceneColorHandle);
+                const depthTexture = frame.depthFramebuffer?.getDepthAttachment();
+                if (!colorTexture || !depthTexture) {
+                    return;
+                }
+                // Color only. The scene depth is sampled by this pass, which it cannot
+                // be while it is still attached to the bound framebuffer.
+                const colorFramebuffer = rgCtx.createFramebuffer({
+                    width: colorTexture.width,
+                    height: colorTexture.height,
+                    colorAttachments: colorTexture,
+                    depthAttachment: null
+                });
+                _underwaterRenderer.render(ctx, state, colorFramebuffer, depthTexture);
+            });
+            return out;
+        });
+        lightPassResult.sceneColorHandle = underwaterColorHandle;
+        blackboard.set(FrameResources.SceneColor, underwaterColorHandle);
+    }
+};
 /** @internal */ const CompositeTailModule = {
     type: 'CompositeTail',
     writes: [
@@ -1011,6 +1296,8 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
         const depthPassResult = requireBuildState(fg, 'depth', 'DepthPrepass', 'CompositeTail');
         const hiZHandle = blackboard.get(FrameResources.HiZ);
         const sceneColorCopyHandle = blackboard.get(FrameResources.SceneColorCopy);
+        const shadowMaskHandle = blackboard.get(FrameResources.ShadowMask);
+        const waterCausticsHandle = blackboard.get(FrameResources.WaterCaustics);
         const lightPassResult = requireBuildState(fg, 'lightPass', 'LightPass', 'CompositeTail');
         const renderDepthAttachment = fg.state.renderDepthAttachment;
         const useFinalFramebufferAsIntermediate = fg.state.useFinalFramebufferAsIntermediate;
@@ -1074,9 +1361,27 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
             if (sceneColorCopyHandle) {
                 builder.read(sceneColorCopyHandle);
             }
+            if (shadowMaskHandle) {
+                // Transparent geometry goes through the same clustered-light bind group
+                // as the opaque pass, which binds ctx.shadowMaskTexture whenever
+                // screenSpaceShadowMask is on (ShaderHelper, UNIFORM_NAME_SHADOW_MASK).
+                // Declaring the read is what keeps the mask alive: the executor derives
+                // each resource's lastUse from declared reads and returns the texture to
+                // the pool immediately after, so without this the mask would be recycled
+                // after LightPass while this pass is still sampling it.
+                builder.read(shadowMaskHandle);
+            }
+            if (waterCausticsHandle) {
+                // Same lifetime argument as the shadow mask above.
+                builder.read(waterCausticsHandle);
+            }
             builder.read(opaqueChainResult.color);
             const out = builder.write(opaqueChainResult.color);
             builder.setExecute((rgCtx)=>{
+                // Pulled here rather than inherited from LightPass's execute. The value
+                // is the same, but relying on the leftover would make this pass depend
+                // on execution order instead of on its own declared inputs.
+                ctx.shadowMaskTexture = shadowMaskHandle ? rgCtx.getTexture(shadowMaskHandle) : null;
                 renderTransparentScenePass(frame, rgCtx, opaqueChainRan ? opaqueChainResult.color : null, lightPassResult.sceneColorFramebufferHandle);
             });
             return out;
@@ -1185,6 +1490,7 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
     ClusterLights: ClusterLightsModule,
     GPUPicking: GPUPickingModule,
     ShadowMaps: ShadowMapsModule,
+    WaterCaustics: WaterCausticsModule,
     DepthPrepass: DepthPrepassModule,
     ShadowMask: ShadowMaskModule,
     TransmissionDepthForSSR: TransmissionDepthForSSRModule,
@@ -1193,6 +1499,7 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
     SceneColorGrab: SceneColorGrabModule,
     LightPass: LightPassModule,
     SkyPass: SkyPassModule,
+    Underwater: UnderwaterModule,
     CompositeTail: CompositeTailModule
 };
 /** The default module order assembled by {@link createForwardPlusPipeline}. */ const DEFAULT_FORWARD_PLUS_MODULES = [
@@ -1200,6 +1507,7 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
     ClusterLightsModule,
     GPUPickingModule,
     ShadowMapsModule,
+    WaterCausticsModule,
     DepthPrepassModule,
     ShadowMaskModule,
     TransmissionDepthForSSRModule,
@@ -1208,6 +1516,7 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
     SceneColorGrabModule,
     LightPassModule,
     SkyPassModule,
+    UnderwaterModule,
     CompositeTailModule
 ];
 /** @internal */ let _defaultForwardPlusPipeline = null;
@@ -1235,6 +1544,13 @@ function buildForwardPlusGraphInternal(graph, ctx, renderQueue, options) {
     ctx.SkinSSSTexture = null;
     // ShadowMask sets this only when it produces a texture.
     ctx.shadowMaskTexture = null;
+    // WaterCaustics turns these on together once it has produced a map; they are
+    // read by every light pass, so they must start cleared each frame.
+    ctx.waterCaustics = false;
+    ctx.waterCausticLight = null;
+    ctx.waterCausticTexture = null;
+    ctx.waterCausticHeightTexture = null;
+    ctx.waterCausticUniforms = null;
     const blackboard = new RGBlackboard();
     const frame = {
         ctx,
@@ -1485,7 +1801,47 @@ function cleanupFrame(frame) {
 let _skyMVProgram = null;
 let _skyMVBindGroup = null;
 let _skyMVBox = null;
-/** @internal */ function renderSkyMotionVectors(ctx, rgCtx, framebufferHandle) {
+/** @internal */ /**
+ * Fills in motion vectors for blended geometry that opted into them.
+ *
+ * @remarks
+ * The transparent queue never reaches the ordinary prepass, so without this a
+ * blended surface carries whatever velocity belongs to what is behind it. The
+ * framebuffer here holds the motion vector attachment alone, so nothing touches
+ * the linear depth the light pass and the screen-space effects read, and the
+ * materials run with depth test on and depth write off, so the scene depth is
+ * left as the opaque pass built it.
+ *
+ * Materials that have not opted in discard, which leaves the velocity beneath
+ * them intact. See {@link MeshMaterial.transparentMotionVector} for why that is
+ * the right default and where the approximation breaks.
+ * @internal
+ */ function renderTransparentMotionVectors(frame, rgCtx, framebufferHandle) {
+    const ctx = frame.ctx;
+    const renderQueue = frame.renderQueue;
+    if (!ctx.motionVectors || !renderQueue.itemList?.transparent) {
+        return;
+    }
+    const device = ctx.device;
+    device.pushDeviceStates();
+    try {
+        device.setFramebuffer(rgCtx.getFramebuffer(framebufferHandle));
+        _depthPass.motionVectorOnly = true;
+        _depthPass.encodeDepth = false;
+        _depthPass.transmission = false;
+        _depthPass.renderBackface = false;
+        // Nothing is cleared: this pass only replaces the pixels its own geometry
+        // covers, and everything else in the target is already correct.
+        _depthPass.clearColor = null;
+        _depthPass.clearDepth = null;
+        _depthPass.clearStencil = null;
+        _depthPass.render(ctx, null, null, renderQueue);
+    } finally{
+        _depthPass.motionVectorOnly = false;
+        device.popDeviceStates();
+    }
+}
+function renderSkyMotionVectors(ctx, rgCtx, framebufferHandle) {
     if (!ctx.motionVectorTexture) {
         return;
     }
@@ -1680,7 +2036,11 @@ function blitToCurrentColorAttachment(ctx, source) {
         device.setViewport(null);
         device.setScissor(null);
         ctx.scene.env.sky.renderSky(ctx);
-        if (ctx.scene.env.sky.fogPresents) {
+        // Not while submerged: the medium between the eye and the scene is water,
+        // and the Underwater module composites it. The sky itself is still drawn -
+        // that pass then extinguishes it along with everything else at the far
+        // plane, which is what makes the horizon read as water rather than as air.
+        if (ctx.scene.env.sky.fogPresents && !ctx.underwater) {
             // Snapshot between sky and fog. Sky belongs in the copy - a ray that hits
             // the sky should read the sky - while fog does not, because the fog a
             // screen-space pass would sample lies along the camera ray rather than the
@@ -1762,8 +2122,17 @@ function blitToCurrentColorAttachment(ctx, source) {
     let motionVectorFrameCommitted = false;
     try {
         renderQueue = _scenePass.cullScene(ctx, ctx.camera);
+        // Before the options are derived, because being submerged changes them: the
+        // atmosphere is not the medium the camera is looking through, so its fog is
+        // suppressed for the frame.
+        ctx.underwater = selectUnderwaterSource(ctx);
         const options = deriveForwardPlusOptions(ctx.scene, ctx.camera, device.type, renderQueue);
         options.ssgi &&= supportsSSGIRenderTargets(ctx);
+        // Atmospheric fog describes a column of air, which is not what a submerged
+        // camera is looking through. The Underwater module owns the medium instead.
+        // Clearing the flag here also stops SkyPass reserving a fog-free snapshot
+        // for a frame that composites no fog.
+        options.fogPresents &&= !ctx.underwater;
         ctx.SSS = options.sss;
         historyManager = ctx.camera.getHistoryResourceManager();
         if (!historyManager) {