@driftengine/core 4.8.7 → 4.10.0

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

@@ -5,6 +5,7 @@ import { FLAT_BINDINGS, FLAT_FRAG_WGSL, FLAT_VERT_WGSL, } from '../../shaders/ge
 import { vertexBufferLayouts } from './buffers.js';
 import { shaderModule } from './shaderModules.js';
 import { SCENE_ALPHA_COVERS } from '../../sceneCoverage.js';
+import { REFLECTION_SURFACE_FORMAT } from './reflectionSurfacePass.js';
 /** The material maps the flat pass reads: `2d-array` colour, filtered, not shadow maps. */
 const SURFACE_MAPS = new Set([
     'uAlbedo',
@@ -51,9 +52,13 @@ const FRAGMENT_BINDINGS = FLAT_BINDINGS.flatFrag;
  */
 const VERTEX_BINDINGS = FLAT_BINDINGS.flatVert;
 /** The key for a set of vertex flags: the same rule `variantKey` uses, flags on, sorted, joined. */
-export function flatVertexKey(skinned, morphed, instanced = false) {
+export function flatVertexKey(skinned, morphed, instanced = false, 
+/** Whether an instanced variant plays a bone animation. See `shaders/boneAnimation.ts`. */
+animated = false) {
     const on = [];
     /* 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)
@@ -63,8 +68,8 @@ export function flatVertexKey(skinned, morphed, instanced = false) {
     return on.length === 0 ? 'none' : on.join('+');
 }
 /** Everything the generator recorded about one variant of the vertex stage. */
-export function flatVertexBindings(skinned, morphed = false, instanced = false) {
-    const key = flatVertexKey(skinned, morphed, instanced);
+export function flatVertexBindings(skinned, morphed = false, instanced = false, animated = false) {
+    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}"`);
@@ -135,6 +140,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.
  *
@@ -144,6 +151,48 @@ export const FLAT_VERT_FIELDS = FLAT_BINDINGS.flatVert.none.fields;
  */
 export const FLAT_VERT_SIZE = Math.max(...Object.values(VERTEX_BINDINGS).map((bindings) => bindings.uniformSize));
 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
+ * stage before the probe's permutation can be built. A sampler several textures share counts once,
+ * which is what `// wgsl:share` buys.
+ */
+export function probeStageCeilings() {
+    let textures = 0;
+    let samplers = 0;
+    for (const [variant, bindings] of Object.entries(FLAT_BINDINGS.flatFrag)) {
+        if (!variant.includes('environmentProbe'))
+            continue;
+        const listed = Object.values(bindings.textures ?? {});
+        textures = Math.max(textures, listed.length);
+        samplers = Math.max(samplers, new Set(listed.map((entry) => entry.sampler)).size);
+    }
+    return { textures, samplers };
+}
 /** Everything the generator recorded about one permutation of the fragment stage. */
 export function flatFragmentBindings(variant) {
     const found = FRAGMENT_BINDINGS[variant];
@@ -151,6 +200,26 @@ export function flatFragmentBindings(variant) {
         throw new Error(`flatPass: no bindings for variant "${variant}"`);
     return found;
 }
+export function flatFragmentScratch(variant) {
+    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 = { ...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**.
  *
@@ -160,7 +229,7 @@ export function flatFragmentBindings(variant) {
  * "GLASS_SHADOWS" not found*, and the frame drew nothing. Every override the variant declares is
  * set, so a switch added to the shader and not to the cache is refused here rather than defaulted.
  */
-function flatFragmentConstants(variant, cache, model, skinPass = 'whole') {
+function flatFragmentConstants(variant, cache, model, skinPass = 'whole', reflectionSurface = false) {
     const overrides = flatFragmentBindings(variant).overrides;
     if (overrides?.['GLASS_SHADOWS'] === undefined) {
         throw new Error(`flatPass: variant "${variant}" has no glass switch`);
@@ -178,6 +247,11 @@ function flatFragmentConstants(variant, cache, model, skinPass = 'whole') {
             constants[String(id)] = skinPass !== 'whole' && name === SKIN_HALF_SWITCH[skinPass] ? 1 : 0;
             continue;
         }
+        /* The reflection pass's surface half, set from the key too. See `reflectionSurface.ts`. */
+        if (name === 'REFLECTION_SURFACE') {
+            constants[String(id)] = reflectionSurface ? 1 : 0;
+            continue;
+        }
         if (!(name in cache.litSwitches)) {
             throw new Error(`flatPass: variant "${variant}" declares a switch "${name}" no cache sets`);
         }
@@ -185,6 +259,13 @@ function flatFragmentConstants(variant, cache, model, skinPass = 'whole') {
     }
     return constants;
 }
+/** The material block's binding, which every lit variant declares. */
+function materialBinding(fragment) {
+    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. */
@@ -194,11 +275,15 @@ 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, variant, skinned = false, morphed = false) {
+export function createFlatBindGroupLayout(device, variant, skinned = false, morphed = false, 
+/** The instanced variant that plays a bone animation: its three vertex textures. */
+animated = false) {
     const fragment = flatFragmentBindings(variant);
     const entries = [
         {
@@ -206,15 +291,31 @@ export function createFlatBindGroupLayout(device, variant, skinned = false, morp
             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. */
     const samplerKind = new Map();
@@ -355,11 +456,33 @@ export function createFlatBindGroupLayout(device, variant, skinned = false, morp
             });
         }
     }
+    /* 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() {
+    const textures = flatVertexBindings(false, false, true, true).textures;
+    const at = (name) => {
+        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')];
+}
 /**
  * Bind the buffers and one view per declared texture.
  *
@@ -369,20 +492,27 @@ export function createFlatBindGroupLayout(device, variant, skinned = false, morp
  * and WebGPU still requires something there, which is why `renderer.ts` keeps an
  * `emptyTexture2D` for the same reason on the other side.
  */
-export function createFlatBindGroup(device, layout, variant, perDraw, perFrame, resolve, 
+export function createFlatBindGroup(device, layout, variant, perDraw, passes, materials, views, resolve, 
 /** The palette view for a skinned bind group, or null for an unskinned one. */
 palette = null, 
 /** The delta view for a morphed bind group, or null for an unmorphed one. */
 deltas = null, 
 /** A skinned bind group's cloth views — the draw's, or the stand-in where it sets none. */
-cloth = null) {
+cloth = null, 
+/** An animated instanced group's views. See `AnimationViews`. */
+animation = null) {
     const fragment = flatFragmentBindings(variant);
     const entries = [
         {
             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
        sampler, and a bind group that filled it fifteen times would be rejected. Every member
@@ -417,8 +547,14 @@ cloth = null) {
         entries.push({ binding: particlesAt, resource: cloth.particles });
         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,
     });
@@ -481,8 +617,15 @@ cloth = false,
 /** Which shading model its fragment stage shades by, null the standard. The key must carry it. */
 model = null, 
 /** Which half of a skin it draws. The key must carry it: `|ss`, `|sd` or `|sa`. See `SkinHalf`. */
-skinPass = 'whole') {
-    return cache.get(key, () => flatDescriptor(cache, device, layout, variant, key, present, translucent, skinned, morphed, depthWrite, depthLayer, instanced, oit, doubleSided, alphaToCoverage, skinEight, cloth, model, skinPass), true);
+skinPass = 'whole', 
+/**
+ * The reflection pass's surface half: the draw again, against its own depth, into the two
+ * 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) {
+    return cache.get(key, () => flatDescriptor(cache, device, layout, variant, key, present, translucent, skinned, morphed, depthWrite, depthLayer, instanced, oit, doubleSided, alphaToCoverage, skinEight, cloth, model, skinPass, reflectionSurface, animated), true);
 }
 /**
  * The same pipeline, compiled off the main thread.
@@ -562,10 +705,13 @@ oit = 'none',
 /** Culls nothing: a surface seen from both faces. */
 doubleSided = false, alphaToCoverage = false, skinEight = false, 
 /** Whether its vertex stage places vertices by a cloth binding. See `clothBinding.ts`. */
-cloth = false, model = null, skinPass = 'whole') {
+cloth = false, model = null, skinPass = 'whole', reflectionSurface = false, 
+/** An instanced pipeline that plays a bone animation. See `shaders/boneAnimation.ts`. */
+animated = false) {
     const offset = depthOffsetForLayer(depthLayer);
-    /* The diffuse and colour halves are the same surface again, into the blur's targets. */
-    const diffuseAlone = skinPass === 'diffuse' || skinPass === 'albedo';
+    /* The diffuse and colour halves are the same surface again, into the blur's targets; and so is
+       the reflection pass's surface half, into its two. */
+    const diffuseAlone = skinPass === 'diffuse' || skinPass === 'albedo' || reflectionSurface;
     return {
         label: key,
         layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
@@ -576,12 +722,12 @@ cloth = false, model = null, skinPass = 'whole') {
              * 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), skinEight, cloth, model === 'lightmap'),
+            constants: vertexConstants(flatVertexBindings(skinned, morphed, instanced, animated), skinEight, cloth, model === 'lightmap'),
         },
         fragment: {
             module: shaderModule(device, {
@@ -590,31 +736,33 @@ cloth = false, model = null, skinPass = 'whole') {
             }),
             entryPoint: 'main',
             /* Every variant declares it, so every lit pipeline may set it: see `PipelineCache`. */
-            constants: flatFragmentConstants(variant, cache, model, skinPass),
-            targets: [
-                oitTarget(oit) ??
-                    (translucent === 'additive'
-                        ? {
-                            format: cache.format,
-                            blend: {
-                                color: { srcFactor: 'src-alpha', dstFactor: 'one', operation: 'add' },
-                                alpha: { srcFactor: 'zero', dstFactor: 'one', operation: 'add' },
-                            },
-                        }
-                        : translucent
+            constants: flatFragmentConstants(variant, cache, model, skinPass, reflectionSurface),
+            targets: reflectionSurface
+                ? [null, { format: REFLECTION_SURFACE_FORMAT }, { format: REFLECTION_SURFACE_FORMAT }]
+                : [
+                    oitTarget(oit) ??
+                        (translucent === 'additive'
                             ? {
                                 format: cache.format,
                                 blend: {
-                                    color: {
-                                        srcFactor: 'src-alpha',
-                                        dstFactor: 'one-minus-src-alpha',
-                                        operation: 'add',
-                                    },
-                                    alpha: SCENE_ALPHA_COVERS,
+                                    color: { srcFactor: 'src-alpha', dstFactor: 'one', operation: 'add' },
+                                    alpha: { srcFactor: 'zero', dstFactor: 'one', operation: 'add' },
                                 },
                             }
-                            : { format: cache.format }),
-            ],
+                            : translucent
+                                ? {
+                                    format: cache.format,
+                                    blend: {
+                                        color: {
+                                            srcFactor: 'src-alpha',
+                                            dstFactor: 'one-minus-src-alpha',
+                                            operation: 'add',
+                                        },
+                                        alpha: SCENE_ALPHA_COVERS,
+                                    },
+                                }
+                                : { format: cache.format }),
+                ],
         },
         primitive: { topology: 'triangle-list', cullMode: doubleSided ? 'none' : 'back' },
         /* Coverage only where a sample count can carry it: WebGPU refuses it at one sample. */

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

@@ -1,6 +1,7 @@
 import type { CullSlot } from './instanceCullPass.ts';
 import type { MeshInstances } from '../../instances.ts';
 import type { GpuMesh } from './buffers.ts';
+import { GpuInstanceClocks, type GpuBoneAnimation } from './boneAnimations.ts';
 /**
  * One mesh's per-instance buffer on the device.
  *
@@ -25,7 +26,19 @@ export declare class GpuInstancedBatch {
     /** The frame the slots were last taken in, and how many were taken. */
     slotFrame: number;
     slotsTaken: number;
-    constructor(device: GPUDevice, mesh: GpuMesh, capacity: number, label: string, cull?: boolean);
+    /** 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: Map<GPUBindGroup, GPUBindGroup>;
+    readonly depthGroups: Map<unknown, GPUBindGroup>;
+    readonly depthPeelGroups: Map<unknown, GPUBindGroup>;
+    groupEpoch: number;
+    constructor(device: GPUDevice, mesh: GpuMesh, capacity: number, label: string, cull?: boolean, animation?: GpuBoneAnimation | null);
     /** Last frame's packed slots, for a reconstruction; made on first use by the renderer. */
     previousBuffer: GPUBuffer | null;
     /** How many slots the upload before the last one held, and how many the last one holds. */

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

@@ -1,6 +1,8 @@
 import { instancesBox } from '../../instanceCull.js';
 import { INSTANCE_FLOATS, INSTANCE_STRIDE, packInstances } from '../../instances.js';
 import { destroySlot } from './instanceCullPass.js';
+import { packInstanceClocks } from '../../boneAnimation.js';
+import { GpuInstanceClocks } from './boneAnimations.js';
 /** VERTEX | COPY_DST, spelled the way every other pass here spells it. */
 const USAGE_VERTEX = 0x0020 | 0x0008;
 /** A culling batch's source is read by the cull as storage too. */
@@ -29,10 +31,26 @@ export class GpuInstancedBatch {
     /** The frame the slots were last taken in, and how many were taken. */
     slotFrame = -1;
     slotsTaken = 0;
-    constructor(device, mesh, capacity, label, cull = false) {
+    /** The bone animation every instance plays, and its clocks; null for a batch that plays none. */
+    animation;
+    clocks;
+    /**
+     * 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`.
+     */
+    litGroups = new Map();
+    depthGroups = new Map();
+    depthPeelGroups = new Map();
+    groupEpoch = -1;
+    constructor(device, mesh, capacity, label, cull = false, animation = 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({
             /*
@@ -76,10 +94,15 @@ export class GpuInstancedBatch {
             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() {
         this.previousBuffer?.destroy();
         this.buffer.destroy();
+        this.clocks?.dispose();
         for (const slot of this.slots)
             destroySlot(slot);
     }

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

@@ -0,0 +1,101 @@
+import type { BudgetCounter } from '../budget.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 declare class MaterialStore {
+    private readonly device;
+    private readonly usage;
+    private readonly label;
+    private readonly budget;
+    /** 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;
+    private readonly stride;
+    private capacity;
+    private staging;
+    private ints;
+    /** Per slot: its block's hash, the next slot in its bucket or -1, and whether it holds one. */
+    private hashes;
+    private next;
+    private held;
+    /** Per slot: the frame that last asked for it, and whether it was written since the last flush. */
+    private askedIn;
+    private pending;
+    /** Per slot: how many holders pinned it. A pinned slot is never displaced. */
+    private pins;
+    /**
+     * 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: number;
+    /** Per bucket: its first slot, or -1. A power of two at least twice the slots. */
+    private heads;
+    private mask;
+    private lowPending;
+    private highPending;
+    private hand;
+    /** Starts past zero, so a slot never asked for reads as long unasked. */
+    private frame;
+    constructor(device: GPUDevice, bytesPerBlock: number, slots: number, usage: number, label?: string, budget?: BudgetCounter | null);
+    /** How many distinct blocks a frame may hold. */
+    get slots(): number;
+    /** Start a frame: every slot the last one asked for may be displaced from here on, last. */
+    beginFrame(): void;
+    /**
+     * 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;
+    /** Upload every slot written since the last flush, one write per run of neighbouring slots. */
+    flush(): void;
+    /**
+     * 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;
+    /**
+     * 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;
+    unpin(offset: number): void;
+    dispose(): void;
+    private holds;
+    /**
+     * 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;
+    private unlink;
+}
+/**
+ * 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 declare function hashWords(block: Int32Array, words: number): number;