@cesium/engine 2.1.0 → 2.3.0

package/Source/Scene/ClassificationPrimitive.js

@@ -2,6 +2,7 @@ import ColorGeometryInstanceAttribute from "../Core/ColorGeometryInstanceAttribu
 import combine from "../Core/combine.js";
 import defaultValue from "../Core/defaultValue.js";
 import defined from "../Core/defined.js";
+import deprecationWarning from "../Core/deprecationWarning.js";
 import destroyObject from "../Core/destroyObject.js";
 import DeveloperError from "../Core/DeveloperError.js";
 import GeometryInstance from "../Core/GeometryInstance.js";
@@ -164,6 +165,7 @@ function ClassificationPrimitive(options) {
   this._ready = false;
 
   const classificationPrimitive = this;
+  // This is here for backwards compatibility. This promise wrapper can be removed once readyPromise is removed.
   this._readyPromise = new Promise((resolve, reject) => {
     classificationPrimitive._completeLoad = () => {
       if (this._ready) {
@@ -340,9 +342,14 @@ Object.defineProperties(ClassificationPrimitive.prototype, {
    * @memberof ClassificationPrimitive.prototype
    * @type {Promise<ClassificationPrimitive>}
    * @readonly
+   * @deprecated
    */
   readyPromise: {
     get: function () {
+      deprecationWarning(
+        "ClassificationPrimitive.readyPromise",
+        "ClassificationPrimitive.readyPromise was deprecated in CesiumJS 1.104. It will be removed in 1.107. Wait for ClassificationPrimitive.ready to return true instead."
+      );
       return this._readyPromise;
     },
   },

package/Source/Scene/Composite3DTileContent.js

@@ -1,5 +1,6 @@
 import defaultValue from "../Core/defaultValue.js";
 import defined from "../Core/defined.js";
+import deprecationWarning from "../Core/deprecationWarning.js";
 import destroyObject from "../Core/destroyObject.js";
 import getMagic from "../Core/getMagic.js";
 import RuntimeError from "../Core/RuntimeError.js";
@@ -17,23 +18,24 @@ import RuntimeError from "../Core/RuntimeError.js";
  *
  * @private
  */
-function Composite3DTileContent(
-  tileset,
-  tile,
-  resource,
-  arrayBuffer,
-  byteOffset,
-  factory
-) {
+function Composite3DTileContent(tileset, tile, resource, contents) {
   this._tileset = tileset;
   this._tile = tile;
   this._resource = resource;
-  this._contents = [];
+
+  if (!defined(contents)) {
+    contents = [];
+  }
+  this._contents = contents;
 
   this._metadata = undefined;
   this._group = undefined;
+  this._ready = false;
 
-  this._readyPromise = initialize(this, arrayBuffer, byteOffset, factory);
+  this._resolveContent = undefined;
+  this._readyPromise = new Promise((resolve) => {
+    this._resolveContent = resolve;
+  });
 }
 
 Object.defineProperties(Composite3DTileContent.prototype, {
@@ -130,8 +132,37 @@ Object.defineProperties(Composite3DTileContent.prototype, {
     },
   },
 
+  /**
+   * Returns true when the tile's content is ready to render; otherwise false
+   *
+   * @memberof Composite3DTileContent.prototype
+   *
+   * @type {boolean}
+   * @readonly
+   * @private
+   */
+  ready: {
+    get: function () {
+      return this._ready;
+    },
+  },
+
+  /**
+   * Gets the promise that will be resolved when the tile's content is ready to render.
+   *
+   * @memberof Composite3DTileContent.prototype
+   *
+   * @type {Promise<Composite3DTileContent>}
+   * @readonly
+   * @deprecated
+   * @private
+   */
   readyPromise: {
     get: function () {
+      deprecationWarning(
+        "Composite3DTileContent.readyPromise",
+        "Composite3DTileContent.readyPromise was deprecated in CesiumJS 1.104. It will be removed in 1.107. Wait for Composite3DTileContent.ready to return true instead."
+      );
       return this._readyPromise;
     },
   },
@@ -210,7 +241,14 @@ Object.defineProperties(Composite3DTileContent.prototype, {
 
 const sizeOfUint32 = Uint32Array.BYTES_PER_ELEMENT;
 
-function initialize(content, arrayBuffer, byteOffset, factory) {
+Composite3DTileContent.fromTileType = async function (
+  tileset,
+  tile,
+  resource,
+  arrayBuffer,
+  byteOffset,
+  factory
+) {
   byteOffset = defaultValue(byteOffset, 0);
 
   const uint8Array = new Uint8Array(arrayBuffer);
@@ -231,14 +269,11 @@ function initialize(content, arrayBuffer, byteOffset, factory) {
   const tilesLength = view.getUint32(byteOffset, true);
   byteOffset += sizeOfUint32;
 
-  const contentPromises = [];
-
   // For caching purposes, models within the composite tile must be
   // distinguished. To do this, add a query parameter ?compositeIndex=i.
   // Since composite tiles may contain other composite tiles, check for an
   // existing prefix and separate them with underscores. e.g.
   // ?compositeIndex=0_1_1
-  const resource = content._resource;
   let prefix = resource.queryParameters.compositeIndex;
   if (defined(prefix)) {
     // We'll be adding another value at the end, so add an underscore.
@@ -248,6 +283,8 @@ function initialize(content, arrayBuffer, byteOffset, factory) {
     prefix = "";
   }
 
+  const promises = [];
+  promises.length = tilesLength;
   for (let i = 0; i < tilesLength; ++i) {
     const tileType = getMagic(uint8Array, byteOffset);
 
@@ -265,15 +302,9 @@ function initialize(content, arrayBuffer, byteOffset, factory) {
     });
 
     if (defined(contentFactory)) {
-      const innerContent = contentFactory(
-        content._tileset,
-        content._tile,
-        childResource,
-        arrayBuffer,
-        byteOffset
+      promises[i] = Promise.resolve(
+        contentFactory(tileset, tile, childResource, arrayBuffer, byteOffset)
       );
-      content._contents.push(innerContent);
-      contentPromises.push(innerContent.readyPromise);
     } else {
       throw new RuntimeError(
         `Unknown tile content type, ${tileType}, inside Composite tile`
@@ -283,10 +314,15 @@ function initialize(content, arrayBuffer, byteOffset, factory) {
     byteOffset += tileByteLength;
   }
 
-  return Promise.all(contentPromises).then(function () {
-    return content;
-  });
-}
+  const innerContents = await Promise.all(promises);
+  const content = new Composite3DTileContent(
+    tileset,
+    tile,
+    resource,
+    innerContents
+  );
+  return content;
+};
 
 /**
  * Part of the {@link Cesium3DTileContent} interface.  <code>Composite3DTileContent</code>
@@ -326,8 +362,15 @@ Composite3DTileContent.prototype.applyStyle = function (style) {
 Composite3DTileContent.prototype.update = function (tileset, frameState) {
   const contents = this._contents;
   const length = contents.length;
+  let ready = true;
   for (let i = 0; i < length; ++i) {
     contents[i].update(tileset, frameState);
+    ready = ready && contents[i].ready;
+  }
+
+  if (!this._ready && ready) {
+    this._ready = true;
+    this._resolveContent(this);
   }
 };
 

package/Source/Scene/CreditDisplay.js

@@ -4,6 +4,7 @@ import Check from "../Core/Check.js";
 import Credit from "../Core/Credit.js";
 import defaultValue from "../Core/defaultValue.js";
 import defined from "../Core/defined.js";
+import deprecationWarning from "../Core/deprecationWarning.js";
 import destroyObject from "../Core/destroyObject.js";
 import Uri from "urijs";
 
@@ -174,7 +175,7 @@ function addStyle(selector, styles) {
   return style;
 }
 
-function appendCss() {
+function appendCss(container) {
   let style = "";
   style += addStyle(".cesium-credit-lightbox-overlay", {
     display: "none",
@@ -270,10 +271,26 @@ function appendCss() {
     }
   );
 
-  const head = document.head;
+  function getShadowRoot(container) {
+    if (container.shadowRoot) {
+      return container.shadowRoot;
+    }
+    if (container.getRootNode) {
+      const root = container.getRootNode();
+      if (root instanceof ShadowRoot) {
+        return root;
+      }
+    }
+    return undefined;
+  }
+
+  const shadowRootOrDocumentHead = defaultValue(
+    getShadowRoot(container),
+    document.head
+  );
   const css = document.createElement("style");
   css.innerHTML = style;
-  head.insertBefore(css, head.firstChild);
+  shadowRootOrDocumentHead.appendChild(css);
 }
 
 /**
@@ -287,7 +304,14 @@ function appendCss() {
  * @constructor
  *
  * @example
- * const creditDisplay = new Cesium.CreditDisplay(creditContainer);
+ * // Add a credit with a tooltip, image and link to display onscreen
+ * const credit = new Cesium.Credit(`<a href="https://cesium.com/" target="_blank"><img src="/images/cesium_logo.png" title="Cesium"/></a>`, true);
+ * viewer.creditDisplay.addStaticCredit(credit);
+ *
+ * @example
+ * // Add a credit with a plaintext link to display in the lightbox
+ * const credit = new Cesium.Credit('<a href="https://cesium.com/" target="_blank">Cesium</a>');
+ * viewer.creditDisplay.addStaticCredit(credit);
  */
 function CreditDisplay(container, delimiter, viewport) {
   //>>includeStart('debug', pragmas.debug);
@@ -343,7 +367,7 @@ function CreditDisplay(container, delimiter, viewport) {
   expandLink.textContent = "Data attribution";
   container.appendChild(expandLink);
 
-  appendCss();
+  appendCss(container);
   const cesiumCredit = Credit.clone(CreditDisplay.cesiumCredit);
 
   this._delimiter = defaultValue(delimiter, " • ");
@@ -357,7 +381,7 @@ function CreditDisplay(container, delimiter, viewport) {
   this._hideLightbox = hideLightbox;
   this._expandLink = expandLink;
   this._expanded = false;
-  this._defaultCredits = [];
+  this._staticCredits = [];
   this._cesiumCredit = cesiumCredit;
   this._previousCesiumCredit = undefined;
   this._currentCesiumCredit = cesiumCredit;
@@ -402,17 +426,36 @@ function setCredit(creditDisplay, credits, credit, count) {
 }
 /**
  * Adds a credit to the list of current credits to be displayed in the credit container
+ * for the next frame
  *
  * @param {Credit} credit The credit to display
+ * @deprecated
  */
 CreditDisplay.prototype.addCredit = function (credit) {
+  deprecationWarning(
+    "CreditDisplay.addCredit",
+    "CreditDisplay.addCredit was deprecated in CesiumJS 1.105.  It will be removed in CesiumJS 1.107.  Use CreditDisplay.addCreditToNextFrame instead."
+  );
+
+  this.addCreditToNextFrame(credit);
+};
+
+/**
+ * Adds a {@link Credit} that will show on screen or in the lightbox until
+ * the next frame. This is mostly for internal use. Use {@link CreditDisplay.addStaticCredit} to add a persistent credit to the screen.
+ *
+ * @see CreditDisplay.addStaticCredit
+ *
+ * @param {Credit} credit The credit to display in the next frame.
+ */
+CreditDisplay.prototype.addCreditToNextFrame = function (credit) {
   //>>includeStart('debug', pragmas.debug);
   Check.defined("credit", credit);
   //>>includeEnd('debug');
 
   if (credit._isIon) {
     // If this is the an ion logo credit from the ion server
-    // Juse use the default credit (which is identical) to avoid blinking
+    // Just use the default credit (which is identical) to avoid blinking
     if (!defined(this._defaultCredit)) {
       this._defaultCredit = Credit.clone(getDefaultCredit());
     }
@@ -434,40 +477,94 @@ CreditDisplay.prototype.addCredit = function (credit) {
  * Adds credits that will persist until they are removed
  *
  * @param {Credit} credit The credit to added to defaults
+ *
+ * @deprecated
  */
 CreditDisplay.prototype.addDefaultCredit = function (credit) {
   //>>includeStart('debug', pragmas.debug);
   Check.defined("credit", credit);
   //>>includeEnd('debug');
 
-  const defaultCredits = this._defaultCredits;
+  deprecationWarning(
+    "CreditDisplay.addDefaultCredit",
+    "CreditDisplay.addDefaultCredit was deprecated in CesiumJS 1.105.  It will be removed in CesiumJS 1.107.  Use CreditDisplay.addStaticCredit instead."
+  );
+
+  const defaultCredits = this._staticCredits;
   if (!contains(defaultCredits, credit)) {
+    credit.showOnScreen = true;
     defaultCredits.push(credit);
   }
 };
 
 /**
- * Removes a default credit
+ * Adds a {@link Credit} that will show on screen or in the lightbox until removed with {@link CreditDisplay.removeStaticCredit}.
  *
- * @param {Credit} credit The credit to be removed from defaults
+ * @param {Credit} credit The credit to added
+ *
+ * @example
+ * // Add a credit with a tooltip, image and link to display onscreen
+ * const credit = new Cesium.Credit(`<a href="https://cesium.com/" target="_blank"><img src="/images/cesium_logo.png" title="Cesium"/></a>`, true);
+ * viewer.creditDisplay.addStaticCredit(credit);
+ *
+ * @example
+ * // Add a credit with a plaintext link to display in the lightbox
+ * const credit = new Cesium.Credit('<a href="https://cesium.com/" target="_blank">Cesium</a>');
+ * viewer.creditDisplay.addStaticCredit(credit);
  */
-CreditDisplay.prototype.removeDefaultCredit = function (credit) {
+CreditDisplay.prototype.addStaticCredit = function (credit) {
+  //>>includeStart('debug', pragmas.debug);
+  Check.defined("credit", credit);
+  //>>includeEnd('debug');
+
+  const staticCredits = this._staticCredits;
+  if (!contains(staticCredits, credit)) {
+    staticCredits.push(credit);
+  }
+};
+
+/**
+ * Removes a static credit shown on screen or in the lightbox.
+ *
+ * @param {Credit} credit The credit to be removed.
+ */
+CreditDisplay.prototype.removeStaticCredit = function (credit) {
   //>>includeStart('debug', pragmas.debug);
   Check.defined("credit", credit);
   //>>includeEnd('debug');
 
-  const defaultCredits = this._defaultCredits;
-  const index = defaultCredits.indexOf(credit);
+  const staticCredits = this._staticCredits;
+  const index = staticCredits.indexOf(credit);
   if (index !== -1) {
-    defaultCredits.splice(index, 1);
+    staticCredits.splice(index, 1);
   }
 };
 
+/**
+ * Removes a default credit.
+ *
+ * @param {Credit} credit The credit to be removed from defaults
+ */
+CreditDisplay.prototype.removeDefaultCredit = function (credit) {
+  deprecationWarning(
+    "CreditDisplay.removeDefaultCredit",
+    "CreditDisplay.removeDefaultCredit was deprecated in CesiumJS 1.105.  It will be removed in CesiumJS 1.107.  Use CreditDisplay.addStaticCredit instead."
+  );
+
+  this.removeStaticCredit(credit);
+};
+
+/**
+ * @private
+ */
 CreditDisplay.prototype.showLightbox = function () {
   this._lightbox.style.display = "block";
   this._expanded = true;
 };
 
+/**
+ * @private
+ */
 CreditDisplay.prototype.hideLightbox = function () {
   this._lightbox.style.display = "none";
   this._expanded = false;
@@ -490,14 +587,29 @@ CreditDisplay.prototype.beginFrame = function () {
   this._creditDisplayElementPoolIndex = 0;
 
   const screenCredits = currentFrameCredits.screenCredits;
+  const lightboxCredits = currentFrameCredits.lightboxCredits;
+
   screenCredits.removeAll();
-  const defaultCredits = this._defaultCredits;
-  for (let i = 0; i < defaultCredits.length; ++i) {
-    const defaultCredit = defaultCredits[i];
-    setCredit(this, screenCredits, defaultCredit, Number.MAX_VALUE);
-  }
+  lightboxCredits.removeAll();
+
+  const staticCredits = this._staticCredits;
+  for (let i = 0; i < staticCredits.length; ++i) {
+    const staticCredit = staticCredits[i];
+    const creditCollection = staticCredit.showOnScreen
+      ? screenCredits
+      : lightboxCredits;
 
-  currentFrameCredits.lightboxCredits.removeAll();
+    if (
+      staticCredit._isIon &&
+      Credit.equals(CreditDisplay.cesiumCredit, this._cesiumCredit)
+    ) {
+      // If this is an ion logo credit from the ion server,
+      // make sure to de-duplicate with the default ion credit
+      continue;
+    }
+
+    setCredit(this, creditCollection, staticCredit, Number.MAX_VALUE);
+  }
 
   if (!Credit.equals(CreditDisplay.cesiumCredit, this._cesiumCredit)) {
     this._cesiumCredit = Credit.clone(CreditDisplay.cesiumCredit);

package/Source/Scene/DepthPlane.js

@@ -125,7 +125,7 @@ DepthPlane.prototype.update = function (frameState) {
 
   const context = frameState.context;
 
-  // Allow offsetting the ellipsoid radius to address rendering artefacts below ellipsoid zero elevation.
+  // Allow offsetting the ellipsoid radius to address rendering artifacts below ellipsoid zero elevation.
   const radii = frameState.mapProjection.ellipsoid.radii;
   const ellipsoid = new Ellipsoid(
     radii.x + this._ellipsoidOffset,

package/Source/Scene/Empty3DTileContent.js

@@ -1,3 +1,4 @@
+import deprecationWarning from "../Core/deprecationWarning.js";
 import destroyObject from "../Core/destroyObject.js";
 import DeveloperError from "../Core/DeveloperError.js";
 
@@ -64,9 +65,38 @@ Object.defineProperties(Empty3DTileContent.prototype, {
     },
   },
 
+  /**
+   * Returns true when the tile's content is ready to render; otherwise false
+   *
+   * @memberof Empty3DTileContent.prototype
+   *
+   * @type {boolean}
+   * @readonly
+   * @private
+   */
+  ready: {
+    get: function () {
+      return true;
+    },
+  },
+
+  /**
+   * Gets the promise that will be resolved when the tile's content is ready to render.
+   *
+   * @memberof Empty3DTileContent.prototype
+   *
+   * @type {Promise<Empty3DTileContent>}
+   * @readonly
+   * @deprecated
+   * @private
+   */
   readyPromise: {
     get: function () {
-      return undefined;
+      deprecationWarning(
+        "Empty3DTileContent.readyPromise",
+        "Empty3DTileContent.readyPromise was deprecated in CesiumJS 1.104. It will be removed in 1.107. Wait for Empty3DTileContent.ready to return true instead."
+      );
+      return Promise.resolve(this);
     },
   },
 

package/Source/Scene/Geometry3DTileContent.js

@@ -1,6 +1,7 @@
 import Cartesian3 from "../Core/Cartesian3.js";
 import defaultValue from "../Core/defaultValue.js";
 import defined from "../Core/defined.js";
+import deprecationWarning from "../Core/deprecationWarning.js";
 import destroyObject from "../Core/destroyObject.js";
 import DeveloperError from "../Core/DeveloperError.js";
 import getJsonFromTypedArray from "../Core/getJsonFromTypedArray.js";
@@ -42,7 +43,15 @@ function Geometry3DTileContent(
   this.featurePropertiesDirty = false;
   this._group = undefined;
 
-  this._readyPromise = initialize(this, arrayBuffer, byteOffset);
+  this._ready = false;
+
+  // This is for backwards compatibility. It can be removed once readyPromise is removed.
+  this._resolveContent = undefined;
+  this._readyPromise = new Promise((resolve) => {
+    this._resolveContent = resolve;
+  });
+
+  initialize(this, arrayBuffer, byteOffset);
 }
 
 Object.defineProperties(Geometry3DTileContent.prototype, {
@@ -96,8 +105,37 @@ Object.defineProperties(Geometry3DTileContent.prototype, {
     },
   },
 
+  /**
+   * Returns true when the tile's content is ready to render; otherwise false
+   *
+   * @memberof Geometry3DTileContent.prototype
+   *
+   * @type {boolean}
+   * @readonly
+   * @private
+   */
+  ready: {
+    get: function () {
+      return this._ready;
+    },
+  },
+
+  /**
+   * Gets the promise that will be resolved when the tile's content is ready to render.
+   *
+   * @memberof Geometry3DTileContent.prototype
+   *
+   * @type {Promise<Geometry3DTileContent>}
+   * @readonly
+   * @deprecated
+   * @private
+   */
   readyPromise: {
     get: function () {
+      deprecationWarning(
+        "Geometry3DTileContent.readyPromise",
+        "Geometry3DTileContent.readyPromise was deprecated in CesiumJS 1.104. It will be removed in 1.107. Wait for Geometry3DTileContent.ready to return true instead."
+      );
       return this._readyPromise;
     },
   },
@@ -224,7 +262,7 @@ function getBatchIds(featureTableJson, featureTableBinary) {
 
   if (atLeastOneDefined && atLeastOneUndefined) {
     throw new RuntimeError(
-      "If one group of batch ids is defined, then all batch ids must be defined."
+      "If one group of batch ids is defined, then all batch ids must be defined"
     );
   }
 
@@ -290,7 +328,8 @@ function initialize(content, arrayBuffer, byteOffset) {
   byteOffset += sizeOfUint32;
 
   if (byteLength === 0) {
-    content._readyPromise.resolve(content);
+    content._ready = true;
+    content._resolveContent(content);
     return;
   }
 
@@ -451,9 +490,7 @@ function initialize(content, arrayBuffer, byteOffset) {
       boundingVolume: content.tile.boundingVolume.boundingVolume,
     });
 
-    return content._geometries.readyPromise.then(function () {
-      return content;
-    });
+    return content;
   }
 
   return Promise.resolve(content);
@@ -509,8 +546,11 @@ Geometry3DTileContent.prototype.update = function (tileset, frameState) {
     this._geometries.debugWireframe = this._tileset.debugWireframe;
     this._geometries.update(frameState);
   }
-  if (defined(this._batchTable) && this._geometries._ready) {
+
+  if (defined(this._batchTable) && this._geometries.ready) {
     this._batchTable.update(tileset, frameState);
+    this._ready = true;
+    this._resolveContent(this);
   }
 };
 

package/Source/Scene/Globe.js

@@ -436,6 +436,7 @@ Object.defineProperties(Globe.prototype, {
         return true;
       }
       return (
+        // ready is deprecated. This is here for backwards compatibility
         this._surface.tileProvider.ready &&
         this._surface._tileLoadQueueHigh.length === 0 &&
         this._surface._tileLoadQueueMedium.length === 0 &&
@@ -984,7 +985,10 @@ Globe.prototype.beginFrame = function (frameState) {
   const terrainProvider = this.terrainProvider;
   const hasWaterMask =
     this.showWaterEffect &&
-    terrainProvider.ready &&
+    defined(terrainProvider) &&
+    terrainProvider.hasWaterMask &&
+    // ready is deprecated; This is here for backwards compatibility
+    terrainProvider._ready &&
     terrainProvider.hasWaterMask;
 
   if (hasWaterMask && this._oceanNormalMapResourceDirty) {

package/Source/Scene/GlobeSurfaceTile.js

@@ -345,7 +345,8 @@ GlobeSurfaceTile.prototype.processImagery = function (
 
     if (tileImagery.loadingImagery.state === ImageryState.PLACEHOLDER) {
       const imageryLayer = tileImagery.loadingImagery.imageryLayer;
-      if (imageryLayer.imageryProvider.ready) {
+      // ImageryProvider.ready is deprecated. This is here for backwards compatibility
+      if (imageryLayer.ready && imageryLayer.imageryProvider._ready) {
         // Remove the placeholder and add the actual skeletons (if any)
         // at the same position.  Then continue the loop at the same index.
         tileImagery.freeResources();