@driftengine/core 4.9.0 → 4.10.0

package/dist/render/boneAnimation.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Vertex animation from bone textures: a clip that turns and places each bone frame by frame,
+ * which every vertex of an instanced batch's mesh follows — one bone a vertex, named by the mesh's
+ * second coordinates — at a moment each instance keeps its own clock for.
+ *
+ * **What a crowd is built from.** A rigged character skinned per draw costs a palette upload and a
+ * draw each; a crowd of them, played back from a clip a mesh, costs nothing on the processor once
+ * the clip is on the device, and every instance moves at the frame's rate on its own clock rather
+ * than in step with the others. What it gives up against skinning is the blend: a vertex follows
+ * exactly one bone, so a joint bends hard, which at a crowd's distance is what such clips are made
+ * for.
+ *
+ * **The vertex's bone is its second coordinates' u times `boneScale`**, rounded: a mesh's second
+ * coordinates (`MeshData.lightmapUvs`) are free on a crowd, which bakes no lightmap, and the format
+ * that writes one bone a sixty-fourth of u is the format this reads with `boneScale: 64`.
+ *
+ * **A frame's turn and place move the vertex as the bone does**: the turn about the mesh's origin,
+ * then the place added — `turn(q, p) + t` — and its normal and tangent turned with it. Between two
+ * frames both are blended: the places linearly, the turns normalised along the shorter arc. The
+ * moment is `(sceneTime × rate + phase) × framesPerSecond`, looping, where the scene's time is the
+ * clock `setAnimationTime` sets, once a frame before the shadows, and each instance's phase and
+ * rate are `MeshInstances.clocks`.
+ *
+ * Backend-neutral: both backends upload what `packBoneAnimation` packs and run
+ * `shaders/boneAnimation.ts`, which is `animateBoneVertex` below, line for line.
+ */
+import type { MeshInstances } from './instances.ts';
+/** A clip on the device, from `createBoneAnimation`. Opaque but for its size. */
+export interface BoneAnimationHandle {
+    readonly bones: number;
+    readonly frames: number;
+}
+/** A clip, as a caller hands it to `createBoneAnimation`. */
+export interface BoneAnimationClip {
+    /** Bones each frame holds. */
+    readonly bones: number;
+    /** Frames, played in order and looped. */
+    readonly frames: number;
+    readonly framesPerSecond: number;
+    /** Where each bone puts what it carries: three floats a bone, bone by bone, frame by frame. */
+    readonly places: Float32Array;
+    /** Each bone's turn: a unit quaternion, x y z w, laid out as `places` is. */
+    readonly turns: Float32Array;
+    /** How many bones one unit of the second coordinates' u counts: `bones` unless given. */
+    readonly boneScale?: number;
+}
+/** A clip as textures hold it: a texel a bone a frame, bones across and frames down. */
+export interface BoneAnimationTexels {
+    readonly bones: number;
+    readonly frames: number;
+    readonly framesPerSecond: number;
+    readonly boneScale: number;
+    /** RGBA floats: the place, and 1. */
+    readonly places: Float32Array;
+    /** RGBA floats: the turn, normalised. */
+    readonly turns: Float32Array;
+}
+/**
+ * The most bones or frames a clip may have: WebGL2's guaranteed texture size. A clip past it is
+ * refused rather than cut, since a cut clip is a crowd frozen at its last row.
+ */
+export declare const MAX_BONE_TEXTURE_SIZE = 2048;
+/** A clip checked and packed into its two textures' texels. Runs once, when the clip is made. */
+export declare function packBoneAnimation(clip: BoneAnimationClip): BoneAnimationTexels;
+/** How wide a batch's clock texture is: one row up to this many instances, then more rows. */
+export declare const CLOCK_TEXTURE_WIDTH = 1024;
+/**
+ * Each instance's clock into `out`, two floats an instance — its phase in seconds and its rate —
+ * from `data.clocks`, and `(0, 1)` where it gives none: every instance at the clip's own speed,
+ * in step. `out` is the batch's, sized once.
+ */
+export declare function packInstanceClocks(data: MeshInstances, out: Float32Array): void;
+/**
+ * Which two frames a moment falls between, and how far: what the shader reads. Looped, with a
+ * moment before the clip's start counted back from its end. **The first frame is clamped to the
+ * last**, with the blend left at whatever reaches the next: a moment a hair short of the loop that
+ * float error rounds up to `frames` lands on the last frame blended fully into the first, which is
+ * the first frame — the right answer — where an index of `frames` would read past the texture.
+ */
+export declare function boneFrame(moment: number, frames: number, out: {
+    first: number;
+    second: number;
+    blend: number;
+}): void;
+/**
+ * Where the clip puts a vertex at rest at `position`, following `bone`, at the scene's `time` on an
+ * instance clock of `phase` and `rate`, into `out`. The processor's statement of what the shader
+ * does, which the tests hold the arithmetic to and a device check holds the shader to.
+ */
+export declare function animateBoneVertex(clip: BoneAnimationTexels, bone: number, position: ArrayLike<number>, time: number, phase: number, rate: number, out: Float32Array): void;
+/** The bone a vertex follows, from its second coordinates' u: what the shader rounds. */
+export declare function boneOf(u: number, boneScale: number): number;

