@cesium/engine 26.2.0 → 26.3.0

package/Source/Scene/Model/Model.js

@@ -13,6 +13,7 @@ import Ellipsoid from "../../Core/Ellipsoid.js";
 import Event from "../../Core/Event.js";
 import Matrix3 from "../../Core/Matrix3.js";
 import Matrix4 from "../../Core/Matrix4.js";
+import Rectangle from "../../Core/Rectangle.js";
 import Resource from "../../Core/Resource.js";
 import RuntimeError from "../../Core/RuntimeError.js";
 import Pass from "../../Renderer/Pass.js";
@@ -46,6 +47,8 @@ import StyleCommandsNeeded from "./StyleCommandsNeeded.js";
 import pickModel from "./pickModel.js";
 import ModelImagery from "./ModelImagery.js";
 
+/** @import { VectorTileData } from "../../Core/VectorPipeline.js"; */
+
 /**
  * <div class="notice">
  * To construct a Model, call {@link Model.fromGltfAsync}. Do not call the constructor directly.
@@ -399,6 +402,30 @@ function Model(options) {
     this._clippingPolygons = clippingPolygons;
   }
   this._clippingPolygonsState = 0; // If this value changes, the shaders need to be regenerated.
+  this._clippingPolygonsNeedRebake = false; // If true, the clipping textures are rebaked.
+  this._removeClippingPolygonAdded = undefined;
+  this._removeClippingPolygonRemoved = undefined;
+  updateClippingPolygonListeners(this);
+
+  /**
+   * Vector lookup data baked for this model's bounding region by the scene's
+   * VectorProvider, draping vector data onto the model's surface.
+   * @type {VectorTileData|undefined}
+   * @ignore
+   */
+  this._vectorData = undefined;
+
+  this._vectorLookupFlags = 0; // If this value changes, the shaders need to be regenerated.
+
+  /*
+   * Textures and other intermediate data used in polygon clipping workflows.
+   * Clipping polygons build on top of the vector tile data system (both rely on the same rendering technique), thus the type.
+   * @type {VectorTileData | undefined}
+   * @private
+   */
+  this._clippingPolygonData = undefined;
+
+  this._rectangle = new Rectangle();
 
   this._modelImagery = new ModelImagery(this);
 
@@ -1376,7 +1403,17 @@ Object.defineProperties(Model.prototype, {
       if (value !== this._clippingPolygons) {
         // Handle destroying old clipping polygons, new clipping polygons ownership
         ClippingPolygonCollection.setOwner(value, this, "_clippingPolygons");
+        updateClippingPolygonListeners(this);
         this.resetDrawCommands();
+
+        this._clippingPolygonsState = 0;
+        this._clippingPolygonsNeedRebake = true;
+        if (defined(this._clippingPolygonData)) {
+          ClippingPolygonCollection.releaseRectangleData(
+            this._clippingPolygonData,
+          );
+          this._clippingPolygonData = undefined;
+        }
       }
     },
   },
@@ -1788,6 +1825,41 @@ Object.defineProperties(Model.prototype, {
   },
 });
 
