@driftengine/core 4.9.0 → 4.11.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/globalMediumPass.d.ts

@@ -11,6 +11,8 @@ export interface MediumLight {
     readonly sunShadow: number;
     /** World → light clip, **uncorrected**: the shader does its own `* 0.5 + 0.5`. */
     readonly lightViewProj: ReadonlyMat4;
+    /** The same for the sun's moving layer, whose shadow pass may be drawn with its own. */
+    readonly movingLightViewProj: ReadonlyMat4;
     /** The sun's static, moving and peeled maps, as one array. See `shadowMap.ts`. */
     readonly sunShadows: WebGLTexture;
     readonly peeledEnabled: boolean;

package/dist/render/globalMediumPass.js

@@ -173,6 +173,7 @@ export class GlobalMediumPass {
         gl.uniform1i(u['uSteps'] ?? null, steps);
         gl.uniform1f(u['uSunShadow'] ?? null, light.sunShadow);
         gl.uniformMatrix4fv(u['uLightViewProj'] ?? null, false, light.lightViewProj);
+        gl.uniformMatrix4fv(u['uMovingLightViewProj'] ?? null, false, light.movingLightViewProj);
         gl.uniform1i(u['uPeeledShadowEnabled'] ?? null, light.peeledEnabled ? 1 : 0);
         gl.drawArrays(gl.TRIANGLES, 0, 3);
         gl.bindVertexArray(null);

package/dist/render/indexWidth.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A mesh's indices in the narrowest type that holds them: sixteen bits where every vertex can be
+ * named in sixteen, thirty-two otherwise — half the index memory for every mesh of 65,536 vertices
+ * or fewer, which is most of them. Lossless because `validateMeshData` has already refused an
+ * index past the last vertex.
+ *
+ * **Padded to an even count**, so the sixteen-bit copy is a whole number of four-byte words: WebGPU
+ * writes a buffer only in whole words. The extra index is never drawn, since every draw counts the
+ * mesh's own indices. What would make this wrong is a draw that counts the buffer instead.
+ *
+ * **What it costs** is a copy of the indices while the mesh is built, let go once they are on the
+ * device; and every draw of the mesh has to say which width it holds, which is why the width
+ * travels with the mesh rather than being worked out where it is drawn.
+ */
+/** The most vertices sixteen-bit indices can name: every index below 65,536. */
+export declare const MAX_UINT16_VERTICES = 65536;
+export declare function compactIndices(indices: Uint32Array, vertexCount: number): Uint16Array | Uint32Array;

package/dist/render/indexWidth.js

@@ -0,0 +1,23 @@
+/**
+ * A mesh's indices in the narrowest type that holds them: sixteen bits where every vertex can be
+ * named in sixteen, thirty-two otherwise — half the index memory for every mesh of 65,536 vertices
+ * or fewer, which is most of them. Lossless because `validateMeshData` has already refused an
+ * index past the last vertex.
+ *
+ * **Padded to an even count**, so the sixteen-bit copy is a whole number of four-byte words: WebGPU
+ * writes a buffer only in whole words. The extra index is never drawn, since every draw counts the
+ * mesh's own indices. What would make this wrong is a draw that counts the buffer instead.
+ *
+ * **What it costs** is a copy of the indices while the mesh is built, let go once they are on the
+ * device; and every draw of the mesh has to say which width it holds, which is why the width
+ * travels with the mesh rather than being worked out where it is drawn.
+ */
+/** The most vertices sixteen-bit indices can name: every index below 65,536. */
+export const MAX_UINT16_VERTICES = 65536;
+export function compactIndices(indices, vertexCount) {
+    if (vertexCount > MAX_UINT16_VERTICES)
+        return indices;
+    const out = new Uint16Array(indices.length + (indices.length % 2));
+    out.set(indices);
+    return out;
+}