package/dist/render/boneAnimation.js

@@ -0,0 +1,133 @@
+/**
+ * The most bones or frames a clip may have: WebGL2's guaranteed texture size. A clip past it is
+ * refused rather than cut, since a cut clip is a crowd frozen at its last row.
+ */
+export const MAX_BONE_TEXTURE_SIZE = 2048;
+/** A clip checked and packed into its two textures' texels. Runs once, when the clip is made. */
+export function packBoneAnimation(clip) {
+    const { bones, frames, framesPerSecond } = clip;
+    for (const [name, value] of [
+        ['bones', bones],
+        ['frames', frames],
+    ]) {
+        if (!Number.isInteger(value) || value < 1 || value > MAX_BONE_TEXTURE_SIZE) {
+            throw new Error(`createBoneAnimation: ${name} is ${value}; a whole number from 1 to ${MAX_BONE_TEXTURE_SIZE}`);
+        }
+    }
+    if (!(framesPerSecond > 0)) {
+        throw new Error(`createBoneAnimation: framesPerSecond is ${framesPerSecond}; above zero`);
+    }
+    const count = bones * frames;
+    if (clip.places.length !== count * 3 || clip.turns.length !== count * 4) {
+        throw new Error(`createBoneAnimation: ${bones} bones over ${frames} frames is ${count * 3} places and ` +
+            `${count * 4} turn numbers, and was given ${clip.places.length} and ${clip.turns.length}`);
+    }
+    const boneScale = clip.boneScale ?? bones;
+    if (!(boneScale > 0)) {
+        throw new Error(`createBoneAnimation: boneScale is ${boneScale}; above zero`);
+    }
+    const places = new Float32Array(count * 4);
+    const turns = new Float32Array(count * 4);
+    for (let i = 0; i < count; i++) {
+        places[i * 4] = clip.places[i * 3];
+        places[i * 4 + 1] = clip.places[i * 3 + 1];
+        places[i * 4 + 2] = clip.places[i * 3 + 2];
+        places[i * 4 + 3] = 1;
+        const x = clip.turns[i * 4];
+        const y = clip.turns[i * 4 + 1];
+        const z = clip.turns[i * 4 + 2];
+        const w = clip.turns[i * 4 + 3];
+        const length = Math.hypot(x, y, z, w);
+        /* A zero turn is no turn, rather than a NaN through every vertex that reads it. */
+        const scale = length > 0 ? 1 / length : 0;
+        turns[i * 4] = x * scale;
+        turns[i * 4 + 1] = y * scale;
+        turns[i * 4 + 2] = z * scale;
+        turns[i * 4 + 3] = length > 0 ? w * scale : 1;
+    }
+    return { bones, frames, framesPerSecond, boneScale, places, turns };
+}
+/** How wide a batch's clock texture is: one row up to this many instances, then more rows. */
+export const CLOCK_TEXTURE_WIDTH = 1024;
+/**
+ * Each instance's clock into `out`, two floats an instance — its phase in seconds and its rate —
+ * from `data.clocks`, and `(0, 1)` where it gives none: every instance at the clip's own speed,
+ * in step. `out` is the batch's, sized once.
+ */
+export function packInstanceClocks(data, out) {
+    const clocks = data.clocks;
+    const count = Math.min(data.count, out.length / 2);
+    for (let i = 0; i < count; i++) {
+        out[i * 2] = clocks === undefined ? 0 : (clocks[i * 2] ?? 0);
+        out[i * 2 + 1] = clocks === undefined ? 1 : (clocks[i * 2 + 1] ?? 1);
+    }
+}
+/**
+ * Which two frames a moment falls between, and how far: what the shader reads. Looped, with a
+ * moment before the clip's start counted back from its end. **The first frame is clamped to the
+ * last**, with the blend left at whatever reaches the next: a moment a hair short of the loop that
+ * float error rounds up to `frames` lands on the last frame blended fully into the first, which is
+ * the first frame — the right answer — where an index of `frames` would read past the texture.
+ */
+export function boneFrame(moment, frames, out) {
+    const wrapped = moment - frames * Math.floor(moment / frames);
+    const first = Math.min(Math.floor(wrapped), frames - 1);
+    out.first = first;
+    out.second = first + 1 === frames ? 0 : first + 1;
+    out.blend = Math.min(Math.max(wrapped - first, 0), 1);
+}
+const scratchFrame = { first: 0, second: 0, blend: 0 };
+const mixed = new Float32Array(4);
+/** `v` turned by the unit quaternion `q`, into `out`. */
+function turn(q, at, v, out) {
+    const qx = q[at];
+    const qy = q[at + 1];
+    const qz = q[at + 2];
+    const qw = q[at + 3];
+    const vx = v[0];
+    const vy = v[1];
+    const vz = v[2];
+    /* v + 2 q.xyz × (q.xyz × v + q.w v), as the shader writes it. */
+    const cx = qy * vz - qz * vy + qw * vx;
+    const cy = qz * vx - qx * vz + qw * vy;
+    const cz = qx * vy - qy * vx + qw * vz;
+    out[0] = vx + 2 * (qy * cz - qz * cy);
+    out[1] = vy + 2 * (qz * cx - qx * cz);
+    out[2] = vz + 2 * (qx * cy - qy * cx);
+}
+/**
+ * Where the clip puts a vertex at rest at `position`, following `bone`, at the scene's `time` on an
+ * instance clock of `phase` and `rate`, into `out`. The processor's statement of what the shader
+ * does, which the tests hold the arithmetic to and a device check holds the shader to.
+ */
+export function animateBoneVertex(clip, bone, position, time, phase, rate, out) {
+    boneFrame((time * rate + phase) * clip.framesPerSecond, clip.frames, scratchFrame);
+    const { first, second, blend } = scratchFrame;
+    const b = Math.min(Math.max(bone, 0), clip.bones - 1);
+    const a = (first * clip.bones + b) * 4;
+    const c = (second * clip.bones + b) * 4;
+    const q = clip.turns;
+    /* The shorter arc: a quaternion and its negation are one turn. */
+    const sign = q[a] * q[c] +
+        q[a + 1] * q[c + 1] +
+        q[a + 2] * q[c + 2] +
+        q[a + 3] * q[c + 3] <
+        0
+        ? -1
+        : 1;
+    for (let k = 0; k < 4; k++) {
+        mixed[k] = q[a + k] * (1 - blend) + sign * q[c + k] * blend;
+    }
+    const length = Math.hypot(mixed[0], mixed[1], mixed[2], mixed[3]);
+    for (let k = 0; k < 4; k++)
+        mixed[k] = mixed[k] / length;
+    turn(mixed, 0, position, out);
+    const p = clip.places;
+    for (let k = 0; k < 3; k++) {
+        out[k] = out[k] + p[a + k] * (1 - blend) + p[c + k] * blend;
+    }
+}
+/** The bone a vertex follows, from its second coordinates' u: what the shader rounds. */
+export function boneOf(u, boneScale) {
+    return Math.floor(u * boneScale + 0.5);
+}

