@cesium/engine 23.0.1 → 25.0.0

package/Source/Scene/QuadtreeTileLoadState.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 /**
  * The state of a {@link QuadtreeTile} in the tile load pipeline.
  * @enum {number}
@@ -36,4 +38,7 @@ const QuadtreeTileLoadState = {
    */
   FAILED: 3,
 };
-export default Object.freeze(QuadtreeTileLoadState);
+
+Object.freeze(QuadtreeTileLoadState);
+
+export default QuadtreeTileLoadState;

package/Source/Scene/QuadtreeTileProvider.js

@@ -1,212 +1,196 @@
+// @ts-check
+
 import DeveloperError from "../Core/DeveloperError.js";
 
+/** @import Context from "../Renderer/Context.js"; */
+/** @import DrawCommand from "../Renderer/DrawCommand.js"; */
+/** @import FrameState from "./FrameState.js"; */
+/** @import QuadtreeOccluders from "./QuadtreeOccluders.js"; */
+/** @import QuadtreePrimitive from "./QuadtreePrimitive.js"; */
+/** @import QuadtreeTile from "./QuadtreeTile.js"; */
+/** @import TilingScheme from "../Core/TilingScheme.js"; */
+/** @import Visibility from "../Core/Visibility.js"; */
+
 /**
  * Provides general quadtree tiles to be displayed on or near the surface of an ellipsoid.  It is intended to be
  * used with the {@link QuadtreePrimitive}.  This type describes an interface and is not intended to be
  * instantiated directly.
  *
- * @alias QuadtreeTileProvider
- * @constructor
+ * @interface
  * @private
  */
