@luma.gl/core 9.3.3 → 9.3.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luma.gl/core",
-  "version": "9.3.3",
+  "version": "9.3.5",
   "description": "The luma.gl core Device API",
   "license": "MIT",
   "type": "module",
@@ -46,5 +46,5 @@
     "@probe.gl/stats": "^4.1.1",
     "@types/offscreencanvas": "^2019.7.3"
   },
-  "gitHead": "1069000732d3dd5ba6e41f9ad958a7f274125ef4"
+  "gitHead": "7c66d63f213836a3fc83f2ad0103d1d3dadf7633"
 }

package/src/adapter/canvas-observer.ts

@@ -2,22 +2,33 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
+/** Options and callbacks used by {@link CanvasObserver}. */
 type CanvasObserverProps = {
+  /** HTML canvas element whose DOM lifecycle should be observed. */
   canvas?: HTMLCanvasElement;
+  /** Whether to poll for canvas position changes. */
   trackPosition: boolean;
+  /** ResizeObserver box type passed to `observe()`. */
+  resizeObserverBox: ResizeObserverBoxOptions;
+  /** Called with ResizeObserver entries for the observed canvas. */
   onResize: (entries: ResizeObserverEntry[]) => void;
+  /** Called with IntersectionObserver entries for the observed canvas. */
   onIntersection: (entries: IntersectionObserverEntry[]) => void;
+  /** Called when the window device pixel ratio may have changed. */
   onDevicePixelRatioChange: () => void;
+  /** Called while canvas position tracking is enabled. */
   onPositionChange: () => void;
 };
 
 /**
  * Internal DOM observer orchestration for HTML canvas surfaces.
  *
+ * @remarks
  * CanvasSurface owns the tracked state and device callback dispatch. This helper only manages
  * browser observers, timers, and polling loops, then reports events through callbacks.
  */
 export class CanvasObserver {
+  /** Observer options and event callbacks. */
   readonly props: CanvasObserverProps;
 
   private _resizeObserver: ResizeObserver | undefined;
@@ -28,14 +39,21 @@ export class CanvasObserver {
   private _trackPositionInterval: ReturnType<typeof setInterval> | null = null;
   private _started = false;
 
+  /** Whether the DOM observers and polling loops have been started. */
   get started(): boolean {
     return this._started;
   }
 
+  /**
+   * Creates an observer coordinator for one HTML canvas.
+   *
+   * @param props - Observer options and event callbacks.
+   */
   constructor(props: CanvasObserverProps) {
     this.props = props;
   }
 
+  /** Starts DOM observation and optional position polling. */
   start(): void {
     if (this._started || !this.props.canvas) {
       return;
@@ -48,8 +66,9 @@ export class CanvasObserver {
     this._resizeObserver ||= new ResizeObserver(entries => this.props.onResize(entries));
 
     this._intersectionObserver.observe(this.props.canvas);
+    const box = this.props.resizeObserverBox;
     try {
-      this._resizeObserver.observe(this.props.canvas, {box: 'device-pixel-content-box'});
+      this._resizeObserver.observe(this.props.canvas, {box});
     } catch {
       this._resizeObserver.observe(this.props.canvas, {box: 'content-box'});
     }
@@ -61,6 +80,7 @@ export class CanvasObserver {
     }
   }
 
+  /** Stops DOM observation, media-query listeners, and position polling. */
   stop(): void {
     if (!this._started) {
       return;
@@ -90,6 +110,7 @@ export class CanvasObserver {
     this._intersectionObserver?.disconnect();
   }
 
+  /** Reports the current device pixel ratio and arms the media query for its next change. */
   private _refreshDevicePixelRatio(): void {
     if (!this._started) {
       return;
@@ -111,6 +132,11 @@ export class CanvasObserver {
     );
   }
 
+  /**
+   * Starts periodic position callbacks while the observer remains active.
+   *
+   * @param intervalMs - Poll interval in milliseconds.
+   */
   private _trackPosition(intervalMs: number = 100): void {
     if (this._trackPositionInterval) {
       return;

package/src/adapter/canvas-surface.ts

@@ -29,6 +29,15 @@ export type CanvasContextProps = {
   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;
+  /**
+   * How to derive the tracked device pixel size for HTML canvases when auto-resizing.
+   *
+   * - `'exact'` uses `ResizeObserver.devicePixelContentBoxSize` when available to match the
+   *   browser's exact physical pixel coverage.
+   * - `'css-dpr'` uses `Math.floor(cssSize * devicePixelRatio)` to match overlays and external
+   *   canvases that size their drawing buffer via implicit truncation (e.g. `canvas.width = css * dpr`).
+   */
+  pixelSizeSource?: 'exact' | 'css-dpr';
   /** Whether to track window resizes. */
   autoResize?: boolean;
   /** @see https://developer.mozilla.org/en-US/docs/Web/API/GPUCanvasContext/configure#alphamode */
@@ -44,6 +53,11 @@ export type MutableCanvasContextProps = {
   useDevicePixels?: boolean | number;
 };
 
+type DevicePixelSize = {
+  devicePixelWidth: number;
+  devicePixelHeight: number;
+};
+
 /**
  * Shared tracked-canvas lifecycle used by both renderable and presentation contexts.
  * - Creates a new canvas or looks up a canvas from the DOM
@@ -66,6 +80,7 @@ export abstract class CanvasSurface {
     width: 800,
     height: 600,
     useDevicePixels: true,
+    pixelSizeSource: 'exact',
     autoResize: true,
     container: null,
     visible: true,
@@ -166,6 +181,8 @@ export abstract class CanvasSurface {
     this._canvasObserver = new CanvasObserver({
       canvas: this.htmlCanvas,
       trackPosition: this.props.trackPosition,
+      resizeObserverBox:
+        this.props.pixelSizeSource === 'css-dpr' ? 'content-box' : 'device-pixel-content-box',
       onResize: entries => this._handleResize(entries),
       onIntersection: entries => this._handleIntersection(entries),
       onDevicePixelRatioChange: () => this._observeDevicePixelRatio(),
@@ -347,17 +364,7 @@ export abstract class CanvasSurface {
 
     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._setDevicePixelSize(this._getDevicePixelSizeFromResizeEntry(entry));
 
     this._updateDrawingBufferSize();
 
@@ -385,6 +392,40 @@ export abstract class CanvasSurface {
     this.updatePosition();
   }
 
+  protected _getDevicePixelSizeFromResizeEntry(entry: ResizeObserverEntry): DevicePixelSize {
+    const contentBoxSize = assertDefined(entry.contentBoxSize?.[0]);
+
+    if (this.props.pixelSizeSource === 'css-dpr') {
+      return this._getDevicePixelSizeFromCSSSize(
+        contentBoxSize.inlineSize,
+        contentBoxSize.blockSize
+      );
+    }
+
+    return {
+      devicePixelWidth:
+        entry.devicePixelContentBoxSize?.[0]?.inlineSize ||
+        contentBoxSize.inlineSize * devicePixelRatio,
+      devicePixelHeight:
+        entry.devicePixelContentBoxSize?.[0]?.blockSize ||
+        contentBoxSize.blockSize * devicePixelRatio
+    };
+  }
+
+  protected _getDevicePixelSizeFromCSSSize(cssWidth: number, cssHeight: number): DevicePixelSize {
+    const devicePixelRatio = this.getDevicePixelRatio();
+    return {
+      devicePixelWidth: Math.floor(cssWidth * devicePixelRatio),
+      devicePixelHeight: Math.floor(cssHeight * devicePixelRatio)
+    };
+  }
+
+  protected _setDevicePixelSize({devicePixelWidth, devicePixelHeight}: DevicePixelSize): void {
+    const [maxDevicePixelWidth, maxDevicePixelHeight] = this.getMaxDrawingBufferSize();
+    this.devicePixelWidth = Math.max(1, Math.min(devicePixelWidth, maxDevicePixelWidth));
+    this.devicePixelHeight = Math.max(1, Math.min(devicePixelHeight, maxDevicePixelHeight));
+  }
+
   _resizeDrawingBufferIfNeeded() {
     if (this._needsDrawingBufferResize) {
       this._needsDrawingBufferResize = false;
@@ -406,6 +447,15 @@ export abstract class CanvasSurface {
     const oldRatio = this.devicePixelRatio;
     this.devicePixelRatio = window.devicePixelRatio;
 
+    if (this.props.pixelSizeSource === 'css-dpr') {
+      // In css-dpr mode the ResizeObserver watches content-box, which won't fire on a pure DPR
+      // change (CSS size unchanged). Recalculate the drawing buffer from the new DPR here.
+      const oldPixelSize = this.getDevicePixelSize();
+      this._setDevicePixelSize(this._getDevicePixelSizeFromCSSSize(this.cssWidth, this.cssHeight));
+      this._updateDrawingBufferSize();
+      this.device.props.onResize(this as CanvasContext | PresentationContext, {oldPixelSize});
+    }
+
     this.updatePosition();
 
     this.device.props.onDevicePixelRatioChange?.(this as CanvasContext | PresentationContext, {