melonjs 13.0.0 → 13.2.0

package/src/video/webgl/webgl_renderer.js

@@ -20,10 +20,10 @@ class WebGLRenderer extends Renderer {
      * @param {number} options.width The width of the canvas without scaling
      * @param {number} options.height The height of the canvas without scaling
      * @param {HTMLCanvasElement} [options.canvas] The html canvas to draw to on screen
-     * @param {boolean} [options.doubleBuffering=false] Whether to enable double buffering (not applicable when using the WebGL Renderer)
      * @param {boolean} [options.antiAlias=false] Whether to enable anti-aliasing
      * @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.
-     * @param {boolean} [options.transparent=false] Whether to enable transparency on the canvas (performance hit when enabled)
+     * @param {boolean} [options.transparent=false] Whether to enable transparency on the canvas
+     * @param {boolean} [options.premultipliedAlpha=true] in WebGL, whether the renderer will assume that colors have premultiplied alpha when canvas transparency is enabled
      * @param {boolean} [options.subPixel=false] Whether to enable subpixel renderering (performance hit when enabled)
      * @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.
@@ -38,8 +38,6 @@ class WebGLRenderer extends Renderer {
 
         /**
          * The WebGL version used by this renderer (1 or 2)
-         * @name WebGLVersion
-         * @memberof WebGLRenderer#
          * @type {number}
          * @default 1
          * @readonly
@@ -48,8 +46,6 @@ class WebGLRenderer extends Renderer {
 
         /**
          * The vendor string of the underlying graphics driver.
-         * @name GPUVendor
-         * @memberof WebGLRenderer#
          * @type {string}
          * @default null
          * @readonly
@@ -58,8 +54,6 @@ class WebGLRenderer extends Renderer {
 
         /**
          * The renderer string of the underlying graphics driver.
-         * @name GPURenderer
-         * @memberof WebGLRenderer#
          * @type {string}
          * @default null
          * @readonly
@@ -69,15 +63,12 @@ class WebGLRenderer extends Renderer {
         /**
          * The WebGL context
          * @name gl
-         * @memberof WebGLRenderer
          * @type {WebGLRenderingContext}
          */
-        this.context = this.gl = this.getContextGL(this.getScreenCanvas(), options.transparent);
+        this.context = this.gl = this.getContextGL(this.getCanvas(), options.transparent);
 
         /**
          * Maximum number of texture unit supported under the current context
-         * @name maxTextures
-         * @memberof WebGLRenderer#
          * @type {number}
          * @readonly
          */
@@ -105,25 +96,19 @@ class WebGLRenderer extends Renderer {
 
         /**
          * The current transformation matrix used for transformations on the overall scene
-         * @name currentTransform
          * @type {Matrix2d}
-         * @memberof WebGLRenderer#
          */
         this.currentTransform = new Matrix2d();
 
         /**
          * The current compositor used by the renderer
-         * @name currentCompositor
          * @type {WebGLCompositor}
-         * @memberof WebGLRenderer#
          */
         this.currentCompositor = null;
 
         /**
          * The list of active compositors
-         * @name compositors
          * @type {Map<WebGLCompositor>}
-         * @memberof WebGLRenderer#
          */
         this.compositors = new Map();
 
@@ -154,13 +139,13 @@ class WebGLRenderer extends Renderer {
         // to simulate context lost and restore in WebGL:
         // var ctx = me.video.renderer.context.getExtension('WEBGL_lose_context');
         // ctx.loseContext()
-        this.getScreenCanvas().addEventListener("webglcontextlost", (e) => {
+        this.getCanvas().addEventListener("webglcontextlost", (e) => {
             e.preventDefault();
             this.isContextValid = false;
             event.emit(event.ONCONTEXT_LOST, this);
         }, false );
         // ctx.restoreContext()
-        this.getScreenCanvas().addEventListener("webglcontextrestored", () => {
+        this.getCanvas().addEventListener("webglcontextrestored", () => {
             this.reset();
             this.isContextValid = true;
             event.emit(event.ONCONTEXT_RESTORED, this);
@@ -169,8 +154,6 @@ class WebGLRenderer extends Renderer {
 
     /**
      * Reset context state
-     * @name reset
-     * @memberof WebGLRenderer
      */
     reset() {
         super.reset();
@@ -193,9 +176,7 @@ class WebGLRenderer extends Renderer {
 
     /**
      * set the active compositor for this renderer
-     * @name setCompositor
      * @param {WebGLCompositor|string} compositor a compositor name or instance
-     * @memberof WebGLRenderer
      */
     setCompositor(compositor = "default") {
 
@@ -219,8 +200,6 @@ class WebGLRenderer extends Renderer {
 
     /**
      * Reset the gl transform to identity
-     * @name resetTransform
-     * @memberof WebGLRenderer
      */
     resetTransform() {
         this.currentTransform.identity();
@@ -231,7 +210,7 @@ class WebGLRenderer extends Renderer {
      */
     createFontTexture(cache) {
         if (typeof this.fontTexture === "undefined") {
-            var canvas = this.backBufferCanvas;
+            var canvas = this.getCanvas();
             var width = canvas.width;
             var height = canvas.height;
 
@@ -265,8 +244,6 @@ class WebGLRenderer extends Renderer {
 
     /**
      * Create a pattern with the specified repetition
-     * @name createPattern
-     * @memberof WebGLRenderer
      * @param {Image} image Source image
      * @param {string} repeat Define how the pattern should be repeated
      * @returns {TextureAtlas}
@@ -297,8 +274,6 @@ class WebGLRenderer extends Renderer {
 
     /**
      * Flush the compositor to the frame buffer
-     * @name flush
-     * @memberof WebGLRenderer
      */
     flush() {
         this.currentCompositor.flush();
@@ -306,8 +281,6 @@ class WebGLRenderer extends Renderer {
 
     /**
      * set/change the current projection matrix (WebGL only)
-     * @name setProjection
-     * @memberof WebGLRenderer
      * @param {Matrix3d} matrix
      */
     setProjection(matrix) {
@@ -315,10 +288,15 @@ class WebGLRenderer extends Renderer {
         this.currentCompositor.setProjection(matrix);
     }
 
+    /**
+     * prepare the framebuffer for drawing a new frame
+     */
+    clear() {
+        this.currentCompositor.clear(this.settings.transparent ? 0.0 : 1.0);
+    }
+
     /**
      * Clears the gl context with the given color.
-     * @name clearColor
-     * @memberof WebGLRenderer
      * @param {Color|string} [color="#000000"] CSS color.
      * @param {boolean} [opaque=false] Allow transparency [default] or clear the surface completely [true]
      */
@@ -335,17 +313,10 @@ class WebGLRenderer extends Renderer {
         }
         // clear gl context with the specified color
         this.currentCompositor.clearColor(glArray[0], glArray[1], glArray[2], (opaque === true) ? 1.0 : glArray[3]);
-        this.currentCompositor.clear();
-
-        // restore default clear Color black
-        this.currentCompositor.clearColor(0.0, 0.0, 0.0, 0.0);
-
     }
 
     /**
      * Erase the pixels in the given rectangular area by setting them to transparent black (rgba(0,0,0,0)).
-     * @name clearRect
-     * @memberof WebGLRenderer
      * @param {number} x x axis of the coordinate for the rectangle starting point.
      * @param {number} y y axis of the coordinate for the rectangle starting point.
      * @param {number} width The rectangle's width.
@@ -379,7 +350,7 @@ class WebGLRenderer extends Renderer {
             uvs[1],
             uvs[2],
             uvs[3],
-            this.currentTint.toUint32()
+            this.currentTint.toUint32(this.getGlobalAlpha())
         );
 
         // Clear font context2D
@@ -393,8 +364,6 @@ class WebGLRenderer extends Renderer {
 
     /**
      * Draw an image to the gl context
-     * @name drawImage
-     * @memberof WebGLRenderer
      * @param {Image} image An element to draw into the context. The specification permits any canvas image source (CanvasImageSource), specifically, a CSSImageValue, an HTMLImageElement, an SVGImageElement, an HTMLVideoElement, an HTMLCanvasElement, an ImageBitmap, or an OffscreenCanvas.
      * @param {number} sx The X coordinate of the top left corner of the sub-rectangle of the source image to draw into the destination context.
      * @param {number} sy The Y coordinate of the top left corner of the sub-rectangle of the source image to draw into the destination context.
@@ -440,13 +409,11 @@ class WebGLRenderer extends Renderer {
 
         var texture = this.cache.get(image);
         var uvs = texture.getUVs(sx + "," + sy + "," + sw + "," + sh);
-        this.currentCompositor.addQuad(texture, dx, dy, dw, dh, uvs[0], uvs[1], uvs[2], uvs[3], this.currentTint.toUint32());
+        this.currentCompositor.addQuad(texture, dx, dy, dw, dh, uvs[0], uvs[1], uvs[2], uvs[3], this.currentTint.toUint32(this.getGlobalAlpha()));
     }
 
     /**
      * Draw a pattern within the given rectangle.
-     * @name drawPattern
-     * @memberof WebGLRenderer
      * @param {TextureAtlas} pattern Pattern object
      * @param {number} x
      * @param {number} y
@@ -456,29 +423,16 @@ class WebGLRenderer extends Renderer {
      */
     drawPattern(pattern, x, y, width, height) {
         var uvs = pattern.getUVs("0,0," + width + "," + height);
-        this.currentCompositor.addQuad(pattern, x, y, width, height, uvs[0], uvs[1], uvs[2], uvs[3], this.currentTint.toUint32());
-    }
-
-
-    /**
-     * return a reference to the screen canvas corresponding WebGL Context
-     * @name getScreenContext
-     * @memberof WebGLRenderer
-     * @returns {WebGLRenderingContext}
-     */
-    getScreenContext() {
-        return this.gl;
+        this.currentCompositor.addQuad(pattern, x, y, width, height, uvs[0], uvs[1], uvs[2], uvs[3], this.currentTint.toUint32(this.getGlobalAlpha()));
     }
 
     /**
-     * Returns the WebGL Context object of the given Canvas
-     * @name getContextGL
-     * @memberof WebGLRenderer
+     * Returns the WebGL Context object of the given canvas element
      * @param {HTMLCanvasElement} canvas
-     * @param {boolean} [transparent=true] use false to disable transparency
+     * @param {boolean} [transparent=false] use true to enable transparency
      * @returns {WebGLRenderingContext}
      */
-    getContextGL(canvas, transparent) {
+    getContextGL(canvas, transparent = false) {
         if (typeof canvas === "undefined" || canvas === null) {
             throw new Error(
                 "You must pass a canvas element in order to create " +
@@ -486,17 +440,13 @@ class WebGLRenderer extends Renderer {
             );
         }
 
-        if (typeof transparent !== "boolean") {
-            transparent = true;
-        }
-
         var attr = {
             alpha : transparent,
             antialias : this.settings.antiAlias,
             depth : false,
             stencil: true,
             preserveDrawingBuffer : false,
-            premultipliedAlpha: transparent,
+            premultipliedAlpha: transparent ? this.settings.premultipliedAlpha : false,
             powerPreference: this.settings.powerPreference,
             failIfMajorPerformanceCaveat : this.settings.failIfMajorPerformanceCaveat
         };
@@ -529,8 +479,6 @@ class WebGLRenderer extends Renderer {
     /**
      * Returns the WebGLContext instance for the renderer
      * return a reference to the system 2d Context
-     * @name getContext
-     * @memberof WebGLRenderer
      * @returns {WebGLRenderingContext}
      */
     getContext() {
@@ -548,9 +496,7 @@ class WebGLRenderer extends Renderer {
      * <img src="images/lighter-blendmode.png" width="510"/> <br>
      * - "screen" : The pixels are inverted, multiplied, and inverted again. A lighter picture is the result (opposite of multiply) <br>
      * <img src="images/screen-blendmode.png" width="510"/> <br>
-     * @name setBlendMode
      * @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/globalCompositeOperation
-     * @memberof WebGLRenderer
      * @param {string} [mode="normal"] blend mode : "normal", "multiply", "lighter", "additive", "screen"
      * @param {WebGLRenderingContext} [gl]
      */
@@ -599,8 +545,6 @@ class WebGLRenderer extends Renderer {
 
     /**
      * restores the canvas context
-     * @name restore
-     * @memberof WebGLRenderer
      */
     restore() {
         // do nothing if there is no saved states
@@ -627,15 +571,13 @@ class WebGLRenderer extends Renderer {
             this.gl.disable(this.gl.SCISSOR_TEST);
             this.currentScissor[0] = 0;
             this.currentScissor[1] = 0;
-            this.currentScissor[2] = this.backBufferCanvas.width;
-            this.currentScissor[3] = this.backBufferCanvas.height;
+            this.currentScissor[2] = this.getCanvas().width;
+            this.currentScissor[3] = this.getCanvas().height;
         }
     }
 
     /**
      * saves the canvas context
-     * @name save
-     * @memberof WebGLRenderer
      */
     save() {
         this._colorStack.push(this.currentColor.clone());
@@ -651,8 +593,6 @@ class WebGLRenderer extends Renderer {
 
     /**
      * rotates the uniform matrix
-     * @name rotate
-     * @memberof WebGLRenderer
      * @param {number} angle in radians
      */
     rotate(angle) {
@@ -661,8 +601,6 @@ class WebGLRenderer extends Renderer {
 
     /**
      * scales the uniform matrix
-     * @name scale
-     * @memberof WebGLRenderer
      * @param {number} x
      * @param {number} y
      */
@@ -681,8 +619,6 @@ class WebGLRenderer extends Renderer {
 
     /**
      * Set the global alpha
-     * @name setGlobalAlpha
-     * @memberof WebGLRenderer
      * @param {number} alpha 0.0 to 1.0 values accepted.
      */
     setGlobalAlpha(alpha) {
@@ -691,8 +627,6 @@ class WebGLRenderer extends Renderer {
 
     /**
      * Return the global alpha
-     * @name getGlobalAlpha
-     * @memberof WebGLRenderer
      * @returns {number} global alpha value
      */
     getGlobalAlpha() {
@@ -702,8 +636,6 @@ class WebGLRenderer extends Renderer {
     /**
      * Set the current fill & stroke style color.
      * By default, or upon reset, the value is set to #000000.
-     * @name setColor
-     * @memberof WebGLRenderer
      * @param {Color|string} color css color string.
      */
     setColor(color) {
@@ -714,18 +646,14 @@ class WebGLRenderer extends Renderer {
 
     /**
      * Set the line width
-     * @name setLineWidth
-     * @memberof WebGLRenderer
      * @param {number} width Line width
      */
     setLineWidth(width) {
-        this.getScreenContext().lineWidth(width);
+        this.getContext().lineWidth(width);
     }
 
     /**
      * Stroke an arc at the specified coordinates with given radius, start and end points
-     * @name strokeArc
-     * @memberof WebGLRenderer
      * @param {number} x arc center point x-axis
      * @param {number} y arc center point y-axis
      * @param {number} radius
@@ -751,8 +679,6 @@ class WebGLRenderer extends Renderer {
 
     /**
      * Fill an arc at the specified coordinates with given radius, start and end points
-     * @name fillArc
-     * @memberof WebGLRenderer
      * @param {number} x arc center point x-axis
      * @param {number} y arc center point y-axis
      * @param {number} radius
@@ -766,8 +692,6 @@ class WebGLRenderer extends Renderer {
 
     /**
      * Stroke an ellipse at the specified coordinates with given radius
-     * @name strokeEllipse
-     * @memberof WebGLRenderer
      * @param {number} x ellipse center point x-axis
      * @param {number} y ellipse center point y-axis
      * @param {number} w horizontal radius of the ellipse
@@ -791,8 +715,6 @@ class WebGLRenderer extends Renderer {
 
     /**
      * Fill an ellipse at the specified coordinates with given radius
-     * @name fillEllipse
-     * @memberof WebGLRenderer
      * @param {number} x ellipse center point x-axis
      * @param {number} y ellipse center point y-axis
      * @param {number} w horizontal radius of the ellipse
@@ -804,8 +726,6 @@ class WebGLRenderer extends Renderer {
 
     /**
      * Stroke a line of the given two points
-     * @name strokeLine
-     * @memberof WebGLRenderer
      * @param {number} startX the start x coordinate
      * @param {number} startY the start y coordinate
      * @param {number} endX the end x coordinate
@@ -825,8 +745,6 @@ class WebGLRenderer extends Renderer {
 
     /**
      * Fill a line of the given two points
-     * @name fillLine
-     * @memberof WebGLRenderer
      * @param {number} startX the start x coordinate
      * @param {number} startY the start y coordinate
      * @param {number} endX the end x coordinate
@@ -838,8 +756,6 @@ class WebGLRenderer extends Renderer {
 
     /**
      * Stroke a me.Polygon on the screen with a specified color
-     * @name strokePolygon
-     * @memberof WebGLRenderer
      * @param {Polygon} poly the shape to draw
      * @param {boolean} [fill=false] also fill the shape with the current color if true
      */
@@ -869,8 +785,6 @@ class WebGLRenderer extends Renderer {
 
     /**
      * Fill a me.Polygon on the screen
-     * @name fillPolygon
-     * @memberof WebGLRenderer
      * @param {Polygon} poly the shape to draw
      */
     fillPolygon(poly) {
@@ -879,8 +793,6 @@ class WebGLRenderer extends Renderer {
 
     /**
      * Draw a stroke rectangle at the specified coordinates
-     * @name strokeRect
-     * @memberof WebGLRenderer
      * @param {number} x
      * @param {number} y
      * @param {number} width
@@ -903,8 +815,6 @@ class WebGLRenderer extends Renderer {
 
     /**
      * Draw a filled rectangle at the specified coordinates
-     * @name fillRect
-     * @memberof WebGLRenderer
      * @param {number} x
      * @param {number} y
      * @param {number} width
@@ -916,8 +826,6 @@ class WebGLRenderer extends Renderer {
 
     /**
      * Stroke a rounded rectangle at the specified coordinates
-     * @name strokeRoundRect
-     * @memberof WebGLRenderer
      * @param {number} x
      * @param {number} y
      * @param {number} width
@@ -942,8 +850,6 @@ class WebGLRenderer extends Renderer {
 
     /**
      * Draw a rounded filled rectangle at the specified coordinates
-     * @name fillRoundRect
-     * @memberof WebGLRenderer
      * @param {number} x
      * @param {number} y
      * @param {number} width
@@ -954,11 +860,29 @@ class WebGLRenderer extends Renderer {
         this.strokeRoundRect(x, y, width, height, radius, true);
     }
 
+    /**
+     * Stroke a Point at the specified coordinates
+     * @param {number} x
+     * @param {number} y
+     */
+    strokePoint(x, y) {
+        this.strokeLine(x, y, x + 1, y + 1);
+    }
+
+    /**
+     * Draw a a point at the specified coordinates
+     * @param {number} x
+     * @param {number} y
+     * @param {number} width
+     * @param {number} height
+     */
+    fillPoint(x, y) {
+        this.strokePoint(x, y);
+    }
+
     /**
      * Reset (overrides) the renderer transformation matrix to the
      * identity one, and then apply the given transformation matrix.
-     * @name setTransform
-     * @memberof WebGLRenderer
      * @param {Matrix2d} mat2d Matrix to transform by
      */
     setTransform(mat2d) {
@@ -968,8 +892,6 @@ class WebGLRenderer extends Renderer {
 
     /**
      * Multiply given matrix into the renderer tranformation matrix
-     * @name transform
-     * @memberof WebGLRenderer
      * @param {Matrix2d} mat2d Matrix to transform by
      */
     transform(mat2d) {
@@ -985,8 +907,6 @@ class WebGLRenderer extends Renderer {
 
     /**
      * Translates the uniform matrix by the given coordinates
-     * @name translate
-     * @memberof WebGLRenderer
      * @param {number} x
      * @param {number} y
      */
@@ -1007,15 +927,13 @@ class WebGLRenderer extends Renderer {
      * You can however save the current region using the save(),
      * and restore it (with the restore() method) any time in the future.
      * (<u>this is an experimental feature !</u>)
-     * @name clipRect
-     * @memberof WebGLRenderer
      * @param {number} x
      * @param {number} y
      * @param {number} width
      * @param {number} height
      */
     clipRect(x, y, width, height) {
-        var canvas = this.backBufferCanvas;
+        var canvas = this.getCanvas();
         var gl = this.gl;
         // if requested box is different from the current canvas size
         if (x !== 0 || y !== 0 || width !== canvas.width || height !== canvas.height) {
@@ -1054,8 +972,6 @@ class WebGLRenderer extends Renderer {
      * A mask limits rendering elements to the shape and position of the given mask object.
      * So, if the renderable is larger than the mask, only the intersecting part of the renderable will be visible.
      * Mask are not preserved through renderer context save and restore.
-     * @name setMask
-     * @memberof WebGLRenderer
      * @param {Rect|RoundRect|Polygon|Line|Ellipse} [mask] a shape defining the mask to be applied
      * @param {boolean} [invert=false] either the given shape should define what is visible (default) or the opposite
      */
@@ -1069,8 +985,6 @@ class WebGLRenderer extends Renderer {
             // Enable and setup GL state to write to stencil buffer
             gl.enable(gl.STENCIL_TEST);
             gl.clear(gl.STENCIL_BUFFER_BIT);
-
-
         }
 
         this.maskLevel++;
@@ -1099,9 +1013,7 @@ class WebGLRenderer extends Renderer {
 
     /**
      * disable (remove) the rendering mask set through setMask.
-     * @name clearMask
      * @see WebGLRenderer#setMask
-     * @memberof WebGLRenderer
      */
     clearMask() {
         if (this.maskLevel > 0) {