feat(engine): Add BufferPointCollection, BufferPolylineCollection, BufferPolygonCollection

Author: donmccurdy

CHANGES.md

@@ -1,5 +1,13 @@
 # Change Log
 
+## 1.140 - 2026-04-01
+
+### @cesium/engine
+
+#### Additions :tada:
+
+- Added experimental, performance-focused vector primitive APIs: `BufferPointCollection`, `BufferPolylineCollection`, and `BufferPolygonCollection`. [#13212](https://github.com/CesiumGS/cesium/pull/13212)
+
 ## 1.139 - 2026-03-02
 
 ### @cesium/engine

Tools/jsdoc/cesiumTags.js

@@ -64,8 +64,8 @@ exports.defineTags = function (dictionary) {
   // https://github.com/microsoft/TypeScript/issues/22160#issuecomment-2021459033
   // https://devblogs.microsoft.com/typescript/announcing-typescript-5-5-beta/#type-imports-in-jsdoc
   dictionary.defineTag("import", {
-    canHaveType: true,
-    canHaveName: true,
     mustHaveValue: true,
+    canHaveType: false,
+    canHaveName: false,
   });
 };

packages/engine/Source/Core/BoundingSphere.js

@@ -350,7 +350,7 @@ BoundingSphere.fromRectangle3D = function (
  * algorithms, a naive algorithm and Ritter's algorithm. The smaller of the two spheres is used to
  * ensure a tight fit.
  *
- * @param {number[]} [positions] An array of points that the bounding sphere will enclose.  Each point
+ * @param {number[]|TypedArray} [positions] An array of points that the bounding sphere will enclose.  Each point
  *        is formed from three elements in the array in the order X, Y, Z.
  * @param {Cartesian3} [center=Cartesian3.ZERO] The position to which the positions are relative, which need not be the
  *        origin of the coordinate system.  This is useful when the positions are to be used for

packages/engine/Source/Core/DeveloperError.js

@@ -65,7 +65,8 @@ DeveloperError.prototype.toString = function () {
 };
 
 /**
- * @private
+ * @returns {never}
+ * @ignore
  */
 DeveloperError.throwInstantiationError = function () {
   throw new DeveloperError(

packages/engine/Source/Core/assert.js

@@ -0,0 +1,27 @@
+// @ts-check
+
+import DeveloperError from "./DeveloperError.js";
+
+/**
+ * Checks that a condition is truthy, throwing a specified message if condition
+ * fails. The `asserts condition` return type allows TypeScript to narrow the
+ * types of the condition and enforce stricter types without further if/else
+ * checks or nullish coalescing.
+ *
+ * @example
+ * assert(object.optionalProperty, 'Missing .optionalProperty');
+ * object.optionalProperty.toString(); // safe; no type error.
+ *
+ * @function
+ *
+ * @param {*} condition
+ * @param {string} msg
+ * @ignore
+ */
+function assert(condition, msg) {
+  if (!condition) {
+    throw new DeveloperError(msg);
+  }
+}
+
+export default assert;

packages/engine/Source/Renderer/RenderState.js

@@ -456,7 +456,7 @@ let renderStateCache = {};
  * @see DrawCommand
  * @see ClearCommand
  *
- * @private
+ * @ignore
  */
 RenderState.fromCache = function (renderState) {
   const partialKey = JSON.stringify(renderState);

packages/engine/Source/Scene/BufferPoint.js

@@ -0,0 +1,146 @@
+// @ts-check
+
+import BufferPrimitive from "./BufferPrimitive.js";
+import Cartesian3 from "../Core/Cartesian3.js";
+import assert from "../Core/assert.js";
+import BufferPrimitiveCollection from "./BufferPrimitiveCollection.js";
+
+/** @import BufferPointCollection from "./BufferPointCollection.js"; */
+
+const { ERR_CAPACITY } = BufferPrimitiveCollection.Error;
+
+const scratchCartesian = new Cartesian3();
+
+/**
+ * View bound to the underlying buffer data of a {@link BufferPointCollection}.
+ *
+ * <p>BufferPoint instances are {@link https://en.wikipedia.org/wiki/Flyweight_pattern|flyweights}:
+ * a single BufferPoint instance can be temporarily bound to any conceptual
+ * "point" in a BufferPointCollection, allowing very large collections to be
+ * iterated and updated with a minimal memory footprint.</p>
+ *
+ * Represented as one (1) position.
+ *
+ * @see BufferPointCollection
+ * @see BufferPrimitive
+ * @experimental This feature is not final and is subject to change without Cesium's standard deprecation policy.
+ * @extends BufferPrimitive
+ */
+class BufferPoint extends BufferPrimitive {
+  /**
+   * @type {BufferPointCollection}
+   * @ignore
+   */
+  _collection = null;
+
+  /** @ignore */
+  static Layout = {
+    ...BufferPrimitive.Layout,
+
+    /**
+     * Offset in position array to current point vertex, number of VEC3 elements.
+     * @type {number}
+     * @ignore
+     */
+    POSITION_OFFSET_U32: BufferPrimitive.Layout.__BYTE_LENGTH,
+
+    /**
+     * @type {number}
+     * @ignore
+     */
+    __BYTE_LENGTH: BufferPrimitive.Layout.__BYTE_LENGTH + 4,
+  };
+
+  /////////////////////////////////////////////////////////////////////////////
+  // LIFECYCLE
+
+  /**
+   * Copies data from source point to result.
+   *
+   * @param {BufferPoint} point
+   * @param {BufferPoint} result
+   * @return {BufferPoint}
+   * @override
+   */
+  static clone(point, result) {
+    super.clone(point, result);
+    result.setPosition(point.getPosition(scratchCartesian));
+    return result;
+  }
+
+  /////////////////////////////////////////////////////////////////////////////
+  // GEOMETRY
+
+  /**
+   * Offset in collection position array to position of this point, number
+   * of VEC3 elements.
+   *
+   * @type {number}
+   * @readonly
+   * @ignore
+   */
+  get vertexOffset() {
+    return this._getUint32(BufferPoint.Layout.POSITION_OFFSET_U32);
+  }
+
+  /**
+   * Count of positions (vertices) in this primitive. Always 1.
+   *
+   * @type {number}
+   * @readonly
+   */
+  get vertexCount() {
+    return 1;
+  }
+
+  /**
+   * Gets the position of this point.
+   *
+   * @param {Cartesian3} [result]
+   * @returns {Cartesian3}
+   */
+  getPosition(result) {
+    const positionF64 = this._collection._positionF64;
+    return Cartesian3.fromArray(positionF64, this.vertexOffset * 3, result);
+  }
+
+  /**
+   * Sets the position of this point.
+   *
+   * @param {Cartesian3} position
+   */
+  setPosition(position) {
+    const collection = this._collection;
+    const vertexOffset = this.vertexOffset;
+
+    //>>includeStart('debug', pragmas.debug);
+    assert(vertexOffset < collection.vertexCountMax, ERR_CAPACITY);
+    //>>includeEnd('debug');
+
+    collection._positionF64[vertexOffset * 3] = position.x;
+    collection._positionF64[vertexOffset * 3 + 1] = position.y;
+    collection._positionF64[vertexOffset * 3 + 2] = position.z;
+
+    collection._makeDirtyBoundingVolume();
+  }
+
+  /////////////////////////////////////////////////////////////////////////////
+  // DEBUG
+
+  /**
+   * Returns a JSON-serializable object representing the point. This encoding
+   * is not memory-efficient, and should generally be used for debugging and
+   * testing.
+   *
+   * @returns {Object} JSON-serializable object.
+   * @override
+   */
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      position: Cartesian3.pack(this.getPosition(), []),
+    };
+  }
+}
+
+export default BufferPoint;

packages/engine/Source/Scene/BufferPointCollection.js

@@ -0,0 +1,122 @@
+// @ts-check
+
+import BufferPrimitiveCollection from "./BufferPrimitiveCollection.js";
+import BufferPoint from "./BufferPoint.js";
+import Cartesian3 from "../Core/Cartesian3.js";
+import Frozen from "../Core/Frozen.js";
+
+/** @import Color from "../Core/Color.js"; */
+/** @import FrameState from "./FrameState.js" */
+
+/**
+ * @typedef {object} BufferPointOptions
+ * @property {boolean} [show=true]
+ * @property {Color} [color=Color.WHITE]
+ * @property {Cartesian3} [position=Cartesian3.ZERO]
+ * @experimental This feature is not final and is subject to change without Cesium's standard deprecation policy.
+ */
+
+/**
+ * Collection of points held in ArrayBuffer storage for performance and memory optimization.
+ *
+ * <p>Default buffer memory allocation is arbitrary, and collections cannot be resized,
+ * so specific per-buffer capacities should be provided in the collection
+ * constructor when available.</p>
+ *
+ * @example
+ * const collection = new BufferPointCollection({primitiveCountMax: 1024});
+ *
+ * const point = new BufferPoint();
+ *
+ * // Create a new point, temporarily bound to 'point' local variable.
+ * collection.add({
+ *   position: new Cartesian3(0.0, 0.0, 0.0),
+ *   color: Color.WHITE,
+ * }, point);
+ *
+ * // Iterate over all points in collection, temporarily binding 'point'
+ * // local variable to each, and updating point color.
+ * for (let i = 0; i < collection.primitiveCount; i++) {
+ *   collection.get(i, point);
+ *   point.setColor(Color.RED);
+ * }
+ *
+ * @see BufferPoint
+ * @see BufferPrimitiveCollection
+ * @extends BufferPrimitiveCollection<BufferPoint>
+ * @experimental This feature is not final and is subject to change without Cesium's standard deprecation policy.
+ */
+class BufferPointCollection extends BufferPrimitiveCollection {
+  /**
+   * @param {object} options
+   * @param {number} [options.primitiveCountMax=BufferPrimitiveCollection.DEFAULT_CAPACITY]
+   * @param {boolean} [options.show=true]
+   * @param {boolean} [options.debugShowBoundingVolume=false]
+   */
+  constructor(options = Frozen.EMPTY_OBJECT) {
+    super({ ...options, vertexCountMax: options.primitiveCountMax });
+  }
+
+  _getCollectionClass() {
+    return BufferPointCollection;
+  }
+
+  _getPrimitiveClass() {
+    return BufferPoint;
+  }
+
+  /////////////////////////////////////////////////////////////////////////////
+  // COLLECTION LIFECYCLE
+
+  /**
+   * @param {BufferPointCollection} collection
+   * @returns {BufferPointCollection}
+   * @override
+   * @ignore
+   */
+  static _cloneEmpty(collection) {
+    return new BufferPointCollection({
+      primitiveCountMax: collection.primitiveCountMax,
+    });
+  }
+
+  /////////////////////////////////////////////////////////////////////////////
+  // PRIMITIVE LIFECYCLE
+
+  /**
+   * Adds a new point to the collection, with the specified options. A
+   * {@link BufferPoint} instance is linked to the new point, using
+   * the 'result' argument if given, or a new instance if not. For repeated
+   * calls, prefer to reuse a single BufferPoint instance rather than
+   * allocating a new instance on each call.
+   *
+   * @param {BufferPointOptions} options
+   * @param {BufferPoint} result
+   * @returns {BufferPoint}
+   * @override
+   */
+  add(options, result = new BufferPoint()) {
+    super.add(options, result);
+
+    result._setUint32(
+      BufferPoint.Layout.POSITION_OFFSET_U32,
+      this._positionCount++,
+    );
+    result.setPosition(options.position ?? Cartesian3.ZERO);
+
+    return result;
+  }
+
+  /////////////////////////////////////////////////////////////////////////////
+  // RENDER
+
+  /**
+   * @param {FrameState} frameState
+   * @ignore
+   */
+  update(frameState) {
+    super.update(frameState);
+  }
+}
+
+export default BufferPointCollection;