The new CanvasTexture class now working and linked to examples.

Author: photonstorm

src/textures/CanvasTexture.js

@@ -5,11 +5,28 @@
  */
 
 var Class = require('../utils/Class');
+var IsSizePowerOfTwo = require('../math/pow2/IsSizePowerOfTwo');
 var Texture = require('./Texture');
 
 /**
  * @classdesc
- * [description]
+ * A Canvas Texture is a special kind of Texture that is backed by an HTML Canvas Element as its source.
+ *
+ * You can use the properties of this texture to draw to the canvas element directly, using all of the standard
+ * canvas operations available in the browser. Any Game Object can be given this texture and will render with it.
+ *
+ * Note: When running under WebGL the Canvas Texture needs to re-generate its base WebGLTexture and reupload it to
+ * the GPU every time you modify it, otherwise the changes you make to this texture will not be visible. To do this
+ * you should call `CanvasTexture.refresh()` once you are finished with your changes to the canvas. Try and keep
+ * this to a minimum, especially on large canvas sizes, or you may inadvertently thrash the GPU by constantly uploading
+ * texture data to it. This restriction does not apply if using the Canvas Renderer.
+ * 
+ * It starts with only one frame that covers the whole of the canvas. You can add further frames, that specify
+ * sections of the canvas using the `add` method.
+ * 
+ * Should you need to resize the canvas use the `setSize` method so that it accurately updates all of the underlying
+ * texture data as well. Forgetting to do this (i.e. by changing the canvas size directly from your code) could cause
+ * graphical errors.
  *
  * @class CanvasTexture
  * @extends Phaser.Textures.Texture
@@ -19,9 +36,9 @@ var Texture = require('./Texture');
  *
  * @param {Phaser.Textures.TextureManager} manager - A reference to the Texture Manager this Texture belongs to.
  * @param {string} key - The unique string-based key of this Texture.
- * @param {HTMLCanvasElement} source - The source that is used to create the texture. Usually an Image, but can also be a Canvas.
- * @param {number} [width] - The width of the Texture. This is optional and automatically derived from the source images.
- * @param {number} [height] - The height of the Texture. This is optional and automatically derived from the source images.
+ * @param {HTMLCanvasElement} source - The canvas element that is used as the base of this texture.
+ * @param {integer} width - The width of the canvas.
+ * @param {integer} height - The height of the canvas.
  */
 var CanvasTexture = new Class({
 
@@ -33,14 +50,58 @@ var CanvasTexture = new Class({
     {
         Texture.call(this, manager, key, source, width, height);
 
-        this._texture = this.frames['__BASE'].source;
-
-        this.canvas = this._texture.image;
-
+        this.add('__BASE', 0, 0, 0, width, height);
+
+        /**
+         * A reference to the Texture Source of this Canvas.
+         *
+         * @name Phaser.Textures.TextureManager#_source
+         * @type {Phaser.Textures.TextureSource}
+         * @private
+         * @since 3.6.1
+         */
+        this._source = this.frames['__BASE'].source;
+
+        /**
+         * The source Canvas Element.
+         *
+         * @name Phaser.Textures.TextureManager#canvas
+         * @readOnly
+         * @type {HTMLCanvasElement}
+         * @since 3.6.1
+         */
+        this.canvas = this._source.image;
+
+        /**
+         * The 2D Canvas Rendering Context.
+         *
+         * @name Phaser.Textures.TextureManager#canvas
+         * @readOnly
+         * @type {CanvasRenderingContext2D}
+         * @since 3.6.1
+         */
         this.context = this.canvas.getContext('2d');
 
+        /**
+         * The width of the Canvas.
+         * This property is read-only, if you wish to change use `setSize`.
+         *
+         * @name Phaser.Textures.TextureManager#width
+         * @readOnly
+         * @type {integer}
+         * @since 3.6.1
+         */
         this.width = width;
 
+        /**
+         * The height of the Canvas.
+         * This property is read-only, if you wish to change use `setSize`.
+         *
+         * @name Phaser.Textures.TextureManager#height
+         * @readOnly
+         * @type {integer}
+         * @since 3.6.1
+         */
         this.height = height;
     },
 
@@ -56,13 +117,13 @@ var CanvasTexture = new Class({
      */
     refresh: function ()
     {
-        this._texture.update();
+        this._source.update();
 
         return this;
     },
 
     /**
-     * [description]
+     * Gets the Canvas Element.
      *
      * @method Phaser.Textures.CanvasTexture#getCanvas
      * @since 3.6.1
@@ -75,18 +136,68 @@ var CanvasTexture = new Class({
     },
 
     /**
-     * [description]
+     * Gets the 2D Canvas Rendering Context.
      *
      * @method Phaser.Textures.CanvasTexture#getContext
      * @since 3.6.1
      *
-     * @return {HTMLCanvasElement} The Canvas DOM element this texture is using.
+     * @return {CanvasRenderingContext2D} The Canvas Rendering Context this texture is using.
      */
     getContext: function ()
     {
         return this.context;
     },
 
+    /**
+     * Clears this Canvas Texture, resetting it back to transparent.
+     *
+     * @method Phaser.Textures.CanvasTexture#clear
+     * @since 3.6.1
+     *
+     * @return {Phaser.Textures.CanvasTexture} The Canvas Texture.
+     */
+    clear: function ()
+    {
+        this.context.clearRect(0, 0, this.width, this.height);
+
+        return this;
+    },
+
+    /**
+     * Changes the size of this Canvas Texture.
+     *
+     * @method Phaser.Textures.CanvasTexture#setSize
+     * @since 3.6.1
+     *
+     * @param {integer} width - The new width of the Canvas.
+     * @param {integer} [height] - The new height of the Canvas. If not given it will use the width as the height.
+     *
+     * @return {Phaser.Textures.CanvasTexture} The Canvas Texture.
+     */
+    setSize: function (width, height)
+    {
+        if (height === undefined) { height = width; }
+
+        if (width !== this.width || height !== this.height)
+        {
+            //  Update the Canvas
+            this.canvas.width = width;
+            this.canvas.height = height;
+
+            //  Update the Texture Source
+            this._source.width = width;
+            this._source.height = height;
+            this._source.isPowerOf2 = IsSizePowerOfTwo(width, height);
+
+            //  Update the Frame
+            this.frames['__BASE'].setSize(width, height, 0, 0);
+
+            this.refresh();
+        }
+
+        return this;
+    }
+
 });
 
 module.exports = CanvasTexture;