add much to docs

Author: peteroupc

glmath.js

@@ -1055,6 +1055,21 @@ mat4translate:function(mat,v3,v3y,v3z){
  * 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><b>Choosing the "near" and "far" parameters:</b>
+ * Depth buffers often have 16 bits per pixel; each pixel isn't usually
+ * a floating-point number.  If the difference between "far" and "near"
+ * is too high, the depth buffer can't distinguish well between two objects
+ * that are very close, especially if both objects are quite far in the distance.
+ * For best results:<ul>
+ * <li>For <code>mat4perspective</code> and <code>mat4frustum</code>,
+* the "near" parameter 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.1 or 1.  This doesn't apply to <code>mat4ortho</code>.</li>
+ * <li>The difference between "far" and "near" should not be greater than 65536
+ * (the number of possible values per pixel in a 16-bit depth buffer) and should be
+ * as small as the application can accept.  In any case, "far" cannot be less than
+ * "near".</li>
+ * </ul>
 * @param {number}  fovY Vertical 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,
@@ -1064,18 +1079,18 @@ mat4translate:function(mat,v3,v3y,v3z){
 *  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. This should be slightly greater than 0.
-* @param {number}  farZ The distance from the camera to
+* seen.
+* @param {number} far The distance from the camera to
 * the far clipping plane. Objects beyond this distance will be too far
 * to be seen.
  * @return {Array<number>} The resulting 4x4 matrix.
  */
-mat4perspective:function(fovY,aspectRatio,nearZ,farZ){
+mat4perspective:function(fovY,aspectRatio,near,far){
  var f = 1/Math.tan(fovY*GLMath.PiDividedBy360);
- var nmf = nearZ-farZ;
+ var nmf = near-far;
  nmf=1/nmf;
  return [f/aspectRatio, 0, 0, 0, 0, f, 0, 0, 0, 0,
-   nmf*(nearZ+farZ), -1, 0, 0, nmf*nearZ*farZ*2, 0]
+   nmf*(near+far), -1, 0, 0, nmf*near*far*2, 0]
 },
 /**
  * Returns a 4x4 matrix representing a camera view.<p>
@@ -1131,6 +1146,9 @@ mat4lookat:function(viewerPos,lookingAt,up){
  * 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 Leftmost coordinate of the 3D view.
  * @param {number} r Rightmost coordinate of the 3D view.
  * (Note that r can be greater than l or vice versa.)
@@ -1174,6 +1192,9 @@ mat4ortho2d:function(l,r,b,t){
  * 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
@@ -1184,7 +1205,7 @@ mat4ortho2d:function(l,r,b,t){
  * clipping plane meets the near clipping plane.
 * @param {number} n The distance from the camera to
 * the near clipping plane. Objects closer than this distance won't be
-* seen. This should be slightly greater than 0.
+* seen.
 * @param {number} f The distance from the camera to
 * the far clipping plane. Objects beyond this distance will be too far
 * to be seen.

glutil-eval.js

@@ -159,7 +159,7 @@ function BezierCurve(cp, u1, u2){
  * in a Bézier curve.
  * @param {number} u Point on the curve to evaluate (generally within the range
  * given in the constructor).
- * @return An array of the result of
+ * @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.
  */
@@ -228,7 +228,7 @@ function BezierSurface(cp, u1, u2, v1, v2){
  * @param {number} u U-coordinate of the surface to evaluate (generally within the range
  * given in the constructor).
  * @param {number} v V-coordinate of the surface to evaluate.
- * @return An array of the result of
+ * @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.
  */

glutil.js

@@ -1221,7 +1221,7 @@ function Scene3D(canvasOrContext){
  this.context.blendFunc(context.SRC_ALPHA,context.ONE_MINUS_SRC_ALPHA);
  this.context.enable(this.context.DEPTH_TEST);
  this.context.depthFunc(this.context.LEQUAL);
- this.context.clearDepth(999999);
+ this.context.clearDepth(1.0);
  this._setClearColor();
  this.context.clear(
     this.context.COLOR_BUFFER_BIT |
@@ -1327,7 +1327,10 @@ Scene3D.prototype.createBuffer=function(){
 
 /**
 *  Sets this scene's projection matrix to a perspective projection.
-* @param {number}  fov Vertical field of view, in degrees. Should be less
+ * <p>
+ * For considerations when choosing the "near" and "far" parameters,
+ * see {@link glmath.GLMath.mat4perspective}.
+ * @param {number}  fov Vertical 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
@@ -1336,7 +1339,7 @@ Scene3D.prototype.createBuffer=function(){
 *  the scene's aspect ratio (getAspect()).
 * @param {number} near The distance from the camera to
 * the near clipping plane. Objects closer than this distance won't be
-* seen. This should be slightly greater than 0.
+* seen.
 * @param {number}  far The distance from the camera to
 * the far clipping plane. Objects beyond this distance will be too far
 * to be seen.
@@ -1353,6 +1356,9 @@ Scene3D.prototype.setPerspective=function(fov, aspect, near, far){
 /**
  * Sets this scene's projection matrix to a perspective projection that defines
  * the view frustum, or the limits in the camera's view.
+ * <p>
+ * For considerations when choosing the "near" and "far" parameters,
+ * see {@link glmath.GLMath.mat4perspective}.
  * @param {number} left X-coordinate of the point where the left
  * clipping plane meets the near clipping plane.
  * @param {number} right X-coordinate of the point where the right
@@ -1363,7 +1369,7 @@ Scene3D.prototype.setPerspective=function(fov, aspect, near, far){
  * clipping plane meets the near clipping plane.
 * @param {number} near The distance from the camera to
 * the near clipping plane. Objects closer than this distance won't be
-* seen. This should be slightly greater than 0.
+* seen.
 * @param {number}  far The distance from the camera to
 * the far clipping plane. Objects beyond this distance will be too far
 * to be seen.
@@ -1377,6 +1383,9 @@ Scene3D.prototype.setFrustum=function(left,right,bottom,top,near,far){
  * Sets this scene's projection matrix to an orthographic projection.
  * In this projection, the left clipping plane is parallel to the right clipping
  * plane and the top to the bottom.
+ * <p>
+ * For considerations when choosing the "near" and "far" parameters,
+ * see {@link glmath.GLMath.mat4perspective}.
  * @param {number} left Leftmost coordinate of the 3D view.
  * @param {number} right Rightmost coordinate of the 3D view.
  * (Note that right can be greater than left or vice versa.)