@driftengine/core 4.9.0 → 4.10.0

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

@@ -99,6 +99,20 @@ export interface StageBindings {
   readonly textures: Readonly<Record<string, TextureBinding>>;
   /** Each pipeline-overridable constant's id, by the GLSL name it was declared under. */
   readonly overrides?: Readonly<Record<string, number>>;
+  /**
+   * The second block, of the uniforms marked `// wgsl:material`: its binding, size and fields.
+   * Absent from a stage that marks none, which is every stage but the lit fragment's.
+   */
+  readonly materialUniforms?: number;
+  readonly materialSize?: number;
+  readonly materialFields?: StageBindings['fields'];
+  /**
+   * The vertex stage's view block, of the uniforms marked `// wgsl:view`: the camera, the light's
+   * matrix and the wind, which a pass settles. Absent from every stage but the lit vertex one.
+   */
+  readonly viewUniforms?: number;
+  readonly viewSize?: number;
+  readonly viewFields?: StageBindings['fields'];
 }
 
 /*
@@ -130,9 +144,16 @@ const VERTEX_BINDINGS = FLAT_BINDINGS.flatVert as unknown as Readonly<
 >;
 
 /** The key for a set of vertex flags: the same rule `variantKey` uses, flags on, sorted, joined. */
-export function flatVertexKey(skinned: boolean, morphed: boolean, instanced = false): string {
+export function flatVertexKey(
+  skinned: boolean,
+  morphed: boolean,
+  instanced = false,
+  /** Whether an instanced variant plays a bone animation. See `shaders/boneAnimation.ts`. */
+  animated = false,
+): string {
   const on: string[] = [];
   /* Alphabetical, because the generator's own `variantKey` sorts and the two keys must agree. */
+  if (animated) on.push('animated');
   if (instanced) on.push('instanced');
   if (morphed) on.push('morphed');
   if (skinned) on.push('skinned');
@@ -144,8 +165,9 @@ export function flatVertexBindings(
   skinned: boolean,
   morphed = false,
   instanced = false,
+  animated = false,
 ): StageBindings {
-  const key = flatVertexKey(skinned, morphed, instanced);
+  const key = flatVertexKey(skinned, morphed, instanced, animated);
   const found = VERTEX_BINDINGS[key];
   if (found === undefined) throw new Error(`flatPass: no vertex bindings for variant "${key}"`);
   return found;
@@ -221,6 +243,8 @@ for (const [key, bindings] of Object.entries(VERTEX_BINDINGS)) {
 }
 
 export const FLAT_VERT_FIELDS = FLAT_BINDINGS.flatVert.none.fields;
+/** The animated instanced variant's block: the instanced fields, and the clip's `uBoneClip`. */
+export const FLAT_ANIMATED_VERT_FIELDS = FLAT_BINDINGS.flatVert['animated+instanced'].fields;
 /**
  * The **largest** variant's block, because one ring serves every draw.
  *
@@ -233,6 +257,35 @@ export const FLAT_VERT_SIZE = Math.max(
 );
 const FLAT_VERT_BINDING = PLAIN_VERTEX.uniforms;
 
+/*
+ * **The view block may be shorter in a variant, never different.** One slot serves every lit draw
+ * of a pass, plain and instanced alike, so every field a variant's view block declares must sit
+ * where the plain variant has it. The instanced variant declares no wind, and its block is the plain
+ * one's first two matrices.
+ */
+const PLAIN_VIEW_FIELDS = PLAIN_VERTEX.viewFields ?? {};
+for (const [key, bindings] of Object.entries(VERTEX_BINDINGS)) {
+  if (bindings.viewUniforms !== PLAIN_VERTEX.viewUniforms) {
+    throw new Error(`flatPass: vertex variant "${key}" binds its view block elsewhere`);
+  }
+  for (const [field, here] of Object.entries(bindings.viewFields ?? {})) {
+    if (PLAIN_VIEW_FIELDS[field]?.offset !== here.offset) {
+      throw new Error(
+        `flatPass: vertex variant "${key}" puts view field ${field} at ${here.offset} where the ` +
+          `plain variant has it at ${PLAIN_VIEW_FIELDS[field]?.offset}.`,
+      );
+    }
+  }
+}
+
+/** The view block's fields, binding and size: the largest variant's, as `FLAT_VERT_SIZE` is. */
+export const FLAT_VIEW_FIELDS = PLAIN_VIEW_FIELDS;
+export const FLAT_VIEW_SIZE = Math.max(
+  ...Object.values(VERTEX_BINDINGS).map((bindings) => bindings.viewSize ?? 0),
+);
+const FLAT_VIEW_BINDING = PLAIN_VERTEX.viewUniforms ?? -1;
+if (FLAT_VIEW_BINDING < 0) throw new Error('flatPass: the lit vertex stage declares no view block');
+
 /**
  * The most sampled textures and distinct samplers any lit variant carrying the environment probe
  * binds in its fragment stage, counted from the generated bindings: what a device must allow per
@@ -260,6 +313,46 @@ export function flatFragmentBindings(variant: FlatVariant): StageBindings {
   return found;
 }
 
+/**
+ * The lit fragment stage's two blocks as the renderer keeps them on the CPU: the pass's, then the
+ * material's straight after it, in one scratch, with every field at its offset in that scratch.
+ *
+ * **One scratch rather than two, so no setter has to know which block its field is in.** A setter
+ * writes by name, as it always has; the draw copies the material's bytes — `passSize` onwards — into
+ * the store and the pass's bytes into a ring slot, each only when something has changed it.
+ */
+export interface FlatFragmentScratch {
+  readonly fields: StageBindings['fields'];
+  /** Bytes of the pass's block, which is where the material's starts in the scratch. */
+  readonly passSize: number;
+  readonly passBinding: number;
+  readonly materialSize: number;
+  readonly materialBinding: number;
+}
+
+export function flatFragmentScratch(variant: FlatVariant): FlatFragmentScratch {
+  const bindings = flatFragmentBindings(variant);
+  const { materialUniforms, materialSize, materialFields } = bindings;
+  if (
+    materialUniforms === undefined ||
+    materialSize === undefined ||
+    materialFields === undefined
+  ) {
+    throw new Error(`flatPass: variant "${variant}" has no material block`);
+  }
+  const fields: Record<string, StageBindings['fields'][string]> = { ...bindings.fields };
+  for (const [name, field] of Object.entries(materialFields)) {
+    fields[name] = { ...field, offset: bindings.uniformSize + field.offset };
+  }
+  return {
+    fields,
+    passSize: bindings.uniformSize,
+    passBinding: bindings.uniforms,
+    materialSize,
+    materialBinding: materialUniforms,
+  };
+}
+
 /**
  * The lit fragment stage's constants, set from the cache's switches, keyed by each one's **id**.
  *
@@ -306,6 +399,14 @@ function flatFragmentConstants(
   return constants;
 }
 
+/** The material block's binding, which every lit variant declares. */
+function materialBinding(fragment: StageBindings): number {
+  if (fragment.materialUniforms === undefined) {
+    throw new Error('flatPass: the lit fragment stage declares no material block');
+  }
+  return fragment.materialUniforms;
+}
+
 /** The depth format both backends compare with. */
 /* Re-exported so the twenty passes that already import it from here do not each learn a new
    module; `depthConvention.ts` is where the decision lives and why. */
@@ -317,15 +418,19 @@ const VISIBILITY_FRAGMENT = 0x2;
 /**
  * The layout this variant binds against.
  *
- * The vertex block is **dynamic**, because every draw supplies its own model matrix and tint
- * from its own slot of one buffer. The fragment block is not: it holds the lights, the fog
- * and the camera, settled once by `bindMeshPass` and unchanged between draws.
+ * All four blocks are **dynamic**: the vertex block because every draw supplies its own model
+ * matrix and tint from its own slot of one buffer; the fragment stage's pass block — the lights, the
+ * fog, the camera — and the vertex stage's view block because a frame binds more than one pass; and
+ * the material block because a material changes between draws. Their dynamic offsets go in binding
+ * order: the draw's, the pass's, the material's, the view's.
  */
 export function createFlatBindGroupLayout(
   device: GPUDevice,
   variant: FlatVariant,
   skinned = false,
   morphed = false,
+  /** The instanced variant that plays a bone animation: its three vertex textures. */
+  animated = false,
 ): GPUBindGroupLayout {
   const fragment = flatFragmentBindings(variant);
   const entries: GPUBindGroupLayoutEntry[] = [
@@ -334,15 +439,31 @@ export function createFlatBindGroupLayout(
       visibility: VISIBILITY_VERTEX,
       buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: FLAT_VERT_SIZE },
     },
+    {
+      binding: FLAT_VIEW_BINDING,
+      visibility: VISIBILITY_VERTEX,
+      /* Dynamic, a slot a pass, for the reason the fragment stage's pass block is. */
+      buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: FLAT_VIEW_SIZE },
+    },
     {
       binding: fragment.uniforms,
       visibility: VISIBILITY_FRAGMENT,
       /*
-       * Dynamic, because this block carries the material and a material changes between draws.
-       * See `WebGPURenderer.perFrame` for why one buffer cannot hold two answers.
+       * Dynamic, because a pass's lights and camera change between passes of one frame — a
+       * mirror's, a capture's — and one buffer cannot hold two answers. See `WebGPURenderer.passRing`.
        */
       buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: fragment.uniformSize },
     },
+    {
+      binding: materialBinding(fragment),
+      visibility: VISIBILITY_FRAGMENT,
+      /* Dynamic, because a material changes between draws. See `MaterialStore`. */
+      buffer: {
+        type: 'uniform',
+        hasDynamicOffset: true,
+        minBindingSize: fragment.materialSize ?? 0,
+      },
+    },
   ];
 
   /** What each sampler binding was declared as, so a shared one is declared once and agrees. */
@@ -489,12 +610,43 @@ export function createFlatBindGroupLayout(
     }
   }
 
