@driftengine/core 4.9.0 → 4.10.0

package/src/render/boneAnimation.ts

@@ -0,0 +1,223 @@
+/**
+ * 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 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: BoneAnimationClip): BoneAnimationTexels {
+  const { bones, frames, framesPerSecond } = clip;
+  for (const [name, value] of [
+    ['bones', bones],
+    ['frames', frames],
+  ] as const) {
+    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] as number;
+    places[i * 4 + 1] = clip.places[i * 3 + 1] as number;
+    places[i * 4 + 2] = clip.places[i * 3 + 2] as number;
+    places[i * 4 + 3] = 1;
+    const x = clip.turns[i * 4] as number;
+    const y = clip.turns[i * 4 + 1] as number;
+    const z = clip.turns[i * 4 + 2] as number;
+    const w = clip.turns[i * 4 + 3] as number;
+    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: MeshInstances, out: Float32Array): void {
+  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] as number | undefined) ?? 0);
+    out[i * 2 + 1] = clocks === undefined ? 1 : ((clocks[i * 2 + 1] as number | undefined) ?? 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: number,
+  frames: number,
+  out: { first: number; second: number; blend: number },
+): void {
+  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: ArrayLike<number>, at: number, v: ArrayLike<number>, out: Float32Array): void {
+  const qx = q[at] as number;
+  const qy = q[at + 1] as number;
+  const qz = q[at + 2] as number;
+  const qw = q[at + 3] as number;
+  const vx = v[0] as number;
+  const vy = v[1] as number;
+  const vz = v[2] as number;
+  /* 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: BoneAnimationTexels,
+  bone: number,
+  position: ArrayLike<number>,
+  time: number,
+  phase: number,
+  rate: number,
+  out: Float32Array,
+): void {
+  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] as number) * (q[c] as number) +
+      (q[a + 1] as number) * (q[c + 1] as number) +
+      (q[a + 2] as number) * (q[c + 2] as number) +
+      (q[a + 3] as number) * (q[c + 3] as number) <
+    0
+      ? -1
+      : 1;
+  for (let k = 0; k < 4; k++) {
+    mixed[k] = (q[a + k] as number) * (1 - blend) + sign * (q[c + k] as number) * blend;
+  }
+  const length = Math.hypot(
+    mixed[0] as number,
+    mixed[1] as number,
+    mixed[2] as number,
+    mixed[3] as number,
+  );
+  for (let k = 0; k < 4; k++) mixed[k] = (mixed[k] as number) / length;
+  turn(mixed, 0, position, out);
+  const p = clip.places;
+  for (let k = 0; k < 3; k++) {
+    out[k] = (out[k] as number) + (p[a + k] as number) * (1 - blend) + (p[c + k] as number) * blend;
+  }
+}
+
+/** The bone a vertex follows, from its second coordinates' u: what the shader rounds. */
+export function boneOf(u: number, boneScale: number): number {
+  return Math.floor(u * boneScale + 0.5);
+}

package/src/render/compressedSource.ts

@@ -2,25 +2,106 @@
  * 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;
