@zephyr3d/scene 0.9.27 → 0.10.0

package/dist/render/rendergraph/forward_plus_builder.js

@@ -5,6 +5,7 @@ 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 { TransmissionThicknessRenderer } from '../transmission_thickness_pass.js';
 import { getHiZFormat, buildHiZ } from '../hzb.js';
 import '../primitive.js';
 import '@zephyr3d/device';
@@ -25,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';
@@ -38,11 +40,18 @@ 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);
@@ -59,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;
@@ -92,7 +95,7 @@ function renderQueueHasActiveSSS(renderQueue) {
     }
     return false;
 }
-function renderQueueHasActiveSkinSSS(renderQueue) {
+function renderQueueHasActivePostSSS(renderQueue) {
     const itemList = renderQueue.itemList;
     if (!itemList) {
         return false;
@@ -103,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;
             }
         }
@@ -129,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
     };
 }
@@ -141,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;
@@ -253,22 +258,22 @@ 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. 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';
+    // instead of in resolveFrameResourceRequirements.
+    const needHiZNearest = renderQueue.needHiZNearest() || camera.HiZNearest;
     return {
         depthPrepass: true,
         motionVectors: false,
@@ -285,12 +290,14 @@ 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.hiZNearest ||= !!requirements.hiZNearest;
     // The nearest channel lives on the same pyramid, so asking for it is asking
@@ -299,15 +306,6 @@ function resolveFrameResourceRequirements(ctx, options, requirements) {
     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();
@@ -321,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;
@@ -388,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));
             });
         });
     }
@@ -439,7 +439,7 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
  * most likely to be looking through.
  * @internal
  */ function selectWaterCausticSource(ctx, renderQueue) {
-    if (ctx.device.type === 'webgl' || renderQueue.waters.length === 0) {
+    if (renderQueue.waters.length === 0) {
         return null;
     }
     // The caustic light must own an additive shadow pass, because that is the pass
@@ -581,7 +581,8 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
     writes: [
         FrameResources.LinearDepth,
         FrameResources.MotionVector,
-        FrameResources.SceneDepthAttachment
+        FrameResources.SceneDepthAttachment,
+        FrameResources.SSSProfileId
     ],
     prepare: ()=>({
             enabled: true
@@ -590,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,
@@ -602,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;
@@ -611,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
             });
@@ -646,6 +664,7 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
             return {
                 depthHandle,
                 motionVectorHandle,
+                sssProfileIdHandle: sssProfileIdHandle,
                 graphDepthAttachmentHandle,
                 externalDepthAttachmentHandle,
                 externalDepthAttachment,
@@ -658,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;
@@ -675,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) {
@@ -714,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: [
@@ -811,10 +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);
@@ -822,6 +947,9 @@ 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
@@ -853,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 {
@@ -876,10 +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);
@@ -887,6 +1018,9 @@ 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
@@ -928,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 {
@@ -946,7 +1081,7 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
         FrameResources.SceneNormal,
         FrameResources.SSSDiffuse,
         FrameResources.SSSTransmission,
-        FrameResources.SkinSSS
+        FrameResources.PostSSS
     ],
     prepare: ()=>({
             enabled: true
@@ -955,11 +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;
@@ -1022,10 +1159,14 @@ 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
@@ -1056,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({
@@ -1073,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,
@@ -1086,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',
@@ -1103,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;
@@ -1110,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);
@@ -1139,7 +1287,7 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
                 sceneNormalHandle,
                 sssDiffuseHandle,
                 sssTransmissionHandle,
-                skinSSSHandle
+                postSSSHandle: postSSSHandle
             };
         });
         const lightPassResult = opaquePassResult;
@@ -1157,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);
         }
     }
 };
@@ -1297,6 +1445,7 @@ 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;
@@ -1325,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);
@@ -1350,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.
@@ -1371,6 +1524,12 @@ 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);
@@ -1382,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;
@@ -1480,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);
@@ -1492,7 +1674,9 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
     ShadowMaps: ShadowMapsModule,
     WaterCaustics: WaterCausticsModule,
     DepthPrepass: DepthPrepassModule,
+    VirtualTextureUpdate: VirtualTextureModule,
     ShadowMask: ShadowMaskModule,
+    TransmissionThickness: TransmissionThicknessModule,
     TransmissionDepthForSSR: TransmissionDepthForSSRModule,
     HiZ: HiZModule,
     SSSProfile: SSSProfileModule,
@@ -1509,7 +1693,9 @@ function validateProducedFrameResources(blackboard, options, renderQueue) {
     ShadowMapsModule,
     WaterCausticsModule,
     DepthPrepassModule,
+    VirtualTextureModule,
     ShadowMaskModule,
+    TransmissionThicknessModule,
     TransmissionDepthForSSRModule,
     HiZModule,
     SSSProfileModule,
@@ -1539,11 +1725,17 @@ 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;
@@ -1584,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;
@@ -1680,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;
     }
@@ -1714,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({
@@ -1763,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;
@@ -1970,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.