package/dist/render/compressedSource.d.ts

@@ -2,22 +2,39 @@
  * A block-compressed image a caller hands to `createSurfaceTexture`, and the one decision about it
  * both backends share: whether this device takes it as blocks.
  *
- * **Uploaded as it is, or not at all.** A BC texture costs a byte a texel on the GPU (BC7) or half
- * of one (BC1) against four for RGBA, and keeps the mip chain its author built rather than one a box
- * filter makes. A device that cannot sample the format — most phones, which have ASTC and ETC2 —
- * gets nothing from the blocks, and the engine does not decode them here: core ships no decoder.
- * The loader in `@driftengine/assets` asks `uploadsCompressed` first and decodes at load where the
- * answer is no; a caller handing a source this device cannot take is refused by name.
+ * **Uploaded as it is, or not at all.** A block format costs a byte a texel on the GPU (BC7, ETC2
+ * with alpha, ASTC 4x4) or half of one (BC1, ETC2 without) against four for RGBA, and keeps the mip
+ * chain its author built rather than one a box filter makes. **Three families, and a device has the
+ * ones it has**: desktops sample BC, phones ETC2 and ASTC, and few anything else. A device that
+ * cannot sample a format gets nothing from its blocks, and core does not convert them: the loader
+ * in `@driftengine/assets` asks `uploadsCompressed` first, and where the answer is no it decodes
+ * them — and encodes ETC2 where the device takes that — off the main thread. A caller handing a
+ * source this device cannot take is refused by name.
  *
  * Backend-neutral, because both backends must agree on what they accept before either touches a
- * device. `BlockFormat` is the same union `@driftengine/drft` names `BcFormat`; core imports nothing
+ * device. `@driftengine/drft`'s `BcFormat` is the BC part of `BlockFormat`; core imports nothing
  * from that package, and a format added there without a twin here fails where the loader passes one
  * to the other, at compile time.
  */
