@cesium/engine 2.1.0 → 2.3.0

package/Source/Scene/ImageryProvider.js

@@ -43,92 +43,6 @@ import Resource from "../Core/Resource.js";
  * @demo {@link https://sandcastle.cesium.com/index.html?src=Imagery%20Layers%20Manipulation.html|Cesium Sandcastle Imagery Manipulation Demo}
  */
 function ImageryProvider() {
-  /**
-   * The default alpha blending value of this provider, with 0.0 representing fully transparent and
-   * 1.0 representing fully opaque.
-   *
-   * @type {number|undefined}
-   * @default undefined
-   */
-  this.defaultAlpha = undefined;
-
-  /**
-   * The default alpha blending value on the night side of the globe of this provider, with 0.0 representing fully transparent and
-   * 1.0 representing fully opaque.
-   *
-   * @type {number|undefined}
-   * @default undefined
-   */
-  this.defaultNightAlpha = undefined;
-
-  /**
-   * The default alpha blending value on the day side of the globe of this provider, with 0.0 representing fully transparent and
-   * 1.0 representing fully opaque.
-   *
-   * @type {number|undefined}
-   * @default undefined
-   */
-  this.defaultDayAlpha = undefined;
-
-  /**
-   * The default brightness of this provider.  1.0 uses the unmodified imagery color.  Less than 1.0
-   * makes the imagery darker while greater than 1.0 makes it brighter.
-   *
-   * @type {number|undefined}
-   * @default undefined
-   */
-  this.defaultBrightness = undefined;
-
-  /**
-   * The default contrast of this provider.  1.0 uses the unmodified imagery color.  Less than 1.0 reduces
-   * the contrast while greater than 1.0 increases it.
-   *
-   * @type {number|undefined}
-   * @default undefined
-   */
-  this.defaultContrast = undefined;
-
-  /**
-   * The default hue of this provider in radians. 0.0 uses the unmodified imagery color.
-   *
-   * @type {number|undefined}
-   * @default undefined
-   */
-  this.defaultHue = undefined;
-
-  /**
-   * The default saturation of this provider. 1.0 uses the unmodified imagery color. Less than 1.0 reduces the
-   * saturation while greater than 1.0 increases it.
-   *
-   * @type {number|undefined}
-   * @default undefined
-   */
-  this.defaultSaturation = undefined;
-
-  /**
-   * The default gamma correction to apply to this provider.  1.0 uses the unmodified imagery color.
-   *
-   * @type {number|undefined}
-   * @default undefined
-   */
-  this.defaultGamma = undefined;
-
-  /**
-   * The default texture minification filter to apply to this provider.
-   *
-   * @type {TextureMinificationFilter}
-   * @default undefined
-   */
-  this.defaultMinificationFilter = undefined;
-
-  /**
-   * The default texture magnification filter to apply to this provider.
-   *
-   * @type {TextureMagnificationFilter}
-   * @default undefined
-   */
-  this.defaultMagnificationFilter = undefined;
-
   DeveloperError.throwInstantiationError();
 }
 
@@ -138,6 +52,7 @@ Object.defineProperties(ImageryProvider.prototype, {
    * @memberof ImageryProvider.prototype
    * @type {boolean}
    * @readonly
+   * @deprecated
    */
   ready: {
     get: DeveloperError.throwInstantiationError,
@@ -148,14 +63,14 @@ Object.defineProperties(ImageryProvider.prototype, {
    * @memberof ImageryProvider.prototype
    * @type {Promise<boolean>}
    * @readonly
+   * @deprecated
    */
   readyPromise: {
     get: DeveloperError.throwInstantiationError,
   },
 
   /**
-   * Gets the rectangle, in radians, of the imagery provided by the instance.  This function should
-   * not be called before {@link ImageryProvider#ready} returns true.
+   * Gets the rectangle, in radians, of the imagery provided by the instance.
    * @memberof ImageryProvider.prototype
    * @type {Rectangle}
    * @readonly
@@ -165,8 +80,7 @@ Object.defineProperties(ImageryProvider.prototype, {
   },
 
   /**
-   * Gets the width of each tile, in pixels.  This function should
-   * not be called before {@link ImageryProvider#ready} returns true.
+   * Gets the width of each tile, in pixels.
    * @memberof ImageryProvider.prototype
    * @type {number}
    * @readonly
@@ -176,8 +90,7 @@ Object.defineProperties(ImageryProvider.prototype, {
   },
 
   /**
-   * Gets the height of each tile, in pixels.  This function should
-   * not be called before {@link ImageryProvider#ready} returns true.
+   * Gets the height of each tile, in pixels.
    * @memberof ImageryProvider.prototype
    * @type {number}
    * @readonly
@@ -187,8 +100,7 @@ Object.defineProperties(ImageryProvider.prototype, {
   },
 
   /**
-   * Gets the maximum level-of-detail that can be requested.  This function should
-   * not be called before {@link ImageryProvider#ready} returns true.
+   * Gets the maximum level-of-detail that can be requested.
    * @memberof ImageryProvider.prototype
    * @type {number|undefined}
    * @readonly
@@ -198,8 +110,7 @@ Object.defineProperties(ImageryProvider.prototype, {
   },
 
   /**
-   * Gets the minimum level-of-detail that can be requested.  This function should
-   * not be called before {@link ImageryProvider#ready} returns true. Generally,
+   * Gets the minimum level-of-detail that can be requested.  Generally,
    * a minimum level should only be used when the rectangle of the imagery is small
    * enough that the number of tiles at the minimum level is small.  An imagery
    * provider with more than a few tiles at the minimum level will lead to
@@ -213,8 +124,7 @@ Object.defineProperties(ImageryProvider.prototype, {
   },
 
   /**
-   * Gets the tiling scheme used by the provider.  This function should
-   * not be called before {@link ImageryProvider#ready} returns true.
+   * Gets the tiling scheme used by the provider.
    * @memberof ImageryProvider.prototype
    * @type {TilingScheme}
    * @readonly
@@ -226,8 +136,7 @@ Object.defineProperties(ImageryProvider.prototype, {
   /**
    * Gets the tile discard policy.  If not undefined, the discard policy is responsible
    * for filtering out "missing" tiles via its shouldDiscardImage function.  If this function
-   * returns undefined, no tiles are filtered.  This function should
-   * not be called before {@link ImageryProvider#ready} returns true.
+   * returns undefined, no tiles are filtered.
    * @memberof ImageryProvider.prototype
    * @type {TileDiscardPolicy}
    * @readonly
@@ -237,7 +146,7 @@ Object.defineProperties(ImageryProvider.prototype, {
   },
 
   /**
-   * Gets an event that is raised when the imagery provider encounters an asynchronous error..  By subscribing
+   * Gets an event that is raised when the imagery provider encounters an asynchronous error.  By subscribing
    * to the event, you will be notified of the error and can potentially recover from it.  Event listeners
    * are passed an instance of {@link TileProviderError}.
    * @memberof ImageryProvider.prototype
@@ -250,8 +159,7 @@ Object.defineProperties(ImageryProvider.prototype, {
 
   /**
    * Gets the credit to display when this imagery provider is active.  Typically this is used to credit
-   * the source of the imagery. This function should
-   * not be called before {@link ImageryProvider#ready} returns true.
+   * the source of the imagery.
    * @memberof ImageryProvider.prototype
    * @type {Credit}
    * @readonly
@@ -283,6 +191,122 @@ Object.defineProperties(ImageryProvider.prototype, {
   hasAlphaChannel: {
     get: DeveloperError.throwInstantiationError,
   },
+
+  /**
+   * The default alpha blending value of this provider, with 0.0 representing fully transparent and
+   * 1.0 representing fully opaque.
+   * @memberof ImageryProvider.prototype
+   * @type {Number|undefined}
+   * @deprecated
+   */
+  defaultAlpha: {
+    get: DeveloperError.throwInstantiationError,
+    set: DeveloperError.throwInstantiationError,
+  },
+
+  /**
+   * The default alpha blending value on the night side of the globe of this provider, with 0.0 representing fully transparent and
+   * 1.0 representing fully opaque.
+   * @memberof ImageryProvider.prototype
+   * @type {Number|undefined}
+   * @deprecated
+   */
+  defaultNightAlpha: {
+    get: DeveloperError.throwInstantiationError,
+    set: DeveloperError.throwInstantiationError,
+  },
+
+  /**
+   * The default alpha blending value on the day side of the globe of this provider, with 0.0 representing fully transparent and
+   * 1.0 representing fully opaque.
+   * @memberof ImageryProvider.prototype
+   * @type {Number|undefined}
+   * @deprecated
+   */
+  defaultDayAlpha: {
+    get: DeveloperError.throwInstantiationError,
+    set: DeveloperError.throwInstantiationError,
+  },
+
+  /**
+   * The default brightness of this provider.  1.0 uses the unmodified imagery color.  Less than 1.0
+   * makes the imagery darker while greater than 1.0 makes it brighter.
+   * @memberof ImageryProvider.prototype
+   * @type {Number|undefined}
+   * @deprecated
+   */
+  defaultBrightness: {
+    get: DeveloperError.throwInstantiationError,
+    set: DeveloperError.throwInstantiationError,
+  },
+
+  /**
+   * The default contrast of this provider.  1.0 uses the unmodified imagery color.  Less than 1.0 reduces
+   * the contrast while greater than 1.0 increases it.
+   * @memberof ImageryProvider.prototype
+   * @type {Number|undefined}
+   * @deprecated
+   */
+  defaultContrast: {
+    get: DeveloperError.throwInstantiationError,
+    set: DeveloperError.throwInstantiationError,
+  },
+
+  /**
+   * The default hue of this provider in radians. 0.0 uses the unmodified imagery color.
+   * @memberof ImageryProvider.prototype
+   * @type {Number|undefined}
+   * @deprecated
+   */
+  defaultHue: {
+    get: DeveloperError.throwInstantiationError,
+    set: DeveloperError.throwInstantiationError,
+  },
+
+  /**
+   * The default saturation of this provider. 1.0 uses the unmodified imagery color. Less than 1.0 reduces the
+   * saturation while greater than 1.0 increases it.
+   * @memberof ImageryProvider.prototype
+   * @type {Number|undefined}
+   * @deprecated
+   */
+  defaultSaturation: {
+    get: DeveloperError.throwInstantiationError,
+    set: DeveloperError.throwInstantiationError,
+  },
+
+  /**
+   * The default gamma correction to apply to this provider.  1.0 uses the unmodified imagery color.
+   * @memberof ImageryProvider.prototype
+   * @type {Number|undefined}
+   * @deprecated
+   */
+  defaultGamma: {
+    get: DeveloperError.throwInstantiationError,
+    set: DeveloperError.throwInstantiationError,
+  },
+
+  /**
+   * The default texture minification filter to apply to this provider.
+   * @memberof ImageryProvider.prototype
+   * @type {TextureMinificationFilter}
+   * @deprecated
+   */
+  defaultMinificationFilter: {
+    get: DeveloperError.throwInstantiationError,
+    set: DeveloperError.throwInstantiationError,
+  },
+
+  /**
+   * The default texture magnification filter to apply to this provider.
+   * @memberof ImageryProvider.prototype
+   * @type {TextureMagnificationFilter}
+   * @deprecated
+   */
+  defaultMagnificationFilter: {
+    get: DeveloperError.throwInstantiationError,
+    set: DeveloperError.throwInstantiationError,
+  },
 });
 
 /**
@@ -292,16 +316,13 @@ Object.defineProperties(ImageryProvider.prototype, {
  * @param {number} y The tile Y coordinate.
  * @param {number} level The tile level;
  * @returns {Credit[]} The credits to be displayed when the tile is displayed.
- *
- * @exception {DeveloperError} <code>getTileCredits</code> must not be called before the imagery provider is ready.
  */
 ImageryProvider.prototype.getTileCredits = function (x, y, level) {
   DeveloperError.throwInstantiationError();
 };
 
 /**
- * Requests the image for a given tile.  This function should
- * not be called before {@link ImageryProvider#ready} returns true.
+ * Requests the image for a given tile.
  *
  * @param {number} x The tile X coordinate.
  * @param {number} y The tile Y coordinate.
@@ -309,8 +330,6 @@ ImageryProvider.prototype.getTileCredits = function (x, y, level) {
  * @param {Request} [request] The request object. Intended for internal use only.
  * @returns {Promise<ImageryTypes>|undefined} Returns a promise for the image that will resolve when the image is available, or
  *          undefined if there are too many active requests to the server, and the request should be retried later.
- *
- * @exception {DeveloperError} <code>requestImage</code> must not be called before the imagery provider is ready.
  */
 ImageryProvider.prototype.requestImage = function (x, y, level, request) {
   DeveloperError.throwInstantiationError();
@@ -318,7 +337,7 @@ ImageryProvider.prototype.requestImage = function (x, y, level, request) {
 
 /**
  * Asynchronously determines what features, if any, are located at a given longitude and latitude within
- * a tile.  This function should not be called before {@link ImageryProvider#ready} returns true.
+ * a tile.
  * This function is optional, so it may not exist on all ImageryProviders.
  *
  * @function
@@ -333,7 +352,6 @@ ImageryProvider.prototype.requestImage = function (x, y, level, request) {
  *                   instances.  The array may be empty if no features are found at the given location.
  *                   It may also be undefined if picking is not supported.
  *
- * @exception {DeveloperError} <code>pickFeatures</code> must not be called before the imagery provider is ready.
  */
 ImageryProvider.prototype.pickFeatures = function (
   x,

package/Source/Scene/Implicit3DTileContent.js

@@ -4,6 +4,7 @@ import clone from "../Core/clone.js";
 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 CesiumMath from "../Core/Math.js";
@@ -26,6 +27,7 @@ import parseBoundingVolumeSemantics from "./parseBoundingVolumeSemantics.js";
  * <p>
  * Implements the {@link Cesium3DTileContent} interface.
  * </p>
+ * This object is normally not instantiated directly, use {@link Implicit3DTileContent.fromSubtreeJson}.
  *
  * @alias Implicit3DTileContent
  * @constructor
@@ -42,20 +44,10 @@ import parseBoundingVolumeSemantics from "./parseBoundingVolumeSemantics.js";
  * @private
  * @experimental This feature is using part of the 3D Tiles spec that is not final and is subject to change without Cesium's standard deprecation policy.
  */
-function Implicit3DTileContent(
-  tileset,
-  tile,
-  resource,
-  json,
-  arrayBuffer,
-  byteOffset
-) {
+function Implicit3DTileContent(tileset, tile, resource) {
   //>>includeStart('debug', pragmas.debug);
   Check.defined("tile.implicitTileset", tile.implicitTileset);
   Check.defined("tile.implicitCoordinates", tile.implicitCoordinates);
-  if (defined(json) === defined(arrayBuffer)) {
-    throw new DeveloperError("One of json and arrayBuffer must be defined.");
-  }
   //>>includeEnd('debug');
 
   const implicitTileset = tile.implicitTileset;
@@ -81,7 +73,8 @@ function Implicit3DTileContent(
   );
   this._url = subtreeResource.getUrlComponent(true);
 
-  this._readyPromise = initialize(this, json, arrayBuffer, byteOffset);
+  this._ready = false;
+  this._readyPromise = undefined;
 }
 
 Object.defineProperties(Implicit3DTileContent.prototype, {
@@ -127,8 +120,37 @@ Object.defineProperties(Implicit3DTileContent.prototype, {
     },
   },
 
+  /**
+   * Returns true when the tile's content is ready to render; otherwise false
+   *
+   * @memberof Implicit3DTileContent.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 Implicit3DTileContent.prototype
+   *
+   * @type {Promise<Implicit3DTileContent>}
+   * @readonly
+   * @deprecated
+   * @private
+   */
   readyPromise: {
     get: function () {
+      deprecationWarning(
+        "Implicit3DTileContent.readyPromise",
+        "Implicit3DTileContent.readyPromise was deprecated in CesiumJS 1.104. It will be removed in 1.107. Wait for Implicit3DTileContent.ready to return true instead."
+      );
       return this._readyPromise;
     },
   },
@@ -188,33 +210,60 @@ Object.defineProperties(Implicit3DTileContent.prototype, {
  * Initialize the implicit content by parsing the subtree resource and setting
  * up a promise chain to expand the immediate subtree.
  *
- * @param {Implicit3DTileContent} content The implicit content
+ * @param {Cesium3DTileset} tileset The tileset this content belongs to
+ * @param {Cesium3DTile} tile The tile this content belongs to.
+ * @param {Resource} resource The resource for the tileset
  * @param {object} [json] The JSON containing the subtree. Mutually exclusive with arrayBuffer.
  * @param {ArrayBuffer} [arrayBuffer] The ArrayBuffer containing a subtree binary. Mutually exclusive with json.
  * @param {number} [byteOffset=0] The byte offset into the arrayBuffer
+ * @return {Promise<Implicit3DTileContent>}
+ *
+ * @exception {DeveloperError} One of json and arrayBuffer must be defined.
+ *
  * @private
  */
-function initialize(content, json, arrayBuffer, byteOffset) {
+Implicit3DTileContent.fromSubtreeJson = async function (
+  tileset,
+  tile,
+  resource,
+  json,
+  arrayBuffer,
+  byteOffset
+) {
+  //>>includeStart('debug', pragmas.debug);
+  Check.defined("tile.implicitTileset", tile.implicitTileset);
+  Check.defined("tile.implicitCoordinates", tile.implicitCoordinates);
+  if (defined(json) === defined(arrayBuffer)) {
+    throw new DeveloperError("One of json and arrayBuffer must be defined.");
+  }
+  //>>includeEnd('debug');
+
   byteOffset = defaultValue(byteOffset, 0);
   let uint8Array;
   if (defined(arrayBuffer)) {
     uint8Array = new Uint8Array(arrayBuffer, byteOffset);
   }
 
-  const subtree = new ImplicitSubtree(
-    content._resource,
+  const implicitTileset = tile.implicitTileset;
+  const implicitCoordinates = tile.implicitCoordinates;
+
+  const subtree = await ImplicitSubtree.fromSubtreeJson(
+    resource,
     json,
     uint8Array,
-    content._implicitTileset,
-    content._implicitCoordinates
+    implicitTileset,
+    implicitCoordinates
   );
 
+  const content = new Implicit3DTileContent(tileset, tile, resource);
+
   content._implicitSubtree = subtree;
-  return subtree.readyPromise.then(function () {
-    expandSubtree(content, subtree);
-    return content;
-  });
-}
+  expandSubtree(content, subtree);
+  content._ready = true;
+  content._readyPromise = Promise.resolve(content);
+
+  return content;
+};
 
 /**
  * Expand a single subtree placeholder tile. This transcodes the subtree into