@cesium/engine 21.0.1 → 22.1.0

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";
@@ -356,7 +357,7 @@ function Context(canvas, options) {
     this._vertexAttribDivisors.push(0);
   }
 
-  this._pickObjects = {};
+  this._pickObjects = new Map();
   this._nextPickColor = new Uint32Array(1);
 
   /**
@@ -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 {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 {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 {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,
@@ -1562,7 +1640,7 @@ Context.prototype.createViewportQuadCommand = function (
 /**
  * Gets the object associated with a pick color.
  *
- * @param {Color} pickColor The pick color.
+ * @param {number} pickColor The unsigned 32-bit RGBA pick color
  * @returns {object} The object associated with the pick color, or undefined if no object is associated with that color.
  *
  * @example
@@ -1575,9 +1653,15 @@ Context.prototype.getObjectByPickColor = function (pickColor) {
   Check.defined("pickColor", pickColor);
   //>>includeEnd('debug');
 
-  return this._pickObjects[pickColor.toRgba()];
+  return this._pickObjects.get(pickColor);
 };
 
+/**
+ *
+ * @param {Map<number, object>} pickObjects
+ * @param {number} key
+ * @param {Color} color
+ */
 function PickId(pickObjects, key, color) {
   this._pickObjects = pickObjects;
   this.key = key;
@@ -1587,16 +1671,16 @@ function PickId(pickObjects, key, color) {
 Object.defineProperties(PickId.prototype, {
   object: {
     get: function () {
-      return this._pickObjects[this.key];
+      return this._pickObjects.get(this.key);
     },
     set: function (value) {
-      this._pickObjects[this.key] = value;
+      this._pickObjects.set(this.key, value);
     },
   },
 });
 
 PickId.prototype.destroy = function () {
-  delete this._pickObjects[this.key];
+  this._pickObjects.delete(this.key);
   return undefined;
 };
 
@@ -1633,7 +1717,7 @@ Context.prototype.createPickId = function (object) {
     throw new RuntimeError("Out of unique Pick IDs.");
   }
 
-  this._pickObjects[key] = object;
+  this._pickObjects.set(key, object);
   return new PickId(this._pickObjects, key, Color.fromRgba(key));
 };
 

package/Source/Renderer/Pass.js

@@ -15,14 +15,15 @@ const Pass = {
   COMPUTE: 1,
   GLOBE: 2,
   TERRAIN_CLASSIFICATION: 3,
-  CESIUM_3D_TILE: 4,
-  CESIUM_3D_TILE_CLASSIFICATION: 5,
-  CESIUM_3D_TILE_CLASSIFICATION_IGNORE_SHOW: 6,
-  OPAQUE: 7,
-  TRANSLUCENT: 8,
-  VOXELS: 9,
-  GAUSSIAN_SPLATS: 10,
-  OVERLAY: 11,
-  NUMBER_OF_PASSES: 12,
+  CESIUM_3D_TILE_EDGES: 4,
+  CESIUM_3D_TILE: 5,
+  CESIUM_3D_TILE_CLASSIFICATION: 6,
+  CESIUM_3D_TILE_CLASSIFICATION_IGNORE_SHOW: 7,
+  OPAQUE: 8,
+  TRANSLUCENT: 9,
+  VOXELS: 10,
+  GAUSSIAN_SPLATS: 11,
+  OVERLAY: 12,
+  NUMBER_OF_PASSES: 13,
 };
 export default Object.freeze(Pass);

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;
 }
@@ -644,34 +648,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 +700,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/Renderer/UniformState.js

@@ -25,6 +25,18 @@ function UniformState() {
    * @type {Texture}
    */
   this.globeDepthTexture = undefined;
+  /**
+   * @type {Texture}
+   */
+  this.edgeIdTexture = undefined;
+  /**
+   * @type {Texture}
+   */
+  this.edgeColorTexture = undefined;
+  /**
+   * @type {Texture}
+   */
+  this.edgeDepthTexture = undefined; // packed depth color attachment from edge pass
   /**
    * @type {number}
    */

package/Source/Renderer/VertexArray.js

@@ -178,7 +178,7 @@ function bind(gl, attributes, indexBuffer) {
  *
  * @param {object} options Object with the following properties:
  * @param {Context} options.context The context in which the VertexArray gets created.
- * @param {Object[]} options.attributes An array of attributes.
+ * @param {object[]} options.attributes An array of attributes.
  * @param {IndexBuffer} [options.indexBuffer] An optional index buffer.
  *
  * @returns {VertexArray} The vertex array, ready for use with drawing.

package/Source/Scene/ArcGisMapServerImageryProvider.js

@@ -681,7 +681,7 @@ Object.defineProperties(ArcGisMapServerImageryProvider.prototype, {
  * Creates an {@link ImageryProvider} which provides tiled imagery hosted by an ArcGIS MapServer.  By default, the server's pre-cached tiles are
  * used, if available.
  *
- * @param {Resource|String} url The URL of the ArcGIS MapServer service.
+ * @param {Resource|string} url The URL of the ArcGIS MapServer service.
  * @param {ArcGisMapServerImageryProvider.ConstructorOptions} [options] Object describing initialization options.
  * @returns {Promise<ArcGisMapServerImageryProvider>} A promise that resolves to the created ArcGisMapServerImageryProvider.
  *

package/Source/Scene/ArcGisMapService.js

@@ -4,7 +4,7 @@ import Resource from "../Core/Resource.js";
 
 let defaultTokenCredit;
 const defaultAccessToken =
-  "AAPTxy8BH1VEsoebNVZXo8HurEOF051kAEKlhkOhBEc9BmQqEeLjCLZBBnNm_y_K-Cs-tuPcsgUmlxDWvPdTmGIEhrihfZMTG77j2nmCeqeYCPAenHGG1YfJqJaeRLuy5YjARJcFLP2I_judomiDS-8A_LVZxWUObwIQNE5wcsQKxJl7RHiKm-81XRDuUJZXGqy9B4PwPxWkS-N9PZ7NmTT-sP6BOGn5ouiAN8dkxwNx3tA.AT1_BU0Co4D8";
+  "AAPTxy8BH1VEsoebNVZXo8HurEOF051kAEKlhkOhBEc9BmRA_-es9rk59JndtXxJExAf4pmezE6N8auY2oiYF7U6dXh7yRaT1sNQtBY9wlqlw0devC6v78rHPdmwJcUuC_MbH3liCP4RLfDGesom_8vT8bbbaPe8MoNz66fpwDaRk4lfCE9paNVC2Mx1K0Dgg7eJJ4TF14HaUnSgkHUcR7gLbj_277ZHX9P-QkLR9Tqcf_Y.AT1_7xNXmYif";
 /**
  * Default options for accessing the ArcGIS image tile service.
  *