@driftengine/core 4.4.2 → 4.5.0

package/dist/render/shaders/recon/motion.wgsl.js

@@ -83,6 +83,90 @@ fn motionUv(clip: vec4<f32>) -> vec2<f32> {
   return clip.xy / clip.w * 0.5 + vec2<f32>(0.5);
 }
 
+/*
+ * The skinned stage: the joints this frame and last frame, read from two palette textures of the
+ * frame's ring. The same four weighted products in the same order as the scene's own skinning, so
+ * the depth this stage produces is the depth the scene wrote.
+ */
+@group(1) @binding(0) var palette: texture_2d<f32>;
+@group(1) @binding(1) var previousPalette: texture_2d<f32>;
+
+fn jointOf(source: texture_2d<f32>, index: i32) -> mat4x4<f32> {
+  let x = index * 4;
+  return mat4x4<f32>(
+    textureLoad(source, vec2<i32>(x, 0), 0),
+    textureLoad(source, vec2<i32>(x + 1, 0), 0),
+    textureLoad(source, vec2<i32>(x + 2, 0), 0),
+    textureLoad(source, vec2<i32>(x + 3, 0), 0));
+}
+
+fn skinOf(source: texture_2d<f32>, joints: vec4<f32>, weights: vec4<f32>) -> mat4x4<f32> {
+  return jointOf(source, i32(joints.x)) * weights.x
+       + jointOf(source, i32(joints.y)) * weights.y
+       + jointOf(source, i32(joints.z)) * weights.z
+       + jointOf(source, i32(joints.w)) * weights.w;
+}
+
+@vertex
+fn motionSkinnedVert(
+  @location(0) position: vec3<f32>,
+  @location(11) joints: vec4<f32>,
+  @location(12) weights: vec4<f32>,
+) -> Varyings {
+  let world = draw.model * (skinOf(palette, joints, weights) * vec4<f32>(position, 1.0));
+  let wasWorld =
+    draw.previousModel * (skinOf(previousPalette, joints, weights) * vec4<f32>(position, 1.0));
+  var out: Varyings;
+  out.clip = frame.raster * world;
+  out.now = frame.viewProj * world;
+  out.was = frame.previousViewProj * wasWorld;
+  return out;
+}
+
+/*
+ * The rewritten stage: a mesh whose vertices were rewritten this frame reads last frame's rows from
+ * a second buffer of the same stride, so each vertex carries both of its positions.
+ */
+@vertex
+fn motionDynamicVert(
+  @location(0) position: vec3<f32>,
+  @location(1) previousPosition: vec3<f32>,
+) -> Varyings {
+  let world = draw.model * vec4<f32>(position, 1.0);
+  let wasWorld = draw.previousModel * vec4<f32>(previousPosition, 1.0);
+  var out: Varyings;
+  out.clip = frame.raster * world;
+  out.now = frame.viewProj * world;
+  out.was = frame.previousViewProj * wasWorld;
+  return out;
+}
+
+/*
+ * The instanced stage: each instance's matrix this frame and last frame, read from the batch's
+ * placement and the copy of last frame's it kept. Slot for slot, so an instance is paired with
+ * itself; the per-draw matrices are not read.
+ */
+@vertex
+fn motionInstancedVert(
+  @location(0) position: vec3<f32>,
+  @location(2) m0: vec4<f32>,
+  @location(3) m1: vec4<f32>,
+  @location(4) m2: vec4<f32>,
+  @location(5) m3: vec4<f32>,
+  @location(6) p0: vec4<f32>,
+  @location(7) p1: vec4<f32>,
+  @location(8) p2: vec4<f32>,
+  @location(9) p3: vec4<f32>,
+) -> Varyings {
+  let world = mat4x4<f32>(m0, m1, m2, m3) * vec4<f32>(position, 1.0);
+  let wasWorld = mat4x4<f32>(p0, p1, p2, p3) * vec4<f32>(position, 1.0);
+  var out: Varyings;
+  out.clip = frame.raster * world;
+  out.now = frame.viewProj * world;
+  out.was = frame.previousViewProj * wasWorld;
+  return out;
+}
+
 @fragment
 fn motionFrag(in: Varyings) -> @location(0) vec4<f32> {
   /*

package/dist/render/shadowCasters.d.ts

@@ -1,3 +1,4 @@
+import { type GlassOptions, type ResolvedGlass } from './glass.ts';
 import type { ReadonlyMat4 } from 'gl-matrix';
 import type { InstanceData } from './instancedMesh.ts';
 import type { InstancedHandle, MeshHandle, ScatterHandle } from './backend/api.ts';
@@ -40,7 +41,25 @@ import type { SurfaceTextureHandle } from './backend/api.ts';
  * outwards, so a required parameter added in a minor stops every consumer's sink and every test
  * double compiling. A sink that ignores it behaves exactly as it did.
  */
-export type SceneCasterMaterial = SurfaceMaterial<SurfaceTextureHandle> | null;
+export type SceneCasterMaterial = (SurfaceMaterial<SurfaceTextureHandle> & {
+    /**
+     * The caster is glass: it lets light through, so it writes no depth into any shadow map and a
+     * lamp behind it lights what is beyond. The colour replay into a mirror or a probe still draws
+     * it. With `RenderQuality.glassShadows` on it casts a coloured shadow instead: see
+     * `glassShadow.ts`.
+     */
+    readonly glass?: GlassOptions;
+}) | null;
+/**
+ * Whether a caster writes depth into a shadow map: everything but glass. One line in each depth
+ * sink, so the answer is the same in every shadow a backend draws.
+ */
+export declare function castsDepth(material: SceneCasterMaterial | undefined): boolean;
+/**
+ * The caster's glass, resolved into `out`, and whether it is glass at all — the rule `castsDepth`
+ * states from the other side, so a caster is exactly one of the two.
+ */
+export declare function glassOf(material: SceneCasterMaterial | undefined, out: ResolvedGlass): boolean;
 export interface ShadowCasterSink {
     /** A rigid mesh at a model transform: the world, a prop, a static piece of scenery. */
     mesh(mesh: MeshHandle, model: ReadonlyMat4, material?: SceneCasterMaterial): void;

package/dist/render/shadowCasters.js

@@ -1 +1,15 @@
-export {};
+import { resolveGlass } from './glass.js';
+/**
+ * Whether a caster writes depth into a shadow map: everything but glass. One line in each depth
+ * sink, so the answer is the same in every shadow a backend draws.
+ */
+export function castsDepth(material) {
+    return (material?.glass?.transmission ?? 0) <= 0;
+}
+/**
+ * The caster's glass, resolved into `out`, and whether it is glass at all — the rule `castsDepth`
+ * states from the other side, so a caster is exactly one of the two.
+ */
+export function glassOf(material, out) {
+    return resolveGlass(material?.glass, out);
+}

package/dist/render/shadowMap.d.ts

@@ -1,10 +1,59 @@
-export declare class ShadowMap {
+/** Where each of the sun's maps lives in the array. The shaders read these same numbers. */
+export declare const SUN_STATIC_LAYER = 0;
+export declare const SUN_DYNAMIC_LAYER = 1;
+/** Present only when more than one static depth layer is asked for. */
+export declare const SUN_PEELED_LAYER = 2;
+/**
+ * Where the nearest pane's depth lives once glass has cast: after the three maps, at fixed places,
+ * because a shader cannot ask an array how many layers it has here — naga refuses the third
+ * component of an arrayed size query. A profile with no peel grows past an unused third layer to
+ * reach them, which is one map's memory in a profile that already declined one.
+ */
+export declare const SUN_GLASS_STATIC_LAYER = 3;
+export declare const SUN_GLASS_MOVING_LAYER = 4;
+/** The three passes a scene opens, by the names `beginShadowPass` takes. */
+export type SunShadowLayer = 'static' | 'static-peel' | 'dynamic';
+/** The array layer a pass draws into. */
+export declare function sunLayerIndex(layer: SunShadowLayer): number;
+export declare class SunShadowArray {
     readonly size: number;
-    readonly texture: WebGLTexture;
+    /** Replaced once, when glass first casts: see `growForGlass`. */
+    private current;
+    private layerCount;
+    private glass;
     private readonly framebuffer;
-    constructor(gl: WebGL2RenderingContext, size?: number);
-    /** Bind as the render target and clear. Caller then draws the casters. */
-    begin(gl: WebGL2RenderingContext): void;
+    /**
+     * **The peel is drawn here and copied into its layer when the pass ends.** It reads the static
+     * layer while it is drawn, and WebGL2 calls a texture both sampled and attached a feedback loop
+     * whatever layer each names — so drawing the peel into the array would draw nothing at all.
+     * What it costs is one more map's memory where a peel is asked for, and one blit per peel.
+     */
+    private readonly peelTexture;
+    private readonly peelFramebuffer;
+    private peeling;
+    constructor(gl: WebGL2RenderingContext, size?: number, peeled?: boolean);
+    get texture(): WebGLTexture;
+    get layers(): number;
+    /** Whether the two glass layers exist: from the first glass a sun pass is offered, for good. */
+    get hasGlass(): boolean;
+    /** The glass depth layer beside a map: fixed places after the three maps. */
+    glassLayer(which: 'static' | 'dynamic'): number;
+    /**
+     * Add the two glass layers, once, carrying every layer already held across.
+     *
+     * **Carried rather than re-baked**, because the sun's static map is the consumer's to bake and
+     * it may bake it once: the glass that grows the array arrives in the very pass that drew that
+     * map, so a copy is what keeps it. A depth blit per layer, same size and format, and the glass
+     * layers cleared to the far plane — nothing nearer than the sun until a pane is drawn there.
+     * Returns whether it grew, so the caller knows every bind of the old texture is stale.
+     */
+    growForGlass(gl: WebGL2RenderingContext): boolean;
+    /** Bind `layer` as the render target and clear it. Caller then draws the casters. */
+    begin(gl: WebGL2RenderingContext, layer: SunShadowLayer): void;
+    /** Bind a glass depth layer as the render target and clear it: where the nearest pane is. */
+    beginGlass(gl: WebGL2RenderingContext, which: 'static' | 'dynamic'): void;
+    private attach;
+    private clearAndRaster;
     end(gl: WebGL2RenderingContext): void;
     dispose(gl: WebGL2RenderingContext): void;
 }

package/dist/render/shadowMap.js

@@ -1,43 +1,92 @@
 /**
- * Single-cascade directional shadow map: one depth texture, one extra draw of
- * the static world per update.
+ * The sun's shadow: one depth array whose layers are the static world, its movers, and the static
+ * world's second occluder (the peel), drawn one at a time and sampled together.
  *
- * Filtering belongs to the receiving material shader, so the depth target can
- * stay a single-sample texture shared by every mesh pass.
+ * **One array rather than three maps since 4.5.0**, for the reason the lamps' twelve cubemaps
+ * became one: a texture unit. The lit pass binds all three through one `sampler2DArray`, which is
+ * what paid for the two tints glass casts with. The layers share one size and one format, so
+ * nothing about how each is drawn or read moved — only where it lives.
  *
- * Note this is a depth *render target*, not an art texture: AGENTS.md's
- * "zero textures" rule is about the art direction (no image assets in the
- * payload), and nothing here adds a byte to it.
+ * Filtering belongs to the receiving material shader, so the depth target can stay a
+ * single-sample texture shared by every mesh pass. This is a depth *render target*, not an art
+ * texture: AGENTS.md's "zero textures" rule is about the payload, and nothing here adds to it.
  */
 import { SHADOW_DEPTH_CLEAR } from './depthConvention.js';
 import { DEFAULT_RENDER_QUALITY } from './renderQuality.js';
-export class ShadowMap {
+/** Where each of the sun's maps lives in the array. The shaders read these same numbers. */
+export const SUN_STATIC_LAYER = 0;
+export const SUN_DYNAMIC_LAYER = 1;
+/** Present only when more than one static depth layer is asked for. */
+export const SUN_PEELED_LAYER = 2;
+/**
+ * Where the nearest pane's depth lives once glass has cast: after the three maps, at fixed places,
+ * because a shader cannot ask an array how many layers it has here — naga refuses the third
+ * component of an arrayed size query. A profile with no peel grows past an unused third layer to
+ * reach them, which is one map's memory in a profile that already declined one.
+ */
+export const SUN_GLASS_STATIC_LAYER = 3;
+export const SUN_GLASS_MOVING_LAYER = 4;
+/** The array layer a pass draws into. */
+export function sunLayerIndex(layer) {
+    return layer === 'static'
+        ? SUN_STATIC_LAYER
+        : layer === 'dynamic'
+            ? SUN_DYNAMIC_LAYER
+            : SUN_PEELED_LAYER;
+}
+export class SunShadowArray {
     size;
-    texture;
+    /** Replaced once, when glass first casts: see `growForGlass`. */
+    current;
+    layerCount;
+    glass = false;
     framebuffer;
-    constructor(gl, size = DEFAULT_RENDER_QUALITY.directionalShadowMapSize) {
+    /**
+     * **The peel is drawn here and copied into its layer when the pass ends.** It reads the static
+     * layer while it is drawn, and WebGL2 calls a texture both sampled and attached a feedback loop
+     * whatever layer each names — so drawing the peel into the array would draw nothing at all.
+     * What it costs is one more map's memory where a peel is asked for, and one blit per peel.
+     */
+    peelTexture;
+    peelFramebuffer;
+    peeling = false;
+    constructor(gl, size = DEFAULT_RENDER_QUALITY.directionalShadowMapSize, peeled = false) {
         this.size = size;
-        const texture = gl.createTexture();
-        if (texture === null)
-            throw new Error('ShadowMap: createTexture failed');
-        this.texture = texture;
-        gl.bindTexture(gl.TEXTURE_2D, texture);
-        gl.texStorage2D(gl.TEXTURE_2D, 1, gl.DEPTH_COMPONENT24, size, size);
-        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
-        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
-        // Clamp so anything outside the light frustum samples the border and is
-        // treated as lit, rather than wrapping into a spurious shadow.
-        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);
+        this.layerCount = peeled ? 3 : 2;
+        const texture = createSunTexture(gl, size, this.layerCount);
+        this.current = texture;
         const framebuffer = gl.createFramebuffer();
         if (framebuffer === null)
-            throw new Error('ShadowMap: createFramebuffer failed');
+            throw new Error('SunShadowArray: createFramebuffer failed');
         this.framebuffer = framebuffer;
         gl.bindFramebuffer(gl.FRAMEBUFFER, framebuffer);
-        gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, gl.TEXTURE_2D, texture, 0);
+        gl.framebufferTextureLayer(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, texture, 0, SUN_STATIC_LAYER);
         // Depth-only: without this WebGL expects a colour attachment.
         gl.drawBuffers([gl.NONE]);
         gl.readBuffer(gl.NONE);
+        if (peeled) {
+            const peelTexture = gl.createTexture();
+            const peelFramebuffer = gl.createFramebuffer();
+            if (peelTexture === null || peelFramebuffer === null) {
+                throw new Error('SunShadowArray: the peel target could not be created');
+            }
+            gl.bindTexture(gl.TEXTURE_2D, peelTexture);
+            gl.texStorage2D(gl.TEXTURE_2D, 1, gl.DEPTH_COMPONENT24, size, size);
+            gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+            gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+            gl.bindFramebuffer(gl.FRAMEBUFFER, peelFramebuffer);
+            gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, gl.TEXTURE_2D, peelTexture, 0);
+            gl.drawBuffers([gl.NONE]);
+            gl.readBuffer(gl.NONE);
+            gl.bindTexture(gl.TEXTURE_2D, null);
+            this.peelTexture = peelTexture;
+            this.peelFramebuffer = peelFramebuffer;
+        }
+        else {
+            this.peelTexture = null;
+            this.peelFramebuffer = null;
+        }
+        gl.bindFramebuffer(gl.FRAMEBUFFER, framebuffer);
         const status = gl.checkFramebufferStatus(gl.FRAMEBUFFER);
         if (status !== gl.FRAMEBUFFER_COMPLETE) {
             /*
@@ -47,26 +96,102 @@ export class ShadowMap {
              */
             if (gl.isContextLost())
                 return;
-            throw new Error(`ShadowMap: framebuffer incomplete (0x${status.toString(16)})`);
+            throw new Error(`SunShadowArray: framebuffer incomplete (0x${status.toString(16)})`);
         }
         /*
-         * **Cleared once, here, to the far plane, because nothing else says what the texture holds.**
-         * WebGL zeroes it, and a zero compared with `LEQUAL` is an occluder at the light itself, so
-         * a layer no pass has drawn put the whole world in shade. ANGLE on Vulkan hands the same
-         * texture back reading 1, which is lit, and that is what every capture here ran on: a scene
-         * with a second depth layer it never peeled lost its sun only under ANGLE's GL backend, the
-         * one Chrome on Linux runs by default. The frame's clear value is borrowed and put back.
+         * **Every layer cleared once, here, to the far plane, because nothing else says what it
+         * holds.** WebGL zeroes the texture, and a zero compared with `LEQUAL` is an occluder at the
+         * light itself, so a layer no pass has drawn put the whole world in shade. ANGLE on Vulkan
+         * hands the same texture back reading 1, which is lit, and that is what every capture here
+         * ran on: a scene with a second depth layer it never peeled lost its sun only under ANGLE's
+         * GL backend, the one Chrome on Linux runs by default. The frame's clear value is put back.
          */
         const frameClear = gl.getParameter(gl.DEPTH_CLEAR_VALUE);
         gl.clearDepth(SHADOW_DEPTH_CLEAR);
-        gl.clear(gl.DEPTH_BUFFER_BIT);
+        gl.viewport(0, 0, size, size);
+        for (let layer = 0; layer < this.layers; layer++) {
+            gl.framebufferTextureLayer(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, texture, 0, layer);
+            gl.clear(gl.DEPTH_BUFFER_BIT);
+        }
         gl.clearDepth(frameClear);
         gl.bindFramebuffer(gl.FRAMEBUFFER, null);
-        gl.bindTexture(gl.TEXTURE_2D, null);
+        gl.bindTexture(gl.TEXTURE_2D_ARRAY, null);
+    }
+    get texture() {
+        return this.current;
+    }
+    get layers() {
+        return this.layerCount;
+    }
+    /** Whether the two glass layers exist: from the first glass a sun pass is offered, for good. */
+    get hasGlass() {
+        return this.glass;
+    }
+    /** The glass depth layer beside a map: fixed places after the three maps. */
+    glassLayer(which) {
+        return which === 'static' ? SUN_GLASS_STATIC_LAYER : SUN_GLASS_MOVING_LAYER;
     }
-    /** Bind as the render target and clear. Caller then draws the casters. */
-    begin(gl) {
+    /**
+     * Add the two glass layers, once, carrying every layer already held across.
+     *
+     * **Carried rather than re-baked**, because the sun's static map is the consumer's to bake and
+     * it may bake it once: the glass that grows the array arrives in the very pass that drew that
+     * map, so a copy is what keeps it. A depth blit per layer, same size and format, and the glass
+     * layers cleared to the far plane — nothing nearer than the sun until a pane is drawn there.
+     * Returns whether it grew, so the caller knows every bind of the old texture is stale.
+     */
+    growForGlass(gl) {
+        if (this.glass)
+            return false;
+        const old = this.current;
+        const oldLayers = this.layerCount;
+        const layers = SUN_GLASS_MOVING_LAYER + 1;
+        const texture = createSunTexture(gl, this.size, layers);
+        const read = gl.createFramebuffer();
+        if (read === null)
+            throw new Error('SunShadowArray: createFramebuffer failed');
+        gl.bindFramebuffer(gl.READ_FRAMEBUFFER, read);
+        gl.bindFramebuffer(gl.DRAW_FRAMEBUFFER, this.framebuffer);
+        for (let layer = 0; layer < oldLayers; layer++) {
+            gl.framebufferTextureLayer(gl.READ_FRAMEBUFFER, gl.DEPTH_ATTACHMENT, old, 0, layer);
+            gl.framebufferTextureLayer(gl.DRAW_FRAMEBUFFER, gl.DEPTH_ATTACHMENT, texture, 0, layer);
+            gl.blitFramebuffer(0, 0, this.size, this.size, 0, 0, this.size, this.size, gl.DEPTH_BUFFER_BIT, gl.NEAREST);
+        }
+        for (let layer = oldLayers; layer < layers; layer++) {
+            gl.framebufferTextureLayer(gl.DRAW_FRAMEBUFFER, gl.DEPTH_ATTACHMENT, texture, 0, layer);
+            gl.clearBufferfv(gl.DEPTH, 0, FAR_PLANE);
+        }
+        gl.bindFramebuffer(gl.READ_FRAMEBUFFER, null);
+        gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+        gl.deleteFramebuffer(read);
+        gl.deleteTexture(old);
+        this.current = texture;
+        this.layerCount = layers;
+        this.glass = true;
+        return true;
+    }
+    /** Bind `layer` as the render target and clear it. Caller then draws the casters. */
+    begin(gl, layer) {
+        this.peeling = layer === 'static-peel' && this.peelFramebuffer !== null;
+        if (this.peeling) {
+            gl.bindFramebuffer(gl.FRAMEBUFFER, this.peelFramebuffer);
+        }
+        else {
+            this.attach(gl, sunLayerIndex(layer));
+        }
+        this.clearAndRaster(gl);
+    }
+    /** Bind a glass depth layer as the render target and clear it: where the nearest pane is. */
+    beginGlass(gl, which) {
+        this.peeling = false;
+        this.attach(gl, this.glassLayer(which));
+        this.clearAndRaster(gl);
+    }
+    attach(gl, layer) {
         gl.bindFramebuffer(gl.FRAMEBUFFER, this.framebuffer);
+        gl.framebufferTextureLayer(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, this.current, 0, layer);
+    }
+    clearAndRaster(gl) {
         gl.viewport(0, 0, this.size, this.size);
         gl.clear(gl.DEPTH_BUFFER_BIT);
         /*
@@ -84,10 +209,39 @@ export class ShadowMap {
     end(gl) {
         gl.disable(gl.POLYGON_OFFSET_FILL);
         gl.cullFace(gl.BACK);
+        if (this.peeling) {
+            /* The peel into its layer: same size, same format, so a nearest depth blit is a copy. */
+            gl.bindFramebuffer(gl.READ_FRAMEBUFFER, this.peelFramebuffer);
+            gl.bindFramebuffer(gl.DRAW_FRAMEBUFFER, this.framebuffer);
+            gl.framebufferTextureLayer(gl.DRAW_FRAMEBUFFER, gl.DEPTH_ATTACHMENT, this.current, 0, SUN_PEELED_LAYER);
+            gl.blitFramebuffer(0, 0, this.size, this.size, 0, 0, this.size, this.size, gl.DEPTH_BUFFER_BIT, gl.NEAREST);
+            gl.bindFramebuffer(gl.READ_FRAMEBUFFER, null);
+            this.peeling = false;
+        }
         gl.bindFramebuffer(gl.FRAMEBUFFER, null);
     }
     dispose(gl) {
         gl.deleteFramebuffer(this.framebuffer);
-        gl.deleteTexture(this.texture);
+        gl.deleteTexture(this.current);
+        if (this.peelFramebuffer !== null)
+            gl.deleteFramebuffer(this.peelFramebuffer);
+        if (this.peelTexture !== null)
+            gl.deleteTexture(this.peelTexture);
     }
 }
+/** The far plane, as `clearBufferfv` takes it: a layer no pane has reached is clear of glass. */
+const FAR_PLANE = new Float32Array([SHADOW_DEPTH_CLEAR]);
+function createSunTexture(gl, size, layers) {
+    const texture = gl.createTexture();
+    if (texture === null)
+        throw new Error('SunShadowArray: createTexture failed');
+    gl.bindTexture(gl.TEXTURE_2D_ARRAY, texture);
+    gl.texStorage3D(gl.TEXTURE_2D_ARRAY, 1, gl.DEPTH_COMPONENT24, size, size, layers);
+    gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+    gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+    // Clamp so anything outside the light frustum samples the border and is
+    // treated as lit, rather than wrapping into a spurious shadow.
+    gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+    gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+    return texture;
+}

package/dist/render/sunGlassTint.d.ts

@@ -0,0 +1,25 @@
+/**
+ * What the sun's light keeps of itself through glass: an RGBA8 array of two layers, static and
+ * moving, beside the sun's depth array. RGB is the product of every pane's
+ * `transmission × (1 − F) × tint`, A the product of their clarities (`glassShadow.ts`).
+ *
+ * **Cleared to white and drawn with a multiplying blend and no depth test**, so every pane on a ray
+ * contributes and the order they come in cannot matter. **Mipmapped and filtered**, unlike the
+ * depths beside it: a frosted pane's colour is read at the level its spread asks for, so a wide
+ * spread is smooth rather than a scatter of taps — the chain is rebuilt after every draw of a layer.
+ * `'half'` makes it half the depth map's size and nothing else changes: the light matrix is the
+ * same, so a texel is a texel of the same place, only larger.
+ */
+export declare class SunGlassTint {
+    readonly size: number;
+    readonly texture: WebGLTexture;
+    private readonly framebuffer;
+    constructor(gl: WebGL2RenderingContext, size: number);
+    /** Bind `layer` (0 static, 1 moving), clear it to white, and set the multiplying state. */
+    begin(gl: WebGL2RenderingContext, layer: number): void;
+    /** Put back what `begin` changed, and rebuild the mip chain the frost reads. */
+    end(gl: WebGL2RenderingContext): void;
+    /** Every level from level 0, both layers: bound on the active unit and handed back. */
+    private fillMips;
+    dispose(gl: WebGL2RenderingContext): void;
+}

package/dist/render/sunGlassTint.js

@@ -0,0 +1,79 @@
+/**
+ * What the sun's light keeps of itself through glass: an RGBA8 array of two layers, static and
+ * moving, beside the sun's depth array. RGB is the product of every pane's
+ * `transmission × (1 − F) × tint`, A the product of their clarities (`glassShadow.ts`).
+ *
+ * **Cleared to white and drawn with a multiplying blend and no depth test**, so every pane on a ray
+ * contributes and the order they come in cannot matter. **Mipmapped and filtered**, unlike the
+ * depths beside it: a frosted pane's colour is read at the level its spread asks for, so a wide
+ * spread is smooth rather than a scatter of taps — the chain is rebuilt after every draw of a layer.
+ * `'half'` makes it half the depth map's size and nothing else changes: the light matrix is the
+ * same, so a texel is a texel of the same place, only larger.
+ */
+export class SunGlassTint {
+    size;
+    texture;
+    framebuffer;
+    constructor(gl, size) {
+        this.size = size;
+        const texture = gl.createTexture();
+        const framebuffer = gl.createFramebuffer();
+        if (texture === null || framebuffer === null) {
+            throw new Error('SunGlassTint: the tint target could not be created');
+        }
+        this.texture = texture;
+        this.framebuffer = framebuffer;
+        gl.bindTexture(gl.TEXTURE_2D_ARRAY, texture);
+        gl.texStorage3D(gl.TEXTURE_2D_ARRAY, mipLevels(size), gl.RGBA8, size, size, 2);
+        gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_MIN_FILTER, gl.LINEAR_MIPMAP_LINEAR);
+        gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+        gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+        gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+        gl.bindTexture(gl.TEXTURE_2D_ARRAY, null);
+        /* Both layers born clear: a layer no pane has reached lets everything through. */
+        gl.bindFramebuffer(gl.FRAMEBUFFER, framebuffer);
+        for (let layer = 0; layer < 2; layer++) {
+            gl.framebufferTextureLayer(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, texture, 0, layer);
+            gl.clearBufferfv(gl.COLOR, 0, CLEAR);
+        }
+        gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+        this.fillMips(gl);
+    }
+    /** Bind `layer` (0 static, 1 moving), clear it to white, and set the multiplying state. */
+    begin(gl, layer) {
+        gl.bindFramebuffer(gl.FRAMEBUFFER, this.framebuffer);
+        gl.framebufferTextureLayer(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, this.texture, 0, layer);
+        gl.viewport(0, 0, this.size, this.size);
+        gl.clearBufferfv(gl.COLOR, 0, CLEAR);
+        gl.disable(gl.DEPTH_TEST);
+        gl.depthMask(false);
+        gl.disable(gl.POLYGON_OFFSET_FILL);
+        gl.enable(gl.BLEND);
+        gl.blendEquation(gl.FUNC_ADD);
+        gl.blendFuncSeparate(gl.DST_COLOR, gl.ZERO, gl.DST_ALPHA, gl.ZERO);
+    }
+    /** Put back what `begin` changed, and rebuild the mip chain the frost reads. */
+    end(gl) {
+        gl.disable(gl.BLEND);
+        gl.depthMask(true);
+        gl.enable(gl.DEPTH_TEST);
+        gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+        this.fillMips(gl);
+    }
+    /** Every level from level 0, both layers: bound on the active unit and handed back. */
+    fillMips(gl) {
+        const previous = gl.getParameter(gl.TEXTURE_BINDING_2D_ARRAY);
+        gl.bindTexture(gl.TEXTURE_2D_ARRAY, this.texture);
+        gl.generateMipmap(gl.TEXTURE_2D_ARRAY);
+        gl.bindTexture(gl.TEXTURE_2D_ARRAY, previous);
+    }
+    dispose(gl) {
+        gl.deleteFramebuffer(this.framebuffer);
+        gl.deleteTexture(this.texture);
+    }
+}
+const CLEAR = new Float32Array([1, 1, 1, 1]);
+/** A full chain down to one texel. */
+function mipLevels(size) {
+    return Math.floor(Math.log2(Math.max(1, size))) + 1;
+}

package/dist/render/translucentQueue.d.ts

@@ -1,5 +1,6 @@
 import type { ReadonlyMat4 } from 'gl-matrix';
 import type { TranslucentMeshOptions } from './backend/webgl2/renderer.ts';
+import type { ResolvedGlass } from './glass.ts';
 /**
  * The frame's translucent draws, held so they can be submitted more than once.
  *
@@ -46,11 +47,14 @@ export interface TranslucentDraw {
     /** What survives one metre of the medium. Null where the draw named none; otherwise a copy. */
     refractTint: Float32Array | null;
     thicknessM: number;
+    /** Glass, resolved, or null for a draw that is not glass. See `glass.ts`. */
+    glass: ResolvedGlass | null;
 }
 export declare class TranslucentQueue {
     private readonly pool;
     private count;
     private refracting;
+    private glassing;
     /** How many draws this frame has recorded. */
     get length(): number;
     /**
@@ -58,6 +62,8 @@ export declare class TranslucentQueue {
      * frame behind it first, and does not copy it for a set that never reads it.
      */
     get refracts(): boolean;
+    /** Whether anything recorded this frame is glass, so the copy it reads needs its mip chain. */
+    get glassy(): boolean;
     /** How many records are pooled, which a test uses to assert a steady scene stops allocating. */
     get capacity(): number;
     /**

package/dist/render/translucentQueue.js

@@ -1,3 +1,4 @@
+import { resolveGlass } from './glass.js';
 function newRecord() {
     return {
         mesh: null,
@@ -14,12 +15,15 @@ function newRecord() {
         refractTint: null,
         thicknessM: 0,
         refractTintStore: new Float32Array(3),
+        glass: null,
+        glassStore: { transmission: 0, frost: 0, tint: [1, 1, 1] },
     };
 }
 export class TranslucentQueue {
     pool = [];
     count = 0;
     refracting = 0;
+    glassing = 0;
     /** How many draws this frame has recorded. */
     get length() {
         return this.count;
@@ -31,6 +35,10 @@ export class TranslucentQueue {
     get refracts() {
         return this.refracting > 0;
     }
+    /** Whether anything recorded this frame is glass, so the copy it reads needs its mip chain. */
+    get glassy() {
+        return this.glassing > 0;
+    }
     /** How many records are pooled, which a test uses to assert a steady scene stops allocating. */
     get capacity() {
         return this.pool.length;
@@ -65,7 +73,12 @@ export class TranslucentQueue {
             record.tint = record.tintStore;
         }
         record.refraction = options.refraction ?? 0;
-        if (record.refraction > 0)
+        /* Glass reads the copy too, whether or not it bends: see `glass.ts`. */
+        const glassy = resolveGlass(options.glass, record.glassStore);
+        record.glass = glassy ? record.glassStore : null;
+        if (glassy)
+            this.glassing++;
+        if (record.refraction > 0 || glassy)
             this.refracting++;
         record.thicknessM = options.thicknessM ?? 0;
         const refractTint = options.refractTint ?? null;
@@ -97,5 +110,6 @@ export class TranslucentQueue {
     reset() {
         this.count = 0;
         this.refracting = 0;
+        this.glassing = 0;
     }
 }