@cesium/engine 26.2.0 → 26.3.0

package/Source/Scene/GlobeSurfaceTileProvider.js

@@ -40,6 +40,7 @@ import ClippingPlaneCollection from "./ClippingPlaneCollection.js";
 import ClippingPolygonCollection from "./ClippingPolygonCollection.js";
 import DepthFunction from "./DepthFunction.js";
 import GlobeSurfaceTile from "./GlobeSurfaceTile.js";
+import HeightReference from "./HeightReference.js";
 import ImageryLayer from "./ImageryLayer.js";
 import ImageryState from "./ImageryState.js";
 import PerInstanceColorAppearance from "./PerInstanceColorAppearance.js";
@@ -209,6 +210,12 @@ class GlobeSurfaceTileProvider {
      */
     this._clippingPolygons = undefined;
 
+    this._clippingPolygonsDirty = false;
+
+    this._removeClippingPolygonAdded = undefined;
+
+    this._removeClippingPolygonRemoved = undefined;
+
     /**
      * A property specifying a {@link Rectangle} used to selectively limit terrain and imagery rendering.
      * @type {Rectangle}
@@ -348,7 +355,33 @@ class GlobeSurfaceTileProvider {
   }
 
   set clippingPolygons(value) {
+    if (value === this._clippingPolygons) {
+      return;
+    }
+
     ClippingPolygonCollection.setOwner(value, this, "_clippingPolygons");
+
+    // First, remove the previous listeners if they exist
+    this._removeClippingPolygonAdded =
+      this._removeClippingPolygonAdded && this._removeClippingPolygonAdded();
+    this._removeClippingPolygonRemoved =
+      this._removeClippingPolygonRemoved &&
+      this._removeClippingPolygonRemoved();
+
+    this._clippingPolygonsDirty = true;
+
+    if (!defined(value)) {
+      return;
+    }
+
+    const markDirty = () => {
+      this._clippingPolygonsDirty = true;
+    };
+
+    this._removeClippingPolygonAdded =
+      value.polygonAdded.addEventListener(markDirty);
+    this._removeClippingPolygonRemoved =
+      value.polygonRemoved.addEventListener(markDirty);
   }
 
   /**
@@ -384,7 +417,8 @@ class GlobeSurfaceTileProvider {
     // Record regions dirtied by changed collections, re-bake overlapping
     // tiles, and build vector data for new surface tiles.
     const vectorProvider = this._vectorProvider;
-    vectorProvider.update();
+    vectorProvider.minimumTileScreenPixels = minimumTileScreenPixels(this);
+    vectorProvider.update(frameState.frameNumber);
     this._quadtree.forEachRenderedTile(
       /** @param {QuadtreeTile} tile */
       (tile) => {
@@ -397,6 +431,7 @@ class GlobeSurfaceTileProvider {
             tile.level,
             frameState.context,
             surfaceTile.vectorData,
+            HeightReference.CLAMP_TO_TERRAIN,
           );
         } else {
           surfaceTile.vectorData = vectorProvider.requestTileData(
@@ -404,6 +439,7 @@ class GlobeSurfaceTileProvider {
             tile.y,
             tile.level,
             frameState.context,
+            HeightReference.CLAMP_TO_TERRAIN,
           );
         }
       },
@@ -447,8 +483,6 @@ class GlobeSurfaceTileProvider {
     if (defined(clippingPolygons) && clippingPolygons.enabled) {
       // @ts-expect-error Missing types.
       clippingPolygons.update(frameState);
-      // @ts-expect-error Missing types.
-      clippingPolygons.queueCommands(frameState);
     }
 
     this._usedDrawCommands = 0;
@@ -555,6 +589,10 @@ class GlobeSurfaceTileProvider {
       );
     }
 
+    if (this._clippingPolygonsDirty) {
+      releaseClippingPolygonData(this);
+    }
+
     // Add the tile render commands to the command list, sorted by texture count.
     const tilesToRenderByTextureCount = this._tilesToRenderByTextureCount;
     for (
@@ -575,6 +613,7 @@ class GlobeSurfaceTileProvider {
       ) {
         const tile = tilesToRender[tileIndex];
         const surfaceTile = /** @type {GlobeSurfaceTile} */ (tile.data);
+        updateTileClippingPolygonData(this, tile, surfaceTile, frameState);
         const tileBoundingRegion = surfaceTile.tileBoundingRegion;
         addDrawCommandsForTile(this, tile, frameState);
         frameState.minimumTerrainHeight = Math.min(
@@ -594,7 +633,16 @@ class GlobeSurfaceTileProvider {
     // Add the tile pick commands from the tiles drawn last frame.
     const drawCommands = this._drawCommands;
     for (let i = 0, length = this._usedDrawCommands; i < length; ++i) {
-      pushCommand(drawCommands[i], frameState);
+      const command = drawCommands[i];
+      // Pooled commands move between tiles, so a cached pick command may still
+      // hold the vertex array of a tile that has since been released.
+      command.dirty = true;
+      command.derivedCommands.picking = undefined;
+      const logDepthCommand = command.derivedCommands.logDepth?.command;
+      if (defined(logDepthCommand)) {
+        logDepthCommand.derivedCommands.picking = undefined;
+      }
+      pushCommand(command, frameState);
     }
   }
 
@@ -1161,8 +1209,7 @@ class GlobeSurfaceTileProvider {
     this._tileProvider = this._tileProvider && this._tileProvider.destroy();
     this._clippingPlanes =
       this._clippingPlanes && this._clippingPlanes.destroy();
-    this._clippingPolygons =
-      this._clippingPolygons && this._clippingPolygons.destroy();
+    this._clippingPolygons = undefined;
     this._removeLayerAddedListener =
       this._removeLayerAddedListener && this._removeLayerAddedListener();
     this._removeLayerRemovedListener =
@@ -1171,6 +1218,11 @@ class GlobeSurfaceTileProvider {
       this._removeLayerMovedListener && this._removeLayerMovedListener();
     this._removeLayerShownListener =
       this._removeLayerShownListener && this._removeLayerShownListener();
+    this._removeClippingPolygonAdded =
+      this._removeClippingPolygonAdded && this._removeClippingPolygonAdded();
+    this._removeClippingPolygonRemoved =
+      this._removeClippingPolygonRemoved &&
+      this._removeClippingPolygonRemoved();
 
     return destroyObject(this);
   }
@@ -1325,6 +1377,40 @@ class GlobeSurfaceTileProvider {
   }
 }
 
+const scratchLevelZeroRectangle = new Rectangle();
+
+/**
+ * Estimates the smallest screen size, in pixels, a rendered tile can have. Screen-space error is
+ * the tile's geometric error projected to the screen, so the tile projects to that error scaled by
+ * their ratio in meters, and refinement holds the error above half the maximum.
+ *
+ * @param {GlobeSurfaceTileProvider} tileProvider
+ * @returns {number}
+ * @private
+ */
+function minimumTileScreenPixels(tileProvider) {
+  const geometricError = tileProvider.getLevelMaximumGeometricError(0);
+  if (geometricError <= 0.0) {
+    // No terrain provider yet.
+    return tileProvider._vectorProvider.minimumTileScreenPixels;
+  }
+
+  const tilingScheme = tileProvider.tilingScheme;
+  const rectangle = tilingScheme.tileXYToRectangle(
+    0,
+    0,
+    0,
+    scratchLevelZeroRectangle,
+  );
+  const tileWidth = rectangle.width * tilingScheme.ellipsoid.maximumRadius;
+
+  return (
+    ((tileWidth / geometricError) *
+      tileProvider._quadtree.maximumScreenSpaceError) /
+    2.0
+  );
+}
+
 function sortTileImageryByLayerIndex(a, b) {
   let aImagery = a.loadingImagery;
   if (!defined(aImagery)) {
@@ -1339,6 +1425,81 @@ function sortTileImageryByLayerIndex(a, b) {
   return aImagery.imageryLayer._layerIndex - bImagery.imageryLayer._layerIndex;
 }
 
+/**
+ * Releases cached clipping polygon data on all loaded tiles so it is rebuilt
+ * against the current collection, and clears the dirty flag.
+ * @param {GlobeSurfaceTileProvider} tileProvider
+ * @ignore
+ */
+function releaseClippingPolygonData(tileProvider) {
+  tileProvider._quadtree.forEachLoadedTile(
+    /** @param {QuadtreeTile} tile */
+    function (tile) {
+      const surfaceTile = /** @type {GlobeSurfaceTile} */ (tile.data);
+      if (!defined(surfaceTile?.clippingPolygonData)) {
+        return;
+      }
+
+      ClippingPolygonCollection.releaseRectangleData(
+        surfaceTile.clippingPolygonData,
+      );
+      surfaceTile.clippingPolygonData = undefined;
+    },
+  );
+  tileProvider._clippingPolygonsDirty = false;
+}
+
+/**
+ * Builds clipping polygon data for a tile about to be rendered, unless it is
+ * unclipped or its data was already built this frame.
+ * @param {GlobeSurfaceTileProvider} tileProvider
+ * @param {QuadtreeTile} tile
+ * @param {GlobeSurfaceTile} surfaceTile
+ * @param {FrameState} frameState
+ * @ignore
+ */
+function updateTileClippingPolygonData(
+  tileProvider,
+  tile,
+  surfaceTile,
+  frameState,
+) {
+  const clippingPolygons = tileProvider._clippingPolygons;
+  if (
+    !defined(clippingPolygons) ||
+    !clippingPolygons.enabled ||
+    !tile.isClipped ||
+    defined(surfaceTile.clippingPolygonData)
+  ) {
+    return;
+  }
+
+  surfaceTile.clippingPolygonData = clippingPolygons.requestRectangleData(
+    tile.rectangle,
+    frameState.context,
+  );
+}
+
+/**
+ * Determines whether a tile is wholly clipped away by inverse clipping. In
+ * inverse mode a clipped tile with no polygon geometry lies entirely outside
+ * every polygon, so all of it is clipped and it should not be drawn.
+ * @param {GlobeSurfaceTileProvider} tileProvider
+ * @param {GlobeSurfaceTile} surfaceTile
+ * @returns {boolean}
+ * @ignore
+ */
+function isTileClippedAwayByInversePolygons(tileProvider, surfaceTile) {
+  const clippingPolygons = tileProvider._clippingPolygons;
+  return (
+    defined(clippingPolygons) &&
+    clippingPolygons.enabled &&
+    clippingPolygons.length > 0 &&
+    clippingPolygons.inverse &&
+    (surfaceTile.clippingPolygonData?.polygonRings.length ?? 0) === 0
+  );
+}
+
 /**
  * @param {GlobeSurfaceTileProvider} surface
  * @param {FrameState} frameState
@@ -1910,22 +2071,6 @@ function createTileUniformMap(frameState, globeSurfaceTileProvider) {
       style.alpha = this.properties.clippingPlanesEdgeWidth;
       return style;
     },
-    u_clippingDistance: function () {
-      const texture =
-        globeSurfaceTileProvider._clippingPolygons.clippingTexture;
-      if (defined(texture)) {
-        return texture;
-      }
-      return frameState.context.defaultTexture;
-    },
-    u_clippingExtents: function () {
-      // @ts-expect-error Missing types.
-      const texture = globeSurfaceTileProvider._clippingPolygons.extentsTexture;
-      if (defined(texture)) {
-        return texture;
-      }
-      return frameState.context.defaultTexture;
-    },
     u_minimumBrightness: function () {
       return frameState.fog.minimumBrightness;
     },
@@ -1972,6 +2117,12 @@ function createTileUniformMap(frameState, globeSurfaceTileProvider) {
         this.properties.vectorColorTexture ?? frameState.context.defaultTexture
       );
     },
+    u_vectorPickColorTexture: function () {
+      return (
+        this.properties.vectorPickColorTexture ??
+        frameState.context.defaultTexture
+      );
+    },
     u_vectorSegmentPrimitiveIndicesTexture: function () {
       return (
         this.properties.vectorSegmentPrimitiveIndicesTexture ??
@@ -2002,6 +2153,26 @@ function createTileUniformMap(frameState, globeSurfaceTileProvider) {
         frameState.context.defaultTexture
       );
     },
+    u_vectorMetersPerUv: function () {
+      return this.properties.vectorMetersPerUv;
+    },
+    u_clippingEdgeTexture: function () {
+      return (
+        this.properties.clippingEdgeTexture ?? frameState.context.defaultTexture
+      );
+    },
+    u_clippingEdgePrimitiveIndicesTexture: function () {
+      return (
+        this.properties.clippingEdgePrimitiveIndicesTexture ??
+        frameState.context.defaultTexture
+      );
+    },
+    u_clippingGridCellIndicesTexture: function () {
+      return (
+        this.properties.clippingGridCellIndicesTexture ??
+        frameState.context.defaultTexture
+      );
+    },
 
     // make a separate object so that changes to the properties are seen on
     // derived commands that combine another uniform map with this one.
@@ -2068,11 +2239,17 @@ function createTileUniformMap(frameState, globeSurfaceTileProvider) {
       vectorSegmentTexture: undefined,
       vectorWidthTexture: undefined,
       vectorColorTexture: undefined,
+      vectorPickColorTexture: undefined,
       vectorSegmentPrimitiveIndicesTexture: undefined,
       vectorGridCellIndicesTexture: undefined,
       vectorPolygonEdgeTexture: undefined,
       vectorPolygonEdgePrimitiveIndicesTexture: undefined,
       vectorPolygonGridCellIndicesTexture: undefined,
+      vectorMetersPerUv: new Cartesian2(),
+
+      clippingEdgeTexture: undefined,
+      clippingEdgePrimitiveIndicesTexture: undefined,
+      clippingGridCellIndicesTexture: undefined,
     },
   };
 
@@ -2312,6 +2489,7 @@ const surfaceShaderSetOptionsScratch = {
   colorToAlpha: undefined,
   hasGeodeticSurfaceNormals: undefined,
   hasExaggeration: undefined,
+  vectorAntialias: undefined,
 };
 
 const defaultUndergroundColor = Color.TRANSPARENT;
@@ -2326,6 +2504,10 @@ const defaultUndergroundColorAlphaByDistance = new NearFarScalar();
 function addDrawCommandsForTile(tileProvider, tile, frameState) {
   const surfaceTile = /** @type {GlobeSurfaceTile} */ (tile.data);
 
+  if (isTileClippedAwayByInversePolygons(tileProvider, surfaceTile)) {
+    return;
+  }
+
   if (!defined(surfaceTile.vertexArray)) {
     if (surfaceTile.fill === undefined) {
       // No fill was created for this tile, probably because this tile is not connected to
@@ -2445,8 +2627,9 @@ function addDrawCommandsForTile(tileProvider, tile, frameState) {
     defined(tileProvider.clippingPolygons) &&
     tileProvider.clippingPolygons.enabled
   ) {
-    --maxTextures;
-    --maxTextures;
+    // Vector polygon clipping samples three textures: edges, per-edge
+    // primitive indices, and the grid cell index header.
+    maxTextures -= 3;
   }
 
   maxTextures -= globeTranslucencyState.numberOfTextureUniforms;
@@ -2565,6 +2748,8 @@ function addDrawCommandsForTile(tileProvider, tile, frameState) {
   surfaceShaderSetOptions.clippedByBoundaries = surfaceTile.clippedByBoundaries;
   surfaceShaderSetOptions.hasGeodeticSurfaceNormals = hasGeodeticSurfaceNormals;
   surfaceShaderSetOptions.hasExaggeration = hasExaggeration;
+  surfaceShaderSetOptions.vectorAntialias =
+    tileProvider.vectorProvider.antialias;
 
   const tileImageryCollection = surfaceTile.imagery;
   let imageryIndex = 0;
@@ -3019,6 +3204,7 @@ function addDrawCommandsForTile(tileProvider, tile, frameState) {
         vectorData.polylineSegmentTexture;
       uniformMapProperties.vectorWidthTexture = vectorData.widthTexture;
       uniformMapProperties.vectorColorTexture = vectorData.colorTexture;
+      uniformMapProperties.vectorPickColorTexture = vectorData.pickColorTexture;
       uniformMapProperties.vectorSegmentPrimitiveIndicesTexture =
         vectorData.polylineSegmentPrimitiveIndicesTexture;
       uniformMapProperties.vectorGridCellIndicesTexture =
@@ -3029,15 +3215,32 @@ function addDrawCommandsForTile(tileProvider, tile, frameState) {
         vectorData.polygonEdgePrimitiveIndicesTexture;
       uniformMapProperties.vectorPolygonGridCellIndicesTexture =
         vectorData.polygonGridCellIndicesTexture;
+      Cartesian2.clone(
+        vectorData.metersPerUv,
+        uniformMapProperties.vectorMetersPerUv,
+      );
+    }
+
+    const clippingPolygonData = surfaceTile.clippingPolygonData;
+    if (defined(clippingPolygonData)) {
+      uniformMapProperties.clippingEdgeTexture =
+        clippingPolygonData.polygonEdgeTexture;
+      uniformMapProperties.clippingEdgePrimitiveIndicesTexture =
+        clippingPolygonData.polygonEdgePrimitiveIndicesTexture;
+      uniformMapProperties.clippingGridCellIndicesTexture =
+        clippingPolygonData.polygonGridCellIndicesTexture;
     }
 
     // update clipping polygons
     const clippingPolygons = tileProvider._clippingPolygons;
+    const hasClippingPolygonGeometry =
+      (clippingPolygonData?.polygonRings.length ?? 0) > 0;
     const clippingPolygonsEnabled =
       defined(clippingPolygons) &&
       clippingPolygons.enabled &&
       clippingPolygons.length > 0 &&
-      tile.isClipped;
+      tile.isClipped &&
+      hasClippingPolygonGeometry;
 
     surfaceShaderSetOptions.numberOfDayTextures = numberOfDayTextures;
     surfaceShaderSetOptions.applyBrightness = applyBrightness;
@@ -3068,6 +3271,10 @@ function addDrawCommandsForTile(tileProvider, tile, frameState) {
     command.shaderProgram = tileProvider._surfaceShaderSet.getShaderProgram(
       surfaceShaderSetOptions,
     );
+    // Draped vectors are picked through the surface; zero elsewhere keeps the globe unpickable.
+    command.pickId = surfaceTile.vectorData?.show
+      ? "vectorPickColorOver(vec4(0.0))"
+      : undefined;
     command.castShadows = castShadows;
     command.receiveShadows = receiveShadows;
     command.renderState = renderState;

package/Source/Scene/GltfLoader.js

@@ -14,6 +14,8 @@ import PrimitiveType from "../Core/PrimitiveType.js";
 import Quaternion from "../Core/Quaternion.js";
 import RuntimeError from "../Core/RuntimeError.js";
 import Sampler from "../Renderer/Sampler.js";
+import TextureMagnificationFilter from "../Renderer/TextureMagnificationFilter.js";
+import TextureMinificationFilter from "../Renderer/TextureMinificationFilter.js";
 import getAccessorByteStride from "./GltfPipeline/getAccessorByteStride.js";
 import getComponentReader from "./GltfPipeline/getComponentReader.js";
 import numberOfComponentsForType from "./GltfPipeline/numberOfComponentsForType.js";
@@ -1570,7 +1572,41 @@ function loadIndices(
   return indicesPlan;
 }
 
-function loadTexture(loader, textureInfo, frameState, samplerOverride) {
+/**
+ * Returns a copy of <code>sampler</code> with its minification and magnification
+ * filters replaced. Undefined filters keep the value already on the sampler, and
+ * every other property, in particular the wrap modes declared by the glTF, is
+ * carried over unchanged.
+ *
+ * @param {Sampler} sampler The sampler created from the glTF.
+ * @param {TextureMinificationFilter} [minificationFilter] The minification filter to apply instead of the one on <code>sampler</code>.
+ * @param {TextureMagnificationFilter} [magnificationFilter] The magnification filter to apply instead of the one on <code>sampler</code>.
+ * @returns {Sampler} A sampler using the given filters and the original wrap modes.
+ *
+ * @private
+ */
+function overrideSamplerFilters(
+  sampler,
+  minificationFilter,
+  magnificationFilter,
+) {
+  return new Sampler({
+    wrapR: sampler.wrapR,
+    wrapS: sampler.wrapS,
+    wrapT: sampler.wrapT,
+    minificationFilter: minificationFilter ?? sampler.minificationFilter,
+    magnificationFilter: magnificationFilter ?? sampler.magnificationFilter,
+    maximumAnisotropy: sampler.maximumAnisotropy,
+  });
+}
+
+function loadTexture(
+  loader,
+  textureInfo,
+  frameState,
+  minificationFilterOverride,
+  magnificationFilterOverride,
+) {
   const gltf = loader.gltfJson;
   const imageId = GltfLoaderUtil.getImageIdFromTexture({
     gltf: gltf,
@@ -1618,9 +1654,17 @@ function loadTexture(loader, textureInfo, frameState, samplerOverride) {
   // Save this finish callback by the loader index so it can be called
   // in process().
   loader._textureCallbacks[index] = () => {
-    textureReader.texture = textureLoader.texture;
-    if (defined(samplerOverride)) {
-      textureReader.texture.sampler = samplerOverride;
+    const texture = textureLoader.texture;
+    textureReader.texture = texture;
+    if (
+      defined(minificationFilterOverride) ||
+      defined(magnificationFilterOverride)
+    ) {
+      texture.sampler = overrideSamplerFilters(
+        texture.sampler,
+        minificationFilterOverride,
+        magnificationFilterOverride,
+      );
     }
   };
 
@@ -2013,7 +2057,10 @@ function loadFeatureIdTexture(
     loader,
     textureInfo,
     frameState,
-    Sampler.NEAREST, // Feature ID textures require nearest sampling
+    // Feature ID textures require nearest sampling. Only the filters are
+    // overridden so the wrap modes declared by the glTF are preserved.
+    TextureMinificationFilter.NEAREST,
+    TextureMagnificationFilter.NEAREST,
   );
 
   // Though the new channel index is more future-proof, this implementation
@@ -2048,7 +2095,10 @@ function loadFeatureIdTextureLegacy(
     loader,
     textureInfo,
     frameState,
-    Sampler.NEAREST, // Feature ID textures require nearest sampling
+    // Feature ID textures require nearest sampling. Only the filters are
+    // overridden so the wrap modes declared by the glTF are preserved.
+    TextureMinificationFilter.NEAREST,
+    TextureMagnificationFilter.NEAREST,
   );
 
   featureIdTexture.textureReader.channels = featureIds.channels;

package/Source/Scene/HeightReference.js

@@ -28,7 +28,7 @@ const HeightReference = {
   RELATIVE_TO_GROUND: 2,
 
   /**
-   * The position is clamped to terain.
+   * The position is clamped to terrain.
    * @type {number}
    * @constant
    */

package/Source/Scene/MVTDataProvider.js

@@ -12,8 +12,10 @@ import defined from "../Core/defined.js";
 
 /** @import Cesium3DTile from "./Cesium3DTile.js"; */
 /** @import Cesium3DTileset from "./Cesium3DTileset.js"; */
+/** @import HeightReference from "./HeightReference.js"; */
 /** @import Rectangle from "../Core/Rectangle.js"; */
 /** @import Resource from "../Core/Resource.js"; */
+/** @import Scene from "./Scene.js"; */
 
 /**
  * A Mapbox Vector Tiles (MVT) data provider. Loads .mvt or .pbf tiles, converting tiles
@@ -36,6 +38,12 @@ class MVTDataProvider extends UrlTemplate3DTilesDataProvider {
    * @param {number} [options.maxZoom=14] Maximum zoom level represented in the generated tileset.
    * @param {Rectangle} [options.extent] Optional geographic extent in radians to constrain the generated tile tree.
    * @param {string} [options.featureIdProperty] MVT property name to use as feature ID.
+   * @param {HeightReference} [options.heightReference] Drapes the decoded points, lines and polygons onto the
+   *   surfaces selected by the value: {@link HeightReference.CLAMP_TO_TERRAIN} drapes onto the globe,
+   *   {@link HeightReference.CLAMP_TO_3D_TILE} drapes onto 3D Tiles and models, and
+   *   {@link HeightReference.CLAMP_TO_GROUND} drapes onto both. Requires <code>options.scene</code>.
+   * @param {Scene} [options.scene] The scene the generated tileset is rendered in, required when
+   *   <code>options.heightReference</code> is a clamping value.
    * @returns {Promise<MVTDataProvider>}
    */
   static async fromUrl(url, options) {
@@ -51,6 +59,7 @@ class MVTDataProvider extends UrlTemplate3DTilesDataProvider {
    */
   _createTilesetLoadOptions() {
     return {
+      ...super._createTilesetLoadOptions(),
       skipLevelOfDetail: false,
       enablePick: true,
       featureIdLabel: "featureId_0",