@zephyr3d/scene 0.9.18 → 0.9.20

package/dist/render/rendergraph/forward_plus_builder.js

@@ -4,18 +4,20 @@ 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 '../primitive.js';
 import '@zephyr3d/device';
 import { CopyBlitter } from '../../blitter/copy.js';
 import { fetchSampler } from '../../utility/misc.js';
 import { MaterialVaryingFlags } from '../../values.js';
-import { AbstractPostEffect, PostEffectLayer } from '../../posteffect/posteffect.js';
+import { PostEffectLayer, AbstractPostEffect } from '../../posteffect/posteffect.js';
 import { RenderGraph } from './rendergraph.js';
 import { RenderGraphExecutor } from './executor.js';
 import { DevicePoolAllocator } from './device_pool_allocator.js';
 import { HistoryResourceManager } from './history_resource_manager.js';
 import { RGHistoryResources } from './history_resources.js';
+import { FrameResources, RGBlackboard } from './blackboard.js';
 import { renderObjectColors } from '../gpu_picking.js';
 import { BoxShape } from '../../shapes/box.js';
 import '../../shapes/capsule.js';
@@ -30,6 +32,7 @@ const _scenePass = new LightPass();
 const _depthPass = new DepthPass();
 const _shadowMapPass = new ShadowMapPass();
 const _clusters = [];
+const _shadowMaskRenderer = new ShadowMaskRenderer();
 const _devicePoolAllocator = new DevicePoolAllocator();
 let _backDepthColorState = null;
 let _frontDepthColorState = null;
@@ -173,9 +176,11 @@ function getSSSLightingTextureFormat(ctx, attachmentCount, includeSSRSurfaceMRT)
         return colorFormat;
     }
     const caps = ctx.device.getDeviceCaps();
-    const roughnessFormat = ctx.SSRRoughnessTexture?.format ?? colorFormat;
-    const normalFormat = ctx.SSRNormalTexture?.format ?? colorFormat;
-    const colorBytes = getTextureFormatBytes(ctx, colorFormat) + getTextureFormatBytes(ctx, roughnessFormat) + getTextureFormatBytes(ctx, normalFormat);
+    // The SSR roughness/normal MRT textures use the glossy surface format; they
+    // are graph textures now, so derive the format directly instead of reading
+    // the (not yet resolved) DrawContext fields.
+    const surfaceFormat = getSurfaceTextureFormat(ctx);
+    const colorBytes = getTextureFormatBytes(ctx, colorFormat) + getTextureFormatBytes(ctx, surfaceFormat) + getTextureFormatBytes(ctx, surfaceFormat);
     const fullPrecisionBytes = colorBytes + getTextureFormatBytes(ctx, colorFormat) * attachmentCount;
     if (fullPrecisionBytes <= caps.framebufferCaps.maxColorAttachmentBytesPerSample) {
         return colorFormat;
@@ -256,6 +261,8 @@ function buildForwardPlusGraphInternal(graph, ctx, renderQueue, options) {
     const backbuffer = graph.importTexture('backbuffer');
     ctx.SSS = !!options.sss;
     ctx.SkinSSSTexture = null;
+    // Named registry of shared frame resources (consumed by post effect setup)
+    const blackboard = new RGBlackboard();
     // Shared mutable frame state
     const frame = {
         ctx,
@@ -263,7 +270,6 @@ function buildForwardPlusGraphInternal(graph, ctx, renderQueue, options) {
         depthFramebuffer: null,
         sunLightColor: null,
         options,
-        intermediateDeviceStatePushed: false,
         renderQueueDisposed: false,
         clusteredLightReleased: false,
         sunLightRestored: false
@@ -372,21 +378,99 @@ function buildForwardPlusGraphInternal(graph, ctx, renderQueue, options) {
             depthFramebufferHandle
         };
     });
-    const depthHandle = depthPassResult.depthHandle;
+    let depthHandle = depthPassResult.depthHandle;
     const motionVectorHandle = depthPassResult.motionVectorHandle;
+    blackboard.set(FrameResources.LinearDepth, depthHandle);
+    if (motionVectorHandle) {
+        blackboard.set(FrameResources.MotionVector, motionVectorHandle);
+    }
+    if (depthPassResult.graphDepthAttachmentHandle) {
+        blackboard.set(FrameResources.SceneDepthAttachment, depthPassResult.graphDepthAttachmentHandle);
+    }
+    // ── Screen-space shadow mask ────────────────────────────────────────────
+    // When active, render each shadow-casting light's visibility into an RGBA8
+    // texture array (4 lights per layer). The clustered LightPass samples this
+    // mask instead of each shadowed light running its own additive pass. The
+    // layer/channel order is locked to ClusteredLight.getVisibleLights: shadow
+    // lights fill clustered buffer indices 1..N in renderQueue.shadowedLights
+    // order, and ordinal s = index-1 maps to layer s>>2, channel s&3.
+    let shadowMaskHandle = null;
+    // Reset any mask carried over from a previous frame; the pass below re-sets it
+    // during execution only when the mask is actually produced.
+    ctx.shadowMaskTexture = null;
+    // Gate on build-time state only: renderQueue.shadowedLights is available now,
+    // whereas ctx.shadowMapInfo is populated later by the ShadowMaps pass execute
+    // (which runs before this pass thanks to the orderToken chain), so it must not
+    // be part of the pass-creation condition.
+    const useShadowMask = ctx.screenSpaceShadowMask && renderQueue.shadowedLights.length > 0;
+    if (useShadowMask) {
+        const numShadowLights = renderQueue.shadowedLights.length;
+        const numLayers = ShadowMaskRenderer.getLayerCount(numShadowLights);
+        const maskPassResult = graph.addPass('ShadowMaskPass', (builder)=>{
+            builder.read(depthHandle);
+            builder.read(depthPassResult.depthFramebufferHandle);
+            // createTexture already registers this pass as the resource producer, so
+            // downstream passes read this handle directly (same pattern as HiZ). The
+            // per-layer framebuffers are created inside execute (rgCtx.createFramebuffer),
+            // which the graph cannot see; the createTexture producer edge is what keeps
+            // the resource alive and ordered before the LightPass reader.
+            const maskHandle = builder.createTexture({
+                format: 'rgba8unorm',
+                label: 'shadowMask',
+                arrayLayers: numLayers
+            });
+            builder.setExecute((rgCtx)=>{
+                const depthTex = rgCtx.getTexture(depthHandle);
+                const maskTex = rgCtx.getTexture(maskHandle);
+                _shadowMaskRenderer.render(ctx, depthTex, renderQueue.shadowedLights, (layer)=>rgCtx.createFramebuffer({
+                        width: maskTex.width,
+                        height: maskTex.height,
+                        colorAttachments: maskTex,
+                        depthAttachment: null,
+                        attachmentLayer: layer
+                    }));
+                ctx.shadowMaskTexture = maskTex;
+            });
+            return {
+                maskHandle
+            };
+        });
+        shadowMaskHandle = maskPassResult.maskHandle;
+        blackboard.set(FrameResources.ShadowMask, shadowMaskHandle);
+    }
     const renderDepthAttachment = depthPassResult.graphDepthAttachmentHandle ?? depthPassResult.externalDepthAttachment ?? null;
-    const useFinalFramebufferAsIntermediate = !!depthPassResult.externalDepthAttachment && depthPassResult.externalDepthAttachment === ctx.finalFramebuffer?.getDepthAttachment();
+    // Rendering the scene directly into the final framebuffer is only possible
+    // when no opaque-layer effect is enabled: those effects must sample the
+    // opaque scene color as a texture and may require surface MRT attachments
+    // (SSR roughness / SSS / SkinSSS), which the single-color final framebuffer
+    // cannot carry. The legacy compositor.begin() used to redirect rendering to
+    // a temporal MRT framebuffer in that case; the graph path uses the regular
+    // scene color texture pipeline instead.
+    const opaqueLayerHasEffects = !!ctx.compositor?.layerHasEnabledEffect(PostEffectLayer.opaque);
+    const useFinalFramebufferAsIntermediate = !!depthPassResult.externalDepthAttachment && depthPassResult.externalDepthAttachment === ctx.finalFramebuffer?.getDepthAttachment() && !opaqueLayerHasEffects;
     let preLightTransmissionDepthToken;
     if (options.needsTransmissionDepthForSSR) {
-        preLightTransmissionDepthToken = graph.addPass('TransmissionDepthForSSR', (builder)=>{
+        const transmissionDepthResult = graph.addPass('TransmissionDepthForSSR', (builder)=>{
+            builder.read(depthHandle);
             builder.read(depthPassResult.depthFramebufferHandle);
+            // This pass renders transmission geometry into the prepass linear-depth
+            // texture: model the mutation as a write so later readers order against
+            // it through data flow instead of relying on the token alone.
+            const depthOut = builder.write(depthHandle);
             const done = builder.createToken('TransmissionDepthForSSRDone');
             builder.sideEffect();
             builder.setExecute((rgCtx)=>{
                 renderTransmissionDepthPass(frame, rgCtx);
             });
-            return done;
+            return {
+                done,
+                depthOut
+            };
         });
+        preLightTransmissionDepthToken = transmissionDepthResult.done;
+        depthHandle = transmissionDepthResult.depthOut;
+        // Re-register so blackboard consumers read the post-transmission version.
+        blackboard.set(FrameResources.LinearDepth, depthHandle);
     }
     // ── 6. Hi-Z (optional) ───────────────────────────────────────────
     let hiZHandle;
@@ -398,7 +482,7 @@ function buildForwardPlusGraphInternal(graph, ctx, renderQueue, options) {
                 builder.read(preLightTransmissionDepthToken);
             }
             hiZHandle = builder.createTexture({
-                format: 'r32f',
+                format: 'rg32f',
                 label: 'hiZ',
                 mipLevels: getFullMipLevelCount(ctx.renderWidth, ctx.renderHeight)
             });
@@ -420,11 +504,13 @@ function buildForwardPlusGraphInternal(graph, ctx, renderQueue, options) {
                 }
             });
         });