-function QuadtreeTileProvider() {
-  DeveloperError.throwInstantiationError();
-}
-
-/**
- * Computes the default geometric error for level zero of the quadtree.
- *
- * @memberof QuadtreeTileProvider
- *
- * @param {TilingScheme} tilingScheme The tiling scheme for which to compute the geometric error.
- * @returns {number} The maximum geometric error at level zero, in meters.
- */
-QuadtreeTileProvider.computeDefaultLevelZeroMaximumGeometricError = function (
-  tilingScheme,
-) {
-  return (
-    (tilingScheme.ellipsoid.maximumRadius * 2 * Math.PI * 0.25) /
-    (65 * tilingScheme.getNumberOfXTilesAtLevel(0))
-  );
-};
-
-Object.defineProperties(QuadtreeTileProvider.prototype, {
+class QuadtreeTileProvider {
   /**
    * Gets or sets the {@link QuadtreePrimitive} for which this provider is
    * providing tiles.
-   * @memberof QuadtreeTileProvider.prototype
    * @type {QuadtreePrimitive}
    */
-  quadtree: {
-    get: DeveloperError.throwInstantiationError,
-    set: DeveloperError.throwInstantiationError,
-  },
+  quadtree;
 
   /**
    * Gets the tiling scheme used by the provider.
-   * @memberof QuadtreeTileProvider.prototype
    * @type {TilingScheme}
    */
-  tilingScheme: {
-    get: DeveloperError.throwInstantiationError,
-  },
+  tilingScheme;
 
   /**
    * Gets an event that is raised when the geometry provider encounters an asynchronous error.  By subscribing
    * to the event, you will be notified of the error and can potentially recover from it.  Event listeners
    * are passed an instance of {@link TileProviderError}.
-   * @memberof QuadtreeTileProvider.prototype
    * @type {Event}
    */
-  errorEvent: {
-    get: DeveloperError.throwInstantiationError,
-  },
-});
+  errorEvent;
 
-/**
- * Called at the beginning of the update cycle, regardless of id a new frame is being rendered, before {@link QuadtreeTileProvider#beginUpdate}
- * @memberof QuadtreeTileProvider
- * @function
- *
- * @param {Context} context The rendering context.
- * @param {FrameState} frameState The frame state.
- */
-QuadtreeTileProvider.prototype.update = DeveloperError.throwInstantiationError;
+  constructor() {
+    DeveloperError.throwInstantiationError();
+  }
 
-/**
- * Called at the beginning of the update cycle for each render frame, before {@link QuadtreeTileProvider#showTileThisFrame}
- * or any other functions.
- * @memberof QuadtreeTileProvider
- * @function
- *
- * @param {Context} context The rendering context.
- * @param {FrameState} frameState The frame state.
- * @param {DrawCommand[]} commandList An array of rendering commands.  This method may push
- *        commands into this array.
- */
-QuadtreeTileProvider.prototype.beginUpdate =
-  DeveloperError.throwInstantiationError;
+  /**
+   * Computes the default geometric error for level zero of the quadtree.
+   *
+   * @param {TilingScheme} tilingScheme The tiling scheme for which to compute the geometric error.
+   * @returns {number} The maximum geometric error at level zero, in meters.
+   */
+  static computeDefaultLevelZeroMaximumGeometricError(tilingScheme) {
+    return (
+      (tilingScheme.ellipsoid.maximumRadius * 2 * Math.PI * 0.25) /
+      (65 * tilingScheme.getNumberOfXTilesAtLevel(0))
+    );
+  }
 
-/**
- * Called at the end of the update cycle for each render frame, after {@link QuadtreeTileProvider#showTileThisFrame}
- * and any other functions.
- * @memberof QuadtreeTileProvider
- * @function
- *
- * @param {Context} context The rendering context.
- * @param {FrameState} frameState The frame state.
- * @param {DrawCommand[]} commandList An array of rendering commands.  This method may push
- *        commands into this array.
- */
-QuadtreeTileProvider.prototype.endUpdate =
-  DeveloperError.throwInstantiationError;
+  /**
+   * Called at the beginning of the update cycle, regardless of id a new frame is being rendered, before {@link QuadtreeTileProvider#beginUpdate}
+   *
+   * @param {Context} context The rendering context.
+   * @param {FrameState} frameState The frame state.
+   */
+  update(context, frameState) {
+    DeveloperError.throwInstantiationError();
+  }
 
-/**
- * Gets the maximum geometric error allowed in a tile at a given level, in meters.
- *
- * @see QuadtreeTileProvider#computeDefaultLevelZeroMaximumGeometricError
- *
- * @memberof QuadtreeTileProvider
- * @function
- *
- * @param {number} level The tile level for which to get the maximum geometric error.
- * @returns {number} The maximum geometric error in meters.
- */
-QuadtreeTileProvider.prototype.getLevelMaximumGeometricError =
-  DeveloperError.throwInstantiationError;
+  /**
+   * Called at the beginning of the update cycle for each render frame, before {@link QuadtreeTileProvider#showTileThisFrame}
+   * or any other functions.
+   *
+   * @param {Context} context The rendering context.
+   * @param {FrameState} frameState The frame state.
+   * @param {DrawCommand[]} commandList An array of rendering commands.  This method may push
+   *        commands into this array.
+   */
+  beginUpdate(context, frameState, commandList) {
+    DeveloperError.throwInstantiationError();
+  }
 
-/**
- * Loads, or continues loading, a given tile.  This function will continue to be called
- * until {@link QuadtreeTile#state} is no longer {@link QuadtreeTileLoadState#LOADING}.
- *
- * @memberof QuadtreeTileProvider
- * @function
- *
- * @param {Context} context The rendering context.
- * @param {FrameState} frameState The frame state.
- * @param {QuadtreeTile} tile The tile to load.
- */
-QuadtreeTileProvider.prototype.loadTile =
-  DeveloperError.throwInstantiationError;
+  /**
+   * Called at the end of the update cycle for each render frame, after {@link QuadtreeTileProvider#showTileThisFrame}
+   * and any other functions.
+   *
+   * @param {Context} context The rendering context.
+   * @param {FrameState} frameState The frame state.
+   * @param {DrawCommand[]} commandList An array of rendering commands.  This method may push
+   *        commands into this array.
+   */
+  endUpdate(context, frameState, commandList) {
+    DeveloperError.throwInstantiationError();
+  }
 
-/**
- * Determines the visibility of a given tile.  The tile may be fully visible, partially visible, or not
- * visible at all.  Tiles that are renderable and are at least partially visible will be shown by a call
- * to {@link QuadtreeTileProvider#showTileThisFrame}.
- *
- * @memberof QuadtreeTileProvider
- *
- * @param {QuadtreeTile} tile The tile instance.
- * @param {FrameState} frameState The state information about the current frame.
- * @param {QuadtreeOccluders} occluders The objects that may occlude this tile.
- *
- * @returns {Visibility} The visibility of the tile.
- */
-QuadtreeTileProvider.prototype.computeTileVisibility =
-  DeveloperError.throwInstantiationError;
+  /**
+   * Gets the maximum geometric error allowed in a tile at a given level, in meters.
+   *
+   * @see QuadtreeTileProvider#computeDefaultLevelZeroMaximumGeometricError
+   *
+   * @param {number} level The tile level for which to get the maximum geometric error.
+   * @returns {number} The maximum geometric error in meters.
+   */
+  getLevelMaximumGeometricError(level) {
+    DeveloperError.throwInstantiationError();
+  }
 
-/**
- * Shows a specified tile in this frame.  The provider can cause the tile to be shown by adding
- * render commands to the commandList, or use any other method as appropriate.  The tile is not
- * expected to be visible next frame as well, unless this method is call next frame, too.
- *
- * @memberof QuadtreeTileProvider
- * @function
- *
- * @param {QuadtreeTile} tile The tile instance.
- * @param {Context} context The rendering context.
- * @param {FrameState} frameState The state information of the current rendering frame.
- * @param {DrawCommand[]} commandList The list of rendering commands.  This method may add additional commands to this list.
- */
-QuadtreeTileProvider.prototype.showTileThisFrame =
-  DeveloperError.throwInstantiationError;
+  /**
+   * Loads, or continues loading, a given tile.  This function will continue to be called
+   * until {@link QuadtreeTile#state} is no longer {@link QuadtreeTileLoadState#LOADING}.
+   *
+   * @param {Context} context The rendering context.
+   * @param {FrameState} frameState The frame state.
+   * @param {QuadtreeTile} tile The tile to load.
+   */
+  loadTile(context, frameState, tile) {
+    DeveloperError.throwInstantiationError();
+  }
 
-/**
- * Gets the distance from the camera to the closest point on the tile.  This is used for level-of-detail selection.
- *
- * @memberof QuadtreeTileProvider
- * @function
- *
- * @param {QuadtreeTile} tile The tile instance.
- * @param {FrameState} frameState The state information of the current rendering frame.
- *
- * @returns {number} The distance from the camera to the closest point on the tile, in meters.
- */
-QuadtreeTileProvider.prototype.computeDistanceToTile =
-  DeveloperError.throwInstantiationError;
+  /**
+   * Determines the visibility of a given tile.  The tile may be fully visible, partially visible, or not
+   * visible at all.  Tiles that are renderable and are at least partially visible will be shown by a call
+   * to {@link QuadtreeTileProvider#showTileThisFrame}.
+   *
+   * @param {QuadtreeTile} tile The tile instance.
+   * @param {FrameState} frameState The state information about the current frame.
+   * @param {QuadtreeOccluders} occluders The objects that may occlude this tile.
+   *
+   * @returns {Visibility} The visibility of the tile.
+   */
+  computeTileVisibility(tile, frameState, occluders) {
+    DeveloperError.throwInstantiationError();
+  }
 
-/**
- * Returns true if this object was destroyed; otherwise, false.
- * <br /><br />
- * If this object was destroyed, it should not be used; calling any function other than
- * <code>isDestroyed</code> will result in a {@link DeveloperError} exception.
- *
- * @memberof QuadtreeTileProvider
- *
- * @returns {boolean} True if this object was destroyed; otherwise, false.
- *
- * @see QuadtreeTileProvider#destroy
- */
-QuadtreeTileProvider.prototype.isDestroyed =
-  DeveloperError.throwInstantiationError;
+  /**
+   * Shows a specified tile in this frame.  The provider can cause the tile to be shown by adding
+   * render commands to the commandList, or use any other method as appropriate.  The tile is not
+   * expected to be visible next frame as well, unless this method is call next frame, too.
+   *
+   * @param {QuadtreeTile} tile The tile instance.
+   * @param {Context} context The rendering context.
+   * @param {FrameState} frameState The state information of the current rendering frame.
+   * @param {DrawCommand[]} commandList The list of rendering commands.  This method may add additional commands to this list.
+   */
+  showTileThisFrame(tile, context, frameState, commandList) {
+    DeveloperError.throwInstantiationError();
+  }
+
+  /**
+   * Gets the distance from the camera to the closest point on the tile.  This is used for level-of-detail selection.
+   *
+   * @param {QuadtreeTile} tile The tile instance.
+   * @param {FrameState} frameState The state information of the current rendering frame.
+   *
+   * @returns {number} The distance from the camera to the closest point on the tile, in meters.
+   */
+  computeDistanceToTile(tile, frameState) {
+    DeveloperError.throwInstantiationError();
+  }
+
+  /**
+   * Returns true if this object was destroyed; otherwise, false.
+   * <br /><br />
+   * If this object was destroyed, it should not be used; calling any function other than
+   * <code>isDestroyed</code> will result in a {@link DeveloperError} exception.
+   *
+   * @returns {boolean} True if this object was destroyed; otherwise, false.
+   *
+   * @see QuadtreeTileProvider#destroy
+   */
+  isDestroyed() {
+    DeveloperError.throwInstantiationError();
+  }
+
+  /**
+   * Destroys the WebGL resources held by this object.  Destroying an object allows for deterministic
+   * release of WebGL resources, instead of relying on the garbage collector to destroy this object.
+   * <br /><br />
+   * Once an object is destroyed, it should not be used; calling any function other than
+   * <code>isDestroyed</code> will result in a {@link DeveloperError} exception.  Therefore,
+   * assign the return value (<code>undefined</code>) to the object as done in the example.
+   *
+   * @exception {DeveloperError} This object was destroyed, i.e., destroy() was called.
+   *
+   * @example
+   * provider = provider && provider();
+   *
+   * @see QuadtreeTileProvider#isDestroyed
+   */
+  destroy() {
+    DeveloperError.throwInstantiationError();
+  }
+}
 
