littlejsengine 1.19.3 → 1.20.0

package/plugins/drawUtilities.js

@@ -1,7 +1,7 @@
 /**
  * LittleJS Drawing Utilities Plugin
  * - Extra drawing functions for LittleJS
- * - Nine slice and three slice drawing
+ * - Nine slice and three slice drawing, and TileSlice to keep one as a style, like a UI skin
  * @namespace DrawUtilities
  */
 
@@ -9,22 +9,32 @@
 
 ///////////////////////////////////////////////////////////////////////////////
 
-/** Draw a scalable nine-slice UI element to the main canvas in screen space
- *  This function can not apply color because it draws using the 2d context
+/** Draw a scalable nine-slice UI element in screen space, drawNineSlice with screenSpace set
+ *  - Draws with the 2D context by default, on top of what WebGL drew, like drawTextScreen
+ *  - With no angle its pieces land on whole pixels and meet exactly, so pixel art lines up and extraSpace is not used
  *  @param {Vector2} pos - Screen space position
  *  @param {Vector2} size - Screen space size
  *  @param {TileInfo} startTile - Top-left tile of the 3x3 block to sample (see drawNineSlice)
+ *  @param {Color|number} [color=WHITE] - Color to modulate with; a number here is the borderSize of the order before 1.20, deprecated
  *  @param {number} [borderSize] - Rendered thickness of the border sections
+ *  @param {Color} [additiveColor] - Additive color
  *  @param {number} [extraSpace] - Extra spacing adjustment
  *  @param {number} [angle] - Angle to rotate by
+ *  @param {boolean} [useWebGL] - Use WebGL for rendering
+ *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context] - Canvas context to use
  *  @memberof DrawUtilities */
-function drawNineSliceScreen(pos, size, startTile, borderSize=32, extraSpace=2, angle=0)
+function drawNineSliceScreen(pos, size, startTile, color=WHITE, borderSize=32, additiveColor, extraSpace=2, angle=0, useWebGL=false, context)
 {
-    drawNineSlice(pos, size, startTile, WHITE, borderSize, BLACK, extraSpace, angle, false, true);
+    if (isNumber(color)) // deprecated since 1.20, the order before it: borderSize, extraSpace and angle after startTile
+    {
+        [borderSize, extraSpace, angle] = [/** @type {number} */ (color), arguments[4] ?? 2, arguments[5] ?? 0];
+        color = WHITE, additiveColor = undefined;
+    }
+    drawNineSlice(pos, size, startTile, /** @type {Color} */ (color), borderSize, additiveColor, extraSpace, angle, useWebGL, true, context);
 }
 
 /** Draw a scalable nine-slice UI element in world space
- *  This function can apply color and additive color if WebGL is enabled
+ *  Color and additive color apply in WebGL and Canvas2D (with canvasColorTiles)
  *  The nine-slice samples a 3x3 block of tiles from the tilesheet, it does not
  *  subdivide a single tile. Pass the top-left tile of that block as startTile;
  *  the other 8 tiles (edges, corners, and center) are taken automatically from
@@ -34,19 +44,37 @@ function drawNineSliceScreen(pos, size, startTile, borderSize=32, extraSpace=2,
  *  @param {Vector2} size - World space size
  *  @param {TileInfo} startTile - Top-left tile of the 3x3 block to sample the nine-slice from
  *  @param {Color} [color] - Color to modulate with
- *  @param {number} [borderSize] - Rendered thickness of the border sections
+ *  @param {number} [borderSize] - Rendered thickness of the border sections, 1 in world space and 32 pixels in
+ *    screen space by default
  *  @param {Color} [additiveColor] - Additive color
- *  @param {number} [extraSpace] - Extra spacing adjustment
+ *  @param {number} [extraSpace] - Extra spacing adjustment, .05 in world space and 2 pixels in screen space by
+ *    default
  *  @param {number} [angle] - Angle to rotate by
  *  @param {boolean} [useWebGL=glEnable] - Use WebGL for rendering
- *  @param {boolean} [screenSpace] - Use screen space coordinates
- *  @param {CanvasRenderingContext2D} [context] - Canvas context to use
+ *  @param {boolean} [screenSpace=drawScreenSpace] - Use screen space coordinates
+ *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context] - Canvas context to use
  *  @memberof DrawUtilities */