+        if (hiZHandle) {
+            blackboard.set(FrameResources.HiZ, hiZHandle);
+        }
     }
     // ── 7. Main Light Pass ────────────────────────────────────────────
     const historyManager = ctx.camera?.getHistoryResourceManager?.() ?? null;
     const lightHistoryReadBindings = [];
-    const compositeHistoryReadBindings = [];
     const historySize = {
         width: ctx.renderWidth,
         height: ctx.renderHeight
@@ -452,29 +538,7 @@ function buildForwardPlusGraphInternal(graph, ctx, renderQueue, options) {
             });
         }
     }
-    if (historyManager && ctx.camera?.TAA && options.motionVectors) {
-        const colorHistoryHandle = historyManager.importPreviousIfCompatible(graph, RGHistoryResources.TAA_COLOR, {
-            format: ctx.colorFormat,
-            sizeMode: 'absolute',
-            width: ctx.renderWidth,
-            height: ctx.renderHeight
-        }, historySize);
-        const motionVectorHistoryHandle = historyManager.importPreviousIfCompatible(graph, RGHistoryResources.TAA_MOTION_VECTOR, {
-            format: 'rgba16f',
-            sizeMode: 'absolute',
-            width: ctx.renderWidth,
-            height: ctx.renderHeight
-        }, historySize);
-        if (colorHistoryHandle && motionVectorHistoryHandle) {
-            compositeHistoryReadBindings.push({
-                name: RGHistoryResources.TAA_COLOR,
-                handle: colorHistoryHandle
-            }, {
-                name: RGHistoryResources.TAA_MOTION_VECTOR,
-                handle: motionVectorHistoryHandle
-            });
-        }
-    }
+    // Note: TAA history import/commit is handled by TAA.setup() (self-describing).
     let sssProfileResult;
     if (options.sss) {
         sssProfileResult = graph.addPass('SSSProfile', (builder)=>{
@@ -524,9 +588,47 @@ function buildForwardPlusGraphInternal(graph, ctx, renderQueue, options) {
             };
         });
     }
