@driftengine/core 4.13.5 → 4.14.0

package/dist/render/emissiveFlow.d.ts

@@ -0,0 +1,40 @@
+/**
+ * A material's glow moved and masked: `SurfaceMaterial.emissiveScroll` and `emissiveMaskLayer`,
+ * packed into `uEmissiveFlow` for the lit stage's `EMISSIVE_FLOW` switch. Both backends pack it
+ * here and only upload it, so they cannot disagree about which layer a mask is.
+ *
+ * **What it is for**: lava in a rock's cracks, a sign's lettering, a glow repeated with a surface's
+ * first layer and drifting across it, held to where the surface glows by a map that spans the mesh
+ * once. Folded into each vertex's emission instead, the glow spreads across whole faces of a coarse
+ * mesh where it should follow the cracks.
+ *
+ * **The mask is the alpha of a layer of the emissive map's own array**, read at the mesh's first
+ * coordinates as they are, before the material's repeat, offset, layers or projection: alpha is
+ * never decoded as sRGB, so it is the number it was written as in either colour space, and no
+ * texture binding is spent, since the lit stage has none left (`textureUnitBudget.test.ts`). What
+ * that gives up is a mask of its own size: a layer of an array is the array's size.
+ *
+ * **The scroll moves the emissive map alone**, by `Environment.surfaceTime`, in its own repeats a
+ * second, wrapped to one so a long-running clock keeps its precision; the albedo and every other map
+ * stay where they are.
+ */
+/**
+ * Floats in `uEmissiveFlow`: the scroll on u and v, the mask's layer plus one (0, none) and one
+ * unused; then the scale and offset that take the material's coordinates back to the mesh's own.
+ */
+export declare const EMISSIVE_FLOW_FLOATS = 8;
+/** What a material says about its glow's flow, and the repeat and offset its coordinates carry. */
+export interface EmissiveFlowMaterial {
+    readonly emissiveScroll?: readonly [number, number] | null;
+    readonly emissiveMaskLayer?: number | null;
+    readonly uScale?: number;
+    readonly vScale?: number;
+    readonly uOffset?: number;
+    readonly vOffset?: number;
+}
+/**
+ * Pack a material's flow into `out` and say whether it asks for one: a scroll that moves, or a mask
+ * that is a whole layer. A scroll that is not a number is still; a layer that is not a whole number
+ * at or above zero is no mask.
+ */
+export declare function packEmissiveFlow(material: EmissiveFlowMaterial | null, out: Float32Array): boolean;

package/dist/render/emissiveFlow.js

