@hztxi/cesium-engine 25.0.6 → 26.2.1

package/Source/Scene/Model/MaterialPipelineStage.js

@@ -170,13 +170,28 @@ MaterialPipelineStage.process = function (
   const disablePointCloudNormals =
     defined(model.pointCloudShading) && !model.pointCloudShading.normalShading;
 
+  if (defined(material.planarFill)) {
+    processPlanarFill(
+      material.planarFill,
+      primitive,
+      renderResources,
+      frameState,
+    );
+  }
+
+  // When backgroundFill is true (BENTLEY_materials_planar_fill), the primitive
+  // must be unlit so it matches the background color exactly.
+  const hasBackgroundFill =
+    defined(material.planarFill) && material.planarFill.backgroundFill;
+
   // Classification models will be rendered as unlit.
   const lightingOptions = renderResources.lightingOptions;
   if (
     material.unlit ||
     !hasNormals ||
     hasClassification ||
-    disablePointCloudNormals
+    disablePointCloudNormals ||
+    hasBackgroundFill
   ) {
     lightingOptions.lightingModel = LightingModel.UNLIT;
   } else {
@@ -232,6 +247,114 @@ MaterialPipelineStage.process = function (
   }
 };
 
+/**
+ * Add uniforms and defines for the BENTLEY_materials_planar_fill extension.
+ *
+ * Per the BENTLEY_materials_planar_fill spec:
+ * <ul>
+ *   <li>ALL planar primitives must render in front of non-planar (Depth Ordering).</li>
+ *   <li><code>behind</code> fills must render behind coplanar geometry from the SAME
+ *   logical object only (same feature ID from EXT_mesh_features).</li>
+ * </ul>
+ *
+ * Instead of using fixed polygon offset units (which don't scale well with
+ * logarithmic depth), we use proportional depth scaling in the shader.
+ * This approach matches the edge visibility system and scales naturally
+ * at all viewing distances.
+ *
+ * @param {ModelComponents.PlanarFill} planarFill The planar fill properties of the material
+ * @param {ModelComponents.Primitive} primitive The primitive to be rendered
+ * @param {PrimitiveRenderResources} renderResources The render resources for the primitive
+ * @param {FrameState} frameState The frame state.
+ * @private
+ */
+function processPlanarFill(planarFill, primitive, renderResources, frameState) {
+  const { uniformMap, shaderBuilder } = renderResources;
+
+  // Signal to Scene that the planar fill ID framebuffer is needed.
+  frameState.planarFillRequested = true;
+
+  // All planar fills get a proportional depth pull toward camera. Behind fills
+  // additionally sample the planar fill ID texture to test same-feature; if so,
+  // they apply a small proportional push to sit behind non-behind geometry.
+  shaderBuilder.addDefine(
+    "HAS_PLANAR_FILL_DEPTH",
+    undefined,
+    ShaderDestination.FRAGMENT,
+  );
+
+  // Configure background fill for BENTLEY_materials_planar_fill extension.
+  // When backgroundFill is true, the fill is rendered using the view's background color
+  // to create an invisible masking polygon. Lighting is forced to unlit in process().
+  //
+  // NOTE: The wireframeFill property from BENTLEY_materials_planar_fill is intentionally
+  // not handled here. CesiumJS does not yet have a proper wireframe rendering mode
+  // (debugWireframe is not a true wireframe mode), so wireframeFill is loaded as a NO-OP.
+  // When a proper wireframe mode is added to CesiumJS, wireframeFill support should be
+  // implemented here to control fill visibility in that mode. See
+  // https://github.com/CesiumGS/cesium/issues/13620.
+  if (planarFill.backgroundFill) {
+    shaderBuilder.addDefine(
+      "HAS_BACKGROUND_FILL",
+      undefined,
+      ShaderDestination.FRAGMENT,
+    );
+  }
+
+  const hasFeatureIds =
+    defined(primitive.featureIds) && primitive.featureIds.length > 0;
+  if (!hasFeatureIds) {
+    return;
+  }
+
+  // "Same logical object" is implementation-defined per the spec; this
+  // implementation uses the primitive's first feature ID set. Primitives
+  // without feature IDs (checked above) don't participate in the
+  // behind-fill same-object test.
+  const featureIdMember = primitive.featureIds[0].positionalLabel;
+  shaderBuilder.addDefine(
+    "PLANAR_FILL_FEATURE_ID",
+    featureIdMember,
+    ShaderDestination.FRAGMENT,
+  );
+
+  if (planarFill.behind) {
+    // Behind fills READ the planar fill ID texture to test whether the
+    // pixel they cover belongs to the same logical object.
+    shaderBuilder.addDefine(
+      "HAS_PLANAR_FILL_BEHIND",
+      undefined,
+      ShaderDestination.FRAGMENT,
+    );
+  } else {
+    // Non-behind fills WRITE their feature IDs to the planar fill ID
+    // texture in a pre-pass so behind fills can test same-object
+    // coplanarity. Mark this primitive for the pre-pass derived command.
+    renderResources.planarFillIdPass = true;
+
+    // Add a define so that during the pre-pass the shader outputs
+    // the feature ID instead of the normal color.
+    shaderBuilder.addDefine(
+      "HAS_PLANAR_FILL_ID_PASS",
+      undefined,
+      ShaderDestination.FRAGMENT,
+    );
+
+    // Runtime uniform to distinguish the pre-pass from the main pass
+    // (same shader program serves both commands). This default returns false
+    // for the main command; the derived pre-pass command overrides it to
+    // return true (see derivePlanarFillIdCommand in ModelDrawCommand.js).
+    shaderBuilder.addUniform(
+      "bool",
+      "u_isPlanarFillIdPass",
+      ShaderDestination.FRAGMENT,
+    );
+    uniformMap.u_isPlanarFillIdPass = function () {
+      return false;
+    };
+  }
+}
+
 /**
  * Process constant LOD extension for a texture
  *

package/Source/Scene/Model/Model.js

@@ -20,6 +20,7 @@ import ClippingPlaneCollection from "../ClippingPlaneCollection.js";
 import ClippingPolygonCollection from "../ClippingPolygonCollection.js";
 import DynamicEnvironmentMapManager from "../DynamicEnvironmentMapManager.js";
 import ColorBlendMode from "../ColorBlendMode.js";
+import EdgeDisplayMode from "../EdgeDisplayMode.js";
 import GltfLoader from "../GltfLoader.js";
 import HeightReference, {
   isHeightReferenceRelative,
@@ -72,7 +73,12 @@ import ModelImagery from "./ModelImagery.js";
  *  {@link https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Vendor/EXT_mesh_gpu_instancing|EXT_mesh_gpu_instancing}
  *  </li>
  *  <li>
- *  {@link https://github.com/KhronosGroup/glTF/pull/2514|EXT_mesh_primitive_restart}
+ *  {@link https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Vendor/EXT_mesh_primitive_restart|EXT_mesh_primitive_restart}
+ *  </li>
+ *  <li>
+ *  {@link https://github.com/KhronosGroup/glTF/pull/2479|EXT_mesh_primitive_edge_visibility}
+ *  (edges are hidden by default; set {@link EdgeDisplayMode} via
+ *  {@link Model#edgeDisplayMode} or {@link Cesium3DTileset#edgeDisplayMode} to display them)
  *  </li>
  *  <li>
  *  {@link https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Vendor/EXT_meshopt_compression|EXT_meshopt_compression}
@@ -99,9 +105,16 @@ import ModelImagery from "./ModelImagery.js";
  *  {@link https://github.com/KhronosGroup/glTF/tree/master/extensions/2.0/Khronos/KHR_materials_unlit/README.md|KHR_materials_unlit}
  *  </li>
  *  <li>
+ *  {@link https://github.com/KhronosGroup/glTF/pull/2569|KHR_mesh_primitive_restart}
+ *  (requires a WebGL 2 context; behavior on WebGL 1 is undefined)
+ *  </li>
+ *  <li>
  *  {@link https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Khronos/KHR_mesh_quantization|KHR_mesh_quantization}
  *  </li>
  *  <li>
+ *  {@link https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Khronos/KHR_meshopt_compression|KHR_meshopt_compression}
+ *  </li>
+ *  <li>
  *  {@link https://github.com/KhronosGroup/glTF/blob/master/extensions/2.0/Khronos/KHR_texture_basisu|KHR_texture_basisu}
  *  </li>
  *  <li>
@@ -151,6 +164,7 @@ import ModelImagery from "./ModelImagery.js";
  * @privateParam {Color} [options.color] A color that blends with the model's rendered color.
  * @privateParam {ColorBlendMode} [options.colorBlendMode=ColorBlendMode.HIGHLIGHT] Defines how the color blends with the model.
  * @privateParam {number} [options.colorBlendAmount=0.5] Value used to determine the color strength when the <code>colorBlendMode</code> is <code>MIX</code>. A value of 0.0 results in the model's rendered color while a value of 1.0 results in a solid color, with any value in-between resulting in a mix of the two.
+ * @privateParam {EdgeDisplayMode} [options.edgeDisplayMode=EdgeDisplayMode.SURFACES_ONLY] Controls how edges from the {@link https://github.com/KhronosGroup/glTF/pull/2479|EXT_mesh_primitive_edge_visibility} extension are rendered relative to surface geometry.
  * @privateParam {Color} [options.silhouetteColor=Color.RED] The silhouette color. If more than 256 models have silhouettes enabled, there is a small chance that overlapping models will have minor artifacts.
  * @privateParam {number} [options.silhouetteSize=0.0] The size of the silhouette in pixels.
  * @privateParam {boolean} [options.enableShowOutline=true] Whether to enable outlines for models using the {@link https://github.com/KhronosGroup/glTF/tree/master/extensions/2.0/Vendor/CESIUM_primitive_outline|CESIUM_primitive_outline} extension. This can be set to false to avoid the additional processing of geometry at load time. When false, the showOutlines and outlineColor options are ignored.
@@ -259,6 +273,7 @@ function Model(options) {
    */
   this.referenceMatrix = undefined;
   this._iblReferenceFrameMatrix = Matrix3.clone(Matrix3.IDENTITY); // Derived from reference matrix and the current view matrix
+  this._clippingPlanesMatrix = Matrix4.clone(Matrix4.IDENTITY); // Derived from the reference matrix and the clipping planes' own model matrix
 
   this._resourcesLoaded = false;
   this._drawCommandsBuilt = false;
@@ -370,7 +385,6 @@ function Model(options) {
     this._clippingPlanes = clippingPlanes;
   }
   this._clippingPlanesState = 0; // If this value changes, the shaders need to be regenerated.
-  this._clippingPlanesMatrix = Matrix4.clone(Matrix4.IDENTITY); // Derived from reference matrix and the current view matrix
 
   // If the given clipping polygons don't have an owner, make this model its owner.
   // Otherwise, the clipping polygons are passed down from a tileset.
@@ -417,6 +431,8 @@ function Model(options) {
   this._enableDebugWireframe = options.enableDebugWireframe ?? false;
   this._enableShowOutline = options.enableShowOutline ?? true;
   this._debugWireframe = options.debugWireframe ?? false;
+  this._edgeDisplayMode =
+    options.edgeDisplayMode ?? EdgeDisplayMode.SURFACES_ONLY;
 
   // Warning for improper setup of debug wireframe
   if (
@@ -1204,6 +1220,29 @@ Object.defineProperties(Model.prototype, {
     },
   },
 
+  /**
+   * Controls how edges from the
+   * {@link https://github.com/KhronosGroup/glTF/pull/2479|EXT_mesh_primitive_edge_visibility}
+   * glTF extension are rendered relative to surface geometry. Primitives that
+   * do not declare the extension are unaffected by this setting.
+   *
+   * @memberof Model.prototype
+   *
+   * @type {EdgeDisplayMode}
+   *
+   * @default EdgeDisplayMode.SURFACES_ONLY
+   *
+   * @experimental This feature is using part of the glTF spec that is not yet final and is subject to change without Cesium's standard deprecation policy.
+   */
+  edgeDisplayMode: {
+    get: function () {
+      return this._edgeDisplayMode;
+    },
+    set: function (value) {
+      this._edgeDisplayMode = value;
+    },
+  },
+
   /**
    * Whether or not to render the model.
    *
@@ -2444,16 +2483,10 @@ function updateReferenceMatrices(model, frameState) {
   );
 
   if (model.isClippingEnabled()) {
-    let clippingPlanesMatrix = scratchClippingPlanesMatrix;
-    clippingPlanesMatrix = Matrix4.multiply(
-      context.uniformState.view3D,
+    const clippingPlanesMatrix = Matrix4.multiply(
       referenceMatrix,
-      clippingPlanesMatrix,
-    );
-    clippingPlanesMatrix = Matrix4.multiply(
-      clippingPlanesMatrix,
       model._clippingPlanes.modelMatrix,
-      clippingPlanesMatrix,
+      scratchClippingPlanesMatrix,
     );
     model._clippingPlanesMatrix = Matrix4.inverseTranspose(
       clippingPlanesMatrix,
@@ -2941,6 +2974,7 @@ Model.prototype.destroyModelResources = function () {
  * @param {Color} [options.color] A color that blends with the model's rendered color.
  * @param {ColorBlendMode} [options.colorBlendMode=ColorBlendMode.HIGHLIGHT] Defines how the color blends with the model.
  * @param {number} [options.colorBlendAmount=0.5] Value used to determine the color strength when the <code>colorBlendMode</code> is <code>MIX</code>. A value of 0.0 results in the model's rendered color while a value of 1.0 results in a solid color, with any value in-between resulting in a mix of the two.
+ * @param {EdgeDisplayMode} [options.edgeDisplayMode=EdgeDisplayMode.SURFACES_ONLY] Controls how edges from the {@link https://github.com/KhronosGroup/glTF/pull/2479|EXT_mesh_primitive_edge_visibility} extension are rendered relative to surface geometry.
  * @param {Color} [options.silhouetteColor=Color.RED] The silhouette color. If more than 256 models have silhouettes enabled, there is a small chance that overlapping models will have minor artifacts.
  * @param {number} [options.silhouetteSize=0.0] The size of the silhouette in pixels.
  * @param {boolean} [options.enableShowOutline=true] Whether to enable outlines for models using the {@link https://github.com/KhronosGroup/glTF/tree/master/extensions/2.0/Vendor/CESIUM_primitive_outline|CESIUM_primitive_outline} extension. This can be set false to avoid post-processing geometry at load time. When false, the showOutlines and outlineColor options are ignored.
@@ -3307,6 +3341,7 @@ function makeModelOptions(loader, modelType, options) {
     color: options.color,
     colorBlendAmount: options.colorBlendAmount,
     colorBlendMode: options.colorBlendMode,
+    edgeDisplayMode: options.edgeDisplayMode,
     silhouetteColor: options.silhouetteColor,
     silhouetteSize: options.silhouetteSize,
     enableShowOutline: options.enableShowOutline,