@cesium/engine 26.1.0 → 26.3.0

package/Source/Scene/ShadowMap.js

@@ -1719,20 +1719,25 @@ function createCastDerivedCommand(
     const isPointLight = shadowMap._isPointLight;
     const usesDepthTexture = shadowMap._usesDepthTexture;
 
+    const vertexShaderSource = shaderProgram.vertexShaderSource;
+    const fragmentShaderSource = shaderProgram.fragmentShaderSource;
+
+    const hasClipping =
+      isOpaque &&
+      ShadowMapShader.hasClippingForShadowCast(fragmentShaderSource);
+
     const keyword = ShadowMapShader.getShadowCastShaderKeyword(
       isPointLight,
       isTerrain,
       usesDepthTexture,
       isOpaque,
+      hasClipping,
     );
     castShader = context.shaderCache.getDerivedShaderProgram(
       shaderProgram,
       keyword,
     );
     if (!defined(castShader)) {
-      const vertexShaderSource = shaderProgram.vertexShaderSource;
-      const fragmentShaderSource = shaderProgram.fragmentShaderSource;
-
       const castVS = ShadowMapShader.createShadowCastVertexShader(
         vertexShaderSource,
         isPointLight,
@@ -1743,6 +1748,7 @@ function createCastDerivedCommand(
         isPointLight,
         usesDepthTexture,
         isOpaque,
+        hasClipping,
       );
 
       castShader = context.shaderCache.createDerivedShaderProgram(

package/Source/Scene/ShadowMapShader.js

@@ -6,13 +6,48 @@ import ShaderSource from "../Renderer/ShaderSource.js";
  */
 function ShadowMapShader() {}
 
+const clippingDefines = {
+  HAS_CLIPPING_PLANES: true,
+  ENABLE_CLIPPING_POLYGONS: true,
+};
+
+/**
+ * Returns true if the fragment shader clips fragments via a
+ * ClippingPlaneCollection or ClippingPolygonCollection, in which case the
+ * shadow cast pass must run the original main so that clipped fragments
+ * are discarded and do not cast shadows.
+ *
+ * @param {ShaderSource} fragmentShaderSource
+ * @returns {boolean}
+ */
+ShadowMapShader.hasClippingForShadowCast = function (fragmentShaderSource) {
+  const defines = fragmentShaderSource.defines;
+  return (
+    defined(defines) &&
+    defines.some(function (define) {
+      return clippingDefines[define] === true;
+    })
+  );
+};
+
+/**
+ * @param {boolean} isPointLight
+ * @param {boolean} isTerrain
+ * @param {boolean} usesDepthTexture
+ * @param {boolean} isOpaque
+ * @param {boolean} hasClipping True if the fragment shader discards clipped
+ *   fragments. Differentiates cached shader variants so that a shader that
+ *   must call czm_shadow_cast_main() is never reused for one that does not.
+ * @returns {string}
+ */
 ShadowMapShader.getShadowCastShaderKeyword = function (
   isPointLight,
   isTerrain,
   usesDepthTexture,
   isOpaque,
+  hasClipping,
 ) {
-  return `castShadow ${isPointLight} ${isTerrain} ${usesDepthTexture} ${isOpaque}`;
+  return `castShadow ${isPointLight} ${isTerrain} ${usesDepthTexture} ${isOpaque} ${hasClipping}`;
 };
 
 ShadowMapShader.createShadowCastVertexShader = function (
@@ -54,11 +89,22 @@ ShadowMapShader.createShadowCastVertexShader = function (
   });
 };
 
+/**
+ * @param {ShaderSource} fs
+ * @param {boolean} isPointLight
+ * @param {boolean} usesDepthTexture
+ * @param {boolean} opaque
+ * @param {boolean} hasClipping True if the fragment shader discards clipped
+ *   fragments. When true, czm_shadow_cast_main() (the renamed original main)
+ *   is called first so that clipping discards execute during the shadow cast pass.
+ * @returns {ShaderSource}
+ */
 ShadowMapShader.createShadowCastFragmentShader = function (
   fs,
   isPointLight,
   usesDepthTexture,
   opaque,
+  hasClipping,
 ) {
   const defines = fs.defines.slice(0);
   const sources = fs.sources.slice(0);
@@ -85,7 +131,9 @@ ShadowMapShader.createShadowCastFragmentShader = function (
     fsSource += "uniform vec4 shadowMap_lightPositionEC; \n";
   }
 
-  if (opaque) {
+  if (opaque && hasClipping) {
+    fsSource += "void main() \n" + "{ \n" + "    czm_shadow_cast_main(); \n";
+  } else if (opaque) {
     fsSource += "void main() \n" + "{ \n";
   } else {
     fsSource +=

package/Source/Scene/SnapFramebuffer.js

@@ -0,0 +1,121 @@
+import BoundingRectangle from "../Core/BoundingRectangle.js";
+import defined from "../Core/defined.js";
+import destroyObject from "../Core/destroyObject.js";
+import PixelFormat from "../Core/PixelFormat.js";
+import FramebufferManager from "../Renderer/FramebufferManager.js";
+import PassState from "../Renderer/PassState.js";
+import PixelDatatype from "../Renderer/PixelDatatype.js";
+
+/**
+ * @private
+ */
+function SnapFramebuffer(context) {
+  const passState = new PassState(context);
+  passState.blendingEnabled = false;
+  passState.scissorTest = {
+    enabled: true,
+    rectangle: new BoundingRectangle(),
+  };
+  passState.viewport = new BoundingRectangle();
+
+  this._context = context;
+  this._fb = new FramebufferManager({
+    depthStencil: true,
+    pixelDatatype: PixelDatatype.FLOAT,
+    pixelFormat: PixelFormat.RGBA,
+  });
+  this._passState = passState;
+}
+
+function getSnapObjectsFromPixels(context, pixels, width, height) {
+  const max = Math.max(width, height);
+  const length = max * max;
+  const halfWidth = Math.floor(width * 0.5);
+  const halfHeight = Math.floor(height * 0.5);
+
+  let x = 0;
+  let y = 0;
+  let dx = 0;
+  let dy = -1;
+
+  const results = [];
+  for (let i = 0; i < length; ++i) {
+    if (
+      -halfWidth <= x &&
+      x <= halfWidth &&
+      -halfHeight <= y &&
+      y <= halfHeight
+    ) {
+      const index = 4 * ((halfHeight - y) * width + x + halfWidth);
+
+      const pickColor = pixels[index];
+      const object = context.getObjectByPickColor(pickColor);
+      if (defined(object)) {
+        results.push({
+          object: object,
+          isEdge: pixels[index + 1] > 0.0,
+          depth: pixels[index + 2],
+          x: x,
+          y: y,
+        });
+      }
+    }
+
+    if (x === y || (x < 0 && -x === y) || (x > 0 && x === 1 - y)) {
+      const temp = dx;
+      dx = -dy;
+      dy = temp;
+    }
+
+    x += dx;
+    y += dy;
+  }
+
+  return results;
+}
+
+SnapFramebuffer.prototype.begin = function (screenSpaceRectangle, viewport) {
+  const context = this._context;
+  const { width, height } = viewport;
+
+  BoundingRectangle.clone(
+    screenSpaceRectangle,
+    this._passState.scissorTest.rectangle,
+  );
+
+  this._fb.update(context, width, height);
+  this._passState.framebuffer = this._fb.framebuffer;
+
+  this._passState.viewport.width = width;
+  this._passState.viewport.height = height;
+
+  return this._passState;
+};
+
+SnapFramebuffer.prototype.end = function (screenSpaceRectangle) {
+  const width = screenSpaceRectangle.width ?? 1.0;
+  const height = screenSpaceRectangle.height ?? 1.0;
+
+  const context = this._context;
+  const pixels = context.readPixels({
+    x: screenSpaceRectangle.x,
+    y: screenSpaceRectangle.y,
+    width: width,
+    height: height,
+    pixelDatatype: PixelDatatype.FLOAT,
+    framebuffer: this._fb.framebuffer,
+  });
+
+  return getSnapObjectsFromPixels(context, pixels, width, height);
+};
+
+SnapFramebuffer.prototype.isDestroyed = function () {
+  return false;
+};
+
+SnapFramebuffer.prototype.destroy = function () {
+  this._fb.destroy();
+  return destroyObject(this);
+};
+
+export default SnapFramebuffer;

package/Source/Scene/Snapping.js

@@ -0,0 +1,241 @@
+import BoundingRectangle from "../Core/BoundingRectangle.js";
+import Cartesian2 from "../Core/Cartesian2.js";
+import Cartesian3 from "../Core/Cartesian3.js";
+import Check from "../Core/Check.js";
+import defined from "../Core/defined.js";
+import oneTimeWarning from "../Core/oneTimeWarning.js";
+import Ray from "../Core/Ray.js";
+import { pickBegin, pickEnd } from "./Picking.js";
+import SnapFramebuffer from "./SnapFramebuffer.js";
+
+/**
+ * Implementation of {@link Scene#snap}: snap-to-geometry picking.
+ *
+ * A snapping pass is an offscreen pick render (it reuses the pick render
+ * machinery via <code>pickBegin</code>/<code>pickEnd</code>) that targets a
+ * dedicated RGBA32F framebuffer instead of the RGBA8 pick framebuffer. Each
+ * pixel carries a fuller payload than a pick color:
+ * <ul>
+ *   <li>R: pick ID (uint32)</li>
+ *   <li>G: isEdge flag (0.0/1.0)</li>
+ *   <li>B: linear eye-space depth (meters)</li>
+ *   <li>A: unused</li>
+ * </ul>
+ * The payload expression is built in PickingPipelineStage (DrawCommand.snapId)
+ * and compiled into a snap-derived shader by
+ * DerivedCommand.createSnapDerivedCommand. Only commands with a
+ * <code>snapId</code> (i.e. Model-pipeline primitives) render during a
+ * snapping pass.
+ *
+ * @namespace Snapping
+ *
+ * @private
+ */
+const Snapping = {};
+
+const scratchRectangle = new BoundingRectangle(0.0, 0.0, 3.0, 3.0);
+const scratchSnapCoord = new Cartesian2();
+const scratchSurfaceCoord = new Cartesian2();
+const scratchSnapRay = new Ray();
+const scratchSnapOffset = new Cartesian3();
+
+// Radius around the crosshair, in pixels, used to sample the nearest surface
+// (the occluder the cursor is on).
+const SNAP_OCCLUDER_RADIUS_PIXELS = 3.0;
+
+// An edge more than this fraction deeper than that surface is treated as
+// occluded by it (the edge is only visible because it pokes through a gap in a
+// nearer silhouette), so snap doesn't punch through to geometry behind the
+// object the cursor is on.
+const SNAP_OCCLUSION_TOLERANCE = 0.1;
+
+// Width of the region, centered on a winning edge hit, read to find the
+// adjacent surface fragment for surfacePosition. Deliberately centered on the
+// edge hit rather than the cursor: the cursor-centered snap region can clip
+// away the object's surface, potentially causing the server-side backend to
+// give a mismatched snap.
+const SNAP_SURFACE_REGION_WIDTH = 9.0;
+
+function cursorDist(hit) {
+  return Math.sqrt(hit.x * hit.x + hit.y * hit.y);
+}
+
+function selectBestHit(hits) {
+  // Depth of the nearest surface under the crosshair; edges well behind it are
+  // occluded by the object the cursor is on and must not win.
+  let occluderDepth = Number.POSITIVE_INFINITY;
+  for (const hit of hits) {
+    if (!hit.isEdge && cursorDist(hit) <= SNAP_OCCLUDER_RADIUS_PIXELS) {
+      occluderDepth = Math.min(occluderDepth, hit.depth);
+    }
+  }
+  const maxEdgeDepth = occluderDepth * (1.0 + SNAP_OCCLUSION_TOLERANCE);
+
+  // Edges outrank surfaces, but only edges in front of (or at) the occluder;
+  // otherwise fall back to the closest surface. Within the chosen group the
+  // hit closest to the crosshair wins.
+  const visible = hits.filter(
+    (hit) => !hit.isEdge || hit.depth <= maxEdgeDepth,
+  );
+  const wantEdge = visible.some((hit) => hit.isEdge);
+  const group = visible.filter((hit) => hit.isEdge === wantEdge);
+  return group.reduce((best, hit) =>
+    cursorDist(hit) < cursorDist(best) ? hit : best,
+  );
+}
+
+// Find the surface hit belonging to the same object that lies closest to the
+// region center, if any. Unlike an edge hit, whose position lies exactly on
+// the object's silhouette, this point is unambiguously on the object.
+function nearestSurfaceHit(hits, object) {
+  let best;
+  let bestDist = Number.POSITIVE_INFINITY;
+  for (const hit of hits) {
+    if (hit.isEdge || hit.object !== object) {
+      continue;
+    }
+    const dist = hit.x * hit.x + hit.y * hit.y;
+    if (dist < bestDist) {
+      best = hit;
+      bestDist = dist;
+    }
+  }
+  return best;
+}
+
+// Unproject a snap hit's eye-space depth (channel B of the snap framebuffer,
+// written by the snap shader at the edge fragment itself) into a world
+// position.
+function snapHitToWorld(scene, windowPosition, hit) {
+  const coords = scratchSnapCoord;
+  coords.x = windowPosition.x + hit.x;
+  coords.y = windowPosition.y + hit.y;
+
+  const ray = scene.camera.getPickRay(coords, scratchSnapRay);
+  if (!defined(ray)) {
+    return undefined;
+  }
+
+  // hit.depth is perpendicular distance from the camera plane along the view
+  // direction; convert to distance along the (non-axis-aligned) pick ray.
+  const cos = Cartesian3.dot(ray.direction, scene.camera.directionWC);
+  if (cos <= 0.0) {
+    return undefined;
+  }
+  const t = hit.depth / cos;
+
+  const offset = Cartesian3.multiplyByScalar(
+    ray.direction,
+    t,
+    scratchSnapOffset,
+  );
+  return Cartesian3.add(ray.origin, offset, new Cartesian3());
+}
+
+/**
+ * Returns the best snap target in a screen-space region around
+ * <code>windowPosition</code>. See {@link Scene#snap} for the public API.
+ *
+ * @param {Scene} scene
+ * @param {Cartesian2} windowPosition Window coordinates at the center of the search region.
+ * @param {object} [options] Object with the following properties:
+ * @param {number} [options.width=25] Width of the search region in pixels.
+ * @param {number} [options.height=options.width] Height of the search region in pixels.
+ * @returns {SceneSnapResult | undefined}
+ *
+ * @private
+ */
+Snapping.snap = function (scene, windowPosition, options) {
+  //>>includeStart('debug', pragmas.debug);
+  Check.defined("windowPosition", windowPosition);
+  //>>includeEnd('debug');
+
+  const width = options?.width ?? 25;
+  const height = options?.height ?? width;
+
+  const { context, defaultView } = scene;
+
+  // The snap framebuffer is RGBA32F; rendering to it requires float color
+  // attachment support.
+  if (!context.colorBufferFloat) {
+    oneTimeWarning(
+      "snap-color-buffer-float",
+      "Scene.snap requires the EXT_color_buffer_float extension, which is not supported on this platform.",
+    );
+    return undefined;
+  }
+
+  // Created lazily so applications that never snap pay no framebuffer cost.
+  if (!defined(defaultView.snapFramebuffer)) {
+    defaultView.snapFramebuffer = new SnapFramebuffer(context);
+  }
+  const snapFramebuffer = defaultView.snapFramebuffer;
+
+  const drawingBufferRectangle = scratchRectangle;
+  pickBegin(scene, windowPosition, drawingBufferRectangle, width, height, {
+    framebuffer: snapFramebuffer,
+    snap: true,
+  });
+  const hits = snapFramebuffer.end(drawingBufferRectangle);
+  pickEnd(scene);
+
+  if (hits.length === 0) {
+    return undefined;
+  }
+
+  const best = selectBestHit(hits);
+  if (!defined(best)) {
+    return undefined;
+  }
+
+  const position = snapHitToWorld(scene, windowPosition, best);
+  if (!defined(position)) {
+    return undefined;
+  }
+
+  // For edge hits, also unproject the nearest same-object surface fragment so
+  // consumers have a seed point that is on the object but off its silhouette.
+  // Found with a read centered on the edge hit itself, so the seed does not
+  // depend on where in the snap region the cursor was.
+  let surfacePosition = position;
+  if (best.isEdge) {
+    const surfaceOrigin = scratchSurfaceCoord;
+    surfaceOrigin.x = windowPosition.x + best.x;
+    surfaceOrigin.y = windowPosition.y + best.y;
+    pickBegin(
+      scene,
+      surfaceOrigin,
+      drawingBufferRectangle,
+      SNAP_SURFACE_REGION_WIDTH,
+      SNAP_SURFACE_REGION_WIDTH,
+      {
+        framebuffer: snapFramebuffer,
+        snap: true,
+      },
+    );
+    const surfaceHits = snapFramebuffer.end(drawingBufferRectangle);
+    pickEnd(scene);
+    const surfaceHit = nearestSurfaceHit(surfaceHits, best.object);
+    surfacePosition = defined(surfaceHit)
+      ? snapHitToWorld(scene, surfaceOrigin, surfaceHit)
+      : undefined;
+  }
+
+  return {
+    object: best.object,
+    isEdge: best.isEdge,
+    position: position,
+    surfacePosition: surfacePosition,
+    screenPosition: new Cartesian2(
+      windowPosition.x + best.x,
+      windowPosition.y + best.y,
+    ),
+  };
+};
+
+// Exposed for testing.
+Snapping._selectBestHit = selectBestHit;
+Snapping._nearestSurfaceHit = nearestSurfaceHit;
+Snapping._snapHitToWorld = snapHitToWorld;
+
+export default Snapping;

package/Source/Scene/TerrainFillMesh.js

@@ -823,6 +823,7 @@ function createFillMesh(tileProvider, frameState, tile, vertexArraysToDestroy) {
   GlobeSurfaceTile.initialize(
     tile,
     tileProvider.terrainProvider,
+    tileProvider.vectorProvider,
     tileProvider._imageryLayers,
   );
 
@@ -1243,7 +1244,7 @@ function createFillMesh(tileProvider, frameState, tile, vertexArraysToDestroy) {
 
     indices[indexOut++] = centerIndex;
     indices[indexOut++] = i;
-    indices[indexOut++] = 0;
+    indices[indexOut] = 0;
 
     const westIndicesSouthToNorth = [];
     for (i = southwestIndex; i >= northwestIndex; --i) {
@@ -1800,7 +1801,7 @@ function addEdgeMesh(
   heightRange,
 ) {
   // Handle copying edges across the anti-meridian.
-  let sourceRectangle = edgeTile.rectangle;
+  let sourceRectangle;
   if (tileEdge === TileEdge.EAST && terrainFillMesh.tile.x === 0) {
     sourceRectangle = Rectangle.clone(
       edgeTile.rectangle,

package/Source/Scene/UrlTemplate3DTilesDataProvider.js

@@ -13,7 +13,9 @@ import destroyObject from "../Core/destroyObject.js";
 import CesiumMath from "../Core/Math.js";
 
 /** @import FrameState from "./FrameState.js"; */
+/** @import HeightReference from "./HeightReference.js"; */
 /** @import PassState from "../Renderer/PassState.js"; */
+/** @import Scene from "./Scene.js"; */
 /** @import TilingScheme from "../Core/TilingScheme.js"; */
 
 /**
@@ -41,7 +43,7 @@ const scratchIntersectionRectangle = new Rectangle();
  * Base provider for URL-template vector sources that are rendered through a
  * runtime-generated 3D Tiles tileset.
  *
- * @private
+ * @experimental This feature is not final and is subject to change without Cesium's standard deprecation policy.
  */
 class UrlTemplate3DTilesDataProvider {
   /**
@@ -51,6 +53,10 @@ class UrlTemplate3DTilesDataProvider {
    * @param {number} [options.maxZoom=14] Maximum zoom level represented in the generated tileset.
    * @param {Rectangle} [options.extent] Optional geographic extent in radians to constrain the generated tile tree.
    * @param {string} [options.featureIdProperty] Feature property name to use as feature ID when supported by content decoding.
+   * @param {HeightReference} [options.heightReference] Drapes the vector content onto the surfaces selected by the
+   *   value. Requires <code>options.scene</code>.
+   * @param {Scene} [options.scene] The scene the generated tileset is rendered in, required when
+   *   <code>options.heightReference</code> is a clamping value.
    */
   constructor(urlTemplate, options) {
     options = options ?? {};
@@ -61,6 +67,8 @@ class UrlTemplate3DTilesDataProvider {
     this._minZoom = options.minZoom ?? DEFAULT_MIN_ZOOM;
     this._maxZoom = options.maxZoom ?? DEFAULT_MAX_ZOOM;
     this._featureIdProperty = options.featureIdProperty;
+    this._heightReference = options.heightReference;
+    this._scene = options.scene;
     this._show = true;
     this._tileset = undefined;
     this._tilesetJsonUrl = undefined;
@@ -149,7 +157,10 @@ class UrlTemplate3DTilesDataProvider {
    * @returns {object}
    */
   _createTilesetLoadOptions() {
-    return {};
+    return {
+      heightReference: this._heightReference,
+      scene: this._scene,
+    };
   }
 
   /**

package/Source/Scene/Vector3DTileContent.js

@@ -402,8 +402,8 @@ function initialize(content, arrayBuffer, byteOffset) {
   byteOffset += sizeOfUint32;
   const polylinePositionByteLength = view.getUint32(byteOffset, true);
   byteOffset += sizeOfUint32;
-  const pointsPositionByteLength = view.getUint32(byteOffset, true);
-  byteOffset += sizeOfUint32;
+  // Ignore pointsPositionByteLength
+  byteOffset += sizeOfUint32; // For pointsPositionByteLength
 
   const featureTableJson = getJsonFromTypedArray(
     uint8Array,
@@ -687,7 +687,6 @@ function initialize(content, arrayBuffer, byteOffset) {
       byteOffset,
       numberOfPoints * 3,
     );
-    byteOffset += pointsPositionByteLength;
     content._points = new Vector3DTilePoints({
       positions: pointPositions,
       batchIds: batchIds.points,

package/Source/Scene/VectorGltf3DTileContent.js

@@ -14,10 +14,12 @@ import Matrix4 from "../Core/Matrix4.js";
 import Model from "./Model/Model.js";
 import ModelUtility from "./Model/ModelUtility.js";
 import Pass from "../Renderer/Pass.js";
+import VectorProvider from "../Core/VectorProvider.js";
 import createVectorTileBuffersFromModelComponents from "./Model/createVectorTileBuffersFromModelComponents.js";
 import defined from "../Core/defined.js";
 import destroyObject from "../Core/destroyObject.js";
 import DeveloperError from "../Core/DeveloperError.js";
+import { isHeightReferenceClamp } from "./HeightReference.js";
 
 /** @import BufferPrimitive from "./BufferPrimitive.js"; */
 /** @import BufferPrimitiveCollection from "./BufferPrimitiveCollection.js"; */
@@ -319,6 +321,9 @@ class VectorGltf3DTileContent {
    * @param {FrameState} frameState
    */
   update(_tileset, frameState) {
+    const tileset = this._tileset;
+    const vectorProvider = tileset._scene?.vectorProvider;
+
     if (defined(this._model) && !this._ready) {
       const model = this._model;
       model.modelMatrix = this._tile.computedTransform;
@@ -337,13 +342,31 @@ class VectorGltf3DTileContent {
       scratchTileModelMatrix,
     );
 
+    // Only bake collections selected to render this frame (avoids duplicates).
+    const isSelected =
+      defined(vectorProvider) &&
+      this._tile._selectedFrame === frameState.frameNumber;
+
     for (let i = 0; i < this._collections.length; i++) {
+      const collection = this._collections[i];
       Matrix4.multiplyTransformation(
         scratchTileModelMatrix,
         this._collectionLocalMatrices[i],
-        this._collections[i].modelMatrix,
+        collection.modelMatrix,
       );
-      this._collections[i].update(frameState);
+
+      if (
+        !isHeightReferenceClamp(tileset._heightReference) ||
+        !VectorProvider.isSupported(collection)
+      ) {
+        collection.update(frameState);
+      } else if (isSelected) {
+        vectorProvider.markForFrame(
+          collection,
+          frameState.frameNumber,
+          tileset._heightReference,
+        );
+      }
     }
   }
 
@@ -362,9 +385,14 @@ class VectorGltf3DTileContent {
   }
 
   destroy() {
+    const vectorProvider = this._tileset._scene?.vectorProvider;
+
     this._model?.destroy();
     this._model = undefined;
-    this._collections.forEach((collection) => collection.destroy());
+    for (const collection of this._collections) {
+      vectorProvider?.remove(collection);
+      collection.destroy();
+    }
     this._collections.length = 0;
     return destroyObject(this);
   }