@cesium/engine 14.0.0 → 16.0.0

package/Source/Scene/BillboardLoadState.js

@@ -0,0 +1,44 @@
+/**
+ * Defines loading state of a image as any request is resolved and the WebGL resources are updated.
+ * @private
+ * @enum {number}
+ */
+const BillboardLoadState = Object.freeze({
+  /**
+   * There is no image data to load.
+   * @private
+   * @type {number}
+   * @constant
+   */
+  NONE: 0,
+  /**
+   * Image data is in the process of downloading, or WebGL resources are being updated.
+   * @private
+   * @type {number}
+   * @constant
+   */
+  LOADING: 2,
+  /**
+   * The image data has been downloaded and the WebGL resources have been created. It is ready for rendering.
+   * @private
+   * @type {number}
+   * @constant
+   */
+  LOADED: 3,
+  /**
+   * There was an error while downloading an image or updating the WebGL resources.
+   * @private
+   * @type {number}
+   * @constant
+   */
+  ERROR: 4,
+  /**
+   * Updating the WebGL resources failed, due to the resource being destroyed or another error.
+   * @private
+   * @type {number}
+   * @constant
+   */
+  FAILED: 5,
+});
+
+export default BillboardLoadState;

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/BingMapsImageryProvider.js

@@ -1,7 +1,7 @@
 import buildModuleUrl from "../Core/buildModuleUrl.js";
 import Check from "../Core/Check.js";
 import Credit from "../Core/Credit.js";
-import defaultValue from "../Core/defaultValue.js";
+import Frozen from "../Core/Frozen.js";
 import defined from "../Core/defined.js";
 import Event from "../Core/Event.js";
 import CesiumMath from "../Core/Math.js";
@@ -205,7 +205,7 @@ async function requestMetadata(
  * @see {@link http://www.w3.org/TR/cors/|Cross-Origin Resource Sharing}
  */
 function BingMapsImageryProvider(options) {
-  options = defaultValue(options, defaultValue.EMPTY_OBJECT);
+  options = options ?? Frozen.EMPTY_OBJECT;
 
   this._defaultAlpha = undefined;
   this._defaultNightAlpha = undefined;
@@ -218,9 +218,9 @@ function BingMapsImageryProvider(options) {
   this._defaultMinificationFilter = undefined;
   this._defaultMagnificationFilter = undefined;
 
-  this._mapStyle = defaultValue(options.mapStyle, BingMapsStyle.AERIAL);
+  this._mapStyle = options.mapStyle ?? BingMapsStyle.AERIAL;
   this._mapLayer = options.mapLayer;
-  this._culture = defaultValue(options.culture, "");
+  this._culture = options.culture ?? "";
   this._key = options.key;
 
   this._tileDiscardPolicy = options.tileDiscardPolicy;
@@ -471,7 +471,7 @@ Object.defineProperties(BingMapsImageryProvider.prototype, {
  * @exception {RuntimeError} metadata does not specify one resource in resourceSets
  */
 BingMapsImageryProvider.fromUrl = async function (url, options) {
-  options = defaultValue(options, defaultValue.EMPTY_OBJECT);
+  options = options ?? Frozen.EMPTY_OBJECT;
 
   //>>includeStart('debug', pragmas.debug);
   Check.defined("url", url);
@@ -495,7 +495,7 @@ BingMapsImageryProvider.fromUrl = async function (url, options) {
     tileProtocol = documentProtocol === "http:" ? "http" : "https";
   }
 
-  const mapStyle = defaultValue(options.mapStyle, BingMapsStyle.AERIAL);
+  const mapStyle = options.mapStyle ?? BingMapsStyle.AERIAL;
   const resource = Resource.createIfNeeded(url);
   resource.appendForwardSlash();
 

package/Source/Scene/BoxEmitter.js

@@ -1,6 +1,5 @@
 import Cartesian3 from "../Core/Cartesian3.js";
 import Check from "../Core/Check.js";
-import defaultValue from "../Core/defaultValue.js";
 import CesiumMath from "../Core/Math.js";
 
 const defaultDimensions = new Cartesian3(1.0, 1.0, 1.0);
@@ -15,7 +14,7 @@ const defaultDimensions = new Cartesian3(1.0, 1.0, 1.0);
  * @param {Cartesian3} dimensions The width, height and depth dimensions of the box.
  */
 function BoxEmitter(dimensions) {
-  dimensions = defaultValue(dimensions, defaultDimensions);
+  dimensions = dimensions ?? defaultDimensions;
 
   //>>includeStart('debug', pragmas.debug);
   Check.defined("dimensions", dimensions);

package/Source/Scene/BufferLoader.js

@@ -1,4 +1,4 @@
-import defaultValue from "../Core/defaultValue.js";
+import Frozen from "../Core/Frozen.js";
 import defined from "../Core/defined.js";
 import DeveloperError from "../Core/DeveloperError.js";
 import ResourceLoader from "./ResourceLoader.js";
@@ -24,7 +24,7 @@ import ResourceLoaderState from "./ResourceLoaderState.js";
  * @private
  */
 function BufferLoader(options) {
-  options = defaultValue(options, defaultValue.EMPTY_OBJECT);
+  options = options ?? Frozen.EMPTY_OBJECT;
   const typedArray = options.typedArray;
   const resource = options.resource;
   const cacheKey = options.cacheKey;