@cesium/engine 13.1.0 → 15.0.0

package/Source/Scene/BillboardTexture.js

@@ -0,0 +1,348 @@
+import Check from "../Core/Check.js";
+import defined from "../Core/defined.js";
+import BillboardLoadState from "./BillboardLoadState.js";
+
+/**
+ * Tracks a reference to an image and it's loading state, as used in a BillboardCollection and stored in a texture atlas.
+ * @constructor
+ * @private
+ * @see BillboardCollection
+ * @see Billboard#image
+ * @alias BillboardTexture
+ * @param {BillboardCollection} billboardCollection The associated billboard collecion.
+ */
+function BillboardTexture(billboardCollection) {
+  //>>includeStart('debug', pragmas.debug);
+  Check.defined("billboardCollection", billboardCollection);
+  //>>includeEnd('debug');
+
+  this._billboardCollection = billboardCollection;
+
+  this._id = undefined;
+  this._loadState = BillboardLoadState.NONE;
+  this._loadError = undefined;
+
+  this._index = -1;
+  this._width = undefined;
+  this._height = undefined;
+
+  this._hasSubregion = false;
+
+  /**
+   * Used by billboardCollection to track whcih billboards to update.
+   * @type {boolean}
+   * @private
+   */
+  this.dirty = false;
+}
+
+Object.defineProperties(BillboardTexture.prototype, {
+  /**
+   * If defined, this error was encountered during the loading process.
+   * @memberof BillboardTexture.prototype
+   * @type {Error|undefined}
+   * @readonly
+   * @private
+   */
+  loadError: {
+    get: function () {
+      return this._loadError;
+    },
+  },
+
+  /**
+   * The current status of the image load. When <code>BillboardLoadState.LOADED</code>, this billboard is ready to render, i.e., the image
+   * has been downloaded and the WebGL resources are created.
+   * @memberof BillboardTexture.prototype
+   * @type {BillboardLoadState}
+   * @readonly
+   * @default BillboardLoadState.NONE
+   * @private
+   */
+  loadState: {
+    get: function () {
+      return this._loadState;
+    },
+  },
+
+  /**
+   * When <code>true</code>, this texture is ready to render, i.e., the image
+   * has been downloaded and the WebGL resources are created.
+   * @memberof BillboardTexture.prototype
+   * @type {boolean}
+   * @readonly
+   * @default false
+   * @private
+   */
+  ready: {
+    get: function () {
+      return this._loadState === BillboardLoadState.LOADED;
+    },
+  },
+
+  /**
+   * Returns <code>true</code> if there is image data associated with this instance.
+   * @memberof BillboardTexture.prototype
+   * @type {boolean}
+   * @readonly
+   * @private
+   */
+  hasImage: {
+    get: function () {
+      return this._loadState !== BillboardLoadState.NONE;
+    },
+  },
+
+  /**
+   * A unique identifier for the image, or undefined if no image data has been associated with this instance.
+   * @memberof BillboardTexture.prototype
+   * @type {string|undefined}
+   * @readonly
+   * @private
+   */
+  id: {
+    get: function () {
+      return this._id;
+    },
+  },
+
+  /**
+   * The width of the associated image. Before the instance is <code>ready</code>, this will be <code>undefined</code>.
+   * @memberof BillboardTexture.prototype
+   * @type {number|undefined}
+   * @readonly
+   * @private
+   */
+  width: {
+    get: function () {
+      return this._width;
+    },
+  },
+
+  /**
+   * The height of the associated image. Before the instance is <code>ready</code>, this will be <code>undefined</code>.
+   * @memberof BillboardTexture.prototype
+   * @type {number|undefined}
+   * @readonly
+   * @private
+   */
+  height: {
+    get: function () {
+      return this._height;
+    },
+  },
+});
+
+/**
+ * Releases reference to any associated image data.
+ * @private
+ */
+BillboardTexture.prototype.unload = async function () {
+  if (this._loadState === BillboardLoadState.NONE) {
+    return;
+  }
+
+  this._id = undefined;
+  this._loadError = undefined;
+  this._loadState = BillboardLoadState.NONE;
+
+  this._index = -1;
+  this._width = undefined;
+  this._height = undefined;
+
+  this.dirty = true;
+};
+
+/**
+ * Starts loading an image into the texture atlas.
+ * @see {TextureAtlas#addImage}
+ * @private
+ * @param {string} id An identifier to detect whether the image already exists in the atlas.
+ * @param {HTMLImageElement|HTMLCanvasElement|string|Resource|Promise|TextureAtlas.CreateImageCallback} image An image or canvas to add to the texture atlas,
+ *        or a URL to an Image, or a Promise for an image, or a function that creates an image.
+ */
+BillboardTexture.prototype.loadImage = async function (id, image) {
+  if (this._id === id) {
+    // This image has already been loaded
+    return;
+  }
+
+  const collection = this._billboardCollection;
+  const cache = collection.billboardTextureCache;
+  let billboardTexture = cache.get(id);
+  if (
+    (defined(billboardTexture) &&
+      image.loadState === BillboardLoadState.LOADING) ||
+    image.loadState === BillboardLoadState.LOADED
+  ) {
+    // Use the cached texture if it is in progress or successful.
+    BillboardTexture.clone(billboardTexture, this);
+    return;
+  }
+  // Otherwise, load if not yet assigned an image, and try the load again if anything failed during the last billboard creation
+  if (!defined(billboardTexture)) {
+    billboardTexture = new BillboardTexture(collection);
+    cache.set(id, billboardTexture);
+  }
+
+  billboardTexture._id = this._id = id;
+  billboardTexture._loadState = this._loadState = BillboardLoadState.LOADING;
+  billboardTexture._loadError = this._loadError = undefined;
+
+  let index;
+  const atlas = this._billboardCollection.textureAtlas;
+  try {
+    index = await atlas.addImage(id, image);
+  } catch (error) {
+    // There was an error loading the image
+    billboardTexture._loadState = BillboardLoadState.ERROR;
+    billboardTexture._loadError = error;
+
+    if (this._id !== id) {
+      // Another load was initiated and resolved resolved before this one. This operation is cancelled.
+      return;
+    }
+
+    this._loadState = BillboardLoadState.ERROR;
+    this._loadError = error;
+    return;
+  }
+
+  if (!defined(index) || index === -1) {
+    // Resources destroyed or otherwise
+    billboardTexture._loadState = BillboardLoadState.FAILED;
+    billboardTexture._index = -1;
+
+    if (this._id !== id) {
+      // Another load was initiated and resolved resolved before this one. This operation is cancelled.
+      return;
+    }
+
+    this._loadState = BillboardLoadState.FAILED;
+    this._index = -1;
+
+    return;
+  }
+
+  billboardTexture._index = index;
+  billboardTexture._loadState = BillboardLoadState.LOADED;
+
+  const rectangle = atlas.rectangles[index];
+  billboardTexture._width = rectangle.width;
+  billboardTexture._height = rectangle.height;
+
+  if (this._id !== id) {
+    // Another load was initiated and resolved resolved before this one. This operation is cancelled.
+    return;
+  }
+
+  this._index = index;
+  this._loadState = BillboardLoadState.LOADED;
+  this._width = rectangle.width;
+  this._height = rectangle.height;
+
+  this.dirty = true;
+};
+
+/**
+ * Track a reference to a sub-region of an existing image.
+ * @see {TextureAtlas#addImageSubRegion}
+ * @private
+ * @param {string} id An identifier to detect whether the image already exists in the atlas.
+ * @param {BoundingRectangle} subRegion An {@link BoundingRectangle} defining a region of an existing image, measured in pixels from the bottom-left of the image.
+ */
+BillboardTexture.prototype.addImageSubRegion = async function (id, subRegion) {
+  this._id = id;
+  this._loadState = BillboardLoadState.LOADING;
+  this._loadError = undefined;
+  this._hasSubregion = true;
+
+  let index;
+  const atlas = this._billboardCollection.textureAtlas;
+  try {
+    index = await atlas.addImageSubRegion(id, subRegion);
+  } catch (error) {
+    // There was an error loading the referenced image
+    this._loadState = BillboardLoadState.ERROR;
+    this._loadError = error;
+    return;
+  }
+
+  if (!defined(index) || index === -1) {
+    this._loadState = BillboardLoadState.FAILED;
+    this._index = -1;
+    this._width = undefined;
+    this._height = undefined;
+    return;
+  }
+
+  this._width = subRegion.width;
+  this._height = subRegion.height;
+
+  this._index = index;
+  this._loadState = BillboardLoadState.LOADED;
+
+  this.dirty = true;
+};
+
+/**
+ * Get the texture coordinates for reading the loaded texture in shaders.
+ * @private
+ * @param {BoundingRectangle} [result] The modified result parameter or a new BoundingRectangle instance if one was not provided.
+ * @return {BoundingRectangle} The modified result parameter or a new BoundingRectangle instance if one was not provided.
+ */
+BillboardTexture.prototype.computeTextureCoordinates = function (result) {
+  const atlas = this._billboardCollection.textureAtlas;
+  return atlas.computeTextureCoordinates(this._index, result);
+};
+
+/**
+ * Clones an existing billboard texture, inlcuding any in-flight tracking, into the target billboard texture.
+ * @param {BillboardTexture} billboardTexture
+ * @param {BillboardTexture} target
+ * @returns {BillboardTexture} target
+ */
+BillboardTexture.clone = function (billboardTexture, target) {
+  target._id = billboardTexture._id;
+  target._loadState = billboardTexture._loadState;
+  target._loadError = undefined;
+  target._index = billboardTexture._index;
+  target._width = billboardTexture._width;
+  target._height = billboardTexture._height;
+  target._hasSubregion = billboardTexture._hasSubregion;
+
+  if (billboardTexture.ready) {
+    target.dirty = true;
+    return;
+  }
+
+  const completeLoad = async () => {
+    const id = billboardTexture._id;
+    const atlas = billboardTexture._billboardCollection.textureAtlas;
+    await atlas._indexPromiseById.get(id);
+
+    // Any errors should have already been handled
+    if (target._id !== id) {
+      // Another load was initiated and resolved resolved before this one. This operation is cancelled.
+      return;
+    }
+
+    if (billboardTexture._hasSubregion) {
+      // Subregions must wait an additional frame to be ready
+      await Promise.resolve();
+    }
+
+    target._id = id;
+    target._loadState = billboardTexture._loadState;
+    target._loadError = billboardTexture._loadError;
+    target._index = billboardTexture._index;
+    target._width = billboardTexture._width;
+    target._height = billboardTexture._height;
+    target.dirty = true;
+  };
+
+  completeLoad();
+  return target;
+};
+
+export default BillboardTexture;