-/** BC1 to BC5 and BC7. BC6H and the signed forms are not among them. */
-export type BlockFormat = 'bc1' | 'bc2' | 'bc3' | 'bc4' | 'bc5' | 'bc7';
+/**
+ * BC1 to BC5 and BC7; ETC2's three and EAC's two; and ASTC at every block size the LDR profile has.
+ * BC6H, ASTC HDR and the signed forms are not among them.
+ */
+export type BlockFormat = 'bc1' | 'bc2' | 'bc3' | 'bc4' | 'bc5' | 'bc7' | 'etc2-rgb8' | 'etc2-rgb8a1' | 'etc2-rgba8' | 'eac-r11' | 'eac-rg11' | 'astc-4x4' | 'astc-5x4' | 'astc-5x5' | 'astc-6x5' | 'astc-6x6' | 'astc-8x5' | 'astc-8x6' | 'astc-8x8' | 'astc-10x5' | 'astc-10x6' | 'astc-10x8' | 'astc-10x10' | 'astc-12x10' | 'astc-12x12';
+/** The formats with no sRGB form: one or two channels of data, never colour. */
+type LinearOnly = 'bc4' | 'bc5' | 'eac-r11' | 'eac-rg11';
 /** A format as a device offers it: the colour space is part of the name, as WebGPU's are. */