+  /* A bone animation's places, turns and the batch's clocks, read by index as the palette is. */
+  if (animated) {
+    for (const binding of animationBindings()) {
+      entries.push({
+        binding,
+        visibility: VISIBILITY_VERTEX,
+        texture: { sampleType: 'unfilterable-float' },
+      });
+    }
+  }
+
   return device.createBindGroupLayout({
-    label: `flat.layout:${variant}|${flatVertexKey(skinned, morphed)}`,
+    label: `flat.layout:${variant}|${flatVertexKey(skinned, morphed, animated, animated)}`,
     entries,
   });
 }
 
+/** The three textures a bone animation binds, in the order `AnimationViews` holds them. */
+function animationBindings(): [number, number, number] {
+  const textures = flatVertexBindings(false, false, true, true).textures;
+  const at = (name: string): number => {
+    const found = textures[name];
+    if (found === undefined) {
+      throw new Error(`flatPass: the animated vertex shader declares no ${name}`);
+    }
+    return found.texture;
+  };
+  return [at('uBonePlaces'), at('uBoneTurns'), at('uInstanceClocks')];
+}
+
+/** What an animated draw binds besides its material: the clip's two textures and its batch's clocks. */
+export interface AnimationViews {
+  readonly places: GPUTextureView;
+  readonly turns: GPUTextureView;
+  readonly clocks: GPUTextureView;
+}
+
 /**
  * Bind the buffers and one view per declared texture.
  *
@@ -509,7 +661,9 @@ export function createFlatBindGroup(
   layout: GPUBindGroupLayout,
   variant: FlatVariant,
   perDraw: GPUBuffer,
-  perFrame: GPUBuffer,
+  passes: GPUBuffer,
+  materials: GPUBuffer,
+  views: GPUBuffer,
   resolve: (name: string) => { view: GPUTextureView; sampler: GPUSampler },
   /** The palette view for a skinned bind group, or null for an unskinned one. */
   palette: GPUTextureView | null = null,
