@cesium/engine 14.0.0 → 16.0.0

package/Source/Scene/Billboard.js

@@ -6,7 +6,7 @@ import Cartographic from "../Core/Cartographic.js";
 import Check from "../Core/Check.js";
 import Color from "../Core/Color.js";
 import createGuid from "../Core/createGuid.js";
-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 DistanceDisplayCondition from "../Core/DistanceDisplayCondition.js";
@@ -14,6 +14,7 @@ import Ellipsoid from "../Core/Ellipsoid.js";
 import Matrix4 from "../Core/Matrix4.js";
 import NearFarScalar from "../Core/NearFarScalar.js";
 import Resource from "../Core/Resource.js";
+import BillboardTexture from "./BillboardTexture.js";
 import HeightReference, {
   isHeightReferenceRelative,
 } from "./HeightReference.js";
@@ -93,7 +94,7 @@ import SplitDirection from "./SplitDirection.js";
  * @demo {@link https://sandcastle.cesium.com/index.html?src=Billboards.html|Cesium Sandcastle Billboard Demo}
  */
 function Billboard(options, billboardCollection) {
-  options = defaultValue(options, defaultValue.EMPTY_OBJECT);
+  options = options ?? Frozen.EMPTY_OBJECT;
 
   //>>includeStart('debug', pragmas.debug);
   if (
@@ -155,59 +156,39 @@ function Billboard(options, billboardCollection) {
     );
   }
 
-  this._show = defaultValue(options.show, true);
-  this._position = Cartesian3.clone(
-    defaultValue(options.position, Cartesian3.ZERO),
-  );
+  this._show = options.show ?? true;
+  this._position = Cartesian3.clone(options.position ?? Cartesian3.ZERO);
   this._actualPosition = Cartesian3.clone(this._position); // For columbus view and 2D
-  this._pixelOffset = Cartesian2.clone(
-    defaultValue(options.pixelOffset, Cartesian2.ZERO),
-  );
+  this._pixelOffset = Cartesian2.clone(options.pixelOffset ?? Cartesian2.ZERO);
   this._translate = new Cartesian2(0.0, 0.0); // used by labels for glyph vertex translation
-  this._eyeOffset = Cartesian3.clone(
-    defaultValue(options.eyeOffset, Cartesian3.ZERO),
-  );
-  this._heightReference = defaultValue(
-    options.heightReference,
-    HeightReference.NONE,
-  );
-  this._verticalOrigin = defaultValue(
-    options.verticalOrigin,
-    VerticalOrigin.CENTER,
-  );
-  this._horizontalOrigin = defaultValue(
-    options.horizontalOrigin,
-    HorizontalOrigin.CENTER,
-  );
-  this._scale = defaultValue(options.scale, 1.0);
-  this._color = Color.clone(defaultValue(options.color, Color.WHITE));
-  this._rotation = defaultValue(options.rotation, 0.0);
-  this._alignedAxis = Cartesian3.clone(
-    defaultValue(options.alignedAxis, Cartesian3.ZERO),
-  );
+  this._eyeOffset = Cartesian3.clone(options.eyeOffset ?? Cartesian3.ZERO);
+  this._heightReference = options.heightReference ?? HeightReference.NONE;
+  this._verticalOrigin = options.verticalOrigin ?? VerticalOrigin.CENTER;
+  this._horizontalOrigin = options.horizontalOrigin ?? HorizontalOrigin.CENTER;
+  this._scale = options.scale ?? 1.0;
+  this._color = Color.clone(options.color ?? Color.WHITE);
+  this._rotation = options.rotation ?? 0.0;
+  this._alignedAxis = Cartesian3.clone(options.alignedAxis ?? Cartesian3.ZERO);
   this._width = options.width;
   this._height = options.height;
   this._scaleByDistance = scaleByDistance;
   this._translucencyByDistance = translucencyByDistance;
   this._pixelOffsetScaleByDistance = pixelOffsetScaleByDistance;
-  this._sizeInMeters = defaultValue(options.sizeInMeters, false);
+  this._sizeInMeters = options.sizeInMeters ?? false;
   this._distanceDisplayCondition = distanceDisplayCondition;
   this._disableDepthTestDistance = options.disableDepthTestDistance;
   this._id = options.id;
-  this._collection = defaultValue(options.collection, billboardCollection);
+  this._collection = options.collection ?? billboardCollection; // Used only for pick ids
 
   this._pickId = undefined;
-  this._pickPrimitive = defaultValue(options._pickPrimitive, this);
+  this._pickPrimitive = options._pickPrimitive ?? this;
+
   this._billboardCollection = billboardCollection;
   this._dirty = false;
-  this._index = -1; //Used only by BillboardCollection
+  this._index = -1; // Used only by BillboardCollection
   this._batchIndex = undefined; // Used only by Vector3DTilePoints and BillboardCollection
 
-  this._imageIndex = -1;
-  this._imageIndexPromise = undefined;
-  this._imageId = undefined;
-  this._image = undefined;
-  this._imageSubRegion = undefined;
+  this._imageTexture = new BillboardTexture(billboardCollection);
   this._imageWidth = undefined;
   this._imageHeight = undefined;
 
@@ -228,17 +209,11 @@ function Billboard(options, billboardCollection) {
       }
     }
 
-    this._imageId = imageId;
-    this._image = image;
+    this._imageTexture.loadImage(imageId, image);
   }
 
   if (defined(options.imageSubRegion)) {
-    this._imageId = imageId;
-    this._imageSubRegion = options.imageSubRegion;
-  }
-
-  if (defined(this._billboardCollection._textureAtlas)) {
-    this._loadImage();
+    this._imageTexture.addImageSubRegion(imageId, options.imageSubRegion);
   }
 
   this._actualClampedPosition = undefined;
