@jbrowse/render-core 4.3.0 → 5.0.0-beta.10

package/esm/hal/deviceGpuCache.js

@@ -1,120 +1,111 @@
 /// <reference types="@webgpu/types" />
+import { STANDARD_BLEND_STATE, stageVisibility, toGpuVertexFormat, } from '../webgpuUtils.js';
+// A device's layouts and pipelines, shared by every WebGPUHal on it. Held per
+// module copy rather than on the `globalThis` cell: a second bundled copy
+// builds a duplicate set, never a wrong one, since WebGPU compares layouts
+// structurally.
+const perDevice = new WeakMap();
 /**
- * The GPU objects that belong to the **device** rather than to one `WebGPUHal`,
- * memoized so the second display of a track type builds none of them.
- *
- * WebGL2 has no equivalent and wants none: a program is owned by the context
- * that linked it, and each display owns a context, so nothing there is
- * shareable. WebGPU inverts that — `gpuDevice.ts` hands every display one
- * device, and a `GPURenderPipeline` is a device object — and until this module
- * the HAL kept building per-display copies anyway. Ten alignments tracks
- * compiled 230 pipelines for 23 distinct programs.
- *
- * **The key is the descriptor object, and that is what makes it correct.** A
- * plugin's pass list is a module-level const (`ALIGNMENTS_PASSES`) and
- * `slangPass` reads `wgslSource` off a generated module const, so every display
- * of a type hands the HAL the *same* `PipelineDescriptor` objects by reference.
- * Identity therefore means "same shader, same layout, same blend, same
- * topology" without comparing any of them, and two passes that merely share a
- * `.slang` shape module (MAF and multi-row both draw `rowRect`) get separate
- * entries because `slangPass` built them separate objects. The **sample count**
- * is the one pipeline input the descriptor cannot express, so it is the inner
- * key; see the `pipelines` field.
- *
- * The one field of a pipeline that is not on the descriptor is the uniform
- * size, and it cannot make two HALs disagree here:
- * `createUniformOnlyBindGroupLayout` declares no `minBindingSize`, so the
- * layout — and thus the pipeline built against it — is the same whatever a
- * display's `uniformByteSize` is. The size reaches the GPU through the bind
- * group's `size` and the dynamic offset, both of which stay per-HAL.
- *
- * Per copy of this module rather than on the `globalThis` cell, for the reason
- * `createHal.ts` gives for `warnedSoftwareRasterizer`: a second bundled copy
- * builds a second set, which costs a duplicate and never a wrong answer.
- * Layouts compare structurally in WebGPU, so a bind group from one copy is
- * valid against a pipeline from the other.
+ * A render pass's bind-group layout, read off its shader's reflected table:
+ * each binding visible to exactly the stages that read it, so the layout
+ * cannot disagree with the shader about which stage reads what. The uniform
+ * block takes a dynamic offset into the HAL's ring.
  */
