improves doc and test/examples

chesterGL/actions.js

@@ -30,8 +30,8 @@ goog.require("chesterGL.Block");
 
 /**
  * @constructor
- * @param {number} totalTime
- * @param {chesterGL.Block=} block
+ * @param {number} totalTime in seconds
+ * @param {chesterGL.Block=} block The target block
  */
 chesterGL.Action = function (totalTime, block) {
 	this.totalTime = totalTime * 1000;
@@ -81,7 +81,7 @@ chesterGL.Action.prototype.finished = false;
 chesterGL.Action.prototype.running = false;
 
 /**
- * This is the default delta function (does nothing)
+ * This is the default update function (does nothing)
  * @param {number} delta
  */
 chesterGL.Action.prototype.update = function (delta) {
@@ -103,9 +103,9 @@ chesterGL.Action.prototype.begin = function () {
 
 /**
  * @constructor
- * @param {Array|Float32Array} finalPosition
- * @param {number} totalTime
- * @param {chesterGL.Block=} block
+ * @param {Array|Float32Array} finalPosition The final position (the initial position is the current one of the block)
+ * @param {number} totalTime The total time in seconds that this action should take
+ * @param {chesterGL.Block=} block The block that will execute this action
  * @extends {chesterGL.Action}
  */
 chesterGL.MoveToAction = function (finalPosition, totalTime, block) {
@@ -128,10 +128,11 @@ chesterGL.MoveToAction.prototype.startPosition = null;
  * @type {goog.vec.Vec3.Type}
  * @ignore
  */
-var __tmp_pos = goog.vec.Vec3.createFloat32();
+chesterGL.MoveToAction__tmp_pos = goog.vec.Vec3.createFloat32();
 
 /**
  * @param {number} delta miliseconds from last time we updated
+ * @ignore
  */
 chesterGL.MoveToAction.prototype.update = function (delta) {
 	chesterGL.Action.prototype.update.call(this, delta);
@@ -141,13 +142,14 @@ chesterGL.MoveToAction.prototype.update = function (delta) {
 	} else {
 		var t = Math.min(1, this.elapsed / this.totalTime);
 		// console.log("t: " + t + "\t(" + dx + ")");
-		goog.vec.Vec3.lerp(this.startPosition, this.finalPosition, t, __tmp_pos);
-		block.setPosition(__tmp_pos);
+		goog.vec.Vec3.lerp(this.startPosition, this.finalPosition, t, chesterGL.MoveToAction__tmp_pos);
+		block.setPosition(chesterGL.MoveToAction__tmp_pos);
 	}
 };
 
 /**
  * just set the initial position
+ * @ignore
  */
 chesterGL.MoveToAction.prototype.begin = function () {
 	if (!this.block) {
@@ -158,37 +160,40 @@ chesterGL.MoveToAction.prototype.begin = function () {
 
 /**
  * @constructor
- * @param {number} delay in seconds
- * @param {Array.<Object>} frames
- * @param {boolean?} loop
- * @param {chesterGL.Block=} block
+ * @param {number} delay in seconds between frames
+ * @param {Array.<Object>} frames The frames of the animation
+ * @param {boolean=} loop Whether or not this animation should loop
+ * @param {chesterGL.Block=} block The block that will receive this action
  * @extends {chesterGL.Action}
  */
 chesterGL.AnimateAction = function (delay, frames, loop, block) {
 	this.delay = delay * 1000.0;
 	var totalTime = this.delay * frames.length;
-	if (loop == true) totalTime = -1;
+	if (loop === true) totalTime = -1;
 	chesterGL.Action.call(this, totalTime, block);
-	this.shouldLoop = (loop == true);
+	this.shouldLoop = (loop === true);
 	this.frames = frames.slice(0);
 };
 goog.inherits(chesterGL.AnimateAction, chesterGL.Action);
 
 /**
  * the current frame
  * @type {number}
+ * @ignore
  */
 chesterGL.AnimateAction.prototype.currentFrame = 0;
 
 /**
  * The delay between frames
  * @type {number}
+ * @ignore
  */
 chesterGL.AnimateAction.prototype.delay = 0.0;
 
 /**
  * The total frames of the animation
  * @type {Array.<goog.vec.Vec4.Type>}
+ * @ignore
  */
 chesterGL.AnimateAction.prototype.frames = null;
 
@@ -200,6 +205,7 @@ chesterGL.AnimateAction.prototype.shouldLoop = false;
 
 /**
  * @param {number} delta
+ * @ignore
  */
 chesterGL.AnimateAction.prototype.update = function (delta) {
 	chesterGL.Action.prototype.update.call(this, delta);
@@ -246,6 +252,7 @@ chesterGL.ActionManager.scheduleAction = function (action) {
 /**
  * Iterate over all scheduled actions
  * @param {number} delta number of miliseconds to run in all actions
+ * @ignore
  */
 chesterGL.ActionManager.tick = function (delta) {
 	var i = 0, len = chesterGL.ActionManager.scheduledActions_.length;

chesterGL/block.js

@@ -114,6 +114,7 @@ chesterGL.Block.TYPE = {
  * 12 (verts, 3 floats) + 8 (tex coords, 2 floats) + 16 (color, 4 floats)
  * @const
  * @type {number}
+ * @ignore
  */
 chesterGL.Block.QUAD_SIZE = 36;
 
@@ -122,6 +123,7 @@ chesterGL.Block.QUAD_SIZE = 36;
  * 3 (vert) + 2 (tex) + 4 (color) = 9; 9 * 4 (verts) = 36
  * @const
  * @type {number}
+ * @ignore
  */
 chesterGL.Block.BUFFER_SIZE = 36;
 
@@ -137,6 +139,13 @@ chesterGL.Block.DEG_TO_RAD = Math.PI / 180.0;
  */
 chesterGL.Block.RAD_TO_DEG = 180.0 / Math.PI;
 
+/**
+ * One degree in radians
+ * @const
+ * @type {number}
+ */
+chesterGL.Block.ONE_DEG = 1 * chesterGL.Block.DEG_TO_RAD;
+
 /**
  * the full frame
  * 
@@ -154,6 +163,7 @@ chesterGL.Block.FullFrame = goog.vec.Vec4.createFloat32FromValues(0.0, 0.0, 1.0,
 chesterGL.Block.SizeZero = new goog.math.Size(0.0, 0.0);
 
 /**
+ * Sets the title of this block, only used in the scenes right now (for analytics)
  * @type {string}
  */
 chesterGL.Block.prototype.title = "";
@@ -220,24 +230,25 @@ chesterGL.Block.prototype.glBuffer = null;
 chesterGL.Block.prototype.glBufferData = null;
 
 /**
- * the position of the center of the block
+ * the position of the center of the block. Use the setter to modify this property
  * @type {goog.vec.Vec3.Type}
  */
 chesterGL.Block.prototype.position = goog.vec.Vec3.createFloat32();
 
 /**
- * the content size of the block
+ * the content size of the block. Use the setter to modify this property
  * @type {?goog.math.Size}
  */
 chesterGL.Block.prototype.contentSize = null;
 
 /**
- * the color of the block
+ * the color of the block. Use the setter to modify this property
  * @type {goog.vec.Vec4.Type}
  */
 chesterGL.Block.prototype.color = goog.vec.Vec4.createFloat32FromValues(1.0, 1.0, 1.0, 1.0);
 
 /**
+ * The name of the texture associated with this block. Use the setter to modify this property
  * @type {?string}
  */
 chesterGL.Block.prototype.texture = null;
@@ -248,37 +259,37 @@ chesterGL.Block.prototype.texture = null;
 chesterGL.Block.prototype.opacity = 1.0;
 
 /**
- * rotation of the box - in radians
+ * rotation of the box - in radians. Use the setter to modify this property
  * @type {number}
  */
 chesterGL.Block.prototype.rotation = 0;
 
 /**
- * the scale of the box
+ * the scale of the box. Use the setter to modify this property
  * @type {number}
  */
 chesterGL.Block.prototype.scale = 1.0;
 
 /**
- * update function
+ * update function - called every frame with the delta in milliseconds since last frame
  * @type {?function(number)}
  */
 chesterGL.Block.prototype.update = null;
 
 /**
- * the texture frame
+ * the texture frame. Use the setter to modify this property
  * @type {?goog.vec.Vec4.Type}
  */
 chesterGL.Block.prototype.frame = null;
 
 /**
- * the block group this block belongs to
+ * the block group this block belongs to. Read only
  * @type {?chesterGL.Block}
  */
 chesterGL.Block.prototype.parent = null;
 
 /**
- * the array to hold children blocks
+ * the array to hold children blocks. Read only, to modify use addChild or removeChild
  * @type {?Array.<chesterGL.Block>}
  */
 chesterGL.Block.prototype.children = null;
@@ -459,6 +470,7 @@ chesterGL.Block.prototype.removeChild = function (block) {
 
 /**
  * actually performs the transformation
+ * @ignore
  */
 chesterGL.Block.prototype.transform = function () {
 	var gl = chesterGL.gl;
@@ -553,6 +565,7 @@ chesterGL.Block.prototype.transform = function () {
 
 /**
  * prepares the block for the rendering (transforms if necessary)
+ * @ignore
  */
 chesterGL.Block.prototype.visit = function () {
 	this._inVisit = true;
@@ -591,6 +604,7 @@ chesterGL.Block.prototype.visit = function () {
 
 /**
  * render (only will work for non-blockgroup blocks)
+ * @ignore
  */
 chesterGL.Block.prototype.render = function () {
 	if (this.type == chesterGL.Block.TYPE['BLOCKGROUP']) {
@@ -658,6 +672,9 @@ goog.exportSymbol('chesterGL.Block.SizeZero', chesterGL.Block.SizeZero);
 goog.exportSymbol('chesterGL.Block.TYPE', chesterGL.Block.TYPE);
 goog.exportSymbol('chesterGL.Block.PROGRAM', chesterGL.Block.PROGRAM);
 goog.exportSymbol('chesterGL.Block.PROGRAM_NAME', chesterGL.Block.PROGRAM_NAME);
+goog.exportSymbol('chesterGL.Block.DEG_TO_RAD', chesterGL.Block.DEG_TO_RAD);
+goog.exportSymbol('chesterGL.Block.RAD_TO_DEG', chesterGL.Block.RAD_TO_DEG);
+goog.exportSymbol('chesterGL.Block.ONE_DEG', chesterGL.Block.ONE_DEG);
 // properties
 goog.exportProperty(chesterGL.Block.prototype, 'title', chesterGL.Block.prototype.title);
 // instance methods

chesterGL/blockGroup.js

@@ -58,21 +58,25 @@ goog.inherits(chesterGL.BlockGroup, chesterGL.Block);
 /**
  * The max number of children this blockgroup can hold (this is here for the buffer data)
  * @type {number}
+ * @ignore
  */
 chesterGL.BlockGroup.prototype.maxChildren = 0;
 
 /**
  * @type {boolean}
+ * @ignore
  */
 chesterGL.BlockGroup.prototype.isChildDirty = false;
 
 /**
  * @type {?WebGLBuffer}
+ * @ignore
  */
 chesterGL.BlockGroup.prototype.indexBuffer = null;
 
 /**
  * @type {?Uint16Array}
+ * @ignore
  */
 chesterGL.BlockGroup.prototype.indexBufferData = null;
 
@@ -156,6 +160,7 @@ chesterGL.BlockGroup.prototype.removeBlock = function (b) {
 
 /**
  * where the fun begins
+ * @ignore
  */
 chesterGL.BlockGroup.prototype.visit = function () {
 	if (this.update) {
@@ -191,6 +196,7 @@ chesterGL.BlockGroup.prototype.visit = function () {
 
 /**
  * actually render the block group
+ * @ignore
  */
 chesterGL.BlockGroup.prototype.render = function () {
 	var gl = chesterGL.gl;