@cesium/engine 26.1.0 → 26.3.0

package/Source/DataSources/CzmlDataSource.js

@@ -497,6 +497,8 @@ function getPropertyType(czmlInterval) {
     return Object;
   } else if (czmlInterval.hasOwnProperty("unitQuaternion")) {
     return Quaternion;
+  } else if (czmlInterval.hasOwnProperty("pathMode")) {
+    return PathMode;
   } else if (czmlInterval.hasOwnProperty("shadowMode")) {
     return ShadowMode;
   } else if (czmlInterval.hasOwnProperty("string")) {

package/Source/DataSources/DataSourceDisplay.js

@@ -415,7 +415,7 @@ DataSourceDisplay.prototype.getBoundingSphere = function (
   const tmp = getBoundingSphereBoundingSphereScratch;
 
   let count = 0;
-  let state = BoundingSphereState.DONE;
+  let state;
   const visualizers = dataSource._visualizers;
   const visualizersLength = visualizers.length;
 

package/Source/DataSources/GeoJsonDataSource.js

@@ -149,7 +149,6 @@ function createObject(geoJson, entityCollection, describe) {
           const lowerKey = key.toLowerCase();
 
           if (namePropertyPrecedence > 1 && lowerKey === "title") {
-            namePropertyPrecedence = 1;
             nameProperty = key;
             break;
           } else if (namePropertyPrecedence > 2 && lowerKey === "name") {

package/Source/DataSources/GeometryVisualizer.js

@@ -336,7 +336,7 @@ GeometryVisualizer.prototype.getBoundingSphere = function (entity, result) {
   const tmp = getBoundingSphereBoundingSphereScratch;
 
   let count = 0;
-  let state = BoundingSphereState.DONE;
+  let state;
   const batches = this._batches;
   const batchesLength = batches.length;
 

package/Source/DataSources/KmlDataSource.js

@@ -1495,9 +1495,8 @@ function processPositionGraphics(
     billboard.image = undefined;
   }
 
-  let scale = 1.0;
   if (defined(billboard.scale)) {
-    scale = billboard.scale.getValue();
+    const scale = billboard.scale.getValue();
     if (scale !== 0) {
       label.pixelOffset = new Cartesian2(scale * 16 + 1, 0);
     } else {

package/Source/DataSources/PolylineVisualizer.js

@@ -295,7 +295,7 @@ PolylineVisualizer.prototype.getBoundingSphere = function (entity, result) {
   const tmp = getBoundingSphereBoundingSphereScratch;
 
   let count = 0;
-  let state = BoundingSphereState.DONE;
+  let state;
   const batches = this._batches;
   const batchesLength = batches.length;
   const updater = this._updaters.get(entity.id);

package/Source/DataSources/StaticOutlineGeometryBatch.js

@@ -375,7 +375,7 @@ StaticOutlineGeometryBatch.prototype.update = function (time) {
   const translucentBatchesLength = translucentBatches.length;
   let itemsToRemove;
   let isUpdated = true;
-  let needUpdate = false;
+  let needUpdate;
 
   do {
     needUpdate = false;

package/Source/Renderer/AutomaticUniforms.js

@@ -222,6 +222,29 @@ const AutomaticUniforms = {
     },
   }),
 
+  /**
+   * An automatic GLSL uniform containing the feature-ID texture produced by
+   * the planar fill pre-pass (BENTLEY_materials_planar_fill). Non-behind
+   * planar fill geometry writes its per-fragment feature ID here so that
+   * behind fills can test whether the existing pixel belongs to the same
+   * logical object.
+   *
+   * @example
+   * // GLSL declaration
+   * uniform sampler2D czm_planarFillIdTexture;
+   *
+   * // Sample
+   * vec2 coords = gl_FragCoord.xy / czm_viewport.zw;
+   * float existingFeatureId = texture(czm_planarFillIdTexture, coords).r;
+   */
+  czm_planarFillIdTexture: new AutomaticUniform({
+    size: 1,
+    datatype: WebGLConstants.SAMPLER_2D,
+    getValue: function (uniformState) {
+      return uniformState.planarFillIdTexture;
+    },
+  }),
+
   /**
    * An automatic GLSL uniform representing a 4x4 model transformation matrix that
    * transforms model coordinates to world coordinates.
@@ -985,6 +1008,27 @@ const AutomaticUniforms = {
     },
   }),
 
+  /**
+   * An automatic GLSL uniform containing the geodetic longitude (<code>x</code>),
+   * latitude (<code>y</code>) in radians and height (<code>z</code>) in meters of the
+   * eye (camera). The <code>z</code> component matches {@link czm_eyeHeight}.
+   * This uniform is only valid when the {@link SceneMode} is <code>SCENE3D</code>.
+   *
+   * @example
+   * // GLSL declaration
+   * uniform vec3 czm_eyeCartographic;
+   *
+   * // Example
+   * float cameraLatitude = czm_eyeCartographic.y;
+   */
+  czm_eyeCartographic: new AutomaticUniform({
+    size: 1,
+    datatype: WebGLConstants.FLOAT_VEC3,
+    getValue: function (uniformState) {
+      return uniformState.eyeCartographic;
+    },
+  }),
+
   /**
    * An automatic GLSL uniform containing height (<code>x</code>) and height squared (<code>y</code>)
    * in meters of the eye (camera) above the 2D world plane. This uniform is only valid
@@ -1027,10 +1071,31 @@ const AutomaticUniforms = {
     },
   }),
 
+  /**
+   * An automatic GLSL uniform containing a 3x3 rotation from eye coordinates to an
+   * east-north-up coordinate system centered at the position on the ellipsoid below
+   * the camera.
+   * This uniform is only valid when the {@link SceneMode} is <code>SCENE3D</code>.
+   *
+   * @example
+   * // GLSL declaration
+   * uniform mat3 czm_eyeToEnu;
+   *
+   * // Example
+   * vec3 enu = czm_eyeToEnu * positionEC;
+   */
+  czm_eyeToEnu: new AutomaticUniform({
+    size: 1,
+    datatype: WebGLConstants.FLOAT_MAT3,
+    getValue: function (uniformState) {
+      return uniformState.eyeToEnu;
+    },
+  }),
+
   /**
    * An automatic GLSL uniform containing the transform from model coordinates
    * to an east-north-up coordinate system centered at the position on the
-   * ellipsoid below the camera.
+   * ellipsoid nearest to the camera.
    * This uniform is only valid when the {@link SceneMode} is <code>SCENE3D</code>.
    */
   czm_modelToEnu: new AutomaticUniform({
@@ -1042,7 +1107,7 @@ const AutomaticUniforms = {
   }),
 
   /**
-   * An automatic GLSL uniform containing the the inverse of
+   * An automatic GLSL uniform containing the inverse of
    * {@link AutomaticUniforms.czm_modelToEnu}.
    * This uniform is only valid when the {@link SceneMode} is <code>SCENE3D</code>.
    */

package/Source/Renderer/Context.js

@@ -1010,20 +1010,26 @@ Object.defineProperties(Context.prototype, {
   },
 
   /**
-   * A 1x1 RGBA texture initialized to [255, 255, 255, 255].  This can
-   * be used as a placeholder texture while other textures are downloaded.
+   * A 1x1 RGBA texture initialized to the color defined by {@link Texture.defaultColor}.
+   * This can be used as a placeholder texture while other textures are downloaded.
    * @memberof Context.prototype
    * @type {Texture}
    */
   defaultTexture: {
     get: function () {
       if (this._defaultTexture === undefined) {
+        const color = Texture.defaultColor;
         this._defaultTexture = new Texture({
           context: this,
           source: {
             width: 1,
             height: 1,
-            arrayBufferView: new Uint8Array([255, 255, 255, 255]),
+            arrayBufferView: new Uint8Array([
+              color.red * 255,
+              color.green * 255,
+              color.blue * 255,
+              color.alpha * 255,
+            ]),
           },
           flipY: false,
         });

package/Source/Renderer/DrawCommand.js

@@ -47,6 +47,7 @@ const Flags = {
  * @property {Pass} [pass]
  * @property {object} [owner]
  * @property {string} [pickId]
+ * @property {string} [snapId]
  * @property {boolean} [pickMetadataAllowed=false]
  * @property {boolean} [cull=true]
  * @property {boolean} [occlude=true]
@@ -102,6 +103,7 @@ class DrawCommand {
     this._debugOverlappingFrustums = 0;
     /** @private */
     this._pickId = options.pickId;
+    this._snapId = options.snapId;
     /** @private */
     this._pickMetadataAllowed = options.pickMetadataAllowed === true;
     /**
@@ -532,6 +534,25 @@ class DrawCommand {
     }
   }
 
+  /**
+   * A GLSL string that will evaluate to the float snap payload written during
+   * a snapping pass (see {@link Scene#snap}). When <code>undefined</code>, the
+   * command does not render during a snapping pass.
+   *
+   * @type {string|undefined}
+   * @default undefined
+   */
+  get snapId() {
+    return this._snapId;
+  }
+
+  set snapId(value) {
+    if (this._snapId !== value) {
+      this._snapId = value;
+      this.dirty = true;
+    }
+  }
+
   /**
    * Whether metadata picking is allowed.
    *
@@ -628,6 +649,7 @@ class DrawCommand {
     result._owner = command._owner;
     result._debugOverlappingFrustums = command._debugOverlappingFrustums;
     result._pickId = command._pickId;
+    result._snapId = command._snapId;
     result._pickMetadataAllowed = command._pickMetadataAllowed;
     result._pickedMetadataInfo = command._pickedMetadataInfo;
     result._flags = command._flags;

package/Source/Renderer/Framebuffer.js

@@ -287,6 +287,10 @@ function Framebuffer(options) {
   }
 
   this._unBind();
+
+  // _bind and _unBind bypass the context's framebuffer binding cache. The GL
+  // binding is now the default framebuffer; update the cache to match.
+  context._currentFramebuffer = undefined;
 }
 
 Object.defineProperties(Framebuffer.prototype, {

package/Source/Renderer/Pass.js

@@ -19,16 +19,17 @@ const Pass = {
   GLOBE: 2,
   TERRAIN_CLASSIFICATION: 3,
   CESIUM_3D_TILE_EDGES: 4,
-  CESIUM_3D_TILE: 5,
-  CESIUM_3D_TILE_CLASSIFICATION: 6,
-  CESIUM_3D_TILE_CLASSIFICATION_IGNORE_SHOW: 7,
-  OPAQUE: 8,
-  TRANSLUCENT: 9,
-  VOXELS: 10,
-  GAUSSIAN_SPLATS: 11,
-  CESIUM_3D_TILE_EDGES_DIRECT: 12,
-  OVERLAY: 13,
-  NUMBER_OF_PASSES: 14,
+  CESIUM_3D_TILE_PLANAR_FILL_ID: 5,
+  CESIUM_3D_TILE: 6,
+  CESIUM_3D_TILE_CLASSIFICATION: 7,
+  CESIUM_3D_TILE_CLASSIFICATION_IGNORE_SHOW: 8,
+  OPAQUE: 9,
+  TRANSLUCENT: 10,
+  VOXELS: 11,
+  GAUSSIAN_SPLATS: 12,
+  CESIUM_3D_TILE_EDGES_DIRECT: 13,
+  OVERLAY: 14,
+  NUMBER_OF_PASSES: 15,
 };
 
 Object.freeze(Pass);

package/Source/Renderer/ShaderBuilder.js

@@ -424,7 +424,7 @@ ShaderBuilder.prototype.addVertexLines = function (lines) {
 /**
  * Appends lines of GLSL code to the fragment shader
  *
- * @param {string[]} lines The lines to add to the end of the fragment shader source
+ * @param {string|string[]} lines One or more lines to add to the end of the fragment shader source
  *
  * @example
  * shaderBuilder.addFragmentLines([

package/Source/Renderer/Texture.js

@@ -1,5 +1,6 @@
 import Cartesian2 from "../Core/Cartesian2.js";
 import Check from "../Core/Check.js";
+import Color from "../Core/Color.js";
 import createGuid from "../Core/createGuid.js";
 import Frozen from "../Core/Frozen.js";
 import defined from "../Core/defined.js";
@@ -1123,4 +1124,14 @@ Texture.prototype.destroy = function () {
   this._context._gl.deleteTexture(this._texture);
   return destroyObject(this);
 };
+
+/**
+ * The default color used as a placeholder texture while other textures are downloaded.
+ * This can be changed globally to customize the placeholder appearance.
+ *
+ * @type {Color}
+ * @default Color.WHITE
+ */
+Texture.defaultColor = Color.WHITE;
+
 export default Texture;

package/Source/Renderer/UniformState.js

@@ -37,6 +37,13 @@ function UniformState() {
    * @type {Texture}
    */
   this.edgeDepthTexture = undefined; // packed depth color attachment from edge pass
+  /**
+   * Texture written by the planar fill feature-ID pre-pass.
+   * Contains per-pixel feature IDs for non-behind planar fill geometry.
+   * Sampled by behind fills to test same-object coplanarity.
+   * @type {Texture}
+   */
+  this.planarFillIdTexture = undefined;
   /**
    * @type {number}
    */
@@ -155,8 +162,10 @@ function UniformState() {
   this._frustum2DWidth = 0.0;
   this._eyeHeight = 0.0;
   this._eyeHeight2D = new Cartesian2();
+  this._eyeCartographic = new Cartesian3();
   this._eyeEllipsoidNormalEC = new Cartesian3();
   this._eyeEllipsoidCurvature = new Cartesian2();
+  this._eyeToEnu = new Matrix3();
   this._modelToEnu = new Matrix4();
   this._enuToModel = new Matrix4();
   this._pixelRatio = 1.0;
@@ -708,6 +717,19 @@ Object.defineProperties(UniformState.prototype, {
     },
   },
 
+  /**
+   * The geodetic longitude (<code>x</code>), latitude (<code>y</code>) in radians and
+   * height (<code>z</code>) in meters of the eye (camera).
+   * This is only valid when the {@link SceneMode} is <code>SCENE3D</code>.
+   * @memberof UniformState.prototype
+   * @type {Cartesian3}
+   */
+  eyeCartographic: {
+    get: function () {
+      return this._eyeCartographic;
+    },
+  },
+
   /**
    * The height (<code>x</code>) and the height squared (<code>y</code>)
    * in meters of the eye (camera) above the 2D world plane. This uniform is only valid
@@ -744,9 +766,22 @@ Object.defineProperties(UniformState.prototype, {
     },
   },
 
+  /**
+   * A 3x3 rotation from eye coordinates to an east-north-up coordinate system
+   * centered at the position on the ellipsoid below the camera.
+   * This uniform is only valid when the {@link SceneMode} is <code>SCENE3D</code>.
+   * @memberof UniformState.prototype
+   * @type {Matrix3}
+   */
+  eyeToEnu: {
+    get: function () {
+      return this._eyeToEnu;
+    },
+  },
+
   /**
    * A transform from model coordinates to an east-north-up coordinate system
-   * centered at the position on the ellipsoid below the camera
+   * centered at the position on the ellipsoid nearest to the camera.
    * @memberof UniformState.prototype
    * @type {Matrix4}
    */
@@ -1234,6 +1269,7 @@ function setInfiniteProjection(uniformState, matrix) {
 
 const surfacePositionScratch = new Cartesian3();
 const enuTransformScratch = new Matrix4();
+const enuRotationScratch = new Matrix3();
 
 function setCamera(uniformState, camera) {
   Cartesian3.clone(camera.positionWC, uniformState._cameraPosition);
@@ -1259,6 +1295,12 @@ function setCamera(uniformState, camera) {
     );
   } else {
     uniformState._eyeHeight = positionCartographic.height;
+    uniformState._eyeCartographic = Cartesian3.fromElements(
+      positionCartographic.longitude,
+      positionCartographic.latitude,
+      positionCartographic.height,
+      uniformState._eyeCartographic,
+    );
     uniformState._eyeEllipsoidNormalEC =
       ellipsoid.geodeticSurfaceNormalCartographic(
         positionCartographic,
@@ -1300,6 +1342,17 @@ function setCamera(uniformState, camera) {
     uniformState._modelToEnu,
   );
 
+  const enuToWorldRotation = Matrix4.getRotation(
+    enuToWorld,
+    enuRotationScratch,
+  );
+  const enuToView = Matrix3.multiply(
+    uniformState._viewRotation,
+    enuToWorldRotation,
+    enuRotationScratch,
+  );
+  uniformState._eyeToEnu = Matrix3.transpose(enuToView, uniformState._eyeToEnu);
+
   if (
     !CesiumMath.equalsEpsilon(
       ellipsoid._radii.x,

package/Source/Renderer/VertexArray.js

@@ -645,7 +645,6 @@ VertexArray.fromGeometry = function (options) {
         }
 
         let attrProps = {};
-        vertexBuffer = undefined;
         if (defined(attribute.values)) {
           vertexBuffer = Buffer.createVertexBuffer({
             context: context,

package/Source/Scene/ArcGisMapServerImageryProvider.js

@@ -325,11 +325,6 @@ function ArcGisMapServerImageryProvider(options) {
   this._credit = options.credit;
   this._tileCredits = undefined;
 
-  let credit = options.credit;
-  if (typeof credit === "string") {
-    credit = new Credit(credit);
-  }
-
   /**
    * Gets or sets a value indicating whether feature picking is enabled.  If true, {@link ArcGisMapServerImageryProvider#pickFeatures} will
    * invoke the "identify" operation on the ArcGIS server and return the features included in the response.  If false,

package/Source/Scene/ArcGisMapService.js

@@ -4,7 +4,7 @@ import Resource from "../Core/Resource.js";
 
 let defaultTokenCredit;
 const defaultAccessToken =
-  "AAPTaNEKX8S_W5tHpwdW7Txp1uA..bCHyKIo32UDZUn0ep6bzo_JLzQdslNSJ9HpSru5K9nkNyUqvkKFceNFYUFPbtEEZPfCqpF_qVG3zdTZOzocx6Dnzy0e2LctUukYPVrG2GPAdcPN-M9nklag0M8cYMkSCHQOort_AeIxl8C7ORIX0KjE5Mrvbe0Rm3eC-YpZDiHp6PUyarwFpsRdcq1TvpcQqsqJQ3aoWdEIxnEjEZ6e6iZhte1i2oJgrZ8SxsSPaIbrjA4USgsQGeBjUAT1_V7gBCY6D";
+  "AAPTaeRGM19PsTpo1ePVkJZk4Tg..zqn3rpU4kUaF-8QMW-oWZntlxvKhdUFXLBoo5dQwRNEKd1EoKJh-Ha2zxbrz2Nhz2tV_gLVZTQwFHLzJHKwsGDz4GTKV8jeUgb12Ci9CeU_9sOrauJYnGK2vHhtSSAQ-73rmKzNG_2lZ0zuCCEKslxCmXUw2mT1Cpk0RoCCtDheWByX1e7Lnb3LKCBDt9VhGFSGCOiaFfizFRLld8LWukKgxCgluTpKgUuUi4OytX84roEpm6mP7PE91AT1_5Uash6To";
 /**
  * Default options for accessing the ArcGIS image tile service.
  *

package/Source/Scene/Billboard.js

@@ -706,8 +706,9 @@ Object.defineProperties(Billboard.prototype, {
   },
 
   /**
-   * Gets or sets the aligned axis in world space. The aligned axis is the unit vector that the billboard up vector points towards.
+   * The aligned axis is the direction vector that the billboard up vector points towards.
    * The default is the zero vector, which means the billboard is aligned to the screen up vector.
+   * Note that only the zero vector (0,0,0) resets the alignment to screen up.
    * @memberof Billboard.prototype
    * @type {Cartesian3}
    * @example

package/Source/Scene/BillboardCollection.js

@@ -1033,8 +1033,9 @@ function writeCompressedAttrib1(
   billboard,
 ) {
   const writer = vafWriters[attributeLocations.compressedAttribute1];
-  const alignedAxis = billboard.alignedAxis;
+  let alignedAxis = billboard.alignedAxis;
   if (!Cartesian3.equals(alignedAxis, Cartesian3.ZERO)) {
+    alignedAxis = Cartesian3.normalize(alignedAxis, new Cartesian3());
     billboardCollection._shaderAlignedAxis = true;
   }
 
@@ -1096,12 +1097,15 @@ function writeCompressedAttrib2(
     ? billboard.getPickId(frameState.context).color
     : Color.WHITE;
   const sizeInMeters = billboard.sizeInMeters ? 1.0 : 0.0;
+  const rawAxis = billboard.alignedAxis;
+  const normalizedAxis = !Cartesian3.equals(rawAxis, Cartesian3.ZERO)
+    ? Cartesian3.normalize(rawAxis, new Cartesian3())
+    : rawAxis;
   const validAlignedAxis =
-    Math.abs(Cartesian3.magnitudeSquared(billboard.alignedAxis) - 1.0) <
+    Math.abs(Cartesian3.magnitudeSquared(normalizedAxis) - 1.0) <
     CesiumMath.EPSILON6
       ? 1.0
       : 0.0;
-
   billboardCollection._allSizedInMeters =
     billboardCollection._allSizedInMeters && sizeInMeters === 1.0;
 

package/Source/Scene/BufferPointCollection.js

@@ -12,6 +12,7 @@ import BufferPointMaterial from "./BufferPointMaterial.js";
 /** @import ComponentDatatype from "../Core/ComponentDatatype.js"; */
 /** @import Matrix4 from "../Core/Matrix4.js"; */
 /** @import FrameState from "./FrameState.js"; */
+/** @import { BufferPrimitiveCollectionOptions } from "./BufferPrimitiveCollection.js"; */
 
 /**
  * @typedef {object} BufferPointOptions
@@ -91,17 +92,13 @@ class BufferPointCollection extends BufferPrimitiveCollection {
   // COLLECTION LIFECYCLE
 
   /**
-   * @param {BufferPointCollection} collection
+   * @param {BufferPrimitiveCollectionOptions} [options]
    * @returns {BufferPointCollection}
    * @override
    * @ignore
    */
-  static _cloneEmpty(collection) {
-    return new BufferPointCollection({
-      primitiveCountMax: collection.primitiveCountMax,
-      positionDatatype: collection.positionDatatype,
-      positionNormalized: collection.positionNormalized,
-    });
+  _cloneEmpty(options = Frozen.EMPTY_OBJECT) {
+    return new BufferPointCollection(this._cloneEmptyBaseArgs(options));
   }
 
   /////////////////////////////////////////////////////////////////////////////

package/Source/Scene/BufferPolygonCollection.js

@@ -14,6 +14,7 @@ import BufferPolygonMaterial from "./BufferPolygonMaterial.js";
 /** @import { TypedArray } from "../Core/globalTypes.js"; */
 /** @import Matrix4 from "../Core/Matrix4.js"; */
 /** @import FrameState from "./FrameState.js" */
+/** @import HeightReference from "./HeightReference.js"; */
 /** @import ComponentDatatype from "../Core/ComponentDatatype.js"; */
 
 const { ERR_CAPACITY } = BufferPrimitiveCollection.Error;
@@ -31,6 +32,29 @@ const { ERR_CAPACITY } = BufferPrimitiveCollection.Error;
  * @experimental This feature is not final and is subject to change without Cesium's standard deprecation policy.
  */
 
+/**
+ * @typedef {object} BufferPolygonCollectionOptions
+ * @property {number} [primitiveCountMax=BufferPrimitiveCollection.DEFAULT_CAPACITY] Maximum number of polygons.
+ * @property {number} [vertexCountMax=BufferPrimitiveCollection.DEFAULT_CAPACITY] Maximum number of vertices.
+ * @property {number} [holeCountMax=BufferPrimitiveCollection.DEFAULT_CAPACITY] Maximum number of holes.
+ * @property {number} [triangleCountMax=BufferPrimitiveCollection.DEFAULT_CAPACITY] Maximum number of triangles.
+ * @property {ComponentDatatype} [positionDatatype=ComponentDatatype.DOUBLE] The component datatype used to store position values.
+ * @property {boolean} [positionNormalized=false] When <code>true</code>, integer position values are treated as normalized,
+ *   where the full integer range maps to [-1, 1] (signed) or [0, 1] (unsigned). Only relevant for integer position datatypes
+ *   (BYTE, UNSIGNED_BYTE, SHORT, UNSIGNED_SHORT).
+ * @property {boolean} [show=true]
+ * @property {boolean} [allowPicking=true] When <code>true</code>, primitives are pickable with {@link Scene#pick}. When <code>false</code>, memory and initialization cost are lower.
+ * @property {BoundingSphere} [boundingVolume] Bounding volume, in world space, for the collection. When
+ *    unspecified, a bounding volume is computed automatically and updated when primitive positions change. When
+ *    specified, users are responsible for updating bounding volume as needed. Pre-computing the bounding volume
+ *    manually, and updating it only as needed, will improve performance for larger dynamic collections.
+ * @property {boolean} [debugShowBoundingVolume=false]
+ * @property {BlendOption} [blendOption=BlendOption.TRANSLUCENT]
+ * @property {HeightReference} [heightReference=HeightReference.NONE] When set to a clamping value, the
+ *   collection is draped onto terrain and/or 3D Tiles, rather than drawn as geometry of its own.
+ * @experimental This feature is not final and is subject to change without Cesium's standard deprecation policy.
+ */
+
 /**
  * Collection of polygons held in ArrayBuffer storage for performance and memory optimization.
  *
@@ -76,21 +100,7 @@ const { ERR_CAPACITY } = BufferPrimitiveCollection.Error;
  */
 class BufferPolygonCollection extends BufferPrimitiveCollection {
   /**
-   * @param {object} options
-   * @param {number} [options.primitiveCountMax=BufferPrimitiveCollection.DEFAULT_CAPACITY]
-   * @param {number} [options.vertexCountMax=BufferPrimitiveCollection.DEFAULT_CAPACITY]
-   * @param {number} [options.holeCountMax=BufferPrimitiveCollection.DEFAULT_CAPACITY]
-   * @param {number} [options.triangleCountMax=BufferPrimitiveCollection.DEFAULT_CAPACITY]
-   * @param {ComponentDatatype} [options.positionDatatype=ComponentDatatype.DOUBLE]
-   * @param {boolean} [options.positionNormalized=false]
-   * @param {boolean} [options.show=true]
-   * @param {boolean} [options.allowPicking=true] When <code>true</code>, primitives are pickable with {@link Scene#pick}. When <code>false</code>, memory and initialization cost are lower.
-   * @param {BoundingSphere} [options.boundingVolume] Bounding volume, in world space, for the collection. When
-   *    unspecified, a bounding volume is computed automatically and updated when primitive positions change. When
-   *    specified, users are responsible for updating bounding volume as needed. Pre-computing the bounding volume
-   *    manually, and updating it only as needed, will improve performance for larger dynamic collections.
-   * @param {boolean} [options.debugShowBoundingVolume=false]
-   * @param {BlendOption} [options.blendOption=BlendOption.TRANSLUCENT]
+   * @param {BufferPolygonCollectionOptions} [options]
    */
   constructor(options = Frozen.EMPTY_OBJECT) {
     super(options);
@@ -193,10 +203,16 @@ class BufferPolygonCollection extends BufferPrimitiveCollection {
    *
    * @param {BufferPolygonCollection} collection
    * @param {BufferPolygonCollection} result
+   * @param {function(BufferPolygon, number): boolean} [predicate] When provided, only polygons for which this returns <code>true</code> are copied. Surviving polygons are compacted into contiguous indices.
    * @returns {BufferPolygonCollection}
    */
-  static clone(collection, result) {
-    super.clone(collection, result);
+  static clone(collection, result, predicate) {
+    super.clone(collection, result, predicate);
+
+    // Base class's filtered clone uses PrimitiveClass.clone, which handles holes and triangles, so just return the result.
+    if (defined(predicate)) {
+      return result;
+    }
 
     //>>includeStart('debug', pragmas.debug);
     assert(collection.holeCount <= result.holeCountMax, ERR_CAPACITY);
@@ -222,19 +238,33 @@ class BufferPolygonCollection extends BufferPrimitiveCollection {
   }
 
   /**
-   * @param {BufferPolygonCollection} collection
+   * Returns a copy of the given collection, overriding any constructor options
+   * provided. Omitted options are inherited from the source collection. Any
+   * resized buffers must be large enough to hold every polygon.
+   *
+   * @param {BufferPolygonCollection} collection Source collection to copy.
+   * @param {BufferPolygonCollectionOptions} [options] Constructor options to override. Omitted options are inherited from the source collection.
+   * @param {function(BufferPolygon, number): boolean} [predicate] When provided, only polygons for which this returns <code>true</code> are copied. Surviving polygons are compacted into contiguous indices.
+   * @returns {BufferPolygonCollection}
+   * @override
+   */
+  static fromCollection(collection, options, predicate) {
+    return /** @type {BufferPolygonCollection} */ (
+      super.fromCollection(collection, options, predicate)
+    );
+  }
+
+  /**
+   * @param {BufferPolygonCollectionOptions} [options]
    * @returns {BufferPolygonCollection}
    * @override
    * @ignore
    */
-  static _cloneEmpty(collection) {
+  _cloneEmpty(options = Frozen.EMPTY_OBJECT) {
     return new BufferPolygonCollection({
-      primitiveCountMax: collection.primitiveCountMax,
-      vertexCountMax: collection.vertexCountMax,
-      holeCountMax: collection.holeCountMax,
-      triangleCountMax: collection.triangleCountMax,
-      positionDatatype: collection.positionDatatype,
-      positionNormalized: collection.positionNormalized,
+      holeCountMax: this.holeCountMax,
+      triangleCountMax: this.triangleCountMax,
+      ...this._cloneEmptyBaseArgs(options),
     });
   }
 
@@ -305,8 +335,7 @@ class BufferPolygonCollection extends BufferPrimitiveCollection {
   update(frameState) {
     super.update(frameState);
 
-    const passes = frameState.passes;
-    if (this.show && (passes.render || passes.pick)) {
+    if (this._isRendered(frameState)) {
       this._renderContext = renderPolygons(
         this,
         frameState,