edit docs; avoid creating too-small or too-narrow triangles in tris.html; fix attribute-disable bug

Author: peteroupc

camera.js

@@ -296,10 +296,7 @@ Camera.prototype.moveForward=function(dist){
 Camera.prototype.getPosition=function(){
   return this.position.slice(0,3);
 }
-/**
- * Not documented yet.
- * @param {*} e
- */
+/** @private */
 Camera.prototype.mousewheel=function(e){
  var ticks=e.delta/120.0;
  // mousewheel up (negative) means move forward,
@@ -453,6 +450,7 @@ InputTracker.ENTER=13;
 InputTracker.TAB=9;
 InputTracker.SHIFT=16;
 InputTracker.CTRL=17;
+InputTracker.ALT=18;
 InputTracker.ESC=27;
 InputTracker.SPACE=32;
 InputTracker.PAGEUP=33;

glmath.js

@@ -75,6 +75,28 @@ return [a[1]*b[2]-a[2]*b[1],
 vec3dot:function(a,b){
 return a[0]*b[0]+a[1]*b[1]+a[2]*b[2];
 },
+/**
+ * Adds two 3-element vectors and returns a new
+ * vector with the result. Adding two vectors
+ * is the same as adding each of their components.
+ * @param {Array<number>} a The first 3-element vector.
+ * @param {Array<number>} b The second 3-element vector.
+ * @return {Array<number>} The resulting 3-element vector.
+ */
+vec3add:function(a,b){
+return [a[0]+b[0],a[1]+b[1],a[2]+b[2]];
+},
+/**
+ * Subtracts two 3-element vectors and returns a new
+ * vector with the result. Subtracting two vectors
+ * is the same as subtracting each of their components.
+ * @param {Array<number>} a The first 3-element vector.
+ * @param {Array<number>} b The second 3-element vector.
+ * @return {Array<number>} The resulting 3-element vector.
+ */
+vec3sub:function(a,b){
+return [a[0]-b[0],a[1]-b[1],a[2]-b[2]];
+},
 /**
  * Adds two 3-element vectors and stores
  * the result in the first vector. Adding two vectors
@@ -1214,23 +1236,31 @@ mat4ortho:function(l,r,b,t,n,f){
 },
 
 /**
- * Returns a 4x4 matrix representing a perspective projection
- * given an X-axis field of view.<p>
- * This method assumes a right-hand coordinate system;
- * see {@link glmath.GLMath.mat4perspective}.  For considerations
- * when choosing the "n" and "f" parameters,
- * see {@link glmath.GLMath.mat4perspective}.
+ * Returns a 4x4 matrix representing a perspective projection,
+ * given an X-axis field of view.</p>
+ * This method assumes a right-handed coordinate system, such as
+ * OpenGL's. To adjust the result of this method to a left-handed system,
+ * such as Direct3D's, reverse the sign of the 9th, 10th, 11th, and 12th
+ * elements of the result (zero-based indices 8, 9, 10, and 11).
 * @param {number}  fovX X-axis field of view, in degrees. Should be less
 * than 180 degrees.  (The smaller
 * this number, the bigger close objects appear to be.)
 * @param {number}  aspectRatio The ratio of width to height of the viewport, usually
 *  the scene's aspect ratio.
 * @param {number} near The distance from the camera to
 * the near clipping plane. Objects closer than this distance won't be
-* seen.
+* seen.<p>This value should not be 0 or less, and should be set to the highest distance
+* from the camera that the application can afford to clip out for being too
+* close, for example, 0.5, 1, or higher.
 * @param {number} far The distance from the camera to
 * the far clipping plane. Objects beyond this distance will be too far
-* to be seen.
+* to be seen.  This value should be greater than "near" and be set so that the ratio of "far" to "near"
+* is as small as the application can accept.<p>
+ * (Depth buffers often allow only 65536 possible values per pixel,
+ * which are more spread out toward the far clipping plane than toward the
+ * near plane due to the perspective projection.  The greater the ratio of "far" to
+ * "near", the more the values spread out, and the more likely two objects close
+ * to the far plane will have identical depth values.)
  * @return {Array<number>} The resulting 4x4 matrix.
  */
 mat4perspectiveHorizontal:function(fovX,aspectRatio,near,far){
@@ -1315,15 +1345,12 @@ mat4orthoAspect:function(l,r,b,t,n,f,aspect){
  }
 },
 /**
- * Returns a 4x4 matrix representing a view frustum,
- * or the limits in the camera's view.<p>
+ * Returns a 4x4 matrix representing a perspective projection
+ * in the form of a view frustum, or the limits in the camera's view.<p>
  * This method assumes a right-handed coordinate system, such as
  * OpenGL's. To adjust the result of this method to a left-handed system,
  * such as Direct3D's, reverse the sign of the 9th, 10th, 11th, and 12th
  * elements of the result (zero-based indices 8, 9, 10, and 11).
- * <p>
- * For considerations when choosing the "n" and "f" parameters,
- * see {@link glmath.GLMath.mat4perspective}.
  * @param {number} l X-coordinate of the point where the left
  * clipping plane meets the near clipping plane.
  * @param {number} r X-coordinate of the point where the right
@@ -1332,24 +1359,32 @@ mat4orthoAspect:function(l,r,b,t,n,f,aspect){
  * clipping plane meets the near clipping plane.
  * @param {number} t Y-coordinate of the point where the top
  * clipping plane meets the near clipping plane.
-* @param {number} n The distance from the camera to
+* @param {number} near The distance from the camera to
 * the near clipping plane. Objects closer than this distance won't be
-* seen.
-* @param {number} f The distance from the camera to
+* seen.<p>This value should not be 0 or less, and should be set to the highest distance
+* from the camera that the application can afford to clip out for being too
+* close, for example, 0.5, 1, or higher.
+* @param {number} far The distance from the camera to
 * the far clipping plane. Objects beyond this distance will be too far
-* to be seen.
+* to be seen.  This value should be greater than "near" and be set so that the ratio of "far" to "near"
+* is as small as the application can accept.<p>
+ * (Depth buffers often allow only 65536 possible values per pixel,
+ * which are more spread out toward the far clipping plane than toward the
+ * near plane due to the perspective projection.  The greater the ratio of "far" to
+ * "near", the more the values spread out, and the more likely two objects close
+ * to the far plane will have identical depth values.)
  * @return {Array<number>} The resulting 4x4 matrix.
  */
-mat4frustum:function(l,r,b,t,n,f){
- var dn=2*n;
+mat4frustum:function(l,r,b,t,near,far){
+ var dn=2*near;
  var onedx=1/(r-l);
  var onedy=1/(t-b);
- var onedz=1/(f-n);
+ var onedz=1/(far-near);
 return [
     dn*onedx,0,0,0,
     0,dn*onedy,0,0,
-    (l+r)*onedx,(t+b)*onedy,-(f+n)*onedz,-1,
-   0,0,-(dn*f)*onedz,0];
+    (l+r)*onedx,(t+b)*onedy,-(far+near)*onedz,-1,
+   0,0,-(dn*far)*onedz,0];
 },
 /**
  * Modifies a 4x4 matrix by multiplying it by a

glutil-eval.js

@@ -162,6 +162,13 @@ function BezierCurve(cp, u1, u2){
  * @return {Array<number>} An array of the result of
  * the evaluation.  Its length will be equal to the
  * length of a control point, as specified in the constructor.
+* @example
+* // Generate 11 points forming the B&eacute;zier curve.
+* // Assumes the curve was created with u1=0 and u2=1 (the default).
+* var points=[];
+* for(var i=0;i<=10;i++){
+*  points.push(curve.evaluate(i/10.0));
+* }
  */
 BezierCurve.prototype.evaluate=function(u){
  var output=[];

glutil-mesh.js

@@ -63,7 +63,7 @@ Mesh._isCompatibleMode=function(oldMode,newMode){
    return true;
  return false;
 }
-
+/** @private */
 Mesh._recalcNormalsStart=function(vertices,uniqueVertices,faces,stride,offset,flat){
   for(var i=0;i<vertices.length;i+=stride){
     vertices[i+offset]=0.0
@@ -78,6 +78,7 @@ Mesh._recalcNormalsStart=function(vertices,uniqueVertices,faces,stride,offset,fl
     }
   }
 }
+/** @private */
 Mesh._recalcNormalsFinish=function(vertices,uniqueVertices,faces,stride,offset,flat){
  var len;
    if(!flat){

glutil.js

@@ -1160,7 +1160,7 @@ BufferedSubMesh.prototype.draw=function(program){
     context.FLOAT, stride*4, offset*4);
   } else {
    program.setUniforms({"useColorAttr":0.0});
-   attr=program.get("uv");
+   attr=program.get("colorAttr");
    if(attr!==null)context.disableVertexAttribArray(attr);
   }
   offset=Mesh.texCoordOffset(format);