@oliversalzburg/js-utils 0.7.0 → 0.8.0

package/lib/graphics/canvas.js

@@ -0,0 +1,37 @@
+/**
+ * The base class for canvas helpers, which also defines a common interface.
+ *
+ * Derivates of the class might chose to leave implementations of individual methods
+ * empty, if it fits their pattern better. For example, one canvas might wrap its
+ * context and applications using that canvas will only interact with its interface.
+ * Another canvas implementation might expose the context and all give the application
+ * full control over the rendering cycle.
+ */
+export class Canvas {
+    /**
+     * The canvas element we're interacting with.
+     */
+    canvasElement;
+    /**
+     * Retrieves the width of the canvas.
+     * @returns The width of the canvas.
+     */
+    get width() {
+        return this.canvasElement.width;
+    }
+    /**
+     * Retrieves the height of the canvas.
+     * @returns The height of the canvas.
+     */
+    get height() {
+        return this.canvasElement.height;
+    }
+    /**
+     * Constructs a new canvas helper.
+     * @param canvas - The canvas node to wrap.
+     */
+    constructor(canvas) {
+        this.canvasElement = canvas;
+    }
+}
+//# sourceMappingURL=canvas.js.map

package/lib/graphics/canvas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas.js","sourceRoot":"","sources":["../../source/graphics/canvas.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,OAAgB,MAAM;IAC3B;;OAEG;IACM,aAAa,CAAsC;IAE5D;;;OAGG;IACH,IAAI,KAAK;QACR,OAAO,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC;IACjC,CAAC;IAED;;;OAGG;IACH,IAAI,MAAM;QACT,OAAO,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC;IAClC,CAAC;IAED;;;OAGG;IACH,YAAY,MAA2C;QACtD,IAAI,CAAC,aAAa,GAAG,MAAM,CAAC;IAC7B,CAAC;CAqCD"}

package/lib/graphics/canvas2d-headless.d.ts

@@ -0,0 +1,85 @@
+import { Canvas } from "./canvas.js";
+import type { Canvas2DOptions } from "./canvas2d.js";
+/**
+ * An offscreen canvas.
+ *
+ * This isn't created from a DOM node, but from an existing {@linkcode !OffscreenCanvas}.
+ */
+export declare class Canvas2DHeadless extends Canvas {
+    #private;
+    /**
+     * Retrieves the rendering context of the canvas.
+     * @returns The rendering context of the canvas.
+     */
+    get context(): OffscreenCanvasRenderingContext2D;
+    /**
+     * Our back buffer.
+     */
+    buffer: Uint8ClampedArray;
+    /**
+     * The configuration that was used for this canvas.
+     */
+    readonly options: Readonly<Partial<Canvas2DOptions>>;
+    /**
+     * Constructs a new {@linkcode Canvas2DHeadless}.
+     * @param canvas - The offscreen canvas we're drawing to.
+     * @param context - The rendering context to use for the canvas.
+     * @param options - The configuration for this canvas.
+     */
+    constructor(canvas: OffscreenCanvas, context: OffscreenCanvasRenderingContext2D, options?: Partial<Canvas2DOptions>);
+    /**
+     * Recreate internal buffers in reaction to a change in our target {@linkcode !OffscreenCanvas}.
+     */
+    refreshCanvasNode(): void;
+    /**
+     * Draw FPS information onto the canvas.
+     * @param frameTimes - Durations of previous frame draws.
+     * @param frameTime - The duration of the previous frame draw.
+     * @param timeDelta - The time elapsed since the last frame.
+     */
+    renderFpsInfo(frameTimes: Array<number>, frameTime: number, timeDelta: number): void;
+    /**
+     * Draws the back buffer onto the canvas.
+     */
+    update(): void;
+    /**
+     * Draws the offscreen canvas into the DOM canvas.
+     */
+    render(): void;
+    /**
+     * Draws a slightly transparent, black rectangle over the canvas,
+     * and then reads the result back into the buffer.
+     * @param color - The color to fade the buffer with. The alpha component of
+     * the color defines how strong the fade is. `0` is not at all, `255` makes
+     * it instantly black.
+     */
+    fade(color?: number): void;
+    /**
+     * Reads the front buffer back into the back buffer.
+     */
+    bufferReadBack(): void;
+    /**
+     * Returns the color of a pixel in the back buffer.
+     * @param x - The X coordinate to retrieve.
+     * @param y - The X coordinate to retrieve.
+     * @returns The color of the pixel at the given local.
+     */
+    getPixel32(x: number, y: number): number;
+    /**
+     * Colors a pixel in the back buffer.
+     * @param x - The X coordinate to color.
+     * @param y - The Y coordinate to color.
+     * @param color - The color to place at the coordinate.
+     */
+    setPixel32(x: number, y: number, color: number): void;
+    /**
+     * Fills the entire back buffer with the given color.
+     * @param color - The color to fill the back buffer with.
+     */
+    clearWith(color: number): void;
+    /**
+     * Fills the entire back buffer with the given color.
+     * @param color - The color to fill the back buffer with.
+     */
+    blendWith(color: number): void;
+}

