@thi.ng/canvas/index.d.ts

Canvas creation & HDPI support helpers

export interface Canvas2DOpts {
    /**
     * (Native) options passed to `canvas.getContext("2d")`
     */
    ctx: CanvasRenderingContext2DSettings;
    /**
     * If true, adds CSS rule to force canvas being displayed properly pixelated
     * (no smoothing)
     */
    pixelated: boolean;
}
export interface AdaptiveCanvas2DOpts extends Canvas2DOpts {
    /**
     * Device pixel ratio (aka scale value) to use for the canvas. By default
     * this will be sourced from the current `window.devicePixelRatio`, but this
     * option can be used if a specific fixed number of pixels is required (i.e.
     * set `dpr: 1` to ensure the `width` and `height` values given to
     * {@link canvas2d} _are_ the actual real pixel dimensions).
     *
     * Also see {@link adaptDPI} for more details.
     */
    dpr: number;
}
export interface CanvasContext {
    canvas: HTMLCanvasElement;
    ctx: CanvasRenderingContext2D;
}
export interface OffscreenCanvasContext {
    canvas: OffscreenCanvas;
    ctx: OffscreenCanvasRenderingContext2D;
}
export interface OffscreenCtxOpts {
    alpha: boolean;
    willReadFrequently: boolean;
    storage: string;
}
/**
 * Creates a canvas element of given size, obtains its 2D drawing context and
 * returns object of both. If `parent` is given, the canvas is appended to it as
 * child.
 *
 * @remarks
 * By default the actual pixel size of the canvas will depend of the
 * `windowDevicePixelRatio` of the current `window` object. To force a specific
 * fixed scale, use the {@link AdaptiveCanvas2DOpts.dpr} option. Also see
 * {@link adaptDPI} for details.
 *
 * @param width -
 * @param height -
 * @param parent -
 * @param opts -
 */
export declare const adaptiveCanvas2d: (width: number, height?: number, parent?: HTMLElement | null, opts?: Partial<AdaptiveCanvas2DOpts>) => CanvasContext;
/**
 * Convenience version of {@link adaptiveCanvas2d} with a fixed device pixel
 * ratio of 1.0 (to avoid any rescaling).
 *
 * @param width
 * @param height
 * @param parent
 * @param opts
 */
export declare const canvas2d: (width: number, height?: number, parent?: HTMLElement | null, opts?: Partial<Canvas2DOpts>) => CanvasContext;
/**
 * Convenience version of {@link canvas2d} which also enables the
 * {@link Canvas2DOpts.pixelated} option by default.
 *
 * @param width
 * @param height
 * @param parent
 * @param opts
 */
export declare const pixelCanvas2d: (width: number, height?: number, parent?: HTMLElement | null, opts?: Partial<Canvas2DOpts>) => CanvasContext;
export declare const offscreenCanvas2d: (width: number, height?: number, opts?: Partial<OffscreenCtxOpts>) => OffscreenCanvasContext;
/**
 * Creates a canvas and draws given image into it. The `width` and `height`
 * params default to the actual image size, but can be used to resize the image
 * (canvas).
 *
 * @remarks
 * See {@link adaptiveCanvas2d} for more details.
 *
 * @param img
 * @param width
 * @param height
 * @param parent
 * @param opts
 */
export declare const imageCanvas: (img: HTMLImageElement, width?: number, height?: number, parent?: HTMLElement | null, opts?: Partial<Canvas2DOpts>) => CanvasContext;
/**
 * Sets the canvas size to given `width` & `height` (given as CSS pixels, but
 * applied as device pixels) and adjusts canvas' `style` to compensate for HDPI
 * devices.
 *
 * @remarks
 * For example if `dpr` is 2, the `canvas.width` will be set to `width * 2`
 * (same for `height`) and the `canvas.style.width` will be set to given `width`
 * (in CSS pixels), thus creating a canvas with double resolution in the same
 * _apparent_ size.
 *
 * For 2D canvases, this will automatically clear any prior canvas content.
 * Returns given `dpr` (presumably the window's `devicePixelRatio` or 1.0, if
 * not available).
 *
 * @param canvas -
 * @param width - uncompensated pixel width
 * @param height - uncompensated pixel height
 * @param dpr - device pixel ratio
 */
export declare const adaptDPI: (canvas: HTMLCanvasElement, width: number, height: number, dpr?: number) => number;
/**
 * Returns true if device's DPR > 1 (aka HighDPI)
 */
export declare const isHighDPI: () => boolean;
//# sourceMappingURL=index.d.ts.map