melonjs 15.0.0 → 15.1.0

package/src/video/canvas/canvas_renderer.js

@@ -68,8 +68,6 @@ import * as event from "./../../system/event.js";
 
     /**
      * Reset context state
-     * @name reset
-     * @memberof CanvasRenderer
      */
     reset() {
         super.reset();
@@ -78,8 +76,6 @@ import * as event from "./../../system/event.js";
 
     /**
      * Reset the canvas transform to identity
-     * @name resetTransform
-     * @memberof CanvasRenderer
      */
     resetTransform() {
         this.getContext().setTransform(1, 0, 0, 1, 0, 0);
@@ -96,9 +92,7 @@ import * as event 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]
      */
@@ -128,27 +122,23 @@ import * as event 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();
@@ -161,8 +151,6 @@ import * as event 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.
@@ -174,17 +162,15 @@ import * as event 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);
@@ -192,9 +178,7 @@ import * as event 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.
@@ -216,7 +200,7 @@ import * as event 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;
@@ -244,8 +228,8 @@ import * as event 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());
@@ -255,8 +239,6 @@ import * as event 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
@@ -269,8 +251,8 @@ import * as event 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;
@@ -278,8 +260,6 @@ import * as event 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
@@ -293,7 +273,7 @@ import * as event 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();
@@ -304,8 +284,6 @@ import * as event 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
@@ -319,8 +297,6 @@ import * as event 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
@@ -332,16 +308,16 @@ import * as event 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,
@@ -360,8 +336,6 @@ import * as event 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
@@ -373,8 +347,6 @@ import * as event 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
@@ -386,7 +358,7 @@ import * as event from "./../../system/event.js";
             return;
         }
 
-        var context = this.getContext();
+        let context = this.getContext();
 
         context.beginPath();
         context.moveTo(startX, startY);
@@ -396,8 +368,6 @@ import * as event 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
@@ -409,8 +379,6 @@ import * as event 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
      */
@@ -419,13 +387,13 @@ import * as event 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);
         }