@@ -517,6 +671,8 @@ export function createFlatBindGroup(
   deltas: GPUTextureView | null = null,
   /** A skinned bind group's cloth views — the draw's, or the stand-in where it sets none. */
   cloth: ClothViews | null = null,
+  /** An animated instanced group's views. See `AnimationViews`. */
+  animation: AnimationViews | null = null,
 ): GPUBindGroup {
   const fragment = flatFragmentBindings(variant);
   const entries: GPUBindGroupEntry[] = [
@@ -524,7 +680,12 @@ export function createFlatBindGroup(
       binding: FLAT_VERT_BINDING,
       resource: { buffer: perDraw, size: FLAT_VERT_SIZE },
     },
-    { binding: fragment.uniforms, resource: { buffer: perFrame, size: fragment.uniformSize } },
+    { binding: FLAT_VIEW_BINDING, resource: { buffer: views, size: FLAT_VIEW_SIZE } },
+    { binding: fragment.uniforms, resource: { buffer: passes, size: fragment.uniformSize } },
+    {
+      binding: materialBinding(fragment),
+      resource: { buffer: materials, size: fragment.materialSize ?? 0 },
+    },
   ];
 
   /* The same dedupe the layout does, and for the same reason: the shadow bindings share one
@@ -563,8 +724,15 @@ export function createFlatBindGroup(
     entries.push({ binding: restAt, resource: cloth.rest });
   }
 
+  if (animation !== null) {
+    const [places, turns, clocks] = animationBindings();
+    entries.push({ binding: places, resource: animation.places });
+    entries.push({ binding: turns, resource: animation.turns });
+    entries.push({ binding: clocks, resource: animation.clocks });
+  }
+
   return device.createBindGroup({
-    label: `flat.bindGroup:${variant}|${flatVertexKey(palette !== null, deltas !== null)}`,
+    label: `flat.bindGroup:${variant}|${flatVertexKey(palette !== null, deltas !== null, animation !== null, animation !== null)}`,
     layout,
     entries,
   });
@@ -641,6 +809,8 @@ export function flatPipeline(
    * targets `reflectionSurfacePass.ts` holds. The key must carry it: `|rs`.
    */
   reflectionSurface = false,
+  /** An instanced pipeline that plays a bone animation. The key must carry it: `|anim`. */
+  animated = false,
 ): GPURenderPipeline {
   return cache.get(
     key,
@@ -666,6 +836,7 @@ export function flatPipeline(
         model,
         skinPass,
         reflectionSurface,
+        animated,
       ),
     true,
   );
@@ -799,6 +970,8 @@ function flatDescriptor(
   model: SurfaceModelKind | null = null,
   skinPass: SkinHalf = 'whole',
   reflectionSurface = false,
+  /** An instanced pipeline that plays a bone animation. See `shaders/boneAnimation.ts`. */
+  animated = false,
 ): GPURenderPipelineDescriptor {
   const offset = depthOffsetForLayer(depthLayer);
   /* The diffuse and colour halves are the same surface again, into the blur's targets; and so is
@@ -814,13 +987,13 @@ function flatDescriptor(
        * layout validates, draws, and is wrong, exactly as this file's header says.
        */
       module: shaderModule(device, {
-        label: `flat.vert:${flatVertexKey(skinned, morphed, instanced)}`,
-        code: FLAT_VERT_WGSL[flatVertexKey(skinned, morphed, instanced)] ?? '',
+        label: `flat.vert:${flatVertexKey(skinned, morphed, instanced, animated)}`,
+        code: FLAT_VERT_WGSL[flatVertexKey(skinned, morphed, instanced, animated)] ?? '',
       }),
       entryPoint: 'main',
       buffers: vertexBufferLayouts(present, instanced),
       constants: vertexConstants(
-        flatVertexBindings(skinned, morphed, instanced),
+        flatVertexBindings(skinned, morphed, instanced, animated),
         skinEight,
         cloth,
         model === 'lightmap',

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

@@ -4,6 +4,8 @@ import { destroySlot } from './instanceCullPass.ts';
 import type { CullSlot } from './instanceCullPass.ts';
 import type { MeshInstances } from '../../instances.ts';
 import type { GpuMesh } from './buffers.ts';
+import { packInstanceClocks } from '../../boneAnimation.ts';
+import { GpuInstanceClocks, type GpuBoneAnimation } from './boneAnimations.ts';
 
 /** VERTEX | COPY_DST, spelled the way every other pass here spells it. */
 const USAGE_VERTEX = 0x0020 | 0x0008;
@@ -36,10 +38,34 @@ export class GpuInstancedBatch {
   slotFrame = -1;
   slotsTaken = 0;
 
-  constructor(device: GPUDevice, mesh: GpuMesh, capacity: number, label: string, cull = false) {
+  /** The bone animation every instance plays, and its clocks; null for a batch that plays none. */
+  readonly animation: GpuBoneAnimation | null;
+  readonly clocks: GpuInstanceClocks | null;
+  /**
+   * An animated batch's own groups — its lit twins by the material group they were built beside, its
+   * shadow groups by what they cut with — and the renderer's group epoch they were built in, after
+   * which every one is dropped. See `WebGPURenderer.animatedGroup`.
+   */
+  readonly litGroups = new Map<GPUBindGroup, GPUBindGroup>();
+  readonly depthGroups = new Map<unknown, GPUBindGroup>();
+  readonly depthPeelGroups = new Map<unknown, GPUBindGroup>();
+  groupEpoch = -1;
+
+  constructor(
+    device: GPUDevice,
+    mesh: GpuMesh,
+    capacity: number,
+    label: string,
+    cull = false,
+    animation: GpuBoneAnimation | null = null,
+  ) {
     this.mesh = mesh;
     this.capacity = capacity;
+    /* An animated batch is culled whole and never by instance: see `submitInstanced`. */
     this.cull = cull;
+    this.animation = animation;
+    this.clocks =
+      animation === null ? null : new GpuInstanceClocks(device, capacity, `${label}.clocks`);
     this.staging = new Float32Array(capacity * INSTANCE_FLOATS);
     this.buffer = device.createBuffer({
       /*
@@ -83,11 +109,16 @@ export class GpuInstancedBatch {
     if (count === 0) return;
     packInstances(data, this.staging);
     queue.writeBuffer(this.buffer, 0, this.staging, 0, count * INSTANCE_FLOATS);
+    if (this.clocks !== null) {
+      packInstanceClocks(data, this.clocks.staging);
+      this.clocks.upload(queue, count);
+    }
   }
 
   dispose(): void {
     this.previousBuffer?.destroy();
     this.buffer.destroy();
+    this.clocks?.dispose();
     for (const slot of this.slots) destroySlot(slot);
   }
 }

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

@@ -0,0 +1,276 @@
+import type { BudgetCounter } from '../budget.ts';
+import { DYNAMIC_ALIGNMENT, MAX_RING_BYTES } from './uniformRing.ts';
+
+/**
+ * The lit stage's material blocks, each kept in its slot for as long as later draws ask for the
+ * same numbers, so a material that has not changed since the last frame costs no upload at all.
+ *
+ * **Keyed by content, because nothing else names a material.** A material here is whatever the
+ * setters left in the block when a draw took it — a consumer never hands over an object that could
+ * carry an identity — so the block's own words are the key: hashed to find a bucket, compared word
+ * for word to accept a match, and bound by the slot's offset. What it gives up is a hash and a
+ * compare of a few hundred bytes per material change, against copying and uploading the whole
+ * block every frame, which a stage of four hundred materials measured at megabytes a frame.
+ *
+ * **A slot the frame has asked for is never given away within it**, for the reason `UniformRing`
+ * exists: a queue write does not interleave with recorded draws, so rewriting a slot a recorded draw
+ * reads would hand that draw the new numbers. A frame asking for more distinct blocks than there are
+ * slots is refused, counted and skipped, as the ring was. Across frames rewriting is safe, because a
+ * write issued after a submit is ordered after the commands in it.
+ *
+ * **What a new block displaces is a slot nobody asked for this frame or the last**, found by a hand
+ * that sweeps the slots in turn; only when every slot was asked for recently does it take one the
+ * last frame used. What would make that wrong is a scene whose distinct materials a frame approach
+ * the store's size: it then rewrites some of its steady materials every frame, which costs their
+ * upload and nothing else.
+ */
+export class MaterialStore {
+  /** Replaced by `growTo`, so every bind group over it is rebuilt when that says so. */
+  buffer: GPUBuffer;
+  /** Bytes per slot, rounded up to the alignment a dynamic offset requires. */
+  readonly slotSize: number;
+
+  private readonly words: number;
+  private readonly stride: number;
+  private capacity: number;
+  private staging: ArrayBuffer;
+  private ints: Int32Array;
+  /** Per slot: its block's hash, the next slot in its bucket or -1, and whether it holds one. */
+  private hashes: Int32Array;
+  private next: Int32Array;
+  private held: Uint8Array;
+  /** Per slot: the frame that last asked for it, and whether it was written since the last flush. */
+  private askedIn: Int32Array;
+  private pending: Uint8Array;
+  /** Per slot: how many holders pinned it. A pinned slot is never displaced. */
+  private pins: Int32Array;
+  /**
+   * How many times the store has forgotten everything it held, which growth does: a holder of an
+   * offset compares this, because an offset from before is a slot of a buffer that is gone.
+   */
+  epoch = 0;
+  /** Per bucket: its first slot, or -1. A power of two at least twice the slots. */
+  private heads: Int32Array;
+  private mask: number;
+  private lowPending: number;
+  private highPending = -1;
+  private hand = 0;
+  /** Starts past zero, so a slot never asked for reads as long unasked. */
+  private frame = 2;
+
+  constructor(
+    private readonly device: GPUDevice,
+    bytesPerBlock: number,
+    slots: number,
+    private readonly usage: number,
+    private readonly label = 'materials.store',
+    private readonly budget: BudgetCounter | null = null,
+  ) {
+    this.words = Math.ceil(bytesPerBlock / 4);
+    this.slotSize = Math.ceil(bytesPerBlock / DYNAMIC_ALIGNMENT) * DYNAMIC_ALIGNMENT;
+    this.stride = this.slotSize / 4;
+    this.capacity = slots;
+    this.lowPending = slots;
+    this.staging = new ArrayBuffer(this.slotSize * slots);
+    this.ints = new Int32Array(this.staging);
+    this.hashes = new Int32Array(slots);
+    this.next = new Int32Array(slots);
+    this.held = new Uint8Array(slots);
+    this.askedIn = new Int32Array(slots);
+    this.pending = new Uint8Array(slots);
+    this.pins = new Int32Array(slots);
+    this.heads = new Int32Array(bucketsFor(slots)).fill(-1);
+    this.mask = this.heads.length - 1;
+    this.buffer = device.createBuffer({ label, size: this.staging.byteLength, usage });
+  }
+
+  /** How many distinct blocks a frame may hold. */
+  get slots(): number {
+    return this.capacity;
+  }
+
+  /** Start a frame: every slot the last one asked for may be displaced from here on, last. */
+  beginFrame(): void {
+    this.frame += 1;
+  }
+
+  /**
+   * The byte offset of a slot holding exactly `block`, written there if no slot did, or null when
+   * every slot is one this frame has asked for. `block` is the whole block, word for word.
+   */
+  place(block: Int32Array): number | null {
+    this.budget?.ask();
+    const hash = hashWords(block, this.words);
+    const bucket = hash & this.mask;
+    for (let slot = this.heads[bucket] as number; slot >= 0; slot = this.next[slot] as number) {
+      if (this.hashes[slot] === hash && this.holds(slot, block)) {
+        this.askedIn[slot] = this.frame;
+        return slot * this.slotSize;
+      }
+    }
+    const slot = this.displace();
+    if (slot < 0) {
+      this.budget?.drop();
+      return null;
+    }
+    if (this.held[slot] === 1) this.unlink(slot);
+    this.ints.set(block, slot * this.stride);
+    this.hashes[slot] = hash;
+    this.next[slot] = this.heads[bucket] as number;
+    this.heads[bucket] = slot;
+    this.held[slot] = 1;
+    this.askedIn[slot] = this.frame;
+    this.pending[slot] = 1;
+    if (slot < this.lowPending) this.lowPending = slot;
+    if (slot > this.highPending) this.highPending = slot;
+    return slot * this.slotSize;
+  }
+
+  /** Upload every slot written since the last flush, one write per run of neighbouring slots. */
+  flush(): void {
+    let slot = this.lowPending;
+    while (slot <= this.highPending) {
+      if (this.pending[slot] !== 1) {
+        slot += 1;
+        continue;
+      }
+      const from = slot;
+      while (slot <= this.highPending && this.pending[slot] === 1) {
+        this.pending[slot] = 0;
+        slot += 1;
+      }
+      const at = from * this.slotSize;
+      this.device.queue.writeBuffer(
+        this.buffer,
+        at,
+        this.staging,
+        at,
+        (slot - from) * this.slotSize,
+      );
+    }
+    this.lowPending = this.capacity;
+    this.highPending = -1;
+  }
+
+  /**
+   * Make room for at least `slots`, forgetting every block held, and say whether the buffer was
+   * replaced. Called where `UniformRing.growTo` is, at a frame's start, for the reasons it gives,
+   * and refused past the same ceiling.
+   */
+  growTo(slots: number): boolean {
+    if (slots <= this.capacity) return false;
+    if (this.slotSize * slots > MAX_RING_BYTES) return false;
+    this.buffer.destroy();
+    this.capacity = slots;
+    this.staging = new ArrayBuffer(this.slotSize * slots);
+    this.ints = new Int32Array(this.staging);
+    this.hashes = new Int32Array(slots);
+    this.next = new Int32Array(slots);
+    this.held = new Uint8Array(slots);
+    this.askedIn = new Int32Array(slots);
+    this.pending = new Uint8Array(slots);
+    this.pins = new Int32Array(slots);
+    this.heads = new Int32Array(bucketsFor(slots)).fill(-1);
+    this.mask = this.heads.length - 1;
+    this.lowPending = slots;
+    this.epoch += 1;
+    this.highPending = -1;
+    this.hand = 0;
+    this.buffer = this.device.createBuffer({
+      label: this.label,
+      size: this.staging.byteLength,
+      usage: this.usage,
+    });
+    return true;
+  }
+
+  /**
+   * Keep the block at `offset` where it is until `unpin`: a holder binding it by offset frame after
+   * frame — a list recorded once — whether or not anything asks for it. Counted, so two holders of
+   * one block each let go of their own pin.
+   */
+  pin(offset: number): void {
+    const slot = offset / this.slotSize;
+    this.pins[slot] = (this.pins[slot] as number) + 1;
+  }
+
+  unpin(offset: number): void {
+    const slot = offset / this.slotSize;
+    if ((this.pins[slot] as number) > 0) this.pins[slot] = (this.pins[slot] as number) - 1;
+  }
+
+  dispose(): void {
+    this.buffer.destroy();
+  }
+
+  private holds(slot: number, block: Int32Array): boolean {
+    const base = slot * this.stride;
+    for (let word = 0; word < this.words; word++) {
+      if (this.ints[base + word] !== block[word]) return false;
+    }
+    return true;
+  }
+
+  /**
+   * The slot a new block goes in: the first from the hand nobody asked for this frame or the last,
+   * else the first this frame has not asked for, else none. One sweep at most.
+   */
+  private displace(): number {
+    let fallback = -1;
+    for (let step = 0; step < this.capacity; step++) {
+      const slot = this.hand;
+      this.hand = slot + 1 === this.capacity ? 0 : slot + 1;
+      if ((this.pins[slot] as number) > 0) continue;
+      const asked = this.askedIn[slot] as number;
+      if (asked < this.frame - 1) return slot;
+      if (fallback < 0 && asked !== this.frame) fallback = slot;
+    }
+    return fallback;
+  }
+
+  private unlink(slot: number): void {
+    const bucket = (this.hashes[slot] as number) & this.mask;
+    let at = this.heads[bucket] as number;
+    if (at === slot) {
+      this.heads[bucket] = this.next[slot] as number;
+      return;
+    }
+    while (at >= 0) {
+      const after = this.next[at] as number;
+      if (after === slot) {
+        this.next[at] = this.next[slot] as number;
+        return;
+      }
+      at = after;
+    }
+  }
+}
+
+function bucketsFor(slots: number): number {
+  let buckets = 16;
+  while (buckets < slots * 2) buckets *= 2;
+  return buckets;
+}
+
+/**
+ * MurmurHash3's 32-bit mix over the block's words. Not FNV, whose multiply carries a difference only
+ * upward: the bucket is the hash's low bits, and a material's words are mostly floats, whose low
+ * mantissa bits are zero for every value a person types — 0.5, 1, 2 — so blocks differing only in
+ * those would all have shared one bucket. The compare that follows a match is what decides.
+ */
+export function hashWords(block: Int32Array, words: number): number {
+  let hash = 0x9747b28c;
+  for (let word = 0; word < words; word++) {
+    let k = Math.imul(block[word] as number, 0xcc9e2d51);
+    k = (k << 15) | (k >>> 17);
+    hash ^= Math.imul(k, 0x1b873593);
+    hash = (hash << 13) | (hash >>> 19);
+    hash = (Math.imul(hash, 5) + 0xe6546b64) | 0;
+  }
+  hash ^= words * 4;
+  hash ^= hash >>> 16;
+  hash = Math.imul(hash, 0x85ebca6b);
+  hash ^= hash >>> 13;
+  hash = Math.imul(hash, 0xc2b2ae35);
+  return hash ^ (hash >>> 16);
+}