jax 1.1.1 → 2.0.0

data/lib/assets/javascripts/jax/webgl/core/buffer.js

@@ -0,0 +1,292 @@
+/**
+ * class Jax.Buffer
+ *
+ * Root class of all WebGL buffer objects.
+ *
+ * Wrapper to manage JS and GL buffer (array) types. Automates context
+ * juggling by requiring the context to generate the buffer for as an
+ * argument to #bind. If the context doesn't have a corresponding GL
+ * buffer for this data, it will be created. Calling #refresh will
+ * regenerate the buffer data for all contexts.
+ *
+ **/
+Jax.Buffer = (function() {
+  function each_gl_buffer(self, func)
+  {
+    for (var id in self.gl)
+      func(self.gl[id].context, self.gl[id].buffer);
+  }
+
+  return Jax.Class.create({
+    /**
+     * new Jax.Buffer(bufferType, classType, drawType, jsarr, itemSize)
+     * - bufferType (GLenum): A WebGL enumeration specifying what type
+     *                        of buffer this represents, such as GL_ELEMENT_ARRAY_BUFFER or
+     *                        GL_ARRAY_BUFFER.
+     * - classType (TypedArray): a typed array to implement this buffer
+     * with, such as +Uint6Array+ or +Float32Array+.
+     * - drawType (GLenum): GL_STREAM_DRAW, GL_STATIC_DRAW, or GL_DYNAMIC_DRAW.
+     * - jsarr (Array): a JavaScript Array containing the actual raw
+     * data. This should be a flat array (that is, no nested arrays).
+     * - itemSize (Number): the number of items in a single element
+     * of the buffer. The length of the buffer must be divisible by
+     * this number.
+     *
+     **/
+    initialize: function(bufferType, classType, drawType, jsarr, itemSize) {
+      // if (jsarr.length == 0) throw new Error("No elements in array to be buffered!");
+      if (!itemSize) throw new Error("Expected an itemSize - how many JS array elements represent a single buffered element?");
+      this.classType = classType;
+      this.itemSize = itemSize;
+      this.js = jsarr;
+      this.gl = {};
+      this.numItems = this.length = jsarr.length / itemSize;
+      this.bufferType = bufferType;
+      this.drawType = drawType;
+    },
+
+    /**
+     * Jax.Buffer#refresh() -> Jax.Buffer
+     *
+     * Causes Jax to immediately refresh the buffer data on the graphics card
+     * for all WebGL contexts the buffer is bound to. This should be done any
+     * time you change the data within the buffer's underlying JavaScript array.
+     **/
+    refresh: function() {
+      var self = this;
+      var instance = this.refreshTypedArray();
+      if (!self.gl) return;
+
+      each_gl_buffer(self, function(context, buffer) {
+        context.glBindBuffer(self.bufferType, buffer);
+        context.glBufferData(self.bufferType, instance, self.drawType);
+      });
+      
+      return this;
+    },
+    
+    /**
+     * Jax.Buffer#refreshTypedArray() -> TypedArray
+     *
+     * Refreshes the contents of the buffer's typed array and then returns
+     * the typed array itself. This does not cause the corresponding GL
+     * buffers to be refreshed.
+     **/
+    refreshTypedArray: function() {
+      var self = this;
+      var instance = this.getTypedArray();
+      instance.set(self.js);
+
+      self.numItems = self.length = self.js.length / self.itemSize;
+      return instance;
+    },
+    
+    /**
+     * Jax.Buffer#getTypedArray([defaultValues]) -> TypedArray
+     *
+     * Returns the typed array instance corresponding for this buffer.
+     **/
+    getTypedArray: function() {
+      return this.classTypeInstance = this.classTypeInstance || new this.classType(this.js);
+    },
+
+    /**
+     * Jax.Buffer#dispose() -> Jax.Buffer
+     *
+     * Dispose of this buffer's WebGL counterparts. This is applied to all contexts
+     * the buffer is associated with.
+     *
+     * Note that calling Jax.Buffer#bind will rebuild this buffer, effectively
+     * cancelling this method out, so take care not to use the buffer after
+     * disposing it unless this is the functionality you want (e.g. to clean up
+     * some Jax contexts, but not all of them).
+     **/
+    dispose: function() {
+      var self = this;
+      each_gl_buffer(this, function(context, buffer) {
+        context.glDeleteBuffer(buffer);
+        self.gl[context.id] = null;
+      });
+      self.gl = {};
+      return self;
+    },
+
+    /**
+     * Jax.Buffer#isDisposed() -> Boolean
+     * 
+     * Returns true if this buffer is in an uninitialized state.
+     **/
+    isDisposed: function() { return !this.gl; },
+
+    /**
+     * Jax.Buffer#bind(context) -> Jax.Buffer
+     * - context (Jax.Context): the context to bind the buffer to.
+     *
+     * Binds this buffer to the specified context, then returns the buffer.
+     * If this buffer is in an uninitialized or disposed state, it will be
+     * built (or rebuilt) prior to binding.
+     **/
+    bind: function(context) { context.glBindBuffer(this.bufferType, this.getGLBuffer(context)); return this; },
+
+    /**
+     * Jax.Buffer#getGLBuffer(context) -> WebGLBuffer
+     * - context (Jax.Context): the context to get the buffer for.
+     * 
+     * Returns the underlying WebGLBuffer instance representing this buffer's data
+     * for the specified context. Note that this is different for each context.
+     * If the buffer has not yet been defined for the given context, it will be.
+     **/
+    getGLBuffer: function(context)
+    {
+      if (!context || typeof(context.id) == "undefined")
+        throw new Error("Cannot build a buffer without a context!");
+
+      if (!this.gl[context.id])
+      {
+        var buffer = context.glCreateBuffer();
+        buffer.itemSize = this.itemSize;
+        this.gl[context.id] = {context:context,buffer:buffer};
+        this.refresh();
+      }
+      return this.gl[context.id].buffer;
+    }
+  });
+})();
+
+/**
+ * class Jax.ElementArrayBuffer < Jax.Buffer
+ *
+ * A generic Int16 Array. Initialized with a standard JavaScript Array argument.
+ * Its item size is 1, so each element in the array represents a separate datum,
+ *
+ * This type of buffer is commonly used for vertex indices, etc.
+ *
+ * Example:
+ *     var buf = new Jax.ElementArrayBuffer([...]);
+ **/
+Jax.ElementArrayBuffer = Jax.Class.create(Jax.Buffer, {
+  initialize: function($super, jsarr) {
+    $super(GL_ELEMENT_ARRAY_BUFFER, Uint16Array, GL_STREAM_DRAW, jsarr, 1);
+  }
+});
+
+/**
+ * class Jax.FloatArrayBuffer < Jax.Buffer
+ *
+ * A generic Float Array. Initialized with a standard JavaScript Array argument,
+ * and an item size. As the item size represents how many array elements represent
+ * a single datum, the array must be divisible by this number.
+ *
+ * Unless you're implementing something Jax does not support by default, you're
+ * most likely looking for one of the subclasses of Jax.FloatArrayBuffer.
+ *
+ * Example:
+ *     var buf = new Jax.FloatArrayBuffer([...], 3);
+ **/
+Jax.FloatArrayBuffer = Jax.Class.create(Jax.Buffer, {
+  initialize: function($super, jsarr, itemSize) {
+    $super(GL_ARRAY_BUFFER, Float32Array, GL_STATIC_DRAW, jsarr, itemSize);
+  }
+});
+
+/**
+ * class Jax.VertexBuffer < Jax.FloatArrayBuffer
+ *
+ * Initialized with a standard JavaScript Array argument.
+ *
+ * Example:
+ *     var buf = new Jax.VertexBuffer([...]);
+ **/
+Jax.VertexBuffer = Jax.Class.create(Jax.FloatArrayBuffer, {
+  initialize: function($super, jsarr) { $super(jsarr, 3); }
+});
+
+/**
+ * class Jax.ColorBuffer < Jax.FloatArrayBuffer
+ *
+ * Initialized with a standard JavaScript Array argument.
+ *
+ * Example:
+ *     var buf = new Jax.ColorBuffer([...]);
+ **/
+Jax.ColorBuffer = Jax.Class.create(Jax.FloatArrayBuffer, {
+  initialize: function($super, jsarr) { $super(jsarr, 4); }
+});
+
+/**
+ * class Jax.TextureCoordsBuffer < Jax.FloatArrayBuffer
+ *
+ * Initialized with a standard JavaScript Array argument.
+ *
+ * Example:
+ *     var buf = new Jax.TextureCoordsBuffer([...]);
+ **/
+Jax.TextureCoordsBuffer = Jax.Class.create(Jax.FloatArrayBuffer, {
+  initialize: function($super, jsarr) { $super(jsarr, 2); }
+});
+
+/**
+ * class Jax.NormalBuffer < Jax.FloatArrayBuffer
+ *
+ * Initialized with a standard JavaScript Array argument.
+ *
+ * Example:
+ *     var buf = new Jax.NormalBuffer([...]);
+ **/
+Jax.NormalBuffer = Jax.Class.create(Jax.FloatArrayBuffer, {
+  initialize: function($super, jsarr) { $super(jsarr, 3); }
+});
+
+
+/**
+ * class Jax.DataBuffer < Jax.Buffer
+ *
+ * Creates a buffer specifically designed for use with Jax.DataSegment.
+ *
+ * Jax meshes as of v1.1.0 use this kind of buffer in place of all others for memory efficiency.
+ * Using a Jax.DataBuffer cuts out the redundant data introduced by the other buffer types,
+ * and can be refreshed much more quickly since the data does not need to be copied into
+ * storage buffers before being dispatched to the GL.
+ *
+ * Example:
+ *     var region = new Jax.DataRegion();
+ *     var vertexData = region.map(Float32Array, 9); // allocate 1 triangle
+ *     var vertices = vertexData.group(3); // vertices are 3 groups of 3 (XYZ) elements each
+ *     var buffer = new Jax.DataBuffer(GL_ARRAY_BUFFER, vertices);
+ *
+ * An alternative usage is to use a data segment directly, without remapping it into a group.
+ * This usage requires an extra argument, the element size, which will default to 1 if omitted:
+ *
+ *     var region = new DataRegion();
+ *     var vertexData = region.map(Float32Array, 9); // allocate 1 triangle
+ *     var buffer = new Jax.DataBuffer(GL_ARRAY_BUFFER, vertexData, 3);
+ *
+ **/
+Jax.DataBuffer = Jax.Class.create(Jax.Buffer, {
+  
+  initialize: function($super, bufferType, data, size) {
+    size = size || 1;
+    if (data.getRawData) {
+      size = data.size;
+      this.mirror = data;
+      this.data = data.getRawData();
+    } else {
+      this.data = data;
+    }
+    var type = this.data.type;
+    
+    if (!size || !type) throw new Error("Couldn't detect element size or type! Use a different buffer.");
+    
+    $super(bufferType, type, GL_DYNAMIC_DRAW, this.data.array, size);
+  },
+  
+  refreshTypedArray: function() {
+    this.numItems = this.length = (this.mirror ? this.mirror.length : this.data.length / this.itemSize);
+    // we don't need to update anything else
+    return this.getTypedArray();
+  },
+  
+  getTypedArray: function() {
+    return this.data.array;
+  }
+});

