@driftengine/core 4.8.7 → 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/displayRange.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Which dynamic range the frame goes out in, and why: the one decision behind
+ * `RenderQuality.highDynamicRange`, made here so both backends answer it in the same words.
+ *
+ * **A high range is asked for, found, and held, or it is not had.** Three things must all be true:
+ * the profile asked; the frame has a composite holding light past white (`screenEffects` and
+ * `hdrScene`), since every other pass writes display values already clipped; and the display says
+ * it can show more than paper white. The backend then has to be able to configure such a canvas,
+ * which only it knows, and it may still answer standard after this says high.
+ *
+ * **What a high range gives up** is nothing a standard frame had: paper white stays where it is,
+ * and only what was above it — a lamp, a flash, a sunlit edge — goes on rising to the display's
+ * peak instead of rolling off at white. **What would make it wrong** is a display that reports a
+ * high range it cannot show, which a page cannot detect and the platform owns.
+ */
+export type DisplayRange = 'high' | 'standard';
+export interface DisplayRangeChoice {
+    readonly range: DisplayRange;
+    /** A sentence saying why, for `RendererApi.displayRangeReason`. */
+    readonly reason: string;
+}
+/** The display's own answer, as the browser gives it. A host without a DOM supplies its own. */
+export declare function browserHighDynamicRange(): boolean;
+/** The range a profile gets on a display, before the backend has tried to configure it. */
+export declare function chooseDisplayRange(asked: boolean, composite: boolean, displayIsHigh: boolean): DisplayRangeChoice;
+/**
+ * The display's peak over the frame's paper white, as `setDisplayLuminance` is handed it: at
+ * least 1, and 1 where the range is standard or a number is not one. Capped at 64, a thousand nits
+ * over a sixteen-nit white, which no display reaches and no curve should be asked to.
+ */
+export declare function displayHeadroom(range: DisplayRange, paperWhite: number, peak: number): number;

package/dist/render/displayRange.js

@@ -0,0 +1,47 @@
+/**
+ * Which dynamic range the frame goes out in, and why: the one decision behind
+ * `RenderQuality.highDynamicRange`, made here so both backends answer it in the same words.
+ *
+ * **A high range is asked for, found, and held, or it is not had.** Three things must all be true:
+ * the profile asked; the frame has a composite holding light past white (`screenEffects` and
+ * `hdrScene`), since every other pass writes display values already clipped; and the display says
+ * it can show more than paper white. The backend then has to be able to configure such a canvas,
+ * which only it knows, and it may still answer standard after this says high.
+ *
+ * **What a high range gives up** is nothing a standard frame had: paper white stays where it is,
+ * and only what was above it — a lamp, a flash, a sunlit edge — goes on rising to the display's
+ * peak instead of rolling off at white. **What would make it wrong** is a display that reports a
+ * high range it cannot show, which a page cannot detect and the platform owns.
+ */
+/** The display's own answer, as the browser gives it. A host without a DOM supplies its own. */
+export function browserHighDynamicRange() {
+    // platform: browser default — `CreateRendererOptions.highDynamicRangeDisplay` replaces it
+    return typeof matchMedia === 'function' && matchMedia('(dynamic-range: high)').matches;
+}
+/** The range a profile gets on a display, before the backend has tried to configure it. */
+export function chooseDisplayRange(asked, composite, displayIsHigh) {
+    if (!asked)
+        return { range: 'standard', reason: 'highDynamicRange was not asked for' };
+    if (!composite) {
+        return {
+            range: 'standard',
+            reason: 'highDynamicRange needs screenEffects and hdrScene: without a composite holding light ' +
+                'past white, every pass writes values already clipped to it',
+        };
+    }
+    if (!displayIsHigh) {
+        return { range: 'standard', reason: 'the display reports a standard dynamic range' };
+    }
+    return { range: 'high', reason: 'an extended-range canvas on a high dynamic range display' };
+}
+/**
+ * The display's peak over the frame's paper white, as `setDisplayLuminance` is handed it: at
+ * least 1, and 1 where the range is standard or a number is not one. Capped at 64, a thousand nits
+ * over a sixteen-nit white, which no display reaches and no curve should be asked to.
+ */
+export function displayHeadroom(range, paperWhite, peak) {
+    if (range !== 'high')
+        return 1;
+    const ratio = peak / paperWhite;
+    return Number.isFinite(ratio) ? Math.min(Math.max(ratio, 1), 64) : 1;
+}

