@driftengine/core 3.61.0

package/dist/render/globalMedium.d.ts

@@ -0,0 +1,124 @@
+/**
+ * A medium filling the whole frustum: what a caller may say about it, and what that resolves to.
+ *
+ * **Here rather than in either renderer, for the reason `lightVolumeDraw.ts` states at its own
+ * top**: two copies of a clamp is a fog that thins on one backend and not the other, and nothing
+ * raises, because either frame is a plausible one. Everything in this file is arithmetic both
+ * backends run before they bind anything.
+ *
+ * The pass this feeds is described in `shaders/globalMedium.ts`. The short version of why it is
+ * not `atmosphere.ts`: distance fog asks how much of a *surface* survives the journey to the eye,
+ * and this asks what the journey adds — which is every point along it the sun can see, and is the
+ * only one of the two that can put the shape of a doorway on a floor.
+ */
+/**
+ * The most steps a march may take, which is the shader's own loop bound.
+ *
+ * **Here rather than beside the GLSL, and the reason is bundle size rather than tidiness.**
+ * `renderQuality.ts` clamps against this and is imported by everything; importing one integer out
+ * of the shader module would carry seventeen kilobytes of shader text into every consumer's
+ * bundle, tree-shaken or not. The engine has paid that once already — see
+ * `docs/IMPROVEMENTS.md` on a constant imported from an offline module.
+ *
+ * Sixty-four is well past useful: at that count the step is centimetres across a room, and the
+ * picture stopped changing somewhere around a third of it.
+ */
+export declare const MAX_GLOBAL_MEDIUM_STEPS = 64;
+/**
+ * The most steps a part `isWeakGpuFamily` names gets, whatever the profile asked for.
+ *
+ * **The march is the only ceiling in `RenderQuality` that is a per-pixel loop**, so it is the one
+ * a weak part gains most from having lowered and the one a settings screen would otherwise have to
+ * know about by name. Sixteen still resolves a shaft across a room; what it gives up is the
+ * smoothness of a long march through a low sun, which is where the banding a step count buys off
+ * actually lives.
+ *
+ * A floor and not a verdict, like the two clamps beside it: `capabilityClamp: false` means "this
+ * person chose these numbers themselves", and a player who asks a weak part for a thick fog is
+ * entitled to it and to the frame rate that comes with it.
+ */
+export declare const WEAK_GPU_MEDIUM_STEPS = 16;
+/**
+ * How thick the air is, this frame.
+ *
+ * A per-frame dial and not a quality setting, in the split `renderQuality.ts` draws for depth of
+ * field: what a device can afford is `globalMediumSteps`, and what the weather is doing is this.
+ * A game walks into a fog bank; a profile decides how expensive being in one is allowed to be.
+ */
+export interface GlobalMediumOptions {
+    /**
+     * Extinction per metre. **0 is off, and off is free** — no target is allocated, no pass is
+     * built and the composite is skipped, so a game that never sets this pays nothing at all.
+     *
+     * As a scale: 0.02 leaves a wall at 50 m about a third obscured, 0.1 is thick weather, and
+     * above about 0.5 nothing is visible past a room.
+     */
+    readonly density: number;
+    /**
+     * How much of what the medium takes out of a ray comes back as light rather than as heat, 0 to 1.
+     *
+     * Near 1 for water droplets, which is fog, cloud and steam; lower for smoke, which is soot and
+     * absorbs most of what it intercepts. It is the difference between a white fog that a torch
+     * lights up and a black smoke that swallows the same torch.
+     */
+    readonly albedo: number;
+    /**
+     * Henyey-Greenstein anisotropy, -1 back to 1 forward. 0 is isotropic.
+     *
+     * **This is the term that makes a medium read as weather rather than as a grey wash.** Real haze
+     * is strongly forward-scattering, which is why the air around a low sun glows and the same air
+     * behind the viewer does not. Around 0.6 for atmospheric haze; 0 for a medium with nothing
+     * directional about it at all.
+     */
+    readonly anisotropy: number;
+    /**
+     * Where the march stops, in metres. Beyond it the medium is not sampled and nothing is added.
+     *
+     * A bound on the *integral*, not on the fog: extinction is still integrated over the whole
+     * distance a ray travels, so a far wall behind this bound is still obscured. What stops is the
+     * search for light to scatter, which is what costs — and past a few extinction lengths there is
+     * no transmittance left for a sample to contribute through.
+     */
+    readonly maxDistance: number;
+}
+/**
+ * What a renderer starts with: off, and everything else at a value that means "ordinary air".
+ *
+ * The three settings beside `density` are never consulted while it is zero, so they are chosen to
+ * make `setGlobalMedium(0.02)`-shaped calls — one number, the rest defaulted — land somewhere
+ * recognisable rather than on a black isotropic soup.
+ */
+export declare const DEFAULT_GLOBAL_MEDIUM: GlobalMediumOptions;
+/**
+ * A caller's numbers, clamped to what the shader can be handed.
+ *
+ * **Every bound here is a picture rather than a guard.** A negative density is `exp(+x)` and a
+ * frame that grows brighter with distance; an anisotropy of exactly 1 or -1 divides the phase
+ * function by zero, which is a NaN that a half-float target spreads over the whole screen rather
+ * than reporting; a `maxDistance` of zero is a march with no length that still costs its steps.
+ */
+export declare function resolveGlobalMedium(options: Partial<GlobalMediumOptions>): GlobalMediumOptions;
+/**
+ * Whether this frame draws the medium at all.
+ *
+ * Both halves, in one place, because both backends have to agree about it exactly: the claim that
+ * `density: 0` is pixel-identical to the pass being absent is only true if neither backend runs a
+ * composite at zero, and a second copy of this test is where that stops being true.
+ */
+export declare function mediumActive(options: GlobalMediumOptions, steps: number): boolean;
+/**
+ * The march's target size.
+ *
+ * **Half each way is a quarter of the march, which is the whole reason a global medium is
+ * affordable.** A step is a shadow lookup and an exponential, tens of times a pixel, where an
+ * occlusion tap is one depth fetch — which is why `ambientOcclusionPass.ts` can run at the frame's
+ * own size and this cannot. What half resolution costs is bought back by the upsample, which is
+ * depth-aware precisely because the one place a half-res medium is visible is a silhouette.
+ *
+ * Rounded up, never below one: a frame one pixel tall halved is zero, and a zero-height target is
+ * refused by both backends at creation.
+ */
+export declare function mediumTargetSize(width: number, height: number, halfResolution: boolean): {
+    width: number;
+    height: number;
+};

