@jbrowse/render-core 5.0.0-beta.1 → 5.0.0-beta.11

package/esm/hal/types.d.ts

@@ -27,9 +27,8 @@ export interface VertexAttributeLayout {
  * this is worth stating per display — see ARCHITECTURAL_LIMITS.md §"The MSAA
  * target is the largest per-display allocation".
  *
- * WebGL2 has no counterpart: it draws to the default framebuffer with
- * `antialias: true`, so its multisampling is the browser's choice inside the
- * browser's budget.
+ * WebGL2 draws to the default framebuffer and asks for `antialias` above one
+ * sample, so there the samples are the browser's, inside the browser's budget.
  */
 export type SampleCount = 1 | 4;
 export type BlendFactor = 'one' | 'src-alpha' | 'one-minus-src-alpha' | 'zero';
@@ -39,29 +38,55 @@ 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
+ * are copied on the GPU — the circular view's ring samples a linear display's
+ * finished strip that way. A canvas source lands premultiplied, so a shader
+ * reading one returns its sample under `//! blend: premultiplied`.
+ */
+export type TextureSource = Uint8Array | HTMLCanvasElement | OffscreenCanvas;
 export interface TextureBinding {
-    textureBinding: number;
-    samplerBinding: number;
+    name: string;
     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
@@ -76,19 +101,22 @@ 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;
     verticesPerInstance: number;
     blend: boolean;
     blendState?: BlendState;
     vertexAttributes: readonly VertexAttributeLayout[];
     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. */
+    readonly uniformByteSize: number;
     /**
      * Size the canvas, and report the scale its backing store actually got.
      * Callers derive every device-px rect from THAT rather than from `getDpr()`:
@@ -97,15 +125,22 @@ export interface GpuHal {
      * track goes blank; WebGL2 clamps and paints at the wrong scale).
      */
     resize(width: number, height: number): CanvasScale;
+    /**
+     * Drop the canvas-sized render targets this HAL allocated, keeping the
+     * device, the context, the compiled pipelines and every uploaded buffer. The
+     * next `resize` rebuilds them, so a display whose canvas has scrolled out of
+     * the page can give the bytes back and come back at the cost of one frame
+     * rather than a context re-acquire and a shader recompile.
+     */
+    releaseRenderTargets(): void;
     uploadBuffer(regionKey: number, passId: string, data: ArrayBuffer | ArrayBufferView, count: number): void;
     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;
     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;
     endFrame(): void;
     setScissor(x: number, y: number, w: number, h: number): void;
     clearScissor(): void;

package/esm/hal/webgl2Hal.d.ts

@@ -1,5 +1,5 @@
 import { GpuHalBase } from './gpuHalBase.ts';
-import type { GpuHal, PipelineDescriptor, TextureBinding } from './types.ts';
+import type { GpuHal, PipelineDescriptor, SampleCount, TextureBinding, TextureSource } from './types.ts';
 interface RegionPassBuffer {
     vbo: WebGLBuffer;
     count: number;
@@ -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[], uniformByteSize: number);
+    /**
+     * 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[], sampleCount?: SampleCount): Promise<WebGL2Hal>;
+    private constructor();
     protected limits(): {
         maxBufferBytes: number;
         maxTextureDimensionPx: number;
@@ -27,21 +35,30 @@ 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: Uint8Array, width: number, height: number): void;
+    /**
+     * Nothing to give back. WebGL2 multisamples in the drawing buffer the context
+     * owns (`antialias` above one sample), so this HAL holds no separate target —
+     * releasing its samples means dropping the context, which costs a re-acquire
+     * against a hard 16-context ceiling and a full shader recompile per display.
+     * `agent-docs/reference/GPU_PORTABILITY.md` measured that trade and
+     * declined it; what makes the WebGPU side worth doing is that it pays
+     * neither.
+     */
+    releaseRenderTargets(): void;
+    protected createTexture(passId: string, binding: TextureBinding, data: TextureSource, width: number, height: number): void;
     writeUniforms(data: ArrayBuffer): void;
     beginFrame(clearR: number, clearG: number, clearB: number, clearA?: number): void;
     setScissor(x: number, y: number, w: number, h: number): void;
     clearScissor(): void;
     setViewport(x: number, y: number, w: number, h: number): void;
     clearViewport(): void;
-    drawPass(passId: string, regionKey: number, bufferPassId?: string): void;
+    drawPass(passId: string, regionKey: number, bufferPassId?: string, verticesPerInstance?: number): void;
     endFrame(): void;
     protected releaseResources(): void;
     private applyBlendState;
-    private bindTextures;
     private bindAttributes;
 }
 export {};