-function drawNineSlice(pos, size, startTile, color, borderSize=1, additiveColor, extraSpace=.05, angle=0, useWebGL=glEnable, screenSpace, context)
+function drawNineSlice(pos, size, startTile, color, borderSize, additiveColor, extraSpace, angle=0, useWebGL=glEnable, screenSpace=drawScreenSpace, context)
 {
+    // the border and spacing defaults are in the units of the space it draws in
+    borderSize ??= screenSpace ? 32 : 1;
+    extraSpace ??= screenSpace ? 2 : .05;
+    if (!size.x || !size.y) return; // nothing to draw, the spacing must not make a sliver of it
+    if (color && color.a < 1)
+        extraSpace = 0; // see through, the overlap that hides a seam would draw twice and show brighter
     // setup nine slice tiles - startTile is the top-left of a 3x3 tile block,
-    // so the center tile is one tile down and right from it
-    const centerTile = startTile.offset(startTile.size);
+    // so the center tile is one tile down and right from it, stepping over
+    // the padding around each tile the way tile() lays out the grid
+    const step = startTile.size.add(vec2(startTile.padding*2));
+    if (screenSpace && !angle)
+    {
+        // on whole pixels, the pieces in the screen's rows and columns of the block
+        drawSliceSnapped(pos, size, borderSize, (col, row)=>
+            [startTile.offset(step.multiply(vec2(col, row))), 0], color, additiveColor, useWebGL, context);
+        return;
+    }
+    borderSize = min(borderSize, abs(size.x)/2, abs(size.y)/2); // a box too small for two borders splits between them
+    const centerTile = startTile.offset(step);
     const centerSize = size.add(vec2(extraSpace-borderSize*2));
     const cornerSize = vec2(borderSize);
     const cornerOffset = size.scale(.5).subtract(cornerSize.scale(.5));
@@ -61,7 +89,7 @@ function drawNineSlice(pos, size, startTile, color, borderSize=1, additiveColor,
         const horizontal = i%2;
         const sidePos = cornerOffset.multiply(vec2(horizontal?i===1?1:-1:0, horizontal?0:i?-1:1));
         const sideSize = vec2(horizontal ? borderSize : centerSize.x, horizontal ? centerSize.y : borderSize);
-        const sideTile = centerTile.offset(startTile.size.multiply(vec2(i===1?1:i===3?-1:0,i===0?-flip:i===2?flip:0)))
+        const sideTile = centerTile.offset(step.multiply(vec2(i===1?1:i===3?-1:0,i===0?-flip:i===2?flip:0)))
         drawTile(pos.add(sidePos.rotate(rotateAngle)), sideSize, sideTile, color, angle, false, additiveColor, useWebGL, screenSpace, context);
     }
     for (let i=4; i--;)
@@ -70,27 +98,37 @@ function drawNineSlice(pos, size, startTile, color, borderSize=1, additiveColor,
         const flipX = i>1;
         const flipY = i && i<3;
         const cornerPos = cornerOffset.multiply(vec2(flipX?-1:1, flipY?-1:1));
-        const cornerTile = centerTile.offset(startTile.size.multiply(vec2(flipX?-1:1,flipY?flip:-flip)));
+        const cornerTile = centerTile.offset(step.multiply(vec2(flipX?-1:1,flipY?flip:-flip)));
         drawTile(pos.add(cornerPos.rotate(rotateAngle)), cornerSize, cornerTile, color, angle, false, additiveColor, useWebGL, screenSpace, context);
     }
 }
 
