edit docs; add math constants

Author: peteroupc

README.md

@@ -64,8 +64,7 @@ Examples
    rotation[0]+=.5; // Adjust x-rotation by .5 degree
    rotation[1]+=1.0; // Adjust y-rotation by 1 degree
    // Update the shape's rotation
-   var q=GLMath.quatFromTaitBryan(rotation);
-   shape.setOrientation(q);
+   shape.setQuaternion(GLMath.quatFromTaitBryan(rotation));
    // Render the scene
    scene.render();
   });

glmath.js

@@ -36,10 +36,10 @@ var GLMath={
  * The cross product is the vector that is perpendicular to
  * each of two other vectors.<p>
  * If both vectors are unit length
- * (via {@link glmath.GLMath.vec3norm}), the sine of
- * the angle between them is equal to the length of their
+ * (via {@link glmath.GLMath.vec3norm}), the absolute value
+ * of the sine of the angle between them is equal to the length of their
  * cross product. <small>(More formally, the length of the cross
- * product equals |<b>a</b>| * |<b>b</b>| * sin &theta;
+ * product equals |<b>a</b>| * |<b>b</b>| * |sin &theta|;
  * where |<b>x</b>| is the length of vector <b>x</b>.)</small><p>
  * The cross product (<b>c</b>) of vectors <b>a</b> and <b>b</b> is found as
  * follows:<pre>
@@ -424,16 +424,20 @@ return r;
 },
 /**
  * Inverts the rotation given in this quaternion without normalizing it;
- * returns a new quaternion.
+ * returns a new quaternion.  The conjugate represents the same
+ * rotation as the original.
  * @param {Array<number>} quat A quaternion, containing four elements.
+ * @return {Array<number>}
  */
 quatConjugate:function(quat){
  return [-quat[0],-quat[1],-quat[2],quat[3]];
 },
 /**
  * Inverts the rotation given in this quaternion, then normalizes the result;
- * returns a new quaternion.
+ * returns a new quaternion. The inverse represents the same
+ * rotation as the original.
  * @param {Array<number>} quat A quaternion, containing four elements.
+ * @return {Array<number>}
  */
 quatInverse:function(quat){
  return GLMath.quatNormInPlace(
@@ -1085,9 +1089,7 @@ mat4translate:function(mat,v3,v3y,v3z){
  * </ul>
 * @param {number}  fovY Y-axis field of view, in degrees. Should be less
 * than 180 degrees.  (The smaller
-* this number, the bigger close objects appear to be.  As a result,
-* zoom can be implemented by multiplying field of view by an
-* additional factor.)
+* 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
@@ -1118,8 +1120,9 @@ mat4perspective:function(fovY,aspectRatio,near,far){
 * the point in world space that the camera is looking at.  May be null or omitted,
 * in which case the default is the coordinates (0,0,0).
 * @param {Array<number>} [up] A 3-element vector specifying
-* the up-vector direction.  May be null or omitted, in which case
-* the default is a vector pointing positive on the Y axis.  This
+* the direction from the center of the camera to its top. This parameter may
+* be null or omitted, in which case the default is the vector (0, 1, 0),
+* the vector that results when the camera is held upright.  This
 * vector must not point in the same or opposite direction as
 * the camera's view direction. (For best results, rotate the vector (0, 1, 0)
 * so it points perpendicular to the camera's view direction.)
@@ -1299,7 +1302,12 @@ mat4multiply:function(a,b){
 /**
 * Multiplies two quaternions, creating a composite rotation.
 * The quaternions are multiplied such that the second quaternion's
-* rotation happens before the first quaternion's rotation.
+* rotation happens before the first quaternion's rotation.<p>
+* Multiplying two unit quaternions (each with a length of 1) will result
+* in a unit quaternion.  However, for best results, you should
+* normalize the quaternions every few multiplications (using
+* quatNormalize or quatNormInPlace, since successive
+* multiplications can cause rounding errors.
  * @param {Array<number>} a The first quaternion.
  * @param {Array<number>} b The second quaternion.
  * @return {Array<number>} The resulting quaternion.
@@ -1534,6 +1542,18 @@ GLMath.quatScaleInPlace=GLMath.vec4scaleInPlace;
  * @return {Array<number>}
  */
 GLMath.quatCopy=GLMath.vec4copy;
+/**
+ Closest approximation to pi times 2.
+ @const
+ @default
+*/
+GLMath.PiTimes2 = 6.283185307179586476925286766559;
+/**
+ Closest approximation to pi divided by 2.
+ @const
+ @default
+*/
+GLMath.HalfPi = 1.5707963267948966192313216916398;
 /**
  Closest approximation to pi divided by 180. Multiply by this number to convert degrees to radians.
  @const

glutil-meshes.js

@@ -115,7 +115,7 @@ Meshes.createCylinder=function(baseRad, topRad, height, slices, stacks, flat, in
  var normDir=(inside) ? -1 : 1;
  var sc=[0,1]; // sin(0), cos(0)
  var tc=[0];
- var twopi=Math.PI*2;
+ var twopi=GLMath.PiTimes2;
  for(var i=1;i<slices;i++){
   var t=i*1.0/slices;
   var angle=twopi*t;
@@ -294,7 +294,7 @@ Meshes.createPartialDisk=function(inner, outer, slices, loops, start, sweep, inw
  if(sweep==0)sweep=360;
  var sc=[];
  var tc=[];
- var twopi=Math.PI*2;
+ var twopi=GLMath.PiTimes2;
  var arcLength=(sweep==360) ? twopi : sweep*GLMath.PiDividedBy180;
  start=start*GLMath.PiDividedBy180;
  if(sweepDir<0){
@@ -394,7 +394,7 @@ Meshes.createTorus=function(inner, outer, lengthwise, crosswise,flat,inward){
  if(inner==0)return mesh;
  var tubeRadius=inner;
  var circleRad=outer;
- var twopi=Math.PI*2.0;
+ var twopi=GLMath.PiTimes2;
  var sci=[];
  var scj=[];
  for(var i = 0; i <= crosswise; i++){
@@ -530,8 +530,8 @@ Meshes.createSphere=function(radius, slices, stacks, flat, inside){
  var scStack=[];
  var texc=[];
  var tc=[0];
- var twopi=Math.PI*2;
- var pidiv2=Math.PI*0.5;
+ var twopi=GLMath.PiTimes2;
+ var pidiv2=GLMath.HalfPi;
  for(var i=1;i<slices;i++){
   var t=i*1.0/slices;
   var angle=twopi*t;

glutil-shaderprog.js

@@ -151,6 +151,7 @@ ShaderProgram.prototype.use=function(){
  this.savedUniforms={};
  return this;
 }
+/** @private */
 ShaderProgram.prototype._log=function(i,v){
 // console.log("setting "+i+": "+v);
 }
@@ -444,6 +445,25 @@ return ShaderProgram.makeEffect(context,
 "}}"
 ].join("\n"));
 }
+
+/** @private */
+ShaderProgram.getBasicVertex=function(){
+var shader=""+
+"attribute vec3 position;\n" +
+"attribute vec3 uv;\n" +
+"attribute vec3 colorAttr;\n" +
+"varying vec2 uvVar;\n"+
+"varying vec3 colorAttrVar;\n" +
+"void main(){\n"+
+"vec4 positionVec4;\n"+
+"positionVec4.w=1.0;\n"+
+"positionVec4.xyz=position;\n" +
+"gl_PointSize=1.0;\n" +
+"uvVar=uv;\n" +
+"colorAttrVar=colorAttr;\n" +
+"gl_Position=positionVec4;\n" +
+"}\n";
+}
 /**
 * Gets the text of the default vertex shader.  Putting "#define SHADING\n"
 * at the start of the return value enables the lighting model.

glutil-transform.js

@@ -219,8 +219,8 @@ Transform.prototype.setOrientation=function(angle, v,vy,vz){
  */
 Transform.prototype.multQuaternion=function(quat){
   if(this.complexMatrix)return this;
-  this.rotation=GLMath.quatMultiply(this.rotation,quat);
-  GLMath.quatNormInPlace(this.rotation);
+  this.rotation=GLMath.quatNormInPlace(
+   GLMath.quatMultiply(this.rotation,quat));
   this._isIdentity=false;
   this._matrixDirty=true;
   return this;

glutil.js

@@ -653,13 +653,13 @@ function Material(ambient, diffuse, specular,shininess,emission) {
  this.shininess=(shininess==null) ? 0 : Math.min(Math.max(0,shininess),128);
  /** Ambient reflection of this material.<p>
  * Ambient reflection indicates how much an object reflects
- * ambient lights (lights that color pixels
- * the same way regardless of direction or distance)
- * in the red, green, and blue components.
+ * ambient colors, those that color pixels the same way regardless
+ * of direction or distance.
  * Because every part of an object will be shaded the same way by ambient
- * light, an object with just ambient reflection will not look much like a 3D object.
- * Ambient reflection
- * depends on the color of ambient lights.<p>
+ * light, an object with just ambient reflection will not look much like a 3D object.<p>
+ * This value is a 3-element array giving the red, green, and blue
+ * components of the ambient reflection; the final ambient color depends
+ * on the ambient color of the scene.
  * (0,0,0) means no ambient reflection,
  * and (1,1,1) means total ambient reflection.<p>
  * Setting ambient and diffuse reflection to the same value usually defines an object's
@@ -669,14 +669,14 @@ function Material(ambient, diffuse, specular,shininess,emission) {
  */
  this.ambient=ambient ? ambient.slice(0,3) : [0.2,0.2,0.2];
  /**
- * Diffuse reflection of this material.<p>
- * Diffuse reflection indicates how much an object reflects
- * diffuse lights (lights that point
- * directly on the object) in the red, green, and blue components.
- * Because different parts of an object are shaded differently depending
+ * Diffuse reflection of this material. Diffuse reflection is the color that a material
+ * reflects equally in all directions. Because different parts of an object are shaded
+ * differently depending
  * on how directly they face diffuse lights, diffuse reflection can contribute
- * much of the 3D effect of that object.  Diffuse reflection
- * depends on the color of diffuse lights.<p>
+ * much of the 3D effect of that object.<p>
+ * This value is a 4-element array giving the red, green, blue, and
+ * alpha components of the diffuse reflection; the final diffuse color depends
+ * on the reflected colors of lights that shine on the material.
  * (0,0,0,1) means no diffuse reflection,
  * and (1,1,1,1) means total diffuse reflection.<p>
  * Setting ambient and diffuse reflection to the same value usually defines an object's
@@ -688,12 +688,14 @@ function Material(ambient, diffuse, specular,shininess,emission) {
  */
  this.diffuse=diffuse ? diffuse.slice(0,diffuse.length) : [0.8,0.8,0.8,1.0];
  /** Specular highlight reflection of this material.
- * Specular reflection makes an object shiny, and it depends
- * on lights that give off specular highlights as well as on the color
- * of those highlights. Similar to diffuse reflection, specular reflection
+ * Similar to diffuse reflection, specular reflection
  * is affected by how directly each part of an object faces
  * a light that gives off specular highlights, but unlike diffuse light,
  * specular light doesn't scatter very much to other parts of an object.
+ * Specular reflection can make an object shiny.
+ * This value is a 3-element array giving the red, green, and blue
+ * components of the ambient reflection; the final specular color depends
+ * on the specular color of lights that shine on the material.
  * (0,0,0) means no specular reflection,
  * and (1,1,1) means total specular reflection.<p>
 */
@@ -705,6 +707,8 @@ function Material(ambient, diffuse, specular,shininess,emission) {
 * same way regardless of lighting (this property won't be used in the
 * default shader if [Scene3D.disableLighting()]{@link glutil.Scene3D#disableLighting}
 * is called, disabling lighting calculations).<p>
+* This value is a 3-element array giving the red, green, and blue
+* components.
 * For each of the three color components, positive values add to that component,
 * while negative values subtract from it. (0,0,0) means no additive color.
  */
@@ -1373,9 +1377,7 @@ Scene3D.prototype.createBuffer=function(){
  * see {@link glmath.GLMath.mat4perspective}.
  * @param {number}  fov Y-axis field of view, in degrees. Should be less
 * than 180 degrees. (The smaller
-* this number, the bigger close objects appear to be.  As a result,
-* zoom can be implemented by multiplying field of view by an
-* additional factor.)
+* this number, the bigger close objects appear to be.)
 * @param {number}  aspect The ratio of width to height of the viewport, usually
 *  the scene's aspect ratio (getAspect()).
 * @param {number} near The distance from the camera to
@@ -1401,7 +1403,7 @@ Scene3D.prototype.setPerspective=function(fov, aspect, near, far){
  * plane and the top to the bottom.<p>
  * If the view rectangle's aspect ratio doesn't match the desired aspect
  * ratio, the view rectangle will be centered on the 3D scene's viewport
- * or otherwise moved so as to keep the entire view rectangle visible without stretching
+ * or otherwise moved and scaled so as to keep the entire view rectangle visible without stretching
  * or squishing it.
  * <p>
  * For considerations when choosing the "near" and "far" parameters,
@@ -1438,7 +1440,7 @@ Scene3D.prototype.setOrthoAspect=function(left, right, bottom, top, near, far, a
  * The near and far clipping planes will be set to -1 and 1, respectively.<p>
  * If the view rectangle's aspect ratio doesn't match the desired aspect
  * ratio, the view rectangle will be centered on the 3D scene's viewport
- * or otherwise moved so as to keep the entire view rectangle visible without stretching
+ * or otherwise moved and scaled so as to keep the entire view rectangle visible without stretching
  * or squishing it.
  * @param {number} left Leftmost coordinate of the view rectangle.
  * @param {number} right Rightmost coordinate of the view rectangle.
@@ -1640,8 +1642,9 @@ Scene3D.prototype.setViewMatrix=function(matrix){
 * the point in world space that the camera is looking at. May be null or omitted,
 * in which case the default is the coordinates (0,0,0).
 * @param {Array<number>} [up] A 3-element vector specifying
-* the up-vector direction.  May be null or omitted, in which case
-* the default is a vector pointing positive on the Y axis.  This
+* the direction from the center of the camera to its top. This parameter may
+* be null or omitted, in which case the default is the vector (0, 1, 0),
+* the vector that results when the camera is held upright.  This
 * vector must not point in the same or opposite direction as
 * the camera's view direction. (For best results, rotate the vector (0, 1, 0)
 * so it points perpendicular to the camera's view direction.)