@luma.gl/core 9.2.6 → 9.3.0-alpha.10

package/src/adapter/canvas-surface.ts

@@ -0,0 +1,521 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {isBrowser} from '@probe.gl/env';
+import type {Device} from './device';
+import type {CanvasContext} from './canvas-context';
+import {CanvasObserver} from './canvas-observer';
+import type {PresentationContext} from './presentation-context';
+import type {Framebuffer} from './resources/framebuffer';
+import type {TextureFormatDepthStencil} from '../shadertypes/texture-types/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;
+};
+
+/**
+ * Shared tracked-canvas lifecycle used by both renderable and presentation contexts.
+ * - 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 CanvasSurface {
+  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>();
+  protected _canvasObserver: CanvasObserver;
+  /** 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 = {...CanvasSurface.defaultProps, ...props};
+    props = this.props;
+
+    this.initialized = this._initializedResolvers.promise;
+
+    if (!isBrowser()) {
+      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 (CanvasSurface.isHTMLCanvas(this.canvas)) {
+      this.id = props.id || this.canvas.id;
+      this.type = 'html-canvas';
+      this.htmlCanvas = this.canvas;
+    } else if (CanvasSurface.isOffscreenCanvas(this.canvas)) {
+      this.id = props.id || 'offscreen-canvas';
+      this.type = 'offscreen-canvas';
+      this.offscreenCanvas = this.canvas;
+    } else {
+      this.id = props.id || 'node-canvas-context';
+      this.type = 'node';
+    }
+
+    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];
+    this._canvasObserver = new CanvasObserver({
+      canvas: this.htmlCanvas,
+      trackPosition: this.props.trackPosition,
+      onResize: entries => this._handleResize(entries),
+      onIntersection: entries => this._handleIntersection(entries),
+      onDevicePixelRatioChange: () => this._observeDevicePixelRatio(),
+      onPositionChange: () => this.updatePosition()
+    });
+  }
+
+  destroy() {
+    if (!this.destroyed) {
+      this.destroyed = true;
+      this._stopObservers();
+      // @ts-expect-error Clear the device to make sure we don't access it after destruction.
+      this.device = null;
+    }
+  }
+
+  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);
+  }
+
+  getCSSSize(): [number, number] {
+    return [this.cssWidth, this.cssHeight];
+  }
+
+  getPosition() {
+    return this._position;
+  }
+
+  getDevicePixelSize(): [number, number] {
+    return [this.devicePixelWidth, this.devicePixelHeight];
+  }
+
+  getDrawingBufferSize(): [number, number] {
+    return [this.drawingBufferWidth, this.drawingBufferHeight];
+  }
+
+  getMaxDrawingBufferSize(): [number, number] {
+    const maxTextureDimension = this.device.limits.maxTextureDimension2D;
+    return [maxTextureDimension, maxTextureDimension];
+  }
+
+  setDrawingBufferSize(width: number, height: number) {
+    width = Math.floor(width);
+    height = Math.floor(height);
+    if (this.drawingBufferWidth === width && this.drawingBufferHeight === height) {
+      return;
+    }
+    this.drawingBufferWidth = width;
+    this.drawingBufferHeight = height;
+    this._needsDrawingBufferResize = true;
+  }
+
+  getDevicePixelRatio(): number {
+    const devicePixelRatio = typeof window !== 'undefined' && window.devicePixelRatio;
+    return devicePixelRatio || 1;
+  }
+
+  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 Use the current drawing buffer size for projection setup. */
+  getAspect(): number {
+    const [width, height] = this.getDrawingBufferSize();
+    return width > 0 && height > 0 ? width / height : 1;
+  }
+
+  /** @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);
+  }
+
+  protected abstract _configureDevice(): void;
+
+  protected abstract _getCurrentFramebuffer(options?: {
+    depthStencilFormat?: TextureFormatDepthStencil | false;
+  }): Framebuffer;
+
+  protected _setAutoCreatedCanvasId(id: string) {
+    if (this.htmlCanvas?.id === 'lumagl-auto-created-canvas') {
+      this.htmlCanvas.id = id;
+    }
+  }
+
+  /**
+   * Starts DOM observation after the derived context and its device are fully initialized.
+   *
+   * `CanvasSurface` construction runs before subclasses can assign `this.device`, and the
+   * default WebGL canvas context is created before `WebGLDevice` has initialized `limits`,
+   * `features`, and the rest of its runtime state. Deferring observer startup avoids early
+   * `ResizeObserver` and DPR callbacks running against a partially initialized device.
+   */
+  _startObservers(): void {
+    if (this.destroyed) {
+      return;
+    }
+    this._canvasObserver.start();
+  }
+
+  /**
+   * Stops all DOM observation and timers associated with a canvas surface.
+   *
+   * This pairs with `_startObservers()` so teardown uses the same lifecycle whether a context is
+   * explicitly destroyed, abandoned during device reuse, or temporarily has not started observing
+   * yet. Centralizing shutdown here keeps resize/DPR/position watchers from surviving past the
+   * lifetime of the owning device.
+   */
+  _stopObservers(): void {
+    this._canvasObserver.stop();
+  }
+
+  protected _handleIntersection(entries: IntersectionObserverEntry[]) {
+    if (this.destroyed) {
+      return;
+    }
+
+    const entry = entries.find(entry_ => entry_.target === this.canvas);
+    if (!entry) {
+      return;
+    }
+    const isVisible = entry.isIntersecting;
+    if (this.isVisible !== isVisible) {
+      this.isVisible = isVisible;
+      this.device.props.onVisibilityChange(this as CanvasContext | PresentationContext);
+    }
+  }
+
+  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]);
+    this.cssWidth = contentBoxSize.inlineSize;
+    this.cssHeight = contentBoxSize.blockSize;
+
+    const oldPixelSize = this.getDevicePixelSize();
+
+    const devicePixelWidth =
+      entry.devicePixelContentBoxSize?.[0]?.inlineSize ||
+      contentBoxSize.inlineSize * devicePixelRatio;
+
+    const devicePixelHeight =
+      entry.devicePixelContentBoxSize?.[0]?.blockSize ||
+      contentBoxSize.blockSize * devicePixelRatio;
+
+    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();
+
+    this.device.props.onResize(this as CanvasContext | PresentationContext, {oldPixelSize});
+  }
+
+  protected _updateDrawingBufferSize() {
+    if (this.props.autoResize) {
+      if (typeof this.props.useDevicePixels === 'number') {
+        const devicePixelRatio = this.props.useDevicePixels;
+        this.setDrawingBufferSize(
+          this.cssWidth * devicePixelRatio,
+          this.cssHeight * devicePixelRatio
+        );
+      } else if (this.props.useDevicePixels) {
+        this.setDrawingBufferSize(this.devicePixelWidth, this.devicePixelHeight);
+      } else {
+        this.setDrawingBufferSize(this.cssWidth, this.cssHeight);
+      }
+    }
+
+    this._initializedResolvers.resolve();
+    this.isInitialized = true;
+
+    this.updatePosition();
+  }
+
+  _resizeDrawingBufferIfNeeded() {
+    if (this._needsDrawingBufferResize) {
+      this._needsDrawingBufferResize = false;
+      const sizeChanged =
+        this.drawingBufferWidth !== this.canvas.width ||
+        this.drawingBufferHeight !== this.canvas.height;
+      if (sizeChanged) {
+        this.canvas.width = this.drawingBufferWidth;
+        this.canvas.height = this.drawingBufferHeight;
+        this._configureDevice();
+      }
+    }
+  }
+
+  _observeDevicePixelRatio() {
+    if (this.destroyed || !this._canvasObserver.started) {
+      return;
+    }
+    const oldRatio = this.devicePixelRatio;
+    this.devicePixelRatio = window.devicePixelRatio;
+
+    this.updatePosition();
+
+    this.device.props.onDevicePixelRatioChange?.(this as CanvasContext | PresentationContext, {
+      oldRatio
+    });
+  }
+
+  updatePosition() {
+    if (this.destroyed) {
+      return;
+    }
+    const newRect = this.htmlCanvas?.getBoundingClientRect();
+    if (newRect) {
+      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 as CanvasContext | PresentationContext, {
+          oldPosition
+        });
+      }
+    }
+  }
+}
+
+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;
+}
+
+function getCanvasFromDOM(canvasId: string): HTMLCanvasElement {
+  const canvas = document.getElementById(canvasId);
+  if (!CanvasSurface.isHTMLCanvas(canvas)) {
+    throw new Error('Object is not a canvas element');
+  }
+  return 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';
+  }
+  const container = getContainer(props?.container || null);
+  container.insertBefore(newCanvas, container.firstChild);
+
+  return newCanvas;
+}
+
+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);
+
+  let temporary = scaleX(point[0] + 1, ratio, width);
+  const xHigh = temporary === width - 1 ? temporary : temporary - 1;
+
+  temporary = scaleY(point[1] + 1, ratio, height, yInvert);
+  let yHigh;
+  if (yInvert) {
+    temporary = temporary === 0 ? temporary : temporary + 1;
+    yHigh = y;
+    y = temporary;
+  } else {
+    yHigh = temporary === height - 1 ? temporary : temporary - 1;
+  }
+  return {
+    x,
+    y,
+    width: Math.max(xHigh - x + 1, 1),
+    height: Math.max(yHigh - y + 1, 1)
+  };
+}
+
+function scaleX(x: number, ratio: number, width: number): number {
+  return Math.min(Math.round(x * ratio), width - 1);
+}
+
+function scaleY(y: number, ratio: number, height: number, yInvert: boolean): number {
+  return yInvert
+    ? Math.max(0, height - 1 - Math.round(y * ratio))
+    : Math.min(Math.round(y * ratio), height - 1);
+}