@cesium/engine 26.1.0 → 26.2.0

package/Source/Core/VectorProvider.js

@@ -0,0 +1,429 @@
+// @ts-check
+
+import BufferPolygonCollection from "../Scene/BufferPolygonCollection.js";
+import BufferPolylineCollection from "../Scene/BufferPolylineCollection.js";
+import Rectangle from "./Rectangle.js";
+import defined from "./defined.js";
+import VectorPipeline from "./VectorPipeline.js";
+
+/** @import BufferPrimitive from "../Scene/BufferPrimitive.js"; */
+/** @import BufferPrimitiveCollection from "../Scene/BufferPrimitiveCollection.js"; */
+/** @import Context from "../Renderer/Context.js"; */
+/** @import Ellipsoid from "./Ellipsoid.js"; */
+/** @import TilingScheme from "./TilingScheme.js"; */
+/** @import { VectorCollectionData, VectorTileData } from "./VectorPipeline.js"; */
+
+/** @ignore */
+const scratchTileRectangle = new Rectangle();
+const scratchCollectionRectangle = new Rectangle();
+const scratchIntersectRectangle = new Rectangle();
+
+/**
+ * Extracts a collection's snapshot of projected positions and per-primitive
+ * material properties.
+ *
+ * @callback PackCollectionData
+ * @param {*} collection
+ * @param {TilingScheme} tilingScheme
+ * @param {VectorCollectionData} [result]
+ * @returns {VectorCollectionData}
+ * @private
+ */
+
+/**
+ * Packs a collection's primitives into a tile's vector data.
+ *
+ * @callback PackTilePrimitives
+ * @param {*} collection
+ * @param {VectorCollectionData} collectionData
+ * @param {Rectangle} rectangle
+ * @param {VectorTileData} result
+ * @returns {void}
+ * @private
+ */
+
+/**
+ * Packing functions for a collection type.
+ *
+ * @typedef {object} CollectionPacker
+ * @property {PackCollectionData} packCollectionData Extracts the per-collection snapshot.
+ * @property {PackTilePrimitives} packTilePrimitives Packs the collection's primitives into a tile.
+ * @private
+ */
+
+/**
+ * Per-type packing functions, keyed by collection class.
+ * @type {Map<Function, CollectionPacker>}
+ * @private
+ */
+const collectionPackers = new Map();
+collectionPackers.set(BufferPolylineCollection, {
+  packCollectionData: VectorPipeline.packPolylineCollectionData,
+  packTilePrimitives: VectorPipeline.packPolylineSegments,
+});
+collectionPackers.set(BufferPolygonCollection, {
+  packCollectionData: VectorPipeline.packPolygonCollectionData,
+  packTilePrimitives: VectorPipeline.packPolygonRings,
+});
+
+/**
+ * @typedef {object} VectorProviderConstructorOptions
+ * @property {TilingScheme} tilingScheme
+ * @private
+ */
+
+/**
+ * @ignore
+ */
+class VectorProvider {
+  /** @param {VectorProviderConstructorOptions} options */
+  constructor(options) {
+    /** @private */
+    this._tilingScheme = options.tilingScheme;
+
+    /**
+     * @type {Set<BufferPrimitiveCollection<BufferPrimitive>>}
+     * @private
+     */
+    this._collections = new Set();
+
+    /**
+     * Per-collection snapshot of projected positions and per-primitive
+     * material properties, keyed by collection version.
+     * @type {WeakMap<BufferPrimitiveCollection<BufferPrimitive>, VectorCollectionData>}
+     * @private
+     */
+    this._collectionDataCache = new WeakMap();
+
+    /**
+     * Collections marked selected this frame (only these are baked).
+     * @type {Set<BufferPrimitiveCollection<BufferPrimitive>>}
+     * @private
+     */
+    this._selectedThisFrame = new Set();
+
+    /**
+     * Collections added via markSelected (not add); only these are pruned.
+     * @type {Set<BufferPrimitiveCollection<BufferPrimitive>>}
+     * @private
+     */
+    this._selectionDriven = new Set();
+
+    /** @private */
+    this._selectionFrameNumber = -1;
+
+    /**
+     * Cartographic regions changed since the last
+     * {@link VectorProvider#makeClean}, so only overlapping terrain
+     * tiles are re-baked.
+     * @type {Rectangle[]}
+     * @private
+     */
+    this._dirtyRectangles = [];
+  }
+
+  /** @type {TilingScheme} */
+  get tilingScheme() {
+    return this._tilingScheme;
+  }
+
+  set tilingScheme(value) {
+    this._tilingScheme = value;
+  }
+
+  /** @type {Ellipsoid} */
+  get ellipsoid() {
+    return this._tilingScheme.ellipsoid;
+  }
+
+  /**
+   * @param {BufferPrimitiveCollection<BufferPrimitive>} collection
+   */
+  add(collection) {
+    const previousSize = this._collections.size;
+    this._collections.add(collection);
+    if (this._collections.size !== previousSize) {
+      this._markCollectionRegionDirty(collection);
+    }
+  }
+
+  /**
+   * @param {BufferPrimitiveCollection<BufferPrimitive>} collection
+   */
+  remove(collection) {
+    this._selectedThisFrame.delete(collection);
+    this._selectionDriven.delete(collection);
+    if (this._collections.delete(collection)) {
+      this._markCollectionRegionDirty(collection);
+    }
+  }
+
+  /**
+   * Marks a collection as selected this frame so it is baked; collections not
+   * marked are pruned next frame, keeping the baked set aligned with the
+   * rendered LOD.
+   *
+   * @param {BufferPrimitiveCollection<BufferPrimitive>} collection
+   * @param {number} frameNumber
+   */
+  markSelected(collection, frameNumber) {
+    if (frameNumber !== this._selectionFrameNumber) {
+      this._commitSelectedFrame();
+      this._selectionFrameNumber = frameNumber;
+    }
+    this._selectedThisFrame.add(collection);
+    this._selectionDriven.add(collection);
+    const previousSize = this._collections.size;
+    this._collections.add(collection);
+    if (this._collections.size !== previousSize) {
+      this._markCollectionRegionDirty(collection);
+    }
+  }
+
+  /**
+   * Prunes selection-driven collections not marked in the frame that just ended.
+   * @private
+   */
+  _commitSelectedFrame() {
+    for (const collection of this._selectionDriven) {
+      if (!this._selectedThisFrame.has(collection)) {
+        this._selectionDriven.delete(collection);
+        if (this._collections.delete(collection)) {
+          this._markCollectionRegionDirty(collection);
+        }
+      }
+    }
+    this._selectedThisFrame.clear();
+  }
+
+  /**
+   * Records a changed collection's region(s) so the next re-bake only touches
+   * overlapping tiles.
+   * @param {BufferPrimitiveCollection<BufferPrimitive>} collection
+   * @private
+   */
+  _markCollectionRegionDirty(collection) {
+    const collectionRectangle = Rectangle.fromBoundingSphere(
+      collection.boundingVolume,
+      this._tilingScheme.ellipsoid,
+      new Rectangle(),
+    );
+    this._dirtyRectangles.push(collectionRectangle);
+  }
+
+  /**
+   * @param {number} x
+   * @param {number} y
+   * @param {number} level
+   * @param {Context} context
+   * @returns {VectorTileData}
+   */
+  requestTileData(x, y, level, context) {
+    const tilingScheme = this._tilingScheme;
+    const tileRectangle = tilingScheme.tileXYToRectangle(x, y, level);
+
+    /** @type {VectorTileData} */
+    const result = { show: true };
+
+    for (const collection of this._collections) {
+      const packer = collectionPackers.get(collection.constructor);
+      if (!defined(packer)) {
+        continue;
+      }
+
+      const collectionRectangle = Rectangle.fromBoundingSphere(
+        collection.boundingVolume,
+        tilingScheme.ellipsoid,
+        scratchCollectionRectangle,
+      );
+
+      const isIntersected = !!Rectangle.intersection(
+        tileRectangle,
+        collectionRectangle,
+        scratchIntersectRectangle,
+      );
+
+      if (!isIntersected) {
+        continue;
+      }
+
+      const collectionData = this._getCollectionDataCached(
+        collection,
+        packer.packCollectionData,
+      );
+      packer.packTilePrimitives(
+        collection,
+        collectionData,
+        tileRectangle,
+        result,
+      );
+    }
+
+    const hasPolylines =
+      defined(result.polylineSegments) && result.polylineSegments.length > 0;
+    const hasPolygons =
+      defined(result.polygonRings) && result.polygonRings.length > 0;
+
+    if (!hasPolylines && !hasPolygons) {
+      result.show = false;
+      return result;
+    }
+
+    if (hasPolylines) {
+      VectorPipeline.packPolylineGrid(result);
+      VectorPipeline.packPolylineTextures(context, result);
+    }
+
+    if (hasPolygons) {
+      VectorPipeline.packPolygonGrid(result);
+      VectorPipeline.packPolygonTextures(context, result);
+    }
+
+    VectorPipeline.packPrimitiveTextures(context, result);
+
+    return result;
+  }
+
+  /**
+   * @param {VectorTileData} data
+   */
+  releaseTileData(data) {
+    VectorPipeline.freeResources(data);
+  }
+
+  /**
+   * Re-bakes a tile's vector data if the tile overlaps a region changed since
+   * the last {@link VectorProvider#makeClean}, releasing the previous data.
+   * Returns the current data unchanged when the tile is outside every changed
+   * region.
+   *
+   * @param {number} x
+   * @param {number} y
+   * @param {number} level
+   * @param {Context} context
+   * @param {VectorTileData|undefined} currentData
+   * @returns {VectorTileData|undefined}
+   */
+  updateTileData(x, y, level, context, currentData) {
+    const dirtyRectangles = this._dirtyRectangles;
+    const tilingScheme = this._tilingScheme;
+    if (!intersectRectangles(x, y, level, dirtyRectangles, tilingScheme)) {
+      return currentData;
+    }
+
+    if (defined(currentData)) {
+      this.releaseTileData(currentData);
+    }
+
+    return this.requestTileData(x, y, level, context);
+  }
+
+  /**
+   * Clears the regions recorded as changed. Call once after a re-bake pass has
+   * updated the overlapping tiles via {@link VectorProvider#updateTileData}.
+   */
+  makeClean() {
+    this._dirtyRectangles.length = 0;
+  }
+
+  /**
+   * Records dirty regions for collections whose content has changed since
+   * their last extraction, so overlapping tiles are re-baked. Call once per
+   * frame, before {@link VectorProvider#updateTileData}.
+   */
+  update() {
+    for (const collection of this._collections) {
+      const cache = this._collectionDataCache.get(collection);
+      if (!defined(cache)) {
+        // Never extracted; new tiles bake on request.
+        continue;
+      }
+      const changed =
+        collection._dirtyCount > 0 || cache.version !== collection._version;
+      if (!changed) {
+        continue;
+      }
+      // Re-bake both the previously baked region (content may have moved
+      // away from it) and the collection's current region.
+      if (defined(cache.rectangle)) {
+        this._dirtyRectangles.push(Rectangle.clone(cache.rectangle));
+      }
+      this._markCollectionRegionDirty(collection);
+    }
+  }
+
+  /**
+   * Returns the collection's {@link VectorCollectionData} snapshot,
+   * re-extracted when the collection has changed. The collection is marked
+   * clean only after everything has been read back.
+   *
+   * @param {BufferPrimitiveCollection<BufferPrimitive>} collection
+   * @param {PackCollectionData} packCollectionData
+   * @returns {VectorCollectionData}
+   * @private
+   */
+  _getCollectionDataCached(collection, packCollectionData) {
+    const cache = this._collectionDataCache.get(collection);
+    const dirty = collection._dirtyCount > 0;
+    const outdated = cache?.version !== collection._version;
+
+    if (defined(cache) && !dirty && !outdated) {
+      return cache;
+    }
+
+    const data = packCollectionData(collection, this._tilingScheme, cache);
+
+    // If dirty, the version increments +1 when marked clean below.
+    data.version = collection._version + (dirty ? 1 : 0);
+    data.rectangle = Rectangle.fromBoundingSphere(
+      collection.boundingVolume,
+      this.ellipsoid,
+      data.rectangle,
+    );
+    this._collectionDataCache.set(collection, data);
+
+    collection._makeClean();
+
+    return data;
+  }
+}
+
+/**
+ * @param {number} x
+ * @param {number} y
+ * @param {number} level
+ * @param {Rectangle[]} rectangles
+ * @param {TilingScheme} tilingScheme
+ * @returns {boolean}
+ * @private
+ */
+function intersectRectangles(x, y, level, rectangles, tilingScheme) {
+  // No dirty regions recorded — nothing to re-bake. A caller needing a full
+  // re-bake should record Rectangle.MAX_VALUE instead.
+  if (rectangles.length === 0) {
+    return false;
+  }
+
+  const tileRectangle = tilingScheme.tileXYToRectangle(
+    x,
+    y,
+    level,
+    scratchTileRectangle,
+  );
+
+  for (let i = 0; i < rectangles.length; i++) {
+    const isIntersected = Rectangle.intersection(
+      tileRectangle,
+      rectangles[i],
+      scratchIntersectRectangle,
+    );
+
+    if (isIntersected) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+export default VectorProvider;

package/Source/Core/WallOutlineGeometry.js

@@ -419,7 +419,7 @@ WallOutlineGeometry.createGeometry = function (wallGeometry) {
   }
 
   indices[edgeIndex++] = numVertices - 2;
-  indices[edgeIndex++] = numVertices - 1;
+  indices[edgeIndex] = numVertices - 1;
 
   return new Geometry({
     attributes: attributes,

package/Source/Core/getTimestamp.js

@@ -1,11 +1,12 @@
+// @ts-check
+
 /**
  * Gets a timestamp that can be used in measuring the time between events.  Timestamps
  * are expressed in milliseconds, but it is not specified what the milliseconds are
  * measured from.  This function uses performance.now() if it is available, or Date.now()
  * otherwise.
- *
+ * @type {Function}
  * @function getTimestamp
- *
  * @returns {number} The timestamp in milliseconds since some unspecified reference time.
  */
 let getTimestamp;
@@ -23,4 +24,5 @@ if (
     return Date.now();
   };
 }
+
 export default getTimestamp;

package/Source/DataSources/CompositeEntityCollection.js

@@ -218,7 +218,6 @@ CompositeEntityCollection.prototype.addCollection = function (
   //>>includeEnd('debug');
 
   if (!hasIndex) {
-    index = this._collections.length;
     this._collections.push(collection);
   } else {
     this._collections.splice(index, 0, collection);

package/Source/DataSources/CzmlDataSource.js

@@ -497,6 +497,8 @@ function getPropertyType(czmlInterval) {
     return Object;
   } else if (czmlInterval.hasOwnProperty("unitQuaternion")) {
     return Quaternion;
+  } else if (czmlInterval.hasOwnProperty("pathMode")) {
+    return PathMode;
   } else if (czmlInterval.hasOwnProperty("shadowMode")) {
     return ShadowMode;
   } else if (czmlInterval.hasOwnProperty("string")) {

package/Source/DataSources/DataSourceDisplay.js

@@ -415,7 +415,7 @@ DataSourceDisplay.prototype.getBoundingSphere = function (
   const tmp = getBoundingSphereBoundingSphereScratch;
 
   let count = 0;
-  let state = BoundingSphereState.DONE;
+  let state;
   const visualizers = dataSource._visualizers;
   const visualizersLength = visualizers.length;
 

package/Source/DataSources/GeoJsonDataSource.js

@@ -149,7 +149,6 @@ function createObject(geoJson, entityCollection, describe) {
           const lowerKey = key.toLowerCase();
 
           if (namePropertyPrecedence > 1 && lowerKey === "title") {
-            namePropertyPrecedence = 1;
             nameProperty = key;
             break;
           } else if (namePropertyPrecedence > 2 && lowerKey === "name") {

package/Source/DataSources/GeometryVisualizer.js

@@ -336,7 +336,7 @@ GeometryVisualizer.prototype.getBoundingSphere = function (entity, result) {
   const tmp = getBoundingSphereBoundingSphereScratch;
 
   let count = 0;
-  let state = BoundingSphereState.DONE;
+  let state;
   const batches = this._batches;
   const batchesLength = batches.length;
 

package/Source/DataSources/KmlDataSource.js

@@ -1495,9 +1495,8 @@ function processPositionGraphics(
     billboard.image = undefined;
   }
 
-  let scale = 1.0;
   if (defined(billboard.scale)) {
-    scale = billboard.scale.getValue();
+    const scale = billboard.scale.getValue();
     if (scale !== 0) {
       label.pixelOffset = new Cartesian2(scale * 16 + 1, 0);
     } else {

package/Source/DataSources/PolylineVisualizer.js

@@ -295,7 +295,7 @@ PolylineVisualizer.prototype.getBoundingSphere = function (entity, result) {
   const tmp = getBoundingSphereBoundingSphereScratch;
 
   let count = 0;
-  let state = BoundingSphereState.DONE;
+  let state;
   const batches = this._batches;
   const batchesLength = batches.length;
   const updater = this._updaters.get(entity.id);

package/Source/DataSources/StaticOutlineGeometryBatch.js

@@ -375,7 +375,7 @@ StaticOutlineGeometryBatch.prototype.update = function (time) {
   const translucentBatchesLength = translucentBatches.length;
   let itemsToRemove;
   let isUpdated = true;
-  let needUpdate = false;
+  let needUpdate;
 
   do {
     needUpdate = false;

package/Source/Renderer/AutomaticUniforms.js

@@ -222,6 +222,29 @@ const AutomaticUniforms = {
     },
   }),
 
+  /**
+   * An automatic GLSL uniform containing the feature-ID texture produced by
+   * the planar fill pre-pass (BENTLEY_materials_planar_fill). Non-behind
+   * planar fill geometry writes its per-fragment feature ID here so that
+   * behind fills can test whether the existing pixel belongs to the same
+   * logical object.
+   *
+   * @example
+   * // GLSL declaration
+   * uniform sampler2D czm_planarFillIdTexture;
+   *
+   * // Sample
+   * vec2 coords = gl_FragCoord.xy / czm_viewport.zw;
+   * float existingFeatureId = texture(czm_planarFillIdTexture, coords).r;
+   */
+  czm_planarFillIdTexture: new AutomaticUniform({
+    size: 1,
+    datatype: WebGLConstants.SAMPLER_2D,
+    getValue: function (uniformState) {
+      return uniformState.planarFillIdTexture;
+    },
+  }),
+
   /**
    * An automatic GLSL uniform representing a 4x4 model transformation matrix that
    * transforms model coordinates to world coordinates.

package/Source/Renderer/Context.js

@@ -1010,20 +1010,26 @@ Object.defineProperties(Context.prototype, {
   },
 
   /**
-   * A 1x1 RGBA texture initialized to [255, 255, 255, 255].  This can
-   * be used as a placeholder texture while other textures are downloaded.
+   * A 1x1 RGBA texture initialized to the color defined by {@link Texture.defaultColor}.
+   * This can be used as a placeholder texture while other textures are downloaded.
    * @memberof Context.prototype
    * @type {Texture}
    */
   defaultTexture: {
     get: function () {
       if (this._defaultTexture === undefined) {
+        const color = Texture.defaultColor;
         this._defaultTexture = new Texture({
           context: this,
           source: {
             width: 1,
             height: 1,
-            arrayBufferView: new Uint8Array([255, 255, 255, 255]),
+            arrayBufferView: new Uint8Array([
+              color.red * 255,
+              color.green * 255,
+              color.blue * 255,
+              color.alpha * 255,
+            ]),
           },
           flipY: false,
         });

package/Source/Renderer/DrawCommand.js

@@ -47,6 +47,7 @@ const Flags = {
  * @property {Pass} [pass]
  * @property {object} [owner]
  * @property {string} [pickId]
+ * @property {string} [snapId]
  * @property {boolean} [pickMetadataAllowed=false]
  * @property {boolean} [cull=true]
  * @property {boolean} [occlude=true]
@@ -102,6 +103,7 @@ class DrawCommand {
     this._debugOverlappingFrustums = 0;
     /** @private */
     this._pickId = options.pickId;
+    this._snapId = options.snapId;
     /** @private */
     this._pickMetadataAllowed = options.pickMetadataAllowed === true;
     /**
@@ -532,6 +534,25 @@ class DrawCommand {
     }
   }
 
+  /**
+   * A GLSL string that will evaluate to the float snap payload written during
+   * a snapping pass (see {@link Scene#snap}). When <code>undefined</code>, the
+   * command does not render during a snapping pass.
+   *
+   * @type {string|undefined}
+   * @default undefined
+   */
+  get snapId() {
+    return this._snapId;
+  }
+
+  set snapId(value) {
+    if (this._snapId !== value) {
+      this._snapId = value;
+      this.dirty = true;
+    }
+  }
+
   /**
    * Whether metadata picking is allowed.
    *
@@ -628,6 +649,7 @@ class DrawCommand {
     result._owner = command._owner;
     result._debugOverlappingFrustums = command._debugOverlappingFrustums;
     result._pickId = command._pickId;
+    result._snapId = command._snapId;
     result._pickMetadataAllowed = command._pickMetadataAllowed;
     result._pickedMetadataInfo = command._pickedMetadataInfo;
     result._flags = command._flags;

package/Source/Renderer/Framebuffer.js

@@ -287,6 +287,10 @@ function Framebuffer(options) {
   }
 
   this._unBind();
+
+  // _bind and _unBind bypass the context's framebuffer binding cache. The GL
+  // binding is now the default framebuffer; update the cache to match.
+  context._currentFramebuffer = undefined;
 }
 
 Object.defineProperties(Framebuffer.prototype, {

package/Source/Renderer/Pass.js

@@ -19,16 +19,17 @@ const Pass = {
   GLOBE: 2,
   TERRAIN_CLASSIFICATION: 3,
   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,
-  CESIUM_3D_TILE_EDGES_DIRECT: 12,
-  OVERLAY: 13,
-  NUMBER_OF_PASSES: 14,
+  CESIUM_3D_TILE_PLANAR_FILL_ID: 5,
+  CESIUM_3D_TILE: 6,
+  CESIUM_3D_TILE_CLASSIFICATION: 7,
+  CESIUM_3D_TILE_CLASSIFICATION_IGNORE_SHOW: 8,
+  OPAQUE: 9,
+  TRANSLUCENT: 10,
+  VOXELS: 11,
+  GAUSSIAN_SPLATS: 12,
+  CESIUM_3D_TILE_EDGES_DIRECT: 13,
+  OVERLAY: 14,
+  NUMBER_OF_PASSES: 15,
 };
 
 Object.freeze(Pass);