melonjs 10.2.0 → 10.3.0

package/src/system/device.js

@@ -8,7 +8,7 @@ import * as event from "./../system/event.js";
 /**
  * The device capabilities and specific events
  * @namespace me.device
- * @memberOf me
+ * @memberof me
  */
 
 // private properties
@@ -17,6 +17,10 @@ let deviceOrientationInitialized = false;
 
 // swipe utility fn & flag
 let swipeEnabled = true;
+
+/**
+ * @ignore
+ */
 function _disableSwipeFn(e) {
     e.preventDefault();
     if (typeof window.scroll === "function") {
@@ -28,7 +32,10 @@ function _disableSwipeFn(e) {
 // DOM loading stuff
 let readyBound = false, isReady = false, readyList = [];
 
-// called to check if the device is ready
+/**
+ * // called to check if the device is ready
+ * @ignore
+ */
 function _domReady() {
     // Make sure that the DOM is not already loaded
     if (!isReady) {
@@ -61,8 +68,10 @@ function _domReady() {
 // a cache DOMRect object
 let _domRect = {left: 0, top: 0, x: 0, y: 0, width: 0, height: 0, right: 0, bottom: 0};
 
-
-// detect the device type
+/**
+ * detect the device type
+ * @ignore
+ */
 function _detectDevice() {
     // iOS Device ?
     device.iOS = /iPhone|iPad|iPod/i.test(device.ua);
@@ -92,7 +101,10 @@ function _detectDevice() {
     device.isWeixin = /MicroMessenger/i.test(device.ua);
 };
 
-// check the device capapbilities
+/**
+ * check the device capapbilities
+ * @ignore
+ */
 function _checkCapabilities() {
 
     // detect device type/platform
@@ -119,12 +131,8 @@ function _checkCapabilities() {
     // Modern browsers support "wheel", Webkit and IE support at least "mousewheel
     device.wheel = ("onwheel" in document.createElement("div"));
 
-    // pointerlock detection
-    device.hasPointerLockSupport = prefixed("pointerLockElement", document);
-
-    if (device.hasPointerLockSupport) {
-        document.exitPointerLock = prefixed("exitPointerLock", document);
-    }
+    // pointerlock detection (pointerLockElement can be null when the feature is supported)
+    device.hasPointerLockSupport = typeof document.pointerLockElement !== "undefined";
 
     // device orientation and motion detection
     device.hasDeviceOrientation = !!window.DeviceOrientationEvent;
@@ -242,93 +250,93 @@ let device = {
 
     /**
      * the `ua` read-only property returns the user agent string for the current browser.
-     * @type String
+     * @type {string}
      * @readonly
      * @name ua
-     * @memberOf me.device
+     * @memberof me.device
      */
     ua : navigator.userAgent,
 
     /**
      * Browser Local Storage capabilities <br>
      * (this flag will be set to false if cookies are blocked)
-     * @type Boolean
+     * @type {boolean}
      * @readonly
      * @name localStorage
-     * @memberOf me.device
+     * @memberof me.device
      */
     localStorage : false,
 
     /**
      * Browser accelerometer capabilities
-     * @type Boolean
+     * @type {boolean}
      * @readonly
      * @name hasAccelerometer
-     * @memberOf me.device
+     * @memberof me.device
      */
     hasAccelerometer : false,
 
     /**
      * Browser device orientation
-     * @type Boolean
+     * @type {boolean}
      * @readonly
      * @name hasDeviceOrientation
-     * @memberOf me.device
+     * @memberof me.device
      */
     hasDeviceOrientation : false,
 
     /**
      * Supports the ScreenOrientation API
      * @see https://developer.mozilla.org/en-US/docs/Web/API/ScreenOrientation/onchange
-     * @type Boolean
+     * @type {boolean}
      * @readonly
      * @name ScreenOrientation
-     * @memberOf me.device
+     * @memberof me.device
      */
     ScreenOrientation : false,
 
     /**
      * Browser full screen support
-     * @type Boolean
+     * @type {boolean}
      * @readonly
      * @name hasFullscreenSupport
-     * @memberOf me.device
+     * @memberof me.device
      */
     hasFullscreenSupport : false,
 
-     /**
+    /**
      * Browser pointerlock api support
-     * @type Boolean
+     * @type {boolean}
      * @readonly
      * @name hasPointerLockSupport
-     * @memberOf me.device
+     * @memberof me.device
      */
     hasPointerLockSupport : false,
 
     /**
-    * Device WebAudio Support
-    * @type Boolean
-    * @readonly
-    * @name hasWebAudio
-    * @memberOf me.device
-    */
-   hasWebAudio : false,
+     * Device WebAudio Support
+     * @type {boolean}
+     * @readonly
+     * @name hasWebAudio
+     * @memberof me.device
+     */
+    hasWebAudio : false,
 
     /**
      * Browser Base64 decoding capability
-     * @type Boolean
+     * @type {boolean}
      * @readonly
      * @name nativeBase64
-     * @memberOf me.device
+     * @memberof me.device
      */
     nativeBase64 : (typeof(window.atob) === "function"),
 
     /**
      * Return the maximum number of simultaneous touch contact points are supported by the current device.
-     * @type Number
+     * @type {number}
      * @readonly
      * @name maxTouchPoints
-     * @memberOf me.device
+     * @memberof me.device
      * @example
      * if (me.device.maxTouchPoints > 1) {
      *     // device supports multi-touch
@@ -338,175 +346,175 @@ let device = {
 
     /**
      * Touch capabilities
-     * @type Boolean
+     * @type {boolean}
      * @readonly
      * @name touch
-     * @memberOf me.device
+     * @memberof me.device
      */
     touch : false,
 
     /**
      * W3C standard wheel events
-     * @type Boolean
+     * @type {boolean}
      * @readonly
      * @name wheel
-     * @memberOf me.device
+     * @memberof me.device
      */
     wheel : false,
 
     /**
      * equals to true if a mobile device <br>
      * (Android | iPhone | iPad | iPod | BlackBerry | Windows Phone | Kindle)
-     * @type Boolean
+     * @type {boolean}
      * @readonly
      * @name isMobile
-     * @memberOf me.device
+     * @memberof me.device
      */
     isMobile : false,
 
     /**
      * equals to true if the device is an iOS platform.
-     * @type Boolean
+     * @type {boolean}
      * @readonly
      * @name iOS
-     * @memberOf me.device
+     * @memberof me.device
      */
     iOS : false,
 
     /**
      * equals to true if the device is an Android platform.
-     * @type Boolean
+     * @type {boolean}
      * @readonly
      * @name android
-     * @memberOf me.device
+     * @memberof me.device
      */
     android : false,
 
     /**
      * equals to true if the device is an Android 2.x platform.
-     * @type Boolean
+     * @type {boolean}
      * @readonly
      * @name android2
-     * @memberOf me.device
+     * @memberof me.device
      */
     android2 : false,
 
     /**
      * equals to true if the device is a Linux platform.
-     * @type Boolean
+     * @type {boolean}
      * @readonly
      * @name linux
-     * @memberOf me.device
+     * @memberof me.device
      */
     linux : false,
 
    /**
     * equals to true if the game is running under Ejecta.
-    * @type Boolean
+    * @type {boolean}
     * @readonly
     * @see http://impactjs.com/ejecta
     * @name ejecta
-    * @memberOf me.device
+    * @memberof me.device
     */
     ejecta : false,
 
     /**
      * equals to true if the game is running under Wechat.
-     * @type Boolean
+     * @type {boolean}
      * @readonly
      * @name isWeixin
-     * @memberOf me.device
+     * @memberof me.device
      */
      isWeixin : false,
 
     /**
      * equals to true if the device is running on ChromeOS.
-     * @type Boolean
+     * @type {boolean}
      * @readonly
      * @name chromeOS
-     * @memberOf me.device
+     * @memberof me.device
      */
     chromeOS : false,
 
-     /**
+    /**
      * equals to true if the device is a Windows Phone platform.
-     * @type Boolean
+     * @type {boolean}
      * @readonly
      * @name wp
-     * @memberOf me.device
+     * @memberof me.device
      */
     wp : false,
 
     /**
      * equals to true if the device is a BlackBerry platform.
-     * @type Boolean
+     * @type {boolean}
      * @readonly
      * @name BlackBerry
-     * @memberOf me.device
+     * @memberof me.device
      */
     BlackBerry : false,
 
     /**
      * equals to true if the device is a Kindle platform.
-     * @type Boolean
+     * @type {boolean}
      * @readonly
      * @name Kindle
-     * @memberOf me.device
+     * @memberof me.device
      */
     Kindle : false,
 
     /**
      * contains the g-force acceleration along the x-axis.
      * @public
-     * @type Number
+     * @type {number}
      * @readonly
      * @name accelerationX
      * @see me.device.watchAccelerometer
-     * @memberOf me.device
+     * @memberof me.device
      */
     accelerationX : 0,
 
     /**
      * contains the g-force acceleration along the y-axis.
      * @public
-     * @type Number
+     * @type {number}
      * @readonly
      * @name accelerationY
      * @see me.device.watchAccelerometer
-     * @memberOf me.device
+     * @memberof me.device
      */
     accelerationY : 0,
 
     /**
      * contains the g-force acceleration along the z-axis.
      * @public
-     * @type Number
+     * @type {number}
      * @readonly
      * @name accelerationZ
      * @see me.device.watchAccelerometer
-     * @memberOf me.device
+     * @memberof me.device
      */
     accelerationZ : 0,
 
     /**
      * Device orientation Gamma property. Gives angle on tilting a portrait held phone left or right
      * @public
-     * @type Number
+     * @type {number}
      * @readonly
      * @name gamma
      * @see me.device.watchDeviceOrientation
-     * @memberOf me.device
+     * @memberof me.device
      */
     gamma : 0,
 
     /**
      * Device orientation Beta property. Gives angle on tilting a portrait held phone forward or backward
      * @public
-     * @type Number
+     * @type {number}
      * @readonly
      * @name beta
      * @see me.device.watchDeviceOrientation
-     * @memberOf me.device
+     * @memberof me.device
      */
     beta: 0,
 
@@ -514,11 +522,11 @@ let device = {
      * Device orientation Alpha property. Gives angle based on the rotation of the phone around its z axis.
      * The z-axis is perpendicular to the phone, facing out from the center of the screen.
      * @public
-     * @type Number
+     * @type {number}
      * @readonly
      * @name alpha
      * @see me.device.watchDeviceOrientation
-     * @memberOf me.device
+     * @memberof me.device
      */
     alpha : 0,
 
@@ -526,53 +534,53 @@ let device = {
      * a string representing the preferred language of the user, usually the language of the browser UI.
      * (will default to "en" if the information is not available)
      * @public
-     * @type String
+     * @type {string}
      * @readonly
      * @see http://www.w3schools.com/tags/ref_language_codes.asp
      * @name language
-     * @memberOf me.device
+     * @memberof me.device
      */
     language : navigator.language || navigator.browserLanguage || navigator.userLanguage || "en",
 
     /**
      * Specify whether to pause the game when losing focus
-     * @type {Boolean}
+     * @type {boolean}
      * @default true
-     * @memberOf me.device
+     * @memberof me.device
      */
     pauseOnBlur : true,
 
     /**
      * Specify whether to unpause the game when gaining focus
-     * @type {Boolean}
+     * @type {boolean}
      * @default true
-     * @memberOf me.device
+     * @memberof me.device
      */
     resumeOnFocus : true,
 
     /**
      * Specify whether to automatically bring the window to the front
-     * @type {Boolean}
+     * @type {boolean}
      * @default true
-     * @memberOf me.device
+     * @memberof me.device
      */
     autoFocus : true,
 
     /**
      * Specify whether to stop the game when losing focus or not.
      * The engine restarts on focus if this is enabled.
-     * @type {Boolean}
+     * @type {boolean}
      * @default false
-     * @memberOf me.device
+     * @memberof me.device
      */
     stopOnBlur : false,
 
     /**
      * equals to true if the device browser supports OffScreenCanvas.
-     * @type Boolean
+     * @type {boolean}
      * @readonly
      * @name OffScreenCanvas
-     * @memberOf me.device
+     * @memberof me.device
      */
     OffscreenCanvas : false,
 
@@ -653,7 +661,7 @@ let device = {
     /**
      * enable/disable swipe on WebView.
      * @function me.device.enableSwipe
-     * @param {Boolean} [enable=true] enable or disable swipe.
+     * @param {boolean} [enable=true] enable or disable swipe.
      */
     enableSwipe(enable) {
         if (enable !== false) {
@@ -670,7 +678,7 @@ let device = {
     /**
      * Triggers a fullscreen request. Requires fullscreen support from the browser/device.
      * @function me.device.requestFullscreen
-     * @param {Object} [element=default canvas object] the element to be set in full-screen mode.
+     * @param {object} [element=default canvas object] the element to be set in full-screen mode.
      * @example
      * // add a keyboard shortcut to toggle Fullscreen mode on/off
      * me.input.bindKey(me.input.KEY.F, "toggleFullscreen");
@@ -710,7 +718,7 @@ let device = {
      * It can be "any", "natural", "landscape", "portrait", "portrait-primary", "portrait-secondary", "landscape-primary", "landscape-secondary"
      * @function me.device.getScreenOrientation
      * @see https://developer.mozilla.org/en-US/docs/Web/API/Screen/orientation
-     * @return {String} the screen orientation
+     * @returns {string} the screen orientation
      */
     getScreenOrientation() {
         var PORTRAIT = "portrait";
@@ -744,14 +752,15 @@ let device = {
      * This method only works for installed Web apps or for Web pages in full-screen mode.
      * @function me.device.lockOrientation
      * @see https://developer.mozilla.org/en-US/docs/Web/API/Screen/lockOrientation
-     * @return {Boolean} true if the orientation was unsuccessfully locked
+     * @param {string|string[]} orientation The orientation into which to lock the screen.
+     * @returns {boolean} true if the orientation was unsuccessfully locked
      */
     lockOrientation(orientation) {
         var screen = window.screen;
         if (typeof screen !== "undefined") {
-            var lockOrientation = prefixed("lockOrientation", screen);
-            if (typeof lockOrientation !== "undefined") {
-                return lockOrientation(orientation);
+            var _lockOrientation = prefixed("lockOrientation", screen);
+            if (typeof _lockOrientation !== "undefined") {
+                return _lockOrientation(orientation);
             }
         }
         return false;
@@ -762,14 +771,14 @@ let device = {
      * This method only works for installed Web apps or for Web pages in full-screen mode.
      * @function me.device.unlockOrientation
      * @see https://developer.mozilla.org/en-US/docs/Web/API/Screen/lockOrientation
-     * @return {Boolean} true if the orientation was unsuccessfully unlocked
+     * @returns {boolean} true if the orientation was unsuccessfully unlocked
      */
-    unlockOrientation(orientation) {
+    unlockOrientation() {
         var screen = window.screen;
         if (typeof screen !== "undefined") {
-            var unlockOrientation = prefixed("unlockOrientation", screen);
-            if (typeof unlockOrientation !== "undefined") {
-                return unlockOrientation(orientation);
+            var _unlockOrientation = prefixed("unlockOrientation", screen);
+            if (typeof _unlockOrientation !== "undefined") {
+                return _unlockOrientation();
             }
         }
         return false;
@@ -778,7 +787,7 @@ let device = {
     /**
      * return true if the device screen orientation is in Portrait mode
      * @function me.device.isPortrait
-     * @return {Boolean}
+     * @returns {boolean}
      */
     isPortrait() {
         return this.getScreenOrientation().includes("portrait");
@@ -787,7 +796,7 @@ let device = {
     /**
      * return true if the device screen orientation is in Portrait mode
      * @function me.device.isLandscape
-     * @return {Boolean}
+     * @returns {boolean}
      */
     isLandscape() {
         return this.getScreenOrientation().includes("landscape");
@@ -797,8 +806,8 @@ let device = {
      * return the device storage
      * @function me.device.getStorage
      * @see me.save
-     * @param {String} [type="local"]
-     * @return {Object} a reference to the device storage
+     * @param {string} [type="local"]
+     * @returns {object} a reference to the device storage
      */
     getStorage(type = "local") {
         switch (type) {
@@ -813,8 +822,8 @@ let device = {
     /**
      * return the parent DOM element for the given parent name or HTMLElement object
      * @function me.device.getParentElement
-     * @param {String|HTMLElement} element the parent element name or a HTMLElement object
-     * @return {HTMLElement} the parent Element
+     * @param {string|HTMLElement} element the parent element name or a HTMLElement object
+     * @returns {HTMLElement} the parent Element
      */
     getParentElement(element) {
         var target = this.getElement(element);
@@ -829,8 +838,8 @@ let device = {
     /**
      * return the DOM element for the given element name or HTMLElement object
      * @function me.device.getElement
-     * @param {String|HTMLElement} element the parent element name or a HTMLElement object
-     * @return {HTMLElement} the corresponding DOM Element or null if not existing
+     * @param {string|HTMLElement} element the parent element name or a HTMLElement object
+     * @returns {HTMLElement} the corresponding DOM Element or null if not existing
      */
     getElement(element) {
         var target = null;
@@ -857,8 +866,8 @@ let device = {
      * <br><img src="images/element-box-diagram.png"/>
      * @see https://developer.mozilla.org/en-US/docs/Web/API/DOMRect
      * @function me.device.getElementBounds
-     * @param {String|HTMLElement} element an HTMLElement object
-     * @return {DOMRect} the size and position of the element relatively to the viewport
+     * @param {string|HTMLElement} element an HTMLElement object
+     * @returns {DOMRect} the size and position of the element relatively to the viewport
      */
     getElementBounds(element) {
         if (typeof element === "object" && element !== document.body && typeof element.getBoundingClientRect !== "undefined") {
@@ -875,8 +884,8 @@ let device = {
      * <br><img src="images/element-box-diagram.png"/>
      * @see https://developer.mozilla.org/en-US/docs/Web/API/DOMRect
      * @function me.device.getParentBounds
-     * @param {String|HTMLElement} element an HTMLElement object
-     * @return {DOMRect} the size and position of the given element parent relative to the viewport
+     * @param {string|HTMLElement} element an HTMLElement object
+     * @returns {DOMRect} the size and position of the given element parent relative to the viewport
      */
     getParentBounds(element) {
         return this.getElementBounds(this.getParentElement(element));
@@ -885,9 +894,9 @@ let device = {
     /**
      * returns true if the device supports WebGL
      * @function me.device.isWebGLSupported
-     * @param {Object} [options] context creation options
-     * @param {Boolean} [options.failIfMajorPerformanceCaveat=true] If true, the renderer will switch to CANVAS mode if the performances of a WebGL context would be dramatically lower than that of a native application making equivalent OpenGL calls.
-     * @return {Boolean} true if WebGL is supported
+     * @param {object} [options] context creation options
+     * @param {boolean} [options.failIfMajorPerformanceCaveat=true] If true, the renderer will switch to CANVAS mode if the performances of a WebGL context would be dramatically lower than that of a native application making equivalent OpenGL calls.
+     * @returns {boolean} true if WebGL is supported
      */
     isWebGLSupported(options) {
         var _supported = false;
@@ -909,7 +918,7 @@ let device = {
      * return the highest precision format supported by this device for GL Shaders
      * @function me.device.getMaxShaderPrecision
      * @param {WebGLRenderingContext} gl
-     * @return {Boolean} "lowp", "mediump", or "highp"
+     * @returns {boolean} "lowp", "mediump", or "highp"
      */
     getMaxShaderPrecision(gl) {
         if (gl.getShaderPrecisionFormat(gl.VERTEX_SHADER, gl.HIGH_FLOAT ).precision > 0 &&
@@ -961,58 +970,6 @@ let device = {
         this.alpha = e.alpha;
     },
 
-    /**
-     * Enters pointer lock, requesting it from the user first. Works on supported devices & browsers
-     * Must be called in a click event or an event that requires user interaction.
-     * If you need to run handle events for errors or change of the pointer lock, see below.
-     * @function me.device.turnOnPointerLock
-     * @example
-     * document.addEventListener("pointerlockchange", pointerlockchange, false);
-     * document.addEventListener("mozpointerlockchange", pointerlockchange, false);
-     * document.addEventListener("webkitpointerlockchange", pointerlockchange, false);
-     *
-     * document.addEventListener("pointerlockerror", pointerlockerror, false);
-     * document.addEventListener("mozpointerlockerror", pointerlockerror, false);
-     * document.addEventListener("webkitpointerlockerror", pointerlockerror, false);
-     */
-    turnOnPointerLock() {
-        if (this.hasPointerLockSupport) {
-            var element = getParent();
-            if (this.ua.match(/Firefox/i)) {
-                var fullscreenchange = function() {
-                    if ((prefixed("fullscreenElement", document) ||
-                        document.mozFullScreenElement) === element) {
-
-                        document.removeEventListener("fullscreenchange", fullscreenchange);
-                        document.removeEventListener("mozfullscreenchange", fullscreenchange);
-                        element.requestPointerLock = prefixed("requestPointerLock", element);
-                        element.requestPointerLock();
-                    }
-                };
-
-                document.addEventListener("fullscreenchange", fullscreenchange, false);
-                document.addEventListener("mozfullscreenchange", fullscreenchange, false);
-
-                this.requestFullscreen();
-
-            }
-            else {
-                element.requestPointerLock();
-            }
-        }
-    },
-
-    /**
-     * Exits pointer lock. Works on supported devices & browsers
-     * @function me.device.turnOffPointerLock
-     * @function
-     */
-    turnOffPointerLock() {
-        if (this.hasPointerLockSupport) {
-            document.exitPointerLock();
-        }
-    },
-
     /**
      * Enable monitor of the device accelerator to detect the amount of physical force of acceleration the device is receiving.
      * (one some device a first user gesture will be required before calling this function)
@@ -1020,7 +977,7 @@ let device = {
      * @see me.device.accelerationX
      * @see me.device.accelerationY
      * @see me.device.accelerationZ
-     * @return {Boolean} false if not supported or permission not granted by the user
+     * @returns {boolean} false if not supported or permission not granted by the user
      * @example
      * // try to enable device accelerometer event on user gesture
      * me.input.registerPointerEvent("pointerleave", me.game.viewport, function() {
@@ -1071,7 +1028,7 @@ let device = {
      * @see me.device.alpha
      * @see me.device.beta
      * @see me.device.gamma
-     * @return {Boolean} false if not supported or permission not granted by the user
+     * @returns {boolean} false if not supported or permission not granted by the user
      * @example
      * // try to enable device orientation event on user gesture
      * me.input.registerPointerEvent("pointerleave", me.game.viewport, function() {
@@ -1118,7 +1075,7 @@ let device = {
      * If a vibration pattern is already in progress when this method is called,
      * the previous pattern is halted and the new one begins instead.
      * @function me.device.vibrate
-     * @param {Number|Number[]} pattern pattern of vibration and pause intervals
+     * @param {number|number[]} pattern pattern of vibration and pause intervals
      * @example
      * // vibrate for 1000 ms
      * me.device.vibrate(1000);
@@ -1140,11 +1097,11 @@ let device = {
 /**
  * Ratio of the resolution in physical pixels to the resolution in CSS pixels for the current display device.
  * @name devicePixelRatio
- * @memberOf me.device
+ * @memberof me.device
  * @public
- * @type {Number}
+ * @type {number}
  * @readonly
- * @return {Number}
+ * @returns {number}
  */
 Object.defineProperty(device, "devicePixelRatio", {
     /**
@@ -1158,11 +1115,11 @@ Object.defineProperty(device, "devicePixelRatio", {
 /**
  * Returns true if the browser/device is in full screen mode.
  * @name isFullscreen
- * @memberOf me.device
+ * @memberof me.device
  * @public
- * @type {Boolean}
+ * @type {boolean}
  * @readonly
- * @return {Boolean}
+ * @returns {boolean}
  */
 Object.defineProperty(device, "isFullscreen", {
     /**
@@ -1181,11 +1138,11 @@ Object.defineProperty(device, "isFullscreen", {
 /**
  * Returns true if the browser/device has audio capabilities.
  * @name sound
- * @memberOf me.device
+ * @memberof me.device
  * @public
- * @type {Boolean}
+ * @type {boolean}
  * @readonly
- * @return {Boolean}
+ * @returns {boolean}
  */
 Object.defineProperty(device, "sound", {
     /**