@cesium/engine 22.3.0 → 23.0.0

package/Source/Core/GoogleMaps.js

@@ -5,7 +5,11 @@ import Resource from "./Resource.js";
  * Default settings for accessing the Google Maps API.
  * <br/>
  * An API key is only required if you are directly using any Google Maps APIs, such as through {@link createGooglePhotorealistic3DTileset}.
- * Follow instructions for managing API keys for the Google Maps Platform at {@link https://developers.google.com/maps/documentation/embed/get-api-key}
+ * Follow instructions for managing API keys for the Google Maps Platform at {@link https://developers.google.com/maps/documentation/embed/get-api-key}.
+ * <br/>
+ * You can enable multiple Google Maps Platform APIs on a single API key.
+ * However, a separate {@link GoogleMaps.defaultStreetViewStaticApiKey}
+ * is available if you prefer to use a dedicated key for the Street View Static API.
  *
  * @see createGooglePhotorealistic3DTileset
  * @see https://developers.google.com/maps/documentation/embed/get-api-key
@@ -31,9 +35,26 @@ GoogleMaps.mapTilesApiEndpoint = new Resource({
   url: "https://tile.googleapis.com/",
 });
 
+/**
+ * Gets or sets the default Google Maps Street View Static API key.
+ *
+ * @type {undefined|string}
+ */
+GoogleMaps.defaultStreetViewStaticApiKey = undefined;
+
+/**
+ * Gets or sets the default Google Street View Static API endpoint.
+ *
+ * @type {string|Resource}
+ * @default https://maps.googleapis.com/maps/api/streetview
+ */
+GoogleMaps.streetViewStaticApiEndpoint = new Resource({
+  url: "https://maps.googleapis.com/maps/api/streetview",
+});
+
 GoogleMaps.getDefaultCredit = function () {
   return new Credit(
-    `<img src="https://assets.ion.cesium.com/google-credit.png" style="vertical-align: -5px" alt="Google">`,
+    `<img alt=\"Google\" src=\"https://assets.ion.cesium.com/google-credit.png\" style=\"vertical-align:-6px\">`,
     true,
   );
 };

package/Source/Core/Ion.js

@@ -4,7 +4,7 @@ import Resource from "./Resource.js";
 
 let defaultTokenCredit;
 const defaultAccessToken =
-  "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJlZWVkZjhjNC01NjdhLTQwNTctOTExMy02MThlYjIxM2U4OTkiLCJpZCI6MjU5LCJpYXQiOjE3NzAwNTUxOTV9.aJTRjsRlsJwPC0Nfcq4xscYc2lPJcGFku_PVxp1ZPyQ";
+  "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJhMzVlNTU2ZC1lYmM1LTQ2OWEtODRhOS0wYTFkODZmZTQ0OTgiLCJpZCI6MjU5LCJpYXQiOjE3NzI0ODIxOTR9.1oVHvVA9yr1C3CbLjlzcQQUyBuUuNaNCcc9_Giy8t7U";
 /**
  * Default settings for accessing the Cesium ion API.
  *

package/Source/Core/OpenCageGeocoderService.js

@@ -119,9 +119,8 @@ OpenCageGeocoderService.prototype.geocode = async function (query) {
           bounds.northeast.lat,
         );
       } else {
-        const lon = resultObject.geometry.lat;
-        const lat = resultObject.geometry.lng;
-        destination = Cartesian3.fromDegrees(lon, lat);
+        const { lng, lat } = resultObject.geometry;
+        destination = Cartesian3.fromDegrees(lng, lat);
       }
 
       return {

package/Source/Core/globalTypes.js

@@ -0,0 +1,16 @@
+/**
+ * Union of all numeric typed array types.
+ * @typedef {Float64Array|Float32Array|Uint32Array|Uint16Array|Uint8Array|Int32Array|Int16Array|Int8Array} TypedArray
+ */
+
+/**
+ * Union of all numeric typed array constructor types.
+ * @typedef {Float64ArrayConstructor|Float32ArrayConstructor|Uint32ArrayConstructor|Uint16ArrayConstructor|Uint8ArrayConstructor|Int32ArrayConstructor|Int16ArrayConstructor|Int8ArrayConstructor} TypedArrayConstructor
+ */
+
+/**
+ * This file is omitted from 'workspaceSourceFiles' in 'scripts/build.js', and
+ * must provide type-only exports exclusively, without runtime values.
+ * @ignore
+ */
+export default null;

package/Source/Renderer/ShaderDestination.js

@@ -1,15 +1,17 @@
 import Check from "../Core/Check.js";
+import DeveloperError from "../Core/DeveloperError.js";
 
 /**
- * An enum describing whether a variable should be added to the
- * vertex shader, the fragment shader, or both.
+ * A bit flag describing whether a variable should be added to the
+ * vertex shader, the fragment shader, or both (or none).
  *
  * @private
  */
 const ShaderDestination = {
-  VERTEX: 0,
-  FRAGMENT: 1,
-  BOTH: 2,
+  NONE: 0,
+  VERTEX: 1,
+  FRAGMENT: 2,
+  BOTH: 3,
 };
 
 /**
@@ -24,10 +26,7 @@ ShaderDestination.includesVertexShader = function (destination) {
   Check.typeOf.number("destination", destination);
   //>>includeEnd('debug');
 
-  return (
-    destination === ShaderDestination.VERTEX ||
-    destination === ShaderDestination.BOTH
-  );
+  return (destination & ShaderDestination.VERTEX) !== 0;
 };
 
 /**
@@ -42,10 +41,52 @@ ShaderDestination.includesFragmentShader = function (destination) {
   Check.typeOf.number("destination", destination);
   //>>includeEnd('debug');
   //
-  return (
-    destination === ShaderDestination.FRAGMENT ||
-    destination === ShaderDestination.BOTH
-  );
+
+  return (destination & ShaderDestination.FRAGMENT) !== 0;
+};
+
+/**
+ * Compute the union of multiple ShaderDestinations (e.g., VERTEX | FRAGMENT yields BOTH)
+ * @param  {...ShaderDestination} destinations
+ * @returns {ShaderDestination} The union of the provided destinations
+ * @private
+ */
+ShaderDestination.union = function (...destinations) {
+  //>>includeStart('debug', pragmas.debug);
+  if (destinations.length === 0) {
+    throw new DeveloperError(
+      "ShaderDestination.union requires at least one destination.",
+    );
+  }
+  //>>includeEnd('debug');
+
+  let result = 0;
+  for (let i = 0; i < destinations.length; i++) {
+    result |= destinations[i];
+  }
+  return result;
+};
+
+/**
+ * Compute the intersection of multiple ShaderDestinations (e.g., VERTEX & FRAGMENT yields NONE)
+ * @param  {...ShaderDestination} destinations
+ * @returns {ShaderDestination} The intersection of the provided destinations
+ * @private
+ */
+ShaderDestination.intersection = function (...destinations) {
+  //>>includeStart('debug', pragmas.debug);
+  if (destinations.length === 0) {
+    throw new DeveloperError(
+      "ShaderDestination.intersection requires at least one destination.",
+    );
+  }
+  //>>includeEnd('debug');
+
+  let result = destinations[0];
+  for (let i = 1; i < destinations.length; i++) {
+    result &= destinations[i];
+  }
+  return result;
 };
 
 export default Object.freeze(ShaderDestination);

package/Source/Scene/ArcGisMapService.js

@@ -4,7 +4,7 @@ import Resource from "../Core/Resource.js";
 
 let defaultTokenCredit;
 const defaultAccessToken =
-  "AAPTxy8BH1VEsoebNVZXo8HurEOF051kAEKlhkOhBEc9BmQBN5OwMQnvqcM3GTdzwDusCXj4eE5jKKONHLoPEAvNXnML4d2_ObFMHiYtbS6gOWoNlH6cNDium9FLGy4eRBK7mcDQKdokYzlY27y-WPo25dgjAfx6C0rbvGsk0yn7FHPv8yDcsW5frQhhXIJ48lW5UcbIlpxY_j-Im5MJfxgIQuUA_m0tvy4rxbkTMNS26yA.AT1_DJvNEaWq";
+  "AAPTahokHpH_PEeQIduLwb1A8ZA..rA8bGH-48FscqzwJpCALUEqt2P_mHiflgl0WkBvCxPJzsFMRqAukz-mcG8oZ3eKnfk4MHGvCFMNsNrxXb2fGxfKH-3TQxCZVkCycztIPWRM5OIQ7pzTZIBOO9D7N8VXXpyPtp2bSsxWp5dUpv8qsgrfMHU4IXWGiiKWELBnANXn1QgzyLKngOHAgYWUq2OQ2XuULOpwJwOEWpyX5KvoLavJP0LFJdjB08Mmz-wCvnFqwr8CZjFpKaVSbAT1_aZs2dlMP";
 /**
  * Default options for accessing the ArcGIS image tile service.
  *

package/Source/Scene/Billboard.js

@@ -52,7 +52,7 @@ import isDataUri from "../Core/isDataUri.js";
  * @property {NearFarScalar} [pixelOffsetScaleByDistance] A {@link NearFarScalar} Specifying near and far pixel offset scaling properties of a Billboard based on the billboard's distance from the camera.
  * @property {BoundingRectangle} [imageSubRegion] A {@link BoundingRectangle} Specifying the sub-region of the image to use for the billboard, rather than the entire image.
  * @property {DistanceDisplayCondition} [distanceDisplayCondition] A {@link DistanceDisplayCondition} Specifying the distance from the camera at which this billboard will be displayed.
- * @property {number} [disableDepthTestDistance] A number specifying the distance from the camera at which to disable the depth test to, for example, prevent clipping against terrain.
+ * @property {number} [disableDepthTestDistance] The distance from the camera, beyond which, depth testing is disabled—to, for example, prevent clipping against terrain.
  * @property {SplitDirection} [splitDirection] A {@link SplitDirection} Specifying the split property of the billboard.
  */
 
@@ -845,10 +845,13 @@ Object.defineProperties(Billboard.prototype, {
   },
 
   /**
-   * Gets or sets the distance from the camera at which to disable the depth test to, for example, prevent clipping against terrain.
-   * When set to zero, the depth test is always applied. When set to Number.POSITIVE_INFINITY, the depth test is never applied.
+   * Gets or sets the distance from the camera, beyond which, depth testing is disbaled—to,
+   * for example, prevent clipping against terrain. When set to <code>undefined</code> or
+   * <code>0</code>, the depth test is always applied. When set to
+   * <code>Number.POSITIVE_INFINITY</code>, the depth test is never applied.
    * @memberof Billboard.prototype
-   * @type {number}
+   * @type {number|undefined}
+   * @default undefined
    */
   disableDepthTestDistance: {
     get: function () {

package/Source/Scene/BillboardCollection.js

@@ -118,7 +118,8 @@ const attributeLocationsInstanced = {
  * is used for rendering both opaque and translucent billboards. However, if either all of the billboards are completely opaque or all are completely translucent,
  * setting the technique to BlendOption.OPAQUE or BlendOption.TRANSLUCENT can improve performance by up to 2x.
  * @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}.
  * @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
@@ -317,8 +318,11 @@ function BillboardCollection(options) {
   ];
 
   this._highlightColor = Color.clone(Color.WHITE); // Only used by Vector3DTilePoints
-  this._coarseDepthTestDistance = Ellipsoid.default.minimumRadius / 100;
-  this._threePointDepthTestDistance = Ellipsoid.default.minimumRadius / 1000;
+  this._coarseDepthTestDistance =
+    options.coarseDepthTestDistance ?? Ellipsoid.default.minimumRadius / 10.0;
+  this._threePointDepthTestDistance =
+    options.threePointDepthTestDistance ??
+    Ellipsoid.default.minimumRadius / 1000.0;
 
   this._uniforms = {
     u_atlas: () => {
@@ -327,13 +331,9 @@ function BillboardCollection(options) {
     u_highlightColor: () => {
       return this._highlightColor;
     },
-    // An eye-space distance, beyond which, the billboard is simply tested against a camera-facing plane at the ellipsoid's center,
-    // rather than against a depth texture. Note: only if the disableDepthTestingDistance property permits.
     u_coarseDepthTestDistance: () => {
       return this._coarseDepthTestDistance;
     },
-    // Within this distance, if the billboard is clamped to the ground, we'll depth-test 3 key points.
-    // If any key point is visible, the whole billboard will be visible.
     u_threePointDepthTestDistance: () => {
       return this._threePointDepthTestDistance;
     },
@@ -466,6 +466,56 @@ Object.defineProperties(BillboardCollection.prototype, {
       return this._billboardTextureCache;
     },
   },
+
+  /**
+   * 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. When set to <code>0</code>, the
+   * approximate depth test is always applied. When set to <code>Number.POSITIVE_INFINITY</code>, the
+   * approximate depth test is never applied.
+   * <br/><br/>
+   * This setting only applies when a billboard's {@link Billboard#disableDepthTestDistance} value would
+   * otherwise allow depth testing—i.e., distance from the camera to the billboard is less than a
+   * billboard's {@link Billboard#disableDepthTestDistance} value.
+   * @memberof BillboardCollection.prototype
+   * @type {number}
+   */
+  coarseDepthTestDistance: {
+    get: function () {
+      return this._coarseDepthTestDistance;
+    },
+    set: function (value) {
+      //>>includeStart('debug', pragmas.debug);
+      Check.typeOf.number("coarseDepthTestDistance", value);
+      //>>includeEnd('debug');
+      this._coarseDepthTestDistance = value;
+    },
+  },
+
+  /**
+   * 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. When set to <code>0</code>, this feature is disabled and portions of a
+   * billboards behind terrain be clipped.
+   * <br/><br/>
+   * This setting only applies when a billboard's {@link Billboard#disableDepthTestDistance} value would
+   * otherwise allow depth testing—i.e., distance from the camera to the billboard is less than a
+   * billboard's {@link Billboard#disableDepthTestDistance} value.
+   * @see {@link https://cesium.com/blog/2018/07/30/billboards-on-terrain-improvements/|Billboards and Labels on Terrain Improvements}
+   * @memberof BillboardCollection.prototype
+   * @type {number}
+   */
+  threePointDepthTestDistance: {
+    get: function () {
+      return this._threePointDepthTestDistance;
+    },
+    set: function (value) {
+      //>>includeStart('debug', pragmas.debug);
+      Check.typeOf.number("threePointDepthTestDistance", value);
+      //>>includeEnd('debug');
+      this._threePointDepthTestDistance = value;
+    },
+  },
 });
 
 function destroyBillboards(billboards) {
@@ -1204,22 +1254,14 @@ function writeCompressedAttrib2(
   );
   let labelHorizontalOrigin = billboard._labelHorizontalOrigin ?? -2;
   labelHorizontalOrigin += 2;
-  const compressed3 = imageHeight * LEFT_SHIFT2 + labelHorizontalOrigin;
 
-  let red = Color.floatToByte(color.red);
-  let green = Color.floatToByte(color.green);
-  let blue = Color.floatToByte(color.blue);
-  const compressed0 = red * LEFT_SHIFT16 + green * LEFT_SHIFT8 + blue;
-
-  red = Color.floatToByte(pickColor.red);
-  green = Color.floatToByte(pickColor.green);
-  blue = Color.floatToByte(pickColor.blue);
-  const compressed1 = red * LEFT_SHIFT16 + green * LEFT_SHIFT8 + blue;
-
-  let compressed2 =
+  const compressed0 = AttributeCompression.encodeRGB8(color);
+  const compressed1 = AttributeCompression.encodeRGB8(pickColor);
+  const compressed2 =
     Color.floatToByte(color.alpha) * LEFT_SHIFT16 +
-    Color.floatToByte(pickColor.alpha) * LEFT_SHIFT8;
-  compressed2 += sizeInMeters * 2.0 + validAlignedAxis;
+    Color.floatToByte(pickColor.alpha) * LEFT_SHIFT8 +
+    (sizeInMeters * 2.0 + validAlignedAxis);
+  const compressed3 = imageHeight * LEFT_SHIFT2 + labelHorizontalOrigin;
 
   if (billboardCollection._instanced) {
     i = billboard._index;
@@ -1526,10 +1568,7 @@ function writeSDF(billboardCollection, frameState, vafWriters, billboard) {
   const outlineColor = billboard.outlineColor;
   const outlineWidth = billboard.outlineWidth;
 
-  const red = Color.floatToByte(outlineColor.red);
-  const green = Color.floatToByte(outlineColor.green);
-  const blue = Color.floatToByte(outlineColor.blue);
-  const compressed0 = red * LEFT_SHIFT16 + green * LEFT_SHIFT8 + blue;
+  const compressed0 = AttributeCompression.encodeRGB8(outlineColor);
 
   // Compute the relative outline distance
   const outlineDistance = outlineWidth / SDFSettings.RADIUS;

package/Source/Scene/BufferLoader.js

@@ -10,46 +10,40 @@ import ResourceLoaderState from "./ResourceLoaderState.js";
  * Implements the {@link ResourceLoader} interface.
  * </p>
  *
- * @alias BufferLoader
- * @constructor
- * @augments ResourceLoader
- *
- * @param {object} options Object with the following properties:
- * @param {Uint8Array} [options.typedArray] The typed array containing the embedded buffer contents. Mutually exclusive with options.resource.
- * @param {Resource} [options.resource] The {@link Resource} pointing to the external buffer. Mutually exclusive with options.typedArray.
- * @param {string} [options.cacheKey] The cache key of the resource.
- *
- * @exception {DeveloperError} One of options.typedArray and options.resource must be defined.
- *
  * @private
  */
-function BufferLoader(options) {
-  options = options ?? Frozen.EMPTY_OBJECT;
-  const typedArray = options.typedArray;
-  const resource = options.resource;
-  const cacheKey = options.cacheKey;
+class BufferLoader extends ResourceLoader {
+  /**
+   * @param {object} options Object with the following properties:
+   * @param {Uint8Array} [options.typedArray] The typed array containing the embedded buffer contents. Mutually exclusive with options.resource.
+   * @param {Resource} [options.resource] The {@link Resource} pointing to the external buffer. Mutually exclusive with options.typedArray.
+   * @param {string} [options.cacheKey] The cache key of the resource.
+   *
+   * @exception {DeveloperError} One of options.typedArray and options.resource must be defined.
+   */
+  constructor(options) {
+    super();
 
-  //>>includeStart('debug', pragmas.debug);
-  if (defined(typedArray) === defined(resource)) {
-    throw new DeveloperError(
-      "One of options.typedArray and options.resource must be defined.",
-    );
-  }
-  //>>includeEnd('debug');
+    options = options ?? Frozen.EMPTY_OBJECT;
+    const typedArray = options.typedArray;
+    const resource = options.resource;
+    const cacheKey = options.cacheKey;
 
-  this._typedArray = typedArray;
-  this._resource = resource;
-  this._cacheKey = cacheKey;
-  this._state = ResourceLoaderState.UNLOADED;
-  this._promise = undefined;
-}
+    //>>includeStart('debug', pragmas.debug);
+    if (defined(typedArray) === defined(resource)) {
+      throw new DeveloperError(
+        "One of options.typedArray and options.resource must be defined.",
+      );
+    }
+    //>>includeEnd('debug');
 
-if (defined(Object.create)) {
-  BufferLoader.prototype = Object.create(ResourceLoader.prototype);
-  BufferLoader.prototype.constructor = BufferLoader;
-}
+    this._typedArray = typedArray;
+    this._resource = resource;
+    this._cacheKey = cacheKey;
+    this._state = ResourceLoaderState.UNLOADED;
+    this._promise = undefined;
+  }
 
-Object.defineProperties(BufferLoader.prototype, {
   /**
    * The cache key of the resource.
    *
@@ -59,11 +53,10 @@ Object.defineProperties(BufferLoader.prototype, {
    * @readonly
    * @private
    */
-  cacheKey: {
-    get: function () {
-      return this._cacheKey;
-    },
-  },
+  get cacheKey() {
+    return this._cacheKey;
+  }
+
   /**
    * The typed array containing the embedded buffer contents.
    *
@@ -73,31 +66,45 @@ Object.defineProperties(BufferLoader.prototype, {
    * @readonly
    * @private
    */
-  typedArray: {
-    get: function () {
-      return this._typedArray;
-    },
-  },
-});
+  get typedArray() {
+    return this._typedArray;
+  }
 
-/**
- * Loads the resource.
- * @returns {Promise<BufferLoader>} A promise which resolves to the loader when the resource loading is completed.
- * @private
- */
-BufferLoader.prototype.load = async function () {
-  if (defined(this._promise)) {
+  /**
+   * Loads the resource.
+   * @returns {Promise<BufferLoader>} A promise which resolves to the loader when the resource loading is completed.
+   * @private
+   */
+  async load() {
+    if (defined(this._promise)) {
+      return this._promise;
+    }
+
+    if (defined(this._typedArray)) {
+      this._promise = Promise.resolve(this);
+      return this._promise;
+    }
+
+    this._promise = loadExternalBuffer(this);
     return this._promise;
   }
 
-  if (defined(this._typedArray)) {
-    this._promise = Promise.resolve(this);
-    return this._promise;
+  /**
+   * Exposed for testing
+   * @private
+   */
+  static _fetchArrayBuffer(resource) {
+    return resource.fetchArrayBuffer();
   }
 
-  this._promise = loadExternalBuffer(this);
-  return this._promise;
-};
+  /**
+   * Unloads the resource.
+   * @private
+   */
+  unload() {
+    this._typedArray = undefined;
+  }
+}
 
 async function loadExternalBuffer(bufferLoader) {
   const resource = bufferLoader._resource;
@@ -122,20 +129,4 @@ async function loadExternalBuffer(bufferLoader) {
   }
 }
 
-/**
- * Exposed for testing
- * @private
- */
-BufferLoader._fetchArrayBuffer = function (resource) {
-  return resource.fetchArrayBuffer();
-};
-
-/**
- * Unloads the resource.
- * @private
- */
-BufferLoader.prototype.unload = function () {
-  this._typedArray = undefined;
-};
-
 export default BufferLoader;