@@ -0,0 +1,51 @@
+/**
+ * A material's glow moved and masked: `SurfaceMaterial.emissiveScroll` and `emissiveMaskLayer`,
+ * packed into `uEmissiveFlow` for the lit stage's `EMISSIVE_FLOW` switch. Both backends pack it
+ * here and only upload it, so they cannot disagree about which layer a mask is.
+ *
+ * **What it is for**: lava in a rock's cracks, a sign's lettering, a glow repeated with a surface's
+ * first layer and drifting across it, held to where the surface glows by a map that spans the mesh
+ * once. Folded into each vertex's emission instead, the glow spreads across whole faces of a coarse
+ * mesh where it should follow the cracks.
+ *
+ * **The mask is the alpha of a layer of the emissive map's own array**, read at the mesh's first
+ * coordinates as they are, before the material's repeat, offset, layers or projection: alpha is
+ * never decoded as sRGB, so it is the number it was written as in either colour space, and no
+ * texture binding is spent, since the lit stage has none left (`textureUnitBudget.test.ts`). What
+ * that gives up is a mask of its own size: a layer of an array is the array's size.
+ *
+ * **The scroll moves the emissive map alone**, by `Environment.surfaceTime`, in its own repeats a
+ * second, wrapped to one so a long-running clock keeps its precision; the albedo and every other map
+ * stay where they are.
+ */
+/**
+ * Floats in `uEmissiveFlow`: the scroll on u and v, the mask's layer plus one (0, none) and one
+ * unused; then the scale and offset that take the material's coordinates back to the mesh's own.
+ */
+export const EMISSIVE_FLOW_FLOATS = 8;
+/**
+ * Pack a material's flow into `out` and say whether it asks for one: a scroll that moves, or a mask
+ * that is a whole layer. A scroll that is not a number is still; a layer that is not a whole number
+ * at or above zero is no mask.
+ */
+export function packEmissiveFlow(material, out) {
+    const scroll = material?.emissiveScroll ?? null;
+    const u = scroll !== null && Number.isFinite(scroll[0]) ? scroll[0] : 0;
+    const v = scroll !== null && Number.isFinite(scroll[1]) ? scroll[1] : 0;
+    const layer = material?.emissiveMaskLayer ?? null;
+    const masked = layer !== null && Number.isInteger(layer) && layer >= 0;
+    out[0] = u;
+    out[1] = v;
+    /* Plus one, so an unwritten zero is no mask rather than a mask of layer 0. */
+    out[2] = masked ? layer + 1 : 0;
+    out[3] = 0;
+    /* The vertex stage laid `uv · scale + offset`; this undoes it. A scale of zero has no inverse,
+       and every texel of such a surface is the one coordinate, so the mesh's own is taken as 0. */
+    const uScale = material?.uScale ?? 1;
+    const vScale = material?.vScale ?? 1;
+    out[4] = uScale === 0 ? 0 : 1 / uScale;
+    out[5] = vScale === 0 ? 0 : 1 / vScale;
+    out[6] = uScale === 0 ? 0 : -(material?.uOffset ?? 0) / uScale;
+    out[7] = vScale === 0 ? 0 : -(material?.vOffset ?? 0) / vScale;
+    return u !== 0 || v !== 0 || masked;
+}

package/dist/render/fixtureAtlas.d.ts

@@ -3,11 +3,16 @@ export interface FixtureAtlasLayout {
     readonly height: number;
     /** Rows of cookie tiles at the top: `COOKIE_TILE`, or 0 with none loaded. */
     readonly cookieRows: number;
-    /** The first row of the profiles, below the cookies. */
+    /** The first row of the decals' images, below the cookies, and how many rows they take. */
+    readonly decalTop: number;
+    readonly decalRows: number;
+    /** The first row of the profiles, below the cookies and the decals. */
     readonly iesTop: number;
 }
-/** The atlas for `iesRows` rows of profile and `cookieTiles` cookies. */
-export declare function fixtureAtlasLayout(iesRows: number, cookieTiles: number): FixtureAtlasLayout;
+/** The row the decals' band starts at: below the cookies, which are there or are not. */
+export declare function decalBandTop(cookieTiles: number): number;
+/** The atlas for `iesRows` rows of profile, `cookieTiles` cookies and `decalTiles` decal images. */
+export declare function fixtureAtlasLayout(iesRows: number, cookieTiles: number, decalTiles?: number): FixtureAtlasLayout;
 /**
  * The profiles' rows as the atlas holds them: `data` one float a texel, `width` across and `rows`
  * down, spread into the red channel of a four-channel image the atlas's size, the rest ones. The

package/dist/render/fixtureAtlas.js

@@ -1,6 +1,9 @@
 /**
  * What a light fixture throws, in one texture: its spot cookies in the top band, its photometric
- * profiles in the rows below.
+ * profiles in the rows below. And between the two, since the lit stage had no binding left for them
+ * either, the images of the decals laid into base colours (`baseDecals.ts`), a band of squares a
+ * frame may rewrite; each band is found from its own end or its own row, so the others' lookups are
+ * as they were.
  *
  * **One binding for two tables, because the lit stage had one sampler left.** The cookie atlas and
  * the photometric atlas were two small float textures read with `textureLod`, and the widest lit
@@ -19,14 +22,22 @@
  */
 import { IES_ATLAS_WIDTH } from './iesProfile.js';
 import { COOKIE_TILE } from './lightBudget.js';