-/** Draw a scalable three-slice UI element to the main canvas in screen space
- *  This function can not apply color because it draws using the 2d context
+/** Draw a scalable three-slice UI element in screen space, drawThreeSlice with screenSpace set
+ *  - Draws with the 2D context by default, on top of what WebGL drew, like drawTextScreen
+ *  - With no angle its pieces land on whole pixels and meet exactly, so pixel art lines up and extraSpace is not used
  *  @param {Vector2} pos - Screen space position
  *  @param {Vector2} size - Screen space size
  *  @param {TileInfo} startTile - First of 3 consecutive tiles: corner, side, center (see drawThreeSlice)
+ *  @param {Color|number} [color=WHITE] - Color to modulate with; a number here is the borderSize of the order before 1.20, deprecated
  *  @param {number} [borderSize] - Rendered thickness of the border sections
+ *  @param {Color} [additiveColor] - Additive color
  *  @param {number} [extraSpace] - Extra spacing adjustment
  *  @param {number} [angle] - Angle to rotate by
+ *  @param {boolean} [useWebGL] - Use WebGL for rendering
+ *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context] - Canvas context to use
  *  @memberof DrawUtilities */
-function drawThreeSliceScreen(pos, size, startTile, borderSize=32, extraSpace=2, angle=0)
+function drawThreeSliceScreen(pos, size, startTile, color=WHITE, borderSize=32, additiveColor, extraSpace=2, angle=0, useWebGL=false, context)
 {
-    drawThreeSlice(pos, size, startTile, WHITE, borderSize, BLACK, extraSpace, angle, false, true);
+    if (isNumber(color)) // deprecated since 1.20, the order before it: borderSize, extraSpace and angle after startTile
+    {
+        [borderSize, extraSpace, angle] = [/** @type {number} */ (color), arguments[4] ?? 2, arguments[5] ?? 0];
+        color = WHITE, additiveColor = undefined;
+    }
+    drawThreeSlice(pos, size, startTile, /** @type {Color} */ (color), borderSize, additiveColor, extraSpace, angle, useWebGL, true, context);
 }
 
 /** Draw a scalable three-slice UI element in world space
- *  This function can apply color and additive color if WebGL is enabled
+ *  Color and additive color apply in WebGL and Canvas2D (with canvasColorTiles)
  *  The three-slice samples 3 consecutive tiles from the tilesheet, it does not
  *  subdivide a single tile. Pass the first tile as startTile; the three tiles
  *  are used in order as corner, side, and center, then rotated and mirrored to
@@ -99,20 +137,40 @@ function drawThreeSliceScreen(pos, size, startTile, borderSize=32, extraSpace=2,
  *  @param {Vector2} size - World space size
  *  @param {TileInfo} startTile - First of 3 consecutive tiles (corner, side, center) for the three-slice
  *  @param {Color} [color] - Color to modulate with
- *  @param {number} [borderSize] - Rendered thickness of the border sections
+ *  @param {number} [borderSize] - Rendered thickness of the border sections, 1 in world space and 32 pixels in
+ *    screen space by default
  *  @param {Color} [additiveColor] - Additive color
- *  @param {number} [extraSpace] - Extra spacing adjustment
+ *  @param {number} [extraSpace] - Extra spacing adjustment, .05 in world space and 2 pixels in screen space by
+ *    default
  *  @param {number} [angle] - Angle to rotate by
  *  @param {boolean} [useWebGL=glEnable] - Use WebGL for rendering
- *  @param {boolean} [screenSpace] - Use screen space coordinates
- *  @param {CanvasRenderingContext2D} [context] - Canvas context to use
+ *  @param {boolean} [screenSpace=drawScreenSpace] - Use screen space coordinates
+ *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context] - Canvas context to use
  *  @memberof DrawUtilities */
