melonjs 15.15.0 → 16.1.0

package/src/renderable/sprite.js

@@ -4,6 +4,7 @@ import { getImage } from "./../loader/loader.js";
 import { TextureAtlas } from "./../video/texture/atlas.js";
 import Renderable from "./renderable.js";
 import Color from "../math/color.js";
+import * as event from "../system/event.js";
 
 /**
  * @classdesc
@@ -15,7 +16,7 @@ export default class Sprite extends Renderable {
      * @param {number} x - the x coordinates of the sprite object
      * @param {number} y - the y coordinates of the sprite object
      * @param {object} settings - Configuration parameters for the Sprite object
-     * @param {HTMLImageElement|HTMLCanvasElement|TextureAtlas|string} settings.image - reference to spritesheet image, a texture atlas or to a texture atlas
+     * @param {HTMLImageElement|HTMLCanvasElement|HTMLVideoElement|TextureAtlas|string} settings.image - reference to spritesheet image, a texture atlas, a video element, or to a texture atlas
      * @param {string} [settings.name=""] - name of this object
      * @param {string} [settings.region] - region name of a specific region to use when using a texture atlas, see {@link TextureAtlas}
      * @param {number} [settings.framewidth] - Width of a single frame within the spritesheet
@@ -42,6 +43,16 @@ export default class Sprite extends Renderable {
      *     image : mytexture,
      *     region : "npc2.png",
      * });
+     *
+     * // create a video sprite
+     * let videoSprite = new me.Sprite(0, 0, {
+     *     image : me.loader.getVideo("bigbunny"),
+     *     anchorPoint : new me.Vector2d(0.5, 0.5)
+     * });
+     * // scale the video sprite
+     * videoSprite.currentTransform.scale(2);
+     * // start playing the video (if video is preloaded with `autoplay` set to false)
+     * videoSprite.play();
      */
     constructor(x, y, settings) {
 
@@ -49,39 +60,42 @@ export default class Sprite extends Renderable {
         super(x, y, 0, 0);
 
         /**
-         * pause and resume animation
-         * @public
          * @type {boolean}
          * @default false
-         * @name Sprite#animationpause
          */
         this.animationpause = false;
 
         /**
          * animation cycling speed (delay between frame in ms)
-         * @public
          * @type {number}
          * @default 100
-         * @name Sprite#animationspeed
          */
         this.animationspeed = 100;
 
         /**
          * global offset for the position to draw from on the source image.
-         * @public
          * @type {Vector2d}
          * @default <0.0,0.0>
-         * @name offset
-         * @memberof Sprite#
          */
         this.offset = pool.pull("Vector2d", 0, 0);
 
+        /**
+         * true if this is a video sprite (e.g. a HTMLVideoElement was passed as as source)
+         * @type {boolean}
+         * @default false
+         */
+        this.isVideo = false;
+
+        /**
+         * a callback fired when the end of a video or current animation was reached
+         * @type {Function}
+         * @default undefined
+         */
+        this.onended;
+
         /**
          * The source texture object this sprite object is using
-         * @public
          * @type {TextureAtlas}
-         * @name source
-         * @memberof Sprite#
          */
         this.source = null;
 
@@ -99,7 +113,7 @@ export default class Sprite extends Renderable {
             // length of the current animation name
             length : 0,
             //current frame texture offset
-            offset : pool.pull("Vector2d"),
+            offset : pool.pull("Vector2d", 0, 0),
             // current frame size
             width : 0,
             height : 0,
@@ -138,17 +152,46 @@ export default class Sprite extends Renderable {
                 }
             }
         } else {
-            // HTMLImageElement/Canvas or {string}
+            // HTMLImageElement/HTMLVideoElementCanvas or {string}
             this.image = (typeof settings.image === "object") ? settings.image : getImage(settings.image);
             // throw an error if image ends up being null/undefined
             if (!this.image) {
                 throw new Error("me.Sprite: '" + settings.image + "' image/texture not found!");
             }
-            // update the default "current" frame size
-            this.width = this.current.width = settings.framewidth = settings.framewidth || this.image.width;
-            this.height = this.current.height = settings.frameheight = settings.frameheight || this.image.height;
-            this.source = renderer.cache.get(this.image, settings);
-            this.textureAtlas = this.source.getAtlas();
+
+            this.isVideo = HTMLVideoElement && this.image instanceof HTMLVideoElement;
+
+            if (this.isVideo) {
+                this.width = this.current.width = settings.framewidth = settings.framewidth || this.image.videoWidth;
+                this.height = this.current.height = settings.frameheight = settings.frameheight || this.image.videoHeight;
+                // video specific parameter
+                this.animationpause = this.image.autoplay !== true;
+                if (this.animationpause) {
+                    this.image.pause();
+                }
+
+                // pause the video when losing focus
+                this._onBlurFn = () => { this.image.pause(); };
+                event.on(event.STATE_PAUSE, this._onBlurFn);
+
+                // call the onended when the video has ended
+                this.image.onended = () => {
+                    if (typeof this.onended === "function") {
+                        // prevent the video from restarting if video.loop is false
+                        if (!this.image.loop) {
+                            this.animationpause = true;
+                        }
+                        this.onended();
+                    }
+                };
+
+            } else {
+                // update the default "current" frame size
+                this.width = this.current.width = settings.framewidth = settings.framewidth || this.image.width;
+                this.height = this.current.height = settings.frameheight = settings.frameheight || this.image.height;
+                this.source = renderer.cache.get(this.image, settings);
+                this.textureAtlas = this.source.getAtlas();
+            }
         }
 
         // store/reset the current atlas information if specified
@@ -196,7 +239,7 @@ export default class Sprite extends Renderable {
         }
 
         // addAnimation will return 0 if no texture atlas is defined
-        if (this.addAnimation("default", null) !== 0) {
+        if (!this.isVideo && this.addAnimation("default", null) !== 0) {
             // set as default
             this.setCurrentAnimation("default");
         }
@@ -204,18 +247,28 @@ export default class Sprite extends Renderable {
 
     /**
      * return the flickering state of the object
-     * @name isFlickering
-     * @memberof Sprite
      * @returns {boolean}
      */
     isFlickering() {
         return this._flicker.isFlickering;
     }
 
+    /**
+     * play or resume the current animation or video
+     */
+    play() {
+        this.animationpause = false;
+    }
+
+    /**
+     * play or resume the current animation or video
+     */
+    pause() {
+        this.animationpause = true;
+    }
+
     /**
      * make the object flicker
-     * @name flicker
-     * @memberof Sprite
      * @param {number} duration - expressed in milliseconds
      * @param {Function} callback - Function to call when flickering ends
      * @returns {Sprite} Reference to this object for method chaining
@@ -244,11 +297,8 @@ export default class Sprite extends Renderable {
      * For fixed-sized cell sprite sheet, the index list must follow the
      * logic as per the following example :<br>
      * <img src="images/spritesheet_grid.png"/>
-     * @name addAnimation
-     * @memberof Sprite
      * @param {string} name - animation id
-     * @param {number[]|string[]|object[]} index - list of sprite index or name
-     * defining the animation. Can also use objects to specify delay for each frame, see below
+     * @param {number[]|string[]|object[]} index - list of sprite index or name defining the animation. Can also use objects to specify delay for each frame, see below
      * @param {number} [animationspeed] - cycling speed for animation in ms
      * @returns {number} frame amount of frame added to the animation (delay between each frame).
      * @see Sprite#animationspeed
@@ -343,8 +393,6 @@ export default class Sprite extends Renderable {
     /**
      * set the current animation
      * this will always change the animation & set the frame to zero
-     * @name setCurrentAnimation
-     * @memberof Sprite
      * @param {string} name - animation id
      * @param {string|Function} [resetAnim] - animation id to switch to when complete, or callback
      * @param {boolean} [preserve_dt=false] - if false will reset the elapsed time counter since last frame
@@ -405,8 +453,6 @@ export default class Sprite extends Renderable {
 
     /**
      * reverse the given or current animation if none is specified
-     * @name reverseAnimation
-     * @memberof Sprite
      * @param {string} [name] - animation id
      * @returns {Sprite} Reference to this object for method chaining
      * @see Sprite#animationspeed
@@ -423,8 +469,6 @@ export default class Sprite extends Renderable {
 
     /**
      * return true if the specified animation is the current one.
-     * @name isCurrentAnimation
-     * @memberof Sprite
      * @param {string} name - animation id
      * @returns {boolean}
      * @example
@@ -439,8 +483,6 @@ export default class Sprite extends Renderable {
     /**
      * change the current texture atlas region for this sprite
      * @see Texture.getRegion
-     * @name setRegion
-     * @memberof Sprite
      * @param {object} region - typically returned through me.Texture.getRegion()
      * @returns {Sprite} Reference to this object for method chaining
      * @example
@@ -472,8 +514,6 @@ export default class Sprite extends Renderable {
 
     /**
      * force the current animation frame index.
-     * @name setAnimationFrame
-     * @memberof Sprite
      * @param {number} [index=0] - animation frame index
      * @returns {Sprite} Reference to this object for method chaining
      * @example
@@ -487,8 +527,6 @@ export default class Sprite extends Renderable {
 
     /**
      * return the current animation frame index.
-     * @name getCurrentAnimationFrame
-     * @memberof Sprite
      * @returns {number} current animation frame index
      */
     getCurrentAnimationFrame() {
@@ -497,8 +535,6 @@ export default class Sprite extends Renderable {
 
     /**
      * Returns the frame object by the index.
-     * @name getAnimationFrameObjectByIndex
-     * @memberof Sprite
      * @ignore
      * @param {number} id - the frame id
      * @returns {number} if using number indices. Returns {object} containing frame data if using texture atlas
@@ -510,38 +546,51 @@ export default class Sprite extends Renderable {
     /**
      * update function. <br>
      * automatically called by the game manager {@link game}
-     * @name update
-     * @memberof Sprite
      * @protected
      * @param {number} dt - time since the last update in milliseconds.
      * @returns {boolean} true if the Sprite is dirty
      */
     update(dt) {
-        // Update animation if necessary
-        if (!this.animationpause && this.current.length > 1) {
-            let duration = this.getAnimationFrameObjectByIndex(this.current.idx).delay;
-            this.dt += dt;
-            while (this.dt >= duration) {
-                this.isDirty = true;
-                this.dt -= duration;
-
-                let nextFrame = (this.current.length > 1 ? this.current.idx + 1 : this.current.idx);
-                this.setAnimationFrame(nextFrame);
-
-                // Switch animation if we reach the end of the strip and a callback is defined
-                if (this.current.idx === 0 && typeof this.resetAnim === "function") {
-                    // Otherwise is must be callable
-                    if (this.resetAnim() === false) {
-                        // Reset to last frame
-                        this.setAnimationFrame(this.current.length - 1);
-
-                        // Bail early without skipping any more frames.
-                        this.dt %= duration;
-                        break;
+        // play/pause video if necessary
+        if (this.isVideo) {
+            if (this.animationpause) {
+                this.image.pause();
+            } else if (this.image.paused) {
+                this.image.play();
+            }
+            this.isDirty = !this.image.paused;
+        } else {
+            // Update animation if necessary
+            if (!this.animationpause && this.current.length > 1) {
+                let duration = this.getAnimationFrameObjectByIndex(this.current.idx).delay;
+                this.dt += dt;
+                while (this.dt >= duration) {
+                    this.isDirty = true;
+                    this.dt -= duration;
+
+                    let nextFrame = (this.current.length > 1 ? this.current.idx + 1 : this.current.idx);
+                    this.setAnimationFrame(nextFrame);
+
+                    // Switch animation if we reach the end of the strip and a callback is defined
+                    if (this.current.idx === 0) {
+                        if (typeof this.onended === "function") {
+                            this.onended();
+                        }
+                        if (typeof this.resetAnim === "function") {
+                            // Otherwise is must be callable
+                            if (this.resetAnim() === false) {
+                                // Reset to last frame
+                                this.setAnimationFrame(this.current.length - 1);
+
+                                // Bail early without skipping any more frames.
+                                this.dt %= duration;
+                                break;
+                            }
+                        }
                     }
+                    // Get next frame duration
+                    duration = this.getAnimationFrameObjectByIndex(this.current.idx).delay;
                 }
-                // Get next frame duration
-                duration = this.getAnimationFrameObjectByIndex(this.current.idx).delay;
             }
         }
 
@@ -560,20 +609,8 @@ export default class Sprite extends Renderable {
         return super.update(dt);
     }
 
-    /**
-     * Destroy function<br>
-     * @ignore
-     */
-    destroy() {
-        pool.push(this.offset);
-        this.offset = undefined;
-        super.destroy();
-    }
-
     /**
      * draw this srite (automatically called by melonJS)
-     * @name draw
-     * @memberof Sprite
      * @protected
      * @param {CanvasRenderer|WebGLRenderer} renderer - a renderer instance
      * @param {Camera2d} [viewport] - the viewport to (re)draw
@@ -620,4 +657,22 @@ export default class Sprite extends Renderable {
             w, h                         // dw,dh
         );
     }
+
+    /**
+     * Destroy function<br>
+     * @ignore
+     */
+    destroy() {
+        pool.push(this.offset);
+        this.offset = undefined;
+        if (this.isVideo) {
+            event.off(event.STATE_PAUSE, this._onBlurFn);
+            this._onBlurFn = undefined;
+            this.image.onended = undefined;
+            this.image.pause();
+            this.image.currentTime = 0;
+        }
+        this.image = undefined;
+        super.destroy();
+    }
 }

package/src/system/device.js

@@ -17,6 +17,9 @@ let swipeEnabled = true;
 // a cache DOMRect object
 let domRect = {left: 0, top: 0, x: 0, y: 0, width: 0, height: 0, right: 0, bottom: 0};
 
+// a list of supported videoCodecs;
+let videoCodecs;
+
 function disableSwipeFn(e) {
     e.preventDefault();
     if (typeof globalThis.scroll === "function") {
@@ -215,6 +218,18 @@ export const hasHTML5Audio = (typeof globalThis.Audio !== "undefined");
  */
 export const sound = hasWebAudio || hasHTML5Audio;
 
+
+/**
+ * Device Video Support
+ * @name hasVideo
+ * @memberof device
+ * @type {boolean}
+ * @readonly
+ * @public
+ */
+export const hasVideo = typeof globalThis.document !== "undefined" &&  !!globalThis.document.createElement("video").canPlayType;
+
+
 /**
  * Browser Local Storage capabilities <br>
  * (this flag will be set to false if cookies are blocked)
@@ -919,3 +934,31 @@ export function vibrate(pattern) {
         globalThis.navigator.vibrate(pattern);
     }
 }
+
+/**
+ * detect if the given video format is supported
+ * @function hasVideoFormat
+ * @param {"h264"|"h265"|"ogg"|"mp4"|"m4v"|"webm"|"vp9"|"hls"} codec - the video format to check for support
+ * @returns {boolean} return true if the given video format is supported
+ */
+export function hasVideoFormat(codec) {
+    let result = false;
+    if (hasVideo === true) {
+        if (typeof videoCodecs === "undefined") {
+            // check for support
+            const videoElement = document.createElement("video");
+            videoCodecs = {
+                h264:videoElement.canPlayType('video/mp4; codecs="avc1.42E01E"').replace(/^no$/, ""),
+                h265:videoElement.canPlayType('video/mp4; codecs="hev1"').replace(/^no$/, ""),
+                ogg:videoElement.canPlayType('video/ogg; codecs="theora"').replace(/^no$/, ""),
+                mp4:videoElement.canPlayType('video/mp4; codecs="avc1.42E01E"').replace(/^no$/, ""),
+                m4v:videoElement.canPlayType("video/x-m4v").replace(/^no$/, ""),
+                webm:videoElement.canPlayType('video/webm; codecs="vp8, vorbis"').replace(/^no$/, ""),
+                vp9:videoElement.canPlayType('video/webm; codecs="vp9"').replace(/^no$/, ""),
+                hls:videoElement.canPlayType('application/x-mpegURL; codecs="avc1.42E01E"').replace(/^no$/, "")
+            };
+        }
+        result = !!videoCodecs[codec];
+    }
+    return result;
+}

package/src/video/renderer.js

@@ -409,19 +409,18 @@ export default class Renderer {
 
     /**
      * 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.
+     * @param {string} [type="image/png"] - A string indicating the image format
+     * @param {number} [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.
      * @returns {Promise} A Promise returning a Blob object representing the last rendered frame
      * @example
      * renderer.convertToBlob().then((blob) => console.log(blob));
      */
-    toBlob(options) {
+    toBlob(type = "image/png", quality) {
         return new Promise((resolve) => {
             event.once(event.GAME_AFTER_DRAW, () => {
                 this.canvas.toBlob((blob) => {
                     resolve(blob);
-                }, options ? options.type : undefined, options ? options.quality : undefined);
+                }, type, quality);
             });
         });
     }
@@ -429,18 +428,17 @@ export default class Renderer {
     /**
      * 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.
+     * @param {string} [type="image/png"] - A string indicating the image format
+     * @param {number} [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.
      * @returns {Promise} A Promise returning an ImageBitmap.
      * @example
      * renderer.transferToImageBitmap().then((image) => console.log(image));
      */
-    toImageBitmap(options) {
+    toImageBitmap(type = "image/png", quality) {
         return new Promise((resolve) => {
             event.once(event.GAME_AFTER_DRAW, () => {
                 let image = new Image();
-                image.src = this.canvas.toDataURL(options);
+                image.src = this.canvas.toDataURL(type, quality);
                 image.onload = () => {
                     createImageBitmap(image).then((bitmap) => resolve(bitmap));
                 };
@@ -450,17 +448,16 @@ export default class Renderer {
 
     /**
      * 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.
+     * @param {string} [type="image/png"] - A string indicating the image format
+     * @param {number} [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.
      * @returns {Promise} A Promise returning a string containing the requested data URL.
      * @example
      * renderer.toDataURL().then((dataURL) => console.log(dataURL));
      */
-    toDataURL(options) {
+    toDataURL(type = "image/png", quality) {
         return new Promise((resolve) => {
             event.once(event.GAME_AFTER_DRAW, () => {
-                resolve(this.canvas.toDataURL(options));
+                resolve(this.canvas.toDataURL(type, quality));
             });
         });
     }

package/src/video/texture/atlas.js

@@ -174,13 +174,25 @@ export class TextureAtlas {
             if (frame.hasOwnProperty("filename")) {
                 // Source coordinates
                 let s = frame.frame;
+                let trimmed = !!frame.trimmed;
+
+                let trim;
+
+                if (trimmed) {
+                    trim = {
+                        x : frame.spriteSourceSize.x,
+                        y : frame.spriteSourceSize.y,
+                        w : frame.spriteSourceSize.w,
+                        h : frame.spriteSourceSize.h
+                    };
+                }
 
                 let originX, originY;
                 // Pixel-based offset origin from the top-left of the source frame
-                let hasTextureAnchorPoint = (frame.spriteSourceSize && frame.sourceSize && frame.pivot);
+                let hasTextureAnchorPoint = (frame.sourceSize && frame.pivot);
                 if (hasTextureAnchorPoint) {
-                    originX = (frame.sourceSize.w * frame.pivot.x) - ((frame.trimmed) ? frame.spriteSourceSize.x : 0);
-                    originY = (frame.sourceSize.h * frame.pivot.y) - ((frame.trimmed) ? frame.spriteSourceSize.y : 0);
+                    originX = (frame.sourceSize.w * frame.pivot.x) - ((trimmed) ? trim.x : 0);
+                    originY = (frame.sourceSize.h * frame.pivot.y) - ((trimmed) ? trim.y : 0);
                 }
 
                 atlas[frame.filename] = {
@@ -188,7 +200,8 @@ export class TextureAtlas {
                     texture      : data.meta.image || "default", // the source texture
                     offset       : new Vector2d(s.x, s.y),
                     anchorPoint  : (hasTextureAnchorPoint) ? new Vector2d(originX / s.w, originY / s.h) : null,
-                    trimmed      : !!frame.trimmed,
+                    trimmed      : trimmed,
+                    trim         : trim,
                     width        : s.w,
                     height       : s.h,
                     angle        : (frame.rotated === true) ? -ETA : 0
@@ -241,17 +254,18 @@ export class TextureAtlas {
         for (let frame = 0, count = spritecount.x * spritecount.y; frame < count; frame++) {
             let name = "" + frame;
             atlas[name] = {
-                name        : name,
-                texture     : "default", // the source texture
-                offset      : new Vector2d(
+                name            : name,
+                texture         : "default", // the source texture
+                offset          : new Vector2d(
                     margin + (spacing + data.framewidth) * (frame % spritecount.x),
                     margin + (spacing + data.frameheight) * ~~(frame / spritecount.x)
                 ),
-                anchorPoint : (data.anchorPoint || null),
-                trimmed     : false,
-                width       : data.framewidth,
-                height      : data.frameheight,
-                angle       : 0
+                anchorPoint     : (data.anchorPoint || null),
+                trimmed         : false,
+                trim            : undefined,
+                width           : data.framewidth,
+                height          : data.frameheight,
+                angle           : 0
             };
             this.addUVs(atlas, name, width, height);
         }

package/src/video/texture/cache.js

@@ -88,7 +88,7 @@ class TextureCache {
 
         if (typeof entry === "undefined") {
             if (!atlas) {
-                atlas = createAtlas(image.width, image.height, image.src ? fileUtil.getBasename(image.src) : undefined);
+                atlas = createAtlas(image.width || image.videoWidth, image.videoHeight, image.src ? fileUtil.getBasename(image.src) : undefined);
             }
             entry = new TextureAtlas(atlas, image, false);
             this.set(image, entry);
@@ -132,8 +132,8 @@ class TextureCache {
      * @ignore
      */
     set(image, texture) {
-        let width = image.width;
-        let height = image.height;
+        let width = image.width || image.videoWidth;
+        let height = image.height || image.videoHeight;
 
         // warn if a non POT texture is added to the cache when using WebGL1
         if (renderer.WebGLVersion === 1 && (!isPowerOfTwo(width) || !isPowerOfTwo(height))) {