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

@@ -0,0 +1,61 @@
+/**
+ * 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 function browserHighDynamicRange(): boolean {
+  // 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: boolean,
+  composite: boolean,
+  displayIsHigh: boolean,
+): DisplayRangeChoice {
+  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: DisplayRange, paperWhite: number, peak: number): number {
+  if (range !== 'high') return 1;
+  const ratio = peak / paperWhite;
+  return Number.isFinite(ratio) ? Math.min(Math.max(ratio, 1), 64) : 1;
+}