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

package/esm/hal/webgl2Hal.js

@@ -43,8 +43,7 @@ function bindUniformBlock(gl, program, blockName, bindingPoint) {
         gl.uniformBlockBinding(program, idx, bindingPoint);
     }
 }
-// Set `DEBUG.webgl2 = true` in devtools (or `?webgl2-debug=1` in URL) to
-// enable verbose logging. Kept guarded so production builds stay quiet.
+// `DEBUG.webgl2 = true` in devtools, or `?webgl2-debug=1`, logs verbosely.
 function debugEnabled() {
     if (typeof window === 'undefined') {
         return false;
@@ -91,59 +90,33 @@ function glBlendFactor(gl, factor) {
             return gl.ONE_MINUS_SRC_ALPHA;
     }
 }
-// Module-scope lifecycle tracking — Firefox caps active WebGL contexts
-// around 16 and Chrome around 8. Context leaks force the oldest contexts to
-// lose. These counters surface the leak when it happens.
+// Live-context counts for the debug log: a leaked context evicts the oldest
+// once the browser's cap is reached.
 let totalCreated = 0;
 let totalDisposed = 0;
-// The vertex-buffer ceiling this HAL refuses past, in bytes.
-//
-// WebGL2 exposes no max-buffer-size parameter, so unlike WebGPU there is
-// nothing to ask — but "ask the driver" was never what the guard was for. Its
-// job is to turn one pathological upload into the "zoom in" banner, and without
-// it the same upload that banners on WebGPU takes Chrome's context down here
-// instead. That is strictly worse than a blank track on a page at the context
-// ceiling: the loss evicts a sibling, whose recovery evicts another, and
-// GPU_CONTEXT_BUDGET.md is that cascade.
-//
-// 256 MiB is WebGPU's *spec default* `maxBufferSize`. It is not parity with
-// what the WebGPU backend actually refuses at: `gpuDevice.acquire` raises the
-// limit to `adapter.limits.maxBufferSize`, which is 2147483644 bytes (~2 GiB)
-// on the Firefox Nightly / Intel UHD 630 this was checked on, so WebGL2 is the
-// stricter of the two and a region can banner here while rendering there. That
-// asymmetry is accepted — a quarter-gigabyte single vertex buffer is not
-// something to hand an API that answers a failed allocation by dropping the
-// context.
-//
-// Deliberately a ceiling and not a budget: it catches the single upload
-// nothing else bounds, and says nothing about the total, which is
-// ARCHITECTURAL_LIMITS.md §"No session-level GPU memory budget".
+// WebGPU's spec-default `maxBufferSize`, since WebGL2 has none to query: an
+// upload past it banners rather than dropping the context
+// (ARCHITECTURAL_LIMITS.md).
 const MAX_VERTEX_BUFFER_BYTES = 256 * 1024 * 1024;
-// Behavioral parity with WebGPUHal is enforced by tests, not by this file:
-// products/jbrowse-web/browser-tests/compare-backends.ts pixel-diffs webgl vs
-// webgpu vs canvas2d output, and shared buffer bookkeeping is covered by
-// hal/regionRegistry.test.ts. Neither HAL is where attribute layout is checked —
-// `assertVertexInputsMatch` does that at `pnpm gen:shaders` time, per shader and
-// per target. Mirror any behavior change in webgpuHal.ts — and note that
-// `GpuHalBase` already holds the parts that were only ever mirrored: the
-// descriptor map, the buffer registry, both upload shells and their over-limit
-// wording, and the dispose guard.
 export class WebGL2Hal extends GpuHalBase {
     gl;
     canvas;
-    // Compiled passes, filled on demand by `getPass`. A pass whose program failed
-    // to build caches `null` so the failure is reported once, not every frame.
-    passes;
+    // `null` is a pass whose link failed, so it is reported once, not per frame.
+    passes = new Map();
+    glsl;
+    // By vertex source, then fragment source, attribute names and sampler as
+    // JSON: every pass id over one program shares it, and a failed link keeps
+    // its error.
+    programs = new Map();
+    passTextures = new Map();
     ubo;
-    // Asked once: `getParameter` is a synchronous driver query and `limits()` is
-    // now read on every upload, not only on a texture one.
+    // `getParameter` is a synchronous driver query; `limits()` runs per upload.
     maxTextureDim;
     debug = false;
     instanceId = 0;
     firstDrawSeen = new Set();
-    // Latched on context loss, never cleared. GL objects from before the loss are
-    // invalid even after restore — isContextLost()===false by then, so a live
-    // check alone can't guard dispose().
+    // Never cleared: GL objects from before a loss stay invalid after restore,
+    // when isContextLost() already answers false.
     contextWasLost = false;
     contextLostListener = null;
     contextRestoredListener = null;
@@ -156,9 +129,18 @@ export class WebGL2Hal extends GpuHalBase {
             console.error(`[WebGL2Hal] GL error at "${label}": ${glErrorName(this.gl, err)}`);
         }
     }
-    constructor(canvas, descriptors) {
+    /**
+     * Loads every pass's GLSL before the context is acquired, so a load that
+     * fails leaves the canvas free for Canvas2D.
+     */
+    static async create(canvas, descriptors) {
+        const glsl = await Promise.all(descriptors.map(async (d) => [d.id, await d.source.glsl()]));
+        return new WebGL2Hal(canvas, descriptors, new Map(glsl));
+    }
+    constructor(canvas, descriptors, glsl) {
         super(descriptors, 'WebGL2Hal');
         this.canvas = canvas;
+        this.glsl = glsl;
         this.debug = debugEnabled();
         totalCreated += 1;
         this.instanceId = totalCreated;
@@ -178,23 +160,14 @@ export class WebGL2Hal extends GpuHalBase {
         canvas.addEventListener('webglcontextrestored', onContextRestored, false);
         this.contextLostListener = onContextLost;
         this.contextRestoredListener = onContextRestored;
-        // premultipliedAlpha:true is required for correct AA edge blending.
-        // The canvas is cleared to (0,0,0,0) and drawn with SRC_ALPHA,ONE_MINUS_SRC_ALPHA
-        // blend, which produces premultiplied-alpha values in the framebuffer
-        // (edge pixel: rgb = color*alpha, a = alpha).  With premultipliedAlpha:true
-        // the browser compositor reads those as premultiplied and composites correctly:
-        //   output = fb.rgb + bg*(1-fb.a)
-        // With premultipliedAlpha:false the compositor treats them as straight alpha and
-        // multiplies rgb by alpha a second time, making AA edges appear too dark.
-        // The WebGPU HAL uses alphaMode:'premultiplied' for the same reason.
+        // The blend leaves premultiplied values in the framebuffer, which a
+        // straight-alpha compositor would darken at AA edges; WebGPU's alphaMode
+        // matches.
         const gl = canvas.getContext('webgl2', {
             antialias: true,
             premultipliedAlpha: true,
         });
         if (!gl) {
-            // Was a bare 'WebGL2 not supported', which is the wrong diagnosis for the
-            // case that actually reaches here in production: a re-init on a canvas the
-            // WebGPU rung already committed. See canvasContext.ts.
             throw canvasContextError(canvas, 'webgl2');
         }
         noteCanvasContext(canvas, 'webgl2');
@@ -203,29 +176,20 @@ export class WebGL2Hal extends GpuHalBase {
         this.ubo = gl.createBuffer();
         gl.bindBuffer(gl.UNIFORM_BUFFER, this.ubo);
         gl.bufferData(gl.UNIFORM_BUFFER, this.uniformByteSize, gl.DYNAMIC_DRAW);
-        this.passes = new Map();
-        // Programs are built on first use (see `getPass`), not here: a renderer
-        // declares every pass it could ever draw — alignments alone declares 21,
-        // most of them behind a colorBy/arc/per-base setting — and linking one
-        // costs tens of ms of driver time on the main thread. A profile of a
-        // three-track LGV linked 29 programs and drew with 14.
-        //
-        // The first descriptor still links eagerly as a canary, so a GL stack that
-        // can't compile our shaders at all throws from the constructor and
-        // `createGpuHal` falls back to Canvas2D — the ladder only runs at
-        // construction. Per-pass compile failures after that are caught in
-        // `getPass` and surfaced through the error handler.
+        // Programs link on first draw (`getPass`). The first links here as a
+        // canary, so a GL stack that cannot compile our shaders throws while
+        // `createGpuHal` can still fall back to Canvas2D.
         const canary = descriptors[0];
         if (canary) {
-            this.compilePass(canary);
+            this.passes.set(canary.id, {
+                descriptor: canary,
+                linked: this.link(canary),
+            });
         }
         gl.enable(gl.BLEND);
     }
-    // A fixed buffer ceiling rather than a queried one — see
-    // MAX_VERTEX_BUFFER_BYTES for why the guard exists at all and why the number
-    // is WebGPU's. Past it, an unguarded bufferData loses the context in Chrome
-    // and throws RangeError in Firefox; neither is a getError() case, so the
-    // base's report is the only place the display can be told.
+    // Past the ceiling an unguarded bufferData loses the context in Chrome and
+    // throws in Firefox, neither of them a getError() case.
     limits() {
         return {
             maxBufferBytes: MAX_VERTEX_BUFFER_BYTES,
@@ -239,28 +203,55 @@ export class WebGL2Hal extends GpuHalBase {
         gl.bufferData(gl.ARRAY_BUFFER, data, gl.STATIC_DRAW);
         return { vbo, count };
     }
-    // No mid-frame deferral, unlike `WebGPUHal`'s hook: GL is immediate-mode, so
-    // a draw already issued has consumed the buffer and deleting it between
-    // beginFrame and endFrame is defined. The parity that matters is the
-    // caller's — the same upload sequence is legal on both.
+    // No mid-frame deferral, unlike `WebGPUHal`: GL is immediate-mode, so a draw
+    // already issued has consumed the buffer.
     destroyBuffer(buf) {
         const gl = this.gl;
         if (!this.contextWasLost && !gl.isContextLost()) {
             gl.deleteBuffer(buf.vbo);
         }
     }
-    compilePass(desc) {
+    // Throws on a failed link, and again on every later ask for that content.
+    link(desc) {
         const gl = this.gl;
-        const program = createProgram(gl, desc.glslVertex, desc.glslFragment);
+        const stages = this.glsl.get(desc.id);
+        if (!stages) {
+            throw new Error(`no GLSL was loaded for pass "${desc.id}"`);
+        }
+        const { GLSL_VERTEX, GLSL_FRAGMENT } = stages;
+        const tb = desc.textures?.[0];
+        const names = desc.vertexAttributes.map(attr => attr.name);
+        const sampler = tb && [tb.glUniformName, tb.glTextureUnit];
+        const key = JSON.stringify([GLSL_FRAGMENT, names, sampler]);
+        let byVertex = this.programs.get(GLSL_VERTEX);
+        if (!byVertex) {
+            byVertex = new Map();
+            this.programs.set(GLSL_VERTEX, byVertex);
+        }
+        const known = byVertex.get(key);
+        if (known instanceof Error) {
+            throw known;
+        }
+        if (known) {
+            return known;
+        }
+        let program;
+        try {
+            program = createProgram(gl, GLSL_VERTEX, GLSL_FRAGMENT);
+        }
+        catch (e) {
+            byVertex.set(key, e instanceof Error ? e : new Error(String(e)));
+            throw e;
+        }
         bindUniformBlock(gl, program, 'Uniforms', 0);
         this.checkGlError(`link pass "${desc.id}"`);
-        const attrLocs = desc.vertexAttributes.map(attr => gl.getAttribLocation(program, attr.name));
+        const attrLocs = names.map(name => gl.getAttribLocation(program, name));
         if (this.debug) {
-            const pairs = desc.vertexAttributes.map((a, i) => `${a.name}@${attrLocs[i]}`);
+            const pairs = names.map((name, i) => `${name}@${attrLocs[i]}`);
             console.warn(`[WebGL2Hal] pass "${desc.id}" stride=${desc.instanceStride} attrs: ${pairs.join(', ')}`);
-            const missing = desc.vertexAttributes.filter((_, i) => attrLocs[i] < 0);
+            const missing = names.filter((_, i) => attrLocs[i] < 0);
             if (missing.length > 0) {
-                console.warn(`[WebGL2Hal] pass "${desc.id}" missing attribute locations: ${missing.map(a => a.name).join(', ')}`);
+                console.warn(`[WebGL2Hal] pass "${desc.id}" missing attribute locations: ${missing.join(', ')}`);
             }
         }
         const vao = gl.createVertexArray();
@@ -272,26 +263,14 @@ export class WebGL2Hal extends GpuHalBase {
             }
         }
         gl.bindVertexArray(null);
-        let textureState = null;
-        const tb = desc.textures?.[0];
         if (tb) {
-            // Bind the sampler uniform to the texture unit once — it never changes.
             gl.useProgram(program);
             gl.uniform1i(gl.getUniformLocation(program, tb.glUniformName), tb.glTextureUnit);
-            textureState = { texture: null, unit: tb.glTextureUnit };
-        }
-        const state = {
-            program,
-            vao,
-            descriptor: desc,
-            textureState,
-            attrLocs,
-        };
-        this.passes.set(desc.id, state);
-        return state;
+        }
+        const linked = { program, vao, attrLocs };
+        byVertex.set(key, linked);
+        return linked;
     }
-    // Compiled pass for `passId`, building it the first time it's asked for.
-    // Returns undefined for an unknown id or a pass whose program failed to link.
     getPass(passId) {
         const existing = this.passes.get(passId);
         if (existing !== undefined) {
@@ -302,7 +281,9 @@ export class WebGL2Hal extends GpuHalBase {
             return undefined;
         }
         try {
-            return this.compilePass(desc);
+            const pass = { descriptor: desc, linked: this.link(desc) };
+            this.passes.set(passId, pass);
+            return pass;
         }
         catch (e) {
             this.passes.set(passId, null);
@@ -315,12 +296,9 @@ export class WebGL2Hal extends GpuHalBase {
     }
     createTexture(passId, binding, data, width, height) {
         const gl = this.gl;
-        const ts = this.getPass(passId)?.textureState;
-        if (!ts) {
-            return;
-        }
-        if (ts.texture) {
-            gl.deleteTexture(ts.texture);
+        const existing = this.passTextures.get(passId);
+        if (existing) {
+            gl.deleteTexture(existing);
         }
         const tex = gl.createTexture();
         gl.bindTexture(gl.TEXTURE_2D, tex);
@@ -337,7 +315,7 @@ export class WebGL2Hal extends GpuHalBase {
         gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, filter);
         gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
         gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
-        ts.texture = tex;
+        this.passTextures.set(passId, tex);
     }
     writeUniforms(data) {
         const gl = this.gl;
@@ -369,8 +347,7 @@ export class WebGL2Hal extends GpuHalBase {
     }
     drawPass(passId, regionKey, bufferPassId) {
         const gl = this.gl;
-        // Buffer first, program second: a pass with nothing to draw must not be
-        // the reason its shader gets compiled.
+        // Buffer first, so a pass with nothing to draw links no program.
         const regionBuf = this.regions.get(regionKey, bufferPassId ?? passId);
         if (!regionBuf || regionBuf.count === 0) {
             return;
@@ -380,10 +357,10 @@ export class WebGL2Hal extends GpuHalBase {
             return;
         }
         this.applyBlendState(pass.descriptor);
-        gl.useProgram(pass.program);
-        gl.bindVertexArray(pass.vao);
+        gl.useProgram(pass.linked.program);
+        gl.bindVertexArray(pass.linked.vao);
         this.bindAttributes(pass, regionBuf.vbo);
-        this.bindTextures(pass);
+        this.bindTexture(passId, pass.descriptor);
         const topo = pass.descriptor.topology ?? 'triangle-list';
         const glMode = topo === 'triangle-strip'
             ? gl.TRIANGLE_STRIP
@@ -409,10 +386,6 @@ export class WebGL2Hal extends GpuHalBase {
         if (this.debug) {
             console.warn(`[WebGL2Hal #${this.instanceId}] DISPOSING context (live=${totalCreated - totalDisposed}/${totalCreated})`);
         }
-        // Remove canvas event listeners to prevent closure references from keeping
-        // the context alive after disposal. This is critical for test suites where
-        // multiple contexts are created in sequence (e.g. Puppeteer page navigation).
-        // Double-dispose is short-circuited above, so listeners are guaranteed set.
         if (this.contextLostListener) {
             this.canvas.removeEventListener('webglcontextlost', this.contextLostListener);
         }
@@ -421,24 +394,24 @@ export class WebGL2Hal extends GpuHalBase {
         }
         this.regions.deleteAll();
         if (!this.contextWasLost && !gl.isContextLost()) {
-            for (const pass of this.passes.values()) {
-                if (pass) {
-                    gl.deleteVertexArray(pass.vao);
-                    gl.deleteProgram(pass.program);
-                    if (pass.textureState?.texture) {
-                        gl.deleteTexture(pass.textureState.texture);
+            for (const byVertex of this.programs.values()) {
+                for (const linked of byVertex.values()) {
+                    if (!(linked instanceof Error)) {
+                        gl.deleteVertexArray(linked.vao);
+                        gl.deleteProgram(linked.program);
                     }
                 }
             }
+            for (const texture of this.passTextures.values()) {
+                gl.deleteTexture(texture);
+            }
             gl.deleteBuffer(this.ubo);
         }
         this.passes.clear();
-        // Firefox appears to treat WEBGL_lose_context.loseContext() as a
-        // driver-wide reset: calling it on one disposed HAL synchronously
-        // knocks out sibling live contexts too, so tracks go blank en masse.
-        // Chrome only needs this as a test-suite optimisation; for production we
-        // let the browser reclaim the context when the canvas is GC'd. If we
-        // need explicit release again, gate it on navigator.userAgent.
+        this.programs.clear();
+        this.passTextures.clear();
+        // No WEBGL_lose_context.loseContext(): Firefox treats it as a driver-wide
+        // reset that blanks sibling live contexts, so the canvas's GC reclaims it.
     }
     applyBlendState(desc) {
         const gl = this.gl;
@@ -449,30 +422,28 @@ export class WebGL2Hal extends GpuHalBase {
         gl.enable(gl.BLEND);
         const bs = desc.blendState;
         if (bs?.op === 'max') {
-            // MIN/MAX ignore blend factors: the framebuffer keeps the per-channel
-            // max(src, dst). Used by same-color AA lines so overlapping segments union
-            // instead of darkening. Reset explicitly below for every other pass.
             gl.blendEquation(gl.MAX);
         }
+        else if (bs?.op === 'behind') {
+            gl.blendEquation(gl.FUNC_ADD);
+            gl.blendFuncSeparate(gl.ONE_MINUS_DST_ALPHA, gl.ONE, gl.ONE_MINUS_DST_ALPHA, gl.ONE);
+        }
         else {
             gl.blendEquation(gl.FUNC_ADD);
-            // RGB and alpha get different blend factors (blendFuncSeparate):
-            //   RGB:   out = src_rgb * srcFactor + dst_rgb * dstFactor  (default: src-alpha / 1-src-alpha)
-            //   Alpha: out = src_alpha * 1 + dst_alpha * (1 - src_alpha)
-            // The alpha channel uses ONE/ONE_MINUS_SRC_ALPHA regardless of the custom blend state;
-            // using the RGB srcFactor for alpha too would give out_alpha = src_alpha² + ..., which is wrong.
+            // Alpha keeps ONE / ONE_MINUS_SRC_ALPHA whatever the RGB factors: the
+            // RGB srcFactor on alpha would square it.
             const src = bs ? glBlendFactor(gl, bs.srcFactor) : gl.SRC_ALPHA;
             const dst = bs ? glBlendFactor(gl, bs.dstFactor) : gl.ONE_MINUS_SRC_ALPHA;
             gl.blendFuncSeparate(src, dst, gl.ONE, gl.ONE_MINUS_SRC_ALPHA);
         }
     }
-    bindTextures(pass) {
+    bindTexture(passId, desc) {
         const gl = this.gl;
-        const ts = pass.textureState;
-        if (ts?.texture) {
-            gl.activeTexture(gl.TEXTURE0 + ts.unit);
-            gl.bindTexture(gl.TEXTURE_2D, ts.texture);
-            // sampler uniform set once at construction — no uniform1i here
+        const tb = desc.textures?.[0];
+        const texture = tb && this.passTextures.get(passId);
+        if (tb && texture) {
+            gl.activeTexture(gl.TEXTURE0 + tb.glTextureUnit);
+            gl.bindTexture(gl.TEXTURE_2D, texture);
         }
     }
     bindAttributes(pass, vbo) {
@@ -480,7 +451,7 @@ export class WebGL2Hal extends GpuHalBase {
         const desc = pass.descriptor;
         gl.bindBuffer(gl.ARRAY_BUFFER, vbo);
         for (let i = 0; i < desc.vertexAttributes.length; i++) {
-            const loc = pass.attrLocs[i];
+            const loc = pass.linked.attrLocs[i];
             if (loc < 0) {
                 continue;
             }

package/esm/hal/webgpuHal.d.ts

@@ -11,13 +11,11 @@ export declare class WebGPUHal extends GpuHalBase<RegionPassBuffer> implements G
     private pipelines;
     private passTextures;
     private passBindGroups;
-    private layouts;
     private alignedUniformSize;
     private uniformRingBuffer;
     private uniformStaging;
     private uniformSlot;
     private warnedUniformSlots;
-    private uniformOnlyBindGroup;
     private sampleCount;
     private msaaTexture;
     private msaaView;
@@ -36,7 +34,7 @@ export declare class WebGPUHal extends GpuHalBase<RegionPassBuffer> implements G
      * selection spanning two sections re-uploads `OVERLAY_REGION` once per
      * section, inside the block loop.
      *
-     * Deferring is what makes mid-frame replacement legal instead of merely
+     * Deferring the destroy makes mid-frame replacement legal instead of merely
      * warned about; synteny's `ensureUploaded` has always deleted a pass mid-frame
      * that the open pass never referenced, and that case was never the bug.
      */
@@ -49,6 +47,9 @@ export declare class WebGPUHal extends GpuHalBase<RegionPassBuffer> implements G
     private swapChainUnrecoverable;
     private reportedSurfaceFailure;
     private constructor();
+    private bindGroupLayoutOf;
+    private createBindGroup;
+    private bindingResource;
     protected limits(): {
         maxBufferBytes: number;
         maxTextureDimensionPx: number;
@@ -81,13 +82,12 @@ export declare class WebGPUHal extends GpuHalBase<RegionPassBuffer> implements G
      * (and a dropped draw) the moment one side samples a texture.
      *
      * Nothing in a bind group varies per region either: it references the
-     * HAL-wide uniform ring buffer plus the pass's own texture/sampler. So
-     * uniform-only passes all share `uniformOnlyBindGroup`, and a textured pass
-     * gets exactly one, cached until `uploadTexture` replaces its texture.
-     * Returns undefined when a pass needs a texture that hasn't arrived yet;
-     * drawPass skips those.
+     * HAL-wide uniform ring buffer plus the pass's own texture/sampler. Returns
+     * undefined when a pass needs a texture that hasn't arrived yet; drawPass
+     * skips those.
      */
     private getBindGroup;
+    private bindTexture;
     /**
      * The one place a GPU resource this HAL owns is released — see
      * {@link pendingDestroy} for why the frame decides when.