@cesium/engine 26.2.0 → 26.3.0

package/Source/Core/VectorProvider.js

@@ -2,6 +2,11 @@
 
 import BufferPolygonCollection from "../Scene/BufferPolygonCollection.js";
 import BufferPolylineCollection from "../Scene/BufferPolylineCollection.js";
+import DeveloperError from "./DeveloperError.js";
+import HeightReference, {
+  isHeightReferenceClamp,
+} from "../Scene/HeightReference.js";
+import Cartesian2 from "./Cartesian2.js";
 import Rectangle from "./Rectangle.js";
 import defined from "./defined.js";
 import VectorPipeline from "./VectorPipeline.js";
@@ -24,7 +29,7 @@ const scratchIntersectRectangle = new Rectangle();
  *
  * @callback PackCollectionData
  * @param {*} collection
- * @param {TilingScheme} tilingScheme
+ * @param {Ellipsoid} ellipsoid
  * @param {VectorCollectionData} [result]
  * @returns {VectorCollectionData}
  * @private
@@ -69,6 +74,10 @@ collectionPackers.set(BufferPolygonCollection, {
 /**
  * @typedef {object} VectorProviderConstructorOptions
  * @property {TilingScheme} tilingScheme
+ * @property {boolean} [antialias=true] Whether to fade draped polyline edges over the pixel
+ * straddling them. Disabling this is faster but leaves the edges aliased.
+ * @property {number} [minimumTileScreenPixels=256] Lower bound on the screen size, in pixels, of
+ * a tile baked by this provider.
  * @private
  */
 
@@ -82,10 +91,31 @@ class VectorProvider {
     this._tilingScheme = options.tilingScheme;
 
     /**
-     * @type {Set<BufferPrimitiveCollection<BufferPrimitive>>}
+     * Whether to fade draped polyline edges over the pixel straddling them.
+     * Disabling this is faster but leaves the edges aliased.
+     *
+     * @type {boolean}
+     * @default true
+     */
+    this.antialias = options.antialias ?? true;
+
+    /**
+     * Lower bound on the screen size, in pixels, of a tile baked by this provider. Line widths are
+     * in screen pixels but baking has no camera, so this is what converts them to tile UV. The
+     * surface consuming the tiles is expected to derive it from its own refinement criterion.
+     *
+     * @type {number}
+     * @default 256
+     */
+    this.minimumTileScreenPixels = options.minimumTileScreenPixels ?? 256.0;
+
+    /**
+     * Marked collections, mapped to the {@link HeightReference} they were marked
+     * with, which determines the surfaces they are draped onto.
+     * @type {Map<BufferPrimitiveCollection<BufferPrimitive>, HeightReference>}
      * @private
      */
-    this._collections = new Set();
+    this._heightReferenceByCollection = new Map();
 
     /**
      * Per-collection snapshot of projected positions and per-primitive
@@ -96,21 +126,14 @@ class VectorProvider {
     this._collectionDataCache = new WeakMap();
 
     /**
-     * Collections marked selected this frame (only these are baked).
+     * Collections marked 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();
+    this._markedThisFrame = new Set();
 
     /** @private */
-    this._selectionFrameNumber = -1;
+    this._markedFrameNumber = -1;
 
     /**
      * Cartographic regions changed since the last
@@ -137,63 +160,99 @@ class VectorProvider {
   }
 
   /**
+   * Drops a collection immediately, rather than waiting for it to be pruned by
+   * the next {@link VectorProvider#update}. Call when a collection is destroyed,
+   * so that it is never draped after its buffers are released.
+   *
    * @param {BufferPrimitiveCollection<BufferPrimitive>} collection
    */
-  add(collection) {
-    const previousSize = this._collections.size;
-    this._collections.add(collection);
-    if (this._collections.size !== previousSize) {
+  remove(collection) {
+    this._markedThisFrame.delete(collection);
+    if (this._heightReferenceByCollection.delete(collection)) {
       this._markCollectionRegionDirty(collection);
     }
   }
 
   /**
+   * Whether a collection is currently being draped, that is, whether it has
+   * been marked and not yet pruned or removed.
+   *
    * @param {BufferPrimitiveCollection<BufferPrimitive>} collection
+   * @returns {boolean}
    */
-  remove(collection) {
-    this._selectedThisFrame.delete(collection);
-    this._selectionDriven.delete(collection);
-    if (this._collections.delete(collection)) {
-      this._markCollectionRegionDirty(collection);
-    }
+  has(collection) {
+    return this._heightReferenceByCollection.has(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.
+   * Whether draping is supported for the given collection's type. Callers must
+   * render unsupported collections themselves.
+   *
+   * @param {BufferPrimitiveCollection<BufferPrimitive>} collection
+   * @returns {boolean}
+   */
+  static isSupported(collection) {
+    return collectionPackers.has(collection.constructor);
+  }
+
+  /**
+   * Marks a collection as draped for this frame; collections not marked are
+   * pruned next frame, keeping the draped set aligned with the rendered LOD.
    *
    * @param {BufferPrimitiveCollection<BufferPrimitive>} collection
    * @param {number} frameNumber
+   * @param {HeightReference} heightReference The surfaces the collection is
+   *   draped onto: {@link HeightReference.CLAMP_TO_TERRAIN} for the globe,
+   *   {@link HeightReference.CLAMP_TO_3D_TILE} for 3D Tiles, or
+   *   {@link HeightReference.CLAMP_TO_GROUND} for both.
    */
-  markSelected(collection, frameNumber) {
-    if (frameNumber !== this._selectionFrameNumber) {
-      this._commitSelectedFrame();
-      this._selectionFrameNumber = frameNumber;
+  markForFrame(collection, frameNumber, heightReference) {
+    //>>includeStart('debug', pragmas.debug);
+    if (!VectorProvider.isSupported(collection)) {
+      throw new DeveloperError(
+        `Draping is not supported for ${collection.constructor.name}. Check VectorProvider.isSupported before marking a collection.`,
+      );
     }
-    this._selectedThisFrame.add(collection);
-    this._selectionDriven.add(collection);
-    const previousSize = this._collections.size;
-    this._collections.add(collection);
-    if (this._collections.size !== previousSize) {
+    if (!isHeightReferenceClamp(heightReference)) {
+      throw new DeveloperError(
+        "heightReference must be CLAMP_TO_GROUND, CLAMP_TO_TERRAIN, or CLAMP_TO_3D_TILE.",
+      );
+    }
+    //>>includeEnd('debug');
+
+    this._beginFrame(frameNumber);
+    this._markedThisFrame.add(collection);
+
+    if (!this._heightReferenceByCollection.has(collection)) {
       this._markCollectionRegionDirty(collection);
     }
+
+    this._heightReferenceByCollection.set(collection, heightReference);
   }
 
   /**
-   * Prunes selection-driven collections not marked in the frame that just ended.
+   * Prunes the previous frame's unmarked collections when a new frame begins.
+   * Called both from {@link VectorProvider#markForFrame} and once per frame
+   * from {@link VectorProvider#update}, so that a frame in which nothing is
+   * marked still prunes the collections left over from the frame before it.
+   *
+   * @param {number} frameNumber
    * @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);
-        }
+  _beginFrame(frameNumber) {
+    if (frameNumber === this._markedFrameNumber) {
+      return;
+    }
+
+    for (const collection of this._heightReferenceByCollection.keys()) {
+      if (!this._markedThisFrame.has(collection)) {
+        this._heightReferenceByCollection.delete(collection);
+        this._markCollectionRegionDirty(collection);
       }
     }
-    this._selectedThisFrame.clear();
+    this._markedThisFrame.clear();
+
+    this._markedFrameNumber = frameNumber;
   }
 
   /**
@@ -216,18 +275,55 @@ class VectorProvider {
    * @param {number} y
    * @param {number} level
    * @param {Context} context
+   * @param {HeightReference} targetHeightReference The kind of
+   *   surface the data is baked for, either {@link HeightReference.CLAMP_TO_TERRAIN} or
+   *   {@link HeightReference.CLAMP_TO_3D_TILE}. Only collections draped onto that surface are
+   *   included.
    * @returns {VectorTileData}
    */
-  requestTileData(x, y, level, context) {
+  requestTileData(x, y, level, context, targetHeightReference) {
+    const tileRectangle = this._tilingScheme.tileXYToRectangle(
+      x,
+      y,
+      level,
+      scratchTileRectangle,
+    );
+    return this.requestDataForRectangle(
+      tileRectangle,
+      context,
+      targetHeightReference,
+    );
+  }
+
+  /**
+   * Bakes vector lookup data for an arbitrary cartographic rectangle, such as
+   * a 3D Tiles content's bounding region.
+   *
+   * @param {Rectangle} rectangle
+   * @param {Context} context
+   * @param {HeightReference} targetHeightReference The kind of
+   *   surface the data is baked for, either {@link HeightReference.CLAMP_TO_TERRAIN} or
+   *   {@link HeightReference.CLAMP_TO_3D_TILE}. Only collections draped onto that surface are
+   *   included.
+   * @returns {VectorTileData}
+   */
+  requestDataForRectangle(rectangle, context, targetHeightReference) {
     const tilingScheme = this._tilingScheme;
-    const tileRectangle = tilingScheme.tileXYToRectangle(x, y, level);
+    const heightReferenceByCollection = this._heightReferenceByCollection;
 
     /** @type {VectorTileData} */
-    const result = { show: true };
-
-    for (const collection of this._collections) {
-      const packer = collectionPackers.get(collection.constructor);
-      if (!defined(packer)) {
+    const result = {
+      show: true,
+      hasPolylines: false,
+      hasPolygons: false,
+      rectangle: Rectangle.clone(rectangle),
+      collectionVersions: new Map(),
+      minimumTileScreenPixels: this.minimumTileScreenPixels,
+      metersPerUv: computeMetersPerUv(rectangle, tilingScheme.ellipsoid),
+    };
+
+    for (const [collection, heightReference] of heightReferenceByCollection) {
+      if (!targetsSurface(heightReference, targetHeightReference)) {
         continue;
       }
 
@@ -238,7 +334,7 @@ class VectorProvider {
       );
 
       const isIntersected = !!Rectangle.intersection(
-        tileRectangle,
+        rectangle,
         collectionRectangle,
         scratchIntersectRectangle,
       );
@@ -247,22 +343,25 @@ class VectorProvider {
         continue;
       }
 
+      // Guaranteed by the VectorProvider.isSupported check in markForFrame.
+      const packer = /** @type {CollectionPacker} */ (
+        collectionPackers.get(collection.constructor)
+      );
+
       const collectionData = this._getCollectionDataCached(
         collection,
         packer.packCollectionData,
       );
-      packer.packTilePrimitives(
-        collection,
-        collectionData,
-        tileRectangle,
-        result,
-      );
+      result.collectionVersions.set(collection, collectionData.version);
+      packer.packTilePrimitives(collection, collectionData, rectangle, result);
     }
 
     const hasPolylines =
       defined(result.polylineSegments) && result.polylineSegments.length > 0;
     const hasPolygons =
       defined(result.polygonRings) && result.polygonRings.length > 0;
+    result.hasPolylines = hasPolylines;
+    result.hasPolygons = hasPolygons;
 
     if (!hasPolylines && !hasPolygons) {
       result.show = false;
@@ -301,21 +400,118 @@ class VectorProvider {
    * @param {number} y
    * @param {number} level
    * @param {Context} context
-   * @param {VectorTileData|undefined} currentData
-   * @returns {VectorTileData|undefined}
+   * @param {VectorTileData} currentData
+   * @param {HeightReference} targetHeightReference Either
+   *   {@link HeightReference.CLAMP_TO_TERRAIN} or {@link HeightReference.CLAMP_TO_3D_TILE}.
+   * @returns {VectorTileData}
    */
-  updateTileData(x, y, level, context, currentData) {
+  updateTileData(x, y, level, context, currentData, targetHeightReference) {
     const dirtyRectangles = this._dirtyRectangles;
     const tilingScheme = this._tilingScheme;
     if (!intersectRectangles(x, y, level, dirtyRectangles, tilingScheme)) {
       return currentData;
     }
 
-    if (defined(currentData)) {
-      this.releaseTileData(currentData);
+    this.releaseTileData(currentData);
+
+    return this.requestTileData(x, y, level, context, targetHeightReference);
+  }
+
+  /**
+   * Re-bakes vector data for an arbitrary rectangle when the collections it was
+   * baked from have changed. Unlike {@link VectorProvider#updateTileData}, this
+   * does not consult {@link VectorProvider#_dirtyRectangles} — they are cleared
+   * each frame by {@link VectorProvider#makeClean}, which consumers outside the
+   * terrain pass cannot rely on observing — so staleness is instead detected by
+   * comparing the collection versions recorded when the data was baked.
+   *
+   * @param {Rectangle} rectangle
+   * @param {Context} context
+   * @param {VectorTileData} currentData
+   * @param {HeightReference} targetHeightReference Either
+   *   {@link HeightReference.CLAMP_TO_TERRAIN} or {@link HeightReference.CLAMP_TO_3D_TILE}.
+   * @returns {VectorTileData}
+   */
+  updateDataForRectangle(
+    rectangle,
+    context,
+    currentData,
+    targetHeightReference,
+  ) {
+    if (!this._isStale(currentData, rectangle, targetHeightReference)) {
+      return currentData;
+    }
+
+    this.releaseTileData(currentData);
+
+    return this.requestDataForRectangle(
+      rectangle,
+      context,
+      targetHeightReference,
+    );
+  }
+
+  /**
+   * Whether baked data no longer reflects the collections overlapping its
+   * rectangle. Stale when a collection it was baked from has changed, when a
+   * collection has left the rectangle or been pruned, or when a collection has
+   * moved into the rectangle since the bake.
+   *
+   * @param {VectorTileData} data
+   * @param {Rectangle} rectangle
+   * @param {HeightReference} targetHeightReference
+   * @returns {boolean}
+   * @private
+   */
+  _isStale(data, rectangle, targetHeightReference) {
+    // The rectangle itself can change, such as when a model moves.
+    if (!Rectangle.equals(data.rectangle, rectangle)) {
+      return true;
+    }
+
+    const bakedVersions = data.collectionVersions;
+    const heightReferenceByCollection = this._heightReferenceByCollection;
+    let bakedVersionsVisited = 0;
+
+    for (const [collection, heightReference] of heightReferenceByCollection) {
+      if (!targetsSurface(heightReference, targetHeightReference)) {
+        continue;
+      }
+
+      const collectionRectangle = Rectangle.fromBoundingSphere(
+        collection.boundingVolume,
+        this._tilingScheme.ellipsoid,
+        scratchCollectionRectangle,
+      );
+      const isIntersected = !!Rectangle.intersection(
+        rectangle,
+        collectionRectangle,
+        scratchIntersectRectangle,
+      );
+      const bakedVersion = bakedVersions.get(collection);
+
+      if (!isIntersected) {
+        // Left the rectangle since the bake.
+        if (defined(bakedVersion)) {
+          return true;
+        }
+        continue;
+      }
+
+      // Moved into the rectangle since the bake.
+      if (!defined(bakedVersion)) {
+        return true;
+      }
+
+      bakedVersionsVisited++;
+
+      if (collection._dirtyCount > 0 || bakedVersion !== collection._version) {
+        return true;
+      }
     }
 
-    return this.requestTileData(x, y, level, context);
+    // A collection the data was baked from is no longer marked.
+    return bakedVersionsVisited !== bakedVersions.size;
   }
 
   /**
@@ -327,12 +523,20 @@ class VectorProvider {
   }
 
   /**
-   * 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}.
+   * Prunes the previous frame's unmarked collections and 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}.
+   *
+   * @param {number} [frameNumber] The current frame number. When omitted, the
+   *   marked set is left untouched and only dirty regions are recorded.
    */
-  update() {
-    for (const collection of this._collections) {
+  update(frameNumber) {
+    if (defined(frameNumber)) {
+      this._beginFrame(frameNumber);
+    }
+
+    for (const collection of this._heightReferenceByCollection.keys()) {
       const cache = this._collectionDataCache.get(collection);
       if (!defined(cache)) {
         // Never extracted; new tiles bake on request.
@@ -371,13 +575,14 @@ class VectorProvider {
       return cache;
     }
 
-    const data = packCollectionData(collection, this._tilingScheme, cache);
+    const ellipsoid = this.ellipsoid;
+    const data = packCollectionData(collection, ellipsoid, 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,
+      ellipsoid,
       data.rectangle,
     );
     this._collectionDataCache.set(collection, data);
@@ -388,6 +593,41 @@ class VectorProvider {
   }
 }
 
+/**
+ * Whether a collection draped with <code>collectionHeightReference</code> lands
+ * on a surface of kind <code>targetHeightReference</code>.
+ *
+ * @param {HeightReference} collectionHeightReference
+ * @param {HeightReference} targetHeightReference Either
+ *   {@link HeightReference.CLAMP_TO_TERRAIN} or {@link HeightReference.CLAMP_TO_3D_TILE}.
+ * @returns {boolean}
+ * @private
+ */
+function targetsSurface(collectionHeightReference, targetHeightReference) {
+  return (
+    collectionHeightReference === HeightReference.CLAMP_TO_GROUND ||
+    collectionHeightReference === targetHeightReference
+  );
+}
+
+/**
+ * Ground size, in meters, of a rectangle's UV domain. Evaluated at the center latitude, so the
+ * east-west scale drifts toward the northern and southern edges.
+ *
+ * @param {Rectangle} rectangle
+ * @param {Ellipsoid} ellipsoid
+ * @returns {Cartesian2}
+ * @private
+ */
+function computeMetersPerUv(rectangle, ellipsoid) {
+  const radius = ellipsoid.maximumRadius;
+  const centerLatitude = (rectangle.south + rectangle.north) * 0.5;
+  return new Cartesian2(
+    rectangle.width * radius * Math.cos(centerLatitude),
+    rectangle.height * radius,
+  );
+}
+
 /**
  * @param {number} x
  * @param {number} y

package/Source/Renderer/AutomaticUniforms.js

@@ -1008,6 +1008,27 @@ const AutomaticUniforms = {
     },
   }),
 
+  /**
+   * An automatic GLSL uniform containing the geodetic longitude (<code>x</code>),
+   * latitude (<code>y</code>) in radians and height (<code>z</code>) in meters of the
+   * eye (camera). The <code>z</code> component matches {@link czm_eyeHeight}.
+   * This uniform is only valid when the {@link SceneMode} is <code>SCENE3D</code>.
+   *
+   * @example
+   * // GLSL declaration
+   * uniform vec3 czm_eyeCartographic;
+   *
+   * // Example
+   * float cameraLatitude = czm_eyeCartographic.y;
+   */
+  czm_eyeCartographic: new AutomaticUniform({
+    size: 1,
+    datatype: WebGLConstants.FLOAT_VEC3,
+    getValue: function (uniformState) {
+      return uniformState.eyeCartographic;
+    },
+  }),
+
   /**
    * An automatic GLSL uniform containing height (<code>x</code>) and height squared (<code>y</code>)
    * in meters of the eye (camera) above the 2D world plane. This uniform is only valid
@@ -1050,10 +1071,31 @@ const AutomaticUniforms = {
     },
   }),
 
+  /**
+   * An automatic GLSL uniform containing a 3x3 rotation from eye coordinates to an
+   * east-north-up coordinate system centered at the position on the ellipsoid below
+   * the camera.
+   * This uniform is only valid when the {@link SceneMode} is <code>SCENE3D</code>.
+   *
+   * @example
+   * // GLSL declaration
+   * uniform mat3 czm_eyeToEnu;
+   *
+   * // Example
+   * vec3 enu = czm_eyeToEnu * positionEC;
+   */
+  czm_eyeToEnu: new AutomaticUniform({
+    size: 1,
+    datatype: WebGLConstants.FLOAT_MAT3,
+    getValue: function (uniformState) {
+      return uniformState.eyeToEnu;
+    },
+  }),
+
   /**
    * An automatic GLSL uniform containing the transform from model coordinates
    * to an east-north-up coordinate system centered at the position on the
-   * ellipsoid below the camera.
+   * ellipsoid nearest to the camera.
    * This uniform is only valid when the {@link SceneMode} is <code>SCENE3D</code>.
    */
   czm_modelToEnu: new AutomaticUniform({
@@ -1065,7 +1107,7 @@ const AutomaticUniforms = {
   }),
 
   /**
-   * An automatic GLSL uniform containing the the inverse of
+   * An automatic GLSL uniform containing the inverse of
    * {@link AutomaticUniforms.czm_modelToEnu}.
    * This uniform is only valid when the {@link SceneMode} is <code>SCENE3D</code>.
    */

package/Source/Renderer/ShaderBuilder.js

@@ -424,7 +424,7 @@ ShaderBuilder.prototype.addVertexLines = function (lines) {
 /**
  * Appends lines of GLSL code to the fragment shader
  *
- * @param {string[]} lines The lines to add to the end of the fragment shader source
+ * @param {string|string[]} lines One or more lines to add to the end of the fragment shader source
  *
  * @example
  * shaderBuilder.addFragmentLines([