@cesium/engine 22.0.0 → 22.2.0

package/Source/Core/Transforms.js

@@ -1131,23 +1131,32 @@ Transforms.rotationMatrixFromPositionVelocity = function (
   return result;
 };
 
-const swizzleMatrix = new Matrix4(
-  0.0,
-  0.0,
-  1.0,
-  0.0,
-  1.0,
-  0.0,
-  0.0,
-  0.0,
-  0.0,
-  1.0,
-  0.0,
-  0.0,
-  0.0,
-  0.0,
-  0.0,
-  1.0,
+/**
+ * An immutable matrix that swaps x, y, z for 2D.
+ *
+ * @type {Matrix4}
+ * @constant
+ * @private
+ */
+Transforms.SWIZZLE_3D_TO_2D_MATRIX = Object.freeze(
+  new Matrix4(
+    0.0,
+    0.0,
+    1.0,
+    0.0,
+    1.0,
+    0.0,
+    0.0,
+    0.0,
+    0.0,
+    1.0,
+    0.0,
+    0.0,
+    0.0,
+    0.0,
+    0.0,
+    1.0,
+  ),
 );
 
 const scratchCartographic = new Cartographic();
@@ -1210,7 +1219,7 @@ Transforms.basisTo2D = function (projection, matrix, result) {
   const toENU = Matrix4.inverseTransformation(fromENU, scratchToENU);
   const rotation = Matrix4.getMatrix3(matrix, scratchRotation);
   const local = Matrix4.multiplyByMatrix3(toENU, rotation, result);
-  Matrix4.multiply(swizzleMatrix, local, result); // Swap x, y, z for 2D
+  Matrix4.multiply(Transforms.SWIZZLE_3D_TO_2D_MATRIX, local, result); // Swap x, y, z for 2D
   Matrix4.setTranslation(result, projectedPosition, result); // Use the projected center
 
   return result;
@@ -1260,7 +1269,7 @@ Transforms.ellipsoidTo2DModelMatrix = function (projection, center, result) {
     projectedPosition,
     scratchFromENU,
   );
-  Matrix4.multiply(swizzleMatrix, toENU, result);
+  Matrix4.multiply(Transforms.SWIZZLE_3D_TO_2D_MATRIX, toENU, result);
   Matrix4.multiply(translation, result, result);
 
   return result;

package/Source/DataSources/BillboardGraphics.js

@@ -10,7 +10,7 @@ import createPropertyDescriptor from "./createPropertyDescriptor.js";
  * Initialization options for the BillboardGraphics constructor
  *
  * @property {Property | boolean} [show=true] A boolean Property specifying the visibility of the billboard.
- * @property {Property | string | HTMLCanvasElement} [image] A Property specifying the Image, URI, or Canvas to use for the billboard.
+ * @property {Property | string | HTMLImageElement | HTMLCanvasElement} [image] A Property specifying the Image, URI, or Canvas to use for the billboard.
  * @property {Property | number} [scale=1.0] A numeric Property specifying the scale to apply to the image size.
  * @property {Property | Cartesian2} [pixelOffset=Cartesian2.ZERO] A {@link Cartesian2} Property specifying the pixel offset.
  * @property {Property | Cartesian3} [eyeOffset=Cartesian3.ZERO] A {@link Cartesian3} Property specifying the eye offset.

package/Source/DataSources/BillboardVisualizer.js

@@ -131,10 +131,6 @@ BillboardVisualizer.prototype.update = function (time) {
     }
 
     billboard.show = show;
-    if (item.textureValue !== textureValue) {
-      billboard.image = textureValue;
-      item.textureValue = textureValue;
-    }
     billboard.position = position;
     billboard.color = Property.getValueOrDefault(
       billboardGraphics._color,
@@ -227,6 +223,13 @@ BillboardVisualizer.prototype.update = function (time) {
       defaultSplitDirection,
     );
 
+    // Apply .image last, so any necessary property values are available
+    // in Billboard#_computeImageTextureSize before adding to the atlas.
+    if (item.textureValue !== textureValue) {
+      billboard.image = textureValue;
+      item.textureValue = textureValue;
+    }
+
     const subRegion = Property.getValueOrUndefined(
       billboardGraphics._imageSubRegion,
       time,

package/Source/Renderer/Buffer.js

@@ -72,6 +72,26 @@ function Buffer(options) {
   this.vertexArrayDestroyable = true;
 }
 
+Buffer.createPixelBuffer = function (options) {
+  //>>includeStart('debug', pragmas.debug);
+  Check.defined("options.context", options.context);
+  //>>includeEnd('debug');
+
+  if (!options.context._webgl2) {
+    throw new DeveloperError(
+      "A WebGL 2 context is required to create PixelBuffers.",
+    );
+  }
+
+  return new Buffer({
+    context: options.context,
+    bufferTarget: WebGLConstants.PIXEL_PACK_BUFFER,
+    typedArray: options.typedArray,
+    sizeInBytes: options.sizeInBytes,
+    usage: options.usage,
+  });
+};
+
 /**
  * Creates a vertex buffer, which contains untyped vertex data in GPU-controlled memory.
  * <br /><br />
@@ -242,6 +262,18 @@ Buffer.prototype._getBuffer = function () {
   return this._buffer;
 };
 
+Buffer.prototype._bind = function () {
+  const gl = this._gl;
+  const target = this._bufferTarget;
+  gl.bindBuffer(target, this._buffer);
+};
+
+Buffer.prototype._unBind = function () {
+  const gl = this._gl;
+  const target = this._bufferTarget;
+  gl.bindBuffer(target, null);
+};
+
 Buffer.prototype.copyFromArrayView = function (arrayView, offsetInBytes) {
   offsetInBytes = offsetInBytes ?? 0;
 

package/Source/Renderer/BufferUsage.js

@@ -7,12 +7,14 @@ const BufferUsage = {
   STREAM_DRAW: WebGLConstants.STREAM_DRAW,
   STATIC_DRAW: WebGLConstants.STATIC_DRAW,
   DYNAMIC_DRAW: WebGLConstants.DYNAMIC_DRAW,
+  DYNAMIC_READ: WebGLConstants.DYNAMIC_READ,
 
   validate: function (bufferUsage) {
     return (
       bufferUsage === BufferUsage.STREAM_DRAW ||
       bufferUsage === BufferUsage.STATIC_DRAW ||
-      bufferUsage === BufferUsage.DYNAMIC_DRAW
+      bufferUsage === BufferUsage.DYNAMIC_DRAW ||
+      bufferUsage === BufferUsage.DYNAMIC_READ
     );
   },
 };

package/Source/Renderer/Context.js

@@ -1,3 +1,4 @@
+import Buffer from "./Buffer.js";
 import Check from "../Core/Check.js";
 import Color from "../Core/Color.js";
 import ComponentDatatype from "../Core/ComponentDatatype.js";
@@ -1442,13 +1443,88 @@ Context.prototype.endFrame = function () {
 };
 
 /**
+ * @typedef {object} ReadState
+ *
+ * Options defining a rectangle to read pixels from.
+ *
+ * @private
+ * @property {number} [x=0] The x offset of the rectangle to read from.
+ * @property {number} [y=0] The y offset of the rectangle to read from.
+ * @property {number} [width=this.drawingBufferWidth] The width of the rectangle to read from.
+ * @property {number} [height=this.drawingBufferHeight] The height of the rectangle to read from.
+ * @property {FrameBuffer|undefined} [framebuffer] The framebuffer to read from. If undefined, the read will be from the default framebuffer.
+ */
+
+/**
+ * Read pixels from a framebuffer into a Pixel Buffer Object (PBO).
+ *
+ * @private
+ * @param {ReadState} readState Options defining a rectangle to read pixels from.
+ * @returns {Buffer} A PixelBuffer containing the pixels read from the specified rectangle.
+ *
+ * @exception {DeveloperError} A WebGL 2 context is required to read pixels using a PBO.
+ */
+Context.prototype.readPixelsToPBO = function (readState) {
+  const gl = this._gl;
+
+  readState = readState ?? Frozen.EMPTY_OBJECT;
+  const x = Math.max(readState.x ?? 0, 0);
+  const y = Math.max(readState.y ?? 0, 0);
+  const width = readState.width ?? this.drawingBufferWidth;
+  const height = readState.height ?? this.drawingBufferHeight;
+  const framebuffer = readState.framebuffer;
+
+  if (!this._webgl2) {
+    throw new DeveloperError(
+      "A WebGL 2 context is required to read pixels using a PBO.",
+    );
+  }
+
+  //>>includeStart('debug', pragmas.debug);
+  Check.typeOf.number.greaterThan("readState.width", width, 0);
+  Check.typeOf.number.greaterThan("readState.height", height, 0);
+  //>>includeEnd('debug');
+
+  let pixelDatatype = PixelDatatype.UNSIGNED_BYTE;
+  let pixelFormat = PixelFormat.RGBA;
+  if (defined(framebuffer) && framebuffer.numberOfColorAttachments > 0) {
+    pixelDatatype = framebuffer.getColorTexture(0).pixelDatatype;
+    pixelFormat = framebuffer.getColorTexture(0).pixelFormat;
+  }
+
+  const pixels = Buffer.createPixelBuffer({
+    context: this,
+    sizeInBytes: PixelFormat.textureSizeInBytes(
+      pixelFormat,
+      pixelDatatype,
+      width,
+      height,
+    ),
+    usage: BufferUsage.DYNAMIC_READ,
+  });
+
+  bindFramebuffer(this, framebuffer);
+
+  pixels._bind();
+  gl.readPixels(
+    x,
+    y,
+    width,
+    height,
+    pixelFormat,
+    PixelDatatype.toWebGLConstant(pixelDatatype, this),
+    0,
+  );
+  pixels._unBind();
+
+  return pixels;
+};
+
+/**
+ * Read pixels from a framebuffer into a typed array.
+ *
  * @private
- * @param {object} readState An object with the following properties:
- * @param {number} [readState.x=0] The x offset of the rectangle to read from.
- * @param {number} [readState.y=0] The y offset of the rectangle to read from.
- * @param {number} [readState.width=this.drawingBufferWidth] The width of the rectangle to read from.
- * @param {number} [readState.height=this.drawingBufferHeight] The height of the rectangle to read from.
- * @param {Framebuffer} [readState.framebuffer] The framebuffer to read from. If undefined, the read will be from the default framebuffer.
+ * @param {ReadState} readState Options defining a rectangle to read pixels from.
  * @returns {Uint8Array|Uint16Array|Float32Array|Uint32Array} The pixels in the specified rectangle.
  */
 Context.prototype.readPixels = function (readState) {
@@ -1467,12 +1543,14 @@ Context.prototype.readPixels = function (readState) {
   //>>includeEnd('debug');
 
   let pixelDatatype = PixelDatatype.UNSIGNED_BYTE;
+  let pixelFormat = PixelFormat.RGBA;
   if (defined(framebuffer) && framebuffer.numberOfColorAttachments > 0) {
     pixelDatatype = framebuffer.getColorTexture(0).pixelDatatype;
+    pixelFormat = framebuffer.getColorTexture(0).pixelFormat;
   }
 
   const pixels = PixelFormat.createTypedArray(
-    PixelFormat.RGBA,
+    pixelFormat,
     pixelDatatype,
     width,
     height,

package/Source/Renderer/Sync.js

@@ -0,0 +1,104 @@
+import Check from "../Core/Check.js";
+import destroyObject from "../Core/destroyObject.js";
+import DeveloperError from "../Core/DeveloperError.js";
+import Frozen from "../Core/Frozen.js";
+import RuntimeError from "../Core/RuntimeError.js";
+import WebGLConstants from "../Core/WebGLConstants.js";
+
+/**
+ * The WebGLSync interface is part of the WebGL 2 API and is used to synchronize activities between the GPU and the application.
+ *
+ * @param {object} options Object with the following properties:
+ * @param {Context} context
+ *
+ * @exception {DeveloperError} A WebGL 2 context is required to use Sync operations.
+ *
+ * @private
+ * @constructor
+ */
+function Sync(options) {
+  options = options ?? Frozen.EMPTY_OBJECT;
+  const context = options.context;
+
+  //>>includeStart('debug', pragmas.debug);
+  Check.defined("options.context", context);
+  //>>includeEnd('debug');
+
+  if (!context._webgl2) {
+    throw new DeveloperError(
+      "A WebGL 2 context is required to use Sync operations.",
+    );
+  }
+
+  const gl = context._gl;
+  const sync = gl.fenceSync(WebGLConstants.SYNC_GPU_COMMANDS_COMPLETE, 0);
+
+  this._gl = gl;
+  this._sync = sync;
+}
+Sync.create = function (options) {
+  return new Sync(options);
+};
+/**
+ * Query the sync status of this Sync object.
+ *
+ * @returns {number} Returns a WebGLConstants indicating the status of the sync object (WebGLConstants.SIGNALED or WebGLConstants.UNSIGNALED).
+ *
+ * @private
+ */
+Sync.prototype.getStatus = function () {
+  const status = this._gl.getSyncParameter(
+    this._sync,
+    WebGLConstants.SYNC_STATUS,
+  );
+  return status;
+};
+Sync.prototype.isDestroyed = function () {
+  return false;
+};
+Sync.prototype.destroy = function () {
+  this._gl.deleteSync(this._sync);
+  return destroyObject(this);
+};
+
+/**
+ * Incremantally polls the status of the Sync object until signaled then resolves.
+ * Usually polling should be done once per frame.
+ *
+ * @example
+ * try {
+ *  await sync.waitForSignal(function (next) {
+ *    setTimeout(next, 100);
+ *  });
+ *} catch (e) {
+ *  throw "Signal timeout";
+ *} finally {
+ *  sync.destroy();
+ *}
+ *
+ * @param {function} scheduleFunction Function for scheduling the next poll. Receives a callback as its only parameter.
+ * @param {number} [ttl=10] Max number of iterations to poll until timeout.
+ *
+ * @exception {RuntimeError} Wait for signal timeout.
+ */
+Sync.prototype.waitForSignal = async function (scheduleFunction, ttl) {
+  const self = this;
+  ttl = ttl ?? 10;
+  function waitForSignal0(resolve, reject, ttl) {
+    return () => {
+      const syncStatus = self.getStatus();
+      const signaled = syncStatus === WebGLConstants.SIGNALED;
+      if (signaled) {
+        resolve();
+      } else if (ttl <= 0) {
+        reject(new RuntimeError("Wait for signal timeout"));
+      } else {
+        scheduleFunction(waitForSignal0(resolve, reject, ttl - 1));
+      }
+    };
+  }
+  return new Promise((resolve, reject) => {
+    scheduleFunction(waitForSignal0(resolve, reject, ttl));
+  });
+};
+export default Sync;

package/Source/Renderer/TextureAtlas.js

@@ -59,12 +59,16 @@ function TextureAtlas(options) {
   this._initialSize = initialSize;
 
   this._texturePacker = undefined;
+  /** @type {BoundingRectangle[]} */
   this._rectangles = [];
+  /** @type {Map<number, number>} */
   this._subRegions = new Map();
   this._guid = createGuid();
 
   this._imagesToAddQueue = [];
+  /** @type {Map<string, number>} */
   this._indexById = new Map();
+  /** @type {Map<string, Promise<number>>} */
   this._indexPromiseById = new Map();
   this._nextIndex = 0;
 }
@@ -360,26 +364,17 @@ TextureAtlas.prototype._resize = function (context, queueOffset = 0) {
     toPack.push(queue[i]);
   }
 
-  // At minimum, the texture will need to scale to accommodate the largest width and height
-  width = Math.max(maxWidth, width);
-  height = Math.max(maxHeight, height);
+  // At minimum, atlas must fit its largest input images. Texture coordinates are
+  // compressed to 0–1 with 12-bit precision, so use power-of-two size to align pixels.
+  width = CesiumMath.nextPowerOfTwo(Math.max(maxWidth, width));
+  height = CesiumMath.nextPowerOfTwo(Math.max(maxHeight, height));
 
-  if (!context.webgl2) {
-    width = CesiumMath.nextPowerOfTwo(width);
-    height = CesiumMath.nextPowerOfTwo(height);
-  }
-
-  // Determine by what factor the texture need to be scaled by at minimum
-  const areaDifference = areaQueued;
-  let scalingFactor = 1.0;
-  while (areaDifference / width / height >= 1.0) {
-    scalingFactor *= 2.0;
-
-    // Resize by one dimension
+  // Iteratively double the smallest dimension until atlas area is (approximately) sufficient.
+  while (areaQueued >= width * height) {
     if (width > height) {
-      height *= scalingFactor;
+      height *= 2;
     } else {
-      width *= scalingFactor;
+      width *= 2;
     }
   }
 
@@ -644,34 +639,51 @@ async function resolveImage(image, id) {
  * @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.
- * @returns {Promise<number>} A Promise that resolves to the image region index. -1 is returned if resouces are in the process of being destroyed.
+ * @param {number} width A number specifying the width of the texture. If undefined, the image width will be used.
+ * @param {number} height A number specifying the height of the texture. If undefined, the image height will be used.
+ * @returns {Promise<number>} A Promise that resolves to the image region index, or -1 if resources are in the process of being destroyed.
  */
-TextureAtlas.prototype.addImage = function (id, image) {
+TextureAtlas.prototype.addImage = function (id, image, width, height) {
   //>>includeStart('debug', pragmas.debug);
   Check.typeOf.string("id", id);
   Check.defined("image", image);
   //>>includeEnd('debug');
 
   let promise = this._indexPromiseById.get(id);
+  let index = this._indexById.get(id);
   if (defined(promise)) {
-    // This image has already been added
+    // This image is already being added
     return promise;
   }
+  if (defined(index)) {
+    // This image has already been added and resolved
+    return Promise.resolve(index);
+  }
 
-  const index = this._nextIndex++;
+  index = this._nextIndex++;
   this._indexById.set(id, index);
 
   const resolveAndAddImage = async () => {
-    image = await resolveImage(image, id);
+    const resolvedImage = await resolveImage(image, id);
     //>>includeStart('debug', pragmas.debug);
-    Check.defined("image", image);
+    Check.defined("image", resolvedImage);
     //>>includeEnd('debug');
 
-    if (this.isDestroyed() || !defined(image)) {
+    if (this.isDestroyed() || !defined(resolvedImage)) {
+      this._indexPromiseById.delete(id);
       return -1;
     }
 
-    return this._addImage(index, image);
+    if (defined(width)) {
+      resolvedImage.width = width;
+    }
+    if (defined(height)) {
+      resolvedImage.height = height;
+    }
+
+    const imageIndex = await this._addImage(index, resolvedImage);
+    this._indexPromiseById.delete(id);
+    return imageIndex;
   };
 
   promise = resolveAndAddImage();
@@ -679,46 +691,65 @@ TextureAtlas.prototype.addImage = function (id, image) {
   return promise;
 };
 
+/**
+ * Get an existing sub-region of an existing atlas image as additional image indices.
+ * @private
+ * @param {string} id The identifier of the existing image.
+ * @param {BoundingRectangle} subRegion An {@link BoundingRectangle} defining a region of an existing image, measured in pixels from the bottom-left of the image.
+ * @param {number} imageIndex The index of the image.
+ * @returns {Promise<number> | number | undefined} The existing subRegion index, or undefined if not yet added.
+ */
+TextureAtlas.prototype.getCachedImageSubRegion = function (
+  id,
+  subRegion,
+  imageIndex,
+) {
+  const imagePromise = this._indexPromiseById.get(id);
+  for (const [index, parentIndex] of this._subRegions.entries()) {
+    if (imageIndex === parentIndex) {
+      const boundingRegion = this._rectangles[index];
+      if (boundingRegion.equals(subRegion)) {
+        // The subregion is already being tracked
+        if (imagePromise) {
+          return imagePromise.then((resolvedImageIndex) =>
+            resolvedImageIndex === -1 ? -1 : index,
+          );
+        }
+        return index;
+      }
+    }
+  }
+};
+
 /**
  * Add a sub-region of an existing atlas image as additional image indices.
  * @private
  * @param {string} id The identifier of the existing image.
  * @param {BoundingRectangle} subRegion An {@link BoundingRectangle} defining a region of an existing image, measured in pixels from the bottom-left of the image.
- * @returns {Promise<number>} A Promise that resolves to the image region index. -1 is returned if resouces are in the process of being destroyed.
+ * @returns {number | Promise<number>} The resolved image region index, or a Promise that resolves to it. -1 is returned if resources are in the process of being destroyed.
  */
 TextureAtlas.prototype.addImageSubRegion = function (id, subRegion) {
   //>>includeStart('debug', pragmas.debug);
   Check.typeOf.string("id", id);
   Check.defined("subRegion", subRegion);
   //>>includeEnd('debug');
-
   const imageIndex = this._indexById.get(id);
   if (!defined(imageIndex)) {
     throw new RuntimeError(`image with id "${id}" not found in the atlas.`);
   }
 
-  const indexPromise = this._indexPromiseById.get(id);
-  for (const [index, parentIndex] of this._subRegions.entries()) {
-    if (imageIndex === parentIndex) {
-      const boundingRegion = this._rectangles[index];
-      if (boundingRegion.equals(subRegion)) {
-        // The subregion is already being tracked
-        return indexPromise.then((resolvedImageIndex) => {
-          if (resolvedImageIndex === -1) {
-            // The atlas has been destroyed
-            return -1;
-          }
-
-          return index;
-        });
-      }
-    }
+  let index = this.getCachedImageSubRegion(id, subRegion, imageIndex);
+  if (defined(index)) {
+    return index;
   }
 
-  const index = this._nextIndex++;
+  index = this._nextIndex++;
   this._subRegions.set(index, imageIndex);
   this._rectangles[index] = subRegion.clone();
 
+  const indexPromise =
+    this._indexPromiseById.get(id) ?? Promise.resolve(imageIndex);
+
   return indexPromise.then((imageIndex) => {
     if (imageIndex === -1) {
       // The atlas has been destroyed

package/Source/Scene/ArcGisMapService.js

@@ -4,7 +4,7 @@ import Resource from "../Core/Resource.js";
 
 let defaultTokenCredit;
 const defaultAccessToken =
-  "AAPTxy8BH1VEsoebNVZXo8HurEOF051kAEKlhkOhBEc9BmTlKbWoQXtdb-m2VclxMHo8eEPu_iyh95DPKVzeyNrKkb2zc_ICfJxY7tPEl4aVdWCyU_P18q9k6D26yO7pAVtbr3I-gxRJb412PB_FydyuNKYsVRiVLqJGaYOCYhJeY3Tv8USWG4TQVu6i2mMZ8CBE68HAd3DByIRkBcjQRnker5_UyWjO86QZxpbnykaqDtY.AT1_zMTIWhVd";
+  "AAPTxy8BH1VEsoebNVZXo8HurEOF051kAEKlhkOhBEc9BmT-YXumqp4JkvycMs8ZG2hKk2SGBrZlhKMqjDAD5-6Bfkm_qv2ikp3Q3QSZyA_gQmxc8WOi5Z38wPaDHFE06ozG_AMTUg2bOPx2B64azLZ2U4MPzYI01EWp4tZnTgEKEBA2S5ip51CE6gSm0glwVGSEMFb3jjJkxH2JvjWM8eU2sTTihBKpJWxbQYppczgBsdw.AT1_YjTi2kjL";
 /**
  * Default options for accessing the ArcGIS image tile service.
  *