-/** The atlas for `iesRows` rows of profile and `cookieTiles` cookies. */
-export function fixtureAtlasLayout(iesRows, cookieTiles) {
+import { BASE_DECAL_TILE } from './baseDecals.js';
+/** The row the decals' band starts at: below the cookies, which are there or are not. */
+export function decalBandTop(cookieTiles) {
+    return cookieTiles > 0 ? COOKIE_TILE : 0;
+}
+/** The atlas for `iesRows` rows of profile, `cookieTiles` cookies and `decalTiles` decal images. */
+export function fixtureAtlasLayout(iesRows, cookieTiles, decalTiles = 0) {
     const cookieRows = cookieTiles > 0 ? COOKIE_TILE : 0;
+    const decalRows = decalTiles > 0 ? BASE_DECAL_TILE : 0;
     return {
-        width: Math.max(IES_ATLAS_WIDTH, COOKIE_TILE * cookieTiles),
-        height: cookieRows + iesRows,
+        width: Math.max(IES_ATLAS_WIDTH, COOKIE_TILE * cookieTiles, BASE_DECAL_TILE * decalTiles),
+        height: cookieRows + decalRows + iesRows,
         cookieRows,
-        iesTop: cookieRows,
+        decalTop: cookieRows,
+        decalRows,
+        iesTop: cookieRows + decalRows,
     };
 }
 /**

package/dist/render/globalMedium.d.ts

@@ -110,6 +110,16 @@ export interface GlobalMediumOptions {
     readonly sunScatter?: number;
     /** The same for the sky's fill, which lights a shadowed medium from every side. Default 1. */
     readonly skyScatter?: number;
+    /**
+     * The sky's fill the medium scatters, a colour of its own in the units of
+     * `Environment.ambient`, which `skyScatter` then scales. Absent or null, the frame's ambient, as
+     * it always was. **For a scene whose surfaces are lit by more than its flat ambient**, a sky's
+     * cubemap, probes and a bake, which keeps that ambient for what falls outside them: the ambient
+     * is then the wrong colour for the sky's light in the air, and setting it to the right one would
+     * relight those surfaces too. What it gives up is the sky's direction, as the ambient does: one
+     * colour from every side.
+     */
+    readonly skyFill?: readonly [number, number, number] | null;
     /**
      * The same for the lamps, each through its own shadow and times its own `lightMediumScatter`.
      * **Default 0**: a medium was the sun's and the sky's until there was this, and a scene that
@@ -135,6 +145,8 @@ export interface ResolvedGlobalMedium {
     readonly sunScatter: number;
     readonly skyScatter: number;
     readonly lampScatter: number;
+    /** The sky's fill of the medium's own, or null for the frame's ambient: see `mediumSkyFill`. */
+    readonly skyFill: readonly [number, number, number] | null;
 }
 /**
  * What a renderer starts with: off, and everything else at a value that means "ordinary air".
@@ -153,6 +165,11 @@ export declare const DEFAULT_GLOBAL_MEDIUM: GlobalMediumOptions;
  * than reporting; a `maxDistance` of zero is a march with no length that still costs its steps.
  */
 export declare function resolveGlobalMedium(options: Partial<GlobalMediumOptions>): ResolvedGlobalMedium;
+/**
+ * The colour the medium scatters as the sky's fill: its own where it has one, else the frame's
+ * ambient. One decision both backends upload, so the two cannot disagree about which.
+ */
+export declare function mediumSkyFill(medium: Pick<ResolvedGlobalMedium, 'skyFill'>, ambient: ArrayLike<number>): ArrayLike<number>;
 /** `setGlobalMedium`'s object form: a density, and any of the rest. */
 export type GlobalMediumSettings = Partial<GlobalMediumOptions> & {
     readonly density: number;

package/dist/render/globalMedium.js

@@ -88,8 +88,22 @@ export function resolveGlobalMedium(options) {
         sunScatter: Math.max(0, finite(options.sunScatter, 1)),
         skyScatter: Math.max(0, finite(options.skyScatter, 1)),
         lampScatter: Math.max(0, finite(options.lampScatter, 0)),
+        skyFill: options.skyFill === undefined || options.skyFill === null
+            ? null
+            : [
+                Math.max(0, finite(options.skyFill[0], 0)),
+                Math.max(0, finite(options.skyFill[1], 0)),
+                Math.max(0, finite(options.skyFill[2], 0)),
+            ],
     };
 }