@@ -246,17 +221,12 @@ function Billboard(options, billboardCollection) {
   this._mode = SceneMode.SCENE3D;
 
   this._clusterShow = true;
-  this._outlineColor = Color.clone(
-    defaultValue(options.outlineColor, Color.BLACK),
-  );
-  this._outlineWidth = defaultValue(options.outlineWidth, 0.0);
+  this._outlineColor = Color.clone(options.outlineColor ?? Color.BLACK);
+  this._outlineWidth = options.outlineWidth ?? 0.0;
 
   this._updateClamping();
 
-  this._splitDirection = defaultValue(
-    options.splitDirection,
-    SplitDirection.NONE,
-  );
+  this._splitDirection = options.splitDirection ?? SplitDirection.NONE;
 }
 
 const SHOW_INDEX = (Billboard.SHOW_INDEX = 0);
@@ -775,18 +745,19 @@ Object.defineProperties(Billboard.prototype, {
   /**
    * Gets or sets a width for the billboard. If undefined, the image width will be used.
    * @memberof Billboard.prototype
-   * @type {number}
+   * @type {number|undefined}
    */
   width: {
     get: function () {
-      return defaultValue(this._width, this._imageWidth);
+      return this._width ?? this._imageTexture.width;
     },
     set: function (value) {
       //>>includeStart('debug', pragmas.debug);
       if (defined(value)) {
-        Check.typeOf.number("value", value);
+        Check.typeOf.number("width", value);
       }
       //>>includeEnd('debug');
+
       if (this._width !== value) {
         this._width = value;
         makeDirty(this, IMAGE_INDEX_INDEX);
@@ -797,18 +768,19 @@ Object.defineProperties(Billboard.prototype, {
   /**
    * Gets or sets a height for the billboard. If undefined, the image height will be used.
    * @memberof Billboard.prototype
-   * @type {number}
+   * @type {number|undefined}
    */
   height: {
     get: function () {
-      return defaultValue(this._height, this._imageHeight);
+      return this._height ?? this._imageTexture.height;
     },
     set: function (value) {
       //>>includeStart('debug', pragmas.debug);
       if (defined(value)) {
-        Check.typeOf.number("value", value);
+        Check.typeOf.number("height", value);
       }
       //>>includeEnd('debug');
+
       if (this._height !== value) {
         this._height = value;
         makeDirty(this, IMAGE_INDEX_INDEX);
@@ -964,42 +936,69 @@ Object.defineProperties(Billboard.prototype, {
    */
   image: {
     get: function () {
-      return this._imageId;
+      return this._imageTexture.id;
     },
     set: function (value) {
       if (!defined(value)) {
-        this._imageIndex = -1;
-        this._imageSubRegion = undefined;
-        this._imageId = undefined;
-        this._image = undefined;
-        this._imageIndexPromise = undefined;
-        makeDirty(this, IMAGE_INDEX_INDEX);
-      } else if (typeof value === "string") {
-        this.setImage(value, value);
+        this._imageTexture.unload();
+        return;
+      }
+
+      let id;
+      if (typeof value === "string") {
+        id = value;
       } else if (value instanceof Resource) {
-        this.setImage(value.url, value);
+        id = value._url;
       } else if (defined(value.src)) {
-        this.setImage(value.src, value);
+        id = value.src;
       } else {
-        this.setImage(createGuid(), value);
+        id = createGuid();
       }
+
+      this._imageTexture.loadImage(id, value);
     },
   },
 
   /**
    * When <code>true</code>, this billboard is ready to render, i.e., the image
    * has been downloaded and the WebGL resources are created.
-   *
    * @memberof Billboard.prototype
-   *
    * @type {boolean}
    * @readonly
-   *
    * @default false
    */
   ready: {
     get: function () {
-      return this._imageIndex !== -1;
+      return this._imageTexture.ready;
+    },
+  },
+
+  /**
+   * If defined, this error was encountered during the loading process.
+   * @memberof Billboard.prototype
+   * @type {Error|undefined}
+   * @readonly
+   * @private
+   */
+  loadError: {
+    get: function () {
+      return this._imageTexture.loadError;
+    },
+  },
+
+  /**
+   * Used by <code>billboardCollection</code> to track which billboards to update based on image load status.
+   * @memberof Billboard.prototype
+   * @type {boolean}
+   * @private
+   * @default false
+   */
+  textureDirty: {
+    get: function () {
+      return this._imageTexture.dirty;
+    },
+    set: function (value) {
+      this._imageTexture.dirty = value;
     },
   },
 
@@ -1120,8 +1119,7 @@ Billboard.prototype._updateClamping = function () {
 
 const scratchCartographic = new Cartographic();
 Billboard._updateClamping = function (collection, owner) {
-  const scene = collection._scene;
-  if (!defined(scene)) {
+  if (!defined(collection) || !defined(collection._scene)) {
     //>>includeStart('debug', pragmas.debug);
     if (owner._heightReference !== HeightReference.NONE) {
       throw new DeveloperError(
@@ -1131,11 +1129,10 @@ Billboard._updateClamping = function (collection, owner) {
     //>>includeEnd('debug');
     return;
   }
-
-  const ellipsoid = defaultValue(scene.ellipsoid, Ellipsoid.default);
+  const scene = collection._scene;
+  const ellipsoid = scene.ellipsoid ?? Ellipsoid.default;
 
   const mode = scene.frameState.mode;
-
   const modeChanged = mode !== owner._mode;
   owner._mode = mode;
 
@@ -1201,68 +1198,14 @@ Billboard._updateClamping = function (collection, owner) {
   updateFunction(scratchCartographic);
 };
 
-Billboard.prototype._loadImage = function () {
-  const atlas = this._billboardCollection._textureAtlas;
-
-  const imageId = this._imageId;
-  const image = this._image;
-  const imageSubRegion = this._imageSubRegion;
-  let imageIndexPromise;
-
-  const that = this;
-  function completeImageLoad(index) {
-    if (
-      that._imageId !== imageId ||
-      that._image !== image ||
-      !BoundingRectangle.equals(that._imageSubRegion, imageSubRegion)
-    ) {
-      // another load occurred before this one finished, ignore the index
-      return;
-    }
-
-    // fill in imageWidth and imageHeight
-    const textureCoordinates = atlas.textureCoordinates[index];
-    that._imageWidth = atlas.texture.width * textureCoordinates.width;
-    that._imageHeight = atlas.texture.height * textureCoordinates.height;
-
-    that._imageIndex = index;
-    that._ready = true;
-    that._image = undefined;
-    that._imageIndexPromise = undefined;
-    makeDirty(that, IMAGE_INDEX_INDEX);
-
-    const scene = that._billboardCollection._scene;
-    if (!defined(scene)) {
-      return;
-    }
-    // Request a new render in request render mode
-    scene.frameState.afterRender.push(() => true);
-  }
-
-  if (defined(image)) {
-    imageIndexPromise = atlas.addImage(imageId, image);
-  }
-  if (defined(imageSubRegion)) {
-    imageIndexPromise = atlas.addSubRegion(imageId, imageSubRegion);
-  }
-
-  this._imageIndexPromise = imageIndexPromise;
-
-  if (!defined(imageIndexPromise)) {
-    return;
-  }
-
-  // If the promise has already successfully resolved, we can return immediately without waiting a frame
-  const index = atlas.getImageIndex(imageId);
-  if (defined(index) && !defined(imageSubRegion)) {
-    completeImageLoad(index);
-    return;
-  }
-
-  imageIndexPromise.then(completeImageLoad).catch(function (error) {
-    console.error(`Error loading image for billboard: ${error}`);
-    that._imageIndexPromise = undefined;
-  });
+/**
+ * Get the texture coordinates for reading the loaded texture in shaders.
+ * @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.
+ * @private
+ */
+Billboard.prototype.computeTextureCoordinates = function (result) {
+  return this._imageTexture.computeTextureCoordinates(result);
 };
 
 /**
@@ -1301,26 +1244,24 @@ Billboard.prototype._loadImage = function () {
  */
 Billboard.prototype.setImage = function (id, image) {
   //>>includeStart('debug', pragmas.debug);
-  if (!defined(id)) {
-    throw new DeveloperError("id is required.");
-  }
-  if (!defined(image)) {
-    throw new DeveloperError("image is required.");
-  }
+  Check.typeOf.string("id", id);
+  Check.defined("image", image);
   //>>includeEnd('debug');
 
-  if (this._imageId === id) {
-    return;
-  }
+  this._imageTexture.loadImage(id, image);
+};
 
-  this._imageIndex = -1;
-  this._imageSubRegion = undefined;
-  this._imageId = id;
-  this._image = image;
+/**
+ * Copy the values of an existing billboard texture into this one. Useful for prevent downtime for images that have already been loaded.
+ * @private
+ * @param {BillboardTexture} billboardTexture
+ */
+Billboard.prototype.setImageTexture = function (billboardTexture) {
+  //>>includeStart('debug', pragmas.debug);
+  Check.defined("billboardTexture", billboardTexture);
+  //>>includeEnd('debug');
 
-  if (defined(this._billboardCollection._textureAtlas)) {
-    this._loadImage();
-  }
+  BillboardTexture.clone(billboardTexture, this._imageTexture);
 };
 
 /**
@@ -1334,28 +1275,11 @@ Billboard.prototype.setImage = function (id, image) {
  */
 Billboard.prototype.setImageSubRegion = function (id, subRegion) {
   //>>includeStart('debug', pragmas.debug);
-  if (!defined(id)) {
-    throw new DeveloperError("id is required.");
-  }
-  if (!defined(subRegion)) {
-    throw new DeveloperError("subRegion is required.");
-  }
+  Check.typeOf.string("id", id);
+  Check.defined("subRegion", subRegion);
   //>>includeEnd('debug');
 
-  if (
-    this._imageId === id &&
-    BoundingRectangle.equals(this._imageSubRegion, subRegion)
-  ) {
-    return;
-  }
-
-  this._imageIndex = -1;
-  this._imageId = id;
-  this._imageSubRegion = BoundingRectangle.clone(subRegion);
-
-  if (defined(this._billboardCollection._textureAtlas)) {
-    this._loadImage();
-  }
+  this._imageTexture.addImageSubRegion(id, subRegion);
 };
 
 Billboard.prototype._setTranslate = function (value) {
@@ -1571,13 +1495,12 @@ Billboard.prototype.equals = function (other) {
     (defined(other) &&
       this._id === other._id &&
       Cartesian3.equals(this._position, other._position) &&
-      this._imageId === other._imageId &&
+      this.image === other.image &&
       this._show === other._show &&
       this._scale === other._scale &&
       this._verticalOrigin === other._verticalOrigin &&
       this._horizontalOrigin === other._horizontalOrigin &&
       this._heightReference === other._heightReference &&
-      BoundingRectangle.equals(this._imageSubRegion, other._imageSubRegion) &&
       Color.equals(this._color, other._color) &&
       Cartesian2.equals(this._pixelOffset, other._pixelOffset) &&
       Cartesian2.equals(this._translate, other._translate) &&