@cesium/engine 13.1.0 → 15.0.0

package/Source/Scene/BillboardCollection.js

@@ -1,4 +1,5 @@
 import AttributeCompression from "../Core/AttributeCompression.js";
+import BoundingRectangle from "../Core/BoundingRectangle.js";
 import BoundingSphere from "../Core/BoundingSphere.js";
 import Cartesian2 from "../Core/Cartesian2.js";
 import Cartesian3 from "../Core/Cartesian3.js";
@@ -8,7 +9,6 @@ import ComponentDatatype from "../Core/ComponentDatatype.js";
 import defaultValue from "../Core/defaultValue.js";
 import defined from "../Core/defined.js";
 import destroyObject from "../Core/destroyObject.js";
-import DeveloperError from "../Core/DeveloperError.js";
 import EncodedCartesian3 from "../Core/EncodedCartesian3.js";
 import IndexDatatype from "../Core/IndexDatatype.js";
 import CesiumMath from "../Core/Math.js";
@@ -32,7 +32,7 @@ import HeightReference, { isHeightReferenceClamp } from "./HeightReference.js";
 import HorizontalOrigin from "./HorizontalOrigin.js";
 import SceneMode from "./SceneMode.js";
 import SDFSettings from "./SDFSettings.js";
-import TextureAtlas from "./TextureAtlas.js";
+import TextureAtlas from "../Renderer/TextureAtlas.js";
 import VerticalOrigin from "./VerticalOrigin.js";
 
 const SHOW_INDEX = Billboard.SHOW_INDEX;
