jax 0.0.0.1

data/src/jax/core.js

@@ -0,0 +1,39 @@
+//= require "vendor/ejs"
+//= require "vendor/glMatrix"
+//= require "prototype/class"
+//= require "core/math"
+//= require "core/util"
+//= require "core/matrix_stack"
+
+// a global debugAssert method that will do nothing in production, and fail if expr is false
+// in any other run mode. If msg is given, an error with that message is raised. Otherwise,
+// a more generic error is raised.
+window.debugAssert = function(expr, msg) {
+  if (Jax.environment != "production" && !expr)
+  {
+    var error = new Error(msg || "debugAssert failed");
+    if (error.stack) error = new Error((msg || "debugAssert failed")+"\n\n"+error.stack);
+    throw error;
+  }
+};
+
+// If glMatrixArrayType isn't simply Array, then most browsers (FF, Chrome) have a pretty
+// crappy implementation of toString() that actually tells you nothing about the array's
+// contents. This makes the #toString method a little more Array-like.
+//
+// Ex: "[Float32Array: -100,-100,-100]"
+if (glMatrixArrayType.prototype.toString != Array.prototype.toString) {
+  glMatrixArrayType.prototype.toString = function() {
+    var s = "["+glMatrixArrayType.name+": ";
+    var d = false;
+    for (var i in this) {
+      if (parseInt(i) == i) {
+        if (d) s += ",";
+        s += this[i];
+        d = true;
+      }
+    }
+    s += "]";
+    return s;
+  }
+}

data/src/jax/core/math.js

@@ -0,0 +1,40 @@
+// If an epsilon isn't defined, define it. This is used for fuzzy equality with floats,
+// because of floating point imprecision.
+Math.EPSILON = Math.EPSILON || 0.00001;
+
+/**
+ * Math
+ * Defines math-related helper functions.
+ **/
+
+/**
+ * Math.radToDeg(rad) -> Number
+ * Helper to convert radians to degrees.
+ **/
+Math.radToDeg = Math.radToDeg || function(rad) {
+  return rad * 180.0 / Math.PI;
+};
+
+/**
+ * Math.radToDeg(rad) -> Number
+ * Helper to convert degrees to radians.
+ **/
+Math.degToRad = Math.degToRad || function(deg) {
+  return deg * Math.PI / 180.0;
+};
+
+/**
+ * Math.equalish(a, b) -> Boolean
+ * Arguments can be either scalar or vector, but must be of the same type.
+ * Returns true if the arguments are "equal enough" after accounting for floating-point
+ * precision loss. Returns false otherwise.
+ **/
+Math.equalish = Math.equalish || function(a, b) {
+  if (!a.length && !b.length)
+    return Math.abs(a - b) <= Math.EPSILON;
+
+  if (a.length != b.length) return false;
+  for (var i = 0; i < a.length; i++)
+    if (Math.abs(a[i] - b[i]) > Math.EPSILON) return false;
+  return true;
+};

data/src/jax/core/matrix_stack.js

