@luma.gl/core 9.3.0-alpha.4 → 9.3.0-alpha.6

package/dist/utils/stats-manager.js.map

@@ -1 +1 @@
-{"version":3,"file":"stats-manager.js","sourceRoot":"","sources":["../../src/utils/stats-manager.ts"],"names":[],"mappings":"AAAA,UAAU;AACV,+BAA+B;AAC/B,oCAAoC;AAEpC,OAAO,EAAC,KAAK,EAAC,MAAM,iBAAiB,CAAC;AAEtC;;GAEG;AACH,MAAM,OAAO,YAAY;IACvB,KAAK,GAAG,IAAI,GAAG,EAAE,CAAC;IAElB,QAAQ,CAAC,IAAY;QACnB,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACxB,CAAC;IAED,GAAG,CAAC,IAAY;QACd,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAC1B,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,KAAK,CAAC,EAAC,EAAE,EAAE,IAAI,EAAC,CAAC,CAAC,CAAC;QAC9C,CAAC;QAED,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;CACF;AAED,2CAA2C;AAC3C,MAAM,CAAC,MAAM,SAAS,GAAiB,IAAI,YAAY,EAAE,CAAC"}
+{"version":3,"file":"stats-manager.js","sourceRoot":"","sources":["../../src/utils/stats-manager.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luma.gl/core",
-  "version": "9.3.0-alpha.4",
+  "version": "9.3.0-alpha.6",
   "description": "The luma.gl core Device API",
   "license": "MIT",
   "type": "module",
@@ -44,7 +44,7 @@
     "@probe.gl/env": "^4.1.1",
     "@probe.gl/log": "^4.1.1",
     "@probe.gl/stats": "^4.1.1",
-    "@types/offscreencanvas": "^2019.6.4"
+    "@types/offscreencanvas": "^2019.7.3"
   },
-  "gitHead": "7486e7b0377fb6ab961b4499828681bede60f3b1"
+  "gitHead": "59fda5480c4d0bb3d64545d4621175221f2b6c7c"
 }

package/src/adapter/canvas-context.ts

