docs update, prep for release

Author: zadvorsky

dist/bas.js

@@ -114,7 +114,7 @@ THREE.BAS.Utils = {
    *
    * @param {THREE.Geometry} geometry Geometry instance the face is in.
    * @param {THREE.Face3} face Face object from the THREE.Geometry.faces array
-   * @param {THREE.Vector3} v Optional vector to store result in.
+   * @param {THREE.Vector3=} v Optional vector to store result in.
    * @returns {THREE.Vector3}
    */
   computeCentroid: function(geometry, face, v) {
@@ -135,7 +135,7 @@ THREE.BAS.Utils = {
    * Get a random vector between box.min and box.max.
    *
    * @param {THREE.Box3} box THREE.Box3 instance.
-   * @param {THREE.Vector3} v Optional vector to store result in.
+   * @param {THREE.Vector3=} v Optional vector to store result in.
    * @returns {THREE.Vector3}
    */
   randomInBox: function(box, v) {
@@ -151,7 +151,7 @@ THREE.BAS.Utils = {
   /**
    * Get a random axis for quaternion rotation.
    *
-   * @param {THREE.Vector3} v Option vector to store result in.
+   * @param {THREE.Vector3=} v Option vector to store result in.
    * @returns {THREE.Vector3}
    */
   randomAxis: function(v) {
@@ -209,8 +209,8 @@ THREE.BAS.Utils = {
  *
  * @param {THREE.Geometry} model The THREE.Geometry to base this geometry on.
  * @param {Object=} options
- * @param {Boolean=false} options.computeCentroids If true, a centroids will be computed for each face and stored in THREE.BAS.ModelBufferGeometry.centroids.
- * @param {Boolean=false} options.localizeFaces If true, the positions for each face will be stored relative to the centroid. This is useful if you want to rotate or scale faces around their center.
+ * @param {Boolean=} options.computeCentroids If true, a centroids will be computed for each face and stored in THREE.BAS.ModelBufferGeometry.centroids.
+ * @param {Boolean=} options.localizeFaces If true, the positions for each face will be stored relative to the centroid. This is useful if you want to rotate or scale faces around their center.
  * @constructor
  */
 THREE.BAS.ModelBufferGeometry = function(model, options) {
@@ -340,7 +340,7 @@ THREE.BAS.ModelBufferGeometry.prototype.bufferUVs = function() {
  *
  * @param {String} name Name of the attribute.
  * @param {int} itemSize Number of floats per vertex (typically 1, 2, 3 or 4).
- * @param {function} factory Function that will be called for each face upon creation. Accepts 3 arguments: data[], index and faceCount. Calls setFaceData.
+ * @param {function=} factory Function that will be called for each face upon creation. Accepts 3 arguments: data[], index and faceCount. Calls setFaceData.
  *
  * @returns {THREE.BufferAttribute}
  */
@@ -485,7 +485,7 @@ THREE.BAS.PrefabBufferGeometry.prototype.bufferUvs = function() {
  *
  * @param {String} name Name of the attribute.
  * @param {Number} itemSize Number of floats per vertex (typically 1, 2, 3 or 4).
- * @param {function} factory Function that will be called for each prefab upon creation. Accepts 3 arguments: data[], index and prefabCount. Calls setPrefabData.
+ * @param {function=} factory Function that will be called for each prefab upon creation. Accepts 3 arguments: data[], index and prefabCount. Calls setPrefabData.
  *
  * @returns {THREE.BufferAttribute}
  */

dist/bas.min.js

@@ -1,5 +1,11 @@
 window.onload = init;
 
+/**
+ * This is a proof-of-concept for 'embedding' an animation timeline inside the vertex shader.
+ * Implementation is very rough. Only translation and scale are supported.
+ * This may or may not end up being useful.
+ */
+
 function init() {
   var root = new THREERoot();
   root.renderer.setClearColor(0x000000);
@@ -72,6 +78,9 @@ function init() {
 
 function Animation(gridSize) {
   // setup timeline
+
+  // the timeline generates shader chunks where an animation step is baked into.
+  // each prefab will execute the same animation, with in offset position and time (delay).
   var timeline = new Timeline();
 
   // scale down
@@ -125,11 +134,11 @@ function Animation(gridSize) {
   // setup prefab geometry
   var prefabCount = gridSize * gridSize;
   var geometry = new THREE.BAS.PrefabBufferGeometry(prefab, prefabCount);
+
   var aPosition = geometry.createAttribute('aPosition', 3);
   var aDelayDuration = geometry.createAttribute('aDelayDuration', 2);
   var index = 0;
   var dataArray = [];
-
   var maxDelay = 4.0;
 
   this.totalDuration = timeline.totalDuration + maxDelay;
@@ -146,8 +155,6 @@ function Animation(gridSize) {
       geometry.setPrefabData(aPosition, index, dataArray);
 
       // animation
-      //dataArray[0] = maxDelay * index / prefabCount;
-      //dataArray[0] = maxDelay * Math.random();
       dataArray[0] = maxDelay * Math.sqrt(x * x + y * y) / gridSize;
       dataArray[1] = timeline.totalDuration;
       geometry.setPrefabData(aDelayDuration, index, dataArray);
@@ -167,10 +174,12 @@ function Animation(gridSize) {
       roughness: 1.0
     },
     vertexFunctions: [
+      // the eases used by the timeline defined above
       THREE.BAS.ShaderChunk['ease_cubic_in'],
       THREE.BAS.ShaderChunk['ease_cubic_out'],
       THREE.BAS.ShaderChunk['ease_cubic_in_out'],
       THREE.BAS.ShaderChunk['ease_back_out'],
+      // getChunks outputs the shader chunks where the animation is baked into
     ].concat(timeline.getChunks()),
     vertexParameters: [
       'uniform float uTime;',
@@ -179,11 +188,14 @@ function Animation(gridSize) {
       'attribute vec2 aDelayDuration;'
     ],
     vertexPosition: [
+      // calculate animation time for the prefab
       'float tTime = clamp(uTime - aDelayDuration.x, 0.0, aDelayDuration.y);',
 
+      // apply timeline transformations based on 'tTime'
       timeline.getScaleCalls(),
       timeline.getTranslateCalls(),
 
+      // translate the vertex by prefab position
       'transformed += aPosition;'
     ]
   });
@@ -310,6 +322,7 @@ function Segment(key, delay, duration, ease, translate, scale) {
   var sf = 'vec3(' + vecToString(scale.from, 2) + ')';
   var st = 'vec3(' + vecToString(scale.to, 2) + ')';
 
+  // this is where the magic happens, but the magic still needs a lot of work
   this.chunk = [
     'float cDelay' + key + ' = ' + delay.toPrecision(2) + ';',
     'float cDuration' + key + ' = ' + duration.toPrecision(2) + ';',

examples/boxes/main.js

@@ -49,6 +49,7 @@ <h2>Advanced / Showcase</h2>
     <a href="examples/audio_visual">Audio Visualiser</a>
     <a href="examples/image_transition">Image Transition</a>
     <a href="examples/motion_smear">Motion Smear</a>
+    <a href="examples/boxes">Many Boxes</a>
   </div>
   <div class="footer">
     <a href="https://github.com/zadvorsky/three.bas">Source</a> | <a href="docs/gen">Documentation</a> | <a href="https://github.com/zadvorsky/three.bas/wiki">Wiki</a> | <a href="https://twitter.com/zadvorsky">@zadvorsky</a>

index.html

@@ -41,7 +41,7 @@ THREE.BAS.Utils = {
    *
    * @param {THREE.Geometry} geometry Geometry instance the face is in.
    * @param {THREE.Face3} face Face object from the THREE.Geometry.faces array
-   * @param {THREE.Vector3} v Optional vector to store result in.
+   * @param {THREE.Vector3=} v Optional vector to store result in.
    * @returns {THREE.Vector3}
    */
   computeCentroid: function(geometry, face, v) {
@@ -62,7 +62,7 @@ THREE.BAS.Utils = {
    * Get a random vector between box.min and box.max.
    *
    * @param {THREE.Box3} box THREE.Box3 instance.
-   * @param {THREE.Vector3} v Optional vector to store result in.
+   * @param {THREE.Vector3=} v Optional vector to store result in.
    * @returns {THREE.Vector3}
    */
   randomInBox: function(box, v) {
@@ -78,7 +78,7 @@ THREE.BAS.Utils = {
   /**
    * Get a random axis for quaternion rotation.
    *
-   * @param {THREE.Vector3} v Option vector to store result in.
+   * @param {THREE.Vector3=} v Option vector to store result in.
    * @returns {THREE.Vector3}
    */
   randomAxis: function(v) {

src/Utils.js

@@ -3,8 +3,8 @@
  *
  * @param {THREE.Geometry} model The THREE.Geometry to base this geometry on.
  * @param {Object=} options
- * @param {Boolean=false} options.computeCentroids If true, a centroids will be computed for each face and stored in THREE.BAS.ModelBufferGeometry.centroids.
- * @param {Boolean=false} options.localizeFaces If true, the positions for each face will be stored relative to the centroid. This is useful if you want to rotate or scale faces around their center.
+ * @param {Boolean=} options.computeCentroids If true, a centroids will be computed for each face and stored in THREE.BAS.ModelBufferGeometry.centroids.
+ * @param {Boolean=} options.localizeFaces If true, the positions for each face will be stored relative to the centroid. This is useful if you want to rotate or scale faces around their center.
  * @constructor
  */
 THREE.BAS.ModelBufferGeometry = function(model, options) {
@@ -134,7 +134,7 @@ THREE.BAS.ModelBufferGeometry.prototype.bufferUVs = function() {
  *
  * @param {String} name Name of the attribute.
  * @param {int} itemSize Number of floats per vertex (typically 1, 2, 3 or 4).
- * @param {function} factory Function that will be called for each face upon creation. Accepts 3 arguments: data[], index and faceCount. Calls setFaceData.
+ * @param {function=} factory Function that will be called for each face upon creation. Accepts 3 arguments: data[], index and faceCount. Calls setFaceData.
  *
  * @returns {THREE.BufferAttribute}
  */

src/geometry/ModelBufferGeometry.js

@@ -101,7 +101,7 @@ THREE.BAS.PrefabBufferGeometry.prototype.bufferUvs = function() {
  *
  * @param {String} name Name of the attribute.
  * @param {Number} itemSize Number of floats per vertex (typically 1, 2, 3 or 4).
- * @param {function} factory Function that will be called for each prefab upon creation. Accepts 3 arguments: data[], index and prefabCount. Calls setPrefabData.
+ * @param {function=} factory Function that will be called for each prefab upon creation. Accepts 3 arguments: data[], index and prefabCount. Calls setPrefabData.
  *
  * @returns {THREE.BufferAttribute}
  */