-function drawThreeSlice(pos, size, startTile, color, borderSize=1, additiveColor, extraSpace=.05, angle=0, useWebGL=glEnable, screenSpace, context)
+function drawThreeSlice(pos, size, startTile, color, borderSize, additiveColor, extraSpace, angle=0, useWebGL=glEnable, screenSpace=drawScreenSpace, context)
 {
+    // the border and spacing defaults are in the units of the space it draws in
+    borderSize ??= screenSpace ? 32 : 1;
+    extraSpace ??= screenSpace ? 2 : .05;
+    if (!size.x || !size.y) return; // nothing to draw, the spacing must not make a sliver of it
+    if (color && color.a < 1)
+        extraSpace = 0; // see through, the overlap that hides a seam would draw twice and show brighter
     // setup three slice tiles - 3 tiles in a row starting at startTile
     const cornerTile = startTile.frame(0);
     const sideTile   = startTile.frame(1);
     const centerTile = startTile.frame(2);
+    if (screenSpace && !angle)
+    {
+        // on whole pixels, each corner and side the top left one's tile turned a quarter more going clockwise
+        const turns = [[0,0,1],[3,-1,1],[3,2,2]]; // by column in each row, -1 for the center
+        drawSliceSnapped(pos, size, borderSize, (col, row)=>
+        {
+            const turn = turns[row][col], corner = col !== 1 && row !== 1;
+            return turn < 0 ? [centerTile, 0] : [corner ? cornerTile : sideTile, turn*PI/2];
+        }, color, additiveColor, useWebGL, context);
+        return;
+    }
+    borderSize = min(borderSize, abs(size.x)/2, abs(size.y)/2); // a box too small for two borders splits between them
     const centerSize = size.add(vec2(extraSpace-borderSize*2));
     const cornerSize = vec2(borderSize);
     const cornerOffset = size.scale(.5).subtract(cornerSize.scale(.5));
@@ -141,21 +199,138 @@ function drawThreeSlice(pos, size, startTile, color, borderSize=1, additiveColor
     }
 }
 
