Filter.addToWorld allows you to quickly create a Phaser.Image object at the given position and size, with the Filter ready applied to it. This can eliminate lots of duplicate code.

Author: photonstorm

README.md

@@ -262,6 +262,7 @@ If you are an exceptional JavaScript developer and would like to join the Phaser
 * Group.resetChild is a new method that allows you to call both `child.reset` and/or `child.loadTexture` on the given child object. This is used internally by `getFirstDead` and similar, but is made public so you can use it as a group iteration callback. Note that the child must have public `reset` and `loadTexture` methods to be valid for the call.
 * Group.getFirstDead, Group.getFirstAlive and Group.getFirstExists all have new optional arguments: `createIfNull`, `x`, `y`, `key` and `frame`. If the method you call cannot find a matching child (i.e. getFirstDead cannot find any dead children) then the optional `createIfNull` allows you to instantly create a new child in the group using the position and texture arguments to do so. This allows you to always get a child back from the Group and remove the need to do null checks and Group inserts from your game code. The same arguments can also be used in a different way: if `createIfNull` is false AND you provide the extra arguments AND a child is found then it will be passed to the new `Group.resetChild` method. This allows you to retrieve a child from the Group and have it reset and instantly ready for use in your game without any extra code.
 * P2.Body.removeCollisionGroup allows you to remove the given CollisionGroup, or array of CollisionGroups, from the list of groups that a body will collide with and updates the collision masks (thanks @Garbanas #2047)
+* Filter.addToWorld allows you to quickly create a Phaser.Image object at the given position and size, with the Filter ready applied to it. This can eliminate lots of duplicate code.
 
 ### Updates
 

src/core/Filter.js

@@ -143,6 +143,60 @@ Phaser.Filter.prototype = {
 
     },
 
+    /**
+    * Creates a new Phaser.Image object using a blank texture and assigns 
+    * this Filter to it. The image is then added to the world.
+    *
+    * If you don't provide width and height values then Filter.width and Filter.height are used.
+    *
+    * If you do provide width and height values then this filter will be resized to match those
+    * values.
+    *
+    * @method Phaser.Filter#addToWorld
+    * @param {number} [x=0] - The x coordinate to place the Image at.
+    * @param {number} [y=0] - The y coordinate to place the Image at.
+    * @param {number} [width] - The width of the Image. If not specified (or null) it will use Filter.width. If specified Filter.width will be set to this value.
+    * @param {number} [height] - The height of the Image. If not specified (or null) it will use Filter.height. If specified Filter.height will be set to this value.
+    * @param {number} [anchorX=0] - Set the x anchor point of the Image. A value between 0 and 1, where 0 is the top-left and 1 is bottom-right.
+    * @param {number} [anchorY=0] - Set the y anchor point of the Image. A value between 0 and 1, where 0 is the top-left and 1 is bottom-right.
+    * @return {Phaser.Image} The newly added Image object.
+    */
+    addToWorld: function (x, y, width, height, anchorX, anchorY) {
+
+        if (anchorX === undefined) { anchorX = 0; }
+        if (anchorY === undefined) { anchorY = 0; }
+
+        if (width !== undefined && width !== null)
+        {
+            this.width = width;
+        }
+        else
+        {
+            width = this.width;
+        }
+
+        if (height !== undefined && height !== null)
+        {
+            this.height = height;
+        }
+        else
+        {
+            height = this.height;
+        }
+
+        var image = this.game.add.image(x, y, '__default');
+
+        image.width = width;
+        image.height = height;
+
+        image.anchor.set(anchorX, anchorY);
+
+        image.filters = [ this ];
+
+        return image;
+
+    },
+
     /**
     * Clear down this Filter and null out references
     * @method Phaser.Filter#destroy

typescript/phaser.d.ts

@@ -1,7 +1,7 @@
 /// <reference path="pixi.d.ts" />
 /// <reference path="p2.d.ts" />
 
-// Type definitions for Phaser 2.4.4+ 2015-Aug-28
+// Type definitions for Phaser 2.4.4+ 2015-Sep-02
 // Project: https://github.com/photonstorm/phaser
 
 declare class Phaser {
@@ -963,6 +963,7 @@ declare module Phaser {
         uniforms: any;
         width: number;
 
+        addToWorld(x?: number, y?: number, width?: number, height?: number, anchorX?: number, anchorY?: number): Phaser.Image;
         apply(frameBuffer: WebGLFramebuffer): void;
         destroy(): void;
         init(...args: any[]): void;