-/**
- * Destroys the WebGL resources held by this object.  Destroying an object allows for deterministic
- * release of WebGL resources, instead of relying on the garbage collector to destroy this object.
- * <br /><br />
- * Once an object is destroyed, it should not be used; calling any function other than
- * <code>isDestroyed</code> will result in a {@link DeveloperError} exception.  Therefore,
- * assign the return value (<code>undefined</code>) to the object as done in the example.
- *
- * @memberof QuadtreeTileProvider
- *
- * @exception {DeveloperError} This object was destroyed, i.e., destroy() was called.
- *
- *
- * @example
- * provider = provider && provider();
- *
- * @see QuadtreeTileProvider#isDestroyed
- */
-QuadtreeTileProvider.prototype.destroy = DeveloperError.throwInstantiationError;
 export default QuadtreeTileProvider;

package/Source/Scene/ResourceLoader.js

@@ -17,7 +17,6 @@ class ResourceLoader {
   /**
    * The cache key of the resource.
    *
-   * @memberof ResourceLoader.prototype
    *
    * @type {string}
    * @readonly

package/Source/Scene/ResourceLoaderState.js

@@ -1,6 +1,9 @@
+// @ts-check
+
 /**
  * The {@link ResourceLoader} state.
  *
+ * @enum {number}
  * @private
  */
 const ResourceLoaderState = {
@@ -53,4 +56,7 @@ const ResourceLoaderState = {
    */
   FAILED: 5,
 };
-export default Object.freeze(ResourceLoaderState);
+
+Object.freeze(ResourceLoaderState);
+
+export default ResourceLoaderState;

package/Source/Scene/SceneMode.js

@@ -53,4 +53,7 @@ SceneMode.getMorphTime = function (value) {
   }
   return 0.0;
 };
-export default Object.freeze(SceneMode);
+
+Object.freeze(SceneMode);
+
+export default SceneMode;

package/Source/Scene/ScreenSpaceCameraController.js

@@ -2360,6 +2360,19 @@ function zoom3D(controller, startPosition, movement) {
   let distance;
   if (defined(intersection)) {
     distance = Cartesian3.distance(ray.origin, intersection);
+  }
+
+  // In tracking/lookAt mode (_globe is undefined), pickPosition can hit terrain
+  // behind the intended target. Ignore farther picks to prevent zoom snap.
+  if (!defined(controller._globe) && defined(distance)) {
+    const targetDistance = camera.getMagnitude();
+    if (targetDistance < distance) {
+      intersection = undefined;
+      distance = undefined;
+    }
+  }
+
+  if (defined(distance)) {
     preIntersectionDistance = distance;
   }
 

package/Source/Scene/ShadowMode.js

@@ -75,4 +75,6 @@ ShadowMode.fromCastReceive = function (castShadows, receiveShadows) {
   return ShadowMode.DISABLED;
 };
 
-export default Object.freeze(ShadowMode);
+Object.freeze(ShadowMode);
+
+export default ShadowMode;

package/Source/Scene/SkyBox.js

@@ -35,14 +35,7 @@ import destroyObject from "../Core/destroyObject.js";
  */
 function SkyBox(options) {
   this._sources = options.sources;
-
-  /**
-   * Determines if the sky box will be shown.
-   *
-   * @type {boolean}
-   * @default true
-   */
-  this.show = options.show ?? true;
+  this._show = options.show ?? true;
   this._panorama = new CubeMapPanorama({
     sources: this._sources,
     show: this._show,
@@ -64,6 +57,22 @@ Object.defineProperties(SkyBox.prototype, {
       this._panorama.sources = value;
     },
   },
+
+  /**
+   * Determines if the sky box will be shown.
+   * @memberof SkyBox.prototype
+   * @type {boolean}
+   * @default true
+   */
+
+  show: {
+    get: function () {
+      return this._panorama.show;
+    },
+    set: function (value) {
+      this._panorama.show = value;
+    },
+  },
 });
 
 /**

package/Source/Scene/SplitDirection.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 /**
  * The direction to display a primitive or ImageryLayer relative to the {@link Scene#splitPosition}.
  *
@@ -31,4 +33,7 @@ const SplitDirection = {
    */
   RIGHT: 1.0,
 };
-export default Object.freeze(SplitDirection);
+
+Object.freeze(SplitDirection);
+
+export default SplitDirection;

package/Source/Scene/StencilFunction.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 import WebGLConstants from "../Core/WebGLConstants.js";
 
 /**
@@ -70,4 +72,7 @@ const StencilFunction = {
    */
   ALWAYS: WebGLConstants.ALWAYS,
 };
-export default Object.freeze(StencilFunction);
+
+Object.freeze(StencilFunction);
+
+export default StencilFunction;

package/Source/Scene/StencilOperation.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 import WebGLConstants from "../Core/WebGLConstants.js";
 
 /**
@@ -70,4 +72,7 @@ const StencilOperation = {
    */
   DECREMENT_WRAP: WebGLConstants.DECR_WRAP,
 };
