@cesium/engine 14.0.0 → 15.0.0

package/Source/Core/TexturePacker.js

@@ -0,0 +1,166 @@
+import BoundingRectangle from "./BoundingRectangle.js";
+import Check from "./Check.js";
+import defined from "./defined.js";
+
+/**
+ * @typedef {object} TexturePacker.PackableObject
+ * Any object, such as an <code>Image</code> with the following properties:
+ * @private
+ * @property {number} width The width of the image, or other object, usually in pixels
+ * @property {number} height The height of the image, or other object, usually in pixels
+ */
+
+/**
+ * A texture atlas is recursively broken down into regions of space called nodes.
+ * Nodes contain either an image reference or child nodes.
+ * @private
+ * @constructor
+ * @param {object} options An options object with the following properties:
+ * @param {number} options.x The x-offset of the texture node
+ * @param {number} options.y The y-offset of the texture node
+ * @param {number} options.width The width of the texture node
+ * @param {number} options.height The width of the texture node
+ */
+function TextureNode({ x, y, width, height }) {
+  /**
+   * @type {BoundingRectangle}
+   */
+  this.rectangle = new BoundingRectangle(x, y, width, height);
+
+  /**
+   * @type {TextureNode|undefined}
+   */
+  this.childNode1 = undefined;
+  /**
+   * @type {TextureNode|undefined}
+   */
+  this.childNode2 = undefined;
+
+  /**
+   * Identifier referencing an image or packed data
+   * @type {number|undefined}
+   */
+  this.index = undefined;
+}
+
+/**
+ * Typically used with {@link TextureAtlas} to calculate efficient regions of the larger areas to store images or other data. Typically, all units are specified in pixels.
+ * @alias TexturePacker
+ * @constructor
+ * @private
+ * @param {options} options Object with the following properties:
+ * @param {number} options.width Width of the atlas, in pixels
+ * @param {number} options.height Height of atlas, in pixels
+ * @param {number} options.borderPadding Amount of border padding, in pixels
+ */
+function TexturePacker({ width, height, borderPadding }) {
+  this._width = width;
+  this._height = height;
+
+  this._borderPadding = borderPadding;
+
+  this._root = new TextureNode({
+    x: borderPadding,
+    y: borderPadding,
+    width: width - 2 * borderPadding,
+    height: height - 2 * borderPadding,
+  });
+}
+
+/**
+ * Inserts the given object into the next available region based on it's dimensions. Where convenient, it's most efficient to pack items largest to smallest.
+ * @private
+ * @param {number} index An identifier referencing the image or other stored data
+ * @param {TexturePacker.PackableObject} packableObject An object, such as an <code>Image</code>, with <code>width</code> and <code>height</code> properties in pixels.
+ * @returns {TextureNode|undefined} The created region, or <code>undefined</code> if there is no region large enough to accommodate the object's dimensions.
+ */
+TexturePacker.prototype.pack = function (index, { width, height }) {
+  //>>includeStart('debug', pragmas.debug);
+  Check.typeOf.number.greaterThanOrEquals("index", index, 0);
+  Check.typeOf.number.greaterThanOrEquals("image.width", width, 1);
+  Check.typeOf.number.greaterThanOrEquals("image.height", height, 1);
+  //>>includeEnd('debug');
+
+  const node = this._findNode(this._root, { width, height });
+  if (!defined(node)) {
+    return;
+  }
+
+  node.index = index;
+  return node;
+};
+
+// A recursive function that finds the best place to insert
+// a new image based on existing image 'nodes'.
+// Inspired by: http://blackpawn.com/texts/lightmaps/default.html
+TexturePacker.prototype._findNode = function (node, { width, height }) {
+  if (!defined(node)) {
+    return undefined;
+  }
+
+  // Leaf node
+  if (!defined(node.childNode1) && !defined(node.childNode2)) {
+    if (defined(node.index)) {
+      // Node already contains an image: Skip it.
+      return undefined;
+    }
+
+    const { rectangle } = node;
+
+    const nodeWidth = rectangle.width;
+    const nodeHeight = rectangle.height;
+    const widthDifference = nodeWidth - width;
+    const heightDifference = nodeHeight - height;
+
+    // Node is smaller than the image.
+    if (widthDifference < 0 || heightDifference < 0) {
+      return undefined;
+    }
+
+    // If the node is the same size as the image, return the node
+    if (widthDifference === 0 && heightDifference === 0) {
+      return node;
+    }
+
+    // Vertical split (childNode1 = left half, childNode2 = right half).
+    if (widthDifference > heightDifference) {
+      node.childNode1 = new TextureNode({
+        x: rectangle.x,
+        y: rectangle.y,
+        width,
+        height: nodeHeight,
+      });
+      node.childNode2 = new TextureNode({
+        x: rectangle.x + width,
+        y: rectangle.y,
+        width: widthDifference,
+        height: nodeHeight,
+      });
+
+      return this._findNode(node.childNode1, { width, height });
+    }
+
+    // Horizontal split (childNode1 = bottom half, childNode2 = top half).
+    node.childNode1 = new TextureNode({
+      x: rectangle.x,
+      y: rectangle.y,
+      width: nodeWidth,
+      height,
+    });
+    node.childNode2 = new TextureNode({
+      x: rectangle.x,
+      y: rectangle.y + height,
+      width: nodeWidth,
+      height: heightDifference,
+    });
+    return this._findNode(node.childNode1, { width, height });
+  }
+
+  // If not a leaf node
+  return (
+    this._findNode(node.childNode1, { width, height }) ||
+    this._findNode(node.childNode2, { width, height })
+  );
+};
+
+export default TexturePacker;