package/dist/render/globalMedium.js

@@ -0,0 +1,100 @@
+/**
+ * A medium filling the whole frustum: what a caller may say about it, and what that resolves to.
+ *
+ * **Here rather than in either renderer, for the reason `lightVolumeDraw.ts` states at its own
+ * top**: two copies of a clamp is a fog that thins on one backend and not the other, and nothing
+ * raises, because either frame is a plausible one. Everything in this file is arithmetic both
+ * backends run before they bind anything.
+ *
+ * The pass this feeds is described in `shaders/globalMedium.ts`. The short version of why it is
+ * not `atmosphere.ts`: distance fog asks how much of a *surface* survives the journey to the eye,
+ * and this asks what the journey adds — which is every point along it the sun can see, and is the
+ * only one of the two that can put the shape of a doorway on a floor.
+ */
+/**
+ * The most steps a march may take, which is the shader's own loop bound.
+ *
+ * **Here rather than beside the GLSL, and the reason is bundle size rather than tidiness.**
+ * `renderQuality.ts` clamps against this and is imported by everything; importing one integer out
+ * of the shader module would carry seventeen kilobytes of shader text into every consumer's
+ * bundle, tree-shaken or not. The engine has paid that once already — see
+ * `docs/IMPROVEMENTS.md` on a constant imported from an offline module.
+ *
+ * Sixty-four is well past useful: at that count the step is centimetres across a room, and the
+ * picture stopped changing somewhere around a third of it.
+ */
+export const MAX_GLOBAL_MEDIUM_STEPS = 64;
+/**
+ * The most steps a part `isWeakGpuFamily` names gets, whatever the profile asked for.
+ *
+ * **The march is the only ceiling in `RenderQuality` that is a per-pixel loop**, so it is the one
+ * a weak part gains most from having lowered and the one a settings screen would otherwise have to
+ * know about by name. Sixteen still resolves a shaft across a room; what it gives up is the
+ * smoothness of a long march through a low sun, which is where the banding a step count buys off
+ * actually lives.
+ *
+ * A floor and not a verdict, like the two clamps beside it: `capabilityClamp: false` means "this
+ * person chose these numbers themselves", and a player who asks a weak part for a thick fog is
+ * entitled to it and to the frame rate that comes with it.
+ */
+export const WEAK_GPU_MEDIUM_STEPS = 16;
+/**
+ * What a renderer starts with: off, and everything else at a value that means "ordinary air".
+ *
+ * The three settings beside `density` are never consulted while it is zero, so they are chosen to
+ * make `setGlobalMedium(0.02)`-shaped calls — one number, the rest defaulted — land somewhere
+ * recognisable rather than on a black isotropic soup.
+ */
+export const DEFAULT_GLOBAL_MEDIUM = {
+    density: 0,
+    albedo: 0.9,
+    anisotropy: 0.6,
+    maxDistance: 200,
+};
+/**
+ * A caller's numbers, clamped to what the shader can be handed.
+ *
+ * **Every bound here is a picture rather than a guard.** A negative density is `exp(+x)` and a
+ * frame that grows brighter with distance; an anisotropy of exactly 1 or -1 divides the phase
+ * function by zero, which is a NaN that a half-float target spreads over the whole screen rather
+ * than reporting; a `maxDistance` of zero is a march with no length that still costs its steps.
+ */
+export function resolveGlobalMedium(options) {
+    const d = DEFAULT_GLOBAL_MEDIUM;
+    return {
+        density: Math.max(0, options.density ?? d.density),
+        albedo: Math.min(1, Math.max(0, options.albedo ?? d.albedo)),
+        /* Short of the poles, where `(1 - g^2)` over `(1 + g^2 - 2g)^1.5` is 0/0. */
+        anisotropy: Math.min(0.95, Math.max(-0.95, options.anisotropy ?? d.anisotropy)),
+        maxDistance: Math.max(1e-3, options.maxDistance ?? d.maxDistance),
+    };
+}
+/**
+ * Whether this frame draws the medium at all.
+ *
+ * Both halves, in one place, because both backends have to agree about it exactly: the claim that
+ * `density: 0` is pixel-identical to the pass being absent is only true if neither backend runs a
+ * composite at zero, and a second copy of this test is where that stops being true.
+ */
+export function mediumActive(options, steps) {
+    return options.density > 0 && steps > 0;
+}
+/**
+ * The march's target size.
+ *
+ * **Half each way is a quarter of the march, which is the whole reason a global medium is
+ * affordable.** A step is a shadow lookup and an exponential, tens of times a pixel, where an
+ * occlusion tap is one depth fetch — which is why `ambientOcclusionPass.ts` can run at the frame's
+ * own size and this cannot. What half resolution costs is bought back by the upsample, which is
+ * depth-aware precisely because the one place a half-res medium is visible is a silhouette.
+ *
+ * Rounded up, never below one: a frame one pixel tall halved is zero, and a zero-height target is
+ * refused by both backends at creation.
+ */
+export function mediumTargetSize(width, height, halfResolution) {
+    const divisor = halfResolution ? 2 : 1;
+    return {
+        width: Math.max(1, Math.ceil(Math.max(1, width) / divisor)),
+        height: Math.max(1, Math.ceil(Math.max(1, height) / divisor)),
+    };
+}

