jax 0.0.0.1

data/src/jax/compatibility.js

@@ -0,0 +1,140 @@
+/* Defines constants, functions, etc. that may exist in one browser but not in another */
+
+/*
+  Object.keys defined only in the newest browsers. If they're going to fail, let them fail due to HTML5 incompatibility
+  and not standards compat.
+ */
+if (!Object.keys) {
+  Object.keys = function(object) {
+    var arr = [];
+    for (var i in object)
+      arr.push(i);
+    return arr;
+  };
+}
+
+
+/* KeyEvent in Firefox contains various keyCode constants, but they are missing in Chrome. */
+if (typeof(KeyEvent) == "undefined") {
+  // KeyEvent constants taken from Firefox 3.6
+  KeyEvent = {
+    fake: true,
+    DOM_VK_CANCEL : 3,
+    DOM_VK_HELP : 6,
+    DOM_VK_BACK_SPACE : 8,
+    DOM_VK_TAB : 9,
+    DOM_VK_CLEAR : 12,
+    DOM_VK_RETURN : 13,
+    DOM_VK_ENTER : 14,
+    DOM_VK_SHIFT : 16,
+    DOM_VK_CONTROL : 17,
+    DOM_VK_ALT : 18,
+    DOM_VK_PAUSE : 19,
+    DOM_VK_CAPS_LOCK : 20,
+    DOM_VK_ESCAPE : 27,
+    DOM_VK_SPACE : 32,
+    DOM_VK_PAGE_UP : 33,
+    DOM_VK_PAGE_DOWN : 34,
+    DOM_VK_END : 35,
+    DOM_VK_HOME : 36,
+    DOM_VK_LEFT : 37,
+    DOM_VK_UP : 38,
+    DOM_VK_RIGHT : 39,
+    DOM_VK_DOWN : 40,
+    DOM_VK_PRINTSCREEN : 44,
+    DOM_VK_INSERT : 45,
+    DOM_VK_DELETE : 46,
+    DOM_VK_0 : 48,
+    DOM_VK_1 : 49,
+    DOM_VK_2 : 50,
+    DOM_VK_3 : 51,
+    DOM_VK_4 : 52,
+    DOM_VK_5 : 53,
+    DOM_VK_6 : 54,
+    DOM_VK_7 : 55,
+    DOM_VK_8 : 56,
+    DOM_VK_9 : 57,
+    DOM_VK_SEMICOLON : 59,
+    DOM_VK_EQUALS : 61,
+    DOM_VK_A : 65,
+    DOM_VK_B : 66,
+    DOM_VK_C : 67,
+    DOM_VK_D : 68,
+    DOM_VK_E : 69,
+    DOM_VK_F : 70,
+    DOM_VK_G : 71,
+    DOM_VK_H : 72,
+    DOM_VK_I : 73,
+    DOM_VK_J : 74,
+    DOM_VK_K : 75,
+    DOM_VK_L : 76,
+    DOM_VK_M : 77,
+    DOM_VK_N : 78,
+    DOM_VK_O : 79,
+    DOM_VK_P : 80,
+    DOM_VK_Q : 81,
+    DOM_VK_R : 82,
+    DOM_VK_S : 83,
+    DOM_VK_T : 84,
+    DOM_VK_U : 85,
+    DOM_VK_V : 86,
+    DOM_VK_W : 87,
+    DOM_VK_X : 88,
+    DOM_VK_Y : 89,
+    DOM_VK_Z : 90,
+    DOM_VK_CONTEXT_MENU : 93,
+    DOM_VK_NUMPAD0 : 96,
+    DOM_VK_NUMPAD1 : 97,
+    DOM_VK_NUMPAD2 : 98,
+    DOM_VK_NUMPAD3 : 99,
+    DOM_VK_NUMPAD4 : 100,
+    DOM_VK_NUMPAD5 : 101,
+    DOM_VK_NUMPAD6 : 102,
+    DOM_VK_NUMPAD7 : 103,
+    DOM_VK_NUMPAD8 : 104,
+    DOM_VK_NUMPAD9 : 105,
+    DOM_VK_MULTIPLY : 106,
+    DOM_VK_ADD : 107,
+    DOM_VK_SEPARATOR : 108,
+    DOM_VK_SUBTRACT : 109,
+    DOM_VK_DECIMAL : 110,
+    DOM_VK_DIVIDE : 111,
+    DOM_VK_F1 : 112,
+    DOM_VK_F2 : 113,
+    DOM_VK_F3 : 114,
+    DOM_VK_F4 : 115,
+    DOM_VK_F5 : 116,
+    DOM_VK_F6 : 117,
+    DOM_VK_F7 : 118,
+    DOM_VK_F8 : 119,
+    DOM_VK_F9 : 120,
+    DOM_VK_F10 : 121,
+    DOM_VK_F11 : 122,
+    DOM_VK_F12 : 123,
+    DOM_VK_F13 : 124,
+    DOM_VK_F14 : 125,
+    DOM_VK_F15 : 126,
+    DOM_VK_F16 : 127,
+    DOM_VK_F17 : 128,
+    DOM_VK_F18 : 129,
+    DOM_VK_F19 : 130,
+    DOM_VK_F20 : 131,
+    DOM_VK_F21 : 132,
+    DOM_VK_F22 : 133,
+    DOM_VK_F23 : 134,
+    DOM_VK_F24 : 135,
+    DOM_VK_NUM_LOCK : 144,
+    DOM_VK_SCROLL_LOCK : 145,
+    DOM_VK_COMMA : 188,
+    DOM_VK_PERIOD : 190,
+    DOM_VK_SLASH : 191,
+    DOM_VK_BACK_QUOTE : 192,
+    DOM_VK_OPEN_BRACKET : 219,
+    DOM_VK_BACK_SLASH : 220,
+    DOM_VK_CLOSE_BRACKET : 221,
+    DOM_VK_QUOTE : 222,
+    DOM_VK_META: 224
+  };
+  
+  /* TODO handle special cases -- see http://www.javascripter.net/faq/keycodes.htm */
+}

