@cesium/engine 24.0.0 → 26.0.0

package/Source/Scene/BufferPrimitiveCollection.js

@@ -9,15 +9,26 @@ 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 AttributeCompression from "../Core/AttributeCompression.js";
+import SceneMode from "./SceneMode.js";
+import AttributeType from "./AttributeType.js";
+import oneTimeWarning from "../Core/oneTimeWarning.js";
+import BlendOption from "../Scene/BlendOption.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 +51,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.",
@@ -79,8 +77,16 @@ class BufferPrimitiveCollection {
    * @param {number} [options.vertexCountMax=BufferPrimitiveCollection.DEFAULT_CAPACITY]
    * @param {boolean} [options.show=true]
    * @param {ComponentDatatype} [options.positionDatatype=ComponentDatatype.DOUBLE]
+   * @param {boolean} [options.positionNormalized=false] When <code>true</code>, integer position values are treated as normalized,
+   *   where the full integer range maps to [-1, 1] (signed) or [0, 1] (unsigned). Only relevant for integer position datatypes
+   *   (BYTE, UNSIGNED_BYTE, SHORT, UNSIGNED_SHORT).
    * @param {boolean} [options.allowPicking=false] When <code>true</code>, primitives are pickable with {@link Scene#pick}. When <code>false</code>, memory and initialization cost are lower.
+   * @param {BoundingSphere} [options.boundingVolume] Bounding volume, in world space, for the collection. When
+   *    unspecified, a bounding volume is computed automatically and updated when primitive positions change. When
+   *    specified, users are responsible for updating bounding volume as needed. Pre-computing the bounding volume
+   *    manually, and updating it only as needed, will improve performance for larger dynamic collections.
    * @param {boolean} [options.debugShowBoundingVolume=false]
+   * @param {BlendOption} [options.blendOption=BlendOption.TRANSLUCENT]
    */
   constructor(options = Frozen.EMPTY_OBJECT) {
     /**
@@ -90,26 +96,39 @@ class BufferPrimitiveCollection {
      */
     this.show = options.show ?? true;
 
+    /**
+     * Collection blend option; must be OPAQUE or TRANSLUCENT.
+     * @type {BlendOption}
+     * @readonly
+     * @ignore
+     */
+    this._blendOption = options.blendOption ?? BlendOption.TRANSLUCENT;
+
     /**
      * 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 = BoundingSphere.clone(
+      options.boundingVolume ?? new BoundingSphere(),
+      new BoundingSphere(),
+    );
 
     /**
-     * World bounding volume for all primitives in the collection, including both
-     * shown and hidden primitives.
-     * @type {BoundingSphere}
+     * @type {boolean}
+     * @readonly
+     * @protected
      */
-    this.boundingVolumeWC = new BoundingSphere();
+    this._boundingVolumeAutoUpdate = !defined(options.boundingVolume);
 
     /**
      * When <code>true</code>, primitives are pickable with {@link Scene#pick}.
@@ -121,6 +140,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>
@@ -173,6 +206,21 @@ class BufferPrimitiveCollection {
      */
     this._positionView = null;
 
+    /**
+     * @type {ComponentDatatype}
+     * @ignore
+     */
+    this._positionDatatype =
+      options.positionDatatype ?? ComponentDatatype.DOUBLE;
+
+    /**
+     * When <code>true</code>, integer position values represent normalized floats
+     * in [-1, 1] (signed) or [0, 1] (unsigned). Only applicable to integer datatypes.
+     * @type {boolean}
+     * @ignore
+     */
+    this._positionNormalized = options.positionNormalized ?? false;
+
     /**
      * @type {DataView<ArrayBuffer>}
      * @ignore
@@ -202,10 +250,7 @@ class BufferPrimitiveCollection {
     this._dirtyBoundingVolume = false;
 
     this._allocatePrimitiveBuffer();
-    this._allocatePositionBuffer(
-      // @ts-expect-error Requires https://github.com/CesiumGS/cesium/pull/13203.
-      options.positionDatatype ?? ComponentDatatype.DOUBLE,
-    );
+    this._allocatePositionBuffer();
     this._allocateMaterialBuffer();
   }
 
@@ -258,14 +303,13 @@ class BufferPrimitiveCollection {
   }
 
   /**
-   * @param {ComponentDatatype} datatype
    * @private
    * @ignore
    */
-  _allocatePositionBuffer(datatype) {
-    // @ts-expect-error Requires https://github.com/CesiumGS/cesium/pull/13203.
+  _allocatePositionBuffer() {
+    // @ts-expect-error https://github.com/CesiumGS/cesium/issues/13420
     this._positionView = ComponentDatatype.createTypedArray(
-      datatype,
+      this._positionDatatype,
       this._positionCountMax * 3,
     );
   }
@@ -292,6 +336,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;
@@ -454,16 +506,19 @@ class BufferPrimitiveCollection {
    * @ignore
    */
   _updateBoundingVolume() {
-    const TypedArray = /** @type {TypedArrayConstructor} */ (
-      this._positionView.constructor
-    );
-
     // Exclude unused space in the position buffer.
-    const vertices = new TypedArray(
-      /** @type {ArrayBuffer} */ (this._positionView.buffer),
-      this._positionView.byteOffset,
-      this._positionCount * 3,
-    );
+    let vertices = this._positionView.subarray(0, this._positionCount * 3);
+
+    if (this._positionNormalized) {
+      vertices = AttributeCompression.dequantize(
+        /** @type {Int8Array|Uint8Array|Int16Array|Uint16Array|Int32Array|Uint32Array} */ (
+          vertices
+        ),
+        this._positionDatatype,
+        AttributeType.VEC3,
+        this._positionCount,
+      );
+    }
 
     BoundingSphere.fromVertices(
       vertices,
@@ -474,11 +529,51 @@ class BufferPrimitiveCollection {
     BoundingSphere.transform(
       this.boundingVolume,
       this.modelMatrix,
-      this.boundingVolumeWC,
+      this.boundingVolume,
     );
     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 +627,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;
   }
 
@@ -560,11 +661,14 @@ class BufferPrimitiveCollection {
   }
 
   /**
-   * Marks collection bounding volume as 'dirty', to be updated on next render.
+   * Marks collection bounding volume as 'dirty', to be updated on next render,
+   * if automatic bounding volume updates are enabled.
    * @ignore
    */
   _makeDirtyBoundingVolume() {
-    this._dirtyBoundingVolume = true;
+    if (this._boundingVolumeAutoUpdate) {
+      this._dirtyBoundingVolume = true;
+    }
   }
 
   /////////////////////////////////////////////////////////////////////////////
@@ -572,9 +676,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 +754,46 @@ class BufferPrimitiveCollection {
     return this._positionCountMax;
   }
 
+  /**
+   * Transforms geometry from model to world coordinates.
+   * @type {Matrix4}
+   * @default Matrix4.IDENTITY
+   * @readonly
+   */
+  get modelMatrix() {
+    return this._modelMatrix;
+  }
+
+  /**
+   * World-space bounding volume for all primitives in the collection, including both
+   * shown and hidden primitives.
+   * @type {BoundingSphere}
+   * @readonly
+   */
+  get boundingVolume() {
+    return this._boundingVolume;
+  }
+
+  /**
+   * The component datatype used to store position values.
+   * @type {ComponentDatatype}
+   * @readonly
+   */
+  get positionDatatype() {
+    return this._positionDatatype;
+  }
+
+  /**
+   * When <code>true</code>, integer position values are treated as normalized
+   * values, where the full integer range maps to [-1, 1] (signed) or [0, 1]
+   * (unsigned).
+   * @type {boolean}
+   * @readonly
+   */
+  get positionNormalized() {
+    return this._positionNormalized;
+  }
+
   /////////////////////////////////////////////////////////////////////////////
   // UTILS
 
@@ -699,4 +853,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/CameraEventAggregator.js

@@ -8,12 +8,29 @@ import ScreenSpaceEventHandler from "../Core/ScreenSpaceEventHandler.js";
 import ScreenSpaceEventType from "../Core/ScreenSpaceEventType.js";
 import CameraEventType from "./CameraEventType.js";
 
-function getKey(type, modifier) {
-  let key = `${type}`;
-  if (defined(modifier)) {
-    key += `+${modifier}`;
+const keyboardModifierCombinations = [
+  KeyboardEventModifier.SHIFT,
+  KeyboardEventModifier.CTRL,
+  KeyboardEventModifier.ALT,
+  [KeyboardEventModifier.SHIFT, KeyboardEventModifier.CTRL],
+  [KeyboardEventModifier.SHIFT, KeyboardEventModifier.ALT],
+  [KeyboardEventModifier.CTRL, KeyboardEventModifier.ALT],
+  [
+    KeyboardEventModifier.SHIFT,
+    KeyboardEventModifier.CTRL,
+    KeyboardEventModifier.ALT,
+  ],
+];
+
+function getKey(type, modifiers) {
+  if (!defined(modifiers)) {
+    return `${type}`;
   }
-  return key;
+
+  const modifierList = Array.isArray(modifiers)
+    ? modifiers.toSorted()
+    : [modifiers];
+  return `${type}+${modifierList.join("+")}`;
 }
 
 function clonePinchMovement(pinchMovement, result) {
@@ -219,7 +236,7 @@ function listenMouseButtonDownUp(aggregator, modifier, type) {
   aggregator._eventHandler.setInputAction(
     function () {
       cancelMouseDownAction(getKey(type, undefined), aggregator);
-      for (const modifier of Object.values(KeyboardEventModifier)) {
+      for (const modifier of keyboardModifierCombinations) {
         const cancelKey = getKey(type, modifier);
         cancelMouseDownAction(cancelKey, aggregator);
       }
@@ -382,18 +399,13 @@ function CameraEventAggregator(canvas) {
   listenMouseButtonDownUp(this, undefined, CameraEventType.MIDDLE_DRAG);
   listenMouseMove(this, undefined);
 
-  for (const modifierName in KeyboardEventModifier) {
-    if (KeyboardEventModifier.hasOwnProperty(modifierName)) {
-      const modifier = KeyboardEventModifier[modifierName];
-      if (defined(modifier)) {
-        listenToWheel(this, modifier);
-        listenToPinch(this, modifier, canvas);
-        listenMouseButtonDownUp(this, modifier, CameraEventType.LEFT_DRAG);
-        listenMouseButtonDownUp(this, modifier, CameraEventType.RIGHT_DRAG);
-        listenMouseButtonDownUp(this, modifier, CameraEventType.MIDDLE_DRAG);
-        listenMouseMove(this, modifier);
-      }
-    }
+  for (const modifiers of keyboardModifierCombinations) {
+    listenToWheel(this, modifiers);
+    listenToPinch(this, modifiers, canvas);
+    listenMouseButtonDownUp(this, modifiers, CameraEventType.LEFT_DRAG);
+    listenMouseButtonDownUp(this, modifiers, CameraEventType.RIGHT_DRAG);
+    listenMouseButtonDownUp(this, modifiers, CameraEventType.MIDDLE_DRAG);
+    listenMouseMove(this, modifiers);
   }
 }
 

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

@@ -1232,6 +1232,16 @@ async function processArrayBuffer(
       return;
     }
 
+    if (isEmptyTile(tile, error)) {
+      if (expired) {
+        tile.expireDate = undefined;
+      }
+      tile._content = new Empty3DTileContent(tileset, tile);
+      markTileAsEmptyContent(tile);
+      tile._contentState = Cesium3DTileContentState.PROCESSING;
+      return tile._content;
+    }
+
     tile._contentState = Cesium3DTileContentState.FAILED;
     throw error;
   }
@@ -1264,6 +1274,9 @@ async function processArrayBuffer(
     }
 
     tile._content = content;
+    if (content instanceof Empty3DTileContent) {
+      markTileAsEmptyContent(tile);
+    }
     tile._contentState = Cesium3DTileContentState.PROCESSING;
 
     return content;
@@ -1316,6 +1329,35 @@ function requestSingleContent(tile) {
   return processArrayBuffer(tile, tileset, request, expired, promise);
 }
 
+/**
+ * Determines whether a tile load error should be interpreted as "no content"
+ * (empty tile) rather than a true failure. A missing tile policy specifies
+ * HTTP Status Codes to be interpreted as "no content", allowing tiles to be
+ * statically hosted without generating and serving unnecessary content for
+ * empty tiles.
+ * @ignore
+ */
+function isEmptyTile(tile, error) {
+  const tileset = tile._tileset;
+  const policy = tileset?._runtimeContentCodec?.missingTilePolicy;
+  if (!defined(policy)) {
+    return false;
+  }
+
+  if (!defined(error.statusCode)) {
+    return false;
+  }
+  return policy.statusCodes.includes(error.statusCode);
+}
+
+function markTileAsEmptyContent(tile) {
+  // These flags are mutable instance state initialized in the constructor.
+  tile.hasEmptyContent = true;
+  tile.hasRenderableContent = false;
+}
+
+Cesium3DTile._isEmptyTile = isEmptyTile;
+
 /**
  * Given a downloaded content payload, construct a {@link Cesium3DTileContent}.
  * <p>
@@ -1328,10 +1370,21 @@ function requestSingleContent(tile) {
  * @private
  */
 async function makeContent(tile, arrayBuffer) {
+  const tileset = tile._tileset;
+  const codec = tileset?._runtimeContentCodec;
+  if (defined(codec) && typeof codec.createContent === "function") {
+    const content = await Promise.resolve(
+      codec.createContent(tileset, tile, tile._contentResource, arrayBuffer),
+    );
+    if (tile.isDestroyed()) {
+      return;
+    }
+    return content;
+  }
+
   const preprocessed = preprocess3DTileContent(arrayBuffer);
 
   // Vector and Geometry tile rendering do not support the skip LOD optimization.
-  const tileset = tile._tileset;
   tileset._disableSkipLevelOfDetail =
     tileset._disableSkipLevelOfDetail ||
     preprocessed.contentType === Cesium3DTileContentType.GEOMETRY ||

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;