jax 0.0.0.5 → 0.0.0.6

data/src/jax/compatibility.js

@@ -1,4 +1,28 @@
 /* Defines constants, functions, etc. that may exist in one browser but not in another */
+/**
+ * Jax.Compatibility
+ * Contains values used for cross-browser compatibility.
+ **/
+Jax.Compatibility = (function() {
+  var offsetTop = 1;
+  var offsetLeft = 1;
+  
+  return {
+    /**
+     * Jax.Compatibility.offsetTop -> Number
+     * Some browsers have different values for +offsetTop+. Jax must track these
+     * changes in order to ensure that the reported mouse coordinates are accurate.
+     **/
+    offsetTop: offsetTop,
+  
+    /**
+     * Jax.Compatibility.offsetLeft -> Number
+     * Some browsers have different values for +offsetLeft+. Jax must track these
+     * changes in order to ensure that the reported mouse coordinates are accurate.
+     **/
+    offsetLeft: offsetLeft,
+  };
+})();
 
 /*
   Object.keys defined only in the newest browsers. If they're going to fail, let them fail due to HTML5 incompatibility
@@ -13,10 +37,149 @@ if (!Object.keys) {
   };
 }
 
+/**
+ * Array#clear() -> Array
+ * Removes all objects from this array and returns itself, now empty.
+ **/
+Array.prototype.clear = Array.prototype.clear || function() {
+  this.splice(0, this.length);
+  return this;
+};
+
 
 /* KeyEvent in Firefox contains various keyCode constants, but they are missing in Chrome. */
 if (typeof(KeyEvent) == "undefined") {
-  // KeyEvent constants taken from Firefox 3.6
+  /**
+   * Global.KeyEvent
+   *
+   * By default, Firefox defines a global +KeyEvent+ namespace containing character codes
+   * for use with keyboard events. These are very useful for comparison with +event.keyCode+,
+   * but are not supported by other browsers.
+   *
+   * In the event that a browser other than Firefox is used, Jax defines a fake +KeyEvent+
+   * namespace to be used in its place. The constants contained within are taken from
+   * Firefox 3.6, with the addition of the boolean +fake+, which is always true unless
+   * the client is using Firefox.
+   *
+   * The individual values of the following constants may be different from one client to another:
+   *
+   *     KeyEvent.DOM_VK_CANCEL
+   *     KeyEvent.DOM_VK_HELP
+   *     KeyEvent.DOM_VK_BACK_SPACE
+   *     KeyEvent.DOM_VK_TAB
+   *     KeyEvent.DOM_VK_CLEAR
+   *     KeyEvent.DOM_VK_RETURN
+   *     KeyEvent.DOM_VK_ENTER
+   *     KeyEvent.DOM_VK_SHIFT
+   *     KeyEvent.DOM_VK_CONTROL
+   *     KeyEvent.DOM_VK_ALT
+   *     KeyEvent.DOM_VK_PAUSE
+   *     KeyEvent.DOM_VK_CAPS_LOCK
+   *     KeyEvent.DOM_VK_ESCAPE
+   *     KeyEvent.DOM_VK_SPACE
+   *     KeyEvent.DOM_VK_PAGE_UP
+   *     KeyEvent.DOM_VK_PAGE_DOWN
+   *     KeyEvent.DOM_VK_END
+   *     KeyEvent.DOM_VK_HOME
+   *     KeyEvent.DOM_VK_LEFT
+   *     KeyEvent.DOM_VK_UP
+   *     KeyEvent.DOM_VK_RIGHT
+   *     KeyEvent.DOM_VK_DOWN
+   *     KeyEvent.DOM_VK_PRINTSCREEN
+   *     KeyEvent.DOM_VK_INSERT
+   *     KeyEvent.DOM_VK_DELETE
+   *     KeyEvent.DOM_VK_0
+   *     KeyEvent.DOM_VK_1
+   *     KeyEvent.DOM_VK_2
+   *     KeyEvent.DOM_VK_3
+   *     KeyEvent.DOM_VK_4
+   *     KeyEvent.DOM_VK_5
+   *     KeyEvent.DOM_VK_6
+   *     KeyEvent.DOM_VK_7
+   *     KeyEvent.DOM_VK_8
+   *     KeyEvent.DOM_VK_9
+   *     KeyEvent.DOM_VK_SEMICOLON
+   *     KeyEvent.DOM_VK_EQUALS
+   *     KeyEvent.DOM_VK_A
+   *     KeyEvent.DOM_VK_B
+   *     KeyEvent.DOM_VK_C
+   *     KeyEvent.DOM_VK_D
+   *     KeyEvent.DOM_VK_E
+   *     KeyEvent.DOM_VK_F
+   *     KeyEvent.DOM_VK_G
+   *     KeyEvent.DOM_VK_H
+   *     KeyEvent.DOM_VK_I
+   *     KeyEvent.DOM_VK_J
+   *     KeyEvent.DOM_VK_K
+   *     KeyEvent.DOM_VK_L
+   *     KeyEvent.DOM_VK_M
+   *     KeyEvent.DOM_VK_N
+   *     KeyEvent.DOM_VK_O
+   *     KeyEvent.DOM_VK_P
+   *     KeyEvent.DOM_VK_Q
+   *     KeyEvent.DOM_VK_R
+   *     KeyEvent.DOM_VK_S
+   *     KeyEvent.DOM_VK_T
+   *     KeyEvent.DOM_VK_U
+   *     KeyEvent.DOM_VK_V
+   *     KeyEvent.DOM_VK_W
+   *     KeyEvent.DOM_VK_X
+   *     KeyEvent.DOM_VK_Y
+   *     KeyEvent.DOM_VK_Z
+   *     KeyEvent.DOM_VK_CONTEXT_MENU
+   *     KeyEvent.DOM_VK_NUMPAD0
+   *     KeyEvent.DOM_VK_NUMPAD1
+   *     KeyEvent.DOM_VK_NUMPAD2
+   *     KeyEvent.DOM_VK_NUMPAD3
+   *     KeyEvent.DOM_VK_NUMPAD4
+   *     KeyEvent.DOM_VK_NUMPAD5
+   *     KeyEvent.DOM_VK_NUMPAD6
+   *     KeyEvent.DOM_VK_NUMPAD7
+   *     KeyEvent.DOM_VK_NUMPAD8
+   *     KeyEvent.DOM_VK_NUMPAD9
+   *     KeyEvent.DOM_VK_MULTIPLY
+   *     KeyEvent.DOM_VK_ADD
+   *     KeyEvent.DOM_VK_SEPARATOR
+   *     KeyEvent.DOM_VK_SUBTRACT
+   *     KeyEvent.DOM_VK_DECIMAL
+   *     KeyEvent.DOM_VK_DIVIDE
+   *     KeyEvent.DOM_VK_F1
+   *     KeyEvent.DOM_VK_F2
+   *     KeyEvent.DOM_VK_F3
+   *     KeyEvent.DOM_VK_F4
+   *     KeyEvent.DOM_VK_F5
+   *     KeyEvent.DOM_VK_F6
+   *     KeyEvent.DOM_VK_F7
+   *     KeyEvent.DOM_VK_F8
+   *     KeyEvent.DOM_VK_F9
+   *     KeyEvent.DOM_VK_F10
+   *     KeyEvent.DOM_VK_F11
+   *     KeyEvent.DOM_VK_F12
+   *     KeyEvent.DOM_VK_F13
+   *     KeyEvent.DOM_VK_F14
+   *     KeyEvent.DOM_VK_F15
+   *     KeyEvent.DOM_VK_F16
+   *     KeyEvent.DOM_VK_F17
+   *     KeyEvent.DOM_VK_F18
+   *     KeyEvent.DOM_VK_F19
+   *     KeyEvent.DOM_VK_F20
+   *     KeyEvent.DOM_VK_F21
+   *     KeyEvent.DOM_VK_F22
+   *     KeyEvent.DOM_VK_F23
+   *     KeyEvent.DOM_VK_F24
+   *     KeyEvent.DOM_VK_NUM_LOCK
+   *     KeyEvent.DOM_VK_SCROLL_LOCK
+   *     KeyEvent.DOM_VK_COMMA
+   *     KeyEvent.DOM_VK_PERIOD
+   *     KeyEvent.DOM_VK_SLASH
+   *     KeyEvent.DOM_VK_BACK_QUOTE
+   *     KeyEvent.DOM_VK_OPEN_BRACKET
+   *     KeyEvent.DOM_VK_BACK_SLASH
+   *     KeyEvent.DOM_VK_CLOSE_BRACKET
+   *     KeyEvent.DOM_VK_QUOTE
+   *     KeyEvent.DOM_VK_META
+   *
+   **/
   KeyEvent = {
     fake: true,
     DOM_VK_CANCEL : 3,
@@ -137,4 +300,4 @@ if (typeof(KeyEvent) == "undefined") {
   };
   
   /* TODO handle special cases -- see http://www.javascripter.net/faq/keycodes.htm */
-}
+}