@@ -0,0 +1,306 @@
+//= require "../vendor/glMatrix"
+//= require "../prototype/class"
+
+/**
+ * Jax.IDENTITY_MATRIX
+ * A cache of the identity matrix so that we're not constantly allocating identities.
+ **/
+Jax.IDENTITY_MATRIX = mat4.identity(mat4.create());
+
+/**
+ * class Jax.MatrixStack
+ * 
+ * A matrix stack, obviously. Every Jax.Context allocates its own matrix stack, so you probably
+ * shouldn't have to instantiate this directly. Calls to methods of the same name on Jax.Context
+ * are delegated into its own matrix stack, so you're really calling these methods.
+ * 
+ * Note that for performance reasons, whenever you call get[Some]Matrix(), the matrix instance
+ * itself is returned instead of a copy of the instance. That gives you the power to make changes
+ * directly to the matrix, instead of doing them via the stack. For instance, instead of calling
+ * Jax.MatrixStack#loadMatrix(), you could just as easily call mat4#set() using one of the
+ * matrices here as an argument. However, in doing so you will lose the auto-updating of other
+ * matrices, so you must be very careful about how you modify matrices.
+ *
+ * For example, it would be very easy to use mat4.multiply() to change the model matrix. In doing
+ * so, the inverse model matrix would no longer be accurate. This could lead to very
+ * difficult-to-debug situations.
+ * 
+ * When in doubt, it is _strongly_ recommended to use the various matrix methods found in
+ * Jax.MatrixStack to modify the matrices here. This will keep all related matrices up-to-date.
+ **/
+Jax.MatrixStack = (function() {
+  var MODEL = 1, VIEW = 2, PROJECTION = 3;
+  
+  function updateMVP(self) {
+    mat4.multiply(self.getProjectionMatrix(), self.getModelViewMatrix(), self.getModelViewProjectionMatrix());
+  }
+  
+  function updateModelView(self) {
+    mat4.multiply(self.getInverseViewMatrix(), self.getModelMatrix(), self.getModelViewMatrix());
+    mat4.inverse(self.getModelViewMatrix(), self.getInverseModelViewMatrix());
+    updateMVP(self);
+  }
+  
+  function updateNormal(self) {
+    mat4.toMat3(self.getInverseModelViewMatrix(), self.getNormalMatrix());
+    mat3.transpose(self.getNormalMatrix());
+  }
+  
+  function mMatrixUpdated(self) {
+    mat4.inverse(self.getModelMatrix(), self.getInverseModelMatrix());
+    updateModelView(self);
+    updateNormal(self);
+  }
+  
+  function vMatrixUpdated(self) {
+    mat4.inverse(self.getViewMatrix(), self.getInverseViewMatrix());
+    updateModelView(self);
+    updateNormal(self);
+  }
+  
+  function pMatrixUpdated(self) {
+    mat4.inverse(self.getProjectionMatrix(), self.getInverseProjectionMatrix());
+    updateMVP(self);
+  }
+  
+  function loadMatrix(self, which, values) {
+    switch(which) {
+      case MODEL:
+        mat4.set(values, self.getModelMatrix());
+        mMatrixUpdated(self);
+        break;
+      case VIEW:
+        mat4.set(values, self.getViewMatrix());
+        vMatrixUpdated(self);
+        break;
+      case PROJECTION:
+        mat4.set(values, self.getProjectionMatrix());
+        pMatrixUpdated(self);
+        break;
+      default: throw new Error("programming error: matrix ID not understood: "+which);
+    }
+  }
+  
+  function multMatrix(self, which, values) {
+    switch(which) {
+      case MODEL:
+        mat4.multiply(self.getModelMatrix(), values, self.getModelMatrix());
+        mMatrixUpdated(self);
+        break;
+      case VIEW:
+        mat4.multiply(self.getViewMatrix(), values, self.getViewMatrix());
+        vMatrixUpdated(self);
+        break;
+      case PROJECTION:
+        mat4.multiply(self.getProjectionMatrix(), values, self.getProjectionMatrix());
+        pMatrixUpdated(self);
+        break;
+      default: throw new Error("programming error: matrix ID not understood: "+which);
+    }
+  }
+  
+  /*
+    iterates through each matrix stack in self.matrices and pushes a new matrix onto the stack.
+    If the new matrix level already has a matrix, it is used; otherwise, a new one is allocated.
+    Then, the current level's matrix values are copied into the next level's matrix.
+   */
+  function pushMatrix(self) {
+    var current;
+    var stack;
+    var current_depth = self.depth;
+    var type;
+
+    self.depth++;
+    for (var i in self.matrices) {
+      stack = self.matrices[i];
+      current = stack[current_depth];
+      type = (current.length == 9 ? mat3 : mat4);
+      stack[self.depth] = stack[self.depth] || type.create();
+      type.set(current, stack[self.depth]);
+    }
+  }
+  
+  return Jax.Class.create({
+    /**
+     * Jax.MatrixStack#push() -> Jax.MatrixStack
+     * 
+     * Saves the state of all current matrices, so that further operations won't affect them directly.
+     * If another set of matrices already exist, they are used; otherwise, a new set is allocated.
+     * After a new set of matrices has been secured, all current values are copied into the new set.
+     * 
+     * See also Jax.MatrixStack#pop()
+     **/
+    push: function() { pushMatrix(this); },
+
+    /**
+     * Reverts back to an earlier matrix stack, effectively undoing any changes that have been made
+     * since the most recent call to Jax.MatrixStack#push().
+     **/
+    pop: function() { this.depth--; },
+
+    /**
+     * Jax.MatrixStack#reset() -> Jax.MatrixStack
+     * 
+     * Resets the stack depth to zero, effectively undoing all calls to #push().
+     **/
+    reset: function() { this.depth = 0; },
+
+    /**
+     * Jax.MatrixStack#loadModelMatrix(matr) -> Jax.MatrixStack
+     * - matr (mat4): the new matrix values
+     * Replaces the current model matrix with the specified one.
+     * Updates the inverse model matrix, the modelview matrix, the inverse modelview matrix and the normal matrix.
+     **/
+    loadModelMatrix: function(values) { loadMatrix(this, MODEL, values); return this; },
+
+    /**
+     * Jax.MatrixStack#loadViewMatrix(matr) -> Jax.MatrixStack
+     * - matr (mat4): the new matrix values
+     * Replaces the current view matrix with the specified one.
+     * Updates the inverse view matrix, the modelview matrix, the inverse modelview matrix and the normal matrix.
+     **/
+    loadViewMatrix: function(values) { loadMatrix(this, VIEW, values); return this; },
+
+    /**
+     * Jax.MatrixStack#loadProjectionMatrix(matr) -> Jax.MatrixStack
+     * - matr (mat4): the new matrix values
+     * Replaces the current projection matrix with the specified one.
+     * Updates the inverse projection matrix.
+     **/
+    loadProjectionMatrix: function(values) { loadMatrix(this, PROJECTION, values); return this; },
+
+    /**
+     * Jax.MatrixStack#multModelMatrix(matr) -> Jax.MatrixStack
+     * - matr (mat4): the matrix values
+     * Multiplies the current model matrix with the specified one.
+     * Updates the inverse model matrix, the modelview matrix, the inverse modelview matrix and the normal matrix.
+     **/
+    multModelMatrix: function(values) { multMatrix(this, MODEL, values); return this; },
+
+    /**
+     * Jax.MatrixStack#multViewMatrix(matr) -> Jax.MatrixStack
+     * - matr (mat4): the matrix values
+     * Multiplies the current view matrix with the specified one.
+     * Updates the inverse view matrix, the modelview matrix, the inverse modelview matrix and the normal matrix.
+     **/
+    multViewMatrix: function(values) { multMatrix(this, VIEW, values); return this; },
+
+    /**
+     * Jax.MatrixStack#multProjectionMatrix(matr) -> Jax.MatrixStack
+     * - matr (mat4): the matrix values
+     * Multiplies the current projection matrix with the specified one.
+     * Updates the inverse projection matrix.
+     **/
+    multProjectionMatrix: function(values) { multMatrix(this, PROJECTION, values); return this; },
+    
+    /**
+     * Jax.MatrixStack#getModelMatrix() -> mat4
+     * 
+     * the local model transformation matrix. Most models will manipulate this matrix. Multiplying an object-space
+     * coordinate by this matrix will result in a world-space coordinate.
+     **/
+    getModelMatrix: function() { return this.matrices.model[this.depth]; },
+    
+    /**
+     * Jax.MatrixStack#getInverseModelMatrix() -> mat4
+     * 
+     * the opposite of the local model transformation matrix. Multiplying a point in world space against this matrix
+     * will result in an object relative to the current object space.
+     **/
+    getInverseModelMatrix: function() { return this.matrices.inverse_model[this.depth]; },
+
+    /**
+     * Jax.MatrixStack#getNormalMatrix() -> mat3
+     * 
+     * the inverse transpose of the modelview matrix. See
+     *   http://www.lighthouse3d.com/tutorials/glsl-tutorial/the-normal-matrix/
+     * for a good writeup of where and how this matrix is useful. Multiplying a 3D _directional_ (not _positional)
+     * vector against this matrix will result in a 3D _directional_ vector in eye space.
+     **/
+    getNormalMatrix: function() { return this.matrices.normal[this.depth]; },
+    
+    /**
+     * Jax.MatrixStack#getViewMatrix() -> mat4
+     * 
+     * aka the camera matrix. Multiplying a point in eye space (e.g. relative to the camera) against the view matrix
+     * results in a point in world space.
+     **/
+    getViewMatrix: function() { return this.matrices.view[this.depth]; },
+    
+    /**
+     * Jax.MatrixStack#getInverseViewMatrix() -> mat4
+     * 
+     * the opposite of the camera matrix. Multiplying a point in world space against this matrix
+     * will result in a point in eye space (relative to camera).
+     **/
+    getInverseViewMatrix: function() { return this.matrices.inverse_view[this.depth]; },
+
+    /**
+     * Jax.MatrixStack#getModelViewMatrix() -> mat4
+     * 
+     * the only matrix OpenGL actually cares about, the modelview matrix. A combination of both model and view
+     * matrices, equivalent to mat4.multiply(view, model). (OpenGL matrix operations are read from right-to-left.)
+     * 
+     * Multiplying a point in object space by this matrix will effectively skip the world space transformation,
+     * resulting in a coordinate placed directly into eye space. This has the obvious advantage of being faster
+     * than performing the operation in two steps (model and then view).
+     **/
+    getModelViewMatrix: function() { return this.matrices.modelview[this.depth]; },
+    
+    /**
+     * Jax.MatrixStack#getInverseModelViewMatrix() -> mat4
+     * 
+     * The opposite of the modelview matrix. Multiplying an eye-space coordinate by this matrix results in an
+     * object-space coordinate.
+     **/
+    getInverseModelViewMatrix: function() { return this.matrices.inverse_modelview[this.depth]; },
+        
+    /**
+     * Jax.MatrixStack#getProjectionMatrix() -> mat4
+     * 
+     * aka the screen matrix. Multiplying a point in eye space against the projection matrix results in a 4D
+     * vector in clip space. Dividing clip coordinates (XYZ) by the 4th component (W) yields a 3D vector in
+     * normalized device coordinates, where all components are in the range [-1,1]. These points are ultimately
+     * multiplied by screen dimensions to find a pixel position.
+     **/
+    getProjectionMatrix: function() { return this.matrices.projection[this.depth]; },
+
+    /**
+     * Jax.MatrixStack#getModelViewProjectionMatrix() -> mat4
+     * 
+     * Returns the model, view and projection matrices combined into one.
+     **/
+    getModelViewProjectionMatrix: function() { return this.matrices.modelview_projection[this.depth]; },
+        
+    /**
+     * Jax.MatrixStack#getInverseProjectionMatrix() -> mat4
+     * 
+     * the opposite of the projection matrix. Multiplying a 4D vector in normalized device coordinates by
+     * its 4th component will result in clip space coordinates. Multiplying these clip space coordinates by the inverse
+     * projection matrix will result in a point in eye space, relative to the camera.
+     **/
+    getInverseProjectionMatrix: function() { return this.matrices.inverse_projection[this.depth]; },
+    
+    initialize: function() {
+      this.depth = 0;
+      
+      this.matrices = {
+        /* matrix depth, essentially the array index representing the current level in the stack. */
+        model: [mat4.create()],
+        inverse_model: [mat4.create()],
+        normal: [mat3.create()],
+        view: [mat4.create()],
+        inverse_view: [mat4.create()],
+        modelview: [mat4.create()],
+        inverse_modelview: [mat4.create()],
+        projection: [mat4.create()],
+        inverse_projection: [mat4.create()],
+        modelview_projection: [mat4.create()]
+      };
+      
+      this.loadModelMatrix(Jax.IDENTITY_MATRIX);
+      this.loadViewMatrix(Jax.IDENTITY_MATRIX);
+      this.loadProjectionMatrix(Jax.IDENTITY_MATRIX); // there's no known data about the viewport at this time.
+    }
+  });
+})();

