@cesium/engine 26.1.0 → 26.2.0

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

@@ -986,6 +986,7 @@ function updatePrimitiveShowBoundingVolume(runtimePrimitive, options) {
 
 const scratchSilhouetteCommands = [];
 const scratchEdgeCommands = [];
+const scratchPlanarFillIdCommands = [];
 const scratchPushDrawCommandOptions = {
   frameState: undefined,
   hasSilhouette: undefined,
@@ -1011,6 +1012,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 +1031,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 +1042,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 +1064,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,
+    );
+  }
 }
 
 /**

package/Source/Scene/Model/PickingPipelineStage.js

@@ -17,6 +17,32 @@ const PickingPipelineStage = {
   name: "PickingPipelineStage", // Helps with debugging
 };
 
+/**
+ * Builds the GLSL expression for the float snap payload written during a
+ * snapping pass (see {@link Scene#snap}), from the expression that evaluates
+ * to the primitive's RGBA8-normalized pick color.
+ *
+ * Channel layout (RGBA32F snap framebuffer):
+ * <ul>
+ *   <li>R: pick ID, repacked from the RGBA8 pick color to a uint32 via
+ *       <code>rgba8UnormToUint32</code> (injected by DerivedCommand.createSnapDerivedCommand).
+ *       Implicitly cast to float32, which represents far more pick IDs than occur in practice.</li>
+ *   <li>G: isEdge flag (0.0/1.0). <code>isEdge</code> is a ModelFS.glsl global, set by
+ *       edge-pass fragments under <code>u_isEdgePass</code>.</li>
+ *   <li>B: linear eye-space depth (<code>-v_positionEC.z</code>, meters). Eye space is
+ *       global across multifrustum and independent of log-depth encoding.</li>
+ *   <li>A: unused</li>
+ * </ul>
+ *
+ * @param {string} pickId The GLSL expression for the RGBA8 pick color.
+ * @returns {string} The GLSL expression for the snap payload.
+ *
+ * @private
+ */
+function snapIdFromPickId(pickId) {
+  return `vec4(rgba8UnormToUint32(${pickId}), isEdge ? 1.0 : 0.0, -v_positionEC.z, 0.0)`;
+}
+
 /**
  * Process a primitive. This modifies the following parts of the render resources:
  * <ul>
@@ -65,6 +91,7 @@ PickingPipelineStage.process = function (
     };
 
     renderResources.pickId = "czm_pickColor";
+    renderResources.snapId = snapIdFromPickId(renderResources.pickId);
   }
 };
 
@@ -157,6 +184,7 @@ function processPickTexture(renderResources, primitive, instances) {
   // The feature ID is ignored if it is greater than the number of features.
   renderResources.pickId =
     "((selectedFeature.id < int(model_featuresLength)) ? texture(model_pickTexture, selectedFeature.st) : vec4(0.0))";
+  renderResources.snapId = snapIdFromPickId(renderResources.pickId);
 }
 
 function processInstancedPickIds(renderResources, context) {
@@ -213,6 +241,7 @@ function processInstancedPickIds(renderResources, context) {
   shaderBuilder.addAttribute("vec4", "a_pickColor");
   shaderBuilder.addVarying("vec4", "v_pickColor");
   renderResources.pickId = "v_pickColor";
+  renderResources.snapId = snapIdFromPickId(renderResources.pickId);
 }
 
 export default PickingPipelineStage;

package/Source/Scene/Model/PrimitiveRenderResources.js

@@ -133,6 +133,19 @@ function PrimitiveRenderResources(nodeRenderResources, runtimePrimitive) {
    */
   this.hasSkipLevelOfDetail = nodeRenderResources.hasSkipLevelOfDetail;
 
+  /**
+   * Whether this primitive writes its feature IDs to the planar fill ID
+   * texture in a pre-pass (BENTLEY_materials_planar_fill). Set by the
+   * material pipeline stage for non-behind planar fill primitives so that
+   * behind fills can test same-object coplanarity. This value indicates
+   * what draw commands are needed.
+   *
+   * @type {boolean}
+   *
+   * @private
+   */
+  this.planarFillIdPass = false;
+
   /**
    * An object used to build a shader incrementally. This is cloned from the
    * node render resources because each primitive can compute a different shader.
@@ -292,6 +305,17 @@ function PrimitiveRenderResources(nodeRenderResources, runtimePrimitive) {
    * @private
    */
   this.pickId = undefined;
+
+  /**
+   * The shader expression for the float snap payload written during a snapping
+   * pass (see Scene#snap). If picking is enabled, this value is set by
+   * PickingPipelineStage.
+   *
+   * @type {string|undefined}
+   *
+   * @private
+   */
+  this.snapId = undefined;
 }
 
 export default PrimitiveRenderResources;

package/Source/Scene/ModelComponents.js

@@ -1578,6 +1578,67 @@ export class LineStyle {
   pattern = undefined;
 }
 
