@perspective-dev/viewer-charts 4.5.1 → 5.0.0

package/src/ts/webgl/gl-context.ts

@@ -0,0 +1,191 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ Copyright (c) 2017, the Perspective Authors.                              ┃
+// ┃ ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ ┃
+// ┃ This file is part of the Perspective library, distributed under the terms ┃
+// ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+import { ShaderRegistry } from "./shader-registry";
+import { SHADER_MANIFEST } from "./shader-manifest";
+
+export type WebGLCanvas = HTMLCanvasElement | OffscreenCanvas;
+
+/**
+ * The unit the browser actually counts against its per-agent WebGL
+ * context cap (~16 in Chromium): one canvas + one GL context + the
+ * shader programs compiled against it.
+ *
+ * Factored out of {@link WebGLContextManager} so that *many* managers
+ * (one per chart) can share *one* GL context. The browser limit is on
+ * contexts, not on the buffers/programs living inside one — a single
+ * context can host an arbitrary number of independent
+ * `WebGLBuffer`s/programs (bounded only by memory). So N charts can
+ * render through K ≪ N contexts as long as each keeps its own
+ * `BufferPool` (buffers are keyed by name; two charts would otherwise
+ * collide) and renders are serialized per context (the shared drawing
+ * buffer can hold one chart's frame at a time). See
+ * [context-pool.ts](./context-pool.ts) and the scheduler's per-backend
+ * grouping in [../render/scheduler.ts](../render/scheduler.ts).
+ *
+ * Shaders are shared per context: programs are immutable GLSL once
+ * compiled (uniforms are set per draw), so co-tenant charts reuse them
+ * and only pay the compile cost once per context.
+ */
+let NEXT_CONTEXT_ID = 1;
+
+export class GLContext {
+    readonly id: number;
+    readonly canvas: WebGLCanvas;
+    readonly gl: WebGL2RenderingContext | WebGLRenderingContext;
+    readonly isWebGL2: boolean;
+    shaders: ShaderRegistry;
+    private _maxVertexAttribs: number;
+    private _angle: ANGLE_instanced_arrays | null = null;
+    private _precompile: boolean;
+    private _destroyed = false;
+
+    /**
+     * Per-tenant hooks fired after a `webglcontextrestored`. Each
+     * {@link WebGLContextManager} on this context registers one that
+     * rebuilds its `BufferPool` (the shaders are rebuilt here, once, for
+     * all tenants). On an intentional {@link destroy} these are dropped
+     * without firing.
+     */
+    private _onRestore = new Set<() => void>();
+
+    constructor(canvas: WebGLCanvas, options: { precompile?: boolean } = {}) {
+        this.id = NEXT_CONTEXT_ID++;
+        this.canvas = canvas;
+        this._precompile = options.precompile ?? false;
+        const gl2 = canvas.getContext("webgl2", {
+            antialias: true,
+            alpha: true,
+            premultipliedAlpha: false,
+        });
+
+        if (gl2) {
+            this.gl = gl2 as WebGL2RenderingContext;
+            this.isWebGL2 = true;
+        } else {
+            const gl1 = canvas.getContext("webgl", {
+                antialias: true,
+                alpha: true,
+                premultipliedAlpha: false,
+            });
+
+            if (!gl1) {
+                throw new Error("WebGL is not supported");
+            }
+
+            this.gl = gl1 as WebGLRenderingContext;
+            this.isWebGL2 = false;
+        }
+
+        this.shaders = new ShaderRegistry(this.gl);
+        if (this._precompile) {
+            this.shaders.precompile(SHADER_MANIFEST);
+        }
+
+        this._maxVertexAttribs = this.gl.getParameter(
+            this.gl.MAX_VERTEX_ATTRIBS,
+        ) as number;
+        if (!this.isWebGL2) {
+            this._angle = this.gl.getExtension("ANGLE_instanced_arrays");
+        }
+
+        // Both `HTMLCanvasElement` and `OffscreenCanvas` dispatch
+        // `webglcontextlost` / `webglcontextrestored` on the canvas.
+        (canvas as EventTarget).addEventListener(
+            "webglcontextlost",
+            (e: Event) => {
+                // Don't reserve the slot for a restore once we've
+                // intentionally torn the context down — `destroy()`
+                // calls `loseContext()`, which fires this event.
+                if (this._destroyed) {
+                    return;
+                }
+
+                e.preventDefault();
+            },
+        );
+
+        (canvas as EventTarget).addEventListener("webglcontextrestored", () => {
+            // Rebuild the shared program cache once for the whole
+            // context, then let each tenant rebuild its own buffers.
+            this.shaders.releaseAll();
+            this.shaders = new ShaderRegistry(this.gl);
+            if (this._precompile) {
+                this.shaders.precompile(SHADER_MANIFEST);
+            }
+
+            for (const cb of this._onRestore) {
+                cb();
+            }
+        });
+    }
+
+    /**
+     * Return every vertex-attribute slot to its default state: disabled,
+     * with a zero instance divisor. Vertex-array state (enable flags,
+     * pointers, divisors) is global to a context's default VAO — there
+     * are no per-chart VAOs in this codebase — so when many charts share
+     * one pooled context, a slot a prior chart enabled stays enabled for
+     * the next chart, now pointing at a buffer the prior chart's
+     * teardown deleted. Its next `drawArraysInstanced` then fails GL
+     * validation: "no buffer is bound to enabled attribute", silently
+     * dropping the draw.
+     *
+     * Glyphs already (re)enable + bind + set the divisor for every slot
+     * they use on each frame, so clearing to the default here is a safe
+     * baseline — it only removes the *leftover* enables a sibling chart
+     * left behind. Called from {@link WebGLContextManager.beginFrame} in
+     * shared (pooled) mode only; the 1:1 default never shares a context
+     * and so keeps its original, reset-free path.
+     */
+    resetVertexArrayState(): void {
+        const gl = this.gl;
+        for (let i = 0; i < this._maxVertexAttribs; i++) {
+            gl.disableVertexAttribArray(i);
+            if (this.isWebGL2) {
+                (gl as WebGL2RenderingContext).vertexAttribDivisor(i, 0);
+            } else {
+                this._angle?.vertexAttribDivisorANGLE(i, 0);
+            }
+        }
+    }
+
+    /**
+     * Register a tenant's post-restore rebuild hook. Returns a disposer.
+     */
+    onRestore(cb: () => void): () => void {
+        this._onRestore.add(cb);
+        return () => this._onRestore.delete(cb);
+    }
+
+    /**
+     * True once lost — either our own {@link destroy} or a browser
+     * eviction of the oldest context past the per-agent cap.
+     */
+    isContextLost(): boolean {
+        return this._destroyed || this.gl.isContextLost();
+    }
+
+    get destroyed(): boolean {
+        return this._destroyed;
+    }
+
+    destroy(): void {
+        this._destroyed = true;
+        this._onRestore.clear();
+        this.shaders.releaseAll();
+        const ext = this.gl.getExtension("WEBGL_lose_context");
+        if (ext) {
+            ext.loseContext();
+        }
+    }
+}