+/**
+ * The colour the medium scatters as the sky's fill: its own where it has one, else the frame's
+ * ambient. One decision both backends upload, so the two cannot disagree about which.
+ */
+export function mediumSkyFill(medium, ambient) {
+    return medium.skyFill ?? ambient;
+}
 /**
  * `setGlobalMedium`'s two forms, its four numbers or the object, read one way for both backends:
  * a density that is not a number is none.

package/dist/render/globalMediumPass.js

@@ -1,5 +1,5 @@
 import { mat4 } from 'gl-matrix';
-import { mediumTargetSize } from './globalMedium.js';
+import { mediumSkyFill, 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';
@@ -168,7 +168,8 @@ export class GlobalMediumPass {
         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);
+        const sky = mediumSkyFill(options, light.ambient);
+        gl.uniform3f(u['uAmbient'] ?? null, sky[0] ?? 0, sky[1] ?? 0, sky[2] ?? 0);
         gl.uniform1f(u['uDensity'] ?? null, options.density);
         gl.uniform2f(u['uHeight'] ?? null, options.heightFalloff, options.baseY);
         gl.uniform3f(u['uLayer2'] ?? null, options.density2, options.heightFalloff2, options.baseY2);

package/dist/render/iridescentOverlay.d.ts

@@ -0,0 +1,78 @@
+/**
+ * A surface's iridescent overlay: a hue that shifts with the view, laid over the base colour before
+ * it is lit. `SurfaceMaterial.iridescentOverlay`, packed into `uIridescence` for the lit stage's
+ * `IRIDESCENT_OVERLAY` switch, and the same arithmetic on the CPU, which the tests hold the shader to.
+ *
+ * Per pixel, with `N` the mapped normal, `V` toward the eye and `uv` the mesh's own first
+ * coordinates, as many material systems shade a sheen on cloth or a coat:
+ *
+ *     h = saturate((N·H)^contrast), 0 where N·H ≤ 0, H = normalize(V + direction)
+ *     x = N·V + uv.x + blend · (h − N·V)
+ *     t = saturate(fract(x · tiling))
+ *     base' = base + (overlay(base, ramp(t)) − base) · x · mask · weight
+ *
+ * where `overlay` is the usual blend, `a < ½ ? 2ao : 1 − 2(1 − a)(1 − o)` per channel.
+ *
+ * **The ramp is uniforms, thirty-two colours, and not a texture**, because the lit stage has no
+ * texture binding left (`textureUnitBudget.test.ts`): a caller's ramp of any length is resampled to
+ * thirty-two on the way in and read back between neighbours. What that gives up is a ramp with
+ * detail finer than a thirty-second of its length, which a smooth spectrum does not have. **The
+ * mask is a channel of a layer of one of the material's own arrays**, for the same reason, read at
+ * the material's coordinates; alpha is linear in every array, and a colour channel of an sRGB array
+ * is decoded before it is read.
+ *
+ * Thirty-six vectors, so WebGL2 refuses it, in words, on a part whose lit stage has no room, as it
+ * refuses a material's tiled detail.
+ */
+/** Three numbers, read and never written. */
+type Three = readonly [number, number, number];
+/** Colours the ramp is resampled to. */
+export declare const IRIDESCENT_RAMP = 32;
+/** Floats in `uIridescence`: four vectors of numbers, then the ramp a vector a colour. */
+export declare const IRIDESCENT_FLOATS: number;
+/** Which of a material's arrays holds the mask. */
+export type IridescentMaskMap = 'orm' | 'model' | 'albedo' | 'emissive';
+/** `SurfaceMaterial.iridescentOverlay`. */
+export interface IridescentOverlay {
+    /**
+     * The overlay colour along `t`, linear, three floats a colour, at least two colours, the first at
+     * `t = 0` and the last at `t = 1`. Resampled to thirty-two.
+     */
+    readonly ramp: ArrayLike<number>;
+    /** A fixed direction in the world the sheen turns toward, `S`. Need not be unit length. */
+    readonly direction: Three;
+    /** How far the view's term is turned toward the sheen, 0 to 1. Default 0.6. */
+    readonly blend?: number;
+    /** The sheen's exponent. Default 1. */
+    readonly contrast?: number;
+    /** How many times the ramp repeats across `x`. Default 2. */
+    readonly tiling?: number;
+    /** How much of the overlay is laid on. Default 0.25. */
+    readonly weight?: number;
+    /** Where it is laid: a channel of a layer of one of the material's arrays. Absent, everywhere. */
+    readonly mask?: {
+        readonly map: IridescentMaskMap;
+        readonly layer: number;
+        /** 0 red, 1 green, 2 blue, 3 alpha. */
+        readonly channel: 0 | 1 | 2 | 3;
+    } | null;
+}
+/** Why an overlay cannot be drawn, or null where it can. */
+export declare function iridescentRefusal(overlay: IridescentOverlay): string | null;
+/**
+ * Pack an overlay into `out`, with the scale and offset that take the material's coordinates back
+ * to the mesh's own; all zeros, which the shader reads as none, for null. Refuse what
+ * `iridescentRefusal` refuses before calling this.
+ */
+export declare function packIridescentOverlay(overlay: IridescentOverlay | null, uv: {
+    uScale?: number;
+    vScale?: number;
+    uOffset?: number;
+    vOffset?: number;
+}, out: Float32Array): void;
+/**
+ * The base colour with the overlay laid on, as the lit stage computes it from a packed block: `n`
+ * and `toEye` unit length, `uv` the mesh's own coordinates, `mask` the texel's channel. Into `out`.
+ */
+export declare function iridescentBase(packed: ArrayLike<number>, base: Three, n: Three, toEye: Three, uv: readonly [number, number], mask: number, out: [number, number, number]): [number, number, number];
+export {};

