@driftengine/core 4.8.7 → 4.10.0

package/src/render/backend/webgl2/skinPaletteTexture.ts

@@ -22,16 +22,18 @@ 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: WebGL2RenderingContext, palette: Float32Array): void {
     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();
       if (created === null) throw new Error('skin palette: failed to create the palette texture');

package/src/render/backend/webgpu/boneAnimations.ts

@@ -0,0 +1,97 @@
+/**
+ * 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,
+  type BoneAnimationHandle,
+  type BoneAnimationTexels,
+} from '../../boneAnimation.ts';
+
+const USAGE_TEXTURE = 0x4 | 0x2; // TEXTURE_BINDING | COPY_DST
+
+/** A clip on the device, from `createBoneAnimation`. */
+export class GpuBoneAnimation implements BoneAnimationHandle {
+  readonly bones: number;
+  readonly frames: number;
+  readonly framesPerSecond: number;
+  readonly boneScale: number;
+  readonly placesView: GPUTextureView;
+  readonly turnsView: GPUTextureView;
+  disposed = false;
+  private readonly places: GPUTexture;
+  private readonly turns: GPUTexture;
+
+  constructor(device: GPUDevice, texels: BoneAnimationTexels) {
+    this.bones = texels.bones;
+    this.frames = texels.frames;
+    this.framesPerSecond = texels.framesPerSecond;
+    this.boneScale = texels.boneScale;
+    const make = (label: string, data: Float32Array): GPUTexture => {
+      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(): void {
+    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 {
+  readonly view: GPUTextureView;
+  readonly staging: Float32Array;
+  private readonly texture: GPUTexture;
+  private readonly width: number;
+
+  constructor(device: GPUDevice, capacity: number, label: string) {
+    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: GPUQueue, count: number): void {
+    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(): void {
+    this.texture.destroy();
+  }
+}

package/src/render/backend/webgpu/buffers.ts

@@ -258,18 +258,37 @@ export interface GpuMesh {
         device: GPUDevice,
         positions: Float32Array,
         normals?: Float32Array,
-        previous?: GPUBuffer | null,
+        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; changed: number } | null;
+  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 {
   /**
@@ -658,7 +677,10 @@ function gpuMeshOf(parts: {
   readonly morph: MorphTexture | null;
   readonly update: GpuMesh['update'];
 }): GpuMesh {
-  const motion = parts.update === null ? null : { previous: null as GPUBuffer | null, changed: -1 };
+  const motion =
+    parts.update === null
+      ? null
+      : { previous: null as GPUBuffer | null, staging: null as GPUBuffer | null, changed: -1 };
   const { vertices, constants, streams, indexBuffer, progress } = parts;
   return {
     vertexBuffers:
@@ -684,6 +706,7 @@ function gpuMeshOf(parts: {
     motion,
     dispose(): void {
       motion?.previous?.destroy();
+      motion?.staging?.destroy();
       streams?.positions.destroy();
       streams?.normals.destroy();
       vertices.destroy();
@@ -700,9 +723,9 @@ function isStreamed(attribute: VertexAttribute): boolean {
 
 /**
  * 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: GPUBuffer,
@@ -715,7 +738,7 @@ function streamUpdate(
     target: GPUDevice,
     positions: Float32Array,
     normals?: Float32Array,
-    previous: GPUBuffer | null = null,
+    staged: StagedRewrite | null = null,
   ): void => {
     for (const [name, values] of [
       ['update', positions],
@@ -728,15 +751,18 @@ function streamUpdate(
           '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/src/render/backend/webgpu/compressedUpload.ts

@@ -12,7 +12,8 @@
  * the level nominally has.
  */
 import type { CompressedTextureFormat, CompressedTextureSource } from '../../compressedSource.ts';
-import { BLOCK_BYTES } from '../../compressedSource.ts';
+import { BLOCK_SHAPES, blockFamily } from '../../compressedSource.ts';
+import type { BlockFormat } from '../../compressedSource.ts';
 
 const GPU_FORMAT: Readonly<Record<CompressedTextureFormat, GPUTextureFormat>> = {
   bc1: 'bc1-rgba-unorm',
@@ -25,13 +26,61 @@ const GPU_FORMAT: Readonly<Record<CompressedTextureFormat, GPUTextureFormat>> =
   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: Readonly<Record<'bc' | 'etc2' | 'astc', string>> = {
+  bc: 'texture-compression-bc',
+  etc2: 'texture-compression-etc2',
+  astc: 'texture-compression-astc',
+};
+
 export function gpuCompressedFormats(device: GPUDevice): CompressedTextureFormat[] {
-  return device.features.has('texture-compression-bc')
-    ? (Object.keys(GPU_FORMAT) as CompressedTextureFormat[])
-    : [];
+  return (Object.keys(GPU_FORMAT) as CompressedTextureFormat[]).filter((name) =>
+    device.features.has(FEATURE[blockFamily(baseOf(name))]),
+  );
+}
+
+/** The format a name is of, without its colour space. */
+function baseOf(name: CompressedTextureFormat): BlockFormat {
+  return (name.endsWith('-srgb') ? name.slice(0, -'-srgb'.length) : name) as BlockFormat;
 }
 
 /** A texture holding `layers` as `name`, `levels` levels of each, written as they are. */
@@ -43,21 +92,22 @@ export function createCompressedTexture(
 ): GPUTexture {
   const { format, width, height } = layers[0] as CompressedTextureSource;
   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] as CompressedTextureSource).levels[level] as Uint8Array<ArrayBuffer>,
-        { bytesPerRow: across * BLOCK_BYTES[format], rowsPerImage: down },
-        { width: across * 4, height: down * 4, depthOrArrayLayers: 1 },
+        { bytesPerRow: across * block.bytes, rowsPerImage: down },
+        { width: across * block.width, height: down * block.height, depthOrArrayLayers: 1 },
       );
     }
   }

package/src/render/backend/webgpu/depthPass.ts

@@ -3,6 +3,8 @@ import {
   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,
@@ -13,6 +15,7 @@ import { vertexConstants } from './flatPass.ts';
 import type { PipelineCache } from './pipelineCache.ts';
 import { shaderModule } from './shaderModules.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.
@@ -52,6 +55,17 @@ const CLOTH_TEXTURES = [
   DEPTH_BINDINGS.DEPTH_SKINNED_VERT.textures.uClothRest,
 ] as const;
 
+/** 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,
+] as const;
+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;
 
@@ -82,10 +96,19 @@ export function createDepthBindGroupLayout(
    * no cutout caster pays nothing.
    */
   cutout = false,
+  /** An instanced caster playing a bone animation: its three vertex textures. */
+  animated = false,
 ): GPUBindGroupLayout {
   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' as GPUTextureSampleType },
+          }))
+        : []),
       /* 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. */
@@ -174,6 +197,8 @@ export function createDepthBindGroup(
   cutout: { readonly view: GPUTextureView; readonly sampler: GPUSampler } | null = null,
   /** A skinned group's cloth views: the caster's, or the stand-in where it has none. */
   cloth: ClothViews | null = null,
+  /** An animated caster's clip and clocks. See `AnimationViews`. */
+  animation: AnimationViews | null = null,
 ): GPUBindGroup {
   return device.createBindGroup({
     label:
@@ -208,6 +233,13 @@ export function createDepthBindGroup(
             { 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 },
+          ]
+        : []),
     ],
   });
 }