package/src/ts/webgl/instanced-attrs.ts

@@ -108,6 +108,12 @@ export function createQuadCornerBuffer(gl: GL): WebGLBuffer {
  * paint zero data). No-op return `true` when `attr` is negative
  * (optimized-out attribute — drawing the rest is still valid).
  *
+ * `firstInstance` byte-offsets the attribute pointer so the draw's
+ * instance 0 reads element `firstInstance` of the buffer — the WebGL
+ * substitute for a `baseInstance` draw parameter. Faceted renderers
+ * use it to draw a contiguous per-facet sub-range of a shared
+ * instance buffer.
+ *
  * Render-path uses `peek`, never `getOrCreate`: the latter recreates
  * with zero-initialized contents when `_totalCapacity` has grown past
  * the current buffer, which would wipe the previous draw's vertex
@@ -120,6 +126,7 @@ export function bindInstancedFloatAttr(
     attr: number,
     name: string,
     components: number,
+    firstInstance = 0,
 ): boolean {
     if (attr < 0) {
         return true;
@@ -133,7 +140,14 @@ export function bindInstancedFloatAttr(
     const gl: GL = glManager.gl;
     gl.bindBuffer(gl.ARRAY_BUFFER, buf.buffer);
     gl.enableVertexAttribArray(attr);
-    gl.vertexAttribPointer(attr, components, gl.FLOAT, false, 0, 0);
+    gl.vertexAttribPointer(
+        attr,
+        components,
+        gl.FLOAT,
+        false,
+        0,
+        firstInstance * components * Float32Array.BYTES_PER_ELEMENT,
+    );
     instancing.setDivisor(attr, 1);
     return true;
 }

package/src/ts/worker/dispatch.ts

@@ -40,9 +40,12 @@ export function dispatch(r: WorkerRenderer, msg: ControlMsg): void {
         case "redraw":
             r.redraw();
             break;
+        case "deselect":
+            r.chartImpl.deselect?.();
+            break;
         case "resize":
             r.resize(msg.cssWidth, msg.cssHeight, msg.dpr);
-            r.redraw();
+            r.redrawAck(msg.msgId);
             break;
         case "clear":
             r.clear();

package/src/ts/worker/renderer.worker.ts

@@ -16,6 +16,8 @@ import type { Client, Table, View } from "@perspective-dev/client";
 
 import type * as wasm_module_type from "@perspective-dev/viewer/dist/wasm/perspective-viewer.js";
 import { WebGLContextManager } from "../webgl/context-manager";
+import { ContextPool } from "../webgl/context-pool";
+import { RENDER_CONTEXT_POOL_SIZE } from "../config";
 import { ChartImplementation } from "../charts/chart";
 import { ZoomController } from "../interaction/zoom-controller";
 import {
@@ -37,7 +39,7 @@ import { viewToColumnDataMap } from "../data/view-reader";
 import { loadFontDeduped } from "./font-loader";
 import { dispatch } from "./dispatch";
 import { installSessionHost } from "./session-host";
-import { deferIfDraining } from "../render/scheduler";
+import { deferIfDraining, unregister } from "../render/scheduler";
 
 /**
  * Sentinel thrown inside the `with_typed_arrays` callback when a newer
@@ -76,6 +78,25 @@ async function resolveChartImpl(
     return await factory();
 }
 
+/**
+ * Renderer-scope shared context pool for pooled blit mode. Lazily
+ * created on first use so non-blit / non-pooled scopes never allocate
+ * one. One per renderer scope (the worker, or the main thread in
+ * in-process mode) — `WorkerRenderer`s in the same scope share its K
+ * contexts.
+ */
+let CONTEXT_POOL: ContextPool | null = null;
+
+function getContextPool(precompile: boolean): ContextPool {
+    if (!CONTEXT_POOL) {
+        CONTEXT_POOL = new ContextPool(RENDER_CONTEXT_POOL_SIZE, {
+            precompile,
+        });
+    }
+
+    return CONTEXT_POOL;
+}
+
 export class WorkerRenderer {
     chartImpl: ChartImplementation;
     glManager: WebGLContextManager;
@@ -131,20 +152,35 @@ export class WorkerRenderer {
 
         this.chartImpl = new ImplClass();
 
-        // Direct mode hands us the host's transferred `.webgl-canvas`.
-        // Blit mode omits it — the renderer owns its own offscreen
-        // surface and posts each completed frame back as an
-        // `ImageBitmap` via the `endFrame` callback wired below.
-        const glCanvas =
-            msg.glCanvas ??
-            new OffscreenCanvas(
-                Math.max(1, Math.round(msg.cssWidth * msg.dpr)),
-                Math.max(1, Math.round(msg.cssHeight * msg.dpr)),
+        // Three surfaces, by mode:
+        //  - direct: the host's transferred `.webgl-canvas` (1:1 with a
+        //    context, permanently).
+        //  - pooled blit: borrow one of K shared contexts so live-
+        //    context count stays bounded regardless of chart count.
+        //  - unpooled blit: a private offscreen surface per chart.
+        // Blit modes omit `msg.glCanvas`; the renderer ships each frame
+        // as an `ImageBitmap` via the `endFrame` callback wired below.
+        const pooled =
+            msg.renderMode === "blit" &&
+            !msg.glCanvas &&
+            RENDER_CONTEXT_POOL_SIZE > 0;
+
+        if (pooled) {
+            this.glManager = new WebGLContextManager(
+                getContextPool(msg.precompileShaders ?? false).acquire(),
             );
+        } else {
+            const glCanvas =
+                msg.glCanvas ??
+                new OffscreenCanvas(
+                    Math.max(1, Math.round(msg.cssWidth * msg.dpr)),
+                    Math.max(1, Math.round(msg.cssHeight * msg.dpr)),
+                );
 
-        this.glManager = new WebGLContextManager(glCanvas, {
-            precompile: msg.precompileShaders ?? false,
-        });
+            this.glManager = new WebGLContextManager(glCanvas, {
+                precompile: msg.precompileShaders ?? false,
+            });
+        }
 
         if (msg.renderMode === "blit") {
             this.glManager.setFrameCallback((bitmap) => {
@@ -259,16 +295,23 @@ export class WorkerRenderer {
             try {
                 await viewToColumnDataMap(
                     this.view,
-                    async (cols) => {
+                    async (cols, deliveredRows) => {
                         if (this._renderGen !== myGen) {
                             throw new StaleGenerationError();
                         }
 
+                        // `totalRows` came from a SEPARATE `num_rows()`
+                        // round-trip; a fast-updating table with deletions
+                        // can shrink the view before the Arrow fetch, which
+                        // clamps its window silently. Iterating to the stale
+                        // count reads typed arrays out-of-bounds (`undefined`
+                        // values no validity bitmap covers) — clamp to what
+                        // was actually delivered.
                         await this.chartImpl.uploadAndRender(
                             this.glManager,
                             cols,
                             0,
-                            totalRows,
+                            Math.min(totalRows, deliveredRows),
                         );
                     },
                     { end_row: totalRows, float32: msg.options.float32 },
@@ -291,6 +334,24 @@ export class WorkerRenderer {
         this.chartImpl.requestRender(this.glManager);
     }
 
+    /**
+     * `redraw`, acked to the host AFTER the frame's present completes —
+     * the reply backing the viewer's presize contract (`ResizeAckMsg`):
+     * `plugin.resize()` must not resolve until the resized frame is
+     * actually on screen. A resize landing mid-present defers its
+     * canvas mutation (`deferIfDraining`), but the redraw's own frame
+     * applies pending dimensions in `beginFrame`, so the present this
+     * awaits IS at the new size. Always acks — a failed present or a
+     * torn-down chart resolves the host's await rather than stranding
+     * it (completion, not success, is the contract).
+     */
+    redrawAck(msgId: number): void {
+        this.chartImpl
+            .requestRender(this.glManager)
+            .catch(() => {})
+            .finally(() => this.post({ kind: "resizeAck", msgId }));
+    }
+
     resize(cssWidth: number, cssHeight: number, dpr: number): void {
         // `glManager.resize` would set `canvas.width = N`, which the
         // spec mandates clears the drawing buffer immediately. In
@@ -528,13 +589,19 @@ export class WorkerRenderer {
      * Composite the three layers into a single PNG `Blob`.
      */
     async snapshotPng(): Promise<Blob> {
-        // Snapshot bypasses the scheduler's drain, so it must
-        // mirror Phase 1's "apply pending resize before paint"
-        // step itself — otherwise a snapshot taken after a resize
-        // message but before the next drain would render at the
-        // previous dimensions.
-        this.glManager.applyPendingResize();
-        this.chartImpl._fullRender(this.glManager);
+        // Snapshot bypasses the scheduler's drain, so it must mirror
+        // the per-frame prep itself — apply any pending resize, and in
+        // pooled blit mode size the shared canvas to this chart and
+        // reset shared GL state — otherwise a snapshot taken after a
+        // resize message but before the next drain (or after a co-tenant
+        // chart left the shared canvas at its own size) would render at
+        // the wrong dimensions.
+        this.glManager.beginFrame();
+        // `renderFrameSync` (not `_fullRender`) so the gridline + chrome
+        // 2D canvases are actually painted here — the scheduler normally
+        // defers those to a post-fence flush, but the snapshot path
+        // bypasses the scheduler and composites the 2D layers below.
+        this.chartImpl.renderFrameSync(this.glManager);
         const gl = this.glManager.gl;
         const glCanvas = gl.canvas as OffscreenCanvas;
         const w = glCanvas.width;
@@ -574,6 +641,11 @@ export class WorkerRenderer {
     }
 
     destroy(): void {
+        // Drop any frame this manager still has queued in the
+        // module-level scheduler *before* losing its GL context, so a
+        // next-RAF `drain()` can't paint/present against a dead
+        // context (the "scheduler: present failed" path).
+        unregister(this.glManager);
         this.chartImpl.destroy();
         this.glManager.destroy();
     }

package/src/ts/worker/session-host.ts

@@ -21,6 +21,20 @@ import { dispatch } from "./dispatch";
 
 const RENDERERS = new Map<number, WorkerRenderer>();
 
+/**
+ * Sessions whose `destroy` arrived before their async `bootstrap`
+ * resolved. Bootstrap does multiple awaits (wasm `initSync`, font
+ * loads, `open_table`, lazy chart-impl import); a host that connects
+ * then immediately disconnects a viewer can post `init` and `destroy`
+ * back-to-back, with `destroy` landing while the renderer is still
+ * being built. The plain `RENDERERS.get(sessionId)` lookup in the
+ * destroy branch would miss it and the bootstrap would then register a
+ * renderer (and its WebGL context) that nothing ever tears down —
+ * leaking one context per raced toggle until the browser evicts the
+ * oldest. We tombstone the id here and honor it when bootstrap lands.
+ */
+const PENDING_DESTROY = new Set<number>();
+
 function postSession(
     sessionId: number,
     msg: WorkerMsg,
@@ -89,9 +103,18 @@ export function installSessionHost(
 
             bootstrap(msg as InitMsg, makeSessionPort(sessionId))
                 .then((r) => {
+                    // A `destroy` raced ahead of bootstrap completing —
+                    // honor it now instead of leaking the freshly-built
+                    // renderer + its WebGL context.
+                    if (PENDING_DESTROY.delete(sessionId)) {
+                        dispatch(r, { kind: "destroy" });
+                        return;
+                    }
+
                     RENDERERS.set(sessionId, r);
                 })
                 .catch((err) => {
+                    PENDING_DESTROY.delete(sessionId);
                     postSession(sessionId, {
                         kind: "error",
                         message: String(err),
@@ -105,6 +128,12 @@ export function installSessionHost(
             if (r) {
                 dispatch(r, msg);
                 RENDERERS.delete(sessionId);
+            } else {
+                // Renderer not registered yet — bootstrap is still in
+                // flight. Tombstone the id so the bootstrap `.then`
+                // tears it down on arrival instead of registering a
+                // leaked context.
+                PENDING_DESTROY.add(sessionId);
             }
 
             return;