@oliversalzburg/js-utils 0.0.7 → 0.0.9

package/lib/graphics/canvas.d.ts

@@ -1,80 +1,116 @@
 /// <reference types="@types/web" />
 /**
- * A wrapper around {@linkcode https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement HTMLCanvasElement}
+ * A wrapper around {@linkcode !HTMLCanvasElement}
  * to provide some convience for double-buffered drawing.
+ * @group Graphics
  */
 export declare class Canvas {
+    /**
+     * The {@linkcode !HTMLCanvasElement} we're interacting with.
+     */
     readonly canvas: HTMLCanvasElement;
+    /**
+     * The width of the canvas.
+     */
     readonly width: number;
+    /**
+     * The height of the canvas.
+     */
     readonly height: number;
+    /**
+     * The {@linkcode !CanvasRenderingContext2D} we're using to draw to the canvas.
+     */
     readonly context: CanvasRenderingContext2D;
-    readonly pixMap: ImageData;
-    readonly buffer: Uint8ClampedArray;
     /**
-     * Constructs a new {@link Canvas}.
+     * The {@linkcode !ImageData} object
+     * that represents our frontbuffer, which is the canvas itself.
+     */
+    pixMap: ImageData;
+    /**
+     * Our back buffer.
+     */
+    buffer: Uint8ClampedArray;
+    /**
+     * Was this {@linkcode Canvas} created with the ability to copy the front buffer back into
+     * the back buffer?
+     */
+    readonly supportReadBack: boolean;
+    /**
+     * Constructs a new {@linkcode Canvas}.
      * @param canvas The canvas to wrap.
      * @param width The width of the canvas.
      * @param height The height of the canvas.
+     * @param supportReadBack Should this canvas support reading back from the front buffer?
+     * You will need this, if you plan to use regular canvas drawing on the front buffer, and
+     * read the results back into the back buffer.
      */
-    constructor(canvas: HTMLCanvasElement, width: number, height: number);
+    constructor(canvas: HTMLCanvasElement, width: number, height: number, supportReadBack?: boolean);
     /**
-     * Draws the backbuffer onto the canvas.
+     * Draws the back buffer onto the canvas.
      */
     update(): void;
     /**
-     * Returns the color of a pixel in the backbuffer.
+     * 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 backbuffer.
+     * 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 backbuffer with the given color.
-     * @param color The color to fill the backbuffer with.
+     * Fills the entire back buffer with the given color.
+     * @param color The color to fill the back buffer with.
      */
     clearWith(color: number): void;
 }
 /**
- * Linearly blends a new pixel with an existing color value in a {@link Canvas}.
- * @param canvas The {@link Canvas} to interact with.
+ * Linearly blends a new pixel with an existing color value in a {@linkcode Canvas}.
+ * @param canvas The {@linkcode 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.
+ * @group Graphics
  */
 export declare const putPixel32: (canvas: Canvas, x: number, y: number, color: number, alpha: number) => void;
 /**
- * Additively blends a new pixel with an existing color value in a {@link Canvas}.
- * @param canvas The {@link Canvas} to interact with.
+ * Additively blends a new pixel with an existing color value in a {@linkcode Canvas}.
+ * @param canvas The {@linkcode 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.
+ * @group Graphics
  */
 export declare const putPixel32Add: (canvas: Canvas, x: number, y: number, color: number, alpha: number) => void;
 /**
- * Subtractively blends a new pixel with an existing color value in a {@link Canvas}.
- * @param canvas The {@link Canvas} to interact with.
+ * Subtractively blends a new pixel with an existing color value in a {@linkcode Canvas}.
+ * @param canvas The {@linkcode 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.
+ * @group Graphics
  */
 export declare const putPixel32Sub: (canvas: Canvas, x: number, y: number, color: number, alpha: number) => void;
 /**
- * Linearly blends a new pixel with an existing color value in a {@link Canvas}.
- * Compared to {@link putPixel32}, this function supports sub-pixel placement, but is dramatically slower.
- * @param canvas The {@link Canvas} to interact with.
+ * Linearly blends a new pixel with an existing color value in a {@linkcode Canvas}.
+ * Compared to {@linkcode putPixel32}, this function supports sub-pixel placement, but is dramatically slower.
+ * @param canvas The {@linkcode 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.
+ * @group Graphics
  */
 export declare const putSubPixel32: (canvas: Canvas, x: number, y: number, color: number, alpha: number) => void;

package/lib/graphics/canvas.js