+/**
+ * A rectangle that bounds the model in geodetic coordinates. For 3D tile content with a
+ * region bounding volume this is the tile's rectangle. Otherwise the model's bounding sphere
+ * is projected onto the given ellipsoid.
+ *
+ * @param {Ellipsoid} [ellipsoid=Ellipsoid.default] Projects the bounding sphere (for models without a region bounding volume).
+ * @returns {Rectangle} The bounding rectangle.
+ *
+ * @exception {DeveloperError} The model is not loaded. Use Model.readyEvent or wait for Model.ready to be true.
+ *
+ * @private
+ */
+Model.prototype.getRectangle = function (ellipsoid) {
+  //>>includeStart('debug', pragmas.debug);
+  if (!this._ready) {
+    throw new DeveloperError(
+      "The model is not loaded. Use Model.readyEvent or wait for Model.ready to be true.",
+    );
+  }
+  //>>includeEnd('debug');
+
+  // A region bounding volume's rectangle is fixed in WGS84, so the ellipsoid argument does not apply.
+  const bv = this._content?.tile?.contentBoundingVolume;
+  if (defined(bv?.rectangle)) {
+    return bv.rectangle;
+  }
+
+  ellipsoid = ellipsoid ?? this._scene?.ellipsoid ?? Ellipsoid.default;
+  return Rectangle.fromBoundingSphere(
+    this.boundingSphere,
+    ellipsoid,
+    this._rectangle,
+  );
+};
+
 /**
  * Returns the node with the given <code>name</code> in the glTF. This is used to
  * modify a node's transform for user-defined animation.
@@ -2016,6 +2088,7 @@ Model.prototype.update = function (frameState) {
   updateSkipLevelOfDetail(this, frameState);
   updateClippingPlanes(this, frameState);
   updateClippingPolygons(this, frameState);
+  updateVectorLookup(this, frameState);
   updateSceneMode(this, frameState);
   updateFog(this, frameState);
   updateVerticalExaggeration(this, frameState);
@@ -2219,22 +2292,140 @@ function updateClippingPlanes(model, frameState) {
   }
 }
 
+// Only the collection's owner subscribes to its add/remove events. Tileset-owned
+// collections are handled by the tileset, which marks its tiles dirty instead.
+function updateClippingPolygonListeners(model) {
+  model._removeClippingPolygonAdded =
+    model._removeClippingPolygonAdded && model._removeClippingPolygonAdded();
+  model._removeClippingPolygonRemoved =
+    model._removeClippingPolygonRemoved &&
+    model._removeClippingPolygonRemoved();
+
+  const clippingPolygons = model._clippingPolygons;
+  if (!defined(clippingPolygons) || clippingPolygons.owner !== model) {
+    return;
+  }
+
+  const markDirty = () => {
+    model._clippingPolygonsNeedRebake = true;
+  };
+  model._removeClippingPolygonAdded =
+    clippingPolygons.polygonAdded.addEventListener(markDirty);
+  model._removeClippingPolygonRemoved =
+    clippingPolygons.polygonRemoved.addEventListener(markDirty);
+}
+
 function updateClippingPolygons(model, frameState) {
-  // Update the clipping polygon collection / state for this model to detect any changes.
+  const clippingPolygons = model._clippingPolygons;
+  const enabled = model.isClippingPolygonsEnabled();
+
+  // Detect enabled/inverse changes, which require shader regeneration.
   let currentClippingPolygonsState = 0;
-  if (model.isClippingPolygonsEnabled()) {
-    if (model._clippingPolygons.owner === model) {
-      model._clippingPolygons.update(frameState);
-      model._clippingPolygons.queueCommands(frameState);
+  if (enabled) {
+    if (clippingPolygons.owner === model) {
+      clippingPolygons.update(frameState);
     }
-    currentClippingPolygonsState =
-      model._clippingPolygons.clippingPolygonsState;
+    currentClippingPolygonsState = clippingPolygons.clippingPolygonsState;
   }
 
   if (currentClippingPolygonsState !== model._clippingPolygonsState) {
     model.resetDrawCommands();
     model._clippingPolygonsState = currentClippingPolygonsState;
   }
+
+  const wasClipped = (model._clippingPolygonData?.polygonRings.length ?? 0) > 0;
+
+  // A polygon add/remove or a model move only requires rebaking the clipping textures.
+  if (model._clippingPolygonsNeedRebake) {
+    model._clippingPolygonsNeedRebake = false;
+    if (defined(model._clippingPolygonData)) {
+      ClippingPolygonCollection.releaseRectangleData(
+        model._clippingPolygonData,
+      );
+      model._clippingPolygonData = undefined;
+    }
+  }
+
+  if (!enabled || !model._ready) {
+    return;
+  }
+
+  if (!defined(model._clippingPolygonData)) {
+    model._clippingPolygonData = clippingPolygons.requestRectangleData(
+      model.getRectangle(clippingPolygons.ellipsoid),
+      frameState.context,
+    );
+  }
+
+  const isClipped = (model._clippingPolygonData?.polygonRings.length ?? 0) > 0;
+  if (wasClipped !== isClipped) {
+    // Rerun the model pipeline to enable/disable clipping
+    model.resetDrawCommands();
+  }
+}
+
+const scratchVectorRectangle = new Rectangle();
+
+function releaseVectorData(model) {
+  if (!defined(model._vectorData)) {
+    return;
+  }
+
+  model._scene?.vectorProvider?.releaseTileData(model._vectorData);
+  model._vectorData = undefined;
+}
+
+// Each kind of geometry declares its own lookup textures, so the mix drives the shader.
+function vectorLookupFlags(vectorData) {
+  if (vectorData?.show !== true) {
+    return 0;
+  }
+
+  let flags = 1;
+  flags |= vectorData.hasPolylines ? 2 : 0;
+  flags |= vectorData.hasPolygons ? 4 : 0;
+  return flags;
+}
+
+function updateVectorLookup(model, frameState) {
+  const provider = model._scene?.vectorProvider;
+  // HeightReference.CLAMP_TO_3D_TILE covers tileset content only, not standalone glTF.
+  const active =
+    defined(provider) &&
+    defined(model._content) &&
+    model.ready &&
+    frameState.mode === SceneMode.SCENE3D;
+
+  if (active) {
+    // A tile's content region is far tighter than a rectangle circumscribing the bounding sphere.
+    const rectangle =
+      model._content?.tile?.contentBoundingVolume.rectangle ??
+      Rectangle.fromBoundingSphere(
+        model.boundingSphere,
+        provider.ellipsoid,
+        scratchVectorRectangle,
+      );
+    model._vectorData = defined(model._vectorData)
+      ? provider.updateDataForRectangle(
+          rectangle,
+          frameState.context,
+          model._vectorData,
+          HeightReference.CLAMP_TO_3D_TILE,
+        )
+      : provider.requestDataForRectangle(
+          rectangle,
+          frameState.context,
+          HeightReference.CLAMP_TO_3D_TILE,
+        );
+  } else {
+    releaseVectorData(model);
+  }
+
+  const flags = vectorLookupFlags(model._vectorData);
+  if (flags !== model._vectorLookupFlags) {
+    model.resetDrawCommands();
+    model._vectorLookupFlags = flags;
+  }
 }
 
 function updateSceneMode(model, frameState) {
@@ -2502,6 +2693,10 @@ function updateSceneGraph(model, frameState) {
       ? model._clampedModelMatrix
       : model.modelMatrix;
     sceneGraph.updateModelMatrix(modelMatrix, frameState);
+    if (model._updateModelMatrix) {
+      // The model moved, so re-bake the clipping textures for its new rectangle.
+      model._clippingPolygonsNeedRebake = true;
+    }
     model._updateModelMatrix = false;
   }
 
@@ -2561,6 +2756,22 @@ function updateShowCreditsOnScreen(model) {
   }
 }
 
+/**
+ * Determines whether a model is wholly clipped away by inverse clipping. In
+ * inverse mode a model with no polygon geometry lies entirely outside every
+ * polygon, so all of it is clipped and it should not be drawn.
+ * @param {Model} model
+ * @returns {boolean}
+ * @private
+ */
+function isModelClippedAwayByInversePolygons(model) {
+  return (
+    model.isClippingPolygonsEnabled() &&
+    model._clippingPolygons.inverse &&
+    (model._clippingPolygonData?.polygonRings.length ?? 0) === 0
+  );
+}
+
 function submitDrawCommands(model, frameState) {
   // Check that show is true after draw commands are built;
   // we want the user to be able to instantly see the model
@@ -2581,7 +2792,8 @@ function submitDrawCommands(model, frameState) {
     model._show &&
     model._computedScale !== 0 &&
     displayConditionPassed &&
-    (!invisible || silhouette);
+    (!invisible || silhouette) &&
+    !isModelClippedAwayByInversePolygons(model);
 
   const passes = frameState.passes;
   const submitCommandsForPass =
@@ -2806,6 +3018,16 @@ Model.prototype.isClippingPolygonsEnabled = function () {
   );
 };
 
+/**
+ * Gets whether draped vector data is baked and renderable for this model.
+ *
+ * @returns {boolean} <code>true</code> if the model drapes vector data.
+ * @private
+ */
+Model.prototype.hasDrapedVectors = function () {
+  return this._vectorData?.show === true;
+};
+
 /**
  * Returns true if this object was destroyed; otherwise, false.
  * <br /><br />
@@ -2853,6 +3075,8 @@ Model.prototype.destroy = function () {
   this.destroyPipelineResources();
   this.destroyModelResources();
 
+  releaseVectorData(this);
+
   // Remove callbacks for height reference behavior.
   if (defined(this._removeUpdateHeightCallback)) {
     this._removeUpdateHeightCallback();
@@ -2864,6 +3088,12 @@ Model.prototype.destroy = function () {
     this._terrainProviderChangedCallback = undefined;
   }
 
+  // Remove clipping polygon event listeners if this model subscribed to them.
+  this._removeClippingPolygonAdded =
+    this._removeClippingPolygonAdded && this._removeClippingPolygonAdded();
+  this._removeClippingPolygonRemoved =
+    this._removeClippingPolygonRemoved && this._removeClippingPolygonRemoved();
+
   // Only destroy the ClippingPlaneCollection if this is the owner.
   const clippingPlaneCollection = this._clippingPlanes;
   if (
@@ -2875,15 +3105,11 @@ Model.prototype.destroy = function () {
   }
   this._clippingPlanes = undefined;
 
-  // Only destroy the ClippingPolygonCollection if this is the owner.
-  const clippingPolygonCollection = this._clippingPolygons;
-  if (
-    defined(clippingPolygonCollection) &&
-    !clippingPolygonCollection.isDestroyed() &&
-    clippingPolygonCollection.owner === this
-  ) {
-    clippingPolygonCollection.destroy();
+  if (defined(this._clippingPolygonData)) {
+    ClippingPolygonCollection.releaseRectangleData(this._clippingPolygonData);
   }
+  this._clippingPolygonData = undefined;
+
   this._clippingPolygons = undefined;
 
   // Only destroy the ImageBasedLighting if this is the owner.

package/Source/Scene/Model/Model3DTileContent.js

@@ -310,6 +310,10 @@ class Model3DTileContent {
       model._clippingPolygonsState = 0;
     }
 
+    if (tile.clippingPolygonsNeedRebake) {
+      model._clippingPolygonsNeedRebake = true;
+    }
+
     model.update(frameState);
 
     if (!this._ready && model.ready) {
@@ -490,6 +494,7 @@ function makeModelOptions(tileset, tile, content, additionalOptions) {
     incrementallyLoadTextures: false,
     customShader: tileset.customShader,
     content: content,
+    scene: tileset._scene,
     colorBlendMode: tileset.colorBlendMode,
     colorBlendAmount: tileset.colorBlendAmount,
     lightColor: tileset.lightColor,

package/Source/Scene/Model/ModelClippingPolygonsPipelineStage.js

@@ -1,7 +1,11 @@
 import combine from "../../Core/combine.js";
-import ModelClippingPolygonsStageVS from "../../Shaders/Model/ModelClippingPolygonsStageVS.js";
 import ModelClippingPolygonsStageFS from "../../Shaders/Model/ModelClippingPolygonsStageFS.js";
+import ModelClippingPolygonsStageVS from "../../Shaders/Model/ModelClippingPolygonsStageVS.js";
 import ShaderDestination from "../../Renderer/ShaderDestination.js";
+import VectorCommon from "../../Shaders/VectorCommon.js";
+import Cartesian2 from "../../Core/Cartesian2.js";
+import CesiumMath from "../../Core/Math.js";
+import Rectangle from "../../Core/Rectangle.js";
 
 /**
  * The model clipping planes stage is responsible for applying clipping planes to the model.
@@ -14,6 +18,10 @@ const ModelClippingPolygonsPipelineStage = {
   name: "ModelClippingPolygonsPipelineStage", // Helps with debugging
 };
 
+const scratchCameraUv = new Cartesian2();
+const scratchRectangleInverseSize = new Cartesian2();
+const defaultRectangle = Rectangle.MAX_VALUE;
+
 /**
  * Process a model for polygon clipping. This modifies the following parts of the render resources:
  *
@@ -54,40 +62,67 @@ ModelClippingPolygonsPipelineStage.process = function (
     );
   }
 
-  shaderBuilder.addDefine(
-    "CLIPPING_POLYGON_REGIONS_LENGTH",
-    clippingPolygons.extentsCount,
-    ShaderDestination.BOTH,
-  );
+  shaderBuilder.addVarying("vec2", "v_clippingUv");
 
   shaderBuilder.addUniform(
-    "sampler2D",
-    "model_clippingDistance",
-    ShaderDestination.FRAGMENT,
+    "vec2",
+    "u_clippingCameraUv",
+    ShaderDestination.VERTEX,
   );
 
   shaderBuilder.addUniform(
-    "sampler2D",
-    "model_clippingExtents",
+    "vec2",
+    "u_clippingRectangleInverseSize",
     ShaderDestination.VERTEX,
   );
 
-  shaderBuilder.addVarying("vec2", "v_clippingPosition");
-  shaderBuilder.addVarying("int", "v_regionIndex", "flat");
   shaderBuilder.addVertexLines(ModelClippingPolygonsStageVS);
+  shaderBuilder.addFragmentLines(VectorCommon);
   shaderBuilder.addFragmentLines(ModelClippingPolygonsStageFS);
 
   const uniformMap = {
-    model_clippingDistance: function () {
+    // The UV coordinates of the camera within the model's clipping rectangle.
+    u_clippingCameraUv: function () {
+      const rectangle =
+        model._clippingPolygonData?.rectangle ?? defaultRectangle;
+      const halfWidth = rectangle.width * 0.5;
+      const centerLongitude = rectangle.west + halfWidth;
+      const carto = frameState.camera.positionCartographic;
+
+      const longitudeOffset =
+        CesiumMath.negativePiToPi(carto.longitude - centerLongitude) +
+        halfWidth;
+      return Cartesian2.fromElements(
+        longitudeOffset / rectangle.width,
+        (carto.latitude - rectangle.south) / rectangle.height,
+        scratchCameraUv,
+      );
+    },
+    u_clippingRectangleInverseSize: function () {
+      const rectangle =
+        model._clippingPolygonData?.rectangle ?? defaultRectangle;
+      return Cartesian2.fromElements(
+        1.0 / rectangle.width,
+        1.0 / rectangle.height,
+        scratchRectangleInverseSize,
+      );
+    },
+    u_clippingEdgeTexture: function () {
+      return (
+        model._clippingPolygonData?.polygonEdgeTexture ??
+        frameState.context.defaultTexture
+      );
+    },
+    u_clippingEdgePrimitiveIndicesTexture: function () {
       return (
-        // The later should never happen during a render pass, see https://github.com/CesiumGS/cesium/issues/12725
-        clippingPolygons.clippingTexture ?? frameState.context.defaultTexture
+        model._clippingPolygonData?.polygonEdgePrimitiveIndicesTexture ??
+        frameState.context.defaultTexture
       );
     },
-    model_clippingExtents: function () {
+    u_clippingGridCellIndicesTexture: function () {
       return (
-        // The later should never happen during a render pass, see https://github.com/CesiumGS/cesium/issues/12725
-        clippingPolygons.extentsTexture ?? frameState.context.defaultTexture
+        model._clippingPolygonData?.polygonGridCellIndicesTexture ??
+        frameState.context.defaultTexture
       );
     },
   };

package/Source/Scene/Model/ModelRenderResources.js

@@ -25,7 +25,7 @@ function ModelRenderResources(model) {
    * @type {ShaderBuilder}
    * @readonly
    *
-   * @private
+   * @ignore
    */
   this.shaderBuilder = new ShaderBuilder();
 
@@ -44,9 +44,8 @@ function ModelRenderResources(model) {
    * values.
    *
    * @type {Object<string, Function>}
-   * @readonly
    *
-   * @private
+   * @ignore
    */
   this.uniformMap = {};
 

package/Source/Scene/Model/ModelSceneGraph.js

@@ -14,6 +14,7 @@ import ModelArticulation from "./ModelArticulation.js";
 import ModelColorPipelineStage from "./ModelColorPipelineStage.js";
 import ModelClippingPlanesPipelineStage from "./ModelClippingPlanesPipelineStage.js";
 import ModelClippingPolygonsPipelineStage from "./ModelClippingPolygonsPipelineStage.js";
+import ModelVectorLookupPipelineStage from "./ModelVectorLookupPipelineStage.js";
 import ModelNode from "./ModelNode.js";
 import ModelRuntimeNode from "./ModelRuntimeNode.js";
 import ModelRuntimePrimitive from "./ModelRuntimePrimitive.js";
@@ -735,10 +736,18 @@ ModelSceneGraph.prototype.configurePipeline = function (frameState) {
     modelPipelineStages.push(ModelClippingPlanesPipelineStage);
   }
 
-  if (model.isClippingPolygonsEnabled()) {
+  // Even if a model has a clipping polygon collection, the polygons may not overlap the model geometry,
+  // in which case the clipping polygon pipeline stage should not be added.
+  const hasClippingPolygonGeometry =
+    (model._clippingPolygonData?.polygonRings.length ?? 0) > 0;
+  if (model.isClippingPolygonsEnabled() && hasClippingPolygonGeometry) {
     modelPipelineStages.push(ModelClippingPolygonsPipelineStage);
   }
 
+  if (model.hasDrapedVectors()) {
+    modelPipelineStages.push(ModelVectorLookupPipelineStage);
+  }
+
   if (model.hasSilhouette(frameState)) {
     modelPipelineStages.push(ModelSilhouettePipelineStage);
   }