data/src/jax/context.js

@@ -32,12 +32,47 @@ Jax.Context = (function() {
     if (!self.gl) throw new Error("WebGL could not be initialized!");
   }
   
+  function updateFramerate(self) {
+    var current_render_start = Jax.uptime;
+    if (!self.last_render_start) self.last_render_start = Jax.uptime;
+    var time_to_render_this_frame = current_render_start - self.last_render_start;
+    
+    self.time_to_render = (self.time_to_render || 0) * self.framerate_sample_ratio
+                        + time_to_render_this_frame * (1 - self.framerate_sample_ratio);
+    
+    // frames per second = 1 second divided by time to render; time is currently in ms so 1sec = 1000ms
+    self.framerate = self.frames_per_second = 1.0 / self.time_to_render;
+    self.last_render_start = current_render_start;
+  }
+  
+  function updateUpdateRate(self) {
+    var current_update_start = Jax.uptime;
+    if (!self.last_update_start) self.last_update_start = current_update_start;
+    var time_to_update_this_frame = current_update_start - self.last_update_start;
+    
+    if (self.calculateUpdateRate) {
+      self.time_to_update = (self.time_to_update || 0) * self.framerate_sample_ratio
+                          + time_to_update_this_frame * (1 - self.framerate_sample_ratio);
+                        
+      // update rate = seconds / time
+      self.updates_per_second = 1.0 / self.time_to_update;
+    }
+    
+    // in order to avoid recalculating the above for updates, we'll return the timechange
+    // to be used in subsequent updates.
+    var timechange = current_update_start - self.last_update_start;
+    self.last_update_start = current_update_start;
+    return timechange;
+  }
+  
   function startRendering(self) {
     function render() {
+      if (self.calculateFramerate) updateFramerate(self);
       if (self.current_view) {
-        reloadMatrices(self);
-        self.glViewport(0, 0, self.canvas.width, self.canvas.height);
+        self.prepare();
         self.current_view.render();
+        var len = self.afterRenderFuncs.length;
+        for (var i = 0; i < len; i++) self.afterRenderFuncs[i].call(self);
         self.render_interval = requestAnimFrame(render, self.canvas);
       }
       else {
@@ -55,12 +90,11 @@ Jax.Context = (function() {
   
   function startUpdating(self) {
     function updateFunc() {
-      if (!self.lastUpdate) self.lastUpdate = new Date();
-      var now = new Date();
-      var timechange = (now - self.lastUpdate) / 1000.0;
-      self.lastUpdate = now;
+      var timechange = updateUpdateRate(self);
       
       self.update(timechange);
+      var len = self.afterUpdateFuncs.length;
+      for (var i = 0; i < len; i++) self.afterUpdateFuncs[i].call(self);
       self.update_interval = setTimeout(updateFunc, Jax.update_speed);
     }
     updateFunc();
@@ -86,7 +120,7 @@ Jax.Context = (function() {
   function reloadMatrices(self) {
     self.matrix_stack.reset(); // reset depth
     self.matrix_stack.loadModelMatrix(Jax.IDENTITY_MATRIX);
-    self.matrix_stack.loadViewMatrix(self.player.camera.getModelViewMatrix());
+    self.matrix_stack.loadViewMatrix(self.player.camera.getTransformationMatrix());
     self.matrix_stack.loadProjectionMatrix(self.player.camera.getProjectionMatrix());
   }
   
@@ -111,18 +145,100 @@ Jax.Context = (function() {
       this.player.camera.perspective({width:canvas.width, height:canvas.height});
       this.matrix_stack = new Jax.MatrixStack();
       this.current_pass = Jax.Scene.AMBIENT_PASS;
+      this.afterRenderFuncs = [];
+      this.afterUpdateFuncs = [];
+      this.framerate = 0;
+      this.frames_per_second = 0;
+      this.updates_per_second = 0;
+      
+      /**
+       * Jax.Context#framerate_sample_ratio -> Number
+       *
+       * A number between 0 and 1, to be used in updates to frames per second and updates per second.
+       *
+       * Setting this to a high value will produce "smoother" results; they will change less frequently,
+       * but it will take longer to get initial results. High values are better for testing framerate
+       * over the long term, while lower values are better for testing small disruptions in framerate
+       * (such as garbage collection).
+       *
+       * Defaults to 0.9.
+       **/
+      this.framerate_sample_ratio = 0.9;
       
       startUpdating(this);
       if (Jax.routes.isRouted("/"))
         this.redirectTo("/");
     },
     
+    /**
+     * Jax.Context#getFramesPerSecond() -> Number
+     * The average number of frames rendered in one second.
+     *
+     * Implicitly enables calculation of frames-per-second, which is initially disabled by default
+     * to improve performance.
+     **/
+    getFramesPerSecond: function() { this.calculateFramerate = true; return this.frames_per_second; },
+     
+    /**
+     * Jax.Context#getUpdatesPerSecond() -> Number
+     * The average number of updates performed in one second. See also Jax.Context#getFramesPerSecond().
+     *
+     * Implicitly enables calculation of updates-per-second, which is initially disabled by default
+     * to improve performance.
+     **/
+    getUpdatesPerSecond: function() { this.calculateUpdateRate = true; return this.updates_per_second; },
+    
+    /**
+     * Jax.Context#disableFrameSpeedCalculations() -> Jax.Context
+     * Disables calculation of frames-per-second. Note that this calculation is disabled by default
+     * to improve performance, so you should only need to call this if you've previously called
+     * Jax.Context#getUpdatesPerSecond().
+     **/
+    disableFrameSpeedCalculations: function() { this.calculateFramerate = false; },
+    
+    /**
+     * Jax.Context#disableUpdateSpeedCalculations() -> Jax.Context
+     * Disables calculation of updates-per-second. Note that this calculation is disabled by default
+     * to improve performance, so you should only need to call this if you've previously called
+     * Jax.Context#getUpdatesPerSecond().
+     **/
+    disableUpdateSpeedCalculations: function() { this.caclulateUpdateRate = false; },
+     
+    /**
+     * Jax.Context#afterRender(func) -> Jax.Context
+     * 
+     * Registers the specified function to be called immediately after every render pass.
+     * Returns this context.
+     *
+     * When the function is called, its +this+ object is set to the context itself.
+     **/
+    afterRender: function(func) {
+      this.afterRenderFuncs.push(func);
+    },
+    
+    /**
+     * Jax.Context#afterUpdate(func) -> Jax.Context
+     *
+     * Registers the specified function to be called immediately after every update pass.
+     * Returns this context.
+     *
+     * When the function is called, its +this+ object is set to the context itself.
+     **/
+    afterUpdate: function(func) {
+      this.afterUpdateFuncs.push(func);
+    },
+
+    /**
+     * Jax.Context#hasStencil() -> Boolean
+     *
+     * Returns true if this context supports stencil operations.
+     **/
     hasStencil: function() {
       return !!this.gl.stencil;
     },
 
     /**
-     * Jax.Context#redirectTo(path) -> Controller
+     * Jax.Context#redirectTo(path) -> Jax.Controller
      * - path (String): the path to redirect to
      * 
      * Redirects to the specified route, and then returns the Jax.Controller that
@@ -147,10 +263,36 @@ Jax.Context = (function() {
       return this.current_controller;
     },
     
+    /**
+     * Jax.Context#prepare() -> Jax.Context
+     * 
+     * Loads the matrices from +player.camera+ into the matrix stack, then
+     * sets up the viewport. This should be run prior to rendering anything.
+     * This is done automatically when the context has a View associated
+     * with it, but if there is no View then the render process will be
+     * halted, leaving it up to you to prepare the canvas explicitly.
+     **/
+    prepare: function() {
+      reloadMatrices(this);
+      this.glViewport(0, 0, this.canvas.width, this.canvas.height);
+    },
+
+    /**
+     * Jax.Context#update(timechange) -> Jax.Context
+     * - timechange (Number): the amount of time, in seconds, since the previous update
+     *
+     * Automatically called over time, this function will trigger an update
+     * of all controllers and objects attached to this context.
+     *
+     * You can programmatically trigger updates to these objects by calling
+     * this method directly. Doing this is useful for constructing consistent
+     * test cases.
+     **/
     update: function(timechange) {
       if (this.current_controller && this.current_controller.update)
         this.current_controller.update(timechange);
       this.world.update(timechange);
+      return this;
     },
 
     /**
@@ -186,11 +328,30 @@ Jax.Context = (function() {
     isDisposed: function() {
       return !!this.disposed;
     },
-    
+
+    /**
+     * Jax.Context#pushMatrix(yield_to) -> Jax.Context
+     * - yield_to (Function): a function to be called
+     *
+     * Pushes a new level onto the matrix stack and then calls the given function.
+     * After the function completes, the matrix stack is reverted back to its
+     * original state, effectively undoing any modifications made to the matrices
+     * in the meantime.
+     *
+     * Example:
+     *
+     *     context.pushMatrix(function() {
+     *       context.loadModelMatrix(Jax.IDENTITY_MATRIX);
+     *       context.multViewMatrix(this.camera.getTransformationMatrix());
+     *       // do some rendering
+     *     });
+     *     // matrix is restored to its previous state
+     **/
     pushMatrix: function(yield_to) {
       this.matrix_stack.push();
       yield_to();
       this.matrix_stack.pop();
+      return this;
     },
     
     /**
@@ -245,6 +406,12 @@ Jax.Context = (function() {
   /* set up matrix stack delegation */
   klass.delegate(/^(get|load|mult)(.*)Matrix$/).into("matrix_stack");
   
+  /** alias of: Jax.Context#getFramesPerSecond
+   * Jax.Context#getFramerate() -> Number
+   * The average numebr of frames rendered in one second.
+   **/
+  klass.prototype.getFramerate = klass.prototype.getFramesPerSecond;
+  
   return klass;
 })();
 

data/src/jax/core.js

@@ -5,9 +5,12 @@
 //= 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.
+/**
+ * Global#debugAssert(expr[, msg]) -> undefined
+ * 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)
   {