-const perDevice = new WeakMap();
-function createLayouts(device) {
-    const uniformEntry = {
-        binding: 1,
-        visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT,
-        buffer: { type: 'uniform', hasDynamicOffset: true },
-    };
-    const uniformOnlyBindGroupLayout = device.createBindGroupLayout({
-        entries: [uniformEntry],
-    });
-    const texturedBindGroupLayout = device.createBindGroupLayout({
-        entries: [
-            uniformEntry,
-            {
-                binding: 2,
-                visibility: GPUShaderStage.FRAGMENT,
-                texture: { sampleType: 'float' },
-            },
-            {
-                binding: 3,
-                visibility: GPUShaderStage.FRAGMENT,
-                sampler: { type: 'filtering' },
-            },
-        ],
+export function bindGroupLayoutEntries(bindings) {
+    return bindings.map((b) => {
+        const at = { binding: b.index, visibility: stageVisibility(b.stages) };
+        switch (b.kind) {
+            case 'uniform':
+                return { ...at, buffer: { type: 'uniform', hasDynamicOffset: true } };
+            case 'texture':
+                return { ...at, texture: { sampleType: 'float' } };
+            case 'sampler':
+                return { ...at, sampler: { type: 'filtering' } };
+            default:
+                throw new Error(`a render pass binds no ${b.kind}, and '${b.name}' is one at ` +
+                    `binding ${b.index}`);
+        }
     });
+}
+function gpuBlendState(bs) {
+    // WebGPU rejects any factor but 'one' under max and min, which ignore them.
+    // Alpha takes the same equation, as webgl2Hal's applyBlendState does.
+    const max = { srcFactor: 'one', dstFactor: 'one', operation: 'max' };
+    const min = { srcFactor: 'one', dstFactor: 'one', operation: 'min' };
+    const behind = { srcFactor: 'one-minus-dst-alpha', dstFactor: 'one' };
+    return bs.op === 'max'
+        ? { color: max, alpha: max }
+        : bs.op === 'min'
+            ? { color: min, alpha: min }
+            : bs.op === 'behind'
+                ? { color: behind, alpha: behind }
+                : {
+                    color: { srcFactor: bs.srcFactor, dstFactor: bs.dstFactor },
+                    alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha' },
+                };
+}
+export function pipelineRecipe(desc, wgslSource, sampleCount) {
     return {
-        uniformOnlyBindGroupLayout,
-        uniformOnlyPipelineLayout: device.createPipelineLayout({
-            bindGroupLayouts: [uniformOnlyBindGroupLayout],
-        }),
-        texturedBindGroupLayout,
-        texturedPipelineLayout: device.createPipelineLayout({
-            bindGroupLayouts: [texturedBindGroupLayout],
-        }),
+        wgslSource,
+        bindGroupLayout: bindGroupLayoutEntries(desc.bindings),
+        vertexBuffer: {
+            arrayStride: desc.instanceStride,
+            stepMode: 'instance',
+            attributes: desc.vertexAttributes.map((attr, i) => ({
+                shaderLocation: i,
+                offset: attr.offsetBytes,
+                format: toGpuVertexFormat(attr),
+            })),
+        },
+        blend: desc.blend
+            ? desc.blendState
+                ? gpuBlendState(desc.blendState)
+                : STANDARD_BLEND_STATE
+            : undefined,
+        topology: desc.topology ?? 'triangle-list',
+        sampleCount,
     };
 }
 function cacheFor(device) {
     let entry = perDevice.get(device);
     if (!entry) {
-        entry = { layouts: createLayouts(device), pipelines: new WeakMap() };
+        entry = { layouts: new Map(), pipelines: new Map() };
         perDevice.set(device, entry);
     }
     return entry;
 }
-/**
- * The bind group and pipeline layouts for `device`, built once per device.
- *
- * A device that is lost drops out of the map with itself — `gpuDevice.ts`
- * releases its reference in the `.lost` handler and the next acquisition is a
- * new object, so the layouts and pipelines built against the dead one are
- * unreachable and there is no cache to invalidate by hand.
- */
-export function getDeviceLayouts(device) {
-    return cacheFor(device).layouts;
+export function getPassLayout(device, entries) {
+    const { layouts } = cacheFor(device);
+    const key = JSON.stringify(entries);
+    let layout = layouts.get(key);
+    if (!layout) {
+        const bindGroupLayout = device.createBindGroupLayout({ entries });
+        layout = {
+            bindGroupLayout,
+            pipelineLayout: device.createPipelineLayout({
+                bindGroupLayouts: [bindGroupLayout],
+            }),
+        };
+        layouts.set(key, layout);
+    }
+    return layout;
 }
-/**
- * The pipeline for `desc` at `sampleCount` on `device`, building it through
- * `build` on the first ask and handing every later one the same promise.
- *
- * `build` receives the sample count rather than closing over one, so the key
- * and the pipeline stored under it cannot disagree.
- */
-export function getOrBuildPipeline(device, desc, sampleCount, build) {
-    const { layouts, pipelines } = cacheFor(device);
-    let bySampleCount = pipelines.get(desc);
-    if (!bySampleCount) {
-        bySampleCount = new Map();
-        pipelines.set(desc, bySampleCount);
+export function getOrBuildPipeline(device, recipe, build) {
+    const { pipelines } = cacheFor(device);
+    const { wgslSource, ...rest } = recipe;
+    let bySource = pipelines.get(wgslSource);
+    if (!bySource) {
+        bySource = new Map();
+        pipelines.set(wgslSource, bySource);
     }
-    let pipeline = bySampleCount.get(sampleCount);
+    const key = JSON.stringify(rest);
+    let pipeline = bySource.get(key);
     if (!pipeline) {
-        pipeline = build(layouts, sampleCount);
-        bySampleCount.set(sampleCount, pipeline);
+        pipeline = build(recipe);
+        bySource.set(key, pipeline);
     }
     return pipeline;
 }
-/**
- * Drop every device's entry. Tests only — nothing in the app invalidates this
- * cache, because losing the device is what invalidates it (see
- * {@link getDeviceLayouts}).
- */
 export function resetDeviceGpuCacheForTests(device) {
     perDevice.delete(device);
 }

package/esm/hal/gpuHalBase.d.ts

@@ -1,6 +1,6 @@
 import { OomReporter } from './oomReporter.ts';
 import { RegionRegistry } from './regionRegistry.ts';
-import type { PipelineDescriptor, TextureBinding } from './types.ts';
+import type { PipelineDescriptor, TextureBinding, TextureSource } from './types.ts';
 /**
  * The device ceilings the shared upload shells refuse past. WebGPU asks the
  * device, WebGL2 has no such parameter for buffers and carries its own constant
@@ -31,6 +31,7 @@ export declare abstract class GpuHalBase<Buf extends {
     protected descriptors: Map<string, PipelineDescriptor>;
     protected regions: RegionRegistry<Buf>;
     protected oom: OomReporter;
+    readonly uniformByteSize: number;
     protected disposed: boolean;
     constructor(descriptors: PipelineDescriptor[], halName: string);
     protected abstract limits(): HalLimits;
@@ -41,7 +42,7 @@ export declare abstract class GpuHalBase<Buf extends {
      * reached for a pass that declares a binding, and only within
      * `maxTextureDimensionPx`.
      */
-    protected abstract createTexture(passId: string, binding: TextureBinding, data: Uint8Array, width: number, height: number): void;
+    protected abstract createTexture(passId: string, binding: TextureBinding, data: TextureSource, width: number, height: number): void;
     /** Release this HAL's own GPU objects. Runs exactly once, from `dispose`. */
     protected abstract releaseResources(): void;
     setErrorHandler(handler: (error: Error) => void): void;
@@ -49,7 +50,7 @@ export declare abstract class GpuHalBase<Buf extends {
     getBufferCount(regionKey: number, passId: string): number;
     deleteBuffer(regionKey: number, passId: string): void;
     deleteRegion(regionKey: number): void;
-    pruneRegions(active: Iterable<number>): void;
-    uploadTexture(passId: string, data: Uint8Array, width: number, height: number): void;
+    uploadTexture(passId: string, data: TextureSource, width: number, height: number, sampler?: string): void;
+    protected textureBinding(passId: string, sampler?: string): TextureBinding;
     dispose(): void;
 }

package/esm/hal/gpuHalBase.js

@@ -19,11 +19,13 @@ export class GpuHalBase {
     descriptors;
     regions;
     oom;
+    uniformByteSize;
     // Guards dispose() against double invocation (pagehide + React cleanup can
     // both fire).
     disposed = false;
     constructor(descriptors, halName) {
         this.descriptors = new Map(descriptors.map(d => [d.id, d]));
+        this.uniformByteSize = Math.max(0, ...descriptors.map(d => d.uniformByteSize));
         this.oom = new OomReporter(halName);
         this.regions = new RegionRegistry(buf => {
             this.destroyBuffer(buf);
@@ -55,22 +57,31 @@ export class GpuHalBase {
     deleteRegion(regionKey) {
         this.regions.deleteRegion(regionKey);
     }
-    pruneRegions(active) {
-        this.regions.prune(active);
+    uploadTexture(passId, data, width, height, sampler) {
+        const binding = this.textureBinding(passId, sampler);
+        const { maxTextureDimensionPx } = this.limits();
+        if (width > maxTextureDimensionPx || height > maxTextureDimensionPx) {
+            this.oom.report(`This region is too large to render on this GPU — zoom in. (texture ${width}×${height} exceeds max texture size ${maxTextureDimensionPx})`);
+        }
+        else {
+            this.createTexture(passId, binding, data, width, height);
+        }
     }
-    uploadTexture(passId, data, width, height) {
-        // Read the binding off the descriptor, so a pass with no texture is
-        // answered without touching the backend's pipeline state at all.
-        const binding = this.descriptors.get(passId)?.textures?.[0];
-        if (binding) {
-            const { maxTextureDimensionPx } = this.limits();
-            if (width > maxTextureDimensionPx || height > maxTextureDimensionPx) {
-                this.oom.report(`This region is too large to render on this GPU — zoom in. (texture ${width}×${height} exceeds max texture size ${maxTextureDimensionPx})`);
-            }
-            else {
-                this.createTexture(passId, binding, data, width, height);
-            }
+    textureBinding(passId, sampler) {
+        const textures = this.descriptors.get(passId)?.textures ?? [];
+        const binding = sampler === undefined
+            ? textures.length === 1
+                ? textures[0]
+                : undefined
+            : textures.find(t => t.name === sampler);
+        if (!binding) {
+            const names = textures.map(t => `'${t.name}'`).join(', ');
+            const has = names ? `samples ${names}` : 'samples no texture';
+            throw new Error(sampler === undefined
+                ? `uploadTexture: pass '${passId}' ${has}; name the sampler this texture is for`
+                : `uploadTexture: pass '${passId}' has no sampler '${sampler}'; it ${has}`);
         }
+        return binding;
     }
     dispose() {
         if (!this.disposed) {

package/esm/hal/index.d.ts

@@ -1,7 +1,7 @@
 export { createGpuHal } from './createHal.ts';
-export { MockHal } from './mockHal.ts';
+export { MOCK_SHADER_SOURCE, MockHal } from './mockHal.ts';
 export { assertUniquePassIds } from './passIds.ts';
 export { WebGL2Hal } from './webgl2Hal.ts';
 export { WebGPUHal } from './webgpuHal.ts';
 export type { GpuHalOptions } from './createHal.ts';
-export type { BlendState, VertexAttributeLayout, GpuHal, PipelineDescriptor, SampleCount, ShaderBinding, TextureBinding, } from './types.ts';
+export type { BlendState, VertexAttributeLayout, GpuHal, PipelineDescriptor, SampleCount, ShaderBinding, ShaderSource, ShaderStage, TextureBinding, TextureSource, } from './types.ts';

package/esm/hal/index.js

@@ -1,5 +1,5 @@
 export { createGpuHal } from './createHal.js';
-export { MockHal } from './mockHal.js';
+export { MOCK_SHADER_SOURCE, MockHal } from './mockHal.js';
 export { assertUniquePassIds } from './passIds.js';
 export { WebGL2Hal } from './webgl2Hal.js';
 export { WebGPUHal } from './webgpuHal.js';

package/esm/hal/mockHal.d.ts

@@ -1,5 +1,7 @@
 import { GpuHalBase } from './gpuHalBase.ts';
-import type { GpuHal, PipelineDescriptor, TextureBinding } from './types.ts';
+import type { GpuHal, PipelineDescriptor, ShaderSource, TextureBinding, TextureSource } from './types.ts';
+/** Text for a pass built only for a `MockHal`, which never loads it. */
+export declare const MOCK_SHADER_SOURCE: ShaderSource;
 export interface MockCall {
     method: string;
     args: unknown[];
@@ -17,7 +19,7 @@ export interface MockRect {
 /**
  * One draw, with the state that was in force when it was issued — the clip, and
  * which `writeUniforms` it reads. `null` scissor/viewport means unclipped, the
- * full canvas, which is what both HALs owe after a `clearScissor` /
+ * full canvas, the state both HALs must restore after a `clearScissor` /
  * `clearViewport`.
  *
  * `uniformWrite` indexes {@link MockHal.getUniformWritesF32}, or is `-1` when
@@ -32,13 +34,15 @@ export interface MockRect {
  * does an immediate `bufferSubData` into one UBO. They agree only while a
  * renderer writes then draws, which is the convention every renderer in tree
  * follows and nothing enforces: batching the writes and then issuing the draws
- * is right on WebGL2 and Canvas2D and silently wrong on WebGPU. This field is
- * what lets a backend test pin its renderer's pairing.
+ * is right on WebGL2 and Canvas2D and wrong on WebGPU, where the draws read the
+ * last write. `uniformWrite` lets a backend test pin its renderer's pairing.
  */
 export interface MockDraw {
     passId: string;
     regionKey: number;
     bufferPassId: string | undefined;
+    /** The vertex count the draw asked for, its descriptor's where it asked for none. */
+    verticesPerInstance: number;
     scissor: MockRect | null;
     viewport: MockRect | null;
     uniformWrite: number;
@@ -59,8 +63,8 @@ export declare class MockHal extends GpuHalBase<MockBuffer> implements GpuHal {
      * rect without re-issuing a full-canvas one, so every draw after it went on
      * being clipped to the previous block while WebGL2 drew them unclipped — right
      * on Canvas2D, right on WebGL2, wrong on WebGPU alone. Nothing in tree clears
-     * mid-frame today, which is exactly why nothing caught it. Recording the
-     * effective clip per draw is what makes that assertable at all.
+     * mid-frame today, so no test caught it. Recording the effective clip per draw
+     * makes that assertable.
      */
     private scissor;
     private viewport;
@@ -90,7 +94,7 @@ export declare class MockHal extends GpuHalBase<MockBuffer> implements GpuHal {
     };
     protected destroyBuffer(): void;
     private textures;
-    protected createTexture(passId: string, _binding: TextureBinding, data: Uint8Array, width: number, height: number): void;
+    protected createTexture(passId: string, binding: TextureBinding, data: TextureSource, width: number, height: number): void;
     protected releaseResources(): void;
     private record;
     errorHandler: ((error: Error) => void) | null;
@@ -99,15 +103,15 @@ export declare class MockHal extends GpuHalBase<MockBuffer> implements GpuHal {
         x: number;
         y: number;
     };
+    releaseRenderTargets(): void;
     uploadBuffer(regionKey: number, passId: string, data: ArrayBuffer | ArrayBufferView, count: number): void;
     deleteBuffer(regionKey: number, passId: string): void;
     deleteRegion(regionKey: number): void;
-    pruneRegions(active: Iterable<number>): void;
     private noteReplaced;
     private noteRegionReplaced;
     writeUniforms(data: ArrayBuffer): void;
     beginFrame(clearR: number, clearG: number, clearB: number, clearA?: number): void;
-    drawPass(passId: string, regionKey: number, bufferPassId?: string): void;
+    drawPass(passId: string, regionKey: number, bufferPassId?: string, verticesPerInstance?: number): void;
     private assertRegistered;
     endFrame(): void;
     setScissor(x: number, y: number, w: number, h: number): void;
@@ -121,7 +125,8 @@ export declare class MockHal extends GpuHalBase<MockBuffer> implements GpuHal {
     getUniformWritesF32(): Float32Array<ArrayBuffer>[];
     getUniformWritesU32(): Uint32Array<ArrayBuffer>[];
     getBuffer(regionKey: number, passId: string): MockBuffer | undefined;
-    getTexture(passId: string): Uint8Array<ArrayBufferLike> | undefined;
+    /** What the pass's `sampler` samples, named as `uploadTexture` names it. */
+    getTexture(passId: string, sampler?: string): TextureSource | undefined;
     callsOf(method: string): MockCall[];
     /**
      * Every draw of the frame with the state it went out under, in order — the

package/esm/hal/mockHal.js

@@ -1,6 +1,14 @@
 import { getDpr } from '../canvas2dUtils.js';
 import { GpuHalBase } from './gpuHalBase.js';
 import { assertUniquePassIds } from './passIds.js';
+/** Text for a pass built only for a `MockHal`, which never loads it. */
+export const MOCK_SHADER_SOURCE = {
+    wgsl: () => Promise.resolve({ WGSL_SOURCE: '' }),
+    glsl: () => Promise.resolve({ GLSL_VERTEX: '', GLSL_FRAGMENT: '' }),
+};
+function textureKey(passId, sampler) {
+    return `${passId}\u0000${sampler}`;
+}
 export class MockHal extends GpuHalBase {
     calls = [];
     // Every write of the frame, in order, not just the last. A renderer that
@@ -23,8 +31,8 @@ export class MockHal extends GpuHalBase {
      * rect without re-issuing a full-canvas one, so every draw after it went on
      * being clipped to the previous block while WebGL2 drew them unclipped — right
      * on Canvas2D, right on WebGL2, wrong on WebGPU alone. Nothing in tree clears
-     * mid-frame today, which is exactly why nothing caught it. Recording the
-     * effective clip per draw is what makes that assertable at all.
+     * mid-frame today, so no test caught it. Recording the effective clip per draw
+     * makes that assertable.
      */
     scissor = null;
     viewport = null;
@@ -76,9 +84,10 @@ export class MockHal extends GpuHalBase {
     // reason the real HALs keep their texture: a test asserting which LUT a pass
     // samples needs the bytes, not the byteLength the call log records.
     textures = new Map();
-    createTexture(passId, _binding, data, width, height) {
-        this.textures.set(passId, data.slice());
-        this.record('uploadTexture', passId, data.byteLength, width, height);
+    createTexture(passId, binding, data, width, height) {
+        const bytes = data instanceof Uint8Array;
+        this.textures.set(textureKey(passId, binding.name), bytes ? data.slice() : data);
+        this.record('uploadTexture', passId, bytes ? data.byteLength : 'canvas', width, height, binding.name);
     }
     releaseResources() {
         this.record('dispose');
@@ -94,6 +103,9 @@ export class MockHal extends GpuHalBase {
         this.record('setErrorHandler');
     }
     resize(width, height) {
+        if (this.disposed) {
+            return { x: getDpr(), y: getDpr() };
+        }
         this.record('resize', width, height);
         // The real HALs report the scale their backing store actually got, and
         // every device-px rect a renderer builds comes from this — so a mock
@@ -101,6 +113,9 @@ export class MockHal extends GpuHalBase {
         // the unclamped answer, which is what a mock canvas of any size would get.
         return { x: getDpr(), y: getDpr() };
     }
+    releaseRenderTargets() {
+        this.record('releaseRenderTargets');
+    }
     // The overrides below log and then defer to the base's shells, so the buffer
     // lifecycle a test observes (delete-before-count, prune) is the same code both
     // real HALs run rather than a twin that can drift out of parity.
@@ -119,16 +134,6 @@ export class MockHal extends GpuHalBase {
         this.noteRegionReplaced(regionKey);
         super.deleteRegion(regionKey);
     }
-    pruneRegions(active) {
-        const activeSet = new Set(active);
-        this.record('pruneRegions', [...activeSet]);
-        for (const regionKey of this.drawnThisFrame.keys()) {
-            if (!activeSet.has(regionKey)) {
-                this.noteRegionReplaced(regionKey);
-            }
-        }
-        super.pruneRegions(activeSet);
-    }
     noteReplaced(regionKey, passId) {
         if (this.frameOpen && this.drawnThisFrame.get(regionKey)?.has(passId)) {
             this.replacedWhileDrawnLog.push(`${regionKey}:${passId}`);
@@ -168,11 +173,15 @@ export class MockHal extends GpuHalBase {
     // `bufferPassId` is checked too: `drawPass(a, key, b)` runs pass `a`'s
     // pipeline over pass `b`'s buffer, and every such pair in tree names two
     // registered passes (canvas's chevron over line, continuation over rect).
-    drawPass(passId, regionKey, bufferPassId) {
+    drawPass(passId, regionKey, bufferPassId, verticesPerInstance) {
         this.assertRegistered(passId, 'passId');
         if (bufferPassId !== undefined) {
             this.assertRegistered(bufferPassId, 'bufferPassId');
         }
+        const missing = (this.descriptors.get(passId)?.textures ?? []).some(t => !this.textures.has(textureKey(passId, t.name)));
+        if (missing) {
+            return;
+        }
         this.record('drawPass', passId, regionKey, bufferPassId);
         // The buffer the draw reads, which `bufferPassId` renames — that is the
         // resource a later upload in this frame would be replacing under it.
@@ -187,6 +196,8 @@ export class MockHal extends GpuHalBase {
             passId,
             regionKey,
             bufferPassId,
+            verticesPerInstance: verticesPerInstance ??
+                this.descriptors.get(passId).verticesPerInstance,
             scissor: this.scissor && { ...this.scissor },
             viewport: this.viewport && { ...this.viewport },
             uniformWrite: this.uniformWrites.length - 1,
@@ -244,8 +255,10 @@ export class MockHal extends GpuHalBase {
     getBuffer(regionKey, passId) {
         return this.regions.get(regionKey, passId);
     }
-    getTexture(passId) {
-        return this.textures.get(passId);
+    /** What the pass's `sampler` samples, named as `uploadTexture` names it. */
+    getTexture(passId, sampler) {
+        const { name } = this.textureBinding(passId, sampler);
+        return this.textures.get(textureKey(passId, name));
     }
     callsOf(method) {
         return this.calls.filter(c => c.method === method);

package/esm/hal/oomReporter.d.ts

@@ -12,4 +12,11 @@ export declare class OomReporter {
     constructor(hal: string);
     setHandler(handler: (error: Error) => void): void;
     report(message: string): void;
+    /**
+     * Report an error the HAL has already classified, for a failure whose remedy
+     * is not `report`'s "zoom in". Kept separate so the classification stays with
+     * the caller that knows it — flagging every over-limit allocation as a context
+     * loss would offer "Use Canvas2D" for a view that only needs zooming.
+     */
+    reportClassified(error: Error): void;
 }

package/esm/hal/oomReporter.js

@@ -19,4 +19,14 @@ export class OomReporter {
         console.error(`[${this.hal}] ${message}`);
         this.handler?.(new Error(message));
     }
+    /**
+     * Report an error the HAL has already classified, for a failure whose remedy
+     * is not `report`'s "zoom in". Kept separate so the classification stays with
+     * the caller that knows it — flagging every over-limit allocation as a context
+     * loss would offer "Use Canvas2D" for a view that only needs zooming.
+     */
+    reportClassified(error) {
+        console.error(`[${this.hal}] ${error.message}`);
+        this.handler?.(error);
+    }
 }

package/esm/hal/passIds.d.ts

@@ -2,13 +2,14 @@ import type { PipelineDescriptor } from './types.ts';
 /**
  * Throw if two passes in one display's registry share an `id`.
  *
- * A pass id is two keys at once — the pipeline (`pipelines.set(desc.id, …)` in
- * both HALs) and the instance buffer (`uploadBuffer(regionKey, passId, …)`).
- * A duplicate therefore collides both: the second registration replaces the
- * first's pipeline, both passes upload to one buffer so the last write wins,
- * and whichever shader has the larger stride reads off the end of it. No
- * validation error, no throw, no failing test — just wrong pixels on the GPU
- * backends while Canvas2D keeps drawing correctly.
+ * A pass id names a slot: the descriptor a draw of that id uses, its instance
+ * buffer per region, and its texture. Compiled pipelines and programs are keyed
+ * by content instead, so a second id over one shader costs no compile. A
+ * duplicate id collides the slot: the later descriptor answers every draw of
+ * it, both passes upload to one buffer so the last write wins, and whichever
+ * shader has the larger stride reads off the end of it. No validation error, no
+ * throw, no failing test — just wrong pixels on the GPU backends while Canvas2D
+ * keeps drawing correctly.
  *
  * Nothing structural stops it. A display's pass list is concatenated from
  * several registries (`ALIGNMENTS_PASSES` merges three plus a standalone

package/esm/hal/passIds.js

@@ -1,13 +1,14 @@
 /**
  * Throw if two passes in one display's registry share an `id`.
  *
- * A pass id is two keys at once — the pipeline (`pipelines.set(desc.id, …)` in
- * both HALs) and the instance buffer (`uploadBuffer(regionKey, passId, …)`).
- * A duplicate therefore collides both: the second registration replaces the
- * first's pipeline, both passes upload to one buffer so the last write wins,
- * and whichever shader has the larger stride reads off the end of it. No
- * validation error, no throw, no failing test — just wrong pixels on the GPU
- * backends while Canvas2D keeps drawing correctly.
+ * A pass id names a slot: the descriptor a draw of that id uses, its instance
+ * buffer per region, and its texture. Compiled pipelines and programs are keyed
+ * by content instead, so a second id over one shader costs no compile. A
+ * duplicate id collides the slot: the later descriptor answers every draw of
+ * it, both passes upload to one buffer so the last write wins, and whichever
+ * shader has the larger stride reads off the end of it. No validation error, no
+ * throw, no failing test — just wrong pixels on the GPU backends while Canvas2D
+ * keeps drawing correctly.
  *
  * Nothing structural stops it. A display's pass list is concatenated from
  * several registries (`ALIGNMENTS_PASSES` merges three plus a standalone
@@ -29,8 +30,8 @@ export function assertUniquePassIds(passes) {
     }
     if (duplicates.size > 0) {
         throw new Error(`duplicate pass id(s) ${[...duplicates].map(id => `'${id}'`).join(', ')}` +
-            ` — a pass id keys both the pipeline and the instance buffer, so two` +
-            ` passes sharing one draw each other's instances through their own` +
-            ` shader. Rename one.`);
+            ` — a pass id keys the descriptor, the instance buffer and the` +
+            ` texture, so two passes sharing one draw each other's instances` +
+            ` through one shader. Rename one.`);
     }
 }

package/esm/hal/regionRegistry.d.ts

@@ -7,5 +7,4 @@ export declare class RegionRegistry<Buf> {
     deleteBuffer(regionKey: number, passId: string): void;
     deleteRegion(regionKey: number): void;
     deleteAll(): void;
-    prune(active: Iterable<number>): void;
 }