Added erase method for clearing parts of a Render Texture.

Author: photonstorm

src/gameobjects/rendertexture/RenderTexture.js

@@ -4,6 +4,7 @@
  * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
  */
 
+var BlendModes = require('../../renderer/BlendModes');
 var Camera = require('../../cameras/2d/BaseCamera');
 var CanvasPool = require('../../display/canvas/CanvasPool');
 var Class = require('../../utils/Class');
@@ -188,6 +189,16 @@ var RenderTexture = new Class({
          */
         this._saved = false;
 
+        /**
+         * Internal erase mode flag.
+         *
+         * @name Phaser.GameObjects.RenderTexture#_eraseMode
+         * @type {boolean}
+         * @private
+         * @since 3.16.0
+         */
+        this._eraseMode = false;
+
         /**
          * An internal Camera that can be used to move around the Render Texture.
          * Control it just like you would any Scene Camera. The difference is that it only impacts the placement of what
@@ -464,6 +475,70 @@ var RenderTexture = new Class({
         return this;
     },
 
+    /**
+     * Draws the given object, or an array of objects, to this Render Texture using a blend mode of ERASE.
+     * This has the effect of erasing any filled pixels in the objects from this Render Texture.
+     * 
+     * It can accept any of the following:
+     * 
+     * * Any renderable Game Object, such as a Sprite, Text, Graphics or TileSprite.
+     * * Dynamic and Static Tilemap Layers.
+     * * A Group. The contents of which will be iterated and drawn in turn.
+     * * A Container. The contents of which will be iterated fully, and drawn in turn.
+     * * A Scene's Display List. Pass in `Scene.children` to draw the whole list.
+     * * Another Render Texture.
+     * * A Texture Frame instance.
+     * * A string. This is used to look-up a texture from the Texture Manager.
+     * 
+     * Note: You cannot erase a Render Texture from itself.
+     * 
+     * If passing in a Group or Container it will only draw children that return `true`
+     * when their `willRender()` method is called. I.e. a Container with 10 children,
+     * 5 of which have `visible=false` will only draw the 5 visible ones.
+     * 
+     * If passing in an array of Game Objects it will draw them all, regardless if
+     * they pass a `willRender` check or not.
+     * 
+     * You can pass in a string in which case it will look for a texture in the Texture
+     * Manager matching that string, and draw the base frame.
+     * 
+     * You can pass in the `x` and `y` coordinates to draw the objects at. The use of
+     * the coordinates differ based on what objects are being drawn. If the object is
+     * a Group, Container or Display List, the coordinates are _added_ to the positions
+     * of the children. For all other types of object, the coordinates are exact.
+     * 
+     * Calling this method causes the WebGL batch to flush, so it can write the texture
+     * data to the framebuffer being used internally. The batch is flushed at the end,
+     * after the entries have been iterated. So if you've a bunch of objects to draw,
+     * try and pass them in an array in one single call, rather than making lots of
+     * separate calls.
+     *
+     * @method Phaser.GameObjects.RenderTexture#erase
+     * @since 3.16.0
+     *
+     * @param {any} entries - Any renderable Game Object, or Group, Container, Display List, other Render Texture, Texture Frame or an array of any of these.
+     * @param {number} [x] - The x position to draw the Frame at, or the offset applied to the object.
+     * @param {number} [y] - The y position to draw the Frame at, or the offset applied to the object.
+     *
+     * @return {this} This Render Texture instance.
+     */
+    erase: function (entries, x, y)
+    {
+        this._eraseMode = true;
+
+        var blendMode = this.renderer.currentBlendMode;
+
+        this.renderer.setBlendMode(BlendModes.ERASE);
+
+        this.draw(entries, x, y, 1, 16777215);
+
+        this.renderer.setBlendMode(blendMode);
+
+        this._eraseMode = false;
+
+        return this;
+    },
+
     /**
      * Draws the given object, or an array of objects, to this Render Texture.
      * 
@@ -748,7 +823,10 @@ var RenderTexture = new Class({
         var prevX = gameObject.x;
         var prevY = gameObject.y;
 
-        this.renderer.setBlendMode(gameObject.blendMode);
+        if (!this._eraseMode)
+        {
+            this.renderer.setBlendMode(gameObject.blendMode);
+        }
 
         gameObject.setPosition(x, y);
 
@@ -828,7 +906,19 @@ var RenderTexture = new Class({
 
         if (this.gl)
         {
+            if (this._eraseMode)
+            {
+                var blendMode = this.renderer.currentBlendMode;
+
+                this.renderer.setBlendMode(BlendModes.ERASE);
+            }
+            
             this.pipeline.batchTextureFrame(textureFrame, x, y, tint, alpha, this.camera.matrix, null);
+
+            if (this._eraseMode)
+            {
+                this.renderer.setBlendMode(blendMode);
+            }
         }
         else
         {