@cesium/engine 21.0.1 → 22.0.0

package/Source/Scene/Picking.js

@@ -262,9 +262,9 @@ function computePickingDrawingBufferRectangle(
 }
 
 /**
- * Returns an object with a <code>primitive</code> property that contains the first (top) primitive in the scene
- * at a particular window coordinate or undefined if nothing is at the location. Other properties may
- * potentially be set depending on the type of primitive and may be used to further identify the picked object.
+ * Returns a list of objects with a <code>primitive</code> property that contains the first (top) primitives
+ * in the scene at a particular window coordinate. Other properties may potentially be set depending on the
+ * type of primitive and may be used to further identify the picked object.
  * <p>
  * When a feature of a 3D Tiles tileset is picked, <code>pick</code> returns a {@link Cesium3DTileFeature} object.
  * </p>
@@ -272,9 +272,16 @@ function computePickingDrawingBufferRectangle(
  * @param {Cartesian2} windowPosition Window coordinates to perform picking on.
  * @param {number} [width=3] Width of the pick rectangle.
  * @param {number} [height=3] Height of the pick rectangle.
- * @returns {object | undefined} Object containing the picked primitive.
+ * @param {number} [limit=1] If supplied, stop iterating after collecting this many objects.
+ * @returns {object[]} List of objects containing the picked primitives.
  */
