@oliversalzburg/js-utils 0.0.28-dev.10 → 0.0.28-dev.101

package/README.md

@@ -9,3 +9,5 @@ A collection of random utilities for JS/TS development.
 -   Tree-shaking in mind. Subpath-imports fully supported and recommended.
 
 -   No runtime dependencies.
+
+-   All runtime code is licensed under MIT, or fully compatible licenses.

package/graphics/canvas-sandbox-mp.d.ts

@@ -0,0 +1,269 @@
+/// <reference types="@types/web" />
+/// <reference types="node" resolution-mode="require"/>
+/// <reference types="node" resolution-mode="require"/>
+import { ConstructorOf } from "../core.js";
+import { Random } from "../random.js";
+import { CanvasSandboxApplication, CanvasSandboxExpectedOptions } from "./canvas-sandbox.js";
+import { Canvas } from "./canvas.js";
+import { Canvas2DHeadless } from "./canvas2d-headless.js";
+import { RenderLoop } from "./render-loop.js";
+/**
+ * Sent from the host when a worker should reconfigure itself.
+ * @group Graphics
+ */
+export interface CanvasWorkerMessageReconfigure<TApplicationOptions extends CanvasSandboxExpectedOptions> {
+    /**
+     * Type identifier of this message.
+     */
+    type: "reconfigure";
+    /**
+     * New ID for the worker.
+     */
+    id: string;
+    /**
+     * New canvas for the worker to use.
+     */
+    canvas: OffscreenCanvas;
+    /**
+     * New application options to use.
+     */
+    options: TApplicationOptions;
+}
+/**
+ * Sent from the host when a worker should start its rendering kernel.
+ * @group Graphics
+ */
+export interface CanvasWorkerMessageStart<TApplicationOptions extends CanvasSandboxExpectedOptions> {
+    /**
+     * Type identifier of this message.
+     */
+    type: "start";
+    /**
+     * New application options to use before starting.
+     */
+    options: TApplicationOptions;
+}
+/**
+ * Sent from the host when a worker should un/pause rendering.
+ * @group Graphics
+ */
+export interface CanvasWorkerMessagePause {
+    /**
+     * Type identifier of this message.
+     */
+    type: "pause";
+    /**
+     * Should the worker pause (`true`) or unpause (`false`)?
+     */
+    pause: boolean;
+}
+/**
+ * Sent from a worker when it finished rendering the current scene.
+ * @group Graphics
+ */
+export interface CanvasWorkerSceneFinishMessage {
+    /**
+     * Type identifier of this message.
+     */
+    type: "sceneFinish";
+    /**
+     * Point in time when the scene finished rendering.
+     */
+    timestamp: number;
+}
+/**
+ * The messages that are passed between the canvas sandbox host and its workers.
+ * @group Graphics
+ */
+export type CanvasWorkerMessage<TApplicationOptions extends CanvasSandboxExpectedOptions> = CanvasWorkerMessageReconfigure<TApplicationOptions> | CanvasWorkerMessageStart<TApplicationOptions> | CanvasWorkerSceneFinishMessage | CanvasWorkerMessagePause | {
+    type: string;
+};
+/**
+ * The canvas worker handles a web worker instance in the canvas sandbox host.
+ *
+ * It provides a thin abstraction over the web worker IPC messaging.
+ * @group Graphics
+ */
+export declare class CanvasWorker<TApplicationOptions extends CanvasSandboxExpectedOptions> extends EventTarget {
+    /**
+     * The ID of this worker.
+     */
+    id: string;
+    /**
+     * The canvas element that this worker should handle.
+     * This is purely for informational purposes on the host side.
+     */
+    canvas: HTMLCanvasElement | undefined;
+    /**
+     * The offscreen canvas that we created for this worker.
+     */
+    canvasOffscreen: OffscreenCanvas | undefined;
+    /**
+     * The application options for the worker.
+     *
+     * These are usually very similar, if not identical, to the host application options.
+     * Workers just usually get a different viewport assigned to them, correlating with the
+     * canvas element in the DOM that they draw to.
+     */
+    readonly options: TApplicationOptions;
+    /**
+     * The web worker instance itself.
+     */
+    readonly workerInstance: Worker;
+    /**
+     * Constructs a new canvas worker.
+     * @param id - The ID of the worker.
+     * @param source - The code that the worker should run. It's common to use a hybrid code module
+     * for as the sandbox application. This means the code of the host and the workers is identical,
+     * they just construct different code path on load/init. In such case, the source can simply be
+     * `new URL(import.meta.url)`.
+     * @param canvas - The canvas element to draw to.
+     * @param options - The application options.
+     */
+    constructor(id: string, source: URL, canvas: HTMLCanvasElement, options: TApplicationOptions);
+    /**
+     * Posts a message to the worker.
+     *
+     * As messages to workers are _posted_ instead of _sent_, there is no delivery feedback.
+     * @param message - The message to post.
+     * @param transfer - The transferables to transfer to the worker with this message.
+     */
+    postMessage(message: CanvasWorkerMessage<TApplicationOptions>, transfer?: Array<Transferable>): void;
+}
+/**
+ * The canvas worker instance handles a web worker instance in worker instance itself, and
+ * handles a feedback channel to the host application.
+ *
+ * It provides a thin abstraction over the web worker IPC messaging.
+ *
+ * ```ts
+ * // Construct inside of worker from global scope and rendering kernel class.
+ * const worker = new CanvasWorkerInstance(self, RenderKernel);
+ * // Listen to custom events (messages) you send from the host.
+ * worker.addEventListener("fade", () => worker.renderKernel?.fadeOut());
+ * ```
+ * @group Graphics
+ */
+export declare class CanvasWorkerInstance<TCanvas extends Canvas2DHeadless, TApplicationOptions extends CanvasSandboxExpectedOptions, TKernel extends CanvasSandboxApplication<TCanvas, TApplicationOptions>> extends EventTarget {
+    #private;
+    /**
+     * The global scope of the worker.
+     */
+    readonly self: typeof globalThis;
+    /**
+     * The ID of the worker.
+     */
+    id: string;
+    /**
+     * The rendering kernel, which produces frames, and renders them to our
+     * offscreen canvas.
+     */
+    renderKernel: TKernel | undefined;
+    /**
+     * The canvas element we're presenting to.
+     */
+    canvas: TCanvas | undefined;
+    /**
+     * The offscreen canvas we're rendering to.
+     */
+    offscreenCanvas: OffscreenCanvas | undefined;
+    /**
+     * Our rendering context to draw to.
+     */
+    offscreenContext: OffscreenCanvasRenderingContext2D | undefined;
+    /**
+     * Manages frame rendering timing.
+     */
+    renderLoop: RenderLoop | undefined;
+    /**
+     * Constructs a new canvas worker instance.
+     *
+     * Note that many properties are only initialized after the host sent an
+     * initialization message.
+     * @param self - Our global worker scope.
+     * @param Kernel - The rendering kernel class to construct.
+     */
+    constructor(self: typeof globalThis, Kernel: ConstructorOf<TKernel>);
+    /**
+     * Render a frame.
+     * @param delta - How many milliseconds have passed since the last invocation?
+     */
+    render: (delta: number) => void;
+    /**
+     * Reconfigure the worker.
+     * @param id - New ID for this worker.
+     * @param offscreenCanvas - New canvas to render to.
+     * @param options - New application options.
+     */
+    reconfigure(id: string, offscreenCanvas: OffscreenCanvas, options: TApplicationOptions): void;
+    /**
+     * Start rendering.
+     * @param options - New application options.
+     */
+    start(options: TApplicationOptions): void;
+    /**
+     * Posts a message to the host.
+     * @param message - The message to post.
+     */
+    postMessage(message: CanvasWorkerMessage<TApplicationOptions>): void;
+}
+/**
+ * Base class for multi-process canvas sandbox applications.
+ *
+ * Helps in orchestrating the workers.
+ * @group Graphics
+ */
+export declare abstract class CanvasSandboxHostApplication<TCanvas extends Canvas, TApplicationOptions extends CanvasSandboxExpectedOptions> implements CanvasSandboxApplication<TCanvas, TApplicationOptions> {
+    /**
+     * Usually a hidden canvas that serves as a proxy for canvas sandbox events.
+     */
+    canvas: TCanvas;
+    /**
+     * Application options.
+     */
+    options: TApplicationOptions;
+    /**
+     * PRNG instance for the application.
+     */
+    random: Random;
+    /**
+     * Is the application running right now?
+     */
+    paused: boolean;
+    /**
+     * Web worker instances.
+     */
+    readonly workers: CanvasWorker<TApplicationOptions>[];
+    /**
+     * Construct a new host application.
+     * @param canvas - Usually a hidden canvas in the DOM to serve as an event proxy.
+     * @param options - Application options.
+     */
+    constructor(canvas: TCanvas, options: TApplicationOptions);
+    /**
+     * Reconfigure the application with the given options and restart it.
+     * @param canvas - The canvas to use.
+     * @param options - The new options to use.
+     */
+    abstract reconfigure(canvas: TCanvas, options?: Partial<TApplicationOptions>): void;
+    /**
+     * Request the application to draw a new frame.
+     * This call has no effect in a host application, as all rendering happens in the workers.
+     * @param _delta - How many milliseconds passed since the last frame draw.
+     * @param _timestamp - The current timestamp.
+     */
+    onDraw(_delta: number, _timestamp: number): void;
+    /**
+     * Pauses all workers.
+     */
+    pause(): void;
+    /**
+     * Start the application.
+     */
+    start(): void;
+    /**
+     * Posts a message to all workers.
+     * @param message - Message to post to all workers.
+     */
+    postMessageAll(message: CanvasWorkerMessage<TApplicationOptions>): void;
+}

