@driftengine/core 3.61.0

package/dist/render/sceneTarget.js

@@ -0,0 +1,856 @@
+import { glSceneDepthFormat } from './depthConvention.js';
+import { AmbientOcclusionPass } from './ambientOcclusionPass.js';
+import { BloomPass } from './bloomPass.js';
+import { GRADE_PLACEHOLDER_SIZE, identityGradeLut, validateGradeLut, } from './colourGrade.js';
+import { compileProgram, uniformLocations } from './shader.js';
+import { TemporalPass } from './temporalPass.js';
+import { FULLSCREEN_VERT } from './shaders/fullscreen.js';
+import { RUSH_FRAG } from './shaders/rush.js';
+/** No veil, so a caller that omits the argument gets exactly the frame it always got. */
+const NO_VEIL = [0, 0, 0];
+/**
+ * An off-screen colour target for the frame, and the pass that resolves it to the canvas.
+ *
+ * The renderer drew straight to the canvas, which is the right default and is why this is
+ * opt-in: with nothing to sample a finished frame from, no screen-space effect can exist at
+ * all. A speed blur faked with a compositor filter over the canvas gets the boundary
+ * wrong in both directions: it is too strong, and it cannot leave the HUD alone. The
+ * effect belongs to the 3D scene, so the scene needs somewhere to land before it is shown.
+ *
+ * **It resolves to the canvas, always.** Two consumers depend on that and neither is
+ * optional: a frame recorder reads the canvas to build a clip, and a still is a canvas
+ * copy. Leaving the scene in a framebuffer would produce a black export while the screen
+ * looked correct, which is the worst shape a bug can have.
+ *
+ * Sized from the drawing buffer and rebuilt when that changes, so a resize, a DPR change
+ * and an export lock all land on an exactly-sized target rather than a stretched one. The
+ * depth buffer lives here too: a scene drawn into a colour attachment with the canvas's
+ * depth buffer would have no depth at all.
+ */
+export class SceneTarget {
+    gl;
+    discardResolved;
+    framebuffer = null;
+    texture = null;
+    /**
+     * Depth as a *texture* rather than a renderbuffer, so the composite pass can read it.
+     *
+     * A renderbuffer is write-only from a shader's point of view, and every screen-space
+     * effect worth having needs the depth back: motion blur reconstructs a world position
+     * from it to reproject through the previous view, and ambient occlusion is nothing but
+     * depth compared against its neighbours. Costing the same memory and being sampleable,
+     * there is no reason for it to be anything else.
+     */
+    depth = null;
+    /**
+     * A copy of the frame's depth taken mid-pass, for anything that must read it while drawing.
+     *
+     * **Not `depth` itself, and the distinction is the whole reason this exists.** `depth` is the
+     * attachment the frame is testing against, and sampling a texture that is attached to the
+     * bound framebuffer is undefined in WebGL2 — it draws something plausible on this driver and
+     * something else on the next. So a volume of light, which has to know where the opaque scene
+     * is in order to stop marching at it, reads this instead.
+     *
+     * Filled by `snapshotDepth`, on demand, and only in frames that ask.
+     */
+    depthCopy = null;
+    depthCopyFramebuffer = null;
+    /** Whether this frame has filled it. One snapshot serves every volume in a frame. */
+    depthCopyFilled = false;
+    /**
+     * The colour the frame had already drawn when something first asked for it.
+     *
+     * **A copy and never the attachment**, which is the difference `colorAttachment` documents from
+     * the other side: that one returns null while multisampling, because the frame lives in a
+     * renderbuffer until `resolve` blits into it. A blit from a multisampled source to a
+     * single-sampled destination *is* a resolve, so this answers in exactly the configuration where
+     * reading the attachment cannot.
+     *
+     * Filled by `snapshotColor`, on demand, and only in frames that ask.
+     */
+    colorCopy = null;
+    colorCopyFramebuffer = null;
+    /** Whether this frame has filled it. One snapshot serves every refracting draw in a frame. */
+    colorCopyFilled = false;
+    /**
+     * The colour grade, as a 3D texture on unit 4, and the table it was built from.
+     *
+     * **The source is kept to compare identities, not to read.** A grade is set every frame by a
+     * consumer that has one, and re-uploading a 32-lattice table is 131 kilobytes of `texImage3D`
+     * sixty times a second for bytes that did not change. Comparing the object is what makes
+     * `setColourGrade` free to call from a frame loop — and a consumer crossfading between two
+     * grades holds two objects, which compare unequal and upload once each on the swap.
+     */
+    gradeTexture = null;
+    gradeSource = null;
+    gradeSize = GRADE_PLACEHOLDER_SIZE;
+    gradeStrength = 0;
+    width = 0;
+    height = 0;
+    /**
+     * The multisampled pair, present only when a caller asked for samples.
+     *
+     * Two framebuffers rather than one, because a multisampled attachment cannot be sampled
+     * by a shader: the scene is drawn into `msaaFramebuffer`, blitted down into the ordinary
+     * texture, and the post chain reads that exactly as it always has. Everything downstream
+     * of the blit is unchanged, which is what keeps this a quality option rather than a
+     * second rendering path.
+     */
+    msaaFramebuffer = null;
+    msaaColor = null;
+    msaaDepth = null;
+    /** What was actually allocated, after clamping to what the driver reports. */
+    samples = 1;
+    /** Whether anything actually reads the resolved depth. Nothing is copied if not. */
+    depthWanted = false;
+    /** Set once if the driver refuses the depth copy, so it is attempted once and not per frame. */
+    depthBlitRefused = false;
+    program;
+    uniforms;
+    vao;
+    /**
+     * Built the first time a caller asks for occlusion, and never for one that does not.
+     *
+     * Two programs and two full-frame targets is not a thing to allocate on the chance somebody
+     * turns the option on later: the option is construction-time, so a renderer that was not
+     * asked for it will never be.
+     */
+    ao = null;
+    /** Built the first time a caller asks for bloom, on the same terms as the occlusion pass. */
+    bloom = null;
+    /** Built on the first frame that asks for it, like `bloom` beside it. */
+    temporal = null;
+    /** Whether the colour attachments hold half floats. See the constructor. */
+    floatColor = false;
+    constructor(gl, requestedSamples = 1, wantsRange = false, 
+    /**
+     * Whether the multisampled buffers may be thrown away once blitted down.
+     *
+     * True is correct and saves a full attachment write per frame on a tiler. It is a switch
+     * because, like WebGPU's `storeOp: 'discard'`, it is invisible on an immediate-mode desktop
+     * part and therefore cannot be verified by a screenshot: see
+     * `RenderQuality.discardResolvedAttachments`.
+     */
+    discardResolved = true) {
+        this.gl = gl;
+        this.discardResolved = discardResolved;
+        /*
+         * Clamped to MAX_SAMPLES rather than trusted. Asking for more than the part supports
+         * produces a framebuffer that never completes, and an incomplete framebuffer is a black
+         * frame with no GL error attached to explain it.
+         */
+        const maximum = gl.getParameter(gl.MAX_SAMPLES);
+        this.samples = Math.max(1, Math.min(Math.round(requestedSamples), Number.isFinite(maximum) ? maximum : 1));
+        /*
+         * A float colour target where the part will render to one, and eight bits where it will not.
+         *
+         * **The reason it matters is what a composite can still tell apart.** With an eight-bit
+         * target the scene has already been squashed into 0 to 1 by the time anything downstream
+         * looks at it, so a star at five times white and a sheet of white paper arrive identical and
+         * nothing can treat them differently. Half floats keep the difference, which is what makes a
+         * bloom threshold mean brightness rather than mean whiteness, and it is why the tone curve
+         * moved from the mesh pass to the resolve: a curve applied before the buffer throws away the
+         * range the buffer exists to keep.
+         *
+         * `EXT_color_buffer_float` is required for this in WebGL2 and is absent on some parts, so it
+         * is asked for rather than assumed. Without it the target stays eight-bit and everything
+         * still draws: values clip where they always clipped.
+         */
+        this.floatColor = wantsRange && gl.getExtension('EXT_color_buffer_float') !== null;
+        this.program = compileProgram(gl, FULLSCREEN_VERT, RUSH_FRAG, 'rush');
+        this.uniforms = uniformLocations(gl, this.program, 'sceneTarget');
+        /*
+         * A VAO with no attributes: the fullscreen triangle is built from `gl_VertexID`, so
+         * there is nothing to bind. WebGL2 still requires *a* vertex array to be bound for a
+         * draw, and binding one with no state is cheaper than leaving whatever the previous
+         * pass left attached.
+         */
+        const vao = gl.createVertexArray();
+        if (vao === null)
+            throw new Error('SceneTarget: createVertexArray failed');
+        this.vao = vao;
+    }
+    /** Match the target to the drawing buffer. Cheap when unchanged. */
+    ensureSize(width, height) {
+        if (this.width === width && this.height === height && this.framebuffer !== null)
+            return;
+        const { gl } = this;
+        this.width = width;
+        this.height = height;
+        if (this.texture === null)
+            this.texture = gl.createTexture();
+        gl.bindTexture(gl.TEXTURE_2D, this.texture);
+        if (this.floatColor) {
+            gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA16F, width, height, 0, gl.RGBA, gl.HALF_FLOAT, null);
+        }
+        else {
+            gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, width, height, 0, gl.RGBA, gl.UNSIGNED_BYTE, null);
+        }
+        // Linear, because the blur samples between texels; clamped, because a tap that
+        // wrapped would pull the opposite edge of the screen into the corner.
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+        const sceneDepth = glSceneDepthFormat(gl);
+        if (this.depth === null)
+            this.depth = gl.createTexture();
+        gl.bindTexture(gl.TEXTURE_2D, this.depth);
+        gl.texImage2D(gl.TEXTURE_2D, 0, sceneDepth.internalFormat, width, height, 0, gl.DEPTH_COMPONENT, sceneDepth.type, null);
+        /* NEAREST, and not a preference: a depth texture with no compare mode cannot be
+           linearly filtered, and asking for it makes the sample come back undefined. */
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+        /* The mid-pass copy, same format as the depth it is blitted from — `blitFramebuffer`
+           refuses a depth copy between formats that do not match exactly. See `depthCopy`. */
+        if (this.depthCopy === null)
+            this.depthCopy = gl.createTexture();
+        gl.bindTexture(gl.TEXTURE_2D, this.depthCopy);
+        gl.texImage2D(gl.TEXTURE_2D, 0, sceneDepth.internalFormat, width, height, 0, gl.DEPTH_COMPONENT, sceneDepth.type, null);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+        /*
+         * The colour copy, and its format follows the scene texture exactly.
+         *
+         * **`blitFramebuffer` refuses a copy between formats that do not match**, which is the same
+         * constraint the depth copy above is built under — so an HDR profile copies `RGBA16F` and an
+         * LDR one `RGBA8`, chosen by the flag the scene texture itself reads.
+         *
+         * `LINEAR` filtering, because a refracting draw samples at an offset that lands between
+         * texels; `CLAMP_TO_EDGE`, because a sample that wrapped would pull the opposite edge of the
+         * screen into a pane at the frame's border, which reads as a tear.
+         */
+        if (this.colorCopy === null)
+            this.colorCopy = gl.createTexture();
+        gl.bindTexture(gl.TEXTURE_2D, this.colorCopy);
+        if (this.floatColor) {
+            gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA16F, width, height, 0, gl.RGBA, gl.HALF_FLOAT, null);
+        }
+        else {
+            gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, width, height, 0, gl.RGBA, gl.UNSIGNED_BYTE, null);
+        }
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+        /*
+         * Colour only, and no depth attachment at all — the mirror image of the depth copy below,
+         * which attaches depth and switches the colour buffers off by name. **They are kept apart
+         * deliberately**: this file records a combined colour-and-depth blit losing the colour
+         * because the driver disliked the depth, and the depth-only path losing the depth for a
+         * missing colour target. One blit, one buffer bit, each time.
+         */
+        if (this.colorCopyFramebuffer === null)
+            this.colorCopyFramebuffer = gl.createFramebuffer();
+        gl.bindFramebuffer(gl.FRAMEBUFFER, this.colorCopyFramebuffer);
+        gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, this.colorCopy, 0);
+        if (gl.checkFramebufferStatus(gl.FRAMEBUFFER) !== gl.FRAMEBUFFER_COMPLETE) {
+            /* Loud, once, at allocation. A refracting draw then shades as an ordinary translucent one
+               and says why, rather than quietly disagreeing with the other backend. */
+            console.warn('SceneTarget: this driver will not give a colour-only framebuffer, so a refracting ' +
+                'surface cannot read the scene behind it and will draw as ordinary glass.');
+            gl.deleteFramebuffer(this.colorCopyFramebuffer);
+            this.colorCopyFramebuffer = null;
+        }
+        if (this.depthCopyFramebuffer === null)
+            this.depthCopyFramebuffer = gl.createFramebuffer();
+        gl.bindFramebuffer(gl.FRAMEBUFFER, this.depthCopyFramebuffer);
+        gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, gl.TEXTURE_2D, this.depthCopy, 0);
+        /*
+         * **Depth only, and the colour buffers have to be switched off by name.**
+         *
+         * A framebuffer with a depth attachment and no colour one still advertises
+         * `COLOR_ATTACHMENT0` as its draw and read buffer, and a `blitFramebuffer` into it is
+         * refused for the missing colour target — taking the depth half of the copy with it, since
+         * the call fails whole. `resolve` documents the same trap from the other direction, where a
+         * combined colour+depth blit lost the colour because the driver disliked the depth.
+         *
+         * Without these two lines the copy silently never happened: `snapshotDepth` returned null,
+         * `uSceneDepthEnabled` stayed 0, and WebGL2 kept marching through the floor while WebGPU
+         * clamped. Two backends doing different things with nothing said about it, which is the
+         * 2026-08-13 rule exactly — and it was found from a capture pair whose only disagreement
+         * was the band of floor the clamp acts on.
+         */
+        gl.drawBuffers([gl.NONE]);
+        gl.readBuffer(gl.NONE);
+        if (gl.checkFramebufferStatus(gl.FRAMEBUFFER) !== gl.FRAMEBUFFER_COMPLETE) {
+            /* Loud, once, at allocation. A volume then draws unclamped on this driver and says why,
+               rather than quietly disagreeing with the other backend. */
+            console.warn('SceneTarget: this driver will not give a depth-only framebuffer, so light volumes ' +
+                'cannot clamp to the scene and will march through it. The frame is unaffected.');
+            gl.deleteFramebuffer(this.depthCopyFramebuffer);
+            this.depthCopyFramebuffer = null;
+        }
+        if (this.framebuffer === null)
+            this.framebuffer = gl.createFramebuffer();
+        gl.bindFramebuffer(gl.FRAMEBUFFER, this.framebuffer);
+        gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, this.texture, 0);
+        gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, gl.TEXTURE_2D, this.depth, 0);
+        if (this.samples > 1) {
+            if (this.msaaColor === null)
+                this.msaaColor = gl.createRenderbuffer();
+            gl.bindRenderbuffer(gl.RENDERBUFFER, this.msaaColor);
+            gl.renderbufferStorageMultisample(gl.RENDERBUFFER, this.samples, this.floatColor ? gl.RGBA16F : gl.RGBA8, width, height);
+            if (this.msaaDepth === null)
+                this.msaaDepth = gl.createRenderbuffer();
+            gl.bindRenderbuffer(gl.RENDERBUFFER, this.msaaDepth);
+            /*
+             * **Must match the resolve target's format exactly**, or `blitFramebuffer` refuses the depth
+             * half of the copy — so it follows the same convention the depth texture does rather than
+             * naming a format of its own. It said 24-bit here for as long as the texture was 24-bit;
+             * making the texture float and leaving this behind produced
+             * `GL_INVALID_OPERATION: glBlitFramebuffer: Depth/stencil buffer format combination not
+             * allowed for blit` on every scene with MSAA, which is what the pixel gate reported first.
+             */
+            gl.renderbufferStorageMultisample(gl.RENDERBUFFER, this.samples, glSceneDepthFormat(gl).internalFormat, width, height);
+            if (this.msaaFramebuffer === null)
+                this.msaaFramebuffer = gl.createFramebuffer();
+            gl.bindFramebuffer(gl.FRAMEBUFFER, this.msaaFramebuffer);
+            gl.framebufferRenderbuffer(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.RENDERBUFFER, this.msaaColor);
+            gl.framebufferRenderbuffer(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, gl.RENDERBUFFER, this.msaaDepth);
+            /*
+             * Checked here rather than discovered as a black frame. A multisampled attachment can
+             * be refused for a combination the driver does not support even after the sample count
+             * was clamped, and the honest response is to fall back to no multisampling and carry
+             * on drawing, rather than to render nothing.
+             */
+            if (gl.checkFramebufferStatus(gl.FRAMEBUFFER) !== gl.FRAMEBUFFER_COMPLETE) {
+                this.releaseMultisample();
+                this.samples = 1;
+            }
+        }
+        gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+        gl.bindTexture(gl.TEXTURE_2D, null);
+        gl.bindRenderbuffer(gl.RENDERBUFFER, null);
+    }
+    releaseMultisample() {
+        const { gl } = this;
+        if (this.msaaFramebuffer !== null)
+            gl.deleteFramebuffer(this.msaaFramebuffer);
+        if (this.msaaColor !== null)
+            gl.deleteRenderbuffer(this.msaaColor);
+        if (this.msaaDepth !== null)
+            gl.deleteRenderbuffer(this.msaaDepth);
+        this.msaaFramebuffer = null;
+        this.msaaColor = null;
+        this.msaaDepth = null;
+    }
+    /** Bind the off-screen target for a frame. The caller clears as it normally would. */
+    begin(width, height) {
+        this.ensureSize(width, height);
+        /* Last frame's snapshot is last frame's scene. See `snapshotDepth`. */
+        this.depthCopyFilled = false;
+        this.colorCopyFilled = false;
+        this.bind();
+    }
+    /**
+     * Point drawing back at this target, at its own size.
+     *
+     * Needed because every borrowing pass — the shadow maps, the planar reflection — hands
+     * the framebuffer back by binding `null`, which is the *canvas*, not the frame's target.
+     * Without somewhere to come back to, everything drawn after a reflection would land on
+     * the canvas and then be overwritten by the resolve of a half-empty target: a black
+     * frame from a renderer that looked correct in isolation.
+     */
+    bind() {
+        const { gl } = this;
+        gl.bindFramebuffer(gl.FRAMEBUFFER, this.msaaFramebuffer ?? this.framebuffer);
+        gl.viewport(0, 0, this.width, this.height);
+    }
+    /**
+     * Whether this target keeps values above 1, which decides where the tone curve belongs.
+     *
+     * False on a part without `EXT_color_buffer_float`, where the scene is squashed into 0 to 1 on
+     * the way in exactly as it always was.
+     */
+    get keepsRange() {
+        return this.floatColor;
+    }
+    /** How many samples the scene is actually being drawn with. 1 means no multisampling. */
+    get sampleCount() {
+        return this.samples;
+    }
+    /** The frame's depth, resolved and sampleable, for screen-space effects that need it. */
+    get depthTexture() {
+        return this.depth;
+    }
+    /**
+     * Copy the depth drawn so far, so something still drawing can read it. Returns what to bind.
+     *
+     * **Once per frame however many callers ask**, because they all want the same thing: where
+     * the opaque scene is. `begin` clears the latch.
+     *
+     * The blit is from whichever framebuffer the frame is actually rendering into — the
+     * multisampled one where there is one — and it restores that binding afterwards, because the
+     * caller is in the middle of a pass and expects to carry on drawing into it. Forgetting that
+     * is a frame that finishes into the wrong target and comes out empty.
+     *
+     * Null where the copy could not be made, and the caller must read that as "no clamp" rather
+     * than as a texture full of zeros — a depth of zero is the near plane, which would clamp every
+     * march to nothing and delete every beam in the scene.
+     */
+    /**
+     * The depth the frame is testing against, for a pass that must test against it too.
+     *
+     * **Not `snapshotDepth`, and the difference matters.** That returns a *copy*, for a pass that
+     * samples depth while the attachment is bound; this is the attachment itself, for a pass that
+     * attaches it and depth-tests against it without writing. Order-independent transparency needs
+     * the second: its two passes reject a pane behind a wall exactly where the wall is, and both
+     * must reject it in the same place or the accumulation and the revealage cover different
+     * fragments.
+     */
+    depthAttachment() {
+        return this.depth;
+    }
+    /**
+     * The colour the frame has drawn so far, for a pass that reads the picture rather than the depth.
+     *
+     * **Null while multisampling, and that is the honest answer rather than a missing feature.** With
+     * samples above one the frame is drawn into a renderbuffer and this texture holds nothing until
+     * `resolve` blits into it — so a pass running mid-frame would read the frame before last. A
+     * caller that needs the finished picture in the middle of the frame is asking for something a
+     * multisampled attachment cannot give without a resolve of its own.
+     */
+    colorAttachment() {
+        return this.msaaFramebuffer === null ? this.texture : null;
+    }
+    /**
+     * The colour the frame has drawn so far, copied so a draw can sample it while still drawing.
+     *
+     * **A copy and never the attachment.** Sampling a texture attached to the bound framebuffer is
+     * undefined in WebGL2 — it draws something plausible on this driver and something else on the
+     * next — and `colorAttachment` returns null under multisampling anyway. A blit answers both:
+     * it detaches the read, and from a multisampled source it resolves.
+     *
+     * **Latched, and the latch is the same trap `snapshotDepth` documents.** One copy serves every
+     * refracting draw in a frame, so glass does not refract other glass — which is correct, a pane
+     * behind a pane should show the room. What it also means is that opaque geometry drawn *after*
+     * the first refracting draw is missing from what a pane shows. Draw the world, then the glass;
+     * a caller that must have the later geometry asks `afresh` and pays another blit.
+     *
+     * Null where the copy could not be made, and a caller must read that as "do not refract" rather
+     * than as a black texture — refracting against black paints every pane the colour of a hole.
+     */
+    snapshotColor(afresh = false) {
+        if (this.colorCopy === null || this.colorCopyFramebuffer === null)
+            return null;
+        if (this.colorCopyFilled && !afresh)
+            return this.colorCopy;
+        const { gl } = this;
+        const source = this.msaaFramebuffer ?? this.framebuffer;
+        if (source === null)
+            return null;
+        gl.bindFramebuffer(gl.READ_FRAMEBUFFER, source);
+        gl.bindFramebuffer(gl.DRAW_FRAMEBUFFER, this.colorCopyFramebuffer);
+        /* Drained first, for the reason `resolve` gives at length: `getError` reports whatever is
+           pending from anywhere, so a check that does not start clean blames this call for somebody
+           else's mistake — and did, once, permanently disabling an effect. */
+        while (gl.getError() !== gl.NO_ERROR) {
+            /* discard whatever was already pending */
+        }
+        /* `NEAREST` because the rectangles are the same size, so there is nothing to filter and the
+           choice only decides which refusals are possible. */
+        gl.blitFramebuffer(0, 0, this.width, this.height, 0, 0, this.width, this.height, gl.COLOR_BUFFER_BIT, gl.NEAREST);
+        const refused = gl.getError() !== gl.NO_ERROR;
+        /* Back to what the caller was drawing into, whichever that was. */
+        gl.bindFramebuffer(gl.FRAMEBUFFER, source);
+        if (refused)
+            return null;
+        this.colorCopyFilled = true;
+        return this.colorCopy;
+    }
+    snapshotDepth(
+    /**
+     * Take the copy again even though one has already been taken this frame.
+     *
+     * **The latch that makes this cheap is also the trap in it.** A beam asks for the depth in
+     * the middle of the frame, so the copy holds the world *as it stood then* — and a pass that
+     * runs once every draw is in and reuses that copy marks a scene missing everything drawn
+     * after the beam. The symptom is a decal landing on a wall that is no longer the nearest
+     * thing, which reads as a depth-test bug rather than as a stale texture.
+     *
+     * So a caller at the end of the frame asks for it afresh, and pays one more blit on the
+     * frames where something had already asked. `begin` clears the latch either way.
+     */
+    afresh = false) {
+        if (this.depthCopy === null || this.depthCopyFramebuffer === null)
+            return null;
+        if (this.depthCopyFilled && !afresh)
+            return this.depthCopy;
+        const { gl } = this;
+        const source = this.msaaFramebuffer ?? this.framebuffer;
+        if (source === null)
+            return null;
+        gl.bindFramebuffer(gl.READ_FRAMEBUFFER, source);
+        gl.bindFramebuffer(gl.DRAW_FRAMEBUFFER, this.depthCopyFramebuffer);
+        /* Drained first, for the reason `resolve` gives at length: `getError` reports whatever is
+           pending from anywhere, so a check that does not start clean blames this call for
+           somebody else's mistake — and did, once, permanently disabling an effect. */
+        while (gl.getError() !== gl.NO_ERROR) {
+            /* discard whatever was already pending */
+        }
+        gl.blitFramebuffer(0, 0, this.width, this.height, 0, 0, this.width, this.height, gl.DEPTH_BUFFER_BIT, gl.NEAREST);
+        const refused = gl.getError() !== gl.NO_ERROR;
+        /* Back to what the caller was drawing into, whichever that was. */
+        gl.bindFramebuffer(gl.FRAMEBUFFER, source);
+        if (refused)
+            return null;
+        this.depthCopyFilled = true;
+        return this.depthCopy;
+    }
+    /**
+     * Resolve the scene to the canvas, blurred by `strength`.
+     *
+     * Depth and blending are explicitly off for the pass: it is one opaque triangle over the
+     * whole viewport, and inheriting a depth test from the last scene draw would let it fail
+     * against nothing.
+     */
+    /**
+     * The colour grade this and every later frame applies, until it is set again.
+     *
+     * **Held rather than passed to `resolve`**, because a lookup table is a *texture* and every
+     * other texture this pass reads is owned here. The alternative is a ninth parameter on a call
+     * that already takes eight, carrying an object the caller would then have to keep stable
+     * anyway.
+     *
+     * `null`, or a strength at or below zero, is exactly the frame that existed before the effect
+     * did: the shader's branch is on a uniform, so no fetch happens at all.
+     */
+    setColourGrade(lut, strength) {
+        this.gradeStrength = lut === null ? 0 : Math.max(0, Math.min(1, strength));
+        if (lut === null || lut === this.gradeSource)
+            return;
+        validateGradeLut(lut);
+        this.uploadGrade(lut);
+        this.gradeSource = lut;
+    }
+    /**
+     * Put a table on the device, replacing whatever was there.
+     *
+     * `RGBA8` with `LINEAR` in every direction and `CLAMP_TO_EDGE` on all three axes. The filtering
+     * is the whole point — an unfiltered 32-lattice table bands, which is the one artefact a grade
+     * must never introduce — and the clamp is what makes the texel-centre coordinate safe at the
+     * ends of the range rather than wrapping black round to white.
+     */
+    uploadGrade(lut) {
+        const { gl } = this;
+        this.gradeTexture ??= gl.createTexture();
+        gl.activeTexture(gl.TEXTURE4);
+        gl.bindTexture(gl.TEXTURE_3D, this.gradeTexture);
+        gl.texImage3D(gl.TEXTURE_3D, 0, gl.RGBA8, lut.size, lut.size, lut.size, 0, gl.RGBA, gl.UNSIGNED_BYTE, lut.data);
+        gl.texParameteri(gl.TEXTURE_3D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+        gl.texParameteri(gl.TEXTURE_3D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+        gl.texParameteri(gl.TEXTURE_3D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+        gl.texParameteri(gl.TEXTURE_3D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+        gl.texParameteri(gl.TEXTURE_3D, gl.TEXTURE_WRAP_R, gl.CLAMP_TO_EDGE);
+        gl.activeTexture(gl.TEXTURE0);
+        this.gradeSize = lut.size;
+    }
+    resolve(strength, reachUv, 
+    /* The grade, applied here because this is the last pass. See RUSH_FRAG's own note. */
+    grade = {
+        transform: 0,
+        exposure: 1,
+    }, motion, ao, bloom, 
+    /*
+     * Depth of field, between the camera smear and the occlusion in the shader's own order. Like
+     * `motion` and `ao` it needs the depth, and like them it is absent rather than zeroed when the
+     * frame has not asked — so a renderer nobody asked for it never resolves a depth buffer to
+     * feed it.
+     */
+    dof, 
+    /*
+     * The frame veil, composited last of everything this pass does. See
+     * `Renderer.setFrameVeil` for why it sits here rather than upstream or downstream of the
+     * grade. Defaulted rather than optional: the shader always reads both uniforms, so a
+     * caller that never veils anything uploads the same two numbers it always would have.
+     */
+    veilColor = NO_VEIL, veilAlpha = 0, 
+    /*
+     * The temporal resolve, appended rather than placed beside the other effects because
+     * `veilColor` and `veilAlpha` are positional defaults and every existing caller passes them
+     * by position.
+     */
+    temporal) {
+        const { gl } = this;
+        this.depthWanted =
+            motion !== undefined || ao !== undefined || dof !== undefined || temporal !== undefined;
+        /*
+         * Down from the multisampled buffer into the texture first, because a shader cannot
+         * sample a multisampled attachment. NEAREST is the only filter `blitFramebuffer` accepts
+         * for a same-size resolve, and the two are the same size by construction.
+         */
+        if (this.msaaFramebuffer !== null) {
+            gl.bindFramebuffer(gl.READ_FRAMEBUFFER, this.msaaFramebuffer);
+            gl.bindFramebuffer(gl.DRAW_FRAMEBUFFER, this.framebuffer);
+            /*
+             * **Colour on its own, always, and depth as a separate call that is allowed to fail.**
+             *
+             * These were one blit with both bits set, and that shipped a black game. A driver may
+             * refuse a depth copy for a format combination it does not like, and `blitFramebuffer`
+             * refuses the *whole* call when it does — so a disagreement about depth took the
+             * colour with it and the frame resolved to nothing. The symptom is total and the cause
+             * is a flag in a bitmask.
+             *
+             * Split, the worst case is losing the effect that wanted depth. The frame is never at
+             * risk, which is the only acceptable ordering: this method's contract is that the scene
+             * reaches the canvas.
+             */
+            gl.blitFramebuffer(0, 0, this.width, this.height, 0, 0, this.width, this.height, gl.COLOR_BUFFER_BIT, gl.NEAREST);
+            if (this.depthWanted && !this.depthBlitRefused) {
+                /*
+                 * Drained first, and this is not defensive tidiness. `getError` returns whatever
+                 * error is *pending*, from anywhere, and clears it — so a check that does not start
+                 * from a clean queue attributes somebody else's mistake to this call. That happened
+                 * here immediately: an unrelated error elsewhere in the frame was read as the driver
+                 * refusing depth, which switched motion blur off permanently and silently.
+                 */
+                while (gl.getError() !== gl.NO_ERROR) {
+                    /* discard whatever was already pending */
+                }
+                gl.blitFramebuffer(0, 0, this.width, this.height, 0, 0, this.width, this.height, gl.DEPTH_BUFFER_BIT, gl.NEAREST);
+                /*
+                 * Asked once rather than every frame: `getError` is a synchronisation point, and a
+                 * format combination that was refused on the first frame will be refused on every
+                 * one. After that the effect that wanted depth simply does not run.
+                 */
+                if (gl.getError() !== gl.NO_ERROR) {
+                    this.depthBlitRefused = true;
+                    console.warn('SceneTarget: this driver will not resolve multisampled depth, so effects that ' +
+                        'read it are off. The frame itself is unaffected.');
+                }
+            }
+            /*
+             * **Thrown away the moment they have been blitted down, which is WebGL2's half of the
+             * same statement `storeOp: 'discard'` makes on the other backend.**
+             *
+             * The blit above is the resolve, and on its own it is only half of one: the multisampled
+             * renderbuffers still hold contents the driver has no reason to believe are finished
+             * with, so a tile-based GPU dutifully writes all four samples out to memory at the end of
+             * the pass. Nothing can ever read them — a multisampled renderbuffer cannot be sampled by
+             * a shader at all, which is the entire reason this blit exists — so the write buys
+             * nothing and costs a full attachment.
+             *
+             * Measured on the WebGPU side of the same frame at 824x1830 with four samples: 23 MB per
+             * attachment, and the game keeps two of them. On a desktop part it is invisible, which is
+             * why it survived; on a phone it is a share of the memory bandwidth the frame has.
+             *
+             * **Before the unbind, deliberately.** `invalidateFramebuffer` acts on whatever is bound
+             * to the target it is given, so moving these two lines below the ones that follow would
+             * discard the default framebuffer instead — which is the frame.
+             */
+            if (this.discardResolved) {
+                gl.invalidateFramebuffer(gl.READ_FRAMEBUFFER, [gl.COLOR_ATTACHMENT0, gl.DEPTH_ATTACHMENT]);
+            }
+            gl.bindFramebuffer(gl.READ_FRAMEBUFFER, null);
+            gl.bindFramebuffer(gl.DRAW_FRAMEBUFFER, null);
+        }
+        /*
+         * Occlusion before the composite, because the composite consumes it, and after the
+         * resolve above, because it reads the depth that resolve produced. It leaves the
+         * framebuffer unbound and the viewport its own, both of which the composite sets again
+         * below.
+         */
+        let aoTexture = null;
+        if (ao !== undefined && !this.depthBlitRefused && this.depth !== null) {
+            this.ao ??= new AmbientOcclusionPass(gl);
+            aoTexture = this.ao.run(this.depth, this.width, this.height, ao.radius, ao.projScale, ao.invProjection);
+        }
+        /*
+         * Bloom beside occlusion rather than after the composite, because the composite is what
+         * consumes it. It reads the resolved colour rather than the depth, so it is independent of
+         * the blit above having produced anything, and it leaves the framebuffer unbound and the
+         * viewport its own — both of which the composite sets again below.
+         */
+        /*
+         * **The temporal resolve happens before all of it**, and what it returns is what everything
+         * below must treat as the scene. Bloom, occlusion and the grade each read the scene texture,
+         * and reading the unresolved one would put the crawl the resolve just removed back on screen
+         * through the bloom — a stable picture lit by an unstable one.
+         */
+        let scene = this.texture;
+        if (temporal !== undefined && this.texture !== null && this.depth !== null) {
+            this.temporal ??= new TemporalPass(gl, this.floatColor);
+            scene = this.temporal.temporalResolve(this.texture, this.depth, temporal.reprojection, this.width, this.height, temporal.blend);
+        }
+        let bloomTexture = null;
+        if (bloom !== undefined && scene !== null) {
+            this.bloom ??= new BloomPass(gl);
+            bloomTexture = this.bloom.run(scene, this.width, this.height, bloom.threshold);
+        }
+        gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+        gl.viewport(0, 0, this.width, this.height);
+        gl.disable(gl.DEPTH_TEST);
+        gl.disable(gl.BLEND);
+        gl.disable(gl.CULL_FACE);
+        gl.depthMask(false);
+        gl.useProgram(this.program);
+        gl.activeTexture(gl.TEXTURE0);
+        gl.bindTexture(gl.TEXTURE_2D, scene);
+        gl.uniform1i(this.uniforms['uScene'] ?? null, 0);
+        gl.uniform1f(this.uniforms['uStrength'] ?? null, strength);
+        gl.uniform1f(this.uniforms['uReach'] ?? null, reachUv);
+        gl.uniform1i(this.uniforms['uOutputTransform'] ?? null, grade.transform);
+        gl.uniform1f(this.uniforms['uOutputExposure'] ?? null, grade.exposure);
+        /*
+         * Depth on its own unit, and the reprojection with it. Bound every frame rather than
+         * once, because a texture unit is context state and any pass between two frames is free
+         * to have left something else there.
+         */
+        gl.activeTexture(gl.TEXTURE1);
+        gl.bindTexture(gl.TEXTURE_2D, this.depth);
+        gl.uniform1i(this.uniforms['uDepth'] ?? null, 1);
+        /* Off if the driver would not give the depth back, so the shader never samples a
+           texture that holds whatever was in it before. */
+        const motionUsable = motion !== undefined && !this.depthBlitRefused;
+        gl.uniform1f(this.uniforms['uMotionStrength'] ?? null, motionUsable ? motion.strength : 0);
+        gl.uniform1f(this.uniforms['uMotionMax'] ?? null, motion?.max ?? 0);
+        if (motionUsable) {
+            gl.uniformMatrix4fv(this.uniforms['uReprojection'] ?? null, false, motion.reprojection);
+        }
+        /*
+         * Depth of field, on the depth unit bound just above and gated on the same refusal: a driver
+         * that would not give the depth back leaves that texture holding a previous frame, and a
+         * circle of confusion computed from it defocuses the wrong half of the picture.
+         */
+        const dofUsable = dof !== undefined && !this.depthBlitRefused;
+        gl.uniform1f(this.uniforms['uDofStrength'] ?? null, dofUsable ? dof.strength : 0);
+        if (dofUsable) {
+            gl.uniform1f(this.uniforms['uFocusDistance'] ?? null, dof.distance);
+            gl.uniform1f(this.uniforms['uFocusRange'] ?? null, dof.range);
+            /* Height over width, so a radius in fractions of the height is a circle on screen. */
+            gl.uniform2f(this.uniforms['uDofAspect'] ?? null, this.height / this.width, 1);
+            gl.uniform4fv(this.uniforms['uDepthToView'] ?? null, dof.depthToView);
+        }
+        /*
+         * Ambient occlusion on its own unit, gated on the same fact as the blur and for the same
+         * reason: a refused depth resolve leaves that texture holding whatever a previous frame
+         * put there, and occlusion measured from it is not a degraded picture but a pattern of
+         * dirt with no relationship to the scene. The pass may also decline for itself, which
+         * arrives here as a null texture. Either way the strength goes to zero, which is exactly
+         * the frame that existed before the effect did.
+         *
+         * The placeholder rather than an unbound unit when it is off: an incomplete texture is
+         * something a driver may fetch the descriptor for before it evaluates the branch that
+         * would have skipped the read.
+         */
+        gl.activeTexture(gl.TEXTURE2);
+        gl.bindTexture(gl.TEXTURE_2D, aoTexture ?? scene);
+        gl.uniform1i(this.uniforms['uAo'] ?? null, 2);
+        gl.uniform1f(this.uniforms['uAoStrength'] ?? null, aoTexture === null ? 0 : (ao?.strength ?? 0));
+        /* Bloom on its own unit, and the placeholder for the same reason as the one above: a
+           driver may fetch a texture's descriptor before it evaluates the branch that skips the
+           read, and an incomplete texture is not a thing to hand it. */
+        gl.activeTexture(gl.TEXTURE3);
+        gl.bindTexture(gl.TEXTURE_2D, bloomTexture ?? scene);
+        gl.uniform1i(this.uniforms['uBloom'] ?? null, 3);
+        gl.uniform1f(this.uniforms['uBloomStrength'] ?? null, bloomTexture === null ? 0 : (bloom?.strength ?? 0));
+        /*
+         * The grade on unit 4, and the placeholder built here rather than at construction: a frame
+         * that never grades anything should not carry a texture, and a sampler declared in the
+         * program must still have a complete one bound whether or not the branch reads it — the
+         * argument the occlusion and bloom placeholders above make, one dimension up.
+         *
+         * The placeholder is an **identity** table at two lattice points, which is exact: identity
+         * is linear and a trilinear fetch through corners holding their own coordinates reproduces a
+         * linear function precisely. So it is the right answer if anything ever samples it rather
+         * than an inert stand-in that happens not to be read.
+         */
+        if (this.gradeTexture === null)
+            this.uploadGrade(identityGradeLut(GRADE_PLACEHOLDER_SIZE));
+        gl.activeTexture(gl.TEXTURE4);
+        gl.bindTexture(gl.TEXTURE_3D, this.gradeTexture);
+        gl.uniform1i(this.uniforms['uGradeLut'] ?? null, 4);
+        gl.uniform1f(this.uniforms['uGradeStrength'] ?? null, this.gradeStrength);
+        gl.uniform1f(this.uniforms['uGradeSize'] ?? null, this.gradeSize);
+        gl.activeTexture(gl.TEXTURE0);
+        /* No unit and no texture: a flat colour, not a sample. Uploaded unconditionally — two
+           floats and a triplet cost nothing next to the triangle this pass already draws — and it
+           is `withVeil` in the shader, not a branch here, that keeps a veil-less frame free of the
+           mix it does not need. */
+        gl.uniform3fv(this.uniforms['uVeilColor'] ?? null, veilColor);
+        gl.uniform1f(this.uniforms['uVeilAlpha'] ?? null, veilAlpha);
+        gl.bindVertexArray(this.vao);
+        gl.drawArrays(gl.TRIANGLES, 0, 3);
+        gl.bindVertexArray(null);
+        /*
+         * **The units this pass used are released, and that is not tidiness.**
+         *
+         * Unit 1 holds `depth` — an attachment of this very target — and a binding survives the frame
+         * it was made in. Anything that later *attaches* that texture while it is still bound to a
+         * sampler the active program declares forms a feedback loop, which WebGL2 reports as
+         * `GL_INVALID_OPERATION: Feedback loop formed between Framebuffer and active Texture` and then
+         * draws something undefined. Order-independent transparency attaches exactly this depth to its
+         * own framebuffers on the next frame, and that is how this was found: 120 pixels of a frame
+         * that should have been identical, and a warning per draw explaining why.
+         */
+        for (let unit = 0; unit <= 4; unit++) {
+            gl.activeTexture(gl.TEXTURE0 + unit);
+            gl.bindTexture(gl.TEXTURE_2D, null);
+        }
+        gl.activeTexture(gl.TEXTURE0);
+        // Handed back the way the rest of the renderer expects to find it.
+        gl.depthMask(true);
+        gl.enable(gl.DEPTH_TEST);
+        /*
+         * **And culling, which this pass switched off and the next frame's world is drawn with.**
+         *
+         * It was the one borrowed state never returned. `resolve` runs at `endFrame`, so from the
+         * second frame onwards every `drawMesh` in every scene ran with `CULL_FACE` disabled — the
+         * world drawn double-sided on the backend this engine is most often looked at, against a
+         * renderer that enables culling once at setup and documents it as "on for the life of the
+         * renderer because the world is solid".
+         *
+         * Invisible wherever geometry is wound correctly, which is every scene here, so nothing
+         * caught it. What caught it was a scene whose geometry was wound *backwards*: it looked
+         * perfect on WebGL2 and lost its entire ground on WebGPU, where culling is pipeline state
+         * that no pass can leak. The defect read as a WebGPU bug for a fortnight and was this line.
+         */
+        gl.enable(gl.CULL_FACE);
+    }
+    dispose() {
+        const { gl } = this;
+        this.ao?.dispose();
+        this.ao = null;
+        this.bloom?.dispose();
+        this.bloom = null;
+        if (this.framebuffer !== null)
+            gl.deleteFramebuffer(this.framebuffer);
+        if (this.texture !== null)
+            gl.deleteTexture(this.texture);
+        if (this.depth !== null)
+            gl.deleteTexture(this.depth);
+        /*
+         * The two snapshots and their framebuffers, which this method did not release before the
+         * colour one was added. **The depth pair is the same leak and is freed here for the same
+         * reason**: they are allocated in `ensureSize` beside everything above, so releasing some of
+         * what that allocates and not the rest is a distinction nothing here intends.
+         */
+        if (this.colorCopy !== null)
+            gl.deleteTexture(this.colorCopy);
+        if (this.colorCopyFramebuffer !== null)
+            gl.deleteFramebuffer(this.colorCopyFramebuffer);
+        if (this.depthCopy !== null)
+            gl.deleteTexture(this.depthCopy);
+        if (this.depthCopyFramebuffer !== null)
+            gl.deleteFramebuffer(this.depthCopyFramebuffer);
+        if (this.gradeTexture !== null)
+            gl.deleteTexture(this.gradeTexture);
+        this.gradeTexture = null;
+        this.gradeSource = null;
+        this.releaseMultisample();
+        gl.deleteProgram(this.program);
+        gl.deleteVertexArray(this.vao);
+        this.framebuffer = null;
+        this.texture = null;
+        this.depth = null;
+        this.colorCopy = null;
+        this.colorCopyFramebuffer = null;
+        this.depthCopy = null;
+        this.depthCopyFramebuffer = null;
+    }
+}