-Picking.prototype.pick = function (scene, windowPosition, width, height) {
+Picking.prototype.pick = function (
+  scene,
+  windowPosition,
+  width,
+  height,
+  limit = 1,
+) {
   //>>includeStart('debug', pragmas.debug);
   Check.defined("windowPosition", windowPosition);
   //>>includeEnd('debug');
@@ -328,9 +335,9 @@ Picking.prototype.pick = function (scene, windowPosition, width, height) {
   scene.updateAndExecuteCommands(passState, scratchColorZero);
   scene.resolveFramebuffers(passState);
 
-  const object = pickFramebuffer.end(drawingBufferRectangle);
+  const pickedObjects = pickFramebuffer.end(drawingBufferRectangle, limit);
   context.endFrame();
-  return object;
+  return pickedObjects;
 };
 
 /**
@@ -711,39 +718,41 @@ Picking.prototype.pickPosition = function (scene, windowPosition, result) {
   return result;
 };
 
-function drillPick(limit, pickCallback) {
-  // PERFORMANCE_IDEA: This function calls each primitive's update for each pass. Instead
-  // we could update the primitive once, and then just execute their commands for each pass,
-  // and cull commands for picked primitives.  e.g., base on the command's owner.
-  let i;
-  let attributes;
-  const result = [];
-  const pickedPrimitives = [];
-  const pickedAttributes = [];
-  const pickedFeatures = [];
-  if (!defined(limit)) {
-    limit = Number.MAX_VALUE;
-  }
-
-  let pickedResult = pickCallback();
-  while (defined(pickedResult)) {
+/**
+ * @param {object[]} pickedResults the results from the pickCallback
+ * @param {number} limit If supplied, stop drilling after collecting this many picks.
+ * @param {object[]} results
+ * @param {object[]} pickedPrimitives
+ * @param {object[]} pickedAttributes
+ * @param {object[]} pickedFeatures
+ * @returns {boolean} whether picking should end
+ */
+function addDrillPickedResults(
+  pickedResults,
+  limit,
+  results,
+  pickedPrimitives,
+  pickedAttributes,
+  pickedFeatures,
+) {
+  for (const pickedResult of pickedResults) {
     const object = pickedResult.object;
     const position = pickedResult.position;
     const exclude = pickedResult.exclude;
 
     if (defined(position) && !defined(object)) {
-      result.push(pickedResult);
-      break;
+      results.push(pickedResult);
+      return true;
     }
 
     if (!defined(object) || !defined(object.primitive)) {
-      break;
+      return true;
     }
 
     if (!exclude) {
-      result.push(pickedResult);
-      if (0 >= --limit) {
-        break;
+      results.push(pickedResult);
+      if (results.length >= limit) {
+        return true;
       }
     }
 
@@ -753,7 +762,7 @@ function drillPick(limit, pickCallback) {
     // If the picked object has a show attribute, use it.
     if (typeof primitive.getGeometryInstanceAttributes === "function") {
       if (defined(object.id)) {
-        attributes = primitive.getGeometryInstanceAttributes(object.id);
+        const attributes = primitive.getGeometryInstanceAttributes(object.id);
         if (defined(attributes) && defined(attributes.show)) {
           hasShowAttribute = true;
           attributes.show = ShowGeometryInstanceAttribute.toValue(
@@ -776,28 +785,61 @@ function drillPick(limit, pickCallback) {
       primitive.show = false;
       pickedPrimitives.push(primitive);
     }
+  }
+}
 
-    pickedResult = pickCallback();
+/**
+ * Drill pick by repeatedly calling a given `pickCallback`, each time stripping away the previously picked objects.
+ * @param {function(number): object[]} pickCallback Pick callback to execute each iteration
+ * @param {number} [limit=Number.MAX_VALUE] If supplied, stop drilling after collecting this many picks
+ * @returns {object[]} List of picked results
+ */
+function drillPick(pickCallback, limit) {
+  // PERFORMANCE_IDEA: This function calls each primitive's update for each pass. Instead
+  // we could update the primitive once, and then just execute their commands for each pass,
+  // and cull commands for picked primitives.  e.g., base on the command's owner.
+  const results = [];
+  const pickedPrimitives = [];
+  const pickedAttributes = [];
+  const pickedFeatures = [];
+  if (!defined(limit)) {
+    limit = Number.MAX_VALUE;
+  }
+
+  let pickedResults = pickCallback(limit);
+  while (defined(pickedResults) && pickedResults.length > 0) {
+    const complete = addDrillPickedResults(
+      pickedResults,
+      limit,
+      results,
+      pickedPrimitives,
+      pickedAttributes,
+      pickedFeatures,
+    );
+    if (complete) {
+      break;
+    }
+    pickedResults = pickCallback(limit - results.length);
   }
 
   // Unhide everything we hid while drill picking
-  for (i = 0; i < pickedPrimitives.length; ++i) {
+  for (let i = 0; i < pickedPrimitives.length; ++i) {
     pickedPrimitives[i].show = true;
   }
 
-  for (i = 0; i < pickedAttributes.length; ++i) {
-    attributes = pickedAttributes[i];
+  for (let i = 0; i < pickedAttributes.length; ++i) {
+    const attributes = pickedAttributes[i];
     attributes.show = ShowGeometryInstanceAttribute.toValue(
       true,
       attributes.show,
     );
   }
 
-  for (i = 0; i < pickedFeatures.length; ++i) {
+  for (let i = 0; i < pickedFeatures.length; ++i) {
     pickedFeatures[i].show = true;
   }
 
-  return result;
+  return results;
 }
 
 Picking.prototype.drillPick = function (
@@ -807,21 +849,22 @@ Picking.prototype.drillPick = function (
   width,
   height,
 ) {
-  const that = this;
-  const pickCallback = function () {
-    const object = that.pick(scene, windowPosition, width, height);
-    if (defined(object)) {
-      return {
-        object: object,
-        position: undefined,
-        exclude: false,
-      };
-    }
+  const pickCallback = (limit) => {
+    const pickedObjects = this.pick(
+      scene,
+      windowPosition,
+      width,
+      height,
+      limit,
+    );
+    return pickedObjects.map((object) => ({
+      object: object,
+      position: undefined,
+      exclude: false,
+    }));
   };
-  const objects = drillPick(limit, pickCallback);
-  return objects.map(function (element) {
-    return element.object;
-  });
+  const objects = drillPick(pickCallback, limit);
+  return objects.map((element) => element.object);
 };
 
 const scratchRight = new Cartesian3();
@@ -928,7 +971,7 @@ function getTilesets(primitives, objectsToExclude, tilesets) {
  * @param {Picking} picking
  * @param {Scene} scene
  * @param {Ray} ray
- * @param {Object[] | undefined} objectsToExclude
+ * @param {object[] | undefined} objectsToExclude
  * @param {number | undefined} width
  * @param {Function} callback
  * @returns {Promise<Cartesian3 | undefined>}
@@ -1016,7 +1059,8 @@ function getRayIntersection(
   scene.resolveFramebuffers(passState);
 
   let position;
-  const object = view.pickFramebuffer.end(drawingBufferRectangle);
+  // Picking one object, result is either [object] or []
+  const object = view.pickFramebuffer.end(drawingBufferRectangle, 1)[0];
 
   if (scene.context.depthTexture) {
     const { frustumCommandsList } = view;
@@ -1054,7 +1098,7 @@ function getRayIntersection(
   }
 }
 
-function getRayIntersections(
+function drillPickFromRay(
   picking,
   scene,
   ray,
@@ -1065,7 +1109,7 @@ function getRayIntersections(
   mostDetailed,
 ) {
   const pickCallback = function () {
-    return getRayIntersection(
+    const pickResult = getRayIntersection(
       picking,
       scene,
       ray,
@@ -1074,8 +1118,9 @@ function getRayIntersections(
       requirePosition,
       mostDetailed,
     );
+    return pickResult ? [pickResult] : undefined;
   };
-  return drillPick(limit, pickCallback);
+  return drillPick(pickCallback, limit);
 }
 
 function pickFromRay(
@@ -1087,7 +1132,8 @@ function pickFromRay(
   requirePosition,
   mostDetailed,
 ) {
-  const results = getRayIntersections(
+  // Use drillPickFromRay rather than getRayIntersection directly to select the first non-excluded object
+  const results = drillPickFromRay(
     picking,
     scene,
     ray,
@@ -1102,28 +1148,6 @@ function pickFromRay(
   }
 }
 
-function drillPickFromRay(
-  picking,
-  scene,
-  ray,
-  limit,
-  objectsToExclude,
-  width,
-  requirePosition,
-  mostDetailed,
-) {
-  return getRayIntersections(
-    picking,
-    scene,
-    ray,
-    limit,
-    objectsToExclude,
-    width,
-    requirePosition,
-    mostDetailed,
-  );
-}
-
 function deferPromiseUntilPostRender(scene, promise) {
   // Resolve promise after scene's postRender in case entities are created when the promise resolves.
   // Entities can't be created between viewer._onTick and viewer._postRender.
@@ -1365,7 +1389,7 @@ function sampleHeightMostDetailed(
  * @param {Picking} picking
  * @param {Scene} scene
  * @param {Cartesian3} cartesian
- * @param {Object[]} [objectsToExclude]
+ * @param {object[]} [objectsToExclude]
  * @param {number} [width]
  * @param {Cartesian3} [result]
  * @returns {Promise<Cartesian3 | undefined>}
@@ -1519,7 +1543,7 @@ Picking.prototype.sampleHeightMostDetailed = function (
  * @private
  * @param {Scene} scene
  * @param {Cartesian3[]} cartesians
- * @param {Object[]} [objectsToExclude]
+ * @param {object[]} [objectsToExclude]
  * @param {number} [width]
  * @returns {Promise<Array<Cartesian3 | undefined>>}
  */

package/Source/Scene/QuadtreePrimitive.js

@@ -90,7 +90,6 @@ function QuadtreePrimitive(options) {
   this._removeHeightCallbacks = [];
 
   this._tileToUpdateHeights = [];
-  this._lastTileIndex = 0;
   this._updateHeightsTimeSlice = 2.0;
 
   // If a culled tile contains _cameraPositionCartographic or _cameraReferenceFrameOriginCartographic, it will be marked
@@ -217,10 +216,8 @@ function invalidateAllTiles(primitive) {
     for (let i = 0; i < levelZeroTiles.length; ++i) {
       const tile = levelZeroTiles[i];
       const customData = tile.customData;
-      const customDataLength = customData.length;
 
-      for (let j = 0; j < customDataLength; ++j) {
-        const data = customData[j];
+      for (const data of customData) {
         data.level = 0;
         primitive._addHeightCallbacks.push(data);
       }
@@ -513,7 +510,6 @@ function selectTilesForRendering(primitive, frameState) {
   tilesToRender.length = 0;
 
   // We can't render anything before the level zero tiles exist.
-  let i;
   const tileProvider = primitive._tileProvider;
   if (!defined(primitive._levelZeroTiles)) {
     const tilingScheme = tileProvider.tilingScheme;
@@ -524,7 +520,7 @@ function selectTilesForRendering(primitive, frameState) {
       const numberOfRootTiles = primitive._levelZeroTiles.length;
       if (rootTraversalDetails.length < numberOfRootTiles) {
         rootTraversalDetails = new Array(numberOfRootTiles);
-        for (i = 0; i < numberOfRootTiles; ++i) {
+        for (let i = 0; i < numberOfRootTiles; ++i) {
           if (rootTraversalDetails[i] === undefined) {
             rootTraversalDetails[i] = new TraversalDetails();
           }
@@ -537,7 +533,6 @@ function selectTilesForRendering(primitive, frameState) {
 
   primitive._occluders.ellipsoid.cameraPosition = frameState.camera.positionWC;
 
-  let tile;
   const levelZeroTiles = primitive._levelZeroTiles;
   const occluders =
     levelZeroTiles.length > 1 ? primitive._occluders : undefined;
@@ -550,18 +545,28 @@ function selectTilesForRendering(primitive, frameState) {
 
   const customDataAdded = primitive._addHeightCallbacks;
   const customDataRemoved = primitive._removeHeightCallbacks;
-  const frameNumber = frameState.frameNumber;
 
-  let len;
-  if (customDataAdded.length > 0 || customDataRemoved.length > 0) {
-    for (i = 0, len = levelZeroTiles.length; i < len; ++i) {
-      tile = levelZeroTiles[i];
-      tile._updateCustomData(frameNumber, customDataAdded, customDataRemoved);
+  customDataAdded.forEach((data) => {
+    const tile = levelZeroTiles.find((tile) =>
+      Rectangle.contains(tile.rectangle, data.positionCartographic),
+    );
+    if (tile) {
+      tile._addedCustomData.push(data);
     }
+  });
 
-    customDataAdded.length = 0;
-    customDataRemoved.length = 0;
-  }
+  customDataRemoved.forEach((data) => {
+    const tile = levelZeroTiles.find((tile) =>
+      Rectangle.contains(tile.rectangle, data.positionCartographic),
+    );
+    if (tile) {
+      tile._removedCustomData.push(data);
+    }
+  });
+
+  levelZeroTiles.forEach((tile) => tile.updateCustomData());
+  customDataAdded.length = 0;
+  customDataRemoved.length = 0;
 
   const camera = frameState.camera;
 
@@ -577,8 +582,8 @@ function selectTilesForRendering(primitive, frameState) {
     );
 
   // Traverse in depth-first, near-to-far order.
-  for (i = 0, len = levelZeroTiles.length; i < len; ++i) {
-    tile = levelZeroTiles[i];
+  for (let i = 0; i < levelZeroTiles.length; ++i) {
+    const tile = levelZeroTiles[i];
     primitive._tileReplacementQueue.markTileRendered(tile);
     if (!tile.renderable) {
       queueTileLoad(primitive, primitive._tileLoadQueueHigh, tile, frameState);
@@ -596,7 +601,7 @@ function selectTilesForRendering(primitive, frameState) {
     }
   }
 
-  primitive._lastSelectionFrameNumber = frameNumber;
+  primitive._lastSelectionFrameNumber = frameState.frameNumber;
 }
 
 function queueTileLoad(primitive, queue, tile, frameState) {
@@ -716,7 +721,7 @@ function visitTile(
   ++debug.tilesVisited;
 
   primitive._tileReplacementQueue.markTileRendered(tile);
-  tile._updateCustomData(frameState.frameNumber);
+  tile.updateCustomData();
 
   if (tile.level > debug.maxDepthVisited) {
     debug.maxDepthVisited = tile.level;
@@ -1417,15 +1422,18 @@ function updateHeights(primitive, frameState) {
       // Ensure stale position cache is cleared
       tile.clearPositionCache();
       tilesToUpdateHeights.shift();
-      primitive._lastTileIndex = 0;
       continue;
     }
     const customData = tile.customData;
-    const customDataLength = customData.length;
+    if (!defined(tile._customDataIterator)) {
+      tile._customDataIterator = customData.values();
+    }
+    const customDataIterator = tile._customDataIterator;
 
     let timeSliceMax = false;
-    for (i = primitive._lastTileIndex; i < customDataLength; ++i) {
-      const data = customData[i];
+    let nextData;
+    while (!(nextData = customDataIterator.next()).done) {
+      const data = nextData.value;
 
       // No need to run this code when the tile is upsampled, because the height will be the same as its parent.
       const terrainData = tile.data.terrainData;
@@ -1543,10 +1551,10 @@ function updateHeights(primitive, frameState) {
     }
 
     if (timeSliceMax) {
-      primitive._lastTileIndex = i;
+      tile._customDataIterator = customDataIterator;
       break;
     } else {
-      primitive._lastTileIndex = 0;
+      tile._customDataIterator = undefined;
       tilesToUpdateHeights.shift();
     }
   }

package/Source/Scene/QuadtreeTile.js

@@ -1,6 +1,7 @@
 import defined from "../Core/defined.js";
 import DeveloperError from "../Core/DeveloperError.js";
 import Rectangle from "../Core/Rectangle.js";
+import Cartographic from "../Core/Cartographic.js";
 import QuadtreeTileLoadState from "./QuadtreeTileLoadState.js";
 import TileSelectionResult from "./TileSelectionResult.js";
 
@@ -107,8 +108,10 @@ function QuadtreeTile(options) {
   this._distance = 0.0;
   this._loadPriority = 0.0;
 
-  this._customData = [];
-  this._frameUpdated = undefined;
+  this._customData = new Set();
+  this._customDataIterator = undefined;
+  this._addedCustomData = [];
+  this._removedCustomData = [];
   this._lastSelectionResult = TileSelectionResult.NONE;
   this._lastSelectionResultFrame = undefined;
   this._loadedCallbacks = {};
@@ -265,7 +268,7 @@ QuadtreeTile.prototype._getCacheKey = function (
  * @param {number} maximumScreenSpaceError The maximum screen-space error, in pixels, that is allowed.
  *        A higher maximum error will render fewer tiles and improve performance, while a lower
  *        value will improve visual quality.
- * @returns {Object|undefined} The cached position data or undefined if not found.
+ * @returns {object|undefined} The cached position data or undefined if not found.
  */
 QuadtreeTile.prototype.getPositionCacheEntry = function (
   cartographic,
@@ -285,7 +288,7 @@ QuadtreeTile.prototype.getPositionCacheEntry = function (
  * @param {number} maximumScreenSpaceError The maximum screen-space error, in pixels, that is allowed.
  *        A higher maximum error will render fewer tiles and improve performance, while a lower
  *        value will improve visual quality.
- * @param {Object} value - The object to be cached.
+ * @param {object} value - The object to be cached.
  */
 QuadtreeTile.prototype.setPositionCacheEntry = function (
   cartographic,
@@ -311,52 +314,69 @@ QuadtreeTile.prototype.clearPositionCache = function () {
   }
 };
 
-QuadtreeTile.prototype._updateCustomData = function (
-  frameNumber,
-  added,
-  removed,
-) {
-  let customData = this.customData;
-
-  let i;
-  let data;
-  let rectangle;
-
-  if (defined(added) && defined(removed)) {
-    customData = customData.filter(function (value) {
-      return removed.indexOf(value) === -1;
-    });
-    this._customData = customData;
-
-    rectangle = this._rectangle;
-    for (i = 0; i < added.length; ++i) {
-      data = added[i];
-      if (Rectangle.contains(rectangle, data.positionCartographic)) {
-        customData.push(data);
-      }
-    }
+QuadtreeTile.prototype.updateCustomData = function () {
+  const added = this._addedCustomData;
+  const removed = this._removedCustomData;
+  if (added.length === 0 && removed.length === 0) {
+    return;
+  }
 
-    this._frameUpdated = frameNumber;
-  } else {
-    // interior or leaf tile, update from parent
-    const parent = this._parent;
-    if (defined(parent) && this._frameUpdated !== parent._frameUpdated) {
-      customData.length = 0;
-
-      rectangle = this._rectangle;
-      const parentCustomData = parent.customData;
-      for (i = 0; i < parentCustomData.length; ++i) {
-        data = parentCustomData[i];
-        if (Rectangle.contains(rectangle, data.positionCartographic)) {
-          customData.push(data);
-        }
-      }
+  const customData = this.customData;
+  for (let i = 0; i < added.length; ++i) {
+    const data = added[i];
+    customData.add(data);
+
+    const child = childTileAtPosition(this, data.positionCartographic);
+    child._addedCustomData.push(data);
+  }
+  this._addedCustomData.length = 0;
 
-      this._frameUpdated = parent._frameUpdated;
+  for (let i = 0; i < removed.length; ++i) {
+    const data = removed[i];
+    if (customData.has(data)) {
+      customData.delete(data);
     }
+
+    const child = childTileAtPosition(this, data.positionCartographic);
+    child._removedCustomData.push(data);
   }
+  this._removedCustomData.length = 0;
 };
 
+const splitPointScratch = new Cartographic();
+
+/**
+ * Determines which child tile that contains the specified position. Assumes the position is within
+ * the bounds of the parent tile.
+ * @private
+ * @param {QuadtreeTile} tile - The parent tile.
+ * @param {Cartographic} positionCartographic - The cartographic position.
+ * @returns {QuadtreeTile} The child tile that contains the position.
+ */
+function childTileAtPosition(tile, positionCartographic) {
+  // Can't assume that a given tiling scheme divides a parent into four tiles at its rectangle's center.
+  // But we can safely take any child tile's rectangle and take its center-facing corner as the parent's split point.
+  const nwChildRectangle = tile.northwestChild.rectangle;
+  const tileSplitPoint = Rectangle.southeast(
+    nwChildRectangle,
+    splitPointScratch,
+  );
+
+  const x = positionCartographic.longitude >= tileSplitPoint.longitude ? 1 : 0;
+  const y = positionCartographic.latitude < tileSplitPoint.latitude ? 1 : 0;
+
+  switch (y * 2 + x) {
+    case 0:
+      return tile.northwestChild;
+    case 1:
+      return tile.northeastChild;
+    case 2:
+      return tile.southwestChild;
+    default:
+      return tile.southeastChild;
+  }
+}
+
 Object.defineProperties(QuadtreeTile.prototype, {
   /**
    * Gets the tiling scheme used to tile the surface.
@@ -522,9 +542,9 @@ Object.defineProperties(QuadtreeTile.prototype, {
   },
 
   /**
-   * An array of objects associated with this tile.
+   * A set of objects associated with this tile.
    * @memberof QuadtreeTile.prototype
-   * @type {Array}
+   * @type {Set}
    */
   customData: {
     get: function () {

package/Source/Scene/ResourceLoaderState.js

@@ -31,7 +31,7 @@ const ResourceLoaderState = {
   /**
    * The resource is processing. GPU resources are allocated in this state as needed.
    *
-   * @type {Number}
+   * @type {number}
    * @constant
    * @private
    */