package/dist/render/iridescentOverlay.js

@@ -0,0 +1,102 @@
+/** Colours the ramp is resampled to. */
+export const IRIDESCENT_RAMP = 32;
+/** Floats in `uIridescence`: four vectors of numbers, then the ramp a vector a colour. */
+export const IRIDESCENT_FLOATS = (4 + IRIDESCENT_RAMP) * 4;
+const MASK_SOURCE = {
+    orm: 1,
+    model: 2,
+    albedo: 3,
+    emissive: 4,
+};
+/** Why an overlay cannot be drawn, or null where it can. */
+export function iridescentRefusal(overlay) {
+    const values = overlay.ramp.length;
+    if (values < 6 || values % 3 !== 0) {
+        return `a ramp of ${values} numbers; it is three a colour, at least two colours`;
+    }
+    const [x, y, z] = overlay.direction;
+    if (!(Number.isFinite(x) && Number.isFinite(y) && Number.isFinite(z)) ||
+        x * x + y * y + z * z === 0) {
+        return 'a direction that is not one';
+    }
+    const mask = overlay.mask ?? null;
+    if (mask !== null && !(Number.isInteger(mask.layer) && mask.layer >= 0)) {
+        return `a mask layer of ${mask.layer}; a layer is a whole number from 0`;
+    }
+    return null;
+}
+/**
+ * Pack an overlay into `out`, with the scale and offset that take the material's coordinates back
+ * to the mesh's own; all zeros, which the shader reads as none, for null. Refuse what
+ * `iridescentRefusal` refuses before calling this.
+ */
+export function packIridescentOverlay(overlay, uv, out) {
+    out.fill(0);
+    if (overlay === null)
+        return;
+    const [x, y, z] = overlay.direction;
+    const length = Math.hypot(x, y, z);
+    out[0] = x / length;
+    out[1] = y / length;
+    out[2] = z / length;
+    out[3] = overlay.blend ?? 0.6;
+    out[4] = overlay.contrast ?? 1;
+    out[5] = overlay.tiling ?? 2;
+    out[6] = overlay.weight ?? 0.25;
+    /* On: a zero here, which an unwritten block is, is none. */
+    out[7] = 1;
+    const mask = overlay.mask ?? null;
+    out[8] = mask === null ? 0 : MASK_SOURCE[mask.map];
+    out[9] = mask === null ? 0 : mask.layer;
+    out[10] = mask === null ? 0 : mask.channel;
+    const uScale = uv.uScale ?? 1;
+    const vScale = uv.vScale ?? 1;
+    out[12] = uScale === 0 ? 0 : 1 / uScale;
+    out[13] = vScale === 0 ? 0 : 1 / vScale;
+    out[14] = uScale === 0 ? 0 : -(uv.uOffset ?? 0) / uScale;
+    out[15] = vScale === 0 ? 0 : -(uv.vOffset ?? 0) / vScale;
+    /* The ramp, resampled to thirty-two colours between its own neighbours. */
+    const colours = overlay.ramp.length / 3;
+    for (let i = 0; i < IRIDESCENT_RAMP; i++) {
+        const at = (i / (IRIDESCENT_RAMP - 1)) * (colours - 1);
+        const below = Math.min(Math.floor(at), colours - 2);
+        const share = at - below;
+        for (let c = 0; c < 3; c++) {
+            const a = overlay.ramp[below * 3 + c];
+            const b = overlay.ramp[(below + 1) * 3 + c];
+            out[16 + i * 4 + c] = a + (b - a) * share;
+        }
+    }
+}
+/**
+ * The base colour with the overlay laid on, as the lit stage computes it from a packed block: `n`
+ * and `toEye` unit length, `uv` the mesh's own coordinates, `mask` the texel's channel. Into `out`.
+ */
+export function iridescentBase(packed, base, n, toEye, uv, mask, out) {
+    const p = (i) => packed[i];
+    let hx = toEye[0] + p(0);
+    let hy = toEye[1] + p(1);
+    let hz = toEye[2] + p(2);
+    const hl = Math.hypot(hx, hy, hz) || 1;
+    hx /= hl;
+    hy /= hl;
+    hz /= hl;
+    const nh = n[0] * hx + n[1] * hy + n[2] * hz;
+    const h = nh > 0 ? Math.min(1, Math.max(0, nh ** p(4))) : 0;
+    const nv = n[0] * toEye[0] + n[1] * toEye[1] + n[2] * toEye[2];
+    const x = nv + uv[0] + p(3) * (h - nv);
+    const scaled = x * p(5);
+    const t = Math.min(1, Math.max(0, scaled - Math.floor(scaled)));
+    const at = t * (IRIDESCENT_RAMP - 1);
+    const below = Math.min(Math.floor(at), IRIDESCENT_RAMP - 2);
+    const share = at - below;
+    const amount = x * mask * p(6);
+    for (let c = 0; c < 3; c++) {
+        const o0 = p(16 + below * 4 + c);
+        const o = o0 + (p(16 + (below + 1) * 4 + c) - o0) * share;
+        const a = base[c];
+        const blended = a < 0.5 ? 2 * a * o : 1 - 2 * (1 - a) * (1 - o);
+        out[c] = a + (blended - a) * amount;
+    }
+    return out;
+}

