@zephyr3d/scene 0.9.26 → 0.10.0

package/dist/render/rendergraph/forward_plus_builder.js

@@ -1,17 +1,19 @@
-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 { TransmissionThicknessRenderer } from '../transmission_thickness_pass.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';
@@ -24,6 +26,7 @@ import { OrderingScope } from './render_context.js';
 import { RenderPipeline } from './render_pipeline.js';
 import { mergeFrameResourceRequirements } from './frame_resource_requirements.js';
 import { renderObjectColors } from '../gpu_picking.js';
+import '../../node_modules/meshoptimizer/meshopt_simplifier.js';
 import { BoxShape } from '../../shapes/box.js';
 import '../../shapes/capsule.js';
 import '../../shapes/cylinder.js';
@@ -31,13 +34,24 @@ 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 _transmissionThicknessRenderer = new TransmissionThicknessRenderer();
+const _waterCausticsRenderer = new WaterCausticsRenderer();
+const _underwaterRenderer = new UnderwaterRenderer();
 const _devicePoolAllocator = new DevicePoolAllocator();
+/**
+ * Clear value for the depth prepass's skin profile id target.
+ *
+ * @remarks
+ * 0 is "not skin". It has to differ from the depth target's clear, which is the
+ * far plane rather than an id.
+ */ const SKIN_PROFILE_ID_CLEAR = new Vector4(0, 0, 0, 0);
 const _textureAffinityCaches = new WeakMap();
 function getTextureAffinityCache(camera, device) {
     const current = _textureAffinityCaches.get(camera);
@@ -54,20 +68,14 @@ function getTextureAffinityCache(camera, device) {
 let _backDepthColorState = null;
 let _frontDepthColorState = null;
 const SURFACE_MRT_FLAGS = MaterialVaryingFlags.SCENE_STORE_ROUGHNESS | MaterialVaryingFlags.SSS_STORE_PROFILE | MaterialVaryingFlags.SSS_STORE_DIFFUSE | MaterialVaryingFlags.SCENE_STORE_NORMAL | MaterialVaryingFlags.SSS_STORE_TRANSMISSION | MaterialVaryingFlags.SKIN_SSS_STORE;
-function getClusteredLight() {
-    return _clusters.length > 0 ? _clusters.pop() : new ClusteredLight();
-}
-function freeClusteredLight(cl) {
-    _clusters.push(cl);
-}
 function getCoreMaterial(material) {
     return material?.coreMaterial ?? material ?? null;
 }
 function hasSSSMaterialCore(material) {
     return !!getCoreMaterial(material)?.subsurfaceProfile;
 }
-function hasSkinSSSMaterialCore(material) {
-    return !!getCoreMaterial(material)?.skinSSS;
+function hasPostSSSMaterialCore(material) {
+    return !!getCoreMaterial(material)?.postSSS;
 }
 function renderQueueHasActiveSSS(renderQueue) {
     const itemList = renderQueue.itemList;
@@ -87,7 +95,7 @@ function renderQueueHasActiveSSS(renderQueue) {
     }
     return false;
 }
-function renderQueueHasActiveSkinSSS(renderQueue) {
+function renderQueueHasActivePostSSS(renderQueue) {
     const itemList = renderQueue.itemList;
     if (!itemList) {
         return false;
@@ -98,7 +106,7 @@ function renderQueueHasActiveSkinSSS(renderQueue) {
     ];
     for (const list of lists){
         for (const material of list.materialList){
-            if (hasSkinSSSMaterialCore(material)) {
+            if (hasPostSSSMaterialCore(material)) {
                 return true;
             }
         }
@@ -124,8 +132,10 @@ function cloneActualSSSListInfo(source, _targetQueue) {
         morphItemList: filterActualSSSItemList(source.morphItemList),
         skinAndMorphItemList: filterActualSSSItemList(source.skinAndMorphItemList),
         instanceItemList: filterActualSSSItemList(source.instanceItemList),
+        skinInstanceItemList: filterActualSSSItemList(source.skinInstanceItemList),
         materialList: filterActualSSSMaterialList(source.materialList),
         instanceList: {},
+        instanceLods: {},
         renderQueue: source.renderQueue
     };
 }
@@ -136,7 +146,7 @@ function cloneActualSSSBundle(source, targetQueue) {
     };
 }
 function hasAnyActualSSSItems(renderItems) {
-    return renderItems.some((info)=>info.itemList.length > 0 || info.skinItemList.length > 0 || info.morphItemList.length > 0 || info.skinAndMorphItemList.length > 0 || info.instanceItemList.length > 0);
+    return renderItems.some((info)=>info.itemList.length > 0 || info.skinItemList.length > 0 || info.morphItemList.length > 0 || info.skinAndMorphItemList.length > 0 || info.instanceItemList.length > 0 || info.skinInstanceItemList.length > 0);
 }
 function createActualSSSRenderQueue(renderQueue) {
     const itemList = renderQueue.itemList;
@@ -210,6 +220,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);
 }
@@ -233,21 +258,27 @@ function getLightPassColorAttachments(ctx, colorAttachment) {
         attachments.push(ctx.SSSTransmissionTexture);
     }
     if (ctx.materialFlags & MaterialVaryingFlags.SKIN_SSS_STORE) {
-        attachments.push(ctx.SkinSSSTexture);
+        attachments.push(ctx.SSSMaskTexture);
     }
     return attachments.length === 1 ? attachments[0] : attachments;
 }
-/** Derive Forward+ options from scene and camera state. @internal */ function deriveForwardPlusOptions(scene, camera, deviceType, renderQueue) {
+/** Derive Forward+ options from scene and camera state. @internal */ function deriveForwardPlusOptions(scene, camera, _deviceType, renderQueue) {
     const ssr = camera.SSR && scene.env.light.envLight && scene.env.light.envLight.hasRadiance();
     const ssgi = camera.SSGI && camera.HDR && camera.ssgiIntensity > 0 && scene.env.light.type === 'ibl' && !!scene.env.light.envLight?.hasRadiance() && !!scene.env.light.envLight?.hasIrradiance();
     const sss = camera.SSS && renderQueueHasActiveSSS(renderQueue);
-    const skinSSS = camera.skinSSS && renderQueueHasActiveSkinSSS(renderQueue);
+    // No camera switch for this one: a skin material always wants its diffusion,
+    // and the queue already says whether the frame draws any.
+    const postSSS = renderQueueHasActivePostSSS(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.
+    const needHiZNearest = renderQueue.needHiZNearest() || camera.HiZNearest;
     return {
         depthPrepass: true,
         motionVectors: false,
-        hiZ: false,
+        hiZ: needHiZNearest,
+        hiZNearest: needHiZNearest,
         sceneNormal: false,
         sceneRoughness: false,
         shadowMask: false,
@@ -259,26 +290,22 @@ function getLightPassColorAttachments(ctx, colorAttachment) {
         needSceneColorWithDepth,
         needsTransmissionDepthForSSR: !!ssr && needSceneColor && !needSceneColorWithDepth,
         sss: !!sss,
-        skinSSS: !!skinSSS,
+        postSSS: !!postSSS,
+        // Driven entirely by postSSS: the id exists to serve the diffusion and the
+        // transmission thickness pass, and both are gated on the same condition.
+        sssProfileId: !!postSSS,
         fogPresents: !!scene.env.sky?.fogPresents
     };
 }
 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;
-    if (options.motionVectors && deviceType === 'webgl') {
-        throw new Error('Forward+: MotionVector was requested but is not supported by the WebGL backend.');
-    }
-    if (options.hiZ && deviceType === 'webgl') {
-        throw new Error('Forward+: HiZ was requested but is not supported by the WebGL backend.');
-    }
-    if (options.shadowMask && deviceType === 'webgl') {
-        throw new Error('Forward+: ShadowMask was requested but is not supported by the WebGL backend.');
-    }
     const surfaceAttachmentCount = Number(options.sceneNormal) + Number(options.sceneRoughness);
     if (surfaceAttachmentCount > 0) {
         const caps = ctx.device.getDeviceCaps();
@@ -292,6 +319,7 @@ function resolveFrameResourceRequirements(ctx, options, requirements) {
         }
     }
     ctx.motionVectors = options.motionVectors;
+    ctx.sssProfileId = options.sssProfileId;
     ctx.HiZ = options.hiZ;
     ctx.SSGI = options.ssgi;
     ctx.screenSpaceShadowMask = options.shadowMask;
@@ -359,8 +387,9 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
             ordering.emit(builder, 'ClusterLightsDone');
             builder.sideEffect();
             builder.setExecute(()=>{
-                ctx.clusteredLight = getClusteredLight();
-                ctx.clusteredLight.calculateLightIndex(ctx.camera, renderQueue, ctx.screenSpaceShadowMask, ShaderHelper.getPreExposure(ctx));
+                ctx.clusteredLight = ClusteredLight.acquire(ctx.renderWidth, ctx.renderHeight);
+                // The light passes draw into targets of the render size (see renderOpaqueScenePass).
+                ctx.clusteredLight.calculateLightIndex(ctx.camera, renderQueue, ctx.renderWidth, ctx.renderHeight, ctx.screenSpaceShadowMask, ShaderHelper.getPreExposure(ctx));
             });
         });
     }
@@ -401,12 +430,159 @@ 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 (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: [
         FrameResources.LinearDepth,
         FrameResources.MotionVector,
-        FrameResources.SceneDepthAttachment
+        FrameResources.SceneDepthAttachment,
+        FrameResources.SSSProfileId
     ],
     prepare: ()=>({
             enabled: true
@@ -415,7 +591,7 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
         const { graph, ctx, frame, ordering, blackboard, options } = fg;
         const result = graph.addPass('DepthPrepass', (builder)=>{
             ordering.chainInto(builder);
-            const format = ctx.device.type === 'webgl' ? ctx.SSRCalcThickness ? 'rgba16f' : 'rgba8unorm' : ctx.SSRCalcThickness ? 'rg32f' : 'r32f';
+            const format = ctx.SSRCalcThickness ? 'rg32f' : 'r32f';
             const mvFormat = 'rgba16f';
             const depthHandle = builder.createTexture({
                 format,
@@ -427,6 +603,14 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
                 label: 'motionVector',
                 allocationKey: 'ForwardPlus.MotionVector'
             }) : undefined;
+            // r8unorm is exact for this: the material writes `SSSProfile.encodedId`,
+            // i.e. `id / 255`, and the table holds 256 rows, so every representable id
+            // survives the round trip. 0 means "not skin".
+            const sssProfileIdHandle = options.sssProfileId ? builder.createTexture({
+                format: 'r8unorm',
+                label: 'sssProfileId',
+                allocationKey: 'ForwardPlus.SSSProfileId'
+            }) : undefined;
             const finalDepthAttachment = ctx.finalFramebuffer?.getDepthAttachment();
             const externalDepthAttachment = finalDepthAttachment?.isTexture2D() ? finalDepthAttachment : null;
             const externalDepthAttachmentHandle = externalDepthAttachment ? graph.importTexture('externalSceneDepth') : undefined;
@@ -436,14 +620,23 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
                 allocationKey: 'ForwardPlus.SceneDepth'
             });
             const depthAttachmentOrFormat = externalDepthAttachmentHandle ?? graphDepthAttachmentHandle ?? ctx.depthFormat;
+            // Order matters and has to agree with the fragment output declaration
+            // order in MeshMaterial._createProgram: linear depth, then the motion
+            // vector, then the profile id.
+            const prepassColorAttachments = [
+                depthHandle
+            ];
+            if (motionVectorHandle) {
+                prepassColorAttachments.push(motionVectorHandle);
+            }
+            if (sssProfileIdHandle) {
+                prepassColorAttachments.push(sssProfileIdHandle);
+            }
             const depthFramebufferHandle = builder.createFramebuffer({
                 label: 'DepthPrepassFramebuffer',
                 width: ctx.renderWidth,
                 height: ctx.renderHeight,
-                colorAttachments: motionVectorHandle ? [
-                    depthHandle,
-                    motionVectorHandle
-                ] : depthHandle,
+                colorAttachments: prepassColorAttachments.length === 1 ? depthHandle : prepassColorAttachments,
                 depthAttachment: depthAttachmentOrFormat,
                 ignoreDepthStencil: false
             });
@@ -471,6 +664,7 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
             return {
                 depthHandle,
                 motionVectorHandle,
+                sssProfileIdHandle: sssProfileIdHandle,
                 graphDepthAttachmentHandle,
                 externalDepthAttachmentHandle,
                 externalDepthAttachment,
@@ -483,6 +677,9 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
         if (result.motionVectorHandle) {
             blackboard.set(FrameResources.MotionVector, result.motionVectorHandle);
         }
+        if (result.sssProfileIdHandle) {
+            blackboard.set(FrameResources.SSSProfileId, result.sssProfileIdHandle);
+        }
         blackboard.set(FrameResources.SceneDepthAttachment, result.graphDepthAttachmentHandle ?? result.externalDepthAttachmentHandle);
         // Later modules share this attachment without owning it.
         fg.state.renderDepthAttachment = result.graphDepthAttachmentHandle ?? result.externalDepthAttachmentHandle ?? null;
@@ -500,7 +697,7 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
     prepare: ({ ctx, options, renderQueue })=>({
             enabled: options.shadowMask && renderQueue.shadowedLights.length > 0,
             requirements: {
-                shadowMask: ctx.device.type !== 'webgl' && ctx.camera.screenSpaceShadowMask && renderQueue.shadowedLights.length > 0
+                shadowMask: ctx.camera.screenSpaceShadowMask && renderQueue.shadowedLights.length > 0
             }
         }),
     setup (fg) {
@@ -539,6 +736,107 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
         blackboard.set(FrameResources.ShadowMask, maskPassResult.maskHandle);
     }
 };
+/** Orders a pass drawing scene materials after this camera's virtual texture update. @internal */ function readVirtualTextureToken(builder, blackboard) {
+    const token = blackboard.get(FrameResources.VirtualTexture);
+    if (token) {
+        builder.read(token);
+    }
+}
+/** Scene virtual texture clients active for this camera's frame. @internal */ function activeVirtualTextureClients(ctx, renderQueue) {
+    if (ctx.device.type !== 'webgpu') {
+        return [];
+    }
+    return ctx.scene.virtualTextureClients.filter((c)=>c.isActive?.(ctx, renderQueue) ?? true);
+}
+/**
+ * Updates the scene's virtual textures for this camera: mark from the depth prepass, map, fill.
+ */ const VirtualTextureModule = {
+    type: 'VirtualTextureUpdate',
+    reads: [
+        {
+            resource: FrameResources.LinearDepth
+        }
+    ],
+    writes: [
+        FrameResources.VirtualTexture
+    ],
+    prepare: ({ ctx, renderQueue })=>({
+            enabled: activeVirtualTextureClients(ctx, renderQueue).length > 0
+        }),
+    setup (fg) {
+        const { graph, ctx, renderQueue, blackboard } = fg;
+        const clients = activeVirtualTextureClients(ctx, renderQueue);
+        const token = graph.addPass('VirtualTextureUpdate', (builder)=>{
+            const depthHandle = blackboard.expect(FrameResources.LinearDepth);
+            builder.read(depthHandle);
+            // Page tables and pools are scene state the graph does not track
+            builder.sideEffect();
+            const token = builder.createToken('VirtualTextureDone');
+            builder.setExecute((rgCtx)=>{
+                const depthTex = rgCtx.getTexture(depthHandle);
+                const stamp = ctx.device.frameInfo.frameCounter;
+                for (const client of clients){
+                    client.markFromDepth?.(ctx, depthTex);
+                }
+                for (const client of clients){
+                    client.virtualTexture.update(stamp);
+                    client.fill(ctx);
+                }
+            });
+            return token;
+        });
+        blackboard.set(FrameResources.VirtualTexture, token);
+    }
+};
+/** @internal */ const TransmissionThicknessModule = {
+    type: 'TransmissionThicknessPass',
+    writes: [
+        FrameResources.TransmissionThickness
+    ],
+    prepare: ({ options, renderQueue })=>({
+            // Not gated on the device: transmission lights the subject directly in the
+            // base pass, so it does not depend on the WebGPU-only PostSSS diffusion.
+            enabled: options.postSSS && renderQueue.shadowedLights.some((light)=>light.transmission)
+        }),
+    setup (fg) {
+        const { graph, ctx, renderQueue, blackboard } = fg;
+        const depthPassResult = requireBuildState(fg, 'depth', 'DepthPrepass', 'TransmissionThicknessPass');
+        // The ordinal space is shared with the shadow mask so that a light's
+        // thickness and its shadow factor are found with the same arithmetic; that
+        // means the layer count follows the shadow light count, not the (smaller)
+        // transmission light count.
+        const numShadowLights = renderQueue.shadowedLights.length;
+        const numLayers = ShadowMaskRenderer.getLayerCount(numShadowLights);
+        const passResult = graph.addPass('TransmissionThicknessPass', (builder)=>{
+            const depthHandle = blackboard.expect(FrameResources.LinearDepth);
+            const sssProfileIdHandle = blackboard.expect(FrameResources.SSSProfileId);
+            builder.read(depthHandle);
+            builder.read(sssProfileIdHandle);
+            builder.read(depthPassResult.depthFramebufferHandle);
+            const thicknessHandle = builder.createTexture({
+                format: 'rgba8unorm',
+                label: 'transmissionThickness',
+                arrayLayers: numLayers,
+                allocationKey: 'ForwardPlus.TransmissionThickness'
+            });
+            builder.setExecute((rgCtx)=>{
+                const depthTex = rgCtx.getTexture(depthHandle);
+                const thicknessTex = rgCtx.getTexture(thicknessHandle);
+                _transmissionThicknessRenderer.render(ctx, depthTex, rgCtx.getTexture(sssProfileIdHandle), renderQueue.shadowedLights, (layer)=>rgCtx.createFramebuffer({
+                        width: thicknessTex.width,
+                        height: thicknessTex.height,
+                        colorAttachments: thicknessTex,
+                        depthAttachment: null,
+                        attachmentLayer: layer
+                    }));
+            });
+            return {
+                thicknessHandle
+            };
+        });
+        blackboard.set(FrameResources.TransmissionThickness, passResult.thicknessHandle);
+    }
+};
 /** @internal */ const TransmissionDepthForSSRModule = {
     type: 'TransmissionDepthForSSR',
     writes: [
@@ -580,7 +878,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);
@@ -593,11 +891,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',
@@ -633,9 +934,12 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
         const depthPassResult = requireBuildState(fg, 'depth', 'DepthPrepass', 'SSSProfile');
         const preLightTransmissionDepthToken = fg.state.preLightTransmissionDepthToken;
         const shadowMaskHandle = blackboard.get(FrameResources.ShadowMask);
+        const thicknessHandle = blackboard.get(FrameResources.TransmissionThickness);
+        const waterCausticsHandle = blackboard.get(FrameResources.WaterCaustics);
         const renderDepthAttachment = fg.state.renderDepthAttachment;
         const sssProfileResult = graph.addPass('SSSProfile', (builder)=>{
             builder.read(blackboard.expect(FrameResources.LinearDepth));
+            readVirtualTextureToken(builder, blackboard);
             builder.read(depthPassResult.depthFramebufferHandle);
             if (preLightTransmissionDepthToken) {
                 builder.read(preLightTransmissionDepthToken);
@@ -643,6 +947,15 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
             if (shadowMaskHandle) {
                 builder.read(shadowMaskHandle);
             }
+            if (thicknessHandle) {
+                builder.read(thicknessHandle);
+            }
+            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',
@@ -668,6 +981,7 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
             });
             builder.setExecute((rgCtx)=>{
                 ctx.shadowMaskTexture = shadowMaskHandle ? rgCtx.getTexture(shadowMaskHandle) : null;
+                ctx.transmissionThicknessTexture = thicknessHandle ? rgCtx.getTexture(thicknessHandle) : null;
                 renderForwardSSSProfile(frame, rgCtx.getFramebuffer(framebufferHandle), rgCtx.getTexture(profileHandle), rgCtx.getTexture(paramHandle), null);
             });
             return {
@@ -691,9 +1005,12 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
         const depthPassResult = requireBuildState(fg, 'depth', 'DepthPrepass', 'SceneColorGrab');
         const preLightTransmissionDepthToken = fg.state.preLightTransmissionDepthToken;
         const shadowMaskHandle = blackboard.get(FrameResources.ShadowMask);
+        const thicknessHandle = blackboard.get(FrameResources.TransmissionThickness);
+        const waterCausticsHandle = blackboard.get(FrameResources.WaterCaustics);
         const renderDepthAttachment = fg.state.renderDepthAttachment;
         const grabResult = graph.addPass('SceneColorGrab', (builder)=>{
             builder.read(blackboard.expect(FrameResources.LinearDepth));
+            readVirtualTextureToken(builder, blackboard);
             builder.read(depthPassResult.depthFramebufferHandle);
             if (preLightTransmissionDepthToken) {
                 builder.read(preLightTransmissionDepthToken);
@@ -701,9 +1018,37 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
             if (shadowMaskHandle) {
                 builder.read(shadowMaskHandle);
             }
+            if (thicknessHandle) {
+                builder.read(thicknessHandle);
+            }
+            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.
@@ -717,6 +1062,7 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
             }) : undefined;
             builder.setExecute((rgCtx)=>{
                 ctx.shadowMaskTexture = shadowMaskHandle ? rgCtx.getTexture(shadowMaskHandle) : null;
+                ctx.transmissionThicknessTexture = thicknessHandle ? rgCtx.getTexture(thicknessHandle) : null;
                 renderSceneColorGrab(frame, rgCtx, copyHandle, copyFramebufferHandle);
             });
             return {
@@ -735,7 +1081,7 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
         FrameResources.SceneNormal,
         FrameResources.SSSDiffuse,
         FrameResources.SSSTransmission,
-        FrameResources.SkinSSS
+        FrameResources.PostSSS
     ],
     prepare: ()=>({
             enabled: true
@@ -744,10 +1090,13 @@ 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 thicknessHandle = blackboard.get(FrameResources.TransmissionThickness);
+        const waterCausticsHandle = blackboard.get(FrameResources.WaterCaustics);
         const preLightTransmissionDepthToken = fg.state.preLightTransmissionDepthToken;
         const hiZHandle = blackboard.get(FrameResources.HiZ);
         const sssProfileHandle = blackboard.get(FrameResources.SSSProfile);
         const sssParamHandle = blackboard.get(FrameResources.SSSParam);
+        const sssProfileIdHandle = blackboard.get(FrameResources.SSSProfileId);
         const sceneColorCopyHandle = blackboard.get(FrameResources.SceneColorCopy);
         const useFinalFramebufferAsIntermediate = fg.state.useFinalFramebufferAsIntermediate;
         const renderDepthAttachment = fg.state.renderDepthAttachment;
@@ -810,10 +1159,20 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
         }
         const opaquePassResult = graph.addPass('LightPass', (builder)=>{
             builder.read(blackboard.expect(FrameResources.LinearDepth));
+            readVirtualTextureToken(builder, blackboard);
             builder.read(depthPassResult.depthFramebufferHandle);
             if (shadowMaskHandle) {
                 builder.read(shadowMaskHandle);
             }
+            if (thicknessHandle) {
+                builder.read(thicknessHandle);
+            }
+            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);
             }
@@ -838,6 +1197,11 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
             if (sssParamHandle) {
                 builder.read(sssParamHandle);
             }
+            // Reached through ctx.SSSProfileIdTexture, so the read must be declared or
+            // the executor may recycle the prepass target before the effect samples it.
+            if (sssProfileIdHandle) {
+                builder.read(sssProfileIdHandle);
+            }
             const surfaceAttachmentCount = Number(options.sceneRoughness) + Number(options.sceneNormal);
             // Surface MRT products are exposed through blackboard handles.
             const sceneRoughnessHandle = options.sceneRoughness ? builder.createTexture({
@@ -855,8 +1219,8 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
             if (writeSSSDiffuse && writeSSSTransmission && surfaceAttachmentCount > 0 && getSSSLightingTextureFormat(ctx, 2, surfaceAttachmentCount) !== ctx.colorFormat) {
                 writeSSSTransmission = false;
             }
-            const writeSkinSSS = options.skinSSS;
-            const sssLightingAttachmentCount = (writeSSSDiffuse ? 1 : 0) + (writeSSSTransmission ? 1 : 0) + (writeSkinSSS ? 1 : 0);
+            const writePostSSS = options.postSSS;
+            const sssLightingAttachmentCount = (writeSSSDiffuse ? 1 : 0) + (writeSSSTransmission ? 1 : 0) + (writePostSSS ? 1 : 0);
             const sssLightingFormat = getSSSLightingTextureFormat(ctx, sssLightingAttachmentCount, surfaceAttachmentCount);
             const sssDiffuseHandle = writeSSSDiffuse ? builder.createTexture({
                 format: sssLightingFormat,
@@ -868,10 +1232,10 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
                 label: 'sssTransmission',
                 allocationKey: 'ForwardPlus.SSSTransmission'
             }) : undefined;
-            const skinSSSHandle = writeSkinSSS ? builder.createTexture({
+            const postSSSHandle = writePostSSS ? builder.createTexture({
                 format: sssLightingFormat,
-                label: 'skinSSS',
-                allocationKey: 'ForwardPlus.SkinSSS'
+                label: 'postSSS',
+                allocationKey: 'ForwardPlus.PostSSS'
             }) : undefined;
             const sceneColorFramebufferHandle = useFinalFramebufferAsIntermediate ? undefined : builder.createFramebuffer({
                 label: 'SceneColorFramebuffer',
@@ -885,6 +1249,7 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
                 const sceneColorCopyTex = sceneColorCopyHandle ? rgCtx.getTexture(sceneColorCopyHandle) : null;
                 // Legacy effects still read resolved MRT textures from DrawContext.
                 ctx.shadowMaskTexture = shadowMaskHandle ? rgCtx.getTexture(shadowMaskHandle) : null;
+                ctx.transmissionThicknessTexture = thicknessHandle ? rgCtx.getTexture(thicknessHandle) : null;
                 ctx.HiZTexture = hiZHandle ? rgCtx.getTexture(hiZHandle) : null;
                 ctx.SceneRoughnessTexture = sceneRoughnessHandle ? rgCtx.getTexture(sceneRoughnessHandle) : null;
                 ctx.SceneNormalTexture = sceneNormalHandle ? rgCtx.getTexture(sceneNormalHandle) : null;
@@ -892,7 +1257,8 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
                 ctx.SSSParamTexture = sssParamHandle ? rgCtx.getTexture(sssParamHandle) : null;
                 ctx.SSSDiffuseTexture = sssDiffuseHandle ? rgCtx.getTexture(sssDiffuseHandle) : null;
                 ctx.SSSTransmissionTexture = sssTransmissionHandle ? rgCtx.getTexture(sssTransmissionHandle) : null;
-                ctx.SkinSSSTexture = skinSSSHandle ? rgCtx.getTexture(skinSSSHandle) : null;
+                ctx.SSSMaskTexture = postSSSHandle ? rgCtx.getTexture(postSSSHandle) : null;
+                ctx.SSSProfileIdTexture = sssProfileIdHandle ? rgCtx.getTexture(sssProfileIdHandle) : null;
                 const renderLightPass = ()=>renderOpaqueScenePass(frame, sceneColorTex, sceneColorCopyTex, rgCtx, sceneColorFramebufferHandle);
                 if (historyManager && lightHistoryReadBindings.length > 0) {
                     const ssgiIrradianceBinding = lightHistoryReadBindings.find((binding)=>binding.name === RGHistoryResources.SSGI_IRRADIANCE);
@@ -921,7 +1287,7 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
                 sceneNormalHandle,
                 sssDiffuseHandle,
                 sssTransmissionHandle,
-                skinSSSHandle
+                postSSSHandle: postSSSHandle
             };
         });
         const lightPassResult = opaquePassResult;
@@ -939,8 +1305,8 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
         if (lightPassResult.sssTransmissionHandle) {
             blackboard.set(FrameResources.SSSTransmission, lightPassResult.sssTransmissionHandle);
         }
-        if (lightPassResult.skinSSSHandle) {
-            blackboard.set(FrameResources.SkinSSS, lightPassResult.skinSSSHandle);
+        if (lightPassResult.postSSSHandle) {
+            blackboard.set(FrameResources.PostSSS, lightPassResult.postSSSHandle);
         }
     }
 };
@@ -1001,6 +1367,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: [
@@ -1017,6 +1445,8 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
         const hiZHandle = blackboard.get(FrameResources.HiZ);
         const sceneColorCopyHandle = blackboard.get(FrameResources.SceneColorCopy);
         const shadowMaskHandle = blackboard.get(FrameResources.ShadowMask);
+        const thicknessHandle = blackboard.get(FrameResources.TransmissionThickness);
+        const waterCausticsHandle = blackboard.get(FrameResources.WaterCaustics);
         const lightPassResult = requireBuildState(fg, 'lightPass', 'LightPass', 'CompositeTail');
         const renderDepthAttachment = fg.state.renderDepthAttachment;
         const useFinalFramebufferAsIntermediate = fg.state.useFinalFramebufferAsIntermediate;
@@ -1044,7 +1474,10 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
             blackboard.get(FrameResources.SceneNormal),
             blackboard.get(FrameResources.SSSDiffuse),
             blackboard.get(FrameResources.SSSTransmission),
-            blackboard.get(FrameResources.SkinSSS)
+            blackboard.get(FrameResources.PostSSS),
+            // Reached through ctx.SSSProfileIdTexture: without the dependency the
+            // allocator may hand the prepass target to a later pass.
+            blackboard.get(FrameResources.SSSProfileId)
         ]){
             if (handle) {
                 opaqueChainDeps.push(handle);
@@ -1069,6 +1502,7 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
         // Transparent geometry writes a new version of the opaque-chain output.
         const sceneColorHandle = graph.addPass('TransparentPass', (builder)=>{
             builder.read(blackboard.expect(FrameResources.LinearDepth));
+            readVirtualTextureToken(builder, blackboard);
             builder.read(depthPassResult.depthFramebufferHandle);
             if (hiZHandle) {
                 // Transparent materials may ray-march HiZ.
@@ -1090,6 +1524,16 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
                 // after LightPass while this pass is still sampling it.
                 builder.read(shadowMaskHandle);
             }
+            if (thicknessHandle) {
+                // Same reasoning as the shadow mask above: the thickness texture is
+                // bound by the shared clustered-light bind group, so its lifetime has to
+                // reach this pass too.
+                builder.read(thicknessHandle);
+            }
+            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)=>{
@@ -1097,6 +1541,7 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
                 // 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;
+                ctx.transmissionThicknessTexture = thicknessHandle ? rgCtx.getTexture(thicknessHandle) : null;
                 renderTransparentScenePass(frame, rgCtx, opaqueChainRan ? opaqueChainResult.color : null, lightPassResult.sceneColorFramebufferHandle);
             });
             return out;
@@ -1195,6 +1640,28 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
                 return outputBackbuffer;
             });
         }
+        // Debug views of raw data go on the presented image, past tone mapping and exposure
+        const sky = ctx.scene.env.sky;
+        if (sky.cloudDebugViewActive) {
+            const presentedBeforeDebug = presentedBackbuffer;
+            presentedBackbuffer = graph.addPass('VolumetricCloudDebug', (builder)=>{
+                const out = builder.write(presentedBeforeDebug);
+                builder.sideEffect();
+                builder.setExecute(()=>{
+                    const device = ctx.device;
+                    device.pushDeviceStates();
+                    try {
+                        device.setFramebuffer(ctx.finalFramebuffer ?? null);
+                        device.setViewport(null);
+                        device.setScissor(null);
+                        sky.drawCloudDebugView();
+                    } finally{
+                        device.popDeviceStates();
+                    }
+                });
+                return out;
+            });
+        }
         fg.state.presentedBackbuffer = presentedBackbuffer;
         // Downstream modules may replace this sink registration.
         blackboard.set(FrameResources.PresentedColor, presentedBackbuffer);
@@ -1205,14 +1672,18 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
     ClusterLights: ClusterLightsModule,
     GPUPicking: GPUPickingModule,
     ShadowMaps: ShadowMapsModule,
+    WaterCaustics: WaterCausticsModule,
     DepthPrepass: DepthPrepassModule,
+    VirtualTextureUpdate: VirtualTextureModule,
     ShadowMask: ShadowMaskModule,
+    TransmissionThickness: TransmissionThicknessModule,
     TransmissionDepthForSSR: TransmissionDepthForSSRModule,
     HiZ: HiZModule,
     SSSProfile: SSSProfileModule,
     SceneColorGrab: SceneColorGrabModule,
     LightPass: LightPassModule,
     SkyPass: SkyPassModule,
+    Underwater: UnderwaterModule,
     CompositeTail: CompositeTailModule
 };
 /** The default module order assembled by {@link createForwardPlusPipeline}. */ const DEFAULT_FORWARD_PLUS_MODULES = [
@@ -1220,14 +1691,18 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
     ClusterLightsModule,
     GPUPickingModule,
     ShadowMapsModule,
+    WaterCausticsModule,
     DepthPrepassModule,
+    VirtualTextureModule,
     ShadowMaskModule,
+    TransmissionThicknessModule,
     TransmissionDepthForSSRModule,
     HiZModule,
     SSSProfileModule,
     SceneColorGrabModule,
     LightPassModule,
     SkyPassModule,
+    UnderwaterModule,
     CompositeTailModule
 ];
 /** @internal */ let _defaultForwardPlusPipeline = null;
@@ -1250,11 +1725,24 @@ function buildForwardPlusGraphInternal(graph, ctx, renderQueue, options) {
     options.ssgi &&= supportsSSGIRenderTargets(ctx);
     ctx.SSS = !!options.sss;
     ctx.SSGI = !!options.ssgi;
+    ctx.postSSS = !!options.postSSS;
+    // Before the compositor is consulted below: it collects requirements from,
+    // and builds passes for, only the effects that are enabled at that moment.
+    ctx.camera?.setPostSSSActive(ctx.postSSS);
     ctx.SSGIIrradianceHistoryTexture = null;
     ctx.SSGISurfaceHistoryTexture = null;
-    ctx.SkinSSSTexture = null;
+    ctx.SSSMaskTexture = null;
+    ctx.SSSProfileIdTexture = null;
     // ShadowMask sets this only when it produces a texture.
     ctx.shadowMaskTexture = null;
+    ctx.transmissionThicknessTexture = 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,
@@ -1288,6 +1776,10 @@ function buildForwardPlusGraphInternal(graph, ctx, renderQueue, options) {
     const requirements = ctx.compositor?.collectRequirements(ctx) ?? {};
     mergeFrameResourceRequirements(requirements, pipeline.collectRequirements(fg));
     resolveFrameResourceRequirements(ctx, options, requirements);
+    // Must agree with TransmissionThicknessModule.prepare: the flag decides
+    // whether the light pass declares and binds the thickness texture, so a
+    // mismatch would leave the shader layout disagreeing with the bind group.
+    ctx.transmissionThickness = options.postSSS && renderQueue.shadowedLights.some((light)=>light.transmission);
     pipeline.build(fg);
     validateProducedFrameResources(blackboard, options, renderQueue);
     const presented = blackboard.get(FrameResources.PresentedColor) ?? fg.state.presentedBackbuffer;
@@ -1384,7 +1876,7 @@ function disposeRenderQueue(frame) {
 }
 function releaseClusteredLight(frame) {
     if (!frame.clusteredLightReleased && frame.ctx.clusteredLight) {
-        freeClusteredLight(frame.ctx.clusteredLight);
+        ClusteredLight.release(frame.ctx.clusteredLight);
         frame.ctx.clusteredLight = undefined;
         frame.clusteredLightReleased = true;
     }
@@ -1418,7 +1910,7 @@ function cleanupFrame(frame) {
     console.assert(!!existingDepthFb, 'renderSceneDepth: called without an existing depth framebuffer; the ' + 'self-allocating fallback path is untested in the forward+ pipeline.');
     if (!depthFramebuffer) {
         {
-            const format = ctx.device.type === 'webgl' ? ctx.SSRCalcThickness ? 'rgba16f' : 'rgba8unorm' : ctx.SSRCalcThickness ? 'rg32f' : 'r32f';
+            const format = ctx.SSRCalcThickness ? 'rg32f' : 'r32f';
             const mvFormat = 'rgba16f';
             if (!ctx.finalFramebuffer) {
                 depthFramebuffer = rgCtx.createFramebuffer({
@@ -1467,6 +1959,27 @@ function cleanupFrame(frame) {
         ctx.device.setFramebuffer(depthFramebuffer);
         _depthPass.encodeDepth = depthFramebuffer.getColorAttachments()[0].format === 'rgba8unorm';
         _depthPass.clearColor = transmission ? null : _depthPass.encodeDepth ? new Vector4(0, 0, 0, 1) : new Vector4(1, 1, 1, 1);
+        // That clear value is chosen for the linear depth target, where 1 is the far
+        // plane. The profile id target needs the opposite: 0 means "not skin", and
+        // every other value addresses a real row of the profile table. Clearing it
+        // alongside the depth made each background texel read as profile 255, so a
+        // sampling disc wide enough to reach past the silhouette accepted those taps
+        // and averaged the background into the skin instead of rejecting it — as
+        // dark speckle, since only the pixels whose sequence happened to draw a
+        // long radius reached that far.
+        //
+        // Assigning clearColor above resets the per-target list, so this has to come
+        // after it; that also means a frame without the target cannot inherit a
+        // stale list.
+        if (!transmission && ctx.sssProfileId) {
+            const attachmentCount = depthFramebuffer.getColorAttachments().length;
+            if (attachmentCount > 1) {
+                // The id is appended last; see DepthPrepassModule.
+                const clearColors = new Array(attachmentCount).fill(_depthPass.clearColor);
+                clearColors[attachmentCount - 1] = SKIN_PROFILE_ID_CLEAR;
+                _depthPass.clearColors = clearColors;
+            }
+        }
         _depthPass.clearDepth = transmission ? null : DEPTH_CLEAR_VALUE;
         _depthPass.clearStencil = null;
         _depthPass.transmission = transmission;
@@ -1674,7 +2187,7 @@ function blitToCurrentColorAttachment(ctx, source) {
             ctx.materialFlags |= MaterialVaryingFlags.SSS_STORE_TRANSMISSION;
         }
     }
-    if (ctx.SkinSSSTexture) {
+    if (ctx.SSSMaskTexture) {
         ctx.materialFlags |= MaterialVaryingFlags.SKIN_SSS_STORE;
     }
     // Prefer the graph framebuffer; final-target mode has no graph framebuffer.
@@ -1740,7 +2253,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
@@ -1822,8 +2339,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) {