@@ -1,39 +1,83 @@
+import { InvalidOperationError } from "../errors/InvalidOperationError.js";
 import { mustExist } from "../nil.js";
 import { blend, blendAdditive, blendSubtractive, fromRGBA, getA, getB, getG, getR, } from "./core.js";
 /**
- * A wrapper around {@linkcode https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement HTMLCanvasElement}
+ * A wrapper around {@linkcode !HTMLCanvasElement}
  * to provide some convience for double-buffered drawing.
+ * @group Graphics
  */
 export class Canvas {
+    /**
+     * The {@linkcode !HTMLCanvasElement} we're interacting with.
+     */
     canvas;
+    /**
+     * The width of the canvas.
+     */
     width;
+    /**
+     * The height of the canvas.
+     */
     height;
+    /**
+     * The {@linkcode !CanvasRenderingContext2D} we're using to draw to the canvas.
+     */
     context;
+    /**
+     * The {@linkcode !ImageData} object
+     * that represents our frontbuffer, which is the canvas itself.
+     */
     pixMap;
+    /**
+     * Our back buffer.
+     */
     buffer;
     /**
-     * Constructs a new {@link Canvas}.
+     * Was this {@linkcode Canvas} created with the ability to copy the front buffer back into
+     * the back buffer?
+     */
+    supportReadBack;
+    /**
+     * Constructs a new {@linkcode Canvas}.
      * @param canvas The canvas to wrap.
      * @param width The width of the canvas.
      * @param height The height of the canvas.
+     * @param supportReadBack Should this canvas support reading back from the front buffer?
+     * You will need this, if you plan to use regular canvas drawing on the front buffer, and
+     * read the results back into the back buffer.
      */
-    constructor(canvas, width, height) {
+    constructor(canvas, width, height, supportReadBack = false) {
         this.canvas = canvas;
         this.width = width;
         this.height = height;
-        this.context = mustExist(this.canvas.getContext("2d"), "Unable to create rendering context.");
+        this.context = mustExist(this.canvas.getContext("2d", {
+            alpha: false,
+            desynchronized: true,
+            willReadFrequently: supportReadBack,
+        }), "Unable to create rendering context.");
+        this.supportReadBack = supportReadBack;
         this.pixMap = this.context.createImageData(width, height);
         this.buffer = this.pixMap.data;
         this.context.font = "12px sans-serif";
     }
     /**
-     * Draws the backbuffer onto the canvas.
+     * Draws the back buffer onto the canvas.
      */
     update() {
         this.context.putImageData(this.pixMap, 0, 0);
     }
     /**
-     * Returns the color of a pixel in the backbuffer.
+     * Reads the front buffer back into the back buffer.
+     */
+    bufferReadBack() {
+        if (!this.supportReadBack) {
+            throw new InvalidOperationError("To use `bufferReadBack()`, you must construct the `Canvas` with `supportReadBack` set to `true`.");
+        }
+        this.pixMap = this.context.getImageData(0, 0, this.width, this.height);
+        this.buffer = this.pixMap.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.
@@ -43,7 +87,7 @@ export class Canvas {
         return fromRGBA(this.buffer[bufferOffset + 0], this.buffer[bufferOffset + 1], this.buffer[bufferOffset + 2], this.buffer[bufferOffset + 3]);
     }
     /**
-     * Colors a pixel in the backbuffer.
+     * 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.
@@ -56,8 +100,8 @@ export class Canvas {
         this.buffer[bufferOffset + 3] = getA(color);
     }
     /**
-     * Fills the entire backbuffer with the given color.
-     * @param color The color to fill the backbuffer with.
+     * 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);
@@ -73,12 +117,13 @@ export class Canvas {
     }
 }
 /**
- * Linearly blends a new pixel with an existing color value in a {@link Canvas}.
- * @param canvas The {@link Canvas} to interact with.
+ * Linearly blends a new pixel with an existing color value in a {@linkcode Canvas}.
+ * @param canvas The {@linkcode 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.
+ * @group Graphics
  */
 export const putPixel32 = (canvas, x, y, color, alpha) => {
     if (canvas.width < x || x < 0 || canvas.height < y || y < 0) {
@@ -94,12 +139,13 @@ export const putPixel32 = (canvas, x, y, color, alpha) => {
     canvas.setPixel32(x, y, newColor);
 };
 /**
- * Additively blends a new pixel with an existing color value in a {@link Canvas}.
- * @param canvas The {@link Canvas} to interact with.
+ * Additively blends a new pixel with an existing color value in a {@linkcode Canvas}.
+ * @param canvas The {@linkcode 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.
+ * @group Graphics
  */
 export const putPixel32Add = (canvas, x, y, color, alpha) => {
     if (canvas.width < x || x < 0 || canvas.height < y || y < 0) {
@@ -115,12 +161,13 @@ export const putPixel32Add = (canvas, x, y, color, alpha) => {
     canvas.setPixel32(x, y, newColor);
 };
 /**
- * Subtractively blends a new pixel with an existing color value in a {@link Canvas}.
- * @param canvas The {@link Canvas} to interact with.
+ * Subtractively blends a new pixel with an existing color value in a {@linkcode Canvas}.
+ * @param canvas The {@linkcode 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.
+ * @group Graphics
  */
 export const putPixel32Sub = (canvas, x, y, color, alpha) => {
     if (canvas.width < x || x < 0 || canvas.height < y || y < 0) {
@@ -136,13 +183,14 @@ export const putPixel32Sub = (canvas, x, y, color, alpha) => {
     canvas.setPixel32(x, y, newColor);
 };
 /**
- * Linearly blends a new pixel with an existing color value in a {@link Canvas}.
- * Compared to {@link putPixel32}, this function supports sub-pixel placement, but is dramatically slower.
- * @param canvas The {@link Canvas} to interact with.
+ * Linearly blends a new pixel with an existing color value in a {@linkcode Canvas}.
+ * Compared to {@linkcode putPixel32}, this function supports sub-pixel placement, but is dramatically slower.
+ * @param canvas The {@linkcode 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.
+ * @group Graphics
  */
 export const putSubPixel32 = (canvas, x, y, color, alpha) => {
     if (canvas.width < x || x < 0 || canvas.height < y || y < 0) {

package/lib/graphics/canvas.js.map

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

package/lib/graphics/core.d.ts

@@ -1,8 +1,13 @@
+/**
+ * Color palettes that can be used to quickly colorize a drawing.
+ * @group Graphics
+ */
 export declare const PALETTES: number[][];
 /**
  * Constrains a color component value to single-byte range (`0`-`255`).
  * @param c A color component value.
  * @returns The input value constrained into single-byte range.
+ * @group Graphics
  */
 export declare const safeRGBComponent: (c: number) => number;
 /**
@@ -12,6 +17,7 @@ export declare const safeRGBComponent: (c: number) => number;
  * @param b The B component.
  * @param a The A component.
  * @returns The constructed color value.
+ * @group Graphics
  */
 export declare const fromRGBA: (r: number, g: number, b: number, a: number) => number;
 /**
@@ -21,30 +27,35 @@ export declare const fromRGBA: (r: number, g: number, b: number, a: number) => n
  * @param g The G component.
  * @param b The B component.
  * @returns The constructed color value.
+ * @group Graphics
  */
 export declare const fromRGB: (r: number, g: number, b: number) => number;
 /**
  * Extracts the R component from a color value.
  * @param color The color value.
  * @returns The R component of the color value.
+ * @group Graphics
  */
 export declare const getR: (color: number) => number;
 /**
  * Extracts the G component from a color value.
  * @param color The color value.
  * @returns The G component of the color value.
+ * @group Graphics
  */
 export declare const getG: (color: number) => number;
 /**
  * Extracts the B component from a color value.
  * @param color The color value.
  * @returns The B component of the color value.
+ * @group Graphics
  */
 export declare const getB: (color: number) => number;
 /**
  * Extracts the A component from a color value.
  * @param color The color value.
  * @returns The A component of the color value.
+ * @group Graphics
  */
 export declare const getA: (color: number) => number;
 /**
@@ -55,6 +66,7 @@ export declare const getA: (color: number) => number;
  * @param dst The destination color.
  * @param alpha The alpha value to use for blending.
  * @returns The blended color.
+ * @group Graphics
  */
 export declare const blend: (src: number, dst: number, alpha: number) => number;
 /**
@@ -65,6 +77,7 @@ export declare const blend: (src: number, dst: number, alpha: number) => number;
  * @param dst The destination color.
  * @param alpha The alpha value to use for blending.
  * @returns The blended color.
+ * @group Graphics
  */
 export declare const blendAdditive: (src: number, dst: number, alpha: number) => number;
 /**
@@ -75,20 +88,25 @@ export declare const blendAdditive: (src: number, dst: number, alpha: number) =>
  * @param dst The destination color.
  * @param alpha The alpha value to use for blending.
  * @returns The blended color.
+ * @group Graphics
  */
 export declare const blendSubtractive: (src: number, dst: number, alpha: number) => number;
 /**
  * Retrieves a random color from the current global palette.
+ * Uses the global {@linkcode random} object.
  * @returns A random color.
+ * @group Graphics
  */
 export declare const somecolor: () => number;
 /**
  * Switches the global palette to the next available preset.
+ * @group Graphics
  */
 export declare const nextPalette: () => void;
 /**
  * Converts a color value to grayscale.
  * @param color The color to convert.
  * @returns The grayscale value appropriate for the color.
+ * @group Graphics
  */
 export declare const toGrayScale: (color: number) => number;

package/lib/graphics/core.js

@@ -1,5 +1,9 @@
 import { random } from "../random.js";
 let PALETTE_INDEX = 0;
+/**
+ * Color palettes that can be used to quickly colorize a drawing.
+ * @group Graphics
+ */
 export const PALETTES = [
     [
         0xc2b799, 0xa6a183, 0xc5bfa7, 0x6d624e, 0xa8987e, 0xc1bca6, 0xe3decb, 0x896b51, 0x744d26,
@@ -322,6 +326,7 @@ export const PALETTES = [
  * Constrains a color component value to single-byte range (`0`-`255`).
  * @param c A color component value.
  * @returns The input value constrained into single-byte range.
+ * @group Graphics
  */
 export const safeRGBComponent = (c) => {
     if (c < 0) {
@@ -339,6 +344,7 @@ export const safeRGBComponent = (c) => {
  * @param b The B component.
  * @param a The A component.
  * @returns The constructed color value.
+ * @group Graphics
  */
 export const fromRGBA = (r, g, b, a) => {
     r = safeRGBComponent(r);
@@ -354,6 +360,7 @@ export const fromRGBA = (r, g, b, a) => {
  * @param g The G component.
  * @param b The B component.
  * @returns The constructed color value.
+ * @group Graphics
  */
 export const fromRGB = (r, g, b) => {
     return fromRGBA(r, g, b, 255);
@@ -362,6 +369,7 @@ export const fromRGB = (r, g, b) => {
  * Extracts the R component from a color value.
  * @param color The color value.
  * @returns The R component of the color value.
+ * @group Graphics
  */
 export const getR = (color) => {
     return (color >> 24) & 0xff;
@@ -370,6 +378,7 @@ export const getR = (color) => {
  * Extracts the G component from a color value.
  * @param color The color value.
  * @returns The G component of the color value.
+ * @group Graphics
  */
 export const getG = (color) => {
     return (color >> 16) & 0xff;
@@ -378,6 +387,7 @@ export const getG = (color) => {
  * Extracts the B component from a color value.
  * @param color The color value.
  * @returns The B component of the color value.
+ * @group Graphics
  */
 export const getB = (color) => {
     return (color >> 8) & 0xff;
@@ -386,6 +396,7 @@ export const getB = (color) => {
  * Extracts the A component from a color value.
  * @param color The color value.
  * @returns The A component of the color value.
+ * @group Graphics
  */
 export const getA = (color) => {
     return color & 0xff;
@@ -398,6 +409,7 @@ export const getA = (color) => {
  * @param dst The destination color.
  * @param alpha The alpha value to use for blending.
  * @returns The blended color.
+ * @group Graphics
  */
 export const blend = (src, dst, alpha) => {
     if (alpha >= 255) {
@@ -418,6 +430,7 @@ export const blend = (src, dst, alpha) => {
  * @param dst The destination color.
  * @param alpha The alpha value to use for blending.
  * @returns The blended color.
+ * @group Graphics
  */
 export const blendAdditive = (src, dst, alpha) => {
     if (alpha >= 255) {
@@ -436,6 +449,7 @@ export const blendAdditive = (src, dst, alpha) => {
  * @param dst The destination color.
  * @param alpha The alpha value to use for blending.
  * @returns The blended color.
+ * @group Graphics
  */
 export const blendSubtractive = (src, dst, alpha) => {
     if (alpha >= 255) {
@@ -451,7 +465,9 @@ export const blendSubtractive = (src, dst, alpha) => {
 };
 /**
  * Retrieves a random color from the current global palette.
+ * Uses the global {@linkcode random} object.
  * @returns A random color.
+ * @group Graphics
  */
 export const somecolor = () => {
     // pick some random good color
@@ -460,6 +476,7 @@ export const somecolor = () => {
 };
 /**
  * Switches the global palette to the next available preset.
+ * @group Graphics
  */
 export const nextPalette = () => {
     ++PALETTE_INDEX;
@@ -471,6 +488,7 @@ export const nextPalette = () => {
  * Converts a color value to grayscale.
  * @param color The color to convert.
  * @returns The grayscale value appropriate for the color.
+ * @group Graphics
  */
 export const toGrayScale = (color) => {
     const gs = getR(color) * 0.3 + getG(color) * 0.59 + getB(color) * 0.11;