@hztxi/cesium-engine 25.0.6 → 26.2.1

package/Source/Scene/ArcGisMapServerImageryProvider.js

@@ -325,11 +325,6 @@ function ArcGisMapServerImageryProvider(options) {
   this._credit = options.credit;
   this._tileCredits = undefined;
 
-  let credit = options.credit;
-  if (typeof credit === "string") {
-    credit = new Credit(credit);
-  }
-
   /**
    * Gets or sets a value indicating whether feature picking is enabled.  If true, {@link ArcGisMapServerImageryProvider#pickFeatures} will
    * invoke the "identify" operation on the ArcGIS server and return the features included in the response.  If false,

package/Source/Scene/ArcGisMapService.js

@@ -4,7 +4,7 @@ import Resource from "../Core/Resource.js";
 
 let defaultTokenCredit;
 const defaultAccessToken =
-  "AAPTarorp_WgBbyDABMqDfNsSWg..ykf3buvvbFduVL73NrRrnqBR8lO4ndPrO94nF7-3rfUWF5n3sbUe2Xe0d4rhAGa-sOTDpE-AI5kom4O4ixK3QFkTnjaGpFtDOxyrPXZUj1vRmsZAaIMZlzC5TWfBDr-RYeD9NCRMq8JwaP2Fp9blpXTqYVCWpENJLiCJ3pUlQ7XSrnJYNlPwph4B3k1FAK_j3DTlLDd2xbHwcMRbVYq8iJqt7vGuWHw3otSkmltdnNAgMaVQ366Rf0YUAT1_Hbd2aXK9";
+  "AAPTa7BPWL4PoZRFPJ2CM2YRclg..ub1vMOBXctC7ozMMKNnmx3ZwVTsDJAXo2GLomQ2CZjuOc2HLr1-CryeuRo9ZsV65cuZ9xN1yFKeLTu7Cxld7B97aI28os_NnuC9nvWde_l4G1DTApSHmhrVoZfKgO0bqOrsDfvvSgO-cdkUEvBASNX_4Lb9tB5fEY7lbYaWdOOWBXyZylR9il0-biB248V6HdDT1kgkSwz9esfKialRTLgxJx8AFM9is--UXK0CLvZn6JUU44PZSFuMyAT1_rgxsirsZ";
 /**
  * Default options for accessing the ArcGIS image tile service.
  *

package/Source/Scene/Billboard.js

@@ -706,8 +706,9 @@ Object.defineProperties(Billboard.prototype, {
   },
 
   /**
-   * Gets or sets the aligned axis in world space. The aligned axis is the unit vector that the billboard up vector points towards.
+   * The aligned axis is the direction vector that the billboard up vector points towards.
    * The default is the zero vector, which means the billboard is aligned to the screen up vector.
+   * Note that only the zero vector (0,0,0) resets the alignment to screen up.
    * @memberof Billboard.prototype
    * @type {Cartesian3}
    * @example

package/Source/Scene/BillboardCollection.js

@@ -102,6 +102,7 @@ const attributeLocations = {
  * @param {boolean} [options.show=true] Determines if the billboards in the collection will be shown.
  * @param {number} [options.coarseDepthTestDistance] The distance from the camera, beyond which, billboards are depth-tested against an approximation of the globe ellipsoid rather than against the full globe depth buffer. If unspecified, the default value is determined relative to the value of {@link Ellipsoid.default}.
  * @param {number} [options.threePointDepthTestDistance] The distance from the camera, within which, billboards with a {@link Billboard#heightReference} value of {@link HeightReference.CLAMP_TO_GROUND} or {@link HeightReference.CLAMP_TO_TERRAIN} are depth tested against three key points. This ensures that if any key point of the billboard is visible, the whole billboard will be visible. If unspecified, the default value is determined relative to the value of {@link Ellipsoid.default}.
+ * @param {boolean} [options.alwaysThreePointDepthTest=false] Enables the three-point depth test even when {@link Globe#depthTestAgainstTerrain} is false.
  * @performance For best performance, prefer a few collections, each with many billboards, to
  * many collections with only a few billboards each.  Organize collections so that billboards
  * with the same update frequency are in the same collection, i.e., billboards that do not
@@ -305,6 +306,7 @@ function BillboardCollection(options) {
   this._threePointDepthTestDistance =
     options.threePointDepthTestDistance ??
     Ellipsoid.default.minimumRadius / 1000.0;
+  this._alwaysThreePointDepthTest = options.alwaysThreePointDepthTest ?? false;
 
   this._uniforms = {
     u_atlas: () => {
@@ -1033,8 +1035,9 @@ function writeCompressedAttrib1(
   billboard,
 ) {
   const writer = vafWriters[attributeLocations.compressedAttribute1];
-  const alignedAxis = billboard.alignedAxis;
+  let alignedAxis = billboard.alignedAxis;
   if (!Cartesian3.equals(alignedAxis, Cartesian3.ZERO)) {
+    alignedAxis = Cartesian3.normalize(alignedAxis, new Cartesian3());
     billboardCollection._shaderAlignedAxis = true;
   }
 
@@ -1096,12 +1099,15 @@ function writeCompressedAttrib2(
     ? billboard.getPickId(frameState.context).color
     : Color.WHITE;
   const sizeInMeters = billboard.sizeInMeters ? 1.0 : 0.0;
+  const rawAxis = billboard.alignedAxis;
+  const normalizedAxis = !Cartesian3.equals(rawAxis, Cartesian3.ZERO)
+    ? Cartesian3.normalize(rawAxis, new Cartesian3())
+    : rawAxis;
   const validAlignedAxis =
-    Math.abs(Cartesian3.magnitudeSquared(billboard.alignedAxis) - 1.0) <
+    Math.abs(Cartesian3.magnitudeSquared(normalizedAxis) - 1.0) <
     CesiumMath.EPSILON6
       ? 1.0
       : 0.0;
-
   billboardCollection._allSizedInMeters =
     billboardCollection._allSizedInMeters && sizeInMeters === 1.0;
 
@@ -1292,9 +1298,13 @@ function writeTextureCoordinateBoundsOrLabelTranslate(
     const depthTestAgainstTerrain =
       defined(scene.globe) && scene.globe.depthTestAgainstTerrain;
 
-    // Only do manual depth test if the globe is opaque and writes depth
+    // Only do manual depth test when the globe is opaque. Collections may
+    // explicitly opt in when the globe does not also depth-test entities.
     billboardCollection._shaderClampToGround =
-      context.depthTexture && !globeTranslucent && depthTestAgainstTerrain;
+      context.depthTexture &&
+      !globeTranslucent &&
+      (depthTestAgainstTerrain ||
+        billboardCollection._alwaysThreePointDepthTest);
   }
   const writer =
     vafWriters[attributeLocations.textureCoordinateBoundsOrLabelTranslate];

package/Source/Scene/BillboardTexture.js

@@ -199,9 +199,11 @@ BillboardTexture.prototype.loadImage = async function (
   let index;
   const atlas = this._billboardCollection.textureAtlas;
   try {
-    index = atlas.addImage(id, image, width, height);
-    if (index instanceof Promise) {
-      index = await index;
+    const indexOrPromise = atlas.addImage(id, image, width, height);
+    if (typeof indexOrPromise === "number") {
+      index = indexOrPromise;
+    } else {
+      index = await indexOrPromise;
     }
   } catch (error) {
     // There was an error loading the image

package/Source/Scene/BufferPointCollection.js

@@ -7,6 +7,8 @@ import Frozen from "../Core/Frozen.js";
 import renderPoints from "./renderBufferPointCollection.js";
 import BufferPointMaterial from "./BufferPointMaterial.js";
 
+/** @import BlendOption from "./BlendOption.js"; */
+/** @import BoundingSphere from "../Core/BoundingSphere.js"; */
 /** @import ComponentDatatype from "../Core/ComponentDatatype.js"; */
 /** @import Matrix4 from "../Core/Matrix4.js"; */
 /** @import FrameState from "./FrameState.js"; */
@@ -58,10 +60,16 @@ class BufferPointCollection extends BufferPrimitiveCollection {
    * @param {object} options
    * @param {Matrix4} [options.modelMatrix=Matrix4.IDENTITY] Transforms geometry from model to world coordinates.
    * @param {number} [options.primitiveCountMax=BufferPrimitiveCollection.DEFAULT_CAPACITY]
-   * @param {boolean} [options.show=true]
    * @param {ComponentDatatype} [options.positionDatatype=ComponentDatatype.DOUBLE]
+   * @param {boolean} [options.positionNormalized=false]
+   * @param {boolean} [options.show=true]
    * @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) {
     super({ ...options, vertexCountMax: options.primitiveCountMax });
@@ -91,6 +99,8 @@ class BufferPointCollection extends BufferPrimitiveCollection {
   static _cloneEmpty(collection) {
     return new BufferPointCollection({
       primitiveCountMax: collection.primitiveCountMax,
+      positionDatatype: collection.positionDatatype,
+      positionNormalized: collection.positionNormalized,
     });
   }
 

package/Source/Scene/BufferPolygonCollection.js

@@ -9,6 +9,8 @@ import IndexDatatype from "../Core/IndexDatatype.js";
 import renderPolygons from "./renderBufferPolygonCollection.js";
 import BufferPolygonMaterial from "./BufferPolygonMaterial.js";
 
+/** @import BlendOption from "./BlendOption.js"; */
+/** @import BoundingSphere from "../Core/BoundingSphere.js"; */
 /** @import { TypedArray } from "../Core/globalTypes.js"; */
 /** @import Matrix4 from "../Core/Matrix4.js"; */
 /** @import FrameState from "./FrameState.js" */
@@ -80,9 +82,15 @@ class BufferPolygonCollection extends BufferPrimitiveCollection {
    * @param {number} [options.holeCountMax=BufferPrimitiveCollection.DEFAULT_CAPACITY]
    * @param {number} [options.triangleCountMax=BufferPrimitiveCollection.DEFAULT_CAPACITY]
    * @param {ComponentDatatype} [options.positionDatatype=ComponentDatatype.DOUBLE]
+   * @param {boolean} [options.positionNormalized=false]
    * @param {boolean} [options.show=true]
    * @param {boolean} [options.allowPicking=true] 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) {
     super(options);
@@ -107,6 +115,22 @@ class BufferPolygonCollection extends BufferPrimitiveCollection {
      */
     this._holeIndexView = null;
 
+    /**
+     * Per-vertex tile side flags used to suppress outlines along clipped tile
+     * boundaries. Undefined for collections that do not originate from MVT.
+     * @type {TypedArray|undefined}
+     * @ignore
+     */
+    this._polygonTileBoundaryFlags = undefined;
+
+    /**
+     * Whether the collection draws polygon outlines. Vector tile styling sets
+     * this when either outline color or width is present in the style.
+     * @type {boolean}
+     * @ignore
+     */
+    this._polygonOutlineEnabled = false;
+
     /**
      * @type {number}
      * @ignore
@@ -225,6 +249,8 @@ class BufferPolygonCollection extends BufferPrimitiveCollection {
       vertexCountMax: collection.vertexCountMax,
       holeCountMax: collection.holeCountMax,
       triangleCountMax: collection.triangleCountMax,
+      positionDatatype: collection.positionDatatype,
+      positionNormalized: collection.positionNormalized,
     });
   }
 

package/Source/Scene/BufferPolylineCollection.js

@@ -82,6 +82,8 @@ class BufferPolylineCollection extends BufferPrimitiveCollection {
     return new BufferPolylineCollection({
       primitiveCountMax: collection.primitiveCountMax,
       vertexCountMax: collection.vertexCountMax,
+      positionDatatype: collection.positionDatatype,
+      positionNormalized: collection.positionNormalized,
     });
   }
 

package/Source/Scene/BufferPrimitiveCollection.js

@@ -9,8 +9,11 @@ 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"; */
@@ -74,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) {
     /**
@@ -86,6 +97,15 @@ 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
@@ -98,14 +118,17 @@ class BufferPrimitiveCollection {
      * @readonly
      * @protected
      */
-    this._boundingVolume = new BoundingSphere();
+    this._boundingVolume = BoundingSphere.clone(
+      options.boundingVolume ?? new BoundingSphere(),
+      new BoundingSphere(),
+    );
 
     /**
-     * @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}.
@@ -171,7 +194,6 @@ class BufferPrimitiveCollection {
 
     /**
      * @type {number}
-     * @protected
      * @ignore
      */
     this._positionCountMax =
@@ -183,6 +205,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
@@ -211,10 +248,15 @@ class BufferPrimitiveCollection {
      */
     this._dirtyBoundingVolume = false;
 
+    /**
+     * Monotonically increasing counter, bumped each time collection is marked "clean".
+     * @type {number}
+     * @ignore
+     */
+    this._version = 0;
+
     this._allocatePrimitiveBuffer();
-    this._allocatePositionBuffer(
-      options.positionDatatype ?? ComponentDatatype.DOUBLE,
-    );
+    this._allocatePositionBuffer();
     this._allocateMaterialBuffer();
   }
 
@@ -267,14 +309,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,
     );
   }
@@ -471,28 +512,32 @@ 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,
       Cartesian3.ZERO,
       3,
-      this.boundingVolume,
+      this._boundingVolume,
     );
     BoundingSphere.transform(
-      this.boundingVolume,
-      this.modelMatrix,
-      this.boundingVolumeWC,
+      this._boundingVolume,
+      this._modelMatrix,
+      this._boundingVolume,
     );
+
     this._dirtyBoundingVolume = false;
   }
 
@@ -623,11 +668,26 @@ class BufferPrimitiveCollection {
   }
 
   /**
-   * Marks collection bounding volume as 'dirty', to be updated on next render.
+   * Marks all primitives 'clean', and updates version counter.
+   * @ignore
+   */
+  _makeClean() {
+    if (this._dirtyCount > 0) {
+      this._dirtyCount = 0;
+      this._dirtyOffset = 0;
+      this._version++;
+    }
+  }
+
+  /**
+   * 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;
+    }
   }
 
   /////////////////////////////////////////////////////////////////////////////
@@ -724,23 +784,36 @@ class BufferPrimitiveCollection {
   }
 
   /**
-   * Local bounding volume for all primitives in the collection, including both
+   * World-space bounding volume for all primitives in the collection, including both
    * shown and hidden primitives.
    * @type {BoundingSphere}
    * @readonly
    */
   get boundingVolume() {
+    if (this._dirtyBoundingVolume) {
+      this._updateBoundingVolume();
+    }
     return this._boundingVolume;
   }
 
   /**
-   * World bounding volume for all primitives in the collection, including both
-   * shown and hidden primitives.
-   * @type {BoundingSphere}
+   * 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 boundingVolumeWC() {
-    return this._boundingVolumeWC;
+  get positionNormalized() {
+    return this._positionNormalized;
   }
 
   /////////////////////////////////////////////////////////////////////////////