@jbrowse/render-core 4.3.0

package/esm/hal/webgpuHal.d.ts

@@ -0,0 +1,169 @@
+import { GpuHalBase } from './gpuHalBase.ts';
+import type { GpuHal, PipelineDescriptor, SampleCount, TextureBinding } from './types.ts';
+interface RegionPassBuffer {
+    dataBuffer: GPUBuffer;
+    count: number;
+}
+export declare class WebGPUHal extends GpuHalBase<RegionPassBuffer> implements GpuHal {
+    private device;
+    private canvas;
+    private context;
+    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;
+    private currentTextureView;
+    private currentEncoder;
+    private currentPass;
+    /**
+     * Buffers and textures whose destroy landed while the frame's render pass was
+     * open, held until the frame has been submitted.
+     *
+     * WebGPU validates `destroy()` against the submitted command buffer, not
+     * against when the draw was encoded: destroying a vertex buffer an already
+     * encoded draw references makes `queue.submit` reject the whole frame, so one
+     * region re-uploading a pass it drew earlier in the same frame blanks
+     * everything else drawn with it. Alignments does exactly that — a chain
+     * 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
+     * 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.
+     */
+    private pendingDestroy;
+    private scissorRect;
+    private viewportRect;
+    private appliedScissor;
+    private appliedViewport;
+    private warnedSwapChainLoss;
+    private swapChainUnrecoverable;
+    private constructor();
+    protected limits(): {
+        maxBufferBytes: number;
+        maxTextureDimensionPx: number;
+    };
+    protected createBuffer(data: ArrayBuffer | ArrayBufferView, count: number): {
+        dataBuffer: GPUBuffer;
+        count: number;
+    };
+    protected destroyBuffer(buf: RegionPassBuffer): void;
+    /**
+     * Claim the canvas's swap chain, and record that this HAL is the one holding
+     * it — see `noteCanvasConfigured` for why that ownership has to be tracked.
+     *
+     * Called from the constructor rather than from `create`, so that the object
+     * doing the claiming exists, and so a throwing constructor leaves no
+     * configured context behind with nothing to release it.
+     */
+    private configureContext;
+    static create(canvas: HTMLCanvasElement, descriptors: PipelineDescriptor[], uniformByteSize: number, sampleCount: SampleCount): Promise<WebGPUHal | null>;
+    resize(width: number, height: number): import("./types.ts").CanvasScale;
+    private recreateMsaaTexture;
+    /**
+     * Bind group matching the pipeline layout of `passId`.
+     *
+     * Keyed on the pass being DRAWN, never on the buffer it draws from:
+     * `drawPass(a, key, b)` runs pass `a`'s pipeline over pass `b`'s vertex
+     * buffer, so the bind group has to match `a`'s layout. Caching it on the
+     * (region, `b`) buffer entry instead bound `b`'s layout to `a`'s pipeline —
+     * fine while every such pair happened to be uniform-only, a validation error
+     * (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.
+     */
+    private getBindGroup;
+    /**
+     * The one place a GPU resource this HAL owns is released — see
+     * {@link pendingDestroy} for why the frame decides when.
+     *
+     * Every buffer release routes here through the `RegionRegistry` destroy hook,
+     * so `uploadBuffer`, `deleteBuffer`, `deleteRegion`, `pruneRegions` and
+     * `dispose` are all covered without any of them knowing a frame is open.
+     */
+    private destroyWhenIdle;
+    private drainPendingDestroy;
+    protected createTexture(passId: string, binding: TextureBinding, data: Uint8Array, width: number, height: number): void;
+    writeUniforms(data: ArrayBuffer): void;
+    /**
+     * The canvas texture to draw this frame into, or null when the swap chain is
+     * gone and could not be rebuilt.
+     *
+     * **A configuration can disappear under a live HAL.** The case we have seen is
+     * a sibling HAL on a reused canvas element releasing a context it turned out
+     * not to own (`noteCanvasConfigured` has the shape), and a browser is free to
+     * drop one for its own reasons too. Firefox reports it as `InvalidStateError:
+     * GPUCanvasContext.getCurrentTexture: Canvas not configured` — on this call
+     * and, measured, on no other. Nothing else in the stack hears about it: there
+     * is no context-lost event to fire the recovery in `useRenderingBackend`, so
+     * unguarded the throw leaves `RenderLifecycleMixin`'s render autorun, lands in
+     * `renderError`, and the display banners a raw DOMException until the tab is
+     * reloaded.
+     *
+     * Reconfiguring restores it in full, so this frame goes on to paint. A
+     * reconfigure that does *not* restore it is reported and not retried — every
+     * later frame would rebuild a swap chain to no effect, and the display's own
+     * Retry is what builds a fresh HAL.
+     */
+    private acquireTextureView;
+    beginFrame(clearR: number, clearG: number, clearB: number, clearA?: number): void;
+    drawPass(passId: string, regionKey: number, bufferPassId?: string): void;
+    /**
+     * Close the frame's state whether the submit landed or threw.
+     *
+     * The scopes pushed in `beginFrame` have to be popped either way — leaving a
+     * pair pushed makes every later frame's pop read an older frame's errors —
+     * and the deferred destroys have to be drained either way, since a frame that
+     * threw is a frame no later `endFrame` will run for.
+     */
+    private closeFrame;
+    endFrame(): void;
+    /**
+     * Mark `at` as holding the whole attachment — the state a freshly-begun
+     * render pass is already in, so seeding with it means the first draw of an
+     * unclipped frame issues nothing.
+     */
+    private seedApplied;
+    /**
+     * Re-issue the scissor whenever it differs from what this pass was last told,
+     * **including when it has been cleared**.
+     *
+     * WebGL2 clears by turning the state off — `disable(SCISSOR_TEST)`, and a
+     * `viewport` back to the full canvas — and that lands immediately.
+     * `setScissorRect` / `setViewport` have no off switch and no reset: they are
+     * render-pass state that persists to the end of the pass. So dropping the
+     * stored rect on `clearScissor` is not a clear at all — it left the
+     * *previous* rect clipping every later draw of the frame, while WebGL2 drew
+     * those same calls unclipped.
+     *
+     * Nothing in tree clears mid-frame today — the two callers
+     * (`GpuPerRegionRenderingBackend.renderBlocks` and alignments' own) clear
+     * after their last draw — so this is parity kept ahead of the renderer that
+     * needs it rather than a fix for a live bug. The bug it would have been is
+     * the kind this package exists to refuse: right on Canvas2D, right on WebGL2,
+     * wrong on WebGPU alone, and silent everywhere.
+     */
+    private applyScissor;
+    /** The viewport half of {@link applyScissor}; same reasoning throughout. */
+    private applyViewport;
+    setScissor(x: number, y: number, w: number, h: number): void;
+    clearScissor(): void;
+    setViewport(x: number, y: number, w: number, h: number): void;
+    clearViewport(): void;
+    protected releaseResources(): void;
+}
+export {};