Improve documentation and readability in Scene and depth-related code

packages/engine/Source/Core/Matrix4.js

@@ -937,8 +937,8 @@ Matrix4.computeOrthographicOffCenter = function (
  *
  * @param {number} left The number of meters to the left of the camera that will be in view.
  * @param {number} right The number of meters to the right of the camera that will be in view.
- * @param {number} bottom The number of meters below of the camera that will be in view.
- * @param {number} top The number of meters above of the camera that will be in view.
+ * @param {number} bottom The number of meters below the camera that will be in view.
+ * @param {number} top The number of meters above the camera that will be in view.
  * @param {number} near The distance to the near plane in meters.
  * @param {number} far The distance to the far plane in meters.
  * @param {Matrix4} result The object in which the result will be stored.

packages/engine/Source/Core/PerspectiveFrustum.js

@@ -167,65 +167,71 @@ function update(frustum) {
   }
   //>>includeEnd('debug');
 
-  const f = frustum._offCenterFrustum;
-
-  if (
+  const changed =
     frustum.fov !== frustum._fov ||
     frustum.aspectRatio !== frustum._aspectRatio ||
     frustum.near !== frustum._near ||
     frustum.far !== frustum._far ||
     frustum.xOffset !== frustum._xOffset ||
-    frustum.yOffset !== frustum._yOffset
-  ) {
-    //>>includeStart('debug', pragmas.debug);
-    if (frustum.fov < 0 || frustum.fov >= Math.PI) {
-      throw new DeveloperError("fov must be in the range [0, PI).");
-    }
-
-    if (frustum.aspectRatio < 0) {
-      throw new DeveloperError("aspectRatio must be positive.");
-    }
-
-    if (frustum.near < 0 || frustum.near > frustum.far) {
-      throw new DeveloperError(
-        "near must be greater than zero and less than far."
-      );
-    }
-    //>>includeEnd('debug');
-
-    frustum._aspectRatio = frustum.aspectRatio;
-    frustum._fov = frustum.fov;
-    frustum._fovy =
-      frustum.aspectRatio <= 1
-        ? frustum.fov
-        : Math.atan(Math.tan(frustum.fov * 0.5) / frustum.aspectRatio) * 2.0;
-    frustum._near = frustum.near;
-    frustum._far = frustum.far;
-    frustum._sseDenominator = 2.0 * Math.tan(0.5 * frustum._fovy);
-    frustum._xOffset = frustum.xOffset;
-    frustum._yOffset = frustum.yOffset;
-
-    f.top = frustum.near * Math.tan(0.5 * frustum._fovy);
-    f.bottom = -f.top;
-    f.right = frustum.aspectRatio * f.top;
-    f.left = -f.right;
-    f.near = frustum.near;
-    f.far = frustum.far;
-
-    f.right += frustum.xOffset;
-    f.left += frustum.xOffset;
-    f.top += frustum.yOffset;
-    f.bottom += frustum.yOffset;
+    frustum.yOffset !== frustum._yOffset;
+
+  if (!changed) {
+    return;
+  }
+
+  //>>includeStart('debug', pragmas.debug);
+  if (frustum.fov < 0 || frustum.fov >= Math.PI) {
+    throw new DeveloperError("fov must be in the range [0, PI).");
+  }
+
+  if (frustum.aspectRatio < 0) {
+    throw new DeveloperError("aspectRatio must be positive.");
   }
+
+  if (frustum.near < 0 || frustum.near > frustum.far) {
+    throw new DeveloperError(
+      "near must be greater than zero and less than far."
+    );
+  }
+  //>>includeEnd('debug');
+
+  frustum._aspectRatio = frustum.aspectRatio;
+  frustum._fov = frustum.fov;
+  frustum._fovy =
+    frustum.aspectRatio <= 1
+      ? frustum.fov
+      : Math.atan(Math.tan(frustum.fov * 0.5) / frustum.aspectRatio) * 2.0;
+  frustum._near = frustum.near;
+  frustum._far = frustum.far;
+  frustum._sseDenominator = 2.0 * Math.tan(0.5 * frustum._fovy);
+  frustum._xOffset = frustum.xOffset;
+  frustum._yOffset = frustum.yOffset;
+
+  const f = frustum._offCenterFrustum;
+
+  f.top = frustum.near * Math.tan(0.5 * frustum._fovy);
+  f.bottom = -f.top;
+  f.right = frustum.aspectRatio * f.top;
+  f.left = -f.right;
+  f.near = frustum.near;
+  f.far = frustum.far;
+
+  f.right += frustum.xOffset;
+  f.left += frustum.xOffset;
+  f.top += frustum.yOffset;
+  f.bottom += frustum.yOffset;
 }
 
 Object.defineProperties(PerspectiveFrustum.prototype, {
   /**
    * Gets the perspective projection matrix computed from the view frustum.
+   * If necessary, the projection matrix will be recomputed.
+   *
    * @memberof PerspectiveFrustum.prototype
    * @type {Matrix4}
    * @readonly
    *
+   * @see PerspectiveOffCenterFrustum#projectionMatrix.
    * @see PerspectiveFrustum#infiniteProjectionMatrix
    */
   projectionMatrix: {

packages/engine/Source/Core/PerspectiveOffCenterFrustum.js

@@ -108,58 +108,57 @@ function update(frustum) {
   }
   //>>includeEnd('debug');
 
-  const t = frustum.top;
-  const b = frustum.bottom;
-  const r = frustum.right;
-  const l = frustum.left;
-  const n = frustum.near;
-  const f = frustum.far;
+  const { top, bottom, right, left, near, far } = frustum;
+
+  const changed =
+    top !== frustum._top ||
+    bottom !== frustum._bottom ||
+    left !== frustum._left ||
+    right !== frustum._right ||
+    near !== frustum._near ||
+    far !== frustum._far;
+  if (!changed) {
+    return;
+  }
 
-  if (
-    t !== frustum._top ||
-    b !== frustum._bottom ||
-    l !== frustum._left ||
-    r !== frustum._right ||
-    n !== frustum._near ||
-    f !== frustum._far
-  ) {
-    //>>includeStart('debug', pragmas.debug);
-    if (frustum.near <= 0 || frustum.near > frustum.far) {
-      throw new DeveloperError(
-        "near must be greater than zero and less than far."
-      );
-    }
-    //>>includeEnd('debug');
-
-    frustum._left = l;
-    frustum._right = r;
-    frustum._top = t;
-    frustum._bottom = b;
-    frustum._near = n;
-    frustum._far = f;
-    frustum._perspectiveMatrix = Matrix4.computePerspectiveOffCenter(
-      l,
-      r,
-      b,
-      t,
-      n,
-      f,
-      frustum._perspectiveMatrix
-    );
-    frustum._infinitePerspective = Matrix4.computeInfinitePerspectiveOffCenter(
-      l,
-      r,
-      b,
-      t,
-      n,
-      frustum._infinitePerspective
+  //>>includeStart('debug', pragmas.debug);
+  if (frustum.near <= 0 || frustum.near > frustum.far) {
+    throw new DeveloperError(
+      "near must be greater than zero and less than far."
     );
   }
+  //>>includeEnd('debug');
+
+  frustum._left = left;
+  frustum._right = right;
+  frustum._top = top;
+  frustum._bottom = bottom;
+  frustum._near = near;
+  frustum._far = far;
+  frustum._perspectiveMatrix = Matrix4.computePerspectiveOffCenter(
+    left,
+    right,
+    bottom,
+    top,
+    near,
+    far,
+    frustum._perspectiveMatrix
+  );
+  frustum._infinitePerspective = Matrix4.computeInfinitePerspectiveOffCenter(
+    left,
+    right,
+    bottom,
+    top,
+    near,
+    frustum._infinitePerspective
+  );
 }
 
 Object.defineProperties(PerspectiveOffCenterFrustum.prototype, {
   /**
    * Gets the perspective projection matrix computed from the view frustum.
+   * The projection matrix will be recomputed if any frustum parameters have changed.
+   *
    * @memberof PerspectiveOffCenterFrustum.prototype
    * @type {Matrix4}
    * @readonly

packages/engine/Source/Renderer/Context.js

@@ -1409,7 +1409,7 @@ Context.prototype.draw = function (
   //>>includeEnd('debug');
 
   passState = defaultValue(passState, this._defaultPassState);
-  // The command's framebuffer takes presidence over the pass' framebuffer, e.g., for off-screen rendering.
+  // The command's framebuffer takes precedence over the pass' framebuffer, e.g., for off-screen rendering.
   const framebuffer = defaultValue(
     drawCommand._framebuffer,
     passState.framebuffer

packages/engine/Source/Renderer/DrawCommand.js

@@ -16,6 +16,9 @@ const Flags = {
 /**
  * Represents a command to the renderer for drawing.
  *
+ * @alias DrawCommand
+ * @constructor
+ *
  * @private
  */
 function DrawCommand(options) {