like2d 2.11.0 → 2.12.0

package/dist/graphics/canvas.js

@@ -1,5 +1,13 @@
 import { Rect } from "../math/rect";
 import { Vec2 } from "../math/vector2";
+/**
+ * A manager for the HTML canvas element, similar to `love.window`.
+ *
+ * Controls game size / scaling -- both native and pixelart mode via {@link Canvas.setMode}, as well as fullscreen functions.
+ *
+ * The canvas keeps two canvases: render and display. Each frame, it copies render to display before the canvas is presented.
+ * This allows for pixel-accurate scaling.
+ */
 export class Canvas {
     constructor(
     /** The ultimately visible canvas in the browser */
@@ -22,10 +30,7 @@ export class Canvas {
             writable: true,
             value: abort
         });
-        /** The canvas that we're drawing to with `like.gfx` functions.
-         * If it's the same as displayCanvas, we're in native mode.
-         * Otherwise, we're in pixelart mode, consisting of nearest -> linear scaling.
-        */
+        /** The canvas that we're drawing to with `like.gfx` functions.  */
         Object.defineProperty(this, "renderCanvas", {
             enumerable: true,
             configurable: true,
@@ -38,42 +43,39 @@ export class Canvas {
             writable: true,
             value: 0
         });
+        Object.defineProperty(this, "isNativeMode", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: true
+        });
         displayCanvas.tabIndex = 0;
         displayCanvas.style.width = '100%';
         displayCanvas.style.height = '100%';
-        this.renderCanvas = this.displayCanvas;
+        displayCanvas.style.objectFit = 'contain';
+        // Always create a separate render canvas
+        this.renderCanvas = document.createElement('canvas');
         this.setMode('native');
         /** Only the canvas can really transform the mouse to the game size.
          * This hack sends an event for the mouse module to listen to.
          */
         this.displayCanvas.addEventListener('mousemove', (ev) => {
-            let pos;
-            let delta;
             const rawPos = [ev.offsetX, ev.offsetY];
             const rawDelta = [ev.movementX, ev.movementY];
-            if (this.renderCanvas == this.displayCanvas) {
-                /* Native mode. */
-                pos = Vec2.mul(rawPos, window.devicePixelRatio ?? 1);
-                delta = Vec2.mul(rawDelta, window.devicePixelRatio ?? 1);
-            }
-            else {
-                /* Pixelart mode. This math simulates object-fit: contain,
-                * which preserves aspect ratio.
-                */
-                const csize = [
-                    this.displayCanvas.clientWidth,
-                    this.displayCanvas.clientHeight
-                ];
-                /* Scale of both dimensions */
-                const scale = calcAspectFriendlyScale(this.getSize(), csize);
-                /* Upper-left corner */
-                const offset = Vec2.div(Vec2.sub(csize, Vec2.mul(this.getSize(), scale)), 2);
-                pos = Vec2.div(Vec2.sub(rawPos, offset), scale);
-                delta = Vec2.div(rawDelta, scale);
-                /* Only handle mousemove events that are in bounds. */
-                if (!Rect.containsPoint(this.getRect(), pos)) {
-                    return;
-                }
+            /* Recreation of object-fit */
+            const csize = [
+                this.displayCanvas.clientWidth,
+                this.displayCanvas.clientHeight
+            ];
+            /* Scale of both dimensions */
+            const scale = calcAspectFriendlyScale(this.getSize(), csize);
+            /* Upper-left corner */
+            const offset = Vec2.div(Vec2.sub(csize, Vec2.mul(this.getSize(), scale)), 2);
+            const pos = Vec2.div(Vec2.sub(rawPos, offset), scale);
+            const delta = Vec2.div(rawDelta, scale);
+            /* Only handle mousemove events that are in bounds. */
+            if (!Rect.containsPoint(this.getRect(), pos)) {
+                return;
             }
             this.displayCanvas.dispatchEvent(new CustomEvent('like:mousemoved', {
                 detail: {
@@ -85,6 +87,14 @@ export class Canvas {
         this.displayCanvas.addEventListener("like:preDraw", this.preDraw.bind(this), { signal: this.abort });
         this.displayCanvas.addEventListener("like:postDraw", this.postDraw.bind(this), { signal: this.abort });
     }
+    /**
+     * Get the canvas that graphics functions render to.
+     * This is separate from the display canvas; it is
+     * not visibly exposed but rather copied each frame.
+    */
+    getContext() {
+        return this.renderCanvas.getContext('2d');
+    }
     /** Get a unified canvas info object. */
     getMode() {
         return {
@@ -110,27 +120,13 @@ export class Canvas {
      * @param flags optional options.
      */
     setMode(size, flags = {}) {
-        // set up sizing / render target
-        const prevRenderCanvas = this.renderCanvas;
-        if (size == 'native') {
-            this.displayCanvas.style.objectFit = 'fill';
-            this.renderCanvas = this.displayCanvas;
-        }
-        else {
-            this.displayCanvas.style.objectFit = 'contain';
-            this.renderCanvas = document.createElement('canvas');
+        this.isNativeMode = size === 'native';
+        if (size !== 'native') {
             const changed = Canvas.setCanvasElemSize(this.renderCanvas, size);
             if (changed) {
                 this.dispatchResize(size);
             }
         }
-        if (prevRenderCanvas != this.renderCanvas) {
-            this.displayCanvas.dispatchEvent(new CustomEvent("like:updateRenderTarget", {
-                detail: {
-                    target: this.renderCanvas,
-                },
-            }));
-        }
         if ('fullscreen' in flags) {
             this.setFullscreen(flags.fullscreen);
         }
@@ -159,6 +155,10 @@ export class Canvas {
     getFullscreen() {
         return this.displayCanvas === document.fullscreenElement;
     }
+    /** Does the canvas have focus? */
+    hasFocus() {
+        return document.activeElement === this.displayCanvas;
+    }
     /** Set fullscreen. */
     setFullscreen(fullscreen) {
         if (fullscreen) {
@@ -172,49 +172,50 @@ export class Canvas {
         }
     }
     /**
-     * Called internally by the engine before
-     * rendering a frame.
+     * Trigered by `like:preDraw`
      */
     preDraw() {
-        if (this.renderCanvas == this.displayCanvas) {
+        if (this.isNativeMode) {
+            // In native mode, renderCanvas tracks display size
             const realSize = this.getDisplayPixelSize();
-            if ((realSize[0] != this.displayCanvas.width ||
-                realSize[1] != this.displayCanvas.height) &&
+            if ((realSize[0] != this.renderCanvas.width ||
+                realSize[1] != this.renderCanvas.height) &&
                 !this.resizeTimeoutId) {
                 /** In native scaling mode, zooming and resizing the window cause us
                  * to set canvas width and height every frame, which could cause
                  * tons of canvas bitmap reallocations. So wait 1/4 second..
                  */
-                Canvas.setCanvasElemSize(this.displayCanvas, realSize);
+                Canvas.setCanvasElemSize(this.renderCanvas, realSize);
                 this.dispatchResize(realSize);
                 this.resizeTimeoutId = setTimeout(() => { this.resizeTimeoutId = 0; }, 250);
             }
         }
-        this.renderCanvas.getContext('2d').resetTransform();
+        const ctx = this.renderCanvas.getContext('2d');
+        ctx.resetTransform();
+        // Enable smoothing in native mode, disable in pixelart mode
+        ctx.imageSmoothingEnabled = this.isNativeMode;
     }
-    /** Called every frame by the engine after drawing */
+    /** Triggered by `like:postDraw` */
     postDraw() {
-        if (this.renderCanvas != this.displayCanvas) {
-            /* We're in pixelart mode,
-             * so set output canvas size to an ideal integer scale.
-             * No debounce: changes to integer ratio are infrequent.
-             */
+        // Always blit from render canvas to display canvas
+        if (this.isNativeMode) {
+            // In native mode, display canvas matches render canvas size
+            Canvas.setCanvasElemSize(this.displayCanvas, this.getSize());
+        }
+        else {
+            // In pixelart mode, set output canvas size to an ideal integer scale
             Canvas.setCanvasElemSize(this.displayCanvas, Vec2.mul(this.getSize(), Math.round(calcAspectFriendlyScale(this.getSize(), this.getDisplayPixelSize()))));
-            // Copy the internal canvas to the visible one.
-            const ctx = this.displayCanvas.getContext('2d');
-            ctx.imageSmoothingEnabled = false;
-            ctx.drawImage(this.renderCanvas, 0, 0, this.renderCanvas.width, this.renderCanvas.height, 0, 0, this.displayCanvas.width, this.displayCanvas.height);
         }
+        // Copy the render canvas to the visible one
+        const displayCtx = this.displayCanvas.getContext('2d');
+        displayCtx.imageSmoothingEnabled = false;
+        displayCtx.drawImage(this.renderCanvas, 0, 0, this.renderCanvas.width, this.renderCanvas.height, 0, 0, this.displayCanvas.width, this.displayCanvas.height);
     }
     /** @returns if size was changed.  */
     static setCanvasElemSize(canvas, newSize) {
-        const ctx = canvas.getContext('2d');
-        if (!ctx)
-            return false;
         if (canvas.width === newSize[0] && canvas.height === newSize[1])
             return false;
-        canvas.width = newSize[0];
-        canvas.height = newSize[1];
+        [canvas.width, canvas.height] = newSize;
         return true;
     }
     static getCanvasElemSize(canvas) {

package/dist/graphics/graphics.d.ts

@@ -26,8 +26,9 @@
  * - Y increases down
  * - Angles in radians, 0 is right, positive is clockwise
  */
-import { type Vector2 } from "../math/vector2";
+import type { Vector2 } from "../math/vector2";
 import type { Rectangle } from "../math/rect";
+import { ImageHandle } from "./image";
 export type DrawMode = "fill" | "line";
 /**
  * - RGBA array with values 0-1: `[r, g, b, a]`
@@ -35,64 +36,72 @@ export type DrawMode = "fill" | "line";
  * - CSS color strings also accepted: `"red"`, `"#ff0000"`, `"rgb(255,0,0)"`
  */
 export type Color = [number, number, number, number?] | string;
+export type TransformProps = {
+    angle?: number;
+    scale?: number | Vector2;
+    origin?: Vector2;
+};
 export type ShapeProps = {
     lineWidth?: number;
     lineCap?: CanvasLineCap;
     lineJoin?: CanvasLineJoin;
     miterLimit?: number;
-};
+} & TransformProps;
 export type DrawProps = ShapeProps & {
     quad?: Rectangle;
-    r?: number;
-    scale?: number | Vector2;
-    origin?: number | Vector2;
 };
 export type PrintProps = {
     font?: string;
     width?: number;
     align?: CanvasTextAlign;
-};
-export declare class ImageHandle {
-    readonly path: string;
-    private element;
-    private loadPromise;
-    private isLoaded;
-    constructor(path: string);
-    isReady(): boolean;
-    ready(): Promise<void>;
-    get size(): Vector2;
-    getElement(): HTMLImageElement | null;
-}
+} & TransformProps;
 /**
- * All of these methods exist on `like.gfx`, but with `ctx`
- * bound to the first arg.
+ * LIKE's way of drawing to the screen.
+ *
+ * More specifically: a system for wrapping canvas draw calls conveniently.
  *
- * Acts as the core of the graphics system, but can be used separately.
+ *  - Reduces state in calls -- no `setColor`, etc. Everything is passed in.
+ *  - Abstracts away common drawing operations.
  *
+ * ### Examples
+ * Draw a spinning symbol in the center of the screen using transforms.
  * ```ts
- * import { draw } from "like/graphics"
- * draw.clear(my2dContext, "red");
- * ```
+ * function drawSpinningYinYang(like: Like) {
+ *   const color1 = "black";
+ *   const color2 = "white";
+ *   const size = 50;
+ *   const pos = Vec2.div(like.canvas.getSize(), 2); // calc center of screen
+ *   const speed = 0.5; // rotations per second
+ *
+ *   like.gfx.withTransform(() => {
+ *     like.gfx.translate(pos);
+ *     like.gfx.rotate(like.timer.getTime() * Math.PI * 2.0 * speed);
+ *     like.gfx.scale(size);
+ *     like.gfx.circle("fill", color1, [0, 0], 2);
+ *     // use the arc parameter to fill in a semicircle. Note that it's clockwise from {x:1, y:0}.
+ *     like.gfx.circle("fill", color2, [0, 0], 2, { arc: [Math.PI/2, Math.PI*3/2] });
+ *     like.gfx.circle("fill", color2, [0, -1], 1);
+ *     like.gfx.circle("fill", color1, [0, 1], 1);
+ *     like.gfx.circle("fill", color2, [0, 1], 1/3);
+ *     like.gfx.circle("fill", color1, [0, -1], 1/3);
+ *   })
+ * }
  *
+ * like.draw = (like: Like) => {
+ *   drawSpinningYinYang(like);
+ * }
+ * ```
  */
 export declare class Graphics {
     private ctx;
     constructor(ctx: CanvasRenderingContext2D);
-    /**
-     * Set the 2d drawing context for graphics.
-     *
-     * Be aware that that `like` can set this value at any time.
-     */
-    setContext(ctx: CanvasRenderingContext2D): void;
     /**
      * Clears the canvas with a solid color.
-     * @param this.ctx Canvas context.
      * @param color Fill color.
      */
     clear(color?: Color): void;
     /**
      * Draws a rectangle.
-     * @param this.ctx Canvas context.
      * @param mode Fill or line.
      * @param color Fill or stroke color.
      * @param rect Rectangle [x, y, w, h].
@@ -101,20 +110,20 @@ export declare class Graphics {
     rectangle(mode: DrawMode, color: Color, rect: Rectangle, props?: ShapeProps): void;
     /**
      * Draws a circle or ellipse.
-     * @param this.ctx Canvas context.
+     
      * @param mode Fill or line.
      * @param color Fill or stroke color.
      * @param position Center position.
      * @param radii Radius (number) or [rx, ry] for ellipse.
      * @param props Optional arc, center, and stroke properties. Center is true by default.
      */
-    circle(mode: DrawMode, color: Color, position: Vector2, radii: number | Vector2, props?: ShapeProps & {
+    circle(mode: DrawMode, color: Color, position: Vector2, radius: number, props?: ShapeProps & {
         arc?: [number, number];
         center?: boolean;
     }): void;
     /**
      * Draws connected line segments.
-     * @param this.ctx Canvas context.
+     
      * @param color Stroke color.
      * @param points Array of [x, y] positions.
      * @param props Optional stroke properties.
@@ -130,7 +139,7 @@ export declare class Graphics {
      * to the left and right of its position. If you align right, your position
      * becomes the upper-right corner of the text.
      *
-     * @param this.ctx Canvas context.
+     
      * @param color Fill color.
      * @param text Text string.
      * @param position Top-left position.
@@ -142,8 +151,7 @@ export declare class Graphics {
      *
      * @remarks named "draw" because it draws anything _drawable_
      * in the long run.
-     *
-     * @param this.ctx Canvas context.
+     
      * @param handle Image handle from newImage.
      * @param position Draw position.
      * @param props Optional rotation, scale, origin, or quad.
@@ -151,61 +159,81 @@ export declare class Graphics {
     draw(handle: ImageHandle, position: Vector2, props?: DrawProps): void;
     /**
      * Loads an image from a path.
-     * Unlike built-in loading, this pretends to be synchronous.
-     * @param this.ctx Canvas context.
+     * Unlike fetch, this pretends to be synchronous.
+     
      * @param path Image file path.
      * @returns ImageHandle for use with draw.
      */
     newImage(path: string): ImageHandle;
-    /**
-     * Sets the clipping region.
-     * @param this.ctx Canvas context.
-     * @param rect Clipping rectangle, or full canvas if omitted.
-     */
-    clip(rect?: Rectangle): void;
     /**
      * Draws a polygon.
-     * @param this.ctx Canvas context.
+      
      * @param mode Fill or line.
      * @param color Fill or stroke color.
      * @param points Array of [x, y] vertices.
-     * @param props Optional stroke properties.
+     * @param props Optional stroke and transform properties.
      */
-    polygon(mode: DrawMode, color: Color, points: Vector2[], props?: ShapeProps): void;
+    polygon(mode: DrawMode, color: Color, position: Vector2, points: Vector2[], props?: ShapeProps): void;
     /**
      * Draws individual pixels.
-     * @param this.ctx Canvas context.
+     
      * @param color Fill color.
      * @param pts Array of [x, y] positions.
      */
-    points(color: Color, pts: Vector2[]): void;
+    points(color: Color, pts: Vector2[], props?: TransformProps): void;
+    private applyTransform;
     /**
      * Saves canvas state.
-     * @param this.ctx Canvas context.
+      
      */
     push(): void;
     /**
      * Restores canvas state.
-     * @param this.ctx Canvas context.
+     
      */
     pop(): void;
     /**
      * Applies a translation.
-     * @param this.ctx Canvas context.
+     
      * @param offset [x, y] offset.
      */
     translate(offset: Vector2): void;
     /**
      * Applies a rotation.
-     * @param this.ctx Canvas context.
+     
      * @param angle Rotation in radians.
      */
     rotate(angle: number): void;
     /**
      * Applies a scale.
-     * @param this.ctx Canvas context.
+     
      * @param factor Scale factor (number or [x, y]).
      */
     scale(factor: number | Vector2): void;
+    /**
+     * The idiomatic way to render to an external canvas.
+     *
+     * Within this scope, the target canvas has changed.
+     *
+     * Outside, it stays the same.
+     *
+     * @param canvas The canvas to draw to.
+     * @param callback Functions that will be called while drawing to the target.
+     */
+    withRenderTarget(context: CanvasRenderingContext2D, callback: () => void): void;
+    /**
+     * _For Expressive Purposes_
+     *
+     * A simple wrapper around push/pop (save/restore)
+     * that clearly allows a set of statements to have their
+     * own transform matrix.
+     *
+     * In other words, any `scale`, `translate`, etc.
+     * performed in this block does not affect the
+     * outside world.
+     *
+     * @param callback the drawing logic.
+     */
+    withTransform(callback: () => void): void;
 }
 //# sourceMappingURL=graphics.d.ts.map