-export type CompressedTextureFormat = 'bc1' | 'bc1-srgb' | 'bc2' | 'bc2-srgb' | 'bc3' | 'bc3-srgb' | 'bc4' | 'bc5' | 'bc7' | 'bc7-srgb';
+export type CompressedTextureFormat = BlockFormat | `${Exclude<BlockFormat, LinearOnly>}-srgb`;
+/** A format's block: how many texels across and down, and how many bytes it takes. */
+export interface BlockShape {
+    readonly width: number;
+    readonly height: number;
+    readonly bytes: number;
+}
+/** Every format's block. ASTC's are sixteen bytes whatever their size, which is its whole idea. */
+export declare const BLOCK_SHAPES: Readonly<Record<BlockFormat, BlockShape>>;
+/** Every format's family, which is what a device offers or does not. */
+export declare function blockFamily(format: BlockFormat): 'bc' | 'etc2' | 'astc';
 /** Block-compressed texels with their stored mip chain, level 0 first. */
 export interface CompressedTextureSource {
     readonly format: BlockFormat;
@@ -32,7 +49,7 @@ export type SurfaceSource = TexImageSource | CompressedTextureSource;
  * one GPU texture has one format.
  */
 export declare function compressedLayers(sources: readonly SurfaceSource[]): readonly CompressedTextureSource[] | null;
-/** Bytes per 4x4 block. */
+/** Bytes per block. See `BLOCK_SHAPES` for the block's size, which is not always 4x4. */
 export declare const BLOCK_BYTES: Readonly<Record<BlockFormat, number>>;
 /** Whether `source` is a compressed source rather than an image. */
 export declare function isCompressedSource(source: unknown): source is CompressedTextureSource;
@@ -40,11 +57,13 @@ export declare function isCompressedSource(source: unknown): source is Compresse
 export declare function compressedFormatName(format: BlockFormat, srgb: boolean): CompressedTextureFormat | null;
 /**
  * Whether a `width` by `height` source in `format` uploads as blocks on a device offering
- * `available`. Level 0 must be whole blocks each way: WebGPU refuses any other size for a BC
- * texture, and WebGL2's S3TC extension says the same, so a 6x6 image is decoded rather than
+ * `available`. Level 0 must be whole blocks each way: WebGPU refuses any other size for a block
+ * texture, and WebGL2's extensions say the same, so a 6x6 image in 4x4 blocks is decoded rather than
  * refused. What would make that wrong is a device that pads; none is relied on here.
  */
 export declare function uploadsCompressed(format: BlockFormat, srgb: boolean, width: number, height: number, available: readonly CompressedTextureFormat[]): boolean;
+/** The bytes level `level` of a `width` by `height` image takes: whole blocks, one at least. */
+export declare function levelBytes(format: BlockFormat, width: number, height: number, level: number): number;
 /**
  * How many levels the layers carry, after checking each is the size its place requires and every
  * layer matches the first. Refuses by name: a short level uploaded anyway is a device error at
@@ -64,3 +83,4 @@ export declare function planBlocks(blocks: readonly CompressedTextureSource[], s
  * quietly reallocated, so the handle a draw holds keeps meaning what it meant.
  */
 export declare function refuseBlockUpdate(format: BlockFormat | null): void;
+export {};

package/dist/render/compressedSource.js

@@ -2,18 +2,61 @@
  * A block-compressed image a caller hands to `createSurfaceTexture`, and the one decision about it
  * both backends share: whether this device takes it as blocks.
  *
- * **Uploaded as it is, or not at all.** A BC texture costs a byte a texel on the GPU (BC7) or half
- * of one (BC1) against four for RGBA, and keeps the mip chain its author built rather than one a box
- * filter makes. A device that cannot sample the format — most phones, which have ASTC and ETC2 —
- * gets nothing from the blocks, and the engine does not decode them here: core ships no decoder.
- * The loader in `@driftengine/assets` asks `uploadsCompressed` first and decodes at load where the
- * answer is no; a caller handing a source this device cannot take is refused by name.
+ * **Uploaded as it is, or not at all.** A block format costs a byte a texel on the GPU (BC7, ETC2
+ * with alpha, ASTC 4x4) or half of one (BC1, ETC2 without) against four for RGBA, and keeps the mip
+ * chain its author built rather than one a box filter makes. **Three families, and a device has the
+ * ones it has**: desktops sample BC, phones ETC2 and ASTC, and few anything else. A device that
+ * cannot sample a format gets nothing from its blocks, and core does not convert them: the loader
+ * in `@driftengine/assets` asks `uploadsCompressed` first, and where the answer is no it decodes
+ * them — and encodes ETC2 where the device takes that — off the main thread. A caller handing a
+ * source this device cannot take is refused by name.
  *
  * Backend-neutral, because both backends must agree on what they accept before either touches a
- * device. `BlockFormat` is the same union `@driftengine/drft` names `BcFormat`; core imports nothing
+ * device. `@driftengine/drft`'s `BcFormat` is the BC part of `BlockFormat`; core imports nothing
  * from that package, and a format added there without a twin here fails where the loader passes one
  * to the other, at compile time.
  */
+const shape = (width, height, bytes) => ({
+    width,
+    height,
+    bytes,
+});
+/** Every format's block. ASTC's are sixteen bytes whatever their size, which is its whole idea. */
+export const BLOCK_SHAPES = {
+    bc1: shape(4, 4, 8),
+    bc2: shape(4, 4, 16),
+    bc3: shape(4, 4, 16),
+    bc4: shape(4, 4, 8),
+    bc5: shape(4, 4, 16),
+    bc7: shape(4, 4, 16),
+    'etc2-rgb8': shape(4, 4, 8),
+    'etc2-rgb8a1': shape(4, 4, 8),
+    'etc2-rgba8': shape(4, 4, 16),
+    'eac-r11': shape(4, 4, 8),
+    'eac-rg11': shape(4, 4, 16),
+    'astc-4x4': shape(4, 4, 16),
+    'astc-5x4': shape(5, 4, 16),
+    'astc-5x5': shape(5, 5, 16),
+    'astc-6x5': shape(6, 5, 16),
+    'astc-6x6': shape(6, 6, 16),
+    'astc-8x5': shape(8, 5, 16),
+    'astc-8x6': shape(8, 6, 16),
+    'astc-8x8': shape(8, 8, 16),
+    'astc-10x5': shape(10, 5, 16),
+    'astc-10x6': shape(10, 6, 16),
+    'astc-10x8': shape(10, 8, 16),
+    'astc-10x10': shape(10, 10, 16),
+    'astc-12x10': shape(12, 10, 16),
+    'astc-12x12': shape(12, 12, 16),
+};
+/** Every format's family, which is what a device offers or does not. */
+export function blockFamily(format) {
+    if (format.startsWith('bc'))
+        return 'bc';
+    if (format.startsWith('astc'))
+        return 'astc';
+    return 'etc2';
+}
 /**
  * The layers as blocks, or null where every one is an image. An array mixing the two is refused:
  * one GPU texture has one format.
@@ -31,15 +74,8 @@ export function compressedLayers(sources) {
     }
     return sources;
 }
-/** Bytes per 4x4 block. */
-export const BLOCK_BYTES = {
-    bc1: 8,
-    bc2: 16,
-    bc3: 16,
-    bc4: 8,
-    bc5: 16,
-    bc7: 16,
-};
+/** Bytes per block. See `BLOCK_SHAPES` for the block's size, which is not always 4x4. */
+export const BLOCK_BYTES = Object.fromEntries(Object.entries(BLOCK_SHAPES).map(([format, block]) => [format, block.bytes]));
 /** Whether `source` is a compressed source rather than an image. */
 export function isCompressedSource(source) {
     const candidate = source;
@@ -52,23 +88,30 @@ export function isCompressedSource(source) {
 export function compressedFormatName(format, srgb) {
     if (!srgb)
         return format;
-    return format === 'bc4' || format === 'bc5' ? null : `${format}-srgb`;
+    return format === 'bc4' || format === 'bc5' || format === 'eac-r11' || format === 'eac-rg11'
+        ? null
+        : `${format}-srgb`;
 }
 /**
  * Whether a `width` by `height` source in `format` uploads as blocks on a device offering
- * `available`. Level 0 must be whole blocks each way: WebGPU refuses any other size for a BC
- * texture, and WebGL2's S3TC extension says the same, so a 6x6 image is decoded rather than
+ * `available`. Level 0 must be whole blocks each way: WebGPU refuses any other size for a block
+ * texture, and WebGL2's extensions say the same, so a 6x6 image in 4x4 blocks is decoded rather than
  * refused. What would make that wrong is a device that pads; none is relied on here.
  */
 export function uploadsCompressed(format, srgb, width, height, available) {
     const name = compressedFormatName(format, srgb);
-    return name !== null && width % 4 === 0 && height % 4 === 0 && available.includes(name);
+    const block = BLOCK_SHAPES[format];
+    return (name !== null &&
+        width % block.width === 0 &&
+        height % block.height === 0 &&
+        available.includes(name));
 }
 /** The bytes level `level` of a `width` by `height` image takes: whole blocks, one at least. */
-function levelBytes(format, width, height, level) {
+export function levelBytes(format, width, height, level) {
     const w = Math.max(1, width >> level);
     const h = Math.max(1, height >> level);
-    return Math.ceil(w / 4) * Math.ceil(h / 4) * BLOCK_BYTES[format];
+    const block = BLOCK_SHAPES[format];
+    return Math.ceil(w / block.width) * Math.ceil(h / block.height) * block.bytes;
 }
 /**
  * How many levels the layers carry, after checking each is the size its place requires and every
@@ -111,10 +154,12 @@ export function compressedLevels(layers) {
 /** What a refusal names: the format, its colour space, and what the device offers instead. */
 export function compressedRefusal(format, srgb, width, height, available) {
     const asked = `${format.toUpperCase()}${srgb ? ' sRGB' : ''} at ${width}x${height}`;
-    const offered = available.length === 0 ? 'no BC format' : available.join(', ');
+    const offered = available.length === 0 ? 'no block format' : available.join(', ');
+    const block = BLOCK_SHAPES[format];
     return (`createSurfaceTexture: this device cannot take ${asked} as blocks — it offers ${offered}, and ` +
-        'a BC texture must be whole 4x4 blocks at level 0. Decode it first (decodeBc in ' +
-        '@driftengine/assets), or ask renderer.compressedFormats before choosing.');
+        `the texture must be whole ${block.width}x${block.height} blocks at level 0. Decode it first ` +
+        '(decodeBc, or encodeEtc2 for a device that takes ETC2, in @driftengine/assets), or ask ' +
+        'renderer.compressedFormats before choosing.');
 }
 /** The format name and level count blocks upload as here, or a refusal naming why they cannot. */
 export function planBlocks(blocks, srgb, compressed) {

package/dist/render/glCompressed.js

@@ -10,12 +10,95 @@ const INTERNAL = {
     bc5: 0x8dbd, // COMPRESSED_RED_GREEN_RGTC2_EXT
     bc7: 0x8e8c, // COMPRESSED_RGBA_BPTC_UNORM_EXT
     'bc7-srgb': 0x8e8d, // COMPRESSED_SRGB_ALPHA_BPTC_UNORM_EXT
+    'eac-r11': 0x9270, // COMPRESSED_R11_EAC
+    'eac-rg11': 0x9272, // COMPRESSED_RG11_EAC
+    'etc2-rgb8': 0x9274, // COMPRESSED_RGB8_ETC2
+    'etc2-rgb8-srgb': 0x9275, // COMPRESSED_SRGB8_ETC2
+    'etc2-rgb8a1': 0x9276, // COMPRESSED_RGB8_PUNCHTHROUGH_ALPHA1_ETC2
+    'etc2-rgb8a1-srgb': 0x9277, // COMPRESSED_SRGB8_PUNCHTHROUGH_ALPHA1_ETC2
+    'etc2-rgba8': 0x9278, // COMPRESSED_RGBA8_ETC2_EAC
+    'etc2-rgba8-srgb': 0x9279, // COMPRESSED_SRGB8_ALPHA8_ETC2_EAC
+    'astc-4x4': 0x93b0, // COMPRESSED_RGBA_ASTC_4x4_KHR
+    'astc-4x4-srgb': 0x93d0, // COMPRESSED_SRGB8_ALPHA8_ASTC_4x4_KHR
+    'astc-5x4': 0x93b1, // COMPRESSED_RGBA_ASTC_5x4_KHR
+    'astc-5x4-srgb': 0x93d1, // COMPRESSED_SRGB8_ALPHA8_ASTC_5x4_KHR
+    'astc-5x5': 0x93b2, // COMPRESSED_RGBA_ASTC_5x5_KHR
+    'astc-5x5-srgb': 0x93d2, // COMPRESSED_SRGB8_ALPHA8_ASTC_5x5_KHR
+    'astc-6x5': 0x93b3, // COMPRESSED_RGBA_ASTC_6x5_KHR
+    'astc-6x5-srgb': 0x93d3, // COMPRESSED_SRGB8_ALPHA8_ASTC_6x5_KHR
+    'astc-6x6': 0x93b4, // COMPRESSED_RGBA_ASTC_6x6_KHR
+    'astc-6x6-srgb': 0x93d4, // COMPRESSED_SRGB8_ALPHA8_ASTC_6x6_KHR
+    'astc-8x5': 0x93b5, // COMPRESSED_RGBA_ASTC_8x5_KHR
+    'astc-8x5-srgb': 0x93d5, // COMPRESSED_SRGB8_ALPHA8_ASTC_8x5_KHR
+    'astc-8x6': 0x93b6, // COMPRESSED_RGBA_ASTC_8x6_KHR
+    'astc-8x6-srgb': 0x93d6, // COMPRESSED_SRGB8_ALPHA8_ASTC_8x6_KHR
+    'astc-8x8': 0x93b7, // COMPRESSED_RGBA_ASTC_8x8_KHR
+    'astc-8x8-srgb': 0x93d7, // COMPRESSED_SRGB8_ALPHA8_ASTC_8x8_KHR
+    'astc-10x5': 0x93b8, // COMPRESSED_RGBA_ASTC_10x5_KHR
+    'astc-10x5-srgb': 0x93d8, // COMPRESSED_SRGB8_ALPHA8_ASTC_10x5_KHR
+    'astc-10x6': 0x93b9, // COMPRESSED_RGBA_ASTC_10x6_KHR
+    'astc-10x6-srgb': 0x93d9, // COMPRESSED_SRGB8_ALPHA8_ASTC_10x6_KHR
+    'astc-10x8': 0x93ba, // COMPRESSED_RGBA_ASTC_10x8_KHR
+    'astc-10x8-srgb': 0x93da, // COMPRESSED_SRGB8_ALPHA8_ASTC_10x8_KHR
+    'astc-10x10': 0x93bb, // COMPRESSED_RGBA_ASTC_10x10_KHR
+    'astc-10x10-srgb': 0x93db, // COMPRESSED_SRGB8_ALPHA8_ASTC_10x10_KHR
+    'astc-12x10': 0x93bc, // COMPRESSED_RGBA_ASTC_12x10_KHR
+    'astc-12x10-srgb': 0x93dc, // COMPRESSED_SRGB8_ALPHA8_ASTC_12x10_KHR
+    'astc-12x12': 0x93bd, // COMPRESSED_RGBA_ASTC_12x12_KHR
+    'astc-12x12-srgb': 0x93dd, // COMPRESSED_SRGB8_ALPHA8_ASTC_12x12_KHR
 };
 const BY_EXTENSION = [
     ['WEBGL_compressed_texture_s3tc', ['bc1', 'bc2', 'bc3']],
     ['WEBGL_compressed_texture_s3tc_srgb', ['bc1-srgb', 'bc2-srgb', 'bc3-srgb']],
     ['EXT_texture_compression_rgtc', ['bc4', 'bc5']],
     ['EXT_texture_compression_bptc', ['bc7', 'bc7-srgb']],
+    /* The two families a phone has: every GLES 3 device takes ETC2, and most take ASTC beside it. */
+    [
+        'WEBGL_compressed_texture_etc',
+        [
+            'etc2-rgb8',
+            'etc2-rgb8-srgb',
+            'etc2-rgb8a1',
+            'etc2-rgb8a1-srgb',
+            'etc2-rgba8',
+            'etc2-rgba8-srgb',
+            'eac-r11',
+            'eac-rg11',
+        ],
+    ],
+    [
+        'WEBGL_compressed_texture_astc',
+        [
+            'astc-4x4',
+            'astc-4x4-srgb',
+            'astc-5x4',
+            'astc-5x4-srgb',
+            'astc-5x5',
+            'astc-5x5-srgb',
+            'astc-6x5',
+            'astc-6x5-srgb',
+            'astc-6x6',
+            'astc-6x6-srgb',
+            'astc-8x5',
+            'astc-8x5-srgb',
+            'astc-8x6',
+            'astc-8x6-srgb',
+            'astc-8x8',
+            'astc-8x8-srgb',
+            'astc-10x5',
+            'astc-10x5-srgb',
+            'astc-10x6',
+            'astc-10x6-srgb',
+            'astc-10x8',
+            'astc-10x8-srgb',
+            'astc-10x10',
+            'astc-10x10-srgb',
+            'astc-12x10',
+            'astc-12x10-srgb',
+            'astc-12x12',
+            'astc-12x12-srgb',
+        ],
+    ],
 ];
 /**
  * The BC formats this context samples, enabling each extension that offers some. Enabling is what

package/dist/render/instances.d.ts

@@ -66,6 +66,14 @@ export interface MeshInstances {
      */
     readonly uvRegions?: Float32Array;
     /** How many instances the arrays hold. Fixed at creation; the buffers are sized from it. */
+    /**
+     * Two floats each, the instance's clock for a batch that plays a bone animation
+     * (`InstancedOptions.animation`): its phase in seconds, added to the scene's time once the rate has
+     * scaled it, and its rate, 1 for the clip's own speed. **Absent, or an instance past its end, is
+     * `(0, 1)`** — every instance at the clip's speed and in step. Read by `uploadInstanced`, as the
+     * matrices are; a batch with no animation ignores it.
+     */
+    readonly clocks?: Float32Array;
     readonly capacity: number;
     /** How many are live. The rest of the buffer is neither uploaded nor drawn. */
     count: number;
@@ -103,6 +111,7 @@ export declare const INSTANCE_STRIDE: number;
  * Writes nothing beyond `count`, and allocates nothing: `out` is the caller's staging array.
  */
 export declare function packInstances(instances: MeshInstances, out: Float32Array): void;
+import type { BoneAnimationHandle } from './boneAnimation.ts';
 /** How a batch made by `createInstanced` behaves. */
 export interface InstancedOptions {
     /**
@@ -117,4 +126,21 @@ export interface InstancedOptions {
      * place gains only the whole-batch test, which it could as well do itself.
      */
     readonly cull?: boolean;
+    /**
+     * A bone animation every instance plays (`createBoneAnimation`): each vertex follows the bone its
+     * mesh's second coordinates name, at the instance's own moment of the clip (`MeshInstances.clocks`
+     * and the clock `setAnimationTime` sets), in the colour pass and in every shadow. The mesh must
+     * carry second coordinates. See `boneAnimation.ts`.
+     *
+     * **An animated batch is culled whole, never instance by instance**: its instances read their
+     * clocks by index, which a cull that compacts the survivors would reorder. And its bounds are the
+     * rest pose's, so a clip that carries vertices far from it wants a mesh whose bounds hold them.
+     *
+     * **What it gives up**: under reconstruction or the temporal resolve, a crowd's own movement is not
+     * in the frame's motion — the motion pass places a batch by its matrices, not by its clip — so its
+     * moving parts are reprojected as though still, which softens a fast clip a little; and a glass
+     * batch's coloured shadow is cast from rest. What would make the first wrong is a clip fast enough
+     * at the size it is seen to smear, which is then the motion pass's to learn.
+     */
+    readonly animation?: BoneAnimationHandle;
 }

package/dist/render/lightBudget.d.ts

@@ -243,6 +243,16 @@ export declare const SKIN_BLUR_ALBEDO_UNIT: number;
  */
 export declare const PARTICLE_SPRITE_UNIT: number;
 export declare const PARTICLE_DEPTH_UNIT: number;
+/**
+ * A bone animation's places and turns and its batch's clocks (`shaders/boneAnimation.ts`): vertex
+ * samplers of the animated instanced program, so they count against the vertex stage's sixteen, not
+ * the lit stage's. Numbered past every unit before them rather than sharing the cloth's, which no
+ * animated program declares: a unit two programs both write is a binding one draw can leave for the
+ * other to read. Twenty-six to twenty-eight, inside the combined pool of thirty-two.
+ */
+export declare const BONE_PLACES_TEXTURE_UNIT: number;
+export declare const BONE_TURNS_TEXTURE_UNIT: number;
+export declare const INSTANCE_CLOCKS_TEXTURE_UNIT: number;
 /**
  * A cookie's tile, in texels a side.
  *

package/dist/render/lightBudget.js

@@ -244,6 +244,16 @@ export const SKIN_BLUR_ALBEDO_UNIT = SKIN_BLUR_DEPTH_UNIT + 1;
  */
 export const PARTICLE_SPRITE_UNIT = SKIN_BLUR_ALBEDO_UNIT + 1;
 export const PARTICLE_DEPTH_UNIT = PARTICLE_SPRITE_UNIT + 1;
+/**
+ * A bone animation's places and turns and its batch's clocks (`shaders/boneAnimation.ts`): vertex
+ * samplers of the animated instanced program, so they count against the vertex stage's sixteen, not
+ * the lit stage's. Numbered past every unit before them rather than sharing the cloth's, which no
+ * animated program declares: a unit two programs both write is a binding one draw can leave for the
+ * other to read. Twenty-six to twenty-eight, inside the combined pool of thirty-two.
+ */
+export const BONE_PLACES_TEXTURE_UNIT = PARTICLE_DEPTH_UNIT + 1;
+export const BONE_TURNS_TEXTURE_UNIT = BONE_PLACES_TEXTURE_UNIT + 1;
+export const INSTANCE_CLOCKS_TEXTURE_UNIT = BONE_TURNS_TEXTURE_UNIT + 1;
 /**
  * A cookie's tile, in texels a side.
  *

package/dist/render/lightmap.d.ts

@@ -15,7 +15,7 @@
  *     light = irradiance(uv) * max(0, dot(d.xyz, n) + d.w)
  *     diffuse += albedo * (1 - metal) * light
  *
- * Unreal's high-quality lightmap read, `GetLightMapColorHQ`, once its own vectors have decoded the
+ * A directional lightmap read, once its own vectors have decoded the
  * page — the first-order spherical harmonic its direction carries, in this engine's axes. **Added
  * to what the dynamic lights give**, and to the ambient: a consumer whose bake already holds the
  * sky's light zeroes the ambient for those draws itself, with `setAmbientSH` and nine zeros.

package/dist/render/mesh.d.ts

@@ -63,6 +63,11 @@ export declare class Mesh {
     readonly isSkinnedEight: boolean;
     /** Whether it has texture coordinates, without which a material's maps read one texel. */
     readonly hasUvs: boolean;
+    /**
+     * Whether it carries a grain lane, which is where second coordinates ride (`lightmap.ts`): what
+     * a bone animation reads each vertex's bone from.
+     */
+    readonly hasGrain: boolean;
     /** How many vertices it has, which a cloth binding is checked against. */
     readonly vertexCount: number;
     /**