@cesium/engine 24.0.0 → 25.0.0

package/Source/Renderer/MipmapHint.js

@@ -1,6 +1,7 @@
 import WebGLConstants from "../Core/WebGLConstants.js";
 
 /**
+ * @enum {number}
  * @private
  */
 const MipmapHint = {
@@ -16,4 +17,7 @@ const MipmapHint = {
     );
   },
 };
-export default Object.freeze(MipmapHint);
+
+Object.freeze(MipmapHint);
+
+export default MipmapHint;

package/Source/Renderer/Pass.js

@@ -1,6 +1,9 @@
+// @ts-check
+
 /**
  * The render pass for a command.
  *
+ * @enum {number}
  * @private
  */
 const Pass = {
@@ -26,4 +29,7 @@ const Pass = {
   OVERLAY: 12,
   NUMBER_OF_PASSES: 13,
 };
-export default Object.freeze(Pass);
+
+Object.freeze(Pass);
+
+export default Pass;

package/Source/Renderer/PickId.js

@@ -0,0 +1,44 @@
+// @ts-check
+
+/** @import Color from "../Core/Color.js"; */
+/** @import {Destroyable} from "../Core/globalTypes.js"; */
+
+/**
+ * Represents a pickable object with a unique integer ID and picking color.
+ *
+ * @implements {Destroyable}
+ * @ignore
+ */
+class PickId {
+  /**
+   * @param {Map<number, object>} pickObjects
+   * @param {number} key
+   * @param {Color} color
+   */
+  constructor(pickObjects, key, color) {
+    this._pickObjects = pickObjects;
+
+    /** @type {number} */
+    this.key = key;
+
+    /** @type {Color} */
+    this.color = color;
+  }
+
+  /** @type {object} */
+  get object() {
+    return this._pickObjects.get(this.key);
+  }
+
+  set object(value) {
+    this._pickObjects.set(this.key, value);
+  }
+
+  /** @returns {void} */
+  destroy() {
+    this._pickObjects.delete(this.key);
+    return undefined;
+  }
+}
+
+export default PickId;

package/Source/Renderer/PixelDatatype.js

@@ -118,4 +118,6 @@ PixelDatatype.getTypedArrayConstructor = function (pixelDatatype) {
   return Uint32Array;
 };
 
-export default Object.freeze(PixelDatatype);
+Object.freeze(PixelDatatype);
+
+export default PixelDatatype;

package/Source/Renderer/RenderbufferFormat.js

@@ -1,6 +1,7 @@
 import WebGLConstants from "../Core/WebGLConstants.js";
 
 /**
+ * @enum {number}
  * @private
  */
 const RenderbufferFormat = {
@@ -39,4 +40,7 @@ const RenderbufferFormat = {
     return RenderbufferFormat.RGBA8;
   },
 };
-export default Object.freeze(RenderbufferFormat);
+
+Object.freeze(RenderbufferFormat);
+
+export default RenderbufferFormat;

package/Source/Renderer/ShaderDestination.js

@@ -5,6 +5,7 @@ import DeveloperError from "../Core/DeveloperError.js";
  * A bit flag describing whether a variable should be added to the
  * vertex shader, the fragment shader, or both (or none).
  *
+ * @enum {number}
  * @private
  */
 const ShaderDestination = {
@@ -89,4 +90,6 @@ ShaderDestination.intersection = function (...destinations) {
   return result;
 };
 
-export default Object.freeze(ShaderDestination);
+Object.freeze(ShaderDestination);
+
+export default ShaderDestination;

package/Source/Renderer/TextureMagnificationFilter.js

@@ -38,4 +38,6 @@ TextureMagnificationFilter.validate = function (textureMagnificationFilter) {
   );
 };
 
-export default Object.freeze(TextureMagnificationFilter);
+Object.freeze(TextureMagnificationFilter);
+
+export default TextureMagnificationFilter;

package/Source/Renderer/TextureMinificationFilter.js

@@ -91,4 +91,6 @@ TextureMinificationFilter.validate = function (textureMinificationFilter) {
   );
 };
 