@@ -256,6 +288,8 @@ export function depthPipeline(
   skinEight = false,
   /** Whether a skinned caster is placed by a cloth binding, as its visible draw is. The key carries it. */
   cloth = false,
+  /** An instanced caster playing a bone animation. The key must carry it. */
+  animated = false,
 ): GPURenderPipeline {
   return cache.get(key, () => ({
     label: key,
@@ -263,15 +297,22 @@ export function depthPipeline(
     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 },
+        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),

package/src/render/backend/webgpu/device.ts

@@ -7,6 +7,14 @@
  * reset the page did not cause, and a frame is wrong because of something the frame did.
  */
 
+import type { DisplayRange, DisplayRangeChoice } from '../../displayRange.ts';
+
+/** A canvas nobody asked to extend. */
+const STANDARD_RANGE: DisplayRangeChoice = {
+  range: 'standard',
+  reason: 'highDynamicRange was not asked for',
+};
+
 /** What the renderer needs from the canvas it draws into, with the API's shape absorbed. */
 export interface GpuSurface {
   readonly device: GPUDevice;
@@ -22,6 +30,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. */
@@ -51,13 +62,27 @@ export interface GpuSurface {
  * consumer its GPU had failed every time it unmounted a canvas on purpose, so a disposed
  * surface stays silent.
  */
-export function createGpuSurface(canvas: HTMLCanvasElement, device: GPUDevice): GpuSurface {
+export function createGpuSurface(
+  canvas: HTMLCanvasElement,
+  device: GPUDevice,
+  /** The range the profile and the display allow (`chooseDisplayRange`); standard unless given. */
+  wanted: DisplayRangeChoice = STANDARD_RANGE,
+): GpuSurface {
   const context = canvas.getContext('webgpu') as GPUCanvasContext | null;
   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: GPUTextureFormat = extended
+    ? 'rgba16float'
+    : navigator.gpu.getPreferredCanvasFormat();
+  let range: DisplayRangeChoice = wanted;
   const listeners: (() => void)[] = [];
   let lost = false;
   let disposed = false;
@@ -115,16 +140,30 @@ export function createGpuSurface(canvas: HTMLCanvasElement, device: GPUDevice):
      * 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;
     },

package/src/render/backend/webgpu/drawCommand.ts

@@ -2,7 +2,7 @@
  * One recorded draw, in the only shape this backend ever issues.
  *
  * Sampled across three unrelated verbs — panels, particles, wind streaks — the sequence is the
- * same every time: a pipeline, a bind group with up to two dynamic offsets, some vertex
+ * same every time: a pipeline, a bind group with up to four dynamic offsets, some vertex
  * buffers, perhaps an index buffer, then a draw. Nothing in it is specific to what is being
  * drawn except the values.
  *
@@ -21,9 +21,14 @@ const VERTEX_BUFFER_SLOTS = 8;
 export interface DrawCommand {
   pipeline: GPURenderPipeline | null;
   bindGroup: GPUBindGroup | null;
-  /** Dynamic offsets, held as two numbers rather than an array so a reset stays free. */
+  /**
+   * Dynamic offsets, held as numbers rather than an array so a reset stays free. Four only for a
+   * lit mesh: its draw's slot, its pass's, its material's and its view's, in binding order.
+   */
   offsetA: number;
   offsetB: number;
+  offsetC: number;
+  offsetD: number;
   offsetCount: number;
   /** Fixed length; `vertexCount` says how many slots are live. */
   readonly vertexBuffers: (GPUBuffer | null)[];
@@ -37,6 +42,12 @@ export interface DrawCommand {
    * cull's survivors, counted on the device. Null for every other draw.
    */
   indirect: GPUBuffer | null;
+  /**
+   * Render bundles to execute instead of everything above: a static list recorded once, replayed
+   * as one command. Held as the array `executeBundles` takes, kept by the list, so issuing it
+   * allocates nothing. Null for every other command, and put back to null by every take.
+   */
+  bundles: readonly GPURenderBundle[] | null;
 }
 
 export interface CommandPool {
@@ -52,6 +63,8 @@ function emptyCommand(): DrawCommand {
     bindGroup: null,
     offsetA: 0,
     offsetB: 0,
+    offsetC: 0,
+    offsetD: 0,
     offsetCount: 0,
     vertexBuffers: new Array<GPUBuffer | null>(VERTEX_BUFFER_SLOTS).fill(null),
     vertexCount: 0,
@@ -60,6 +73,7 @@ function emptyCommand(): DrawCommand {
     count: 0,
     instances: 1,
     indirect: null,
+    bundles: null,
   };
 }
 
@@ -72,14 +86,18 @@ export function createCommandPool(capacity: number): CommandPool {
 /**
  * Hand out the next command, growing if a frame overruns.
  *
- * The entry is **not cleared**. Every caller fills every field it uses, and clearing here would
- * be a write per field per draw for no reader — the same reasoning the node arena uses.
+ * The entry is **not cleared**, but for `bundles`. Every caller fills every field it uses, and
+ * clearing here would be a write per field per draw for no reader — the same reasoning the node
+ * arena uses. `bundles` is the exception because almost no caller knows it exists: a pooled command
+ * that once carried a static list's bundles and was then taken for an ordinary draw would replay the
+ * list instead, so the one field nobody fills is the one field put back here.
  */
 export function takeCommand(pool: CommandPool): number {
   const at = pool.taken;
   while (at >= pool.commands.length) pool.commands.push(emptyCommand());
   pool.taken = at + 1;
   if (pool.taken > pool.highWater) pool.highWater = pool.taken;
+  (pool.commands[at] as DrawCommand).bundles = null;
   return at;
 }