@cesium/engine 26.1.0 → 26.3.0

package/Source/Scene/Model/ModelVectorLookupPipelineStage.js

@@ -0,0 +1,205 @@
+// @ts-check
+
+import Cartesian2 from "../../Core/Cartesian2.js";
+import combine from "../../Core/combine.js";
+import CesiumMath from "../../Core/Math.js";
+import ShaderDestination from "../../Renderer/ShaderDestination.js";
+import VectorCommon from "../../Shaders/VectorCommon.js";
+import ModelVectorLookupStageVS from "../../Shaders/Model/ModelVectorLookupStageVS.js";
+import ModelVectorLookupStageFS from "../../Shaders/Model/ModelVectorLookupStageFS.js";
+
+/** @import FrameState from "../FrameState.js"; */
+/** @import Model from "./Model.js"; */
+/** @import ModelRenderResources from "./ModelRenderResources.js"; */
+
+/**
+ * The model vector lookup stage drapes vector data, baked into
+ * per-content lookup textures by the scene's VectorProvider, onto the model's
+ * surface.
+ *
+ * @namespace ModelVectorLookupPipelineStage
+ *
+ * @private
+ */
+const ModelVectorLookupPipelineStage = {
+  name: "ModelVectorLookupPipelineStage", // Helps with debugging
+  process: process,
+};
+
+const scratchCameraUv = new Cartesian2();
+const scratchRectangleInverseSize = new Cartesian2();
+
+/**
+ * Processes a model with baked vector lookup data. This modifies the
+ * following parts of the render resources:
+ *
+ * <ul>
+ *  <li>adds the HAS_VECTOR_LOOKUP define to both shaders</li>
+ *  <li>adds a vertex shader function computing the vertex's UV within the baked rectangle</li>
+ *  <li>adds the shared vector lookup functions and a compositing function to the fragment shader</li>
+ *  <li>adds the uniforms for the baked rectangle and the lookup textures</li>
+ * </ul>
+ *
+ * @param {ModelRenderResources} renderResources The render resources for this model.
+ * @param {Model} model The model.
+ * @param {FrameState} frameState The frameState.
+ *
+ * @private
+ */
+function process(renderResources, model, frameState) {
+  const shaderBuilder = renderResources.shaderBuilder;
+  const vectorData = model._vectorData;
+  const hasPolylines = vectorData.hasPolylines;
+  const hasPolygons = vectorData.hasPolygons;
+
+  shaderBuilder.addDefine(
+    "HAS_VECTOR_LOOKUP",
+    undefined,
+    ShaderDestination.BOTH,
+  );
+
+  if (hasPolylines) {
+    shaderBuilder.addDefine(
+      "HAS_VECTOR_POLYLINES",
+      undefined,
+      ShaderDestination.FRAGMENT,
+    );
+
+    if (vectorData.hasMeterWidths) {
+      shaderBuilder.addDefine(
+        "VECTOR_WIDTH_IN_METERS",
+        undefined,
+        ShaderDestination.FRAGMENT,
+      );
+      if (vectorData.hasPixelWidths) {
+        shaderBuilder.addDefine(
+          "VECTOR_WIDTH_MIXED_UNITS",
+          undefined,
+          ShaderDestination.FRAGMENT,
+        );
+      }
+      shaderBuilder.addUniform(
+        "vec2",
+        "u_vectorMetersPerUv",
+        ShaderDestination.FRAGMENT,
+      );
+    }
+  }
+
+  if (hasPolygons) {
+    shaderBuilder.addDefine(
+      "HAS_VECTOR_POLYGONS",
+      undefined,
+      ShaderDestination.FRAGMENT,
+    );
+  }
+
+  shaderBuilder.addUniform(
+    "vec2",
+    "u_vectorCameraUv",
+    ShaderDestination.VERTEX,
+  );
+  shaderBuilder.addUniform(
+    "vec2",
+    "u_vectorRectangleInverseSize",
+    ShaderDestination.VERTEX,
+  );
+
+  shaderBuilder.addVarying("vec2", "v_vectorUv");
+  shaderBuilder.addVertexLines(ModelVectorLookupStageVS);
+  // VectorCommon declares the lookup texture uniforms and sampling functions
+  // shared with the terrain path.
+  shaderBuilder.addFragmentLines(VectorCommon);
+  shaderBuilder.addFragmentLines(ModelVectorLookupStageFS);
+
+  // A re-bake replaces _vectorData, and its rectangle, without rebuilding draw
+  // commands, so the callbacks read the rectangle per call.
+  const buildRectangle = vectorData.rectangle;
+
+  const defaultTexture = function () {
+    return frameState.context.defaultTexture;
+  };
+
+  /** @type {Object<string, Function>} */
+  const uniformMap = {
+    // The UV coordinates of the camera within the baked rectangle.
+    u_vectorCameraUv: function () {
+      const rectangle = model._vectorData?.rectangle ?? buildRectangle;
+      const carto = frameState.camera.positionCartographic;
+
+      const halfWidth = rectangle.width * 0.5;
+      const centerLongitude = rectangle.west + halfWidth;
+      const longitudeOffset =
+        CesiumMath.negativePiToPi(carto.longitude - centerLongitude) +
+        halfWidth;
+      return Cartesian2.fromElements(
+        longitudeOffset / rectangle.width,
+        (carto.latitude - rectangle.south) / rectangle.height,
+        scratchCameraUv,
+      );
+    },
+    u_vectorRectangleInverseSize: function () {
+      const rectangle = model._vectorData?.rectangle ?? buildRectangle;
+      return Cartesian2.fromElements(
+        1.0 / rectangle.width,
+        1.0 / rectangle.height,
+        scratchRectangleInverseSize,
+      );
+    },
+    u_vectorColorTexture: function () {
+      return model._vectorData?.colorTexture ?? defaultTexture();
+    },
+    u_vectorPickColorTexture: function () {
+      return model._vectorData?.pickColorTexture ?? defaultTexture();
+    },
+  };
+
+  if (hasPolylines) {
+    uniformMap.u_vectorSegmentTexture = function () {
+      return model._vectorData?.polylineSegmentTexture ?? defaultTexture();
+    };
+    uniformMap.u_vectorWidthTexture = function () {
+      return model._vectorData?.widthTexture ?? defaultTexture();
+    };
+    uniformMap.u_vectorSegmentPrimitiveIndicesTexture = function () {
+      return (
+        model._vectorData?.polylineSegmentPrimitiveIndicesTexture ??
+        defaultTexture()
+      );
+    };
+    uniformMap.u_vectorGridCellIndicesTexture = function () {
+      return (
+        model._vectorData?.polylineGridCellIndicesTexture ?? defaultTexture()
+      );
+    };
+
+    if (vectorData.hasMeterWidths) {
+      uniformMap.u_vectorMetersPerUv = function () {
+        return model._vectorData.metersPerUv;
+      };
+    }
+  }
+
+  if (hasPolygons) {
+    uniformMap.u_vectorPolygonEdgeTexture = function () {
+      return model._vectorData?.polygonEdgeTexture ?? defaultTexture();
+    };
+    uniformMap.u_vectorPolygonEdgePrimitiveIndicesTexture = function () {
+      return (
+        model._vectorData?.polygonEdgePrimitiveIndicesTexture ??
+        defaultTexture()
+      );
+    };
+    uniformMap.u_vectorPolygonGridCellIndicesTexture = function () {
+      return (
+        model._vectorData?.polygonGridCellIndicesTexture ?? defaultTexture()
+      );
+    };
+  }
+
+  renderResources.uniformMap = /** @type {Object<string, Function>} */ (
+    combine(uniformMap, renderResources.uniformMap)
+  );
+}
+
+export default ModelVectorLookupPipelineStage;

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,11 @@ PickingPipelineStage.process = function (
     };
 
     renderResources.pickId = "czm_pickColor";
