@cesium/engine 26.1.0 → 26.3.0

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/ModelDrawCommand.js

@@ -103,6 +103,9 @@ function ModelDrawCommand(options) {
   this._needsSkipLevelOfDetailCommands = needsSkipLevelOfDetailCommands;
   this._needsSilhouetteCommands = needsSilhouetteCommands;
   this._needsEdgeCommands = needsEdgeCommands;
+  // Non-behind planar fill primitives write their feature IDs in a pre-pass
+  // so that behind fills can test same-object coplanarity.
+  this._needsPlanarFillIdCommand = renderResources.planarFillIdPass;
 
   // Derived commands
   this._originalCommand = undefined;
@@ -112,6 +115,10 @@ function ModelDrawCommand(options) {
   this._silhouetteModelCommand = undefined;
   this._silhouetteColorCommand = undefined;
   this._edgeCommand = undefined;
+  // Snap-pass variant of the edge command, pinned at 1 px width.
+  // See deriveEdgeCommand.
+  this._edgeSnapCommand = undefined;
+  this._planarFillIdCommand = undefined;
 
   // All derived commands (including 2D commands)
   this._derivedCommands = [];
@@ -226,8 +233,27 @@ function initialize(drawCommand) {
 
   if (drawCommand._needsEdgeCommands) {
     const renderResources = drawCommand._primitiveRenderResources;
+    const edgeGeometry = renderResources.edgeGeometry;
+    const colorLineWidth = defined(edgeGeometry.lineWidth)
+      ? edgeGeometry.lineWidth
+      : 1.0;
+    // Snap-pass edge width is held at 1 px independent of the color width.
+    // A wider snap band results in snap wiggle: as the cursor moves
+    // perpendicular to an edge inside the band, the "edge pixel nearest
+    // the cursor" shifts, so Snapping.snap returns a slightly different
+    // point each frame.
+    const snapLineWidth = 1.0;
+
     drawCommand._edgeCommand = new ModelDerivedCommand({
-      command: deriveEdgeCommand(command, renderResources, model),
+      command: deriveEdgeCommand(command, renderResources, colorLineWidth),
+      updateShadows: false,
+      updateBackFaceCulling: false,
+      updateCullFace: false,
+      updateDebugShowBoundingVolume: false,
+    });
+
+    drawCommand._edgeSnapCommand = new ModelDerivedCommand({
+      command: deriveEdgeCommand(command, renderResources, snapLineWidth),
       updateShadows: false,
       updateBackFaceCulling: false,
       updateCullFace: false,
@@ -235,6 +261,19 @@ function initialize(drawCommand) {
     });
 
     derivedCommands.push(drawCommand._edgeCommand);
+    derivedCommands.push(drawCommand._edgeSnapCommand);
+  }
+
+  if (drawCommand._needsPlanarFillIdCommand) {
+    drawCommand._planarFillIdCommand = new ModelDerivedCommand({
+      command: derivePlanarFillIdCommand(command),
+      updateShadows: false,
+      updateBackFaceCulling: false,
+      updateCullFace: false,
+      updateDebugShowBoundingVolume: false,
+    });
+
+    derivedCommands.push(drawCommand._planarFillIdCommand);
   }
 }
 
@@ -584,14 +623,6 @@ ModelDrawCommand.prototype.pushCommands = function (frameState, result) {
 
   pushCommand(result, this._originalCommand, use2D);
 
-  // Push edge commands after the original command
-  if (
-    this._needsEdgeCommands &&
-    this._model.edgeDisplayMode !== EdgeDisplayMode.SURFACES_ONLY
-  ) {
-    pushCommand(result, this._edgeCommand, use2D);
-  }
-
   return result;
 };
 
@@ -636,15 +667,51 @@ ModelDrawCommand.prototype.pushEdgeCommands = function (frameState, result) {
     return result;
   }
 
-  // SURFACES_ONLY mode suppresses all edge rendering
-  if (this._model.edgeDisplayMode === EdgeDisplayMode.SURFACES_ONLY) {
+  const mode = this._model.edgeDisplayMode;
+  const passes = frameState.passes;
+  const use2D = shouldUse2DCommands(this, frameState);
+
+  if (passes.snap) {
+    // Snapping pass: route the 1 px snap variant directly into the bound
+    // snap framebuffer, regardless of display mode -- snapping works even
+    // when edges are visually suppressed (SURFACES_ONLY).
+    const edgeCommand = this._edgeSnapCommand;
+    edgeCommand.command.pass = Pass.CESIUM_3D_TILE_EDGES_DIRECT;
+    if (defined(edgeCommand.derivedCommand2D)) {
+      edgeCommand.derivedCommand2D.command.pass =
+        Pass.CESIUM_3D_TILE_EDGES_DIRECT;
+    }
+    pushCommand(result, edgeCommand, use2D);
+    return result;
+  }
+
+  if (passes.pick) {
+    // Plain pick pass: edges contribute nothing to the RGBA8 pick
+    // framebuffer except in EDGES_ONLY mode, where they are the only
+    // pickable geometry (pushCommands skips the surface command).
+    if (mode !== EdgeDisplayMode.EDGES_ONLY) {
+      return result;
+    }
+    const edgeCommand = this._edgeCommand;
+    edgeCommand.command.pass = Pass.CESIUM_3D_TILE_EDGES_DIRECT;
+    if (defined(edgeCommand.derivedCommand2D)) {
+      edgeCommand.derivedCommand2D.command.pass =
+        Pass.CESIUM_3D_TILE_EDGES_DIRECT;
+    }
+    pushCommand(result, edgeCommand, use2D);
     return result;
   }
 
-  // Use direct pass (renders to main framebuffer) when EDGES_ONLY mode is enabled,
-  // otherwise use MRT pass (renders to edge framebuffer for compositing)
+  // Color pass. SURFACES_ONLY mode suppresses all edge rendering.
+  if (mode === EdgeDisplayMode.SURFACES_ONLY) {
+    return result;
+  }
+
+  // Use direct pass (renders to currently bound framebuffer) when EDGES_ONLY
+  // mode is enabled, otherwise use MRT pass (renders to edge framebuffer for
+  // compositing).
   const edgePass =
-    this._model.edgeDisplayMode === EdgeDisplayMode.EDGES_ONLY
+    mode === EdgeDisplayMode.EDGES_ONLY
       ? Pass.CESIUM_3D_TILE_EDGES_DIRECT
       : Pass.CESIUM_3D_TILE_EDGES;
 
@@ -653,12 +720,34 @@ ModelDrawCommand.prototype.pushEdgeCommands = function (frameState, result) {
     this._edgeCommand.derivedCommand2D.command.pass = edgePass;
   }
 
-  const use2D = shouldUse2DCommands(this, frameState);
   pushCommand(result, this._edgeCommand, use2D);
 
   return result;
 };
 
+/**
+ * Push the planar fill feature-ID pre-pass command (if any).
+ *
+ * @param {FrameState} frameState The frame state.
+ * @param {DrawCommand[]} result The draw commands to push to.
+ * @returns {DrawCommand[]} The modified command list.
+ *
+ * @private
+ */
+ModelDrawCommand.prototype.pushPlanarFillIdCommands = function (
+  frameState,
+  result,
+) {
+  if (!defined(this._planarFillIdCommand)) {
+    return result;
+  }
+
+  const use2D = shouldUse2DCommands(this, frameState);
+  pushCommand(result, this._planarFillIdCommand, use2D);
+
+  return result;
+};
+
 function pushCommand(commandList, derivedCommand, use2D) {
   commandList.push(derivedCommand.command);
   if (use2D) {
@@ -718,6 +807,8 @@ function derive2DCommands(drawCommand) {
   derive2DCommand(drawCommand, drawCommand._silhouetteModelCommand);
   derive2DCommand(drawCommand, drawCommand._silhouetteColorCommand);
   derive2DCommand(drawCommand, drawCommand._edgeCommand);
+  derive2DCommand(drawCommand, drawCommand._edgeSnapCommand);
+  derive2DCommand(drawCommand, drawCommand._planarFillIdCommand);
 }
 
 function deriveTranslucentCommand(command) {
@@ -826,7 +917,13 @@ function deriveSilhouetteColorCommand(command, model) {
   return silhouetteColorCommand;
 }
 
-function deriveEdgeCommand(command, renderResources) {
+// Builds an edge draw command at the given screen-space line width.
+//
+// Two variants are derived per primitive (one for the color pass and one
+// for the snapping pass). Therefore, the visual line width and the snap-pass line
+// width can be set independently. The snap variant is pinned at 1 px to
+// avoid snap wiggle (see initialize). In practice both default to 1 px.
+function deriveEdgeCommand(command, renderResources, lineWidth) {
   const edgeGeometry = renderResources.edgeGeometry;
   const edgeCommand = DrawCommand.shallowClone(command);
 
@@ -848,6 +945,12 @@ function deriveEdgeCommand(command, renderResources) {
   uniformMap.u_isEdgePass = function () {
     return true; // This is the edge pass
   };
+
+  // Set line width uniform for quad-based edge rendering
+  uniformMap.u_lineWidth = function () {
+    return lineWidth;
+  };
+
   edgeCommand.uniformMap = uniformMap;
   edgeCommand.castShadows = false;
   edgeCommand.receiveShadows = false;
@@ -855,6 +958,47 @@ function deriveEdgeCommand(command, renderResources) {
   return edgeCommand;
 }
 
+/**
+ * Derive a command for the planar fill feature-ID pre-pass.
+ *
+ * This command uses the same geometry as the original but writes only a
+ * feature-ID value to the color attachment (no lighting, no material).
+ * The fragment shader outputs <code>vec4(featureId, 0, 0, 1)</code>
+ * via the <code>PLANAR_FILL_ID_PASS</code> define.
+ *
+ * No polygon offset is applied: the pre-pass uses the natural depth of the
+ * non-behind planar fill geometry (same program as the main command minus
+ * the POLYGON_OFFSET path that would shift it).
+ *
+ * Like the other derived commands (translucent, silhouette, edge, etc.),
+ * this is called once per draw command from <code>initialize</code> when the
+ * ModelDrawCommand is constructed — not per frame.
+ *
+ * @param {DrawCommand} command The original draw command.
+ * @returns {DrawCommand} The derived command for the feature-ID pass.
+ * @private
+ */
+function derivePlanarFillIdCommand(command) {
+  const derived = DrawCommand.shallowClone(command);
+  derived.pass = Pass.CESIUM_3D_TILE_PLANAR_FILL_ID;
+  derived.castShadows = false;
+  derived.receiveShadows = false;
+
+  // Use the same render state but disable blending.
+  const rs = clone(command.renderState, true);
+  rs.blending.enabled = false;
+  derived.renderState = RenderState.fromCache(rs);
+
+  // Override uniformMap to set u_isPlanarFillIdPass to true for the pre-pass
+  const uniformMap = clone(command.uniformMap);
+  uniformMap.u_isPlanarFillIdPass = function () {
+    return true;
+  };
+  derived.uniformMap = uniformMap;
+
+  return derived;
+}
+
 function updateSkipLodStencilCommand(drawCommand, tile, use2D) {
   const stencilDerivedComand = drawCommand._skipLodStencilCommand;
   const stencilCommand = stencilDerivedComand.command;

package/Source/Scene/Model/ModelDrawCommands.js

@@ -169,6 +169,9 @@ function buildDrawCommandForModel(
   const pickId = hasClassification
     ? undefined
     : primitiveRenderResources.pickId;
+  const snapId = hasClassification
+    ? undefined
+    : primitiveRenderResources.snapId;
 
   const command = new DrawCommand({
     boundingVolume: boundingSphere,
@@ -182,6 +185,7 @@ function buildDrawCommandForModel(
     count: primitiveRenderResources.count,
     owner: model,
     pickId: pickId,
+    snapId: snapId,
     pickMetadataAllowed: true,
     instanceCount: primitiveRenderResources.instanceCount,
     primitiveType: primitiveRenderResources.primitiveType,

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);
   }
@@ -986,6 +995,7 @@ function updatePrimitiveShowBoundingVolume(runtimePrimitive, options) {
 
 const scratchSilhouetteCommands = [];
 const scratchEdgeCommands = [];
+const scratchPlanarFillIdCommands = [];
 const scratchPushDrawCommandOptions = {
   frameState: undefined,
   hasSilhouette: undefined,
@@ -1011,6 +1021,10 @@ ModelSceneGraph.prototype.pushDrawCommands = function (frameState) {
   const edgeCommands = scratchEdgeCommands;
   edgeCommands.length = 0;
 
+  // Gather planar fill feature-ID pre-pass commands
+  const planarFillIdCommands = scratchPlanarFillIdCommands;
+  planarFillIdCommands.length = 0;
+
   // Since this function is called each frame, the options object is
   // preallocated in a scratch variable
   const pushDrawCommandOptions = scratchPushDrawCommandOptions;
@@ -1026,6 +1040,7 @@ ModelSceneGraph.prototype.pushDrawCommands = function (frameState) {
 
   addAllToArray(frameState.commandList, silhouetteCommands);
   addAllToArray(frameState.commandList, edgeCommands);
+  addAllToArray(frameState.commandList, planarFillIdCommands);
 };
 
 // Callback is defined here to avoid allocating a closure in the render loop
@@ -1036,9 +1051,16 @@ function pushPrimitiveDrawCommands(runtimePrimitive, options) {
   const passes = frameState.passes;
   const silhouetteCommands = scratchSilhouetteCommands;
   const edgeCommands = scratchEdgeCommands;
+  const planarFillIdCommands = scratchPlanarFillIdCommands;
   const primitiveDrawCommand = runtimePrimitive.drawCommand;
   primitiveDrawCommand.pushCommands(frameState, frameState.commandList);
 
+  // Renew the per-frame planar fill request while this primitive renders.
+  const material = runtimePrimitive.primitive.material;
+  if (defined(material) && defined(material.planarFill)) {
+    frameState.planarFillRequested = true;
+  }
+
   // If a model has silhouettes, the commands that draw the silhouettes for
   // each primitive can only be invoked after the entire model has drawn.
   // Otherwise, the silhouette may draw on top of the model. This requires
@@ -1051,6 +1073,14 @@ function pushPrimitiveDrawCommands(runtimePrimitive, options) {
   if (defined(primitiveDrawCommand.pushEdgeCommands)) {
     primitiveDrawCommand.pushEdgeCommands(frameState, edgeCommands);
   }
+
+  // Add planar fill feature-ID pre-pass commands
+  if (defined(primitiveDrawCommand.pushPlanarFillIdCommands)) {
+    primitiveDrawCommand.pushPlanarFillIdCommands(
+      frameState,
+      planarFillIdCommands,
+    );
+  }
 }
 
 /**