@aura3d/rendering 3.0.1 → 4.0.2

package/dist/renderer/PostprocessExecution.js

@@ -0,0 +1,745 @@
+// PR 0b-2 carve-out (CONTRACTS.md §3.3) — verbatim move from Renderer.ts; 0 changed logic lines.
+// File: packages/rendering/src/renderer/PostprocessExecution.ts — owner lane 03.
+import { BloomPass, FXAAPass, ToneMappingPass, bloomFloatPixels, bloomPixels, chromaticAberrationPixels, colorGradePixels, contactShadowPixels, createDepthTextureBinding, depthOfFieldPixels, filmGrainPixels, fusedLdrPostprocessPixels, fxaaPixels, motionBlurPixels, outlinePixels, ssaoPixels, ssrPixels, taaPixels, toneMapFloatPixels, toneMapPixels, volumetricLightPixels, writePostProcessPixels } from "../PostProcessPass.js";
+import { RenderDeviceError } from "../RenderDevice.js";
+import { createRendererPostprocessPasses, createRendererPostprocessPlanDiagnostics } from "../RendererPostprocessPlan.js";
+import { isIterable } from "./RenderShared.js";
+import { rendererQrFlags } from "./FrameGraph.js";
+import { qrCoreOutputOn } from "./qrSubFlags.js";
+import { Scene } from "@aura3d/scene";
+import { webgl2DeviceHost } from "../webgl2/Counters.js";
+import { executePostGraphWebGL2 } from "../webgl2/LegacyPost.js";
+import { recordPostSkipped } from "./postSkipped.js";
+import { guardPostprocessPlan } from "../quality/PostprocessGuard.js";
+import { renderTargetPoolSlot } from "../contracts/device.js";
+export { postProductionBuild, postSkippedReasons, recordPostSkipped, resetPostSkipped } from "./postSkipped.js";
+/* Q-03-1 (#91, C-28/C-13, behind A3D_QR_TIERS): one C-28 pool per device for
+ * the legacy chain's intermediate targets. The slot factory builds a new pool
+ * per call, so the instance is cached here. */
+const postChainPools = new WeakMap();
+function qrTiersOn() {
+    return Boolean(rendererQrFlags()?.on("A3D_QR_TIERS"));
+}
+function postChainPool(device) {
+    let pool = postChainPools.get(device);
+    if (!pool) {
+        pool = renderTargetPoolSlot.get(rendererQrFlags())(device);
+        postChainPools.set(device, pool);
+    }
+    return pool;
+}
+/**
+ * Q-03-1 (#91): under `A3D_QR_TIERS` the plan goes through lane 11's
+ * `guardPostprocessPlan` before any pass runs, so a pass with no GPU
+ * implementation never reaches a CPU readback. Mode comes from
+ * `A3D_QR_STRICT` (throw `POSTPROCESS_PASS_CPU_ONLY`); otherwise dropped
+ * passes are recorded as `POSTPROCESS_PASS_DROPPED:<name>` on the §6.9 skip
+ * registry (`diagnostics().post.skipped`). Flag-off returns the plan as-is.
+ */
+export function guardRendererPostprocessPlan(device, postprocess, source, passes) {
+    if (!qrTiersOn())
+        return passes;
+    const flags = rendererQrFlags();
+    const guarded = guardPostprocessPlan(passes, {
+        mode: flags?.on("A3D_QR_STRICT") ? "throw" : "drop",
+        gpuFusable: Boolean(device.presentLdrPostprocess),
+        hasDepthTexture: Boolean(source.depthTexture),
+        cpuDeterministic: postprocess.execution === "cpu-deterministic"
+    });
+    for (const name of guarded.dropped)
+        recordPostSkipped(`POSTPROCESS_PASS_DROPPED:${name}`);
+    return guarded.passes;
+}
+/* v2 module warm cache — the sync `render()` route cannot `import()`; the
+ * first flag-on frame fires it, later frames run the real S1–S12 stages. */
+let postV2Modules;
+/* 03-S18c: what the last `tryExecutePostGraphV2` call did — "v2" when the v2
+ * stages (and C-13 custom passes) ran, "v2-modules-loading" while the
+ * deferred bag is still loading, or `legacy-chain:<reason>` when the seam
+ * declined. `null` until a postprocess frame reached the seam (e.g. the
+ * Renderer dropped the chain under core output). */
+let lastPostGraphV2Outcome = null;
+export function postGraphV2LastOutcome() {
+    return lastPostGraphV2Outcome;
+}
+/** Test hook. */
+export function resetPostGraphV2Outcome() {
+    lastPostGraphV2Outcome = null;
+}
+let postV2WarmPromise = null;
+export function warmPostV2Modules() {
+    // Fire-and-forget from the frame path; a failed load is retried next frame.
+    postV2ModulesReady().catch(() => undefined);
+}
+/**
+ * Starts (once) and returns the deferred `post/v2Entry` load. The sync
+ * `render()` route runs the v2 stages (S1–S12, C-13 custom passes) only
+ * after this resolves; until then the seam reports `v2-modules-loading`.
+ * Callers that need the first frames on the real v2 chain (the flag-on post
+ * surface at mount, browser probes) await it. Rejection resets the warm so
+ * the next frame retries.
+ */
+export function postV2ModulesReady() {
+    if (postV2Modules)
+        return Promise.resolve();
+    if (!postV2WarmPromise) {
+        postV2WarmPromise = import("../post/v2Entry.js").then((modules) => {
+            postV2Modules = modules;
+        }).catch((error) => {
+            postV2WarmPromise = null;
+            throw error;
+        });
+    }
+    return postV2WarmPromise;
+}
+export function collectPostprocess(source) {
+    if (source instanceof Scene || isIterable(source))
+        return undefined;
+    if (source.postprocess === true)
+        return {};
+    if (!source.postprocess)
+        return undefined;
+    return source.postprocess;
+}
+function canFuseLdrPostprocess(source, passes) {
+    const sourceIsHdr = isHdrRenderTarget(source);
+    return passes.length > 0
+        && (!sourceIsHdr || passes[0]?.name === "tone-mapping" || (passes[0]?.name === "bloom" && passes[1]?.name === "tone-mapping"))
+        && passes.every((pass) => pass.name === "bloom" || pass.name === "tone-mapping" || pass.name === "color-grade" || pass.name === "depth-of-field" || pass.name === "motion-blur" || pass.name === "ssao" || pass.name === "ssr" || pass.name === "taa" || pass.name === "outline" || pass.name === "fxaa")
+        && passes.every((pass, index) => {
+            const previousRank = index === 0 ? -1 : ldrFusionPassRank(passes[index - 1].name);
+            return ldrFusionPassRank(pass.name) >= previousRank;
+        });
+}
+const FUSABLE_LDR_PASS_NAMES = new Set([
+    "bloom", "tone-mapping", "color-grade", "depth-of-field", "motion-blur",
+    "ssao", "ssr", "taa", "outline", "fxaa"
+]);
+/** Pass names `canFuseLdrPostprocess` cannot route — used only to label the
+ * recorded `POSTPROCESS_V2_UNMIGRATED` skip reason under core-output (T0-07).
+ * "order" = all names fusable but ordering/prefix rules unmet. */
+function unfusedPassNames(passes) {
+    const unfused = passes.map((pass) => pass.name).filter((name) => !FUSABLE_LDR_PASS_NAMES.has(name));
+    return unfused.length ? unfused.join(",") : "order";
+}
+function ldrFusionPassRank(name) {
+    if (name === "bloom")
+        return -1;
+    if (name === "tone-mapping")
+        return 0;
+    if (name === "color-grade")
+        return 1;
+    if (name === "depth-of-field")
+        return 2;
+    if (name === "motion-blur")
+        return 3;
+    if (name === "ssao")
+        return 4;
+    if (name === "ssr")
+        return 5;
+    if (name === "taa")
+        return 6;
+    if (name === "outline")
+        return 7;
+    if (name === "fxaa")
+        return 8;
+    return Number.POSITIVE_INFINITY;
+}
+function isDepthPostprocessPass(name) {
+    return name === "volumetric-light" || name === "depth-of-field" || name === "contact-shadow" || name === "ssao" || name === "ssr";
+}
+function postprocessPassHasDepth(options) {
+    return typeof options === "object" && options !== null && "depth" in options && Boolean(options.depth);
+}
+function withRendererDepth(options, depth) {
+    return depth && !options.depth ? { ...options, depth } : options;
+}
+function isHdrRenderTarget(target) {
+    return target.colorTexture.format === "rgba16f" || target.colorTexture.format === "rgba32f";
+}
+export function postprocessRequiresDepthTexture(postprocess) {
+    return Boolean((postprocess.volumetricLight && !postprocess.volumetricLight.depth) ||
+        (postprocess.depthOfField && !postprocess.depthOfField.depth) ||
+        (postprocess.contactShadow && !postprocess.contactShadow.depth) ||
+        (postprocess.ssao && !postprocess.ssao.depth) ||
+        (postprocess.ssr && !postprocess.ssr.depth) ||
+        // PRD-03 §6.9: on the v2 route the legacy fields are not populated — the
+        // depth-needing stages (S1 depth-prep feeding S2 GTAO / S4 god rays /
+        // Phase-4 DOF+motion blur+SSR) live on the pipeline bag instead.
+        (postprocess.v2 === true && v2PipelineNeedsDepth(postprocess.pipeline)));
+}
+function v2PipelineNeedsDepth(pipeline) {
+    if (pipeline === null || typeof pipeline !== "object")
+        return false;
+    const bag = pipeline;
+    // S5 TAA reads linear Z for disocclusion and S1-C reads device depth for
+    // camera velocity — the depth attachment is required on the forward target.
+    return Boolean(bag.ao ?? bag.godRays ?? bag.dof ?? bag.motionBlur ?? bag.ssr ?? bag.taa) || bag.antiAliasing === "taa";
+}
+export function defaultPostprocessTargetFormat(device, postprocess) {
+    if (postprocess.toneMapping === false)
+        return "rgba8";
+    return device.info.capabilities?.includes("hdr-render-targets") ? "rgba16f" : "rgba8";
+}
+export function createPostprocessDiagnostics(postprocess, ownedTargets, width, height, context = {}) {
+    if (!postprocess)
+        return undefined;
+    const passes = createRendererPostprocessPasses(postprocess);
+    const targetFormat = context.targetFormat ?? postprocess.targetFormat ?? "rgba8";
+    return {
+        postprocessPasses: passes.length,
+        postprocessPassNames: passes.map((pass) => pass.name),
+        postprocessTargetFormat: targetFormat,
+        postprocessRenderTargets: ownedTargets.length,
+        postprocessTextures: ownedTargets.reduce((total, target) => total + 1 + (target.depthTexture ? 1 : 0), 0),
+        postprocessTargetWidth: width,
+        postprocessTargetHeight: height,
+        postprocessPlan: createRendererPostprocessPlanDiagnostics(postprocess, {
+            sourceTargetFormat: targetFormat,
+            targetFormat,
+            nativeLdrPostprocess: context.nativeLdrPostprocess,
+            rendererDepthAvailable: context.rendererDepthAvailable,
+            width,
+            height
+        })
+    };
+}
+export class RendererPostprocessPipeline {
+    host;
+    constructor(host) {
+        this.host = host;
+    }
+    /**
+     * Intermediate chain target. Flag-off: a fresh device target owned by the
+     * frame (`ownedTargets`, disposed by the Renderer). Under `A3D_QR_TIERS`
+     * (Q-03-1, #91): acquired from the C-28 pool and tracked in `pooled`, which
+     * the caller releases back to the pool when the chain finishes.
+     */
+    chainTarget(label, ownedTargets, pooled) {
+        if (pooled) {
+            const target = postChainPool(this.host.device).acquire({
+                width: this.host.width,
+                height: this.host.height,
+                format: "rgba8",
+                samples: 1,
+                depth: false
+            });
+            pooled.push(target);
+            return target;
+        }
+        const target = this.host.device.createRenderTarget({
+            width: this.host.width,
+            height: this.host.height,
+            label,
+            format: "rgba8",
+            depth: false
+        });
+        ownedTargets.push(target);
+        return target;
+    }
+    /** Removes (and records) the flag-on CPU pixel passes; tone mapping, bloom and FXAA have their own passes. */
+    dropSkippedCpuPasses(passes, cpuDeterministic) {
+        return passes.filter((pass) => pass.name === "tone-mapping" || pass.name === "bloom" || pass.name === "fxaa" || !this.postCpuPassSkipped(pass.name, cpuDeterministic));
+    }
+    /** Every pass was skipped: present the source, or copy it to an explicit output. */
+    presentUnchanged(current, outputTarget) {
+        if (outputTarget) {
+            this.host.device.setRenderTarget(current);
+            writePostProcessPixels(this.host.device, current, outputTarget, this.host.device.readPixels(0, 0, current.width, current.height));
+        }
+        else {
+            this.host.device.presentRenderTarget?.(current);
+        }
+    }
+    releaseChainTargets(pooled) {
+        if (!pooled)
+            return;
+        const pool = postChainPool(this.host.device);
+        for (const target of pooled)
+            pool.release(target);
+        pooled.length = 0;
+    }
+    /**
+     * PRD-03 C-13 / Phase 2: flag-on (`v2` + pipeline bag) on a WebGL2 device
+     * routes the present through `executePostGraphWebGL2` — the device
+     * internals carve (CONTRACTS §3.1) — instead of the per-pass loop. Returns
+     * true when the v2 seam executed.
+     */
+    tryExecutePostGraphV2(postprocess, current, passes, outputTarget, v2Modules) {
+        // T0-07 (lane-03 half): under `A3D_QR_CORE_OUTPUT` lane 01's Renderer
+        // stops dropping the configured chain; the reasons the v2 seam still
+        // declines are recorded so `diagnostics().output.postSkipped` reports
+        // the residue instead of silently falling back to the legacy encode.
+        const coreOutput = qrCoreOutputOn(rendererQrFlags());
+        if (postprocess.v2 !== true || this.host.device.kind !== "webgl2") {
+            const reason = postprocess.v2 !== true ? "no-v2-plan" : "backend";
+            if (coreOutput)
+                recordPostSkipped(`POSTPROCESS_V2_UNMIGRATED:${reason}`);
+            lastPostGraphV2Outcome = `legacy-chain:${reason}`;
+            return false;
+        }
+        const pipeline = postprocess.pipeline;
+        if (!pipeline || typeof pipeline !== "object") {
+            if (coreOutput)
+                recordPostSkipped("POSTPROCESS_V2_UNMIGRATED:no-pipeline");
+            lastPostGraphV2Outcome = "legacy-chain:no-pipeline";
+            return false;
+        }
+        // Transitional seam: the v2 path delegates to the native fused present,
+        // which only covers the fused pass names. Scenes authoring anything
+        // outside that set (film-grain, chromatic-aberration, volumetric-light,
+        // contact-shadow) — or requesting cpu-deterministic — keep the legacy
+        // route so nothing authored is silently dropped. An empty pass list is
+        // fine: pipeline-only effects (vignette/film-grain/CA) emit no plan pass.
+        if (postprocess.execution === "cpu-deterministic") {
+            if (coreOutput)
+                recordPostSkipped("POSTPROCESS_V2_UNMIGRATED:cpu-deterministic");
+            lastPostGraphV2Outcome = "legacy-chain:cpu-deterministic";
+            return false;
+        }
+        if (passes.length > 0 && !canFuseLdrPostprocess(current, passes)) {
+            if (coreOutput)
+                recordPostSkipped(`POSTPROCESS_V2_UNMIGRATED:${unfusedPassNames(passes)}`);
+            lastPostGraphV2Outcome = `legacy-chain:${unfusedPassNames(passes)}`;
+            return false;
+        }
+        warmPostV2Modules();
+        v2Modules = v2Modules ?? postV2Modules;
+        // Without the deferred module bag the seam runs the fused present only:
+        // no v2 stage (and no C-13 custom pass) executes this frame.
+        lastPostGraphV2Outcome = v2Modules ? "v2" : "v2-modules-loading";
+        const descriptors = passes.map((pass) => ({
+            name: pass.name,
+            options: pass.options
+        }));
+        // Phase 4: the Renderer stamps the flag-on TemporalHistory bindings onto
+        // `taa.temporal` / `motionBlur.temporal` — lift them for the v2 stages.
+        const temporal = postprocess.taa?.temporal ??
+            postprocess.motionBlur?.temporal;
+        executePostGraphWebGL2(webgl2DeviceHost(this.host.device), current, {
+            pipeline: pipeline,
+            passes: descriptors,
+            ...(v2Modules ? { v2: v2Modules } : {}),
+            ...(postprocess.cameraFrame ? { cameraFrame: postprocess.cameraFrame } : {}),
+            ...(postprocess.postFrameContext ? { frameContext: postprocess.postFrameContext } : {}),
+            ...(temporal ? { temporal } : {}),
+            ...(outputTarget ? { outputTarget } : {}),
+            ...(postprocess.depthRange ? { depthRange: postprocess.depthRange } : {})
+        });
+        return true;
+    }
+    executePostprocess(postprocess, ownedTargets, outputTarget) {
+        const pooled = qrTiersOn() ? [] : null;
+        try {
+            this.executePostprocessChain(postprocess, ownedTargets, outputTarget, pooled);
+        }
+        finally {
+            this.releaseChainTargets(pooled);
+        }
+    }
+    executePostprocessChain(postprocess, ownedTargets, outputTarget, pooled) {
+        const forwardTarget = ownedTargets[0];
+        let current = forwardTarget;
+        if (!current) {
+            throw new RenderDeviceError("Renderer postprocess missing forward render target", "POSTPROCESS_TARGET_MISSING");
+        }
+        let passes = guardRendererPostprocessPlan(this.host.device, postprocess, current, createRendererPostprocessPasses(postprocess));
+        if (passes.length === 0) {
+            // §6.9: a pipeline-only frame (e.g. vignette + toneMapping:"none")
+            // emits no plan passes — the v2 route still applies its stages.
+            if (postprocess.v2 === true && this.tryExecutePostGraphV2(postprocess, current, passes, outputTarget))
+                return;
+            if (outputTarget) {
+                this.host.device.setRenderTarget(current);
+                writePostProcessPixels(this.host.device, current, outputTarget, this.host.device.readPixels(0, 0, current.width, current.height));
+            }
+            else {
+                this.host.device.presentRenderTarget?.(current);
+            }
+            return;
+        }
+        if (this.tryExecutePostGraphV2(postprocess, current, passes, outputTarget))
+            return;
+        if (this.executeFusedLdrPostprocess(current, passes, outputTarget, postprocess.execution === "cpu-deterministic", postprocess.depthRange))
+            return;
+        // §6.9/T0-17: flag-on CPU pixel passes are recorded and skipped before the
+        // per-pass loop, so a skipped pass costs no readback (the previous
+        // record-and-skip still read the frame back to copy it through).
+        passes = this.dropSkippedCpuPasses(passes, postprocess.execution === "cpu-deterministic");
+        if (passes.length === 0) {
+            this.presentUnchanged(current, outputTarget);
+            return;
+        }
+        for (let index = 0; index < passes.length; index += 1) {
+            const pass = passes[index];
+            const nextPass = passes[index + 1];
+            if (pass.name === "bloom" && isHdrRenderTarget(current)) {
+                if (nextPass?.name !== "tone-mapping") {
+                    throw new RenderDeviceError("Renderer HDR bloom requires tone mapping immediately after the float bloom pass.", "HDR_BLOOM_TONEMAPPING_REQUIRED", {
+                        source: current.label
+                    });
+                }
+                const isCombinedLast = index + 1 === passes.length - 1;
+                const target = isCombinedLast ? outputTarget : this.chainTarget("renderer-postprocess-tone-mapping", ownedTargets, pooled);
+                if (target && isCombinedLast)
+                    ownedTargets.push(target);
+                this.host.device.setRenderTarget(current);
+                const bloomed = bloomFloatPixels(this.host.device.readFloatPixels(0, 0, current.width, current.height), current.width, current.height, pass.options);
+                const mapped = toneMapFloatPixels(bloomed.pixels, current.width, current.height, {
+                    outputColorSpace: "srgb",
+                    ...nextPass.options
+                });
+                writePostProcessPixels(this.host.device, current, target, mapped.pixels);
+                if (target)
+                    current = target;
+                index += 1;
+                continue;
+            }
+            const isLast = index === passes.length - 1;
+            const target = isLast ? outputTarget : this.chainTarget(`renderer-postprocess-${pass.name}`, ownedTargets, pooled);
+            if (target && isLast)
+                ownedTargets.push(target);
+            if (pass.name === "tone-mapping") {
+                new ToneMappingPass({
+                    source: current,
+                    target,
+                    outputColorSpace: "srgb",
+                    ...pass.options
+                }).execute({ device: this.host.device, width: this.host.width, height: this.host.height });
+            }
+            else if (pass.name === "bloom") {
+                new BloomPass({
+                    source: current,
+                    target,
+                    ...pass.options
+                }).execute({ device: this.host.device, width: this.host.width, height: this.host.height });
+            }
+            else if (pass.name === "fxaa") {
+                new FXAAPass({
+                    source: current,
+                    target,
+                    ...pass.options
+                }).execute({ device: this.host.device, width: this.host.width, height: this.host.height });
+            }
+            else {
+                this.executePixelPostprocessPass(pass, current, target, forwardTarget, postprocess.execution === "cpu-deterministic");
+            }
+            if (target)
+                current = target;
+        }
+    }
+    executeFusedLdrPostprocess(current, passes, outputTarget, forceCpuDeterministic = false, depthRange) {
+        const nativeHdrBloom = isHdrRenderTarget(current) && passes[0]?.name === "bloom" && passes[1]?.name === "tone-mapping";
+        if (nativeHdrBloom && (forceCpuDeterministic || !this.host.device.presentLdrPostprocess))
+            return false;
+        if (!canFuseLdrPostprocess(current, passes))
+            return false;
+        if (!forceCpuDeterministic && !this.host.device.presentLdrPostprocess && passes.some((pass) => pass.name === "depth-of-field" || pass.name === "motion-blur" || pass.name === "ssao" || pass.name === "ssr" || pass.name === "taa"))
+            return false;
+        // A caller that supplies its own `depth` array for depth-of-field/SSAO/SSR gets a plain
+        // depth renderbuffer, because `postprocessRequiresDepthTexture` only requests a
+        // sampleable depth texture when the renderer has to generate the depth itself. The
+        // backend's fused path samples `depthTextureHandle` regardless and used to throw
+        // `WEBGL_LDR_POSTPROCESS_DEPTH_REQUIRED`, failing the whole render rather than falling
+        // back. Declining fusion here routes those passes through the per-pass CPU path, which
+        // consumes the caller's depth directly and is the behaviour the options already imply.
+        if (!forceCpuDeterministic && !current.depthTexture && passes.some((pass) => pass.name === "depth-of-field" || pass.name === "ssao" || pass.name === "ssr"))
+            return false;
+        if (!forceCpuDeterministic && this.host.device.presentLdrPostprocess) {
+            this.host.device.presentLdrPostprocess(current, {
+                passes: passes.map((pass) => ({
+                    name: pass.name,
+                    options: pass.options
+                })),
+                ...(outputTarget ? { outputTarget } : {}),
+                toneMappingDefaults: { outputColorSpace: "srgb" },
+                // CCR-03-1: real camera range for depth-gated native passes.
+                ...(depthRange ? { depthRange: { near: depthRange.near, far: depthRange.far } } : {})
+            });
+            return true;
+        }
+        this.host.device.setRenderTarget(current);
+        const pixels = fusedLdrPostprocessPixels(this.host.device.readPixels(0, 0, current.width, current.height), current.width, current.height, passes, {
+            mutateInput: true,
+            scratch: this.host.fusedLdrPostprocessScratch,
+            toneMappingDefaults: { outputColorSpace: "srgb" }
+        });
+        writePostProcessPixels(this.host.device, current, outputTarget, pixels);
+        return true;
+    }
+    async executePostprocessAsync(postprocess, ownedTargets, outputTarget) {
+        const pooled = qrTiersOn() ? [] : null;
+        try {
+            await this.executePostprocessChainAsync(postprocess, ownedTargets, outputTarget, pooled);
+        }
+        finally {
+            this.releaseChainTargets(pooled);
+        }
+    }
+    async executePostprocessChainAsync(postprocess, ownedTargets, outputTarget, pooled) {
+        const forwardTarget = ownedTargets[0];
+        let current = forwardTarget;
+        if (!current) {
+            throw new RenderDeviceError("Renderer postprocess missing forward render target", "POSTPROCESS_TARGET_MISSING");
+        }
+        let passes = guardRendererPostprocessPlan(this.host.device, postprocess, current, createRendererPostprocessPasses(postprocess));
+        if (passes.length === 0) {
+            const v2ModulesEmpty = postprocess.v2 === true && this.host.device.kind === "webgl2"
+                ? await import("../post/v2Entry.js")
+                : undefined;
+            if (this.host.device.disposed || current.disposed)
+                return;
+            if (v2ModulesEmpty && this.tryExecutePostGraphV2(postprocess, current, passes, outputTarget, v2ModulesEmpty))
+                return;
+            if (outputTarget) {
+                this.host.device.setRenderTarget(current);
+                writePostProcessPixels(this.host.device, current, outputTarget, await this.readRenderTargetPixelsAsync(current));
+            }
+            else {
+                this.host.device.presentRenderTarget?.(current);
+            }
+            return;
+        }
+        // C-13 v2 seam: the ONLY import() of `post/` GPU modules in the
+        // renderer — the deferred chunk the bundle gate measures. The sync
+        // `executePostprocess` path runs the same carve without the bag (the
+        // transitional fused mapping needs none of it).
+        const v2Modules = postprocess.v2 === true && this.host.device.kind === "webgl2"
+            ? await import("../post/v2Entry.js")
+            : undefined;
+        if (this.host.device.disposed || current.disposed)
+            return;
+        if (this.tryExecutePostGraphV2(postprocess, current, passes, outputTarget, v2Modules))
+            return;
+        if (await this.executeFusedLdrPostprocessAsync(current, passes, outputTarget, postprocess.execution === "cpu-deterministic", postprocess.depthRange))
+            return;
+        // §6.9/T0-17: flag-on CPU pixel passes are recorded and skipped before the
+        // per-pass loop, so a skipped pass costs no readback (the previous
+        // record-and-skip still read the frame back to copy it through).
+        passes = this.dropSkippedCpuPasses(passes, postprocess.execution === "cpu-deterministic");
+        if (passes.length === 0) {
+            this.presentUnchanged(current, outputTarget);
+            return;
+        }
+        for (let index = 0; index < passes.length; index += 1) {
+            const pass = passes[index];
+            const nextPass = passes[index + 1];
+            if (pass.name === "bloom" && isHdrRenderTarget(current)) {
+                if (nextPass?.name !== "tone-mapping") {
+                    throw new RenderDeviceError("Renderer HDR bloom requires tone mapping immediately after the float bloom pass.", "HDR_BLOOM_TONEMAPPING_REQUIRED", {
+                        source: current.label
+                    });
+                }
+                const isCombinedLast = index + 1 === passes.length - 1;
+                const target = isCombinedLast ? outputTarget : this.chainTarget("renderer-postprocess-tone-mapping", ownedTargets, pooled);
+                if (target && isCombinedLast)
+                    ownedTargets.push(target);
+                const bloomed = bloomFloatPixels(await this.readRenderTargetFloatPixelsAsync(current), current.width, current.height, pass.options);
+                const mapped = toneMapFloatPixels(bloomed.pixels, current.width, current.height, {
+                    outputColorSpace: "srgb",
+                    ...nextPass.options
+                });
+                writePostProcessPixels(this.host.device, current, target, mapped.pixels);
+                if (target)
+                    current = target;
+                index += 1;
+                continue;
+            }
+            const isLast = index === passes.length - 1;
+            const target = isLast ? outputTarget : this.chainTarget(`renderer-postprocess-${pass.name}`, ownedTargets, pooled);
+            if (target && isLast)
+                ownedTargets.push(target);
+            if (pass.name === "tone-mapping") {
+                const mapped = isHdrRenderTarget(current)
+                    ? toneMapFloatPixels(await this.readRenderTargetFloatPixelsAsync(current), current.width, current.height, {
+                        outputColorSpace: "srgb",
+                        ...pass.options
+                    })
+                    : toneMapPixels(await this.readRenderTargetPixelsAsync(current), current.width, current.height, {
+                        outputColorSpace: "srgb",
+                        ...pass.options
+                    });
+                writePostProcessPixels(this.host.device, current, target, mapped.pixels);
+            }
+            else if (pass.name === "bloom") {
+                const bloomed = bloomPixels(await this.readRenderTargetPixelsAsync(current), current.width, current.height, pass.options);
+                writePostProcessPixels(this.host.device, current, target, bloomed.pixels);
+            }
+            else if (pass.name === "fxaa") {
+                const smoothed = fxaaPixels(await this.readRenderTargetPixelsAsync(current), current.width, current.height, pass.options);
+                writePostProcessPixels(this.host.device, current, target, smoothed.pixels);
+            }
+            else {
+                await this.executePixelPostprocessPassAsync(pass, current, target, forwardTarget, postprocess.execution === "cpu-deterministic");
+            }
+            if (target)
+                current = target;
+        }
+    }
+    async executeFusedLdrPostprocessAsync(current, passes, outputTarget, forceCpuDeterministic = false, depthRange) {
+        const nativeHdrBloom = isHdrRenderTarget(current) && passes[0]?.name === "bloom" && passes[1]?.name === "tone-mapping";
+        if (nativeHdrBloom && (forceCpuDeterministic || !this.host.device.presentLdrPostprocess))
+            return false;
+        if (!canFuseLdrPostprocess(current, passes))
+            return false;
+        if (!forceCpuDeterministic && !this.host.device.presentLdrPostprocess && passes.some((pass) => pass.name === "depth-of-field" || pass.name === "motion-blur" || pass.name === "ssao" || pass.name === "ssr" || pass.name === "taa"))
+            return false;
+        // A caller that supplies its own `depth` array for depth-of-field/SSAO/SSR gets a plain
+        // depth renderbuffer, because `postprocessRequiresDepthTexture` only requests a
+        // sampleable depth texture when the renderer has to generate the depth itself. The
+        // backend's fused path samples `depthTextureHandle` regardless and used to throw
+        // `WEBGL_LDR_POSTPROCESS_DEPTH_REQUIRED`, failing the whole render rather than falling
+        // back. Declining fusion here routes those passes through the per-pass CPU path, which
+        // consumes the caller's depth directly and is the behaviour the options already imply.
+        if (!forceCpuDeterministic && !current.depthTexture && passes.some((pass) => pass.name === "depth-of-field" || pass.name === "ssao" || pass.name === "ssr"))
+            return false;
+        if (!forceCpuDeterministic && this.host.device.presentLdrPostprocess) {
+            this.host.device.presentLdrPostprocess(current, {
+                passes: passes.map((pass) => ({
+                    name: pass.name,
+                    options: pass.options
+                })),
+                ...(outputTarget ? { outputTarget } : {}),
+                toneMappingDefaults: { outputColorSpace: "srgb" },
+                // CCR-03-1: real camera range for depth-gated native passes.
+                ...(depthRange ? { depthRange: { near: depthRange.near, far: depthRange.far } } : {})
+            });
+            return true;
+        }
+        const pixels = fusedLdrPostprocessPixels(await this.readRenderTargetPixelsAsync(current), current.width, current.height, passes, {
+            mutateInput: true,
+            scratch: this.host.fusedLdrPostprocessScratch,
+            toneMappingDefaults: { outputColorSpace: "srgb" }
+        });
+        writePostProcessPixels(this.host.device, current, outputTarget, pixels);
+        return true;
+    }
+    executePixelPostprocessPass(pass, source, target, forwardTarget, cpuDeterministic = false) {
+        this.host.device.setRenderTarget(source);
+        const input = this.host.device.readPixels(0, 0, source.width, source.height);
+        const skipped = this.postCpuPassSkipped(pass.name, cpuDeterministic);
+        const rendererDepth = !skipped && isDepthPostprocessPass(pass.name) && !postprocessPassHasDepth(pass.options)
+            ? this.readRendererOwnedDepthTexture(forwardTarget)
+            : undefined;
+        const result = skipped
+            // §6.9 record-and-skip (T0-17/FLAG-ON-4): copy the input through so
+            // the chain survives; the skip is on diagnostics().post.skipped.
+            ? input
+            : pass.name === "color-grade"
+                ? colorGradePixels(input, source.width, source.height, pass.options).pixels
+                : pass.name === "chromatic-aberration"
+                    ? chromaticAberrationPixels(input, source.width, source.height, pass.options).pixels
+                    : pass.name === "film-grain"
+                        ? filmGrainPixels(input, source.width, source.height, pass.options).pixels
+                        : pass.name === "depth-of-field"
+                            ? depthOfFieldPixels(input, source.width, source.height, withRendererDepth(pass.options, rendererDepth)).pixels
+                            : pass.name === "volumetric-light"
+                                ? volumetricLightPixels(input, source.width, source.height, withRendererDepth(pass.options, rendererDepth)).pixels
+                                : pass.name === "motion-blur"
+                                    ? motionBlurPixels(input, source.width, source.height, pass.options).pixels
+                                    : pass.name === "contact-shadow"
+                                        ? contactShadowPixels(input, source.width, source.height, withRendererDepth(pass.options, rendererDepth)).pixels
+                                        : pass.name === "ssao"
+                                            ? ssaoPixels(input, source.width, source.height, withRendererDepth(pass.options, rendererDepth)).pixels
+                                            : pass.name === "ssr"
+                                                ? ssrPixels(input, source.width, source.height, withRendererDepth(pass.options, rendererDepth)).pixels
+                                                : pass.name === "taa"
+                                                    ? taaPixels(input, source.width, source.height, pass.options).pixels
+                                                    : pass.name === "outline"
+                                                        ? outlinePixels(input, source.width, source.height, pass.options).pixels
+                                                        : undefined;
+        if (!result) {
+            throw new RenderDeviceError("Renderer postprocess pass is outside the supported renderer pass catalog", "POSTPROCESS_PASS_UNKNOWN", {
+                pass: pass.name
+            });
+        }
+        writePostProcessPixels(this.host.device, source, target, result);
+    }
+    async executePixelPostprocessPassAsync(pass, source, target, forwardTarget, cpuDeterministic = false) {
+        const input = await this.readRenderTargetPixelsAsync(source);
+        const skipped = this.postCpuPassSkipped(pass.name, cpuDeterministic);
+        const rendererDepth = !skipped && isDepthPostprocessPass(pass.name) && !postprocessPassHasDepth(pass.options)
+            ? this.readRendererOwnedDepthTexture(forwardTarget)
+            : undefined;
+        const result = skipped
+            ? input
+            : pass.name === "color-grade"
+                ? colorGradePixels(input, source.width, source.height, pass.options).pixels
+                : pass.name === "chromatic-aberration"
+                    ? chromaticAberrationPixels(input, source.width, source.height, pass.options).pixels
+                    : pass.name === "film-grain"
+                        ? filmGrainPixels(input, source.width, source.height, pass.options).pixels
+                        : pass.name === "depth-of-field"
+                            ? depthOfFieldPixels(input, source.width, source.height, withRendererDepth(pass.options, rendererDepth)).pixels
+                            : pass.name === "volumetric-light"
+                                ? volumetricLightPixels(input, source.width, source.height, withRendererDepth(pass.options, rendererDepth)).pixels
+                                : pass.name === "motion-blur"
+                                    ? motionBlurPixels(input, source.width, source.height, pass.options).pixels
+                                    : pass.name === "contact-shadow"
+                                        ? contactShadowPixels(input, source.width, source.height, withRendererDepth(pass.options, rendererDepth)).pixels
+                                        : pass.name === "ssao"
+                                            ? ssaoPixels(input, source.width, source.height, withRendererDepth(pass.options, rendererDepth)).pixels
+                                            : pass.name === "ssr"
+                                                ? ssrPixels(input, source.width, source.height, withRendererDepth(pass.options, rendererDepth)).pixels
+                                                : pass.name === "taa"
+                                                    ? taaPixels(input, source.width, source.height, pass.options).pixels
+                                                    : pass.name === "outline"
+                                                        ? outlinePixels(input, source.width, source.height, pass.options).pixels
+                                                        : undefined;
+        if (!result) {
+            throw new RenderDeviceError("Renderer postprocess pass is outside the supported renderer pass catalog", "POSTPROCESS_PASS_UNKNOWN", {
+                pass: pass.name
+            });
+        }
+        writePostProcessPixels(this.host.device, source, target, result);
+    }
+    /**
+     * §6.9/T0-17 (FLAG-ON-4): with `A3D_QR_POST` on, a non-GPU post pass must
+     * never kill the frame — every build records
+     * `POSTPROCESS_PASS_NOT_GPU:<name>` and the caller copies the input
+     * through (`postSkippedReasons` surfaces it into
+     * `diagnostics().post.skipped`). The previous dev-only throw fired per
+     * frame once the v2 seam declined.
+     */
+    postCpuPassSkipped(passName, cpuDeterministic) {
+        const flags = rendererQrFlags();
+        if (!flags?.on("A3D_QR_POST") || cpuDeterministic)
+            return false;
+        recordPostSkipped(`POSTPROCESS_PASS_NOT_GPU:${passName}`);
+        return true;
+    }
+    async readRenderTargetPixelsAsync(target) {
+        this.host.device.setRenderTarget(target);
+        if (this.host.device.readPixelsAsync && target.colorTexture.format === "rgba8") {
+            return this.host.device.readPixelsAsync(0, 0, target.width, target.height);
+        }
+        return this.host.device.readPixels(0, 0, target.width, target.height);
+    }
+    async readRenderTargetFloatPixelsAsync(target) {
+        this.host.device.setRenderTarget(target);
+        if (this.host.device.readFloatPixelsAsync && isHdrRenderTarget(target)) {
+            return this.host.device.readFloatPixelsAsync(0, 0, target.width, target.height);
+        }
+        return this.host.device.readFloatPixels(0, 0, target.width, target.height);
+    }
+    readRendererOwnedDepthTexture(forwardTarget) {
+        if (!forwardTarget.depthTexture) {
+            throw new RenderDeviceError("Renderer-owned depth postprocess requires the forward target to expose a depth texture.", "POSTPROCESS_DEPTH_TARGET_MISSING", {
+                renderTarget: forwardTarget.label
+            });
+        }
+        if (!this.host.device.readDepthPixels) {
+            throw new RenderDeviceError("Renderer-owned depth postprocess requires backend depth readback.", "DEPTH_READBACK_UNSUPPORTED", {
+                backend: this.host.device.kind
+            });
+        }
+        this.host.device.setRenderTarget(forwardTarget);
+        return createDepthTextureBinding({
+            label: forwardTarget.depthTexture.label,
+            width: forwardTarget.width,
+            height: forwardTarget.height,
+            data: this.host.device.readDepthPixels(0, 0, forwardTarget.width, forwardTarget.height)
+        });
+    }
+}
+//# sourceMappingURL=PostprocessExecution.js.map