package/dist/render/globalMediumPass.d.ts

@@ -0,0 +1,101 @@
+import type { ReadonlyMat4 } from 'gl-matrix';
+import type { GlobalMediumOptions } from './globalMedium.ts';
+/** What the march needs about the light, which is the sun and the sky and nothing else. */
+export interface MediumLight {
+    /** Surface → sun, normalised. `Environment.directionalDir` unchanged. */
+    readonly sunDir: ArrayLike<number>;
+    readonly sunColor: ArrayLike<number>;
+    /** The sky's fill, scattered isotropically, so a shadowed medium is grey rather than black. */
+    readonly ambient: ArrayLike<number>;
+    /** How much of the medium the sun's shadow map removes, 0 to 1. At 0 no map is sampled. */
+    readonly sunShadow: number;
+    /** World → light clip, **uncorrected**: the shader does its own `* 0.5 + 0.5`. */
+    readonly lightViewProj: ReadonlyMat4;
+    readonly staticShadowMap: WebGLTexture;
+    readonly peeledShadowMap: WebGLTexture;
+    readonly dynamicShadowMap: WebGLTexture;
+    readonly peeledEnabled: boolean;
+}
+/**
+ * The global participating medium on WebGL2: a half-res march, then a depth-aware composite.
+ *
+ * **Its own module rather than more of `SceneTarget`**, on the split `ambientOcclusionPass.ts`
+ * draws: that class owns where the frame lands and how it reaches the canvas, and this owns one
+ * effect's target and programs. It is patterned on `SsrPass` more closely than on the occlusion
+ * pass, because it has the same shape — a march into a target of its own, then one composite done
+ * by the blend state, so neither pass ever samples the colour it is modifying.
+ *
+ * **One target and no ping-pong.** The march writes scattered light in `rgb` and transmittance in
+ * `a`; `(ONE, SRC_ALPHA)` against that is `dst * T + L`, which is the transfer equation for the
+ * segment written out. There is nothing to blur — a homogeneous medium is smooth by construction,
+ * and the only sharp thing in the integral is the shadow map, which the march dithers.
+ */
+export declare class GlobalMediumPass {
+    private readonly gl;
+    /**
+     * Whether a half-float target is available, which is `EXT_color_buffer_float`.
+     *
+     * `RGBA8` is a real fallback rather than a refusal: transmittance lives in 0 to 1 by
+     * definition, and the inscatter only leaves that range against an HDR scene — where the
+     * fallback clips a bright fog to white instead of losing it. `SceneTarget.keepsRange` makes
+     * the same trade for the frame itself.
+     */
+    private readonly floatColor;
+    private readonly march;
+    private readonly marchUniforms;
+    private readonly upsample;
+    private readonly upsampleUniforms;
+    private readonly vao;
+    private target;
+    private framebuffer;
+    private width;
+    private height;
+    /** The frame size the current target was derived from, so a resize is noticed. */
+    private frameWidth;
+    private frameHeight;
+    private half;
+    /**
+     * Set once if the target will not complete, after which this pass does nothing and says so once.
+     *
+     * The same honest "off" `ambientOcclusionPass.ts` takes, and its note is the argument: *"the
+     * alternative to an honest off is a frame multiplied by a target that was never written, and the
+     * last time an effect in this renderer sampled a target nobody had filled, the failure presented
+     * as the driver being at fault."* Here the multiplication is literal — a composite reading an
+     * unwritten alpha would multiply the whole frame by whatever was in that memory.
+     */
+    private unavailable;
+    /** `inverse(viewProjection) * DEPTH_01_TO_CLIP`, rebuilt once a frame. See `SsrPass`. */
+    private readonly depthToWorld;
+    /** The four terms the upsample linearises a depth with, so a per-frame pass allocates nothing. */
+    private readonly depthToViewZ;
+    private readonly mediumTexel;
+    private readonly invProjection;
+    constructor(gl: WebGL2RenderingContext, 
+    /**
+     * Whether a half-float target is available, which is `EXT_color_buffer_float`.
+     *
+     * `RGBA8` is a real fallback rather than a refusal: transmittance lives in 0 to 1 by
+     * definition, and the inscatter only leaves that range against an HDR scene — where the
+     * fallback clips a bright fog to white instead of losing it. `SceneTarget.keepsRange` makes
+     * the same trade for the frame itself.
+     */
+    floatColor: boolean);
+    private ensureSize;
+    /**
+     * March the medium into this pass's own target. Returns false if it could not run, which the
+     * caller must read as "no medium" rather than composite something nobody wrote.
+     *
+     * `viewProjection` and `projection` are the **raw** camera matrices, as `SsrPass` takes them:
+     * `DEPTH_01_TO_CLIP` carries a stored depth back into the clip space the first was built in,
+     * and pairing either with a clip-corrected matrix applies the remap twice.
+     */
+    marchMedium(depth: WebGLTexture, frameWidth: number, frameHeight: number, half: boolean, steps: number, options: GlobalMediumOptions, viewProjection: ReadonlyMat4, projection: ReadonlyMat4, eye: ArrayLike<number>, light: MediumLight): boolean;
+    /**
+     * Composite the march over whatever framebuffer is bound, upsampled depth-aware.
+     *
+     * `(ONE, SRC_ALPHA)` on colour is `dst * transmittance + inscatter`; alpha is left alone with
+     * `(ZERO, ONE)`, because the frame's own alpha is not the medium's to spend.
+     */
+    compositeMedium(depth: WebGLTexture, frameWidth: number, frameHeight: number): void;
+    dispose(): void;
+}