-export default Object.freeze(TextureMinificationFilter);
+Object.freeze(TextureMinificationFilter);
+
+export default TextureMinificationFilter;

package/Source/Renderer/TextureWrap.js

@@ -1,6 +1,7 @@
 import WebGLConstants from "../Core/WebGLConstants.js";
 
 /**
+ * @enum {number}
  * @private
  */
 const TextureWrap = {
@@ -16,4 +17,7 @@ const TextureWrap = {
     );
   },
 };
-export default Object.freeze(TextureWrap);
+
+Object.freeze(TextureWrap);
+
+export default TextureWrap;

package/Source/Scene/AlphaMode.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 /**
  * The alpha rendering mode of the material.
  *
@@ -30,4 +32,6 @@ const AlphaMode = {
   BLEND: "BLEND",
 };
 
-export default Object.freeze(AlphaMode);
+Object.freeze(AlphaMode);
+
+export default AlphaMode;

package/Source/Scene/ArcGisBaseMapType.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 /**
  * ArcGisBaseMapType enumerates the ArcGIS image tile layers that are supported by default.
  *
@@ -9,4 +11,7 @@ const ArcGisBaseMapType = {
   OCEANS: 2,
   HILLSHADE: 3,
 };
-export default Object.freeze(ArcGisBaseMapType);
+
+Object.freeze(ArcGisBaseMapType);
+
+export default ArcGisBaseMapType;

package/Source/Scene/ArcGisMapService.js

@@ -4,7 +4,7 @@ import Resource from "../Core/Resource.js";
 
 let defaultTokenCredit;
 const defaultAccessToken =
-  "AAPTaUFUfciXgT4YKNZew9lUqpQ..yIoArbcKGeWnsxrcf8Sk9LLcQN1dML2469i9e8v1mZyMILiwWzGR3sxU2vr8L749gvuB4ERujd1vMmNwfZTbCPPaJ1vtts4rXZ3DZEhW9L3GKH6KRRfqXy77cdjc7mg3iIVkWEg8yhReRsNIyw-nlzduhCipHDMwkkx-GmOxnsNYE-0CE2uEB9Mm8b6UppjohI1tn864yN1vLTJMP1vCRFD2b0uyE0vqzx-cE12TppkVQQ4Ry9apOVC3AT1_oO2ZY8gh";
+  "AAPTarorp_WgBbyDABMqDfNsSWg..ykf3buvvbFduVL73NrRrnqBR8lO4ndPrO94nF7-3rfUWF5n3sbUe2Xe0d4rhAGa-sOTDpE-AI5kom4O4ixK3QFkTnjaGpFtDOxyrPXZUj1vRmsZAaIMZlzC5TWfBDr-RYeD9NCRMq8JwaP2Fp9blpXTqYVCWpENJLiCJ3pUlQ7XSrnJYNlPwph4B3k1FAK_j3DTlLDd2xbHwcMRbVYq8iJqt7vGuWHw3otSkmltdnNAgMaVQ366Rf0YUAT1_Hbd2aXK9";
 /**
  * Default options for accessing the ArcGIS image tile service.
  *

package/Source/Scene/AttributeType.js

@@ -197,4 +197,6 @@ AttributeType.getGlslType = function (attributeType) {
   }
 };
 
-export default Object.freeze(AttributeType);
+Object.freeze(AttributeType);
+
+export default AttributeType;

package/Source/Scene/Axis.js

@@ -113,4 +113,6 @@ Axis.fromName = function (name) {
   return Axis[name];
 };
 
-export default Object.freeze(Axis);
+Object.freeze(Axis);
+
+export default Axis;

package/Source/Scene/BingMapsStyle.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 /**
  * The types of imagery provided by Bing Maps.
  *
@@ -90,4 +92,7 @@ const BingMapsStyle = {
    */
   COLLINS_BART: "CollinsBart",
 };