-export default Object.freeze(StencilOperation);
+
+Object.freeze(StencilOperation);
+
+export default StencilOperation;

package/Source/Scene/TerrainState.js

@@ -1,4 +1,7 @@
+// @ts-check
+
 /**
+ * @enum {number}
  * @private
  */
 const TerrainState = {
@@ -10,4 +13,7 @@ const TerrainState = {
   TRANSFORMED: 5,
   READY: 6,
 };
-export default Object.freeze(TerrainState);
+
+Object.freeze(TerrainState);
+
+export default TerrainState;

package/Source/Scene/TileBoundingRegion.js

@@ -462,7 +462,7 @@ TileBoundingRegion.prototype.createDebugVolume = function (color) {
   Check.defined("color", color);
   //>>includeEnd('debug');
 
-  const modelMatrix = new Matrix4.clone(Matrix4.IDENTITY);
+  const modelMatrix = Matrix4.clone(Matrix4.IDENTITY);
   const geometry = new RectangleOutlineGeometry({
     rectangle: this.rectangle,
     height: this.minimumHeight,

package/Source/Scene/TileBoundingS2Cell.js

@@ -627,7 +627,7 @@ TileBoundingS2Cell.prototype.createDebugVolume = function (color) {
   Check.defined("color", color);
   //>>includeEnd('debug');
 
-  const modelMatrix = new Matrix4.clone(Matrix4.IDENTITY);
+  const modelMatrix = Matrix4.clone(Matrix4.IDENTITY);
   const topPlanePolygon = new CoplanarPolygonOutlineGeometry({
     polygonHierarchy: {
       positions: this._planeVertices[0],

package/Source/Scene/TileBoundingSphere.js

@@ -144,7 +144,7 @@ TileBoundingSphere.prototype.createDebugVolume = function (color) {
   });
   const modelMatrix = Matrix4.fromTranslation(
     this.center,
-    new Matrix4.clone(Matrix4.IDENTITY),
+    Matrix4.clone(Matrix4.IDENTITY),
   );
   const instance = new GeometryInstance({
     geometry: geometry,

package/Source/Scene/TileState.js

@@ -1,4 +1,7 @@
+// @ts-check
+
 /**
+ * @enum {number}
  * @private
  */
 const TileState = {
@@ -7,4 +10,7 @@ const TileState = {
   READY: 2,
   UPSAMPLED_ONLY: 3,
 };
-export default Object.freeze(TileState);
+
+Object.freeze(TileState);
+
+export default TileState;

package/Source/Scene/Tonemapper.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 /**
  * A tonemapping algorithm when rendering with high dynamic range.
  *
@@ -61,4 +63,6 @@ export function validateTonemapper(tonemapper) {
   );
 }
 
-export default Object.freeze(Tonemapper);
+Object.freeze(Tonemapper);
+
+export default Tonemapper;

package/Source/Scene/TweenCollection.js

@@ -562,6 +562,13 @@ TweenCollection.prototype.update = function (time) {
     } else if (tweenjs.update(time)) {
       i++;
     } else {
+      // there's a chance that the update callback has side effects that clear the list of tweens and/or adds new tweens
+      // if it's the case that the update callback 1) clears all tweens held in the scene, then 2) adds new tweens
+      // the splice operation below will not be operating on the original tween, but one of the unprocessed tweens added
+      // from the update callback
+      if (tweens[i]?.needsStart) {
+        continue;
+      }
       tweenjs.stop();
       tweens.splice(i, 1);
     }