+///////////////////////////////////////////////////////////////////////////////
+
+/**
+ * A tile drawn as a box of any size, kept as a style to draw with, like a UI skin
+ * - 9 slices is a nine-slice from the 3x3 block of tiles at tileInfo, see drawNineSlice
+ * - 3 slices is a three-slice from the 3 tiles in a row at tileInfo, see drawThreeSlice
+ * - 1 slice is the whole tile stretched over the box, a plain image
+ * - The UI system draws a widget's background with one, see uiSystem.defaultSlice
+ * @memberof DrawUtilities
+ * @example
+ * const panel = new TileSlice(tile(0, 16), 9, .5); // a border of half a world unit
+ * panel.draw(vec2(0, 5), vec2(10, 4));
+ * uiSystem.defaultSlice = new TileSlice(tile(0, 16), 9, 16); // UI sizes are pixels, every widget made after this
+ */
+class TileSlice
+{
+    /** Create a tile slice style
+     *  @param {TileInfo} tileInfo - The tile, or the first of the tiles, to draw with
+     *  @param {number} [slices] - 9 for a nine-slice, 3 for a three-slice, 1 for the whole tile
+     *  @param {number} [borderSize] - Drawn thickness of the edges and corners, undefined for the draw's own default
+     *  @param {number} [extraSpace] - Extra spacing adjustment of the slices, undefined for the draw's own default */
+    constructor(tileInfo, slices=9, borderSize, extraSpace)
+    {
+        ASSERT(tileInfo instanceof TileInfo, 'tileInfo must be a TileInfo');
+        ASSERT(slices === 9 || slices === 3 || slices === 1, 'slices must be 9, 3 or 1');
+        ASSERT(borderSize === undefined || isNumber(borderSize), 'borderSize must be a number');
+
+        /** @property {TileInfo} - The tile, or the first of the tiles, to draw with */
+        this.tileInfo = tileInfo;
+        /** @property {number} - 9 for a nine-slice, 3 for a three-slice, 1 for the whole tile */
+        this.slices = slices;
+        /** @property {number|undefined} - Drawn thickness of the edges and corners, undefined for the draw's default
+         *  @type {number|undefined} */
+        this.borderSize = borderSize;
+        /** @property {number|undefined} - Extra spacing adjustment of the slices, undefined for the draw's default
+         *  @type {number|undefined} */
+        this.extraSpace = extraSpace;
+    }
+
+    /** Draw it as a box in world space, or in screen space
+     *  @param {Vector2} pos - Center position
+     *  @param {Vector2} size - Size of the box
+     *  @param {Color} [color] - Color to modulate with
+     *  @param {Color} [additiveColor] - Additive color
+     *  @param {number} [angle] - Angle to rotate by
+     *  @param {boolean} [useWebGL=glEnable] - Use WebGL for rendering
+     *  @param {boolean} [screenSpace=drawScreenSpace] - Are pos and size in screen space?
+     *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context] - Canvas context to use */
+    draw(pos, size, color=WHITE, additiveColor, angle=0, useWebGL=glEnable, screenSpace=drawScreenSpace, context)
+    {
+        if (screenSpace) // with the screen space defaults for the border and spacing
+            return this.drawScreen(pos, size, color, additiveColor, angle, useWebGL, context);
+        if (this.slices === 9)
+            drawNineSlice(pos, size, this.tileInfo, color, this.borderSize, additiveColor, this.extraSpace, angle, useWebGL, screenSpace, context);
+        else if (this.slices === 3)
+            drawThreeSlice(pos, size, this.tileInfo, color, this.borderSize, additiveColor, this.extraSpace, angle, useWebGL, screenSpace, context);
+        else
+            drawTile(pos, size, this.tileInfo, color, angle, false, additiveColor, useWebGL, screenSpace, context);
+    }
+
+    /** Draw it as a box in screen space, with the 2D context by default, on top of what WebGL drew, like drawTextScreen
+     *  @param {Vector2} pos - Screen space center position
+     *  @param {Vector2} size - Screen space size
+     *  @param {Color} [color] - Color to modulate with
+     *  @param {Color} [additiveColor] - Additive color
+     *  @param {number} [angle] - Angle to rotate by
+     *  @param {boolean} [useWebGL] - Use WebGL for rendering
+     *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context] - Canvas context to use */
+    drawScreen(pos, size, color=WHITE, additiveColor, angle=0, useWebGL=false, context)
+    {
+        if (this.slices === 9)
+            drawNineSliceScreen(pos, size, this.tileInfo, color, this.borderSize, additiveColor, this.extraSpace, angle, useWebGL, context);
+        else if (this.slices === 3)
+            drawThreeSliceScreen(pos, size, this.tileInfo, color, this.borderSize, additiveColor, this.extraSpace, angle, useWebGL, context);
+        else
+            drawTile(pos, size, this.tileInfo, color, angle, false, additiveColor, useWebGL, true, context);
+    }
+}
+
+// draw a slice box in screen space with no angle on whole pixels: the edges and the border are rounded, and every
+// piece is cut from them, so the pieces meet exactly and their texels line up where they do, with no overlap to hide
+// a seam; pieceTile(col, row) gives the tile and angle for the piece in that column and row of the box, top left 0
+function drawSliceSnapped(pos, size, borderSize, pieceTile, color, additiveColor, useWebGL, context)
+{
+    // the pixels it lands on are the device's: a 2D context's own scale and offset, like the UI under nativeHeight
+    // centered on an odd sized canvas, or the pixel ratio; the draws land half a pixel past, see shift below
+    const canvas2D = !useWebGL || !glEnable || !!context;
+    const transform = canvas2D && (context || drawContext)?.getTransform?.();
+    const ratio = getCanvasPixelRatio();
+    const [scaleX, scaleY, offsetX, offsetY] = transform ?
+        [transform.a || 1, transform.d || 1, transform.e || 0, transform.f || 0] : [ratio, ratio, 0, 0];
+    const edges = (center, length, scale, offset)=>
+    {
+        // snapped in device order, which a mirrored context reverses, then put back in the box's own order
+        const border = max(1, round(borderSize * abs(scale)));
+        const a = round((center - length/2) * scale + offset), b = a + round(length * scale);
+        const start = min(a, b), end = max(a, b);
+        const inner = min(start + border, floor((start + end)/2)); // a box too small for two borders splits
+        const device = [start, inner, max(end - border, inner), end];
+        return (scale < 0 ? device.reverse() : device).map(edge=> (edge - offset) / scale);
+    };
+    const xs = edges(pos.x, size.x, scaleX, offsetX), ys = edges(pos.y, size.y, scaleY, offsetY);
+    const shift = .5; // a screen space draw lands half a pixel past its position, in Canvas2D and WebGL alike
+    for (let row = 3; row--;)
+    for (let col = 3; col--;)
+    {
+        const w = xs[col+1] - xs[col], h = ys[row+1] - ys[row];
+        if (w <= 0 || h <= 0) continue;
+        const [tileInfo, angle] = pieceTile(col, row);
+        const turned = round(angle / (PI/2)) % 2; // a quarter turn swaps the sides it is drawn with
+        const piecePos = vec2(xs[col] + w/2 - shift, ys[row] + h/2 - shift);
+        drawTile(piecePos, turned ? vec2(h, w) : vec2(w, h), tileInfo, color, angle, false, additiveColor, useWebGL, true, context);
+    }
+}
+
 /** Draw a crescent / moon-phase shape built from a polygon
  *  Routes through drawPoly, so it supports WebGL, screen space, color, and outlines
+ *  - At angle 0 the lit side faces up while waxing (percent below .5) and down while waning, and the lit width
+ *    grows evenly with the phase, not as the real moon's does
  *  @param {Vector2} pos - Center position
  *  @param {number}  [size] - Diameter
  *  @param {number}  [percent] - Moon phase over a full cycle (0=new, .25=first quarter, .5=full, .75=last quarter), wraps
  *  @param {Color}   [color] - Fill color
  *  @param {number}  [angle] - Angle to rotate by
- *  @param {boolean} [invert] - Flip which side is illuminated
+ *  @param {boolean} [invert] - Draw the unlit part of the disk instead of the lit part
  *  @param {number}  [lineWidth] - Outline width, 0 for no outline
  *  @param {Color}   [lineColor] - Outline color
  *  @param {boolean} [useWebGL=glEnable] - Use WebGL for rendering
- *  @param {boolean} [screenSpace] - Use screen space coordinates
- *  @param {CanvasRenderingContext2D} [context] - Canvas context to use
+ *  @param {boolean} [screenSpace=drawScreenSpace] - Use screen space coordinates
+ *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context] - Canvas context to use
  *  @memberof DrawUtilities */