-export default Object.freeze(BingMapsStyle);
+
+Object.freeze(BingMapsStyle);
+
+export default BingMapsStyle;

package/Source/Scene/BlendEquation.js

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

package/Source/Scene/BlendFunction.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 import WebGLConstants from "../Core/WebGLConstants.js";
 
 /**
@@ -126,4 +128,7 @@ const BlendFunction = {
    */
   SOURCE_ALPHA_SATURATE: WebGLConstants.SRC_ALPHA_SATURATE,
 };
-export default Object.freeze(BlendFunction);
+
+Object.freeze(BlendFunction);
+
+export default BlendFunction;

package/Source/Scene/BlendOption.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 /**
  * Determines how opaque and translucent parts of billboards, points, and labels are blended with the scene.
  *
@@ -25,4 +27,7 @@ const BlendOption = {
    */
   OPAQUE_AND_TRANSLUCENT: 2,
 };
-export default Object.freeze(BlendOption);
+
+Object.freeze(BlendOption);
+
+export default BlendOption;

package/Source/Scene/BlendingState.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 import BlendEquation from "./BlendEquation.js";
 import BlendFunction from "./BlendFunction.js";
 
@@ -70,4 +72,7 @@ const BlendingState = {
     functionDestinationAlpha: BlendFunction.ONE,
   }),
 };
-export default Object.freeze(BlendingState);
+
+Object.freeze(BlendingState);
+
+export default BlendingState;

package/Source/Scene/BufferLoader.js