@@ -2,631 +2,15 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {isBrowser} from '@probe.gl/env';
-import type {Device} from './device';
-import type {Framebuffer} from './resources/framebuffer';
-import type {TextureFormatDepthStencil} from '../shadertypes/textures/texture-formats';
-import {uid} from '../utils/uid';
-import {withResolvers} from '../utils/promise-utils';
-import {assertDefined} from '../utils/assert';
-
-/** Properties for a CanvasContext */
-export type CanvasContextProps = {
-  /** Identifier, for debugging */
-  id?: string;
-  /** If a canvas not supplied, one will be created and added to the DOM. If a string, a canvas with that id will be looked up in the DOM */
-  canvas?: HTMLCanvasElement | OffscreenCanvas | string | null;
-  /** If new canvas is created, it will be created in the specified container, otherwise is appended as a child of document.body */
-  container?: HTMLElement | string | null;
-  /** Width in pixels of the canvas - used when creating a new canvas */
-  width?: number;
-  /** Height in pixels of the canvas - used when creating a new canvas */
-  height?: number;
-  /** Visibility (only used if new canvas is created). */
-  visible?: boolean;
-  /** Whether to size the drawing buffer to the pixel size during auto resize. If a number is provided it is used as a static pixel ratio */
-  useDevicePixels?: boolean | number;
-  /** Whether to track window resizes. */
-  autoResize?: boolean;
-  /** @see https://developer.mozilla.org/en-US/docs/Web/API/GPUCanvasContext/configure#alphamode */
-  alphaMode?: 'opaque' | 'premultiplied';
-  /** @see https://developer.mozilla.org/en-US/docs/Web/API/GPUCanvasContext/configure#colorspace */
-  colorSpace?: 'srgb'; // GPUPredefinedColorSpace
-  /** Whether to track position changes. Calls this.device.onPositionChange */
-  trackPosition?: boolean;
-};
-
-export type MutableCanvasContextProps = {
-  /** Whether to size the drawing buffer to the pixel size during auto resize. If a number is provided it is used as a static pixel ratio */
-  useDevicePixels?: boolean | number;
-};
-
-/**
- * Manages a canvas. Supports both HTML or offscreen canvas
- * - Creates a new canvas or looks up a canvas from the DOM
- * - Provides check for DOM loaded
- * @todo commit() @see https://github.com/w3ctag/design-reviews/issues/288
- * @todo transferControlToOffscreen: @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/transferControlToOffscreen
- */
-export abstract class CanvasContext {
-  static isHTMLCanvas(canvas: unknown): canvas is HTMLCanvasElement {
-    return typeof HTMLCanvasElement !== 'undefined' && canvas instanceof HTMLCanvasElement;
-  }
-
-  static isOffscreenCanvas(canvas: unknown): canvas is OffscreenCanvas {
-    return typeof OffscreenCanvas !== 'undefined' && canvas instanceof OffscreenCanvas;
-  }
-
-  static defaultProps: Required<CanvasContextProps> = {
-    id: undefined!,
-    canvas: null,
-    width: 800,
-    height: 600,
-    useDevicePixels: true,
-    autoResize: true,
-    container: null,
-    visible: true,
-    alphaMode: 'opaque',
-    colorSpace: 'srgb',
-    trackPosition: false
-  };
-
-  abstract readonly device: Device;
-  abstract readonly handle: unknown;
-  readonly id: string;
-
-  readonly props: Required<CanvasContextProps>;
-  readonly canvas: HTMLCanvasElement | OffscreenCanvas;
-  /** Handle to HTML canvas */
-  readonly htmlCanvas?: HTMLCanvasElement;
-  /** Handle to wrapped OffScreenCanvas */
-  readonly offscreenCanvas?: OffscreenCanvas;
-  readonly type: 'html-canvas' | 'offscreen-canvas' | 'node';
-
-  /** Promise that resolved once the resize observer has updated the pixel size */
-  initialized: Promise<void>;
-  isInitialized: boolean = false;
-
-  /** Visibility is automatically updated (via an IntersectionObserver) */
-  isVisible: boolean = true;
-
-  /** Width of canvas in CSS units (tracked by a ResizeObserver) */
-  cssWidth: number;
-  /** Height of canvas in CSS units (tracked by a ResizeObserver) */
-  cssHeight: number;
-
-  /** Device pixel ratio. Automatically updated via media queries */
-  devicePixelRatio: number;
-  /** Exact width of canvas in physical pixels (tracked by a ResizeObserver) */
-  devicePixelWidth: number;
-  /** Exact height of canvas in physical pixels (tracked by a ResizeObserver) */
-  devicePixelHeight: number;
-
-  /** Width of drawing buffer: automatically tracks this.pixelWidth if props.autoResize is true */
-  drawingBufferWidth: number;
-  /** Height of drawing buffer: automatically tracks this.pixelHeight if props.autoResize is true */
-  drawingBufferHeight: number;
-
-  /** Resolves when the canvas is initialized, i.e. when the ResizeObserver has updated the pixel size */
-  protected _initializedResolvers = withResolvers<void>();
-  /** ResizeObserver to track canvas size changes */
-  protected readonly _resizeObserver: ResizeObserver | undefined;
-  /** IntersectionObserver to track canvas visibility changes */
-  protected readonly _intersectionObserver: IntersectionObserver | undefined;
-  private _observeDevicePixelRatioTimeout: ReturnType<typeof setTimeout> | null = null;
-  /** Position of the canvas in the document, updated by a timer */
-  protected _position: [number, number] = [0, 0];
-  /** Whether this canvas context has been destroyed */
-  protected destroyed = false;
-  /** Whether the drawing buffer size needs to be resized (deferred resizing to avoid flicker) */
-  protected _needsDrawingBufferResize: boolean = true;
-
-  abstract get [Symbol.toStringTag](): string;
-
-  toString(): string {
-    return `${this[Symbol.toStringTag]}(${this.id})`;
-  }
-
-  constructor(props?: CanvasContextProps) {
-    this.props = {...CanvasContext.defaultProps, ...props};
-    props = this.props;
-
-    this.initialized = this._initializedResolvers.promise;
-
-    // Create a canvas element if needed
-    if (!isBrowser()) {
-      // TODO - does this prevent app from using jsdom style polyfills?
-      this.canvas = {width: props.width || 1, height: props.height || 1} as OffscreenCanvas;
-    } else if (!props.canvas) {
-      this.canvas = createCanvasElement(props);
-    } else if (typeof props.canvas === 'string') {
-      this.canvas = getCanvasFromDOM(props.canvas);
-    } else {
-      this.canvas = props.canvas;
-    }
-
-    if (CanvasContext.isHTMLCanvas(this.canvas)) {
-      this.id = props.id || this.canvas.id;
-      this.type = 'html-canvas';
-      this.htmlCanvas = this.canvas;
-    } else if (CanvasContext.isOffscreenCanvas(this.canvas)) {
-      this.id = props.id || 'offscreen-canvas';
-      this.type = 'offscreen-canvas';
-      this.offscreenCanvas = this.canvas;
-    } else {
-      // TODO - Node.js support is currently untested (was used for headless-gl in luma v8)
-      this.id = props.id || 'node-canvas-context';
-      this.type = 'node';
-    }
-
-    // Initialize size variables to some sane values (these will be updated by ResizeObserver)
-    this.cssWidth = this.htmlCanvas?.clientWidth || this.canvas.width;
-    this.cssHeight = this.htmlCanvas?.clientHeight || this.canvas.height;
-    this.devicePixelWidth = this.canvas.width;
-    this.devicePixelHeight = this.canvas.height;
-    this.drawingBufferWidth = this.canvas.width;
-    this.drawingBufferHeight = this.canvas.height;
-    this.devicePixelRatio = globalThis.devicePixelRatio || 1;
-    this._position = [0, 0];
-
-    if (CanvasContext.isHTMLCanvas(this.canvas)) {
-      // Track visibility changes
-      this._intersectionObserver = new IntersectionObserver(entries =>
-        this._handleIntersection(entries)
-      );
-      this._intersectionObserver.observe(this.canvas);
-
-      // Track size changes
-      this._resizeObserver = new ResizeObserver(entries => this._handleResize(entries));
-      try {
-        this._resizeObserver.observe(this.canvas, {box: 'device-pixel-content-box'});
-      } catch {
-        // Safari fallback
-        this._resizeObserver.observe(this.canvas, {box: 'content-box'});
-      }
-
-      // Track device pixel ratio changes.
-      // Defer call to after construction completes to ensure `this.device` is available.
-      this._observeDevicePixelRatioTimeout = setTimeout(() => this._observeDevicePixelRatio(), 0);
-
-      // Track top/left position changes
-      if (this.props.trackPosition) {
-        this._trackPosition();
-      }
-    }
-  }
-
-  destroy() {
-    if (!this.destroyed) {
-      this.destroyed = true;
-      if (this._observeDevicePixelRatioTimeout) {
-        clearTimeout(this._observeDevicePixelRatioTimeout);
-        this._observeDevicePixelRatioTimeout = null;
-      }
-      // @ts-expect-error Clear the device to make sure we don't access it after destruction.
-      this.device = null;
-      // Disconnect observers to prevent callbacks from firing after destruction
-      this._resizeObserver?.disconnect();
-      this._intersectionObserver?.disconnect();
-    }
-  }
-
-  setProps(props: MutableCanvasContextProps): this {
-    if ('useDevicePixels' in props) {
-      this.props.useDevicePixels = props.useDevicePixels || false;
-      this._updateDrawingBufferSize();
-    }
-    return this;
-  }
-
-  /** Returns a framebuffer with properly resized current 'swap chain' textures */
-  getCurrentFramebuffer(options?: {
-    depthStencilFormat?: TextureFormatDepthStencil | false;
-  }): Framebuffer {
-    this._resizeDrawingBufferIfNeeded();
-    return this._getCurrentFramebuffer(options);
-  }
-
-  // SIZE METHODS
-
-  /**
-   * Returns the size covered by the canvas in CSS pixels
-   * @note This can be different from the actual device pixel size of a canvas due to DPR scaling, and rounding to integer pixels
-   * @note This is independent of the canvas' internal drawing buffer size (.width, .height).
-   */
-  getCSSSize(): [number, number] {
-    return [this.cssWidth, this.cssHeight];
-  }
-
-  getPosition() {
-    return this._position;
-  }
-
-  /**
-   * Returns the size covered by the canvas in actual device pixels.
-   * @note This can be different from the 'CSS' size of a canvas due to DPR scaling, and rounding to integer pixels
-   * @note This is independent of the canvas' internal drawing buffer size (.width, .height).
-   */
-  getDevicePixelSize(): [number, number] {
-    return [this.devicePixelWidth, this.devicePixelHeight];
-  }
-
-  /** Get the drawing buffer size (number of pixels GPU is rendering into, can be different from CSS size) */
-  getDrawingBufferSize(): [number, number] {
-    return [this.drawingBufferWidth, this.drawingBufferHeight];
-  }
-
-  /** Returns the biggest allowed framebuffer size. @todo Allow the application to limit this? */
-  getMaxDrawingBufferSize(): [number, number] {
-    const maxTextureDimension = this.device.limits.maxTextureDimension2D;
-    return [maxTextureDimension, maxTextureDimension];
-  }
-
-  /**
-   * Update the canvas drawing buffer size.
-   * @note - Called automatically if props.autoResize is true.
-   * @note - Defers update of drawing buffer size until framebuffer is requested to avoid flicker
-   * (resizing clears the drawing buffer)!
-   */
-  setDrawingBufferSize(width: number, height: number) {
-    width = Math.floor(width);
-    height = Math.floor(height);
-    if (this.drawingBufferWidth === width && this.drawingBufferHeight === height) {
-      return;
-    }
-    // TODO(ib) - temporarily makes drawingBufferWidth/Height out of sync with canvas.width/height, could that cause issues?
-    this.drawingBufferWidth = width;
-    this.drawingBufferHeight = height;
-    this._needsDrawingBufferResize = true;
-  }
-
-  /**
-   * Returns the current DPR (number of physical pixels per CSS pixel), if props.useDevicePixels is true
-   * @note This can be a fractional (non-integer) number, e.g. when the user zooms in the browser.
-   * @note This function handles the non-HTML canvas cases
-   */
-  getDevicePixelRatio(): number {
-    const dpr = typeof window !== 'undefined' && window.devicePixelRatio;
-    return dpr || 1;
-  }
-
-  // DEPRECATED METHODS
-
-  /**
-   * Maps CSS pixel position to device pixel position
-   */
-  cssToDevicePixels(
-    cssPixel: [number, number],
-    yInvert: boolean = true
-  ): {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-  } {
-    const ratio = this.cssToDeviceRatio();
-    const [width, height] = this.getDrawingBufferSize();
-    return scalePixels(cssPixel, ratio, width, height, yInvert);
-  }
-
-  /** @deprecated - use .getDevicePixelSize() */
-  getPixelSize() {
-    return this.getDevicePixelSize();
-  }
-
-  /** @deprecated - TODO which values should we use for aspect */
-  getAspect(): number {
-    const [width, height] = this.getDevicePixelSize();
-    return width / height;
-  }
-
-  /** @deprecated Returns multiplier need to convert CSS size to Device size */
-  cssToDeviceRatio(): number {
-    try {
-      const [drawingBufferWidth] = this.getDrawingBufferSize();
-      const [cssWidth] = this.getCSSSize();
-      return cssWidth ? drawingBufferWidth / cssWidth : 1;
-    } catch {
-      return 1;
-    }
-  }
-
-  /** @deprecated Use canvasContext.setDrawingBufferSize() */
-  resize(size: {width: number; height: number}): void {
-    this.setDrawingBufferSize(size.width, size.height);
-  }
-
-  // SUBCLASS OVERRIDES
-
-  /**
-   * Performs platform specific updates (WebGPU vs WebGL)
-   * Can be called after changes to size or props,
-   * to give implementation an opportunity to update configurations.
-   */
-  protected abstract _configureDevice(): void;
-
-  /** Returns a framebuffer with properly resized current 'swap chain' textures */
-  protected abstract _getCurrentFramebuffer(options?: {
-    depthStencilFormat?: TextureFormatDepthStencil | false;
-  }): Framebuffer;
-
-  // IMPLEMENTATION
-
-  /**
-   * Allows subclass constructor to override the canvas id for auto created canvases.
-   * This can really help when debugging DOM in apps that create multiple devices
-   */
-  protected _setAutoCreatedCanvasId(id: string) {
-    if (this.htmlCanvas?.id === 'lumagl-auto-created-canvas') {
-      this.htmlCanvas.id = id;
-    }
-  }
-
-  /** reacts to an observed intersection */
-  protected _handleIntersection(entries: IntersectionObserverEntry[]) {
-    if (this.destroyed) {
-      return;
-    }
-
-    const entry = entries.find(entry_ => entry_.target === this.canvas);
-    if (!entry) {
-      return;
-    }
-    // TODO - store intersection rectangle?
-    const isVisible = entry.isIntersecting;
-    if (this.isVisible !== isVisible) {
-      this.isVisible = isVisible;
-      this.device.props.onVisibilityChange(this);
-    }
-  }
-
-  /**
-   * Reacts to an observed resize by using the most accurate pixel size information the browser can provide
-   * @see https://web.dev/articles/device-pixel-content-box
-   * @see https://webgpufundamentals.org/webgpu/lessons/webgpu-resizing-the-canvas.html
-   */
-  protected _handleResize(entries: ResizeObserverEntry[]) {
-    if (this.destroyed) {
-      return;
-    }
-
-    const entry = entries.find(entry_ => entry_.target === this.canvas);
-    if (!entry) {
-      return;
-    }
-
-    const contentBoxSize = assertDefined(entry.contentBoxSize?.[0]);
-    // Update CSS size using content box size
-    this.cssWidth = contentBoxSize.inlineSize;
-    this.cssHeight = contentBoxSize.blockSize;
-
-    // Update our drawing buffer size variables, saving the old values for logging
-    const oldPixelSize = this.getDevicePixelSize();
-
-    // Use the most accurate drawing buffer size information the current browser can provide
-    // Note: content box sizes are guaranteed to be integers
-    // Note: Safari falls back to contentBoxSize
-    const devicePixelWidth =
-      entry.devicePixelContentBoxSize?.[0]?.inlineSize ||
-      contentBoxSize.inlineSize * devicePixelRatio;
-
-    const devicePixelHeight =
-      entry.devicePixelContentBoxSize?.[0]?.blockSize ||
-      contentBoxSize.blockSize * devicePixelRatio;
-
-    // Make sure we don't overflow the maximum supported texture size
-    const [maxDevicePixelWidth, maxDevicePixelHeight] = this.getMaxDrawingBufferSize();
-    this.devicePixelWidth = Math.max(1, Math.min(devicePixelWidth, maxDevicePixelWidth));
-    this.devicePixelHeight = Math.max(1, Math.min(devicePixelHeight, maxDevicePixelHeight));
-
-    this._updateDrawingBufferSize();
-
-    // Inform the device
-    this.device.props.onResize(this, {oldPixelSize});
-  }
-
-  /** Initiate a deferred update for the canvas drawing buffer size */
-  protected _updateDrawingBufferSize() {
-    // Update the canvas drawing buffer size
-    if (this.props.autoResize) {
-      if (typeof this.props.useDevicePixels === 'number') {
-        const dpr = this.props.useDevicePixels;
-        this.setDrawingBufferSize(this.cssWidth * dpr, this.cssHeight * dpr);
-      } else if (this.props.useDevicePixels) {
-        this.setDrawingBufferSize(this.devicePixelWidth, this.devicePixelHeight);
-      } else {
-        this.setDrawingBufferSize(this.cssWidth, this.cssHeight);
-      }
-    }
-
-    // Resolve the initialized promise
-    this._initializedResolvers.resolve();
-    this.isInitialized = true;
-
-    this.updatePosition();
-  }
-
-  /** Perform a deferred resize of the drawing buffer if needed */
-  _resizeDrawingBufferIfNeeded() {
-    if (this._needsDrawingBufferResize) {
-      this._needsDrawingBufferResize = false;
-      const sizeChanged =
-        this.drawingBufferWidth !== this.canvas.width ||
-        this.drawingBufferHeight !== this.canvas.height;
-      if (sizeChanged) {
-        // Update the canvas size
-        this.canvas.width = this.drawingBufferWidth;
-        this.canvas.height = this.drawingBufferHeight;
-        // Inform the subclass: WebGPU needs to call canvascontext.configure()
-        this._configureDevice();
-      }
-    }
-  }
-
-  /** Monitor DPR changes */
-  _observeDevicePixelRatio() {
-    if (this.destroyed) {
-      return;
-    }
-    const oldRatio = this.devicePixelRatio;
-    this.devicePixelRatio = window.devicePixelRatio;
-
-    this.updatePosition();
-
-    // Inform the device
-    this.device.props.onDevicePixelRatioChange?.(this, {oldRatio});
-    // Set up a one time query against the current resolution.
-    matchMedia(`(resolution: ${this.devicePixelRatio}dppx)`).addEventListener(
-      'change',
-      () => this._observeDevicePixelRatio(),
-      {once: true}
-    );
-  }
-
-  /** Start tracking positions with a timer */
-  _trackPosition(intervalMs: number = 100): void {
-    const intervalId = setInterval(() => {
-      if (this.destroyed) {
-        clearInterval(intervalId);
-      } else {
-        this.updatePosition();
-      }
-    }, intervalMs);
-  }
-
-  /**
-   * Calculated the absolute position of the canvas
-   * @note - getBoundingClientRect() is normally cheap but can be expensive
-   * if called before browser has finished a reflow. Should not be the case here.
-   */
-  updatePosition() {
-    if (this.destroyed) {
-      return;
-    }
-    const newRect = this.htmlCanvas?.getBoundingClientRect();
-    if (newRect) {
-      // We only track position since we rely on the more precise ResizeObserver for size
-      const position: [number, number] = [newRect.left, newRect.top];
-      this._position ??= position;
-      const positionChanged =
-        position[0] !== this._position[0] || position[1] !== this._position[1];
-      if (positionChanged) {
-        const oldPosition = this._position;
-        this._position = position;
-        this.device.props.onPositionChange?.(this, {oldPosition});
-      }
-    }
-  }
-}
-
-// HELPER FUNCTIONS
-
-/** Get a container element from a string or DOM element */
-function getContainer(container: HTMLElement | string | null): HTMLElement {
-  if (typeof container === 'string') {
-    const element = document.getElementById(container);
-    if (!element) {
-      throw new Error(`${container} is not an HTML element`);
-    }
-    return element;
-  }
-  if (container) {
-    return container;
-  }
-  return document.body;
-}
-
-/** Get a Canvas element from DOM id */
-function getCanvasFromDOM(canvasId: string): HTMLCanvasElement {
-  const canvas = document.getElementById(canvasId);
-  if (!CanvasContext.isHTMLCanvas(canvas)) {
-    throw new Error('Object is not a canvas element');
-  }
-  return canvas;
-}
-
-/** Create a new canvas */
-function createCanvasElement(props: CanvasContextProps) {
-  const {width, height} = props;
-  const newCanvas = document.createElement('canvas');
-  newCanvas.id = uid('lumagl-auto-created-canvas');
-  newCanvas.width = width || 1;
-  newCanvas.height = height || 1;
-  newCanvas.style.width = Number.isFinite(width) ? `${width}px` : '100%';
-  newCanvas.style.height = Number.isFinite(height) ? `${height}px` : '100%';
-  if (!props?.visible) {
-    newCanvas.style.visibility = 'hidden';
-  }
-  // Insert the canvas in the DOM
-  const container = getContainer(props?.container || null);
-  container.insertBefore(newCanvas, container.firstChild);
-
-  return newCanvas;
-}
+export type {CanvasContextProps, MutableCanvasContextProps} from './canvas-surface';
+import {CanvasSurface} from './canvas-surface';
 
 /**
- * Scales pixels linearly, handles edge cases
- * @param pixel
- * @param ratio
- * @param width
- * @param height
- * @param yInvert
- * @returns
+ * Manages a renderable backend canvas. Supports both HTML or offscreen canvas
+ * and returns backend framebuffers sourced from the canvas itself.
  */