+    renderResources.snapId = snapIdFromPickId(renderResources.pickId);
+  }
+
+  if (!defined(model.classificationType) && model.hasDrapedVectors()) {
+    renderResources.pickId = `vectorPickColorOver(${renderResources.pickId})`;
   }
 };
 
@@ -157,6 +188,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 +245,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();
 }

package/Source/Scene/PlanarFillIdFramebuffer.js

@@ -0,0 +1,172 @@
+import defined from "../Core/defined.js";
+import destroyObject from "../Core/destroyObject.js";
+import PixelFormat from "../Core/PixelFormat.js";
+import Color from "../Core/Color.js";
+import PixelDatatype from "../Renderer/PixelDatatype.js";
+import FramebufferManager from "../Renderer/FramebufferManager.js";
+import ClearCommand from "../Renderer/ClearCommand.js";
+
+/**
+ * Creates and manages a framebuffer for the planar fill feature-ID pre-pass.
+ *
+ * During this pass, non-behind planar fill geometry writes its per-fragment
+ * feature ID into a screen-sized texture. Later, primitives with
+ * <code>behind: true</code> (BENTLEY_materials_planar_fill) sample this
+ * texture to check whether the pixel they are about to overwrite belongs to
+ * the same logical object (same feature ID). Only then do they apply an
+ * additional depth offset, pushing the fill behind its own object's edges
+ * and non-behind fills — but NOT behind other objects.
+ *
+ * Layout:
+ *   Color attachment 0 – R32F (single RED channel): encoded feature ID.
+ *   Depth-stencil attachment – shared with the main scene for correct depth testing.
+ *
+ * @alias PlanarFillIdFramebuffer
+ * @constructor
+ * @private
+ */
+function PlanarFillIdFramebuffer() {
+  this._framebufferManager = new FramebufferManager({
+    colorAttachmentsLength: 1,
+    createColorAttachments: true,
+    depthStencil: true,
+    supportsDepthTexture: true,
+    color: true,
+  });
+
+  this._framebuffer = undefined;
+  this._idTexture = undefined;
+  this._depthStencilTexture = undefined;
+
+  this._clearCommand = new ClearCommand({
+    color: new Color(0.0, 0.0, 0.0, 0.0),
+    depth: 1.0,
+    stencil: 0,
+    owner: this,
+  });
+}
+
+Object.defineProperties(PlanarFillIdFramebuffer.prototype, {
+  /**
+   * Gets the underlying framebuffer.
+   * @memberof PlanarFillIdFramebuffer.prototype
+   * @type {Framebuffer}
+   * @readonly
+   */
+  framebuffer: {
+    get: function () {
+      return this._framebuffer;
+    },
+  },
+
+  /**
+   * Gets the feature-ID texture (color attachment 0).
+   * @memberof PlanarFillIdFramebuffer.prototype
+   * @type {Texture}
+   * @readonly
+   */
+  idTexture: {
+    get: function () {
+      return this._idTexture;
+    },
+  },
+
+  /**
+   * Gets the depth-stencil texture.
+   * @memberof PlanarFillIdFramebuffer.prototype
+   * @type {Texture}
+   * @readonly
+   */
+  depthStencilTexture: {
+    get: function () {
+      return this._depthStencilTexture;
+    },
+  },
+});
+
+/**
+ * Updates (creates / resizes) the framebuffer to match the viewport.
+ *
+ * @param {Context} context
+ * @param {BoundingRectangle} viewport
+ * @param {boolean} hdr
+ * @returns {boolean} <code>true</code> if the framebuffer was recreated.
+ */
+PlanarFillIdFramebuffer.prototype.update = function (context, viewport, hdr) {
+  const width = viewport.width;
+  const height = viewport.height;
+
+  // Feature IDs are integers, so a 32-bit float channel provides plenty of range
+  // for feature IDs. A single RED channel (R32F) is used since only one value is
+  // stored per pixel. Rendering to R32F requires EXT_color_buffer_float, which is
+  // available in WebGL2 on all browsers CesiumJS supports; the UNSIGNED_BYTE fallback
+  // below only exists for stubbed WebGL contexts possibly used in tests.
+  const pixelDatatype = context.colorBufferFloat
+    ? PixelDatatype.FLOAT
+    : PixelDatatype.UNSIGNED_BYTE;
+
+  const changed = this._framebufferManager.update(
+    context,
+    width,
+    height,
+    1, // no MSAA
+    pixelDatatype,
+    PixelFormat.RED,
+  );
+
+  if (this._framebufferManager.framebuffer) {
+    this._framebuffer = this._framebufferManager.framebuffer;
+    this._idTexture = this._framebufferManager.getColorTexture(0);
+    this._depthStencilTexture =
+      this._framebufferManager.getDepthStencilTexture();
+  }
+
+  return changed;
+};
+
+/**
+ * Returns a ClearCommand that targets this framebuffer.
+ *
+ * @param {Color} [clearColor] Override the clear color (default: transparent black).
+ * @returns {ClearCommand}
+ */
+PlanarFillIdFramebuffer.prototype.getClearCommand = function (clearColor) {
+  this._clearCommand.framebuffer = this._framebuffer;
+  if (defined(clearColor)) {
+    Color.clone(clearColor, this._clearCommand.color);
+  }
+  return this._clearCommand;
+};
+
+/**
+ * Releases GPU resources without destroying this object; a later call to
+ * {@link PlanarFillIdFramebuffer#update} recreates them.
+ */
+PlanarFillIdFramebuffer.prototype.releaseResources = function () {
+  if (!defined(this._framebuffer)) {
+    return;
+  }
+  this._framebufferManager.destroy();
+  this._framebuffer = undefined;
+  this._idTexture = undefined;
+  this._depthStencilTexture = undefined;
+};
+
+/**
+ * @returns {boolean}
+ */
+PlanarFillIdFramebuffer.prototype.isDestroyed = function () {
+  return false;
+};
+
+/**
+ * Destroys WebGL resources.
+ */
+PlanarFillIdFramebuffer.prototype.destroy = function () {
+  this._framebufferManager =
+    this._framebufferManager && this._framebufferManager.destroy();
+  this._clearCommand = undefined;
+  return destroyObject(this);
+};
+
+export default PlanarFillIdFramebuffer;

package/Source/Scene/PntsParser.js

@@ -105,7 +105,6 @@ PntsParser.parse = function (arrayBuffer, byteOffset) {
       );
       // Copy the batchTableBinary section and let the underlying ArrayBuffer be freed
       batchTableBinary = new Uint8Array(batchTableBinary);
-      byteOffset += batchTableBinaryByteLength;
     }
   }
 

package/Source/Scene/PolylineCollection.js

@@ -846,7 +846,7 @@ function createVertexArrays(collection, context, projection) {
 
   //stores all of the individual indices arrays.
   const totalIndices = [[]];
-  let indices = totalIndices[0];
+  let indices;
 
   const batchTable = collection._batchTable;
   const useHighlightColor = collection._useHighlightColor;