From 9618aaed3cc082341ee9e6f2fee0d4b3e0f465b7 Mon Sep 17 00:00:00 2001
From: David <david@gskinner.com>
Date: Fri, 17 Nov 2017 14:35:29 -0700
Subject: [PATCH 01/39] Minor formatting cleanup

---
 src/easeljs/filters/AlphaMapFilter.js |  1 -
 src/easeljs/filters/BlurFilter.js     |  2 +-
 src/easeljs/filters/Filter.js         | 13 ++++++-------
 3 files changed, 7 insertions(+), 9 deletions(-)

diff --git a/src/easeljs/filters/AlphaMapFilter.js b/src/easeljs/filters/AlphaMapFilter.js
index ee64231e8..4ddb2c24e 100644
--- a/src/easeljs/filters/AlphaMapFilter.js
+++ b/src/easeljs/filters/AlphaMapFilter.js
@@ -79,7 +79,6 @@ this.createjs = this.createjs || {};
 		 **/
 		this.alphaMap = alphaMap;
 		
-		
 	// private properties:
 		/**
 		 * @property _alphaMap
diff --git a/src/easeljs/filters/BlurFilter.js b/src/easeljs/filters/BlurFilter.js
index cc888925f..8230a01dd 100644
--- a/src/easeljs/filters/BlurFilter.js
+++ b/src/easeljs/filters/BlurFilter.js
@@ -163,7 +163,7 @@ this.createjs = this.createjs||{};
 		}
 		return this._compiledShader;
 	};
-	p._setShader = function() { this._compiledShader; };
+	p._setShader = function(value) { this._compiledShader = value; };
 
 	try {
 		Object.defineProperties(p, {
diff --git a/src/easeljs/filters/Filter.js b/src/easeljs/filters/Filter.js
index 045993f8f..ffcc9305a 100644
--- a/src/easeljs/filters/Filter.js
+++ b/src/easeljs/filters/Filter.js
@@ -57,11 +57,12 @@ this.createjs = this.createjs||{};
 	 *
 	 * <h4>EaselJS Filters</h4>
 	 * EaselJS comes with a number of pre-built filters:
-	 * <ul><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>
+	 * <ul>
+	 *     <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>
 	 * </ul>
 	 *
 	 * @class Filter
@@ -89,7 +90,6 @@ this.createjs = this.createjs||{};
 		 * Pre-processed template shader code. It will be parsed before being fed in into the shader compiler.
 		 * This should be based upon StageGL.SHADER_VERTEX_BODY_REGULAR
 		 * @property VTX_SHADER
-		 * @virtual
 		 * @type {String}
 		 * @readonly
 		 */
@@ -99,7 +99,6 @@ this.createjs = this.createjs||{};
 		 * Pre-processed template shader code. It will be parsed before being fed in into the shader compiler.
 		 * This should be based upon StageGL.SHADER_FRAGMENT_BODY_REGULAR
 		 * @property FRAG_SHADER
-		 * @virtual
 		 * @type {String}
 		 * @readonly
 		 */

From 90de64ce78a77b08e7d05d74e68c8453b30b6f7e Mon Sep 17 00:00:00 2001
From: David <david@gskinner.com>
Date: Fri, 17 Nov 2017 14:36:38 -0700
Subject: [PATCH 02/39] ColorMatrix improvements and defaults

---
 src/easeljs/filters/ColorMatrix.js       | 73 +++++++++++++++++++++++-
 src/easeljs/filters/ColorMatrixFilter.js | 23 ++++++--
 2 files changed, 89 insertions(+), 7 deletions(-)

diff --git a/src/easeljs/filters/ColorMatrix.js b/src/easeljs/filters/ColorMatrix.js
index b6279172e..d830a85d3 100644
--- a/src/easeljs/filters/ColorMatrix.js
+++ b/src/easeljs/filters/ColorMatrix.js
@@ -107,6 +107,52 @@ this.createjs = this.createjs||{};
 	ColorMatrix.LENGTH = ColorMatrix.IDENTITY_MATRIX.length;
 
 
+// static methods:
+	/**
+	 * Create an instance of ColorMatrix using the Sepia preset
+	 * @returns {ColorMatrix}
+	 */
+	ColorMatrix.createSepiaPreset = function() {
+		return (new ColorMatrix()).copy([
+			0.4977, 0.9828, 0.1322, 0.0000, 14,
+			0.4977, 0.9828, 0.1322, 0.0000, -14,
+			0.4977, 0.9828, 0.1322, 0.0000, -47,
+			0.0000, 0.0000, 0.0000, 1.0000, 0,
+			0, 0, 0, 0, 1
+		]);
+	};
+
+	/**
+	 * Create an instance of ColorMatrix using an invert color preset
+	 * @returns {ColorMatrix}
+	 */
+	ColorMatrix.createInvertPreset = function() {
+		return (new ColorMatrix()).copy([
+			-1.0000, 0.0000, 0.0000, 0.0000, 255,
+			0.0000, -1.0000, 0.0000, 0.0000, 255,
+			0.0000, 0.0000, -1.0000, 0.0000, 255,
+			0.0000, 0.0000, 0.0000, 1.0000, 0,
+			0, 0, 0, 0, 1
+		]);
+	};
+
+	/**
+	 * Create an instance of ColorMatrix using the Greyscale preset.
+	 * This differs from -100 saturation in that it uses a balanced representation per channel instead of luminance.
+	 * @returns {ColorMatrix}
+	 */
+	ColorMatrix.createGreyscalePreset = function() {
+		return (new ColorMatrix()).copy([
+			0.3333, 0.3334, 0.3333, 0.0000, 0,
+			0.3333, 0.3334, 0.3333, 0.0000, 0,
+			0.3333, 0.3334, 0.3333, 0.0000, 0,
+			0.0000, 0.0000, 0.0000, 1.0000, 0,
+			0, 0, 0, 0, 1
+		]);
+	};
+
+	//TODO: some "fun" filters
+
 // public methods:
 	/**
 	 * Resets the instance with the specified values.
@@ -172,6 +218,24 @@ this.createjs = this.createjs||{};
 		return this;
 	};
 
+	/**
+	 * Adjusts the colour offset of pixel color by adding the specified value to the red, green and blue channels.
+	 * Positive values will make the image brighter, negative values will make it darker.
+	 * @method adjustBrightness
+	 * @param {Number} r A value between -255 & 255 that will be added to the Red channel.
+	 * @param {Number} g A value between -255 & 255 that will be added to the Green channel.
+	 * @param {Number} b A value between -255 & 255 that will be added to the Blue channel.
+	 * @return {ColorMatrix} The ColorMatrix instance the method is called on (useful for chaining calls.)
+	 * @chainable
+	 **/
+	p.adjustOffset = function(r,g,b) {
+		if (isNaN(r) || isNaN(g) || isNaN(b)) { return this; }
+		this[4] = this._cleanValue(this[4] + r,255);
+		this[9] = this._cleanValue(this[9] + g,255);
+		this[14] = this._cleanValue(this[14] + b,255);
+		return this;
+	};
+
 	/**
 	 * Adjusts the contrast of pixel color.
 	 * Positive values will increase contrast, negative values will decrease contrast.
@@ -313,7 +377,13 @@ this.createjs = this.createjs||{};
 	 * @return {String} a string representation of the instance.
 	 **/
 	p.toString = function() {
-		return "[ColorMatrix]";
+		var sz = "";
+		sz += "    "+ this[0].toFixed(4)+", "+this[1].toFixed(4)+", "+this[2].toFixed(4)+", "+this[3].toFixed(4)+", "+(this[4]|0)+",\n";
+		sz += "    "+ this[5].toFixed(4)+", "+this[6].toFixed(4)+", "+this[7].toFixed(4)+", "+this[8].toFixed(4)+", "+(this[9]|0)+",\n";
+		sz += "    "+ this[10].toFixed(4)+", "+this[11].toFixed(4)+", "+this[12].toFixed(4)+", "+this[13].toFixed(4)+", "+(this[14]|0)+",\n";
+		sz += "    "+ this[15].toFixed(4)+", "+this[16].toFixed(4)+", "+this[17].toFixed(4)+", "+this[18].toFixed(4)+", "+(this[19]|0)+",\n";
+		sz += "    "+ (this[20]|0)+", "+(this[21]|0)+", "+(this[22]|0)+", "+(this[23]|0)+", "+(this[24]|0)+"\n";
+		return "[ColorMatrix] {\n"+ sz +"}";
 	};
 
 
@@ -367,6 +437,5 @@ this.createjs = this.createjs||{};
 		return matrix;
 	};
 
-
 	createjs.ColorMatrix = ColorMatrix;
 }());
diff --git a/src/easeljs/filters/ColorMatrixFilter.js b/src/easeljs/filters/ColorMatrixFilter.js
index 6d189f58f..28e4d9b9a 100644
--- a/src/easeljs/filters/ColorMatrixFilter.js
+++ b/src/easeljs/filters/ColorMatrixFilter.js
@@ -56,6 +56,18 @@ this.createjs = this.createjs||{};
 	 *
 	 *      shape.cache(-50, -50, 100, 100);
 	 *
+	 * <h4>Example</h4>
+	 * This example uses a preset to generate a sepia photograph effect
+	 *
+	 *      var shape = new createjs.Shape().set({x:100,y:100});
+	 *      shape.graphics.beginFill("#ff0000").drawCircle(0,0,50);
+	 *
+	 *      shape.filters = [
+	 *          new createjs.ColorMatrixFilter( createjs.ColorMatrix.createSepiaPreset() )
+	 *      ];
+	 *
+	 *      shape.cache(-50, -50, 100, 100);
+	 *
 	 * See {{#crossLink "Filter"}}{{/crossLink}} for an more information on applying filters.
 	 * @class ColorMatrixFilter
 	 * @constructor
@@ -82,11 +94,12 @@ this.createjs = this.createjs||{};
 				"vec4 color = texture2D(uSampler, vRenderCoord);" +
 
 				"mat4 m = uColorMatrix;" +
-				"vec4 newColor = vec4(0,0,0,0);" +
-				"newColor.r = color.r*m[0][0] + color.g*m[0][1] + color.b*m[0][2] + color.a*m[0][3];" +
-				"newColor.g = color.r*m[1][0] + color.g*m[1][1] + color.b*m[1][2] + color.a*m[1][3];" +
-				"newColor.b = color.r*m[2][0] + color.g*m[2][1] + color.b*m[2][2] + color.a*m[2][3];" +
-				"newColor.a = color.r*m[3][0] + color.g*m[3][1] + color.b*m[3][2] + color.a*m[3][3];" +
+				"vec4 newColor = vec4(" +
+					"color.r*m[0][0] + color.g*m[0][1] + color.b*m[0][2] + color.a*m[0][3]," +
+					"color.r*m[1][0] + color.g*m[1][1] + color.b*m[1][2] + color.a*m[1][3]," +
+					"color.r*m[2][0] + color.g*m[2][1] + color.b*m[2][2] + color.a*m[2][3]," +
+					"color.r*m[3][0] + color.g*m[3][1] + color.b*m[3][2] + color.a*m[3][3]" +
+				");" +
 
 				"gl_FragColor = newColor + uColorMatrixOffset;" +
 			"}"

From bf7f91c6017f89994f385ff7e4b0a8f6c81c7741 Mon Sep 17 00:00:00 2001
From: David <david@gskinner.com>
Date: Fri, 17 Nov 2017 14:49:49 -0700
Subject: [PATCH 03/39] Stage invalidation system added, improve performance of
 stages as textures in StageGL

---
 src/easeljs/display/Stage.js   | 19 ++++++++++++++++++-
 src/easeljs/display/StageGL.js | 19 ++++++++++++-------
 2 files changed, 30 insertions(+), 8 deletions(-)

diff --git a/src/easeljs/display/Stage.js b/src/easeljs/display/Stage.js
index 380c1fbea..a6c675ccb 100644
--- a/src/easeljs/display/Stage.js
+++ b/src/easeljs/display/Stage.js
@@ -376,7 +376,24 @@ this.createjs = this.createjs||{};
 		ctx.restore();
 		this.dispatchEvent("drawend");
 	};
-	
+
+	/**
+	 * Draws the stage into the specified context ignoring its visible, alpha, shadow, and transform.
+	 * Returns true if the draw was handled (useful for overriding functionality).
+	 *
+	 * NOTE: This method is mainly for internal use, though it may be useful for advanced uses.
+	 * @method draw
+	 * @param {CanvasRenderingContext2D} ctx The canvas 2D context object to draw into.
+	 * @param {Boolean} [ignoreCache=false] Indicates whether the draw operation should ignore any current cache.
+	 * For example, used for drawing the cache (to prevent it from simply drawing an existing cache back
+	 * into itself).
+	 **/
+	p.draw = function(ctx, ignoreCache) {
+		var result = this.Container_draw(ctx, ignoreCache);
+		this.canvas._invalid = true;
+		return result;
+	};
+
 	/**
 	 * Propagates a tick event through the display list. This is automatically called by {{#crossLink "Stage/update"}}{{/crossLink}}
 	 * unless {{#crossLink "Stage/tickOnUpdate:property"}}{{/crossLink}} is set to false.
diff --git a/src/easeljs/display/StageGL.js b/src/easeljs/display/StageGL.js
index 414a5c35a..bb1dedb88 100644
--- a/src/easeljs/display/StageGL.js
+++ b/src/easeljs/display/StageGL.js
@@ -928,6 +928,8 @@ this.createjs = this.createjs||{};
 
 				this._webGLContext.clearColor(this._clearColor.r, this._clearColor.g, this._clearColor.b, this._clearColor.a);
 				this.updateViewport(this._viewportWidth || this.canvas.width, this._viewportHeight || this.canvas.height);
+
+				this.canvas._invalid = true;
 			}
 		} else {
 			this._webGLContext = null;
@@ -1801,7 +1803,7 @@ this.createjs = this.createjs||{};
 		if (storeID === undefined) {
 			this._textureIDs[srcPath] = storeID = this._textureDictionary.length;
 			image._storeID = storeID;
-			image._invalid = !image.isCanvas;
+			image._invalid = true;
 			texture = this._getSafeTexture();
 			this._textureDictionary[storeID] = texture;
 		} else {
@@ -1863,7 +1865,7 @@ this.createjs = this.createjs||{};
 			}
 		}
 
-		image._invalid = false;
+		if (image._invalid !== undefined) { image._invalid = false; } // only adjust what is tracking this data
 
 		texture._w = image.width;
 		texture._h = image.height;
@@ -1886,6 +1888,7 @@ this.createjs = this.createjs||{};
 	 * @protected
 	 */
 	p._insertTextureInBatch = function (gl, texture) {
+		var image;
 		if (this._batchTextures[texture._activeIndex] !== texture) {	// if it wasn't used last batch
 			// we've got to find it a a spot.
 			var found = -1;
@@ -1910,8 +1913,8 @@ this.createjs = this.createjs||{};
 			// lets put it into that spot
 			this._batchTextures[found] = texture;
 			texture._activeIndex = found;
-			var image = texture._imageData && texture._imageData[0]; // first come first served, potentially problematic
-			if (image && image._invalid) {
+			image = texture._imageData && texture._imageData[0]; // first come first served, potentially problematic
+			if (image && ((image._invalid === undefined && image._isCanvas) || image._invalid)) {
 				this._updateTextureImageData(gl, image);
 			} else {
 				gl.activeTexture(gl.TEXTURE0 + found);
@@ -1920,9 +1923,9 @@ this.createjs = this.createjs||{};
 			}
 			this._lastTextureInsert = found;
 
-		} else if(texture._drawID !== this._drawID) {	// hanging around from previous draws means the content might be out of date
-			var image = texture._imageData && texture._imageData[0];
-			if (image && image._invalid) {
+		} else if(texture._drawID !== this._drawID) {	// being active from previous draws doesn't mean up to date
+			image = texture._imageData && texture._imageData[0];
+			if (image && ((image._invalid === undefined && image._isCanvas) || image._invalid)) {
 				this._updateTextureImageData(gl, image);
 			}
 		}
@@ -2027,7 +2030,9 @@ this.createjs = this.createjs||{};
 
 		this.batchReason = "drawFinish";
 		this._drawBuffers(gl);								// <--------------------------------------------------------
+
 		this._isDrawing--;
+		this.canvas._invalid = true;
 	};
 
 	/**

From 1967fbff267e66b828fcc9b0417441a543fc75f0 Mon Sep 17 00:00:00 2001
From: David <david@gskinner.com>
Date: Fri, 17 Nov 2017 14:50:18 -0700
Subject: [PATCH 04/39] Aberration Filter for shifting colour channels

---
 src/easeljs/filters/AberrationFilter.js | 182 ++++++++++++++++++++++++
 1 file changed, 182 insertions(+)
 create mode 100644 src/easeljs/filters/AberrationFilter.js

diff --git a/src/easeljs/filters/AberrationFilter.js b/src/easeljs/filters/AberrationFilter.js
new file mode 100644
index 000000000..5b1d1c3f9
--- /dev/null
+++ b/src/easeljs/filters/AberrationFilter.js
@@ -0,0 +1,182 @@
+/*
+ * AberrationFilter
+ * Visit http://createjs.com/ for documentation, updates and examples.
+ *
+ * Copyright (c) 2010 gskinner.com, inc.
+ *
+ * Permission is hereby granted, free of charge, to any person
+ * obtaining a copy of this software and associated documentation
+ * files (the "Software"), to deal in the Software without
+ * restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the
+ * Software is furnished to do so, subject to the following
+ * conditions:
+ *
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+ * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+ * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+ * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+ * OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+/**
+ * @module EaselJS
+ */
+
+(function() {
+	"use strict";
+
+
+// constructor:
+	/**
+	 * Seperates and pushes the different colour channels apart.
+	 *
+	 * See {{#crossLink "Filter"}}{{/crossLink}} for an more information on applying filters.
+	 * @class AberrationFilter
+	 * @extends Filter
+	 * @constructor
+	 * @param {Number} [xDir=0] Movement in x, specified in pixels.
+	 * @param {Number} [yDir=0] Movement in y, specified in pixels.
+	 * @param {Number} [redMultiplier=0] Multiplier for movement of the Red channel. Negative values allowed.
+	 * @param {Number} [greenMultiplier=0] Multiplier for movement of the Green channel. Negative values allowed.
+	 * @param {Number} [blueMultiplier=0] Multiplier for movement of the Blue channel. Negative values allowed.
+	 * @param {Number} [originalMix=0] Amount of original image to keep, 0-1.
+	 * @param {Boolean} [alphaMax=false] Calculate combined alpha using maximum value available.
+	 **/
+	function AberrationFilter(xDir, yDir, redMultiplier, greenMultiplier, blueMultiplier, originalMix, alphaMax) {
+		this.Filter_constructor();
+
+		// public properties:
+		this.xDir = Number(xDir) || 0;
+		this.yDir = Number(yDir) || 0;
+
+		this.redMultiplier = Number(redMultiplier) || 0;
+		this.greenMultiplier = Number(greenMultiplier) || 0;
+		this.blueMultiplier = Number(blueMultiplier) || 0;
+
+		this.originalMix = Math.min(Math.max(originalMix, 0), 1) || 0;
+		this._alphaMax = Boolean(alphaMax);
+
+		this.FRAG_SHADER_BODY = (
+			"uniform vec2 uColorDirection;" +
+			"uniform vec3 uColorMultiplier;" +
+			"uniform vec2 uExtraProps;" +
+
+			"void main(void) {" +
+				"vec4 sample = texture2D(" +
+					"uSampler, " +
+					"vRenderCoord" +
+				");" +
+				"vec4 rSample = texture2D(" +
+					"uSampler, " +
+					"vRenderCoord + (uColorDirection * uColorMultiplier.r)" +
+				");" +
+				"vec4 gSample = texture2D(" +
+					"uSampler, " +
+					"vRenderCoord + (uColorDirection * uColorMultiplier.g)" +
+				");" +
+				"vec4 bSample = texture2D(" +
+					"uSampler, " +
+					"vRenderCoord + (uColorDirection * uColorMultiplier.b)" +
+				");" +
+
+				"vec4 result = vec4(" +
+					"rSample.r*rSample.a, " +
+					"gSample.g*gSample.a, " +
+					"bSample.b*bSample.a, " +
+					(alphaMax ?
+							"max(rSample.a, max(gSample.a, max(bSample.a, sample.a)))" :
+							"(rSample.a + gSample.a + bSample.a) / 3.0"
+					) +
+				");" +
+				"gl_FragColor = mix(result, sample, uExtraProps[0]*sample.a);" +
+			"}"
+		);
+
+	}
+	var p = createjs.extend(AberrationFilter, createjs.Filter);
+
+
+// public methods:
+	p.shaderParamSetup = function(gl, stage, shaderProgram) {
+
+		gl.uniform2f(
+			gl.getUniformLocation(shaderProgram, "uColorDirection"),
+			this.xDir*(1/stage._viewportWidth), this.yDir*(1/stage._viewportHeight)
+		);
+
+		gl.uniform3f(
+			gl.getUniformLocation(shaderProgram, "uColorMultiplier"),
+			-this.redMultiplier,
+			-this.greenMultiplier,
+			-this.blueMultiplier
+		);
+
+		gl.uniform2f(
+			gl.getUniformLocation(shaderProgram, "uExtraProps"),
+			this.originalMix, 0
+		);
+	};
+
+// private methods:
+	p._applyFilter = function(imageData) {
+		var refPixels = imageData.data.slice();
+		var outPixels = imageData.data;
+		var width = imageData.width;
+		var height = imageData.height;
+		var offset, pixel;
+
+		for (var i=0; i<height; i++) {
+			offset = i*width;
+			for (var j=0; j<width; j++) {
+				pixel = (offset+j)*4;
+
+				var redX = j+( (this.xDir*-this.redMultiplier) |0), redY = i+( (this.yDir*this.redMultiplier) |0);
+				var grnX = j+( (this.xDir*-this.greenMultiplier) |0), grnY = i+( (this.yDir*this.greenMultiplier) |0);
+				var bluX = j+( (this.xDir*-this.blueMultiplier) |0), bluY = i+( (this.yDir*this.blueMultiplier) |0);
+
+				if (redX < 0) { redX = 0; }
+				if (redX >= width) { redX = width-1; }
+				if (redY < 0) { redY = 0; }
+				if (redY >= height) { redY = height-1; }
+
+				if (grnX < 0) { grnX = 0; }
+				if (grnX >= width) { grnX = width-1; }
+				if (grnY < 0) { grnY = 0; }
+				if (grnY >= height) { grnY = height-1; }
+
+				if (bluX < 0) { bluX = 0; }
+				if (bluX >= width) { bluX = width-1; }
+				if (bluY < 0) { bluY = 0; }
+				if (bluY >= height) { bluY = height-1; }
+
+				var redPixel = ((redY*width)+redX)*4;
+				var grnPixel = ((grnY*width)+grnX)*4;
+				var bluPixel = ((bluY*width)+bluX)*4;
+
+				if(this._alphaMax) {
+					outPixels[pixel] =		refPixels[redPixel];
+					outPixels[pixel+1] =	refPixels[grnPixel+1];
+					outPixels[pixel+2] =	refPixels[bluPixel+2];
+					outPixels[pixel+3] =	refPixels[pixel+3];
+				} else {
+					outPixels[pixel] =		refPixels[redPixel];
+					outPixels[pixel+1] =	refPixels[grnPixel+1];
+					outPixels[pixel+2] =	refPixels[bluPixel+2];
+					outPixels[pixel+3] =	refPixels[pixel+3];
+				}
+			}
+		}
+
+		return true;
+	};
+
+	createjs.AberrationFilter = createjs.promote(AberrationFilter, "Filter");
+}());

From f47adf13b086b258ad41946a4eeff5ce6aef3ef4 Mon Sep 17 00:00:00 2001
From: David <david@gskinner.com>
Date: Fri, 17 Nov 2017 14:50:43 -0700
Subject: [PATCH 05/39] DisplacementFilter for adjust relative pixel positions

---
 src/easeljs/filters/DisplacementFilter.js | 191 ++++++++++++++++++++++
 1 file changed, 191 insertions(+)
 create mode 100644 src/easeljs/filters/DisplacementFilter.js

diff --git a/src/easeljs/filters/DisplacementFilter.js b/src/easeljs/filters/DisplacementFilter.js
new file mode 100644
index 000000000..832029234
--- /dev/null
+++ b/src/easeljs/filters/DisplacementFilter.js
@@ -0,0 +1,191 @@
+/*
+ * DisplacementFilter
+ * Visit http://createjs.com/ for documentation, updates and examples.
+ *
+ * Copyright (c) 2010 gskinner.com, inc.
+ *
+ * Permission is hereby granted, free of charge, to any person
+ * obtaining a copy of this software and associated documentation
+ * files (the "Software"), to deal in the Software without
+ * restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the
+ * Software is furnished to do so, subject to the following
+ * conditions:
+ *
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+ * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+ * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+ * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+ * OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+/**
+ * @module EaselJS
+ */
+
+// namespace:
+this.createjs = this.createjs||{};
+
+(function() {
+	"use strict";
+
+
+// constructor:
+	/**
+	 * Distorts portions of the image, creates effects like computer glitches, bulge/pinch, and pond ripples. This filter
+	 * Uses a reference image/canvas and interprets its r/g channels as a displacement map. A displacement map species
+	 * how far from the original pixel the output pixel should be taken from.
+	 *
+	 * Painting a displacement map means understanding how the r/g channel are interpreted. The red channel changes
+	 * how far in the x to sample, and the green changes how far in the y to sample. The maximum range is -distance to
+	 * +distance ('distance' being the distance value on the filter instance). This maps to the 0-255 color space for
+	 * each channel. This means that for an image to experience no change it should be painted #808000 as that is in the
+	 * middle for both the x and the y displacements.
+	 * <ul>
+	 *     <li>Red values smaller than 0x80 sample from further left, and larger than 0x80 sample form further right.</li>
+	 *     <li>Green values smaller than 0x80 sample from higher up, and larger than 0x80 sample form lower down.</li>
+	 * </ul>
+	 * The output vs input can take some getting used to so experiment! As a tip: when painting to a canvas that
+	 * will act as displacement map, consider using the blend mode of "overlay" or "softlight". These blend modes
+	 * will preserve mid tones (no displacement) while still mixing the high and low values as you might need per channel.
+	 *
+	 * See {{#crossLink "Filter"}}{{/crossLink}} for an more information on applying filters.
+	 * @class DisplacementFilter
+	 * @extends Filter
+	 * @constructor
+	 * @param {Image|HTMLCanvasElement} 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)";
+		}
+
+		// public properties:
+		/**
+		 * The visual source to fetch the displacement map from.
+		 * @property dudvMap
+		 * @type {Image|HTMLCanvasElement}
+		 **/
+		this.dudvMap = dudvMap;
+
+		/**
+		 * The absolute value of the maximum shift in x/y possible.
+		 * @property distance
+		 * @default 128
+		 * @type {Image|HTMLCanvasElement}
+		 **/
+		this.distance = Number(distance);
+		if(isNaN(this.distance)) { this.distance = 128; }
+
+		/**
+		 * This is a template to generate the shader for {{#crossLink FRAG_SHADER_BODY}}{{/crossLink}}
+		 */
+		this.FRAG_SHADER_BODY = (
+			"uniform sampler2D uDudvSampler;"+
+			"uniform float fPower;" +
+			"uniform vec2 pixelAdjustment;" +
+
+			"void main(void) {" +
+				"vec4 dispSample = texture2D(" +
+					"uDudvSampler, " +
+					"vRenderCoord" +
+				");" +
+				"gl_FragColor = texture2D(" +
+					"uSampler, " +
+					"vRenderCoord + (dispSample.xy-0.5)*fPower*pixelAdjustment" +
+				");" +
+			"}"
+		);
+
+		if (dudvMap instanceof HTMLCanvasElement) {
+			this._dudvCanvas = dudvMap;
+			this._dudvCtx = dudvMap.getContext("2d");
+		} else {
+			var canvas = this._dudvCanvas = document.createElement("canvas");
+			canvas.width = dudvMap.width;
+			canvas.height = dudvMap.height;
+			(this._dudvCtx = canvas.getContext("2d")).drawImage(dudvMap);
+		}
+	}
+	var p = createjs.extend(DisplacementFilter, createjs.Filter);
+
+
+// public methods:
+	/** docced in super class **/
+	p.shaderParamSetup = function(gl, stage, shaderProgram) {
+		if (!this._mapTexture) { this._mapTexture = gl.createTexture(); }
+
+		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);
+
+		gl.uniform1i(
+			gl.getUniformLocation(shaderProgram, "uDudvSampler"),
+			1
+		);
+
+		gl.uniform1f(
+			gl.getUniformLocation(shaderProgram, "fPower"),
+			this.distance
+		);
+
+		gl.uniform2f( //this is correct as the color maps to -0.5,0.5. This compounds the pixel delta, thus 2/size
+			gl.getUniformLocation(shaderProgram, "pixelAdjustment"),
+			2/stage._viewportWidth, 2/stage._viewportHeight
+		);
+	};
+
+// private methods:
+	/** docced in super class **/
+	p._applyFilter = function(imageData) {
+		var refPixels = imageData.data.slice();
+		var outPixels = imageData.data;
+		var width = imageData.width;
+		var height = imageData.height;
+		var offset, pixel;
+
+		var dudvData = this._dudvCtx.getImageData(0,0, this.dudvMap.width,this.dudvMap.height);
+		var dudvPixels = dudvData.data;
+		var dudvWidth = dudvData.width;
+		var dudvHeight = dudvData.height;
+		var dudvOffset, dudvPixel;
+
+		for (var i=0; i<height; i++) {
+			offset = i*width;
+			dudvOffset = ((i*(width/dudvWidth)) * dudvWidth) |0;
+			for (var j=0; j<width; j++) {
+				pixel = (offset+j)*4;
+				dudvPixel = (dudvOffset + ((j*(height/dudvHeight)) |0) )*4;
+
+				var xDelta = (((dudvPixels[dudvPixel] - 128)/128)*this.distance) |0;
+				var yDelta = (((dudvPixels[dudvPixel+1] - 128)/128)*this.distance) |0;
+
+				if (j+xDelta < 0) { xDelta = -j; }
+				if (j+xDelta > width) { xDelta = width-j; }
+				if (i+yDelta < 0) { yDelta = -i; }
+				if (i+yDelta > height) { yDelta = height-i; }
+
+				var targetPixel = (pixel + xDelta*4) + yDelta*4*width;
+				outPixels[pixel] =		refPixels[targetPixel];
+				outPixels[pixel+1] =	refPixels[targetPixel+1];
+				outPixels[pixel+2] =	refPixels[targetPixel+2];
+				outPixels[pixel+3] =	refPixels[targetPixel+3];
+			}
+		}
+
+		return true;
+	};
+
+	createjs.DisplacementFilter = createjs.promote(DisplacementFilter, "Filter");
+}());

From 4d58d33fe888adfdc1156e08206defb5875a53f5 Mon Sep 17 00:00:00 2001
From: David <david@gskinner.com>
Date: Tue, 21 Nov 2017 15:45:27 -0700
Subject: [PATCH 06/39] Correct and remove texture flipping logic. NOTE:
 Breaking change for deeper integrations.

---
 src/easeljs/display/StageGL.js            | 92 +++++++----------------
 src/easeljs/filters/AberrationFilter.js   |  8 +-
 src/easeljs/filters/AlphaMapFilter.js     |  2 +-
 src/easeljs/filters/AlphaMaskFilter.js    |  2 +-
 src/easeljs/filters/BlurFilter.js         |  2 +-
 src/easeljs/filters/ColorFilter.js        |  2 +-
 src/easeljs/filters/ColorMatrixFilter.js  |  2 +-
 src/easeljs/filters/DisplacementFilter.js |  4 +-
 8 files changed, 39 insertions(+), 75 deletions(-)

diff --git a/src/easeljs/display/StageGL.js b/src/easeljs/display/StageGL.js
index bb1dedb88..1a29b2d3b 100644
--- a/src/easeljs/display/StageGL.js
+++ b/src/easeljs/display/StageGL.js
@@ -490,9 +490,9 @@ this.createjs = this.createjs||{};
 
 			var r = f.rect;
 			f.uvRect = {
-				t: r.y / f.image.height,
+				t: 1 - (r.y / f.image.height),
 				l: r.x / f.image.width,
-				b: (r.y + r.height) / f.image.height,
+				b: 1 - ((r.y + r.height) / f.image.height),
 				r: (r.x + r.width) / f.image.width
 			};
 		}
@@ -569,7 +569,7 @@ this.createjs = this.createjs||{};
 	 * @default {t:0, l:0, b:1, r:1}
 	 * @readonly
 	 */
-	StageGL.UV_RECT = {t:0, l:0, b:1, r:1};
+	StageGL.UV_RECT = {t:1, l:0, b:0, r:1};
 
 	try {
 		/**
@@ -582,10 +582,10 @@ this.createjs = this.createjs||{};
 		 */
 		StageGL.COVER_VERT = new Float32Array([
 			-1,		 1,		//TL
-			1,		 1,		//TR
+			 1,		 1,		//TR
 			-1,		-1,		//BL
-			1,		 1,		//TR
-			1,		-1,		//BR
+			 1,		 1,		//TR
+			 1,		-1,		//BR
 			-1,		-1		//BL
 		]);
 
@@ -598,12 +598,12 @@ this.createjs = this.createjs||{};
 		 * @readonly
 		 */
 		StageGL.COVER_UV = new Float32Array([
-			 0,		 0,		//TL
-			 1,		 0,		//TR
-			 0,		 1,		//BL
-			 1,		 0,		//TR
-			 1,		 1,		//BR
-			 0,		 1		//BL
+			 0,		 1,		//TL
+			 1,		 1,		//TR
+			 0,		 0,		//BL
+			 1,		 1,		//TR
+			 1,		 0,		//BR
+			 0,		 0		//BL
 		]);
 
 		/**
@@ -615,12 +615,12 @@ this.createjs = this.createjs||{};
 		 * @readonly
 		 */
 		StageGL.COVER_UV_FLIP = new Float32Array([
-			 0,		 1,		//TL
-			 1,		 1,		//TR
-			 0,		 0,		//BL
-			 1,		 1,		//TR
-			 1,		 0,		//BR
-			 0,		 0		//BL
+			 0,		 0,		//TL
+			 1,		 0,		//TR
+			 0,		 1,		//BL
+			 1,		 0,		//TR
+			 1,		 1,		//BR
+			 0,		 1		//BL
 		]);
 	} catch(e) { /* Breaking in older browsers, but those browsers wont run StageGL so no recovery or warning needed */ }
 
@@ -768,7 +768,6 @@ this.createjs = this.createjs||{};
 	StageGL.COVER_VARYING_HEADER = (
 		"precision mediump float;" +
 
-		"varying highp vec2 vRenderCoord;" +
 		"varying highp vec2 vTextureCoord;"
 	);
 
@@ -785,8 +784,7 @@ this.createjs = this.createjs||{};
 	StageGL.COVER_VERTEX_HEADER = (
 		StageGL.COVER_VARYING_HEADER +
 		"attribute vec2 vertexPosition;" +
-		"attribute vec2 uvPosition;" +
-		"uniform float uUpright;"
+		"attribute vec2 uvPosition;"
 	);
 
 	/**
@@ -816,8 +814,7 @@ this.createjs = this.createjs||{};
 	StageGL.COVER_VERTEX_BODY  = (
 		"void main(void) {" +
 			"gl_Position = vec4(vertexPosition.x, vertexPosition.y, 0.0, 1.0);" +
-			"vRenderCoord = uvPosition;" +
-			"vTextureCoord = vec2(uvPosition.x, abs(uUpright - uvPosition.y));" +
+			"vTextureCoord = uvPosition;" +
 		"}"
 	);
 
@@ -832,7 +829,7 @@ this.createjs = this.createjs||{};
 	 */
 	StageGL.COVER_FRAGMENT_BODY = (
 		"void main(void) {" +
-			"vec4 color = texture2D(uSampler, vRenderCoord);" +
+			"vec4 color = texture2D(uSampler, vTextureCoord);" +
 			"gl_FragColor = color;" +
 		"}"
 	);
@@ -924,7 +921,7 @@ this.createjs = this.createjs||{};
 				gl.enable(gl.BLEND);
 				gl.blendFuncSeparate(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA, gl.ONE, gl.ONE_MINUS_SRC_ALPHA);
 				gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, this._premultiply);
-				//gl.pixelStorei(gl.UNPACK_COLORSPACE_CONVERSION_WEBGL, gl.NONE);
+				gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true);
 
 				this._webGLContext.clearColor(this._clearColor.r, this._clearColor.g, this._clearColor.b, this._clearColor.a);
 				this.updateViewport(this._viewportWidth || this.canvas.width, this._viewportHeight || this.canvas.height);
@@ -1258,12 +1255,6 @@ this.createjs = this.createjs||{};
 				0,							0,								1,							0,
 				-1,							1,								0.1,						0
 			]);
-			// create the flipped version for use with render texture flipping
-			// DHG: this would be a slice/clone but some platforms don't offer them for Float32Array
-			this._projectionMatrixFlip = new Float32Array([0,0,0,0, 0,0,0,0, 0,0,0,0, 0,0,0,0]);
-			this._projectionMatrixFlip.set(this._projectionMatrix);
-			this._projectionMatrixFlip[5] *= -1;
-			this._projectionMatrixFlip[13] *= -1;
 		}
 	};
 
@@ -1592,9 +1583,6 @@ this.createjs = this.createjs||{};
 				shaderProgram.samplerUniform = gl.getUniformLocation(shaderProgram, "uSampler");
 				gl.uniform1i(shaderProgram.samplerUniform, 0);
 
-				shaderProgram.uprightUniform = gl.getUniformLocation(shaderProgram, "uUpright");
-				gl.uniform1f(shaderProgram.uprightUniform, 0);
-
 				// if there's some custom attributes be sure to hook them up
 				if (shaderParamSetup) {
 					shaderParamSetup(gl, this, shaderProgram);
@@ -2051,8 +2039,6 @@ this.createjs = this.createjs||{};
 		one drawing directly into the main context and the other drawing into a stored renderTexture respectively.
 		When the draw is a 'filtered' draw, the filters are applied sequentially and will draw into saved textures repeatedly.
 		Once the final filter is done the final output is treated depending upon whether it is a same or unique context.
-		The internal complexity comes from reducing over-draw, shared code, and issues like textures needing to be flipped
-		sometimes when written to render textures.
 		*/
 		var renderTexture;
 		var shaderBackup = this._activeShader;
@@ -2091,7 +2077,6 @@ this.createjs = this.createjs||{};
 				// draw item to render texture		I -> T
 				gl.bindFramebuffer(gl.FRAMEBUFFER, renderTexture._frameBuffer);
 				this.updateViewport(manager._drawWidth, manager._drawHeight);
-				this._projectionMatrix = this._projectionMatrixFlip;
 				gl.clear(gl.COLOR_BUFFER_BIT);
 				this._batchDraw(container, gl, true);
 
@@ -2139,7 +2124,6 @@ this.createjs = this.createjs||{};
 		gl.bindTexture(gl.TEXTURE_2D, renderTexture);
 		this.setTextureParams(gl);
 
-		var flipY = false;
 		var i = 0, filter = filters[i];
 		do { // this is safe because we wouldn't be in apply filters without a filter count of at least 1
 
@@ -2155,19 +2139,13 @@ this.createjs = this.createjs||{};
 			// draw result to render texture	R -> T
 			gl.viewport(0, 0, manager._drawWidth, manager._drawHeight);
 			gl.clear(gl.COLOR_BUFFER_BIT);
-			this._drawCover(gl, flipY);
+			this._drawCover(gl);
 
 			// bind the result texture to slot 0 as all filters and cover draws assume original content is in slot 0
 			gl.activeTexture(gl.TEXTURE0);
 			gl.bindTexture(gl.TEXTURE_2D, renderTexture);
 			this.setTextureParams(gl);
 
-			// use flipping to keep things upright, things already cancel out on a single filter
-			// this needs to be here as multiPass is not accurate to _this_ frame until after shader acquisition
-			if (filterCount > 1 || filters[0]._multiPass) {
-				flipY = !flipY;
-			}
-
 			// work through the multipass if it's there, otherwise move on
 			filter = filter._multiPass !== null ? filter._multiPass : filters[++i];
 		} while (filter);
@@ -2180,19 +2158,8 @@ this.createjs = this.createjs||{};
 			// draw result to canvas			R -> C
 			this._activeShader = this.getFilterShader(this);
 			gl.clear(gl.COLOR_BUFFER_BIT);
-			this._drawCover(gl, flipY);
+			this._drawCover(gl);
 		} else {
-			//TODO: DHG: this is less than ideal. A flipped initial render for this circumstance might help. Adjust the perspective matrix?
-			if (flipY) {
-				gl.activeTexture(gl.TEXTURE0 + lastTextureSlot);
-				renderTexture = this.getTargetRenderTexture(target, manager._drawWidth, manager._drawHeight);
-				gl.bindFramebuffer(gl.FRAMEBUFFER, renderTexture._frameBuffer);
-
-				this._activeShader = this.getFilterShader(this);
-				gl.viewport(0, 0, manager._drawWidth, manager._drawHeight);
-				gl.clear(gl.COLOR_BUFFER_BIT);
-				this._drawCover(gl, !flipY);
-			}
 			gl.bindFramebuffer(gl.FRAMEBUFFER, null);
 			this.updateViewport(wBackup, hBackup);
 
@@ -2317,9 +2284,9 @@ this.createjs = this.createjs||{};
 					if (!item._uvRect) { item._uvRect = {}; }
 					src = item.sourceRect;
 					uvRect = item._uvRect;
-					uvRect.t = (src.y)/image.height;
+					uvRect.t = 1 - ((src.y)/image.height);
 					uvRect.l = (src.x)/image.width;
-					uvRect.b = (src.y + src.height)/image.height;
+					uvRect.b = 1 - ((src.y + src.height)/image.height);
 					uvRect.r = (src.x + src.width)/image.width;
 
 					// calculate vertices
@@ -2436,11 +2403,9 @@ this.createjs = this.createjs||{};
 	 * Draws a card that covers the entire render surface. Mainly used for filters.
 	 * @method _drawBuffers
 	 * @param {WebGLRenderingContext} gl The canvas WebGL context object to draw into.
-	 * @param {Boolean} flipY Covers are used for things like RenderTextures and because of 3D vs Canvas space this can
-	 * end up meaning the `y` space sometimes requires flipping in the render.
 	 * @protected
 	 */
-	p._drawCover = function (gl, flipY) {
+	p._drawCover = function (gl) {
 		if (this._isDrawing > 0) {
 			this._drawBuffers(gl);
 		}
@@ -2460,10 +2425,9 @@ this.createjs = this.createjs||{};
 		gl.bufferSubData(gl.ARRAY_BUFFER, 0, StageGL.COVER_VERT);
 		gl.bindBuffer(gl.ARRAY_BUFFER, uvPositionBuffer);
 		gl.vertexAttribPointer(shaderProgram.uvPositionAttribute, uvPositionBuffer.itemSize, gl.FLOAT, false, 0, 0);
-		gl.bufferSubData(gl.ARRAY_BUFFER, 0, flipY?StageGL.COVER_UV_FLIP:StageGL.COVER_UV);
+		gl.bufferSubData(gl.ARRAY_BUFFER, 0, StageGL.COVER_UV);
 
 		gl.uniform1i(shaderProgram.samplerUniform, 0);
-		gl.uniform1f(shaderProgram.uprightUniform, flipY?0:1);
 
 		gl.drawArrays(gl.TRIANGLES, 0, StageGL.INDICIES_PER_CARD);
 	};
diff --git a/src/easeljs/filters/AberrationFilter.js b/src/easeljs/filters/AberrationFilter.js
index 5b1d1c3f9..d1a2ec2c4 100644
--- a/src/easeljs/filters/AberrationFilter.js
+++ b/src/easeljs/filters/AberrationFilter.js
@@ -72,19 +72,19 @@
 			"void main(void) {" +
 				"vec4 sample = texture2D(" +
 					"uSampler, " +
-					"vRenderCoord" +
+					"vTextureCoord" +
 				");" +
 				"vec4 rSample = texture2D(" +
 					"uSampler, " +
-					"vRenderCoord + (uColorDirection * uColorMultiplier.r)" +
+					"vTextureCoord + (uColorDirection * uColorMultiplier.r)" +
 				");" +
 				"vec4 gSample = texture2D(" +
 					"uSampler, " +
-					"vRenderCoord + (uColorDirection * uColorMultiplier.g)" +
+					"vTextureCoord + (uColorDirection * uColorMultiplier.g)" +
 				");" +
 				"vec4 bSample = texture2D(" +
 					"uSampler, " +
-					"vRenderCoord + (uColorDirection * uColorMultiplier.b)" +
+					"vTextureCoord + (uColorDirection * uColorMultiplier.b)" +
 				");" +
 
 				"vec4 result = vec4(" +
diff --git a/src/easeljs/filters/AlphaMapFilter.js b/src/easeljs/filters/AlphaMapFilter.js
index 4ddb2c24e..681d2b6ce 100644
--- a/src/easeljs/filters/AlphaMapFilter.js
+++ b/src/easeljs/filters/AlphaMapFilter.js
@@ -99,7 +99,7 @@ this.createjs = this.createjs || {};
 			"uniform sampler2D uAlphaSampler;"+
 
 			"void main(void) {" +
-				"vec4 color = texture2D(uSampler, vRenderCoord);" +
+				"vec4 color = texture2D(uSampler, vTextureCoord);" +
 				"vec4 alphaMap = texture2D(uAlphaSampler, vTextureCoord);" +
 
 				// some image formats can have transparent white rgba(1,1,1, 0) when put on the GPU, this means we need a slight tweak
diff --git a/src/easeljs/filters/AlphaMaskFilter.js b/src/easeljs/filters/AlphaMaskFilter.js
index 7a378598c..af5d6bf50 100644
--- a/src/easeljs/filters/AlphaMaskFilter.js
+++ b/src/easeljs/filters/AlphaMaskFilter.js
@@ -84,7 +84,7 @@ this.createjs = this.createjs || {};
 			"uniform sampler2D uAlphaSampler;"+
 
 			"void main(void) {" +
-				"vec4 color = texture2D(uSampler, vRenderCoord);" +
+				"vec4 color = texture2D(uSampler, vTextureCoord);" +
 				"vec4 alphaMap = texture2D(uAlphaSampler, vTextureCoord);" +
 
 				"gl_FragColor = vec4(color.rgb, color.a * alphaMap.a);" +
diff --git a/src/easeljs/filters/BlurFilter.js b/src/easeljs/filters/BlurFilter.js
index 8230a01dd..20bad1404 100644
--- a/src/easeljs/filters/BlurFilter.js
+++ b/src/easeljs/filters/BlurFilter.js
@@ -115,7 +115,7 @@ this.createjs = this.createjs||{};
 
 				"for(int i=0; i<{{blurX}}; i++) {" +
 					"for(int j=0; j<{{blurY}}; j++) {" +
-						"sampleOffset = vRenderCoord + (textureOffset * vec2(float(i)-xAdj, float(j)-yAdj));" +
+						"sampleOffset = vTextureCoord + (textureOffset * vec2(float(i)-xAdj, float(j)-yAdj));" +
 						"color += texture2D(uSampler, sampleOffset) * (xWeight[i] * yWeight[j]);" +
 					"}" +
 				"}" +
diff --git a/src/easeljs/filters/ColorFilter.js b/src/easeljs/filters/ColorFilter.js
index 4fcfa491c..20a7f77ff 100644
--- a/src/easeljs/filters/ColorFilter.js
+++ b/src/easeljs/filters/ColorFilter.js
@@ -135,7 +135,7 @@ this.createjs = this.createjs||{};
 			"uniform vec4 uColorOffset;" +
 
 			"void main(void) {" +
-				"vec4 color = texture2D(uSampler, vRenderCoord);" +
+				"vec4 color = texture2D(uSampler, vTextureCoord);" +
 
 				"gl_FragColor = (color * uColorMultiplier) + uColorOffset;" +
 			"}"
diff --git a/src/easeljs/filters/ColorMatrixFilter.js b/src/easeljs/filters/ColorMatrixFilter.js
index 28e4d9b9a..d88ce3cbd 100644
--- a/src/easeljs/filters/ColorMatrixFilter.js
+++ b/src/easeljs/filters/ColorMatrixFilter.js
@@ -91,7 +91,7 @@ this.createjs = this.createjs||{};
 			"uniform vec4 uColorMatrixOffset;" +
 
 			"void main(void) {" +
-				"vec4 color = texture2D(uSampler, vRenderCoord);" +
+				"vec4 color = texture2D(uSampler, vTextureCoord);" +
 
 				"mat4 m = uColorMatrix;" +
 				"vec4 newColor = vec4(" +
diff --git a/src/easeljs/filters/DisplacementFilter.js b/src/easeljs/filters/DisplacementFilter.js
index 832029234..5f40c766a 100644
--- a/src/easeljs/filters/DisplacementFilter.js
+++ b/src/easeljs/filters/DisplacementFilter.js
@@ -98,11 +98,11 @@ this.createjs = this.createjs||{};
 			"void main(void) {" +
 				"vec4 dispSample = texture2D(" +
 					"uDudvSampler, " +
-					"vRenderCoord" +
+					"vTextureCoord" +
 				");" +
 				"gl_FragColor = texture2D(" +
 					"uSampler, " +
-					"vRenderCoord + (dispSample.xy-0.5)*fPower*pixelAdjustment" +
+					"vTextureCoord + (dispSample.xy-0.5)*fPower*pixelAdjustment" +
 				");" +
 			"}"
 		);

From 8702ba2cbb694f95ef564ac3ea8ef1b8f096063e Mon Sep 17 00:00:00 2001
From: David <david@gskinner.com>
Date: Tue, 21 Nov 2017 16:01:10 -0700
Subject: [PATCH 07/39] Minor code improvements, fixes potentially incorrect
 assumptions about cache

---
 src/easeljs/display/StageGL.js     |  6 +++---
 src/easeljs/filters/BitmapCache.js | 11 ++++++-----
 2 files changed, 9 insertions(+), 8 deletions(-)

diff --git a/src/easeljs/display/StageGL.js b/src/easeljs/display/StageGL.js
index 1a29b2d3b..a81f3296c 100644
--- a/src/easeljs/display/StageGL.js
+++ b/src/easeljs/display/StageGL.js
@@ -1099,7 +1099,7 @@ this.createjs = this.createjs||{};
 	 * Textures in use, or to be used again shortly, should not be removed. This is simply for performance reasons.
 	 * Removing a texture in use will cause the texture to have to be re-uploaded slowing rendering.
 	 * @method releaseTexture
-	 * @param {DisplayObject | Texture | Image | Canvas} item An object that used the texture to be discarded.
+	 * @param {DisplayObject | WebGLTexture | Image | Canvas} item An object that used the texture to be discarded.
 	 * @param {Boolean} safe Should the release attempt to be "safe" and only delete this usage.
 	 */
 	p.releaseTexture = function (item, safe) {
@@ -1349,7 +1349,7 @@ this.createjs = this.createjs||{};
 	 * @method getRenderBufferTexture
 	 * @param  {Number} w The width of the texture in pixels.
 	 * @param  {Number} h The height of the texture in pixels.
-	 * @return {Texture} the basic texture instance with a render buffer property.
+	 * @return {WebGLTexture} the basic texture instance with a render buffer property.
 	 */
 	p.getRenderBufferTexture = function (w, h) {
 		var gl = this._webGLContext;
@@ -1927,7 +1927,7 @@ this.createjs = this.createjs||{};
 	 * {{#crossLink "StageGL/releaseTexture"}}{{/crossLink}} instead as it will call this with the correct texture object(s).
 	 * Note: Testing shows this may not happen immediately, have to wait frames for WebGL to have actually adjust memory.
 	 * @method _killTextureObject
-	 * @param {Texture} texture The texture to be cleaned out
+	 * @param {WebGLTexture} texture The texture to be cleaned out
 	 * @protected
 	 */
 	p._killTextureObject = function (texture) {
diff --git a/src/easeljs/filters/BitmapCache.js b/src/easeljs/filters/BitmapCache.js
index aede25ba2..cc6ca90ec 100644
--- a/src/easeljs/filters/BitmapCache.js
+++ b/src/easeljs/filters/BitmapCache.js
@@ -460,14 +460,13 @@ this.createjs = this.createjs||{};
 				this._webGLCache = this.target.stage;
 
 			} else if(this._options.useGL === "new") {
-				this.target.cacheCanvas = document.createElement("canvas"); // we can turn off autopurge because we wont be making textures here
-				this._webGLCache = new createjs.StageGL(this.target.cacheCanvas, {antialias: true, transparent: true, autoPurge: -1});
+				this.target.cacheCanvas = document.createElement("canvas"); // low autopurge in case of filter swapping and low texture count
+				this._webGLCache = new createjs.StageGL(this.target.cacheCanvas, {antialias: true, transparent: true, autoPurge: 10});
 				this._webGLCache.isCacheControlled = true;	// use this flag to control stage sizing and final output
 
 			} else if(this._options.useGL instanceof createjs.StageGL) {
 				this.target.cacheCanvas = true; // will be replaced with RenderTexture, temporary positive value for old "isCached" checks
 				this._webGLCache = this._options.useGL;
-				this._webGLCache.isCacheControlled = true;	// use this flag to control stage sizing and final output
 
 			} else {
 				throw "Invalid option provided to useGL, expected ['stage', 'new', StageGL, undefined], got "+ this._options.useGL;
@@ -484,12 +483,14 @@ this.createjs = this.createjs||{};
 			surface.height = this._drawHeight;
 			stageGL.updateViewport(this._drawWidth, this._drawHeight);
 		}
+
+		// make surfaces now, instead of potentially expensive texture operations during a render call
 		if (this.target.filters) {
 			// with filters we can't tell how many we'll need but the most we'll ever need is two, so make them now
 			stageGL.getTargetRenderTexture(this.target, this._drawWidth,this._drawHeight);
 			stageGL.getTargetRenderTexture(this.target, this._drawWidth,this._drawHeight);
 		} else {
-			// without filters then we only need one RenderTexture, and that's only if its not a dedicated stage
+			// without filters then we only need one RenderTexture
 			if (!stageGL.isCacheControlled) {
 				stageGL.getTargetRenderTexture(this.target, this._drawWidth,this._drawHeight);
 			}
@@ -506,7 +507,7 @@ this.createjs = this.createjs||{};
 		var target = this.target;
 		var webGL = this._webGLCache;
 
-		if (webGL){
+		if (webGL) {
 			webGL.cacheDraw(target, target.filters, this);
 
 			// we may of swapped around which element the surface is, so we re-fetch it

From 7baae5982da8665e6349cf2a3214599dc627be65 Mon Sep 17 00:00:00 2001
From: David <david@gskinner.com>
Date: Wed, 22 Nov 2017 14:48:09 -0700
Subject: [PATCH 08/39] Fixed issue with Displacement Lookup now flipping
 behaviour is correct

---
 src/easeljs/filters/DisplacementFilter.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/easeljs/filters/DisplacementFilter.js b/src/easeljs/filters/DisplacementFilter.js
index 5f40c766a..fbbd3cb1d 100644
--- a/src/easeljs/filters/DisplacementFilter.js
+++ b/src/easeljs/filters/DisplacementFilter.js
@@ -142,7 +142,7 @@ this.createjs = this.createjs||{};
 
 		gl.uniform2f( //this is correct as the color maps to -0.5,0.5. This compounds the pixel delta, thus 2/size
 			gl.getUniformLocation(shaderProgram, "pixelAdjustment"),
-			2/stage._viewportWidth, 2/stage._viewportHeight
+			2/stage._viewportWidth, -2/stage._viewportHeight
 		);
 	};
 

From 7bd477f2b13c81f24ffea1bfde343a7ecc3b3aec Mon Sep 17 00:00:00 2001
From: David <david@gskinner.com>
Date: Wed, 22 Nov 2017 15:02:11 -0700
Subject: [PATCH 09/39] Stabilize the cacheCanvas in RenderTexture mode to a
 single reliable object, optimize some filter render actions to remove
 avoidable calls

---
 src/easeljs/display/StageGL.js     | 100 ++++++++++++++---------------
 src/easeljs/filters/BitmapCache.js |  47 ++++++--------
 2 files changed, 68 insertions(+), 79 deletions(-)

diff --git a/src/easeljs/display/StageGL.js b/src/easeljs/display/StageGL.js
index a81f3296c..e4daf4503 100644
--- a/src/easeljs/display/StageGL.js
+++ b/src/easeljs/display/StageGL.js
@@ -1044,45 +1044,42 @@ this.createjs = this.createjs||{};
 
 	/**
 	 * Render textures can't draw into themselves so any item being used for renderTextures needs two to alternate between.
-	 * This function creates, gets, and toggles the render surface between the two.
+	 * This function creates, gets, and adjusts the specified render surface.
 	 *
-	 * NOTE: This method is mainly for internal use, though it may be useful for advanced uses.
 	 * @method getTargetRenderTexture
 	 * @param  {DisplayObject} target The object associated with the render textures, usually a cached object.
 	 * @param  {Number} w The width to create the texture at.
 	 * @param  {Number} h The height to create the texture at.
-	 * @return {Objet}
-	 * @todo fill in return type
+	 * @param  {Boolean} [primary=false] Whether this is the primary render surface
+	 * @return {WebGLTexture}
 	 */
-	p.getTargetRenderTexture = function (target, w, h) {
-		var result, toggle = false;
-		var gl = this._webGLContext;
-		if (target.__lastRT !== undefined && target.__lastRT === target.__rtA) { toggle = true; }
-		if (!toggle) {
-			if (target.__rtA === undefined) {
-				target.__rtA = this.getRenderBufferTexture(w, h);
+	p.getTargetRenderTexture = function (target, w, h, primary) {
+		var result, gl = this._webGLContext;
+		if (primary) {
+			result = target._renderTextureOut;
+			if (!result) {
+				result = target._renderTextureOut = this.getRenderBufferTexture(w, h);
 			} else {
-				if (w != target.__rtA._width || h != target.__rtA._height) {
-					this.resizeTexture(target.__rtA, w, h);
+				if (w != result._width || h != result._height) {
+					this.resizeTexture(result, w, h);
 				}
 				this.setTextureParams(gl);
 			}
-			result = target.__rtA;
 		} else {
-			if (target.__rtB === undefined) {
-				target.__rtB = this.getRenderBufferTexture(w, h);
+			result = target._renderTextureTemp;
+			if (!result) {
+				result = target._renderTextureTemp = this.getRenderBufferTexture(w, h);
 			} else {
-				if (w != target.__rtB._width || h != target.__rtB._height) {
-					this.resizeTexture(target.__rtB, w, h);
+				if (w != result._width || h != result._height) {
+					this.resizeTexture(result, w, h);
 				}
 				this.setTextureParams(gl);
 			}
-			result = target.__rtB;
 		}
-		if (!result) {
+
+		if (result == null) {
 			throw "Problems creating render textures, known causes include using too much VRAM by not releasing WebGL texture instances";
 		}
-		target.__lastRT = result;
 		return result;
 	};
 
@@ -2071,7 +2068,7 @@ this.createjs = this.createjs||{};
 				this._batchDraw(container, gl, true);
 			} else {
 				gl.activeTexture(gl.TEXTURE0 + lastTextureSlot);
-				target.cacheCanvas = this.getTargetRenderTexture(target, manager._drawWidth, manager._drawHeight);
+				target.cacheCanvas = this.getTargetRenderTexture(target, manager._drawWidth, manager._drawHeight, true);
 				renderTexture = target.cacheCanvas;
 
 				// draw item to render texture		I -> T
@@ -2105,13 +2102,14 @@ this.createjs = this.createjs||{};
 		var lastTextureSlot = this._maxTextureSlots-1;
 		var wBackup = this._viewportWidth, hBackup = this._viewportHeight;
 
+		var filtersLeft = manager._filterCount;
 		var container = this._cacheContainer;
-		var filterCount = filters.length;
+		var useOut = !(filtersLeft%2); // we have to swap render surface, so start with the one that will make 'out' the last
 
 		// we don't know which texture slot we're dealing with previously and we need one out of the way
 		// once we're using that slot activate it so when we make and bind our RenderTexture it's safe there
 		gl.activeTexture(gl.TEXTURE0 + lastTextureSlot);
-		renderTexture = this.getTargetRenderTexture(target, manager._drawWidth, manager._drawHeight);
+		renderTexture = this.getTargetRenderTexture(target, manager._drawWidth, manager._drawHeight, useOut);
 
 		// draw item to render texture		I -> T
 		gl.bindFramebuffer(gl.FRAMEBUFFER, renderTexture._frameBuffer);
@@ -2126,46 +2124,46 @@ this.createjs = this.createjs||{};
 
 		var i = 0, filter = filters[i];
 		do { // this is safe because we wouldn't be in apply filters without a filter count of at least 1
+			filtersLeft--;
+			useOut = !useOut;
 
 			// swap to correct shader
 			this._activeShader = this.getFilterShader(filter);
 			if (!this._activeShader) { continue; }
 
-			// now the old result is stored in slot 0, make a new render texture
 			gl.activeTexture(gl.TEXTURE0 + lastTextureSlot);
-			renderTexture = this.getTargetRenderTexture(target, manager._drawWidth, manager._drawHeight);
-			gl.bindFramebuffer(gl.FRAMEBUFFER, renderTexture._frameBuffer);
+			renderTexture = this.getTargetRenderTexture(target, manager._drawWidth, manager._drawHeight, useOut);
 
-			// draw result to render texture	R -> T
-			gl.viewport(0, 0, manager._drawWidth, manager._drawHeight);
-			gl.clear(gl.COLOR_BUFFER_BIT);
-			this._drawCover(gl);
+			if (filtersLeft == 0 && this.isCacheControlled) {
+				gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+
+				// draw result to canvas			R -> C
+				this.updateViewport(wBackup, hBackup);
+				gl.clear(gl.COLOR_BUFFER_BIT);
+				this._drawCover(gl);
+
+				return;
 
-			// bind the result texture to slot 0 as all filters and cover draws assume original content is in slot 0
-			gl.activeTexture(gl.TEXTURE0);
-			gl.bindTexture(gl.TEXTURE_2D, renderTexture);
-			this.setTextureParams(gl);
+			} else {
+				gl.bindFramebuffer(gl.FRAMEBUFFER, renderTexture._frameBuffer);
+
+				// draw result to render texture	R -> T
+				gl.viewport(0, 0, manager._drawWidth, manager._drawHeight);
+				gl.clear(gl.COLOR_BUFFER_BIT);
+				this._drawCover(gl);
+
+				// bind the result texture to slot 0 as all filters and cover draws assume original content is in slot 0
+				gl.activeTexture(gl.TEXTURE0);
+				gl.bindTexture(gl.TEXTURE_2D, renderTexture);
+				this.setTextureParams(gl);
+			}
 
 			// work through the multipass if it's there, otherwise move on
 			filter = filter._multiPass !== null ? filter._multiPass : filters[++i];
 		} while (filter);
 
-		// is this for another stage or mine
-		if (this.isCacheControlled) {
-			gl.bindFramebuffer(gl.FRAMEBUFFER, null);
-			this.updateViewport(wBackup, hBackup);
-
-			// draw result to canvas			R -> C
-			this._activeShader = this.getFilterShader(this);
-			gl.clear(gl.COLOR_BUFFER_BIT);
-			this._drawCover(gl);
-		} else {
-			gl.bindFramebuffer(gl.FRAMEBUFFER, null);
-			this.updateViewport(wBackup, hBackup);
-
-			// make sure the last texture is the active thing to draw
-			target.cacheCanvas = renderTexture;
-		}
+		gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+		this.updateViewport(wBackup, hBackup);
 	};
 
 	/**
diff --git a/src/easeljs/filters/BitmapCache.js b/src/easeljs/filters/BitmapCache.js
index cc6ca90ec..1e9b53681 100644
--- a/src/easeljs/filters/BitmapCache.js
+++ b/src/easeljs/filters/BitmapCache.js
@@ -138,6 +138,13 @@ this.createjs = this.createjs||{};
 		this.cacheID = 0;
 
 		// protected:
+		/**
+		 * The number of filters found to process this update, used to optimize some decisions and surfaces
+		 * @type {number}
+		 * @private
+		 */
+		this._filterCount = 0;
+
 		/**
 		 * The relative offset of the filter's x position, used for drawing the cache onto its container.
 		 * Re-calculated every update call before drawing.
@@ -335,6 +342,9 @@ this.createjs = this.createjs||{};
 
 		this._drawWidth = Math.ceil(this.width*this.scale) + filterBounds.width;
 		this._drawHeight = Math.ceil(this.height*this.scale) + filterBounds.height;
+		this._filterCount = this.target.filters.reduce( function (acc, o) {
+			var out = 1; while (o._multiPass) { o = o._multiPass; out++; } return acc + out;
+		}, 0);
 
 		if(!surface || this._drawWidth != surface.width || this._drawHeight != surface.height) {
 			this._updateSurface();
@@ -358,9 +368,8 @@ this.createjs = this.createjs||{};
 		if (this._webGLCache) {
 			// if it isn't cache controlled clean up after yourself
 			if (!this._webGLCache.isCacheControlled) {
-				if (this.__lastRT){ this.__lastRT = undefined; }
-				if (this.__rtA){ this._webGLCache._killTextureObject(this.__rtA); }
-				if (this.__rtB){ this._webGLCache._killTextureObject(this.__rtB); }
+				if (this._renderTextureOut){ this._webGLCache._killTextureObject(this._renderTextureOut); }
+				if (this._renderTextureTemp){ this._webGLCache._killTextureObject(this._renderTextureTemp); }
 				if (this.target && this.target.cacheCanvas){ this._webGLCache._killTextureObject(this.target.cacheCanvas); }
 			}
 			// set the context to none and let the garbage collector get the rest when the canvas itself gets removed
@@ -451,50 +460,39 @@ this.createjs = this.createjs||{};
 		// create it if it's missing
 		if (!this._webGLCache) {
 			if (this._options.useGL === "stage") {
+				// use the stage that this object belongs on as the WebGL context
 				if(!(this.target.stage && this.target.stage.isWebGL)){
 					var error = "Cannot use 'stage' for cache because the object's parent stage is ";
 					error += this.target.stage ? "non WebGL." : "not set, please addChild to the correct stage.";
 					throw error;
 				}
-				this.target.cacheCanvas = true; // will be replaced with RenderTexture, temporary positive value for old "isCached" checks
 				this._webGLCache = this.target.stage;
+				this.target.cacheCanvas = this._webGLCache.getTargetRenderTexture(this.target, this._drawWidth,this._drawHeight, true);
 
 			} else if(this._options.useGL === "new") {
+				// create a new WebGL context to run this cache
 				this.target.cacheCanvas = document.createElement("canvas"); // low autopurge in case of filter swapping and low texture count
 				this._webGLCache = new createjs.StageGL(this.target.cacheCanvas, {antialias: true, transparent: true, autoPurge: 10});
 				this._webGLCache.isCacheControlled = true;	// use this flag to control stage sizing and final output
 
 			} else if(this._options.useGL instanceof createjs.StageGL) {
-				this.target.cacheCanvas = true; // will be replaced with RenderTexture, temporary positive value for old "isCached" checks
+				// use the provided WebGL context to run this cache, trust the user it works and is configured.
 				this._webGLCache = this._options.useGL;
+				this.target.cacheCanvas = this._webGLCache.getTargetRenderTexture(this.target, this._drawWidth,this._drawHeight, true);
 
 			} else {
 				throw "Invalid option provided to useGL, expected ['stage', 'new', StageGL, undefined], got "+ this._options.useGL;
 			}
 		}
 
-		// now size render surfaces
-		surface = this.target.cacheCanvas;
+		// if we have a dedicated stage we've got to size it
 		var stageGL = this._webGLCache;
-
-		// if we have a dedicated stage we've gotta size it
 		if (stageGL.isCacheControlled) {
+			surface = this.target.cacheCanvas;
 			surface.width = this._drawWidth;
 			surface.height = this._drawHeight;
 			stageGL.updateViewport(this._drawWidth, this._drawHeight);
 		}
-
-		// make surfaces now, instead of potentially expensive texture operations during a render call
-		if (this.target.filters) {
-			// with filters we can't tell how many we'll need but the most we'll ever need is two, so make them now
-			stageGL.getTargetRenderTexture(this.target, this._drawWidth,this._drawHeight);
-			stageGL.getTargetRenderTexture(this.target, this._drawWidth,this._drawHeight);
-		} else {
-			// without filters then we only need one RenderTexture
-			if (!stageGL.isCacheControlled) {
-				stageGL.getTargetRenderTexture(this.target, this._drawWidth,this._drawHeight);
-			}
-		}
 	};
 
 	/**
@@ -509,12 +507,6 @@ this.createjs = this.createjs||{};
 
 		if (webGL) {
 			webGL.cacheDraw(target, target.filters, this);
-
-			// we may of swapped around which element the surface is, so we re-fetch it
-			surface = this.target.cacheCanvas;
-
-			surface.width = this._drawWidth;
-			surface.height = this._drawHeight;
 		} else {
 			var ctx = surface.getContext("2d");
 
@@ -529,7 +521,6 @@ this.createjs = this.createjs||{};
 			target.draw(ctx, true);
 			ctx.restore();
 
-
 			if (target.filters && target.filters.length) {
 				this._applyFilters(ctx);
 			}

From 90e15178e1136215f493601d88f3fdc077cbb204 Mon Sep 17 00:00:00 2001
From: David <david@gskinner.com>
Date: Fri, 24 Nov 2017 09:22:27 -0700
Subject: [PATCH 10/39] WebGLTexture support on filters

---
 src/easeljs/filters/AlphaMapFilter.js     | 25 ++++++++++++++-----
 src/easeljs/filters/AlphaMaskFilter.js    | 12 +++++++---
 src/easeljs/filters/DisplacementFilter.js | 16 ++++++++-----
 src/easeljs/filters/Filter.js             | 29 +++++++++++++++++++++++
 4 files changed, 67 insertions(+), 15 deletions(-)

diff --git a/src/easeljs/filters/AlphaMapFilter.js b/src/easeljs/filters/AlphaMapFilter.js
index 681d2b6ce..02b6aa591 100644
--- a/src/easeljs/filters/AlphaMapFilter.js
+++ b/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;
 	};
diff --git a/src/easeljs/filters/AlphaMaskFilter.js b/src/easeljs/filters/AlphaMaskFilter.js
index af5d6bf50..0e2226757 100644
--- a/src/easeljs/filters/AlphaMaskFilter.js
+++ b/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"),
diff --git a/src/easeljs/filters/DisplacementFilter.js b/src/easeljs/filters/DisplacementFilter.js
index fbbd3cb1d..c8590e02d 100644
--- a/src/easeljs/filters/DisplacementFilter.js
+++ b/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"),
diff --git a/src/easeljs/filters/Filter.js b/src/easeljs/filters/Filter.js
index ffcc9305a..842e540c8 100644
--- a/src/easeljs/filters/Filter.js
+++ b/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.

From 4ab360d7af432ffdc5011ee869d4e86e74a32369 Mon Sep 17 00:00:00 2001
From: Lanny McNie <lannymcnie@users.noreply.github.com>
Date: Wed, 8 Nov 2017 11:35:32 -0700
Subject: [PATCH 11/39] Minor doc fix

---
 src/easeljs/display/SpriteSheet.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/easeljs/display/SpriteSheet.js b/src/easeljs/display/SpriteSheet.js
index d6acfa5b1..ad7597ad8 100644
--- a/src/easeljs/display/SpriteSheet.js
+++ b/src/easeljs/display/SpriteSheet.js
@@ -193,7 +193,7 @@ this.createjs = this.createjs||{};
 	 * You can get around this by setting `crossOrigin` property on your images before passing them to EaselJS, or
 	 * setting the `crossOrigin` property on PreloadJS' LoadQueue or LoadItems.
 	 *
-	 * 		var image = new Image();
+	 * 		var img = new Image();
 	 * 		img.crossOrigin="Anonymous";
 	 * 		img.src = "http://server-with-CORS-support.com/path/to/image.jpg";
 	 *

From 4bfeb40d15a8e0925ab5827aac06f7de3dc11d32 Mon Sep 17 00:00:00 2001
From: Sebastian DeRossi <sebastian@gskinner.com>
Date: Tue, 21 Nov 2017 08:44:40 -0700
Subject: [PATCH 12/39] Fixed minor typo on getBounds in BitmapCache

---
 src/easeljs/filters/BitmapCache.js | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/src/easeljs/filters/BitmapCache.js b/src/easeljs/filters/BitmapCache.js
index 1e9b53681..93d704b0e 100644
--- a/src/easeljs/filters/BitmapCache.js
+++ b/src/easeljs/filters/BitmapCache.js
@@ -45,16 +45,16 @@ this.createjs = this.createjs||{};
 	 *
 	 * Caching in this context is purely visual, and will render the DisplayObject out into an image to be used instead
 	 * of the object. The actual cache itself is still stored on the target with the {{#crossLink "DisplayObject/cacheCanvas:property"}}{{/crossLink}}.
-	 * Working with a singular image like a {{#crossLink "Bitmap"}}{{/crossLink}} there is little benefit to performing 
-	 * a cache as it is already a single image. Caching is best done on containers containing multiple complex parts that 
-	 * do not move often, so that rendering the image instead will improve overall rendering speed. A cached object will 
-	 * not visually update until explicitly told to do so with a call to update, much like a Stage. If a cache is being 
+	 * Working with a singular image like a {{#crossLink "Bitmap"}}{{/crossLink}} there is little benefit to performing
+	 * a cache as it is already a single image. Caching is best done on containers containing multiple complex parts that
+	 * do not move often, so that rendering the image instead will improve overall rendering speed. A cached object will
+	 * not visually update until explicitly told to do so with a call to update, much like a Stage. If a cache is being
 	 * updated every frame it is likely not improving rendering performance. Cache are best used when updates will be sparse.
 	 *
-	 * Caching is also a co-requisite for applying filters to prevent expensive filters running constantly without need, 
-	 * and to physically enable some effects. The BitmapCache is also responsible for applying filters to objects and 
-	 * reads each {{#crossLink "Filter"}}{{/crossLink}} due to this relationship. Real-time Filters are not recommended 
-	 * performance wise when dealing with a Context2D canvas. For best performance and to still allow for some visual 
+	 * Caching is also a co-requisite for applying filters to prevent expensive filters running constantly without need,
+	 * and to physically enable some effects. The BitmapCache is also responsible for applying filters to objects and
+	 * reads each {{#crossLink "Filter"}}{{/crossLink}} due to this relationship. Real-time Filters are not recommended
+	 * performance wise when dealing with a Context2D canvas. For best performance and to still allow for some visual
 	 * effects use a compositeOperation when possible.
 	 * @class BitmapCache
 	 * @constructor
@@ -426,7 +426,7 @@ this.createjs = this.createjs||{};
 	 */
 	p.getBounds = function() {
 		var scale = this.scale;
-		return this._boundRect.setValue(
+		return this._boundRect.setValues(
 			this._filterOffX/scale,		this._filterOffY/scale,
 			this.width/scale,			this.height/scale
 		);

From 9c76117220a1ea7f569ae32fab36e0e590608480 Mon Sep 17 00:00:00 2001
From: David <david@gskinner.com>
Date: Tue, 28 Nov 2017 14:03:05 -0700
Subject: [PATCH 13/39] cleanup

---
 src/easeljs/display/StageGL.js | 89 ++++++++--------------------------
 1 file changed, 20 insertions(+), 69 deletions(-)

diff --git a/src/easeljs/display/StageGL.js b/src/easeljs/display/StageGL.js
index e4daf4503..9a01ddccf 100644
--- a/src/easeljs/display/StageGL.js
+++ b/src/easeljs/display/StageGL.js
@@ -48,6 +48,14 @@ this.createjs = this.createjs||{};
  * 		combined and paired these are a shader "program"
  * Texture: WebGL representation of image data and associated extra information
  * Slot: A space on the GPU into which textures can be loaded for use in a batch, using "ActiveTexture" switches texture slot.
+ *
+ * Notes:
+ *
+ * - WebGL treats 0,0 as the bottom left, as such there's a lot of co-ordinate space flipping to make regular canvas
+ * 		numbers make sense to users and WebGL simultaneously. This extends to textures stored in memory too.
+ * - Older versions had distinct internal paths for filters and regular draws, these have been merged.
+ * - Draws are slowly assembled out of found content. Overflowing things like shaders, object/texture count will cause
+ * 		an early draw before continuing. Lookout for the things that force a draw (marked with <------------------------
  */
 
 (function () {
@@ -605,23 +613,6 @@ this.createjs = this.createjs||{};
 			 1,		 0,		//BR
 			 0,		 0		//BL
 		]);
-
-		/**
-		 * Flipped U/V for {{#crossLink "StageGL:COVER_VERT:property"}}{{/crossLink}}.
-		 * @property COVER_UV_FLIP
-		 * @static
-		 * @final
-		 * @type {Float32Array}
-		 * @readonly
-		 */
-		StageGL.COVER_UV_FLIP = new Float32Array([
-			 0,		 0,		//TL
-			 1,		 0,		//TR
-			 0,		 1,		//BL
-			 1,		 0,		//TR
-			 1,		 1,		//BR
-			 0,		 1		//BL
-		]);
 	} catch(e) { /* Breaking in older browsers, but those browsers wont run StageGL so no recovery or warning needed */ }
 
 	/**
@@ -684,15 +675,7 @@ this.createjs = this.createjs||{};
 	 */
 	StageGL.REGULAR_VERTEX_BODY  = (
 		"void main(void) {" +
-			//DHG TODO: This doesn't work. Must be something wrong with the hand built matrix see js... bypass for now
-			//vertexPosition, round if flag
-			//"gl_Position = pMatrix * vec4(vertexPosition.x, vertexPosition.y, 0.0, 1.0);" +
-			"gl_Position = vec4("+
-				"(vertexPosition.x * pMatrix[0][0]) + pMatrix[3][0]," +
-				"(vertexPosition.y * pMatrix[1][1]) + pMatrix[3][1]," +
-				"pMatrix[3][2]," +
-				"1.0" +
-			");" +
+			"gl_Position = pMatrix * vec4(vertexPosition.x, vertexPosition.y, 0.0, 1.0);" +
 			"alphaValue = objectAlpha;" +
 			"indexPicker = textureIndex;" +
 			"vTextureCoord = uvPosition;" +
@@ -731,30 +714,6 @@ this.createjs = this.createjs||{};
 		"}"
 	);
 
-	//TODO: DHG: a real particle shader
-	/**
-	 * @property PARTICLE_VERTEX_BODY
-	 * @todo
-	 * @final
-	 * @static
-	 * @type {String}
-	 * @readonly
-	 */
-	StageGL.PARTICLE_VERTEX_BODY = (
-		StageGL.REGULAR_VERTEX_BODY
-	);
-	/**
-	 * @property PARTICLE_FRAGMENT_BODY
-	 * @todo
-	 * @final
-	 * @static
-	 * @type {String}
-	 * @readonly
-	 */
-	StageGL.PARTICLE_FRAGMENT_BODY = (
-		StageGL.REGULAR_FRAGMENT_BODY
-	);
-
 	/**
 	 * Portion of the shader that contains the "varying" properties required in both vertex and fragment shaders. The
 	 * cover shader is designed to be a simple vertex/uv only texture render that covers the render surface. Shader
@@ -903,7 +862,7 @@ this.createjs = this.createjs||{};
 				var options = {
 					depth: false, // Disable the depth buffer as it isn't used.
 					alpha: this._transparent, // Make the canvas background transparent.
-					stencil: true,
+					stencil: false, // while there's uses for this, we're not using any yet
 					antialias: this._antialias,
 					premultipliedAlpha: this._premultiply, // Assume the drawing buffer contains colors with premultiplied alpha.
 					preserveDrawingBuffer: this._preserveBuffer
@@ -920,10 +879,11 @@ this.createjs = this.createjs||{};
 				gl.disable(gl.DEPTH_TEST);
 				gl.enable(gl.BLEND);
 				gl.blendFuncSeparate(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA, gl.ONE, gl.ONE_MINUS_SRC_ALPHA);
+				gl.clearColor(this._clearColor.r, this._clearColor.g, this._clearColor.b, this._clearColor.a);
 				gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, this._premultiply);
 				gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true);
 
-				this._webGLContext.clearColor(this._clearColor.r, this._clearColor.g, this._clearColor.b, this._clearColor.a);
+
 				this.updateViewport(this._viewportWidth || this.canvas.width, this._viewportHeight || this.canvas.height);
 
 				this.canvas._invalid = true;
@@ -1248,9 +1208,9 @@ this.createjs = this.createjs||{};
 			// additionally we offset into they Y so the polygons are inside the camera's "clipping" plane
 			this._projectionMatrix = new Float32Array([
 				2 / this._viewportWidth,	0,								0,							0,
-				0,							-2 / this._viewportHeight,		1,							0,
+				0,							-2 / this._viewportHeight,		0,							0,
 				0,							0,								1,							0,
-				-1,							1,								0.1,						0
+				-1,							1,								0,							1
 			]);
 		}
 	};
@@ -1533,14 +1493,6 @@ this.createjs = this.createjs||{};
 				targetVtx = StageGL.COVER_VERTEX_HEADER + (customVTX || StageGL.COVER_VERTEX_BODY);
 				targetFrag = StageGL.COVER_FRAGMENT_HEADER + (customFRAG || StageGL.COVER_FRAGMENT_BODY);
 				break;
-			case "particle": //TODO
-				targetVtx = StageGL.REGULAR_VERTEX_HEADER + StageGL.PARTICLE_VERTEX_BODY;
-				targetFrag = StageGL.REGULAR_FRAGMENT_HEADER + StageGL.PARTICLE_FRAGMENT_BODY;
-				break;
-			case "override":
-				targetVtx = StageGL.REGULAR_VERTEX_HEADER + (customVTX || StageGL.REGULAR_VERTEX_BODY);
-				targetFrag = StageGL.REGULAR_FRAGMENT_HEADER + (customFRAG || StageGL.REGULAR_FRAGMENT_BODY);
-				break;
 			case "regular":
 			default:
 				targetVtx = StageGL.REGULAR_VERTEX_HEADER + StageGL.REGULAR_VERTEX_BODY;
@@ -1557,7 +1509,6 @@ this.createjs = this.createjs||{};
 		gl.attachShader(shaderProgram, vertexShader);
 		gl.attachShader(shaderProgram, fragmentShader);
 		gl.linkProgram(shaderProgram);
-		shaderProgram._type = shaderName;
 
 		// check compile status
 		if (!gl.getProgramParameter(shaderProgram, gl.LINK_STATUS)) {
@@ -1604,7 +1555,7 @@ this.createjs = this.createjs||{};
 				gl.enableVertexAttribArray(shaderProgram.alphaAttribute);
 
 				var samplers = [];
-				for (var i = 0; i < this._batchTextureCount; i++) {
+					for (var i = 0; i < this._batchTextureCount; i++) {
 					samplers[i] = i;
 				}
 
@@ -1658,10 +1609,10 @@ this.createjs = this.createjs||{};
 	/**
 	 * Sets up the necessary vertex property buffers, including position and U/V.
 	 * @method _createBuffers
-	 * @param {WebGLRenderingContext} gl
 	 * @protected
 	 */
-	p._createBuffers = function (gl) {
+	p._createBuffers = function () {
+		var gl = this._webGLContext;
 		var groupCount = this._maxCardsPerBatch * StageGL.INDICIES_PER_CARD;
 		var groupSize, i, l;
 
@@ -1753,7 +1704,7 @@ this.createjs = this.createjs||{};
 		// fill in blanks as it helps the renderer be stable while textures are loading and reduces need for safety code
 		for (var i=0; i<this._batchTextureCount;i++) {
 			var texture = this.getBaseTexture();
-			this._baseTextures[i] = this._batchTextures[i] = texture;
+				this._baseTextures[i] = this._batchTextures[i] = texture;
 			if (!texture) {
 				throw "Problems creating basic textures, known causes include using too much VRAM by not releasing WebGL texture instances";
 			} else {
@@ -1852,8 +1803,8 @@ this.createjs = this.createjs||{};
 
 		if (image._invalid !== undefined) { image._invalid = false; } // only adjust what is tracking this data
 
-		texture._w = image.width;
-		texture._h = image.height;
+		texture.width = image.width;
+		texture.height = image.height;
 
 		if (this.vocalDebug) {
 			if (isNPOT && this._antialias) {

From 12038d34d886c2bcd0225b4db561a4525ae91e6a Mon Sep 17 00:00:00 2001
From: David <david@gskinner.com>
Date: Tue, 28 Nov 2017 14:05:19 -0700
Subject: [PATCH 14/39] reorganize texture batching to account for potentially
 reserved surfaces and reserve drawing buffer for rendering

---
 src/easeljs/display/StageGL.js | 281 ++++++++++++++++-----------------
 1 file changed, 140 insertions(+), 141 deletions(-)

diff --git a/src/easeljs/display/StageGL.js b/src/easeljs/display/StageGL.js
index 9a01ddccf..0ffcea25e 100644
--- a/src/easeljs/display/StageGL.js
+++ b/src/easeljs/display/StageGL.js
@@ -263,6 +263,8 @@ this.createjs = this.createjs||{};
 		 */
 		this._activeShader = null;
 
+		this._mainShader = null;
+
 		/**
 		 * The vertex position data for the current draw call.
 		 * @property _vertices
@@ -335,6 +337,8 @@ this.createjs = this.createjs||{};
 		 */
 		this._alphaBuffer = null;
 
+		this._outTexture = null;
+
 		/**
 		 * An index based lookup of every WebGL Texture currently in use.
 		 * @property _drawTexture
@@ -369,30 +373,41 @@ this.createjs = this.createjs||{};
 		this._baseTextures = [];
 
 		/**
-		 * The number of concurrent textures the GPU can handle. This value is dynamically set from WebGL during initialization
-		 * via `gl.getParameter(gl.MAX_TEXTURE_IMAGE_UNITS)`. The WebGL spec states that the lowest guaranteed value is 8,
-		 * but it could be higher. Do not set this value higher than the value returned by the GPU. Setting it lower will
-		 * probably reduce performance, but may be advisable to reserve slots for custom filter work.
-		 * NOTE: Can also act as a length for {{#crossLink "StageGL/_batchTextures:property"}}.
-		 * @property _batchTextureCount
-		 * @protected
-		 * @type {Number}
-		 * @default 8
+		 * Texture slots for a draw
 		 */
-		this._batchTextureCount = 8;
+		this._gpuTextureCount = 8;
 
 		/**
-		 * The location at which the last texture was inserted into a GPU slot in {{#crossLink "StageGL/_batchTextures:property"}}{{/crossLink}}.
-		 * Manual control of this variable can yield improvements in performance by intelligently replacing textures
-		 * inside a batch to reduce texture re-load. It is impossible to write automated general use code, as it requires
-		 * display list look ahead inspection and/or render foreknowledge.
-		 * @property _lastTextureInsert
-		 * @protected
-		 * @type {Number}
-		 * @default -1
+		 * Texture slots on the hardware
+		 */
+		this._gpuTextureMax = 8;
+
+		/**
+		 * Number of texture slots being reserved by StageGL for filters and effect drawing
+		 */
+		this._textureDrawReserve = -1;
+
+		/**
+		 * Number of texture slots being reserved by StageGL for drawing into
+		 */
+		this._textureTrackReserve = -1;
+
+		/**
+		 * Texture slots in a batch for User textures
+		 */
+		this._batchTextureCount = 0;
+
+		/**
+		 * Texture slots available for User textures
+		 */
+		this._freeTextureCount = 0;
+
+		/**
+		 * The location at which the last texture was inserted into a GPU slot
 		 */
 		this._lastTextureInsert = -1;
 
+
 		/**
 		 * The current batch being drawn, A batch consists of a call to `drawElements` on the GPU. Many of these calls
 		 * can occur per draw.
@@ -871,11 +886,6 @@ this.createjs = this.createjs||{};
 				var gl = this._webGLContext = this._fetchWebGLContext(this.canvas, options);
 				if (!gl) { return null; }
 
-				this.updateSimultaneousTextureCount(gl.getParameter(gl.MAX_TEXTURE_IMAGE_UNITS));
-				this._maxTextureSlots = gl.getParameter(gl.MAX_COMBINED_TEXTURE_IMAGE_UNITS);
-				this._createBuffers(gl);
-				this._initTextures(gl);
-
 				gl.disable(gl.DEPTH_TEST);
 				gl.enable(gl.BLEND);
 				gl.blendFuncSeparate(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA, gl.ONE, gl.ONE_MINUS_SRC_ALPHA);
@@ -883,8 +893,11 @@ this.createjs = this.createjs||{};
 				gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, this._premultiply);
 				gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true);
 
+				this._createBuffers();
+				this._initMaterials();
 
 				this.updateViewport(this._viewportWidth || this.canvas.width, this._viewportHeight || this.canvas.height);
+				this._outTexture = this.getRenderBufferTexture(this._viewportWidth, this._viewportHeight);
 
 				this.canvas._invalid = true;
 			}
@@ -902,7 +915,6 @@ this.createjs = this.createjs||{};
 		if (!this.canvas) { return; }
 		if (this.tickOnUpdate) { this.tick(props); }
 		this.dispatchEvent("drawstart");
-		if (this.autoClear) { this.clear(); }
 
 		if (this._webGLContext) {
 			// Use WebGL.
@@ -912,6 +924,7 @@ this.createjs = this.createjs||{};
 			}
 		} else {
 			// Use 2D.
+			if (this.autoClear) { this.clear(); }
 			var ctx = this.canvas.getContext("2d");
 			ctx.save();
 			this.updateContext(ctx);
@@ -996,7 +1009,7 @@ this.createjs = this.createjs||{};
 	 * @param  {Boolean} [lock=false] Whether this slot is the one being locked.
 	 */
 	p.protectTextureSlot = function (id, lock) {
-		if (id > this._maxTextureSlots || id < 0) {
+		if (id > this._freeTextureCount || id < 0) {
 			throw "Slot outside of acceptable range";
 		}
 		this._slotBlacklist[id] = !!lock;
@@ -1150,43 +1163,6 @@ this.createjs = this.createjs||{};
 		}
 	};
 
-	/**
-	 * Try to set the max textures the system can handle. It should default to the hardware maximum, and lower values
-	 * may limit performance. Some devices have been known to mis-report their max textures, or you may need a standard
-	 * baseline cross devices for testing. Barring the previous suggestions, there is little need to call this function
-	 * as the library will automatically try to find the best value.
-	 *
-	 * NOTE: This method is mainly for internal use, though it may be useful for advanced uses.
-	 * @method updateSimultaneousTextureCount
-	 * @param {Number} [count=1] The number of textures intended for simultaneous loading.
-	 */
-	p.updateSimultaneousTextureCount = function (count) {
-		// TODO: DHG: make sure API works in all instances, may be some issues with buffers etc I haven't foreseen
-		var gl = this._webGLContext;
-		var success = false;
-
-		if (count < 1 || isNaN(count)) { count = 1; }
-		this._batchTextureCount = count;
-
-		while (!success) {
-			try {
-				this._activeShader = this._fetchShaderProgram(gl);
-				success = true;
-			} catch(e) {
-				if (this._batchTextureCount == 1) {
-					throw "Cannot compile shader " + e;
-				}
-
-				this._batchTextureCount -= 4;
-				if (this._batchTextureCount < 1) { this._batchTextureCount = 1; }
-
-				if (this.vocalDebug) {
-					console.log("Reducing desired texture count due to errors: " + this._batchTextureCount);
-				}
-			}
-		}
-	};
-
 	/**
 	 * Update the WebGL viewport. Note that this does <strong>not</strong> update the canvas element's width/height, but
 	 * the render surface's instead. This is necessary after manually resizing the canvas element on the DOM to avoid a
@@ -1212,6 +1188,10 @@ this.createjs = this.createjs||{};
 				0,							0,								1,							0,
 				-1,							1,								0,							1
 			]);
+
+			if (this._outTexture !== null) {
+				this.resizeTexture(this._outTexture, this._viewportWidth, this._viewportHeight);
+			}
 		}
 	};
 
@@ -1237,7 +1217,7 @@ this.createjs = this.createjs||{};
 		} else {
 			try {
 				targetShader = this._fetchShaderProgram(
-					gl, "filter",
+					"cover",
 					filter.VTX_SHADER_BODY, filter.FRAG_SHADER_BODY,
 					filter.shaderParamSetup && filter.shaderParamSetup.bind(filter)
 				);
@@ -1472,8 +1452,7 @@ this.createjs = this.createjs||{};
 	 * filters. Once compiled, shaders are saved so. If the Shader code requires dynamic alterations re-run this function
 	 * to generate a new shader.
 	 * @method _fetchShaderProgram
-	 * @param  {WebGLRenderingContext} gl The canvas WebGL context object to draw into.
-	 * @param  {String} [shaderName="regular"] Working values: "regular", "override", and "filter". Which type of shader to build.
+	 * @param  {Boolean} [coverShader=false] Is this a per object or a texture cover shader
 	 * Filter and override both accept the custom params. Regular and override have all features. Filter is a special case reduced feature shader meant to be over-ridden.
 	 * @param  {String} [customVTX] Extra vertex shader information to replace a regular draw, see 
 	 * {{#crossLink "StageGL/COVER_VERTEX_BODY"}}{{/crossLink}} for default and {{#crossLink "Filter"}}{{/crossLink}} for examples.
@@ -1483,21 +1462,19 @@ this.createjs = this.createjs||{};
 	 * @protected
 	 * @return {WebGLProgram} The compiled and linked shader
 	 */
-	p._fetchShaderProgram = function (gl, shaderName, customVTX, customFRAG, shaderParamSetup) {
+	p._fetchShaderProgram = function (coverShader, customVTX, customFRAG, shaderParamSetup) {
+		var gl = this._webGLContext;
+
 		gl.useProgram(null);		// safety to avoid collisions
 
 		// build the correct shader string out of the right headers and bodies
 		var targetFrag, targetVtx;
-		switch (shaderName) {
-			case "filter":
-				targetVtx = StageGL.COVER_VERTEX_HEADER + (customVTX || StageGL.COVER_VERTEX_BODY);
-				targetFrag = StageGL.COVER_FRAGMENT_HEADER + (customFRAG || StageGL.COVER_FRAGMENT_BODY);
-				break;
-			case "regular":
-			default:
-				targetVtx = StageGL.REGULAR_VERTEX_HEADER + StageGL.REGULAR_VERTEX_BODY;
-				targetFrag = StageGL.REGULAR_FRAGMENT_HEADER + StageGL.REGULAR_FRAGMENT_BODY;
-				break;
+		if (coverShader) {
+			targetVtx = StageGL.COVER_VERTEX_HEADER + (customVTX || StageGL.COVER_VERTEX_BODY);
+			targetFrag = StageGL.COVER_FRAGMENT_HEADER + (customFRAG || StageGL.COVER_FRAGMENT_BODY);
+		} else {
+			targetVtx = StageGL.REGULAR_VERTEX_HEADER + (customVTX || StageGL.REGULAR_VERTEX_BODY);
+			targetFrag = StageGL.REGULAR_FRAGMENT_HEADER + (customFRAG || StageGL.REGULAR_FRAGMENT_BODY);
 		}
 
 		// create the separate vars
@@ -1518,53 +1495,40 @@ this.createjs = this.createjs||{};
 
 		// set up the parameters on the shader
 		gl.useProgram(shaderProgram);
-		switch (shaderName) {
-			case "filter":
-				// get the places in memory the shader is stored so we can feed information into them
-				// then save it off on the shader because it's so tied to the shader itself
-				shaderProgram.vertexPositionAttribute = gl.getAttribLocation(shaderProgram, "vertexPosition");
-				gl.enableVertexAttribArray(shaderProgram.vertexPositionAttribute);
-
-				shaderProgram.uvPositionAttribute = gl.getAttribLocation(shaderProgram, "uvPosition");
-				gl.enableVertexAttribArray(shaderProgram.uvPositionAttribute);
-
-				shaderProgram.samplerUniform = gl.getUniformLocation(shaderProgram, "uSampler");
-				gl.uniform1i(shaderProgram.samplerUniform, 0);
-
-				// if there's some custom attributes be sure to hook them up
-				if (shaderParamSetup) {
-					shaderParamSetup(gl, this, shaderProgram);
-				}
-				break;
-			case "override":
-			case "particle":
-			case "regular":
-			default:
-				// get the places in memory the shader is stored so we can feed information into them
-				// then save it off on the shader because it's so tied to the shader itself
-				shaderProgram.vertexPositionAttribute = gl.getAttribLocation(shaderProgram, "vertexPosition");
-				gl.enableVertexAttribArray(shaderProgram.vertexPositionAttribute);
-
-				shaderProgram.uvPositionAttribute = gl.getAttribLocation(shaderProgram, "uvPosition");
-				gl.enableVertexAttribArray(shaderProgram.uvPositionAttribute);
-
-				shaderProgram.textureIndexAttribute = gl.getAttribLocation(shaderProgram, "textureIndex");
-				gl.enableVertexAttribArray(shaderProgram.textureIndexAttribute);
-
-				shaderProgram.alphaAttribute = gl.getAttribLocation(shaderProgram, "objectAlpha");
-				gl.enableVertexAttribArray(shaderProgram.alphaAttribute);
-
-				var samplers = [];
-					for (var i = 0; i < this._batchTextureCount; i++) {
-					samplers[i] = i;
-				}
 
-				shaderProgram.samplerData = samplers;
-				shaderProgram.samplerUniform = gl.getUniformLocation(shaderProgram, "uSampler");
-				gl.uniform1iv(shaderProgram.samplerUniform, samplers);
+		// get the places in memory the shader is stored so we can feed information into them
+		// then save it off on the shader because it's so tied to the shader itself
+		shaderProgram.vertexPositionAttribute = gl.getAttribLocation(shaderProgram, "vertexPosition");
+		gl.enableVertexAttribArray(shaderProgram.vertexPositionAttribute);
+
+		shaderProgram.uvPositionAttribute = gl.getAttribLocation(shaderProgram, "uvPosition");
+		gl.enableVertexAttribArray(shaderProgram.uvPositionAttribute);
 
-				shaderProgram.pMatrixUniform = gl.getUniformLocation(shaderProgram, "pMatrix");
-				break;
+		if (coverShader) {
+			shaderProgram.samplerUniform = gl.getUniformLocation(shaderProgram, "uSampler");
+			gl.uniform1i(shaderProgram.samplerUniform, 0);
+
+			// if there's some custom attributes be sure to hook them up
+			if (shaderParamSetup) {
+				shaderParamSetup(gl, this, shaderProgram);
+			}
+		} else {
+			shaderProgram.textureIndexAttribute = gl.getAttribLocation(shaderProgram, "textureIndex");
+			gl.enableVertexAttribArray(shaderProgram.textureIndexAttribute);
+
+			shaderProgram.alphaAttribute = gl.getAttribLocation(shaderProgram, "objectAlpha");
+			gl.enableVertexAttribArray(shaderProgram.alphaAttribute);
+
+			var samplers = [];
+			for (var i = 0; i < this._gpuTextureCount; i++) {
+				samplers[i] = i;
+			}
+
+			shaderProgram.samplerData = samplers;
+			shaderProgram.samplerUniform = gl.getUniformLocation(shaderProgram, "uSampler");
+			gl.uniform1iv(shaderProgram.samplerUniform, samplers);
+
+			shaderProgram.pMatrixUniform = gl.getUniformLocation(shaderProgram, "pMatrix");
 		}
 
 		gl.useProgram(this._activeShader);
@@ -1581,13 +1545,15 @@ this.createjs = this.createjs||{};
 	 * @protected
 	 */
 	p._createShader = function (gl, type, str) {
+		var count = this._batchTextureCount || this._gpuTextureCount;
+
 		// inject the static number
-		str = str.replace(/\{\{count}}/g, this._batchTextureCount);
+		str = str.replace(/\{\{count}}/g, count);
 
 		// resolve issue with no dynamic samplers by creating correct samplers in if else chain
 		// TODO: WebGL 2.0 does not need this support
 		var insert = "";
-		for (var i = 1; i<this._batchTextureCount; i++) {
+		for (var i = 1; i<count; i++) {
 			insert += "} else if (indexPicker <= "+ i +".5) { color = texture2D(uSampler["+ i +"], vTextureCoord);";
 		}
 		str = str.replace(/\{\{alternates}}/g, insert);
@@ -1685,12 +1651,12 @@ this.createjs = this.createjs||{};
 	};
 
 	/**
-	 * Do all the setup steps for textures in the system.
-	 * @method _initTextures
+	 * Do all the setup steps for standard textures & shaders.
+	 * @method _initMaterials
 	 * @protected
 	 */
-	p._initTextures = function () {
-		//TODO: DHG: add a cleanup routine in here in case this happens mid stream
+	p._initMaterials = function () {
+		var gl = this._webGLContext;
 
 		// reset counters
 		this._lastTextureInsert = -1;
@@ -1701,16 +1667,43 @@ this.createjs = this.createjs||{};
 		this._baseTextures = [];
 		this._batchTextures = [];
 
-		// fill in blanks as it helps the renderer be stable while textures are loading and reduces need for safety code
-		for (var i=0; i<this._batchTextureCount;i++) {
-			var texture = this.getBaseTexture();
-				this._baseTextures[i] = this._batchTextures[i] = texture;
-			if (!texture) {
-				throw "Problems creating basic textures, known causes include using too much VRAM by not releasing WebGL texture instances";
-			} else {
-				texture._storeID = -1;
+		this._gpuTextureCount = gl.getParameter(gl.MAX_TEXTURE_IMAGE_UNITS); // this is what we can draw with
+		this._gpuTextureMax = gl.getParameter(gl.MAX_COMBINED_TEXTURE_IMAGE_UNITS); // this could be higher
+
+		var success = false;
+		while (!success) {
+			try {
+				this._fetchShaderProgram();
+				success = true;
+			} catch(e) {
+				if (this._gpuTextureCount <= 1) { throw "Cannot compile shader " + e; }
+				this._gpuTextureCount = (this._gpuTextureCount / 2)|0;
+
+				if (this.vocalDebug) {
+					console.log("Reducing possible texture count due to errors: " + this._gpuTextureCount);
+				}
 			}
 		}
+
+		//TODO: turn into function for dynamic updates
+		this._textureDrawReserve = 0;
+		this._textureTrackReserve = 1;
+
+		this._freeTextureCount = this._gpuTextureMax - this._textureTrackReserve;
+		this._batchTextureCount = Math.min(this._freeTextureCount, this._gpuTextureCount - this._textureDrawReserve);
+
+		this._mainShader = this._activeShader = this._fetchShaderProgram();
+
+		// fill in blanks as it helps the renderer be stable while textures are loading and reduces need for safety code
+		var texture = this.getBaseTexture();
+		if (!texture) {
+			throw "Problems creating basic textures, known causes include using too much VRAM by not releasing WebGL texture instances";
+		} else {
+			texture._storeID = -1;
+		}
+		for (var i=0; i<this._gpuTextureCount; i++) { // use GPU textures count to ensure we have enough
+			this._baseTextures[i] = this._batchTextures[i] = texture;
+		}
 	};
 
 	/**
@@ -1962,12 +1955,21 @@ this.createjs = this.createjs||{};
 		this.batchCardCount = 0;
 		this.depth = 0;
 
+		gl.bindFramebuffer(gl.FRAMEBUFFER, this._outTexture._frameBuffer);
+		if (this.autoClear) { this.clear(); }
 		this._appendToBatchGroup(sceneGraph, gl, new createjs.Matrix2D(), this.alpha, ignoreCache);
 
 		this.batchReason = "drawFinish";
 		this._drawBuffers(gl);								// <--------------------------------------------------------
-
 		this._isDrawing--;
+
+		gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+		gl.activeTexture(gl.TEXTURE0);
+		gl.bindTexture(gl.TEXTURE_2D, this._outTexture);
+		this._activeShader = this.getFilterShader(this);
+		this._drawCover(gl);
+		this._activeShader = this._mainShader;
+
 		this.canvas._invalid = true;
 	};
 
@@ -1991,12 +1993,9 @@ this.createjs = this.createjs||{};
 		var renderTexture;
 		var shaderBackup = this._activeShader;
 		var blackListBackup = this._slotBlacklist;
-		var lastTextureSlot = this._maxTextureSlots-1;
+		var lastTextureSlot = this._freeTextureCount;
 		var wBackup = this._viewportWidth, hBackup = this._viewportHeight;
 
-		// protect the last slot so that we have somewhere to bind the renderTextures so it doesn't get upset
-		this.protectTextureSlot(lastTextureSlot, true);
-
 		// create offset container for drawing item
 		var mtx = target.getMatrix();
 		mtx = mtx.clone();
@@ -2050,7 +2049,7 @@ this.createjs = this.createjs||{};
 	p._drawFilters = function (target, filters, manager) {
 		var gl = this._webGLContext;
 		var renderTexture;
-		var lastTextureSlot = this._maxTextureSlots-1;
+		var lastTextureSlot = this._freeTextureCount;
 		var wBackup = this._viewportWidth, hBackup = this._viewportHeight;
 
 		var filtersLeft = manager._filterCount;

From 9a895157065da382761ac1c120c15b027a42e9a8 Mon Sep 17 00:00:00 2001
From: David <david@gskinner.com>
Date: Wed, 29 Nov 2017 17:06:04 -0700
Subject: [PATCH 15/39] Rewritten drawing loop to add blending modes,
 incomplete. All blend modes not written. Filters do not use new loop yet.

---
 src/easeljs/display/StageGL.js            | 738 ++++++++++++++++------
 src/easeljs/filters/AlphaMapFilter.js     |   2 +-
 src/easeljs/filters/AlphaMaskFilter.js    |   2 +-
 src/easeljs/filters/BitmapCache.js        |   2 +-
 src/easeljs/filters/DisplacementFilter.js |   2 +-
 5 files changed, 560 insertions(+), 186 deletions(-)

diff --git a/src/easeljs/display/StageGL.js b/src/easeljs/display/StageGL.js
index 0ffcea25e..6dae32298 100644
--- a/src/easeljs/display/StageGL.js
+++ b/src/easeljs/display/StageGL.js
@@ -34,8 +34,8 @@ this.createjs = this.createjs||{};
 
 /*
  * README IF EDITING:
- * Terminology for developers:
  *
+ * - Terminology for developers:
  * Vertex: a point that help defines a shape, 3 per triangle. Usually has an x,y,z but can have more/less info.
  * Vertex Property: a piece of information attached to the vertex like a vector3 containing x,y,z
  * Index/Indices: used in groups of 3 to define a triangle, points to vertices by their index in an array (some render
@@ -43,18 +43,20 @@ this.createjs = this.createjs||{};
  * Card: a group of 2 triangles used to display a rectangular image
  * U/V: common names for the [0-1] texture co-ordinates on an image
  * Batch: a single call to the renderer, best done as little as possible so multiple cards are put into a single batch
- * Buffer: WebGL array data
  * Program/Shader: For every vertex we run the Vertex shader. The results are used per pixel by the Fragment shader. When
  * 		combined and paired these are a shader "program"
  * Texture: WebGL representation of image data and associated extra information
  * Slot: A space on the GPU into which textures can be loaded for use in a batch, using "ActiveTexture" switches texture slot.
+ * Render___: actual WebGL draw call
+ * Buffer: WebGL array data
+ * Cover: A card that covers the entire viewport
  *
- * Notes:
- *
- * - WebGL treats 0,0 as the bottom left, as such there's a lot of co-ordinate space flipping to make regular canvas
- * 		numbers make sense to users and WebGL simultaneously. This extends to textures stored in memory too.
- * - Older versions had distinct internal paths for filters and regular draws, these have been merged.
- * - Draws are slowly assembled out of found content. Overflowing things like shaders, object/texture count will cause
+ * - Notes:
+ * WebGL treats 0,0 as the bottom left, as such there's a lot of co-ordinate space flipping to make regular canvas
+ * 		numbers make sense to users and WebGL simultaneously. This extends to textures stored in memory too. If writing
+ * 		code that deals with x/y, be aware your y may be flipped.
+ * Older versions had distinct internal paths for filters and regular draws, these have been merged.
+ * Draws are slowly assembled out of found content. Overflowing things like shaders, object/texture count will cause
  * 		an early draw before continuing. Lookout for the things that force a draw (marked with <------------------------
  */
 
@@ -120,9 +122,6 @@ this.createjs = this.createjs||{};
 	 *  to perform anti-aliasing. This will also enable linear pixel sampling on power-of-two textures (smoother images).
 	 * @param {Boolean} [options.transparent=false] If `true`, the canvas is transparent. This is <strong>very</strong>
 	 * expensive, and should be used with caution.
-	 * @param {Boolean} [options.premultiply=false] Alters color handling. If `true`, this assumes the shader must
-	 * account for pre-multiplied alpha. This can help avoid visual halo effects with some assets, but may also cause
-	 * problems with other assets.
 	 * @param {Integer} [options.autoPurge=1200] How often the system should automatically dump unused textures with
 	 * `purgeTextures(autoPurge)` every `autoPurge/2` draws. See {{#crossLink "StageGL/purgeTextures"}}{{/crossLink}} for more
 	 * information.
@@ -132,7 +131,6 @@ this.createjs = this.createjs||{};
 
 		if (options !== undefined) {
 			if (typeof options !== "object"){ throw("Invalid options object"); }
-			var premultiply = options.premultiply;
 			var transparent = options.transparent;
 			var antialias = options.antialias;
 			var preserveBuffer = options.preserveBuffer;
@@ -179,15 +177,6 @@ this.createjs = this.createjs||{};
 		 */
 		this._transparent = transparent||false;
 
-		/**
-		 * Specifies whether or not StageGL is handling colours as premultiplied alpha.
-		 * @property _premultiply
-		 * @protected
-		 * @type {Boolean}
-		 * @default false
-		 */
-		this._premultiply = premultiply||false;
-
 		/**
 		 * Internal value of {{#crossLink "StageGL/autoPurge"}}{{/crossLink}}
 		 * @property _autoPurge
@@ -262,6 +251,7 @@ this.createjs = this.createjs||{};
 		 * @default null
 		 */
 		this._activeShader = null;
+		this._activeBuffer = null;
 
 		this._mainShader = null;
 
@@ -337,7 +327,11 @@ this.createjs = this.createjs||{};
 		 */
 		this._alphaBuffer = null;
 
-		this._outTexture = null;
+		this._bufferTextureOutput = null;		// what you're drawing to, occasionally swaps with concat
+		this._bufferTextureConcat = null;		// what you've draw before now, occasionally swaps with output
+		this._bufferTextureTemp = null;			// temporary surface for mixing in other objects
+
+		this._builtShaders = {};
 
 		/**
 		 * An index based lookup of every WebGL Texture currently in use.
@@ -407,6 +401,15 @@ this.createjs = this.createjs||{};
 		 */
 		this._lastTextureInsert = -1;
 
+		this._renderMode = "";
+		this._immediateRender = false;
+
+		/**
+		 * Cards drawn into the batch so far.
+		 * @type {number}
+		 * @private
+		 */
+		this._batchCardCount = 0;
 
 		/**
 		 * The current batch being drawn, A batch consists of a call to `drawElements` on the GPU. Many of these calls
@@ -641,7 +644,8 @@ this.createjs = this.createjs||{};
 	 * @readonly
 	 */
 	StageGL.REGULAR_VARYING_HEADER = (
-		"precision mediump float;" +
+		"precision highp float;" +
+
 		"varying vec2 vTextureCoord;" +
 		"varying lowp float indexPicker;" +
 		"varying lowp float alphaValue;"
@@ -715,17 +719,7 @@ this.createjs = this.createjs||{};
 				"{{alternates}}" +
 			"}" +
 
-			"{{fragColor}}" +
-		"}"
-	);
-	StageGL.REGULAR_FRAG_COLOR_NORMAL = (
-		"gl_FragColor = vec4(color.rgb, color.a * alphaValue);"
-	);
-	StageGL.REGULAR_FRAG_COLOR_PREMULTIPLY = (
-		"if(color.a > 0.0035) {" +		// 1/255 = 0.0039, so ignore any value below 1 because it's probably noise
-			"gl_FragColor = vec4(color.rgb/color.a, color.a * alphaValue);" +
-		"} else {" +
-			"gl_FragColor = vec4(0.0, 0.0, 0.0, 0.0);" +
+			"gl_FragColor = vec4(color.rgb, color.a * alphaValue);" +
 		"}"
 	);
 
@@ -740,9 +734,9 @@ this.createjs = this.createjs||{};
 	 * @readonly
 	 */
 	StageGL.COVER_VARYING_HEADER = (
-		"precision mediump float;" +
+		"precision highp float;" +	//this is usually essential for filter math
 
-		"varying highp vec2 vTextureCoord;"
+		"varying vec2 vTextureCoord;"
 	);
 
 	/**
@@ -803,11 +797,301 @@ this.createjs = this.createjs||{};
 	 */
 	StageGL.COVER_FRAGMENT_BODY = (
 		"void main(void) {" +
-			"vec4 color = texture2D(uSampler, vTextureCoord);" +
-			"gl_FragColor = color;" +
+			"gl_FragColor = texture2D(uSampler, vTextureCoord);" +
 		"}"
 	);
 
+	StageGL.BLEND_FRAGMENT_SIMPLE = (
+		"uniform sampler2D uMixSampler;"+
+		"void main(void) {" +
+			"vec4 src = texture2D(uMixSampler, vTextureCoord);" +
+			"vec4 dst = texture2D(uSampler, vTextureCoord);"
+		// note this is an open bracket on main!
+	);
+
+	StageGL.BLEND_FRAGMENT_COMPLEX = (
+		StageGL.BLEND_FRAGMENT_SIMPLE +
+			"vec3 srcClr = min(src.rgb/src.a, 1.0);" +
+			"vec3 dstClr = min(dst.rgb/dst.a, 1.0);" +
+
+			"float totalAlpha = min(1.0 - (1.0-dst.a) * (1.0-src.a), 1.0);" +
+			"float srcFactor = min(max(src.a - dst.a, 0.0) / totalAlpha, 1.0);" +
+			"float dstFactor = min(max(dst.a - src.a, 0.0) / totalAlpha, 1.0);" +
+			"float mixFactor = max(max(1.0 - srcFactor, 0.0) - dstFactor, 0.0);" +
+
+			"gl_FragColor = vec4(" +
+				"(" +
+					"srcFactor * srcClr +" +
+					"dstFactor * dstClr +" +
+					"mixFactor * ("
+		// this should be closed with the cap!
+	);
+	StageGL.BLEND_FRAGMENT_COMPLEX_CAP = (
+					")" +
+				") * totalAlpha, totalAlpha" +
+			");" +
+		"}"
+	);
+
+	StageGL.BLEND_FRAGMENT_OVERLAY_UTIL = (
+		"float overlay(float a, float b) {" +
+			"if(a < 0.5) { return 2.0 * a * b; }" +
+			"return 1.0 - 2.0 * (1.0-a) * (1.0-b);" +
+		"}"
+	);
+
+	StageGL.BLEND_FRAGMENT_HSL_UTIL = (
+		"float lum(vec3 c) { return 0.299*c.r + 0.589*c.g + 0.109*c.b; }" +
+		"float sat(vec3 c) { return max(max(c.r, c.g), c.b) - min(min(c.r, c.g), c.b); }" +
+		"vec3 clipHSL(vec3 c) {" +
+			"float l = lum(c);" +
+			"float n = min(min(c.r, c.g), c.b);" +
+			"float x = max(max(c.r, c.g), c.b);" +
+			"if(n < 0.0){ c = l + (((c - l) * l) / (l - n)); }" +
+			"if(x < 1.0){ c = l + (((c - l) * (1.0 - l)) / (x - l)); }" +
+			"return c;" +
+		"}" +
+		"vec3 setLum(vec3 c, float val) {" +
+			"return clipHSL(c + (val - lum(c)));" +
+		"}" +
+		"vec3 setSat(vec3 c, float val) {" +
+			"bool rxg = c.r > c.g; bool rxb = c.r > c.b; bool gxb = c.g > c.b;" +
+			"vec3 midMask = vec3(0.0); vec3 maxMask = vec3(0.0); vec3 result = vec3(0.0);" +
+			"if(rxg){" +
+				"if(rxb) {" +
+					"maxMask.r = 1.0;" +
+					"if(gxb) {midMask.g = 1.0;} else {midMask.b = 1.0;}" +
+				"} else {" +
+					"maxMask.b = 1.0;" +
+					"midMask.r = 1.0;" +
+				"}" +
+			"} else {" +
+				"if(gxb) {" +
+					"maxMask.g = 1.0;" +
+					"if(rxb) {midMask.r = 1.0;} else {midMask.b = 1.0;}" +
+				"} else {" +
+					"maxMask.b = 1.0;" +
+					"midMask.g = 1.0;" +
+				"}" +
+			"}" +
+			"vec3 minMask = 1.0 - (midMask+maxMask);" +
+			"if(any(greaterThan(c*maxMask, c*minMask))) {" +
+				"result = midMask*( ((c*midMask - c*minMask) * val) / (c*maxMask - c*minMask) );" +
+				"result += maxMask*( val );" +
+			"}" +
+
+			"return result;" +
+		"}"
+	);
+
+	StageGL.BLEND_SOURCES = {
+		"source-over": {																								//YAY
+			non_immediate: true
+			//srcRGB: "ONE",							srcA: "ONE"
+			//dstRGB: "ONE_MINUS_SRC_ALPHA",			dstA: "ONE_MINUS_SRC_ALPHA"
+		},
+		"source-in": {
+			non_immediate: true,
+			srcRGB: "DST_ALPHA",					srcA: "ZERO",
+			dstRGB: "ZERO",							dstA: "SRC_ALPHA"
+		},
+		"source-out": {
+			shader: (StageGL.BLEND_FRAGMENT_SIMPLE +
+				"gl_FragColor = vec4(src.rgb*(1-dst.a), src.a-dst.a); }"
+			)
+		},
+		"source-atop": {
+			shader: (StageGL.BLEND_FRAGMENT_SIMPLE +
+				"gl_FragColor = vec4(src.rgb*src.a + dst.rgb*(1.0-src.a), dst.a); }"
+			)
+		},
+		"destination-over": {
+			shader: (StageGL.BLEND_FRAGMENT_SIMPLE +
+				"gl_FragColor = vec4(src.rgb*(1.0-dst.a) + dst.rgb*dst.a, src.a+dst.a); }"
+			)
+		},
+		"destination-in": {
+			shader: (StageGL.BLEND_FRAGMENT_SIMPLE +
+				"gl_FragColor = vec4(dst.rgb, src.a*dst.a); }"
+			)
+		},
+		"destination-out": {
+			shader: (StageGL.BLEND_FRAGMENT_SIMPLE +
+				"gl_FragColor = vec4(dst.rgb, dst.a*(1.0-src.a)); }"
+			)
+		},
+		"destination-atop": {
+			shader: (StageGL.BLEND_FRAGMENT_SIMPLE +
+				"gl_FragColor = vec4(src.rgb*(1.0-dst.a) + dst.rgb*dst.a, src.a); }"
+			)
+		},
+		"copy": {																										//YAY
+			non_immediate: true,
+			dstRGB: "ZERO",							dstA: "ZERO"
+		},
+
+		"multiply": {																									//YAY
+			shader: (StageGL.BLEND_FRAGMENT_COMPLEX +
+				"srcClr * dstClr"
+			+ StageGL.BLEND_FRAGMENT_COMPLEX_CAP)
+		},
+		"multiply-cheap": {																								//YAY
+			non_immediate: true,
+			srcRGB: "ZERO",							srcA: "ONE",
+			dstRGB: "SRC_COLOR",					dstA: "ONE"
+		},
+		"screen": {																										//YAY
+			shader: (StageGL.BLEND_FRAGMENT_COMPLEX +
+				"1.0 - (1.0 - srcClr) * (1.0 - dstClr)"
+			+ StageGL.BLEND_FRAGMENT_COMPLEX_CAP)
+		},
+		"screen-cheap": {																								//
+			non_immediate: true,
+			srcRGB: "ZERO",							srcA: "ONE",
+			dstRGB: "SRC_COLOR",					dstA: "ONE"
+		},
+		"lighter": {																									//YAY
+			non_immediate: true,
+			dstRGB: "ONE",							dstA:"ONE"
+		},
+		"lighten": {
+			shader: (StageGL.BLEND_FRAGMENT_COMPLEX +
+				"max(src.rgb, dst.rgb) * shared," +
+				"dst.a+src.a); }"
+			)
+		},
+		"darken": {
+			shader: (StageGL.BLEND_FRAGMENT_COMPLEX +
+				"min(src.rgb, dst.rgb) * shared," +
+				"dst.a+src.a); }"
+			)
+		},
+
+		"overlay": {
+			shader: (
+				StageGL.BLEND_FRAGMENT_OVERLAY_UTIL + StageGL.BLEND_FRAGMENT_SIMPLE +
+				"gl_FragColor = vec4(overlay(dst.r,src.r), overlay(dst.g,src.g), overlay(dst.b,src.b), dst.a+src.a); }"
+			)
+		},
+		"hard-light": {
+			shader: (
+				StageGL.BLEND_FRAGMENT_OVERLAY_UTIL + StageGL.BLEND_FRAGMENT_SIMPLE +
+				"gl_FragColor = vec4(overlay(src.r,dst.r), overlay(src.g,dst.g), overlay(src.b,dst.b), dst.a+src.a); }"
+			)
+		},
+		"soft-light": {
+			shader: (
+				"float softcurve(float a) {" +
+				"if(a > 0.25) { return sqrt(a); }" +
+				"return ((16.0 * a - 12.0) * a + 4.0) * a;" +
+				"}" +
+				"float softmix(float a, float b) {" +
+				"if(b <= 0.5) { return a - (1.0 - 2.0*b) * a * (1.0 - a); }" +
+				"return a + (2.0 * b - 1.0) * (softcurve(a) - a);" +
+				"}" + StageGL.BLEND_FRAGMENT_COMPLEX +
+				"vec3(softmix(src.r,dst.r), softmix(src.g,dst.g), softmix(src.b,dst.b)) * shared," +
+				"dst.a+src.a); }"
+			)
+		},
+		"color-dodge": {
+			//shader: (
+			//	"float blendColorDodge(float base, float blend) {" +
+			//		"return (blend==1.0)?blend:min(base/(1.0-blend),1.0);" +
+			//	"}" +
+			//	"vec3 blendColorDodge(vec3 base, vec3 blend) {" +
+			//		"return vec3(blendColorDodge(base.r,blend.r),blendColorDodge(base.g,blend.g),blendColorDodge(base.b,blend.b));" +
+			//	"}" +
+			//	"vec3 blendColorDodge(vec3 base, vec3 blend, float opacity) {" +
+			//		"return (blendColorDodge(base, blend) * opacity + base * (1.0 - opacity));" +
+			//	"}" + StageGL.BLEND_FRAGMENT_SIMPLE +
+			//	"gl_FragColor = vec4(blendColorDodge(dst.rgb, src.rgb, src.a), 1.0); }"
+
+			//shader: (StageGL.BLEND_FRAGMENT_SIMPLE +
+			//	"vec4 color = vec4(0.0, 0.0, 0.0, dst.a+src.a);" +
+
+			//	"if(src.r*src.a >= 0.96) {" +
+			//		"if(dst.r*dst.a >= 0.0035) { color.r = 1.0; } else { color.r = 0.0; }" +
+			//	"} else {" +
+			//		"color.r = clamp(dst.r*dst.a / (1.0-src.r*src.a), 0.0, 1.0);" +
+			//	"}" +
+
+			//	"if(src.g*src.a >= 0.96) {" +
+			//		"if(dst.g*dst.a >= 0.0035) { color.g = 1.0; } else { color.g = 0.0; }" +
+			//	"} else {" +
+			//		"color.g = clamp(dst.g*dst.a / (1.0-src.g*src.a), 0.0, 1.0);" +
+			//	"}" +
+
+			//	"if(src.b*src.a >= 0.96) {" +
+			//		"if(dst.b*dst.a >= 0.0035) { color.b = 1.0; } else { color.b = 0.0; }" +
+			//	"} else {" +
+			//		"color.b = clamp(dst.b*dst.a / (1.0-src.b*src.a), 0.0, 1.0);" +
+			//	"}" +
+
+			//	"gl_FragColor = color; }"
+			//shader: (StageGL.BLEND_FRAGMENT_COMPLEX +
+			//		"((dst.rgb*dst.a) / (1.0-src.rgb*src.a) * shared," +
+			//	"dst.a+src.a); }"
+			shader: (StageGL.BLEND_FRAGMENT_SIMPLE +
+				//"gl_FragColor = vec4(1.0/1.0, 1.0/0.0, 0.0/1.0, 1.0); }"		//1.0, 1.0, 0.0
+				//"gl_FragColor = vec4(0.5/1.0, 0.5/0.0, 0.0/0.5, 1.0); }"		//0.5, 1.0, 0.0
+				//"gl_FragColor = vec4(0.0/1.0, 0.0/0.0, 0.0/0.0, 1.0); }"		//0.0, 0.0, 0.0
+				"gl_FragColor = vec4(0.1/0.0, 1.0/1.0, 0.0/0.0, 1.0); }"		//0.0, 0.0, 0.0
+			)
+		},
+		"color-burn": {
+			shader: (StageGL.BLEND_FRAGMENT_SIMPLE +
+				"gl_FragColor = vec4(0.0, 0.0, 0.0, 1.0); }"
+			)
+		},
+
+		"xor": {
+			shader: (StageGL.BLEND_FRAGMENT_SIMPLE +
+				"gl_FragColor = vec4(src.rgb*src.a + dst.rgb*dst.a, abs(src.a-dst.a)); }"
+			)
+		},
+		"difference": {
+			shader: (StageGL.BLEND_FRAGMENT_SIMPLE +
+				"gl_FragColor = vec4(abs(src.rgb-dst.rgb), src.a+dst.a); }"
+			)
+		},
+		"exclusion": {
+			shader: (StageGL.BLEND_FRAGMENT_COMPLEX +
+				"(src.rgb + dst.rgb - 2.0 * src.rgb * dst.rgb) * shared," +
+				"dst.a+src.a); }"
+			)
+		},
+
+		"hue": {
+			shader: (StageGL.BLEND_FRAGMENT_HSL_UTIL + StageGL.BLEND_FRAGMENT_COMPLEX +
+				" * shared," +
+				"dst.a+src.a); }"
+			)
+		},
+		"saturation": {
+			shader: (StageGL.BLEND_FRAGMENT_HSL_UTIL + StageGL.BLEND_FRAGMENT_COMPLEX +
+				" * shared," +
+				"dst.a+src.a); }"
+			)
+		},
+		"color": {
+			//shader: (StageGL.BLEND_FRAGMENT_HSL_UTIL + StageGL.BLEND_FRAGMENT_COMPLEX +
+			//		"setLum(src.rgb*src.a, lum(dst.rgb*dst.a)) * shared," +
+			//	"dst.a+src.a); }"
+			shader: (StageGL.BLEND_FRAGMENT_HSL_UTIL + StageGL.BLEND_FRAGMENT_SIMPLE +
+				//"gl_FragColor = vec4(  setLum(vec3(1.0), lum(dst.rgb*dst.a)),  1.0); }"
+				//"gl_FragColor = vec4(  vec3(setLum(vec3(1.0), 0.5)),  1.0); }"
+				//"gl_FragColor = vec4(  (dst.rgb - 0.8) + 0.8,  1.0); }"
+				"gl_FragColor = vec4(  dst.rgb,  1.0); }"
+			)
+		},
+		"luminosity": {
+			shader: (StageGL.BLEND_FRAGMENT_HSL_UTIL + StageGL.BLEND_FRAGMENT_COMPLEX +
+				"setLum(dst.rgb, lum(src.rgb)) * shared," +
+				"dst.a+src.a); }"
+			)
+		}
+	};
+
 // events:
 	/**
 	 * Dispatched each update immediately before the canvas is cleared and the display list is drawn to it. You can call
@@ -875,11 +1159,12 @@ this.createjs = this.createjs||{};
 
 				// defaults and options
 				var options = {
-					depth: false, // Disable the depth buffer as it isn't used.
-					alpha: this._transparent, // Make the canvas background transparent.
+					depth: false, // nothing has depth
 					stencil: false, // while there's uses for this, we're not using any yet
+					premultipliedAlpha: this._transparent, // this is complicated, trust it
+
+					alpha: this._transparent,
 					antialias: this._antialias,
-					premultipliedAlpha: this._premultiply, // Assume the drawing buffer contains colors with premultiplied alpha.
 					preserveDrawingBuffer: this._preserveBuffer
 				};
 
@@ -888,16 +1173,17 @@ this.createjs = this.createjs||{};
 
 				gl.disable(gl.DEPTH_TEST);
 				gl.enable(gl.BLEND);
-				gl.blendFuncSeparate(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA, gl.ONE, gl.ONE_MINUS_SRC_ALPHA);
-				gl.clearColor(this._clearColor.r, this._clearColor.g, this._clearColor.b, this._clearColor.a);
-				gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, this._premultiply);
+				gl.blendFunc(gl.ONE, gl.ONE_MINUS_SRC_ALPHA);
 				gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true);
 
 				this._createBuffers();
 				this._initMaterials();
+				this._updateRenderMode("source-over");
 
 				this.updateViewport(this._viewportWidth || this.canvas.width, this._viewportHeight || this.canvas.height);
-				this._outTexture = this.getRenderBufferTexture(this._viewportWidth, this._viewportHeight);
+				this._bufferTextureOutput = this.getRenderBufferTexture(this._viewportWidth, this._viewportHeight);
+				this._bufferTextureConcat = this.getRenderBufferTexture(this._viewportWidth, this._viewportHeight);
+				this._bufferTextureTemp = this.getRenderBufferTexture(this._viewportWidth, this._viewportHeight);
 
 				this.canvas._invalid = true;
 			}
@@ -917,11 +1203,7 @@ this.createjs = this.createjs||{};
 		this.dispatchEvent("drawstart");
 
 		if (this._webGLContext) {
-			// Use WebGL.
-			this._batchDraw(this, this._webGLContext);
-			if (this._autoPurge != -1 && !(this._drawID%((this._autoPurge/2)|0))) {
-				this.purgeTextures(this._autoPurge);
-			}
+			this.draw(this._webGLContext, false);
 		} else {
 			// Use 2D.
 			if (this.autoClear) { this.clear(); }
@@ -939,18 +1221,15 @@ this.createjs = this.createjs||{};
 	 */
 	p.clear = function () {
 		if (!this.canvas) { return; }
-		if (StageGL.isWebGLActive(this._webGLContext)) {
-			var gl = this._webGLContext;
-			var cc = this._clearColor;
-			var adjust = this._transparent ? cc.a : 1.0;
-			// Use WebGL settings; adjust for pre multiplied alpha appropriate to scenario
-			this._webGLContext.clearColor(cc.r * adjust, cc.g * adjust, cc.b * adjust, adjust);
-			gl.clear(gl.COLOR_BUFFER_BIT);
-			this._webGLContext.clearColor(cc.r, cc.g, cc.b, cc.a);
-		} else {
+
+		var gl = this._webGLContext;
+		if (!StageGL.isWebGLActive(gl)) {
 			// Use 2D.
 			this.Stage_clear();
 		}
+
+		gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+		this._clearFrameBuffer(this._transparent ? this._clearColor.a : 1);
 	};
 
 	/**
@@ -966,13 +1245,30 @@ this.createjs = this.createjs||{};
 	 * @return {Boolean} If the draw was handled by this function
 	 */
 	p.draw = function (context, ignoreCache) {
-		if (context === this._webGLContext && StageGL.isWebGLActive(this._webGLContext)) {
-			var gl = this._webGLContext;
-			this._batchDraw(this, gl, ignoreCache);
-			return true;
-		} else {
+		var gl = this._webGLContext;
+		// 2D context fallback
+		if (!(context === this._webGLContext && StageGL.isWebGLActive(gl))) {
 			return this.Stage_draw(context, ignoreCache);
 		}
+
+		// Use WebGL
+		this._batchCardCount = 0;
+		this._drawID++;
+
+		if (this.autoClear) { this.clear(); }
+
+		this._updateRenderMode("source-over");
+		this._drawContent(this, ignoreCache);
+
+		this._updateRenderMode("source-over");
+		this.batchReason = "finalOutput";
+		this._drawCover(null, this._bufferTextureOutput);
+
+		if (this._autoPurge != -1 && !(this._drawID%((this._autoPurge/2)|0))) {
+			this.purgeTextures(this._autoPurge);
+		}
+
+		return true;
 	};
 
 	/**
@@ -986,33 +1282,14 @@ this.createjs = this.createjs||{};
 	 * @param {BitmapCache} manager The BitmapCache instance looking after the cache
 	 * @return {Boolean} If the draw was handled by this function
 	 */
-	p.cacheDraw = function (target, filters, manager) {
-		if (StageGL.isWebGLActive(this._webGLContext)) {
-			var gl = this._webGLContext;
-			this._cacheDraw(gl, target, filters, manager);
-			return true;
-		} else {
+	p.cacheDraw = function (target, manager) {
+		// 2D context fallback
+		if (!StageGL.isWebGLActive(this._webGLContext)) {
 			return false;
 		}
-	};
 
-	/**
-	 * Blocks, or frees a texture "slot" on the GPU. Can be useful if you are overflowing textures. When overflowing
-	 * textures they are re-uploaded to the GPU every time they're encountered, this can be expensive with large textures.
-	 * By blocking the slot you reduce available slots, potentially increasing draw calls, but mostly you prevent a
-	 * texture being re-uploaded if it would have moved slots due to overflow.
-	 *
-	 * NOTE: This method is mainly for internal use, though it may be useful for advanced uses.
-	 * For example, block the slot a background image is stored in so there is less re-loading of that image.
-	 * @method protectTextureSlot
-	 * @param  {Number} id The slot to be affected
-	 * @param  {Boolean} [lock=false] Whether this slot is the one being locked.
-	 */
-	p.protectTextureSlot = function (id, lock) {
-		if (id > this._freeTextureCount || id < 0) {
-			throw "Slot outside of acceptable range";
-		}
-		this._slotBlacklist[id] = !!lock;
+		this._cacheDraw(target, target.filters, manager);
+		return true;
 	};
 
 	/**
@@ -1070,7 +1347,7 @@ this.createjs = this.createjs||{};
 	 * Removing a texture in use will cause the texture to have to be re-uploaded slowing rendering.
 	 * @method releaseTexture
 	 * @param {DisplayObject | WebGLTexture | Image | Canvas} item An object that used the texture to be discarded.
-	 * @param {Boolean} safe Should the release attempt to be "safe" and only delete this usage.
+	 * @param {Boolean} [safe=false] Should the release attempt to be "safe" and only delete this usage.
 	 */
 	p.releaseTexture = function (item, safe) {
 		var i, l;
@@ -1079,7 +1356,7 @@ this.createjs = this.createjs||{};
 		// this is a container object
 		if (item.children) {
 			for (i = 0, l = item.children.length; i < l; i++) {
-				this.releaseTexture(item.children[i]);
+				this.releaseTexture(item.children[i], safe);
 			}
 		}
 
@@ -1105,7 +1382,7 @@ this.createjs = this.createjs||{};
 		} else if (item._webGLRenderStyle === 1) {
 			// this is a SpriteSheet, we can't tell which image we used from the list easily so remove them all!
 			for (i = 0, l = item.spriteSheet._images.length; i < l; i++) {
-				this.releaseTexture(item.spriteSheet._images[i]);
+				this.releaseTexture(item.spriteSheet._images[i], safe);
 			}
 			return;
 		}
@@ -1189,8 +1466,14 @@ this.createjs = this.createjs||{};
 				-1,							1,								0,							1
 			]);
 
-			if (this._outTexture !== null) {
-				this.resizeTexture(this._outTexture, this._viewportWidth, this._viewportHeight);
+			if (this._bufferTextureConcat !== null) {
+				this.resizeTexture(this._bufferTextureConcat, this._viewportWidth, this._viewportHeight);
+			}
+			if (this._bufferTextureOutput !== null) {
+				this.resizeTexture(this._bufferTextureOutput, this._viewportWidth, this._viewportHeight);
+			}
+			if (this._bufferTextureTemp !== null) {
+				this.resizeTexture(this._bufferTextureTemp, this._viewportWidth, this._viewportHeight);
 			}
 		}
 	};
@@ -1217,8 +1500,7 @@ this.createjs = this.createjs||{};
 		} else {
 			try {
 				targetShader = this._fetchShaderProgram(
-					"cover",
-					filter.VTX_SHADER_BODY, filter.FRAG_SHADER_BODY,
+					"cover", filter.VTX_SHADER_BODY, filter.FRAG_SHADER_BODY,
 					filter.shaderParamSetup && filter.shaderParamSetup.bind(filter)
 				);
 				filter._builtShader = targetShader;
@@ -1384,9 +1666,6 @@ this.createjs = this.createjs||{};
 		this._clearColor.g = g || 0;
 		this._clearColor.b = b || 0;
 		this._clearColor.a = a || 0;
-
-		if (!this._webGLContext) { return; }
-		this._webGLContext.clearColor(this._clearColor.r, this._clearColor.g, this._clearColor.b, this._clearColor.a);
 	};
 
 	/**
@@ -1418,6 +1697,19 @@ this.createjs = this.createjs||{};
 		return texture;
 	};
 
+	p._clearFrameBuffer = function (alpha) {
+		var gl = this._webGLContext;
+		var cc = this._clearColor;
+
+		if(alpha > 0) { alpha = 1; }
+		if(alpha < 0) { alpha = 0; }
+
+		// Use WebGL settings; adjust for pre multiplied alpha appropriate to scenario
+		gl.clearColor(cc.r * alpha, cc.g * alpha, cc.b * alpha, alpha);
+		gl.clear(gl.COLOR_BUFFER_BIT);
+		gl.clearColor(0, 0, 0, 0);
+	};
+
 	/**
 	 * Sets up and returns the WebGL context for the canvas. May return undefined in error scenarios. These can include 
 	 * situations where the canvas element already has a context, 2D or GL.
@@ -1557,7 +1849,8 @@ this.createjs = this.createjs||{};
 			insert += "} else if (indexPicker <= "+ i +".5) { color = texture2D(uSampler["+ i +"], vTextureCoord);";
 		}
 		str = str.replace(/\{\{alternates}}/g, insert);
-		str = str.replace(/\{\{fragColor}}/g, this._premultiply ? StageGL.REGULAR_FRAG_COLOR_PREMULTIPLY : StageGL.REGULAR_FRAG_COLOR_NORMAL);
+
+		console.log(str);
 
 		// actually compile the shader
 		var shader = gl.createShader(type);
@@ -1607,7 +1900,7 @@ this.createjs = this.createjs||{};
 		// }
 		// vertexBuffer.itemSize = groupSize;
 		// vertexBuffer.numItems = groupCount;
-		// TODO bechmark and test using unified buffer
+		// TODO benchmark and test using unified buffer
 
 		// the actual position information
 		var vertexPositionBuffer = this._vertexPositionBuffer = gl.createBuffer();
@@ -1781,6 +2074,7 @@ this.createjs = this.createjs||{};
 		this.setTextureParams(gl, texture.isPOT);
 
 		try {
+			gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, true);
 			gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, image);
 		} catch(e) {
 			var errString = "\nAn error has occurred. This is most likely due to security restrictions on WebGL images with local or cross-domain origins";
@@ -1793,6 +2087,7 @@ this.createjs = this.createjs||{};
 				console.log(e);
 			}
 		}
+		gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, false);
 
 		if (image._invalid !== undefined) { image._invalid = false; } // only adjust what is tracking this data
 
@@ -1834,8 +2129,7 @@ this.createjs = this.createjs||{};
 			// we couldn't find anywhere for it go, meaning we're maxed out
 			if (found === -1) {
 				this.batchReason = "textureOverflow";
-				this._drawBuffers(gl);		// <------------------------------------------------------------------------
-				this.batchCardCount = 0;
+				this._renderBuffers();		// <------------------------------------------------------------------------
 				found = start; //TODO: how do we optimize this to be smarter?
 			}
 
@@ -1909,68 +2203,114 @@ this.createjs = this.createjs||{};
 		}
 	};
 
-	/**
-	 * Store or restore current batch textures into a backup array
-	 * @method _backupBatchTextures
-	 * @param {Boolean} restore Perform a restore instead of a store.
-	 * @param {Array} [target=this._backupTextures] Where to perform the backup, defaults to internal backup.
-	 * @protected
-	 */
-	p._backupBatchTextures = function (restore, target) {
-		var gl = this._webGLContext;
+	p._setCoverMixShaderParams = function (gl, stage, shaderProgram) {
+		gl.uniform1i(
+			gl.getUniformLocation(shaderProgram, "uMixSampler"),
+			1
+		);
+	};
 
-		if (!this._backupTextures) { this._backupTextures = []; }
-		if (target === undefined) { target = this._backupTextures; }
+	p._updateRenderMode = function (newMode) {
+		if ( newMode === null || newMode === undefined){ newMode = "source-over"; }
 
-		for (var i=0; i<this._batchTextureCount; i++) {
-			gl.activeTexture(gl.TEXTURE0 + i);
-			if (restore) {
-				this._batchTextures[i] = target[i];
-			} else {
-				target[i] = this._batchTextures[i];
-				this._batchTextures[i] = this._baseTextures[i];
+		var blendSrc = StageGL.BLEND_SOURCES[newMode];
+		if (blendSrc === undefined) {
+			if(this.vocalDebug){ console.log("Unknown shader ["+ newMode +"], reverting to default"); }
+			blendSrc = StageGL.BLEND_SOURCES[newMode = "source-over"];
+		}
+
+		if (this._renderMode === newMode) { return; }
+
+		var gl = this._webGLContext;
+		var shaderData = this._builtShaders[newMode];
+		if (shaderData === undefined) {
+			try {
+				shaderData = this._builtShaders[newMode] = {
+					immediate: !blendSrc.non_immediate,
+					srcRGB: gl[blendSrc.srcRGB || "ONE"],
+					dstRGB: gl[blendSrc.dstRGB || "ONE_MINUS_SRC_ALPHA"],
+					srcA: gl[blendSrc.srcA || "ONE"],
+					dstA: gl[blendSrc.dstA || "ONE_MINUS_SRC_ALPHA"],
+					shader: this._fetchShaderProgram(
+						"cover", undefined, blendSrc.shader,
+						this._setCoverMixShaderParams
+					)
+				};
+			} catch (e) {
+				this._builtShaders[newMode] = undefined;
+				console && console.log("SHADER SWITCH FAILURE", e);
+				return;
 			}
-			gl.bindTexture(gl.TEXTURE_2D, this._batchTextures[i]);
-			this.setTextureParams(gl, this._batchTextures[i].isPOT);
 		}
 
-		if (restore && target === this._backupTextures) { this._backupTextures = []; }
+		this.batchReason = "shaderSwap";
+		this._renderBuffers();		// <--------------------------------------------------------------------------------
+
+		this._renderMode = newMode;
+		this._immediateRender = shaderData.immediate;
+		gl.blendFuncSeparate(shaderData.srcRGB, shaderData.dstRGB, shaderData.srcA, shaderData.dstA);
 	};
 
 	/**
-	 * Begin the drawing process for a regular render.
-	 * @method _batchDraw
-	 * @param {WebGLRenderingContext} gl The canvas WebGL context object to draw into.
-	 * @param {Stage || Container} sceneGraph {{#crossLink "Container"}}{{/crossLink}} object with all that needs to rendered, preferably a Stage.
+	 *
+	 * @param {Stage | Container} content
 	 * @param {Boolean} ignoreCache
-	 * @protected
+	 * @private
 	 */
-	p._batchDraw = function (sceneGraph, gl, ignoreCache) {
-		if (this._isDrawing > 0) {
-			this._drawBuffers(gl);
-		}
+	p._drawContent = function (content, ignoreCache) {
+		var gl = this._webGLContext;
+
 		this._isDrawing++;
-		this._drawID++;
 
-		this.batchCardCount = 0;
-		this.depth = 0;
+		this._activeShader = this._mainShader;
 
-		gl.bindFramebuffer(gl.FRAMEBUFFER, this._outTexture._frameBuffer);
-		if (this.autoClear) { this.clear(); }
-		this._appendToBatchGroup(sceneGraph, gl, new createjs.Matrix2D(), this.alpha, ignoreCache);
+		gl.bindFramebuffer(gl.FRAMEBUFFER, this._bufferTextureOutput._frameBuffer);
+		gl.clear(gl.COLOR_BUFFER_BIT);
+
+		this._appendToBatchGroup(content, new createjs.Matrix2D(), this.alpha, ignoreCache);
+
+		this.batchReason = "contentEnd";
+		this._renderBuffers();
 
-		this.batchReason = "drawFinish";
-		this._drawBuffers(gl);								// <--------------------------------------------------------
 		this._isDrawing--;
+	};
+
+	/**
+	 *
+	 * @param {WebGLFramebuffer} out Buffer to draw the results into
+	 * @param {WebGLTexture} dst Base texture layer "destination"
+	 * @param {WebGLTexture} [src = undefined] Applied texture layer "source"
+	 * @param {Filter} [filter = undefined] Filter to use instead of blend mode
+	 * @private
+	 */
+	p._drawCover = function (out, dst, src, filter) {
+		var gl = this._webGLContext;
+
+		gl.bindFramebuffer(gl.FRAMEBUFFER, out);
 
-		gl.bindFramebuffer(gl.FRAMEBUFFER, null);
 		gl.activeTexture(gl.TEXTURE0);
-		gl.bindTexture(gl.TEXTURE_2D, this._outTexture);
-		this._activeShader = this.getFilterShader(this);
-		this._drawCover(gl);
-		this._activeShader = this._mainShader;
+		gl.bindTexture(gl.TEXTURE_2D, dst);
+		this.setTextureParams(gl);
 
-		this.canvas._invalid = true;
+		if (src !== undefined) {
+			gl.activeTexture(gl.TEXTURE1);
+			gl.bindTexture(gl.TEXTURE_2D, src);
+			this.setTextureParams(gl);
+		}
+
+		if (filter === undefined) {
+			this._activeShader = this._builtShaders[this._renderMode].shader;
+		} else {
+			this.getFilterShader(filter);
+		}
+
+		this._renderCover();
+	};
+
+	p._batchDraw = function(content, ignoreCache) {
+		this._appendToBatchGroup(content, new createjs.Matrix2D(), this.alpha, ignoreCache);
+		this.batchReason = "contentEnd";
+		this._renderBuffers();
 	};
 
 	/**
@@ -1982,7 +2322,9 @@ this.createjs = this.createjs||{};
 	 * @param {BitmapCache} manager The BitmapCache instance looking after the cache
 	 * @protected
 	 */
-	p._cacheDraw = function (gl, target, filters, manager) {
+	p._cacheDraw = function(target, filters, manager) {
+		var gl = this._webGLContext;
+
 		/*
 		Implicitly there are 4 modes to this function: filtered-sameContext, filtered-uniqueContext, sameContext, uniqueContext.
 		Each situation must be handled slightly differently as 'sameContext' or 'uniqueContext' define how the output works,
@@ -2006,8 +2348,6 @@ this.createjs = this.createjs||{};
 		container.children = [target];
 		container.transformMatrix = mtx;
 
-		this._backupBatchTextures(false);
-
 		if (filters && filters.length) {
 			this._drawFilters(target, filters, manager);
 		} else {
@@ -2015,7 +2355,7 @@ this.createjs = this.createjs||{};
 			if (this.isCacheControlled) {
 				// draw item to canvas				I -> C
 				gl.clear(gl.COLOR_BUFFER_BIT);
-				this._batchDraw(container, gl, true);
+				this._batchDraw(container, true);
 			} else {
 				gl.activeTexture(gl.TEXTURE0 + lastTextureSlot);
 				target.cacheCanvas = this.getTargetRenderTexture(target, manager._drawWidth, manager._drawHeight, true);
@@ -2025,16 +2365,14 @@ this.createjs = this.createjs||{};
 				gl.bindFramebuffer(gl.FRAMEBUFFER, renderTexture._frameBuffer);
 				this.updateViewport(manager._drawWidth, manager._drawHeight);
 				gl.clear(gl.COLOR_BUFFER_BIT);
-				this._batchDraw(container, gl, true);
+				this._batchDraw(container, true);
 
 				gl.bindFramebuffer(gl.FRAMEBUFFER, null);
 				this.updateViewport(wBackup, hBackup);
 			}
 		}
 
-		this._backupBatchTextures(true);
-
-		this.protectTextureSlot(lastTextureSlot, false);
+		//this.protectTextureSlot(lastTextureSlot, false);
 		this._activeShader = shaderBackup;
 		this._slotBlacklist = blackListBackup;
 	};
@@ -2046,7 +2384,7 @@ this.createjs = this.createjs||{};
 	 * @param {Array} filters The filters we're drawing into cache.
 	 * @param {BitmapCache} manager The BitmapCache instance looking after the cache
 	 */
-	p._drawFilters = function (target, filters, manager) {
+	p._drawFilters = function(target, filters, manager) {
 		var gl = this._webGLContext;
 		var renderTexture;
 		var lastTextureSlot = this._freeTextureCount;
@@ -2065,7 +2403,9 @@ this.createjs = this.createjs||{};
 		gl.bindFramebuffer(gl.FRAMEBUFFER, renderTexture._frameBuffer);
 		this.updateViewport(manager._drawWidth, manager._drawHeight);
 		gl.clear(gl.COLOR_BUFFER_BIT);
-		this._batchDraw(container, gl, true);
+		this._batchDraw(container, true);
+
+		gl.blendFuncSeparate(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA, gl.ONE, gl.ONE_MINUS_SRC_ALPHA);
 
 		// bind the result texture to slot 0 as all filters and cover draws assume original content is in slot 0
 		gl.activeTexture(gl.TEXTURE0);
@@ -2090,7 +2430,7 @@ this.createjs = this.createjs||{};
 				// draw result to canvas			R -> C
 				this.updateViewport(wBackup, hBackup);
 				gl.clear(gl.COLOR_BUFFER_BIT);
-				this._drawCover(gl);
+				this._renderCover();
 
 				return;
 
@@ -2100,7 +2440,7 @@ this.createjs = this.createjs||{};
 				// draw result to render texture	R -> T
 				gl.viewport(0, 0, manager._drawWidth, manager._drawHeight);
 				gl.clear(gl.COLOR_BUFFER_BIT);
-				this._drawCover(gl);
+				this._renderCover();
 
 				// bind the result texture to slot 0 as all filters and cover draws assume original content is in slot 0
 				gl.activeTexture(gl.TEXTURE0);
@@ -2121,18 +2461,19 @@ this.createjs = this.createjs||{};
 	 * trigger a draw if a buffer runs out of space. This is the main workforce of the render loop.
 	 * @method _appendToBatchGroup
 	 * @param {Container} container The {{#crossLink "Container"}}{{/crossLink}} that contains everything to be drawn.
-	 * @param {WebGLRenderingContext} gl The canvas WebGL context object to draw into.
 	 * @param {Matrix2D} concatMtx The effective (concatenated) transformation matrix when beginning this container
 	 * @param {Number} concatAlpha The effective (concatenated) alpha when beginning this container
 	 * @param {Boolean} ignoreCache Don't use an element's cache during this draw
 	 * @protected
 	 */
-	p._appendToBatchGroup = function (container, gl, concatMtx, concatAlpha, ignoreCache) {
+	p._appendToBatchGroup = function (container, concatMtx, concatAlpha, ignoreCache) {
+		var gl = this._webGLContext;
+
 		// sort out shared properties
-		if (!container._glMtx) { container._glMtx = new createjs.Matrix2D(); }
+		if (container._glMtx === undefined) { container._glMtx = new createjs.Matrix2D(); }
 		var cMtx = container._glMtx;
 		cMtx.copy(concatMtx);
-		if (container.transformMatrix) {
+		if (container.transformMatrix !== null) {
 			cMtx.appendMatrix(container.transformMatrix);
 		} else {
 			cMtx.appendTransform(
@@ -2143,6 +2484,12 @@ this.createjs = this.createjs||{};
 			);
 		}
 
+		var backupMode = null;
+		if (container.compositeOperation) {
+			backupMode = this._renderMode;
+			this._updateRenderMode(container.compositeOperation);
+		}
+
 		// sub components of figuring out the position an object holds
 		var subL, subT, subR, subB;
 
@@ -2151,23 +2498,26 @@ this.createjs = this.createjs||{};
 		for (var i = 0; i < l; i++) {
 			var item = container.children[i];
 
-			if (!(item.visible && concatAlpha)) { continue; }
-			if (!item.cacheCanvas || ignoreCache) {
+			if (item.compositeOperation !== null) {
+				this._updateRenderMode(item.compositeOperation);
+			}
+
+			if (!(item.visible && concatAlpha > 0.0035)) { continue; }
+			if (item.cacheCanvas === null || ignoreCache) {
 				if (item._updateState){
 					item._updateState();
 				}
 				if (item.children) {
-					this._appendToBatchGroup(item, gl, cMtx, item.alpha * concatAlpha);
+					this._appendToBatchGroup(item, cMtx, item.alpha * concatAlpha, ignoreCache);
 					continue;
 				}
 			}
 
 			// check for overflowing batch, if yes then force a render
 			// TODO: DHG: consider making this polygon count dependant for things like vector draws
-			if (this.batchCardCount+1 > this._maxCardsPerBatch) {
+			if (this._batchCardCount+1 > this._maxCardsPerBatch) {
 				this.batchReason = "vertexOverflow";
-				this._drawBuffers(gl);					// <------------------------------------------------------------
-				this.batchCardCount = 0;
+				this._renderBuffers();					// <------------------------------------------------------------
 			}
 
 			// keep track of concatenated position
@@ -2268,7 +2618,7 @@ this.createjs = this.createjs||{};
 			}
 
 			// These must be calculated here else a forced draw might happen after they're set
-			var offV1 = this.batchCardCount*StageGL.INDICIES_PER_CARD;		// offset for 1 component vectors
+			var offV1 = this._batchCardCount*StageGL.INDICIES_PER_CARD;		// offset for 1 component vectors
 			var offV2 = offV1*2;											// offset for 2 component vectors
 
 			//DHG: See Matrix2D.transformPoint for why this math specifically
@@ -2294,18 +2644,42 @@ this.createjs = this.createjs||{};
 			// apply alpha
 			alphas[offV1] = alphas[offV1+1] = alphas[offV1+2] = alphas[offV1+3] = alphas[offV1+4] = alphas[offV1+5] = item.alpha * concatAlpha;
 
-			this.batchCardCount++;
+			this._batchCardCount++;
+
+			if (this._immediateRender) {
+				gl.bindFramebuffer(gl.FRAMEBUFFER, this._bufferTextureConcat._frameBuffer);
+				gl.clear(gl.COLOR_BUFFER_BIT);
+
+				var swap = this._bufferTextureOutput;
+				this._bufferTextureOutput = this._bufferTextureConcat;
+				this._bufferTextureConcat = swap;
+
+				this._activeShader = this._mainShader;
+				gl.bindFramebuffer(gl.FRAMEBUFFER, this._bufferTextureTemp._frameBuffer);
+				gl.clear(gl.COLOR_BUFFER_BIT);
+				this.batchReason = "immediateBuffer";
+				this._renderBuffers();//<-------------------------------------------------------------------------------
+
+				this.batchReason = "immediateDraw";
+				this._drawCover(this._bufferTextureOutput._frameBuffer, this._bufferTextureConcat, this._bufferTextureTemp);
+
+				gl.bindFramebuffer(gl.FRAMEBUFFER, this._bufferTextureOutput._frameBuffer);
+			}
+		}
+
+		if (backupMode !== null) {
+			this._updateRenderMode(backupMode);
 		}
 	};
 
 	/**
 	 * Draws all the currently defined cards in the buffer to the render surface.
-	 * @method _drawBuffers
-	 * @param {WebGLRenderingContext} gl The canvas WebGL context object to draw into.
+	 * @method _renderBuffers
 	 * @protected
 	 */
-	p._drawBuffers = function (gl) {
-		if (this.batchCardCount <= 0) { return; }	// prevents error logs on stages filled with un-renederable content.
+	p._renderBuffers = function () {
+		if (this._batchCardCount <= 0) { return; }	// prevents error logs on stages filled with un-renederable content.
+		var gl = this._webGLContext;
 
 		if (this.vocalDebug) {
 			console.log("Draw["+ this._drawID +":"+ this._batchID +"] : "+ this.batchReason);
@@ -2343,29 +2717,28 @@ this.createjs = this.createjs||{};
 			this.setTextureParams(gl, texture.isPOT);
 		}
 
-		gl.drawArrays(gl.TRIANGLES, 0, this.batchCardCount*StageGL.INDICIES_PER_CARD);
+		gl.drawArrays(gl.TRIANGLES, 0, this._batchCardCount*StageGL.INDICIES_PER_CARD);
+
+		this._batchCardCount = 0;
 		this._batchID++;
 	};
 
 	/**
 	 * Draws a card that covers the entire render surface. Mainly used for filters.
-	 * @method _drawBuffers
+	 * @method _renderCover
 	 * @param {WebGLRenderingContext} gl The canvas WebGL context object to draw into.
 	 * @protected
 	 */
-	p._drawCover = function (gl) {
-		if (this._isDrawing > 0) {
-			this._drawBuffers(gl);
-		}
+	p._renderCover = function () {
+		var gl = this._webGLContext;
 
 		if (this.vocalDebug) {
-			console.log("Draw["+ this._drawID +":"+ this._batchID +"] : "+ "Cover");
+			console.log("Cover["+ this._drawID +":"+ this._batchID +"] : "+ this.batchReason);
 		}
 		var shaderProgram = this._activeShader;
 		var vertexPositionBuffer = this._vertexPositionBuffer;
 		var uvPositionBuffer = this._uvPositionBuffer;
 
-		gl.clear(gl.COLOR_BUFFER_BIT);
 		gl.useProgram(shaderProgram);
 
 		gl.bindBuffer(gl.ARRAY_BUFFER, vertexPositionBuffer);
@@ -2378,6 +2751,7 @@ this.createjs = this.createjs||{};
 		gl.uniform1i(shaderProgram.samplerUniform, 0);
 
 		gl.drawArrays(gl.TRIANGLES, 0, StageGL.INDICIES_PER_CARD);
+		this._batchID++;
 	};
 
 	createjs.StageGL = createjs.promote(StageGL, "Stage");
diff --git a/src/easeljs/filters/AlphaMapFilter.js b/src/easeljs/filters/AlphaMapFilter.js
index 02b6aa591..a22bbee8c 100644
--- a/src/easeljs/filters/AlphaMapFilter.js
+++ b/src/easeljs/filters/AlphaMapFilter.js
@@ -70,7 +70,7 @@ this.createjs = this.createjs || {};
 	function AlphaMapFilter(alphaMap) {
 		this.Filter_constructor();
 
-		if (!Filter.isValidImageSource(alphaMap)) {
+		if (!createjs.Filter.isValidImageSource(alphaMap)) {
 			throw "Must provide valid image source for alpha map, see Filter.isValidImageSource";
 		}
 
diff --git a/src/easeljs/filters/AlphaMaskFilter.js b/src/easeljs/filters/AlphaMaskFilter.js
index 0e2226757..ab0354aa0 100644
--- a/src/easeljs/filters/AlphaMaskFilter.js
+++ b/src/easeljs/filters/AlphaMaskFilter.js
@@ -69,7 +69,7 @@ this.createjs = this.createjs || {};
 	function AlphaMaskFilter(mask) {
 		this.Filter_constructor();
 
-		if (!Filter.isValidImageSource(mask)) {
+		if (!createjs.Filter.isValidImageSource(mask)) {
 			throw "Must provide valid image source for alpha mask, see Filter.isValidImageSource";
 		}
 
diff --git a/src/easeljs/filters/BitmapCache.js b/src/easeljs/filters/BitmapCache.js
index 93d704b0e..54dd70857 100644
--- a/src/easeljs/filters/BitmapCache.js
+++ b/src/easeljs/filters/BitmapCache.js
@@ -506,7 +506,7 @@ this.createjs = this.createjs||{};
 		var webGL = this._webGLCache;
 
 		if (webGL) {
-			webGL.cacheDraw(target, target.filters, this);
+			webGL.cacheDraw(target, this);
 		} else {
 			var ctx = surface.getContext("2d");
 
diff --git a/src/easeljs/filters/DisplacementFilter.js b/src/easeljs/filters/DisplacementFilter.js
index c8590e02d..3137ca6f9 100644
--- a/src/easeljs/filters/DisplacementFilter.js
+++ b/src/easeljs/filters/DisplacementFilter.js
@@ -66,7 +66,7 @@ this.createjs = this.createjs||{};
 	function DisplacementFilter(dudvMap, distance) {
 		this.Filter_constructor();
 
-		if (!Filter.isValidImageSource(dudvMap)) {
+		if (!createjs.Filter.isValidImageSource(dudvMap)) {
 			throw "Must provide valid image source for displacement map, see Filter.isValidImageSource";
 		}
 

From 00f6fefbdba797e213619ea002890efc85c25671 Mon Sep 17 00:00:00 2001
From: David <david@gskinner.com>
Date: Thu, 14 Dec 2017 14:25:23 -0700
Subject: [PATCH 16/39] Incomplete set of blend modes. Most functional.

---
 src/easeljs/display/DisplayObject.js |   1 +
 src/easeljs/display/StageGL.js       | 274 +++++++++++----------------
 2 files changed, 110 insertions(+), 165 deletions(-)

diff --git a/src/easeljs/display/DisplayObject.js b/src/easeljs/display/DisplayObject.js
index 190bbd6e2..36b9f84f9 100644
--- a/src/easeljs/display/DisplayObject.js
+++ b/src/easeljs/display/DisplayObject.js
@@ -1254,6 +1254,7 @@ this.createjs = this.createjs||{};
 		o.hitArea = this.hitArea;
 		o.cursor = this.cursor;
 		o._bounds = this._bounds;
+		o._webGLRenderStyle = this._webGLRenderStyle;
 		return o;
 	};
 
diff --git a/src/easeljs/display/StageGL.js b/src/easeljs/display/StageGL.js
index 6dae32298..f5762a29a 100644
--- a/src/easeljs/display/StageGL.js
+++ b/src/easeljs/display/StageGL.js
@@ -809,7 +809,7 @@ this.createjs = this.createjs||{};
 		// note this is an open bracket on main!
 	);
 
-	StageGL.BLEND_FRAGMENT_COMPLEX = (
+	StageGL.BLEND_FRAGMENT_COMPLEX = (																					// CLOSE
 		StageGL.BLEND_FRAGMENT_SIMPLE +
 			"vec3 srcClr = min(src.rgb/src.a, 1.0);" +
 			"vec3 dstClr = min(dst.rgb/dst.a, 1.0);" +
@@ -823,7 +823,7 @@ this.createjs = this.createjs||{};
 				"(" +
 					"srcFactor * srcClr +" +
 					"dstFactor * dstClr +" +
-					"mixFactor * ("
+					"mixFactor * vec3("
 		// this should be closed with the cap!
 	);
 	StageGL.BLEND_FRAGMENT_COMPLEX_CAP = (
@@ -841,18 +841,19 @@ this.createjs = this.createjs||{};
 	);
 
 	StageGL.BLEND_FRAGMENT_HSL_UTIL = (
-		"float lum(vec3 c) { return 0.299*c.r + 0.589*c.g + 0.109*c.b; }" +
-		"float sat(vec3 c) { return max(max(c.r, c.g), c.b) - min(min(c.r, c.g), c.b); }" +
+		/*"float getLum(vec3 c) { return 0.299*c.r + 0.589*c.g + 0.109*c.b; }" +
+		//"float getSat(vec3 c) { return max(max(c.r, c.g), c.b) - min(min(c.r, c.g), c.b); }" +
 		"vec3 clipHSL(vec3 c) {" +
-			"float l = lum(c);" +
-			"float n = min(min(c.r, c.g), c.b);" +
-			"float x = max(max(c.r, c.g), c.b);" +
-			"if(n < 0.0){ c = l + (((c - l) * l) / (l - n)); }" +
-			"if(x < 1.0){ c = l + (((c - l) * (1.0 - l)) / (x - l)); }" +
-			"return c;" +
+			"float lum = getLum(c);" +
+			//"float n = min(min(c.r, c.g), c.b);" +
+			//"float x = max(max(c.r, c.g), c.b);" +
+			//"if(n < 0.0){ c = lum + (((c - lum) * lum) / (lum - n)); }" +
+			//"if(x < 1.0){ c = lum + (((c - lum) * (1.0 - lum)) / (x - lum)); }" +
+			"return clamp(c, 0.0, 1.0);" +
 		"}" +
-		"vec3 setLum(vec3 c, float val) {" +
-			"return clipHSL(c + (val - lum(c)));" +
+		"vec3 setLum(vec3 c, float lum) {" +
+			//"return clipHSL(c + (lum - getLum(c)));" +
+			"return vec3(getLum(c) + (lum - getLum(c)));" +
 		"}" +
 		"vec3 setSat(vec3 c, float val) {" +
 			"bool rxg = c.r > c.g; bool rxb = c.r > c.b; bool gxb = c.g > c.b;" +
@@ -881,214 +882,154 @@ this.createjs = this.createjs||{};
 			"}" +
 
 			"return result;" +
-		"}"
+		"}"/**/
 	);
 
 	StageGL.BLEND_SOURCES = {
-		"source-over": {																								//YAY
-			non_immediate: true
+		"source-over": { // empty object verifies it as a blend mode, but default values handle actual settings
+			//eqRGB: "FUNC_ADD",						eqA: "FUNC_ADD"
 			//srcRGB: "ONE",							srcA: "ONE"
 			//dstRGB: "ONE_MINUS_SRC_ALPHA",			dstA: "ONE_MINUS_SRC_ALPHA"
 		},
-		"source-in": {
-			non_immediate: true,
+		"source-in": {																									// CLOSE
 			srcRGB: "DST_ALPHA",					srcA: "ZERO",
 			dstRGB: "ZERO",							dstA: "SRC_ALPHA"
 		},
-		"source-out": {
-			shader: (StageGL.BLEND_FRAGMENT_SIMPLE +
-				"gl_FragColor = vec4(src.rgb*(1-dst.a), src.a-dst.a); }"
-			)
+		"source-out": {																									// CLOSE
+			eqA: "FUNC_SUBTRACT",
+			srcRGB: "ONE_MINUS_DST_ALPHA",			srcA: "ONE",
+			dstRGB: "ZERO",							dstA: "SRC_ALPHA"
 		},
 		"source-atop": {
-			shader: (StageGL.BLEND_FRAGMENT_SIMPLE +
-				"gl_FragColor = vec4(src.rgb*src.a + dst.rgb*(1.0-src.a), dst.a); }"
-			)
+			srcRGB: "DST_ALPHA",					srcA: "ZERO",
+			dstRGB: "ONE_MINUS_SRC_ALPHA",			dstA: "ONE"
 		},
 		"destination-over": {
-			shader: (StageGL.BLEND_FRAGMENT_SIMPLE +
-				"gl_FragColor = vec4(src.rgb*(1.0-dst.a) + dst.rgb*dst.a, src.a+dst.a); }"
-			)
+			srcRGB: "ONE_MINUS_DST_ALPHA",			srcA: "ONE_MINUS_DST_ALPHA",
+			dstRGB: "ONE",							dstA: "ONE"
 		},
-		"destination-in": {
-			shader: (StageGL.BLEND_FRAGMENT_SIMPLE +
-				"gl_FragColor = vec4(dst.rgb, src.a*dst.a); }"
-			)
+		"destination-in": {																								// CLOSE
+			srcRGB: "ZERO",							srcA: "DST_ALPHA",
+			dstRGB: "SRC_ALPHA",					dstA: "ZERO"
 		},
 		"destination-out": {
-			shader: (StageGL.BLEND_FRAGMENT_SIMPLE +
-				"gl_FragColor = vec4(dst.rgb, dst.a*(1.0-src.a)); }"
-			)
+			eqA: "FUNC_REVERSE_SUBTRACT",
+			srcRGB: "ZERO",							srcA: "DST_ALPHA",
+			dstRGB: "ONE_MINUS_SRC_ALPHA",			dstA: "ONE"
 		},
-		"destination-atop": {
-			shader: (StageGL.BLEND_FRAGMENT_SIMPLE +
-				"gl_FragColor = vec4(src.rgb*(1.0-dst.a) + dst.rgb*dst.a, src.a); }"
-			)
+		"destination-atop": {																							// CLOSE
+			srcRGB: "ONE_MINUS_DST_ALPHA",			srcA: "ONE",
+			dstRGB: "SRC_ALPHA",					dstA: "ZERO"
 		},
-		"copy": {																										//YAY
-			non_immediate: true,
+		"copy": {
 			dstRGB: "ZERO",							dstA: "ZERO"
 		},
+		"xor": {
+			shader: (StageGL.BLEND_FRAGMENT_SIMPLE +
+				"float omSRC = (1.0 - src.a);" +
+				"float omDST = (1.0 - dst.a);" +
+				"gl_FragColor = vec4(src.rgb * omDST + dst.rgb * omSRC, src.a * omDST + dst.a * omSRC);" +
+			"}"
+			)
+		},
 
-		"multiply": {																									//YAY
+		"multiply": { // this has to be complex to handle retention of both dst and src in non mixed scenarios
 			shader: (StageGL.BLEND_FRAGMENT_COMPLEX +
 				"srcClr * dstClr"
 			+ StageGL.BLEND_FRAGMENT_COMPLEX_CAP)
 		},
-		"multiply-cheap": {																								//YAY
-			non_immediate: true,
-			srcRGB: "ZERO",							srcA: "ONE",
+		"multiply_cheap": { // NEW, handles retention of src data incorrectly when no dst data present
+			srcRGB: "ONE_MINUS_DST_ALPHA",			srcA: "ONE",
 			dstRGB: "SRC_COLOR",					dstA: "ONE"
 		},
-		"screen": {																										//YAY
-			shader: (StageGL.BLEND_FRAGMENT_COMPLEX +
-				"1.0 - (1.0 - srcClr) * (1.0 - dstClr)"
-			+ StageGL.BLEND_FRAGMENT_COMPLEX_CAP)
-		},
-		"screen-cheap": {																								//
-			non_immediate: true,
-			srcRGB: "ZERO",							srcA: "ONE",
-			dstRGB: "SRC_COLOR",					dstA: "ONE"
+		"screen": {
+			srcRGB: "ONE",							srcA: "ONE",
+			dstRGB: "ONE_MINUS_SRC_COLOR",			dstA: "ONE_MINUS_SRC_ALPHA"
 		},
-		"lighter": {																									//YAY
-			non_immediate: true,
+		"lighter": {
 			dstRGB: "ONE",							dstA:"ONE"
 		},
-		"lighten": {
+		"lighten": { //WebGL 2.0 can optimize this
 			shader: (StageGL.BLEND_FRAGMENT_COMPLEX +
-				"max(src.rgb, dst.rgb) * shared," +
-				"dst.a+src.a); }"
-			)
+				"max(srcClr, dstClr)"
+			+ StageGL.BLEND_FRAGMENT_COMPLEX_CAP)
 		},
-		"darken": {
+		"darken": { //WebGL 2.0 can optimize this
 			shader: (StageGL.BLEND_FRAGMENT_COMPLEX +
-				"min(src.rgb, dst.rgb) * shared," +
-				"dst.a+src.a); }"
-			)
+				"min(srcClr, dstClr)"
+			+ StageGL.BLEND_FRAGMENT_COMPLEX_CAP)
 		},
 
 		"overlay": {
-			shader: (
-				StageGL.BLEND_FRAGMENT_OVERLAY_UTIL + StageGL.BLEND_FRAGMENT_SIMPLE +
-				"gl_FragColor = vec4(overlay(dst.r,src.r), overlay(dst.g,src.g), overlay(dst.b,src.b), dst.a+src.a); }"
-			)
+			shader: (StageGL.BLEND_FRAGMENT_OVERLAY_UTIL + StageGL.BLEND_FRAGMENT_COMPLEX +
+				"overlay(dstClr.r,srcClr.r), overlay(dstClr.g,srcClr.g), overlay(dstClr.b,srcClr.b)"
+			+ StageGL.BLEND_FRAGMENT_COMPLEX_CAP)
 		},
 		"hard-light": {
-			shader: (
-				StageGL.BLEND_FRAGMENT_OVERLAY_UTIL + StageGL.BLEND_FRAGMENT_SIMPLE +
-				"gl_FragColor = vec4(overlay(src.r,dst.r), overlay(src.g,dst.g), overlay(src.b,dst.b), dst.a+src.a); }"
-			)
+			shader: (StageGL.BLEND_FRAGMENT_OVERLAY_UTIL + StageGL.BLEND_FRAGMENT_COMPLEX +
+				"overlay(srcClr.r,dstClr.r), overlay(srcClr.g,dstClr.g), overlay(srcClr.b,dstClr.b)"
+			+ StageGL.BLEND_FRAGMENT_COMPLEX_CAP)
 		},
 		"soft-light": {
 			shader: (
 				"float softcurve(float a) {" +
-				"if(a > 0.25) { return sqrt(a); }" +
-				"return ((16.0 * a - 12.0) * a + 4.0) * a;" +
+					"if(a > 0.25) { return sqrt(a); }" +
+					"return ((16.0 * a - 12.0) * a + 4.0) * a;" +
 				"}" +
 				"float softmix(float a, float b) {" +
-				"if(b <= 0.5) { return a - (1.0 - 2.0*b) * a * (1.0 - a); }" +
-				"return a + (2.0 * b - 1.0) * (softcurve(a) - a);" +
+					"if(b <= 0.5) { return a - (1.0 - 2.0*b) * a * (1.0 - a); }" +
+					"return a + (2.0 * b - 1.0) * (softcurve(a) - a);" +
 				"}" + StageGL.BLEND_FRAGMENT_COMPLEX +
-				"vec3(softmix(src.r,dst.r), softmix(src.g,dst.g), softmix(src.b,dst.b)) * shared," +
-				"dst.a+src.a); }"
-			)
+				"softmix(dstClr.r,srcClr.r), softmix(dstClr.g,srcClr.g), softmix(dstClr.b,srcClr.b)"
+			+ StageGL.BLEND_FRAGMENT_COMPLEX_CAP)
 		},
 		"color-dodge": {
-			//shader: (
-			//	"float blendColorDodge(float base, float blend) {" +
-			//		"return (blend==1.0)?blend:min(base/(1.0-blend),1.0);" +
-			//	"}" +
-			//	"vec3 blendColorDodge(vec3 base, vec3 blend) {" +
-			//		"return vec3(blendColorDodge(base.r,blend.r),blendColorDodge(base.g,blend.g),blendColorDodge(base.b,blend.b));" +
-			//	"}" +
-			//	"vec3 blendColorDodge(vec3 base, vec3 blend, float opacity) {" +
-			//		"return (blendColorDodge(base, blend) * opacity + base * (1.0 - opacity));" +
-			//	"}" + StageGL.BLEND_FRAGMENT_SIMPLE +
-			//	"gl_FragColor = vec4(blendColorDodge(dst.rgb, src.rgb, src.a), 1.0); }"
-
-			//shader: (StageGL.BLEND_FRAGMENT_SIMPLE +
-			//	"vec4 color = vec4(0.0, 0.0, 0.0, dst.a+src.a);" +
-
-			//	"if(src.r*src.a >= 0.96) {" +
-			//		"if(dst.r*dst.a >= 0.0035) { color.r = 1.0; } else { color.r = 0.0; }" +
-			//	"} else {" +
-			//		"color.r = clamp(dst.r*dst.a / (1.0-src.r*src.a), 0.0, 1.0);" +
-			//	"}" +
-
-			//	"if(src.g*src.a >= 0.96) {" +
-			//		"if(dst.g*dst.a >= 0.0035) { color.g = 1.0; } else { color.g = 0.0; }" +
-			//	"} else {" +
-			//		"color.g = clamp(dst.g*dst.a / (1.0-src.g*src.a), 0.0, 1.0);" +
-			//	"}" +
-
-			//	"if(src.b*src.a >= 0.96) {" +
-			//		"if(dst.b*dst.a >= 0.0035) { color.b = 1.0; } else { color.b = 0.0; }" +
-			//	"} else {" +
-			//		"color.b = clamp(dst.b*dst.a / (1.0-src.b*src.a), 0.0, 1.0);" +
-			//	"}" +
-
-			//	"gl_FragColor = color; }"
-			//shader: (StageGL.BLEND_FRAGMENT_COMPLEX +
-			//		"((dst.rgb*dst.a) / (1.0-src.rgb*src.a) * shared," +
-			//	"dst.a+src.a); }"
-			shader: (StageGL.BLEND_FRAGMENT_SIMPLE +
-				//"gl_FragColor = vec4(1.0/1.0, 1.0/0.0, 0.0/1.0, 1.0); }"		//1.0, 1.0, 0.0
-				//"gl_FragColor = vec4(0.5/1.0, 0.5/0.0, 0.0/0.5, 1.0); }"		//0.5, 1.0, 0.0
-				//"gl_FragColor = vec4(0.0/1.0, 0.0/0.0, 0.0/0.0, 1.0); }"		//0.0, 0.0, 0.0
-				"gl_FragColor = vec4(0.1/0.0, 1.0/1.0, 0.0/0.0, 1.0); }"		//0.0, 0.0, 0.0
-			)
-		},
-		"color-burn": {
-			shader: (StageGL.BLEND_FRAGMENT_SIMPLE +
-				"gl_FragColor = vec4(0.0, 0.0, 0.0, 1.0); }"
-			)
+			shader: (StageGL.BLEND_FRAGMENT_COMPLEX +
+				"clamp(dstClr / (1.0 - srcClr), 0.0, 1.0)"
+			+ StageGL.BLEND_FRAGMENT_COMPLEX_CAP)
 		},
-
-		"xor": {
-			shader: (StageGL.BLEND_FRAGMENT_SIMPLE +
-				"gl_FragColor = vec4(src.rgb*src.a + dst.rgb*dst.a, abs(src.a-dst.a)); }"
-			)
+		"color-burn": {																									// CLOSE
+			shader: (StageGL.BLEND_FRAGMENT_COMPLEX +
+				"1.0 - (clamp((1.0 - dstClr) / srcClr, 0.0, 1.0))"
+			+ StageGL.BLEND_FRAGMENT_COMPLEX_CAP)
 		},
-		"difference": {
-			shader: (StageGL.BLEND_FRAGMENT_SIMPLE +
-				"gl_FragColor = vec4(abs(src.rgb-dst.rgb), src.a+dst.a); }"
-			)
+		"difference": { // do this to match visible results in browsers
+			shader: (StageGL.BLEND_FRAGMENT_COMPLEX +
+				"abs(src.rgb - dstClr)"
+			+ StageGL.BLEND_FRAGMENT_COMPLEX_CAP)
 		},
-		"exclusion": {
+		"exclusion": { // do this to match visible results in browsers
 			shader: (StageGL.BLEND_FRAGMENT_COMPLEX +
-				"(src.rgb + dst.rgb - 2.0 * src.rgb * dst.rgb) * shared," +
-				"dst.a+src.a); }"
-			)
+				"dstClr + src.rgb - 2.0 * src.rgb * dstClr"
+			+ StageGL.BLEND_FRAGMENT_COMPLEX_CAP)
 		},
 
-		"hue": {
+		"hue": {																										// NEWP
 			shader: (StageGL.BLEND_FRAGMENT_HSL_UTIL + StageGL.BLEND_FRAGMENT_COMPLEX +
 				" * shared," +
 				"dst.a+src.a); }"
 			)
 		},
-		"saturation": {
+		"saturation": {																									// NEWP
 			shader: (StageGL.BLEND_FRAGMENT_HSL_UTIL + StageGL.BLEND_FRAGMENT_COMPLEX +
 				" * shared," +
 				"dst.a+src.a); }"
 			)
 		},
-		"color": {
+		"color": {																										// NEWP
+			shader: (StageGL.BLEND_FRAGMENT_HSL_UTIL + StageGL.BLEND_FRAGMENT_COMPLEX +
+				//"setLum(srcClr, getLum(dstClr))"
+			+ StageGL.BLEND_FRAGMENT_COMPLEX_CAP)
+		},
+		"luminosity": {																									// NEWP
 			//shader: (StageGL.BLEND_FRAGMENT_HSL_UTIL + StageGL.BLEND_FRAGMENT_COMPLEX +
-			//		"setLum(src.rgb*src.a, lum(dst.rgb*dst.a)) * shared," +
-			//	"dst.a+src.a); }"
+			//	"setLum(dstClr, getLum(srcClr))"
+			//+ StageGL.BLEND_FRAGMENT_COMPLEX_CAP)
 			shader: (StageGL.BLEND_FRAGMENT_HSL_UTIL + StageGL.BLEND_FRAGMENT_SIMPLE +
-				//"gl_FragColor = vec4(  setLum(vec3(1.0), lum(dst.rgb*dst.a)),  1.0); }"
-				//"gl_FragColor = vec4(  vec3(setLum(vec3(1.0), 0.5)),  1.0); }"
-				//"gl_FragColor = vec4(  (dst.rgb - 0.8) + 0.8,  1.0); }"
-				"gl_FragColor = vec4(  dst.rgb,  1.0); }"
-			)
-		},
-		"luminosity": {
-			shader: (StageGL.BLEND_FRAGMENT_HSL_UTIL + StageGL.BLEND_FRAGMENT_COMPLEX +
-				"setLum(dst.rgb, lum(src.rgb)) * shared," +
-				"dst.a+src.a); }"
-			)
+				"vec3 srcClr = min(src.rgb/src.a, 1.0);" +
+				"vec3 dstClr = min(dst.rgb/dst.a, 1.0);" +
+				"gl_FragColor = vec4(setLum(vec3(1.0,0.0,0.0), getLum(src.rgb)), 1.0);" +
+			"}")
 		}
 	};
 
@@ -1173,8 +1114,8 @@ this.createjs = this.createjs||{};
 
 				gl.disable(gl.DEPTH_TEST);
 				gl.enable(gl.BLEND);
-				gl.blendFunc(gl.ONE, gl.ONE_MINUS_SRC_ALPHA);
 				gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true);
+				gl.clearColor(0.0, 0.0, 0.0, 0);
 
 				this._createBuffers();
 				this._initMaterials();
@@ -1223,9 +1164,9 @@ this.createjs = this.createjs||{};
 		if (!this.canvas) { return; }
 
 		var gl = this._webGLContext;
-		if (!StageGL.isWebGLActive(gl)) {
-			// Use 2D.
+		if (!StageGL.isWebGLActive(gl)) { // Use 2D.
 			this.Stage_clear();
+			return;
 		}
 
 		gl.bindFramebuffer(gl.FRAMEBUFFER, null);
@@ -1850,8 +1791,6 @@ this.createjs = this.createjs||{};
 		}
 		str = str.replace(/\{\{alternates}}/g, insert);
 
-		console.log(str);
-
 		// actually compile the shader
 		var shader = gl.createShader(type);
 		gl.shaderSource(shader, str);
@@ -2226,15 +2165,18 @@ this.createjs = this.createjs||{};
 		if (shaderData === undefined) {
 			try {
 				shaderData = this._builtShaders[newMode] = {
-					immediate: !blendSrc.non_immediate,
+					eqRGB: gl[blendSrc.eqRGB || "FUNC_ADD"],
 					srcRGB: gl[blendSrc.srcRGB || "ONE"],
 					dstRGB: gl[blendSrc.dstRGB || "ONE_MINUS_SRC_ALPHA"],
+					eqA: gl[blendSrc.eqA || "FUNC_ADD"],
 					srcA: gl[blendSrc.srcA || "ONE"],
 					dstA: gl[blendSrc.dstA || "ONE_MINUS_SRC_ALPHA"],
-					shader: this._fetchShaderProgram(
-						"cover", undefined, blendSrc.shader,
-						this._setCoverMixShaderParams
-					)
+					immediate: Boolean(blendSrc.shader),
+					shader: (blendSrc.shader || this._builtShaders["source-over"] === undefined) ?
+						this._fetchShaderProgram(
+							"cover", undefined, blendSrc.shader,
+							this._setCoverMixShaderParams
+						) : this._builtShaders["source-over"].shader // re-use source-over when we don't need a new shader
 				};
 			} catch (e) {
 				this._builtShaders[newMode] = undefined;
@@ -2248,6 +2190,7 @@ this.createjs = this.createjs||{};
 
 		this._renderMode = newMode;
 		this._immediateRender = shaderData.immediate;
+		gl.blendEquationSeparate(shaderData.eqRGB, shaderData.eqA);
 		gl.blendFuncSeparate(shaderData.srcRGB, shaderData.dstRGB, shaderData.srcA, shaderData.dstA);
 	};
 
@@ -2405,6 +2348,7 @@ this.createjs = this.createjs||{};
 		gl.clear(gl.COLOR_BUFFER_BIT);
 		this._batchDraw(container, true);
 
+		gl.blendEquationSeparate(gl.FUNC_ADD, gl.FUNC_ADD);
 		gl.blendFuncSeparate(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA, gl.ONE, gl.ONE_MINUS_SRC_ALPHA);
 
 		// bind the result texture to slot 0 as all filters and cover draws assume original content is in slot 0

From 5d1c4fd6c7237484635ee7122887952841d79b72 Mon Sep 17 00:00:00 2001
From: David <david@gskinner.com>
Date: Thu, 14 Dec 2017 16:19:23 -0700
Subject: [PATCH 17/39] fix HSL draw modes

---
 src/easeljs/display/StageGL.js | 82 +++++++++++++---------------------
 1 file changed, 30 insertions(+), 52 deletions(-)

diff --git a/src/easeljs/display/StageGL.js b/src/easeljs/display/StageGL.js
index f5762a29a..bd806aac2 100644
--- a/src/easeljs/display/StageGL.js
+++ b/src/easeljs/display/StageGL.js
@@ -841,48 +841,33 @@ this.createjs = this.createjs||{};
 	);
 
 	StageGL.BLEND_FRAGMENT_HSL_UTIL = (
-		/*"float getLum(vec3 c) { return 0.299*c.r + 0.589*c.g + 0.109*c.b; }" +
-		//"float getSat(vec3 c) { return max(max(c.r, c.g), c.b) - min(min(c.r, c.g), c.b); }" +
+		"float getLum(vec3 c) { return 0.299*c.r + 0.589*c.g + 0.109*c.b; }" +
+		"float getSat(vec3 c) { return max(max(c.r, c.g), c.b) - min(min(c.r, c.g), c.b); }" +
 		"vec3 clipHSL(vec3 c) {" +
 			"float lum = getLum(c);" +
-			//"float n = min(min(c.r, c.g), c.b);" +
-			//"float x = max(max(c.r, c.g), c.b);" +
-			//"if(n < 0.0){ c = lum + (((c - lum) * lum) / (lum - n)); }" +
-			//"if(x < 1.0){ c = lum + (((c - lum) * (1.0 - lum)) / (x - lum)); }" +
+			"float n = min(min(c.r, c.g), c.b);" +
+			"float x = max(max(c.r, c.g), c.b);" +
+			"if(n < 0.0){ c = lum + (((c - lum) * lum) / (lum - n)); }" +
+			"if(x > 1.0){ c = lum + (((c - lum) * (1.0 - lum)) / (x - lum)); }" +
 			"return clamp(c, 0.0, 1.0);" +
 		"}" +
 		"vec3 setLum(vec3 c, float lum) {" +
-			//"return clipHSL(c + (lum - getLum(c)));" +
-			"return vec3(getLum(c) + (lum - getLum(c)));" +
+			"return clipHSL(c + (lum - getLum(c)));" +
 		"}" +
 		"vec3 setSat(vec3 c, float val) {" +
-			"bool rxg = c.r > c.g; bool rxb = c.r > c.b; bool gxb = c.g > c.b;" +
-			"vec3 midMask = vec3(0.0); vec3 maxMask = vec3(0.0); vec3 result = vec3(0.0);" +
-			"if(rxg){" +
-				"if(rxb) {" +
-					"maxMask.r = 1.0;" +
-					"if(gxb) {midMask.g = 1.0;} else {midMask.b = 1.0;}" +
-				"} else {" +
-					"maxMask.b = 1.0;" +
-					"midMask.r = 1.0;" +
-				"}" +
-			"} else {" +
-				"if(gxb) {" +
-					"maxMask.g = 1.0;" +
-					"if(rxb) {midMask.r = 1.0;} else {midMask.b = 1.0;}" +
-				"} else {" +
-					"maxMask.b = 1.0;" +
-					"midMask.g = 1.0;" +
-				"}" +
-			"}" +
-			"vec3 minMask = 1.0 - (midMask+maxMask);" +
-			"if(any(greaterThan(c*maxMask, c*minMask))) {" +
-				"result = midMask*( ((c*midMask - c*minMask) * val) / (c*maxMask - c*minMask) );" +
-				"result += maxMask*( val );" +
+			"vec3 result = vec3(0.0);" +
+			"float minVal = min(min(c.r, c.g), c.b);" +
+			"float maxVal = max(max(c.r, c.g), c.b);" +
+			"vec3 minMask = vec3(c.r == minVal, c.g == minVal, c.b == minVal);" +
+			"vec3 maxMask = vec3(c.r == maxVal, c.g == maxVal, c.b == maxVal);" +
+			"vec3 midMask = 1.0 - min(minMask+maxMask, 1.0);" +
+			"float midVal = (c*midMask).r + (c*midMask).g + (c*midMask).b;" +
+			"if(maxVal > minVal) {" +
+				"result = midMask * min( ((midVal - minVal) * val) / (maxVal - minVal), 1.0);" +
+				"result += maxMask * val;" +
 			"}" +
-
 			"return result;" +
-		"}"/**/
+		"}"
 	);
 
 	StageGL.BLEND_SOURCES = {
@@ -1004,32 +989,25 @@ this.createjs = this.createjs||{};
 			+ StageGL.BLEND_FRAGMENT_COMPLEX_CAP)
 		},
 
-		"hue": {																										// NEWP
+		"hue": {
 			shader: (StageGL.BLEND_FRAGMENT_HSL_UTIL + StageGL.BLEND_FRAGMENT_COMPLEX +
-				" * shared," +
-				"dst.a+src.a); }"
-			)
+			"setLum(setSat(srcClr, getSat(dstClr)), getLum(dstClr))"
+			+ StageGL.BLEND_FRAGMENT_COMPLEX_CAP)
 		},
-		"saturation": {																									// NEWP
+		"saturation": {
 			shader: (StageGL.BLEND_FRAGMENT_HSL_UTIL + StageGL.BLEND_FRAGMENT_COMPLEX +
-				" * shared," +
-				"dst.a+src.a); }"
-			)
+				"setLum(setSat(dstClr, getSat(srcClr)), getLum(dstClr))"
+			+ StageGL.BLEND_FRAGMENT_COMPLEX_CAP)
 		},
-		"color": {																										// NEWP
+		"color": {
 			shader: (StageGL.BLEND_FRAGMENT_HSL_UTIL + StageGL.BLEND_FRAGMENT_COMPLEX +
-				//"setLum(srcClr, getLum(dstClr))"
+				"setLum(srcClr, getLum(dstClr))"
 			+ StageGL.BLEND_FRAGMENT_COMPLEX_CAP)
 		},
-		"luminosity": {																									// NEWP
-			//shader: (StageGL.BLEND_FRAGMENT_HSL_UTIL + StageGL.BLEND_FRAGMENT_COMPLEX +
-			//	"setLum(dstClr, getLum(srcClr))"
-			//+ StageGL.BLEND_FRAGMENT_COMPLEX_CAP)
-			shader: (StageGL.BLEND_FRAGMENT_HSL_UTIL + StageGL.BLEND_FRAGMENT_SIMPLE +
-				"vec3 srcClr = min(src.rgb/src.a, 1.0);" +
-				"vec3 dstClr = min(dst.rgb/dst.a, 1.0);" +
-				"gl_FragColor = vec4(setLum(vec3(1.0,0.0,0.0), getLum(src.rgb)), 1.0);" +
-			"}")
+		"luminosity": {
+			shader: (StageGL.BLEND_FRAGMENT_HSL_UTIL + StageGL.BLEND_FRAGMENT_COMPLEX +
+				"setLum(dstClr, getLum(srcClr))"
+			+ StageGL.BLEND_FRAGMENT_COMPLEX_CAP)
 		}
 	};
 

From c5b471092003e6de530a9f40d3461bf4dfe21ff8 Mon Sep 17 00:00:00 2001
From: David <david@gskinner.com>
Date: Fri, 15 Dec 2017 12:11:32 -0700
Subject: [PATCH 18/39] fixed color-burn

---
 src/easeljs/display/StageGL.js | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/easeljs/display/StageGL.js b/src/easeljs/display/StageGL.js
index bd806aac2..01df7afde 100644
--- a/src/easeljs/display/StageGL.js
+++ b/src/easeljs/display/StageGL.js
@@ -973,9 +973,9 @@ this.createjs = this.createjs||{};
 				"clamp(dstClr / (1.0 - srcClr), 0.0, 1.0)"
 			+ StageGL.BLEND_FRAGMENT_COMPLEX_CAP)
 		},
-		"color-burn": {																									// CLOSE
+		"color-burn": {
 			shader: (StageGL.BLEND_FRAGMENT_COMPLEX +
-				"1.0 - (clamp((1.0 - dstClr) / srcClr, 0.0, 1.0))"
+				"1.0 - clamp((1.0 - smoothstep(0.0035, 0.9955, dstClr)) / smoothstep(0.0035, 0.9955, srcClr), 0.0, 1.0)"
 			+ StageGL.BLEND_FRAGMENT_COMPLEX_CAP)
 		},
 		"difference": { // do this to match visible results in browsers

From c8ccbdc8eb963abc6d3fbb2ae7526cb06c91a0aa Mon Sep 17 00:00:00 2001
From: David <david@gskinner.com>
Date: Mon, 18 Dec 2017 10:11:03 -0700
Subject: [PATCH 19/39] resolved issues with hanging content

---
 src/easeljs/display/StageGL.js | 37 +++++++++++++++++++++++++---------
 1 file changed, 28 insertions(+), 9 deletions(-)

diff --git a/src/easeljs/display/StageGL.js b/src/easeljs/display/StageGL.js
index 01df7afde..1dd77ccae 100644
--- a/src/easeljs/display/StageGL.js
+++ b/src/easeljs/display/StageGL.js
@@ -809,7 +809,7 @@ this.createjs = this.createjs||{};
 		// note this is an open bracket on main!
 	);
 
-	StageGL.BLEND_FRAGMENT_COMPLEX = (																					// CLOSE
+	StageGL.BLEND_FRAGMENT_COMPLEX = (
 		StageGL.BLEND_FRAGMENT_SIMPLE +
 			"vec3 srcClr = min(src.rgb/src.a, 1.0);" +
 			"vec3 dstClr = min(dst.rgb/dst.a, 1.0);" +
@@ -876,11 +876,21 @@ this.createjs = this.createjs||{};
 			//srcRGB: "ONE",							srcA: "ONE"
 			//dstRGB: "ONE_MINUS_SRC_ALPHA",			dstA: "ONE_MINUS_SRC_ALPHA"
 		},
-		"source-in": {																									// CLOSE
+		"source-in": {
+			shader: (StageGL.BLEND_FRAGMENT_SIMPLE +
+				"gl_FragColor = vec4(src.rgb * dst.a, src.a * dst.a);" +
+			"}")
+		},
+		"source-in_cheap": {
 			srcRGB: "DST_ALPHA",					srcA: "ZERO",
 			dstRGB: "ZERO",							dstA: "SRC_ALPHA"
 		},
-		"source-out": {																									// CLOSE
+		"source-out": {
+			shader: (StageGL.BLEND_FRAGMENT_SIMPLE +
+				"gl_FragColor = vec4(src.rgb * (1.0 - dst.a), src.a - dst.a);" +
+			"}")
+		},
+		"source-out_cheap": {
 			eqA: "FUNC_SUBTRACT",
 			srcRGB: "ONE_MINUS_DST_ALPHA",			srcA: "ONE",
 			dstRGB: "ZERO",							dstA: "SRC_ALPHA"
@@ -893,7 +903,12 @@ this.createjs = this.createjs||{};
 			srcRGB: "ONE_MINUS_DST_ALPHA",			srcA: "ONE_MINUS_DST_ALPHA",
 			dstRGB: "ONE",							dstA: "ONE"
 		},
-		"destination-in": {																								// CLOSE
+		"destination-in": {
+			shader: (StageGL.BLEND_FRAGMENT_SIMPLE +
+				"gl_FragColor = vec4(dst.rgb * src.a, src.a * dst.a);" +
+			"}")
+		},
+		"destination-in_cheap": {
 			srcRGB: "ZERO",							srcA: "DST_ALPHA",
 			dstRGB: "SRC_ALPHA",					dstA: "ZERO"
 		},
@@ -902,7 +917,12 @@ this.createjs = this.createjs||{};
 			srcRGB: "ZERO",							srcA: "DST_ALPHA",
 			dstRGB: "ONE_MINUS_SRC_ALPHA",			dstA: "ONE"
 		},
-		"destination-atop": {																							// CLOSE
+		"destination-atop": {
+			shader: (StageGL.BLEND_FRAGMENT_SIMPLE +
+			"gl_FragColor = vec4(dst.rgb * src.a + src.rgb * (1.0 - dst.a), src.a);" +
+			"}")
+		},
+		"destination-atop_cheap": {
 			srcRGB: "ONE_MINUS_DST_ALPHA",			srcA: "ONE",
 			dstRGB: "SRC_ALPHA",					dstA: "ZERO"
 		},
@@ -913,9 +933,8 @@ this.createjs = this.createjs||{};
 			shader: (StageGL.BLEND_FRAGMENT_SIMPLE +
 				"float omSRC = (1.0 - src.a);" +
 				"float omDST = (1.0 - dst.a);" +
-				"gl_FragColor = vec4(src.rgb * omDST + dst.rgb * omSRC, src.a * omDST + dst.a * omSRC);" +
-			"}"
-			)
+				"gl_FragColor = vec4(src.rgb * omDST + dst.rgb * omSRC, src.a * omDST + dst.a * omSRC);"
+			+ "}")
 		},
 
 		"multiply": { // this has to be complex to handle retention of both dst and src in non mixed scenarios
@@ -2149,7 +2168,7 @@ this.createjs = this.createjs||{};
 					eqA: gl[blendSrc.eqA || "FUNC_ADD"],
 					srcA: gl[blendSrc.srcA || "ONE"],
 					dstA: gl[blendSrc.dstA || "ONE_MINUS_SRC_ALPHA"],
-					immediate: Boolean(blendSrc.shader),
+					immediate: blendSrc.shader !== undefined,
 					shader: (blendSrc.shader || this._builtShaders["source-over"] === undefined) ?
 						this._fetchShaderProgram(
 							"cover", undefined, blendSrc.shader,

From 7f07f2604d890047824025d316e3d993306367d2 Mon Sep 17 00:00:00 2001
From: David Gillen <david@gskinner.com>
Date: Mon, 5 Mar 2018 10:26:12 -0700
Subject: [PATCH 20/39] code quality, documentation, and incomplete transition
 to new internal cache and filter drawing structure

---
 src/easeljs/display/DisplayObject.js |  16 +-
 src/easeljs/display/StageGL.js       | 514 ++++++++++++++++-----------
 src/easeljs/filters/BitmapCache.js   | 168 +++++++--
 3 files changed, 447 insertions(+), 251 deletions(-)

diff --git a/src/easeljs/display/DisplayObject.js b/src/easeljs/display/DisplayObject.js
index 36b9f84f9..ebbd5c92b 100644
--- a/src/easeljs/display/DisplayObject.js
+++ b/src/easeljs/display/DisplayObject.js
@@ -153,7 +153,7 @@ this.createjs = this.createjs||{};
 		 * If a cache is active, this returns the canvas that holds the image of this display object. See {{#crossLink "DisplayObject/cache:method"}}{{/crossLink}}
 		 * for more information. Use this to display the result of a cache. This will be a HTMLCanvasElement unless special cache rules have been deliberately enabled for this cache.
 		 * @property cacheCanvas
-		 * @type {HTMLCanvasElement | Object}
+		 * @type {HTMLCanvasElement | WebGLTexture | Object}
 		 * @default null
 		 * @readonly
 		 **/
@@ -457,6 +457,15 @@ this.createjs = this.createjs||{};
 		 * @default 0
 		 */
 		this._webGLRenderStyle = DisplayObject._StageGL_NONE;
+
+		/**
+		 * Storage for the calculated position of an object in StageGL
+		 * @property _glMtx
+		 * @protected
+		 * @type {Rectangle}
+		 * @default null
+		 */
+		this._glMtx = null;
 	}
 	var p = createjs.extend(DisplayObject, createjs.EventDispatcher);
 
@@ -996,8 +1005,9 @@ this.createjs = this.createjs||{};
 	 * @return {Matrix2D} A matrix representing this display object's transform.
 	 **/
 	p.getMatrix = function(matrix) {
-		var o = this, mtx = matrix&&matrix.identity() || new createjs.Matrix2D();
-		return o.transformMatrix ?  mtx.copy(o.transformMatrix) : mtx.appendTransform(o.x, o.y, o.scaleX, o.scaleY, o.rotation, o.skewX, o.skewY, o.regX, o.regY);
+		var o = this, mtx = matrix || new createjs.Matrix2D();
+		return o.transformMatrix ?  mtx.copy(o.transformMatrix) :
+			(matrix.identity() && mtx.appendTransform(o.x, o.y, o.scaleX, o.scaleY, o.rotation, o.skewX, o.skewY, o.regX, o.regY));
 	};
 
 	/**
diff --git a/src/easeljs/display/StageGL.js b/src/easeljs/display/StageGL.js
index 1dd77ccae..a9147c80b 100644
--- a/src/easeljs/display/StageGL.js
+++ b/src/easeljs/display/StageGL.js
@@ -41,12 +41,12 @@ this.createjs = this.createjs||{};
  * Index/Indices: used in groups of 3 to define a triangle, points to vertices by their index in an array (some render
  * 		modes do not use these)
  * Card: a group of 2 triangles used to display a rectangular image
- * U/V: common names for the [0-1] texture co-ordinates on an image
- * Batch: a single call to the renderer, best done as little as possible so multiple cards are put into a single batch
+ * UV: common names for the [0-1] texture co-ordinates on an image
+ * Batch: a single call to the renderer, best done as little as possible. Multiple cards are batched for this reason
  * Program/Shader: For every vertex we run the Vertex shader. The results are used per pixel by the Fragment shader. When
- * 		combined and paired these are a shader "program"
- * Texture: WebGL representation of image data and associated extra information
- * Slot: A space on the GPU into which textures can be loaded for use in a batch, using "ActiveTexture" switches texture slot.
+ * 		combined and paired these are a "shader program"
+ * Texture: WebGL representation of image data and associated extra information, separate from a DOM Image
+ * Slot: A space on the GPU into which textures can be loaded for use in a batch, i.e. using "ActiveTexture" switches texture slot.
  * Render___: actual WebGL draw call
  * Buffer: WebGL array data
  * Cover: A card that covers the entire viewport
@@ -57,16 +57,16 @@ this.createjs = this.createjs||{};
  * 		code that deals with x/y, be aware your y may be flipped.
  * Older versions had distinct internal paths for filters and regular draws, these have been merged.
  * Draws are slowly assembled out of found content. Overflowing things like shaders, object/texture count will cause
- * 		an early draw before continuing. Lookout for the things that force a draw (marked with <------------------------
+ * 		an early draw before continuing. Lookout for the things that force a draw. Marked with <------------------------
  */
 
 (function () {
 	"use strict";
 
 	/**
-	 * A StageGL instance is the root level {{#crossLink "Container"}}{{/crossLink}} for an WebGL-optimized display list,
-	 * which is used in place of the usual {{#crossLink "Stage"}}{{/crossLink}}. This class should behave identically to
-	 * a {{#crossLink "Stage"}}{{/crossLink}} except for WebGL-specific functionality.
+	 * A StageGL instance is the root level {{#crossLink "Container"}}{{/crossLink}} for a WebGL-optimized display list,
+	 * which can be used in place of the usual {{#crossLink "Stage"}}{{/crossLink}}. This class should behave identically
+	 * to a {{#crossLink "Stage"}}{{/crossLink}} except for WebGL-specific functionality.
 	 *
 	 * Each time the {{#crossLink "Stage/tick"}}{{/crossLink}} method is called, the display list is rendered to the
 	 * target &lt;canvas/&gt; instance, ignoring non-WebGL-compatible display objects. On devices and browsers that don't
@@ -104,37 +104,40 @@ this.createjs = this.createjs||{};
 	 *          stage.update();
 	 *      }
 	 *
-	 * <h4>Notes</h4>
-	 * - StageGL is not currently included in the minified version of EaselJS.
-	 * - {{#crossLink "SpriteContainer"}}{{/crossLink}} (the previous approach to WebGL with EaselJS) has been deprecated.
-	 * - Earlier versions of WebGL support in EaselJS (SpriteStage and SpriteContainer) had hard limitations on images
-	 * 	per container, which have been solved.
-	 *
 	 * @class StageGL
 	 * @extends Stage
 	 * @constructor
 	 * @param {HTMLCanvasElement | String | Object} canvas A canvas object that StageGL will render to, or the string id
-	 *  of a canvas object in the current DOM.
+	 * of a canvas object in the current DOM.
 	 * @param {Object} options All the option parameters in a reference object, some are not supported by some browsers.
 	 * @param {Boolean} [options.preserveBuffer=false] If `true`, the canvas is NOT auto-cleared by WebGL (the spec
-	 *  discourages setting this to `true`). This is useful if you want persistent draw effects.
+	 * discourages setting this to `true`). This is useful if you want persistent draw effects and has also fixed device
+	 * specific bugs due to mis-timed clear commands.
 	 * @param {Boolean} [options.antialias=false] Specifies whether or not the browser's WebGL implementation should try
-	 *  to perform anti-aliasing. This will also enable linear pixel sampling on power-of-two textures (smoother images).
+	 * to perform anti-aliasing. This will also enable linear pixel sampling on power-of-two textures (smoother images).
 	 * @param {Boolean} [options.transparent=false] If `true`, the canvas is transparent. This is <strong>very</strong>
 	 * expensive, and should be used with caution.
-	 * @param {Integer} [options.autoPurge=1200] How often the system should automatically dump unused textures with
-	 * `purgeTextures(autoPurge)` every `autoPurge/2` draws. See {{#crossLink "StageGL/purgeTextures"}}{{/crossLink}} for more
-	 * information.
+	 * @param {Boolean} [options.directDraw=false] If `true`, this will bypass intermediary render-textures when possible
+	 * resulting in reduced memory and increased performance, this disables some features. Cache-less filters and some
+	 * {{#crossLink "DisplayObject/compositeOperation:property"}}{{/crossLink}} values rely on this being false.
+	 * @param (Boolean} [options.premultiply] @deprecated Upgraded colour & transparency handling have fixed the issue
+	 * this flag was trying to solve rendering it unnecessary.
+	 * @param {int} [options.autoPurge=1200] How often the system should automatically dump unused textures. Calls
+	 * `purgeTextures(autoPurge)` every `autoPurge/2` draws. See {{#crossLink "StageGL/purgeTextures"}}{{/crossLink}}
+	 * for more information on texture purging.
+	 * @param {String|int} [options.clearColor=undefined] Automatically calls {{#crossLink "StageGL/setClearColor"}}{{/crossLink}}
+	 * after init is complete, can be overridden and changed manually later.
 	 */
 	function StageGL(canvas, options) {
 		this.Stage_constructor(canvas);
 
+		var transparent, antialias, preserveBuffer, autoPurge, directDraw;
 		if (options !== undefined) {
 			if (typeof options !== "object"){ throw("Invalid options object"); }
-			var transparent = options.transparent;
-			var antialias = options.antialias;
-			var preserveBuffer = options.preserveBuffer;
-			var autoPurge = options.autoPurge;
+			transparent = options.transparent;
+			antialias = options.antialias;
+			preserveBuffer = options.preserveBuffer;
+			autoPurge = options.autoPurge;
 		}
 
 // public properties:
@@ -147,6 +150,18 @@ this.createjs = this.createjs||{};
 		 */
 		this.vocalDebug = false;
 
+		/**
+		 * Specifies whether this instance is slaved to a {{#crossLink "BitmapCache"}}{{/crossLink}} or is its own master.
+		 * Controls whether final rendering output of a {{#crossLink "cacheDraw"}}{{/crossLink}} command is to the canvas
+		 * or a render texture. See the {{#crossLink "cache"}}{{/crossLink}} function documentation and read the code for
+		 * full implications and details of necessity. Enabled by default when BitmapCache's `useGL` is true.
+		 * NOTE: This method is mainly for internal use, though it may be useful for advanced uses.
+		 * @property isCacheControlled
+		 * @type {Boolean}
+		 * @default false
+		 */
+		this.isCacheControlled = false;
+
 // private properties:
 		/**
 		 * Specifies whether or not the canvas is auto-cleared by WebGL. The WebGL spec discourages `true`.
@@ -181,11 +196,24 @@ this.createjs = this.createjs||{};
 		 * Internal value of {{#crossLink "StageGL/autoPurge"}}{{/crossLink}}
 		 * @property _autoPurge
 		 * @protected
-		 * @type {Integer}
+		 * @type {int}
 		 * @default null
 		 */
 		this._autoPurge = undefined;
-		this.autoPurge = autoPurge;	//getter/setter handles setting the real value and validating
+		this.autoPurge = autoPurge;	//getter/setter handles setting the real value and validating and documentation
+
+		/**
+		 * aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+		 * aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+		 * aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+		 * aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+		 * aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+		 * @property _directDraw
+		 * @protected
+		 * @type {Boolean}
+		 * @default false
+		 */
+		this._directDraw = directDraw;
 
 		/**
 		 * The width in px of the drawing surface saved in memory.
@@ -241,7 +269,7 @@ this.createjs = this.createjs||{};
 		 * @type {Number}
 		 * @default StageGL.DEFAULT_MAX_BATCH_SIZE (10000)
 		 */
-		this._maxCardsPerBatch = StageGL.DEFAULT_MAX_BATCH_SIZE;														//TODO: write getter/setters for this
+		this._maxCardsPerBatch = StageGL.DEFAULT_MAX_BATCH_SIZE;
 
 		/**
 		 * The shader program used to draw the current batch.
@@ -251,8 +279,12 @@ this.createjs = this.createjs||{};
 		 * @default null
 		 */
 		this._activeShader = null;
-		this._activeBuffer = null;
 
+		/**
+		 * The non cover, per object shader used for most rendering actions.
+		 * @type {WebGLProgram}
+		 * @protected
+		 */
 		this._mainShader = null;
 
 		/**
@@ -274,7 +306,7 @@ this.createjs = this.createjs||{};
 		this._vertexPositionBuffer = null;
 
 		/**
-		 * The vertex U/V data for the current draw call.
+		 * The vertex UV data for the current draw call.
 		 * @property _uvs
 		 * @protected
 		 * @type {Float32Array}
@@ -327,10 +359,38 @@ this.createjs = this.createjs||{};
 		 */
 		this._alphaBuffer = null;
 
-		this._bufferTextureOutput = null;		// what you're drawing to, occasionally swaps with concat
-		this._bufferTextureConcat = null;		// what you've draw before now, occasionally swaps with output
-		this._bufferTextureTemp = null;			// temporary surface for mixing in other objects
+		/**
+		 * One of the major buffers used in composite blending drawing. Do not expect this to always be the same object
+		 * "what you're drawing to, occasionally swaps with concat"
+		 * @type {WebGLTexture}
+		 * @private
+		 */
+		this._bufferTextureOutput = null;
+
+		/**
+		 * One of the major buffers used in composite blending drawing. Do not expect this to always be the same object
+		 * "wwhat you've draw before now, occasionally swaps with output"
+		 * @type {WebGLTexture}
+		 * @private
+		 */
+		this._bufferTextureConcat = null;
+
+		/**
+		 * One of the major buffers used in composite blending drawing. Do not expect this to always be the same object
+		 * "temporary surface for mixing in other objects"
+		 * @type {WebGLTexture}
+		 * @private
+		 */
+		this._bufferTextureTemp = null;
 
+		/**
+		 * Internal library of the shaders that have been compiled and created along with their parameters. Should contain
+		 * compiled `gl.ShaderProgram` and settings for `gl.blendFunc` and `gl.blendEquation`. Populated as requested.
+		 *
+		 * See {{#crossLink "StageGL/_updateRenderMode:method"}}{{/crossLink}} for exact details.
+		 * @type {Object}
+		 * @private
+		 */
 		this._builtShaders = {};
 
 		/**
@@ -401,7 +461,22 @@ this.createjs = this.createjs||{};
 		 */
 		this._lastTextureInsert = -1;
 
+		/**
+		 * The current string name of the render mode being employed per Context2D spec.
+		 * Must start invalid to trigger default shader into being built during init.
+		 * https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/globalCompositeOperation
+		 * @type {string}
+		 * @private
+		 */
 		this._renderMode = "";
+
+		/**
+		 * Flag indicating that the content being batched in `appendToBatch` must be drawn now and not follow batch logic.
+		 * Used for effects that are compounding in nature and cannot be applied in a single pass.
+		 * Should be enabled with extreme care due to massive performance implications.
+		 * @type {boolean}
+		 * @private
+		 */
 		this._immediateRender = false;
 
 		/**
@@ -439,15 +514,6 @@ this.createjs = this.createjs||{};
 		 */
 		this._slotBlacklist = [];
 
-		/**
-		 * Used to prevent nested draw calls from accidentally overwriting drawing information by tracking depth.
-		 * @property _isDrawing
-		 * @protected
-		 * @type {Number}
-		 * @default 0
-		 */
-		this._isDrawing = 0;
-
 		/**
 		 * Used to ensure every canvas used as a texture source has a unique ID.
 		 * @property _lastTrackedCanvas
@@ -457,17 +523,6 @@ this.createjs = this.createjs||{};
 		 */
 		this._lastTrackedCanvas = -1;
 
-		/**
-		 * Controls whether final rendering output of a {{#crossLink "cacheDraw"}}{{/crossLink}} is the canvas or a render
-		 * texture. See the {{#crossLink "cache"}}{{/crossLink}} function modifications for full implications and discussion.
-		 * @property isCacheControlled
-		 * @protected
-		 * @type {Boolean}
-		 * @default false
-		 * @todo LM: is this supposed to be _isCacheControlled since its private?
-		 */
-		this.isCacheControlled = false;
-
 		/**
 		 * Used to counter-position the object being cached so it aligns with the cache surface. Additionally ensures
 		 * that all rendering starts with a top level container.
@@ -480,12 +535,18 @@ this.createjs = this.createjs||{};
 
 		// and begin
 		this._initializeWebGL();
+
+		// these settings require everything to be ready
+		if (options !== undefined) {
+			options.clearColor !== undefined && this.setClearColor(options.clearColor);
+			options.premultiply !== undefined && (createjs.deprecate(null, "options.premultiply")());
+		}
 	}
 	var p = createjs.extend(StageGL, createjs.Stage);
 
 // static methods:
 	/**
-	 * Calculate the U/V co-ordinate based info for sprite frames. Instead of pixel count it uses a 0-1 space. Also includes
+	 * Calculate the UV co-ordinate based info for sprite frames. Instead of pixel count it uses a 0-1 space. Also includes
 	 * the ability to get info back for a specific frame, or only calculate that one frame.
 	 *
 	 *     //generate UV rects for all entries
@@ -508,8 +569,8 @@ this.createjs = this.createjs||{};
 		if (target === undefined) { target = -1; }
 		if (onlyTarget === undefined) { onlyTarget = false; }
 
-		var start = (target != -1 && onlyTarget)?(target):(0);
-		var end = (target != -1 && onlyTarget)?(target+1):(spritesheet._frames.length);
+		var start = (target !== -1 && onlyTarget)?(target):(0);
+		var end = (target !== -1 && onlyTarget)?(target+1):(spritesheet._frames.length);
 		for (var i=start; i<end; i++) {
 			var f = spritesheet._frames[i];
 			if (f.uvRect || f.image.width <= 0 || f.image.height <= 0) { continue; }
@@ -523,13 +584,13 @@ this.createjs = this.createjs||{};
 			};
 		}
 
-		return spritesheet._frames[(target != -1) ? target : 0].uvRect || {t:0, l:0, b:1, r:1};
+		return spritesheet._frames[(target !== -1) ? target : 0].uvRect || {t:0, l:0, b:1, r:1};
 	};
 
 	/**
 	 * Test a context to see if it has WebGL enabled on it.
 	 * @method isWebGLActive
-	 * @param {CanvasContext} ctx The context to test
+	 * @param {CanvasRenderingContext2D | WebGLRenderingContext} ctx The context to test
 	 * @static
 	 * @return {Boolean} Whether WebGL is enabled
 	 */
@@ -587,7 +648,7 @@ this.createjs = this.createjs||{};
 	StageGL.WEBGL_MAX_INDEX_NUM = Math.pow(2, 16);
 
 	/**
-	 * Default U/V rect for dealing with full coverage from an image source.
+	 * Default UV rect for dealing with full coverage from an image source.
 	 * @property UV_RECT
 	 * @static
 	 * @final
@@ -616,7 +677,7 @@ this.createjs = this.createjs||{};
 		]);
 
 		/**
-		 * U/V for {{#crossLink "StageGL/COVER_VERT:property"}}{{/crossLink}}.
+		 * UV for {{#crossLink "StageGL/COVER_VERT:property"}}{{/crossLink}}.
 		 * @property COVER_UV
 		 * @static
 		 * @final
@@ -927,6 +988,11 @@ this.createjs = this.createjs||{};
 			dstRGB: "SRC_ALPHA",					dstA: "ZERO"
 		},
 		"copy": {
+			shader: (StageGL.BLEND_FRAGMENT_SIMPLE +
+				"gl_FragColor = vec4(src.rgb, src.a);" +
+			"}")
+		},
+		"copy_cheap": {
 			dstRGB: "ZERO",							dstA: "ZERO"
 		},
 		"xor": {
@@ -1049,7 +1115,7 @@ this.createjs = this.createjs||{};
 
 	p._set_autoPurge = function (value) {
 		value = isNaN(value)?1200:value;
-		if (value != -1) {
+		if (value !== -1) {
 			value = value<10?10:value;
 		}
 		this._autoPurge = value;
@@ -1071,10 +1137,12 @@ this.createjs = this.createjs||{};
 
 			/**
 			 * Specifies whether or not StageGL is automatically purging unused textures. Higher numbers purge less
-			 * often. Values below 10 are upgraded to 10, and -1 disables this feature.
+			 * often. Values below 10 are upgraded to 10, and -1 disables this feature. If you are not dynamically adding
+			 * and removing new images this can be se9000t to -1, and should be for performance reasons. If you only add images,
+			 * or add and remove the same images for the entire application, it is safe to turn off this feature. Alternately,
+			 * manually manage removing textures yourself with {{#crossLink "StageGL/releaseTexture"}}{{/crossLink}}
 			 * @property autoPurge
-			 * @protected
-			 * @type {Integer}
+			 * @type {int}
 			 * @default 1000
 			 */
 			autoPurge: { get: p._get_autoPurge, set: p._set_autoPurge }
@@ -1118,10 +1186,12 @@ this.createjs = this.createjs||{};
 				this._initMaterials();
 				this._updateRenderMode("source-over");
 
-				this.updateViewport(this._viewportWidth || this.canvas.width, this._viewportHeight || this.canvas.height);
-				this._bufferTextureOutput = this.getRenderBufferTexture(this._viewportWidth, this._viewportHeight);
-				this._bufferTextureConcat = this.getRenderBufferTexture(this._viewportWidth, this._viewportHeight);
-				this._bufferTextureTemp = this.getRenderBufferTexture(this._viewportWidth, this._viewportHeight);
+				this.updateViewport(this.canvas.width, this.canvas.height);
+				if(!this._directDraw) {
+					this._bufferTextureOutput = this.getRenderBufferTexture(this._viewportWidth, this._viewportHeight);
+					this._bufferTextureConcat = this.getRenderBufferTexture(this._viewportWidth, this._viewportHeight);
+					this._bufferTextureTemp = this.getRenderBufferTexture(this._viewportWidth, this._viewportHeight);
+				}
 
 				this.canvas._invalid = true;
 			}
@@ -1196,13 +1266,12 @@ this.createjs = this.createjs||{};
 		if (this.autoClear) { this.clear(); }
 
 		this._updateRenderMode("source-over");
-		this._drawContent(this, ignoreCache);
+		this._drawContent(this._bufferTextureOutput._frameBuffer, this, ignoreCache);
 
-		this._updateRenderMode("source-over");
 		this.batchReason = "finalOutput";
 		this._drawCover(null, this._bufferTextureOutput);
 
-		if (this._autoPurge != -1 && !(this._drawID%((this._autoPurge/2)|0))) {
+		if (this._autoPurge !== -1 && !(this._drawID%((this._autoPurge/2)|0))) {
 			this.purgeTextures(this._autoPurge);
 		}
 
@@ -1216,7 +1285,6 @@ this.createjs = this.createjs||{};
 	 * @method cacheDraw
 	 * @param {DisplayObject} target The object we're drawing into cache.
 	 * For example, used for drawing the cache (to prevent it from simply drawing an existing cache back into itself).
-	 * @param {Array} filters The filters we're drawing into cache.
 	 * @param {BitmapCache} manager The BitmapCache instance looking after the cache
 	 * @return {Boolean} If the draw was handled by this function
 	 */
@@ -1226,7 +1294,28 @@ this.createjs = this.createjs||{};
 			return false;
 		}
 
-		this._cacheDraw(target, target.filters, manager);
+		// TODO: fix it so we don't have to do this
+		var temp = this._directDraw;
+		this._directDraw = true;
+
+		var filterCount = manager._filterCount;
+		var backupWidth = this._viewportWidth, backupHeight = this._viewportHeight;
+		this.updateViewport(manager._drawWidth, manager._drawHeight);
+
+		var contentStamp = manager._getGLContentTarget();
+		var container = this._cacheContainer;
+		container.children = [target];
+		container.transformMatrix = this._alignTargetToCache(target, manager);
+
+		this._updateRenderMode("source-over");
+		this._drawContent(contentStamp._frameBuffer, container, true);
+
+		if(filterCount) {
+			this._drawFilters(contentStamp, target, manager);
+		}
+
+		this.updateViewport(backupWidth, backupHeight);
+		this._directDraw = temp;
 		return true;
 	};
 
@@ -1235,40 +1324,41 @@ this.createjs = this.createjs||{};
 	 * This function creates, gets, and adjusts the specified render surface.
 	 *
 	 * @method getTargetRenderTexture
-	 * @param  {DisplayObject} target The object associated with the render textures, usually a cached object.
+	 * @param  {BitmapCache} target The object associated with the render textures, usually a cached object.
 	 * @param  {Number} w The width to create the texture at.
 	 * @param  {Number} h The height to create the texture at.
 	 * @param  {Boolean} [primary=false] Whether this is the primary render surface
 	 * @return {WebGLTexture}
 	 */
 	p.getTargetRenderTexture = function (target, w, h, primary) {
-		var result, gl = this._webGLContext;
+		var output, lookup;
+
+		// create if new
 		if (primary) {
-			result = target._renderTextureOut;
-			if (!result) {
-				result = target._renderTextureOut = this.getRenderBufferTexture(w, h);
-			} else {
-				if (w != result._width || h != result._height) {
-					this.resizeTexture(result, w, h);
-				}
-				this.setTextureParams(gl);
+			lookup = target._renderTextureOut;
+			if (!lookup) {
+				output = target._renderTextureOut = this.getRenderBufferTexture(w, h);
 			}
 		} else {
-			result = target._renderTextureTemp;
-			if (!result) {
-				result = target._renderTextureTemp = this.getRenderBufferTexture(w, h);
-			} else {
-				if (w != result._width || h != result._height) {
-					this.resizeTexture(result, w, h);
-				}
-				this.setTextureParams(gl);
+			lookup = target._renderTextureTemp;
+			if (!lookup) {
+				output = target._renderTextureTemp = this.getRenderBufferTexture(w, h);
+			}
+		}
+
+		// configure if we found it, make sure it's configured right
+		if(lookup) {
+			if (w !== lookup._width || h !== lookup._height) {
+				this.resizeTexture(lookup, w, h);
 			}
+			this.setTextureParams(this._webGLContext);
+			output = lookup;
 		}
 
-		if (result == null) {
+		if (output == null) {
 			throw "Problems creating render textures, known causes include using too much VRAM by not releasing WebGL texture instances";
 		}
-		return result;
+		return output;
 	};
 
 	/**
@@ -1282,7 +1372,7 @@ this.createjs = this.createjs||{};
 	 * developer to ensure that a texture in use is not removed.
 	 *
 	 * Textures in use, or to be used again shortly, should not be removed. This is simply for performance reasons.
-	 * Removing a texture in use will cause the texture to have to be re-uploaded slowing rendering.
+	 * Removing a texture in use will cause the texture to end up being re-uploaded slowing rendering.
 	 * @method releaseTexture
 	 * @param {DisplayObject | WebGLTexture | Image | Canvas} item An object that used the texture to be discarded.
 	 * @param {Boolean} [safe=false] Should the release attempt to be "safe" and only delete this usage.
@@ -1383,8 +1473,8 @@ this.createjs = this.createjs||{};
 	 * the render surface's instead. This is necessary after manually resizing the canvas element on the DOM to avoid a
 	 * up/down scaled render.
 	 * @method updateViewport
-	 * @param {Integer} width The width of the render surface in pixels.
-	 * @param {Integer} height The height of the render surface in pixels.
+	 * @param {int} width The width of the render surface in pixels.
+	 * @param {int} height The height of the render surface in pixels.
 	 */
 	p.updateViewport = function (width, height) {
 		this._viewportWidth = width|0;
@@ -1438,7 +1528,7 @@ this.createjs = this.createjs||{};
 		} else {
 			try {
 				targetShader = this._fetchShaderProgram(
-					"cover", filter.VTX_SHADER_BODY, filter.FRAG_SHADER_BODY,
+					true, filter.VTX_SHADER_BODY, filter.FRAG_SHADER_BODY,
 					filter.shaderParamSetup && filter.shaderParamSetup.bind(filter)
 				);
 				filter._builtShader = targetShader;
@@ -1502,7 +1592,7 @@ this.createjs = this.createjs||{};
 	/**
 	 * Returns a base texture (see {{#crossLink "StageGL/getBaseTexture"}}{{/crossLink}}) for details. Also includes an
 	 * attached and linked render buffer in `texture._frameBuffer`. RenderTextures can be thought of as an internal
-	 * canvas on the GPU that can be drawn to.
+	 * canvas on the GPU that can be drawn to. Being internal to the GPU they are much faster than "offscreen canvases".
 	 * @method getRenderBufferTexture
 	 * @param  {Number} w The width of the texture in pixels.
 	 * @param  {Number} h The height of the texture in pixels.
@@ -1577,16 +1667,16 @@ this.createjs = this.createjs||{};
 	p.setClearColor = function (color) {
 		var r, g, b, a, output;
 
-		if (typeof color == "string") {
-			if (color.indexOf("#") == 0) {
-				if (color.length == 4) {
+		if (typeof color === "string") {
+			if (color.indexOf("#") === 0) {
+				if (color.length === 4) {
 					color = "#" + color.charAt(1)+color.charAt(1) + color.charAt(2)+color.charAt(2) + color.charAt(3)+color.charAt(3)
 				}
 				r = Number("0x"+color.slice(1, 3))/255;
 				g = Number("0x"+color.slice(3, 5))/255;
 				b = Number("0x"+color.slice(5, 7))/255;
 				a = Number("0x"+color.slice(7, 9))/255;
-			} else if (color.indexOf("rgba(") == 0) {
+			} else if (color.indexOf("rgba(") === 0) {
 				output = color.slice(5, -1).split(",");
 				r = Number(output[0])/255;
 				g = Number(output[1])/255;
@@ -1621,6 +1711,7 @@ this.createjs = this.createjs||{};
 	 * @method _getSafeTexture
 	 * @param  {uint} [w=1] The width of the texture in pixels, defaults to 1
 	 * @param  {uint} [h=1] The height of the texture in pixels, defaults to 1
+	 * @protected
 	 */
 	p._getSafeTexture = function (w, h) {
 		var texture = this.getBaseTexture(w, h);
@@ -1635,6 +1726,12 @@ this.createjs = this.createjs||{};
 		return texture;
 	};
 
+	/**
+	 * Visually clear out the currently active FrameBuffer, does not rebind or adjust the frameBuffer in use.
+	 * @method _getSafeTexture
+	 * @param alpha
+	 * @protected
+	 */
 	p._clearFrameBuffer = function (alpha) {
 		var gl = this._webGLContext;
 		var cc = this._clearColor;
@@ -1682,13 +1779,13 @@ this.createjs = this.createjs||{};
 	 * filters. Once compiled, shaders are saved so. If the Shader code requires dynamic alterations re-run this function
 	 * to generate a new shader.
 	 * @method _fetchShaderProgram
-	 * @param  {Boolean} [coverShader=false] Is this a per object or a texture cover shader
+	 * @param  {Boolean} coverShader Is this a per object shader or a cover shader
 	 * Filter and override both accept the custom params. Regular and override have all features. Filter is a special case reduced feature shader meant to be over-ridden.
-	 * @param  {String} [customVTX] Extra vertex shader information to replace a regular draw, see 
+	 * @param  {String | undefined} [customVTX=undefined] Extra vertex shader information to replace a regular draw, see
 	 * {{#crossLink "StageGL/COVER_VERTEX_BODY"}}{{/crossLink}} for default and {{#crossLink "Filter"}}{{/crossLink}} for examples.
-	 * @param  {String} [customFRAG] Extra fragment shader information to replace a regular draw, see 
+	 * @param  {String | undefined} [customFRAG=undefined] Extra fragment shader information to replace a regular draw, see
 	 * {{#crossLink "StageGL/COVER_FRAGMENT_BODY"}}{{/crossLink}} for default and {{#crossLink "Filter"}}{{/crossLink}} for examples.
-	 * @param  {Function} [shaderParamSetup] Function to run so custom shader parameters can get applied for the render.
+	 * @param  {Function | undefined} [shaderParamSetup=undefined] Function to run so custom shader parameters can get applied for the render.
 	 * @protected
 	 * @return {WebGLProgram} The compiled and linked shader
 	 */
@@ -1802,7 +1899,7 @@ this.createjs = this.createjs||{};
 	};
 
 	/**
-	 * Sets up the necessary vertex property buffers, including position and U/V.
+	 * Sets up the necessary vertex property buffers, including position and UV.
 	 * @method _createBuffers
 	 * @protected
 	 */
@@ -1826,7 +1923,7 @@ this.createjs = this.createjs||{};
 
 		// var vertexBuffer = this._vertexBuffer = gl.createBuffer();
 		// gl.bindBuffer(gl.ARRAY_BUFFER, vertexBuffer);
-		// groupSize = 2 + 2 + 1 + 1; //x/y, u/v, index, alpha
+		// groupSize = 2 + 2 + 1 + 1; //{x,y}, {u,v}, index, alpha
 		// var vertexData = this._vertexData = new Float32Array(groupCount * groupSize);
 		// for (i=0; i<vertexData.length; i+=groupSize) {
 		// 	vertexData[i+0] = vertexData[i+1] = 0;
@@ -1902,7 +1999,7 @@ this.createjs = this.createjs||{};
 		var success = false;
 		while (!success) {
 			try {
-				this._fetchShaderProgram();
+				this._fetchShaderProgram(false);
 				success = true;
 			} catch(e) {
 				if (this._gpuTextureCount <= 1) { throw "Cannot compile shader " + e; }
@@ -1921,7 +2018,7 @@ this.createjs = this.createjs||{};
 		this._freeTextureCount = this._gpuTextureMax - this._textureTrackReserve;
 		this._batchTextureCount = Math.min(this._freeTextureCount, this._gpuTextureCount - this._textureDrawReserve);
 
-		this._mainShader = this._activeShader = this._fetchShaderProgram();
+		this._mainShader = this._activeShader = this._fetchShaderProgram(false);
 
 		// fill in blanks as it helps the renderer be stable while textures are loading and reduces need for safety code
 		var texture = this.getBaseTexture();
@@ -1970,7 +2067,7 @@ this.createjs = this.createjs||{};
 		}
 
 		// allow the texture to track its references for cleanup, if it's not an error ref
-		if (texture._storeID != -1) {
+		if (texture._storeID !== -1) {
 			texture._storeID = storeID;
 			if (texture._imageData) {
 				texture._imageData.push(image);
@@ -2055,7 +2152,7 @@ this.createjs = this.createjs||{};
 			var start = (this._lastTextureInsert+1) % this._batchTextureCount;
 			var look = start;
 			do {
-				if (this._batchTextures[look]._batchID != this._batchID && !this._slotBlacklist[look]) {
+				if (this._batchTextures[look]._batchID !== this._batchID && !this._slotBlacklist[look]) {
 					found = look;
 					break;
 				}
@@ -2065,7 +2162,7 @@ this.createjs = this.createjs||{};
 			// we couldn't find anywhere for it go, meaning we're maxed out
 			if (found === -1) {
 				this.batchReason = "textureOverflow";
-				this._renderBuffers();		// <------------------------------------------------------------------------
+				this._renderBatch();		// <------------------------------------------------------------------------
 				found = start; //TODO: how do we optimize this to be smarter?
 			}
 
@@ -2109,7 +2206,7 @@ this.createjs = this.createjs||{};
 		if (texture._storeID !== undefined && texture._storeID >= 0) {
 			this._textureDictionary[texture._storeID] = undefined;
 			for (var n in this._textureIDs) {
-				if (this._textureIDs[n] == texture._storeID) { delete this._textureIDs[n]; }
+				if (this._textureIDs[n] === texture._storeID) { delete this._textureIDs[n]; }
 			}
 			var data = texture._imageData;
 			for (var i=data.length-1; i>=0; i--) { data[i]._storeID = undefined; }
@@ -2139,6 +2236,14 @@ this.createjs = this.createjs||{};
 		}
 	};
 
+	/**
+	 * Small utility function to keep internal API consistent and set the uniforms for a dual texture cover render
+	 * @method _setCoverMixShaderParams
+	 * @param {WebGLRenderingContext} gl The context where the drawing takes place
+	 * @param stage unused
+	 * @param shaderProgram unused
+	 * @protected
+	 */
 	p._setCoverMixShaderParams = function (gl, stage, shaderProgram) {
 		gl.uniform1i(
 			gl.getUniformLocation(shaderProgram, "uMixSampler"),
@@ -2146,6 +2251,12 @@ this.createjs = this.createjs||{};
 		);
 	};
 
+	/**
+	 * Change the respective render settings and filters to the correct settings. Will build the shader on first use.
+	 * @method _updateRenderMode
+	 * @param {String} newMode Composite operation name
+	 * @protected
+	 */
 	p._updateRenderMode = function (newMode) {
 		if ( newMode === null || newMode === undefined){ newMode = "source-over"; }
 
@@ -2171,7 +2282,7 @@ this.createjs = this.createjs||{};
 					immediate: blendSrc.shader !== undefined,
 					shader: (blendSrc.shader || this._builtShaders["source-over"] === undefined) ?
 						this._fetchShaderProgram(
-							"cover", undefined, blendSrc.shader,
+							true, undefined, blendSrc.shader,
 							this._setCoverMixShaderParams
 						) : this._builtShaders["source-over"].shader // re-use source-over when we don't need a new shader
 				};
@@ -2182,8 +2293,13 @@ this.createjs = this.createjs||{};
 			}
 		}
 
+		if(shaderData.immediate && this._directDraw) {
+			if(this.vocalDebug) { console.log("ignored render mode ["+ newMode +"] due to directDraw"); }
+			return;
+		}
+
 		this.batchReason = "shaderSwap";
-		this._renderBuffers();		// <--------------------------------------------------------------------------------
+		this._renderBatch();		// <--------------------------------------------------------------------------------
 
 		this._renderMode = newMode;
 		this._immediateRender = shaderData.immediate;
@@ -2192,36 +2308,35 @@ this.createjs = this.createjs||{};
 	};
 
 	/**
-	 *
+	 * Helper function for the standard content draw
+	 * @param {WebGLFramebuffer} out Buffer to draw the results into (null is the canvas element)
 	 * @param {Stage | Container} content
 	 * @param {Boolean} ignoreCache
-	 * @private
+	 * @protected
 	 */
-	p._drawContent = function (content, ignoreCache) {
+	p._drawContent = function (out, content, ignoreCache) {
 		var gl = this._webGLContext;
 
-		this._isDrawing++;
-
 		this._activeShader = this._mainShader;
 
-		gl.bindFramebuffer(gl.FRAMEBUFFER, this._bufferTextureOutput._frameBuffer);
+		gl.bindFramebuffer(gl.FRAMEBUFFER, out);
 		gl.clear(gl.COLOR_BUFFER_BIT);
 
-		this._appendToBatchGroup(content, new createjs.Matrix2D(), this.alpha, ignoreCache);
+		this._appendToBatch(content, new createjs.Matrix2D(), this.alpha, ignoreCache);
 
 		this.batchReason = "contentEnd";
-		this._renderBuffers();
-
-		this._isDrawing--;
+		this._renderBatch();
 	};
 
 	/**
-	 *
-	 * @param {WebGLFramebuffer} out Buffer to draw the results into
-	 * @param {WebGLTexture} dst Base texture layer "destination"
-	 * @param {WebGLTexture} [src = undefined] Applied texture layer "source"
-	 * @param {Filter} [filter = undefined] Filter to use instead of blend mode
-	 * @private
+	 * Used to draw one or more textures potentially using a filter into the supplied buffer.
+	 * Mostly used for caches, filters, and outputting final render frames.
+	 * Draws `dst` into `out` after applying `src` (if specified) using `filter` or the current `_renderMode`.
+	 * @param {WebGLFramebuffer} out Buffer to draw the results into (null is the canvas element)
+	 * @param {WebGLTexture} dst Base texture layer aka "destination" in image blending terminology
+	 * @param {WebGLTexture} [src = undefined] Modification texture layer aka "source" in image blending terminology
+	 * @param {Filter} [filter = undefined] Filter to use instead of blend mode, must supply a src to work.
+	 * @protected
 	 */
 	p._drawCover = function (out, dst, src, filter) {
 		var gl = this._webGLContext;
@@ -2247,84 +2362,52 @@ this.createjs = this.createjs||{};
 		this._renderCover();
 	};
 
-	p._batchDraw = function(content, ignoreCache) {
-		this._appendToBatchGroup(content, new createjs.Matrix2D(), this.alpha, ignoreCache);
-		this.batchReason = "contentEnd";
-		this._renderBuffers();
-	};
-
 	/**
-	 * Perform the drawing process to fill a specific cache texture, including applying filters.
-	 * @method _cacheDraw
-	 * @param {DisplayObject} target The object we're drawing into the cache. For example, used for drawing the cache
-	 * (to prevent it from simply drawing an existing cache back into itself).
-	 * @param {Array} filters The filters we're drawing into cache.
-	 * @param {BitmapCache} manager The BitmapCache instance looking after the cache
-	 * @protected
+	 * Returns a matrix that can be used to counter position the `target` so that it fits and scales to the `manager`
+	 * @param {DisplayObject} target The object to be counter positioned
+	 * @param {BitmapCache} manager The cache manager to be aligned to
+	 * @returns {Matrix2D} The matrix that can be used used to counter position the container
+	 * @method _alignTargetToCache
+	 * @private
 	 */
-	p._cacheDraw = function(target, filters, manager) {
-		var gl = this._webGLContext;
-
-		/*
-		Implicitly there are 4 modes to this function: filtered-sameContext, filtered-uniqueContext, sameContext, uniqueContext.
-		Each situation must be handled slightly differently as 'sameContext' or 'uniqueContext' define how the output works,
-		one drawing directly into the main context and the other drawing into a stored renderTexture respectively.
-		When the draw is a 'filtered' draw, the filters are applied sequentially and will draw into saved textures repeatedly.
-		Once the final filter is done the final output is treated depending upon whether it is a same or unique context.
-		*/
-		var renderTexture;
-		var shaderBackup = this._activeShader;
-		var blackListBackup = this._slotBlacklist;
-		var lastTextureSlot = this._freeTextureCount;
-		var wBackup = this._viewportWidth, hBackup = this._viewportHeight;
+	p._alignTargetToCache = function(target, manager) {
+		if(manager._counterMatrix === null) {
+			manager._counterMatrix = target.getMatrix();
+		} else {
+			target.getMatrix(manager._counterMatrix)
+		}
 
-		// create offset container for drawing item
-		var mtx = target.getMatrix();
-		mtx = mtx.clone();
+		var mtx = manager._counterMatrix;
 		mtx.scale(1/manager.scale, 1/manager.scale);
 		mtx = mtx.invert();
 		mtx.translate(-manager.offX/manager.scale*target.scaleX, -manager.offY/manager.scale*target.scaleY);
-		var container = this._cacheContainer;
-		container.children = [target];
-		container.transformMatrix = mtx;
-
-		if (filters && filters.length) {
-			this._drawFilters(target, filters, manager);
-		} else {
-			// is this for another stage or mine?
-			if (this.isCacheControlled) {
-				// draw item to canvas				I -> C
-				gl.clear(gl.COLOR_BUFFER_BIT);
-				this._batchDraw(container, true);
-			} else {
-				gl.activeTexture(gl.TEXTURE0 + lastTextureSlot);
-				target.cacheCanvas = this.getTargetRenderTexture(target, manager._drawWidth, manager._drawHeight, true);
-				renderTexture = target.cacheCanvas;
-
-				// draw item to render texture		I -> T
-				gl.bindFramebuffer(gl.FRAMEBUFFER, renderTexture._frameBuffer);
-				this.updateViewport(manager._drawWidth, manager._drawHeight);
-				gl.clear(gl.COLOR_BUFFER_BIT);
-				this._batchDraw(container, true);
-
-				gl.bindFramebuffer(gl.FRAMEBUFFER, null);
-				this.updateViewport(wBackup, hBackup);
-			}
-		}
 
-		//this.protectTextureSlot(lastTextureSlot, false);
-		this._activeShader = shaderBackup;
-		this._slotBlacklist = blackListBackup;
+		return mtx;
 	};
 
 	/**
-	 * Sub portion of _cacheDraw, split off for readability. Do not call independently.
+	 * Sub portion of cacheDraw, split off for readability. Do not call independently. Swap surfaces are texture drawn
+	 * into back and forth due to limitations drawing a texture a into itself. This will draw into the managers out.
 	 * @method _drawFilters
+	 * @param {WebGLTexture} content A render texture which should contain original content
 	 * @param {DisplayObject} target The object we're drawing with a filter.
-	 * @param {Array} filters The filters we're drawing into cache.
 	 * @param {BitmapCache} manager The BitmapCache instance looking after the cache
 	 */
-	p._drawFilters = function(target, filters, manager) {
+	p._drawFilters = function(content, target, manager) {
+		// we can use one of the swap buffers as the out, but we need to notice that and start off on the right foot
+
+
+
+
+
+
+
+
+
+
+	};
+
+	p._drawFilters_OLD = function(target, filters, manager) {
 		var gl = this._webGLContext;
 		var renderTexture;
 		var lastTextureSlot = this._freeTextureCount;
@@ -2365,7 +2448,7 @@ this.createjs = this.createjs||{};
 			gl.activeTexture(gl.TEXTURE0 + lastTextureSlot);
 			renderTexture = this.getTargetRenderTexture(target, manager._drawWidth, manager._drawHeight, useOut);
 
-			if (filtersLeft == 0 && this.isCacheControlled) {
+			if (filtersLeft === 0 && this.isCacheControlled) {
 				gl.bindFramebuffer(gl.FRAMEBUFFER, null);
 
 				// draw result to canvas			R -> C
@@ -2400,18 +2483,18 @@ this.createjs = this.createjs||{};
 	/**
 	 * Add all the contents of a container to the pending buffers, called recursively on each container. This may
 	 * trigger a draw if a buffer runs out of space. This is the main workforce of the render loop.
-	 * @method _appendToBatchGroup
+	 * @method _appendToBatch
 	 * @param {Container} container The {{#crossLink "Container"}}{{/crossLink}} that contains everything to be drawn.
 	 * @param {Matrix2D} concatMtx The effective (concatenated) transformation matrix when beginning this container
 	 * @param {Number} concatAlpha The effective (concatenated) alpha when beginning this container
-	 * @param {Boolean} ignoreCache Don't use an element's cache during this draw
+	 * @param {Boolean} [ignoreCache=false] Don't use an element's cache during this draw
 	 * @protected
 	 */
-	p._appendToBatchGroup = function (container, concatMtx, concatAlpha, ignoreCache) {
+	p._appendToBatch = function (container, concatMtx, concatAlpha, ignoreCache) {
 		var gl = this._webGLContext;
 
 		// sort out shared properties
-		if (container._glMtx === undefined) { container._glMtx = new createjs.Matrix2D(); }
+		if (container._glMtx === undefined) { container._glMtx = new createjs.Matrix2D(); }		//TODO: benchmark removing this
 		var cMtx = container._glMtx;
 		cMtx.copy(concatMtx);
 		if (container.transformMatrix !== null) {
@@ -2438,18 +2521,19 @@ this.createjs = this.createjs||{};
 		var l = container.children.length;
 		for (var i = 0; i < l; i++) {
 			var item = container.children[i];
+			var useCache = item.cacheCanvas && !ignoreCache;
 
 			if (item.compositeOperation !== null) {
 				this._updateRenderMode(item.compositeOperation);
 			}
 
 			if (!(item.visible && concatAlpha > 0.0035)) { continue; }
-			if (item.cacheCanvas === null || ignoreCache) {
+			if (!useCache) {
 				if (item._updateState){
 					item._updateState();
 				}
 				if (item.children) {
-					this._appendToBatchGroup(item, cMtx, item.alpha * concatAlpha, ignoreCache);
+					this._appendToBatch(item, cMtx, item.alpha * concatAlpha);
 					continue;
 				}
 			}
@@ -2458,11 +2542,11 @@ this.createjs = this.createjs||{};
 			// TODO: DHG: consider making this polygon count dependant for things like vector draws
 			if (this._batchCardCount+1 > this._maxCardsPerBatch) {
 				this.batchReason = "vertexOverflow";
-				this._renderBuffers();					// <------------------------------------------------------------
+				this._renderBatch();					// <------------------------------------------------------------
 			}
 
 			// keep track of concatenated position
-			if (!item._glMtx) { item._glMtx = new createjs.Matrix2D(); }
+			if (!item._glMtx) { item._glMtx = new createjs.Matrix2D(); }		//TODO: benchmark removing this
 			var iMtx = item._glMtx;
 			iMtx.copy(cMtx);
 			if (item.transformMatrix) {
@@ -2477,16 +2561,20 @@ this.createjs = this.createjs||{};
 			}
 
 			var uvRect, texIndex, image, frame, texture, src;
-			var useCache = item.cacheCanvas && !ignoreCache;
 
 			// get the image data, or abort if not present
-			if (item._webGLRenderStyle === 2 || useCache) {			// BITMAP / Cached Canvas
+			// BITMAP / Cached Canvas
+			if (item._webGLRenderStyle === 2 || useCache) {
 				image = (ignoreCache?false:item.cacheCanvas) || item.image;
-			} else if (item._webGLRenderStyle === 1) {								// SPRITE
-				frame = item.spriteSheet.getFrame(item.currentFrame);	//TODO: Faster way?
+
+			// SPRITE
+			} else if (item._webGLRenderStyle === 1) {
+				frame = item.spriteSheet.getFrame(item.currentFrame);
 				if (frame === null) { continue; }
 				image = frame.image;
-			} else {																// MISC (DOM objects render themselves later)
+
+			// MISC (DOM objects render themselves later)
+			} else {
 				continue;
 			}
 			if (!image) { continue; }
@@ -2599,7 +2687,7 @@ this.createjs = this.createjs||{};
 				gl.bindFramebuffer(gl.FRAMEBUFFER, this._bufferTextureTemp._frameBuffer);
 				gl.clear(gl.COLOR_BUFFER_BIT);
 				this.batchReason = "immediateBuffer";
-				this._renderBuffers();//<-------------------------------------------------------------------------------
+				this._renderBatch();//<-------------------------------------------------------------------------------
 
 				this.batchReason = "immediateDraw";
 				this._drawCover(this._bufferTextureOutput._frameBuffer, this._bufferTextureConcat, this._bufferTextureTemp);
@@ -2615,10 +2703,10 @@ this.createjs = this.createjs||{};
 
 	/**
 	 * Draws all the currently defined cards in the buffer to the render surface.
-	 * @method _renderBuffers
+	 * @method _renderBatch
 	 * @protected
 	 */
-	p._renderBuffers = function () {
+	p._renderBatch = function () {
 		if (this._batchCardCount <= 0) { return; }	// prevents error logs on stages filled with un-renederable content.
 		var gl = this._webGLContext;
 
diff --git a/src/easeljs/filters/BitmapCache.js b/src/easeljs/filters/BitmapCache.js
index 54dd70857..cc0c7b3b4 100644
--- a/src/easeljs/filters/BitmapCache.js
+++ b/src/easeljs/filters/BitmapCache.js
@@ -36,7 +36,6 @@ this.createjs = this.createjs||{};
 (function() {
 	"use strict";
 
-
 // constructor:
 	/**
 	 * The BitmapCache is an internal representation of all the cache properties and logic required in order to "cache"
@@ -165,6 +164,30 @@ this.createjs = this.createjs||{};
 		 **/
 		this._filterOffY = 0;
 
+		/**
+		 * Internal tracking of the disabled state, use the getter/setters.
+		 * @property _disabled
+		 * @type {boolean}
+		 * @protected
+		 */
+		this._disabled = false;
+
+		/**
+		 * Internal tracking of intended cacheCanvas, may or may not be assigned based on disabled state.
+		 * @property _cacheCanvas
+		 * @type {HTMLCanvasElement | WebGLTexture | Object}
+		 * @protected
+		 */
+		this._cacheCanvas = null;
+
+		/**
+		 * Output StageGL target for GL drawing
+		 * @property _stageGL
+		 * @type {StageGL}
+		 * @protected
+		 */
+		this._stageGL = null;
+
 		/**
 		 * The cacheID when a DataURL was requested.
 		 * @property _cacheDataURLID
@@ -209,9 +232,60 @@ this.createjs = this.createjs||{};
 		 * @default 0
 		 **/
 		this._boundRect = new createjs.Rectangle();
+
+		// semi protected: not public API but modified by other classes
+		/**
+		 * Storage for the StageGL counter positioning matrix used on the object being cached
+		 * @property _counterMatrix
+		 * @type {Matrix2D}
+		 */
+		this._counterMatrix = null;
+
+		/**
+		 * Render texture temporary surface, used for swapping render calls in complex effects.
+		 * The difference between out and Temp is that Out is assigned to the cacheCanvas property of the display object
+		 * being managed by this class. That needs to be the same element consistently to allow for chaining filters & effects.
+		 * @property _renderTextureOut
+		 * @type {WebGLTexture}
+		 * @default 0
+		 */
+		this._renderTextureOut = null;
+
+		/**
+		 * Render texture temporary surface, used for swapping render calls in complex effects.
+		 * The difference between out and Temp is that Out is assigned to the cacheCanvas property of the display object
+		 * being managed by this class. That needs to be the same element consistently to allow for chaining filters & effects.
+		 * @property _renderTextureTemp
+		 * @type {WebGLTexture}
+		 * @default 0
+		 */
+		this._renderTextureTemp = null;
 	}
 	var p = BitmapCache.prototype;
 
+	p._get_disabled = function () {
+		return this._disabled;
+	};
+	p._set_disabled = function (value) {
+		this._disabled = !!value;
+		if(this.target) {
+			this.target.cacheCanvas = this._disabled ? null : this._cacheCanvas;
+		}
+	};
+
+	try {
+		Object.defineProperties(p, {
+			/**
+			 * Disable or enable the BitmapCache from displaying. Does not cause or block cache or cache updates when toggled.
+			 * Best used if the cached state is always identical, but the object will need temporary uncaching.
+			 * @property autoPurge
+			 * @type {Boolean}
+			 * @default false
+			 */
+			disabled: { get: p._get_disabled, set: p._set_disabled }
+		});
+	} catch (e) {} // TODO: use Log
+
 	/**
 	 * Returns the bounds that surround all applied filters, relies on each filter to describe how it changes bounds.
 	 * @method getFilterBounds
@@ -231,7 +305,7 @@ this.createjs = this.createjs||{};
 			if(!f || !f.getBounds){ continue; }
 			var test = f.getBounds();
 			if(!test){ continue; }
-			if(i==0) {
+			if(i === 0) {
 				output.setValues(test.x, test.y, test.width, test.height);
 			} else {
 				output.extend(test.x, test.y, test.width, test.height);
@@ -338,7 +412,7 @@ this.createjs = this.createjs||{};
 		if(!this.target) { throw "define() must be called before update()"; }
 
 		var filterBounds = BitmapCache.getFilterBounds(this.target);
-		var surface = this.target.cacheCanvas;
+		var surface = this._cacheCanvas;
 
 		this._drawWidth = Math.ceil(this.width*this.scale) + filterBounds.width;
 		this._drawHeight = Math.ceil(this.height*this.scale) + filterBounds.height;
@@ -346,10 +420,19 @@ this.createjs = this.createjs||{};
 			var out = 1; while (o._multiPass) { o = o._multiPass; out++; } return acc + out;
 		}, 0);
 
-		if(!surface || this._drawWidth != surface.width || this._drawHeight != surface.height) {
+		if(!surface || this._drawWidth !== surface.width || this._drawHeight !== surface.height) {
 			this._updateSurface();
 		}
 
+		var surfaceCount = this._filterCount + (this._stageGL.isCacheControlled ? 0 : 1);
+		if(surfaceCount >= 1) {
+			var out = this._stageGL.getTargetRenderTexture(this, this._drawWidth,this._drawHeight, true);
+			if(this._cacheCanvas === null){ this._cacheCanvas = out; }
+		}
+		if(surfaceCount >= 2) {
+			this._stageGL.getTargetRenderTexture(this, this._drawWidth,this._drawHeight, false);
+		}
+
 		this._filterOffX = filterBounds.x;
 		this._filterOffY = filterBounds.y;
 		this.offX = this.x*this.scale + this._filterOffX;
@@ -365,23 +448,20 @@ this.createjs = this.createjs||{};
 	 * @method release
 	 **/
 	p.release = function() {
-		if (this._webGLCache) {
-			// if it isn't cache controlled clean up after yourself
-			if (!this._webGLCache.isCacheControlled) {
-				if (this._renderTextureOut){ this._webGLCache._killTextureObject(this._renderTextureOut); }
-				if (this._renderTextureTemp){ this._webGLCache._killTextureObject(this._renderTextureTemp); }
-				if (this.target && this.target.cacheCanvas){ this._webGLCache._killTextureObject(this.target.cacheCanvas); }
-			}
+		if (this._stageGL) {
+			if (this._renderTextureOut){ this._stageGL._killTextureObject(this._renderTextureOut); }
+			if (this._renderTextureTemp){ this._stageGL._killTextureObject(this._renderTextureTemp); }
 			// set the context to none and let the garbage collector get the rest when the canvas itself gets removed
-			this._webGLCache = false;
+			this._stageGL = false;
 		} else {
 			var stage = this.target.stage;
-			if (stage instanceof createjs.StageGL){
-				stage.releaseTexture(this.target.cacheCanvas);
+			if (stage instanceof createjs.StageGL) {
+				stage.releaseTexture(this._cacheCanvas);
 			}
 		}
 
-		this.target = this.target.cacheCanvas = null;
+		this.disabled = true;
+		this.target = this._cacheCanvas = null;
 		this.cacheID = this._cacheDataURLID = this._cacheDataURL = undefined;
 		this.width = this.height = this.x = this.y = this.offX = this.offY = 0;
 		this.scale = 1;
@@ -395,11 +475,11 @@ this.createjs = this.createjs||{};
 	 * @return {String} The image data url for the cache.
 	 **/
 	p.getCacheDataURL = function() {
-		var cacheCanvas = this.target && this.target.cacheCanvas;
+		var cacheCanvas = this.target && this._cacheCanvas;
 		if (!cacheCanvas) { return null; }
-		if (this.cacheID != this._cacheDataURLID) {
+		if (this.cacheID !== this._cacheDataURLID) {
 			this._cacheDataURLID = this.cacheID;
-			this._cacheDataURL = cacheCanvas.toDataURL?cacheCanvas.toDataURL():null;	// incase function is
+			this._cacheDataURL = cacheCanvas.toDataURL ? cacheCanvas.toDataURL() : null;
 		}
 		return this._cacheDataURL;
 	};
@@ -412,7 +492,7 @@ this.createjs = this.createjs||{};
 	 **/
 	p.draw = function(ctx) {
 		if(!this.target) { return false; }
-		ctx.drawImage(this.target.cacheCanvas,
+		ctx.drawImage(this._cacheCanvas,
 			this.x + (this._filterOffX/this.scale),		this.y + (this._filterOffY/this.scale),
 			this._drawWidth/this.scale,					this._drawHeight/this.scale
 		);
@@ -432,6 +512,23 @@ this.createjs = this.createjs||{};
 		);
 	};
 
+	/**
+	 * Determines and returns the correct draw target for the content (pre filters) to be output to.
+	 * Intended for internal use.
+	 * @returns {WebGLTexture}
+	 */
+	p._getGLContentTarget = function() {
+		// draws ping pong between out/temp as each filter pass occurs, starting on the right foot avoids pointless draws
+		// to canvas, no filter			= canvas
+		// to canvas, odd filters		= out
+		// to canvas, even filters		= temp
+		// to texture, no filter		= out
+		// to texture, odd filters		= temp
+		// to texture, even filters		= out
+		if(this._filterCount === 0 && this._stageGL.isCacheControlled) { return this._cacheCanvas }
+		return ((this._filterCount % 2) ^ this._stageGL.isCacheControlled) ? this._renderTextureTemp : this._renderTextureOut;
+	};
+
 // private methods:
 	/**
 	 * Create or resize the invisible canvas/surface that is needed for the display object(s) to draw to,
@@ -444,11 +541,11 @@ this.createjs = this.createjs||{};
 		var surface;
 
 		if (!this._options || !this._options.useGL) {
-			surface = this.target.cacheCanvas;
+			surface = this._cacheCanvas;
 
 			// create it if it's missing
 			if(!surface) {
-				surface = this.target.cacheCanvas = createjs.createCanvas?createjs.createCanvas():document.createElement("canvas");
+				surface = this._cacheCanvas = createjs.createCanvas?createjs.createCanvas():document.createElement("canvas");
 			}
 
 			// now size it
@@ -458,37 +555,38 @@ this.createjs = this.createjs||{};
 		}
 
 		// create it if it's missing
-		if (!this._webGLCache) {
+		if (!this._stageGL) {
 			if (this._options.useGL === "stage") {
+				var targetStage = this.target.stage;
 				// use the stage that this object belongs on as the WebGL context
-				if(!(this.target.stage && this.target.stage.isWebGL)){
+				if(!(targetStage && targetStage.isWebGL)){
 					var error = "Cannot use 'stage' for cache because the object's parent stage is ";
-					error += this.target.stage ? "non WebGL." : "not set, please addChild to the correct stage.";
+					error += targetStage ? "non WebGL." : "not set, please addChild to the correct stage.";
 					throw error;
 				}
-				this._webGLCache = this.target.stage;
-				this.target.cacheCanvas = this._webGLCache.getTargetRenderTexture(this.target, this._drawWidth,this._drawHeight, true);
+				this._stageGL = targetStage;
 
 			} else if(this._options.useGL === "new") {
 				// create a new WebGL context to run this cache
-				this.target.cacheCanvas = document.createElement("canvas"); // low autopurge in case of filter swapping and low texture count
-				this._webGLCache = new createjs.StageGL(this.target.cacheCanvas, {antialias: true, transparent: true, autoPurge: 10});
-				this._webGLCache.isCacheControlled = true;	// use this flag to control stage sizing and final output
+				this._cacheCanvas = document.createElement("canvas"); // low autopurge in case of filter swapping and low texture count
+				this._stageGL = new createjs.StageGL(this.target.cacheCanvas, {antialias: true, transparent: true, autoPurge: 10});
+				this._stageGL.isCacheControlled = true;	// use this flag to control stage sizing and final output
 
 			} else if(this._options.useGL instanceof createjs.StageGL) {
 				// use the provided WebGL context to run this cache, trust the user it works and is configured.
-				this._webGLCache = this._options.useGL;
-				this.target.cacheCanvas = this._webGLCache.getTargetRenderTexture(this.target, this._drawWidth,this._drawHeight, true);
+				this._stageGL = this._options.useGL;
 
 			} else {
 				throw "Invalid option provided to useGL, expected ['stage', 'new', StageGL, undefined], got "+ this._options.useGL;
 			}
 		}
 
+		this.target.cacheCanvas = this._disabled ? null : this._cacheCanvas;
+
 		// if we have a dedicated stage we've got to size it
-		var stageGL = this._webGLCache;
+		var stageGL = this._stageGL;
 		if (stageGL.isCacheControlled) {
-			surface = this.target.cacheCanvas;
+			surface = this._cacheCanvas;
 			surface.width = this._drawWidth;
 			surface.height = this._drawHeight;
 			stageGL.updateViewport(this._drawWidth, this._drawHeight);
@@ -501,9 +599,9 @@ this.createjs = this.createjs||{};
 	 * @protected
 	 **/
 	p._drawToCache = function(compositeOperation) {
-		var surface = this.target.cacheCanvas;
+		var surface = this._cacheCanvas;
 		var target = this.target;
-		var webGL = this._webGLCache;
+		var webGL = this._stageGL;
 
 		if (webGL) {
 			webGL.cacheDraw(target, this);

From d0cf1460c6e166c4c6567ce6b92862a141476454 Mon Sep 17 00:00:00 2001
From: David Gillen <david@gskinner.com>
Date: Mon, 5 Mar 2018 12:21:44 -0700
Subject: [PATCH 21/39] 90% complete internal transition, some edge cases
 unhandled

---
 src/easeljs/display/StageGL.js     | 156 ++++++++---------------------
 src/easeljs/filters/BitmapCache.js |  29 +++++-
 2 files changed, 67 insertions(+), 118 deletions(-)

diff --git a/src/easeljs/display/StageGL.js b/src/easeljs/display/StageGL.js
index a9147c80b..bfd039754 100644
--- a/src/easeljs/display/StageGL.js
+++ b/src/easeljs/display/StageGL.js
@@ -252,6 +252,24 @@ this.createjs = this.createjs||{};
 		 */
 		this._webGLContext = null;
 
+////////////////////////////////////////////////////////////
+////////////////////////////////////////////////////////////
+////////////////////////////////////////////////////////////
+////////////////////////////////////////////////////////////
+////////////////////////////////////////////////////////////
+////////////////////////////////////////////////////////////
+////////////////////////////////////////////////////////////
+////////////////////////////////////////////////////////////
+		this._frameBuffer = null;
+////////////////////////////////////////////////////////////
+////////////////////////////////////////////////////////////
+////////////////////////////////////////////////////////////
+////////////////////////////////////////////////////////////
+////////////////////////////////////////////////////////////
+////////////////////////////////////////////////////////////
+////////////////////////////////////////////////////////////
+////////////////////////////////////////////////////////////
+
 		/**
 		 * The color to use when the WebGL canvas has been cleared. May appear as a background color. Defaults to grey.
 		 * @property _clearColor
@@ -1299,20 +1317,27 @@ this.createjs = this.createjs||{};
 		this._directDraw = true;
 
 		var filterCount = manager._filterCount;
+		var filtersLeft = filterCount;
 		var backupWidth = this._viewportWidth, backupHeight = this._viewportHeight;
 		this.updateViewport(manager._drawWidth, manager._drawHeight);
 
-		var contentStamp = manager._getGLContentTarget();
+		var contentStamp = manager._getGLContentTarget(filtersLeft);
 		var container = this._cacheContainer;
 		container.children = [target];
 		container.transformMatrix = this._alignTargetToCache(target, manager);
 
 		this._updateRenderMode("source-over");
 		this._drawContent(contentStamp._frameBuffer, container, true);
-
-		if(filterCount) {
-			this._drawFilters(contentStamp, target, manager);
+		console.log("-----------------");
+
+		while(filtersLeft) { //warning: pay attention to where filtersLeft is modified, this is a micro-optimization
+			var filter = manager._getGLFilter(filterCount - filtersLeft);
+			var drawTarget = manager._getGLContentTarget(--filtersLeft);
+			this._drawCover(drawTarget._frameBuffer, contentStamp, filter);
+			console.log(filter);
+			contentStamp = drawTarget;
 		}
+		console.log("==================");
 
 		this.updateViewport(backupWidth, backupHeight);
 		this._directDraw = temp;
@@ -2331,14 +2356,14 @@ this.createjs = this.createjs||{};
 	/**
 	 * Used to draw one or more textures potentially using a filter into the supplied buffer.
 	 * Mostly used for caches, filters, and outputting final render frames.
-	 * Draws `dst` into `out` after applying `src` (if specified) using `filter` or the current `_renderMode`.
+	 * Draws `dst` into `out` after applying `srcFilter` depending on its current value.
 	 * @param {WebGLFramebuffer} out Buffer to draw the results into (null is the canvas element)
 	 * @param {WebGLTexture} dst Base texture layer aka "destination" in image blending terminology
-	 * @param {WebGLTexture} [src = undefined] Modification texture layer aka "source" in image blending terminology
-	 * @param {Filter} [filter = undefined] Filter to use instead of blend mode, must supply a src to work.
+	 * @param {WebGLTexture | Filter} [srcFilter = undefined] Modification parameter for the draw. If a texture, the
+	 * current _renderMode applies it as a "source" image. If a Filter, the filter is applied to the dst with its params.
 	 * @protected
 	 */
-	p._drawCover = function (out, dst, src, filter) {
+	p._drawCover = function (out, dst, srcFilter) {
 		var gl = this._webGLContext;
 
 		gl.bindFramebuffer(gl.FRAMEBUFFER, out);
@@ -2347,16 +2372,17 @@ this.createjs = this.createjs||{};
 		gl.bindTexture(gl.TEXTURE_2D, dst);
 		this.setTextureParams(gl);
 
-		if (src !== undefined) {
-			gl.activeTexture(gl.TEXTURE1);
-			gl.bindTexture(gl.TEXTURE_2D, src);
-			this.setTextureParams(gl);
-		}
-
-		if (filter === undefined) {
-			this._activeShader = this._builtShaders[this._renderMode].shader;
+		if (srcFilter instanceof createjs.Filter) {
+			this._activeShader = this.getFilterShader(srcFilter);
 		} else {
-			this.getFilterShader(filter);
+			if (srcFilter instanceof WebGLTexture) {
+				gl.activeTexture(gl.TEXTURE1);
+				gl.bindTexture(gl.TEXTURE_2D, srcFilter);
+				this.setTextureParams(gl);
+			} else if(srcFilter !== undefined && this.vocalDebug) {
+				console.log("Unknown data handed to function: ", srcFilter);
+			}
+			this._activeShader = this._builtShaders[this._renderMode].shader;
 		}
 
 		this._renderCover();
@@ -2385,101 +2411,6 @@ this.createjs = this.createjs||{};
 		return mtx;
 	};
 
-	/**
-	 * Sub portion of cacheDraw, split off for readability. Do not call independently. Swap surfaces are texture drawn
-	 * into back and forth due to limitations drawing a texture a into itself. This will draw into the managers out.
-	 * @method _drawFilters
-	 * @param {WebGLTexture} content A render texture which should contain original content
-	 * @param {DisplayObject} target The object we're drawing with a filter.
-	 * @param {BitmapCache} manager The BitmapCache instance looking after the cache
-	 */
-	p._drawFilters = function(content, target, manager) {
-		// we can use one of the swap buffers as the out, but we need to notice that and start off on the right foot
-
-
-
-
-
-
-
-
-
-
-	};
-
-	p._drawFilters_OLD = function(target, filters, manager) {
-		var gl = this._webGLContext;
-		var renderTexture;
-		var lastTextureSlot = this._freeTextureCount;
-		var wBackup = this._viewportWidth, hBackup = this._viewportHeight;
-
-		var filtersLeft = manager._filterCount;
-		var container = this._cacheContainer;
-		var useOut = !(filtersLeft%2); // we have to swap render surface, so start with the one that will make 'out' the last
-
-		// we don't know which texture slot we're dealing with previously and we need one out of the way
-		// once we're using that slot activate it so when we make and bind our RenderTexture it's safe there
-		gl.activeTexture(gl.TEXTURE0 + lastTextureSlot);
-		renderTexture = this.getTargetRenderTexture(target, manager._drawWidth, manager._drawHeight, useOut);
-
-		// draw item to render texture		I -> T
-		gl.bindFramebuffer(gl.FRAMEBUFFER, renderTexture._frameBuffer);
-		this.updateViewport(manager._drawWidth, manager._drawHeight);
-		gl.clear(gl.COLOR_BUFFER_BIT);
-		this._batchDraw(container, true);
-
-		gl.blendEquationSeparate(gl.FUNC_ADD, gl.FUNC_ADD);
-		gl.blendFuncSeparate(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA, gl.ONE, gl.ONE_MINUS_SRC_ALPHA);
-
-		// bind the result texture to slot 0 as all filters and cover draws assume original content is in slot 0
-		gl.activeTexture(gl.TEXTURE0);
-		gl.bindTexture(gl.TEXTURE_2D, renderTexture);
-		this.setTextureParams(gl);
-
-		var i = 0, filter = filters[i];
-		do { // this is safe because we wouldn't be in apply filters without a filter count of at least 1
-			filtersLeft--;
-			useOut = !useOut;
-
-			// swap to correct shader
-			this._activeShader = this.getFilterShader(filter);
-			if (!this._activeShader) { continue; }
-
-			gl.activeTexture(gl.TEXTURE0 + lastTextureSlot);
-			renderTexture = this.getTargetRenderTexture(target, manager._drawWidth, manager._drawHeight, useOut);
-
-			if (filtersLeft === 0 && this.isCacheControlled) {
-				gl.bindFramebuffer(gl.FRAMEBUFFER, null);
-
-				// draw result to canvas			R -> C
-				this.updateViewport(wBackup, hBackup);
-				gl.clear(gl.COLOR_BUFFER_BIT);
-				this._renderCover();
-
-				return;
-
-			} else {
-				gl.bindFramebuffer(gl.FRAMEBUFFER, renderTexture._frameBuffer);
-
-				// draw result to render texture	R -> T
-				gl.viewport(0, 0, manager._drawWidth, manager._drawHeight);
-				gl.clear(gl.COLOR_BUFFER_BIT);
-				this._renderCover();
-
-				// bind the result texture to slot 0 as all filters and cover draws assume original content is in slot 0
-				gl.activeTexture(gl.TEXTURE0);
-				gl.bindTexture(gl.TEXTURE_2D, renderTexture);
-				this.setTextureParams(gl);
-			}
-
-			// work through the multipass if it's there, otherwise move on
-			filter = filter._multiPass !== null ? filter._multiPass : filters[++i];
-		} while (filter);
-
-		gl.bindFramebuffer(gl.FRAMEBUFFER, null);
-		this.updateViewport(wBackup, hBackup);
-	};
-
 	/**
 	 * Add all the contents of a container to the pending buffers, called recursively on each container. This may
 	 * trigger a draw if a buffer runs out of space. This is the main workforce of the render loop.
@@ -2755,7 +2686,6 @@ this.createjs = this.createjs||{};
 	/**
 	 * Draws a card that covers the entire render surface. Mainly used for filters.
 	 * @method _renderCover
-	 * @param {WebGLRenderingContext} gl The canvas WebGL context object to draw into.
 	 * @protected
 	 */
 	p._renderCover = function () {
diff --git a/src/easeljs/filters/BitmapCache.js b/src/easeljs/filters/BitmapCache.js
index cc0c7b3b4..dcffbb2af 100644
--- a/src/easeljs/filters/BitmapCache.js
+++ b/src/easeljs/filters/BitmapCache.js
@@ -427,7 +427,10 @@ this.createjs = this.createjs||{};
 		var surfaceCount = this._filterCount + (this._stageGL.isCacheControlled ? 0 : 1);
 		if(surfaceCount >= 1) {
 			var out = this._stageGL.getTargetRenderTexture(this, this._drawWidth,this._drawHeight, true);
-			if(this._cacheCanvas === null){ this._cacheCanvas = out; }
+			if(this._cacheCanvas === null){
+				this._cacheCanvas = out;
+				this.disabled = this._disabled;
+			}
 		}
 		if(surfaceCount >= 2) {
 			this._stageGL.getTargetRenderTexture(this, this._drawWidth,this._drawHeight, false);
@@ -513,11 +516,14 @@ this.createjs = this.createjs||{};
 	};
 
 	/**
-	 * Determines and returns the correct draw target for the content (pre filters) to be output to.
+	 * Determines and returns the correct draw target for the content to be output to.
 	 * Intended for internal use.
+	 * @method _getGLContentTarget
+	 * @param {Number} filterCount Whole number, the number of filters still to be drawn
 	 * @returns {WebGLTexture}
 	 */
-	p._getGLContentTarget = function() {
+	p._getGLContentTarget = function(filterCount) {
+		if(!(filterCount >= 0)){ filterCount = 0; }
 		// draws ping pong between out/temp as each filter pass occurs, starting on the right foot avoids pointless draws
 		// to canvas, no filter			= canvas
 		// to canvas, odd filters		= out
@@ -525,8 +531,21 @@ this.createjs = this.createjs||{};
 		// to texture, no filter		= out
 		// to texture, odd filters		= temp
 		// to texture, even filters		= out
-		if(this._filterCount === 0 && this._stageGL.isCacheControlled) { return this._cacheCanvas }
-		return ((this._filterCount % 2) ^ this._stageGL.isCacheControlled) ? this._renderTextureTemp : this._renderTextureOut;
+		if(filterCount === 0 && this._stageGL.isCacheControlled) { return this._cacheCanvas }
+		return ((filterCount % 2) ^ this._stageGL.isCacheControlled) ? this._renderTextureTemp : this._renderTextureOut;
+	};
+
+	/**
+	 * Fetch the correct filter in order, complicated by multipass filtering.
+	 * @param {Number} lookup The filter in the list to return
+	 */
+	p._getGLFilter = function(lookup) {
+		var i = 0;
+		var result = this.target.filters[i];
+		while(result && --lookup >= 0) {
+			result = result._multiPass ? result._multiPass : this.target.filters[++i];
+		}
+		return result
 	};
 
 // private methods:

From ee0fd2eb0adb7e301c9e9db1496d1fdc8f93a4b5 Mon Sep 17 00:00:00 2001
From: David Gillen <david@gskinner.com>
Date: Mon, 5 Mar 2018 14:48:39 -0700
Subject: [PATCH 22/39] removing logs, bugs with caches

---
 src/easeljs/display/StageGL.js     |  3 ---
 src/easeljs/filters/BitmapCache.js | 21 ++++++++++++---------
 2 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/src/easeljs/display/StageGL.js b/src/easeljs/display/StageGL.js
index bfd039754..cc76578cc 100644
--- a/src/easeljs/display/StageGL.js
+++ b/src/easeljs/display/StageGL.js
@@ -1328,16 +1328,13 @@ this.createjs = this.createjs||{};
 
 		this._updateRenderMode("source-over");
 		this._drawContent(contentStamp._frameBuffer, container, true);
-		console.log("-----------------");
 
 		while(filtersLeft) { //warning: pay attention to where filtersLeft is modified, this is a micro-optimization
 			var filter = manager._getGLFilter(filterCount - filtersLeft);
 			var drawTarget = manager._getGLContentTarget(--filtersLeft);
 			this._drawCover(drawTarget._frameBuffer, contentStamp, filter);
-			console.log(filter);
 			contentStamp = drawTarget;
 		}
-		console.log("==================");
 
 		this.updateViewport(backupWidth, backupHeight);
 		this._directDraw = temp;
diff --git a/src/easeljs/filters/BitmapCache.js b/src/easeljs/filters/BitmapCache.js
index dcffbb2af..2453735ee 100644
--- a/src/easeljs/filters/BitmapCache.js
+++ b/src/easeljs/filters/BitmapCache.js
@@ -424,16 +424,18 @@ this.createjs = this.createjs||{};
 			this._updateSurface();
 		}
 
-		var surfaceCount = this._filterCount + (this._stageGL.isCacheControlled ? 0 : 1);
-		if(surfaceCount >= 1) {
-			var out = this._stageGL.getTargetRenderTexture(this, this._drawWidth,this._drawHeight, true);
-			if(this._cacheCanvas === null){
-				this._cacheCanvas = out;
-				this.disabled = this._disabled;
+		if (this._stageGL) {
+			var surfaceCount = this._filterCount + (this._stageGL.isCacheControlled ? 0 : 1);
+			if(surfaceCount >= 1) {
+				var out = this._stageGL.getTargetRenderTexture(this, this._drawWidth,this._drawHeight, true);
+				if(this._cacheCanvas === null){
+					this._cacheCanvas = out;
+					this.disabled = this._disabled;
+				}
+			}
+			if(surfaceCount >= 2) {
+				this._stageGL.getTargetRenderTexture(this, this._drawWidth,this._drawHeight, false);
 			}
-		}
-		if(surfaceCount >= 2) {
-			this._stageGL.getTargetRenderTexture(this, this._drawWidth,this._drawHeight, false);
 		}
 
 		this._filterOffX = filterBounds.x;
@@ -565,6 +567,7 @@ this.createjs = this.createjs||{};
 			// create it if it's missing
 			if(!surface) {
 				surface = this._cacheCanvas = createjs.createCanvas?createjs.createCanvas():document.createElement("canvas");
+				this.target.cacheCanvas = this._disabled ? null : this._cacheCanvas;
 			}
 
 			// now size it

From e5d359907ba289782a548f8be46c21b3ff745694 Mon Sep 17 00:00:00 2001
From: David Gillen <david@gskinner.com>
Date: Thu, 8 Mar 2018 14:19:50 -0700
Subject: [PATCH 23/39] Cleanup, incomplete feature addition

---
 src/easeljs/display/StageGL.js     | 96 ++++++++++++++++--------------
 src/easeljs/filters/BitmapCache.js | 17 ++++--
 2 files changed, 65 insertions(+), 48 deletions(-)

diff --git a/src/easeljs/display/StageGL.js b/src/easeljs/display/StageGL.js
index cc76578cc..34895c0c0 100644
--- a/src/easeljs/display/StageGL.js
+++ b/src/easeljs/display/StageGL.js
@@ -203,11 +203,7 @@ this.createjs = this.createjs||{};
 		this.autoPurge = autoPurge;	//getter/setter handles setting the real value and validating and documentation
 
 		/**
-		 * aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
-		 * aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
-		 * aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
-		 * aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
-		 * aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+		 * See directDraw
 		 * @property _directDraw
 		 * @protected
 		 * @type {Boolean}
@@ -252,23 +248,12 @@ this.createjs = this.createjs||{};
 		 */
 		this._webGLContext = null;
 
-////////////////////////////////////////////////////////////
-////////////////////////////////////////////////////////////
-////////////////////////////////////////////////////////////
-////////////////////////////////////////////////////////////
-////////////////////////////////////////////////////////////
-////////////////////////////////////////////////////////////
-////////////////////////////////////////////////////////////
-////////////////////////////////////////////////////////////
+		/**
+		 * Reduce API logic by allowing stage to behave as a renderTexture target, should always be null as null is canvas.
+		 * @type {null}
+		 * @protected
+		 */
 		this._frameBuffer = null;
-////////////////////////////////////////////////////////////
-////////////////////////////////////////////////////////////
-////////////////////////////////////////////////////////////
-////////////////////////////////////////////////////////////
-////////////////////////////////////////////////////////////
-////////////////////////////////////////////////////////////
-////////////////////////////////////////////////////////////
-////////////////////////////////////////////////////////////
 
 		/**
 		 * The color to use when the WebGL canvas has been cleared. May appear as a background color. Defaults to grey.
@@ -1207,8 +1192,6 @@ this.createjs = this.createjs||{};
 				this.updateViewport(this.canvas.width, this.canvas.height);
 				if(!this._directDraw) {
 					this._bufferTextureOutput = this.getRenderBufferTexture(this._viewportWidth, this._viewportHeight);
-					this._bufferTextureConcat = this.getRenderBufferTexture(this._viewportWidth, this._viewportHeight);
-					this._bufferTextureTemp = this.getRenderBufferTexture(this._viewportWidth, this._viewportHeight);
 				}
 
 				this.canvas._invalid = true;
@@ -1312,9 +1295,19 @@ this.createjs = this.createjs||{};
 			return false;
 		}
 
-		// TODO: fix it so we don't have to do this
-		var temp = this._directDraw;
-		this._directDraw = true;
+		// TODO: fix it so we don't have to assume `_directDraw = false`
+		// TODO: fix it so we don't have to assume `_directDraw = false`
+		// TODO: fix it so we don't have to assume `_directDraw = false`
+		// TODO: fix it so we don't have to assume `_directDraw = false`
+		// TODO: fix it so we don't have to assume `_directDraw = false`
+		// TODO: fix it so we don't have to assume `_directDraw = false`
+		// TODO: fix it so we don't have to assume `_directDraw = false`
+		// TODO: fix it so we don't have to assume `_directDraw = false`
+		// Two distinct issues
+		// #) Swap textures for content draws are hard coded to screen canvases, switch to using BitmapCache temps when cache drawing
+		// #) CacheControlled + no filters put the output as the canvas, but we can't assume that till the entire tree is walked
+
+
 
 		var filterCount = manager._filterCount;
 		var filtersLeft = filterCount;
@@ -1337,7 +1330,6 @@ this.createjs = this.createjs||{};
 		}
 
 		this.updateViewport(backupWidth, backupHeight);
-		this._directDraw = temp;
 		return true;
 	};
 
@@ -2457,6 +2449,7 @@ this.createjs = this.createjs||{};
 
 			if (!(item.visible && concatAlpha > 0.0035)) { continue; }
 			if (!useCache) {
+				// TODO: DHG: cacheless filters
 				if (item._updateState){
 					item._updateState();
 				}
@@ -2604,23 +2597,7 @@ this.createjs = this.createjs||{};
 			this._batchCardCount++;
 
 			if (this._immediateRender) {
-				gl.bindFramebuffer(gl.FRAMEBUFFER, this._bufferTextureConcat._frameBuffer);
-				gl.clear(gl.COLOR_BUFFER_BIT);
-
-				var swap = this._bufferTextureOutput;
-				this._bufferTextureOutput = this._bufferTextureConcat;
-				this._bufferTextureConcat = swap;
-
-				this._activeShader = this._mainShader;
-				gl.bindFramebuffer(gl.FRAMEBUFFER, this._bufferTextureTemp._frameBuffer);
-				gl.clear(gl.COLOR_BUFFER_BIT);
-				this.batchReason = "immediateBuffer";
-				this._renderBatch();//<-------------------------------------------------------------------------------
-
-				this.batchReason = "immediateDraw";
-				this._drawCover(this._bufferTextureOutput._frameBuffer, this._bufferTextureConcat, this._bufferTextureTemp);
-
-				gl.bindFramebuffer(gl.FRAMEBUFFER, this._bufferTextureOutput._frameBuffer);
+				this._immediateBatchRender(gl);
 			}
 		}
 
@@ -2629,6 +2606,37 @@ this.createjs = this.createjs||{};
 		}
 	};
 
+	/**
+	 * The shader or effect needs to be drawn immediately, sub function of `_appendToBatch`
+	 * @protected
+	 */
+	p._immediateBatchRender = function(gl) {
+		if(this._bufferTextureConcat === null){
+			this._bufferTextureConcat = this.getRenderBufferTexture(this._viewportWidth, this._viewportHeight);
+		}
+		if(this._bufferTextureTemp === null){
+			this._bufferTextureTemp = this.getRenderBufferTexture(this._viewportWidth, this._viewportHeight);
+		}
+
+		gl.bindFramebuffer(gl.FRAMEBUFFER, this._bufferTextureConcat._frameBuffer);
+		gl.clear(gl.COLOR_BUFFER_BIT);
+
+		var swap = this._bufferTextureOutput;
+		this._bufferTextureOutput = this._bufferTextureConcat;
+		this._bufferTextureConcat = swap;
+
+		this._activeShader = this._mainShader;
+		gl.bindFramebuffer(gl.FRAMEBUFFER, this._bufferTextureTemp._frameBuffer);
+		gl.clear(gl.COLOR_BUFFER_BIT);
+		this.batchReason = "immediateBuffer";
+		this._renderBatch();//<-----------------------------------------------------------------------------------------
+
+		this.batchReason = "immediateDraw";
+		this._drawCover(this._bufferTextureOutput._frameBuffer, this._bufferTextureConcat, this._bufferTextureTemp);
+
+		gl.bindFramebuffer(gl.FRAMEBUFFER, this._bufferTextureOutput._frameBuffer);
+	};
+
 	/**
 	 * Draws all the currently defined cards in the buffer to the render surface.
 	 * @method _renderBatch
diff --git a/src/easeljs/filters/BitmapCache.js b/src/easeljs/filters/BitmapCache.js
index 2453735ee..85e24deec 100644
--- a/src/easeljs/filters/BitmapCache.js
+++ b/src/easeljs/filters/BitmapCache.js
@@ -315,6 +315,16 @@ this.createjs = this.createjs||{};
 		return output;
 	};
 
+	/**
+	 * Utility function, use with `displayObject.filters.reduce(BitmapCache.filterCounter, 0);`
+	 * @param acc Accumulator
+	 * @param o Object
+	 * @returns {*}
+	 */
+	BitmapCache.filterCounter =  function (acc, o) {
+		var out = 1; while (o._multiPass) { o = o._multiPass; out++; } return acc + out;
+	};
+
 // public methods:
 	/**
 	 * Returns a string representation of this object.
@@ -416,9 +426,7 @@ this.createjs = this.createjs||{};
 
 		this._drawWidth = Math.ceil(this.width*this.scale) + filterBounds.width;
 		this._drawHeight = Math.ceil(this.height*this.scale) + filterBounds.height;
-		this._filterCount = this.target.filters.reduce( function (acc, o) {
-			var out = 1; while (o._multiPass) { o = o._multiPass; out++; } return acc + out;
-		}, 0);
+		this._filterCount = this.target.filters.reduce(BitmapCache.filterCounter, 0);
 
 		if(!surface || this._drawWidth !== surface.width || this._drawHeight !== surface.height) {
 			this._updateSurface();
@@ -591,7 +599,8 @@ this.createjs = this.createjs||{};
 			} else if(this._options.useGL === "new") {
 				// create a new WebGL context to run this cache
 				this._cacheCanvas = document.createElement("canvas"); // low autopurge in case of filter swapping and low texture count
-				this._stageGL = new createjs.StageGL(this.target.cacheCanvas, {antialias: true, transparent: true, autoPurge: 10});
+				this._stageGL = new createjs.StageGL(this._cacheCanvas, {antialias: true, transparent: true, autoPurge: 10});
+				if(!this._stageGL._webGLContext){ throw "GL Cache asked for but unavailable"; }
 				this._stageGL.isCacheControlled = true;	// use this flag to control stage sizing and final output
 
 			} else if(this._options.useGL instanceof createjs.StageGL) {

From e5477af9dc640849af650d33f5fb2a34077ced06 Mon Sep 17 00:00:00 2001
From: David Gillen <david@gskinner.com>
Date: Thu, 15 Mar 2018 10:08:32 -0600
Subject: [PATCH 24/39] improved caching and composite operation co-existence,
 cleaned up code, ISSUE: expected bugs with direct to stage cache writes

---
 src/easeljs/display/DisplayObject.js |   8 +-
 src/easeljs/display/StageGL.js       | 311 +++++++++++++--------------
 src/easeljs/filters/BitmapCache.js   |  81 ++++---
 3 files changed, 192 insertions(+), 208 deletions(-)

diff --git a/src/easeljs/display/DisplayObject.js b/src/easeljs/display/DisplayObject.js
index ebbd5c92b..ae57ab010 100644
--- a/src/easeljs/display/DisplayObject.js
+++ b/src/easeljs/display/DisplayObject.js
@@ -459,13 +459,13 @@ this.createjs = this.createjs||{};
 		this._webGLRenderStyle = DisplayObject._StageGL_NONE;
 
 		/**
-		 * Storage for the calculated position of an object in StageGL
+		 * Storage for the calculated position of an object in StageGL. If not using StageGL, you can null it to save memory.
 		 * @property _glMtx
 		 * @protected
-		 * @type {Rectangle}
+		 * @type {Matrix2D}
 		 * @default null
 		 */
-		this._glMtx = null;
+		this._glMtx = new createjs.Matrix2D();
 	}
 	var p = createjs.extend(DisplayObject, createjs.EventDispatcher);
 
@@ -1007,7 +1007,7 @@ this.createjs = this.createjs||{};
 	p.getMatrix = function(matrix) {
 		var o = this, mtx = matrix || new createjs.Matrix2D();
 		return o.transformMatrix ?  mtx.copy(o.transformMatrix) :
-			(matrix.identity() && mtx.appendTransform(o.x, o.y, o.scaleX, o.scaleY, o.rotation, o.skewX, o.skewY, o.regX, o.regY));
+			(mtx.identity() && mtx.appendTransform(o.x, o.y, o.scaleX, o.scaleY, o.rotation, o.skewX, o.skewY, o.regX, o.regY));
 	};
 
 	/**
diff --git a/src/easeljs/display/StageGL.js b/src/easeljs/display/StageGL.js
index 34895c0c0..e56f51c71 100644
--- a/src/easeljs/display/StageGL.js
+++ b/src/easeljs/display/StageGL.js
@@ -138,6 +138,7 @@ this.createjs = this.createjs||{};
 			antialias = options.antialias;
 			preserveBuffer = options.preserveBuffer;
 			autoPurge = options.autoPurge;
+			directDraw = options.directDraw;
 		}
 
 // public properties:
@@ -267,12 +268,12 @@ this.createjs = this.createjs||{};
 		/**
 		 * The maximum number of cards (aka a single sprite) that can be drawn in one draw call. Use getter/setters to
 		 * modify otherwise internal buffers may be incorrect sizes.
-		 * @property _maxCardsPerBatch
+		 * @property _maxBatchVertexCount
 		 * @protected
 		 * @type {Number}
-		 * @default StageGL.DEFAULT_MAX_BATCH_SIZE (10000)
+		 * @default StageGL.DEFAULT_MAX_BATCH_SIZE * StageGL.INDICIES_PER_CARD
 		 */
-		this._maxCardsPerBatch = StageGL.DEFAULT_MAX_BATCH_SIZE;
+		this._maxBatchVertexCount = StageGL.DEFAULT_MAX_BATCH_SIZE * StageGL.INDICIES_PER_CARD;
 
 		/**
 		 * The shader program used to draw the current batch.
@@ -363,29 +364,56 @@ this.createjs = this.createjs||{};
 		this._alphaBuffer = null;
 
 		/**
-		 * One of the major buffers used in composite blending drawing. Do not expect this to always be the same object
-		 * "what you're drawing to, occasionally swaps with concat"
+		 * One of the major render buffers used in composite blending drawing. Do not expect this to always be the same object.
+		 * "What you're drawing to", object occasionally swaps with concat.
+		 * @property _bufferTextureOutput
+		 * @protected
 		 * @type {WebGLTexture}
-		 * @private
 		 */
 		this._bufferTextureOutput = null;
 
 		/**
-		 * One of the major buffers used in composite blending drawing. Do not expect this to always be the same object
-		 * "wwhat you've draw before now, occasionally swaps with output"
+		 * One of the major render buffers used in composite blending drawing. Do not expect this to always be the same object.
+		 * "What you've draw before now", object occasionally swaps with output.
+		 * @property _bufferTextureConcat
+		 * @protected
 		 * @type {WebGLTexture}
-		 * @private
 		 */
 		this._bufferTextureConcat = null;
 
 		/**
-		 * One of the major buffers used in composite blending drawing. Do not expect this to always be the same object
-		 * "temporary surface for mixing in other objects"
+		 * One of the major render buffers used in composite blending drawing.
+		 * "Temporary mixing surface"
+		 * @property _bufferTextureTemp
+		 * @protected
 		 * @type {WebGLTexture}
-		 * @private
 		 */
 		this._bufferTextureTemp = null;
 
+		/**
+		 * The current render buffer being targeted, usually targets internal buffers, but may be set to cache's buffer during a cache render.
+		 * @property _batchTextureOutput
+		 * @protected
+		 * @type {WebGLTexture}
+		 */
+		this._batchTextureOutput = null;
+
+		/**
+		 * The current render buffer being targeted, usually targets internal buffers, but may be set to cache's buffer during a cache render.
+		 * @property _batchTextureConcat
+		 * @protected
+		 * @type {WebGLTexture}
+		 */
+		this._batchTextureConcat = null;
+
+		/**
+		 * The current render buffer being targeted, usually targets internal buffers, but may be set to cache's buffer during a cache render.
+		 * @property _batchTextureTemp
+		 * @protected
+		 * @type {WebGLTexture}
+		 */
+		this._batchTextureTemp = null;
+
 		/**
 		 * Internal library of the shaders that have been compiled and created along with their parameters. Should contain
 		 * compiled `gl.ShaderProgram` and settings for `gl.blendFunc` and `gl.blendEquation`. Populated as requested.
@@ -431,34 +459,28 @@ this.createjs = this.createjs||{};
 
 		/**
 		 * Texture slots for a draw
+		 * @property _gpuTextureCount
+		 * @protected
+		 * @type {uint}
 		 */
 		this._gpuTextureCount = 8;
 
 		/**
 		 * Texture slots on the hardware
+		 * @property _gpuTextureMax
+		 * @protected
+		 * @type {uint}
 		 */
 		this._gpuTextureMax = 8;
 
-		/**
-		 * Number of texture slots being reserved by StageGL for filters and effect drawing
-		 */
-		this._textureDrawReserve = -1;
-
-		/**
-		 * Number of texture slots being reserved by StageGL for drawing into
-		 */
-		this._textureTrackReserve = -1;
-
 		/**
 		 * Texture slots in a batch for User textures
+		 * @property _batchTextureCount
+		 * @protected
+		 * @type {uint}
 		 */
 		this._batchTextureCount = 0;
 
-		/**
-		 * Texture slots available for User textures
-		 */
-		this._freeTextureCount = 0;
-
 		/**
 		 * The location at which the last texture was inserted into a GPU slot
 		 */
@@ -483,11 +505,11 @@ this.createjs = this.createjs||{};
 		this._immediateRender = false;
 
 		/**
-		 * Cards drawn into the batch so far.
+		 * Vertices drawn into the batch so far.
 		 * @type {number}
 		 * @private
 		 */
-		this._batchCardCount = 0;
+		this._batchVertexCount = 0;
 
 		/**
 		 * The current batch being drawn, A batch consists of a call to `drawElements` on the GPU. Many of these calls
@@ -636,7 +658,7 @@ this.createjs = this.createjs||{};
 	 * @default 10000
 	 * @readonly
 	 */
-	StageGL.DEFAULT_MAX_BATCH_SIZE = 10000;
+	StageGL.DEFAULT_MAX_BATCH_SIZE = 10920;
 
 	/**
 	 * The maximum size WebGL allows for element index numbers. Uses a 16 bit unsigned integer. It takes 6 indices to
@@ -1261,16 +1283,31 @@ this.createjs = this.createjs||{};
 		}
 
 		// Use WebGL
-		this._batchCardCount = 0;
+		this._batchVertexCount = 0;
 		this._drawID++;
 
 		if (this.autoClear) { this.clear(); }
 
+		if (this._directDraw) {
+			this._batchTextureOutput = this;
+		} else {
+			this._batchTextureOutput = this._bufferTextureOutput;
+			this._batchTextureConcat = this._bufferTextureConcat;
+			this._batchTextureTemp = this._bufferTextureTemp;
+		}
+
 		this._updateRenderMode("source-over");
-		this._drawContent(this._bufferTextureOutput._frameBuffer, this, ignoreCache);
+		this._drawContent(this, ignoreCache);
 
-		this.batchReason = "finalOutput";
-		this._drawCover(null, this._bufferTextureOutput);
+		if (!this._directDraw) {
+			this.batchReason = "finalOutput";
+			this._drawCover(null, this._batchTextureOutput);
+		}
+
+		// batches may generate or swap around textures. To be sure we capture them, store them back into buffer
+		this._bufferTextureOutput = this._batchTextureOutput;
+		this._bufferTextureConcat = this._batchTextureConcat;
+		this._bufferTextureTemp = this._batchTextureTemp;
 
 		if (this._autoPurge !== -1 && !(this._drawID%((this._autoPurge/2)|0))) {
 			this.purgeTextures(this._autoPurge);
@@ -1295,84 +1332,44 @@ this.createjs = this.createjs||{};
 			return false;
 		}
 
-		// TODO: fix it so we don't have to assume `_directDraw = false`
-		// TODO: fix it so we don't have to assume `_directDraw = false`
-		// TODO: fix it so we don't have to assume `_directDraw = false`
-		// TODO: fix it so we don't have to assume `_directDraw = false`
-		// TODO: fix it so we don't have to assume `_directDraw = false`
-		// TODO: fix it so we don't have to assume `_directDraw = false`
-		// TODO: fix it so we don't have to assume `_directDraw = false`
-		// TODO: fix it so we don't have to assume `_directDraw = false`
-		// Two distinct issues
-		// #) Swap textures for content draws are hard coded to screen canvases, switch to using BitmapCache temps when cache drawing
-		// #) CacheControlled + no filters put the output as the canvas, but we can't assume that till the entire tree is walked
-
-
-
-		var filterCount = manager._filterCount;
-		var filtersLeft = filterCount;
+		var swap, filterCount = manager._filterCount, filtersLeft = filterCount;
 		var backupWidth = this._viewportWidth, backupHeight = this._viewportHeight;
 		this.updateViewport(manager._drawWidth, manager._drawHeight);
 
-		var contentStamp = manager._getGLContentTarget(filtersLeft);
+		// TODO: DIRECT CACHE WRITE
+
+		var out = this._batchTextureOutput = (manager._filterCount%2) ? manager._bufferTextureConcat : manager._bufferTextureOutput;
+		this._batchTextureConcat = (manager._filterCount%2) ? manager._bufferTextureOutput : manager._bufferTextureConcat;
+		this._batchTextureTemp = manager._bufferTextureTemp;
+
 		var container = this._cacheContainer;
 		container.children = [target];
 		container.transformMatrix = this._alignTargetToCache(target, manager);
 
 		this._updateRenderMode("source-over");
-		this._drawContent(contentStamp._frameBuffer, container, true);
+		this._drawContent(container, true);
 
-		while(filtersLeft) { //warning: pay attention to where filtersLeft is modified, this is a micro-optimization
-			var filter = manager._getGLFilter(filterCount - filtersLeft);
-			var drawTarget = manager._getGLContentTarget(--filtersLeft);
-			this._drawCover(drawTarget._frameBuffer, contentStamp, filter);
-			contentStamp = drawTarget;
+		// despite trying to align the buffers for final output we could have had it mis-aligned due to composite operations
+		if (out !== this._batchTextureOutput) {
+			// this works because getGLFilter will return undefined on an out of range value
+			// and the only way to of become desynced will of made a concat buffer to draw to
+			filtersLeft++;
 		}
 
-		this.updateViewport(backupWidth, backupHeight);
-		return true;
-	};
-
-	/**
-	 * Render textures can't draw into themselves so any item being used for renderTextures needs two to alternate between.
-	 * This function creates, gets, and adjusts the specified render surface.
-	 *
-	 * @method getTargetRenderTexture
-	 * @param  {BitmapCache} target The object associated with the render textures, usually a cached object.
-	 * @param  {Number} w The width to create the texture at.
-	 * @param  {Number} h The height to create the texture at.
-	 * @param  {Boolean} [primary=false] Whether this is the primary render surface
-	 * @return {WebGLTexture}
-	 */
-	p.getTargetRenderTexture = function (target, w, h, primary) {
-		var output, lookup;
-
-		// create if new
-		if (primary) {
-			lookup = target._renderTextureOut;
-			if (!lookup) {
-				output = target._renderTextureOut = this.getRenderBufferTexture(w, h);
-			}
-		} else {
-			lookup = target._renderTextureTemp;
-			if (!lookup) {
-				output = target._renderTextureTemp = this.getRenderBufferTexture(w, h);
-			}
+		while (filtersLeft) { //warning: pay attention to where filtersLeft is modified, this is a micro-optimization
+			var filter = manager._getGLFilter(filterCount - (filtersLeft--));
+			var swap = this._batchTextureConcat;
+			this._batchTextureConcat = this._batchTextureOutput;
+			this._batchTextureOutput = swap;
+			this._drawCover(this._batchTextureOutput._frameBuffer, this._batchTextureConcat, filter);
 		}
 
-		// configure if we found it, make sure it's configured right
-		if(lookup) {
-			if (w !== lookup._width || h !== lookup._height) {
-				this.resizeTexture(lookup, w, h);
-			}
-			this.setTextureParams(this._webGLContext);
-			output = lookup;
-		}
+		manager._bufferTextureOutput = this._batchTextureOutput;
+		manager._bufferTextureConcat = this._batchTextureConcat;
+		manager._bufferTextureTemp = this._batchTextureTemp;
 
-		if (output == null) {
-			throw "Problems creating render textures, known causes include using too much VRAM by not releasing WebGL texture instances";
-		}
-		return output;
+		this.updateViewport(backupWidth, backupHeight);
+		return true;
 	};
 
 	/**
@@ -1508,12 +1505,12 @@ this.createjs = this.createjs||{};
 				-1,							1,								0,							1
 			]);
 
-			if (this._bufferTextureConcat !== null) {
-				this.resizeTexture(this._bufferTextureConcat, this._viewportWidth, this._viewportHeight);
-			}
 			if (this._bufferTextureOutput !== null) {
 				this.resizeTexture(this._bufferTextureOutput, this._viewportWidth, this._viewportHeight);
 			}
+			if (this._bufferTextureConcat !== null) {
+				this.resizeTexture(this._bufferTextureConcat, this._viewportWidth, this._viewportHeight);
+			}
 			if (this._bufferTextureTemp !== null) {
 				this.resizeTexture(this._bufferTextureTemp, this._viewportWidth, this._viewportHeight);
 			}
@@ -1584,10 +1581,12 @@ this.createjs = this.createjs||{};
 	 * @protected
 	 * @method resizeTexture
 	 * @param  {WebGLTexture} texture The GL Texture to be modified.
-	 * @param  {uint} [width=1] The width of the texture in pixels, defaults to 1
-	 * @param  {uint} [height=1] The height of the texture in pixels, defaults to 1
+	 * @param  {uint} width The width of the texture in pixels
+	 * @param  {uint} height The height of the texture in pixels
 	 */
 	p.resizeTexture = function (texture, width,height) {
+		if(texture.width === width && texture.height === height){ return; }
+
 		var gl = this._webGLContext;
 		gl.bindTexture(gl.TEXTURE_2D, texture);
 		gl.texImage2D(
@@ -1599,6 +1598,8 @@ this.createjs = this.createjs||{};
 			gl.UNSIGNED_BYTE,			// type of texture(pixel color depth)
 			null						// image data, we can do null because we're doing array data
 		);
+
+		// set its width and height for spoofing as an image and tracking
 		texture.width = width;
 		texture.height = height;
 	};
@@ -1615,15 +1616,13 @@ this.createjs = this.createjs||{};
 	p.getRenderBufferTexture = function (w, h) {
 		var gl = this._webGLContext;
 
-		// get the texture
 		var renderTexture = this.getBaseTexture(w, h);
 		if (!renderTexture) { return null; }
 
-		// get the frame buffer
 		var frameBuffer = gl.createFramebuffer();
 		if (!frameBuffer) { return null; }
 
-		// set its width and height for spoofing as an image
+		// set its width and height for spoofing as an image and tracking
 		renderTexture.width = w;
 		renderTexture.height = h;
 
@@ -1886,18 +1885,20 @@ this.createjs = this.createjs||{};
 	 * @protected
 	 */
 	p._createShader = function (gl, type, str) {
-		var count = this._batchTextureCount || this._gpuTextureCount;
+		var textureCount = this._batchTextureCount;
 
 		// inject the static number
-		str = str.replace(/\{\{count}}/g, count);
-
-		// resolve issue with no dynamic samplers by creating correct samplers in if else chain
-		// TODO: WebGL 2.0 does not need this support
-		var insert = "";
-		for (var i = 1; i<count; i++) {
-			insert += "} else if (indexPicker <= "+ i +".5) { color = texture2D(uSampler["+ i +"], vTextureCoord);";
+		str = str.replace(/\{\{count}}/g, textureCount);
+
+		if(type === gl.FRAGMENT_SHADER) {
+			// resolve issue with no dynamic samplers by creating correct samplers in if else chain
+			// TODO: WebGL 2.0 does not need this support
+			var insert = "";
+			for (var i = 1; i<textureCount; i++) {
+				insert += "} else if (indexPicker <= "+ i +".5) { color = texture2D(uSampler["+ i +"], vTextureCoord);";
+			}
+			str = str.replace(/\{\{alternates}}/g, insert);
 		}
-		str = str.replace(/\{\{alternates}}/g, insert);
 
 		// actually compile the shader
 		var shader = gl.createShader(type);
@@ -1919,7 +1920,7 @@ this.createjs = this.createjs||{};
 	 */
 	p._createBuffers = function () {
 		var gl = this._webGLContext;
-		var groupCount = this._maxCardsPerBatch * StageGL.INDICIES_PER_CARD;
+		var groupCount = this._maxBatchVertexCount;
 		var groupSize, i, l;
 
 		// INFO:
@@ -2010,29 +2011,23 @@ this.createjs = this.createjs||{};
 		this._gpuTextureCount = gl.getParameter(gl.MAX_TEXTURE_IMAGE_UNITS); // this is what we can draw with
 		this._gpuTextureMax = gl.getParameter(gl.MAX_COMBINED_TEXTURE_IMAGE_UNITS); // this could be higher
 
+		this._batchTextureCount = this._gpuTextureCount;
 		var success = false;
 		while (!success) {
 			try {
-				this._fetchShaderProgram(false);
+				this._activeShader = this._fetchShaderProgram(false);
 				success = true;
 			} catch(e) {
-				if (this._gpuTextureCount <= 1) { throw "Cannot compile shader " + e; }
-				this._gpuTextureCount = (this._gpuTextureCount / 2)|0;
+				if (this._batchTextureCount <= 1) { throw "Cannot compile shader " + e; }
+				this._batchTextureCount = (this._batchTextureCount / 2)|0;
 
 				if (this.vocalDebug) {
-					console.log("Reducing possible texture count due to errors: " + this._gpuTextureCount);
+					console.log("Reducing possible texture count due to errors: " + this._batchTextureCount);
 				}
 			}
 		}
 
-		//TODO: turn into function for dynamic updates
-		this._textureDrawReserve = 0;
-		this._textureTrackReserve = 1;
-
-		this._freeTextureCount = this._gpuTextureMax - this._textureTrackReserve;
-		this._batchTextureCount = Math.min(this._freeTextureCount, this._gpuTextureCount - this._textureDrawReserve);
-
-		this._mainShader = this._activeShader = this._fetchShaderProgram(false);
+		this._mainShader = this._activeShader;
 
 		// fill in blanks as it helps the renderer be stable while textures are loading and reduces need for safety code
 		var texture = this.getBaseTexture();
@@ -2041,7 +2036,7 @@ this.createjs = this.createjs||{};
 		} else {
 			texture._storeID = -1;
 		}
-		for (var i=0; i<this._gpuTextureCount; i++) { // use GPU textures count to ensure we have enough
+		for (var i=0; i<this._batchTextureCount; i++) {
 			this._baseTextures[i] = this._batchTextures[i] = texture;
 		}
 	};
@@ -2276,7 +2271,7 @@ this.createjs = this.createjs||{};
 
 		var blendSrc = StageGL.BLEND_SOURCES[newMode];
 		if (blendSrc === undefined) {
-			if(this.vocalDebug){ console.log("Unknown shader ["+ newMode +"], reverting to default"); }
+			if(this.vocalDebug){ console.log("Unknown compositeOperation ["+ newMode +"], reverting to default"); }
 			blendSrc = StageGL.BLEND_SOURCES[newMode = "source-over"];
 		}
 
@@ -2307,8 +2302,8 @@ this.createjs = this.createjs||{};
 			}
 		}
 
-		if(shaderData.immediate && this._directDraw) {
-			if(this.vocalDebug) { console.log("ignored render mode ["+ newMode +"] due to directDraw"); }
+		if (shaderData.immediate && this._directDraw) {
+			if(this.vocalDebug) { console.log("Illegal compositeOperation ["+ newMode +"] due to StageGL.directDraw = true, reverting to default"); }
 			return;
 		}
 
@@ -2323,17 +2318,17 @@ this.createjs = this.createjs||{};
 
 	/**
 	 * Helper function for the standard content draw
-	 * @param {WebGLFramebuffer} out Buffer to draw the results into (null is the canvas element)
+	 * @method _drawContent
 	 * @param {Stage | Container} content
 	 * @param {Boolean} ignoreCache
 	 * @protected
 	 */
-	p._drawContent = function (out, content, ignoreCache) {
+	p._drawContent = function (content, ignoreCache) {
 		var gl = this._webGLContext;
 
 		this._activeShader = this._mainShader;
 
-		gl.bindFramebuffer(gl.FRAMEBUFFER, out);
+		gl.bindFramebuffer(gl.FRAMEBUFFER, this._batchTextureOutput._frameBuffer);
 		gl.clear(gl.COLOR_BUFFER_BIT);
 
 		this._appendToBatch(content, new createjs.Matrix2D(), this.alpha, ignoreCache);
@@ -2346,6 +2341,7 @@ this.createjs = this.createjs||{};
 	 * Used to draw one or more textures potentially using a filter into the supplied buffer.
 	 * Mostly used for caches, filters, and outputting final render frames.
 	 * Draws `dst` into `out` after applying `srcFilter` depending on its current value.
+	 * @method _drawCover
 	 * @param {WebGLFramebuffer} out Buffer to draw the results into (null is the canvas element)
 	 * @param {WebGLTexture} dst Base texture layer aka "destination" in image blending terminology
 	 * @param {WebGLTexture | Filter} [srcFilter = undefined] Modification parameter for the draw. If a texture, the
@@ -2414,7 +2410,6 @@ this.createjs = this.createjs||{};
 		var gl = this._webGLContext;
 
 		// sort out shared properties
-		if (container._glMtx === undefined) { container._glMtx = new createjs.Matrix2D(); }		//TODO: benchmark removing this
 		var cMtx = container._glMtx;
 		cMtx.copy(concatMtx);
 		if (container.transformMatrix !== null) {
@@ -2428,9 +2423,8 @@ this.createjs = this.createjs||{};
 			);
 		}
 
-		var backupMode = null;
+		var previousRenderMode = this._renderMode;
 		if (container.compositeOperation) {
-			backupMode = this._renderMode;
 			this._updateRenderMode(container.compositeOperation);
 		}
 
@@ -2461,13 +2455,12 @@ this.createjs = this.createjs||{};
 
 			// check for overflowing batch, if yes then force a render
 			// TODO: DHG: consider making this polygon count dependant for things like vector draws
-			if (this._batchCardCount+1 > this._maxCardsPerBatch) {
+			if (this._batchVertexCount+StageGL.INDICIES_PER_CARD > this._maxBatchVertexCount) {
 				this.batchReason = "vertexOverflow";
 				this._renderBatch();					// <------------------------------------------------------------
 			}
 
 			// keep track of concatenated position
-			if (!item._glMtx) { item._glMtx = new createjs.Matrix2D(); }		//TODO: benchmark removing this
 			var iMtx = item._glMtx;
 			iMtx.copy(cMtx);
 			if (item.transformMatrix) {
@@ -2568,8 +2561,8 @@ this.createjs = this.createjs||{};
 			}
 
 			// These must be calculated here else a forced draw might happen after they're set
-			var offV1 = this._batchCardCount*StageGL.INDICIES_PER_CARD;		// offset for 1 component vectors
-			var offV2 = offV1*2;											// offset for 2 component vectors
+			var offV1 = this._batchVertexCount;					// offset for 1 component vectors
+			var offV2 = offV1*2;								// offset for 2 component vectors
 
 			//DHG: See Matrix2D.transformPoint for why this math specifically
 			// apply vertices
@@ -2594,15 +2587,15 @@ this.createjs = this.createjs||{};
 			// apply alpha
 			alphas[offV1] = alphas[offV1+1] = alphas[offV1+2] = alphas[offV1+3] = alphas[offV1+4] = alphas[offV1+5] = item.alpha * concatAlpha;
 
-			this._batchCardCount++;
+			this._batchVertexCount += StageGL.INDICIES_PER_CARD;
 
 			if (this._immediateRender) {
 				this._immediateBatchRender(gl);
 			}
 		}
 
-		if (backupMode !== null) {
-			this._updateRenderMode(backupMode);
+		if (this._renderMode !== previousRenderMode) {
+			this._updateRenderMode(previousRenderMode);
 		}
 	};
 
@@ -2611,30 +2604,30 @@ this.createjs = this.createjs||{};
 	 * @protected
 	 */
 	p._immediateBatchRender = function(gl) {
-		if(this._bufferTextureConcat === null){
-			this._bufferTextureConcat = this.getRenderBufferTexture(this._viewportWidth, this._viewportHeight);
+		if(this._batchTextureConcat === null){
+			this._batchTextureConcat = this.getRenderBufferTexture(this._viewportWidth, this._viewportHeight);
 		}
-		if(this._bufferTextureTemp === null){
-			this._bufferTextureTemp = this.getRenderBufferTexture(this._viewportWidth, this._viewportHeight);
+		if(this._batchTextureTemp === null){
+			this._batchTextureTemp = this.getRenderBufferTexture(this._viewportWidth, this._viewportHeight);
 		}
 
-		gl.bindFramebuffer(gl.FRAMEBUFFER, this._bufferTextureConcat._frameBuffer);
+		gl.bindFramebuffer(gl.FRAMEBUFFER, this._batchTextureConcat._frameBuffer);
 		gl.clear(gl.COLOR_BUFFER_BIT);
 
-		var swap = this._bufferTextureOutput;
-		this._bufferTextureOutput = this._bufferTextureConcat;
-		this._bufferTextureConcat = swap;
+		var swap = this._batchTextureOutput;
+		this._batchTextureOutput = this._batchTextureConcat;
+		this._batchTextureConcat = swap;
 
 		this._activeShader = this._mainShader;
-		gl.bindFramebuffer(gl.FRAMEBUFFER, this._bufferTextureTemp._frameBuffer);
+		gl.bindFramebuffer(gl.FRAMEBUFFER, this._batchTextureTemp._frameBuffer);
 		gl.clear(gl.COLOR_BUFFER_BIT);
 		this.batchReason = "immediateBuffer";
 		this._renderBatch();//<-----------------------------------------------------------------------------------------
 
 		this.batchReason = "immediateDraw";
-		this._drawCover(this._bufferTextureOutput._frameBuffer, this._bufferTextureConcat, this._bufferTextureTemp);
+		this._drawCover(this._batchTextureOutput._frameBuffer, this._batchTextureConcat, this._batchTextureTemp);
 
-		gl.bindFramebuffer(gl.FRAMEBUFFER, this._bufferTextureOutput._frameBuffer);
+		gl.bindFramebuffer(gl.FRAMEBUFFER, this._batchTextureOutput._frameBuffer);
 	};
 
 	/**
@@ -2643,7 +2636,7 @@ this.createjs = this.createjs||{};
 	 * @protected
 	 */
 	p._renderBatch = function () {
-		if (this._batchCardCount <= 0) { return; }	// prevents error logs on stages filled with un-renederable content.
+		if (this._batchVertexCount <= 0) { return; }	// prevents error logs on stages filled with un-renederable content.
 		var gl = this._webGLContext;
 
 		if (this.vocalDebug) {
@@ -2682,9 +2675,9 @@ this.createjs = this.createjs||{};
 			this.setTextureParams(gl, texture.isPOT);
 		}
 
-		gl.drawArrays(gl.TRIANGLES, 0, this._batchCardCount*StageGL.INDICIES_PER_CARD);
+		gl.drawArrays(gl.TRIANGLES, 0, this._batchVertexCount);
 
-		this._batchCardCount = 0;
+		this._batchVertexCount = 0;
 		this._batchID++;
 	};
 
diff --git a/src/easeljs/filters/BitmapCache.js b/src/easeljs/filters/BitmapCache.js
index 85e24deec..dabacad5f 100644
--- a/src/easeljs/filters/BitmapCache.js
+++ b/src/easeljs/filters/BitmapCache.js
@@ -242,24 +242,28 @@ this.createjs = this.createjs||{};
 		this._counterMatrix = null;
 
 		/**
-		 * Render texture temporary surface, used for swapping render calls in complex effects.
-		 * The difference between out and Temp is that Out is assigned to the cacheCanvas property of the display object
-		 * being managed by this class. That needs to be the same element consistently to allow for chaining filters & effects.
-		 * @property _renderTextureOut
+		 * One of the major render buffers used in composite blending and filter drawing. Do not expect this to always be the same object.
+		 * "What you're drawing to", object occasionally swaps with concat.
+		 * @property _bufferTextureOutput
 		 * @type {WebGLTexture}
-		 * @default 0
 		 */
-		this._renderTextureOut = null;
+		this._bufferTextureOutput = null;
 
 		/**
-		 * Render texture temporary surface, used for swapping render calls in complex effects.
-		 * The difference between out and Temp is that Out is assigned to the cacheCanvas property of the display object
-		 * being managed by this class. That needs to be the same element consistently to allow for chaining filters & effects.
-		 * @property _renderTextureTemp
+		 * One of the major render buffers used in composite blending and filter drawing. Do not expect this to always be the same object.
+		 * "What you've draw before now", object occasionally swaps with output.
+		 * @property _bufferTextureConcat
+		 * @type {WebGLTexture}
+		 */
+		this._bufferTextureConcat = null;
+
+		/**
+		 * One of the major render buffers used only for composite blending draws.
+		 * "Temporary mixing surface"
+		 * @property _bufferTextureTemp
 		 * @type {WebGLTexture}
-		 * @default 0
 		 */
-		this._renderTextureTemp = null;
+		this._bufferTextureTemp = null;
 	}
 	var p = BitmapCache.prototype;
 
@@ -419,7 +423,7 @@ this.createjs = this.createjs||{};
 	 * @param {String} [compositeOperation=null] The DisplayObject this cache is linked to.
 	 **/
 	p.update = function(compositeOperation) {
-		if(!this.target) { throw "define() must be called before update()"; }
+		if (!this.target) { throw "define() must be called before update()"; }
 
 		var filterBounds = BitmapCache.getFilterBounds(this.target);
 		var surface = this._cacheCanvas;
@@ -433,16 +437,22 @@ this.createjs = this.createjs||{};
 		}
 
 		if (this._stageGL) {
-			var surfaceCount = this._filterCount + (this._stageGL.isCacheControlled ? 0 : 1);
-			if(surfaceCount >= 1) {
-				var out = this._stageGL.getTargetRenderTexture(this, this._drawWidth,this._drawHeight, true);
-				if(this._cacheCanvas === null){
-					this._cacheCanvas = out;
-					this.disabled = this._disabled;
-				}
+			if (this._bufferTextureOutput === null) {
+				this._bufferTextureOutput = this._stageGL.getRenderBufferTexture(this._drawWidth, this._drawHeight);
+			} else {
+				this._stageGL.resizeTexture(this._bufferTextureOutput, this._drawWidth, this._drawHeight);
 			}
-			if(surfaceCount >= 2) {
-				this._stageGL.getTargetRenderTexture(this, this._drawWidth,this._drawHeight, false);
+
+			if(this._cacheCanvas === null){
+				this._cacheCanvas = this._bufferTextureOutput;
+				this.disabled = this._disabled;
+			}
+			if (this._filterCount >= 1) {
+				if (this._bufferTextureConcat === null) {
+					this._bufferTextureConcat = this._stageGL.getRenderBufferTexture(this._drawWidth, this._drawHeight);
+				} else {
+					this._stageGL.resizeTexture(this._bufferTextureConcat, this._drawWidth, this._drawHeight);
+				}
 			}
 		}
 
@@ -462,8 +472,9 @@ this.createjs = this.createjs||{};
 	 **/
 	p.release = function() {
 		if (this._stageGL) {
-			if (this._renderTextureOut){ this._stageGL._killTextureObject(this._renderTextureOut); }
-			if (this._renderTextureTemp){ this._stageGL._killTextureObject(this._renderTextureTemp); }
+			if (this._bufferTextureOutput !== null){ this._stageGL._killTextureObject(this._bufferTextureOutput); }
+			if (this._bufferTextureConcat !== null){ this._stageGL._killTextureObject(this._bufferTextureConcat); }
+			if (this._bufferTextureTemp !== null){ this._stageGL._killTextureObject(this._bufferTextureTemp); }
 			// set the context to none and let the garbage collector get the rest when the canvas itself gets removed
 			this._stageGL = false;
 		} else {
@@ -525,26 +536,6 @@ this.createjs = this.createjs||{};
 		);
 	};
 
-	/**
-	 * Determines and returns the correct draw target for the content to be output to.
-	 * Intended for internal use.
-	 * @method _getGLContentTarget
-	 * @param {Number} filterCount Whole number, the number of filters still to be drawn
-	 * @returns {WebGLTexture}
-	 */
-	p._getGLContentTarget = function(filterCount) {
-		if(!(filterCount >= 0)){ filterCount = 0; }
-		// draws ping pong between out/temp as each filter pass occurs, starting on the right foot avoids pointless draws
-		// to canvas, no filter			= canvas
-		// to canvas, odd filters		= out
-		// to canvas, even filters		= temp
-		// to texture, no filter		= out
-		// to texture, odd filters		= temp
-		// to texture, even filters		= out
-		if(filterCount === 0 && this._stageGL.isCacheControlled) { return this._cacheCanvas }
-		return ((filterCount % 2) ^ this._stageGL.isCacheControlled) ? this._renderTextureTemp : this._renderTextureOut;
-	};
-
 	/**
 	 * Fetch the correct filter in order, complicated by multipass filtering.
 	 * @param {Number} lookup The filter in the list to return
@@ -555,7 +546,7 @@ this.createjs = this.createjs||{};
 		while(result && --lookup >= 0) {
 			result = result._multiPass ? result._multiPass : this.target.filters[++i];
 		}
-		return result
+		return result;
 	};
 
 // private methods:

From d0fd064ae0cf5abd5072491aefc130cc66a43987 Mon Sep 17 00:00:00 2001
From: David Gillen <david@gskinner.com>
Date: Thu, 15 Mar 2018 11:25:57 -0600
Subject: [PATCH 25/39] documentation update and fixes for cacheControlled
 StageGL and no filter caches

---
 src/easeljs/display/StageGL.js     | 87 +++++++++++++++++++++++++++---
 src/easeljs/filters/BitmapCache.js |  2 +-
 2 files changed, 80 insertions(+), 9 deletions(-)

diff --git a/src/easeljs/display/StageGL.js b/src/easeljs/display/StageGL.js
index e56f51c71..88a667e94 100644
--- a/src/easeljs/display/StageGL.js
+++ b/src/easeljs/display/StageGL.js
@@ -629,6 +629,7 @@ this.createjs = this.createjs||{};
 	/**
 	 * The number of properties defined per vertex (x, y, textureU, textureV, textureIndex, alpha)
 	 * @property VERTEX_PROPERTY_COUNT
+	 * @protected
 	 * @static
 	 * @final
 	 * @type {Number}
@@ -640,6 +641,7 @@ this.createjs = this.createjs||{};
 	/**
 	 * The number of triangle indices it takes to form a Card. 3 per triangle, 2 triangles.
 	 * @property INDICIES_PER_CARD
+	 * @protected
 	 * @static
 	 * @final
 	 * @type {Number}
@@ -675,6 +677,7 @@ this.createjs = this.createjs||{};
 	/**
 	 * Default UV rect for dealing with full coverage from an image source.
 	 * @property UV_RECT
+	 * @protected
 	 * @static
 	 * @final
 	 * @type {Object}
@@ -724,6 +727,7 @@ this.createjs = this.createjs||{};
 	 * regular shader is designed to render all expected objects. Shader code may contain templates that are replaced
 	 * pre-compile.
 	 * @property REGULAR_VARYING_HEADER
+	 * @protected
 	 * @static
 	 * @final
 	 * @type {String}
@@ -741,6 +745,7 @@ this.createjs = this.createjs||{};
 	 * Actual full header for the vertex shader. Includes the varying header. The regular shader is designed to render
 	 * all expected objects. Shader code may contain templates that are replaced pre-compile.
 	 * @property REGULAR_VERTEX_HEADER
+	 * @protected
 	 * @static
 	 * @final
 	 * @type {String}
@@ -759,6 +764,7 @@ this.createjs = this.createjs||{};
 	 * Actual full header for the fragment shader. Includes the varying header. The regular shader is designed to render
 	 * all expected objects. Shader code may contain templates that are replaced pre-compile.
 	 * @property REGULAR_FRAGMENT_HEADER
+	 * @protected
 	 * @static
 	 * @final
 	 * @type {String}
@@ -773,6 +779,7 @@ this.createjs = this.createjs||{};
 	 * Body of the vertex shader. The regular shader is designed to render all expected objects. Shader code may contain
 	 * templates that are replaced pre-compile.
 	 * @property REGULAR_VERTEX_BODY
+	 * @protected
 	 * @static
 	 * @final
 	 * @type {String}
@@ -791,6 +798,7 @@ this.createjs = this.createjs||{};
 	 * Body of the fragment shader. The regular shader is designed to render all expected objects. Shader code may
 	 * contain templates that are replaced pre-compile.
 	 * @property REGULAR_FRAGMENT_BODY
+	 * @protected
 	 * @static
 	 * @final
 	 * @type {String}
@@ -814,6 +822,7 @@ this.createjs = this.createjs||{};
 	 * cover shader is designed to be a simple vertex/uv only texture render that covers the render surface. Shader
 	 * code may contain templates that are replaced pre-compile.
 	 * @property COVER_VARYING_HEADER
+	 * @protected
 	 * @static
 	 * @final
 	 * @type {String}
@@ -830,6 +839,7 @@ this.createjs = this.createjs||{};
 	 * simple vertex/uv only texture render that covers the render surface. Shader code may contain templates that are
 	 * replaced pre-compile.
 	 * @property COVER_VERTEX_HEADER
+	 * @protected
 	 * @static
 	 * @final
 	 * @type {String}
@@ -846,6 +856,7 @@ this.createjs = this.createjs||{};
 	 * simple vertex/uv only texture render that covers the render surface. Shader code may contain templates that are
 	 * replaced pre-compile.
 	 * @property COVER_FRAGMENT_HEADER
+	 * @protected
 	 * @static
 	 * @final
 	 * @type {String}
@@ -860,6 +871,7 @@ this.createjs = this.createjs||{};
 	 * Body of the vertex shader. The cover shader is designed to be a simple vertex/uv only texture render that covers
 	 * the render surface. Shader code may contain templates that are replaced pre-compile.
 	 * @property COVER_VERTEX_BODY
+	 * @protected
 	 * @static
 	 * @final
 	 * @type {String}
@@ -876,6 +888,7 @@ this.createjs = this.createjs||{};
 	 * Body of the fragment shader. The cover shader is designed to be a simple vertex/uv only texture render that
 	 * covers the render surface. Shader code may contain templates that are replaced pre-compile.
 	 * @property COVER_FRAGMENT_BODY
+	 * @protected
 	 * @static
 	 * @final
 	 * @type {String}
@@ -887,6 +900,15 @@ this.createjs = this.createjs||{};
 		"}"
 	);
 
+	/**
+	 * The starting template of a cover fragment shader with simple blending equations
+	 * @property BLEND_FRAGMENT_SIMPLE
+	 * @protected
+	 * @static
+	 * @final
+	 * @type {String}
+	 * @readonly
+	 */
 	StageGL.BLEND_FRAGMENT_SIMPLE = (
 		"uniform sampler2D uMixSampler;"+
 		"void main(void) {" +
@@ -895,6 +917,15 @@ this.createjs = this.createjs||{};
 		// note this is an open bracket on main!
 	);
 
+	/**
+	 * The starting template of a cover fragment shader which has complex blending equations
+	 * @property BLEND_FRAGMENT_COMPLEX
+	 * @protected
+	 * @static
+	 * @final
+	 * @type {String}
+	 * @readonly
+	 */
 	StageGL.BLEND_FRAGMENT_COMPLEX = (
 		StageGL.BLEND_FRAGMENT_SIMPLE +
 			"vec3 srcClr = min(src.rgb/src.a, 1.0);" +
@@ -912,6 +943,16 @@ this.createjs = this.createjs||{};
 					"mixFactor * vec3("
 		// this should be closed with the cap!
 	);
+
+	/**
+	 * The closing portion of a template for a cover fragment shader which has complex blending equations
+	 * @property BLEND_FRAGMENT_COMPLEX_CAP
+	 * @protected
+	 * @static
+	 * @final
+	 * @type {String}
+	 * @readonly
+	 */
 	StageGL.BLEND_FRAGMENT_COMPLEX_CAP = (
 					")" +
 				") * totalAlpha, totalAlpha" +
@@ -919,6 +960,15 @@ this.createjs = this.createjs||{};
 		"}"
 	);
 
+	/**
+	 * A shader utility function, used to calculate the "overlay" blend of two elements
+	 * @property BLEND_FRAGMENT_OVERLAY_UTIL
+	 * @protected
+	 * @static
+	 * @final
+	 * @type {String}
+	 * @readonly
+	 */
 	StageGL.BLEND_FRAGMENT_OVERLAY_UTIL = (
 		"float overlay(float a, float b) {" +
 			"if(a < 0.5) { return 2.0 * a * b; }" +
@@ -926,6 +976,16 @@ this.createjs = this.createjs||{};
 		"}"
 	);
 
+	/**
+	 * A collection of shader utility functions, used to calculate HSL math. Taken from W3C spec
+	 * https://www.w3.org/TR/compositing-1/#blendingnonseparable
+	 * @property BLEND_FRAGMENT_HSL_UTIL
+	 * @protected
+	 * @static
+	 * @final
+	 * @type {String}
+	 * @readonly
+	 */
 	StageGL.BLEND_FRAGMENT_HSL_UTIL = (
 		"float getLum(vec3 c) { return 0.299*c.r + 0.589*c.g + 0.109*c.b; }" +
 		"float getSat(vec3 c) { return max(max(c.r, c.g), c.b) - min(min(c.r, c.g), c.b); }" +
@@ -956,6 +1016,14 @@ this.createjs = this.createjs||{};
 		"}"
 	);
 
+	/**
+	 * The hash of supported blend modes and their properties
+	 * @property BLEND_SOURCES
+	 * @static
+	 * @final
+	 * @type {Object}
+	 * @readonly
+	 */
 	StageGL.BLEND_SOURCES = {
 		"source-over": { // empty object verifies it as a blend mode, but default values handle actual settings
 			//eqRGB: "FUNC_ADD",						eqA: "FUNC_ADD"
@@ -1332,12 +1400,10 @@ this.createjs = this.createjs||{};
 			return false;
 		}
 
-		var swap, filterCount = manager._filterCount, filtersLeft = filterCount;
+		var filterCount = manager._filterCount, filtersLeft = filterCount;
 		var backupWidth = this._viewportWidth, backupHeight = this._viewportHeight;
 		this.updateViewport(manager._drawWidth, manager._drawHeight);
 
-		// TODO: DIRECT CACHE WRITE
-
 		var out = this._batchTextureOutput = (manager._filterCount%2) ? manager._bufferTextureConcat : manager._bufferTextureOutput;
 		this._batchTextureConcat = (manager._filterCount%2) ? manager._bufferTextureOutput : manager._bufferTextureConcat;
 		this._batchTextureTemp = manager._bufferTextureTemp;
@@ -1349,10 +1415,15 @@ this.createjs = this.createjs||{};
 		this._updateRenderMode("source-over");
 		this._drawContent(container, true);
 
-		// despite trying to align the buffers for final output we could have had it mis-aligned due to composite operations
+		// re-align buffers with fake filter passes to solve certain error cases
 		if (out !== this._batchTextureOutput) {
-			// this works because getGLFilter will return undefined on an out of range value
-			// and the only way to of become desynced will of made a concat buffer to draw to
+			// pre filter pass to align output, may of become misaligned due to composite operations
+			filtersLeft++;
+		}
+		if (this.isCacheControlled) {
+			// post filter pass to place content into output buffer
+			//TODO: add in directDraw support for cache controlled StageGLs
+			filterCount++;
 			filtersLeft++;
 		}
 
@@ -1360,7 +1431,7 @@ this.createjs = this.createjs||{};
 			var filter = manager._getGLFilter(filterCount - (filtersLeft--));
 			var swap = this._batchTextureConcat;
 			this._batchTextureConcat = this._batchTextureOutput;
-			this._batchTextureOutput = swap;
+			this._batchTextureOutput = (this.isCacheControlled && filtersLeft === 0) ? this : swap;
 			this._drawCover(this._batchTextureOutput._frameBuffer, this._batchTextureConcat, filter);
 		}
 
@@ -2682,7 +2753,7 @@ this.createjs = this.createjs||{};
 	};
 
 	/**
-	 * Draws a card that covers the entire render surface. Mainly used for filters.
+	 * Draws a card that covers the entire render surface. Mainly used for filters and composite operations.
 	 * @method _renderCover
 	 * @protected
 	 */
diff --git a/src/easeljs/filters/BitmapCache.js b/src/easeljs/filters/BitmapCache.js
index dabacad5f..112668ddc 100644
--- a/src/easeljs/filters/BitmapCache.js
+++ b/src/easeljs/filters/BitmapCache.js
@@ -430,7 +430,7 @@ this.createjs = this.createjs||{};
 
 		this._drawWidth = Math.ceil(this.width*this.scale) + filterBounds.width;
 		this._drawHeight = Math.ceil(this.height*this.scale) + filterBounds.height;
-		this._filterCount = this.target.filters.reduce(BitmapCache.filterCounter, 0);
+		this._filterCount = this.target.filters && this.target.filters.reduce(BitmapCache.filterCounter, 0);
 
 		if(!surface || this._drawWidth !== surface.width || this._drawHeight !== surface.height) {
 			this._updateSurface();

From e5420c1ededaea0569fce9b529632b7220789e36 Mon Sep 17 00:00:00 2001
From: David Gillen <david@gskinner.com>
Date: Thu, 15 Mar 2018 14:32:30 -0600
Subject: [PATCH 26/39] Resolve issues with composite operations inside of
 caches

---
 src/easeljs/display/StageGL.js     | 30 ++++++++++++++++++++----------
 src/easeljs/filters/BitmapCache.js |  1 +
 2 files changed, 21 insertions(+), 10 deletions(-)

diff --git a/src/easeljs/display/StageGL.js b/src/easeljs/display/StageGL.js
index 88a667e94..55195f6f7 100644
--- a/src/easeljs/display/StageGL.js
+++ b/src/easeljs/display/StageGL.js
@@ -394,9 +394,9 @@ this.createjs = this.createjs||{};
 		 * The current render buffer being targeted, usually targets internal buffers, but may be set to cache's buffer during a cache render.
 		 * @property _batchTextureOutput
 		 * @protected
-		 * @type {WebGLTexture}
+		 * @type {WebGLTexture | StageGL}
 		 */
-		this._batchTextureOutput = null;
+		this._batchTextureOutput = this;
 
 		/**
 		 * The current render buffer being targeted, usually targets internal buffers, but may be set to cache's buffer during a cache render.
@@ -1354,10 +1354,9 @@ this.createjs = this.createjs||{};
 		this._batchVertexCount = 0;
 		this._drawID++;
 
-		if (this.autoClear) { this.clear(); }
-
 		if (this._directDraw) {
 			this._batchTextureOutput = this;
+			if (this.autoClear) { this.clear(); }
 		} else {
 			this._batchTextureOutput = this._bufferTextureOutput;
 			this._batchTextureConcat = this._bufferTextureConcat;
@@ -1368,6 +1367,7 @@ this.createjs = this.createjs||{};
 		this._drawContent(this, ignoreCache);
 
 		if (!this._directDraw) {
+			if (this.autoClear) { this.clear(); }
 			this.batchReason = "finalOutput";
 			this._drawCover(null, this._batchTextureOutput);
 		}
@@ -1432,6 +1432,7 @@ this.createjs = this.createjs||{};
 			var swap = this._batchTextureConcat;
 			this._batchTextureConcat = this._batchTextureOutput;
 			this._batchTextureOutput = (this.isCacheControlled && filtersLeft === 0) ? this : swap;
+			this.batchReason = "filterPass";
 			this._drawCover(this._batchTextureOutput._frameBuffer, this._batchTextureConcat, filter);
 		}
 
@@ -2289,7 +2290,9 @@ this.createjs = this.createjs||{};
 				if (this._textureIDs[n] === texture._storeID) { delete this._textureIDs[n]; }
 			}
 			var data = texture._imageData;
-			for (var i=data.length-1; i>=0; i--) { data[i]._storeID = undefined; }
+			if (data) {
+				for (var i=data.length-1; i>=0; i--) { data[i]._storeID = undefined; }
+			}
 			texture._imageData = texture._storeID = undefined;
 		}
 
@@ -2378,6 +2381,8 @@ this.createjs = this.createjs||{};
 			return;
 		}
 
+		gl.bindFramebuffer(gl.FRAMEBUFFER, this._batchTextureOutput._frameBuffer);
+
 		this.batchReason = "shaderSwap";
 		this._renderBatch();		// <--------------------------------------------------------------------------------
 
@@ -2423,6 +2428,7 @@ this.createjs = this.createjs||{};
 		var gl = this._webGLContext;
 
 		gl.bindFramebuffer(gl.FRAMEBUFFER, out);
+		if (out !== null){ gl.clear(gl.COLOR_BUFFER_BIT); }
 
 		gl.activeTexture(gl.TEXTURE0);
 		gl.bindTexture(gl.TEXTURE_2D, dst);
@@ -2677,21 +2683,25 @@ this.createjs = this.createjs||{};
 	p._immediateBatchRender = function(gl) {
 		if(this._batchTextureConcat === null){
 			this._batchTextureConcat = this.getRenderBufferTexture(this._viewportWidth, this._viewportHeight);
+		} else {
+			this.resizeTexture(this._batchTextureConcat, this._viewportWidth, this._viewportHeight);
+			gl.bindFramebuffer(gl.FRAMEBUFFER, this._batchTextureConcat._frameBuffer);
+			gl.clear(gl.COLOR_BUFFER_BIT);
 		}
 		if(this._batchTextureTemp === null){
 			this._batchTextureTemp = this.getRenderBufferTexture(this._viewportWidth, this._viewportHeight);
+			gl.bindFramebuffer(gl.FRAMEBUFFER, this._batchTextureTemp._frameBuffer);
+		} else {
+			this.resizeTexture(this._batchTextureTemp, this._viewportWidth, this._viewportHeight);
+			gl.bindFramebuffer(gl.FRAMEBUFFER, this._batchTextureTemp._frameBuffer);
+			gl.clear(gl.COLOR_BUFFER_BIT);
 		}
 
-		gl.bindFramebuffer(gl.FRAMEBUFFER, this._batchTextureConcat._frameBuffer);
-		gl.clear(gl.COLOR_BUFFER_BIT);
-
 		var swap = this._batchTextureOutput;
 		this._batchTextureOutput = this._batchTextureConcat;
 		this._batchTextureConcat = swap;
 
 		this._activeShader = this._mainShader;
-		gl.bindFramebuffer(gl.FRAMEBUFFER, this._batchTextureTemp._frameBuffer);
-		gl.clear(gl.COLOR_BUFFER_BIT);
 		this.batchReason = "immediateBuffer";
 		this._renderBatch();//<-----------------------------------------------------------------------------------------
 
diff --git a/src/easeljs/filters/BitmapCache.js b/src/easeljs/filters/BitmapCache.js
index 112668ddc..57f70576f 100644
--- a/src/easeljs/filters/BitmapCache.js
+++ b/src/easeljs/filters/BitmapCache.js
@@ -541,6 +541,7 @@ this.createjs = this.createjs||{};
 	 * @param {Number} lookup The filter in the list to return
 	 */
 	p._getGLFilter = function(lookup) {
+		if (this.target.filters === null){ return undefined; }
 		var i = 0;
 		var result = this.target.filters[i];
 		while(result && --lookup >= 0) {

From 459a7891881a548f80e520e5b04dd095ab7bd6b8 Mon Sep 17 00:00:00 2001
From: David Gillen <david@gskinner.com>
Date: Thu, 15 Mar 2018 15:29:31 -0600
Subject: [PATCH 27/39] misc code standards

---
 src/easeljs/display/DisplayObject.js | 10 +++----
 src/easeljs/display/StageGL.js       | 28 +++++++++----------
 src/easeljs/filters/BitmapCache.js   | 40 ++++++++++++++--------------
 3 files changed, 39 insertions(+), 39 deletions(-)

diff --git a/src/easeljs/display/DisplayObject.js b/src/easeljs/display/DisplayObject.js
index ae57ab010..9789fd2b8 100644
--- a/src/easeljs/display/DisplayObject.js
+++ b/src/easeljs/display/DisplayObject.js
@@ -760,7 +760,7 @@ this.createjs = this.createjs||{};
 	 **/
 	p.draw = function(ctx, ignoreCache) {
 		var cache = this.bitmapCache;
-		if(cache && !ignoreCache) {
+		if (cache && !ignoreCache) {
 			return cache.draw(ctx);
 		}
 		return false;
@@ -835,7 +835,7 @@ this.createjs = this.createjs||{};
 	 * @param {Object} [options=undefined] Specify additional parameters for the cache logic
 	 **/
 	p.cache = function(x, y, width, height, scale, options) {
-		if(!this.bitmapCache){
+		if (!this.bitmapCache){
 			this.bitmapCache = new createjs.BitmapCache();
 		}
 		this.bitmapCache.define(this, x, y, width, height, scale, options);
@@ -864,7 +864,7 @@ this.createjs = this.createjs||{};
 	 * whatwg spec on compositing</a>.
 	 **/
 	p.updateCache = function(compositeOperation) {
-		if(!this.bitmapCache) {
+		if (!this.bitmapCache) {
 			throw "cache() must be called before updateCache()";
 		}
 		this.bitmapCache.update(compositeOperation);
@@ -875,7 +875,7 @@ this.createjs = this.createjs||{};
 	 * @method uncache
 	 **/
 	p.uncache = function() {
-		if(this.bitmapCache) {
+		if (this.bitmapCache) {
 			this.bitmapCache.release();
 			this.bitmapCache = undefined;
 		}
@@ -1044,7 +1044,7 @@ this.createjs = this.createjs||{};
 			
 			// we do this to avoid problems with the matrix being used for both operations when o._props.matrix is passed in as the props param.
 			// this could be simplified (ie. just done as part of the prepend above) if we switched to using a pool.
-			if (o != this) { mtx.prependMatrix(o.getMatrix(o._props.matrix)); }
+			if (o !== this) { mtx.prependMatrix(o.getMatrix(o._props.matrix)); }
 		} while (o = o.parent);
 		return props;
 	};
diff --git a/src/easeljs/display/StageGL.js b/src/easeljs/display/StageGL.js
index 55195f6f7..daa45c919 100644
--- a/src/easeljs/display/StageGL.js
+++ b/src/easeljs/display/StageGL.js
@@ -1280,7 +1280,7 @@ this.createjs = this.createjs||{};
 				this._updateRenderMode("source-over");
 
 				this.updateViewport(this.canvas.width, this.canvas.height);
-				if(!this._directDraw) {
+				if (!this._directDraw) {
 					this._bufferTextureOutput = this.getRenderBufferTexture(this._viewportWidth, this._viewportHeight);
 				}
 
@@ -1657,7 +1657,7 @@ this.createjs = this.createjs||{};
 	 * @param  {uint} height The height of the texture in pixels
 	 */
 	p.resizeTexture = function (texture, width,height) {
-		if(texture.width === width && texture.height === height){ return; }
+		if (texture.width === width && texture.height === height){ return; }
 
 		var gl = this._webGLContext;
 		gl.bindTexture(gl.TEXTURE_2D, texture);
@@ -1801,7 +1801,7 @@ this.createjs = this.createjs||{};
 	p._getSafeTexture = function (w, h) {
 		var texture = this.getBaseTexture(w, h);
 
-		if(!texture) {
+		if (!texture) {
 			var msg = "Problem creating texture, possible cause: using too much VRAM, please try releasing texture memory";
 			(console.error && console.error(msg)) || console.log(msg);
 
@@ -1821,8 +1821,8 @@ this.createjs = this.createjs||{};
 		var gl = this._webGLContext;
 		var cc = this._clearColor;
 
-		if(alpha > 0) { alpha = 1; }
-		if(alpha < 0) { alpha = 0; }
+		if (alpha > 0) { alpha = 1; }
+		if (alpha < 0) { alpha = 0; }
 
 		// Use WebGL settings; adjust for pre multiplied alpha appropriate to scenario
 		gl.clearColor(cc.r * alpha, cc.g * alpha, cc.b * alpha, alpha);
@@ -1962,7 +1962,7 @@ this.createjs = this.createjs||{};
 		// inject the static number
 		str = str.replace(/\{\{count}}/g, textureCount);
 
-		if(type === gl.FRAGMENT_SHADER) {
+		if (type === gl.FRAGMENT_SHADER) {
 			// resolve issue with no dynamic samplers by creating correct samplers in if else chain
 			// TODO: WebGL 2.0 does not need this support
 			var insert = "";
@@ -2192,7 +2192,7 @@ this.createjs = this.createjs||{};
 			gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, image);
 		} catch(e) {
 			var errString = "\nAn error has occurred. This is most likely due to security restrictions on WebGL images with local or cross-domain origins";
-			if(console.error) {
+			if (console.error) {
 				//TODO: LM: I recommend putting this into a log function internally, since you do it so often, and each is implemented differently.
 				console.error(errString);
 				console.error(e);
@@ -2260,7 +2260,7 @@ this.createjs = this.createjs||{};
 			}
 			this._lastTextureInsert = found;
 
-		} else if(texture._drawID !== this._drawID) {	// being active from previous draws doesn't mean up to date
+		} else if (texture._drawID !== this._drawID) {	// being active from previous draws doesn't mean up to date
 			image = texture._imageData && texture._imageData[0];
 			if (image && ((image._invalid === undefined && image._isCanvas) || image._invalid)) {
 				this._updateTextureImageData(gl, image);
@@ -2345,7 +2345,7 @@ this.createjs = this.createjs||{};
 
 		var blendSrc = StageGL.BLEND_SOURCES[newMode];
 		if (blendSrc === undefined) {
-			if(this.vocalDebug){ console.log("Unknown compositeOperation ["+ newMode +"], reverting to default"); }
+			if (this.vocalDebug){ console.log("Unknown compositeOperation ["+ newMode +"], reverting to default"); }
 			blendSrc = StageGL.BLEND_SOURCES[newMode = "source-over"];
 		}
 
@@ -2377,7 +2377,7 @@ this.createjs = this.createjs||{};
 		}
 
 		if (shaderData.immediate && this._directDraw) {
-			if(this.vocalDebug) { console.log("Illegal compositeOperation ["+ newMode +"] due to StageGL.directDraw = true, reverting to default"); }
+			if (this.vocalDebug) { console.log("Illegal compositeOperation ["+ newMode +"] due to StageGL.directDraw = true, reverting to default"); }
 			return;
 		}
 
@@ -2441,7 +2441,7 @@ this.createjs = this.createjs||{};
 				gl.activeTexture(gl.TEXTURE1);
 				gl.bindTexture(gl.TEXTURE_2D, srcFilter);
 				this.setTextureParams(gl);
-			} else if(srcFilter !== undefined && this.vocalDebug) {
+			} else if (srcFilter !== undefined && this.vocalDebug) {
 				console.log("Unknown data handed to function: ", srcFilter);
 			}
 			this._activeShader = this._builtShaders[this._renderMode].shader;
@@ -2459,7 +2459,7 @@ this.createjs = this.createjs||{};
 	 * @private
 	 */
 	p._alignTargetToCache = function(target, manager) {
-		if(manager._counterMatrix === null) {
+		if (manager._counterMatrix === null) {
 			manager._counterMatrix = target.getMatrix();
 		} else {
 			target.getMatrix(manager._counterMatrix)
@@ -2681,14 +2681,14 @@ this.createjs = this.createjs||{};
 	 * @protected
 	 */
 	p._immediateBatchRender = function(gl) {
-		if(this._batchTextureConcat === null){
+		if (this._batchTextureConcat === null){
 			this._batchTextureConcat = this.getRenderBufferTexture(this._viewportWidth, this._viewportHeight);
 		} else {
 			this.resizeTexture(this._batchTextureConcat, this._viewportWidth, this._viewportHeight);
 			gl.bindFramebuffer(gl.FRAMEBUFFER, this._batchTextureConcat._frameBuffer);
 			gl.clear(gl.COLOR_BUFFER_BIT);
 		}
-		if(this._batchTextureTemp === null){
+		if (this._batchTextureTemp === null){
 			this._batchTextureTemp = this.getRenderBufferTexture(this._viewportWidth, this._viewportHeight);
 			gl.bindFramebuffer(gl.FRAMEBUFFER, this._batchTextureTemp._frameBuffer);
 		} else {
diff --git a/src/easeljs/filters/BitmapCache.js b/src/easeljs/filters/BitmapCache.js
index 57f70576f..efd9aae1b 100644
--- a/src/easeljs/filters/BitmapCache.js
+++ b/src/easeljs/filters/BitmapCache.js
@@ -272,7 +272,7 @@ this.createjs = this.createjs||{};
 	};
 	p._set_disabled = function (value) {
 		this._disabled = !!value;
-		if(this.target) {
+		if (this.target) {
 			this.target.cacheCanvas = this._disabled ? null : this._cacheCanvas;
 		}
 	};
@@ -299,17 +299,17 @@ this.createjs = this.createjs||{};
 	 * @static
 	 **/
 	BitmapCache.getFilterBounds = function(target, output) {
-		if(!output){ output = new createjs.Rectangle(); }
+		if (!output){ output = new createjs.Rectangle(); }
 		var filters = target.filters;
 		var filterCount = filters && filters.length;
 		if (!!filterCount <= 0) { return output; }
 
-		for(var i=0; i<filterCount; i++) {
+		for (var i=0; i<filterCount; i++) {
 			var f = filters[i];
-			if(!f || !f.getBounds){ continue; }
+			if (!f || !f.getBounds){ continue; }
 			var test = f.getBounds();
-			if(!test){ continue; }
-			if(i === 0) {
+			if (!test){ continue; }
+			if (i === 0) {
 				output.setValues(test.x, test.y, test.width, test.height);
 			} else {
 				output.extend(test.x, test.y, test.width, test.height);
@@ -401,7 +401,7 @@ this.createjs = this.createjs||{};
 	 * @for BitmapCache
 	 */
 	 p.define = function(target, x, y, width, height, scale, options) {
-		if(!target){ throw "No symbol to cache"; }
+		if (!target){ throw "No symbol to cache"; }
 		this._options = options;
 		this.target = target;
 
@@ -432,7 +432,7 @@ this.createjs = this.createjs||{};
 		this._drawHeight = Math.ceil(this.height*this.scale) + filterBounds.height;
 		this._filterCount = this.target.filters && this.target.filters.reduce(BitmapCache.filterCounter, 0);
 
-		if(!surface || this._drawWidth !== surface.width || this._drawHeight !== surface.height) {
+		if (!surface || this._drawWidth !== surface.width || this._drawHeight !== surface.height) {
 			this._updateSurface();
 		}
 
@@ -443,7 +443,7 @@ this.createjs = this.createjs||{};
 				this._stageGL.resizeTexture(this._bufferTextureOutput, this._drawWidth, this._drawHeight);
 			}
 
-			if(this._cacheCanvas === null){
+			if (this._cacheCanvas === null){
 				this._cacheCanvas = this._bufferTextureOutput;
 				this.disabled = this._disabled;
 			}
@@ -515,7 +515,7 @@ this.createjs = this.createjs||{};
 	 * @return {Boolean} Whether the draw was handled successfully.
 	 **/
 	p.draw = function(ctx) {
-		if(!this.target) { return false; }
+		if (!this.target) { return false; }
 		ctx.drawImage(this._cacheCanvas,
 			this.x + (this._filterOffX/this.scale),		this.y + (this._filterOffY/this.scale),
 			this._drawWidth/this.scale,					this._drawHeight/this.scale
@@ -544,7 +544,7 @@ this.createjs = this.createjs||{};
 		if (this.target.filters === null){ return undefined; }
 		var i = 0;
 		var result = this.target.filters[i];
-		while(result && --lookup >= 0) {
+		while (result && --lookup >= 0) {
 			result = result._multiPass ? result._multiPass : this.target.filters[++i];
 		}
 		return result;
@@ -565,7 +565,7 @@ this.createjs = this.createjs||{};
 			surface = this._cacheCanvas;
 
 			// create it if it's missing
-			if(!surface) {
+			if (!surface) {
 				surface = this._cacheCanvas = createjs.createCanvas?createjs.createCanvas():document.createElement("canvas");
 				this.target.cacheCanvas = this._disabled ? null : this._cacheCanvas;
 			}
@@ -581,21 +581,21 @@ this.createjs = this.createjs||{};
 			if (this._options.useGL === "stage") {
 				var targetStage = this.target.stage;
 				// use the stage that this object belongs on as the WebGL context
-				if(!(targetStage && targetStage.isWebGL)){
+				if (!(targetStage && targetStage.isWebGL)){
 					var error = "Cannot use 'stage' for cache because the object's parent stage is ";
 					error += targetStage ? "non WebGL." : "not set, please addChild to the correct stage.";
 					throw error;
 				}
 				this._stageGL = targetStage;
 
-			} else if(this._options.useGL === "new") {
+			} else if (this._options.useGL === "new") {
 				// create a new WebGL context to run this cache
 				this._cacheCanvas = document.createElement("canvas"); // low autopurge in case of filter swapping and low texture count
 				this._stageGL = new createjs.StageGL(this._cacheCanvas, {antialias: true, transparent: true, autoPurge: 10});
-				if(!this._stageGL._webGLContext){ throw "GL Cache asked for but unavailable"; }
+				if (!this._stageGL._webGLContext){ throw "GL Cache asked for but unavailable"; }
 				this._stageGL.isCacheControlled = true;	// use this flag to control stage sizing and final output
 
-			} else if(this._options.useGL instanceof createjs.StageGL) {
+			} else if (this._options.useGL instanceof createjs.StageGL) {
 				// use the provided WebGL context to run this cache, trust the user it works and is configured.
 				this._stageGL = this._options.useGL;
 
@@ -664,14 +664,14 @@ this.createjs = this.createjs||{};
 
 		var i = 0, filter = filters[i];
 		do { // this is safe because we wouldn't be in apply filters without a filter count of at least 1
-			if(filter.usesContext){
-				if(data) {
+			if (filter.usesContext){
+				if (data) {
 					ctx.putImageData(data, 0,0);
 					data = null;
 				}
 				filter.applyFilter(ctx, 0,0, w,h);
 			} else {
-				if(!data) {
+				if (!data) {
 					data = ctx.getImageData(0,0, w,h);
 				}
 				filter._applyFilter(data);
@@ -682,7 +682,7 @@ this.createjs = this.createjs||{};
 		} while (filter);
 
 		//done
-		if(data) {
+		if (data) {
 			ctx.putImageData(data, 0,0);
 		}
 	};

From b5d88e8f52e8c7178ff88eec90b2821153997985 Mon Sep 17 00:00:00 2001
From: David Gillen <david@gskinner.com>
Date: Fri, 16 Mar 2018 13:35:37 -0600
Subject: [PATCH 28/39] Partial implementation of cacheless filters

---
 src/easeljs/display/Container.js     |  2 +-
 src/easeljs/display/DisplayObject.js |  4 ++-
 src/easeljs/display/StageGL.js       | 51 ++++++++++++++++++++++------
 src/easeljs/filters/BitmapCache.js   | 13 +++++--
 4 files changed, 55 insertions(+), 15 deletions(-)

diff --git a/src/easeljs/display/Container.js b/src/easeljs/display/Container.js
index 4810cfb21..092df39e3 100644
--- a/src/easeljs/display/Container.js
+++ b/src/easeljs/display/Container.js
@@ -705,4 +705,4 @@ this.createjs = this.createjs||{};
 
 
 	createjs.Container = createjs.promote(Container, "DisplayObject");
-}());
\ No newline at end of file
+}());
diff --git a/src/easeljs/display/DisplayObject.js b/src/easeljs/display/DisplayObject.js
index 9789fd2b8..9216d7783 100644
--- a/src/easeljs/display/DisplayObject.js
+++ b/src/easeljs/display/DisplayObject.js
@@ -837,6 +837,8 @@ this.createjs = this.createjs||{};
 	p.cache = function(x, y, width, height, scale, options) {
 		if (!this.bitmapCache){
 			this.bitmapCache = new createjs.BitmapCache();
+		} else {
+			this.bitmapCache._autoGenerated = false;
 		}
 		this.bitmapCache.define(this, x, y, width, height, scale, options);
 	};
@@ -1044,7 +1046,7 @@ this.createjs = this.createjs||{};
 			
 			// we do this to avoid problems with the matrix being used for both operations when o._props.matrix is passed in as the props param.
 			// this could be simplified (ie. just done as part of the prepend above) if we switched to using a pool.
-			if (o !== this) { mtx.prependMatrix(o.getMatrix(o._props.matrix)); }
+			if (o != this) { mtx.prependMatrix(o.getMatrix(o._props.matrix)); }
 		} while (o = o.parent);
 		return props;
 	};
diff --git a/src/easeljs/display/StageGL.js b/src/easeljs/display/StageGL.js
index daa45c919..fc516f8bf 100644
--- a/src/easeljs/display/StageGL.js
+++ b/src/easeljs/display/StageGL.js
@@ -1350,6 +1350,10 @@ this.createjs = this.createjs||{};
 			return this.Stage_draw(context, ignoreCache);
 		}
 
+		var storeBatchOutput = this._batchTextureOutput;
+		var storeBatchConcat = this._batchTextureConcat;
+		var storeBatchTemp = this._batchTextureTemp;
+
 		// Use WebGL
 		this._batchVertexCount = 0;
 		this._drawID++;
@@ -1377,6 +1381,10 @@ this.createjs = this.createjs||{};
 		this._bufferTextureConcat = this._batchTextureConcat;
 		this._bufferTextureTemp = this._batchTextureTemp;
 
+		this._batchTextureOutput = storeBatchOutput;
+		this._batchTextureConcat = storeBatchConcat;
+		this._batchTextureTemp = storeBatchTemp;
+
 		if (this._autoPurge !== -1 && !(this._drawID%((this._autoPurge/2)|0))) {
 			this.purgeTextures(this._autoPurge);
 		}
@@ -1400,6 +1408,10 @@ this.createjs = this.createjs||{};
 			return false;
 		}
 
+		var storeBatchOutput = this._batchTextureOutput;
+		var storeBatchConcat = this._batchTextureConcat;
+		var storeBatchTemp = this._batchTextureTemp;
+
 		var filterCount = manager._filterCount, filtersLeft = filterCount;
 		var backupWidth = this._viewportWidth, backupHeight = this._viewportHeight;
 		this.updateViewport(manager._drawWidth, manager._drawHeight);
@@ -1440,6 +1452,10 @@ this.createjs = this.createjs||{};
 		manager._bufferTextureConcat = this._batchTextureConcat;
 		manager._bufferTextureTemp = this._batchTextureTemp;
 
+		this._batchTextureOutput = storeBatchOutput;
+		this._batchTextureConcat = storeBatchConcat;
+		this._batchTextureTemp = storeBatchTemp;
+
 		this.updateViewport(backupWidth, backupHeight);
 		return true;
 	};
@@ -2514,22 +2530,37 @@ this.createjs = this.createjs||{};
 			var item = container.children[i];
 			var useCache = item.cacheCanvas && !ignoreCache;
 
-			if (item.compositeOperation !== null) {
-				this._updateRenderMode(item.compositeOperation);
+			if (!(item.visible && concatAlpha > 0.0035)) { continue; }
+
+			if (!useCache && item._updateState){
+				item._updateState();
 			}
 
-			if (!(item.visible && concatAlpha > 0.0035)) { continue; }
-			if (!useCache) {
-				// TODO: DHG: cacheless filters
-				if (item._updateState){
-					item._updateState();
+			if(!ignoreCache && item.filters !== null && item.filters.length) {
+				var bounds;
+				if (!item.bitmapCache) {
+					bounds = item.getBounds();
+					item.bitmapCache = new createjs.BitmapCache();
+					item.bitmapCache._autoGenerated = true;
 				}
-				if (item.children) {
-					this._appendToBatch(item, cMtx, item.alpha * concatAlpha);
-					continue;
+				if (item.bitmapCache._autoGenerated) {
+					this.batchReason = "cachelessFilterInterupt";
+					this._renderBatch();					// <----------------------------------------------------
+					bounds = bounds || item.getBounds();
+					item.bitmapCache.define(item, bounds.x, bounds.y, bounds.width, bounds.height, 1, {useGL:this});
+					useCache = true;
 				}
 			}
 
+			if (!useCache && item.children) {
+				this._appendToBatch(item, cMtx, item.alpha * concatAlpha);
+				continue;
+			}
+
+			if (item.compositeOperation !== null) {
+				this._updateRenderMode(item.compositeOperation);
+			}
+
 			// check for overflowing batch, if yes then force a render
 			// TODO: DHG: consider making this polygon count dependant for things like vector draws
 			if (this._batchVertexCount+StageGL.INDICIES_PER_CARD > this._maxBatchVertexCount) {
diff --git a/src/easeljs/filters/BitmapCache.js b/src/easeljs/filters/BitmapCache.js
index efd9aae1b..7b4cba0da 100644
--- a/src/easeljs/filters/BitmapCache.js
+++ b/src/easeljs/filters/BitmapCache.js
@@ -172,6 +172,13 @@ this.createjs = this.createjs||{};
 		 */
 		this._disabled = false;
 
+		/**
+		 * Internal tracking of whether this cache was automatically created and thus automatically controlled
+		 * @type {boolean}
+		 * @protected
+		 */
+		this._autoGenerated = false;
+
 		/**
 		 * Internal tracking of intended cacheCanvas, may or may not be assigned based on disabled state.
 		 * @property _cacheCanvas
@@ -273,7 +280,7 @@ this.createjs = this.createjs||{};
 	p._set_disabled = function (value) {
 		this._disabled = !!value;
 		if (this.target) {
-			this.target.cacheCanvas = this._disabled ? null : this._cacheCanvas;
+			this.target.cacheCanvas = (this._disabled || this._autoGenerated) ? null : this._cacheCanvas;
 		}
 	};
 
@@ -567,7 +574,7 @@ this.createjs = this.createjs||{};
 			// create it if it's missing
 			if (!surface) {
 				surface = this._cacheCanvas = createjs.createCanvas?createjs.createCanvas():document.createElement("canvas");
-				this.target.cacheCanvas = this._disabled ? null : this._cacheCanvas;
+				this.disabled = this._disabled;
 			}
 
 			// now size it
@@ -604,7 +611,7 @@ this.createjs = this.createjs||{};
 			}
 		}
 
-		this.target.cacheCanvas = this._disabled ? null : this._cacheCanvas;
+		this.disabled = this._disabled;
 
 		// if we have a dedicated stage we've got to size it
 		var stageGL = this._stageGL;

From e16209779e719445b285230e4f706215ebe03ddf Mon Sep 17 00:00:00 2001
From: David Gillen <david@gskinner.com>
Date: Mon, 19 Mar 2018 13:52:54 -0600
Subject: [PATCH 29/39] Incomplete cacheless filter support, minor other cache
 bugs as result

---
 src/easeljs/display/StageGL.js | 64 ++++++++++++++++++----------------
 1 file changed, 34 insertions(+), 30 deletions(-)

diff --git a/src/easeljs/display/StageGL.js b/src/easeljs/display/StageGL.js
index fc516f8bf..7a25212b9 100644
--- a/src/easeljs/display/StageGL.js
+++ b/src/easeljs/display/StageGL.js
@@ -1428,7 +1428,7 @@ this.createjs = this.createjs||{};
 		this._drawContent(container, true);
 
 		// re-align buffers with fake filter passes to solve certain error cases
-		if (out !== this._batchTextureOutput) {
+		if (out !== ((manager._filterCount%2) ? this._batchTextureConcat : this._batchTextureOutput)) {
 			// pre filter pass to align output, may of become misaligned due to composite operations
 			filtersLeft++;
 		}
@@ -2528,31 +2528,33 @@ this.createjs = this.createjs||{};
 		var l = container.children.length;
 		for (var i = 0; i < l; i++) {
 			var item = container.children[i];
-			var useCache = item.cacheCanvas && !ignoreCache;
+			var useCache = (!ignoreCache && item.cacheCanvas) || false;
 
 			if (!(item.visible && concatAlpha > 0.0035)) { continue; }
 
-			if (!useCache && item._updateState){
-				item._updateState();
-			}
-
-			if(!ignoreCache && item.filters !== null && item.filters.length) {
-				var bounds;
-				if (!item.bitmapCache) {
-					bounds = item.getBounds();
-					item.bitmapCache = new createjs.BitmapCache();
-					item.bitmapCache._autoGenerated = true;
+			if (useCache === false) {
+				if (item._updateState){
+					item._updateState();
 				}
-				if (item.bitmapCache._autoGenerated) {
-					this.batchReason = "cachelessFilterInterupt";
-					this._renderBatch();					// <----------------------------------------------------
-					bounds = bounds || item.getBounds();
-					item.bitmapCache.define(item, bounds.x, bounds.y, bounds.width, bounds.height, 1, {useGL:this});
-					useCache = true;
+
+				if(!ignoreCache && item.filters !== null && item.filters.length) {
+					var bounds;
+					if (item.bitmapCache === null) {
+						bounds = item.getBounds();
+						item.bitmapCache = new createjs.BitmapCache();
+						item.bitmapCache._autoGenerated = true;
+					}
+					if (item.bitmapCache._autoGenerated) {
+						this.batchReason = "cachelessFilterInterupt";
+						this._renderBatch();					// <----------------------------------------------------
+						bounds = bounds || item.getBounds();
+						item.bitmapCache.define(item, bounds.x, bounds.y, bounds.width, bounds.height, 1, {useGL:this});
+						useCache = item.bitmapCache._cacheCanvas;
+					}
 				}
 			}
 
-			if (!useCache && item.children) {
+			if (useCache === false && item.children) {
 				this._appendToBatch(item, cMtx, item.alpha * concatAlpha);
 				continue;
 			}
@@ -2562,8 +2564,7 @@ this.createjs = this.createjs||{};
 			}
 
 			// check for overflowing batch, if yes then force a render
-			// TODO: DHG: consider making this polygon count dependant for things like vector draws
-			if (this._batchVertexCount+StageGL.INDICIES_PER_CARD > this._maxBatchVertexCount) {
+			if (this._batchVertexCount + StageGL.INDICIES_PER_CARD > this._maxBatchVertexCount) {
 				this.batchReason = "vertexOverflow";
 				this._renderBatch();					// <------------------------------------------------------------
 			}
@@ -2586,8 +2587,8 @@ this.createjs = this.createjs||{};
 
 			// get the image data, or abort if not present
 			// BITMAP / Cached Canvas
-			if (item._webGLRenderStyle === 2 || useCache) {
-				image = (ignoreCache?false:item.cacheCanvas) || item.image;
+			if (item._webGLRenderStyle === 2 || useCache !== false) {
+				image = useCache === false ? item.image : useCache;
 
 			// SPRITE
 			} else if (item._webGLRenderStyle === 1) {
@@ -2627,8 +2628,9 @@ this.createjs = this.createjs||{};
 			texIndex = texture._activeIndex;
 			image._drawID = this._drawID;
 
-			if (item._webGLRenderStyle === 2 || useCache) {			// BITMAP / Cached Canvas
-				if (!useCache && item.sourceRect) {
+			// BITMAP / Cached Canvas
+			if (item._webGLRenderStyle === 2 || useCache !== false) {
+				if (useCache === false && item.sourceRect) {
 					// calculate uvs
 					if (!item._uvRect) { item._uvRect = {}; }
 					src = item.sourceRect;
@@ -2645,16 +2647,18 @@ this.createjs = this.createjs||{};
 					// calculate uvs
 					uvRect = StageGL.UV_RECT;
 					// calculate vertices
-					if (useCache) {
+					if (useCache === false) {
+						subL = 0;						subT = 0;
+						subR = image.width+subL;		subB = image.height+subT;
+					} else {
 						src = item.bitmapCache;
 						subL = src.x+(src._filterOffX/src.scale);	subT = src.y+(src._filterOffY/src.scale);
 						subR = (src._drawWidth/src.scale)+subL;		subB = (src._drawHeight/src.scale)+subT;
-					} else {
-						subL = 0;						subT = 0;
-						subR = image.width+subL;		subB = image.height+subT;
 					}
 				}
-			} else if (item._webGLRenderStyle === 1) {											// SPRITE
+
+			// SPRITE
+			} else if (item._webGLRenderStyle === 1) {
 				var rect = frame.rect;
 
 				// calculate uvs

From 3e07749d35ffe28308aff1637c6bd1f0130b832c Mon Sep 17 00:00:00 2001
From: David Gillen <david@gskinner.com>
Date: Wed, 21 Mar 2018 15:42:03 -0600
Subject: [PATCH 30/39] Fix issues with composite operations in a cache

---
 src/easeljs/display/StageGL.js     | 38 +++++++++++++++++++-----------
 src/easeljs/filters/BitmapCache.js |  2 +-
 2 files changed, 25 insertions(+), 15 deletions(-)

diff --git a/src/easeljs/display/StageGL.js b/src/easeljs/display/StageGL.js
index 7a25212b9..4d3682586 100644
--- a/src/easeljs/display/StageGL.js
+++ b/src/easeljs/display/StageGL.js
@@ -1271,6 +1271,7 @@ this.createjs = this.createjs||{};
 				if (!gl) { return null; }
 
 				gl.disable(gl.DEPTH_TEST);
+				gl.depthMask(false);
 				gl.enable(gl.BLEND);
 				gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true);
 				gl.clearColor(0.0, 0.0, 0.0, 0);
@@ -1416,7 +1417,7 @@ this.createjs = this.createjs||{};
 		var backupWidth = this._viewportWidth, backupHeight = this._viewportHeight;
 		this.updateViewport(manager._drawWidth, manager._drawHeight);
 
-		var out = this._batchTextureOutput = (manager._filterCount%2) ? manager._bufferTextureConcat : manager._bufferTextureOutput;
+		this._batchTextureOutput = (manager._filterCount%2) ? manager._bufferTextureConcat : manager._bufferTextureOutput;
 		this._batchTextureConcat = (manager._filterCount%2) ? manager._bufferTextureOutput : manager._bufferTextureConcat;
 		this._batchTextureTemp = manager._bufferTextureTemp;
 
@@ -1428,7 +1429,7 @@ this.createjs = this.createjs||{};
 		this._drawContent(container, true);
 
 		// re-align buffers with fake filter passes to solve certain error cases
-		if (out !== ((manager._filterCount%2) ? this._batchTextureConcat : this._batchTextureOutput)) {
+		if (manager._cacheCanvas !== ((manager._filterCount%2) ? this._batchTextureConcat : this._batchTextureOutput)) {
 			// pre filter pass to align output, may of become misaligned due to composite operations
 			filtersLeft++;
 		}
@@ -1951,10 +1952,10 @@ this.createjs = this.createjs||{};
 			for (var i = 0; i < this._gpuTextureCount; i++) {
 				samplers[i] = i;
 			}
-
 			shaderProgram.samplerData = samplers;
+
 			shaderProgram.samplerUniform = gl.getUniformLocation(shaderProgram, "uSampler");
-			gl.uniform1iv(shaderProgram.samplerUniform, samplers);
+			gl.uniform1iv(shaderProgram.samplerUniform, shaderProgram.samplerData);
 
 			shaderProgram.pMatrixUniform = gl.getUniformLocation(shaderProgram, "pMatrix");
 		}
@@ -2270,9 +2271,10 @@ this.createjs = this.createjs||{};
 			if (image && ((image._invalid === undefined && image._isCanvas) || image._invalid)) {
 				this._updateTextureImageData(gl, image);
 			} else {
-				gl.activeTexture(gl.TEXTURE0 + found);
-				gl.bindTexture(gl.TEXTURE_2D, texture);
-				this.setTextureParams(gl);
+				// probably redundant, confirm functionality then remove from codebase
+				//gl.activeTexture(gl.TEXTURE0 + found);
+				//gl.bindTexture(gl.TEXTURE_2D, texture);
+				//this.setTextureParams(gl);
 			}
 			this._lastTextureInsert = found;
 
@@ -2537,7 +2539,7 @@ this.createjs = this.createjs||{};
 					item._updateState();
 				}
 
-				if(!ignoreCache && item.filters !== null && item.filters.length) {
+				if(!ignoreCache && item.cacheCanvas === null && item.filters !== null && item.filters.length) {
 					var bounds;
 					if (item.bitmapCache === null) {
 						bounds = item.getBounds();
@@ -2547,9 +2549,14 @@ this.createjs = this.createjs||{};
 					if (item.bitmapCache._autoGenerated) {
 						this.batchReason = "cachelessFilterInterupt";
 						this._renderBatch();					// <----------------------------------------------------
+
+						var shaderBackup = this._activeShader;
 						bounds = bounds || item.getBounds();
 						item.bitmapCache.define(item, bounds.x, bounds.y, bounds.width, bounds.height, 1, {useGL:this});
 						useCache = item.bitmapCache._cacheCanvas;
+
+						this._activeShader = shaderBackup;
+						gl.bindFramebuffer(gl.FRAMEBUFFER, this._batchTextureOutput._frameBuffer);
 					}
 				}
 			}
@@ -2702,7 +2709,7 @@ this.createjs = this.createjs||{};
 			this._batchVertexCount += StageGL.INDICIES_PER_CARD;
 
 			if (this._immediateRender) {
-				this._immediateBatchRender(gl);
+				this._immediateBatchRender();
 			}
 		}
 
@@ -2713,9 +2720,12 @@ this.createjs = this.createjs||{};
 
 	/**
 	 * The shader or effect needs to be drawn immediately, sub function of `_appendToBatch`
+	 * @method _immediateBatchRender
 	 * @protected
 	 */
-	p._immediateBatchRender = function(gl) {
+	p._immediateBatchRender = function() {
+		var gl = this._webGLContext;
+
 		if (this._batchTextureConcat === null){
 			this._batchTextureConcat = this.getRenderBufferTexture(this._viewportWidth, this._viewportHeight);
 		} else {
@@ -2737,10 +2747,10 @@ this.createjs = this.createjs||{};
 		this._batchTextureConcat = swap;
 
 		this._activeShader = this._mainShader;
-		this.batchReason = "immediateBuffer";
+		this.batchReason = "immediatePrep";
 		this._renderBatch();//<-----------------------------------------------------------------------------------------
 
-		this.batchReason = "immediateDraw";
+		this.batchReason = "immediateResults";
 		this._drawCover(this._batchTextureOutput._frameBuffer, this._batchTextureConcat, this._batchTextureTemp);
 
 		gl.bindFramebuffer(gl.FRAMEBUFFER, this._batchTextureOutput._frameBuffer);
@@ -2756,7 +2766,7 @@ this.createjs = this.createjs||{};
 		var gl = this._webGLContext;
 
 		if (this.vocalDebug) {
-			console.log("Draw["+ this._drawID +":"+ this._batchID +"] : "+ this.batchReason);
+			console.log("Batch["+ this._drawID +":"+ this._batchID +"] : "+ this.batchReason);
 		}
 		var shaderProgram = this._activeShader;
 		var vertexPositionBuffer = this._vertexPositionBuffer;
@@ -2824,7 +2834,7 @@ this.createjs = this.createjs||{};
 		gl.uniform1i(shaderProgram.samplerUniform, 0);
 
 		gl.drawArrays(gl.TRIANGLES, 0, StageGL.INDICIES_PER_CARD);
-		this._batchID++;
+		this._batchID++; // while this isn't a batch, this fixes issues with expected textures in expected places
 	};
 
 	createjs.StageGL = createjs.promote(StageGL, "Stage");
diff --git a/src/easeljs/filters/BitmapCache.js b/src/easeljs/filters/BitmapCache.js
index 7b4cba0da..d72f3a64f 100644
--- a/src/easeljs/filters/BitmapCache.js
+++ b/src/easeljs/filters/BitmapCache.js
@@ -548,7 +548,7 @@ this.createjs = this.createjs||{};
 	 * @param {Number} lookup The filter in the list to return
 	 */
 	p._getGLFilter = function(lookup) {
-		if (this.target.filters === null){ return undefined; }
+		if (this.target.filters === null || lookup < 0){ return undefined; }
 		var i = 0;
 		var result = this.target.filters[i];
 		while (result && --lookup >= 0) {

From ee2f616307b1b61d7a5c84875cbb7c07488c73a8 Mon Sep 17 00:00:00 2001
From: David Gillen <david@gskinner.com>
Date: Wed, 21 Mar 2018 15:43:34 -0600
Subject: [PATCH 31/39] Update and improve debugging tools for StageGL ->
 WebGLInspector

---
 src/easeljs/display/StageGL.js      |   4 +
 src/easeljs/utils/WebGLInspector.js | 269 +++++++++++++++++++---------
 2 files changed, 187 insertions(+), 86 deletions(-)

diff --git a/src/easeljs/display/StageGL.js b/src/easeljs/display/StageGL.js
index 4d3682586..19b5e3a74 100644
--- a/src/easeljs/display/StageGL.js
+++ b/src/easeljs/display/StageGL.js
@@ -1960,6 +1960,8 @@ this.createjs = this.createjs||{};
 			shaderProgram.pMatrixUniform = gl.getUniformLocation(shaderProgram, "pMatrix");
 		}
 
+		shaderProgram._type = coverShader ? "cover" : "batch";
+
 		gl.useProgram(this._activeShader);
 		return shaderProgram;
 	};
@@ -2117,6 +2119,7 @@ this.createjs = this.createjs||{};
 		}
 
 		this._mainShader = this._activeShader;
+		this._mainShader._name = "main";
 
 		// fill in blanks as it helps the renderer be stable while textures are loading and reduces need for safety code
 		var texture = this.getBaseTexture();
@@ -2387,6 +2390,7 @@ this.createjs = this.createjs||{};
 							this._setCoverMixShaderParams
 						) : this._builtShaders["source-over"].shader // re-use source-over when we don't need a new shader
 				};
+				if (blendSrc.shader) { shaderData.shader._name = newMode; }
 			} catch (e) {
 				this._builtShaders[newMode] = undefined;
 				console && console.log("SHADER SWITCH FAILURE", e);
diff --git a/src/easeljs/utils/WebGLInspector.js b/src/easeljs/utils/WebGLInspector.js
index 60c42e85c..09ae74c2f 100644
--- a/src/easeljs/utils/WebGLInspector.js
+++ b/src/easeljs/utils/WebGLInspector.js
@@ -43,26 +43,10 @@ this.createjs = this.createjs||{};
 	 * @constructor
 	 * @param {StageGL} stage The default stage to use when none is supplied.
 	 */
-	function WebGLInspector(stage) {
-		this.EventDispatcher_constructor();
-
-	// public properties:
-
-	// private properties:
-		/**
-		 * The internal reference to the default stage this Inspector is for.
-		 * @property _stage
-		 * @protected
-		 * @type {StageGL}
-		 */
-		this._stage = stage;
-
-		// and begin
-		this._initializeWebGLInspector();
-	}
+	function WebGLInspector(stage) {}
 	var p = createjs.extend(WebGLInspector, createjs.EventDispatcher);
 
-// static:
+// properties:
 	/**
 	 * Alternate output for debugging situations where "console" is not available, i.e. Mobile or remote debugging.
 	 * Expects object with a "log" function that takes any number of params.
@@ -72,84 +56,101 @@ this.createjs = this.createjs||{};
 	 * @static
 	 * @protected
 	 */
-	p.alternateOutput = undefined;
+	WebGLInspector.alternateOutput = undefined;
 
-// getter / setters:
-
-// ctor:
 	/**
-	 * @method _initializeWebGL
-	 * @protected
+	 * Default stage to assume when non provided
+	 * @type {StageGL}
+	 * @private
 	 */
-	p._initializeWebGLInspector = function() {};
+	WebGLInspector.stage = undefined;
 
 // public methods:
+	/**
+	 * Utility to call the right logging
+	 * @params *
+	 */
+	WebGLInspector.log = function() {
+		(WebGLInspector.alternateOutput ? WebGLInspector.alternateOutput.log : console.log).apply(this, arguments);
+	};
+
 	/**
 	 * Perform all of the logging reports at once.
 	 * @method log
-	 * @param {StageGL} [stage=this._stage] The stage to log information for.
+	 * @param {StageGL} [stage=WebGLInspector.stage] The stage to log information for.
 	 */
-	p.log = function(stage) {
-		if(!stage){ stage = this._stage; }
+	WebGLInspector.logAll = function(stage) {
+		if (!stage){ stage = WebGLInspector.stage; }
 
-		console.log("Batches Per Draw", (stage._batchID/stage._drawID).toFixed(4));
-		this.logContextInfo(stage._webGLContext);
-		this.logDepth(stage.children, "");
-		this.logTextureFill(stage);
+		WebGLInspector.log("Batches Per Draw", (stage._batchID/stage._drawID).toFixed(4));
+		WebGLInspector.logContextInfo(stage._webGLContext);
+		WebGLInspector.logDepth(stage.children, "");
+		WebGLInspector.logTextureFill(stage);
 	};
 
 	/**
-	 * Replace the stage's Draw command with an empty draw command. This is useful for testing performance, and ignoring
-	 * rendering.
-	 * @method toggleGPUDraw
-	 * @param {StageGL} [stage=this._stage] The stage to log information for.
-	 * @param {Boolean} enabled Force enabled. If left undefined, it will toggle.
+	 * Replace the stage's Draw command with a new draw command. This is useful for:
+	 * <ul>
+	 *     <li> Testing performance, with no render cost. See `WebGLInspector.drawEmpty` </li>
+	 *     <li> Troubleshooting and tracking loaded textures. See `WebGLInspector.drawTexOnBuffer` </li>
+	 *     <li> Misc feature or troubleshooting injection </li>
+	 * </ul>
+	 * @method replaceRenderBatchCall
+	 * @param {StageGL} [stage=WebGLInspector.stage] The stage to log information for.
+	 * @param {Function} newFunc .
 	 */
-	p.toggleGPUDraw = function(stage, enabled) {
-		if(!stage){ stage = this._stage; }
+	WebGLInspector.replaceRenderBatchCall = function(stage, newFunc) {
+		if (!stage){ stage = WebGLInspector.stage; }
 
-		if(enabled === undefined) {
-			enabled = !!stage._drawBuffers_;
+		if (newFunc === undefined && stage._renderBatch_) {
+			stage._renderBatch = stage._renderBatch_;
+			stage._renderBatch_ = undefined;
+		} else {
+			if (stage._renderBatch_ === undefined) {
+				stage._renderBatch_ = stage._renderBatch;
+			}
+			stage._renderBatch = newFunc;
 		}
+	};
 
-		if(enabled) {
-			if(stage._drawBuffers_) {
-				stage._drawBuffers = stage._drawBuffers_;
-				stage._drawBuffers_ = undefined;
-			}
+	/**
+	 * Identical to replaceRenderBatchCall, but affects the Cover command.
+	 * @method replaceRenderCoverCall
+	 * @param {StageGL} [stage=WebGLInspector.stage] The stage to log information for.
+	 * @param {Function} newFunc .
+	 */
+	WebGLInspector.replaceRenderCoverCall = function(stage, newFunc) {
+		if (!stage){ stage = WebGLInspector.stage; }
+
+		if (newFunc === undefined && stage._renderCover_) {
+			stage._renderCover = stage._renderCover_;
+			stage._renderCover_ = undefined;
 		} else {
-			stage._drawBuffers_ = stage._drawBuffers;
-			stage._drawBuffers = function(gl) {
-				if(this.vocalDebug) {
-					var output = "BlankDraw["+ this._drawID +":"+ this._batchID +"] : "+ this.batchReason;
-					this.alternateOutput?this.alternateOutput.log(output):console.log(output);
-				}
-			};
+			if (stage._renderCover_ === undefined) {
+				stage._renderCover_ = stage._renderCover;
+			}
+			stage._renderCover = newFunc;
 		}
 	};
 
 	/**
 	 * Recursively walk the entire display tree, log the attached items, and display it in a tree view.
 	 * @method logDepth
-	 * @param {Array} [children=this._stage.children] The children array to walk through.
+	 * @param {Array} [children=WebGLInspector.stage.children] The children array to walk through.
 	 * @param {String} prepend What to prepend to this output from this point onwards.
 	 * @param {Function} customLog Which logging function to use, mainly for filtering or formatting output.
 	 * Fallback hierarchy is customLog -> alternateOutput -> console.log.
 	 */
-	p.logDepth = function(children, prepend, customLog) {
-		if(!children){ children = this._stage.children; }
-		if(!prepend){ prepend = ""; }
+	WebGLInspector.logDepth = function(children, prepend, customLog) {
+		if (!children){ children = WebGLInspector.stage.children; }
+		if (!prepend){ prepend = ""; }
 
 		var l = children.length;
-		for(var i=0; i<l; i++) {
+		for (var i=0; i<l; i++) {
 			var child = children[i];
-			if(customLog !== undefined){
-				customLog(prepend+"-", child);
-			} else {
-				this.alternateOutput?this.alternateOutput.log(prepend+"-", child):console.log(prepend+"-", child);
-			}
-			if(child.children && child.children.length) {
-				p.logDepth(child.children, "|"+prepend, customLog);
+			(customLog !== undefined ? customLog : WebGLInspector.log)(prepend+"-", child);
+			if (child.children && child.children.length) {
+				WebGLInspector.logDepth(child.children, "|"+prepend, customLog);
 			}
 		}
 	};
@@ -159,8 +160,8 @@ this.createjs = this.createjs||{};
 	 * @method logContextInfo
 	 * @param {WebGLRenderingContext} gl The WebGL context to inspect.
 	 */
-	p.logContextInfo = function(gl) {
-		if(!gl) { gl = this._stage._webGLContext; }
+	WebGLInspector.logContextInfo = function(gl) {
+		if (!gl) { gl = WebGLInspector.stage._webGLContext; }
 		var data = "== LOG:\n";
 		data += "Max textures per draw: " + gl.getParameter(gl.MAX_TEXTURE_IMAGE_UNITS) +"\n";
 		data += "Max textures active: " + gl.getParameter(gl.MAX_COMBINED_TEXTURE_IMAGE_UNITS) +"\n";
@@ -171,50 +172,48 @@ this.createjs = this.createjs||{};
 		data += "Max attributes per vertex: " + gl.getParameter(gl.MAX_VERTEX_ATTRIBS) +"\n";
 		data += "WebGL Version string: " + gl.getParameter(gl.VERSION) +"\n";
 		data += "======";
-		this.alternateOutput?this.alternateOutput.log(data):console.log(data);
+		WebGLInspector.log(data);
 	};
 
 	/**
 	 * Simulate renders and watch what happens for textures moving around between draw calls. A texture moving between
 	 * slots means it was removed and then re-added to draw calls. Performance may be better if it was allowed to stay
-	 * in place.
+	 * on GPU, consider sprite sheeting it with something stable.
 	 * @method logTextureFill
-	 * @param {StageGL} [stage=this._stage] The stage to log information for.
+	 * @param {StageGL} [stage=WebGLInspector.stage] The stage to log information for.
 	 */
-	p.logTextureFill = function(stage) {
-		if(!stage){ stage = this._stage; }
+	WebGLInspector.logTextureFill = function(stage) {
+		if (!stage){ stage = WebGLInspector.stage; }
 
 		var dict = stage._textureDictionary;
 		var count = stage._batchTextureCount;
-		console.log("textureMax:", count);
+		WebGLInspector.log("textureMax:", count);
 		var output = [];
-		for(var n in dict) {
+		for (var n in dict) {
 			var str = n.replace(window.location.origin, "");
 			var tex = dict[n];
-			var shifted = tex._lastActiveInde?tex._lastActiveIndex == tex._activeIndex:false;
+			var shifted = tex._lastActiveIndex?tex._lastActiveIndex === tex._activeIndex:false;
 			output.push({src:str, element:tex, shifted:shifted});
 			tex._lastActiveIndex = tex._activeIndex;
 		}
 
 		output.sort(function(a,b){
-			if (a.element._drawID == stage._drawID) { return 1; }
+			if (a.element._drawID === stage._drawID) { return 1; }
 			if (a.element._drawID < b.element._drawID) { return -1; }
 			return 0;
 		});
 
 		var l = output.length;
-		for(var i = 0; i<l; i++) {
+		for (var i = 0; i<l; i++) {
 			var out = output[i];
-			var active = out.element._drawID == stage._drawID;
-			var output = "["+out.src+"] "+ (active?"ACTIVE":"stale") +" "+ (out.shifted?"steady":"DRIFT");
-			this.alternateOutput?this.alternateOutput.log(output, out.element):console.log(output, out.element);
+			var active = out.element._drawID === stage._drawID;
+			WebGLInspector.log("["+out.src+"] "+ (active?"ACTIVE":"stale") +" "+ (out.shifted?"steady":"DRIFT"), out.element);
 		}
 	};
 
-
 // protected methods:
 
-// static methods:
+// utility methods:
 	/**
 	 * Utility function for use with {{#crossLink "logDepth"))((/crossLink}}. Logs an item's position and registration.
 	 * Useful to see if something is being forced off screen or has an integer position.
@@ -224,16 +223,114 @@ this.createjs = this.createjs||{};
 	 * @static
 	 */
 	WebGLInspector.dispProps = function(prepend, item){
-		if(!prepend){ prepend = ""; }
+		if (!prepend){ prepend = ""; }
 
 		var p = "\tP:"+ item.x.toFixed(2)+"x"+item.y.toFixed(2) +"\t";
 		var r = "\tR:"+ item.regX.toFixed(2)+"x"+item.regY.toFixed(2) +"\t";
 
-		if(!this.alternateOutput) {
-			console.log(prepend, item.toString()+"\t", p,r);
+		WebGLInspector.log(prepend, item.toString()+"\t", p,r);
+	};
+
+	/**
+	 * Utility function for use with {{#crossLink "replaceRenderBatchCall"))((/crossLink}}.
+	 * Performs no GL draw command.
+	 */
+	WebGLInspector.drawEmptyBatch = function() {
+		WebGLInspector.log("BlankBatch["+ this._drawID +":"+ this._batchID +"] : "+ this.batchReason);
+		this._batchVertexCount = 0;
+		this._batchID++;
+	};
+
+	/**
+	 * Utility function for use with {{#crossLink "replaceRenderCoverCall"))((/crossLink}}.
+	 * Performs no GL draw command.
+	 */
+	WebGLInspector.drawEmptyCover = function() {
+		WebGLInspector.log("BlankCover["+ this._drawID +":"+ this._batchID +"] : "+ this.batchReason);
+		this._batchID++;
+	};
+
+	/**
+	 * Utility function for use with {{#crossLink "replaceRenderBatchCall"))((/crossLink}}.
+	 */
+	WebGLInspector.drawTexBuffer = function() {
+		var gl = this._webGLContext;
+		var texSize = 2048;
+
+		// backup
+		var batchVertexCount = this._batchVertexCount;
+		var projectionMatrix = this._projectionMatrix;
+		var shader = this._activeShader;
+		var vertices = this._vertices;
+		var indices = this._indices;
+		var uvs = this._uvs;
+		var alphas = this._alphas;
+		var reason = this.batchReason;
+
+		// create
+		if (this._inspectorFrame === undefined) {
+			this._inspectorFrame = this.getRenderBufferTexture(texSize, texSize);
 		} else {
-			this.alternateOutput.log(prepend, item.toString()+"\t", p,r);
+			gl.bindFramebuffer(gl.FRAMEBUFFER, this._inspectorFrame._frameBuffer);
+			gl.clear(gl.COLOR_BUFFER_BIT);
 		}
+
+		// configure
+		this._activeShader = this._mainShader;
+		gl.blendEquationSeparate(gl.FUNC_ADD, gl.FUNC_ADD);
+		gl.blendFuncSeparate(gl.ONE, gl.ONE_MINUS_SRC_ALPHA, gl.ONE, gl.ONE_MINUS_SRC_ALPHA);
+		gl.viewport(0, 0, texSize, texSize);
+
+		this._projectionMatrix = new Float32Array([2/texSize, 0, 0, 0, 0, -2/texSize, 0, 0, 0, 0, 1, 0, -1, 1, 0, 1]);
+		this._vertices = new Float32Array(this._batchTextureCount * 2 * createjs.StageGL.INDICIES_PER_CARD);
+		this._indices = new Float32Array(this._batchTextureCount * 1 * createjs.StageGL.INDICIES_PER_CARD);
+		this._uvs = new Float32Array(this._batchTextureCount * 2 * createjs.StageGL.INDICIES_PER_CARD);
+		this._alphas = new Float32Array(this._batchTextureCount * 1 * createjs.StageGL.INDICIES_PER_CARD);
+		this.batchReason = "LoadedTextureDebug";
+
+		var squareBase = Math.ceil(Math.sqrt(this._batchTextureCount));
+		for(var i=0; i<this._batchTextureCount; i++) {
+			var i1 = i*6, i2 = i1*2;
+			var row = i % squareBase, col = Math.floor(i / squareBase), size = (1/squareBase) * texSize;
+			this._vertices[i2] =	(row)*size;					this._vertices[i2+1] =	(col)*size;
+			this._vertices[i2+2] =	(row)*size;					this._vertices[i2+3] =	(col+1)*size;
+			this._vertices[i2+4] =	(row+1)*size;				this._vertices[i2+5] =	(col)*size;
+			this._vertices[i2+6] =	this._vertices[i2+2];		this._vertices[i2+7] =	this._vertices[i2+3];
+			this._vertices[i2+8] =	this._vertices[i2+4];		this._vertices[i2+9] =	this._vertices[i2+5];
+			this._vertices[i2+10] =	(row+1)*size;				this._vertices[i2+11] =	(col+1)*size;
+			this._uvs[i2] =		0;			this._uvs[i2+1] =	1;
+			this._uvs[i2+2] =	0;			this._uvs[i2+3] =	0;
+			this._uvs[i2+4] =	1;			this._uvs[i2+5] =	1;
+			this._uvs[i2+6] =	0;			this._uvs[i2+7] =	0;
+			this._uvs[i2+8] =	1;			this._uvs[i2+9] =	1;
+			this._uvs[i2+10] =	1;			this._uvs[i2+11] =	0;
+			this._indices[i1] = this._indices[i1+1] = this._indices[i1+2] = this._indices[i1+3] = this._indices[i1+4] = this._indices[i1+5] = i;
+			this._alphas[i1] = this._alphas[i1+1] = this._alphas[i1+2] = this._alphas[i1+3] = this._alphas[i1+4] = this._alphas[i1+5] = 1;
+		}
+
+		// output
+		this._batchVertexCount = this._batchTextureCount * createjs.StageGL.INDICIES_PER_CARD;
+		this._renderBatch_();
+		this._batchID--;
+
+		// reset and perform
+		gl.bindFramebuffer(gl.FRAMEBUFFER, this._batchTextureOutput._frameBuffer);
+
+		var shaderData = this._builtShaders[this._renderMode];
+		gl.blendEquationSeparate(shaderData.eqRGB, shaderData.eqA);
+		gl.blendFuncSeparate(shaderData.srcRGB, shaderData.dstRGB, shaderData.srcA, shaderData.dstA);
+		gl.viewport(0, 0, this._viewportWidth, this._viewportHeight);
+
+		this._activeShader = shader;
+		this._batchVertexCount = batchVertexCount;
+		this._projectionMatrix = projectionMatrix;
+		this._vertices = vertices;
+		this._indices = indices;
+		this._uvs = uvs;
+		this._alphas = alphas;
+		this.batchReason = reason;
+
+		this._renderBatch_();
 	};
 
 	createjs.WebGLInspector = createjs.promote(WebGLInspector, "EventDispatcher");

From e913f2c0fe84d49e241be3e44c44b8defe5a3ce2 Mon Sep 17 00:00:00 2001
From: David Gillen <david@gskinner.com>
Date: Thu, 22 Mar 2018 12:14:50 -0600
Subject: [PATCH 32/39] Fix issue with cacheControlled surfaces

---
 src/easeljs/display/StageGL.js | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/src/easeljs/display/StageGL.js b/src/easeljs/display/StageGL.js
index 19b5e3a74..07c4f8703 100644
--- a/src/easeljs/display/StageGL.js
+++ b/src/easeljs/display/StageGL.js
@@ -1429,15 +1429,14 @@ this.createjs = this.createjs||{};
 		this._drawContent(container, true);
 
 		// re-align buffers with fake filter passes to solve certain error cases
-		if (manager._cacheCanvas !== ((manager._filterCount%2) ? this._batchTextureConcat : this._batchTextureOutput)) {
-			// pre filter pass to align output, may of become misaligned due to composite operations
-			filtersLeft++;
-		}
 		if (this.isCacheControlled) {
 			// post filter pass to place content into output buffer
 			//TODO: add in directDraw support for cache controlled StageGLs
 			filterCount++;
 			filtersLeft++;
+		} else if (manager._cacheCanvas !== ((manager._filterCount%2) ? this._batchTextureConcat : this._batchTextureOutput)) {
+			// pre filter pass to align output, may of become misaligned due to composite operations
+			filtersLeft++;
 		}
 
 		while (filtersLeft) { //warning: pay attention to where filtersLeft is modified, this is a micro-optimization

From cd713ce0de067229bb5d27f1e17322e51a9d4c3b Mon Sep 17 00:00:00 2001
From: David Gillen <david@gskinner.com>
Date: Thu, 22 Mar 2018 12:15:42 -0600
Subject: [PATCH 33/39] Resolve discrepancies in alpha handling between GL
 filters and regular filters and minor bugs

---
 src/easeljs/filters/AberrationFilter.js   | 17 ++++++-----------
 src/easeljs/filters/AlphaMapFilter.js     |  3 ++-
 src/easeljs/filters/AlphaMaskFilter.js    |  2 +-
 src/easeljs/filters/DisplacementFilter.js |  2 +-
 4 files changed, 10 insertions(+), 14 deletions(-)

diff --git a/src/easeljs/filters/AberrationFilter.js b/src/easeljs/filters/AberrationFilter.js
index d1a2ec2c4..2456eab23 100644
--- a/src/easeljs/filters/AberrationFilter.js
+++ b/src/easeljs/filters/AberrationFilter.js
@@ -161,17 +161,12 @@
 				var grnPixel = ((grnY*width)+grnX)*4;
 				var bluPixel = ((bluY*width)+bluX)*4;
 
-				if(this._alphaMax) {
-					outPixels[pixel] =		refPixels[redPixel];
-					outPixels[pixel+1] =	refPixels[grnPixel+1];
-					outPixels[pixel+2] =	refPixels[bluPixel+2];
-					outPixels[pixel+3] =	refPixels[pixel+3];
-				} else {
-					outPixels[pixel] =		refPixels[redPixel];
-					outPixels[pixel+1] =	refPixels[grnPixel+1];
-					outPixels[pixel+2] =	refPixels[bluPixel+2];
-					outPixels[pixel+3] =	refPixels[pixel+3];
-				}
+				outPixels[pixel] =		refPixels[redPixel];
+				outPixels[pixel+1] =	refPixels[grnPixel+1];
+				outPixels[pixel+2] =	refPixels[bluPixel+2];
+				outPixels[pixel+3] =	this._alphaMax ?
+					Math.max(refPixels[redPixel+3], refPixels[grnPixel+3], refPixels[bluPixel+3]) :
+					(refPixels[redPixel+3] + refPixels[grnPixel+3] + refPixels[bluPixel+3]) / 3;
 			}
 		}
 
diff --git a/src/easeljs/filters/AlphaMapFilter.js b/src/easeljs/filters/AlphaMapFilter.js
index a22bbee8c..3048a8f43 100644
--- a/src/easeljs/filters/AlphaMapFilter.js
+++ b/src/easeljs/filters/AlphaMapFilter.js
@@ -108,7 +108,8 @@ this.createjs = this.createjs || {};
 
 				// some image formats can have transparent white rgba(1,1,1, 0) when put on the GPU, this means we need a slight tweak
 				// using ceil ensure that the colour will be used so long as it exists but pure transparency will be treated black
-				"gl_FragColor = vec4(color.rgb, color.a * (alphaMap.r * ceil(alphaMap.a)));" +
+				"float newAlpha = alphaMap.r * ceil(alphaMap.a);" +
+				"gl_FragColor = vec4(clamp(color.rgb/color.a, 0.0, 1.0) * newAlpha, newAlpha);" +
 			"}"
 		);
 
diff --git a/src/easeljs/filters/AlphaMaskFilter.js b/src/easeljs/filters/AlphaMaskFilter.js
index ab0354aa0..3c2719816 100644
--- a/src/easeljs/filters/AlphaMaskFilter.js
+++ b/src/easeljs/filters/AlphaMaskFilter.js
@@ -91,7 +91,7 @@ this.createjs = this.createjs || {};
 				"vec4 color = texture2D(uSampler, vTextureCoord);" +
 				"vec4 alphaMap = texture2D(uAlphaSampler, vTextureCoord);" +
 
-				"gl_FragColor = vec4(color.rgb, color.a * alphaMap.a);" +
+				"gl_FragColor = vec4(color.rgb * alphaMap.a, color.a * alphaMap.a);" +
 			"}"
 		);
 	}
diff --git a/src/easeljs/filters/DisplacementFilter.js b/src/easeljs/filters/DisplacementFilter.js
index 3137ca6f9..f8cb454fe 100644
--- a/src/easeljs/filters/DisplacementFilter.js
+++ b/src/easeljs/filters/DisplacementFilter.js
@@ -116,7 +116,7 @@ this.createjs = this.createjs||{};
 			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);
+			(this._dudvCtx = canvas.getContext("2d")).drawImage(dudvMap, 0,0);
 		}
 	}
 	var p = createjs.extend(DisplacementFilter, createjs.Filter);

From 064034be4f5a61a5c928935fb563e2a95fb0e24c Mon Sep 17 00:00:00 2001
From: David Gillen <david@gskinner.com>
Date: Thu, 22 Mar 2018 15:35:37 -0600
Subject: [PATCH 34/39] Improve alpha handling and fix image stretch logic

---
 src/easeljs/filters/DisplacementFilter.js | 24 ++++++++++-------------
 1 file changed, 10 insertions(+), 14 deletions(-)

diff --git a/src/easeljs/filters/DisplacementFilter.js b/src/easeljs/filters/DisplacementFilter.js
index f8cb454fe..e8e81785e 100644
--- a/src/easeljs/filters/DisplacementFilter.js
+++ b/src/easeljs/filters/DisplacementFilter.js
@@ -96,14 +96,9 @@ this.createjs = this.createjs||{};
 			"uniform vec2 pixelAdjustment;" +
 
 			"void main(void) {" +
-				"vec4 dispSample = texture2D(" +
-					"uDudvSampler, " +
-					"vTextureCoord" +
-				");" +
-				"gl_FragColor = texture2D(" +
-					"uSampler, " +
-					"vTextureCoord + (dispSample.xy-0.5)*fPower*pixelAdjustment" +
-				");" +
+				"vec4 dudvValue = texture2D(uDudvSampler, vTextureCoord);" +
+				"vec2 sampleOffset = mix(vec2(0.0), dudvValue.rg-0.5, dudvValue.a) * (fPower*pixelAdjustment);" +
+				"gl_FragColor = texture2D(uSampler, vTextureCoord + sampleOffset);" +
 			"}"
 		);
 
@@ -166,14 +161,15 @@ this.createjs = this.createjs||{};
 		var dudvOffset, dudvPixel;
 
 		for (var i=0; i<height; i++) {
-			offset = i*width;
-			dudvOffset = ((i*(width/dudvWidth)) * dudvWidth) |0;
+			offset = i * width;
+			dudvOffset = ((i*(dudvHeight/height))|0) * dudvWidth;
 			for (var j=0; j<width; j++) {
-				pixel = (offset+j)*4;
-				dudvPixel = (dudvOffset + ((j*(height/dudvHeight)) |0) )*4;
+				pixel = (offset + j) *4;
+				dudvPixel = (dudvOffset + ((j*(dudvWidth/width)) |0) ) *4;
 
-				var xDelta = (((dudvPixels[dudvPixel] - 128)/128)*this.distance) |0;
-				var yDelta = (((dudvPixels[dudvPixel+1] - 128)/128)*this.distance) |0;
+				var deltaPower = dudvPixels[dudvPixel+3] / 255;
+				var xDelta = ((((dudvPixels[dudvPixel] - 128)/128) * deltaPower) * this.distance) |0;
+				var yDelta = ((((dudvPixels[dudvPixel+1] - 128)/128) * deltaPower) * this.distance |0);
 
 				if (j+xDelta < 0) { xDelta = -j; }
 				if (j+xDelta > width) { xDelta = width-j; }

From b6969d7562b39bae56a7f11db93fc11b9cd4183d Mon Sep 17 00:00:00 2001
From: David Gillen <david@gskinner.com>
Date: Fri, 23 Mar 2018 12:18:15 -0600
Subject: [PATCH 35/39] Fix for standardizing stretching logic across all
 filters, standardized code a bit more

---
 src/easeljs/filters/AlphaMapFilter.js     | 78 +++++++++++++++--------
 src/easeljs/filters/AlphaMaskFilter.js    | 25 ++++----
 src/easeljs/filters/ColorMatrix.js        |  2 +-
 src/easeljs/filters/DisplacementFilter.js | 52 +++++++++------
 src/easeljs/filters/Filter.js             | 10 +--
 5 files changed, 98 insertions(+), 69 deletions(-)

diff --git a/src/easeljs/filters/AlphaMapFilter.js b/src/easeljs/filters/AlphaMapFilter.js
index 3048a8f43..70ccc285b 100644
--- a/src/easeljs/filters/AlphaMapFilter.js
+++ b/src/easeljs/filters/AlphaMapFilter.js
@@ -85,18 +85,24 @@ this.createjs = this.createjs || {};
 		
 	// private properties:
 		/**
-		 * @property _alphaMap
+		 * @property _map
 		 * @protected
 		 * @type HTMLImageElement|HTMLCanvasElement
 		 **/
-		this._alphaMap = null;
+		this._map = null;
 		
 		/**
-		 * @property _mapData
+		 * @property _mapCtx
 		 * @protected
-		 * @type Uint8ClampedArray
+		 * @type CanvasRenderingContext2D
 		 **/
-		this._mapData = null;
+		this._mapCtx = null;
+
+		/**
+		 * @property _mapTexture
+		 * @protected
+		 * @type WebGLTexture
+		 */
 		this._mapTexture = null;
 
 		this.FRAG_SHADER_BODY = (
@@ -124,7 +130,7 @@ this.createjs = this.createjs || {};
 
 	/** docced in super class **/
 	p.shaderParamSetup = function(gl, stage, shaderProgram) {
-		if(!this._mapTexture) { this._mapTexture = gl.createTexture(); }
+		if(this._mapTexture === null) { this._mapTexture = gl.createTexture(); }
 
 		gl.activeTexture(gl.TEXTURE1);
 		gl.bindTexture(gl.TEXTURE_2D, this._mapTexture);
@@ -143,8 +149,6 @@ this.createjs = this.createjs || {};
 	/** docced in super class **/
 	p.clone = function () {
 		var o = new AlphaMapFilter(this.alphaMap);
-		o._alphaMap = this._alphaMap;
-		o._mapData = this._mapData;
 		return o;
 	};
 
@@ -156,18 +160,43 @@ this.createjs = this.createjs || {};
 
 // private methods:
 	/** docced in super class **/
-	p._applyFilter = function (imageData) {
-		if (!this.alphaMap) { return true; }
+	p._applyFilter = function(imageData) {
 		if (!this._prepAlphaMap()) { return false; }
 
-		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;
+		var outArray = imageData.data;
+		var width = imageData.width;
+		var height = imageData.height;
+		var rowOffset, pixelStart;
+
+		var sampleData = this._mapCtx.getImageData(0,0, this._map.width,this._map.height);
+		var sampleArray = sampleData.data;
+		var sampleWidth = sampleData.width;
+		var sampleHeight = sampleData.height;
+		var sampleRowOffset, samplePixelStart;
+
+		var widthRatio = sampleWidth/width;
+		var heightRatio = sampleHeight/height;
+
+		// performance optimizing lookup
+
+		// the x and y need to stretch separately, nesting the for loops simplifies this logic even if the array is flat
+		for (var i=0; i<height; i++) {
+			rowOffset = i * width;
+			sampleRowOffset = ((i*heightRatio) |0) * sampleWidth;
+
+			// the arrays are int arrays, so a single pixel is [r,g,b,a, ...],so calculate the start of the pixel
+			for (var j=0; j<width; j++) {
+				pixelStart = (rowOffset + j) *4;
+				samplePixelStart = (sampleRowOffset + ((j*widthRatio) |0)) *4;
+
+				// modify the pixels
+				outArray[pixelStart] =   outArray[pixelStart];
+				outArray[pixelStart+1] = outArray[pixelStart+1];
+				outArray[pixelStart+2] = outArray[pixelStart+2];
+				outArray[pixelStart+3] = sampleArray[samplePixelStart];
+			}
 		}
-		
+
 		return true;
 	};
 
@@ -177,10 +206,9 @@ this.createjs = this.createjs || {};
 	 **/
 	p._prepAlphaMap = function () {
 		if (!this.alphaMap) { return false; }
-		if (this.alphaMap == this._alphaMap && this._mapData) { return true; }
+		if (this.alphaMap === this._map && this._mapCtx) { return true; }
 
-		this._mapData = null;
-		var map = this._alphaMap = this.alphaMap;
+		var map = this._map = this.alphaMap;
 		var canvas = map;
 		var ctx;
 		if (map instanceof HTMLCanvasElement) {
@@ -193,14 +221,8 @@ this.createjs = this.createjs || {};
 			ctx.drawImage(map, 0, 0);
 		}
 
-		try {
-			var imgData = ctx.getImageData(0, 0, map.width, map.height);
-		} catch (e) {
-			//if (!this.suppressCrossDomainErrors) throw new Error("unable to access local image data: " + e);
-			return false;
-		}
-		
-		this._mapData = imgData.data;
+		this._mapCtx = ctx;
+
 		return true;
 	};
 
diff --git a/src/easeljs/filters/AlphaMaskFilter.js b/src/easeljs/filters/AlphaMaskFilter.js
index 3c2719816..38024be0a 100644
--- a/src/easeljs/filters/AlphaMaskFilter.js
+++ b/src/easeljs/filters/AlphaMaskFilter.js
@@ -129,26 +129,25 @@ this.createjs = this.createjs || {};
 	 * @param {Number} y The y position to use for the source rect.
 	 * @param {Number} width The width to use for the source rect.
 	 * @param {Number} height The height to use for the source rect.
-	 * @param {CanvasRenderingContext2D} [targetCtx] NOT SUPPORTED IN THIS FILTER. The 2D context to draw the result to. Defaults to the context passed to ctx.
-	 * @param {Number} [targetX] NOT SUPPORTED IN THIS FILTER. The x position to draw the result to. Defaults to the value passed to x.
-	 * @param {Number} [targetY] NOT SUPPORTED IN THIS FILTER. The y position to draw the result to. Defaults to the value passed to y.
+	 * @param {CanvasRenderingContext2D} [targetCtx] The 2D context to draw the result to. Defaults to the context passed to ctx.
 	 * @return {Boolean} If the filter was applied successfully.
 	 **/
-	p.applyFilter = function (ctx, x, y, width, height, targetCtx, targetX, targetY) {
+	p.applyFilter = function (ctx, x, y, width, height, targetCtx) {
 		if (!this.mask) { return true; }
-		targetCtx = targetCtx || ctx;
-		if (targetX == null) { targetX = x; }
-		if (targetY == null) { targetY = y; }
 
-		targetCtx.save();
-		if (ctx != targetCtx) {
-			// TODO: support targetCtx and targetX/Y
-			// clearRect, then draw the ctx in?
-			return false;
+		if (targetCtx === undefined) { targetCtx = ctx; }
+		if (targetCtx !== ctx) {
+			targetCtx.drawImage(ctx.canvas,
+				0, 0, ctx.canvas.width, ctx.canvas.height,
+				0, 0, targetCtx.canvas.width, targetCtx.canvas.height
+			);
 		}
 
+		targetCtx.save();
+
 		targetCtx.globalCompositeOperation = "destination-in";
-		targetCtx.drawImage(this.mask, targetX, targetY);
+		targetCtx.drawImage(this.mask, 0,0, this.mask.width,this.mask.height, x,y, width,height);
+
 		targetCtx.restore();
 		return true;
 	};
diff --git a/src/easeljs/filters/ColorMatrix.js b/src/easeljs/filters/ColorMatrix.js
index d830a85d3..053325c52 100644
--- a/src/easeljs/filters/ColorMatrix.js
+++ b/src/easeljs/filters/ColorMatrix.js
@@ -138,7 +138,7 @@ this.createjs = this.createjs||{};
 
 	/**
 	 * Create an instance of ColorMatrix using the Greyscale preset.
-	 * This differs from -100 saturation in that it uses a balanced representation per channel instead of luminance.
+	 * Note: -100 saturation accounts for perceived brightness, the greyscale preset treats all channels equally.
 	 * @returns {ColorMatrix}
 	 */
 	ColorMatrix.createGreyscalePreset = function() {
diff --git a/src/easeljs/filters/DisplacementFilter.js b/src/easeljs/filters/DisplacementFilter.js
index e8e81785e..01c41b94f 100644
--- a/src/easeljs/filters/DisplacementFilter.js
+++ b/src/easeljs/filters/DisplacementFilter.js
@@ -148,39 +148,51 @@ this.createjs = this.createjs||{};
 // private methods:
 	/** docced in super class **/
 	p._applyFilter = function(imageData) {
-		var refPixels = imageData.data.slice();
-		var outPixels = imageData.data;
+		var refArray = imageData.data.slice(); // as we're reaching across pixels we need an unmodified clone of the source
+
+		var outArray = imageData.data;
 		var width = imageData.width;
 		var height = imageData.height;
-		var offset, pixel;
+		var rowOffset, pixelStart;
+
+		var sampleData = this._dudvCtx.getImageData(0,0, this.dudvMap.width,this.dudvMap.height);
+		var sampleArray = sampleData.data;
+		var sampleWidth = sampleData.width;
+		var sampleHeight = sampleData.height;
+		var sampleRowOffset, samplePixelStart;
 
-		var dudvData = this._dudvCtx.getImageData(0,0, this.dudvMap.width,this.dudvMap.height);
-		var dudvPixels = dudvData.data;
-		var dudvWidth = dudvData.width;
-		var dudvHeight = dudvData.height;
-		var dudvOffset, dudvPixel;
+		var widthRatio = sampleWidth/width;
+		var heightRatio = sampleHeight/height;
+		var pxRange = 1/255;
 
+		// performance optimizing lookup
+		var distance = this.distance*2;
+
+		// the x and y need to stretch separately, nesting the for loops simplifies this logic even if the array is flat
 		for (var i=0; i<height; i++) {
-			offset = i * width;
-			dudvOffset = ((i*(dudvHeight/height))|0) * dudvWidth;
+			rowOffset = i * width;
+			sampleRowOffset = ((i*heightRatio) |0) * sampleWidth;
+
+			// the arrays are int arrays, so a single pixel is [r,g,b,a, ...],so calculate the start of the pixel
 			for (var j=0; j<width; j++) {
-				pixel = (offset + j) *4;
-				dudvPixel = (dudvOffset + ((j*(dudvWidth/width)) |0) ) *4;
+				pixelStart = (rowOffset + j) *4;
+				samplePixelStart = (sampleRowOffset + ((j*widthRatio) |0)) *4;
 
-				var deltaPower = dudvPixels[dudvPixel+3] / 255;
-				var xDelta = ((((dudvPixels[dudvPixel] - 128)/128) * deltaPower) * this.distance) |0;
-				var yDelta = ((((dudvPixels[dudvPixel+1] - 128)/128) * deltaPower) * this.distance |0);
+				// modify the pixels
+				var deltaPower = sampleArray[samplePixelStart+3] * pxRange * distance;
+				var xDelta = ((sampleArray[samplePixelStart] * pxRange - 0.5) * deltaPower) |0;
+				var yDelta = ((sampleArray[samplePixelStart+1] * pxRange - 0.5) * deltaPower) |0;
 
 				if (j+xDelta < 0) { xDelta = -j; }
 				if (j+xDelta > width) { xDelta = width-j; }
 				if (i+yDelta < 0) { yDelta = -i; }
 				if (i+yDelta > height) { yDelta = height-i; }
 
-				var targetPixel = (pixel + xDelta*4) + yDelta*4*width;
-				outPixels[pixel] =		refPixels[targetPixel];
-				outPixels[pixel+1] =	refPixels[targetPixel+1];
-				outPixels[pixel+2] =	refPixels[targetPixel+2];
-				outPixels[pixel+3] =	refPixels[targetPixel+3];
+				var targetPixelStart = (pixelStart + xDelta*4) + yDelta*4*width;
+				outArray[pixelStart] =   refArray[targetPixelStart];
+				outArray[pixelStart+1] = refArray[targetPixelStart+1];
+				outArray[pixelStart+2] = refArray[targetPixelStart+2];
+				outArray[pixelStart+3] = refArray[targetPixelStart+3];
 			}
 		}
 
diff --git a/src/easeljs/filters/Filter.js b/src/easeljs/filters/Filter.js
index 842e540c8..111ffd28b 100644
--- a/src/easeljs/filters/Filter.js
+++ b/src/easeljs/filters/Filter.js
@@ -164,23 +164,19 @@ this.createjs = this.createjs||{};
 	 * @param {Number} y The y position to use for the source rect.
 	 * @param {Number} width The width to use for the source rect.
 	 * @param {Number} height The height to use for the source rect.
-	 * @param {CanvasRenderingContext2D} [targetCtx] The 2D context to draw the result to. Defaults to the context passed to ctx.
-	 * @param {Number} [targetX] The x position to draw the result to. Defaults to the value passed to x.
-	 * @param {Number} [targetY] The y position to draw the result to. Defaults to the value passed to y.
+	 * @param {CanvasRenderingContext2D} [targetCtx=ctx] The 2D context to draw the result to. Defaults to the context passed to ctx.
 	 * @return {Boolean} If the filter was applied successfully.
 	 **/
-	p.applyFilter = function(ctx, x, y, width, height, targetCtx, targetX, targetY) {
+	p.applyFilter = function(ctx, x, y, width, height, targetCtx) {
 		// this is the default behaviour because most filters access pixel data. It is overridden when not needed.
 		targetCtx = targetCtx || ctx;
-		if (targetX == null) { targetX = x; }
-		if (targetY == null) { targetY = y; }
 		try {
 			var imageData = ctx.getImageData(x, y, width, height);
 		} catch (e) {
 			return false;
 		}
 		if (this._applyFilter(imageData)) {
-			targetCtx.putImageData(imageData, targetX, targetY);
+			targetCtx.putImageData(imageData, x, y);
 			return true;
 		}
 		return false;

From 23b8cafdd39a5763589130d06a3f1087763654d3 Mon Sep 17 00:00:00 2001
From: David Gillen <david@gskinner.com>
Date: Mon, 26 Mar 2018 16:52:51 -0600
Subject: [PATCH 36/39] Fix for https://github.com/CreateJS/EaselJS/issues/930

---
 src/easeljs/display/Bitmap.js | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/src/easeljs/display/Bitmap.js b/src/easeljs/display/Bitmap.js
index db90d5fec..497828ce5 100644
--- a/src/easeljs/display/Bitmap.js
+++ b/src/easeljs/display/Bitmap.js
@@ -212,7 +212,10 @@ this.createjs = this.createjs||{};
 	 **/
 	p.clone = function(node) {
 		var image = this.image;
-		if(image && node){ image = image.cloneNode(); }
+		if(image && node){
+			image = image.cloneNode();
+			image.src = image.src; // IE cloneNode bug fix
+		}
 		var o = new Bitmap(image);
 		if (this.sourceRect) { o.sourceRect = this.sourceRect.clone(); }
 		this._cloneProps(o);

From 43420c1bd41a5a1a60fc9479bc3beaeae89d880e Mon Sep 17 00:00:00 2001
From: David Gillen <david@gskinner.com>
Date: Mon, 26 Mar 2018 16:53:09 -0600
Subject: [PATCH 37/39] Fix for IE11

---
 src/easeljs/filters/DisplacementFilter.js | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/src/easeljs/filters/DisplacementFilter.js b/src/easeljs/filters/DisplacementFilter.js
index 01c41b94f..e07f057bb 100644
--- a/src/easeljs/filters/DisplacementFilter.js
+++ b/src/easeljs/filters/DisplacementFilter.js
@@ -148,7 +148,15 @@ this.createjs = this.createjs||{};
 // private methods:
 	/** docced in super class **/
 	p._applyFilter = function(imageData) {
-		var refArray = imageData.data.slice(); // as we're reaching across pixels we need an unmodified clone of the source
+		// as we're reaching across pixels we need an unmodified clone of the source
+		// slice/from/map/filter don't work correctly in IE11 and subarray creates a ref
+		var refArray, refArraySrc = imageData.data;
+		if (refArraySrc.slice !== undefined) {
+			refArray = refArraySrc.slice();
+		} else {
+			refArray = new Uint8ClampedArray(refArraySrc.length);
+			refArray.set(refArraySrc);
+		}
 
 		var outArray = imageData.data;
 		var width = imageData.width;

From e314a63b015fddbd3d8b5a007698baa6daadc931 Mon Sep 17 00:00:00 2001
From: David Gillen <david@gskinner.com>
Date: Thu, 29 Mar 2018 16:43:54 -0600
Subject: [PATCH 38/39] documentation accuracy update

---
 src/easeljs/display/StageGL.js          | 10 +++++-----
 src/easeljs/filters/AberrationFilter.js | 16 +++++++++-------
 src/easeljs/filters/BitmapCache.js      | 24 ++++++++++++++++--------
 src/easeljs/filters/Filter.js           |  9 ++++++---
 4 files changed, 36 insertions(+), 23 deletions(-)

diff --git a/src/easeljs/display/StageGL.js b/src/easeljs/display/StageGL.js
index 07c4f8703..799abb01e 100644
--- a/src/easeljs/display/StageGL.js
+++ b/src/easeljs/display/StageGL.js
@@ -152,11 +152,11 @@ this.createjs = this.createjs||{};
 		this.vocalDebug = false;
 
 		/**
-		 * Specifies whether this instance is slaved to a {{#crossLink "BitmapCache"}}{{/crossLink}} or is its own master.
-		 * Controls whether final rendering output of a {{#crossLink "cacheDraw"}}{{/crossLink}} command is to the canvas
-		 * or a render texture. See the {{#crossLink "cache"}}{{/crossLink}} function documentation and read the code for
-		 * full implications and details of necessity. Enabled by default when BitmapCache's `useGL` is true.
-		 * NOTE: This method is mainly for internal use, though it may be useful for advanced uses.
+		 * Specifies whether this instance is slaved to a {{#crossLink "BitmapCache"}}{{/crossLink}} or draws independantly.
+		 * Necessary to control texture outputs and behaviours when caching. StageGL cache outputs will only render
+		 * properly for the StageGL that made them. See the {{#crossLink "cache"}}{{/crossLink}} function documentation
+		 * for more information. Enabled by default when BitmapCache's `useGL` is true.
+		 * NOTE: This property is mainly for internal use, though it may be useful for advanced uses.
 		 * @property isCacheControlled
 		 * @type {Boolean}
 		 * @default false
diff --git a/src/easeljs/filters/AberrationFilter.js b/src/easeljs/filters/AberrationFilter.js
index 2456eab23..9907d64a4 100644
--- a/src/easeljs/filters/AberrationFilter.js
+++ b/src/easeljs/filters/AberrationFilter.js
@@ -36,19 +36,21 @@
 
 // constructor:
 	/**
-	 * Seperates and pushes the different colour channels apart.
+	 * Separates and pushes each of the colour channels apart. I.E. shift the red channel slightly left.
+	 * Allows specifying the direction and the ammount it affects each channel. Great for computer glitches and VCR like
+	 * effects.
 	 *
 	 * See {{#crossLink "Filter"}}{{/crossLink}} for an more information on applying filters.
 	 * @class AberrationFilter
 	 * @extends Filter
 	 * @constructor
-	 * @param {Number} [xDir=0] Movement in x, specified in pixels.
-	 * @param {Number} [yDir=0] Movement in y, specified in pixels.
-	 * @param {Number} [redMultiplier=0] Multiplier for movement of the Red channel. Negative values allowed.
-	 * @param {Number} [greenMultiplier=0] Multiplier for movement of the Green channel. Negative values allowed.
-	 * @param {Number} [blueMultiplier=0] Multiplier for movement of the Blue channel. Negative values allowed.
+	 * @param {Number} [xDir=0] Movement in x at a multiplier of 1, specified in pixels.
+	 * @param {Number} [yDir=0] Movement in y at a multiplier of 1, specified in pixels.
+	 * @param {Number} [redMultiplier=0] Multiplier for the movement of the Red channel. Negative values allowed.
+	 * @param {Number} [greenMultiplier=0] Multiplier for the movement of the Green channel. Negative values allowed.
+	 * @param {Number} [blueMultiplier=0] Multiplier for the movement of the Blue channel. Negative values allowed.
 	 * @param {Number} [originalMix=0] Amount of original image to keep, 0-1.
-	 * @param {Boolean} [alphaMax=false] Calculate combined alpha using maximum value available.
+	 * @param {Boolean} [alphaMax=false] Calculate combined alpha using maximum alpha available. Creates a stronger image.
 	 **/
 	function AberrationFilter(xDir, yDir, redMultiplier, greenMultiplier, blueMultiplier, originalMix, alphaMax) {
 		this.Filter_constructor();
diff --git a/src/easeljs/filters/BitmapCache.js b/src/easeljs/filters/BitmapCache.js
index d72f3a64f..358a246ab 100644
--- a/src/easeljs/filters/BitmapCache.js
+++ b/src/easeljs/filters/BitmapCache.js
@@ -53,8 +53,11 @@ this.createjs = this.createjs||{};
 	 * Caching is also a co-requisite for applying filters to prevent expensive filters running constantly without need,
 	 * and to physically enable some effects. The BitmapCache is also responsible for applying filters to objects and
 	 * reads each {{#crossLink "Filter"}}{{/crossLink}} due to this relationship. Real-time Filters are not recommended
-	 * performance wise when dealing with a Context2D canvas. For best performance and to still allow for some visual
-	 * effects use a compositeOperation when possible.
+	 * performance wise when dealing with a Context2D canvas. On a StageGL performance is better so the presence of a
+	 * filter will automatically create a cache if one is not made manually.
+	 *
+	 * Some visual effects can be achieved with a {{#crossLink "DisplayObject/compositeOperation:property"}}{{/crossLink}}
+	 * so check out that setting before settling on a filter.
 	 * @class BitmapCache
 	 * @constructor
 	 **/
@@ -352,8 +355,8 @@ this.createjs = this.createjs||{};
 	 * specifics of how to use the options object.
 	 *
 	 * - If options.useGL is set to "new" a StageGL is created and contained on this for use when rendering the cache.
-	 * - If options.useGL is set to "stage" if the current stage is a StageGL it will be used. If not then it will default to "new".
-	 * - If options.useGL is a StageGL instance it will not create one but use the one provided.
+	 * - If options.useGL is set to "stage" if the current stage is a StageGL it will be used. Must be added to a stage first to work.
+	 * - If options.useGL is a StageGL instance then it will use it to cache. Warning, caches made on one StageGL will not render on any other StageGL.
 	 * - If options.useGL is undefined a Context 2D cache will be performed.
 	 *
 	 * This means you can use any combination of StageGL and 2D with either, neither, or both the stage and cache being
@@ -382,16 +385,21 @@ this.createjs = this.createjs||{};
 	 *
 	 *     var stageGL = new createjs.StageGL();
 	 *     var bmp = new createjs.Bitmap(src);
-	 *     bmp.cache(0, 0, bmp.width, bmp.height, 1, {gl: "stage"});       // use our StageGL to cache
+	 *
+	 *     // option 1
+	 *     stageGL.addChild(bmp);
+	 *     bmp.cache(0, 0, bmp.width, bmp.height, 1, {gl: "stage"});       // when added to the display list we can look it up
+	 *     // option 2
+	 *     bmp.cache(0, 0, bmp.width, bmp.height, 1, {gl: stageGL});       // we can specify it explicitly if we add it later
+	 *     stageGL.addChild(bmp);
 	 *
 	 *     var shape = new createjs.Shape();
 	 *     shape.graphics.clear().fill("red").drawRect(0,0,20,20);
 	 *     shape.cache(0, 0, 20, 20, 1);                             // cannot use WebGL cache
 	 *
 	 * You may wish to create your own StageGL instance to control factors like clear color, transparency, AA, and
-	 * others. If you do, pass a new instance in instead of "true", the library will automatically set the
-	 * {{#crossLink "StageGL/isCacheControlled"}}{{/crossLink}} to true on your instance. This will trigger it to behave
-	 * correctly, and not assume your main context is WebGL.
+	 * others. If the specified stage is not rendering content and just the cache set{{#crossLink "StageGL/isCacheControlled"}}{{/crossLink}}
+	 * to true on your instance. This will trigger it to behave correctly for rendering your output.
 	 *
 	 * @public
 	 * @method BitmapCache.cache
diff --git a/src/easeljs/filters/Filter.js b/src/easeljs/filters/Filter.js
index 111ffd28b..f4a3ea125 100644
--- a/src/easeljs/filters/Filter.js
+++ b/src/easeljs/filters/Filter.js
@@ -39,9 +39,11 @@ this.createjs = this.createjs||{};
 
 // constructor:
 	/**
-	 * Base class that all filters should inherit from. Filters need to be applied to objects that have been cached using
-	 * the {{#crossLink "DisplayObject/cache"}}{{/crossLink}} method. If an object changes, please cache it again, or use
-	 * {{#crossLink "DisplayObject/updateCache"}}{{/crossLink}}. Note that the filters must be applied before caching.
+	 * Base class that all filters should inherit from. Appli
+	 *
+	 * When on a regular Stage apply the Filters and then cache the object using the {{#crossLink "DisplayObject/cache"}}{{/crossLink}} method.
+	 * When a cached object changes, please use {{#crossLink "DisplayObject/updateCache"}}{{/crossLink}}.
+	 * When on a StageGL simply setting content in the `.filters` array will trigger an automatic and constantly updated cache.
 	 *
 	 * <h4>Example</h4>
 	 *
@@ -58,6 +60,7 @@ this.createjs = this.createjs||{};
 	 * 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>

From 0a2d2edc0f8432089a65191ec68c327f0782f581 Mon Sep 17 00:00:00 2001
From: David Gillen <david@gskinner.com>
Date: Wed, 4 Apr 2018 17:09:35 -0600
Subject: [PATCH 39/39] default to fast option

---
 src/easeljs/display/StageGL.js | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/src/easeljs/display/StageGL.js b/src/easeljs/display/StageGL.js
index 799abb01e..5522ee793 100644
--- a/src/easeljs/display/StageGL.js
+++ b/src/easeljs/display/StageGL.js
@@ -87,6 +87,7 @@ this.createjs = this.createjs||{};
 	 * resize your canvas after making a StageGL instance, this will properly size the WebGL context stored in memory.
 	 * - Best performance in demanding scenarios will come from manual management of texture memory, but it is handled
 	 * automatically by default. See {{#crossLink "StageGL/releaseTexture"}}{{/crossLink}} for details.
+	 * - Disable `directDraw` to get access to cacheless filters and composite oeprations!
 	 *
 	 * <h4>Example</h4>
 	 * This example creates a StageGL instance, adds a child to it, then uses the EaselJS {{#crossLink "Ticker"}}{{/crossLink}}
@@ -117,7 +118,7 @@ this.createjs = this.createjs||{};
 	 * to perform anti-aliasing. This will also enable linear pixel sampling on power-of-two textures (smoother images).
 	 * @param {Boolean} [options.transparent=false] If `true`, the canvas is transparent. This is <strong>very</strong>
 	 * expensive, and should be used with caution.
-	 * @param {Boolean} [options.directDraw=false] If `true`, this will bypass intermediary render-textures when possible
+	 * @param {Boolean} [options.directDraw=true] If `true`, this will bypass intermediary render-textures when possible
 	 * resulting in reduced memory and increased performance, this disables some features. Cache-less filters and some
 	 * {{#crossLink "DisplayObject/compositeOperation:property"}}{{/crossLink}} values rely on this being false.
 	 * @param (Boolean} [options.premultiply] @deprecated Upgraded colour & transparency handling have fixed the issue
@@ -210,7 +211,7 @@ this.createjs = this.createjs||{};
 		 * @type {Boolean}
 		 * @default false
 		 */
-		this._directDraw = directDraw;
+		this._directDraw = directDraw === undefined ? true : false;
 
 		/**
 		 * The width in px of the drawing surface saved in memory.