@luma.gl/core/dist/adapter/canvas-surface.d.ts

The luma.gl core Device API

import type { Device } from "./device.js";
import { CanvasObserver } from "./canvas-observer.js";
import type { Framebuffer } from "./resources/framebuffer.js";
import type { TextureFormatDepthStencil } from "../shadertypes/texture-types/texture-formats.js";
/** 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';
    /** 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 declare abstract class CanvasSurface {
    static isHTMLCanvas(canvas: unknown): canvas is HTMLCanvasElement;
    static isOffscreenCanvas(canvas: unknown): canvas is OffscreenCanvas;
    static defaultProps: Required<CanvasContextProps>;
    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;
    /** Visibility is automatically updated (via an IntersectionObserver) */
    isVisible: boolean;
    /** 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: {
        promise: Promise<void>;
        resolve: (t: void) => void;
        reject: (error: Error) => void;
    };
    protected _canvasObserver: CanvasObserver;
    /** Position of the canvas in the document, updated by a timer */
    protected _position: [number, number];
    /** Whether this canvas context has been destroyed */
    protected destroyed: boolean;
    /** Whether the drawing buffer size needs to be resized (deferred resizing to avoid flicker) */
    protected _needsDrawingBufferResize: boolean;
    abstract get [Symbol.toStringTag](): string;
    toString(): string;
    constructor(props?: CanvasContextProps);
    destroy(): void;
    setProps(props: MutableCanvasContextProps): this;
    /** Returns a framebuffer with properly resized current 'swap chain' textures */
    getCurrentFramebuffer(options?: {
        depthStencilFormat?: TextureFormatDepthStencil | false;
    }): Framebuffer;
    getCSSSize(): [number, number];
    getPosition(): [number, number];
    getDevicePixelSize(): [number, number];
    getDrawingBufferSize(): [number, number];
    getMaxDrawingBufferSize(): [number, number];
    setDrawingBufferSize(width: number, height: number): void;
    getDevicePixelRatio(): number;
    cssToDevicePixels(cssPixel: [number, number], yInvert?: boolean): {
        x: number;
        y: number;
        width: number;
        height: number;
    };
    /** @deprecated - use .getDevicePixelSize() */
    getPixelSize(): [number, number];
    /** @deprecated Use the current drawing buffer size for projection setup. */
    getAspect(): number;
    /** @deprecated Returns multiplier need to convert CSS size to Device size */
    cssToDeviceRatio(): number;
    /** @deprecated Use canvasContext.setDrawingBufferSize() */
    resize(size: {
        width: number;
        height: number;
    }): void;
    protected abstract _configureDevice(): void;
    protected abstract _getCurrentFramebuffer(options?: {
        depthStencilFormat?: TextureFormatDepthStencil | false;
    }): Framebuffer;
    protected _setAutoCreatedCanvasId(id: string): void;
    /**
     * 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;
    /**
     * 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;
    protected _handleIntersection(entries: IntersectionObserverEntry[]): void;
    protected _handleResize(entries: ResizeObserverEntry[]): void;
    protected _updateDrawingBufferSize(): void;
    _resizeDrawingBufferIfNeeded(): void;
    _observeDevicePixelRatio(): void;
    updatePosition(): void;
}
//# sourceMappingURL=canvas-surface.d.ts.map