Merge branch 'master' into feature-multi-image-loader

Author: jorbascrumps

CHANGELOG.md

@@ -6,23 +6,43 @@
 
 * The Phaser 3 Labs has gained a nifty 'search' feature box thanks to @NemoStein - it allows you to filter out the example categories.
 * We've added a Mask component, which is available on nearly all Game Objects. It includes the methods `setMask`, `clearMask`, `createBitmapMask` and `createGeometryMask`.
+* CanvasTexture is a new extension of the Texture object specifically created for when you've got a Canvas element as the backing source of the texture that you wish to draw to programmatically using the Canvas API. This was possible in previous versions, as a Texture object supported having a Canvas as its source, but we've streamlined the process and made it a lot easier for you to refresh the resulting WebGLTexture on the GPU. To create a CanvasTexture just call the `TextureManager.createCanvas` method as before, only this time you'll get a CanvasTexture back which has helper properties and methods. See the complete JSDocs for more details.
 
 ### Updates
 
 * If you're using Webpack with Phaser you'll need to update your config to match our new one.
 * We've swapped use of the Webpack DefinePlugin so instead of setting a global flag for the compilation of the Canvas and WebGL renderers, we now use a typeof check instead. This means you should now be able to ingest the Phaser source more easily outside of Webpack without having to define any global vars first (thanks @tgrajewski)
 * Under Webpack we still use the raw-loader to import our shader source, but outside of Webpack we now use `require.extensions` to load the shader source via fs. This should allow you to bundle Phaser with packages other than Webpack more easily (thanks @tgrajewski)
-* The Texture Manager will now emit an `addtexture` event whenever you add a new texture to it, which includes when you load images files from the Loader (as it automatically populates the Texture Manager). Once you receive an `addtexture` event you know the image is loaded and the texture is safe to be applied to a Game Object.
+* The Texture Manager will now emit an `addtexture` event whenever you add a new texture to it, which includes when you load image files from the Loader (as it automatically populates the Texture Manager). Once you receive an `addtexture` event you know the image is loaded and the texture is safe to be applied to a Game Object.
+* BitmapMask and GeometryMask both have new `destroy` methods which clear their references, freeing them for gc.
+* CanvasPool has a new argument `selfParent` which allows the canvas itself to be the parent key, used for later removal.
+* Frame has a new method `setSize` which allows you to set the frame x, y, width and height and have it update all of the internal properties automatically. This is now called directly in the constructor.
+* When a TextureSource is destroyed if it's got a canvas texture it's removed from the CanvasPool.
+* TextureManager.checkKey will check if a texture key is in-use and log a console error if it is and then return a boolean. This is now used extensively internally to prevent you from adding textures that already exist into the manager. If you wish to just check if a key is in use without the error, use the `TextureManager.exists` method as before.
+* TextureManager.remove will allow you to remove a texture from the manager. The texture is destroyed and it emits a `removetexture` event.
+* TextureSource has a new property `renderer` as it's used a lot internally and is useful if you extend the class.
+* TextureSource will now remove its respective WebGLTexture from the renderer when destroyed.
+* TextureSource will now automatically create a glTexture from its canvas if using one.
+* WebGLRenderer will now remove a GL texture from its local `nativeTextures` array when you call the `deleteTexture` method.
+* The BaseCache has a new method `exists` that will return a boolean if an entry for the given key exists in the cache or not.
+* Loader.File has a new argument in its constructor which is an instance of the LoaderPlugin. It stores this in the `loader` property. It also has a new property `cache` which is a reference to the cache that the file type will be stored in.
+* Loader.File has a new method `hasCacheConflict` which checks if a key matching the one used by this file exists in the target Cache or not.
+* Loader.File has a new method `addToCache` which will add the file to its target cache and then emit a `filecomplete` event, passing its key and a reference to itself to the listener (thanks to @kalebwalton for a related PR)
+* LoaderPlugin has a new property `cacheManager` which is a reference to the global game cache and is used by the File Types.
+* LoaderPlugin has a new property `textureManager` which is a reference to the global Texture Manager and is used by the File Types.
+* LoaderPlugin will now check to see if loading a file would cache a cache conflict or not, and prevent it if it will.
+* LoaderPlugin now passes off processing of the final file data to the file itself, which will now self-add itself to its target cache.
 
 ### Bug Fixes
 
 * DataManagerPlugin would throw an error on Game.destroy if you had any Scenes in the Scene Manager had not been run. Fix #3596 (thanks @kuoruan)
