@cesium/engine 26.2.0 → 26.3.0

package/Source/Scene/CreditDisplay.js

@@ -162,6 +162,29 @@ function styleLightboxContainer(that) {
   }
 }
 
+/**
+ * Wraps a callback so that it also runs when a keyboard user activates an element
+ * with <code>Enter</code> or <code>Space</code>. Elements exposed as <code>role="button"</code>
+ * are expected to respond to both keys, which anchors without an <code>href</code> do not do natively.
+ *
+ * @param {Function} callback The function to invoke when the element is activated.
+ * @returns {Function} A <code>keydown</code> handler.
+ *
+ * @private
+ */
+function activateOnKeydown(callback) {
+  return function (event) {
+    if (event.key !== "Enter" && event.key !== " ") {
+      return;
+    }
+    // Prevent Space from scrolling the page and stop the event from also
+    // reaching the overlay, which would immediately close the lightbox again.
+    event.preventDefault();
+    event.stopPropagation();
+    callback();
+  };
+}
+
 function appendCss(container) {
   const style = /*css*/ `
 .cesium-credit-lightbox-overlay {
@@ -237,6 +260,12 @@ function appendCss(container) {
   color: ${highlightColor};
 }
 
+.cesium-credit-expand-link:focus-visible,
+.cesium-credit-lightbox-close:focus-visible {
+  outline: 2px solid ${highlightColor};
+  outline-offset: 2px;
+}
+
 .cesium-credit-text {
   color: ${textColor};
 }
@@ -312,6 +341,9 @@ function CreditDisplay(container, delimiter, viewport) {
 
   const lightboxCredits = document.createElement("div");
   lightboxCredits.className = "cesium-credit-lightbox";
+  lightboxCredits.setAttribute("role", "dialog");
+  lightboxCredits.setAttribute("aria-modal", "true");
+  lightboxCredits.setAttribute("aria-label", "Data attribution");
   lightbox.appendChild(lightboxCredits);
 
   function hideLightbox(event) {
@@ -322,6 +354,14 @@ function CreditDisplay(container, delimiter, viewport) {
   }
   lightbox.addEventListener("click", hideLightbox, false);
 
+  function hideLightboxOnEscape(event) {
+    if (event.key === "Escape") {
+      event.preventDefault();
+      that.hideLightbox();
+    }
+  }
+  lightbox.addEventListener("keydown", hideLightboxOnEscape, false);
+
   const title = document.createElement("div");
   title.className = "cesium-credit-lightbox-title";
   title.textContent = "Data provided by:";
@@ -329,8 +369,12 @@ function CreditDisplay(container, delimiter, viewport) {
 
   const closeButton = document.createElement("a");
   closeButton.onclick = this.hideLightbox.bind(this);
+  closeButton.onkeydown = activateOnKeydown(this.hideLightbox.bind(this));
   closeButton.innerHTML = "&times;";
   closeButton.className = "cesium-credit-lightbox-close";
+  closeButton.setAttribute("role", "button");
+  closeButton.setAttribute("tabindex", "0");
+  closeButton.setAttribute("aria-label", "Close data attribution");
   lightboxCredits.appendChild(closeButton);
 
   const creditList = document.createElement("ul");
@@ -349,7 +393,12 @@ function CreditDisplay(container, delimiter, viewport) {
   const expandLink = document.createElement("a");
   expandLink.className = "cesium-credit-expand-link";
   expandLink.onclick = this.showLightbox.bind(this);
+  expandLink.onkeydown = activateOnKeydown(this.showLightbox.bind(this));
   expandLink.textContent = "Data attribution";
+  expandLink.setAttribute("role", "button");
+  expandLink.setAttribute("tabindex", "0");
+  expandLink.setAttribute("aria-haspopup", "dialog");
+  expandLink.setAttribute("aria-expanded", "false");
   container.appendChild(expandLink);
 
   appendCss(container);
@@ -364,7 +413,9 @@ function CreditDisplay(container, delimiter, viewport) {
   this._creditList = creditList;
   this._lightbox = lightbox;
   this._hideLightbox = hideLightbox;
+  this._hideLightboxOnEscape = hideLightboxOnEscape;
   this._expandLink = expandLink;
+  this._closeButton = closeButton;
   this._expanded = false;
   this._staticCredits = [];
   this._cesiumCredit = cesiumCredit;
@@ -492,6 +543,9 @@ CreditDisplay.prototype.removeStaticCredit = function (credit) {
 CreditDisplay.prototype.showLightbox = function () {
   this._lightbox.style.display = "block";
   this._expanded = true;
+  this._expandLink.setAttribute("aria-expanded", "true");
+  // Move focus into the dialog so keyboard users can reach its contents.
+  this._closeButton.focus();
 };
 
 /**
@@ -500,6 +554,9 @@ CreditDisplay.prototype.showLightbox = function () {
 CreditDisplay.prototype.hideLightbox = function () {
   this._lightbox.style.display = "none";
   this._expanded = false;
+  this._expandLink.setAttribute("aria-expanded", "false");
+  // Restore focus to the element that opened the dialog.
+  this._expandLink.focus();
 };
 
 /**
@@ -581,6 +638,11 @@ CreditDisplay.prototype.endFrame = function () {
  */
 CreditDisplay.prototype.destroy = function () {
   this._lightbox.removeEventListener("click", this._hideLightbox, false);
+  this._lightbox.removeEventListener(
+    "keydown",
+    this._hideLightboxOnEscape,
+    false,
+  );
 
   this.container.removeChild(this._cesiumCreditContainer);
   this.container.removeChild(this._screenContainer);

package/Source/Scene/GeoJsonPrimitive.js

@@ -1,8 +1,5 @@
 // @ts-check
 
-/** @import {GeoJson, GeoJsonFeature, GeoJsonGeometry, GeoJsonPosition} from "../Core/globalTypes.js"; */
-/** @import FrameState from "./FrameState.js"; */
-
 import Cartesian2 from "../Core/Cartesian2.js";
 import Cartesian3 from "../Core/Cartesian3.js";
 import Check from "../Core/Check.js";
@@ -11,6 +8,7 @@ import destroyObject from "../Core/destroyObject.js";
 import DeveloperError from "../Core/DeveloperError.js";
 import Ellipsoid from "../Core/Ellipsoid.js";
 import Frozen from "../Core/Frozen.js";
+import HeightReference, { isHeightReferenceClamp } from "./HeightReference.js";
 import PolygonPipeline from "../Core/PolygonPipeline.js";
 import Resource from "../Core/Resource.js";
 import RuntimeError from "../Core/RuntimeError.js";
@@ -20,6 +18,13 @@ import BufferPolygon from "./BufferPolygon.js";
 import BufferPolygonCollection from "./BufferPolygonCollection.js";
 import BufferPolyline from "./BufferPolyline.js";
 import BufferPolylineCollection from "./BufferPolylineCollection.js";
+import assert from "../Core/assert.js";
+import oneTimeWarning from "../Core/oneTimeWarning.js";
+
+/** @import FrameState from "./FrameState.js"; */
+/** @import Scene from "./Scene.js"; */
+/** @import {GeoJson, GeoJsonFeature, GeoJsonGeometry, GeoJsonPosition} from "../Core/globalTypes.js"; */
+/** @import VectorProvider from "../Core/VectorProvider.js"; */
 
 /**
  * @typedef {object} GeoJsonPrimitiveConstructorOptions
@@ -29,6 +34,9 @@ import BufferPolylineCollection from "./BufferPolylineCollection.js";
  * @property {boolean} [allowPicking=true]
  * @property {boolean} [show=true]
  * @property {function(number, object, Record<string, unknown>):object} [pickObjectFactory]
+ * @property {HeightReference} [heightReference=HeightReference.NONE] Allows clamping (draping)
+ *  polylines and polygons on terrain and 3D Tiles. Point clamping is not currently supported.
+ * @property {Scene} [scene] Required for primitives that use a clamping {@link HeightReference}.
  */
 
 /**
@@ -41,14 +49,36 @@ import BufferPolylineCollection from "./BufferPolylineCollection.js";
  * added directly to {@link Scene#primitives}.
  *
  * @example
+ * // Load GeoJSON
  * const loader = await Cesium.GeoJsonPrimitive.fromUrl("./data.geojson");
  * viewer.scene.primitives.add(loader);
  *
+ * @example
+ * // Access GeoJSON features and properties
  * loader.points;     // BufferPointCollection | undefined
  * loader.polylines;  // BufferPolylineCollection | undefined
  * loader.polygons;   // BufferPolygonCollection | undefined
  * loader.ids;        // source feature IDs
  * loader.properties; // source feature properties
+ *
+ * @example
+ * // Style GeoJSON
+ * const material = new Cesium.BufferPolylineMaterial({
+ *   color: Cesium.Color.RED,
+ *   width: 4,
+ * });
+ *
+ * const polyline = new Cesium.BufferPolyline();
+ * const count = primitive.polylines.primitiveCount;
+ * for (let i = 0; i < count; i++) {
+ *   primitive.polylines.get(i, polyline);
+ *
+ *   const properties = primitive.getProperties(polyline.featureId);
+ *   if (properties.myCustomProperty === true) {
+ *     polyline.setMaterial(material);
+ *   }
+ * }
+ *
  * @experimental This feature is not final and is subject to change without Cesium's standard deprecation policy.
  */
 class GeoJsonPrimitive {
@@ -59,9 +89,7 @@ class GeoJsonPrimitive {
     options = options ?? Frozen.EMPTY_OBJECT;
 
     //>>includeStart('debug', pragmas.debug);
-    if (!defined(options.geoJson)) {
-      throw new DeveloperError("options.geoJson is required.");
-    }
+    Check.defined("geoJson", options.geoJson);
     //>>includeEnd('debug');
 
     const parseResult = parseGeoJson(/** @type {GeoJson} */ (options.geoJson));
@@ -86,35 +114,62 @@ class GeoJsonPrimitive {
     this._polylines = undefined;
     this._polygons = undefined;
 
+    /**
+     * @type {HeightReference}
+     * @private
+     */
+    this._heightReference = options.heightReference ?? HeightReference.NONE;
+
+    /**
+     * @type {Scene|undefined}
+     * @private
+     */
+    this._scene = options.scene;
+
+    const heightReference = this._heightReference;
+    const scene = this._scene;
+
+    //>>includeStart('debug', pragmas.debug);
+    assert(
+      !isHeightReferenceClamp(heightReference) || defined(scene),
+      "Clamped HeightReference requires `options.scene`.",
+    );
+    //>>includeEnd('debug');
+
     if (parseResult.pointCount > 0) {
-      /** @type {Record<string, unknown>} */
-      const pointOptions = {
+      //>>includeStart('debug', pragmas.debug);
+      if (isHeightReferenceClamp(heightReference)) {
+        oneTimeWarning(
+          "geojson-heightref",
+          "Clamped HeightReference unsupported on BufferPointCollection.",
+        );
+      }
+      //>>includeEnd('debug');
+
+      this._points = new BufferPointCollection({
         primitiveCountMax: parseResult.pointCount,
         allowPicking: allowPicking,
-      };
-      this._points = new BufferPointCollection(pointOptions);
+      });
     }
 
     if (parseResult.polylineCount > 0) {
-      /** @type {Record<string, unknown>} */
-      const polylineOptions = {
+      this._polylines = new BufferPolylineCollection({
         primitiveCountMax: parseResult.polylineCount,
         vertexCountMax: parseResult.polylineVertexCount,
         allowPicking: allowPicking,
-      };
-      this._polylines = new BufferPolylineCollection(polylineOptions);
+        heightReference,
+      });
     }
 
     if (parseResult.polygonCount > 0) {
-      /** @type {Record<string, unknown>} */
-      const polygonOptions = {
+      this._polygons = new BufferPolygonCollection({
         primitiveCountMax: parseResult.polygonCount,
         vertexCountMax: parseResult.polygonVertexCount,
         holeCountMax: parseResult.polygonHoleCount,
         triangleCountMax: parseResult.polygonTriangleCount,
         allowPicking: allowPicking,
-      };
-      this._polygons = new BufferPolygonCollection(polygonOptions);
+        heightReference,
+      });
     }
 
     const scratch = new Cartesian3();
@@ -338,30 +393,65 @@ class GeoJsonPrimitive {
       return;
     }
 
-    if (defined(this._points)) {
-      this._points.update(frameState);
+    const points = this._points;
+    const polylines = this._polylines;
+    const polygons = this._polygons;
+    const frameNumber = frameState.frameNumber;
+    const heightReference = this._heightReference;
+
+    const vectorProvider = isHeightReferenceClamp(heightReference)
+      ? // @ts-expect-error Missing types, non-ES6 class.
+        /** @type {VectorProvider} */ (this._scene.vectorProvider)
+      : null;
+
+    if (defined(points)) {
+      points.update(frameState);
     }
-    if (defined(this._polylines)) {
-      this._polylines.update(frameState);
+
+    if (defined(polylines)) {
+      if (defined(vectorProvider)) {
+        vectorProvider.markForFrame(polylines, frameNumber, heightReference);
+      } else {
+        polylines.update(frameState);
+      }
     }
-    if (defined(this._polygons)) {
-      this._polygons.update(frameState);
+
+    if (defined(polygons)) {
+      if (defined(vectorProvider)) {
+        vectorProvider.markForFrame(polygons, frameNumber, heightReference);
+      } else {
+        polygons.update(frameState);
+      }
     }
   }
 
   destroy() {
+    const vectorProvider = isHeightReferenceClamp(this._heightReference)
+      ? // @ts-expect-error Missing types, non-ES6 class.
+        /** @type {VectorProvider} */ (this._scene.vectorProvider)
+      : null;
+
     if (this._points) {
       this._points.destroy();
       this._points = undefined;
     }
+
     if (this._polylines) {
+      if (defined(vectorProvider)) {
+        vectorProvider.remove(this._polylines);
+      }
       this._polylines.destroy();
       this._polylines = undefined;
     }
+
     if (this._polygons) {
+      if (defined(vectorProvider)) {
+        vectorProvider.remove(this._polygons);
+      }
       this._polygons.destroy();
       this._polygons = undefined;
     }
+
     return destroyObject(this);
   }
 

package/Source/Scene/GlobeSurfaceShaderSet.js

@@ -82,6 +82,7 @@ class GlobeSurfaceShader {
  * @property {boolean} [hasExaggeration]
  * @property {boolean} [showUndergroundColor]
  * @property {boolean} [translucent]
+ * @property {boolean} [vectorAntialias]
  * @private
  */
 
@@ -141,6 +142,12 @@ class GlobeSurfaceShaderSet {
     const translucent = options.translucent;
     const vectorData = surfaceTile.vectorData;
     const hasVectorLayer = vectorData?.show;
+    const hasVectorPolylines = hasVectorLayer && vectorData.hasPolylines;
+    const hasVectorPolygons = hasVectorLayer && vectorData.hasPolygons;
+    const vectorAntialias = hasVectorLayer && options.vectorAntialias;
+    const vectorWidthInMeters = hasVectorPolylines && vectorData.hasMeterWidths;
+    const vectorMixedWidthUnits =
+      vectorWidthInMeters && vectorData.hasPixelWidths;
 
     let quantization = 0;
     let quantizationDefine = "";
@@ -205,7 +212,12 @@ class GlobeSurfaceShaderSet {
         (+translucent << 31)) >>>
         0) +
       (applyDayNightAlpha ? 0x100000000 : 0) +
-      (hasVectorLayer ? 0x200000000 : 0);
+      (hasVectorLayer ? 0x200000000 : 0) +
+      (hasVectorPolylines ? 0x400000000 : 0) +
+      (hasVectorPolygons ? 0x800000000 : 0) +
+      (vectorAntialias ? 0x1000000000 : 0) +
+      (vectorWidthInMeters ? 0x2000000000 : 0) +
+      (vectorMixedWidthUnits ? 0x4000000000 : 0);
 
     let currentClippingShaderState = 0;
     // @ts-expect-error Missing types.
@@ -263,12 +275,6 @@ class GlobeSurfaceShaderSet {
         );
       }
 
-      // Need to go before GlobeFS
-      if (currentClippingPolygonsShaderState !== 0) {
-        fs.sources.unshift(getPolygonClippingFunction(frameState.context));
-        vs.sources.unshift(getUnpackClippingFunction(frameState.context));
-      }
-
       vs.defines.push(quantizationDefine);
       fs.defines.push(
         `TEXTURE_UNITS ${numberOfDayTextures}`,
@@ -364,20 +370,10 @@ class GlobeSurfaceShaderSet {
 
       if (enableClippingPolygons) {
         fs.defines.push("ENABLE_CLIPPING_POLYGONS");
-        vs.defines.push("ENABLE_CLIPPING_POLYGONS");
 
         if (clippingPolygons.inverse) {
           fs.defines.push("CLIPPING_INVERSE");
         }
-
-        fs.defines.push(
-          // @ts-expect-error Missing types.
-          `CLIPPING_POLYGON_REGIONS_LENGTH ${clippingPolygons.extentsCount}`,
-        );
-        vs.defines.push(
-          // @ts-expect-error Missing types.
-          `CLIPPING_POLYGON_REGIONS_LENGTH ${clippingPolygons.extentsCount}`,
-        );
       }
 
       if (colorCorrect) {
@@ -397,9 +393,27 @@ class GlobeSurfaceShaderSet {
       }
 
       if (hasVectorLayer) {
-        vs.defines.push("HAS_VECTOR_LAYER");
         fs.defines.push("HAS_VECTOR_LAYER");
-        fs.sources.unshift(VectorCommon); // before GlobeFS.
+        if (hasVectorPolylines) {
+          fs.defines.push("HAS_VECTOR_POLYLINES");
+        }
+        if (hasVectorPolygons) {
+          fs.defines.push("HAS_VECTOR_POLYGONS");
+        }
+        if (vectorAntialias) {
+          fs.defines.push("VECTOR_ANTIALIAS");
+        }
+        if (vectorWidthInMeters) {
+          fs.defines.push("VECTOR_WIDTH_IN_METERS");
+        }
+        if (vectorMixedWidthUnits) {
+          fs.defines.push("VECTOR_WIDTH_MIXED_UNITS");
+        }
+      }
+
+      // Polygon clipping builds on top of the same machinery vector rendering uses
+      if (hasVectorLayer || enableClippingPolygons) {
+        fs.sources.unshift(VectorCommon);
       }
 
       let computeDayColor =
@@ -538,41 +552,6 @@ function getPositionMode(sceneMode) {
   return positionMode;
 }
 
-/**
- * @param {Context} context
- * @ignore
- */
-function getPolygonClippingFunction(context) {
-  // return a noop for webgl1
-  // @ts-expect-error Missing types.
-  if (!context.webgl2) {
-    return `void clipPolygons(highp sampler2D clippingDistance, int regionsLength, vec2 clippingPosition, int regionIndex) {
-    }`;
-  }
-
-  return `void clipPolygons(highp sampler2D clippingDistance, int regionsLength, vec2 clippingPosition, int regionIndex) {
-    czm_clipPolygons(clippingDistance, regionsLength, clippingPosition, regionIndex);
-  }`;
-}
-
-/**
- * @param {Context} context
- * @ignore
- */
-function getUnpackClippingFunction(context) {
-  // return a noop for webgl1
-  // @ts-expect-error Missing types.
-  if (!context.webgl2) {
-    return `vec4 unpackClippingExtents(highp sampler2D extentsTexture, int index) {
-      return vec4();
-    }`;
-  }
-
-  return `vec4 unpackClippingExtents(highp sampler2D extentsTexture, int index) {
-    return czm_unpackClippingExtents(extentsTexture, index);
-  }`;
-}
-
 /**
  * @param {boolean} useWebMercatorProjection
  * @returns {string}

package/Source/Scene/GlobeSurfaceTile.js

@@ -19,6 +19,7 @@ import TextureMagnificationFilter from "../Renderer/TextureMagnificationFilter.j
 import TextureMinificationFilter from "../Renderer/TextureMinificationFilter.js";
 import TextureWrap from "../Renderer/TextureWrap.js";
 import VertexArray from "../Renderer/VertexArray.js";
+import ClippingPolygonCollection from "./ClippingPolygonCollection.js";
 import ImageryState from "./ImageryState.js";
 import QuadtreeTileLoadState from "./QuadtreeTileLoadState.js";
 import TerrainState from "./TerrainState.js";
@@ -37,7 +38,8 @@ import TerrainState from "./TerrainState.js";
 /** @import TerrainProvider from "../Core/TerrainProvider.js"; */
 /** @import TileBoundingRegion from "./TileBoundingRegion.js"; */
 /** @import TileImagery from "./TileImagery.js"; */
-/** @import VectorProvider, { VectorTileData } from "../Core/VectorProvider.js"; */
+/** @import VectorProvider from "../Core/VectorProvider.js"; */
+/** @import { VectorTileData } from "../Core/VectorPipeline.js"; */
 
 /**
  * Contains additional information about a {@link QuadtreeTile} of the globe's surface, and
@@ -67,6 +69,12 @@ class GlobeSurfaceTile {
     /** @type {VectorTileData} */
     this.vectorData = undefined;
 
+    /**
+     * Clipping polygons build on top of the vector tile data system (both rely on the same rendering technique).
+     * @type {VectorTileData}
+     */
+    this.clippingPolygonData = undefined;
+
     /** @type {VertexArray} */
     this.vertexArray = undefined;
 
@@ -169,6 +177,11 @@ class GlobeSurfaceTile {
       this.vectorData = undefined;
     }
 
+    if (defined(this.clippingPolygonData)) {
+      ClippingPolygonCollection.releaseRectangleData(this.clippingPolygonData);
+      this.clippingPolygonData = undefined;
+    }
+
     this.terrainData = undefined;
 
     this.terrainState = TerrainState.UNLOADED;