WebGLTexture support on filters

Author: David

src/easeljs/filters/AlphaMapFilter.js

@@ -64,12 +64,16 @@ this.createjs = this.createjs || {};
 	 * @class AlphaMapFilter
 	 * @extends Filter
 	 * @constructor
-	 * @param {HTMLImageElement|HTMLCanvasElement} alphaMap The greyscale image (or canvas) to use as the alpha value for the
+	 * @param {HTMLImageElement|HTMLCanvasElement|WebGLTexture} alphaMap The greyscale image (or canvas) to use as the alpha value for the
 	 * result. This should be exactly the same dimensions as the target.
 	 **/
 	function AlphaMapFilter(alphaMap) {
 		this.Filter_constructor();
-	
+
+		if (!Filter.isValidImageSource(alphaMap)) {
+			throw "Must provide valid image source for alpha map, see Filter.isValidImageSource";
+		}
+
 	// public properties:
 		/**
 		 * The greyscale image (or canvas) to use as the alpha value for the result. This should be exactly the same
@@ -107,6 +111,10 @@ this.createjs = this.createjs || {};
 				"gl_FragColor = vec4(color.rgb, color.a * (alphaMap.r * ceil(alphaMap.a)));" +
 			"}"
 		);
+
+		if(alphaMap instanceof WebGLTexture) {
+			this._mapTexture = alphaMap;
+		}
 	}
 	var p = createjs.extend(AlphaMapFilter, createjs.Filter);
 
@@ -120,7 +128,9 @@ this.createjs = this.createjs || {};
 		gl.activeTexture(gl.TEXTURE1);
 		gl.bindTexture(gl.TEXTURE_2D, this._mapTexture);
 		stage.setTextureParams(gl);
-		gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, this.alphaMap);
+		if (this.alphaMap !== this._mapTexture) {
+			gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, this.alphaMap);
+		}
 
 		gl.uniform1i(
 			gl.getUniformLocation(shaderProgram, "uAlphaSampler"),
@@ -148,11 +158,14 @@ this.createjs = this.createjs || {};
 	p._applyFilter = function (imageData) {
 		if (!this.alphaMap) { return true; }
 		if (!this._prepAlphaMap()) { return false; }
-		
-		// TODO: update to support scenarios where the target has different dimensions.
+
 		var data = imageData.data;
 		var map = this._mapData;
-		for(var i=0, l=data.length; i<l; i += 4) { data[i + 3] = map[i] || 0; }
+
+
+		for(var i=0, l=data.length; i<l; i += 4) {
+			data[i + 3] = map[i] || 0;
+		}
 
 		return true;
 	};

src/easeljs/filters/AlphaMaskFilter.js

@@ -64,11 +64,15 @@ this.createjs = this.createjs || {};
 	 * @class AlphaMaskFilter
 	 * @extends Filter
 	 * @constructor
-	 * @param {HTMLImageElement|HTMLCanvasElement} mask
+	 * @param {HTMLImageElement|HTMLCanvasElement|WebGLTexture} mask
 	 **/
 	function AlphaMaskFilter(mask) {
 		this.Filter_constructor();
-	
+
+		if (!Filter.isValidImageSource(mask)) {
+			throw "Must provide valid image source for alpha mask, see Filter.isValidImageSource";
+		}
+
 	// public properties:
 		/**
 		 * The image (or canvas) to use as the mask.
@@ -103,7 +107,9 @@ this.createjs = this.createjs || {};
 		gl.activeTexture(gl.TEXTURE1);
 		gl.bindTexture(gl.TEXTURE_2D, this._mapTexture);
 		stage.setTextureParams(gl);
-		gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, this.mask);
+		if (this.mask !== this._mapTexture) {
+			gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, this.mask);
+		}
 
 		gl.uniform1i(
 			gl.getUniformLocation(shaderProgram, "uAlphaSampler"),

src/easeljs/filters/DisplacementFilter.js

@@ -60,14 +60,14 @@ this.createjs = this.createjs||{};
 	 * @class DisplacementFilter
 	 * @extends Filter
 	 * @constructor
-	 * @param {Image|HTMLCanvasElement} dudvMap The horizontal blur radius in pixels.
+	 * @param {HTMLImageElement|HTMLCanvasElement|WebGLTexture} dudvMap The horizontal blur radius in pixels.
 	 * @param {Number} [distance=0] The absolute value of the maximum possible displacement from the original pixel.
 	 **/
 	function DisplacementFilter(dudvMap, distance) {
 		this.Filter_constructor();
 
-		if (!dudvMap || !(dudvMap instanceof HTMLCanvasElement || dudvMap instanceof Image)) {
-			throw "Must provide valid image source for displacement map (this can be a canvas)";
+		if (!Filter.isValidImageSource(dudvMap)) {
+			throw "Must provide valid image source for displacement map, see Filter.isValidImageSource";
 		}
 
 		// public properties:
@@ -107,11 +107,13 @@ this.createjs = this.createjs||{};
 			"}"
 		);
 
-		if (dudvMap instanceof HTMLCanvasElement) {
+		if(dudvMap instanceof WebGLTexture) {
+			this._mapTexture = dudvMap;
+		} else if (dudvMap instanceof HTMLCanvasElement) {
 			this._dudvCanvas = dudvMap;
 			this._dudvCtx = dudvMap.getContext("2d");
 		} else {
-			var canvas = this._dudvCanvas = document.createElement("canvas");
+			var canvas = this._dudvCanvas = createjs.createCanvas ? createjs.createCanvas() : document.createElement("canvas");
 			canvas.width = dudvMap.width;
 			canvas.height = dudvMap.height;
 			(this._dudvCtx = canvas.getContext("2d")).drawImage(dudvMap);
@@ -128,7 +130,9 @@ this.createjs = this.createjs||{};
 		gl.activeTexture(gl.TEXTURE1);
 		gl.bindTexture(gl.TEXTURE_2D, this._mapTexture);
 		stage.setTextureParams(gl);
-		gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, this.dudvMap);
+		if (this.dudvMap !== this._mapTexture) {
+			gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, this.dudvMap);
+		}
 
 		gl.uniform1i(
 			gl.getUniformLocation(shaderProgram, "uDudvSampler"),

src/easeljs/filters/Filter.js

@@ -55,14 +55,19 @@ this.createjs = this.createjs||{};
 	 * margins that need to be applied in order to fully display the filter. For example, the {{#crossLink "BlurFilter"}}{{/crossLink}}
 	 * will cause an object to feather outwards, resulting in a margin around the shape.
 	 *
+	 * Any filter that consumes an external image stretches the image to cover the cached bounds. If this is an undesired
+	 * visual result, then use an intermediary cache to properly size and layout your data before passing it to a filter.
+	 *
 	 * <h4>EaselJS Filters</h4>
 	 * EaselJS comes with a number of pre-built filters:
 	 * <ul>
+	 *     <li>{{#crossLink "AberrationFilter"}}{{/crossLink}} : Shift the RGB components separately along a given vector</li>
 	 *     <li>{{#crossLink "AlphaMapFilter"}}{{/crossLink}} : Map a greyscale image to the alpha channel of a display object</li>
 	 *     <li>{{#crossLink "AlphaMaskFilter"}}{{/crossLink}}: Map an image's alpha channel to the alpha channel of a display object</li>
 	 *     <li>{{#crossLink "BlurFilter"}}{{/crossLink}}: Apply vertical and horizontal blur to a display object</li>
 	 *     <li>{{#crossLink "ColorFilter"}}{{/crossLink}}: Color transform a display object</li>
 	 *     <li>{{#crossLink "ColorMatrixFilter"}}{{/crossLink}}: Transform an image using a {{#crossLink "ColorMatrix"}}{{/crossLink}}</li>
+	 *     <li>{{#crossLink "DisplacementFilter"}}{{/crossLink}}: Create localized distortions in supplied display object</li>
 	 * </ul>
 	 *
 	 * @class Filter
@@ -106,6 +111,30 @@ this.createjs = this.createjs||{};
 	}
 	var p = Filter.prototype;
 
+// static methods:
+	/**
+	 * Check to see if an image source being provided is one that is valid.
+	 * <h4>Valid Sources:</h4>
+	 * <ul>
+	 *     <li>Image Object</li>
+	 *     <li>HTML Canvas Element</li>
+	 *     <li>`.cacheCanvas` on an object with the same stage</li>
+	 * </ul>
+	 * WebGLTextures CANNOT be shared between multiple WebGL contexts. This means the only safe source for a WebGLTexture
+	 * is an object cached using the same StageGL as the object trying to use it in a filter. This function does not
+	 * enforce that restriction, as it is difficult or expensive to detect. The render will crash or fail to load the
+	 * image data if the rule isn't followed.
+	 * @param {HTMLImageElement|HTMLCanvasElement|WebGLTexture} src The element to check for validity
+	 * @return Boolean Whether the source is valid
+	 */
+	Filter.isValidImageSource = function(src) {
+		return Boolean(src) && (
+			src instanceof Image ||
+			src instanceof WebGLTexture ||
+			src instanceof HTMLCanvasElement
+		);
+	};
+
 // public methods:
 	/**
 	 * Provides padding values for this filter. That is, how much the filter will extend the visual bounds of an object it is applied to.