data/src/jax/core/util.js

@@ -0,0 +1,226 @@
+/**
+ * Jax.Util
+ * Contains general-purpose utility and helper functions
+ **/
+Jax.Util = {
+  /**
+   * Jax.Util.vectorize(object) -> vec3
+   * - object (Object): any Object
+   *
+   * Analyzes the input object and returns a vec3 based on its contents. Input can be any of the following:
+   *   * a vec3
+   *   * an array
+   *   * an object with {x, y, z} properties
+   *   * an object with {0, 1, 2} properties
+   *   * a string delimited with any combination of commas, spaces and/or tab characters. Examples:
+   *     "x,y,z"
+   *     "x y z"
+   *     "x, y, z"
+   *     "x\ty\tz"
+   *     "x, \ty, \tz"
+   **/
+  vectorize: function(data) {
+    if (data) {
+      var res = vec3.create();
+      if (typeof(data) == "string") {
+        var components = data.split(/[,\s]+/);
+        if (components.length >= 3) {
+          for (var i = 0; i < 3; i++)
+            res[i] = parseFloat(components[i]);
+        }
+        return res;
+      }
+      if (data.length && data.length >= 3) return vec3.set(data, res);
+      if ((res[0] = data.x) != undefined && (res[1] = data.y) != undefined && (res[2] = data.z) != undefined) return res;
+      if ((res[0] = data[0]) != undefined && (res[1] = data[1]) != undefined && (res[2] = data[2]) != undefined) return res;
+    }
+    throw new Error("Input argument for Jax.Util.vectorize not recognized: "+JSON.stringify(data));
+  },
+
+  /**
+   * Jax.Util.colorize(object) -> vec4
+   * - object (Object): any Object
+   *
+   * Analyzes the input object and returns a 4-component color vector based on its contents. Input can be any of the
+   * following:
+   *   * an array
+   *   * an object with {r, g, b, a} properties
+   *   * an object with {0, 1, 2, 3} properties
+   *   * a string delimited with any combination of commas, spaces and/or tab characters. Examples:
+   *     "r,g,b,a"
+   *     "r g b a" 
+   *     "r, g, b, a"
+   *     "r\tg\tb\ta"
+   *     "r, \tg, \tb, \ta"
+   *     
+   * In all cases, if the alpha component is omitted, it defaults to 1.0.
+   **/
+  colorize: function(data) {
+    if (data) {
+      var res = [0,0,0,0];
+
+      if (typeof(data) == "string") {
+        var components = data.split(/[,\s]+/);
+        if (components.length >= 3) {
+          for (var i = 0; i < 4; i++)
+            if (components.length <= i)
+              res[i] = 1.0;
+            else
+              res[i] = parseFloat(components[i]);
+        }
+        return res;
+      }
+      if (data.length && data.length >= 3) {
+        res[0] = data[0];
+        res[1] = data[1];
+        res[2] = data[2];
+        if ((res[3] = data[3]) == undefined) res[3] = 1.0;
+        else res[3] = 1.0;
+        return res;
+      }
+      if ((res[0] = data.r) != undefined && (res[1] = data.g) != undefined && (res[2] = data.b) != undefined) {
+        if ((res[3] = data.a) == undefined) res[3] = 1.0;
+        return res;
+      }
+      if ((res[0] = data.red) != undefined && (res[1] = data.green) != undefined && (res[2] = data.blue) != undefined) {
+        if ((res[3] = data.alpha) == undefined) res[3] = 1.0;
+        return res;
+      }
+      if ((res[0] = data[0]) != undefined && (res[1] = data[1]) != undefined && (res[2] = data[2]) != undefined) {
+        if ((res[3] = data[3]) == undefined) res[3] = 1.0;
+        return res;
+      }
+    }
+    throw new Error("Input argument for Jax.Util.colorize not recognized: "+JSON.stringify(data));
+  },
+  
+  /**
+   * Jax.Util.properties(object) -> Array
+   * - object (Object): any Object
+   * 
+   * Returns an array containing the names of all properties in the specified object.
+   **/
+  properties: function(object) {
+    var arr = [];
+    for (var i in object)
+      arr.push(i);
+    return arr;
+  },
+  
+  /**
+   * Jax.Util.merge(incoming, outgoing) -> outgoing
+   * Merges the two objects by copying all properties from _incoming_ into _outgoing_, replacing
+   * any properties that already exist. _outgoing_ will retain any properties that do not exist
+   * in _incoming_.
+   **/
+  merge: function(src, dst) {
+    if (!src) return;
+    var i, j, n;
+
+    function doComparison(i) {
+      if (src[i] == null) dst[i] = null;
+      else if (src[i].klass)           dst[i] = src[i];
+      else if (Object.isArray(src[i])) Jax.Util.merge(src[i], dst[i] = dst[i] || []);
+      else if (typeof(src[i]) == "object") {
+        if (Object.isArray(dst[i])) {
+          n = {};
+          for (j = 0; j < dst[i].length; j++) n[j] = dst[i][j];
+          dst[i] = n;
+        }
+        Jax.Util.merge(src[i], dst[i] = dst[i] || {});
+      }
+      else dst[i] = src[i];
+    }
+    
+    if (Object.isArray(src)) for (i = 0; i < src.length; i++) doComparison(i);
+    else for (i in src) doComparison(i);
+
+    return dst;
+  },
+  
+  /**
+   * Jax.Util.normalizeOptions(incoming, defaults) -> Object
+   * Receives incoming and formats it into a generic Object with a structure representing the given defaults.
+   * The returned object is always a brand-new object, to avoid polluting original incoming object.
+   * If the object contains a Jax.Class instance, that actual object is copied over. All other objects
+   * are cloned into brand-new objects.
+   **/
+  normalizeOptions: function(incoming, defaults) {
+    var result = {};
+    Jax.Util.merge(defaults, result);
+    Jax.Util.merge(incoming, result);
+    return result;
+  },
+
+  /**
+   * Jax.Util.sizeofFormat(glEnum) -> Number
+   * 
+   * Returns the byte size of an array consisting of this type of element.
+   * 
+   * Example:
+   * 
+   *     Jax.Util.sizeofFormat(GL_RGB)
+   *     //=> 3
+   *
+   * If this isn't a recognized format, it is passed off to Jax.Util.enumName and an error is thrown. 
+   **/
+  sizeofFormat: function(glEnum) {
+    switch(glEnum) {
+      case GL_ALPHA: return 1;           // alpha component only
+      case GL_LUMINANCE: return 1;       // luminance component only
+      case GL_RGB: return 3;             // RGB triplet
+      case GL_RGBA: return 4;            // all 4 components
+      case GL_LUMINANCE_ALPHA: return 2; // luminance/alpha pair
+    }
+    throw new Error("Unrecognized format: "+Jax.Util.enumName(glEnum));
+  },
+
+  /**
+   * Jax.Util.enumName(glEnum) -> String
+   * - glEnum (GLenum): a WebGL enumeration, presumably numeric.
+   * 
+   * Returns the name of the enumeration prefixed with "GL_" that shares a value with the passed-in enum.
+   * 
+   * If the enum can't be found (this happens sometimes when an enum crops up that isn't in the WebGL spec),
+   * then a string containing both the decimal and hexadecimal form of this enum is returned:
+   * 
+   *     "(unrecognized enum: 36059 [0x8cdb])"
+   * 
+   * This is primarily for debugging and error reporting.
+   **/
+  enumName: function(glEnum) {
+    for (var i in window) {
+      if (i.indexOf("GL_") == 0 && window[i] == glEnum)
+        return i;
+    }
+    return "(unrecognized enum: "+glEnum+" [0x"+parseInt(glEnum).toString(16)+"])";
+  },
+
+  /**
+   * Jax.Util.addRequestedHelpers(klass) -> Array
+   * - klass (Jax.Class): A class into which to mix the helpers.
+   *
+   * First, if +ApplicationHelper+ is defined, it is automatically mixed into the specified class.
+   *
+   * Then, the class is searched for a #helpers method; if it exists, it is expected to return an array of
+   * Helpers (created with +Jax.Helper.create({...})+ ). Each element in the array returned by #helpers is
+   * then mixed into the class.
+   *
+   * An array of all helpers that were just mixed into the target class is returned.
+   **/
+  addRequestedHelpers: function(klass) {
+    var helpers = [];
+    if (typeof(ApplicationHelper) != "undefined") {
+      helpers.push(ApplicationHelper);
+      klass.addMethods(ApplicationHelper);
+    }
+    if (klass.prototype.helpers) {
+      var helper_array = klass.prototype.helpers.call(klass);
+      for (var i = 0; i < helper_array.length; i++) {
+        helpers.push(helper_array[i]);
+        klass.addMethods(helper_array[i]);
+      }
+    }
+    return helpers;
+  }
+};