melonjs 10.1.0 → 10.2.2

package/src/video/texture.js

@@ -8,62 +8,61 @@ import loader from "./../loader/loader.js";
 import { ETA } from "./../math/math.js";
 
 /**
-  * @classdesc
-  * A Texture atlas object, currently supports : <br>
-  * - [TexturePacker]{@link http://www.codeandweb.com/texturepacker/} : through JSON export (standard and multipack texture atlas) <br>
-  * - [ShoeBox]{@link http://renderhjs.net/shoebox/} : through JSON export using the
-  * melonJS setting [file]{@link https://github.com/melonjs/melonJS/raw/master/media/shoebox_JSON_export.sbx} <br>
-  * - [Free Texture Packer]{@link http://free-tex-packer.com/app/} : through JSON export (standard and multipack texture atlas) <br>
-  * - Standard (fixed cell size) spritesheet : through a {framewidth:xx, frameheight:xx, anchorPoint:me.Vector2d} object
-  * @class Texture
-  * @memberOf me.Renderer
-  * @constructor
-  * @param {Object|Object[]} atlas atlas information. See {@link me.loader.getJSON}
-  * @param {HTMLImageElement|HTMLCanvasElement|String|HTMLImageElement[]|HTMLCanvasElement[]|String[]} [source=atlas.meta.image] Image source
-  * @param {Boolean} [cached=false] Use true to skip caching this Texture
-  * @example
-  * // create a texture atlas from a JSON Object
-  * game.texture = new me.video.renderer.Texture(
-  *     me.loader.getJSON("texture")
-  * );
-  *
-  * // create a texture atlas from a multipack JSON Object
-  * game.texture = new me.video.renderer.Texture([
-  *     me.loader.getJSON("texture-0"),
-  *     me.loader.getJSON("texture-1"),
-  *     me.loader.getJSON("texture-2")
-  * ]);
-  *
-  * // create a texture atlas for a spritesheet with an anchorPoint in the center of each frame
-  * game.texture = new me.video.renderer.Texture(
-  *     {
-  *         framewidth : 32,
-  *         frameheight : 32,
-  *         anchorPoint : new me.Vector2d(0.5, 0.5)
-  *     },
-  *     me.loader.getImage("spritesheet")
-  * );
-  */
-
-  /**
-   * create a simple 1 frame texture atlas based on the given parameters
-   * @ignore
-   */
+ * create a simple 1 frame texture atlas based on the given parameters
+ * @ignore
+ */
 export function createAtlas(width, height, name = "default", repeat = "no-repeat") {
-    return {
-        "meta" : {
-            "app" : "melonJS",
-            "size" : { "w" : width, "h" : height },
-            "repeat" : repeat,
-            "image" : "default"
-        },
-        "frames" : [{
-            "filename" : name,
-            "frame" : { "x" : 0, "y" : 0, "w" : width, "h" : height }
-        }]
-    };
+   return {
+       "meta" : {
+           "app" : "melonJS",
+           "size" : { "w" : width, "h" : height },
+           "repeat" : repeat,
+           "image" : "default"
+       },
+       "frames" : [{
+           "filename" : name,
+           "frame" : { "x" : 0, "y" : 0, "w" : width, "h" : height }
+       }]
+   };
 }
 