package/Source/DataSources/BillboardVisualizer.js

@@ -126,12 +126,12 @@ BillboardVisualizer.prototype.update = function (time) {
     if (!defined(billboard)) {
       billboard = cluster.getBillboard(entity);
       billboard.id = entity;
-      billboard.image = undefined;
       item.billboard = billboard;
+      item.textureValue = undefined;
     }
 
     billboard.show = show;
-    if (!defined(billboard.image) || item.textureValue !== textureValue) {
+    if (item.textureValue !== textureValue) {
       billboard.image = textureValue;
       item.textureValue = textureValue;
     }
@@ -233,7 +233,7 @@ BillboardVisualizer.prototype.update = function (time) {
       boundingRectangleScratch,
     );
     if (defined(subRegion)) {
-      billboard.setImageSubRegion(billboard._imageId, subRegion);
+      billboard.setImageSubRegion(billboard.image, subRegion);
     }
   }
   return true;

package/Source/DataSources/EntityCluster.js

@@ -610,6 +610,25 @@ Object.defineProperties(EntityCluster.prototype, {
       this._clusterPoints = value;
     },
   },
+
+  /**
+   * Returns true when all clustered data has been rendered.
+   * @memberof EntityCluster.prototype
+   * @type {boolean}
+   * @readonly
+   * @private
+   */
+  ready: {
+    get: function () {
+      return (
+        !this._enabledDirty &&
+        !this._clusterDirty &&
+        (!defined(this._billboardCollection) ||
+          this._billboardCollection.ready) &&
+        (!defined(this._labelCollection) || this._labelCollection.ready)
+      );
+    },
+  },
 });
 
 function createGetEntity(
@@ -866,28 +885,30 @@ EntityCluster.prototype.update = function (frameState) {
   // the glyphs haven't been created so the screen space bounding boxes
   // are incorrect.
   let commandList;
+  const labelCollection = this._labelCollection;
   if (
-    defined(this._labelCollection) &&
-    this._labelCollection.length > 0 &&
-    this._labelCollection.get(0)._glyphs.length === 0
+    defined(labelCollection) &&
+    labelCollection.length > 0 &&
+    !labelCollection.ready
   ) {
     commandList = frameState.commandList;
     frameState.commandList = [];
-    this._labelCollection.update(frameState);
+    labelCollection.update(frameState);
     frameState.commandList = commandList;
   }
 
-  // If clustering is enabled before the billboard collection is updated,
+  // If clustering is enabled before the billboard collections are updated,
   // the images haven't been added to the image atlas so the screen space bounding boxes
   // are incorrect.
+  const billboardCollection = this._billboardCollection;
   if (
-    defined(this._billboardCollection) &&
-    this._billboardCollection.length > 0 &&
-    !defined(this._billboardCollection.get(0).width)
+    defined(billboardCollection) &&
+    billboardCollection.length > 0 &&
+    !billboardCollection.ready
   ) {
     commandList = frameState.commandList;
     frameState.commandList = [];
-    this._billboardCollection.update(frameState);
+    billboardCollection.update(frameState);
     frameState.commandList = commandList;
   }
 
@@ -898,8 +919,12 @@ EntityCluster.prototype.update = function (frameState) {
   }
 
   if (this._clusterDirty) {
-    this._clusterDirty = false;
     this._cluster();
+
+    // Unless all existing billboards and labels were clustered, clustering will need to execute again next frame
+    this._clusterDirty =
+      (defined(labelCollection) && !labelCollection.ready) ||
+      (defined(billboardCollection) && !billboardCollection.ready);
   }
 
   if (defined(this._clusterLabelCollection)) {
@@ -912,11 +937,11 @@ EntityCluster.prototype.update = function (frameState) {
     this._clusterPointCollection.update(frameState);
   }
 
-  if (defined(this._labelCollection)) {
-    this._labelCollection.update(frameState);
+  if (defined(labelCollection)) {
+    labelCollection.update(frameState);
   }
-  if (defined(this._billboardCollection)) {
-    this._billboardCollection.update(frameState);
+  if (defined(billboardCollection)) {
+    billboardCollection.update(frameState);
   }
   if (defined(this._pointCollection)) {
     this._pointCollection.update(frameState);
@@ -932,6 +957,11 @@ EntityCluster.prototype.update = function (frameState) {
  * </p>
  */
 EntityCluster.prototype.destroy = function () {
+  if (defined(this._removeEventListener)) {
+    this._removeEventListener();
+    this._removeEventListener = undefined;
+  }
+
   this._labelCollection =
     this._labelCollection && this._labelCollection.destroy();
   this._billboardCollection =
@@ -947,11 +977,6 @@ EntityCluster.prototype.destroy = function () {
   this._clusterPointCollection =
     this._clusterPointCollection && this._clusterPointCollection.destroy();
 
-  if (defined(this._removeEventListener)) {
-    this._removeEventListener();
-    this._removeEventListener = undefined;
-  }
-
   this._labelCollection = undefined;
   this._billboardCollection = undefined;
   this._pointCollection = undefined;

package/Source/Renderer/Context.js

@@ -4,7 +4,6 @@ import ComponentDatatype from "../Core/ComponentDatatype.js";
 import createGuid from "../Core/createGuid.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 Geometry from "../Core/Geometry.js";
@@ -1671,7 +1670,4 @@ Context.prototype.destroy = function () {
   return destroyObject(this);
 };
 
-// Used for specs.
-Context._deprecationWarning = deprecationWarning;
-
 export default Context;

package/Source/Renderer/Texture.js

@@ -23,7 +23,7 @@ import TextureMinificationFilter from "./TextureMinificationFilter.js";
  * @property {PixelDatatype} [pixelDatatype=PixelDatatype.UNSIGNED_BYTE] The data type of each pixel.
  * @property {boolean} [flipY=true] If true, the source values will be read as if the y-axis is inverted (y=0 at the top).
  * @property {boolean} [skipColorSpaceConversion=false] If true, color space conversions will be skipped when reading the texel values.
- * @property {Sampler} [sampler] Information about how to sample the cubemap texture.
+ * @property {Sampler} [sampler] Information about how to sample the texture.
  * @property {number} [width] The pixel width of the texture. If not supplied, must be available from the source.
  * @property {number} [height] The pixel height of the texture. If not supplied, must be available from the source.
  * @property {boolean} [preMultiplyAlpha] If true, the alpha channel will be multiplied into the other channels.
@@ -704,7 +704,8 @@ Object.defineProperties(Texture.prototype, {
    * coordinates in both directions, uses linear filtering for both magnification and minification,
    * and uses a maximum anisotropy of 1.0.
    * @memberof Texture.prototype
-   * @type {object}
+   * @type {Sampler}
+   * @private
    */
   sampler: {
     get: function () {
@@ -842,7 +843,7 @@ function setupSampler(texture, sampler) {
  * @exception {DeveloperError} xOffset + source.width must be less than or equal to width.
  * @exception {DeveloperError} yOffset + source.height must be less than or equal to height.
  * @exception {DeveloperError} This texture was destroyed, i.e., destroy() was called.
- *
+ * @private
  * @example
  * texture.copyFrom({
  *  source: {
@@ -965,7 +966,7 @@ Texture.prototype.copyFrom = function (options) {
  * @param {number} [framebufferYOffset=0] optional
  * @param {number} [width=width] optional
  * @param {number} [height=height] optional
- *
+ * @private
  * @exception {DeveloperError} Cannot call copyFromFramebuffer when the texture pixel format is DEPTH_COMPONENT or DEPTH_STENCIL.
  * @exception {DeveloperError} Cannot call copyFromFramebuffer when the texture pixel data type is FLOAT.
  * @exception {DeveloperError} Cannot call copyFromFramebuffer when the texture pixel data type is HALF_FLOAT.
@@ -1060,7 +1061,7 @@ Texture.prototype.copyFromFramebuffer = function (
 
 /**
  * @param {MipmapHint} [hint=MipmapHint.DONT_CARE] optional.
- *
+ * @private
  * @exception {DeveloperError} Cannot call generateMipmap when the texture pixel format is DEPTH_COMPONENT or DEPTH_STENCIL.
  * @exception {DeveloperError} Cannot call generateMipmap when the texture pixel format is a compressed format.
  * @exception {DeveloperError} hint is invalid.