melonjs 14.5.0 → 15.1.0

package/dist/melonjs.mjs/video/canvas/canvas_renderer.js

@@ -1,5 +1,5 @@
 /*!
- * melonJS Game Engine - v14.5.0
+ * melonJS Game Engine - v15.1.0
  * http://www.melonjs.org
  * melonjs is licensed under the MIT License.
  * http://www.opensource.org/licenses/mit-license
@@ -12,7 +12,7 @@ import Ellipse from '../../geometries/ellipse.js';
 import RoundRect from '../../geometries/roundrect.js';
 import Rect from '../../geometries/rectangle.js';
 import Bounds from '../../physics/bounds.js';
-import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js';
+import { emit, on, ONCONTEXT_LOST, ONCONTEXT_RESTORED, GAME_RESET } from '../../system/event.js';
 
 /**
  * @classdesc
@@ -66,12 +66,15 @@ import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js'
             this.isContextValid = true;
             emit(ONCONTEXT_RESTORED, this);
         }, false );
+
+        // reset the renderer on game reset
+        on(GAME_RESET, () => {
+            this.reset();
+        });
     }
 
     /**
      * Reset context state
-     * @name reset
-     * @memberof CanvasRenderer
      */
     reset() {
         super.reset();
@@ -80,8 +83,6 @@ import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js'
 
     /**
      * Reset the canvas transform to identity
-     * @name resetTransform
-     * @memberof CanvasRenderer
      */
     resetTransform() {
         this.getContext().setTransform(1, 0, 0, 1, 0, 0);
@@ -98,9 +99,7 @@ import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js'
      * <img src="images/lighter-blendmode.png" width="510"/> <br>
      * - "screen" : The pixels are inverted, multiplied, and inverted again. A lighter picture is the result (opposite of multiply) <br>
      * <img src="images/screen-blendmode.png" width="510"/> <br>
-     * @name setBlendMode
      * @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/globalCompositeOperation
-     * @memberof CanvasRenderer
      * @param {string} [mode="normal"] - blend mode : "normal", "multiply", "lighter, "additive", "screen"
      * @param {CanvasRenderingContext2D} [context]
      */
@@ -130,27 +129,23 @@ import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js'
 
     /**
      * prepare the framebuffer for drawing a new frame
-     * @name clear
-     * @memberof CanvasRenderer
      */
     clear() {
         if (this.settings.transparent === false) {
-            var canvas = this.getCanvas();
-            var context = this.getContext();
+            let canvas = this.getCanvas();
+            let context = this.getContext();
             context.clearRect(0, 0, canvas.width, canvas.height);
         }
     }
 
     /**
      * Clears the main framebuffer with the given color
-     * @name clearColor
-     * @memberof CanvasRenderer
      * @param {Color|string} [color="#000000"] - CSS color.
      * @param {boolean} [opaque=false] - Allow transparency [default] or clear the surface completely [true]
      */
     clearColor(color = "#000000", opaque = false) {
-        var canvas = this.getCanvas();
-        var context = this.getContext();
+        let canvas = this.getCanvas();
+        let context = this.getContext();
 
         this.save();
         this.resetTransform();
@@ -163,8 +158,6 @@ import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js'
 
     /**
      * Erase the pixels in the given rectangular area by setting them to transparent black (rgba(0,0,0,0)).
-     * @name clearRect
-     * @memberof CanvasRenderer
      * @param {number} x - x axis of the coordinate for the rectangle starting point.
      * @param {number} y - y axis of the coordinate for the rectangle starting point.
      * @param {number} width - The rectangle's width.
@@ -176,17 +169,15 @@ import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js'
 
     /**
      * Create a pattern with the specified repetition
-     * @name createPattern
-     * @memberof CanvasRenderer
-     * @param {Image} image - Source image
+     * @param {HTMLImageElement|SVGImageElement|HTMLVideoElement|HTMLCanvasElement|ImageBitmap|OffscreenCanvas|VideoFrame} image - Source image to be used as the pattern's image
      * @param {string} repeat - Define how the pattern should be repeated
      * @returns {CanvasPattern}
      * @see ImageLayer#repeat
      * @example
-     * var tileable   = renderer.createPattern(image, "repeat");
-     * var horizontal = renderer.createPattern(image, "repeat-x");
-     * var vertical   = renderer.createPattern(image, "repeat-y");
-     * var basic      = renderer.createPattern(image, "no-repeat");
+     * let tileable   = renderer.createPattern(image, "repeat");
+     * let horizontal = renderer.createPattern(image, "repeat-x");
+     * let vertical   = renderer.createPattern(image, "repeat-y");
+     * let basic      = renderer.createPattern(image, "no-repeat");
      */
     createPattern(image, repeat) {
         return this.getContext().createPattern(image, repeat);
@@ -194,9 +185,7 @@ import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js'
 
     /**
      * Draw an image onto the main using the canvas api
-     * @name drawImage
-     * @memberof CanvasRenderer
-     * @param {Image} image - An element to draw into the context. The specification permits any canvas image source (CanvasImageSource), specifically, a CSSImageValue, an HTMLImageElement, an SVGImageElement, an HTMLVideoElement, an HTMLCanvasElement, an ImageBitmap, or an OffscreenCanvas.
+     * @param {HTMLImageElement|SVGImageElement|HTMLVideoElement|HTMLCanvasElement|ImageBitmap|OffscreenCanvas|VideoFrame} image - An element to draw into the context.
      * @param {number} sx - The X coordinate of the top left corner of the sub-rectangle of the source image to draw into the destination context.
      * @param {number} sy - The Y coordinate of the top left corner of the sub-rectangle of the source image to draw into the destination context.
      * @param {number} sw - The width of the sub-rectangle of the source image to draw into the destination context. If not specified, the entire rectangle from the coordinates specified by sx and sy to the bottom-right corner of the image is used.
@@ -218,7 +207,7 @@ import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js'
             // Fast path: don't draw fully transparent
             return;
         }
-        var context = this.getContext();
+        let context = this.getContext();
 
         if (typeof sw === "undefined") {
             sw = dw = image.width;
@@ -246,8 +235,8 @@ import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js'
         }
 
         // apply a tint if required
-        var source = image;
-        var tint = this.currentTint.toArray();
+        let source = image;
+        let tint = this.currentTint.toArray();
         if (tint[0] !== 1.0 || tint[1] !== 1.0 || tint[2] !== 1.0) {
             // get a tinted version of this image from the texture cache
             source = this.cache.tint(image, this.currentTint.toRGB());
@@ -257,8 +246,6 @@ import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js'
 
     /**
      * Draw a pattern within the given rectangle.
-     * @name drawPattern
-     * @memberof CanvasRenderer
      * @param {CanvasPattern} pattern - Pattern object
      * @param {number} x
      * @param {number} y
@@ -271,8 +258,8 @@ import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js'
             // Fast path: don't draw fully transparent
             return;
         }
-        var context = this.getContext();
-        var fillStyle = context.fillStyle;
+        let context = this.getContext();
+        let fillStyle = context.fillStyle;
         context.fillStyle = pattern;
         context.fillRect(x, y, width, height);
         context.fillStyle = fillStyle;
@@ -280,8 +267,6 @@ import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js'
 
     /**
      * Stroke an arc at the specified coordinates with given radius, start and end points
-     * @name strokeArc
-     * @memberof CanvasRenderer
      * @param {number} x - arc center point x-axis
      * @param {number} y - arc center point y-axis
      * @param {number} radius
@@ -295,7 +280,7 @@ import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js'
             // Fast path: don't draw fully transparent
             return;
         }
-        var context = this.getContext();
+        let context = this.getContext();
 
         context.translate(x, y);
         context.beginPath();
@@ -306,8 +291,6 @@ import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js'
 
     /**
      * Fill an arc at the specified coordinates with given radius, start and end points
-     * @name fillArc
-     * @memberof CanvasRenderer
      * @param {number} x - arc center point x-axis
      * @param {number} y - arc center point y-axis
      * @param {number} radius
@@ -321,8 +304,6 @@ import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js'
 
     /**
      * Stroke an ellipse at the specified coordinates with given radius
-     * @name strokeEllipse
-     * @memberof CanvasRenderer
      * @param {number} x - ellipse center point x-axis
      * @param {number} y - ellipse center point y-axis
      * @param {number} w - horizontal radius of the ellipse
@@ -334,16 +315,16 @@ import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js'
             // Fast path: don't draw fully transparent
             return;
         }
-        var context = this.getContext();
+        let context = this.getContext();
 
-        var hw = w,
+        let hw = w,
             hh = h,
             lx = x - hw,
             rx = x + hw,
             ty = y - hh,
             by = y + hh;
 
-        var xmagic = hw * 0.551784,
+        let xmagic = hw * 0.551784,
             ymagic = hh * 0.551784,
             xmin = x - xmagic,
             xmax = x + xmagic,
@@ -362,8 +343,6 @@ import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js'
 
     /**
      * Fill an ellipse at the specified coordinates with given radius
-     * @name fillEllipse
-     * @memberof CanvasRenderer
      * @param {number} x - ellipse center point x-axis
      * @param {number} y - ellipse center point y-axis
      * @param {number} w - horizontal radius of the ellipse
@@ -375,8 +354,6 @@ import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js'
 
     /**
      * Stroke a line of the given two points
-     * @name strokeLine
-     * @memberof CanvasRenderer
      * @param {number} startX - the start x coordinate
      * @param {number} startY - the start y coordinate
      * @param {number} endX - the end x coordinate
@@ -388,7 +365,7 @@ import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js'
             return;
         }
 
-        var context = this.getContext();
+        let context = this.getContext();
 
         context.beginPath();
         context.moveTo(startX, startY);
@@ -398,8 +375,6 @@ import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js'
 
     /**
      * Fill a line of the given two points
-     * @name fillLine
-     * @memberof CanvasRenderer
      * @param {number} startX - the start x coordinate
      * @param {number} startY - the start y coordinate
      * @param {number} endX - the end x coordinate
@@ -411,8 +386,6 @@ import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js'
 
     /**
      * Stroke the given me.Polygon on the screen
-     * @name strokePolygon
-     * @memberof CanvasRenderer
      * @param {Polygon} poly - the shape to draw
      * @param {boolean} [fill=false] - also fill the shape with the current color if true
      */
@@ -421,13 +394,13 @@ import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js'
             // Fast path: don't draw fully transparent
             return;
         }
-        var context = this.getContext();
+        let context = this.getContext();
 
         this.translate(poly.pos.x, poly.pos.y);
         context.beginPath();
         context.moveTo(poly.points[0].x, poly.points[0].y);
-        var point;
-        for (var i = 1; i < poly.points.length; i++) {
+        let point;
+        for (let i = 1; i < poly.points.length; i++) {
             point = poly.points[i];
             context.lineTo(point.x, point.y);
         }
@@ -439,8 +412,6 @@ import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js'
 
     /**
      * Fill the given me.Polygon on the screen
-     * @name fillPolygon
-     * @memberof CanvasRenderer
      * @param {Polygon} poly - the shape to draw
      */
     fillPolygon(poly) {
@@ -449,8 +420,6 @@ import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js'
 
     /**
      * Stroke a rectangle at the specified coordinates
-     * @name strokeRect
-     * @memberof CanvasRenderer
      * @param {number} x
      * @param {number} y
      * @param {number} width
@@ -462,15 +431,13 @@ import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js'
             // Fast path: don't draw fully transparent
             return;
         }
-        var context = this.getContext();
+        let context = this.getContext();
 
         context[fill === true ? "fillRect" : "strokeRect"](x, y, width, height);
     }
 
     /**
      * Draw a filled rectangle at the specified coordinates
-     * @name fillRect
-     * @memberof CanvasRenderer
      * @param {number} x
      * @param {number} y
      * @param {number} width
@@ -482,8 +449,6 @@ import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js'
 
     /**
      * Stroke a rounded rectangle at the specified coordinates
-     * @name strokeRoundRect
-     * @memberof CanvasRenderer
      * @param {number} x
      * @param {number} y
      * @param {number} width
@@ -496,7 +461,7 @@ import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js'
             // Fast path: don't draw fully transparent
             return;
         }
-        var context = this.getContext();
+        let context = this.getContext();
 
         context.beginPath();
         context.roundRect(x, y, width, height, radius);
@@ -505,8 +470,6 @@ import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js'
 
     /**
      * Draw a rounded filled rectangle at the specified coordinates
-     * @name fillRoundRect
-     * @memberof CanvasRenderer
      * @param {number} x
      * @param {number} y
      * @param {number} width
@@ -519,8 +482,6 @@ import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js'
 
     /**
      * Stroke a Point at the specified coordinates
-     * @name strokePoint
-     * @memberof CanvasRenderer
      * @param {number} x
      * @param {number} y
      */
@@ -530,8 +491,6 @@ import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js'
 
     /**
      * Draw a a point at the specified coordinates
-     * @name fillPoint
-     * @memberof CanvasRenderer
      * @param {number} x
      * @param {number} y
      * @param {number} width
@@ -541,19 +500,8 @@ import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js'
         this.strokePoint(x, y);
     }
 
-    /**
-     * return a reference to the font 2d Context
-     * @ignore
-     */
-    getFontContext() {
-        // in canvas mode we can directly use the 2d context
-        return this.getContext();
-    }
-
     /**
      * save the canvas context
-     * @name save
-     * @memberof CanvasRenderer
      */
     save() {
         this.getContext().save();
@@ -561,8 +509,6 @@ import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js'
 
     /**
      * restores the canvas context
-     * @name restore
-     * @memberof CanvasRenderer
      */
     restore() {
         this.getContext().restore();
@@ -575,8 +521,6 @@ import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js'
 
     /**
      * rotates the canvas context
-     * @name rotate
-     * @memberof CanvasRenderer
      * @param {number} angle - in radians
      */
     rotate(angle) {
@@ -585,8 +529,6 @@ import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js'
 
     /**
      * scales the canvas context
-     * @name scale
-     * @memberof CanvasRenderer
      * @param {number} x
      * @param {number} y
      */
@@ -597,12 +539,10 @@ import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js'
     /**
      * Set the current fill & stroke style color.
      * By default, or upon reset, the value is set to #000000.
-     * @name setColor
-     * @memberof CanvasRenderer
      * @param {Color|string} color - css color value
      */
     setColor(color) {
-        var context = this.getContext();
+        let context = this.getContext();
         context.strokeStyle =
         context.fillStyle = (
             color instanceof Color ?
@@ -613,8 +553,6 @@ import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js'
 
     /**
      * Set the global alpha
-     * @name setGlobalAlpha
-     * @memberof CanvasRenderer
      * @param {number} alpha - 0.0 to 1.0 values accepted.
      */
     setGlobalAlpha(alpha) {
@@ -623,8 +561,6 @@ import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js'
 
     /**
      * Return the global alpha
-     * @name getGlobalAlpha
-     * @memberof CanvasRenderer
      * @returns {number} global alpha value
      */
     getGlobalAlpha() {
@@ -633,8 +569,6 @@ import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js'
 
     /**
      * Set the line width on the context
-     * @name setLineWidth
-     * @memberof CanvasRenderer
      * @param {number} width - Line width
      */
     setLineWidth(width) {
@@ -644,8 +578,6 @@ import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js'
     /**
      * Reset (overrides) the renderer transformation matrix to the
      * identity one, and then apply the given transformation matrix.
-     * @name setTransform
-     * @memberof CanvasRenderer
      * @param {Matrix2d} mat2d - Matrix to transform by
      */
     setTransform(mat2d) {
@@ -655,12 +587,10 @@ import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js'
 
     /**
      * Multiply given matrix into the renderer tranformation matrix
-     * @name transform
-     * @memberof CanvasRenderer
      * @param {Matrix2d} mat2d - Matrix to transform by
      */
     transform(mat2d) {
-        var m = mat2d.toArray(),
+        let m = mat2d.toArray(),
             a = m[0],
             b = m[1],
             c = m[3],
@@ -678,8 +608,6 @@ import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js'
 
     /**
      * Translates the context to the given position
-     * @name translate
-     * @memberof CanvasRenderer
      * @param {number} x
      * @param {number} y
      */
@@ -697,22 +625,20 @@ import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js'
      * You can however save the current region using the save(),
      * and restore it (with the restore() method) any time in the future.
      * (<u>this is an experimental feature !</u>)
-     * @name clipRect
-     * @memberof CanvasRenderer
      * @param {number} x
      * @param {number} y
      * @param {number} width
      * @param {number} height
      */
     clipRect(x, y, width, height) {
-        var canvas = this.getCanvas();
+        let canvas = this.getCanvas();
         // if requested box is different from the current canvas size;
         if (x !== 0 || y !== 0 || width !== canvas.width || height !== canvas.height) {
-            var currentScissor = this.currentScissor;
+            let currentScissor = this.currentScissor;
             // if different from the current scissor box
             if (currentScissor[0] !== x || currentScissor[1] !== y ||
                 currentScissor[2] !== width || currentScissor[3] !== height) {
-                var context = this.getContext();
+                let context = this.getContext();
                 context.beginPath();
                 context.rect(x, y, width, height);
                 context.clip();
@@ -729,13 +655,11 @@ import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js'
      * A mask limits rendering elements to the shape and position of the given mask object.
      * So, if the renderable is larger than the mask, only the intersecting part of the renderable will be visible.
      * Mask are not preserved through renderer context save and restore.
-     * @name setMask
-     * @memberof CanvasRenderer
      * @param {Rect|RoundRect|Polygon|Line|Ellipse} [mask] - the shape defining the mask to be applied
      * @param {boolean} [invert=false] - either the given shape should define what is visible (default) or the opposite
      */
     setMask(mask, invert = false) {
-        var context = this.getContext();
+        let context = this.getContext();
 
         if (this.maskLevel === 0) {
             // only save context on the first mask
@@ -757,7 +681,7 @@ import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js'
                 ty = _y - hh,
                 by = _y + hh;
 
-            var xmagic = hw * 0.551784,
+            let xmagic = hw * 0.551784,
                 ymagic = hh * 0.551784,
                 xmin = _x - xmagic,
                 xmax = _x + xmagic,
@@ -772,10 +696,10 @@ import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js'
         } else {
             // polygon
             const _x = mask.pos.x, _y = mask.pos.y;
-            var point;
+            let point;
 
             context.moveTo(_x + mask.points[0].x, _y + mask.points[0].y);
-            for (var i = 1; i < mask.points.length; i++) {
+            for (let i = 1; i < mask.points.length; i++) {
                 point = mask.points[i];
                 context.lineTo(_x + point.x, _y + point.y);
             }
@@ -794,9 +718,7 @@ import { emit, ONCONTEXT_LOST, ONCONTEXT_RESTORED } from '../../system/event.js'
 
     /**
      * disable (remove) the rendering mask set through setMask.
-     * @name clearMask
      * @see CanvasRenderer#setMask
-     * @memberof CanvasRenderer
      */
     clearMask() {
         if (this.maskLevel > 0) {