+/**
+ * @classdesc
+ * A Texture atlas object, currently supports : <br>
+ * - [TexturePacker]{@link http://www.codeandweb.com/texturepacker/} : through JSON export (standard and multipack texture atlas) <br>
+ * - [ShoeBox]{@link http://renderhjs.net/shoebox/} : through JSON export using the
+ * melonJS setting [file]{@link https://github.com/melonjs/melonJS/raw/master/media/shoebox_JSON_export.sbx} <br>
+ * - [Free Texture Packer]{@link http://free-tex-packer.com/app/} : through JSON export (standard and multipack texture atlas) <br>
+ * - Standard (fixed cell size) spritesheet : through a {framewidth:xx, frameheight:xx, anchorPoint:me.Vector2d} object
+ * @class Texture
+ * @memberOf me.Renderer
+ * @constructor
+ * @param {object|object[]} atlases atlas information. See {@link me.loader.getJSON}
+ * @param {HTMLImageElement|HTMLCanvasElement|string|HTMLImageElement[]|HTMLCanvasElement[]|string[]} [src=atlas.meta.image] Image source
+ * @param {boolean} [cache=false] Use true to skip caching this Texture
+ * @example
+ * // create a texture atlas from a JSON Object
+ * game.texture = new me.video.renderer.Texture(
+ *     me.loader.getJSON("texture")
+ * );
+ *
+ * // create a texture atlas from a multipack JSON Object
+ * game.texture = new me.video.renderer.Texture([
+ *     me.loader.getJSON("texture-0"),
+ *     me.loader.getJSON("texture-1"),
+ *     me.loader.getJSON("texture-2")
+ * ]);
+ *
+ * // create a texture atlas for a spritesheet with an anchorPoint in the center of each frame
+ * game.texture = new me.video.renderer.Texture(
+ *     {
+ *         framewidth : 32,
+ *         frameheight : 32,
+ *         anchorPoint : new me.Vector2d(0.5, 0.5)
+ *     },
+ *     me.loader.getImage("spritesheet")
+ * );
+ */
 export class Texture {
 
     constructor (atlases, src, cache) {
@@ -75,14 +74,14 @@ export class Texture {
 
         /**
          * the texture source(s) itself
-         * @type Map
+         * @type {Map}
          * @ignore
          */
         this.sources = new Map();
 
         /**
          * the atlas dictionnaries
-         * @type Map
+         * @type {Map}
          * @ignore
          */
         this.atlases = new Map();
@@ -327,12 +326,12 @@ export class Texture {
      * @name getAtlas
      * @memberOf me.Renderer.Texture
      * @function
-     * @param {String} [name] atlas name in case of multipack textures
-     * @return {Object}
+     * @param {string} [name] atlas name in case of multipack textures
+     * @returns {object}
      */
-    getAtlas(key) {
-        if (typeof key === "string") {
-            return this.atlases.get(key);
+    getAtlas(name) {
+        if (typeof name === "string") {
+            return this.atlases.get(name);
         } else {
             return this.atlases.values().next().value;
         }
@@ -343,7 +342,7 @@ export class Texture {
      * @name getFormat
      * @memberOf me.Renderer.Texture
      * @function
-     * @return {String} will return "texturepacker", or "ShoeBox", or "melonJS", or "Spritesheet (fixed cell size)"
+     * @returns {string} will return "texturepacker", or "ShoeBox", or "melonJS", or "Spritesheet (fixed cell size)"
      */
     getFormat() {
         return this.format;
@@ -354,8 +353,8 @@ export class Texture {
      * @name getTexture
      * @memberOf me.Renderer.Texture
      * @function
-     * @param {Object} [region] region name in case of multipack textures
-     * @return {HTMLImageElement|HTMLCanvasElement}
+     * @param {object} [region] region name in case of multipack textures
+     * @returns {HTMLImageElement|HTMLCanvasElement}
      */
     getTexture(region) {
         if ((typeof region === "object") && (typeof region.texture === "string")) {
@@ -370,9 +369,9 @@ export class Texture {
      * @name getRegion
      * @memberOf me.Renderer.Texture
      * @function
-     * @param {String} name name of the sprite
-     * @param {String} [atlas] name of a specific atlas where to search for the region
-     * @return {Object}
+     * @param {string} name name of the sprite
+     * @param {string} [atlas] name of a specific atlas where to search for the region
+     * @returns {object}
      */
     getRegion(name, atlas) {
         var region;
@@ -395,8 +394,8 @@ export class Texture {
      * @name getUVs
      * @memberOf me.Renderer.Texture
      * @function
-     * @param {Object} region region (or frame) name
-     * @return {Float32Array} region Uvs
+     * @param {object} name region (or frame) name
+     * @returns {Float32Array} region Uvs
      */
     getUVs(name) {
         // Get the source texture region
@@ -419,9 +418,10 @@ export class Texture {
      * @name createSpriteFromName
      * @memberOf me.Renderer.Texture
      * @function
-     * @param {String} name name of the sprite
-     * @param {Object} [settings] Additional settings passed to the {@link me.Sprite} contructor
-     * @return {me.Sprite}
+     * @param {string} name name of the sprite
+     * @param {object} [settings] Additional settings passed to the {@link me.Sprite} contructor
+     * @param {boolean} [nineSlice=false] if true returns a 9-slice sprite
+     * @returns {me.Sprite|me.NineSliceSprite}
      * @example
      * // create a new texture object under the `game` namespace
      * game.texture = new me.video.renderer.Texture(
@@ -434,11 +434,20 @@ export class Texture {
      * var sprite = game.texture.createSpriteFromName("coin.png");
      * // set the renderable position to bottom center
      * sprite.anchorPoint.set(0.5, 1.0);
+     * ...
+     * ...
+     * // create a 9-slice sprite
+     * var dialogPanel = game.texture.createSpriteFromName(
+     *    "rpg_dialo.png",
+     *    // width & height are mandatory for 9-slice sprites
+     *    { width: this.width, height: this.height },
+     *    true
+     * );
      */
-    createSpriteFromName(name, settings) {
+    createSpriteFromName(name, settings, nineSlice = false) {
         // instantiate a new sprite object
         return pool.pull(
-            "me.Sprite",
+            nineSlice === true ? "me.NineSliceSprite" : "me.Sprite",
             0, 0,
             Object.assign({
                 image: this,
@@ -452,10 +461,10 @@ export class Texture {
      * @name createAnimationFromName
      * @memberOf me.Renderer.Texture
      * @function
-     * @param {String[]|Number[]} names list of names for each sprite
+     * @param {string[]|number[]} names list of names for each sprite
      * (when manually creating a Texture out of a spritesheet, only numeric values are authorized)
-     * @param {Object} [settings] Additional settings passed to the {@link me.Sprite} contructor
-     * @return {me.Sprite}
+     * @param {object} [settings] Additional settings passed to the {@link me.Sprite} contructor
+     * @returns {me.Sprite}
      * @example
      * // create a new texture object under the `game` namespace
      * game.texture = new me.video.renderer.Texture(

package/src/video/texture_cache.js

@@ -57,6 +57,17 @@ class TextureCache {
         return this.cache.get(image);
     }
 
+    /**
+     * @ignore
+     */
+    remove(image) {
+        if (!this.cache.has(image)) {
+            if (this.cache.remove(image) === true) {
+                this.length--;
+            }
+        }
+    }
+
     /**
      * @ignore
      */

package/src/video/video.js

@@ -192,20 +192,20 @@ export let renderer = null;
  *  - <i><b>`stretch`</b></i> : Canvas is resized to fit; content is scaled to screen aspect ratio
  * <center><img src="images/scale-stretch.png"/></center><br>
  * @function me.video.init
- * @param {Number} width The width of the canvas viewport
- * @param {Number} height The height of the canvas viewport
- * @param {Object} [options] The optional video/renderer parameters.<br> (see Renderer(s) documentation for further specific options)
- * @param {String|HTMLElement} [options.parent=document.body] the DOM parent element to hold the canvas in the HTML file
- * @param {Number} [options.renderer=me.video.AUTO] renderer to use (me.video.CANVAS, me.video.WEBGL, me.video.AUTO)
- * @param {Boolean} [options.doubleBuffering=false] enable/disable double buffering
- * @param {Number|String} [options.scale=1.0] enable scaling of the canvas ('auto' for automatic scaling)
- * @param {String} [options.scaleMethod="fit"] screen scaling modes ('fit','fill-min','fill-max','flex','flex-width','flex-height','stretch')
- * @param {Boolean} [options.preferWebGL1=false] if true the renderer will only use WebGL 1
- * @param {String} [options.powerPreference="default"] a hint to the user agent indicating what configuration of GPU is suitable for the WebGL context ("default", "high-performance", "low-power"). To be noted that Safari and Chrome (since version 80) both default to "low-power" to save battery life and improve the user experience on these dual-GPU machines.
- * @param {Boolean} [options.transparent=false] whether to allow transparent pixels in the front buffer (screen).
- * @param {Boolean} [options.antiAlias=false] whether to enable or not video scaling interpolation
- * @param {Boolean} [options.consoleHeader=true] whether to display melonJS version and basic device information in the console
- * @return {Boolean} false if initialization failed (canvas not supported)
+ * @param {number} width The width of the canvas viewport
+ * @param {number} height The height of the canvas viewport
+ * @param {object} [options] The optional video/renderer parameters.<br> (see Renderer(s) documentation for further specific options)
+ * @param {string|HTMLElement} [options.parent=document.body] the DOM parent element to hold the canvas in the HTML file
+ * @param {number} [options.renderer=me.video.AUTO] renderer to use (me.video.CANVAS, me.video.WEBGL, me.video.AUTO)
+ * @param {boolean} [options.doubleBuffering=false] enable/disable double buffering
+ * @param {number|string} [options.scale=1.0] enable scaling of the canvas ('auto' for automatic scaling)
+ * @param {string} [options.scaleMethod="fit"] screen scaling modes ('fit','fill-min','fill-max','flex','flex-width','flex-height','stretch')
+ * @param {boolean} [options.preferWebGL1=false] if true the renderer will only use WebGL 1
+ * @param {string} [options.powerPreference="default"] a hint to the user agent indicating what configuration of GPU is suitable for the WebGL context ("default", "high-performance", "low-power"). To be noted that Safari and Chrome (since version 80) both default to "low-power" to save battery life and improve the user experience on these dual-GPU machines.
+ * @param {boolean} [options.transparent=false] whether to allow transparent pixels in the front buffer (screen).
+ * @param {boolean} [options.antiAlias=false] whether to enable or not video scaling interpolation
+ * @param {boolean} [options.consoleHeader=true] whether to display melonJS version and basic device information in the console
+ * @returns {boolean} false if initialization failed (canvas not supported)
  * @example
  * // init the video with a 640x480 canvas
  * me.video.init(640, 480, {
@@ -216,7 +216,7 @@ export let renderer = null;
  *     doubleBuffering : true
  * });
  */
-export function init(game_width, game_height, options) {
+export function init(width, height, options) {
 
     // ensure melonjs has been properly initialized
     if (!initialized) {
@@ -227,8 +227,8 @@ export function init(game_width, game_height, options) {
     settings = Object.assign(settings, options || {});
 
     // sanitize potential given parameters
-    settings.width = game_width;
-    settings.height = game_height;
+    settings.width = width;
+    settings.height = height;
     settings.doubleBuffering = !!(settings.doubleBuffering);
     settings.transparent = !!(settings.transparent);
     settings.antiAlias = !!(settings.antiAlias);
@@ -268,13 +268,13 @@ export function init(game_width, game_height, options) {
     }
 
     // hold the requested video size ratio
-    designRatio = game_width / game_height;
-    designWidth = game_width;
-    designHeight = game_height;
+    designRatio = width / height;
+    designWidth = width;
+    designHeight = height;
 
     // default scaled size value
-    settings.zoomX = game_width * scaleRatio.x;
-    settings.zoomY = game_height * scaleRatio.y;
+    settings.zoomX = width * scaleRatio.x;
+    settings.zoomY = width * scaleRatio.y;
 
     //add a channel for the onresize/onorientationchange event
     window.addEventListener(
@@ -367,7 +367,7 @@ export function init(game_width, game_height, options) {
             device.getScreenOrientation() + " | " +
             device.language
         );
-        console.log( "resolution: " + "requested " + game_width + "x" + game_height +
+        console.log( "resolution: " + "requested " + width + "x" + height +
             ", got " + renderer.getWidth() + "x" + renderer.getHeight()
         );
     }
@@ -381,10 +381,10 @@ export function init(game_width, game_height, options) {
 /**
  * Create and return a new Canvas element
  * @function me.video.createCanvas
- * @param {Number} width width
- * @param {Number} height height
- * @param {Boolean} [offscreen=false] will returns an OffscreenCanvas if supported
- * @return {HTMLCanvasElement|OffscreenCanvas}
+ * @param {number} width width
+ * @param {number} height height
+ * @param {boolean} [offscreen=false] will returns an OffscreenCanvas if supported
+ * @returns {HTMLCanvasElement|OffscreenCanvas}
  */
 export function createCanvas(width, height, offscreen) {
     var _canvas;
@@ -413,7 +413,7 @@ export function createCanvas(width, height, offscreen) {
 /**
  * return a reference to the parent DOM element holding the main canvas
  * @function me.video.getParent
- * @return {HTMLElement}
+ * @returns {HTMLElement}
  */
 export function getParent() {
     return parent;
@@ -425,8 +425,8 @@ export function getParent() {
  * Only use this if you are not using the automatic scaling feature.
  * @function me.video.scale
  * @see me.video.init
- * @param {Number} x x scaling multiplier
- * @param {Number} y y scaling multiplier
+ * @param {number} x x scaling multiplier
+ * @param {number} y y scaling multiplier
  */
 export function scale(x, y) {
     var canvas = renderer.getScreenCanvas();

package/src/video/webgl/buffer/vertex.js

@@ -2,7 +2,7 @@
  * @classdesc
  * a Vertex Buffer object
  * @class VertexArrayBuffer
- * @private
+ * @ignore
  */
 
 class VertexArrayBuffer {
@@ -29,6 +29,7 @@ class VertexArrayBuffer {
 
     /**
      * clear the vertex array buffer
+     * @ignore
      */
     clear() {
         this.vertexCount = 0;
@@ -37,6 +38,7 @@ class VertexArrayBuffer {
 
     /**
      * return true if full
+     * @ignore
      */
     isFull(vertex = 0) {
          return (this.vertexCount + vertex >= this.maxVertex);
@@ -44,6 +46,7 @@ class VertexArrayBuffer {
 
     /**
      * resize the vertex buffer, retaining its original contents
+     * @ignore
      */
     resize() {
         // double the vertex size
@@ -64,6 +67,7 @@ class VertexArrayBuffer {
 
     /**
      * push a new vertex to the buffer
+     * @ignore
      */
     push(x, y, u, v, tint) {
         var offset = this.vertexCount * this.vertexSize;
@@ -91,6 +95,7 @@ class VertexArrayBuffer {
 
     /**
      * return a reference to the data in Float32 format
+     * @ignore
      */
     toFloat32(begin, end) {
         if (typeof end !== "undefined") {
@@ -102,6 +107,7 @@ class VertexArrayBuffer {
 
     /**
      * return a reference to the data in Uint32 format
+     * @ignore
      */
     toUint32(begin, end) {
         if (typeof end !== "undefined") {
@@ -113,6 +119,7 @@ class VertexArrayBuffer {
 
     /**
      * return the size of the vertex in vertex
+     * @ignore
      */
     length() {
         return this.vertexCount;
@@ -120,6 +127,7 @@ class VertexArrayBuffer {
 
     /**
      * return true if empty
+     * @ignore
      */
     isEmpty() {
         return this.vertexCount === 0;

package/src/video/webgl/glshader.js

@@ -2,7 +2,7 @@ import * as event from "./../../system/event.js";
 import device from "./../../system/device.js";
 
 /**
- * @private
+ * @ignore
  */
 function extractUniforms(gl, shader) {
     var uniforms = {},
@@ -46,9 +46,9 @@ function extractUniforms(gl, shader) {
                 }
                 else {
                     /**
-                    * A generic setter for uniform vectors
-                    * @ignore
-                    */
+                     * A generic setter for uniform vectors
+                     * @ignore
+                     */
                     return function (val) {
                         var fnv = fn;
                         if (val.length && fn.substr(-1) !== "v") {
@@ -66,7 +66,7 @@ function extractUniforms(gl, shader) {
 };
 
 /**
- * @private
+ * @ignore
  */
 function extractAttributes(gl, shader) {
     var attributes = {},
@@ -83,7 +83,7 @@ function extractAttributes(gl, shader) {
 };
 
 /**
- * @private
+ * @ignore
  */
 function compileShader(gl, type, source) {
     var shader = gl.createShader(type);
@@ -99,7 +99,7 @@ function compileShader(gl, type, source) {
 
 /**
  * Compile GLSL into a shader object
- * @private
+ * @ignore
  */
 function compileProgram(gl, vertex, fragment, attributes) {
     var vertShader = compileShader(gl, gl.VERTEX_SHADER, vertex);
@@ -144,7 +144,7 @@ function compileProgram(gl, vertex, fragment, attributes) {
 
 /**
  * Hash map of GLSL data types to WebGL Uniform methods
- * @private
+ * @ignore
  */
 var fnHash = {
     "bool"      : "1i",
@@ -168,7 +168,7 @@ var fnHash = {
 /**
  * set precision for the fiven shader source
  * won't do anything if the precision is already specified
- * @private
+ * @ignore
  */
 function setPrecision(src, precision) {
     if (src.substring(0, 9) !== "precision") {
@@ -179,7 +179,7 @@ function setPrecision(src, precision) {
 
 /**
  * clean the given source from space, comments, etc...
- * @private
+ * @ignore
  */
 function minify(src) {
     // remove comments
@@ -200,9 +200,9 @@ function minify(src) {
  * @class GLShader
  * @memberOf me
  * @param {WebGLRenderingContext} gl the current WebGL rendering context
- * @param {String} vertex a string containing the GLSL source code to set
- * @param {String} fragment a string containing the GLSL source code to set
- * @param {String} [precision=auto detected] float precision ('lowp', 'mediump' or 'highp').
+ * @param {string} vertex a string containing the GLSL source code to set
+ * @param {string} fragment a string containing the GLSL source code to set
+ * @param {string} [precision=auto detected] float precision ('lowp', 'mediump' or 'highp').
  * @constructor
  * @see https://developer.mozilla.org/en-US/docs/Games/Techniques/3D_on_the_web/GLSL_Shaders
  * @example
@@ -242,7 +242,7 @@ class GLShader {
         /**
          * the vertex shader source code
          * @public
-         * @type {String}
+         * @type {string}
          * @name vertex
          * @memberOf me.GLShader
          */
@@ -251,7 +251,7 @@ class GLShader {
         /**
          * the fragment shader source code
          * @public
-         * @type {String}
+         * @type {string}
          * @name vertex
          * @memberOf me.GLShader
          */
@@ -279,7 +279,7 @@ class GLShader {
         /**
          * the uniforms of the shader
          * @public
-         * @type {Object}
+         * @type {object}
          * @name uniforms
          * @memberOf me.GLShader
          */
@@ -306,8 +306,8 @@ class GLShader {
      * @name getAttribLocation
      * @memberOf me.GLShader
      * @function
-     * @param {String} name the name of the attribute variable whose location to get.
-     * @return {GLint} number indicating the location of the variable name if found. Returns -1 otherwise
+     * @param {string} name the name of the attribute variable whose location to get.
+     * @returns {GLint} number indicating the location of the variable name if found. Returns -1 otherwise
      */
     getAttribLocation(name) {
         var attr = this.attributes[name];
@@ -323,8 +323,8 @@ class GLShader {
      * @name setUniform
      * @memberOf me.GLShader
      * @function
-     * @param {String} name the uniform name
-     * @param {Object|Float32Array} value the value to assign to that uniform
+     * @param {string} name the uniform name
+     * @param {object|Float32Array} value the value to assign to that uniform
      * @example
      * myShader.setUniform("uProjectionMatrix", this.projectionMatrix);
      */