melonjs 10.2.0 → 10.3.0

package/src/video/video.js

@@ -10,7 +10,7 @@ import { initialized, version } from "./../index.js";
 /**
  * video functions
  * @namespace me.video
- * @memberOf me
+ * @memberof me
  */
 
 var designRatio = 1;
@@ -126,7 +126,7 @@ function onresize() {
 /**
  * Select the HTML5 Canvas renderer
  * @name CANVAS
- * @memberOf me.video
+ * @memberof me.video
  * @constant
  */
 export const CANVAS = 0;
@@ -134,7 +134,7 @@ export const CANVAS = 0;
 /**
  * Select the WebGL renderer
  * @name WEBGL
- * @memberOf me.video
+ * @memberof me.video
  * @constant
  */
 export const WEBGL = 1;
@@ -142,7 +142,7 @@ export const WEBGL = 1;
 /**
  * Auto-select the renderer (Attempt WebGL first, with fallback to Canvas)
  * @name AUTO
- * @memberOf me.video
+ * @memberof me.video
  * @constant
  */
 export const AUTO = 2;
@@ -153,7 +153,7 @@ export const AUTO = 2;
  * @type {HTMLElement}
  * @readonly
  * @name parent
- * @memberOf me.video
+ * @memberof me.video
  */
 export let parent = null;
 
@@ -162,7 +162,7 @@ export let parent = null;
  * @name scaleRatio
  * @type {me.Vector2d}
  * @default <1,1>
- * @memberOf me.video
+ * @memberof me.video
  */
 export let scaleRatio = new Vector2d(1, 1);
 
@@ -170,7 +170,7 @@ export let scaleRatio = new Vector2d(1, 1);
   * A reference to the active Canvas or WebGL active renderer renderer
   * @name renderer
   * @type {me.CanvasRenderer|me.WebGLRenderer}
-  * @memberOf me.video
+  * @memberof me.video
   */
 export let renderer = null;
 
@@ -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,12 +381,12 @@ 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) {
+export function createCanvas(width, height, offscreen = false) {
     var _canvas;
 
     if (width === 0 || height === 0) {
@@ -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,13 +2,13 @@
  * @classdesc
  * a Vertex Buffer object
  * @class VertexArrayBuffer
- * @private
+ * @ignore
  */
 
 class VertexArrayBuffer {
 
     constructor(vertex_size, vertex_per_quad) {
-        // the size of one vertex
+        // the size of one vertex in float
         this.vertexSize = vertex_size;
         // size of a quad in vertex
         this.quadSize = vertex_per_quad;
@@ -29,6 +29,7 @@ class VertexArrayBuffer {
 
     /**
      * clear the vertex array buffer
+     * @ignore
      */
     clear() {
         this.vertexCount = 0;
@@ -37,13 +38,15 @@ class VertexArrayBuffer {
 
     /**
      * return true if full
+     * @ignore
      */
-    isFull(vertex = 0) {
+    isFull(vertex = this.quadSize) {
          return (this.vertexCount + vertex >= this.maxVertex);
     }
 
     /**
      * 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
@@ -198,12 +198,11 @@ function minify(src) {
  * @classdesc
  * a base GL Shader object
  * @class GLShader
- * @memberOf me
+ * @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').
- * @constructor
+ * @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').
  * @see https://developer.mozilla.org/en-US/docs/Games/Techniques/3D_on_the_web/GLSL_Shaders
  * @example
  * // create a basic shader
@@ -235,25 +234,25 @@ class GLShader {
          * @public
          * @type {WebGLRenderingContext}
          * @name gl
-         * @memberOf me.GLShader
+         * @memberof me.GLShader
          */
         this.gl = gl;
 
         /**
          * the vertex shader source code
          * @public
-         * @type {String}
+         * @type {string}
          * @name vertex
-         * @memberOf me.GLShader
+         * @memberof me.GLShader
          */
         this.vertex = setPrecision(minify(vertex), precision || device.getMaxShaderPrecision(this.gl));
 
         /**
          * the fragment shader source code
          * @public
-         * @type {String}
+         * @type {string}
          * @name vertex
-         * @memberOf me.GLShader
+         * @memberof me.GLShader
          */
         this.fragment = setPrecision(minify(fragment), precision || device.getMaxShaderPrecision(this.gl));
 
@@ -262,7 +261,7 @@ class GLShader {
          * @public
          * @type {GLint[]}
          * @name attributes
-         * @memberOf me.GLShader
+         * @memberof me.GLShader
          */
         this.attributes = extractAttributes(this.gl, this);
 
@@ -272,16 +271,16 @@ class GLShader {
          * @public
          * @type {WebGLProgram}
          * @name program
-         * @memberOf me.GLShader
+         * @memberof me.GLShader
          */
         this.program = compileProgram(this.gl, this.vertex, this.fragment, this.attributes);
 
         /**
          * the uniforms of the shader
          * @public
-         * @type {Object}
+         * @type {object}
          * @name uniforms
-         * @memberOf me.GLShader
+         * @memberof me.GLShader
          */
         this.uniforms = extractUniforms(this.gl, this);
 
@@ -294,7 +293,7 @@ class GLShader {
     /**
      * Installs this shader program as part of current rendering state
      * @name bind
-     * @memberOf me.GLShader
+     * @memberof me.GLShader
      * @function
      */
     bind() {
@@ -304,10 +303,10 @@ class GLShader {
     /**
      * returns the location of an attribute variable in this shader program
      * @name getAttribLocation
-     * @memberOf me.GLShader
+     * @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];
@@ -321,10 +320,10 @@ class GLShader {
     /**
      * Set the uniform to the given value
      * @name setUniform
-     * @memberOf me.GLShader
+     * @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);
      */
@@ -344,7 +343,7 @@ class GLShader {
     /**
      * destroy this shader objects resources (program, attributes, uniforms)
      * @name destroy
-     * @memberOf me.GLShader
+     * @memberof me.GLShader
      * @function
      */
     destroy() {