@cesium/engine 21.0.1 → 22.1.0

package/Source/Scene/Picking.js

@@ -8,6 +8,7 @@ import Color from "../Core/Color.js";
 import defined from "../Core/defined.js";
 import DeveloperError from "../Core/DeveloperError.js";
 import Matrix4 from "../Core/Matrix4.js";
+import oneTimeWarning from "../Core/oneTimeWarning.js";
 import OrthographicFrustum from "../Core/OrthographicFrustum.js";
 import OrthographicOffCenterFrustum from "../Core/OrthographicOffCenterFrustum.js";
 import PerspectiveFrustum from "../Core/PerspectiveFrustum.js";
@@ -262,23 +263,21 @@ 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.
- * <p>
- * When a feature of a 3D Tiles tileset is picked, <code>pick</code> returns a {@link Cesium3DTileFeature} object.
- * </p>
+ * Setup needed before picking.
+ *
  * @param {Scene} scene
  * @param {Cartesian2} windowPosition Window coordinates to perform picking on.
+ * @param {BoundingRectangle} drawingBufferRectangle The output drawing buffer recangle.
  * @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.
  */
-Picking.prototype.pick = function (scene, windowPosition, width, height) {
-  //>>includeStart('debug', pragmas.debug);
-  Check.defined("windowPosition", windowPosition);
-  //>>includeEnd('debug');
-
+function pickBegin(
+  scene,
+  windowPosition,
+  drawingBufferRectangle,
+  width,
+  height,
+) {
   const { context, frameState, defaultView } = scene;
   const { viewport, pickFramebuffer } = defaultView;
 
@@ -297,12 +296,12 @@ Picking.prototype.pick = function (scene, windowPosition, width, height) {
     windowPosition,
     scratchPosition,
   );
-  const drawingBufferRectangle = computePickingDrawingBufferRectangle(
+  computePickingDrawingBufferRectangle(
     context.drawingBufferHeight,
     drawingBufferPosition,
     width,
     height,
-    scratchRectangle,
+    drawingBufferRectangle,
   );
 
   scene.jobScheduler.disableThisFrame();
@@ -327,10 +326,100 @@ Picking.prototype.pick = function (scene, windowPosition, width, height) {
 
   scene.updateAndExecuteCommands(passState, scratchColorZero);
   scene.resolveFramebuffers(passState);
+}
 
-  const object = pickFramebuffer.end(drawingBufferRectangle);
+/**
+ * Teardown needed after picking.
+ *
+ * @param {Scene} scene
+ */
+function pickEnd(scene) {
+  const { context } = scene;
   context.endFrame();
-  return object;
+}
+
+/**
+ * Same operation as {@link Picking#pick}, but returns a Promise that resolves asynchronously without blocking the main render thread.
+ * Requires WebGL2 else using synchronous fallback.
+ *
+ * @see Picking#pick
+ *
+ * @param {Scene} scene
+ * @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.
+ * @param {number} [limit=1] If supplied, stop iterating after collecting this many objects.
+ * @returns {Promise<object[]>} List of objects containing the picked primitives.
+ *
+ * @exception {RuntimeError} Async Picking Request Timeout.
+ */
+Picking.prototype.pickAsync = async function (
+  scene,
+  windowPosition,
+  width,
+  height,
+  limit = 1,
+) {
+  //>>includeStart('debug', pragmas.debug);
+  Check.defined("windowPosition", windowPosition);
+  //>>includeEnd('debug');
+
+  const { context, frameState, defaultView } = scene;
+  const { pickFramebuffer } = defaultView;
+  const drawingBufferRectangle = scratchRectangle;
+  pickBegin(scene, windowPosition, drawingBufferRectangle, width, height);
+  let pickedObjects;
+  if (context.webgl2) {
+    pickedObjects = pickFramebuffer.endAsync(
+      drawingBufferRectangle,
+      frameState,
+      limit,
+    ); // Promise<Object[]>
+  } else {
+    pickedObjects = pickFramebuffer.end(drawingBufferRectangle, limit); // Object[]
+    pickedObjects = Promise.resolve(pickedObjects); // Promise<Object[]> Wrap as Promise
+    oneTimeWarning(
+      "picking-async-fallback",
+      "Fallback to synchronous picking because async operation requires WebGL2 context.",
+    );
+  }
+  pickEnd(scene);
+  return pickedObjects;
+};
+
+/**
+ * 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>
+ * @param {Scene} scene
+ * @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.
+ * @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,
+  limit = 1,
+) {
+  //>>includeStart('debug', pragmas.debug);
+  Check.defined("windowPosition", windowPosition);
+  //>>includeEnd('debug');
+
+  const { defaultView } = scene;
+  const { pickFramebuffer } = defaultView;
+  const drawingBufferRectangle = scratchRectangle;
+  pickBegin(scene, windowPosition, drawingBufferRectangle, width, height);
+  const pickedObjects = pickFramebuffer.end(drawingBufferRectangle, limit); // Object[]
+  pickEnd(scene);
+  return pickedObjects;
 };
 
 /**
@@ -711,39 +800,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 +844,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 +867,61 @@ function drillPick(limit, pickCallback) {
       primitive.show = false;
       pickedPrimitives.push(primitive);
     }
+  }
+}
+
+/**
+ * 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;
+  }
 
-    pickedResult = pickCallback();
+  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 +931,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 +1053,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 +1141,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 +1180,7 @@ function getRayIntersection(
   }
 }
 
-function getRayIntersections(
+function drillPickFromRay(
   picking,
   scene,
   ray,
@@ -1065,7 +1191,7 @@ function getRayIntersections(
   mostDetailed,
 ) {
   const pickCallback = function () {
-    return getRayIntersection(
+    const pickResult = getRayIntersection(
       picking,
       scene,
       ray,
@@ -1074,8 +1200,9 @@ function getRayIntersections(
       requirePosition,
       mostDetailed,
     );
+    return pickResult ? [pickResult] : undefined;
   };
-  return drillPick(limit, pickCallback);
+  return drillPick(pickCallback, limit);
 }
 
 function pickFromRay(
@@ -1087,7 +1214,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 +1230,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 +1471,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 +1625,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();
     }
   }