@driftengine/core 4.8.7 → 4.10.0

package/dist/render/backend/webgl2/skinPaletteTexture.d.ts

@@ -19,9 +19,11 @@ export declare class SkinPaletteTexture {
     /**
      * Upload a palette, reallocating only when the joint count changes.
      *
-     * A rig's joint count is fixed for its life, so the reallocation path runs once per skeleton and
-     * the steady state is one `texSubImage2D`. Reallocating per frame would be a GPU allocation in
-     * the frame loop, which is the same class of mistake as allocating on the CPU there.
+     * **The texture grows and never shrinks**, so the steady state is one `texSubImage2D` whatever
+     * mix of rigs a frame draws. It was rebuilt whenever the joint count changed, which with one
+     * texture for every skinned draw meant a character and a prop drawn in turn reallocated it at
+     * every draw: a GPU allocation in the frame loop. The shader reads joints by index, so a texture
+     * wider than the rig is read exactly as one that fits.
      */
     update(gl: WebGL2RenderingContext, palette: Float32Array): void;
     /** Bind to a **vertex-stage** unit. See `SKIN_PALETTE_TEXTURE_UNIT` for why that is free. */

package/dist/render/backend/webgl2/skinPaletteTexture.js

@@ -20,15 +20,17 @@ export class SkinPaletteTexture {
     /**
      * Upload a palette, reallocating only when the joint count changes.
      *
-     * A rig's joint count is fixed for its life, so the reallocation path runs once per skeleton and
-     * the steady state is one `texSubImage2D`. Reallocating per frame would be a GPU allocation in
-     * the frame loop, which is the same class of mistake as allocating on the CPU there.
+     * **The texture grows and never shrinks**, so the steady state is one `texSubImage2D` whatever
+     * mix of rigs a frame draws. It was rebuilt whenever the joint count changed, which with one
+     * texture for every skinned draw meant a character and a prop drawn in turn reallocated it at
+     * every draw: a GPU allocation in the frame loop. The shader reads joints by index, so a texture
+     * wider than the rig is read exactly as one that fits.
      */
     update(gl, palette) {
         validateSkinPalette(palette);
         const joints = palette.length / 16;
         const width = paletteTextureWidth(joints);
-        if (this.texture === null || this.joints !== joints) {
+        if (this.texture === null || joints > this.joints) {
             if (this.texture !== null)
                 gl.deleteTexture(this.texture);
             const created = gl.createTexture();

package/dist/render/backend/webgpu/boneAnimations.d.ts

@@ -0,0 +1,34 @@
+/**
+ * A bone animation's textures on this backend, and a batch's clocks: what
+ * `shaders/boneAnimation.ts` reads by index, made once and never filtered.
+ *
+ * **`rgba32float` places and turns, and `rg32float` clocks**, all read with `textureLoad` and bound
+ * `unfilterable-float`, as the joint palette is: a turn in half floats moves a crowd's hands by a
+ * thousandth of their reach, a jitter at the frame's rate, and the bytes are a clip's, once.
+ */
+import { type BoneAnimationHandle, type BoneAnimationTexels } from '../../boneAnimation.ts';
+/** A clip on the device, from `createBoneAnimation`. */
+export declare class GpuBoneAnimation implements BoneAnimationHandle {
+    readonly bones: number;
+    readonly frames: number;
+    readonly framesPerSecond: number;
+    readonly boneScale: number;
+    readonly placesView: GPUTextureView;
+    readonly turnsView: GPUTextureView;
+    disposed: boolean;
+    private readonly places;
+    private readonly turns;
+    constructor(device: GPUDevice, texels: BoneAnimationTexels);
+    dispose(): void;
+}
+/** A batch's clocks: two floats an instance, wrapped onto rows `CLOCK_TEXTURE_WIDTH` wide. */
+export declare class GpuInstanceClocks {
+    readonly view: GPUTextureView;
+    readonly staging: Float32Array;
+    private readonly texture;
+    private readonly width;
+    constructor(device: GPUDevice, capacity: number, label: string);
+    /** The rows that hold the first `count` instances, from `staging`. */
+    upload(queue: GPUQueue, count: number): void;
+    dispose(): void;
+}

package/dist/render/backend/webgpu/boneAnimations.js

@@ -0,0 +1,76 @@
+/**
+ * A bone animation's textures on this backend, and a batch's clocks: what
+ * `shaders/boneAnimation.ts` reads by index, made once and never filtered.
+ *
+ * **`rgba32float` places and turns, and `rg32float` clocks**, all read with `textureLoad` and bound
+ * `unfilterable-float`, as the joint palette is: a turn in half floats moves a crowd's hands by a
+ * thousandth of their reach, a jitter at the frame's rate, and the bytes are a clip's, once.
+ */
+import { CLOCK_TEXTURE_WIDTH, } from '../../boneAnimation.js';
+const USAGE_TEXTURE = 0x4 | 0x2; // TEXTURE_BINDING | COPY_DST
+/** A clip on the device, from `createBoneAnimation`. */
+export class GpuBoneAnimation {
+    bones;
+    frames;
+    framesPerSecond;
+    boneScale;
+    placesView;
+    turnsView;
+    disposed = false;
+    places;
+    turns;
+    constructor(device, texels) {
+        this.bones = texels.bones;
+        this.frames = texels.frames;
+        this.framesPerSecond = texels.framesPerSecond;
+        this.boneScale = texels.boneScale;
+        const make = (label, data) => {
+            const texture = device.createTexture({
+                label,
+                size: [texels.bones, texels.frames],
+                format: 'rgba32float',
+                usage: USAGE_TEXTURE,
+            });
+            device.queue.writeTexture({ texture }, data, { bytesPerRow: texels.bones * 16, rowsPerImage: texels.frames }, [texels.bones, texels.frames]);
+            return texture;
+        };
+        this.places = make('bones.places', texels.places);
+        this.turns = make('bones.turns', texels.turns);
+        this.placesView = this.places.createView();
+        this.turnsView = this.turns.createView();
+    }
+    dispose() {
+        this.disposed = true;
+        this.places.destroy();
+        this.turns.destroy();
+    }
+}
+/** A batch's clocks: two floats an instance, wrapped onto rows `CLOCK_TEXTURE_WIDTH` wide. */
+export class GpuInstanceClocks {
+    view;
+    staging;
+    texture;
+    width;
+    constructor(device, capacity, label) {
+        this.width = Math.max(1, Math.min(capacity, CLOCK_TEXTURE_WIDTH));
+        const rows = Math.max(1, Math.ceil(capacity / this.width));
+        this.staging = new Float32Array(this.width * rows * 2);
+        this.texture = device.createTexture({
+            label,
+            size: [this.width, rows],
+            format: 'rg32float',
+            usage: USAGE_TEXTURE,
+        });
+        this.view = this.texture.createView();
+    }
+    /** The rows that hold the first `count` instances, from `staging`. */
+    upload(queue, count) {
+        if (count <= 0)
+            return;
+        const rows = Math.ceil(count / this.width);
+        queue.writeTexture({ texture: this.texture }, this.staging, { bytesPerRow: this.width * 8, rowsPerImage: rows }, [this.width, rows]);
+    }
+    dispose() {
+        this.texture.destroy();
+    }
+}

package/dist/render/backend/webgpu/buffers.d.ts

@@ -156,18 +156,33 @@ export interface GpuMesh {
      * changed, reported at 2.8 MB a frame for one character. What the split costs is a pipeline per
      * layout, keyed by `:dynamic`, and two more buffers bound per draw of such a mesh.
      */
-    readonly update: ((device: GPUDevice, positions: Float32Array, normals?: Float32Array, previous?: GPUBuffer | null) => void) | null;
+    readonly update: ((device: GPUDevice, positions: Float32Array, normals?: Float32Array, staged?: StagedRewrite | null) => void) | null;
     /**
-     * A dynamic mesh's motion state, which the renderer owns: a buffer for last frame's positions,
-     * made the first time a reconstructing renderer rewrites the mesh, and the frame of the last
-     * rewrite. Null on a mesh created without `{ dynamic: true }`, which never moves a vertex.
+     * A dynamic mesh's motion state, which the renderer owns: a buffer for last frame's positions and
+     * one the new positions are staged in, each made the first time a reconstructing renderer
+     * rewrites the mesh, and the frame of the last rewrite. Null on a mesh created without
+     * `{ dynamic: true }`, which never moves a vertex.
      */
     readonly motion: {
         previous: GPUBuffer | null;
+        staging: GPUBuffer | null;
         changed: number;
     } | null;
     dispose(): void;
 }
+/**
+ * A rewrite a reconstructing renderer stages rather than writes, so last frame's positions can be
+ * kept with no submit of the rewrite's own: the new positions are written into `staging`, and two
+ * copies are recorded into `encoder` — the live positions into `previous` first, where the frame's
+ * first rewrite keeps them, then the staged ones in. The renderer submits that encoder at the head
+ * of the frame's next submit, which is what keeps both copies ahead of every draw that reads the
+ * mesh. A `writeBuffer` straight to the live positions would land before the copy aside could run.
+ */
+export interface StagedRewrite {
+    encoder: GPUCommandEncoder;
+    staging: GPUBuffer;
+    previous: GPUBuffer | null;
+}
 /** A mesh on its way to the device, and the iterator that gets it there. */
 export interface IncrementalGpuMesh {
     /**

package/dist/render/backend/webgpu/buffers.js

@@ -408,7 +408,9 @@ function skinOffsetsOf(supplied) {
 }
 /** The handle, made where it can see only what it hands out. */
 function gpuMeshOf(parts) {
-    const motion = parts.update === null ? null : { previous: null, changed: -1 };
+    const motion = parts.update === null
+        ? null
+        : { previous: null, staging: null, changed: -1 };
     const { vertices, constants, streams, indexBuffer, progress } = parts;
     return {
         vertexBuffers: streams === null
@@ -433,6 +435,7 @@ function gpuMeshOf(parts) {
         motion,
         dispose() {
             motion?.previous?.destroy();
+            motion?.staging?.destroy();
             streams?.positions.destroy();
             streams?.normals.destroy();
             vertices.destroy();
@@ -447,12 +450,12 @@ function isStreamed(attribute) {
 }
 /**
  * A dynamic mesh's `update`: the caller's positions, and its normals where it has them, each
- * written to its own buffer as it came. Last frame's positions, where a reconstruction wants them,
- * are copied on the device before the write — a copy submitted ahead of a `writeBuffer` runs ahead
- * of it on the queue — so no CPU copy of anything is kept.
+ * written to its own buffer as it came — or, where a reconstruction keeps last frame's positions,
+ * the positions staged and copied in on the device behind the copy aside (`StagedRewrite`), so no
+ * CPU copy of anything is kept and the rewrite submits nothing of its own.
  */
 function streamUpdate(positionsBuffer, normalsBuffer, streamBytes, bounds, vertexCount) {
-    return (target, positions, normals, previous = null) => {
+    return (target, positions, normals, staged = null) => {
         for (const [name, values] of [
             ['update', positions],
             ['normals', normals],
@@ -463,15 +466,19 @@ function streamUpdate(positionsBuffer, normalsBuffer, streamBytes, bounds, verte
                 "A mesh's vertex count is fixed at creation: the index buffer, the pipeline and " +
                 'every other attribute are sized against it.');
         }
-        if (previous !== null) {
-            const encoder = target.createCommandEncoder({ label: 'mesh.previousPositions' });
-            encoder.copyBufferToBuffer(positionsBuffer, 0, previous, 0, streamBytes);
-            target.queue.submit([encoder.finish()]);
-        }
         /* Everything that decides whether this is on screen starts from the bounds, so a cloth
            that blew sideways out of its original box would be culled while still visible. */
         boundsOfPositions(positions, bounds);
-        target.queue.writeBuffer(positionsBuffer, 0, positions);
+        if (staged === null) {
+            target.queue.writeBuffer(positionsBuffer, 0, positions);
+        }
+        else {
+            target.queue.writeBuffer(staged.staging, 0, positions);
+            if (staged.previous !== null) {
+                staged.encoder.copyBufferToBuffer(positionsBuffer, 0, staged.previous, 0, streamBytes);
+            }
+            staged.encoder.copyBufferToBuffer(staged.staging, 0, positionsBuffer, 0, streamBytes);
+        }
         if (normals !== undefined)
             target.queue.writeBuffer(normalsBuffer, 0, normals);
     };

package/dist/render/backend/webgpu/compressedUpload.d.ts

@@ -12,7 +12,6 @@
  * the level nominally has.
  */
 import type { CompressedTextureFormat, CompressedTextureSource } from '../../compressedSource.ts';
-/** Every BC format, where the device carries the feature; none where it does not. */
 export declare function gpuCompressedFormats(device: GPUDevice): CompressedTextureFormat[];
 /** A texture holding `layers` as `name`, `levels` levels of each, written as they are. */
 export declare function createCompressedTexture(device: GPUDevice, name: CompressedTextureFormat, layers: readonly CompressedTextureSource[], levels: number): GPUTexture;

package/dist/render/backend/webgpu/compressedUpload.js

@@ -1,4 +1,4 @@
-import { BLOCK_BYTES } from '../../compressedSource.js';
+import { BLOCK_SHAPES, blockFamily } from '../../compressedSource.js';
 const GPU_FORMAT = {
     bc1: 'bc1-rgba-unorm',
     'bc1-srgb': 'bc1-rgba-unorm-srgb',
@@ -10,28 +10,73 @@ const GPU_FORMAT = {
     bc5: 'bc5-rg-unorm',
     bc7: 'bc7-rgba-unorm',
     'bc7-srgb': 'bc7-rgba-unorm-srgb',
+    'etc2-rgb8': 'etc2-rgb8unorm',
+    'etc2-rgb8-srgb': 'etc2-rgb8unorm-srgb',
+    'etc2-rgb8a1': 'etc2-rgb8a1unorm',
+    'etc2-rgb8a1-srgb': 'etc2-rgb8a1unorm-srgb',
+    'etc2-rgba8': 'etc2-rgba8unorm',
+    'etc2-rgba8-srgb': 'etc2-rgba8unorm-srgb',
+    'eac-r11': 'eac-r11unorm',
+    'eac-rg11': 'eac-rg11unorm',
+    'astc-4x4': 'astc-4x4-unorm',
+    'astc-4x4-srgb': 'astc-4x4-unorm-srgb',
+    'astc-5x4': 'astc-5x4-unorm',
+    'astc-5x4-srgb': 'astc-5x4-unorm-srgb',
+    'astc-5x5': 'astc-5x5-unorm',
+    'astc-5x5-srgb': 'astc-5x5-unorm-srgb',
+    'astc-6x5': 'astc-6x5-unorm',
+    'astc-6x5-srgb': 'astc-6x5-unorm-srgb',
+    'astc-6x6': 'astc-6x6-unorm',
+    'astc-6x6-srgb': 'astc-6x6-unorm-srgb',
+    'astc-8x5': 'astc-8x5-unorm',
+    'astc-8x5-srgb': 'astc-8x5-unorm-srgb',
+    'astc-8x6': 'astc-8x6-unorm',
+    'astc-8x6-srgb': 'astc-8x6-unorm-srgb',
+    'astc-8x8': 'astc-8x8-unorm',
+    'astc-8x8-srgb': 'astc-8x8-unorm-srgb',
+    'astc-10x5': 'astc-10x5-unorm',
+    'astc-10x5-srgb': 'astc-10x5-unorm-srgb',
+    'astc-10x6': 'astc-10x6-unorm',
+    'astc-10x6-srgb': 'astc-10x6-unorm-srgb',
+    'astc-10x8': 'astc-10x8-unorm',
+    'astc-10x8-srgb': 'astc-10x8-unorm-srgb',
+    'astc-10x10': 'astc-10x10-unorm',
+    'astc-10x10-srgb': 'astc-10x10-unorm-srgb',
+    'astc-12x10': 'astc-12x10-unorm',
+    'astc-12x10-srgb': 'astc-12x10-unorm-srgb',
+    'astc-12x12': 'astc-12x12-unorm',
+    'astc-12x12-srgb': 'astc-12x12-unorm-srgb',
 };
 /** Every BC format, where the device carries the feature; none where it does not. */
+/** The feature that grants each family, which `select.ts` asks for wherever the adapter offers it. */
+const FEATURE = {
+    bc: 'texture-compression-bc',
+    etc2: 'texture-compression-etc2',
+    astc: 'texture-compression-astc',
+};
 export function gpuCompressedFormats(device) {
-    return device.features.has('texture-compression-bc')
-        ? Object.keys(GPU_FORMAT)
-        : [];
+    return Object.keys(GPU_FORMAT).filter((name) => device.features.has(FEATURE[blockFamily(baseOf(name))]));
+}
+/** The format a name is of, without its colour space. */
+function baseOf(name) {
+    return (name.endsWith('-srgb') ? name.slice(0, -'-srgb'.length) : name);
 }
 /** A texture holding `layers` as `name`, `levels` levels of each, written as they are. */
 export function createCompressedTexture(device, name, layers, levels) {
     const { format, width, height } = layers[0];
     const texture = device.createTexture({
-        label: 'surface.texture.bc',
+        label: `surface.texture.${format}`,
         size: [width, height, layers.length],
         format: GPU_FORMAT[name],
         mipLevelCount: levels,
         usage: 0x2 | 0x4, // COPY_DST | TEXTURE_BINDING
     });
+    const block = BLOCK_SHAPES[format];
     for (let level = 0; level < levels; level++) {
-        const across = Math.ceil(Math.max(1, width >> level) / 4);
-        const down = Math.ceil(Math.max(1, height >> level) / 4);
+        const across = Math.ceil(Math.max(1, width >> level) / block.width);
+        const down = Math.ceil(Math.max(1, height >> level) / block.height);
         for (let layer = 0; layer < layers.length; layer++) {
-            device.queue.writeTexture({ texture, mipLevel: level, origin: [0, 0, layer] }, layers[layer].levels[level], { bytesPerRow: across * BLOCK_BYTES[format], rowsPerImage: down }, { width: across * 4, height: down * 4, depthOrArrayLayers: 1 });
+            device.queue.writeTexture({ texture, mipLevel: level, origin: [0, 0, layer] }, layers[layer].levels[level], { bytesPerRow: across * block.bytes, rowsPerImage: down }, { width: across * block.width, height: down * block.height, depthOrArrayLayers: 1 });
         }
     }
     return texture;

package/dist/render/backend/webgpu/depthPass.d.ts

@@ -1,6 +1,7 @@
 import { DEPTH_FRAG_WGSL } from '../../shaders/generated/depth.wgsl.ts';
 import type { PipelineCache } from './pipelineCache.ts';
 import type { ClothViews } from './clothTextures.ts';
+import type { AnimationViews } from './flatPass.ts';
 /**
  * The shadow pass: the world drawn from the light, into a depth map.
  *
@@ -136,6 +137,55 @@ export declare const DEPTH_PALETTE_BINDING: {
     readonly sampler: 17;
     readonly type: "sampler2D";
 };
+export declare const DEPTH_INSTANCED_ANIMATED_VERT_FIELDS: {
+    readonly uLightViewProj: {
+        readonly offset: 0;
+        readonly size: 64;
+        readonly type: "mat4";
+    };
+    readonly uSceneTime: {
+        readonly offset: 64;
+        readonly size: 4;
+        readonly type: "float";
+    };
+    readonly uBoneClip: {
+        readonly offset: 72;
+        readonly size: 8;
+        readonly type: "vec2";
+    };
+};
+export declare const DEPTH_INSTANCED_ANIMATED_CUTOUT_VERT_FIELDS: {
+    readonly uLightViewProj: {
+        readonly offset: 0;
+        readonly size: 64;
+        readonly type: "mat4";
+    };
+    readonly uUvScale: {
+        readonly offset: 64;
+        readonly size: 8;
+        readonly type: "vec2";
+    };
+    readonly uUvOffset: {
+        readonly offset: 72;
+        readonly size: 8;
+        readonly type: "vec2";
+    };
+    readonly uAlphaCutout: {
+        readonly offset: 80;
+        readonly size: 8;
+        readonly type: "vec2";
+    };
+    readonly uSceneTime: {
+        readonly offset: 88;
+        readonly size: 4;
+        readonly type: "float";
+    };
+    readonly uBoneClip: {
+        readonly offset: 96;
+        readonly size: 8;
+        readonly type: "vec2";
+    };
+};
 /**
  * The format the shadow map is stored in.
  *
@@ -160,7 +210,9 @@ skinned?: boolean,
  * Separate for the palette's reason: the plain layout stays exactly what it was, and a frame with
  * no cutout caster pays nothing.
  */
-cutout?: boolean): GPUBindGroupLayout;
+cutout?: boolean, 
+/** An instanced caster playing a bone animation: its three vertex textures. */
+animated?: boolean): GPUBindGroupLayout;
 export declare function createDepthBindGroup(device: GPUDevice, layout: GPUBindGroupLayout, perDraw: GPUBuffer, perPass: GPUBuffer, previous: GPUTextureView, sampler: GPUSampler, 
 /** The joint palette, for a layout built with `skinned`. Omit for the rigid layout. */
 palette?: GPUTextureView | null, 
@@ -170,7 +222,9 @@ cutout?: {
     readonly sampler: GPUSampler;
 } | null, 
 /** A skinned group's cloth views: the caster's, or the stand-in where it has none. */
-cloth?: ClothViews | null): GPUBindGroup;
+cloth?: ClothViews | null, 
+/** An animated caster's clip and clocks. See `AnimationViews`. */
+animation?: AnimationViews | null): GPUBindGroup;
 /**
  * The depth pipeline.
  *
@@ -209,4 +263,6 @@ cutout?: boolean,
  */
 skinEight?: boolean, 
 /** Whether a skinned caster is placed by a cloth binding, as its visible draw is. The key carries it. */
-cloth?: boolean): GPURenderPipeline;
+cloth?: boolean, 
+/** An instanced caster playing a bone animation. The key must carry it. */
+animated?: boolean): GPURenderPipeline;

package/dist/render/backend/webgpu/depthPass.js

@@ -1,4 +1,4 @@
-import { DEPTH_BINDINGS, DEPTH_CUTOUT_FRAG_WGSL, DEPTH_CUTOUT_VERT_WGSL, DEPTH_FRAG_WGSL, DEPTH_INSTANCED_CUTOUT_VERT_WGSL, DEPTH_INSTANCED_VERT_WGSL, DEPTH_SKINNED_VERT_WGSL, DEPTH_VERT_WGSL, } from '../../shaders/generated/depth.wgsl.js';
+import { DEPTH_BINDINGS, DEPTH_CUTOUT_FRAG_WGSL, DEPTH_CUTOUT_VERT_WGSL, DEPTH_FRAG_WGSL, DEPTH_INSTANCED_ANIMATED_CUTOUT_VERT_WGSL, DEPTH_INSTANCED_ANIMATED_VERT_WGSL, DEPTH_INSTANCED_CUTOUT_VERT_WGSL, DEPTH_INSTANCED_VERT_WGSL, DEPTH_SKINNED_VERT_WGSL, DEPTH_VERT_WGSL, } from '../../shaders/generated/depth.wgsl.js';
 import { vertexBufferLayouts } from './buffers.js';
 import { vertexConstants } from './flatPass.js';
 import { shaderModule } from './shaderModules.js';
@@ -37,6 +37,14 @@ const CLOTH_TEXTURES = [
     DEPTH_BINDINGS.DEPTH_SKINNED_VERT.textures.uClothParticles,
     DEPTH_BINDINGS.DEPTH_SKINNED_VERT.textures.uClothRest,
 ];
+/** A bone animation's three textures, at the bindings both animated depth variants declare them. */
+const ANIMATION_TEXTURES = [
+    DEPTH_BINDINGS.DEPTH_INSTANCED_ANIMATED_VERT.textures.uBonePlaces,
+    DEPTH_BINDINGS.DEPTH_INSTANCED_ANIMATED_VERT.textures.uBoneTurns,
+    DEPTH_BINDINGS.DEPTH_INSTANCED_ANIMATED_VERT.textures.uInstanceClocks,
+];
+export const DEPTH_INSTANCED_ANIMATED_VERT_FIELDS = DEPTH_BINDINGS.DEPTH_INSTANCED_ANIMATED_VERT.fields;
+export const DEPTH_INSTANCED_ANIMATED_CUTOUT_VERT_FIELDS = DEPTH_BINDINGS.DEPTH_INSTANCED_ANIMATED_CUTOUT_VERT.fields;
 const VISIBILITY_VERTEX = 0x1;
 const VISIBILITY_FRAGMENT = 0x2;
 /**
@@ -63,10 +71,19 @@ skinned = false,
  * Separate for the palette's reason: the plain layout stays exactly what it was, and a frame with
  * no cutout caster pays nothing.
  */
-cutout = false) {
+cutout = false, 
+/** An instanced caster playing a bone animation: its three vertex textures. */
+animated = false) {
     return device.createBindGroupLayout({
-        label: skinned ? 'depth.layout.skinned' : cutout ? 'depth.layout.cutout' : 'depth.layout',
+        label: `${skinned ? 'depth.layout.skinned' : cutout ? 'depth.layout.cutout' : 'depth.layout'}${animated ? '.animated' : ''}`,
         entries: [
+            ...(animated
+                ? ANIMATION_TEXTURES.map((binding) => ({
+                    binding: binding.texture,
+                    visibility: VISIBILITY_VERTEX,
+                    texture: { sampleType: 'unfilterable-float' },
+                }))
+                : []),
             /* The texture and no sampler: the shader reads the palette with `textureLoad`, an integer
                coordinate with nothing to filter, which is what `flatPass.ts` binds for the same
                palette. naga declares a sampler for it and nothing ever reads one. */
@@ -147,7 +164,9 @@ palette = null,
 /** The cutout map and its sampler, for a layout built with `cutout`. */
 cutout = null, 
 /** A skinned group's cloth views: the caster's, or the stand-in where it has none. */
-cloth = null) {
+cloth = null, 
+/** An animated caster's clip and clocks. See `AnimationViews`. */
+animation = null) {
     return device.createBindGroup({
         label: palette !== null
             ? 'depth.bindGroup.skinned'
@@ -180,6 +199,13 @@ cloth = null) {
                     { binding: CUTOUT_MAP.sampler, resource: cutout.sampler },
                 ]
                 : []),
+            ...(animation !== null
+                ? [
+                    { binding: ANIMATION_TEXTURES[0].texture, resource: animation.places },
+                    { binding: ANIMATION_TEXTURES[1].texture, resource: animation.turns },
+                    { binding: ANIMATION_TEXTURES[2].texture, resource: animation.clocks },
+                ]
+                : []),
         ],
     });
 }
@@ -221,20 +247,29 @@ cutout = false,
  */
 skinEight = false, 
 /** Whether a skinned caster is placed by a cloth binding, as its visible draw is. The key carries it. */
-cloth = false) {
+cloth = false, 
+/** An instanced caster playing a bone animation. The key must carry it. */
+animated = false) {
     return cache.get(key, () => ({
         label: key,
         layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
         vertex: {
-            module: shaderModule(device, cutout
-                ? instanced
-                    ? { label: 'depth.instanced.cutout.vert', code: DEPTH_INSTANCED_CUTOUT_VERT_WGSL }
-                    : { label: 'depth.cutout.vert', code: DEPTH_CUTOUT_VERT_WGSL }
-                : instanced
-                    ? { label: 'depth.instanced.vert', code: DEPTH_INSTANCED_VERT_WGSL }
-                    : skinned
-                        ? { label: 'depth.skinned.vert', code: DEPTH_SKINNED_VERT_WGSL }
-                        : { label: 'depth.vert', code: DEPTH_VERT_WGSL }),
+            module: shaderModule(device, animated
+                ? cutout
+                    ? {
+                        label: 'depth.instanced.animated.cutout.vert',
+                        code: DEPTH_INSTANCED_ANIMATED_CUTOUT_VERT_WGSL,
+                    }
+                    : { label: 'depth.instanced.animated.vert', code: DEPTH_INSTANCED_ANIMATED_VERT_WGSL }
+                : cutout
+                    ? instanced
+                        ? { label: 'depth.instanced.cutout.vert', code: DEPTH_INSTANCED_CUTOUT_VERT_WGSL }
+                        : { label: 'depth.cutout.vert', code: DEPTH_CUTOUT_VERT_WGSL }
+                    : instanced
+                        ? { label: 'depth.instanced.vert', code: DEPTH_INSTANCED_VERT_WGSL }
+                        : skinned
+                            ? { label: 'depth.skinned.vert', code: DEPTH_SKINNED_VERT_WGSL }
+                            : { label: 'depth.vert', code: DEPTH_VERT_WGSL }),
             entryPoint: 'main',
             buffers: vertexBufferLayouts(present, instanced),
             ...(skinned && !instanced && !cutout

package/dist/render/backend/webgpu/device.d.ts

@@ -6,6 +6,7 @@
  * split matters because these two fail for unrelated reasons: a device is lost by a driver
  * reset the page did not cause, and a frame is wrong because of something the frame did.
  */
+import type { DisplayRange, DisplayRangeChoice } from '../../displayRange.ts';
 /** What the renderer needs from the canvas it draws into, with the API's shape absorbed. */
 export interface GpuSurface {
     readonly device: GPUDevice;
@@ -21,6 +22,9 @@ export interface GpuSurface {
     readonly canvas: HTMLCanvasElement;
     /** The swap chain's format, which every render pipeline has to be built against. */
     readonly format: GPUTextureFormat;
+    /** The range the canvas was configured in, and why. See `displayRange.ts`. */
+    readonly displayRange: DisplayRange;
+    readonly displayRangeReason: string;
     /** Whether the device has gone. Read per frame; never throws. */
     readonly lost: boolean;
     /** Called when the device is lost. Fires immediately if it already has been. */
@@ -49,4 +53,6 @@ export interface GpuSurface {
  * consumer its GPU had failed every time it unmounted a canvas on purpose, so a disposed
  * surface stays silent.
  */
-export declare function createGpuSurface(canvas: HTMLCanvasElement, device: GPUDevice): GpuSurface;
+export declare function createGpuSurface(canvas: HTMLCanvasElement, device: GPUDevice, 
+/** The range the profile and the display allow (`chooseDisplayRange`); standard unless given. */
+wanted?: DisplayRangeChoice): GpuSurface;

package/dist/render/backend/webgpu/device.js

@@ -6,6 +6,11 @@
  * split matters because these two fail for unrelated reasons: a device is lost by a driver
  * reset the page did not cause, and a frame is wrong because of something the frame did.
  */
+/** A canvas nobody asked to extend. */
+const STANDARD_RANGE = {
+    range: 'standard',
+    reason: 'highDynamicRange was not asked for',
+};
 /**
  * Take a canvas and a device, and hand back the surface the renderer draws into.
  *
@@ -25,12 +30,23 @@
  * consumer its GPU had failed every time it unmounted a canvas on purpose, so a disposed
  * surface stays silent.
  */
-export function createGpuSurface(canvas, device) {
+export function createGpuSurface(canvas, device, 
+/** The range the profile and the display allow (`chooseDisplayRange`); standard unless given. */
+wanted = STANDARD_RANGE) {
     const context = canvas.getContext('webgpu');
     if (context === null) {
         throw new Error('createGpuSurface: the canvas would not give a webgpu context');
     }
-    const format = navigator.gpu.getPreferredCanvasFormat();
+    /*
+     * **A high range is half floats with extended tone mapping**: a value of 1 is the display's
+     * paper white, and what lies above it is shown up to the display's peak instead of clipped. The
+     * colour space stays sRGB, so the composite's encoding is the one it always wrote, carried past 1.
+     */
+    const extended = wanted.range === 'high';
+    const format = extended
+        ? 'rgba16float'
+        : navigator.gpu.getPreferredCanvasFormat();
+    let range = wanted;
     const listeners = [];
     let lost = false;
     let disposed = false;
@@ -89,14 +105,26 @@ export function createGpuSurface(canvas, device) {
          * has no use for a transparent canvas, and the opaque path is the one a compositor can
          * take without a blend.
          */
-        context.configure({ device, format, alphaMode: 'opaque' });
+        context.configure(extended
+            ? { device, format, alphaMode: 'opaque', toneMapping: { mode: 'extended' } }
+            : { device, format, alphaMode: 'opaque' });
     };
     configure(canvas.width, canvas.height);
+    /*
+     * **Read back, because a browser that does not know the option ignores it** and draws the
+     * standard range from an extended-range frame, clipped at paper white, which is the frame a game
+     * would grade for the standard range if it knew. So it is told.
+     */
+    if (extended && context.getConfiguration?.()?.toneMapping?.mode !== 'extended') {
+        range = { range: 'standard', reason: 'this browser has no extended-range canvas' };
+    }
     return {
         device,
         context,
         canvas,
         format,
+        displayRange: range.range,
+        displayRangeReason: range.reason,
         get lost() {
             return lost;
         },