jax 0.0.0.5 → 0.0.0.6

data/src/jax/{view.js → mvc/view.js}

@@ -30,8 +30,14 @@ Jax.View = (function() {
       this.view_func = view_func;
     },
     
+    /**
+     * Jax.View#render() -> Jax.View
+     *
+     * Renders this View. Returns itself.
+     **/
     render: function() {
       this.view_func();
+      return this;
     }
   });
 })();

data/src/jax/{view_manager.js → mvc/view_manager.js}

@@ -1,6 +1,7 @@
 /**
  * class Jax.ViewManager
  * 
+ * Maintains a registry of all Jax views and the paths to them.
  **/
 Jax.ViewManager = (function() {
   return Jax.Class.create({

data/src/jax/noise.js

@@ -1,3 +1,16 @@
+/**
+ * class Jax.Noise
+ * Constructs several textures to be used in vertex shaders involving Perlin noise.
+ *
+ * Example:
+ *
+ *     var noise = new Jax.Noise();
+ *     var program = new Jax.Shader.Program({...});
+ *     program.manifest.set('perm', noise.perm);
+ *     program.manifest.set('simplex', noise.simplex);
+ *     program.manifest.set('grad', noise.grad);
+ *
+ **/
 Jax.Noise = (function() {
   var perm/*[256]*/ = [151,160,137,91,90,15,
     131,13,201,95,96,53,194,233,7,225,140,36,103,30,69,142,8,99,37,240,21,10,23,

data/src/jax/prototype/class.js

@@ -1,5 +1,8 @@
 //= require "core"
 
+/**
+ * Jax.Class
+ **/
 Jax.Class = (function() {
   var emptyFunction = function() { };
 

data/src/jax/prototype/extensions.js

@@ -1,5 +1,3 @@
-/* My own custom extensions to Prototype */
-
 //= require "class"
 
 (function() {
@@ -112,12 +110,32 @@
     return klass;
   };
   
-  /*
-    class method #delegate
-    usages:
-      klass.delegate(/^(get|load|mult)(.*)Matrix$/).into("matrix_stack");
-      klass.delegate("getProjectionMatrix", "loadModelMatrix").into("matrix_stack");
-   */
+  /**
+   * Jax.Class.delegate() -> undefined
+   *
+   * This is a class method of all Jax classes.
+   *
+   * Delegates one or more methods into properties of the class. For instance,
+   * the following:
+   * 
+   *     MyClass.delegate("sayHello").into("person");
+   *
+   * will create a +sayHello+ method in the +MyClass+ class that internally calls
+   * 
+   *     this.person.sayHello(...)
+   *
+   * and returns the results.
+   *
+   * There are several other variants:
+   *
+   *     klass.delegate(/regular expression/).into("property_name");
+   *       // delegates any method name in +property_name+ that matches the expression
+   * 
+   *     klass.delegate("one", "two").into("property_name");
+   *       // delegates both 'one' and 'two' methods into +property_name+
+   *
+   *
+   **/
   Jax.Class.Methods.delegate = function() {
     return new Delegator(this, arguments);
   };

data/src/jax/webgl/camera.js

@@ -361,12 +361,12 @@ Jax.Camera = (function() {
     },
 
     /**
-     * Jax.Camera#getModelViewMatrix() -> mat4
+     * Jax.Camera#getTransformationMatrix() -> mat4
      * 
-     * Returns the ModelView matrix. This matrix represents the camera's position and
+     * Returns the transformation matrix. This matrix represents the camera's position and
      * orientation in the world.
      **/
-    getModelViewMatrix: function() { return this.matrices.mv; },
+    getTransformationMatrix: function() { return this.matrices.mv; },
 
     /**
      * Jax.Camera#getProjectionMatrix() -> mat4
@@ -377,16 +377,16 @@ Jax.Camera = (function() {
     getProjectionMatrix: function() { return this.matrices.p; },
 
     /**
-     * Jax.Camera#getNormalMatrix() -> mat4
+     * Jax.Camera#getNormalMatrix() -> mat3
      * 
      * Returns the normal matrix, which is defined as the transpose of the inverse of the
-     * ModelView matrix.
+     * transformation matrix.
      * 
      * This matrix is commonly used in lighting calculations.
      **/
     getNormalMatrix: function() {
       if (!this.normal_matrix_up_to_date) {
-        mat4.toInverseMat3(this.getModelViewMatrix(), this.matrices.n);
+        mat4.toInverseMat3(this.getTransformationMatrix(), this.matrices.n);
         mat3.transpose(this.matrices.n);
       }
       this.normal_matrix_up_to_date = true;

data/src/jax/webgl/core/framebuffer.js

@@ -114,12 +114,12 @@ Jax.Framebuffer = (function() {
      *             
      *   * color: optionally, in place of a colors array, a single color format as above. If both
      *            _color_ and _colors_ are specified, _color_ is simply added to the _colors_ array.
-     *   * depth: true if a depth attachment is required, false otherwise.
-     *   * stencil: true if a stencil attachment is required, false otherwise.
+     *   * depth: true if a depth attachment is required, false otherwise. Defaults to false.
+     *   * stencil: true if a stencil attachment is required, false otherwise. Defaults to false.
      *   * width: the width of the render and color buffers. All render and color buffers for a given
-     *            framebuffer must have the same width. Defaults to 2048.
+     *            framebuffer must have the same width. Defaults to 512.
      *   * height: the height of the render and color buffers. All render and color buffers for a given
-     *             framebuffer must have the same height. Defaults to 2048.
+     *             framebuffer must have the same height. Defaults to 512.
      *     
      **/
     initialize: function(options) {

data/src/jax/webgl/material.js

@@ -83,6 +83,20 @@ Jax.Material = (function() {
       }
     },
     
+    /**
+     * Jax.Material#supportsLighting() -> Boolean
+     *
+     * Returns true if this material supports lighting effects.
+     **/
+    supportsLighting: function() {
+      if (this.getName() == "lighting")
+        return true;
+      for (var i = 0; i < this.layers.length; i++)
+        if (this.layers[i].getName() == "lighting")
+          return true;
+      return false;
+    },
+    
     getName: function() { return this.name; },
     
     addTextureLayer: function(tex) {
@@ -369,8 +383,10 @@ Jax.Material.addResources = function(resources) {
 //= require "../../../builtin/shaders/depthmap/material"
 //= require "../../../builtin/shaders/paraboloid/material"
 //= require "../../../builtin/shaders/fog/material"
+//= require "../../../builtin/shaders/picking/material"
 
 Jax.Material.create("basic");
 Jax.Material.create("default", {default_shader:'basic'});
 Jax.Material.create("depthmap", {default_shader:"depthmap"});
 Jax.Material.create("paraboloid-depthmap", {type:"Paraboloid",default_shader:"paraboloid",layers:[{type:"Depthmap"}]});
+Jax.Material.create("picking", {type:"Picking"});

data/src/jax/webgl/mesh.js

@@ -225,6 +225,24 @@ Jax.Mesh = (function() {
       if (!this.draw_mode)
         this.draw_mode = GL_TRIANGLES;
     },
+    
+    /**
+     * Jax.Mesh#setColor(red, green, blue, alpha) -> Jax.Mesh
+     * Sets the color of this mesh. This will set the color at each vertex, regardless
+     * of the original color of that vertex. The result will be that the entire mesh
+     * takes on the specified color (not just a particular vertex).
+     **/
+    setColor: function(red, green, blue, alpha) {
+      var buf = this.getColorBuffer();
+      for (var i = 0; i < buf.js.length; i += 4) {
+        buf.js[i] = red;
+        buf.js[i+1] = green;
+        buf.js[i+2] = blue;
+        buf.js[i+3] = alpha;
+      }
+      buf.refresh();
+      return this;
+    },
 
     /**
      * Jax.Mesh#dispose() -> undefined
@@ -302,14 +320,11 @@ Jax.Mesh = (function() {
       var result = Jax.Util.normalizeOptions(options, {
         material: this.material,
         default_material: this.default_material,
-//        default_shader: this.default_shader,
-//        shader: this.shader,
         draw_mode: this.draw_mode || GL_TRIANGLES
       });
     
       if (!result.material) result.material = result.default_material;
-//      if (!result.shader) result.shader = result.default_shader;
-    
+
       result.material = findMaterial(result.material);
 
       return result;

data/src/jax/webgl/scene/light_manager.js

@@ -38,11 +38,15 @@ Jax.Scene.LightManager = (function() {
     },
     
     illuminate: function(context, objects, options) {
+      options = Jax.Util.normalizeOptions(options, {});
+      
       // Use alpha blending for the first pass, and additive blending for subsequent passes.
       this.context.glBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA);
       for (var i = 0; i < this._lights.length; i++) {
         for (var j = 0; j < objects.length; j++) {
           this._current_light = i;
+          options.model_index = j;
+          
           /* TODO optimization: see if objects[j] is even affected by this._lights[i] (based on attenuation) */
           if (objects[j].isLit())
             objects[j].render(context, options);
@@ -53,9 +57,13 @@ Jax.Scene.LightManager = (function() {
     },
     
     ambient: function(context, objects, options) {
+      options = Jax.Util.normalizeOptions(options, {});
+      
       for (var i = 0; i < this._lights.length; i++) {
         this._current_light = i;
         for (var j = 0; j < objects.length; j++) {
+          options.model_index = j;
+          
           /* TODO optimization: see if objects[j] is even affected by this._lights[i] (based on attenuation) */
           if (objects[j].isLit())
             objects[j].render(context, options);

data/src/jax/webgl/scene/light_source.js

@@ -167,7 +167,7 @@ Jax.Scene.LightSource = (function() {
             // front paraboloid
             self.framebuffers[0].viewport(context);
             context.glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);
-            context.loadViewMatrix(self.camera.getModelViewMatrix());
+            context.loadViewMatrix(self.camera.getTransformationMatrix());
             mat4.set(context.getInverseViewMatrix(), sm);
             
             for (var i = 0; i < objects.length; i++) {
@@ -179,7 +179,7 @@ Jax.Scene.LightSource = (function() {
             // back paraboloid
             self.framebuffers[1].viewport(context);
             context.glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);
-            context.loadViewMatrix(self.camera.getModelViewMatrix());
+            context.loadViewMatrix(self.camera.getTransformationMatrix());
             for (var i = 0; i < objects.length; i++) {
               objects[i].render(context, {material:paraboloid_depthmap,direction:-1});
             }
@@ -203,7 +203,7 @@ Jax.Scene.LightSource = (function() {
         context.pushMatrix(function() {
           self.framebuffers[0].viewport(context);
           context.matrix_stack.loadProjectionMatrix(self.camera.getProjectionMatrix());
-          context.matrix_stack.loadViewMatrix(self.camera.getModelViewMatrix());
+          context.matrix_stack.loadViewMatrix(self.camera.getTransformationMatrix());
           mat4.identity(sm);
           sm[0] = sm[5] = sm[10] = sm[12] = sm[13] = sm[14] = 0.5;
           mat4.multiply(sm, context.getModelViewProjectionMatrix());

data/src/jax/webgl/shader.js

@@ -103,12 +103,13 @@ Jax.Shader = (function() {
     for (var i in map) {
       if (map[i].shared) {
         if (options.skip_global_definitions && options.skip_global_definitions.indexOf(map[i].full_name) != -1) {
-          var rx = new RegExp("(shared\\s+)?"+map[i].scope+"\\s*"+map[i].type+"[^;]*?"+map[i].full_name+"[^;]*?;\n?", "g");
+          var rx = new RegExp("(shared\\s+)"+map[i].scope+"\\s*"+map[i].type+"[^;]*?"+map[i].full_name+"[^;]*?;\n?", "g");
           source = source.replace(rx, "");
         }
 //        else source = source.replace(rx, map[i].scope+" "+map[i].type+" "+map[i].full_name+";\n");
       }
     }
+
     return source.replace(/shared\s+/, '');
   }
   
@@ -121,6 +122,7 @@ Jax.Shader = (function() {
     source = applyExports(self, options, source);
     source = applyImports(self, options, source);
     source = mangleUniformsAndAttributes(self, options, source);
+
     return source;
   }
   
@@ -234,7 +236,7 @@ Jax.Shader = (function() {
                    (this.getRawSource(options, 'fragment') || "");
       
       // if it's not a "shared" uniform, mangle its name.
-      var rx = new RegExp("(^|\\n|\\s+)((shared\\s+)?)(uniform|attribute|varying) (\\w+) ((?!"+prefix+")[^;]*);"), result;
+      var rx = new RegExp("(^|\\n|\\s+)((shared\\s+)?)(uniform|attribute|varying)\\s+(\\w+)\\s+((?!"+prefix+")[^;]*);"), result;
       while (result = rx.exec(source)) {
         var shared = /shared/.test(result[2]);
         var scope = result[4];

data/src/jax/webgl/shader_chain.js

@@ -230,6 +230,7 @@ Jax.ShaderChain = (function() {
           else map[variable.full_name] = variable;
         }
       }
+
       return map;
     },
     

data/src/jax/webgl/world.js

@@ -1,6 +1,23 @@
 //= require "scene"
 
+/**
+ * class Jax.World
+ * 
+ * A +Jax.World+ represents a scene in the graphics engine. All objects to be rendered (or at least,
+ * all objects that you do not want to manually control!) should be added to the world. Each instance
+ * of +Jax.Context+ has its own +Jax.World+, and the currently-active +Jax.World+ is delegated into
+ * controllers and views as the +this.world+ property.
+ *
+ **/
 Jax.World = (function() {
+  function getPickBuffer(self) {
+    if (self.pickBuffer) return self.pickBuffer;
+    return self.pickBuffer = new Jax.Framebuffer({
+      width:self.context.canvas.width,
+      height:self.context.canvas.height
+    });
+  }
+  
   return Jax.Class.create({
     initialize: function(context) {
       this.context  = context;
@@ -9,12 +26,38 @@ Jax.World = (function() {
       this.shadow_casters = [];
     },
     
+    /**
+     * Jax.World#addLightSource(light) -> Jax.Scene.LightSource
+     * - light (Jax.Scene.LightSource) : the instance of Jax.Scene.LightSource to add to this world.
+     *
+     * Adds the light to the world and then returns the light itself unchanged.
+     **/
     addLightSource: function(light)   { this.lighting.add(light); },
     
+    /**
+     * Jax.World#addObject(object) -> Jax.Model
+     * - object (Jax.Model) : the instance of Jax.Model to add to this world.
+     *
+     * Adds the model to the world and then returns the model itself unchanged.
+     *
+     **/
     addObject: function(object) { this.objects.push(object); this.invalidate(); return object; },
     
+    /**
+     * Jax.World#getObject(index) -> Jax.Model
+     * - index (Number) : the world index of this object
+     *
+     * Returns the object with the specified world index, or undefined.
+     **/
     getObject: function(index) { return this.objects[index]; },
     
+    /**
+     * Jax.World#removeObject(object_or_index) -> Jax.Model
+     * - object_or_index (Number|Jax.Model) : the model instance to remove, or its world index
+     *
+     * If the model or its index cannot be found, nothing happens and the return value is undefined.
+     * Otherwise, the object is removed from this World and then returned.
+     **/
     removeObject: function(object_or_index) {
       if (this.objects[object_or_index]) {
         var obj = this.objects[object_or_index];
@@ -32,6 +75,110 @@ Jax.World = (function() {
           }
     },
     
+    /**
+     * Jax.World#pickRegionalIndices(x1, y1, x2, y2[, ary]) -> Array
+     * - x1 (Number): the screen X coordinate of the first corner of the 2D rectangle within which to pick
+     * - y1 (Number): the screen Y coordinate of the first corner of the 2D rectangle within which to pick
+     * - x2 (Number): the screen X coordinate of the second corner of the 2D rectangle within which to pick
+     * - y2 (Number): the screen Y coordinate of the second corner of the 2D rectangle within which to pick
+     * - ary (Array): an optional array to populate. A new one will be created if this is not specified.
+     *                (Note: the array's contents will be cleared.)
+     * 
+     * Picks all visible object indices within the specified rectangular regions and returns them as elements in
+     * an array.
+     *
+     * An object's index matches its position in the world's object list. That is, the following code is
+     * valid:
+     *
+     *     this.world.getObjects(this.world.pickRegionalIDs(0,0, 100,100));
+     *
+     **/
+    pickRegionalIndices: function(x1, y1, x2, y2, ary) {
+      var w = Math.abs(x2 - x1), h = Math.abs(y2 - y1);
+      if (ary) ary.clear();
+      else ary = new Array();
+      var world = this, pickBuffer = getPickBuffer(this), context = this.context;
+      var data = new Uint8Array(w*h*4);
+
+      pickBuffer.bind(context, function() {
+        pickBuffer.viewport(context);
+         context.glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);
+         context.glDisable(GL_BLEND);
+         world.render({material:"picking"});
+         // read it back in
+         context.glReadPixels(x1, y1, w, h, GL_RGBA, GL_UNSIGNED_BYTE, data);
+         if (data.data) data = data.data;
+      });
+      
+      // restore the visible viewport and blending
+      context.glViewport(0, 0, context.canvas.width, context.canvas.height);
+      context.glEnable(GL_BLEND);
+      
+      var index;
+      for (var i = 2; i < data.length; i += 4) {
+        if (data[i] > 0) { // blue key exists, we've found an object
+          index = Jax.Util.decodePickingColor(data[i-2], data[i-1], data[i], data[i+1]);
+          if (index != undefined) {
+            ary.push(index);
+          }
+        }
+      }
+      
+      return ary;
+    },
+    
+    /**
+     * Jax.World#pickRegion(x1, y1, x2, y2) -> Array
+     * - x1 (Number): the screen X coordinate of the first corner of the 2D rectangle within which to pick
+     * - y1 (Number): the screen Y coordinate of the first corner of the 2D rectangle within which to pick
+     * - x2 (Number): the screen X coordinate of the second corner of the 2D rectangle within which to pick
+     * - y2 (Number): the screen Y coordinate of the second corner of the 2D rectangle within which to pick
+     * - ary (Array): an optional array to populate. A new one will be created if this is not specified.
+     *                (Note: the array's contents will be cleared.)
+     *
+     * Picks all visible objects within the specified rectangular regions and returns them as elements in
+     * an array.
+     **/
+    pickRegion: function(x1, y1, x2, y2, ary) {
+      var result = this.pickRegionalIndices(x1, y1, x2, y2);
+      for (var i = 0; i < result.length; i++)
+        result[i] = this.getObject(i);
+      return result;
+    },
+    
+    /**
+     * Jax.World#pickIndex(x, y) -> Number | undefined
+     * - x (Number): the screen X coordinate to pick at
+     * - y (Number): the screen Y coordinate to pick at
+     *
+     * Picks the visible object at the specified position and returns its index as used by
+     * +Jax.World#getObject+. If no object is visible at the given position, the special value
+     * +undefined+ is returned.
+     **/
+    pickIndex: function(x, y) {
+      this._pick_ary = this._pick_ary || new Array();
+      return this.pickRegionalIndices(x, y, x+1, y+1, this._pick_ary)[0];
+    },
+    
+    /**
+     * Jax.World#pick(x, y) -> Jax.Model | undefined
+     * - x (Number): the screen X coordinate to pick at
+     * - y (Number): the screen Y coordinate to pick at
+     *
+     * Picks the visible object at the specified position and returns it. If no object is visible
+     * at the given position, the special value +undefined+ is returned.
+     **/
+    pick: function(x, y) {
+      var index = this.pickIndex(x, y);
+      if (index != undefined)
+        return this.getObject(index);
+      return index;
+    },
+    
+    /**
+     * Jax.World#countObjects() -> Number
+     * Returns the number of objects currently registered with this World.
+     **/
     countObjects: function() {
       return this.objects.length;
     },
@@ -63,16 +210,16 @@ Jax.World = (function() {
     
     getShadowCasters: function() { return this.shadow_casters; },
     
-    render: function() {
+    render: function(options) {
       var i;
       
       /* this.current_pass is used by the material */
 
       this.context.current_pass = Jax.Scene.AMBIENT_PASS;
       this.context.glBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA);
-      var unlit = {unlit:true};
+      var unlit = Jax.Util.normalizeOptions(options, {unlit:true});
       
-      if (this.lighting.isEnabled()) {
+      if (this.lighting.isEnabled() && (!unlit.material || unlit.material.supportsLighting())) {
         /* ambient pass */
         /*
           So.... I see a legit need for an ambient pass for A) unlit objects and B)
@@ -81,8 +228,10 @@ Jax.World = (function() {
           lighting take care of (ambient + diffuse + specular) all at once?
         */
         for (i = 0; i < this.objects.length; i++)
-          if (!this.objects[i].lit)
+          if (!this.objects[i].lit) {
+            unlit.model_index = i;
             this.objects[i].render(this.context, unlit);
+          }
         // this.lighting.ambient(this.context, this.objects);
       
         /* shadowgen pass */
@@ -94,10 +243,12 @@ Jax.World = (function() {
         
         /* illumination pass */
         this.context.current_pass = Jax.Scene.ILLUMINATION_PASS;
-        this.lighting.illuminate(this.context, this.objects);
+        this.lighting.illuminate(this.context, this.objects, options);
       } else {
-        for (i = 0; i < this.objects.length; i++)
+        for (i = 0; i < this.objects.length; i++) {
+          unlit.model_index = i;
           this.objects[i].render(this.context, unlit);
+        }
       }
     },