+}
+
+const shape = (width: number, height: number, bytes: number): BlockShape => ({
+  width,
+  height,
+  bytes,
+});
+
+/** Every format's block. ASTC's are sixteen bytes whatever their size, which is its whole idea. */
+export const BLOCK_SHAPES: Readonly<Record<BlockFormat, BlockShape>> = {
+  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: BlockFormat): 'bc' | 'etc2' | 'astc' {
+  if (format.startsWith('bc')) return 'bc';
+  if (format.startsWith('astc')) return 'astc';
+  return 'etc2';
+}
 
 /** Block-compressed texels with their stored mip chain, level 0 first. */
 export interface CompressedTextureSource {
@@ -52,15 +133,10 @@ export function compressedLayers(
   return sources as readonly CompressedTextureSource[];
 }
 
-/** Bytes per 4x4 block. */
-export const BLOCK_BYTES: Readonly<Record<BlockFormat, number>> = {
-  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: Readonly<Record<BlockFormat, number>> = Object.fromEntries(
+  Object.entries(BLOCK_SHAPES).map(([format, block]) => [format, block.bytes]),
+) as Record<BlockFormat, number>;
 
 /** Whether `source` is a compressed source rather than an image. */
 export function isCompressedSource(source: unknown): source is CompressedTextureSource {
@@ -79,13 +155,15 @@ export function compressedFormatName(
   srgb: boolean,
 ): CompressedTextureFormat | null {
   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(
@@ -96,14 +174,26 @@ export function uploadsCompressed(
   available: readonly CompressedTextureFormat[],
 ): boolean {
   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: BlockFormat, width: number, height: number, level: number): number {
+export function levelBytes(
+  format: BlockFormat,
+  width: number,
+  height: number,
+  level: number,
+): number {
   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;
 }
 
 /**
@@ -162,11 +252,13 @@ export function compressedRefusal(
   available: readonly CompressedTextureFormat[],
 ): string {
   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.'
   );
 }
 

package/src/render/glCompressed.ts

@@ -28,6 +28,42 @@ const INTERNAL: Readonly<Record<CompressedTextureFormat, number>> = {
   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: readonly (readonly [string, readonly CompressedTextureFormat[]])[] = [
@@ -35,6 +71,53 @@ const BY_EXTENSION: readonly (readonly [string, readonly CompressedTextureFormat
   ['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',
+    ],
+  ],
 ];
 
 /**

package/src/render/instances.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;
@@ -140,6 +148,8 @@ export function packInstances(instances: MeshInstances, out: Float32Array): void
   }
 }
 
+import type { BoneAnimationHandle } from './boneAnimation.ts';
+
 /** How a batch made by `createInstanced` behaves. */
 export interface InstancedOptions {
   /**
@@ -154,4 +164,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/src/render/lightBudget.ts

@@ -276,6 +276,17 @@ 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/src/render/lightmap.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/src/render/mesh.ts

@@ -149,6 +149,11 @@ export 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;
 
@@ -319,6 +324,7 @@ export class Mesh {
       this.attachAttribute(gl, ATTR_TANGENT, data.tangents, 4);
     }
 
+    this.hasGrain = data.grain !== undefined;
     if (data.grain === undefined) {
       gl.disableVertexAttribArray(ATTR_GRAIN);
       this.constants.push({ location: ATTR_GRAIN, value: ABSENT_ATTRIBUTE['grain'] });

package/src/render/pointLightSelection.ts

@@ -204,10 +204,10 @@ export interface PointLightSource {
   inLightField?: boolean;
   /**
    * How the light fades with distance when it names its own way: `(1 - (d/R)^2)^n` with no distance
-   * term, `R` its radius and `n` this. Unreal's falloff for a light without inverse-square falloff,
-   * so a rig authored there — a fill of brightness 160 across 164 m, a key at exponent 8 — lights
-   * the space it was authored for rather than one that ends a few metres out. Absent or 0, the
-   * frame's own falloff (`pointLightFalloff`), which is every light before 4.8.7.
+   * term, `R` its radius and `n` this. The usual falloff for a light without inverse-square
+   * falloff, so a rig authored that way — a fill of brightness 160 across 164 m, a key at exponent
+   * 8 — lights the space it was authored for rather than one that ends a few metres out. Absent or
+   * 0, the frame's own falloff (`pointLightFalloff`), which is every light before 4.8.7.
    */
   falloffExponent?: number;
 }

package/src/render/screenSpaceReflection.ts

@@ -370,7 +370,8 @@ export interface ReflectiveSurfaceOptions extends DecalBox {
    * box. Each pixel then returns `F0 · A + B` of what its ray finds, the split-sum environment BRDF
    * at its own view and `roughness` — Karis's fit, the one the lit stage reflects its environment
    * by — so a floor returns more toward the horizon than underfoot, and the share follows the
-   * camera as Unreal weighs its reflections. **False by default**, the one share as before.
+   * camera as a physically based renderer weighs its reflections. **False by default**, the one
+   * share as before.
    *
    * **What it gives up**: the pass has no material buffer, so the roughness and F0 are the box's,
    * not each pixel's, and nothing occludes the reflection where the lit stage's ambient occlusion