@hztxi/cesium-engine 25.0.6 → 26.2.1

package/Source/Scene/Model/ModelClippingPlanesPipelineStage.js

@@ -2,6 +2,7 @@ import Cartesian2 from "../../Core/Cartesian2.js";
 import ClippingPlaneCollection from "../ClippingPlaneCollection.js";
 import combine from "../../Core/combine.js";
 import Color from "../../Core/Color.js";
+import Matrix4 from "../../Core/Matrix4.js";
 import ModelClippingPlanesStageFS from "../../Shaders/Model/ModelClippingPlanesStageFS.js";
 import ShaderDestination from "../../Renderer/ShaderDestination.js";
 
@@ -17,6 +18,9 @@ const ModelClippingPlanesPipelineStage = {
 };
 
 const textureResolutionScratch = new Cartesian2();
+const scratchClippingPlanesMatrix = new Matrix4();
+const scratchClippingPlanesMatrix2 = new Matrix4();
+
 /**
  * Process a model. This modifies the following parts of the render resources:
  *
@@ -116,7 +120,30 @@ ModelClippingPlanesPipelineStage.process = function (
       return style;
     },
     model_clippingPlanesMatrix: function () {
-      return model._clippingPlanesMatrix;
+      // The clipping planes matrix is factored into a view-dependent and a
+      // view-independent part:
+      //   inverseTranspose(view3D * reference * clipping)
+      //     = transpose(inverseView3D) * inverseTranspose(reference * clipping).
+      //
+      // The view-dependent part, transpose(inverseView3D), reuses inverseView3D
+      // already maintained on UniformState. Since it uses the active view, this is
+      // also correct in the shadow cast pass, where inverseView3D is the light's
+      // view rather than the camera's. Only a transpose is needed here, no inverse.
+      const inverseViewTranspose = Matrix4.transpose(
+        context.uniformState.inverseView3D,
+        scratchClippingPlanesMatrix,
+      );
+      // The view-independent part, inverseTranspose(reference * clipping), is
+      // computed once per frame in Model.updateReferenceMatrices.
+      //
+      // This recomputes the same product for every primitive of a model within
+      // a pass. If it ever shows up in profiling, see the discussion of
+      // alternatives in https://github.com/CesiumGS/cesium/pull/13388.
+      return Matrix4.multiply(
+        inverseViewTranspose,
+        model._clippingPlanesMatrix,
+        scratchClippingPlanesMatrix2,
+      );
     },
   };
 

package/Source/Scene/Model/ModelDrawCommand.js

@@ -14,6 +14,7 @@ import BlendingState from "../BlendingState.js";
 import CullFace from "../CullFace.js";
 import SceneMode from "../SceneMode.js";
 import ShadowMode from "../ShadowMode.js";
+import EdgeDisplayMode from "../EdgeDisplayMode.js";
 import StencilConstants from "../StencilConstants.js";
 import StencilFunction from "../StencilFunction.js";
 import StencilOperation from "../StencilOperation.js";
@@ -102,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;
@@ -111,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 = [];
@@ -225,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,
@@ -234,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);
   }
 }
 
@@ -572,13 +612,17 @@ ModelDrawCommand.prototype.pushCommands = function (frameState, result) {
     return;
   }
 
-  pushCommand(result, this._originalCommand, use2D);
-
-  // Push edge commands after the original command
-  if (this._needsEdgeCommands) {
-    pushCommand(result, this._edgeCommand, use2D);
+  // Skip surface rendering if EDGES_ONLY mode is enabled and this primitive
+  // has edge visibility data. Only the edges will render (via pushEdgeCommands).
+  if (
+    this._model.edgeDisplayMode === EdgeDisplayMode.EDGES_ONLY &&
+    this._needsEdgeCommands
+  ) {
+    return result;
   }
 
+  pushCommand(result, this._originalCommand, use2D);
+
   return result;
 };
 
@@ -623,12 +667,87 @@ ModelDrawCommand.prototype.pushEdgeCommands = function (frameState, result) {
     return result;
   }
 
+  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;
+  }
+
+  // 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 =
+    mode === EdgeDisplayMode.EDGES_ONLY
+      ? Pass.CESIUM_3D_TILE_EDGES_DIRECT
+      : Pass.CESIUM_3D_TILE_EDGES;
+
+  this._edgeCommand.command.pass = edgePass;
+  if (defined(this._edgeCommand.derivedCommand2D)) {
+    this._edgeCommand.derivedCommand2D.command.pass = edgePass;
+  }
+
   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) {
@@ -688,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) {
@@ -796,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);
 
@@ -818,7 +945,11 @@ function deriveEdgeCommand(command, renderResources) {
   uniformMap.u_isEdgePass = function () {
     return true; // This is the edge pass
   };
-  edgeCommand.uniformMap = uniformMap;
+
+  // Set line width uniform for quad-based edge rendering
+  uniformMap.u_lineWidth = function () {
+    return lineWidth;
+  };
 
   edgeCommand.uniformMap = uniformMap;
   edgeCommand.castShadows = false;
@@ -827,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/ModelUtility.js

@@ -345,6 +345,7 @@ ModelUtility.sanitizeGlslIdentifier = function (identifier) {
 
 ModelUtility.supportedExtensions = {
   AGI_articulations: true,
+  CESIUM_mesh_vector: true,
   CESIUM_primitive_outline: true,
   CESIUM_RTC: true,
   EXT_feature_metadata: true,
@@ -353,6 +354,8 @@ ModelUtility.supportedExtensions = {
   EXT_instance_features: true,
   EXT_mesh_features: true,
   EXT_mesh_gpu_instancing: true,
+  EXT_mesh_polygon: true,
+  EXT_mesh_primitive_edge_visibility: true,
   EXT_meshopt_compression: true,
   EXT_primitive_voxels: true,
   EXT_structural_metadata: true,
@@ -367,6 +370,8 @@ ModelUtility.supportedExtensions = {
   KHR_materials_clearcoat: true,
   KHR_materials_unlit: true,
   KHR_mesh_quantization: true,
+  KHR_mesh_primitive_restart: true,
+  KHR_meshopt_compression: true,
   KHR_techniques_webgl: true,
   KHR_texture_basisu: true,
   KHR_texture_transform: true,

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;