@@ -437,8 +405,6 @@ import * as event 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) {
@@ -447,8 +413,6 @@ import * as event from "./../../system/event.js";
 
     /**
      * Stroke a rectangle at the specified coordinates
-     * @name strokeRect
-     * @memberof CanvasRenderer
      * @param {number} x
      * @param {number} y
      * @param {number} width
@@ -460,15 +424,13 @@ import * as event 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
@@ -480,8 +442,6 @@ import * as event 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
@@ -494,7 +454,7 @@ import * as event 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);
@@ -503,8 +463,6 @@ import * as event 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
@@ -517,8 +475,6 @@ import * as event from "./../../system/event.js";
 
     /**
      * Stroke a Point at the specified coordinates
-     * @name strokePoint
-     * @memberof CanvasRenderer
      * @param {number} x
      * @param {number} y
      */
@@ -528,8 +484,6 @@ import * as event 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,8 +495,6 @@ import * as event from "./../../system/event.js";
 
     /**
      * save the canvas context
-     * @name save
-     * @memberof CanvasRenderer
      */
     save() {
         this.getContext().save();
@@ -550,8 +502,6 @@ import * as event from "./../../system/event.js";
 
     /**
      * restores the canvas context
-     * @name restore
-     * @memberof CanvasRenderer
      */
     restore() {
         this.getContext().restore();
@@ -564,8 +514,6 @@ import * as event from "./../../system/event.js";
 
     /**
      * rotates the canvas context
-     * @name rotate
-     * @memberof CanvasRenderer
      * @param {number} angle - in radians
      */
     rotate(angle) {
@@ -574,8 +522,6 @@ import * as event from "./../../system/event.js";
 
     /**
      * scales the canvas context
-     * @name scale
-     * @memberof CanvasRenderer
      * @param {number} x
      * @param {number} y
      */
@@ -586,12 +532,10 @@ import * as event 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 ?
@@ -602,8 +546,6 @@ import * as event from "./../../system/event.js";
 
     /**
      * Set the global alpha
-     * @name setGlobalAlpha
-     * @memberof CanvasRenderer
      * @param {number} alpha - 0.0 to 1.0 values accepted.
      */
     setGlobalAlpha(alpha) {
@@ -612,8 +554,6 @@ import * as event from "./../../system/event.js";
 
     /**
      * Return the global alpha
-     * @name getGlobalAlpha
-     * @memberof CanvasRenderer
      * @returns {number} global alpha value
      */
     getGlobalAlpha() {
@@ -622,8 +562,6 @@ import * as event from "./../../system/event.js";
 
     /**
      * Set the line width on the context
-     * @name setLineWidth
-     * @memberof CanvasRenderer
      * @param {number} width - Line width
      */
     setLineWidth(width) {
@@ -633,8 +571,6 @@ import * as event 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) {
@@ -644,12 +580,10 @@ import * as event 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],
@@ -667,8 +601,6 @@ import * as event from "./../../system/event.js";
 
     /**
      * Translates the context to the given position
-     * @name translate
-     * @memberof CanvasRenderer
      * @param {number} x
      * @param {number} y
      */
@@ -686,22 +618,20 @@ import * as event 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();
@@ -718,13 +648,11 @@ import * as event 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
@@ -746,7 +674,7 @@ import * as event 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,
@@ -761,10 +689,10 @@ import * as event 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);
             }
@@ -783,9 +711,7 @@ import * as event from "./../../system/event.js";
 
     /**
      * disable (remove) the rendering mask set through setMask.
-     * @name clearMask
      * @see CanvasRenderer#setMask
-     * @memberof CanvasRenderer
      */
     clearMask() {
         if (this.maskLevel > 0) {

package/src/video/renderer.js

@@ -29,6 +29,7 @@ import Point from "../geometries/point.js";
      * @param {boolean} [options.transparent=false] - Whether to enable transparency on the canvas
      * @param {boolean} [options.premultipliedAlpha=true] - in WebGL, whether the renderer will assume that colors have premultiplied alpha when canvas transparency is enabled
      * @param {boolean} [options.blendMode="normal"] - the default blend mode to use ("normal", "multiply")
+     * @param {boolean} [options.depthBuffer="sorting"] - ~Experimental~ the default method to sort object on the z axis in WebGL ("sorting", "z-buffer")
      * @param {boolean} [options.subPixel=false] - Whether to enable subpixel rendering (performance hit when enabled)
      * @param {boolean} [options.verbose=false] - Enable the verbose mode that provides additional details as to what the renderer is doing
      * @param {number} [options.zoomX=width] - The actual width of the canvas with scaling applied
@@ -63,6 +64,14 @@ import Point from "../geometries/point.js";
          */
         this.isContextValid = true;
 
+        /**
+         * the default method to sort object ("sorting", "z-buffer")
+         * @type {string}
+         * @default "sorting"
+         */
+        this.depthTest = "sorting";
+
+
         /**
          * The Path2D instance used by the renderer to draw primitives
          * @type {Path2D}
@@ -193,7 +202,7 @@ import Point from "../geometries/point.js";
             transparent = true;
         }
 
-        var _context = canvas.getContext("2d", {
+        let _context = canvas.getContext("2d", {
                 "alpha" : transparent
         });
 
@@ -255,7 +264,7 @@ import Point from "../geometries/point.js";
      * @param {number} height - new height of the canvas
      */
     resize(width, height) {
-        var canvas = this.getCanvas();
+        let canvas = this.getCanvas();
         if (width !== canvas.width || height !== canvas.height) {
             canvas.width = width;
             canvas.height = height;
@@ -274,7 +283,7 @@ import Point from "../geometries/point.js";
      * @param {boolean} [enable=false]
      */
     setAntiAlias(context, enable) {
-        var canvas = context.canvas;
+        let canvas = context.canvas;
 
         // enable/disable antialis on the given Context2d object
         setPrefixed("imageSmoothingEnabled", enable === true, context);
@@ -354,8 +363,8 @@ import Point from "../geometries/point.js";
      * @returns {HTMLCanvasElement|OffscreenCanvas} a new canvas element representing the tinted image
      */
     tint(src, color, mode) {
-        var canvas = createCanvas(src.width, src.height, true);
-        var context = this.getContext2d(canvas);
+        let canvas = createCanvas(src.width, src.height, true);
+        let context = this.getContext2d(canvas);
 
         context.save();
 
@@ -407,4 +416,62 @@ import Point from "../geometries/point.js";
         // reset to default
         this.currentTint.setColor(255, 255, 255, 1.0);
     }
+
+    /**
+     * creates a Blob object representing the last rendered frame
+     * @param {Object} [options] - An object with the following properties:
+     * @param {String} [options.type="image/png"] - A string indicating the image format
+     * @param {Number} [options.quality] - A Number between 0 and 1 indicating the image quality to be used when creating images using file formats that support lossy compression (such as image/jpeg or image/webp). A user agent will use its default quality value if this option is not specified, or if the number is outside the allowed range.
+     * @return {Promise} A Promise returning a Blob object representing the last rendered frame
+     * @example
+     * renderer.convertToBlob().then((blob) => console.log(blob));
+     */
+    toBlob(options) {
+        return new Promise((resolve) => {
+            event.once(event.GAME_AFTER_DRAW, () => {
+                this.canvas.toBlob((blob) => {
+                    resolve(blob);
+                }, options ? options.type : undefined, options ? options.quality : undefined);
+            });
+        });
+    }
+
+    /**
+     * creates an ImageBitmap object of the last frame rendered
+     * (not supported by standard Canvas)
+     * @param {Object} [options] - An object with the following properties:
+     * @param {String} [options.type="image/png"] - A string indicating the image format
+     * @param {Number} [options.quality] - A Number between 0 and 1 indicating the image quality to be used when creating images using file formats that support lossy compression (such as image/jpeg or image/webp). A user agent will use its default quality value if this option is not specified, or if the number is outside the allowed range.
+     * @return {Promise} A Promise returning an ImageBitmap.
+     * @example
+     * renderer.transferToImageBitmap().then((image) => console.log(image));
+     */
+    toImageBitmap(options) {
+        return new Promise((resolve) => {
+            event.once(event.GAME_AFTER_DRAW, () => {
+                let image = new Image();
+                image.src = this.canvas.toDataURL(options);
+                image.onload = () => {
+                    createImageBitmap(image).then((bitmap) => resolve(bitmap));
+                };
+            });
+        });
+    }
+
+    /**
+     * returns a data URL containing a representation of the last frame rendered
+     * @param {Object} [options] - An object with the following properties:
+     * @param {String} [options.type="image/png"] - A string indicating the image format
+     * @param {Number} [options.quality] - A Number between 0 and 1 indicating the image quality to be used when creating images using file formats that support lossy compression (such as image/jpeg or image/webp). A user agent will use its default quality value if this option is not specified, or if the number is outside the allowed range.
+     * @return {Promise} A Promise returning a string containing the requested data URL.
+     * @example
+     * renderer.toDataURL().then((dataURL) => console.log(dataURL));
+     */
+    toDataURL(options) {
+        return new Promise((resolve) => {
+            event.once(event.GAME_AFTER_DRAW, () => {
+                resolve(this.canvas.toDataURL(options));
+            });
+        });
+    }
 }