@@ -47,7 +47,6 @@ class BufferLoader extends ResourceLoader {
   /**
    * The cache key of the resource.
    *
-   * @memberof BufferLoader.prototype
    *
    * @type {string}
    * @readonly
@@ -60,7 +59,6 @@ class BufferLoader extends ResourceLoader {
   /**
    * The typed array containing the embedded buffer contents.
    *
-   * @memberof BufferLoader.prototype
    *
    * @type {Uint8Array}
    * @readonly

package/Source/Scene/BufferPointCollection.js

@@ -12,9 +12,11 @@ import BufferPointMaterial from "./BufferPointMaterial.js";
 
 /**
  * @typedef {object} BufferPointOptions
- * @property {Matrix4} [options.modelMatrix=Matrix4.IDENTITY] Transforms geometry from model to world coordinates.
+ * @property {Matrix4} [modelMatrix=Matrix4.IDENTITY] Transforms geometry from model to world coordinates.
  * @property {boolean} [show=true]
  * @property {BufferPointMaterial} [material=BufferPointMaterial.DEFAULT_MATERIAL]
+ * @property {number} [featureId]
+ * @property {object} [pickObject]
  * @property {Cartesian3} [position=Cartesian3.ZERO]
  * @experimental This feature is not final and is subject to change without Cesium's standard deprecation policy.
  */
@@ -56,6 +58,7 @@ class BufferPointCollection extends BufferPrimitiveCollection {
    * @param {number} [options.primitiveCountMax=BufferPrimitiveCollection.DEFAULT_CAPACITY]
    * @param {boolean} [options.show=true]
    * @param {boolean} [options.debugShowBoundingVolume=false]
+   * @param {boolean} [options.allowPicking=false]
    */
   constructor(options = Frozen.EMPTY_OBJECT) {
     super({ ...options, vertexCountMax: options.primitiveCountMax });

package/Source/Scene/BufferPolygonCollection.js

@@ -18,9 +18,11 @@ const { ERR_CAPACITY } = BufferPrimitiveCollection.Error;
 
 /**
  * @typedef {object} BufferPolygonOptions
- * @property {Matrix4} [options.modelMatrix=Matrix4.IDENTITY] Transforms geometry from model to world coordinates.
+ * @property {Matrix4} [modelMatrix=Matrix4.IDENTITY] Transforms geometry from model to world coordinates.
  * @property {boolean} [show=true]
  * @property {BufferPolygonMaterial} [material=BufferPolygonMaterial.DEFAULT_MATERIAL]
+ * @property {number} [featureId]
+ * @property {object} [pickObject]
  * @property {TypedArray} [positions]
  * @property {TypedArray} [holes]
  * @property {TypedArray} [triangles]

package/Source/Scene/BufferPolylineCollection.js

@@ -12,9 +12,11 @@ import BufferPolylineMaterial from "./BufferPolylineMaterial.js";
 
 /**
  * @typedef {object} BufferPolylineOptions
- * @property {Matrix4} [options.modelMatrix=Matrix4.IDENTITY] Transforms geometry from model to world coordinates.
+ * @property {Matrix4} [modelMatrix=Matrix4.IDENTITY] Transforms geometry from model to world coordinates.
  * @property {boolean} [show=true]
  * @property {BufferPolylineMaterial} [material=BufferPolylineMaterial.DEFAULT_MATERIAL]
+ * @property {number} [featureId]
+ * @property {object} [pickObject]
  * @property {TypedArray} [positions]
  * @experimental This feature is not final and is subject to change without Cesium's standard deprecation policy.
  */

package/Source/Scene/BufferPrimitiveCollection.js

@@ -9,15 +9,23 @@ import assert from "../Core/assert.js";
 import ComponentDatatype from "../Core/ComponentDatatype.js";
 import defined from "../Core/defined.js";
 import Check from "../Core/Check.js";
+import SceneMode from "./SceneMode.js";
+import oneTimeWarning from "../Core/oneTimeWarning.js";
 
 /** @import { Destroyable, TypedArray, TypedArrayConstructor } from "../Core/globalTypes.js"; */
+/** @import Context from "../Renderer/Context.js"; */
+/** @import FrameState from "./FrameState.js"; */
 /** @import BufferPrimitive from "./BufferPrimitive.js"; */
 /** @import BufferPrimitiveMaterial from "./BufferPrimitiveMaterial.js"; */
+/** @import PickId from "../Renderer/PickId.js"; */
 
 /**
  * @typedef {object} BufferPrimitiveOptions
+ * @property {Matrix4} [modelMatrix=Matrix4.IDENTITY] Transforms geometry from model to world coordinates.
  * @property {boolean} [show=true]
  * @property {BufferPrimitiveMaterial} [material]
+ * @property {number} [featureId]
+ * @property {object} [pickObject]
  * @experimental This feature is not final and is subject to change without Cesium's standard deprecation policy.
  */
 
@@ -40,19 +48,6 @@ import Check from "../Core/Check.js";
  * @see BufferPolygonCollection
  */
 class BufferPrimitiveCollection {
-  /**
-   * Default capacity of buffers on new collections. A quantity of elements:
-   * number of vertices in the vertex buffer, primitives in the primitive
-   * buffer, etc. This value is arbitrary, and collections cannot be resized,
-   * so specific per-buffer capacities should be provided in the collection
-   * constructor when available.
-   *
-   * @type {number}
-   * @readonly
-   * @static
-   */
-  static DEFAULT_CAPACITY = 1024;
-
   /** @ignore */
   static Error = {
     ERR_RESIZE: "BufferPrimitive range cannot be resized after initialization.",
@@ -91,25 +86,26 @@ class BufferPrimitiveCollection {
     this.show = options.show ?? true;
 
     /**
-     * Transforms geometry from model to world coordinates.
      * @type {Matrix4}
      * @default Matrix4.IDENTITY
+     * @readonly
+     * @protected
      */
-    this.modelMatrix = Matrix4.clone(options.modelMatrix ?? Matrix4.IDENTITY);
+    this._modelMatrix = Matrix4.clone(options.modelMatrix ?? Matrix4.IDENTITY);
 
     /**
-     * Local bounding volume for all primitives in the collection, including both
-     * shown and hidden primitives.
      * @type {BoundingSphere}
+     * @readonly
+     * @protected
      */
-    this.boundingVolume = new BoundingSphere();
+    this._boundingVolume = new BoundingSphere();
 
     /**
-     * World bounding volume for all primitives in the collection, including both
-     * shown and hidden primitives.
      * @type {BoundingSphere}
+     * @readonly
+     * @protected
      */
-    this.boundingVolumeWC = new BoundingSphere();
+    this._boundingVolumeWC = new BoundingSphere();
 
     /**
      * When <code>true</code>, primitives are pickable with {@link Scene#pick}.
@@ -121,6 +117,20 @@ class BufferPrimitiveCollection {
      */
     this._allowPicking = options.allowPicking ?? false;
 
+    /**
+     * @type {Map<Context, PickId[]>}
+     * @readonly
+     * @ignore
+     */
+    this._pickIds = new Map();
+
+    /**
+     * @type {object[]}
+     * @readonly
+     * @ignore
+     */
+    this._pickObjects = [];
+
     /**
      * This property is for debugging only; it is not for production use nor is it optimized.
      * <p>
@@ -203,7 +213,6 @@ class BufferPrimitiveCollection {
 
     this._allocatePrimitiveBuffer();
     this._allocatePositionBuffer(
-      // @ts-expect-error Requires https://github.com/CesiumGS/cesium/pull/13203.
       options.positionDatatype ?? ComponentDatatype.DOUBLE,
     );
     this._allocateMaterialBuffer();
@@ -292,6 +301,14 @@ class BufferPrimitiveCollection {
 
   /** Destroys collection and its GPU resources. */
   destroy() {
+    this._pickObjects.length = 0;
+
+    for (const contextPickIds of this._pickIds.values()) {
+      for (const pickId of contextPickIds) {
+        pickId.destroy();
+      }
+    }
+
     if (defined(this._renderContext)) {
       this._renderContext.destroy();
       this._renderContext = undefined;
@@ -479,6 +496,46 @@ class BufferPrimitiveCollection {
     this._dirtyBoundingVolume = false;
   }
 
+  /**
+   * Updates PickIds for the given context.
+   * @param {Context} context
+   * @protected
+   * @ignore
+   */
+  _updatePickIds(context) {
+    let pickIds = this._pickIds.get(context);
+    if (pickIds && pickIds.length === this._primitiveCount) {
+      return;
+    }
+
+    if (!pickIds) {
+      pickIds = [];
+      this._pickIds.set(context, pickIds);
+    }
+
+    const collection = this;
+    const PrimitiveClass = this._getPrimitiveClass();
+    const primitive = new PrimitiveClass();
+
+    // Fill in missing PickIDs for recently-added primitives.
+    for (let i = pickIds.length, il = this._primitiveCount; i < il; i++) {
+      this.get(i, primitive);
+
+      const pickObject = this._pickObjects[i] || {
+        collection: this,
+        index: i,
+        get primitive() {
+          // Cannot reuse primitives; scene.drillPick() appends to a list.
+          return collection.get(i, new PrimitiveClass());
+        },
+      };
+
+      const pickId = context.createPickId(pickObject);
+      primitive._pickId = pickId.key;
+      pickIds.push(pickId);
+    }
+  }
+
   /////////////////////////////////////////////////////////////////////////////
   // PRIMITIVE LIFECYCLE
 
@@ -532,13 +589,19 @@ class BufferPrimitiveCollection {
     //>>includeEnd('debug');
 
     const MaterialClass = this._getMaterialClass();
+    const index = this._primitiveCount++;
 
-    result = this.get(this._primitiveCount++, result);
-    result.featureId = this._primitiveCount - 1;
+    result = this.get(index, result);
+    result.featureId = options.featureId ?? index;
     result.show = options.show ?? true;
     result.setMaterial(options.material ?? MaterialClass.DEFAULT_MATERIAL);
     result._pickId = 0; // unset
     result._dirty = true;
+
+    if (defined(options.pickObject)) {
+      this._pickObjects[index] = options.pickObject;
+    }
+
     return result;
   }
 
@@ -572,9 +635,19 @@ class BufferPrimitiveCollection {
 
   /** @param {object} frameState */
   update(frameState) {
+    if (/** @type {FrameState} */ (frameState).mode !== SceneMode.SCENE3D) {
+      oneTimeWarning(
+        "bufferprim-scenemode",
+        "BufferPrimitiveCollection requires SceneMode.SCENE3D.",
+      );
+    }
+
     if (this._dirtyBoundingVolume) {
       this._updateBoundingVolume();
     }
+    if (this._allowPicking && this._dirtyCount > 0) {
+      this._updatePickIds(/** @type {FrameState} */ (frameState).context);
+    }
   }
 
   /////////////////////////////////////////////////////////////////////////////
@@ -640,6 +713,36 @@ class BufferPrimitiveCollection {
     return this._positionCountMax;
   }
 
+  /**
+   * Transforms geometry from model to world coordinates.
+   * @type {Matrix4}
+   * @default Matrix4.IDENTITY
+   * @readonly
+   */
+  get modelMatrix() {
+    return this._modelMatrix;
+  }
+
+  /**
+   * Local bounding volume for all primitives in the collection, including both
+   * shown and hidden primitives.
+   * @type {BoundingSphere}
+   * @readonly
+   */
+  get boundingVolume() {
+    return this._boundingVolume;
+  }
+
+  /**
+   * World bounding volume for all primitives in the collection, including both
+   * shown and hidden primitives.
+   * @type {BoundingSphere}
+   * @readonly
+   */
+  get boundingVolumeWC() {
+    return this._boundingVolumeWC;
+  }
+
   /////////////////////////////////////////////////////////////////////////////
   // UTILS
 
@@ -699,4 +802,17 @@ class BufferPrimitiveCollection {
   }
 }
 
+/**
+ * Default capacity of buffers on new collections. A quantity of elements:
+ * number of vertices in the vertex buffer, primitives in the primitive
+ * buffer, etc. This value is arbitrary, and collections cannot be resized,
+ * so specific per-buffer capacities should be provided in the collection
+ * constructor when available.
+ *
+ * @type {number}
+ * @static
+ * @constant
+ */
+BufferPrimitiveCollection.DEFAULT_CAPACITY = 1024;
+
 export default BufferPrimitiveCollection;

package/Source/Scene/CameraEventType.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 /**
  * Enumerates the available input for interacting with the camera.
  *
@@ -44,4 +46,7 @@ const CameraEventType = {
    */
   PINCH: 4,
 };
-export default Object.freeze(CameraEventType);
+
+Object.freeze(CameraEventType);
+
+export default CameraEventType;

package/Source/Scene/Cesium3DTileColorBlendMode.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 /**
  * Defines how per-feature colors set from the Cesium API or declarative styling blend with the source colors from
  * the original feature, e.g. glTF material or per-point color in the tile.
@@ -49,4 +51,7 @@ const Cesium3DTileColorBlendMode = {
    */
   MIX: 2,
 };
-export default Object.freeze(Cesium3DTileColorBlendMode);
+
+Object.freeze(Cesium3DTileColorBlendMode);
+
+export default Cesium3DTileColorBlendMode;

package/Source/Scene/Cesium3DTileContentState.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 /**
  * @private
  */
@@ -9,4 +11,7 @@ const Cesium3DTileContentState = {
   EXPIRED: 4, // Is expired and will be unloaded once new content is loaded.
   FAILED: 5, // Request failed.
 };
-export default Object.freeze(Cesium3DTileContentState);
+
+Object.freeze(Cesium3DTileContentState);
+
+export default Cesium3DTileContentState;

package/Source/Scene/Cesium3DTileContentType.js

@@ -176,4 +176,6 @@ Cesium3DTileContentType.isBinaryFormat = function (contentType) {
   }
 };
 
-export default Object.freeze(Cesium3DTileContentType);
+Object.freeze(Cesium3DTileContentType);
+
+export default Cesium3DTileContentType;