-function drawCrescent(pos, size=1, percent=0, color=WHITE, angle=0, invert=false, lineWidth=0, lineColor=BLACK, useWebGL=glEnable, screenSpace=false, context)
+function drawCrescent(pos, size=1, percent=0, color=WHITE, angle=0, invert=false, lineWidth=0, lineColor=BLACK, useWebGL=glEnable, screenSpace=drawScreenSpace, context)
 {
     // build local-space points and let drawPoly apply pos/angle so screen space works
     const points = getCrescentPoints(vec2(), size, percent, 0, invert);
@@ -168,7 +343,7 @@ function drawCrescent(pos, size=1, percent=0, color=WHITE, angle=0, invert=false
  *  @param {number}  [size] - Diameter
  *  @param {number}  [percent] - Moon phase over a full cycle (0=new, .25=first quarter, .5=full, .75=last quarter), wraps
  *  @param {number}  [angle] - Angle to rotate by
- *  @param {boolean} [invert] - Flip which side is illuminated
+ *  @param {boolean} [invert] - The unlit part of the disk instead of the lit part
  *  @param {number}  [sides=glCircleSides] - Number of sides for a full circle (halved per arc)
  *  @return {Array<Vector2>} - List of points making up the crescent
  *  @memberof DrawUtilities */
@@ -182,7 +357,7 @@ function getCrescentPoints(pos, size=1, percent=0, angle=0, invert=false, sides=
     if (p >= 2)                // second half of cycle flips orientation
         angle += PI;
     p = p <= 2 ? p-1 : 3-p;
-    if (invert)                // flip the illuminated side
+    if (invert)                // the unlit part: the other side of the same curve
     {
         p = -p;
         angle += PI;