+    // 7b. Scene color grab: renders the full scene (no transmission) into a copy
+    // texture that transmission/refraction materials sample as background.
+    // Extracted from the former monolithic light pass.
+    let grabResult;
+    if (options.needSceneColor) {
+        grabResult = graph.addPass('SceneColorGrab', (builder)=>{
+            builder.read(depthHandle);
+            builder.read(depthPassResult.depthFramebufferHandle);
+            if (preLightTransmissionDepthToken) {
+                builder.read(preLightTransmissionDepthToken);
+            }
+            const copyHandle = builder.createTexture({
+                format: ctx.colorFormat,
+                label: 'sceneColorCopy'
+            });
+            // SSR may pre-insert transmission depth before LightPass for Hi-Z. In that
+            // case the refraction scene-color copy needs an isolated depth buffer so
+            // transmission surfaces do not occlude the background they sample.
+            const copyFramebufferHandle = !options.needsTransmissionDepthForSSR ? builder.createFramebuffer({
+                label: 'SceneColorCopyFramebuffer',
+                width: ctx.renderWidth,
+                height: ctx.renderHeight,
+                colorAttachments: copyHandle,
+                depthAttachment: renderDepthAttachment,
+                ignoreDepthStencil: false
+            }) : undefined;
+            builder.setExecute((rgCtx)=>{
+                renderSceneColorGrab(frame, rgCtx, copyHandle, copyFramebufferHandle);
+            });
+            return {
+                copyHandle,
+                copyFramebufferHandle
+            };
+        });
+    }
     const lightPassResult = graph.addPass('LightPass', (builder)=>{
         builder.read(depthHandle);
         builder.read(depthPassResult.depthFramebufferHandle);
+        if (shadowMaskHandle) {
+            builder.read(shadowMaskHandle);
+        }
         if (preLightTransmissionDepthToken) {
             builder.read(preLightTransmissionDepthToken);
         }
@@ -536,18 +638,18 @@ function buildForwardPlusGraphInternal(graph, ctx, renderQueue, options) {
         for (const binding of lightHistoryReadBindings){
             builder.read(binding.handle);
         }
-        // Create scene color texture (intermediate render target)
-        const sceneColorHandle = builder.createTexture({
+        // Scene color: in final-framebuffer-as-intermediate mode the scene is
+        // physically rendered into the final framebuffer, so declare the
+        // backbuffer write — the graph sees the real data flow and no keep-alive
+        // reads are needed downstream. Otherwise render into a graph texture.
+        const sceneColorHandle = useFinalFramebufferAsIntermediate ? builder.write(backbuffer) : builder.createTexture({
             format: ctx.colorFormat,
             label: 'sceneColor'
         });
-        // Create optional sceneColorCopy for transmission/refraction materials
-        let sceneColorCopyHandle;
-        if (options.needSceneColor) {
-            sceneColorCopyHandle = builder.createTexture({
-                format: ctx.colorFormat,
-                label: 'sceneColorCopy'
-            });
+        // Transmission/refraction background produced by the SceneColorGrab pass
+        const sceneColorCopyHandle = grabResult?.copyHandle;
+        if (sceneColorCopyHandle) {
+            builder.read(sceneColorCopyHandle);
         }
         if (sssProfileResult) {
             builder.read(sssProfileResult.profileHandle);
@@ -557,6 +659,17 @@ function buildForwardPlusGraphInternal(graph, ctx, renderQueue, options) {
             }
         }
         const includeSSRSurfaceMRT = !!options.ssr;
+        // SSR glossy-surface MRT outputs (roughness + world normal) are graph
+        // textures owned by this pass; effects reach them through the blackboard
+        // handles (or the ctx fields resolved below during execution).
+        const ssrRoughnessHandle = includeSSRSurfaceMRT ? builder.createTexture({
+            format: getSurfaceTextureFormat(ctx),
+            label: 'ssrRoughness'
+        }) : undefined;
+        const ssrNormalHandle = includeSSRSurfaceMRT ? builder.createTexture({
+            format: getSurfaceTextureFormat(ctx),
+            label: 'ssrNormal'
+        }) : undefined;
         const writeSSSDiffuse = options.sss && shouldStoreSSSDiffuse(ctx);
         let writeSSSTransmission = options.sss && shouldStoreSSSTransmission(ctx);
         if (writeSSSDiffuse && writeSSSTransmission && includeSSRSurfaceMRT && getSSSLightingTextureFormat(ctx, 2, includeSSRSurfaceMRT) !== ctx.colorFormat) {
@@ -584,20 +697,13 @@ function buildForwardPlusGraphInternal(graph, ctx, renderQueue, options) {
             colorAttachments: sceneColorHandle,
             depthAttachment: renderDepthAttachment
         });
-        // SSR may pre-insert transmission depth before LightPass for Hi-Z. In that case the
-        // refraction scene-color copy needs an isolated depth buffer so transmission surfaces
-        // do not occlude the background color they are about to sample.
-        const sceneColorCopyFramebufferHandle = sceneColorCopyHandle && !options.needsTransmissionDepthForSSR ? builder.createFramebuffer({
-            label: 'SceneColorCopyFramebuffer',
-            width: ctx.renderWidth,
-            height: ctx.renderHeight,
-            colorAttachments: sceneColorCopyHandle,
-            depthAttachment: renderDepthAttachment,
-            ignoreDepthStencil: false
-        }) : undefined;
         builder.setExecute((rgCtx)=>{
             const sceneColorTex = rgCtx.getTexture(sceneColorHandle);
             const sceneColorCopyTex = sceneColorCopyHandle ? rgCtx.getTexture(sceneColorCopyHandle) : null;
+            // Resolve MRT products into the DrawContext bridge fields that scene
+            // rendering and apply()-based effects still read.
+            ctx.SSRRoughnessTexture = ssrRoughnessHandle ? rgCtx.getTexture(ssrRoughnessHandle) : null;
+            ctx.SSRNormalTexture = ssrNormalHandle ? rgCtx.getTexture(ssrNormalHandle) : null;
             if (sssProfileResult) {
                 ctx.SSSProfileTexture = rgCtx.getTexture(sssProfileResult.profileHandle);
                 ctx.SSSParamTexture = rgCtx.getTexture(sssProfileResult.paramHandle);
@@ -608,7 +714,7 @@ function buildForwardPlusGraphInternal(graph, ctx, renderQueue, options) {
             ctx.SSSDiffuseTexture = sssDiffuseHandle ? rgCtx.getTexture(sssDiffuseHandle) : null;
             ctx.SSSTransmissionTexture = sssTransmissionHandle ? rgCtx.getTexture(sssTransmissionHandle) : null;
             ctx.SkinSSSTexture = skinSSSHandle ? rgCtx.getTexture(skinSSSHandle) : null;
-            const renderLightPass = ()=>renderMainLightPass(frame, sceneColorTex, sceneColorCopyTex, rgCtx, sceneColorFramebufferHandle, sceneColorCopyFramebufferHandle);
+            const renderLightPass = ()=>renderOpaqueScenePass(frame, sceneColorTex, sceneColorCopyTex, rgCtx, sceneColorFramebufferHandle);
             if (historyManager && lightHistoryReadBindings.length > 0) {
                 historyManager.beginReadScope(lightHistoryReadBindings.map((binding)=>({
                         name: binding.name,
@@ -626,66 +732,247 @@ function buildForwardPlusGraphInternal(graph, ctx, renderQueue, options) {
         return {
             sceneColorHandle,
             sceneColorCopyHandle,
-            sceneColorFramebufferHandle
+            sceneColorFramebufferHandle,
+            ssrRoughnessHandle,
+            ssrNormalHandle,
+            sssDiffuseHandle,
+            sssTransmissionHandle,
+            skinSSSHandle
         };
     });
-    const sceneColorHandle = lightPassResult.sceneColorHandle;
-    // 8. Transmission depth pass (optional)
-    let transmissionDepthToken;
-    if (options.needSceneColor && !options.needsTransmissionDepthForSSR) {
-        transmissionDepthToken = graph.addPass('TransmissionDepth', (builder)=>{
-            builder.read(sceneColorHandle);
-            builder.read(depthPassResult.depthFramebufferHandle);
-            const done = builder.createToken('TransmissionDepthDone');
-            builder.sideEffect();
-            builder.setExecute((rgCtx)=>{
-                renderTransmissionDepthPass(frame, rgCtx);
-            });
-            return done;
-        });
+    // Register the LightPass MRT products so effects can look them up by name.
+    if (lightPassResult.ssrRoughnessHandle) {
+        blackboard.set(FrameResources.SSRRoughness, lightPassResult.ssrRoughnessHandle);
+    }
+    if (lightPassResult.ssrNormalHandle) {
+        blackboard.set(FrameResources.SSRNormal, lightPassResult.ssrNormalHandle);
+    } else if (sssProfileResult?.normalHandle) {
+        blackboard.set(FrameResources.SSRNormal, sssProfileResult.normalHandle);
+    }
+    if (lightPassResult.sssDiffuseHandle) {
+        blackboard.set(FrameResources.SSSDiffuse, lightPassResult.sssDiffuseHandle);
+    }
+    if (lightPassResult.sssTransmissionHandle) {
+        blackboard.set(FrameResources.SSSTransmission, lightPassResult.sssTransmissionHandle);
+    }
+    if (lightPassResult.skinSSSHandle) {
+        blackboard.set(FrameResources.SkinSSS, lightPassResult.skinSSSHandle);
     }
-    // 9. Post effects + final composite
-    const presentedBackbuffer = graph.addPass('Composite', (builder)=>{
-        builder.read(sceneColorHandle);
+    // 7d. Opaque-layer post effects (SAO/SSR/SSS/SkinSSS). They read the opaque
+    // scene color and must complete before transparent geometry renders on top
+    // of their output. Never direct-write: the chain output becomes the
+    // transparent pass's render target. In final-framebuffer-as-intermediate
+    // mode the scene color handle is the LightPass's backbuffer write version,
+    // so the data flow is real either way — no keep-alive reads needed.
+    const opaqueChainInput = lightPassResult.sceneColorHandle;
+    // Data dependencies for every effect pass: frame textures the effects sample
+    // through DrawContext fields (linear depth, HiZ, scene color copy, SSS MRT
+    // outputs) rather than through declared require* hooks.
+    const opaqueChainDeps = [
+        depthHandle
+    ];
+    if (hiZHandle) {
+        opaqueChainDeps.push(hiZHandle);
+    }
+    if (lightPassResult.sceneColorFramebufferHandle) {
+        opaqueChainDeps.push(lightPassResult.sceneColorFramebufferHandle);
+    }
+    if (grabResult) {
+        opaqueChainDeps.push(grabResult.copyHandle);
+    }
+    if (sssProfileResult) {
+        opaqueChainDeps.push(sssProfileResult.profileHandle, sssProfileResult.paramHandle);
+        if (sssProfileResult.normalHandle) {
+            opaqueChainDeps.push(sssProfileResult.normalHandle);
+        }
+    }
+    for (const handle of [
+        lightPassResult.ssrRoughnessHandle,
+        lightPassResult.ssrNormalHandle,
+        lightPassResult.sssDiffuseHandle,
+        lightPassResult.sssTransmissionHandle,
+        lightPassResult.skinSSSHandle
+    ]){
+        if (handle) {
+            opaqueChainDeps.push(handle);
+        }
+    }
+    const opaqueChainResult = ctx.compositor ? ctx.compositor.buildLayer({
+        graph,
+        ctx,
+        layer: PostEffectLayer.opaque,
+        blackboard,
+        input: opaqueChainInput,
+        finalOutput: null,
+        sceneDepthAttachment: renderDepthAttachment,
+        dependencies: opaqueChainDeps,
+        historyReads: lightHistoryReadBindings,
+        history: historyManager
+    }) : {
+        color: opaqueChainInput,
+        wroteFinal: false
+    };
+    const opaqueChainRan = opaqueChainResult.color !== opaqueChainInput;
+    // 7e. Transparent scene geometry (transmission/transparent lists + OIT).
+    // Renders on top of the opaque-chain output; graph-wise an in-place write
+    // producing a new version of the current scene color.
+    const sceneColorHandle = graph.addPass('TransparentPass', (builder)=>{
         builder.read(depthHandle);
+        builder.read(depthPassResult.depthFramebufferHandle);
         if (hiZHandle) {
+            // Transparent-phase materials may ray-march HiZ (e.g. water SSR)
             builder.read(hiZHandle);
         }
-        if (motionVectorHandle) {
-            builder.read(motionVectorHandle);
-        }
         if (lightPassResult.sceneColorFramebufferHandle) {
             builder.read(lightPassResult.sceneColorFramebufferHandle);
         }
-        if (transmissionDepthToken) {
-            builder.read(transmissionDepthToken);
+        if (lightPassResult.sceneColorCopyHandle) {
+            builder.read(lightPassResult.sceneColorCopyHandle);
         }
-        for (const binding of compositeHistoryReadBindings){
-            builder.read(binding.handle);
-        }
-        const outputBackbuffer = builder.write(backbuffer);
-        const taaHistoryColorHandle = useFinalFramebufferAsIntermediate ? outputBackbuffer : sceneColorHandle;
+        builder.read(opaqueChainResult.color);
+        const out = builder.write(opaqueChainResult.color);
         builder.setExecute((rgCtx)=>{
-            const renderAndCommitComposite = ()=>{
-                renderComposite(frame);
-                queueTAAHistoryCommit(frame, rgCtx, historyManager, taaHistoryColorHandle, motionVectorHandle);
+            renderTransparentScenePass(frame, rgCtx, opaqueChainRan ? opaqueChainResult.color : null, lightPassResult.sceneColorFramebufferHandle);
+        });
+        return out;
+    });
+    blackboard.set(FrameResources.SceneColor, sceneColorHandle);
+    if (lightPassResult.sceneColorCopyHandle) {
+        blackboard.set(FrameResources.SceneColorCopy, lightPassResult.sceneColorCopyHandle);
+    }
+    if (sssProfileResult) {
+        blackboard.set(FrameResources.SSSProfile, sssProfileResult.profileHandle);
+        blackboard.set(FrameResources.SSSParam, sssProfileResult.paramHandle);
+    }
+    // 8. Post effect chains + transmission depth.
+    //
+    // Chain input: the TransparentPass output version — the authoritative scene
+    // color regardless of whether it physically lives in a texture or in the
+    // backbuffer (final framebuffer used as intermediate, no opaque effects).
+    const chainInput = sceneColorHandle;
+    // When the scene color still physically resides in the final framebuffer,
+    // the Present blit must be skipped if no effect moved it to a texture.
+    // (Opaque-layer effects disable final-as-intermediate mode, so the scene
+    // color is backbuffer-resident whenever that mode is active.)
+    const backbufferResidentHandle = useFinalFramebufferAsIntermediate ? sceneColorHandle : null;
+    // No extra chain dependencies: the effect chains link to the scene color
+    // through their inputs, and per-effect texture needs are declared via the
+    // require* hooks in AbstractPostEffect.setup().
+    const chainDependencies = [];
+    const finalOutput = {
+        handle: backbuffer,
+        isScreen: !ctx.finalFramebuffer
+    };
+    const endLayerHasEffects = !!ctx.compositor?.layerHasEnabledEffect(PostEffectLayer.end);
+    // 8a. Transparent-layer effects (bloom, tonemap, FXAA, ...). They run right
+    // after the light pass and must sample the pre-transmission linear depth, so
+    // they carry no transmissionDepthToken dependency; TransmissionDepth is
+    // instead ordered after this chain (see 8b).
+    const transparentChainResult = ctx.compositor ? ctx.compositor.buildLayer({
+        graph,
+        ctx,
+        layer: PostEffectLayer.transparent,
+        blackboard,
+        input: chainInput,
+        finalOutput: endLayerHasEffects ? null : finalOutput,
+        inputResidesInFinalTarget: !!backbufferResidentHandle,
+        sceneDepthAttachment: renderDepthAttachment,
+        dependencies: chainDependencies,
+        history: historyManager
+    }) : {
+        color: chainInput,
+        wroteFinal: false
+    };
+    // 8b. Transmission depth pass (optional). Mutates the linear depth texture;
+    // the mutation is modeled as a graph write: the WAR hazard orders this pass
+    // after every pre-transmission depth reader (the transparent-layer chain),
+    // and re-registering the post-write version in the blackboard gives
+    // end-layer effects (TAA) a real data dependency on the transmission depth.
+    let transmissionDepthToken;
+    if (options.needSceneColor && !options.needsTransmissionDepthForSSR) {
+        const transmissionDepthResult = graph.addPass('TransmissionDepth', (builder)=>{
+            builder.read(sceneColorHandle);
+            if (transparentChainResult.color !== sceneColorHandle) {
+                builder.read(transparentChainResult.color);
+            }
+            builder.read(depthHandle);
+            builder.read(depthPassResult.depthFramebufferHandle);
+            const depthOut = builder.write(depthHandle);
+            const done = builder.createToken('TransmissionDepthDone');
+            builder.sideEffect();
+            builder.setExecute((rgCtx)=>{
+                renderTransmissionDepthPass(frame, rgCtx);
+            });
+            return {
+                done,
+                depthOut
             };
-            if (historyManager && compositeHistoryReadBindings.length > 0) {
-                historyManager.beginReadScope(compositeHistoryReadBindings.map((binding)=>({
-                        name: binding.name,
-                        texture: rgCtx.getTexture(binding.handle)
-                    })));
-                try {
-                    renderAndCommitComposite();
-                } finally{
-                    historyManager.endReadScope();
-                }
-            } else {
-                renderAndCommitComposite();
+        });
+        transmissionDepthToken = transmissionDepthResult.done;
+        depthHandle = transmissionDepthResult.depthOut;
+        // The transparent-layer chain above read the pre-transmission version;
+        // everything built from here on (end-layer chain) reads this one.
+        blackboard.set(FrameResources.LinearDepth, depthHandle);
+    }
+    // 9. End-layer effects (TAA). Ordered after TransmissionDepth.
+    const endChainDependencies = transmissionDepthToken ? [
+        ...chainDependencies,
+        transmissionDepthToken
+    ] : chainDependencies;
+    const chainResult = ctx.compositor ? ctx.compositor.buildLayer({
+        graph,
+        ctx,
+        layer: PostEffectLayer.end,
+        blackboard,
+        input: transparentChainResult.color,
+        finalOutput,
+        // Still backbuffer-resident if the transparent-layer chain ran no effect
+        inputResidesInFinalTarget: !!backbufferResidentHandle && transparentChainResult.color === chainInput,
+        sceneDepthAttachment: renderDepthAttachment,
+        dependencies: endChainDependencies,
+        history: historyManager
+    }) : {
+        color: transparentChainResult.color,
+        wroteFinal: false
+    };
+    const finalWroteFinal = chainResult.wroteFinal || transparentChainResult.wroteFinal;
+    // 10. Present + frame cleanup.
+    let presentedBackbuffer;
+    if (finalWroteFinal) {
+        // The last effect wrote the final target directly; only cleanup remains.
+        presentedBackbuffer = chainResult.color;
+        graph.addPass('FrameCleanup', (builder)=>{
+            builder.read(presentedBackbuffer);
+            for (const dep of endChainDependencies){
+                builder.read(dep);
             }
+            builder.sideEffect();
+            builder.setExecute(()=>{
+                finishFrame(frame);
+            });
         });
-        return outputBackbuffer;
-    });
+    } else {
+        presentedBackbuffer = graph.addPass('Present', (builder)=>{
+            builder.read(chainResult.color);
+            for (const dep of endChainDependencies){
+                builder.read(dep);
+            }
+            const outputBackbuffer = builder.write(backbuffer);
+            // Skip the blit when the chain output already lives in the final target
+            // (final framebuffer used as intermediate and no end-layer effect ran).
+            const needsBlit = chainResult.color !== backbufferResidentHandle;
+            builder.setExecute((rgCtx)=>{
+                const sourceTex = needsBlit ? rgCtx.getTexture(chainResult.color) : null;
+                if (sourceTex) {
+                    const blitter = new CopyBlitter();
+                    blitter.srgbOut = !ctx.finalFramebuffer;
+                    blitter.blit(sourceTex, ctx.finalFramebuffer ?? null, fetchSampler('clamp_nearest_nomip'));
+                }
+                finishFrame(frame);
+            });
+            return outputBackbuffer;
+        });
+    }
     return {
         backbuffer: presentedBackbuffer,
         frame
@@ -766,12 +1053,9 @@ function renderForwardSSSProfile(frame, profileFramebuffer, profileTexture, para
     }
 }
 function releaseIntermediateFramebuffer(frame) {
-    const { ctx } = frame;
-    if (frame.intermediateDeviceStatePushed) {
-        ctx.device.popDeviceStates();
-        frame.intermediateDeviceStatePushed = false;
-    }
-    ctx.intermediateFramebuffer = null;
+    // Device state is contained within each pass now (LightPass/TransparentPass
+    // push/pop their own framebuffer bindings); only the context field remains.
+    frame.ctx.intermediateFramebuffer = null;
 }
 function releaseDepthFramebuffer(frame) {
     frame.depthFramebuffer = null;
@@ -965,9 +1249,58 @@ function blitToCurrentColorAttachment(ctx, source) {
     const destination = framebuffer?.getColorAttachment(0) ?? null;
     new CopyBlitter().blit(source, destination, fetchSampler('clamp_nearest_nomip'));
 }
-/** @internal */ function renderMainLightPass(frame, sceneColorTex, sceneColorCopyTex, rgCtx, sceneColorFramebufferHandle, sceneColorCopyFramebufferHandle) {
+/**
+ * Renders the full scene (no transmission) into the scene-color copy texture
+ * used as refraction background. Runs as its own graph pass before LightPass.
+ * @internal
+ */ function renderSceneColorGrab(frame, rgCtx, copyHandle, copyFramebufferHandle) {
     const { ctx, renderQueue } = frame;
     const device = ctx.device;
+    const depthTex = frame.depthFramebuffer?.getDepthAttachment();
+    const copyTex = rgCtx.getTexture(copyHandle);
+    const compositor = ctx.compositor;
+    ctx.compositor = null;
+    const isolateSceneColorDepth = frame.options.needsTransmissionDepthForSSR;
+    const savedDepthPrepassAttachment = ctx.depthPrepassAttachment;
+    const savedMaterialFlags = ctx.materialFlags;
+    // MRT store flags never apply to the background copy
+    const sceneColorMaterialFlags = ctx.materialFlags & ~SURFACE_MRT_FLAGS;
+    const sceneColorFramebuffer = copyFramebufferHandle ? rgCtx.getFramebuffer(copyFramebufferHandle) : rgCtx.createFramebuffer({
+        width: copyTex.width,
+        height: copyTex.height,
+        colorAttachments: copyTex,
+        depthAttachment: isolateSceneColorDepth ? ctx.depthFormat : depthTex,
+        ignoreDepthStencil: false
+    });
+    let sceneColorStatePushed = false;
+    try {
+        device.pushDeviceStates();
+        sceneColorStatePushed = true;
+        device.setFramebuffer(sceneColorFramebuffer);
+        _scenePass.transmission = false;
+        if (isolateSceneColorDepth) {
+            ctx.depthPrepassAttachment = undefined;
+            _scenePass.clearDepth = 1;
+            _scenePass.clearStencil = 0;
+        } else {
+            _scenePass.clearDepth = depthTex ? null : 1;
+            _scenePass.clearStencil = depthTex ? null : 0;
+        }
+        ctx.materialFlags = sceneColorMaterialFlags;
+        _scenePass.render(ctx, null, null, renderQueue);
+    } finally{
+        ctx.materialFlags = savedMaterialFlags;
+        if (isolateSceneColorDepth) {
+            ctx.depthPrepassAttachment = savedDepthPrepassAttachment;
+        }
+        if (sceneColorStatePushed) {
+            device.popDeviceStates();
+        }
+        ctx.compositor = compositor;
+    }
+}
+/** @internal */ function renderOpaqueScenePass(frame, sceneColorTex, sceneColorCopyTex, rgCtx, sceneColorFramebufferHandle) {
+    const { ctx, renderQueue } = frame;
     // Use RenderGraph-allocated scene color texture
     const depthTex = frame.depthFramebuffer?.getDepthAttachment();
     ctx.materialFlags &= ~(MaterialVaryingFlags.SSR_STORE_ROUGHNESS | MaterialVaryingFlags.SSS_STORE_PROFILE | MaterialVaryingFlags.SSS_STORE_DIFFUSE | MaterialVaryingFlags.SSS_STORE_NORMAL | MaterialVaryingFlags.SSS_STORE_TRANSMISSION | MaterialVaryingFlags.SKIN_SSS_STORE);
@@ -985,10 +1318,15 @@ function blitToCurrentColorAttachment(ctx, source) {
     if (ctx.SkinSSSTexture) {
         ctx.materialFlags |= MaterialVaryingFlags.SKIN_SSS_STORE;
     }
-    if (depthTex === ctx.finalFramebuffer?.getDepthAttachment()) {
-        ctx.intermediateFramebuffer = ctx.finalFramebuffer;
-    } else if (sceneColorFramebufferHandle && !hasSurfaceMRT(ctx)) {
+    // The graph scene color framebuffer takes priority: it is absent only when
+    // the graph was built in final-framebuffer-as-intermediate mode (external
+    // depth shared with the final framebuffer AND no opaque-layer effects).
+    // Checking the shared depth first would wrongly route the MRT/opaque-effect
+    // case into the single-color final framebuffer.
+    if (sceneColorFramebufferHandle && !hasSurfaceMRT(ctx)) {
         ctx.intermediateFramebuffer = rgCtx.getFramebuffer(sceneColorFramebufferHandle);
+    } else if (!sceneColorFramebufferHandle && depthTex === ctx.finalFramebuffer?.getDepthAttachment()) {
+        ctx.intermediateFramebuffer = ctx.finalFramebuffer;
     } else {
         ctx.intermediateFramebuffer = rgCtx.createFramebuffer({
             width: sceneColorTex.width,
@@ -997,104 +1335,122 @@ function blitToCurrentColorAttachment(ctx, source) {
             depthAttachment: depthTex
         });
     }
-    if (ctx.intermediateFramebuffer && ctx.intermediateFramebuffer !== ctx.finalFramebuffer) {
-        device.pushDeviceStates();
-        frame.intermediateDeviceStatePushed = true;
-        device.setFramebuffer(ctx.intermediateFramebuffer);
+    // The scene target is bound explicitly and the device state is restored at
+    // the end of this pass: graph passes never communicate through leftover
+    // device state. TransparentPass re-binds the same target (or the opaque
+    // chain output) explicitly.
+    ctx.device.pushDeviceStates();
+    try {
+        // setFramebuffer() no-ops when the target is unchanged, so reset the
+        // viewport/scissor explicitly to cover that case.
+        ctx.device.setFramebuffer(ctx.intermediateFramebuffer);
+        ctx.device.setViewport(null);
+        ctx.device.setScissor(null);
+        _scenePass.transmission = false;
+        _scenePass.clearDepth = depthTex ? null : 1;
+        _scenePass.clearStencil = depthTex ? null : 0;
+        if (renderQueue.needSceneColor() && sceneColorCopyTex) {
+            // Background copy was produced by the SceneColorGrab pass; seed the main
+            // color attachment with it and render only transmission/transparent on top.
+            ctx.sceneColorTexture = sceneColorCopyTex;
+            blitToCurrentColorAttachment(ctx, ctx.sceneColorTexture);
+            if (hasSurfaceMRT(ctx)) {
+                // The background copy carries no surface MRT attachments, so opaque
+                // geometry exists only there without roughness/normal (and SSS
+                // lighting) data. Re-render the opaque lists into the MRT scene
+                // target: early-z against the prepass depth keeps this cheap, and the
+                // color output matches the blitted copy on opaque pixels while the
+                // MRT attachments receive the surface data SSR/SSS require.
+                _scenePass.clearColor = null;
+                _scenePass.clearDepth = null;
+                _scenePass.clearStencil = null;
+                _scenePass.renderOpaque = true;
+                _scenePass.renderTransparent = false;
+                _scenePass.render(ctx, null, null, renderQueue);
+            }
+            _scenePass.transmission = true;
+            _scenePass.clearColor = null;
+            _scenePass.clearDepth = null;
+            _scenePass.clearStencil = null;
+        }
+        _scenePass.renderOpaque = true;
+        _scenePass.renderTransparent = false;
+        _scenePass.render(ctx, null, null, renderQueue);
+        _scenePass.renderTransparent = true;
+    } finally{
+        ctx.device.popDeviceStates();
+    }
+}
+/**
+ * Renders the transmission/transparent geometry lists (including OIT) on top
+ * of the opaque result. The target framebuffer is always bound explicitly:
+ * the opaque chain output when opaque-layer effects ran, otherwise the same
+ * scene target the light pass rendered into. OIT implementations composite
+ * into the currently bound framebuffer, which this pass guarantees.
+ * @internal
+ */ function renderTransparentScenePass(frame, rgCtx, opaqueChainOutput, sceneColorFramebufferHandle) {
+    const { ctx, renderQueue } = frame;
+    const device = ctx.device;
+    let framebuffer;
+    if (opaqueChainOutput) {
+        // Opaque-layer effects redirected the scene color into their chain output;
+        // transparent geometry renders on top of it with the scene depth attached.
+        const chainTex = rgCtx.getTexture(opaqueChainOutput);
+        const depthTex = frame.depthFramebuffer?.getDepthAttachment();
+        framebuffer = rgCtx.createFramebuffer({
+            width: chainTex.width,
+            height: chainTex.height,
+            colorAttachments: chainTex,
+            depthAttachment: depthTex
+        });
+        // The chain output is single-color: surface MRT stores no longer apply.
+        ctx.materialFlags &= ~SURFACE_MRT_FLAGS;
+    } else if (sceneColorFramebufferHandle) {
+        // No opaque-layer effect ran (thus no surface MRT either): continue in the
+        // graph scene color framebuffer the light pass rendered into.
+        framebuffer = rgCtx.getFramebuffer(sceneColorFramebufferHandle);
     } else {
+        // Final framebuffer used as scene intermediate.
+        framebuffer = ctx.finalFramebuffer;
+    }
+    device.pushDeviceStates();
+    try {
+        // setFramebuffer() no-ops when the target is unchanged, so reset the
+        // viewport/scissor explicitly to cover that case.
+        device.setFramebuffer(framebuffer);
         device.setViewport(null);
         device.setScissor(null);
-    }
-    _scenePass.transmission = false;
-    _scenePass.clearDepth = depthTex ? null : 1;
-    _scenePass.clearStencil = depthTex ? null : 0;
-    ctx.compositor?.begin(ctx);
-    if (renderQueue.needSceneColor() && sceneColorCopyTex) {
-        const compositor = ctx.compositor;
-        ctx.compositor = null;
-        const isolateSceneColorDepth = frame.options.needsTransmissionDepthForSSR;
-        const savedDepthPrepassAttachment = ctx.depthPrepassAttachment;
-        const savedClearDepth = _scenePass.clearDepth;
-        const savedClearStencil = _scenePass.clearStencil;
-        const savedMaterialFlags = ctx.materialFlags;
-        // Use RenderGraph-allocated sceneColorCopy texture
-        const sceneColorMaterialFlags = ctx.materialFlags & ~SURFACE_MRT_FLAGS;
-        const sceneColorFramebuffer = sceneColorCopyFramebufferHandle ? rgCtx.getFramebuffer(sceneColorCopyFramebufferHandle) : rgCtx.createFramebuffer({
-            width: sceneColorCopyTex.width,
-            height: sceneColorCopyTex.height,
-            colorAttachments: sceneColorCopyTex,
-            depthAttachment: isolateSceneColorDepth ? ctx.depthFormat : depthTex,
-            ignoreDepthStencil: false
-        });
-        let sceneColorStatePushed = false;
+        // _scenePass.transmission carries over from the opaque phase (true when the
+        // scene color copy seeded the background, false otherwise). Never clear:
+        // the opaque result is already in the target.
+        _scenePass.clearColor = null;
+        _scenePass.clearDepth = null;
+        _scenePass.clearStencil = null;
+        _scenePass.renderOpaque = false;
+        _scenePass.renderTransparent = true;
         try {
-            device.pushDeviceStates();
-            sceneColorStatePushed = true;
-            device.setFramebuffer(sceneColorFramebuffer);
-            _scenePass.transmission = false;
-            if (isolateSceneColorDepth) {
-                ctx.depthPrepassAttachment = undefined;
-                _scenePass.clearDepth = 1;
-                _scenePass.clearStencil = 0;
-            }
-            ctx.materialFlags = sceneColorMaterialFlags;
             _scenePass.render(ctx, null, null, renderQueue);
         } finally{
-            ctx.materialFlags = savedMaterialFlags;
-            if (isolateSceneColorDepth) {
-                ctx.depthPrepassAttachment = savedDepthPrepassAttachment;
-                _scenePass.clearDepth = savedClearDepth;
-                _scenePass.clearStencil = savedClearStencil;
-            }
-            if (sceneColorStatePushed) {
-                device.popDeviceStates();
-            }
-            ctx.compositor = compositor;
+            _scenePass.renderOpaque = true;
         }
-        ctx.sceneColorTexture = sceneColorCopyTex;
-        blitToCurrentColorAttachment(ctx, ctx.sceneColorTexture);
-        _scenePass.transmission = true;
-        _scenePass.clearColor = null;
-        _scenePass.clearDepth = null;
-        _scenePass.clearStencil = null;
+    } finally{
+        device.popDeviceStates();
     }
-    _scenePass.render(ctx, null, null, renderQueue);
 }
 /** @internal */ function renderTransmissionDepthPass(frame, rgCtx) {
     renderSceneDepth(frame, frame.depthFramebuffer, rgCtx);
 }
-function queueTAAHistoryCommit(frame, rgCtx, historyManager, colorHandle, motionVectorHandle) {
-    const { ctx } = frame;
-    if (!historyManager?.frameActive || !ctx.camera.TAA || !frame.options.motionVectors || !motionVectorHandle) {
-        return;
-    }
-    const colorTexture = rgCtx.getTexture(colorHandle);
-    const colorSize = {
-        width: colorTexture.width,
-        height: colorTexture.height
-    };
-    historyManager.queueRetainedCommit(RGHistoryResources.TAA_COLOR, {
-        format: colorTexture.format,
-        sizeMode: 'absolute',
-        width: colorTexture.width,
-        height: colorTexture.height
-    }, colorSize, colorTexture);
-    const motionVectorTexture = rgCtx.getTexture(motionVectorHandle);
-    const motionVectorSize = {
-        width: motionVectorTexture.width,
-        height: motionVectorTexture.height
-    };
-    historyManager.queueRetainedCommit(RGHistoryResources.TAA_MOTION_VECTOR, {
-        format: motionVectorTexture.format,
-        sizeMode: 'absolute',
-        width: motionVectorTexture.width,
-        height: motionVectorTexture.height
-    }, motionVectorSize, motionVectorTexture);
-}
-/** @internal */ function renderComposite(frame) {
+/**
+ * Frame-tail housekeeping shared by the Present and FrameCleanup passes.
+ *
+ * The end-layer post effect chain and the final blit are graph passes now
+ * (see buildForwardPlusGraphInternal step 9/10); this only releases per-frame
+ * state. The compositor's scene ping-pong is flushed back to the intermediate
+ * framebuffer by compositor.end() at the tail of the light pass.
+ *
+ * @internal
+ */ function finishFrame(frame) {
     const { ctx } = frame;
-    ctx.compositor?.drawPostEffects(ctx, PostEffectLayer.end, ctx.linearDepthTexture);
-    ctx.compositor?.end(ctx);
     disposeRenderQueue(frame);
     ctx.materialFlags &= ~MaterialVaryingFlags.SSR_STORE_ROUGHNESS;
     ctx.materialFlags &= ~MaterialVaryingFlags.SSS_STORE_PROFILE;
@@ -1102,12 +1458,6 @@ function queueTAAHistoryCommit(frame, rgCtx, historyManager, colorHandle, motion
     ctx.materialFlags &= ~MaterialVaryingFlags.SSS_STORE_NORMAL;
     ctx.materialFlags &= ~MaterialVaryingFlags.SSS_STORE_TRANSMISSION;
     ctx.materialFlags &= ~MaterialVaryingFlags.SKIN_SSS_STORE;
-    if (ctx.intermediateFramebuffer && ctx.intermediateFramebuffer !== ctx.finalFramebuffer) {
-        const blitter = new CopyBlitter();
-        blitter.srgbOut = !ctx.finalFramebuffer;
-        const srcTex = ctx.intermediateFramebuffer.getColorAttachments()[0];
-        blitter.blit(srcTex, ctx.finalFramebuffer ?? null, fetchSampler('clamp_nearest_nomip'));
-    }
     releaseIntermediateFramebuffer(frame);
     releaseDepthFramebuffer(frame);
     releaseClusteredLight(frame);