data/src/jax/context.js

@@ -0,0 +1,253 @@
+//= require "webgl"
+//= require "events"
+
+/**
+ * class Jax.Context
+ * The highest level of operation in Jax. Initialization is simple:
+ * 
+ *     var context = new Jax.Context(canvas);
+ *     
+ * where _canvas_ is a reference to an HTML5 Canvas element.
+ * 
+ * If there is a root route set up, then at this point you are done.
+ * If not, there's an additional step:
+ * 
+ *     context.redirect_to("controller_name/action_name");
+ *     
+ * where *controller_name* is the short name of the controller to start at,
+ * and *action_name* is the action to fire within that controller.
+ * 
+ * Note that the specified redirect path must be registered in the route set.
+ * 
+ * Jax will automatically initialize and maintain a WebGL rendering bridge,
+ * and WebGL methods can be called directly on this context by prefixing
+ * the name of the method with "gl". For example:
+ * 
+ *     context.glClear(GL_COLOR_BIT | GL_DEPTH_BUFFER_BIT);
+ * 
+ **/
+Jax.Context = (function() {
+  function setupContext(self) {
+    try { self.gl = self.canvas.getContext(WEBGL_CONTEXT_NAME, WEBGL_CONTEXT_OPTIONS); } catch(e) { }
+    if (!self.gl) throw new Error("WebGL could not be initialized!");
+  }
+  
+  function startRendering(self) {
+    function render() {
+      if (self.current_view) {
+        reloadMatrices(self);
+        self.glViewport(0, 0, self.canvas.width, self.canvas.height);
+        self.current_view.render();
+        self.render_interval = requestAnimFrame(render, self.canvas);
+      }
+      else {
+        clearTimeout(self.render_interval);
+        self.render_interval = null;
+      }
+    }
+    
+    self.render_interval = setTimeout(render, Jax.render_speed);
+  }
+  
+  function stopRendering(self) {
+    clearTimeout(self.render_interval);
+  }
+  
+  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;
+      
+      self.update(timechange);
+      self.update_interval = setTimeout(updateFunc, Jax.update_speed);
+    }
+    updateFunc();
+  }
+  
+  function stopUpdating(self) {
+    clearTimeout(self.update_interval);
+  }
+    
+  function setupView(self, view) {
+    view.context = self;
+    view.world = self.world;
+    view.player = self.player;
+    for (var i in self) {
+      if (i.indexOf("gl") == 0) {
+        /* it's a WebGL method */
+        view[i] = eval("(function() { return this.context."+i+".apply(this.context, arguments); })");
+      }
+    }
+    /* TODO we should set up helpers, etc. here too */
+  }
+  
+  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.loadProjectionMatrix(self.player.camera.getProjectionMatrix());
+  }
+  
+  var klass = Jax.Class.create({
+    initialize: function(canvas) {
+      if (typeof(canvas) == "string") canvas = document.getElementById(canvas);
+      if (!canvas) throw new Error("Can't initialize a WebGL context without a canvas!");
+      this.id = ++Jax.Context.identifier;
+      this.canvas = canvas;
+      setupContext(this);
+      this.setupEventListeners();
+      this.render_interval = null;
+      this.glClearColor(0.0, 0.0, 0.0, 1.0);
+      this.glClearDepth(1.0);
+      this.glEnable(GL_DEPTH_TEST);
+      this.glDepthFunc(GL_LEQUAL);
+      this.glEnable(GL_BLEND);
+      this.glBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA);
+      this.checkForRenderErrors();
+      this.world = new Jax.World(this);
+      this.player = {camera: new Jax.Camera()};
+      this.player.camera.perspective({width:canvas.width, height:canvas.height});
+      this.matrix_stack = new Jax.MatrixStack();
+      this.current_pass = Jax.Scene.AMBIENT_PASS;
+      
+      startUpdating(this);
+      if (Jax.routes.isRouted("/"))
+        this.redirectTo("/");
+    },
+    
+    hasStencil: function() {
+      return !!this.gl.stencil;
+    },
+
+    /**
+     * Jax.Context#redirectTo(path) -> Controller
+     * - path (String): the path to redirect to
+     * 
+     * Redirects to the specified route, and then returns the Jax.Controller that
+     * was just redirected to. The act of redirecting will dispose of the current
+     * World, so be prepared to initialize a new scene.
+     **/
+    redirectTo: function(path) {
+      stopRendering(this);
+
+      this.world.dispose();
+      this.player.camera.reset();
+      /* yes, this is necessary. If the routing fails, controller must be null to prevent #update with a new world. */
+      this.current_controller = this.current_view = null;
+      this.current_controller = Jax.routes.dispatch(path, this);
+      if (!this.current_controller.view_key)
+        throw new Error("Controller '"+this.current_controller.getControllerName()+"' did not produce a renderable result");
+      this.current_view = Jax.views.find(this.current_controller.view_key);
+      
+      setupView(this, this.current_view);
+      if (!this.isRendering()) startRendering(this);
+      
+      return this.current_controller;
+    },
+    
+    update: function(timechange) {
+      if (this.current_controller && this.current_controller.update)
+        this.current_controller.update(timechange);
+      this.world.update(timechange);
+    },
+
+    /**
+     * Jax.Context#isRendering() -> Boolean
+     * Returns true if this Jax.Context currently has a render interval set.
+     * This will be false by default if there is no root route; otherwise
+     * it will be true. It is also enabled automatically upon the first
+     * valid redirect.
+     **/
+    isRendering: function() {
+      return this.render_interval != null;
+    },
+
+    /**
+     * Jax.Context#dispose() -> undefined
+     *
+     * Permanently disposes of this context, freeing the resources it is using.
+     * This stops actions from running, closes any open rendering contexts, and
+     * clears all other timeouts and intervals.
+     *
+     * A Jax.Context cannot be used once it is disposed.
+     **/
+    dispose: function() {
+      this.disposed = true;
+      stopRendering(this);
+      stopUpdating(this);
+    },
+
+    /**
+     * Jax.Context#isDisposed() -> Boolean
+     * Returns true if this context has been disposed.
+     **/
+    isDisposed: function() {
+      return !!this.disposed;
+    },
+    
+    pushMatrix: function(yield_to) {
+      this.matrix_stack.push();
+      yield_to();
+      this.matrix_stack.pop();
+    },
+    
+    /**
+     * Jax.Context#getViewMatrix() -> mat4
+     * Returns the view matrix. See Jax.MatrixStack#getViewMatrix for details.
+     **/
+    getViewMatrix: function() { return this.matrix_stack.getViewMatrix(); },
+    
+    /**
+     * Jax.Context#getInverseViewMatrix() -> mat4
+     * Returns the inverse view matrix. See Jax.MatrixStack#getInverseViewMatrix for details.
+     **/
+    getInverseViewMatrix: function() { return this.matrix_stack.getInverseViewMatrix(); },
+    
+    /**
+     * Jax.Context#getFrustum() -> Jax.Scene.Frustum
+     * Returns the frustum for the player's camera. Equivalent to calling
+     * 
+     *     context.player.camera.getFrustum()
+     *     
+     * Note that changes to the matrix via #multMatrix will not be represented
+     * in this Jax.Scene.Frustum.
+     **/
+    getFrustum: function() { return this.player.camera.frustum; },
+  
+    checkForRenderErrors: function() {
+      /* Error checking is slow, so don't do it in production mode */
+      if (Jax.environment == "production") return;
+
+      var error = this.glGetError();
+      if (error != GL_NO_ERROR)
+      {
+        var str = "GL error in "+this.canvas.id+": "+error;
+        error = new Error(str);
+        var message = error;
+        if (error.stack)
+        {
+          var stack = error.stack.split("\n");
+          stack.shift();
+          message += "\n\n"+stack.join("\n");
+        }
+        
+        throw error;
+      }
+    },
+    
+    handleRenderError: function(method_name, args, err) {
+      throw err;
+    }
+  });
+  
+  /* set up matrix stack delegation */
+  klass.delegate(/^(get|load|mult)(.*)Matrix$/).into("matrix_stack");
+  
+  return klass;
+})();
+
+Jax.Context.identifier = 0;
+Jax.Context.addMethods(GL_METHODS);
+Jax.Context.addMethods(Jax.EVENT_METHODS);