+/**
+ * Planar fill properties from the BENTLEY_materials_planar_fill extension.
+ * Controls the rendering behavior of planar polygon fills for CAD-style visualization.
+ *
+ * @alias ModelComponents.PlanarFill
+ * @constructor
+ *
+ * @private
+ */
+export class PlanarFill {
+  static DEFAULT_WIREFRAME_FILL = 0;
+
+  /**
+   * @param {object} [planarFillInfo={}] The contents of the BENTLEY_materials_planar_fill extension in the parsed glTF JSON.
+   * @param {number} [planarFillInfo.wireframeFill=0] Whether and when the interior fill is displayed in wireframe view mode.
+   * @param {boolean} [planarFillInfo.backgroundFill=false] Whether the fill should be drawn using the view's background color.
+   * @param {boolean} [planarFillInfo.behind=false] Whether the fill should be drawn behind other coplanar geometry of the same logical object.
+   */
+  constructor(planarFillInfo = {}) {
+    const {
+      wireframeFill = PlanarFill.DEFAULT_WIREFRAME_FILL,
+      backgroundFill = false,
+      behind = false,
+    } = planarFillInfo;
+
+    /**
+     * Specifies whether and when the interior fill is displayed in wireframe view mode.
+     * 0 = NONE (never drawn), 1 = ALWAYS (always drawn), 2 = TOGGLE (drawn when fill display is enabled).
+     *
+     * NOTE: This property is currently a NO-OP. CesiumJS does not yet have a proper
+     * wireframe rendering mode (debugWireframe is not a true wireframe mode). The
+     * value is loaded and stored for completeness, but it has no effect on rendering.
+     * This will be implemented when CesiumJS adds a proper wireframe view mode.
+     * See https://github.com/CesiumGS/cesium/issues/13620.
+     *
+     * @type {number}
+     * @default 0
+     */
+    this.wireframeFill = wireframeFill;
+
+    /**
+     * If true, the fill should be drawn using the view's background color,
+     * creating an invisible masking polygon.
+     *
+     * @type {boolean}
+     * @default false
+     */
+    this.backgroundFill = backgroundFill;
+
+    /**
+     * If true, the fill should be drawn behind other coplanar geometry
+     * belonging to the same logical object, useful for mitigating z-fighting
+     * with overlaid geometry such as hatch patterns or text.
+     *
+     * @type {boolean}
+     * @default false
+     */
+    this.behind = behind;
+  }
+}
+
 /**
  * The material appearance of a primitive.
  *
@@ -1709,6 +1770,15 @@ export class Material {
      */
     this.pointDiameter = undefined;
 
+    /**
+     * Planar fill properties from the BENTLEY_materials_planar_fill extension.
+     * Controls the rendering behavior of planar polygon fills for CAD-style visualization.
+     *
+     * @type {ModelComponents.PlanarFill}
+     * @private
+     */
+    this.planarFill = undefined;
+
     /**
      * Material properties for the BENTLEY_materials_line_style extension.
      *
@@ -1799,6 +1869,7 @@ ModelComponents.SpecularGlossiness = SpecularGlossiness;
 ModelComponents.Specular = Specular;
 ModelComponents.Anisotropy = Anisotropy;
 ModelComponents.Clearcoat = Clearcoat;
+ModelComponents.PlanarFill = PlanarFill;
 ModelComponents.LineStyle = LineStyle;
 ModelComponents.Material = Material;
 ModelComponents.Vector = Vector;

package/Source/Scene/Picking.js

@@ -266,22 +266,31 @@ function computePickingDrawingBufferRectangle(
 /**
  * Setup needed before picking.
  *
+ * Exported for use by Snapping, which performs the same offscreen pick render
+ * but targets the snap framebuffer and flags the pass as a snapping pass.
+ *
  * @param {Scene} scene
  * @param {Cartesian2} windowPosition Window coordinates to perform picking on.
  * @param {BoundingRectangle} drawingBufferRectangle The output drawing buffer recangle.
  * @param {number} [width=3] Width of the pick rectangle.
  * @param {number} [height=3] Height of the pick rectangle.
- * @ignore
+ * @param {object} [options] Object with the following properties:
+ * @param {PickFramebuffer|SnapFramebuffer} [options.framebuffer] The framebuffer to render into. Defaults to the view's pick framebuffer.
+ * @param {boolean} [options.snap=false] If <code>true</code>, mark the pass as a snapping pass (sets <code>frameState.passes.snap</code>).
+ *
+ * @private
  */
-function pickBegin(
+export function pickBegin(
   scene,
   windowPosition,
   drawingBufferRectangle,
   width,
   height,
+  options,
 ) {
   const { context, frameState, defaultView } = scene;
   const { viewport, pickFramebuffer } = defaultView;
+  const framebuffer = options?.framebuffer ?? pickFramebuffer;
 
   scene.view = defaultView;
 
@@ -318,13 +327,14 @@ function pickBegin(
   );
   frameState.invertClassification = false;
   frameState.passes.pick = true;
+  frameState.passes.snap = options?.snap ?? false;
   frameState.tilesetPassState = pickTilesetPassState;
 
   context.uniformState.update(frameState);
 
   scene.updateEnvironment();
 
-  passState = pickFramebuffer.begin(drawingBufferRectangle, viewport);
+  passState = framebuffer.begin(drawingBufferRectangle, viewport);
 
   scene.updateAndExecuteCommands(passState, scratchColorZero);
   scene.resolveFramebuffers(passState);
@@ -334,9 +344,10 @@ function pickBegin(
  * Teardown needed after picking.
  *
  * @param {Scene} scene
- * @ignore
+ *
+ * @private
  */
-function pickEnd(scene) {
+export function pickEnd(scene) {
   const { context } = scene;
   context.endFrame();
 }