package/lib/graphics/canvas2d-headless.js

@@ -0,0 +1,197 @@
+import { mustExist } from "../data/nil.js";
+import { InvalidOperationError } from "../errors/InvalidOperationError.js";
+import { Canvas } from "./canvas.js";
+import { blend, fromRGBA, getA, getB, getG, getR } from "./core.js";
+import { MS_PER_FRAME_60FPS } from "./render-loop.js";
+/**
+ * An offscreen canvas.
+ *
+ * This isn't created from a DOM node, but from an existing {@linkcode !OffscreenCanvas}.
+ */
+export class Canvas2DHeadless extends Canvas {
+    /**
+     * The 2D rendering context we're using to draw to the canvas.
+     */
+    #context;
+    /**
+     * Retrieves the rendering context of the canvas.
+     * @returns The rendering context of the canvas.
+     */
+    get context() {
+        return this.#context;
+    }
+    /**
+     * The {@linkcode !ImageData} object in our offscreen canvas. We usually interact with its
+     * {@linkcode Canvas2D.buffer buffer} directly.
+     */
+    #imageData;
+    /**
+     * Our back buffer.
+     */
+    buffer;
+    /**
+     * The configuration that was used for this canvas.
+     */
+    options;
+    /**
+     * Constructs a new {@linkcode Canvas2DHeadless}.
+     * @param canvas - The offscreen canvas we're drawing to.
+     * @param context - The rendering context to use for the canvas.
+     * @param options - The configuration for this canvas.
+     */
+    constructor(canvas, context, options = {}) {
+        super(canvas);
+        this.options = options;
+        this.#context = context;
+        this.#imageData = this.#context.createImageData(this.width, this.height);
+        this.buffer = this.#imageData.data;
+    }
+    /**
+     * Recreate internal buffers in reaction to a change in our target {@linkcode !OffscreenCanvas}.
+     */
+    refreshCanvasNode() {
+        this.#context = mustExist(this.canvasElement.getContext("2d", {
+            alpha: false,
+            desynchronized: true,
+            willReadFrequently: this.options.supportReadBack,
+        }), "Unable to create rendering context for offscreen canvas.");
+        this.#imageData = this.#context.createImageData(this.width, this.height);
+        this.buffer = this.#imageData.data;
+    }
+    /**
+     * Draw FPS information onto the canvas.
+     * @param frameTimes - Durations of previous frame draws.
+     * @param frameTime - The duration of the previous frame draw.
+     * @param timeDelta - The time elapsed since the last frame.
+     */
+    renderFpsInfo(frameTimes, frameTime, timeDelta) {
+        const maxFrameTime = frameTimes.reduce((max, frameTime) => {
+            if (max < frameTime) {
+                max = frameTime;
+            }
+            return max;
+        }, 0);
+        const sumFrameTimes = frameTimes.reduce((sum, frameTime) => sum + frameTime, 0);
+        const fpsAll = Math.round(frameTimes.length / (sumFrameTimes / 1000)).toString();
+        const fpsFrame = 1000 / frameTime;
+        const fpsDelta = 1000 / timeDelta;
+        let currentX = this.width;
+        for (const frameTime of frameTimes) {
+            let fillColor = 0x00ff00ff;
+            let width = 1;
+            if (MS_PER_FRAME_60FPS < frameTime) {
+                const quality = frameTime / maxFrameTime;
+                fillColor =
+                    blend(0x00ff00ff, 0xff0000ff, Math.trunc(quality * 255)) >>> 0;
+                width = Math.round(frameTime / MS_PER_FRAME_60FPS);
+            }
+            this.context.fillStyle = `#${fillColor.toString(16).padStart(8, "0")}`;
+            this.context.globalAlpha = 255;
+            this.context.fillRect(currentX - width, this.height, width, (frameTime / Math.max(100, maxFrameTime)) * -100);
+            currentX -= width;
+        }
+        this.context.beginPath();
+        this.context.strokeStyle = "#fff";
+        this.context.moveTo(0, this.height - MS_PER_FRAME_60FPS);
+        this.context.lineTo(this.width, this.height - MS_PER_FRAME_60FPS);
+        this.context.stroke();
+        const fpsString = `${Math.round(fpsFrame).toFixed(3)}f ${fpsAll}∑ ${Math.round(fpsDelta).toFixed(3)}δ`;
+        this.context.font = "13px monospace";
+        this.context.strokeStyle = "rgba( 255, 255, 255, 1)";
+        this.context.textAlign = "right";
+        this.context.textRendering = "geometricPrecision";
+        this.context.strokeText(fpsString, this.width - 3, this.height - 3);
+        this.context.fillStyle = "#000000";
+        this.context.fillText(fpsString, this.width - 3, this.height - 3);
+    }
+    /**
+     * Draws the back buffer onto the canvas.
+     */
+    update() {
+        this.#context.putImageData(this.#imageData, 0, 0);
+    }
+    /**
+     * Draws the offscreen canvas into the DOM canvas.
+     */
+    render() {
+        // Nothing to do here. Everything happens in update().
+    }
+    /**
+     * Draws a slightly transparent, black rectangle over the canvas,
+     * and then reads the result back into the buffer.
+     * @param color - The color to fade the buffer with. The alpha component of
+     * the color defines how strong the fade is. `0` is not at all, `255` makes
+     * it instantly black.
+     */
+    fade(color = fromRGBA(0, 0, 0, 1)) {
+        this.blendWith(color);
+    }
+    /**
+     * Reads the front buffer back into the back buffer.
+     */
+    bufferReadBack() {
+        if (!this.options.supportReadBack) {
+            throw new InvalidOperationError("To use `bufferReadBack()`, you must construct the `Canvas` with `options.supportReadBack` set to `true`.");
+        }
+        this.#imageData = this.#context.getImageData(0, 0, this.width, this.height);
+        this.buffer = this.#imageData.data;
+    }
+    /**
+     * Returns the color of a pixel in the back buffer.
+     * @param x - The X coordinate to retrieve.
+     * @param y - The X coordinate to retrieve.
+     * @returns The color of the pixel at the given local.
+     */
+    getPixel32(x, y) {
+        const bufferOffset = (x + y * this.width) * 4;
+        return fromRGBA(this.buffer[bufferOffset + 0], this.buffer[bufferOffset + 1], this.buffer[bufferOffset + 2], this.buffer[bufferOffset + 3]);
+    }
+    /**
+     * Colors a pixel in the back buffer.
+     * @param x - The X coordinate to color.
+     * @param y - The Y coordinate to color.
+     * @param color - The color to place at the coordinate.
+     */
+    setPixel32(x, y, color) {
+        const bufferOffset = (x + y * this.width) * 4;
+        this.buffer[bufferOffset + 0] = getR(color);
+        this.buffer[bufferOffset + 1] = getG(color);
+        this.buffer[bufferOffset + 2] = getB(color);
+        this.buffer[bufferOffset + 3] = getA(color);
+    }
+    /**
+     * Fills the entire back buffer with the given color.
+     * @param color - The color to fill the back buffer with.
+     */
+    clearWith(color) {
+        const r = getR(color);
+        const g = getG(color);
+        const b = getB(color);
+        const a = getA(color);
+        for (let bufferOffset = 0; bufferOffset < this.width * this.height * 4; bufferOffset += 4) {
+            this.buffer[bufferOffset + 0] = r;
+            this.buffer[bufferOffset + 1] = g;
+            this.buffer[bufferOffset + 2] = b;
+            this.buffer[bufferOffset + 3] = a;
+        }
+    }
+    /**
+     * Fills the entire back buffer with the given color.
+     * @param color - The color to fill the back buffer with.
+     */
+    blendWith(color) {
+        const r = getR(color);
+        const g = getG(color);
+        const b = getB(color);
+        const a = getA(color);
+        for (let bufferOffset = 0; bufferOffset < this.width * this.height * 4; bufferOffset += 4) {
+            this.buffer[bufferOffset + 0] =
+                (a * r + (255 - a) * this.buffer[bufferOffset + 0]) >> 8;
+            this.buffer[bufferOffset + 1] =
+                (a * g + (255 - a) * this.buffer[bufferOffset + 1]) >> 8;
+            this.buffer[bufferOffset + 2] =
+                (a * b + (255 - a) * this.buffer[bufferOffset + 2]) >> 8;
+        }
+    }
+}
+//# sourceMappingURL=canvas2d-headless.js.map