package/dist/render/globalMediumPass.js

@@ -0,0 +1,250 @@
+import { mat4 } from 'gl-matrix';
+import { mediumTargetSize } from './globalMedium.js';
+import { DEPTH_01_TO_CLIP } from './lightVolumeDraw.js';
+import { compileProgram, uniformLocations } from './shader.js';
+import { FULLSCREEN_VERT } from './shaders/fullscreen.js';
+import { MEDIUM_FRAG, MEDIUM_UPSAMPLE_FRAG } from './shaders/globalMedium.js';
+/**
+ * The global participating medium on WebGL2: a half-res march, then a depth-aware composite.
+ *
+ * **Its own module rather than more of `SceneTarget`**, on the split `ambientOcclusionPass.ts`
+ * draws: that class owns where the frame lands and how it reaches the canvas, and this owns one
+ * effect's target and programs. It is patterned on `SsrPass` more closely than on the occlusion
+ * pass, because it has the same shape — a march into a target of its own, then one composite done
+ * by the blend state, so neither pass ever samples the colour it is modifying.
+ *
+ * **One target and no ping-pong.** The march writes scattered light in `rgb` and transmittance in
+ * `a`; `(ONE, SRC_ALPHA)` against that is `dst * T + L`, which is the transfer equation for the
+ * segment written out. There is nothing to blur — a homogeneous medium is smooth by construction,
+ * and the only sharp thing in the integral is the shadow map, which the march dithers.
+ */
+export class GlobalMediumPass {
+    gl;
+    floatColor;
+    march;
+    marchUniforms;
+    upsample;
+    upsampleUniforms;
+    vao;
+    target = null;
+    framebuffer = null;
+    width = 0;
+    height = 0;
+    /** The frame size the current target was derived from, so a resize is noticed. */
+    frameWidth = 0;
+    frameHeight = 0;
+    half = true;
+    /**
+     * Set once if the target will not complete, after which this pass does nothing and says so once.
+     *
+     * The same honest "off" `ambientOcclusionPass.ts` takes, and its note is the argument: *"the
+     * alternative to an honest off is a frame multiplied by a target that was never written, and the
+     * last time an effect in this renderer sampled a target nobody had filled, the failure presented
+     * as the driver being at fault."* Here the multiplication is literal — a composite reading an
+     * unwritten alpha would multiply the whole frame by whatever was in that memory.
+     */
+    unavailable = false;
+    /** `inverse(viewProjection) * DEPTH_01_TO_CLIP`, rebuilt once a frame. See `SsrPass`. */
+    depthToWorld = new Float32Array(16);
+    /** The four terms the upsample linearises a depth with, so a per-frame pass allocates nothing. */
+    depthToViewZ = new Float32Array(4);
+    mediumTexel = new Float32Array(2);
+    invProjection = new Float32Array(16);
+    constructor(gl, 
+    /**
+     * Whether a half-float target is available, which is `EXT_color_buffer_float`.
+     *
+     * `RGBA8` is a real fallback rather than a refusal: transmittance lives in 0 to 1 by
+     * definition, and the inscatter only leaves that range against an HDR scene — where the
+     * fallback clips a bright fog to white instead of losing it. `SceneTarget.keepsRange` makes
+     * the same trade for the frame itself.
+     */
+    floatColor) {
+        this.gl = gl;
+        this.floatColor = floatColor;
+        this.march = compileProgram(gl, FULLSCREEN_VERT, MEDIUM_FRAG, 'medium');
+        this.marchUniforms = uniformLocations(gl, this.march, 'medium');
+        this.upsample = compileProgram(gl, FULLSCREEN_VERT, MEDIUM_UPSAMPLE_FRAG, 'mediumUpsample');
+        this.upsampleUniforms = uniformLocations(gl, this.upsample, 'mediumUpsample');
+        const vao = gl.createVertexArray();
+        if (vao === null)
+            throw new Error('GlobalMediumPass: createVertexArray failed');
+        this.vao = vao;
+    }
+    ensureSize(frameWidth, frameHeight, half) {
+        if (this.unavailable)
+            return false;
+        if (this.frameWidth === frameWidth &&
+            this.frameHeight === frameHeight &&
+            this.half === half &&
+            this.target !== null) {
+            return true;
+        }
+        const { gl } = this;
+        const size = mediumTargetSize(frameWidth, frameHeight, half);
+        this.frameWidth = frameWidth;
+        this.frameHeight = frameHeight;
+        this.half = half;
+        this.width = size.width;
+        this.height = size.height;
+        /* Unit 0, chosen rather than inherited, for the reason `SsrPass.ensureSize` gives. */
+        gl.activeTexture(gl.TEXTURE0);
+        if (this.target === null)
+            this.target = gl.createTexture();
+        gl.bindTexture(gl.TEXTURE_2D, this.target);
+        gl.texImage2D(gl.TEXTURE_2D, 0, this.floatColor ? gl.RGBA16F : gl.RGBA8, size.width, size.height, 0, gl.RGBA, this.floatColor ? gl.HALF_FLOAT : gl.UNSIGNED_BYTE, null);
+        /*
+         * NEAREST, and it is the upsample's design rather than a saving. That pass computes the four
+         * bilinear weights itself so that it can *refuse* one of them across a depth edge, and it
+         * fetches each texel at its own centre — where a linear filter returns the texel exactly.
+         * Asking the hardware to blend as well would blend the taps this pass exists to separate.
+         */
+        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);
+        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.target, 0);
+        const ready = gl.checkFramebufferStatus(gl.FRAMEBUFFER) === gl.FRAMEBUFFER_COMPLETE;
+        gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+        gl.bindTexture(gl.TEXTURE_2D, null);
+        if (!ready) {
+            this.unavailable = true;
+            console.warn("GlobalMediumPass: this driver will not render to the medium's target, so the global " +
+                'medium is off. The frame itself is unaffected.');
+            return false;
+        }
+        return true;
+    }
+    /**
+     * March the medium into this pass's own target. Returns false if it could not run, which the
+     * caller must read as "no medium" rather than composite something nobody wrote.
+     *
+     * `viewProjection` and `projection` are the **raw** camera matrices, as `SsrPass` takes them:
+     * `DEPTH_01_TO_CLIP` carries a stored depth back into the clip space the first was built in,
+     * and pairing either with a clip-corrected matrix applies the remap twice.
+     */
+    marchMedium(depth, frameWidth, frameHeight, half, steps, options, viewProjection, projection, eye, light) {
+        if (!this.ensureSize(frameWidth, frameHeight, half))
+            return false;
+        const { gl } = this;
+        const u = this.marchUniforms;
+        mat4.invert(this.depthToWorld, viewProjection);
+        mat4.multiply(this.depthToWorld, this.depthToWorld, DEPTH_01_TO_CLIP);
+        /*
+         * The upsample's four terms, taken here because this is the frame the march ran against.
+         * Column major, so `[2][2]` is element 10 and `[3][3]` is element 15 — the same four
+         * `ambientOcclusionPass.ts` reads, in the same order.
+         */
+        mat4.invert(this.invProjection, projection);
+        this.depthToViewZ[0] = this.invProjection[10] ?? 0;
+        this.depthToViewZ[1] = this.invProjection[14] ?? 0;
+        this.depthToViewZ[2] = this.invProjection[11] ?? 0;
+        this.depthToViewZ[3] = this.invProjection[15] ?? 1;
+        gl.bindFramebuffer(gl.FRAMEBUFFER, this.framebuffer);
+        gl.viewport(0, 0, this.width, this.height);
+        /* One triangle over a target with no depth attachment, so nothing inherited from the scene
+           pass is tested against a buffer that is not there. */
+        gl.disable(gl.DEPTH_TEST);
+        gl.depthMask(false);
+        gl.disable(gl.CULL_FACE);
+        gl.disable(gl.BLEND);
+        gl.disable(gl.SCISSOR_TEST);
+        gl.useProgram(this.march);
+        gl.bindVertexArray(this.vao);
+        gl.activeTexture(gl.TEXTURE0);
+        gl.bindTexture(gl.TEXTURE_2D, depth);
+        gl.uniform1i(u['uDepth'] ?? null, 0);
+        gl.activeTexture(gl.TEXTURE1);
+        gl.bindTexture(gl.TEXTURE_2D, light.staticShadowMap);
+        gl.uniform1i(u['uStaticShadowMap'] ?? null, 1);
+        gl.activeTexture(gl.TEXTURE2);
+        gl.bindTexture(gl.TEXTURE_2D, light.peeledShadowMap);
+        gl.uniform1i(u['uPeeledShadowMap'] ?? null, 2);
+        gl.activeTexture(gl.TEXTURE3);
+        gl.bindTexture(gl.TEXTURE_2D, light.dynamicShadowMap);
+        gl.uniform1i(u['uDynamicShadowMap'] ?? null, 3);
+        gl.uniformMatrix4fv(u['uDepthToWorld'] ?? null, false, this.depthToWorld);
+        gl.uniform3f(u['uCameraPos'] ?? null, eye[0] ?? 0, eye[1] ?? 0, eye[2] ?? 0);
+        gl.uniform3f(u['uSunDir'] ?? null, light.sunDir[0] ?? 0, light.sunDir[1] ?? 1, light.sunDir[2] ?? 0);
+        gl.uniform3f(u['uSunColor'] ?? null, light.sunColor[0] ?? 0, light.sunColor[1] ?? 0, light.sunColor[2] ?? 0);
+        gl.uniform3f(u['uAmbient'] ?? null, light.ambient[0] ?? 0, light.ambient[1] ?? 0, light.ambient[2] ?? 0);
+        gl.uniform1f(u['uDensity'] ?? null, options.density);
+        gl.uniform1f(u['uAlbedo'] ?? null, options.albedo);
+        gl.uniform1f(u['uAnisotropy'] ?? null, options.anisotropy);
+        gl.uniform1f(u['uMaxDistance'] ?? null, options.maxDistance);
+        gl.uniform1i(u['uSteps'] ?? null, steps);
+        gl.uniform1f(u['uSunShadow'] ?? null, light.sunShadow);
+        gl.uniformMatrix4fv(u['uLightViewProj'] ?? null, false, light.lightViewProj);
+        gl.uniform1i(u['uPeeledShadowEnabled'] ?? null, light.peeledEnabled ? 1 : 0);
+        gl.drawArrays(gl.TRIANGLES, 0, 3);
+        gl.bindVertexArray(null);
+        /* Released down to unit 0, for the reason `SsrPass` records: a binding outlives the frame that
+           made it, and the next frame attaches one of these as a target while a sampler still names it. */
+        for (const unit of [gl.TEXTURE3, gl.TEXTURE2, gl.TEXTURE1, gl.TEXTURE0]) {
+            gl.activeTexture(unit);
+            gl.bindTexture(gl.TEXTURE_2D, null);
+        }
+        gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+        return true;
+    }
+    /**
+     * Composite the march over whatever framebuffer is bound, upsampled depth-aware.
+     *
+     * `(ONE, SRC_ALPHA)` on colour is `dst * transmittance + inscatter`; alpha is left alone with
+     * `(ZERO, ONE)`, because the frame's own alpha is not the medium's to spend.
+     */
+    compositeMedium(depth, frameWidth, frameHeight) {
+        if (this.target === null || this.unavailable)
+            return;
+        const { gl } = this;
+        const u = this.upsampleUniforms;
+        gl.viewport(0, 0, frameWidth, frameHeight);
+        gl.disable(gl.DEPTH_TEST);
+        gl.depthMask(false);
+        gl.disable(gl.CULL_FACE);
+        gl.enable(gl.BLEND);
+        gl.blendFuncSeparate(gl.ONE, gl.SRC_ALPHA, gl.ZERO, gl.ONE);
+        gl.useProgram(this.upsample);
+        gl.bindVertexArray(this.vao);
+        gl.activeTexture(gl.TEXTURE0);
+        gl.bindTexture(gl.TEXTURE_2D, this.target);
+        gl.uniform1i(u['uMedium'] ?? null, 0);
+        gl.activeTexture(gl.TEXTURE1);
+        gl.bindTexture(gl.TEXTURE_2D, depth);
+        gl.uniform1i(u['uDepth'] ?? null, 1);
+        this.mediumTexel[0] = 1 / Math.max(1, this.width);
+        this.mediumTexel[1] = 1 / Math.max(1, this.height);
+        gl.uniform2fv(u['uMediumTexel'] ?? null, this.mediumTexel);
+        gl.uniform4fv(u['uDepthToViewZ'] ?? null, this.depthToViewZ);
+        gl.drawArrays(gl.TRIANGLES, 0, 3);
+        gl.bindVertexArray(null);
+        gl.activeTexture(gl.TEXTURE1);
+        gl.bindTexture(gl.TEXTURE_2D, null);
+        gl.activeTexture(gl.TEXTURE0);
+        gl.bindTexture(gl.TEXTURE_2D, null);
+        /* Back to the blend every other pass in this renderer assumes it inherits. */
+        gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+        gl.disable(gl.BLEND);
+        gl.depthMask(true);
+        gl.enable(gl.DEPTH_TEST);
+    }
+    dispose() {
+        const { gl } = this;
+        if (this.framebuffer !== null)
+            gl.deleteFramebuffer(this.framebuffer);
+        if (this.target !== null)
+            gl.deleteTexture(this.target);
+        gl.deleteProgram(this.march);
+        gl.deleteProgram(this.upsample);
+        gl.deleteVertexArray(this.vao);
+        this.framebuffer = null;
+        this.target = null;
+        this.width = 0;
+        this.height = 0;
+        this.frameWidth = 0;
+        this.frameHeight = 0;
+    }
+}