data/lib/assets/javascripts/jax/webgl/core/data_region.js

@@ -0,0 +1,184 @@
+//= require "jax/webgl/core/data_segment"
+
+/**
+ * class Jax.DataRegion
+ *
+ * Allocates a single contiguous segment of memory for storing data,
+ * which is then subdivided into smaller segments as needed.
+ *
+ * Creating a 512-byte data region:
+ *
+ *     var data = new DataRegion(512);
+ *
+ * After a region has been created, it can be mapped to any number of
+ * typed arrays.
+ *
+ * Mapping a 12-element Float32Array:
+ *
+ *     var vertices = data.map(Float32Array, 12);
+ *
+ * Mapping an additional 4-element Uint16Array:
+ *
+ *     var indices = data.map(Uint16Array, 4);
+ *
+ * Remapping the 12-element Float32Array into a 16-element Float32Array:
+ *
+ *     data.remap(vertices, 16);
+ *
+ * Using the arrays:
+ *
+ *     vertices.array[0] = 1;
+ *     vertices.array[1] = vertices.array[0] + 1;
+ *     indices.array[0] = 0;
+ *
+ **/
+Jax.DataRegion = (function() {
+  var CHUNK_SIZE = 1024;
+  
+  var klass = Jax.Class.create({
+    /**
+     * new Jax.DataRegion([bytes])
+     * - bytes (Number): the starting number of bytes of memory to allocate
+     *
+     * Initializes a new Jax.DataRegion with the specified number of bytes
+     * of memory.
+     **/
+    initialize: function(bytes) {
+      this.allocate(bytes || CHUNK_SIZE);
+      this.offset = 0;
+      this.segments = [];
+    },
+    
+    /**
+     * Jax.DataRegion#allocate(amount) -> Jax.DataRegion
+     * 
+     * Ensures that the data region is large enough to contain the specified number
+     * of bytes. Note that the amount is expected to include the byte offset, if any.
+     **/
+    allocate: function(amount) {
+      if (!amount && typeof(amount) != 'number') throw new Error("amount required\n\n"+new Error().stack);
+      if (isNaN(amount)) throw new Error("NaN\n\n"+new Error().stack);
+      if (!this.data) {
+        this.data = new ArrayBuffer(amount);
+        return this;
+      }
+      
+      var newlen = this.data.byteLength;
+      if (newlen >= amount) return this;
+      newlen += (parseInt(amount / CHUNK_SIZE) + 1) * CHUNK_SIZE;
+      
+      this.data = new ArrayBuffer(newlen);
+      
+      // copy segment data into new region
+      // remap will also recursively remap all following segments
+      if (this.segments.length > 0) {
+        var buf = this.segments[0].array;
+        this.remap(this.segments[0], this.segments[0].length).set(buf);
+      }
+      
+      return this;
+    },
+    
+    /**
+     * Jax.DataRegion#map(type, length[, values]) -> Jax.DataSegment
+     * Jax.DataRegion#map(type, values) -> Jax.DataSegment
+     * - type (Function): the type of array to instantiate, such as Float32Array.
+     * - length (Number): the number of array elements to create.
+     * - values (Array): If a length is given, values is an optional array
+     *                   containing values to initialize the segment with. If
+     *                   the length is omitted, values becomes a required array
+     *                   whose length will be used as the data segment's length.
+     *
+     * Creates a new segment within the data region.
+     *
+     * If the region does not
+     * contain enough free bytes to allocate the array, a larger region will
+     * be automatically allocated and all attached segments will be updated
+     * to use the new data, discarding the previous. Old values will be
+     * copied into the new arrays at this time.
+     *
+     *
+     * Examples:
+     *     region.map(Float32Array, 4)          //=> Float32Array [0,0,0,0]
+     *     region.map(Float32Array, [1,2,3])    //=> Float32Array [1,2,3]
+     *     region.map(Float32Array, 4, [1,2,3]) //=> Float32Array [1,2,3,0]
+     *
+     **/
+    map: function(type, length, values) {
+      // check for using an array of values without an explicit length
+      if (typeof(length) != "number") {
+        values = length;
+        length = values.length;
+      }
+
+      this.allocate(this.offset + length * type.BYTES_PER_ELEMENT);
+      var segment = new Jax.DataSegment(type, this.data, this.offset, length);
+      this.segments.push(segment);
+      segment.type = type;
+      this.offset += length * type.BYTES_PER_ELEMENT;
+      
+      if (values) segment.set(values);
+      return segment;
+    },
+    
+    /**
+     * Jax.DataRegion#remap(segment, length) -> Jax.DataSegment
+     * - segment (Jax.DataSegment): the data segment to remap
+     * - length (Number): the number of elements the segment should be modified to have
+     *
+     * Modifies the given data segment to have +length+ elements instead of the
+     * number of elements it currently has. If the segment is truncated, the
+     * truncated data is lost. If the segment is enlarged, the new elements will
+     * be initialized to zero.
+     *
+     * All other segments appearing after the specified one in the memory map
+     * will be altered as needed so that there is no overlapping of array data.
+     * Depending on the number of segments involved, this may or may not be an
+     * expensive operation.
+     **/
+    remap: function(segment, length, values, offset) {
+      if (offset == undefined) offset = segment.byteOffset;
+      if (!values && typeof(length) != 'number') {
+        values = length;
+        length = values.length;
+      }
+
+      var oldLength = segment.length;
+      if (oldLength == length && offset == segment.byteOffset) {
+        // no need to reallocate the same structure
+        if (values) segment.set(values);
+        return segment;
+      }
+      
+      this.allocate(offset + length * segment.type.BYTES_PER_ELEMENT);
+      
+      var newAry = new segment.type(this.data, offset, length);
+        if (values) { 
+        try {
+          newAry.set(values);
+          oldLength = Math.max(values.length, oldLength);
+        } catch(e) {
+          throw new Error("Values are not valid: "+JSON.stringify(values));
+        }
+      }
+      segment.setArray(newAry);
+      var index = this.segments.indexOf(segment);
+
+      // remap all following segments, and copy over their current contents
+      if (index < this.segments.length-1) {
+        var next = this.segments[index+1];
+        var buf = next.array;
+        this.remap(next, next.length, null, offset + length * segment.type.BYTES_PER_ELEMENT).set(buf);
+      }
+            
+      // in the case of expansion (not truncation), initialize values to 0.
+      // (Current values may be left over from previous segments).
+      for (var i = oldLength; i < length; i++)
+        segment[i] = 0;
+      
+      return segment;
+    }
+  });
+  
+  return klass;
+})();