package/dist/render/filmicCurve.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The `filmic` output transform: a parametric film curve, its five numbers, and the eight
+ * constants the resolve reads, decided once here for both backends.
+ *
+ * **Why a second filmic curve beside `aces`.** `aces` is the reference RRT and ODT fit, which
+ * holds a mid grey of 0.18 at about 0.11 of display linear: graded for a dark cinema and kept dark.
+ * The curve here holds 0.18 at 0.18 by construction, and is shaped by five numbers a grading
+ * volume carries — a slope through mid grey, a toe and a shoulder, and how far black and white are
+ * clipped past the ends — so a look authored against such a curve is matched by passing its numbers
+ * rather than by baking the difference into a colour lookup table, which has the fewest steps
+ * exactly where two curves differ most: in the shadows.
+ *
+ * **What the curve is.** In the ACEScg working space, after the ACES reference's glow and red
+ * modifier and a 4% desaturation: a straight line of `slope` through mid grey in log10, joined to a
+ * logistic toe below `toeMatch` and a logistic shoulder above `shoulderMatch`, blended by a smooth
+ * step between the two, then desaturated by 7% and taken back to linear sRGB. The toe's position is
+ * solved so that 0.18 in is 0.18 out.
+ *
+ * **What it gives up.** It needs the composite to grade: `screenEffects` and `hdrScene`, since the
+ * forward passes that grade a frame without one carry two uniforms between them and not eight.
+ * Without them every pass grades with `aces` and the renderer says so once at construction.
+ * **What would make it wrong** is a profile wanting this curve without a scene target, which would
+ * then pay six floats in every forward program to have it.
+ */
+/** A film curve's five numbers, as a grading volume states them. */
+export interface FilmicCurve {
+    /** The straight segment's slope in log10, through mid grey. Positive. */
+    readonly slope: number;
+    /** How much of the curve below mid grey the toe takes, 0 to 1. Larger is a longer, softer toe. */
+    readonly toe: number;
+    /** How much of the curve above mid grey the shoulder takes, 0 to 1. Larger rolls off sooner. */
+    readonly shoulder: number;
+    /** How far below 0 the toe's asymptote sits: 0 holds black at black, more crushes it. */
+    readonly blackClip: number;
+    /** How far above 1 the shoulder's asymptote sits: 0 never reaches white, more lets it clip. */
+    readonly whiteClip: number;
+}
+/** The defaults the curve ships with where a volume states nothing. */
+export declare const DEFAULT_FILMIC_CURVE: FilmicCurve;
+/** How many floats `resolveFilmicCurve` fills: two vectors of the resolve's uniforms. */
+export declare const FILMIC_CONSTANTS = 8;
+/**
+ * The eight constants the resolve reads, into `out`: `uFilmA` = (slope, black clip, white clip,
+ * toe scale) and `uFilmB` = (shoulder scale, toe match, straight match, shoulder match). Returns
+ * whether any of the five numbers had to be brought into range.
+ *
+ * Here rather than in the shader, because they are one solve a curve and would be one per pixel
+ * there. **Clamped rather than refused**, because a grading volume is set from inside a frame and
+ * the frame loop never throws: a slope below 0.01, a toe, shoulder or clip outside 0 to 1, and a
+ * toe or shoulder of exactly 1 — whose scale is then zero and divides the curve by it — are each
+ * a picture made of NaN otherwise. A number that is not finite takes the default's. The renderer
+ * says once when anything was clamped.
+ */
+export declare function resolveFilmicCurve(curve: FilmicCurve, out: Float32Array, 
+/**
+ * The display's peak over paper white (`displayHeadroom`), 1 for a standard range. Above 1 the
+ * white clip is raised by the difference, so the shoulder rolls off toward the display's peak
+ * rather than toward white, and the toe and mid grey stay exactly where they were.
+ */
+headroom?: number): boolean;
+/** Said once a renderer, the first time `setFilmicCurve` was handed a number out of range. */
+export declare const FILMIC_CLAMPED: string;
+/**
+ * Said once at construction where `filmic` was asked for and the frame has no composite that
+ * grades: the passes grade with `aces`, which is the nearest curve they carry.
+ */
+export declare const FILMIC_WITHOUT_COMPOSITE: string;
+/**
+ * `filmicCurve(c)`: linear sRGB in, display-linear sRGB out, clamped to 0 to 1 — or, on a high
+ * range display, to the shoulder's own asymptote. Reads `uFilmA`, `uFilmB` and `uDisplayHeadroom`,
+ * which the including stage declares. The ACES helpers are the reference's own:
+ * saturation, `yc`, the glow's sigmoid, and hue in degrees.
+ */
+export declare const FILMIC_GLSL = "\n/* sRGB to ACEScg (through D60), ACEScg back, and ACEScg to and from ACES2065-1. Columns. */\nconst mat3 FILM_SRGB_TO_AP1 = mat3(\n  0.61319, 0.07021, 0.02062,\n  0.33951, 0.91634, 0.10957,\n  0.04737, 0.01345, 0.86961\n);\n/* The inverse of the one above, computed rather than copied, so a round trip is the identity. */\nconst mat3 FILM_AP1_TO_SRGB = mat3(\n   1.70480, -0.13027, -0.02401,\n  -0.62168,  1.14082, -0.12900,\n  -0.08325, -0.01055,  1.15324\n);\nconst mat3 FILM_AP1_TO_AP0 = mat3(\n   0.6954522414, 0.0447945634, -0.0055258826,\n   0.1406786965, 0.8596711185,  0.0040252103,\n   0.1638690622, 0.0955343182,  1.0015006723\n);\nconst mat3 FILM_AP0_TO_AP1 = mat3(\n   1.4514393161, -0.0765537734,  0.0083161484,\n  -0.2365107469,  1.1762296998, -0.0060324498,\n  -0.2149285693, -0.0996759264,  0.9977163014\n);\nconst vec3 FILM_AP1_LUMA = vec3(0.2722287168, 0.6740817658, 0.0536895174);\n\nfloat filmSaturation(vec3 c) {\n  float hi = max(c.r, max(c.g, c.b));\n  float lo = min(c.r, min(c.g, c.b));\n  return (max(hi, 1e-10) - max(lo, 1e-10)) / max(hi, 1e-2);\n}\n\nfloat filmYc(vec3 c) {\n  float chroma = sqrt(max(c.b * (c.b - c.g) + c.g * (c.g - c.r) + c.r * (c.r - c.b), 0.0));\n  return (c.b + c.g + c.r + 1.75 * chroma) / 3.0;\n}\n\nfloat filmSigmoid(float x) {\n  float t = max(1.0 - abs(x / 2.0), 0.0);\n  return (1.0 + sign(x) * (1.0 - t * t)) / 2.0;\n}\n\nfloat filmGlow(float yc, float gain, float mid) {\n  if (yc <= 2.0 / 3.0 * mid) return gain;\n  if (yc >= 2.0 * mid) return 0.0;\n  return gain * (mid / yc - 0.5);\n}\n\n/* Hue in degrees, -180 to 180 about red; 0 for a grey, which then takes no red modifier. */\nfloat filmCentredHue(vec3 c) {\n  float y = sqrt(3.0) * (c.g - c.b);\n  float x = 2.0 * c.r - c.g - c.b;\n  if (abs(x) < 1e-10 && abs(y) < 1e-10) return 0.0;\n  return degrees(atan(y, x));\n}\n\nvec3 filmicCurve(vec3 linear) {\n  vec3 ap0 = FILM_AP1_TO_AP0 * (FILM_SRGB_TO_AP1 * linear);\n  /* The reference's glow, lifting dark saturated colours a little. */\n  float saturation = filmSaturation(ap0);\n  ap0 *= 1.0 + filmGlow(filmYc(ap0), 0.05 * filmSigmoid((saturation - 0.4) / 0.2), 0.08);\n  /* And its red modifier, pulling saturated reds toward a pivot so they do not run to orange. */\n  float weight = smoothstep(0.0, 1.0, 1.0 - abs(2.0 * filmCentredHue(ap0) / 135.0));\n  ap0.r += weight * weight * saturation * (0.03 - ap0.r) * (1.0 - 0.82);\n  vec3 work = max(FILM_AP0_TO_AP1 * ap0, vec3(0.0));\n  work = mix(vec3(dot(work, FILM_AP1_LUMA)), work, 0.96);\n\n  float slope = uFilmA.x;\n  float black = uFilmA.y;\n  float white = uFilmA.z;\n  float toeScale = uFilmA.w;\n  float shoulderScale = uFilmB.x;\n  float toeMatch = uFilmB.y;\n  float straightMatch = uFilmB.z;\n  float shoulderMatch = uFilmB.w;\n  /* log10, through log2: GLSL ES has no log10. */\n  vec3 logc = log2(max(work, vec3(1e-10))) * 0.30102999566;\n  vec3 straight = slope * (logc + straightMatch);\n  vec3 toeC = -black + (2.0 * toeScale) / (1.0 + exp((-2.0 * slope / toeScale) * (logc - toeMatch)));\n  vec3 shoulderC =\n    (1.0 + white) - (2.0 * shoulderScale) / (1.0 + exp((2.0 * slope / shoulderScale) * (logc - shoulderMatch)));\n  toeC = mix(straight, toeC, vec3(lessThan(logc, vec3(toeMatch))));\n  shoulderC = mix(straight, shoulderC, vec3(greaterThan(logc, vec3(shoulderMatch))));\n  vec3 t = clamp((logc - toeMatch) / (shoulderMatch - toeMatch), 0.0, 1.0);\n  if (shoulderMatch < toeMatch) t = 1.0 - t;\n  t = (3.0 - 2.0 * t) * t * t;\n  vec3 tone = mix(toeC, shoulderC, t);\n  tone = mix(vec3(dot(tone, FILM_AP1_LUMA)), tone, 0.93);\n  /* White is the ceiling on a standard display; on a high range one the shoulder's asymptote is. */\n  float ceiling = uDisplayHeadroom > 1.0 ? 1.0 + white : 1.0;\n  return clamp(FILM_AP1_TO_SRGB * max(tone, vec3(0.0)), 0.0, ceiling);\n}\n";