-function scalePixels(
-  pixel: [number, number],
-  ratio: number,
-  width: number,
-  height: number,
-  yInvert: boolean
-): {
-  x: number;
-  y: number;
-  width: number;
-  height: number;
-} {
-  const point = pixel;
-
-  const x = scaleX(point[0], ratio, width);
-  let y = scaleY(point[1], ratio, height, yInvert);
-
-  // Find boundaries of next pixel to provide valid range of device pixel locations
-
-  let t = scaleX(point[0] + 1, ratio, width);
-  // If next pixel's position is clamped to boundary, use it as is, otherwise subtract 1 for current pixel boundary
-  const xHigh = t === width - 1 ? t : t - 1;
-
-  t = scaleY(point[1] + 1, ratio, height, yInvert);
-  let yHigh;
-  if (yInvert) {
-    // If next pixel's position is clamped to boundary, use it as is, otherwise clamp it to valid range
-    t = t === 0 ? t : t + 1;
-    // swap y and yHigh
-    yHigh = y;
-    y = t;
-  } else {
-    // If next pixel's position is clamped to boundary, use it as is, otherwise clamp it to valid range
-    yHigh = t === height - 1 ? t : t - 1;
-    // y remains same
-  }
-  return {
-    x,
-    y,
-    // when ratio < 1, current css pixel and next css pixel may point to same device pixel, set width/height to 1 in those cases.
-    width: Math.max(xHigh - x + 1, 1),
-    height: Math.max(yHigh - y + 1, 1)
-  };
-}
-
-function scaleX(x: number, ratio: number, width: number): number {
-  // since we are rounding to nearest, when ratio > 1, edge pixels may point to out of bounds value, clamp to the limit
-  const r = Math.min(Math.round(x * ratio), width - 1);
-  return r;
-}
+export abstract class CanvasContext extends CanvasSurface {
+  static override defaultProps = CanvasSurface.defaultProps;
 
-function scaleY(y: number, ratio: number, height: number, yInvert: boolean): number {
-  // since we are rounding to nearest, when ratio > 1, edge pixels may point to out of bounds value, clamp to the limit
-  return yInvert
-    ? Math.max(0, height - 1 - Math.round(y * ratio))
-    : Math.min(Math.round(y * ratio), height - 1);
+  abstract override readonly handle: unknown;
 }