Merge remote-tracking branch 'origin/main' into gpm-support

# Conflicts:
#	packages/engine/Source/Scene/DerivedCommand.js

CHANGES.md

@@ -17,6 +17,10 @@
 - Reverts Firefox OIT temporary fix [#4815] and Firefox test failure fix [#5047]
 - Fixed noise in ambient occlusion post process. [#12201](https://github.com/CesiumGS/cesium/pull/12201)
 
+##### Deprecated :hourglass_flowing_sand:
+
+- `Rectangle.validate` has been deprecated. It will be removed in 1.124.
+
 ### 1.121.1 - 2024-09-04
 
 This is an npm-only release to extra source maps included in 1.121

CONTRIBUTORS.md

@@ -207,6 +207,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to contribute to Cesiu
 
 ## [Individual CLA](Documentation/Contributors/CLAs/individual-contributor-license-agreement-v1.0.pdf)
 
+- [Brandon Landry](https://github.com/hotpocket)
 - [Victor Berchet](https://github.com/vicb)
 - [Caleb Morse](https://github.com/cmorse)
 - [Ravi Agrawal](https://github.com/macoda)

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/Occluder.js

@@ -300,8 +300,6 @@ const tempScratch = new Cartesian3();
  * const cameraPosition = new Cesium.Cartesian3(0, 0, 0);
  * const occluder = new Cesium.Occluder(sphere1, cameraPosition);
  * occluder.computeVisibility(sphere2); //returns Visibility.NONE
- *
- * @see Occluder#isVisible
  */
 Occluder.prototype.computeVisibility = function (occludeeBS) {
   //>>includeStart('debug', pragmas.debug);

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);
+  Check.typeOf.number.greaterThanOrEquals("fov", frustum.fov, 0.0);
+  Check.typeOf.number.lessThan("fov", frustum.fov, Math.PI);
+
+  Check.typeOf.number.greaterThanOrEquals(
+    "aspectRatio",
+    frustum.aspectRatio,
+    0.0,
+  );
+
+  Check.typeOf.number.greaterThanOrEquals("near", frustum.near, 0.0);
+  if (frustum.near > frustum.far) {
+    throw new DeveloperError("near must be 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/Core/Rectangle.js

@@ -7,6 +7,7 @@ import Ellipsoid from "./Ellipsoid.js";
 import CesiumMath from "./Math.js";
 import Transforms from "./Transforms.js";
 import Matrix4 from "./Matrix4.js";
+import deprecationWarning from "./deprecationWarning.js";
 
 /**
  * A two dimensional region specified as longitude and latitude coordinates.
@@ -541,8 +542,28 @@ Rectangle.prototype.equalsEpsilon = function (other, epsilon) {
  * @exception {DeveloperError} <code>south</code> must be in the interval [<code>-Pi/2</code>, <code>Pi/2</code>].
  * @exception {DeveloperError} <code>east</code> must be in the interval [<code>-Pi</code>, <code>Pi</code>].
  * @exception {DeveloperError} <code>west</code> must be in the interval [<code>-Pi</code>, <code>Pi</code>].
+ * @deprecated This function is deprecated and will be removed in Cesium 1.124. See <a href="https://github.com/CesiumGS/cesium/issues/4921">Issue 4921</a>
  */
 Rectangle.validate = function (rectangle) {
+  deprecationWarning(
+    "Rectangle.validate",
+    "Rectangle.validate is a no-op and has been deprecated. It will be removed in Cesium 1.124.",
+  );
+  return Rectangle._validate(rectangle);
+};
+
+/**
+ * Checks a Rectangle's properties and throws if they are not in valid ranges.
+ *
+ * @param {Rectangle} rectangle The rectangle to validate
+ *
+ * @exception {DeveloperError} <code>north</code> must be in the interval [<code>-Pi/2</code>, <code>Pi/2</code>].
+ * @exception {DeveloperError} <code>south</code> must be in the interval [<code>-Pi/2</code>, <code>Pi/2</code>].
+ * @exception {DeveloperError} <code>east</code> must be in the interval [<code>-Pi</code>, <code>Pi</code>].
+ * @exception {DeveloperError} <code>west</code> must be in the interval [<code>-Pi</code>, <code>Pi</code>].
+ * @private
+ */
+Rectangle._validate = function (rectangle) {
   //>>includeStart('debug', pragmas.debug);
   Check.typeOf.object("rectangle", rectangle);
 

packages/engine/Source/Core/RectangleGeometry.js

@@ -1020,7 +1020,7 @@ function RectangleGeometry(options) {
 
   //>>includeStart('debug', pragmas.debug);
   Check.typeOf.object("rectangle", rectangle);
-  Rectangle.validate(rectangle);
+  Rectangle._validate(rectangle);
   if (rectangle.north < rectangle.south) {
     throw new DeveloperError(
       "options.rectangle.north must be greater than or equal to options.rectangle.south",
@@ -1199,7 +1199,7 @@ RectangleGeometry.computeRectangle = function (options, result) {
 
   //>>includeStart('debug', pragmas.debug);
   Check.typeOf.object("rectangle", rectangle);
-  Rectangle.validate(rectangle);
+  Rectangle._validate(rectangle);
   if (rectangle.north < rectangle.south) {
     throw new DeveloperError(
       "options.rectangle.north must be greater than or equal to options.rectangle.south",

packages/engine/Source/Core/RectangleOutlineGeometry.js

@@ -284,7 +284,7 @@ function RectangleOutlineGeometry(options) {
   if (!defined(rectangle)) {
     throw new DeveloperError("rectangle is required.");
   }
-  Rectangle.validate(rectangle);
+  Rectangle._validate(rectangle);
   if (rectangle.north < rectangle.south) {
     throw new DeveloperError(
       "options.rectangle.north must be greater than options.rectangle.south",

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) {