package/graphics/canvas-sandbox-mp.js

@@ -0,0 +1,282 @@
+import { isNil, mustExist } from "../nil.js";
+import { Random } from "../random.js";
+import { Canvas2DHeadless } from "./canvas2d-headless.js";
+import { RenderLoop } from "./render-loop.js";
+/**
+ * The canvas worker handles a web worker instance in the canvas sandbox host.
+ *
+ * It provides a thin abstraction over the web worker IPC messaging.
+ * @group Graphics
+ */
+export class CanvasWorker extends EventTarget {
+    /**
+     * The ID of this worker.
+     */
+    id;
+    /**
+     * The canvas element that this worker should handle.
+     * This is purely for informational purposes on the host side.
+     */
+    canvas;
+    /**
+     * The offscreen canvas that we created for this worker.
+     */
+    canvasOffscreen;
+    /**
+     * The application options for the worker.
+     *
+     * These are usually very similar, if not identical, to the host application options.
+     * Workers just usually get a different viewport assigned to them, correlating with the
+     * canvas element in the DOM that they draw to.
+     */
+    options;
+    /**
+     * The web worker instance itself.
+     */
+    workerInstance;
+    /**
+     * Constructs a new canvas worker.
+     * @param id - The ID of the worker.
+     * @param source - The code that the worker should run. It's common to use a hybrid code module
+     * for as the sandbox application. This means the code of the host and the workers is identical,
+     * they just construct different code path on load/init. In such case, the source can simply be
+     * `new URL(import.meta.url)`.
+     * @param canvas - The canvas element to draw to.
+     * @param options - The application options.
+     */
+    constructor(id, source, canvas, options) {
+        super();
+        this.id = id;
+        this.canvas = canvas;
+        this.options = options;
+        this.workerInstance = new Worker(source, {
+            type: "module",
+        });
+        // Translate messages to events.
+        this.workerInstance.onmessage = (message) => this.dispatchEvent(new CustomEvent(message.data.type));
+    }
+    /**
+     * Posts a message to the worker.
+     *
+     * As messages to workers are _posted_ instead of _sent_, there is no delivery feedback.
+     * @param message - The message to post.
+     * @param transfer - The transferables to transfer to the worker with this message.
+     */
+    postMessage(message, transfer) {
+        this.workerInstance.postMessage(message, transfer ?? []);
+    }
+}
+/**
+ * The canvas worker instance handles a web worker instance in worker instance itself, and
+ * handles a feedback channel to the host application.
+ *
+ * It provides a thin abstraction over the web worker IPC messaging.
+ *
+ * ```ts
+ * // Construct inside of worker from global scope and rendering kernel class.
+ * const worker = new CanvasWorkerInstance(self, RenderKernel);
+ * // Listen to custom events (messages) you send from the host.
+ * worker.addEventListener("fade", () => worker.renderKernel?.fadeOut());
+ * ```
+ * @group Graphics
+ */
+export class CanvasWorkerInstance extends EventTarget {
+    /**
+     * The global scope of the worker.
+     */
+    self;
+    /**
+     * The ID of the worker.
+     */
+    id;
+    /**
+     * The rendering kernel, which produces frames, and renders them to our
+     * offscreen canvas.
+     */
+    renderKernel;
+    /**
+     * The canvas element we're presenting to.
+     */
+    canvas;
+    /**
+     * The offscreen canvas we're rendering to.
+     */
+    offscreenCanvas;
+    /**
+     * Our rendering context to draw to.
+     */
+    offscreenContext;
+    /**
+     * Manages frame rendering timing.
+     */
+    renderLoop;
+    /**
+     * Constructor of our rendering kernel.
+     */
+    #Kernel;
+    /**
+     * Constructs a new canvas worker instance.
+     *
+     * Note that many properties are only initialized after the host sent an
+     * initialization message.
+     * @param self - Our global worker scope.
+     * @param Kernel - The rendering kernel class to construct.
+     */
+    constructor(self, Kernel) {
+        super();
+        this.self = self;
+        this.id = "<unassigned>";
+        this.#Kernel = Kernel;
+        self.onmessage = (message) => {
+            const event = new CustomEvent(message.data.type);
+            this.dispatchEvent(event);
+            if (event.defaultPrevented) {
+                return;
+            }
+            if (message.data.type === "start") {
+                const startMessage = message.data;
+                this.start(startMessage.options);
+            }
+            else if (message.data.type === "pause") {
+                const pauseMessage = message.data;
+                this.renderKernel?.pause(pauseMessage.pause);
+            }
+            else if (message.data.type === "reconfigure") {
+                const reconfigureMessage = message.data;
+                this.reconfigure(reconfigureMessage.id, reconfigureMessage.canvas, reconfigureMessage.options);
+            }
+        };
+    }
+    /**
+     * Render a frame.
+     * @param delta - How many milliseconds have passed since the last invocation?
+     */
+    render = (delta) => {
+        this.renderKernel?.onDraw(delta, new Date().valueOf());
+    };
+    /**
+     * Reconfigure the worker.
+     * @param id - New ID for this worker.
+     * @param offscreenCanvas - New canvas to render to.
+     * @param options - New application options.
+     */
+    reconfigure(id, offscreenCanvas, options) {
+        this.renderLoop?.block();
+        this.id = id;
+        this.offscreenCanvas = offscreenCanvas;
+        this.offscreenContext = mustExist(this.offscreenCanvas.getContext("2d"));
+        this.canvas = new Canvas2DHeadless(this.offscreenCanvas, this.offscreenContext);
+        this.renderLoop = new RenderLoop(this.render, this.canvas);
+        if (isNil(this.renderKernel)) {
+            this.renderKernel = new this.#Kernel(this, this.canvas, options);
+        }
+        else {
+            this.renderKernel.reconfigure(this.canvas, options);
+        }
+    }
+    /**
+     * Start rendering.
+     * @param options - New application options.
+     */
+    start(options) {
+        if (!this.renderKernel) {
+            return;
+        }
+        this.renderKernel.random = new Random(options.seed);
+        this.renderKernel.start(options);
+        this.renderLoop?.unblock();
+    }
+    /**
+     * Posts a message to the host.
+     * @param message - The message to post.
+     */
+    postMessage(message) {
+        this.self.postMessage(message);
+    }
+}
+/**
+ * Base class for multi-process canvas sandbox applications.
+ *
+ * Helps in orchestrating the workers.
+ * @group Graphics
+ */
+export class CanvasSandboxHostApplication {
+    /**
+     * Usually a hidden canvas that serves as a proxy for canvas sandbox events.
+     */
+    canvas;
+    /**
+     * Application options.
+     */
+    options;
+    /**
+     * PRNG instance for the application.
+     */
+    random;
+    /**
+     * Is the application running right now?
+     */
+    paused = false;
+    /**
+     * Web worker instances.
+     */
+    workers = new Array();
+    /**
+     * Construct a new host application.
+     * @param canvas - Usually a hidden canvas in the DOM to serve as an event proxy.
+     * @param options - Application options.
+     */
+    constructor(canvas, options) {
+        this.options = options;
+        this.canvas = canvas;
+        this.random = new Random(options.seed);
+        this.reconfigure(canvas, options);
+    }
+    /**
+     * Request the application to draw a new frame.
+     * This call has no effect in a host application, as all rendering happens in the workers.
+     * @param _delta - How many milliseconds passed since the last frame draw.
+     * @param _timestamp - The current timestamp.
+     */
+    onDraw(_delta, _timestamp) {
+        // Draws happen in workers.
+    }
+    /**
+     * Pauses all workers.
+     */
+    pause() {
+        this.paused = !this.paused;
+        for (const worker of this.workers) {
+            worker.postMessage({
+                type: "pause",
+                pause: this.paused,
+            });
+        }
+    }
+    /**
+     * Start the application.
+     */
+    start() {
+        this.paused = false;
+        for (const worker of this.workers) {
+            worker.postMessage({
+                type: "start",
+                options: {
+                    ...this.options,
+                    seed: this.random.seed,
+                    viewport: worker.options.viewport,
+                },
+            });
+        }
+    }
+    /**
+     * Posts a message to all workers.
+     * @param message - Message to post to all workers.
+     */
+    postMessageAll(message) {
+        for (const worker of this.workers) {
+            worker.postMessage(message);
+        }
+    }
+}
+//# sourceMappingURL=canvas-sandbox-mp.js.map

