@jbrowse/render-core 5.0.0-beta.8 → 5.0.0-beta.9

package/esm/hal/deviceGpuCache.js

@@ -1,120 +1,108 @@
 /// <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 descriptor's `uniformByteSize` never reaches the pipeline, so 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, which ignores them. Alpha
+    // accumulates as webgl2Hal's applyBlendState does.
+    const max = { srcFactor: 'one', dstFactor: 'one', operation: 'max' };
+    const behind = { srcFactor: 'one-minus-dst-alpha', dstFactor: 'one' };
+    return bs.op === 'max'
+        ? { color: max, alpha: max }
+        : 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/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, TextureSource, } 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, TextureSource } 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,8 +34,8 @@ 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;
@@ -59,8 +61,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;

package/esm/hal/mockHal.js

@@ -1,6 +1,11 @@
 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: '' }),
+};
 export class MockHal extends GpuHalBase {
     calls = [];
     // Every write of the frame, in order, not just the last. A renderer that
@@ -23,8 +28,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;

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/types.d.ts

@@ -39,21 +39,25 @@ export type BlendState = {
     dstFactor: BlendFactor;
 } | {
     op: 'max';
+} | {
+    op: 'behind';
 };
+export type ShaderStage = 'vertex' | 'fragment' | 'compute';
 /**
  * One entry of a shader's GPU binding table, as the Slang codegen reflects it.
  *
- * `kind` is spelled the way WebGPU spells it so a consumer can build a
- * `createBindGroupLayout` entry from it directly. That is the point: the binding
- * indices used to be asserted by hand in three places that never consulted the
- * shader — this HAL's two hardcoded render layouts, and the LD compute driver's
- * own. A shader's `BINDINGS` export is the reflected truth, and `pnpm
- * gen:shaders` now refuses a render shader whose table is not one the HALs bind.
+ * `kind` is spelled the way WebGPU spells it and `stages` names the entry
+ * points that read the binding, so a consumer builds a `createBindGroupLayout`
+ * entry from it directly, `visibility` included. The WebGPU HAL and the compute
+ * driver both do. `pnpm gen:shaders` refuses a render shader whose table is not
+ * one the HALs bind, and a `stages` that leaves out a stage the emitted WGSL
+ * reads the binding in.
  */
 export interface ShaderBinding {
     index: number;
     kind: 'uniform' | 'texture' | 'sampler' | 'storage' | 'read-only-storage';
     name: string;
+    stages: readonly ShaderStage[];
 }
 /**
  * What a pass's texture is filled from: RGBA bytes, or a canvas whose pixels
@@ -63,12 +67,26 @@ export interface ShaderBinding {
  */
 export type TextureSource = Uint8Array | HTMLCanvasElement | OffscreenCanvas;
 export interface TextureBinding {
-    textureBinding: number;
-    samplerBinding: number;
     glTextureUnit: number;
     glUniformName: string;
     filter: 'linear' | 'nearest';
 }
+/**
+ * A shader's compiled text, one loader per target. `pnpm gen:shaders` emits it
+ * as a shader module's `SOURCE`, each loader an `import()` of a module holding
+ * nothing but that target's strings, so no realm evaluates shader text until a
+ * HAL is built with the pass: WebGPU loads the WGSL, WebGL2 the GLSL, Canvas2D
+ * neither, and the RPC worker never builds one.
+ */
+export interface ShaderSource {
+    wgsl: () => Promise<{
+        WGSL_SOURCE: string;
+    }>;
+    glsl: () => Promise<{
+        GLSL_VERTEX: string;
+        GLSL_FRAGMENT: string;
+    }>;
+}
 /**
  * A **pipeline state object (PSO)**: shaders, vertex input layout, blend state,
  * primitive topology and texture bindings, baked into one immutable
@@ -83,9 +101,7 @@ export interface TextureBinding {
  */
 export interface PipelineDescriptor {
     id: string;
-    wgslSource: string;
-    glslVertex: string;
-    glslFragment: string;
+    source: ShaderSource;
     instanceStride: number;
     /** Bytes of the uniform block the shader binds; the HAL's slot is the largest over its passes. */
     uniformByteSize: number;
@@ -96,7 +112,7 @@ export interface PipelineDescriptor {
     topology?: 'triangle-list' | 'triangle-strip' | 'line-list';
     coverage?: 'analytic';
     textures?: readonly [TextureBinding, ...TextureBinding[]];
-    bindings?: readonly ShaderBinding[];
+    bindings: readonly ShaderBinding[];
 }
 export interface GpuHal {
     /** The uniform slot size, the largest block any registered pass binds. */

package/esm/hal/webgl2Hal.d.ts

@@ -8,6 +8,9 @@ export declare class WebGL2Hal extends GpuHalBase<RegionPassBuffer> implements G
     private gl;
     private canvas;
     private passes;
+    private glsl;
+    private programs;
+    private passTextures;
     private ubo;
     private maxTextureDim;
     private debug;
@@ -17,7 +20,12 @@ export declare class WebGL2Hal extends GpuHalBase<RegionPassBuffer> implements G
     private contextLostListener;
     private contextRestoredListener;
     private checkGlError;
-    constructor(canvas: HTMLCanvasElement, descriptors: PipelineDescriptor[]);
+    /**
+     * Loads every pass's GLSL before the context is acquired, so a load that
+     * fails leaves the canvas free for Canvas2D.
+     */
+    static create(canvas: HTMLCanvasElement, descriptors: PipelineDescriptor[]): Promise<WebGL2Hal>;
+    private constructor();
     protected limits(): {
         maxBufferBytes: number;
         maxTextureDimensionPx: number;
@@ -27,7 +35,7 @@ export declare class WebGL2Hal extends GpuHalBase<RegionPassBuffer> implements G
         count: number;
     };
     protected destroyBuffer(buf: RegionPassBuffer): void;
-    private compilePass;
+    private link;
     private getPass;
     resize(width: number, height: number): import("./types.ts").CanvasScale;
     protected createTexture(passId: string, binding: TextureBinding, data: TextureSource, width: number, height: number): void;
@@ -41,7 +49,7 @@ export declare class WebGL2Hal extends GpuHalBase<RegionPassBuffer> implements G
     endFrame(): void;
     protected releaseResources(): void;
     private applyBlendState;
-    private bindTextures;
+    private bindTexture;
     private bindAttributes;
 }
 export {};