package/lib/graphics/canvas2d-headless.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas2d-headless.js","sourceRoot":"","sources":["../../source/graphics/canvas2d-headless.ts"],"names":[],"mappings":"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"}

package/lib/graphics/canvas2d.d.ts

@@ -0,0 +1,162 @@
+import { Canvas } from "./canvas.js";
+import type { Canvas2DHeadless } from "./canvas2d-headless.js";
+/**
+ * Construction options for a {@linkcode Canvas2D}.
+ */
+export interface Canvas2DOptions {
+    /**
+     * Was this {@linkcode Canvas2D} created with the ability to copy the front buffer back into
+     * the back buffer?
+     */
+    readonly supportReadBack: boolean;
+}
+/**
+ * The {@linkcode Canvas2D} is a double-buffered construct to help with drawing to a
+ * {@linkcode !HTMLCanvasElement} with best possible performance.
+ * We utilize an {@linkcode !OffscreenCanvas} with a {@linkcode !OffscreenCanvasRenderingContext2D}
+ * to draw frames and expect to render them back to the DOM in regular intervals.
+ */
+export declare class Canvas2D extends Canvas {
+    #private;
+    /**
+     * Retrieves the rendering context of the canvas.
+     * @returns The rendering context of the canvas.
+     */
+    get context(): OffscreenCanvasRenderingContext2D;
+    /**
+     * Our back buffer.
+     */
+    buffer: Uint8ClampedArray;
+    /**
+     * The configuration that was used for this canvas.
+     */
+    readonly options: Readonly<Partial<Canvas2DOptions>>;
+    /**
+     * Constructs a new {@linkcode Canvas2D}.
+     * @param canvas - The canvas to wrap.
+     * @param options - The configuration for this canvas.
+     */
+    constructor(canvas: HTMLCanvasElement, options?: Partial<Canvas2DOptions>);
+    /**
+     * Recreate internal buffers in reaction to a change in our target {@linkcode !HTMLCanvasElement}.
+     */
+    refreshCanvasNode(): void;
+    /**
+     * Draw FPS information onto the canvas.
+     * @param frameTimes - Durations of previous frame draws.
+     * @param frameTime - The duration of the previous frame draw.
+     * @param timeDelta - The time elapsed since the last frame.
+     */
+    renderFpsInfo(frameTimes: Array<number>, frameTime: number, timeDelta: number): void;
+    /**
+     * Draws the back buffer onto the canvas.
+     */
+    update(): void;
+    /**
+     * Draws the offscreen canvas into the DOM canvas.
+     */
+    render(): void;
+    /**
+     * Draws a slightly transparent, black rectangle over the canvas,
+     * and then reads the result back into the buffer.
+     * @param color - The color to fade the buffer with. The alpha component of
+     * the color defines how strong the fade is. `0` is not at all, `255` makes
+     * it instantly black.
+     */
+    fade(color?: number): void;
+    /**
+     * Reads the front buffer back into the back buffer.
+     */
+    bufferReadBack(): void;
+    /**
+     * Returns the color of a pixel in the back buffer.
+     * @param x - The X coordinate to retrieve.
+     * @param y - The X coordinate to retrieve.
+     * @returns The color of the pixel at the given local.
+     */
+    getPixel32(x: number, y: number): number;
+    /**
+     * Colors a pixel in the back buffer.
+     * @param x - The X coordinate to color.
+     * @param y - The Y coordinate to color.
+     * @param color - The color to place at the coordinate.
+     */
+    setPixel32(x: number, y: number, color: number): void;
+    /**
+     * Fills the entire back buffer with the given color.
+     * @param color - The color to fill the back buffer with.
+     */
+    clearWith(color: number): void;
+    /**
+     * Fills the entire back buffer with the given color.
+     * @param color - The color to fill the back buffer with.
+     */
+    blendWith(color: number): void;
+}
+/**
+ * Linearly blends a new pixel with an existing color value in a canvas.
+ *
+ * As this method is often called many times in render loops, only bounds
+ * checking is applied to the given coordinates.
+ *
+ * The coordinates are **expected to already be integers**. Supplying numbers with fractions
+ * has performance implications. Ensure you're working with integers, or truncate the
+ * coordinates before passing them in.
+ *
+ * The `alpha` value is expected to be an integer in the range from `0` to `255`.
+ * `0` meaning fully transparent, `255` meaning fully opaque.
+ * @param canvas - The canvas to interact with.
+ * @param x - The X coordinate at which to place the pixel.
+ * @param y - The Y coordinate at which to place the pixel.
+ * @param color - The color of the pixel.
+ * @param alpha - The alpha value to use to blend the pixel with existing color at the location.
+ */
+export declare const putPixel32: (canvas: Canvas2D | Canvas2DHeadless, x: number, y: number, color: number, alpha: number) => void;
+/**
+ * Additively blends a new pixel with an existing color value in a canvas.
+ *
+ * As this method is often called many times in render loops, only bounds
+ * checking is applied to the given coordinates.
+ *
+ * The coordinates are **expected to already be integers**. Supplying numbers with fractions
+ * has performance implications. Ensure you're working with integers, or truncate the
+ * coordinates before passing them in.
+ *
+ * The `alpha` value is expected to be an integer in the range from `0` to `255`.
+ * `0` meaning fully transparent, `255` meaning fully opaque.
+ * @param canvas - The canvas to interact with.
+ * @param x - The X coordinate at which to place the pixel.
+ * @param y - The Y coordinate at which to place the pixel.
+ * @param color - The color of the pixel.
+ * @param alpha - The alpha value to use to blend the pixel with existing color at the location.
+ */
+export declare const putPixel32Add: (canvas: Canvas2D | Canvas2DHeadless, x: number, y: number, color: number, alpha: number) => void;
+/**
+ * Subtractively blends a new pixel with an existing color value in a canvas.
+ *
+ * As this method is often called many times in render loops, only bounds
+ * checking is applied to the given coordinates.
+ *
+ * The coordinates are **expected to already be integers**. Supplying numbers with fractions
+ * has performance implications. Ensure you're working with integers, or truncate the
+ * coordinates before passing them in.
+ *
+ * The `alpha` value is expected to be an integer in the range from `0` to `255`.
+ * `0` meaning fully transparent, `255` meaning fully opaque.
+ * @param canvas - The canvas to interact with.
+ * @param x - The X coordinate at which to place the pixel.
+ * @param y - The Y coordinate at which to place the pixel.
+ * @param color - The color of the pixel.
+ * @param alpha - The alpha value to use to blend the pixel with existing color at the location.
+ */
+export declare const putPixel32Sub: (canvas: Canvas2D | Canvas2DHeadless, x: number, y: number, color: number, alpha: number) => void;
+/**
+ * Linearly blends a new pixel with an existing color value in a canvas.
+ * Compared to {@linkcode putPixel32}, this function supports sub-pixel placement, but is dramatically slower.
+ * @param canvas - The canvas to interact with.
+ * @param x - The X coordinate at which to place the pixel.
+ * @param y - The Y coordinate at which to place the pixel.
+ * @param color - The color of the pixel.
+ * @param alpha - The alpha value to use to blend the pixel with existing color at the location.
+ */
+export declare const putSubPixel32: (canvas: Canvas2D | Canvas2DHeadless, x: number, y: number, color: number, alpha: number) => void;