package/dist/render/mesh.d.ts

@@ -22,6 +22,16 @@ export declare class Mesh {
         readonly positions: WebGLBuffer;
         readonly normals: WebGLBuffer;
     } | null;
+    /**
+     * A dynamic mesh's positions as they stood before this frame's first rewrite, for the motion
+     * WebGL2's temporal resolve follows (`backend/webgl2/motionTarget.ts`). Made the first time one is
+     * kept, so a mesh that never moves under the resolve pays nothing.
+     */
+    private previousPositions;
+    /** The frame that rewrite belongs to (`frameOfChange`), or -1 for none yet. */
+    changedFrame: number;
+    /** A vertex array for the motion pass, without and with last frame's positions, made on demand. */
+    private motionArrays;
     /** The colour buffer, kept so `updateColors` can rewrite it. Null unless `dynamicColors`. */
     private readonly recolourable;
     /** How many floats the position buffer holds, so an update of the wrong size is refused. */
@@ -140,6 +150,20 @@ export declare class Mesh {
     /** Draw `count` instances through a batch's own vertex array. See `createInstanceArray`. */
     drawInstancesThrough(gl: WebGL2RenderingContext, vao: WebGLVertexArrayObject, count: number): void;
     dispose(gl: WebGL2RenderingContext): void;
+    /**
+     * Keep this dynamic mesh's positions as they stand, before a rewrite: one buffer copy on the
+     * device. The caller decides whether this rewrite is the frame's first (`keepsPrevious`).
+     */
+    keepPrevious(gl: WebGL2RenderingContext): void;
+    /** Whether last frame's positions have been kept: a dynamic mesh rewritten under the resolve. */
+    get keptPrevious(): boolean;
+    /**
+     * Draw this mesh for the motion pass: its positions at 0, last frame's at 1 where `previous` asks
+     * and they were kept, and its rig's influences where `flat`'s skinning reads them, 11, 12, 14 and
+     * 15. A vertex array of its own, made once a variant, so the one the lit pass draws with is never
+     * touched.
+     */
+    drawMotion(gl: WebGL2RenderingContext, previous: boolean): void;
     /**
      * Rewrite this mesh's positions, and its normals where the caller has them.
      *

package/dist/render/mesh.js

@@ -27,6 +27,8 @@ import { validateMeshData } from '@driftengine/drft';
  */
 /** Attribute locations are fixed engine-wide (`layout(location = n)` in GLSL). */
 const ATTR_POSITION = 0;
+/** What the motion pass reads: positions, and a rig's two sets of joints and weights. */
+const MOTION_LOCATIONS = [ATTR_POSITION, 11, 12, 14, 15];
 const ATTR_NORMAL = 1;
 const ATTR_COLOR = 2;
 const ATTR_EMISSIVE = 3;
@@ -96,6 +98,16 @@ export class Mesh {
     get streams() {
         return this.deformable;
     }
+    /**
+     * A dynamic mesh's positions as they stood before this frame's first rewrite, for the motion
+     * WebGL2's temporal resolve follows (`backend/webgl2/motionTarget.ts`). Made the first time one is
+     * kept, so a mesh that never moves under the resolve pays nothing.
+     */
+    previousPositions = null;
+    /** The frame that rewrite belongs to (`frameOfChange`), or -1 for none yet. */
+    changedFrame = -1;
+    /** A vertex array for the motion pass, without and with last frame's positions, made on demand. */
+    motionArrays = [null, null];
     /** The colour buffer, kept so `updateColors` can rewrite it. Null unless `dynamicColors`. */
     recolourable = null;
     /** How many floats the position buffer holds, so an update of the wrong size is refused. */
@@ -426,6 +438,73 @@ export class Mesh {
         for (const buffer of this.buffers)
             gl.deleteBuffer(buffer);
         gl.deleteVertexArray(this.vao);
+        for (const vao of this.motionArrays)
+            if (vao !== null)
+                gl.deleteVertexArray(vao);
+        if (this.previousPositions !== null)
+            gl.deleteBuffer(this.previousPositions);
+    }
+    /**
+     * Keep this dynamic mesh's positions as they stand, before a rewrite: one buffer copy on the
+     * device. The caller decides whether this rewrite is the frame's first (`keepsPrevious`).
+     */
+    keepPrevious(gl) {
+        const deformable = this.deformable;
+        if (deformable === null)
+            return;
+        const bytes = this.positionFloats * 4;
+        if (this.previousPositions === null) {
+            const buffer = gl.createBuffer();
+            if (buffer === null)
+                throw new Error('createBuffer failed');
+            gl.bindBuffer(gl.COPY_WRITE_BUFFER, buffer);
+            gl.bufferData(gl.COPY_WRITE_BUFFER, bytes, gl.DYNAMIC_COPY);
+            this.previousPositions = buffer;
+        }
+        gl.bindBuffer(gl.COPY_READ_BUFFER, deformable.positions);
+        gl.bindBuffer(gl.COPY_WRITE_BUFFER, this.previousPositions);
+        gl.copyBufferSubData(gl.COPY_READ_BUFFER, gl.COPY_WRITE_BUFFER, 0, 0, bytes);
+        gl.bindBuffer(gl.COPY_READ_BUFFER, null);
+        gl.bindBuffer(gl.COPY_WRITE_BUFFER, null);
+    }
+    /** Whether last frame's positions have been kept: a dynamic mesh rewritten under the resolve. */
+    get keptPrevious() {
+        return this.previousPositions !== null;
+    }
+    /**
+     * Draw this mesh for the motion pass: its positions at 0, last frame's at 1 where `previous` asks
+     * and they were kept, and its rig's influences where `flat`'s skinning reads them, 11, 12, 14 and
+     * 15. A vertex array of its own, made once a variant, so the one the lit pass draws with is never
+     * touched.
+     */
+    drawMotion(gl, previous) {
+        const at = previous && this.previousPositions !== null ? 1 : 0;
+        let vao = this.motionArrays[at] ?? null;
+        if (vao === null) {
+            vao = gl.createVertexArray();
+            if (vao === null)
+                throw new Error('createVertexArray failed');
+            gl.bindVertexArray(vao);
+            for (const attribute of this.layout) {
+                if (!MOTION_LOCATIONS.includes(attribute.location))
+                    continue;
+                gl.bindBuffer(gl.ARRAY_BUFFER, attribute.buffer);
+                gl.enableVertexAttribArray(attribute.location);
+                gl.vertexAttribPointer(attribute.location, attribute.size, attribute.type, attribute.normalized, 0, 0);
+            }
+            if (at === 1 && this.previousPositions !== null) {
+                gl.bindBuffer(gl.ARRAY_BUFFER, this.previousPositions);
+                gl.enableVertexAttribArray(1);
+                gl.vertexAttribPointer(1, 3, gl.FLOAT, false, 0, 0);
+            }
+            gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, this.indexBuffer);
+            gl.bindVertexArray(null);
+            gl.bindBuffer(gl.ARRAY_BUFFER, null);
+            this.motionArrays[at] = vao;
+        }
+        gl.bindVertexArray(vao);
+        gl.drawElements(gl.TRIANGLES, this.indexCount, this.indexType, 0);
+        gl.bindVertexArray(null);
     }
     /**
      * Rewrite this mesh's positions, and its normals where the caller has them.

package/dist/render/pointSkin.d.ts

@@ -44,8 +44,26 @@ export interface PointSkinReach {
 }
 /** Refuse a skin whose arrays disagree with a mesh of `vertices`, or that names a joint past the rest. */
 export declare function validatePointSkin(data: PointSkinData, vertices: number): void;
+/**
+ * Refuse a rewrite of vertices `first` onward, as many as `data` holds, that does not fit a mesh of
+ * `vertices`: arrays that disagree with each other, a range that is not whole vertices inside the
+ * mesh, or a joint past the rest. Named by the mesh's own vertex numbers.
+ */
+export declare function validatePointSkinRange(data: PointSkinData, first: number, vertices: number): void;
 /** Measure a skin's reach once, at creation. */
 export declare function reachOf(data: PointSkinData): PointSkinReach;
+/**
+ * A skin's reach after part of it is rewritten with `data`: the farther of the old reach and the
+ * new at each joint, the joints the two name between them, and the widest span of weight sums.
+ *
+ * **It widens and never narrows**, because the vertices the rewrite replaced may have been the
+ * ones that set a joint's reach, and finding out would mean keeping every vertex on the CPU and
+ * reading them all again. A skin that changes shape back and forth settles at the union of its
+ * shapes, which is still a box no posed vertex leaves, and culls a little less than it could. What
+ * would make that wrong is a skin rewritten into ever larger shapes and never back; making it
+ * again with `createPointSkin` measures it afresh.
+ */
+export declare function widenReach(reach: PointSkinReach, data: PointSkinData): PointSkinReach;
 /**
  * The bounds of a pose, into the mesh's own: `matrices` holds each joint's transform into the
  * mesh's model space, sixteen floats, column-major. Allocates nothing.