package/Source/Scene/Camera.js

@@ -3270,7 +3270,7 @@ const newOptions = {
 
 /**
  * Cancels the current camera flight and leaves the camera at its current location.
- * If no flight is in progress, this this function does nothing.
+ * If no flight is in progress, this function does nothing.
  */
 Camera.prototype.cancelFlight = function () {
   if (defined(this._currentFlight)) {
@@ -3281,7 +3281,7 @@ Camera.prototype.cancelFlight = function () {
 
 /**
  * Completes the current camera flight and moves the camera immediately to its final destination.
- * If no flight is in progress, this this function does nothing.
+ * If no flight is in progress, this function does nothing.
  */
 Camera.prototype.completeFlight = function () {
   if (defined(this._currentFlight)) {

package/Source/Scene/Cesium3DTile.js

@@ -319,6 +319,24 @@ function Cesium3DTile(tileset, baseResource, header, parent) {
    */
   this.hasImplicitContent = false;
 
+  /**
+   * Determines whether the tile has renderable content.
+   *
+   * The loading starts with the assumption that the tile does have
+   * renderable content, if the content is not empty.<br>
+   * <br>
+   * This turns <code>false</code> only when the tile content is loaded
+   * and turns out to be a single content that points to an external
+   * tileset or implicit content
+   * </p>
+   *
+   * @type {boolean}
+   * @readonly
+   *
+   * @private
+   */
+  this.hasRenderableContent = !hasEmptyContent;
+
   /**
    * When <code>true</code>, the tile contains content metadata from implicit tiling. This flag is set
    * for tiles transcoded by <code>Implicit3DTileContent</code>.
@@ -653,27 +671,6 @@ Object.defineProperties(Cesium3DTile.prototype, {
     },
   },
 
-  /**
-   * Determines if the tile's content is renderable. <code>false</code> if the
-   * tile has empty content or if it points to an external tileset or implicit content
-   *
-   * @memberof Cesium3DTile.prototype
-   *
-   * @type {boolean}
-   * @readonly
-   *
-   * @private
-   */
-  hasRenderableContent: {
-    get: function () {
-      return (
-        !this.hasEmptyContent &&
-        !this.hasTilesetContent &&
-        !this.hasImplicitContent
-      );
-    },
-  },
-
   /**
    * Determines if the tile has available content to render.  <code>true</code> if the tile's
    * content is ready or if it has expired content that renders while new content loads; otherwise,
@@ -1346,10 +1343,12 @@ async function makeContent(tile, arrayBuffer) {
     preprocessed.contentType === Cesium3DTileContentType.IMPLICIT_SUBTREE_JSON
   ) {
     tile.hasImplicitContent = true;
+    tile.hasRenderableContent = false;
   }
 
   if (preprocessed.contentType === Cesium3DTileContentType.EXTERNAL_TILESET) {
     tile.hasTilesetContent = true;
+    tile.hasRenderableContent = false;
   }
 
   let content;
@@ -1729,28 +1728,57 @@ function createBoxFromTransformedRegion(
 }
 
 /**
+ * Creates a TileBoundingVolume from the given region and transform
+ * information.
+ *
+ * This may either be a TileBoundingRegion or a TileOrientedBoundingBox.
+ *
+ * If the given transform is the initial transform, then this will return
+ * a TileBoundingRegion. This will either be the given result parameter,
+ * or a new TileBoundingRegion, if the given result parameter was not
+ * a TileBoundingRegion.
+ *
+ * If the given transform deviates from the initial transform, then this
+ * will return a TileOrientedBoundingBox that was computed by applying
+ * the given transform to the given region. This will either be the
+ * given result parameter, or a new TileOrientedBoundingBox, if the given
+ * result parameter was not a TileOrientedBoundingBox
+ *
  * @private
- * @param {Array} region An array of six numbers that define a bounding geographic region in EPSG:4979 coordinates with the order [west, south, east, north, minimum height, maximum height]
- * @param {Matrix4} transform
- * @param {Matrix4} initialTransform
- * @param {TileBoundingVolume} [result]
- * @returns {TileBoundingVolume}
+ * @param {Array} region An array of six numbers that define a bounding
+ * geographic region in EPSG:4979 coordinates with the order
+ * [west, south, east, north, minimum height, maximum height]
+ * @param {Matrix4} transform The current computedTransform of the tile,
+ * which includes the parent transform (which, in turn, includes the
+ * modelMatrix of the containing tileset)
+ * @param {Matrix4} initialTransform The initial transform of the tile,
+ * before any changes to the modelMatrix of the containing tileset
+ * @param {TileBoundingVolume} [result] An optional result.
+ * @returns {TileBoundingVolume} The resulting bounding volume
  */
 function createRegion(region, transform, initialTransform, result) {
   if (
     !Matrix4.equalsEpsilon(transform, initialTransform, CesiumMath.EPSILON8)
   ) {
+    if (result instanceof TileOrientedBoundingBox) {
+      return createBoxFromTransformedRegion(
+        region,
+        transform,
+        initialTransform,
+        result,
+      );
+    }
     return createBoxFromTransformedRegion(
       region,
       transform,
       initialTransform,
-      result,
+      undefined,
     );
   }
 
   const rectangleRegion = Rectangle.unpack(region, 0, scratchRectangle);
 
-  if (defined(result)) {
+  if (result instanceof TileBoundingRegion) {
     result.rectangle = Rectangle.clone(rectangleRegion, result.rectangle);
     result.minimumHeight = region[4];
     result.maximumHeight = region[5];