package/graphics/canvas-sandbox-mp.js.map

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

package/graphics/canvas-sandbox.d.ts

@@ -38,6 +38,28 @@ export interface CanvasSandboxExpectedOptions {
      * The seed for the PRNG.
      */
     seed: number;
+    /**
+     * The part of the canvas that the targetted render kernel will handle.
+     * This is ignored, unless you use multi-process rendering.
+     */
+    viewport: {
+        /**
+         * Start of the viewport in fractional world-space.
+         */
+        x: number;
+        /**
+         * Start of the viewport in fractional world-space.
+         */
+        y: number;
+        /**
+         * Width of the viewport in fractional world-space.
+         */
+        w: number;
+        /**
+         * Height of the viewport in fractional world-space.
+         */
+        h: number;
+    };
 }
 /**
  * Describes an application running inside the {@linkcode CanvasSandbox}.
@@ -74,7 +96,12 @@ export interface CanvasSandboxApplication<TCanvas extends Canvas, TApplicationOp
     /**
      * Start the application.
      */
-    start(): void;
+    start(options?: Partial<TApplicationOptions>): void;
+    /**
+     * Pause rendering.
+     * @param paused - Should rendering be paused (`true`) or unpaused (`false`)?
+     */
+    pause(paused: boolean): void;
 }
 /**
  * Options for a {@linkcode CanvasSandbox}.

package/graphics/canvas-sandbox.js

@@ -1,7 +1,6 @@
 /* eslint-disable no-console */
 import { Shake } from "../device/shake.js";
 import { getDocumentElementTypeById } from "../dom/core.js";