data/src/jax/controller.js

@@ -0,0 +1,157 @@
+/**
+ * class Jax.Controller
+ * Controllers are a major component of the Jax framework, because they are in
+ * charge of receiving input from the user, setting up a scene, tearing it down,
+ * and deciding when is the right time to transition to a different controller.
+ * 
+ * Controllers need to be either registered with Jax.routes or invoked using
+ * Jax.Controller.invoke(). They are not intended to be instantiated directly,
+ * so you should avoid doing this in your code and instead rely on the route set.
+ * 
+ * Methods added to controllers are called actions. You can name actions whatever
+ * you want, but some action names serve special purposes. They are as follows:
+ * 
+ *   * *index*          - called when the action name is omitted from a route.
+ *   * *destroy*        - called when leaving the current controller.
+ *   * *mouse_clicked*  - called when the mouse is clicked within the canvas.
+ *   * *mouse_entered*  - called when the mouse enters the canvas.
+ *   * *mouse_exited*   - called when the mouse exits the canvas.
+ *   * *mouse_moved*    - called when the mouse is moved, unless a button is pressed.
+ *   * *mouse_dragged*  - called when the mouse is moved while a button is pressed.
+ *   * *mouse_pressed*  - called when a mouse button has been pressed.
+ *   * *mouse_released* - called when a mouse button has been released.
+ *   * *mouse_clicked*  - called when a mouse button has been clicked.
+ *   * *key_pressed*    - called when a keyboard button has been pressed.
+ *   * *key_released*   - called when a keyboard button has been released.
+ *   * *key_typed*      - called when a keyboard button has been typed.
+ *   * *update*         - called (approximately) every 60 milliseconds for as long
+ *   as a controller is active. Time difference in seconds is passed as an arguments.
+ *   
+ * Example:
+ * 
+ *     var WelcomeController = Jax.Controller.Create("welcome", ApplicationController, {
+ *       index: function() {
+ *         // ...
+ *       },
+ *       
+ *       mouse_clicked: function(event) {
+ *         // ...
+ *       },
+ *       
+ *       update: function(timechange) {
+ *        // it's been [timechange] seconds since last update
+ *       }
+ *     });
+ *
+ * With the exception of event actions, which will be fired every time an event occurs,
+ * controller actions are only triggered once for a given controller unless they
+ * explicitly trigger other actions by calling them directly. They differ from their
+ * corresponding views (see Jax.View) in this way, as a view is rendered many times
+ * -- up to a target rate of 60 passes per second.
+ **/
+(function() {
+  var protected_instance_method_names = [
+    'initialize', 'toString', 'getControllerName', 'constructor', 'isKindOf', 'fireAction',
+    'eraseResult'
+  ];
+  
+  function is_protected(method_name) {
+    for (var i = 0; i < protected_instance_method_names.length; i++)
+      if (protected_instance_method_names[i] == method_name)
+        return true;
+    return false;
+  }
+  
+  Jax.Controller = (function() {
+    function setViewKey(self) {
+      self.view_key = self.getControllerName()+"/"+self.action_name;
+      self.rendered_or_redirected = true;
+    }
+    
+    return Jax.Class.create({
+      fireAction: function(action_name) {
+        this.eraseResult();
+        this.action_name = action_name;
+
+        if (this[action_name])
+          this[action_name].call(this, []);
+        else throw new Error("Call to missing action: '"+action_name+"' in controller '"+this.getControllerName()+"'");
+        
+        if (!this.rendered_or_redirected)
+          setViewKey(this);
+      },
+      
+      eraseResult: function() {
+        this.rendered_or_redirected = false;
+        this.view_key = null;
+      }
+    });
+  })();
+
+  var controller_class_methods = {
+    invoke: function(action_name, context) {
+      var instance = new this();
+      instance.context = context;
+      instance.world = context && context.world;
+      instance.player = context && context.player;
+      instance.fireAction(action_name);
+      return instance;
+    }
+  };
+
+  /**
+   * Jax.Controller.create(controllerName, methods) -> Class
+   * Jax.Controller.create(controllerName, superclass, methods) -> Class
+   * - controllerName (String): the short name of this controller
+   * - superclass (Class): a parent class to inherit from
+   * - methods (Object): a set of methods to be added to the Class
+   * 
+   * The controllerName must be the short name of the controller, as represented
+   * in Jax.RouteSet. An example controller name for a WelcomeController would be
+   * "welcome".
+   * 
+   * If superclass is not given, Jax.Controller is used as the superclass instead.
+   * 
+   * The methods object follows the same structure as Prototype.
+   * 
+   * Example:
+   * 
+   *     var WelcomeController = Jax.Controller.Create("welcome", ApplicationController, {
+   *       index: function() {
+   *         // ...
+   *       },
+   *       
+   *       mouse_clicked: function(event) {
+   *         // ...
+   *       }
+   *     });
+   **/
+  Jax.Controller.create = function(controller_name, superclass, inner) {
+    if (typeof(controller_name) != "string")
+    {
+      inner = superclass;
+      superclass = controller_name;
+      controller_name = "generic";
+    }
+    
+    var klass;
+    if (inner) klass = Jax.Class.create(superclass,     inner);
+    else       klass = Jax.Class.create(Jax.Controller, superclass);
+    
+    Object.extend(klass, controller_class_methods);
+    Object.extend(klass, { getControllerName: function() { return controller_name; } });
+    klass.addMethods({getControllerName: function() { return controller_name; } });
+    
+    // we already know the controller name and all its actions, so may as well
+    // set up routing here.
+    for (var method_name in klass.prototype)
+    {
+      if (!is_protected(method_name)) {
+        // it's not a protected name, so treat it as an action
+        Jax.routes.map(controller_name+"/"+method_name, klass, method_name);
+      }
+    }
+
+    return klass;
+  };
+})();