Update and improve debugging tools for StageGL -> WebGLInspector

Author: David Gillen

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);

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");