+* If you created a Game with no Scenes defined, and then added one via `Game.scene.add` and passed in a data object, the data would be ignored when starting the Scene.
 
 ### Examples, Documentation and TypeScript
 
 My thanks to the following for helping with the Phaser 3 Examples, Docs and TypeScript definitions, either by reporting errors, fixing them or helping author the docs:
 
-@wtravO
+@wtravO @Fabadiculous @zilbuz @samme 
 
 ## Version 3.6.0 - Asuna - 19th April 2018
 

src/cache/BaseCache.js

@@ -83,6 +83,7 @@ var BaseCache = new Class({
 
     /**
      * Checks if this cache contains an item matching the given key.
+     * This performs the same action as `BaseCache.exists`.
      *
      * @method Phaser.Cache.BaseCache#has
      * @since 3.0.0
@@ -96,6 +97,22 @@ var BaseCache = new Class({
         return this.entries.has(key);
     },
 
+    /**
+     * Checks if this cache contains an item matching the given key.
+     * This performs the same action as `BaseCache.has` and is called directly by the Loader.
+     *
+     * @method Phaser.Cache.BaseCache#exists
+     * @since 3.7.0
+     *
+     * @param {string} key - The unique key of the item to be checked in this cache.
+     *
+     * @return {boolean} Returns `true` if the cache contains an item matching the given key, otherwise `false`.
+     */
+    exists: function (key)
+    {
+        return this.entries.has(key);
+    },
+
     /**
      * Gets an item from this cache based on the given key.
      *

src/display/canvas/CanvasPool.js

@@ -36,14 +36,16 @@ var CanvasPool = function ()
      * @param {integer} [width=1] - The width of the Canvas.
      * @param {integer} [height=1] - The height of the Canvas.
      * @param {integer} [canvasType=Phaser.CANVAS] - The type of the Canvas. Either `Phaser.CANVAS` or `Phaser.WEBGL`.
+     * @param {boolean} [selfParent=false] - Use the generated Canvas element as the parent?
      *
      * @return {HTMLCanvasElement} [description]
      */
-    var create = function (parent, width, height, canvasType)
+    var create = function (parent, width, height, canvasType, selfParent)
     {
         if (width === undefined) { width = 1; }
         if (height === undefined) { height = 1; }
         if (canvasType === undefined) { canvasType = CONST.CANVAS; }
+        if (selfParent === undefined) { selfParent = false; }
 
         var canvas;
         var container = first(canvasType);
@@ -70,6 +72,11 @@ var CanvasPool = function ()
             canvas = container.canvas;
         }
 
+        if (selfParent)
+        {
+            container.parent = canvas;
+        }
+
         canvas.width = width;
         canvas.height = height;
 

src/display/mask/BitmapMask.js

@@ -191,6 +191,24 @@ var BitmapMask = new Class({
     postRenderCanvas: function ()
     {
         // NOOP
+    },
+
+    /**
+     * Destroys this BitmapMask and nulls any references it holds.
+     * 
+     * Note that if a Game Object is currently using this mask it will _not_ automatically detect you have destroyed it,
+     * so be sure to call `clearMask` on any Game Object using it, before destroying it.
+     *
+     * @method Phaser.Display.Masks.BitmapMask#destroy
+     * @since 3.6.1
+     */
+    destroy: function ()
+    {
+        this.bitmapMask = null;
+        this.mainTexture = null;
+        this.maskTexture = null;
+        this.mainFramebuffer = null;
+        this.maskFramebuffer = null;
     }
 
 });

src/display/mask/GeometryMask.js

@@ -131,6 +131,20 @@ var GeometryMask = new Class({
     postRenderCanvas: function (renderer)
     {
         renderer.currentContext.restore();
+    },
+
+    /**
+     * Destroys this GeometryMask and nulls any references it holds.
+     * 
+     * Note that if a Game Object is currently using this mask it will _not_ automatically detect you have destroyed it,
+     * so be sure to call `clearMask` on any Game Object using it, before destroying it.
+     *
+     * @method Phaser.Display.Masks.GeometryMask#destroy
+     * @since 3.6.1
+     */
+    destroy: function ()
+    {
+        this.geometryMask = null;
     }
 
 });

src/gameobjects/components/GetBounds.js

@@ -196,7 +196,7 @@ var GetBounds = {
      * @method Phaser.GameObjects.Components.GetBounds#getBounds
      * @since 3.0.0
      *
-     * @generic {Phaser.Math.Vector2} O - [output,$return]
+     * @generic {Phaser.Geom.Rectangle} O - [output,$return]
      *
      * @param {(Phaser.Geom.Rectangle|object)} [output] - An object to store the values in. If not provided a new Rectangle will be created.
      *

src/gameobjects/components/Mask.js

@@ -55,10 +55,19 @@ var Mask = {
      * @method Phaser.GameObjects.Components.Mask#clearMask
      * @since 3.6.2
      *
+     * @param {boolean} [destroyMask=false] - Destroy the mask before clearing it?
+     *
      * @return {Phaser.GameObjects.GameObject} This Game Object instance.
      */
-    clearMask: function ()
+    clearMask: function (destroyMask)
     {
+        if (destroyMask === undefined) { destroyMask = false; }
+
+        if (destroyMask)
+        {
+            this.mask.destroy();
+        }
+
         this.mask = null;
 
         return this;

src/gameobjects/components/Texture.js

@@ -20,7 +20,7 @@ var Texture = {
      * The Texture this Game Object is using to render with.
      *
      * @name Phaser.GameObjects.Components.Texture#texture
-     * @type {Phaser.Textures.Texture}
+     * @type {Phaser.Textures.Texture|Phaser.Textures.CanvasTexture}
      * @since 3.0.0
      */
     texture: null,

src/gameobjects/graphics/Graphics.js

@@ -1139,7 +1139,7 @@ var Graphics = new Class({
 
             if (sys.game.renderer.gl && texture)
             {
-                texture.source[0].glTexture = sys.game.renderer.canvasToTexture(ctx.canvas, texture.source[0].glTexture, true, 0);
+                texture.source[0].glTexture = sys.game.renderer.canvasToTexture(ctx.canvas, texture.source[0].glTexture);
             }
         }
 

src/gameobjects/particles/EmitterOp.js

@@ -11,26 +11,81 @@ var GetFastValue = require('../../utils/object/GetFastValue');
 var Wrap = require('../../math/Wrap');
 
 /**
- * The returned value sets what the property will be at the START of the particles life, on emit.
+ * The returned value sets what the property will be at the START of the particle's life, on emit.
  * @callback EmitterOpOnEmitCallback
  *
- * @param {Phaser.GameObjects.Particles.Particle} particle - [description]
- * @param {string} key - [description]
- * @param {number} value - [description]
+ * @param {Phaser.GameObjects.Particles.Particle} particle - The particle.
+ * @param {string} key - The name of the property.
+ * @param {number} value - The current value of the property.
  *
- * @return {number} [description]
+ * @return {number} The new value of the property.
  */
 
 /**
- * The returned value updates the property for the duration of the particles life.
+ * The returned value updates the property for the duration of the particle's life.
  * @callback EmitterOpOnUpdateCallback
  *
- * @param {Phaser.GameObjects.Particles.Particle} particle - [description]
- * @param {string} key - [description]
- * @param {float} t - The T value (between 0 and 1)
- * @param {number} value - [description]
+ * @param {Phaser.GameObjects.Particles.Particle} particle - The particle.
+ * @param {string} key - The name of the property.
+ * @param {float} t - The normalized lifetime of the particle, between 0 (start) and 1 (end).
+ * @param {number} value - The current value of the property.
  *
- * @return {number} [description]
+ * @return {number} The new value of the property.
+ */
+
+/**
+ * Defines an operation yielding a random value within a range.
+ * @typedef {object} EmitterOpRandomConfig
+ *
+ * @property {float[]} random - The minimum and maximum values, as [min, max].
+ */
+
+/**
+ * Defines an operation yielding a random value within a range.
+ * @typedef {object} EmitterOpRandomMinMaxConfig
+ *
+ * @property {float} min - The minimum value.
+ * @property {float} max - The maximum value.
+ */
+
+/**
+ * Defines an operation yielding a random value within a range.
+ * @typedef {object} EmitterOpRandomStartEndConfig
+ *
+ * @property {float} start - The starting value.
+ * @property {float} end - The ending value.
+ * @property {boolean} random - If false, this becomes {@link EmitterOpEaseConfig}.
+ */
+
+/**
+ * Defines an operation yielding a value incremented continuously across a range.
+ * @typedef {object} EmitterOpEaseConfig
+ *
+ * @property {float} start - The starting value.
+ * @property {float} end - The ending value.
+ * @property {string} [ease='Linear'] - The name of the easing function.
+ */
+
+/**
+ * Defines an operation yielding a value incremented by steps across a range.
+ * @typedef {object} EmitterOpSteppedConfig
+ *
+ * @property {number} start - The starting value.
+ * @property {number} end - The ending value.
+ * @property {number} steps - The number of steps between start and end.
+ */
+
+/**
+ * @typedef {object} EmitterOpCustomEmitConfig
+ *
+ * @property {EmitterOpOnEmitCallback} onEmit - [description]
+ */
+
+/**
+ * @typedef {object} EmitterOpCustomUpdateConfig
+ *
+ * @property {EmitterOpOnEmitCallback} [onEmit] - [description]
+ * @property {EmitterOpOnUpdateCallback} onUpdate - [description]
  */
 
 /**
@@ -48,7 +103,10 @@ var Wrap = require('../../math/Wrap');
  * @param {boolean} [emitOnly=false] - [description]
  */
 var EmitterOp = new Class({
-    initialize: function EmitterOp (config, key, defaultValue, emitOnly)
+
+    initialize:
+
+    function EmitterOp (config, key, defaultValue, emitOnly)
     {
         if (emitOnly === undefined)
         {
@@ -247,7 +305,7 @@ var EmitterOp = new Class({
             //  x: 400
 
             this.onEmit = this.staticValueEmit;
-            this.onUpdate = this.staticValueUpdate;
+            this.onUpdate = this.staticValueUpdate; // How?
         }
         else if (Array.isArray(value))
         {
@@ -277,18 +335,12 @@ var EmitterOp = new Class({
                 this.onUpdate = value;
             }
         }
-        else if (
-            t === 'object' &&
-            (this.has(value, 'random') ||
-                this.hasBoth(value, 'start', 'end') ||
-                this.hasBoth(value, 'min', 'max'))
-        )
+        else if (t === 'object' && (this.has(value, 'random') || this.hasBoth(value, 'start', 'end') || this.hasBoth(value, 'min', 'max')))
         {
             this.start = this.has(value, 'start') ? value.start : value.min;
             this.end = this.has(value, 'end') ? value.end : value.max;
 
-            var isRandom =
-                this.hasBoth(value, 'min', 'max') || this.has(value, 'random');
+            var isRandom = (this.hasBoth(value, 'min', 'max') || this.has(value, 'random'));
 
             //  A random starting value (using 'min | max' instead of 'start | end' automatically implies a random value)
 
@@ -336,13 +388,13 @@ var EmitterOp = new Class({
                     this.onEmit = this.easedValueEmit;
                 }
 
+                //  BUG: alpha, rotate, scaleX, scaleY, or tint are eased here if {min, max} is given.
+                //  Probably this branch should exclude isRandom entirely.
+
                 this.onUpdate = this.easeValueUpdate;
             }
         }
-        else if (
-            t === 'object' &&
-            this.hasEither(value, 'onEmit', 'onUpdate')
-        )
+        else if (t === 'object' && this.hasEither(value, 'onEmit', 'onUpdate'))
         {
             //  Custom onEmit and onUpdate callbacks