-import { nextPalette } from "./core.js";
 import { RenderLoop } from "./render-loop.js";
 /**
  * Provides the input as-is.
@@ -60,6 +59,7 @@ export const CANVAS_SANDBOX_DEFAULT_CSS = /* PURE */ css `
     bottom: 0;
     justify-content: center;
     align-items: center;
+    z-index: 1;
 
     filter: drop-shadow(10px 10px 4px rgba(0, 0, 0, 0.5));
     transition: all 1s;
@@ -271,14 +271,11 @@ export class CanvasSandbox {
             switch (event.keyCode) {
                 case 13:
                     // Enter
-                    nextPalette();
                     this.#reconfigureApplication();
-                    this.application.reconfigure(this.canvas);
-                    this.application.start();
                     break;
                 case 32:
                     // Space
-                    this.application.paused = !this.application.paused;
+                    this.application.pause(!this.application.paused);
                     break;
             }
         });
@@ -297,18 +294,8 @@ export class CanvasSandbox {
      * Create event listeners on the canvas node in the document.
      */
     #hookCanvas() {
-        // eslint-disable-next-line @typescript-eslint/no-misused-promises
-        this.canvasNode.addEventListener("click", async (event) => {
-            if (this.document.fullscreenElement) {
-                if (this.sandboxOptions.devMode) {
-                    console.info("CanvasSandbox: Exiting fullscreen mode...");
-                }
-                await document.exitFullscreen();
-                return;
-            }
-            // Run the next variation of the application.
-            nextPalette();
-            this.#reconfigureApplication();
+        this.canvasNode.addEventListener("click", (event) => {
+            this.application.pause(!this.application.paused);
             event.preventDefault();
         });
     }
@@ -321,8 +308,7 @@ export class CanvasSandbox {
             .then(() => {
             this.shakeHandler.addEventListener("shake", () => {
                 console.info("CanvasSandbox: Shake detected. Reconfiguring application...");
-                this.application.reconfigure(this.canvas);
-                this.application.start();
+                this.#reconfigureApplication();
             });
         })
             .catch(console.error);