@@ -148,9 +148,15 @@ function BillboardCollection(options) {
   this._scene = options.scene;
   this._batchTable = options.batchTable;
 
-  this._textureAtlas = undefined;
-  this._textureAtlasGUID = undefined;
+  let textureAtlas = options.textureAtlas; // Hidden option for internal use
+  if (!defined(textureAtlas)) {
+    textureAtlas = new TextureAtlas();
+  }
+  this._textureAtlas = textureAtlas;
+  this._textureAtlasGUID = textureAtlas.guid;
   this._destroyTextureAtlas = true;
+  this._billboardTextureCache = new Map();
+
   this._sp = undefined;
   this._spTranslucent = undefined;
   this._rsOpaque = undefined;
@@ -205,6 +211,8 @@ function BillboardCollection(options) {
 
   this._colorCommands = [];
 
+  this._allBillboardsReady = false;
+
   /**
    * Determines if billboards in this collection will be shown.
    *
@@ -319,13 +327,12 @@ function BillboardCollection(options) {
 
   this._highlightColor = Color.clone(Color.WHITE); // Only used by Vector3DTilePoints
 
-  const that = this;
   this._uniforms = {
-    u_atlas: function () {
-      return that._textureAtlas.texture;
+    u_atlas: () => {
+      return this.textureAtlas.texture;
     },
-    u_highlightColor: function () {
-      return that._highlightColor;
+    u_highlightColor: () => {
+      return this._highlightColor;
     },
   };
 
@@ -353,6 +360,7 @@ Object.defineProperties(BillboardCollection.prototype, {
    * in the collection.
    * @memberof BillboardCollection.prototype
    * @type {number}
+   * @readonly
    */
   length: {
     get: function () {
@@ -372,13 +380,16 @@ Object.defineProperties(BillboardCollection.prototype, {
       return this._textureAtlas;
     },
     set: function (value) {
+      //>>includeStart('debug', pragmas.debug);
+      Check.defined("textureAtlas", value);
+      //>>includeEnd('debug');
+
       if (this._textureAtlas !== value) {
         this._textureAtlas =
           this._destroyTextureAtlas &&
           this._textureAtlas &&
           this._textureAtlas.destroy();
         this._textureAtlas = value;
-        this._createVertexArray = true; // New per-billboard texture coordinates
       }
     },
   },
@@ -398,12 +409,10 @@ Object.defineProperties(BillboardCollection.prototype, {
    * // Set destroyTextureAtlas
    * // Destroy a billboard collection but not its texture atlas.
    *
-   * const atlas = new TextureAtlas({
-   *   scene : scene,
-   *   images : images
-   * });
+   * const atlas = new TextureAtlas();
    * billboards.textureAtlas = atlas;
    * billboards.destroyTextureAtlas = false;
+   *
    * billboards = billboards.destroy();
    * console.log(atlas.isDestroyed()); // False
    */
@@ -415,6 +424,45 @@ Object.defineProperties(BillboardCollection.prototype, {
       this._destroyTextureAtlas = value;
     },
   },
+
+  /**
+   * Returns the size in bytes of the WebGL texture resources.
+   * @private
+   * @memberof BillboardCollection.prototype
+   * @type {number}
+   * @readonly
+   */
+  sizeInBytes: {
+    get: function () {
+      return this._textureAtlas.sizeInBytes;
+    },
+  },
+
+  /**
+   * True when all billboards currently in the collection are ready for rendering.
+   * @private
+   * @memberof BillboardCollection.prototype
+   * @type {boolean}
+   * @readonly
+   */
+  ready: {
+    get: function () {
+      return this._allBillboardsReady;
+    },
+  },
+
+  /**
+   * Cache of loaded billboard images.
+   * @private
+   * @memberof BillboardCollection.prototype
+   * @type {Map<string, BillboardTexture>}
+   * @readonly
+   */
+  billboardTextureCache: {
+    get: function () {
+      return this._billboardTextureCache;
+    },
+  },
 });
 
 function destroyBillboards(billboards) {
@@ -836,7 +884,6 @@ const writePositionScratch = new EncodedCartesian3();
 function writePositionScaleAndRotation(
   billboardCollection,
   frameState,
-  textureAtlasCoordinates,
   vafWriters,
   billboard,
 ) {
@@ -909,10 +956,11 @@ const LOWER_RIGHT = 2.0;
 const UPPER_RIGHT = 3.0;
 const UPPER_LEFT = 1.0;
 
+const scratchBoundingRectangle = new BoundingRectangle();
+
 function writeCompressedAttrib0(
   billboardCollection,
   frameState,
-  textureAtlasCoordinates,
   vafWriters,
   billboard,
 ) {
@@ -958,15 +1006,10 @@ function writeCompressedAttrib0(
   let bottomLeftY = 0;
   let width = 0;
   let height = 0;
-  const index = billboard._imageIndex;
-  if (index !== -1) {
-    const imageRectangle = textureAtlasCoordinates[index];
-
-    //>>includeStart('debug', pragmas.debug);
-    if (!defined(imageRectangle)) {
-      throw new DeveloperError(`Invalid billboard image index: ${index}`);
-    }
-    //>>includeEnd('debug');
+  if (billboard.ready) {
+    const imageRectangle = billboard.computeTextureCoordinates(
+      scratchBoundingRectangle,
+    );
 
     bottomLeftX = imageRectangle.x;
     bottomLeftY = imageRectangle.y;
@@ -1057,7 +1100,6 @@ function writeCompressedAttrib0(
 function writeCompressedAttrib1(
   billboardCollection,
   frameState,
-  textureAtlasCoordinates,
   vafWriters,
   billboard,
 ) {
@@ -1087,24 +1129,7 @@ function writeCompressedAttrib1(
     }
   }
 
-  let width = 0;
-  const index = billboard._imageIndex;
-  if (index !== -1) {
-    const imageRectangle = textureAtlasCoordinates[index];
-
-    //>>includeStart('debug', pragmas.debug);
-    if (!defined(imageRectangle)) {
-      throw new DeveloperError(`Invalid billboard image index: ${index}`);
-    }
-    //>>includeEnd('debug');
-
-    width = imageRectangle.width;
-  }
-
-  const textureWidth = billboardCollection._textureAtlas.texture.width;
-  const imageWidth = Math.round(
-    defaultValue(billboard.width, textureWidth * width),
-  );
+  const imageWidth = billboard.width ?? 0;
   billboardCollection._maxSize = Math.max(
     billboardCollection._maxSize,
     imageWidth,
@@ -1143,7 +1168,6 @@ function writeCompressedAttrib1(
 function writeCompressedAttrib2(
   billboardCollection,
   frameState,
-  textureAtlasCoordinates,
   vafWriters,
   billboard,
 ) {
@@ -1163,24 +1187,7 @@ function writeCompressedAttrib2(
   billboardCollection._allSizedInMeters =
     billboardCollection._allSizedInMeters && sizeInMeters === 1.0;
 
-  let height = 0;
-  const index = billboard._imageIndex;
-  if (index !== -1) {
-    const imageRectangle = textureAtlasCoordinates[index];
-
-    //>>includeStart('debug', pragmas.debug);
-    if (!defined(imageRectangle)) {
-      throw new DeveloperError(`Invalid billboard image index: ${index}`);
-    }
-    //>>includeEnd('debug');
-
-    height = imageRectangle.height;
-  }
-
-  const dimensions = billboardCollection._textureAtlas.texture.dimensions;
-  const imageHeight = Math.round(
-    defaultValue(billboard.height, dimensions.y * height),
-  );
+  const imageHeight = billboard.height ?? 0;
   billboardCollection._maxSize = Math.max(
     billboardCollection._maxSize,
     imageHeight,
@@ -1222,7 +1229,6 @@ function writeCompressedAttrib2(
 function writeEyeOffset(
   billboardCollection,
   frameState,
-  textureAtlasCoordinates,
   vafWriters,
   billboard,
 ) {
@@ -1243,24 +1249,18 @@ function writeEyeOffset(
   );
 
   if (billboardCollection._instanced) {
-    let width = 0;
-    let height = 0;
-    const index = billboard._imageIndex;
-    if (index !== -1) {
-      const imageRectangle = textureAtlasCoordinates[index];
+    scratchCartesian2.x = 0;
+    scratchCartesian2.y = 0;
 
-      //>>includeStart('debug', pragmas.debug);
-      if (!defined(imageRectangle)) {
-        throw new DeveloperError(`Invalid billboard image index: ${index}`);
-      }
-      //>>includeEnd('debug');
+    if (billboard.ready) {
+      const imageRectangle = billboard.computeTextureCoordinates(
+        scratchBoundingRectangle,
+      );
 
-      width = imageRectangle.width;
-      height = imageRectangle.height;
+      scratchCartesian2.x = imageRectangle.width;
+      scratchCartesian2.y = imageRectangle.height;
     }
 
-    scratchCartesian2.x = width;
-    scratchCartesian2.y = height;
     const compressedTexCoordsRange =
       AttributeCompression.compressTextureCoordinates(scratchCartesian2);
 
@@ -1278,7 +1278,6 @@ function writeEyeOffset(
 function writeScaleByDistance(
   billboardCollection,
   frameState,
-  textureAtlasCoordinates,
   vafWriters,
   billboard,
 ) {
@@ -1318,7 +1317,6 @@ function writeScaleByDistance(
 function writePixelOffsetScaleByDistance(
   billboardCollection,
   frameState,
-  textureAtlasCoordinates,
   vafWriters,
   billboard,
 ) {
@@ -1358,7 +1356,6 @@ function writePixelOffsetScaleByDistance(
 function writeCompressedAttribute3(
   billboardCollection,
   frameState,
-  textureAtlasCoordinates,
   vafWriters,
   billboard,
 ) {
@@ -1398,33 +1395,8 @@ function writeCompressedAttribute3(
   let imageWidth;
 
   if (!defined(billboard._labelDimensions)) {
-    let height = 0;
-    let width = 0;
-    const index = billboard._imageIndex;
-    if (index !== -1) {
-      const imageRectangle = textureAtlasCoordinates[index];
-
-      //>>includeStart('debug', pragmas.debug);
-      if (!defined(imageRectangle)) {
-        throw new DeveloperError(`Invalid billboard image index: ${index}`);
-      }
-      //>>includeEnd('debug');
-
-      height = imageRectangle.height;
-      width = imageRectangle.width;
-    }
-
-    imageHeight = Math.round(
-      defaultValue(
-        billboard.height,
-        billboardCollection._textureAtlas.texture.dimensions.y * height,
-      ),
-    );
-
-    const textureWidth = billboardCollection._textureAtlas.texture.width;
-    imageWidth = Math.round(
-      defaultValue(billboard.width, textureWidth * width),
-    );
+    imageWidth = billboard.width ?? 0;
+    imageHeight = billboard.height ?? 0;
   } else {
     imageWidth = billboard._labelDimensions.x;
     imageHeight = billboard._labelDimensions.y;
@@ -1449,7 +1421,6 @@ function writeCompressedAttribute3(
 function writeTextureCoordinateBoundsOrLabelTranslate(
   billboardCollection,
   frameState,
-  textureAtlasCoordinates,
   vafWriters,
   billboard,
 ) {
@@ -1489,20 +1460,15 @@ function writeTextureCoordinateBoundsOrLabelTranslate(
     return;
   }
 
-  //write texture coordinate bounds, used by depth testing in fragment shader
+  // Write texture coordinate bounds, used by depth testing in fragment shader
   let minX = 0;
   let minY = 0;
   let width = 0;
   let height = 0;
-  const index = billboard._imageIndex;
-  if (index !== -1) {
-    const imageRectangle = textureAtlasCoordinates[index];
-
-    //>>includeStart('debug', pragmas.debug);
-    if (!defined(imageRectangle)) {
-      throw new DeveloperError(`Invalid billboard image index: ${index}`);
-    }
-    //>>includeEnd('debug');
+  if (billboard.ready) {
+    const imageRectangle = billboard.computeTextureCoordinates(
+      scratchBoundingRectangle,
+    );
 
     minX = imageRectangle.x;
     minY = imageRectangle.y;
@@ -1524,13 +1490,7 @@ function writeTextureCoordinateBoundsOrLabelTranslate(
   }
 }
 
-function writeBatchId(
-  billboardCollection,
-  frameState,
-  textureAtlasCoordinates,
-  vafWriters,
-  billboard,
-) {
+function writeBatchId(billboardCollection, frameState, vafWriters, billboard) {
   if (!defined(billboardCollection._batchTable)) {
     return;
   }
@@ -1551,13 +1511,7 @@ function writeBatchId(
   }
 }
 
-function writeSDF(
-  billboardCollection,
-  frameState,
-  textureAtlasCoordinates,
-  vafWriters,
-  billboard,
-) {
+function writeSDF(billboardCollection, frameState, vafWriters, billboard) {
   if (!billboardCollection._sdf) {
     return;
   }
@@ -1594,7 +1548,6 @@ function writeSDF(
 function writeSplitDirection(
   billboardCollection,
   frameState,
-  textureAtlasCoordinates,
   vafWriters,
   billboard,
 ) {
@@ -1622,94 +1575,56 @@ function writeSplitDirection(
 function writeBillboard(
   billboardCollection,
   frameState,
-  textureAtlasCoordinates,
   vafWriters,
   billboard,
 ) {
   writePositionScaleAndRotation(
     billboardCollection,
     frameState,
-    textureAtlasCoordinates,
     vafWriters,
     billboard,
   );
   writeCompressedAttrib0(
     billboardCollection,
     frameState,
-    textureAtlasCoordinates,
     vafWriters,
     billboard,
   );
   writeCompressedAttrib1(
     billboardCollection,
     frameState,
-    textureAtlasCoordinates,
     vafWriters,
     billboard,
   );
   writeCompressedAttrib2(
     billboardCollection,
     frameState,
-    textureAtlasCoordinates,
-    vafWriters,
-    billboard,
-  );
-  writeEyeOffset(
-    billboardCollection,
-    frameState,
-    textureAtlasCoordinates,
-    vafWriters,
-    billboard,
-  );
-  writeScaleByDistance(
-    billboardCollection,
-    frameState,
-    textureAtlasCoordinates,
     vafWriters,
     billboard,
   );
+  writeEyeOffset(billboardCollection, frameState, vafWriters, billboard);
+  writeScaleByDistance(billboardCollection, frameState, vafWriters, billboard);
   writePixelOffsetScaleByDistance(
     billboardCollection,
     frameState,
-    textureAtlasCoordinates,
     vafWriters,
     billboard,
   );
   writeCompressedAttribute3(
     billboardCollection,
     frameState,
-    textureAtlasCoordinates,
     vafWriters,
     billboard,
   );
   writeTextureCoordinateBoundsOrLabelTranslate(
     billboardCollection,
     frameState,
-    textureAtlasCoordinates,
-    vafWriters,
-    billboard,
-  );
-  writeBatchId(
-    billboardCollection,
-    frameState,
-    textureAtlasCoordinates,
-    vafWriters,
-    billboard,
-  );
-  writeSDF(
-    billboardCollection,
-    frameState,
-    textureAtlasCoordinates,
-    vafWriters,
-    billboard,
-  );
-  writeSplitDirection(
-    billboardCollection,
-    frameState,
-    textureAtlasCoordinates,
     vafWriters,
     billboard,
   );
+  writeBatchId(billboardCollection, frameState, vafWriters, billboard);
+  writeSDF(billboardCollection, frameState, vafWriters, billboard);
+  writeSplitDirection(billboardCollection, frameState, vafWriters, billboard);
 }
 
 function recomputeActualPositions(
@@ -1838,7 +1753,7 @@ function createDebugCommand(billboardCollection, context) {
   const drawCommand = context.createViewportQuadCommand(fs, {
     uniformMap: {
       billboard_texture: function () {
-        return billboardCollection._textureAtlas.texture;
+        return billboardCollection.textureAtlas.texture;
       },
     },
   });
@@ -1865,9 +1780,6 @@ BillboardCollection.prototype.update = function (frameState) {
     return;
   }
 
-  let billboards = this._billboards;
-  let billboardsLength = billboards.length;
-
   const context = frameState.context;
   this._instanced = context.instancedArrays;
   attributeLocations = this._instanced
@@ -1877,21 +1789,40 @@ BillboardCollection.prototype.update = function (frameState) {
     ? getIndexBufferInstanced
     : getIndexBufferBatched;
 
-  let textureAtlas = this._textureAtlas;
-  if (!defined(textureAtlas)) {
-    textureAtlas = this._textureAtlas = new TextureAtlas({
-      context: context,
-    });
+  let billboards = this._billboards;
+  let billboardsLength = billboards.length;
+  let allBillboardsReady = true;
+  for (let i = 0; i < billboardsLength; ++i) {
+    const billboard = billboards[i];
+    if (defined(billboard.loadError)) {
+      console.error(
+        `Error loading image for billboard: ${billboard.loadError}`,
+      );
+      billboard.image = undefined;
+    }
 
-    for (let ii = 0; ii < billboardsLength; ++ii) {
-      billboards[ii]._loadImage();
+    if (billboard.textureDirty) {
+      this._updateBillboard(billboard, IMAGE_INDEX_INDEX);
+    }
+
+    if (billboard.show) {
+      allBillboardsReady = allBillboardsReady && billboard.ready;
     }
   }
 
-  const textureAtlasCoordinates = textureAtlas.textureCoordinates;
-  if (textureAtlasCoordinates.length === 0) {
-    // Can't write billboard vertices until we have texture coordinates
-    // provided by a texture atlas
+  // Queue any texture resource updates for after the frame is rendered
+  const textureAtlas = this._textureAtlas;
+  frameState.afterRender.push(() => {
+    if (this.isDestroyed()) {
+      return;
+    }
+
+    return textureAtlas.update(frameState.context);
+  });
+
+  if (!defined(textureAtlas.texture)) {
+    // Can't write billboard vertices until the texture atlas
+    // has been updated once
     return;
   }
 
@@ -1939,13 +1870,8 @@ BillboardCollection.prototype.update = function (frameState) {
       for (let i = 0; i < billboardsLength; ++i) {
         const billboard = this._billboards[i];
         billboard._dirty = false; // In case it needed an update.
-        writeBillboard(
-          this,
-          frameState,
-          textureAtlasCoordinates,
-          vafWriters,
-          billboard,
-        );
+        billboard.textureDirty = false;
+        writeBillboard(this, frameState, vafWriters, billboard);
       }
 
       // Different billboard collections share the same index buffer.
@@ -1992,7 +1918,7 @@ BillboardCollection.prototype.update = function (frameState) {
       writers.push(writeCompressedAttrib2);
     }
 
-    if (properties[EYE_OFFSET_INDEX]) {
+    if (properties[IMAGE_INDEX_INDEX] || properties[EYE_OFFSET_INDEX]) {
       writers.push(writeEyeOffset);
     }
 
@@ -2036,9 +1962,10 @@ BillboardCollection.prototype.update = function (frameState) {
       for (let m = 0; m < billboardsToUpdateLength; ++m) {
         const b = billboardsToUpdate[m];
         b._dirty = false;
+        b.textureDirty = false;
 
         for (let n = 0; n < numWriters; ++n) {
-          writers[n](this, frameState, textureAtlasCoordinates, vafWriters, b);
+          writers[n](this, frameState, vafWriters, b);
         }
       }
       this._vaf.commit(getIndexBuffer(context));
@@ -2046,9 +1973,10 @@ BillboardCollection.prototype.update = function (frameState) {
       for (let h = 0; h < billboardsToUpdateLength; ++h) {
         const bb = billboardsToUpdate[h];
         bb._dirty = false;
+        bb.textureDirty = false;
 
         for (let o = 0; o < numWriters; ++o) {
-          writers[o](this, frameState, textureAtlasCoordinates, vafWriters, bb);
+          writers[o](this, frameState, vafWriters, bb);
         }
 
         if (this._instanced) {
@@ -2412,6 +2340,8 @@ BillboardCollection.prototype.update = function (frameState) {
       commandList.push(this.debugCommand);
     }
   }
+
+  this._allBillboardsReady = allBillboardsReady;
 };
 
 /**

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;