@cesium/engine 23.0.1 → 24.0.0

package/Source/Scene/BufferPolygonCollection.js

@@ -0,0 +1,368 @@
+// @ts-check
+
+import defined from "../Core/defined.js";
+import BufferPrimitiveCollection from "./BufferPrimitiveCollection.js";
+import BufferPolygon from "./BufferPolygon.js";
+import Frozen from "../Core/Frozen.js";
+import assert from "../Core/assert.js";
+import IndexDatatype from "../Core/IndexDatatype.js";
+import renderPolygons from "./renderBufferPolygonCollection.js";
+import BufferPolygonMaterial from "./BufferPolygonMaterial.js";
+
+/** @import { TypedArray } from "../Core/globalTypes.js"; */
+/** @import Matrix4 from "../Core/Matrix4.js"; */
+/** @import FrameState from "./FrameState.js" */
+/** @import ComponentDatatype from "../Core/ComponentDatatype.js"; */
+
+const { ERR_CAPACITY } = BufferPrimitiveCollection.Error;
+
+/**
+ * @typedef {object} BufferPolygonOptions
+ * @property {Matrix4} [options.modelMatrix=Matrix4.IDENTITY] Transforms geometry from model to world coordinates.
+ * @property {boolean} [show=true]
+ * @property {BufferPolygonMaterial} [material=BufferPolygonMaterial.DEFAULT_MATERIAL]
+ * @property {TypedArray} [positions]
+ * @property {TypedArray} [holes]
+ * @property {TypedArray} [triangles]
+ * @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.
+ *
+ * <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
+ * import earcut from "earcut";
+ *
+ * const collection = new BufferPolygonCollection({
+ *   primitiveCountMax: 1024,
+ *   vertexCountMax: 4096,
+ *   holeCountMax: 1024,
+ *   triangleCountMax: 2048,
+ * });
+ *
+ * const polygon = new BufferPolygon();
+ * const positions = [ ... ];
+ * const holes = [ ... ];
+ * const material = new BufferPolygonMaterial({color: Color.WHITE});
+ *
+ * // Create a new polygon, temporarily bound to 'polygon' local variable.
+ * collection.add({
+ *   positions: new Float64Array(positions),
+ *   holes: new Uint32Array(holes),
+ *   triangles: new Uint32Array(earcut(positions, holes, 3)),
+ *   material
+ * }, polygon);
+ *
+ * // Iterate over all polygons in collection, temporarily binding 'polygon'
+ * // local variable to each, and updating polygon material.
+ * for (let i = 0; i < collection.primitiveCount; i++) {
+ *   collection.get(i, polygon);
+ *   polygon.setMaterial(material);
+ * }
+ *
+ * @see BufferPolygon
+ * @see BufferPolygonMaterial
+ * @see BufferPrimitiveCollection
+ * @extends BufferPrimitiveCollection<BufferPolygon>
+ * @experimental This feature is not final and is subject to change without Cesium's standard deprecation policy.
+ */
+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.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 {boolean} [options.debugShowBoundingVolume=false]
+   */
+  constructor(options = Frozen.EMPTY_OBJECT) {
+    super(options);
+
+    /**
+     * @type {number}
+     * @ignore
+     */
+    this._holeCount = 0;
+
+    /**
+     * @type {number}
+     * @protected
+     * @ignore
+     */
+    this._holeCountMax =
+      options.holeCountMax ?? BufferPrimitiveCollection.DEFAULT_CAPACITY;
+
+    /**
+     * @type {TypedArray}
+     * @ignore
+     */
+    this._holeIndexView = null;
+
+    /**
+     * @type {number}
+     * @ignore
+     */
+    this._triangleCount = 0;
+
+    /**
+     * @type {number}
+     * @protected
+     * @ignore
+     */
+    this._triangleCountMax =
+      options.triangleCountMax ?? BufferPrimitiveCollection.DEFAULT_CAPACITY;
+
+    /**
+     * @type {TypedArray}
+     * @ignore
+     */
+    this._triangleIndexView = null;
+
+    this._allocateHoleIndexBuffer();
+    this._allocateTriangleIndexBuffer();
+  }
+
+  _getCollectionClass() {
+    return BufferPolygonCollection;
+  }
+
+  _getPrimitiveClass() {
+    return BufferPolygon;
+  }
+
+  _getMaterialClass() {
+    return BufferPolygonMaterial;
+  }
+
+  /////////////////////////////////////////////////////////////////////////////
+  // COLLECTION LIFECYCLE
+
+  /**
+   * @private
+   * @ignore
+   */
+  _allocateHoleIndexBuffer() {
+    // @ts-expect-error Requires https://github.com/CesiumGS/cesium/pull/13203.
+    this._holeIndexView = IndexDatatype.createTypedArray(
+      this._positionCountMax,
+      this._holeCountMax,
+    );
+  }
+
+  /**
+   * @private
+   * @ignore
+   */
+  _allocateTriangleIndexBuffer() {
+    // @ts-expect-error Requires https://github.com/CesiumGS/cesium/pull/13203.
+    this._triangleIndexView = IndexDatatype.createTypedArray(
+      this._positionCountMax,
+      this._triangleCountMax * 3,
+    );
+  }
+
+  /**
+   * Duplicates the contents of this collection into the result collection.
+   * Result collection is not resized, and must contain enough space for all
+   * primitives in the source collection. Existing polygons in the result
+   * collection will be overwritten.
+   *
+   * <p>Useful when allocating more space for a collection that has reached its
+   * capacity, and efficiently transferring polygons to the new collection.</p>
+   *
+   * @example
+   * const result = new BufferPolygonCollection({ ... }); // allocate larger 'result' collection
+   * BufferPolygonCollection.clone(collection, result);   // copy polygons from 'collection' into 'result'
+   *
+   * @param {BufferPolygonCollection} collection
+   * @param {BufferPolygonCollection} result
+   * @returns {BufferPolygonCollection}
+   */
+  static clone(collection, result) {
+    super.clone(collection, result);
+
+    //>>includeStart('debug', pragmas.debug);
+    assert(collection.holeCount <= result.holeCountMax, ERR_CAPACITY);
+    assert(collection.triangleCount <= result.triangleCountMax, ERR_CAPACITY);
+    //>>includeEnd('debug');
+
+    this._copySubArray(
+      collection._holeIndexView,
+      result._holeIndexView,
+      collection.holeCount,
+    );
+
+    this._copySubArray(
+      collection._triangleIndexView,
+      result._triangleIndexView,
+      collection._triangleCount * 3,
+    );
+
+    result._holeCount = collection._holeCount;
+    result._triangleCount = collection._triangleCount;
+
+    return result;
+  }
+
+  /**
+   * @param {BufferPolygonCollection} collection
+   * @returns {BufferPolygonCollection}
+   * @override
+   * @ignore
+   */
+  static _cloneEmpty(collection) {
+    return new BufferPolygonCollection({
+      primitiveCountMax: collection.primitiveCountMax,
+      vertexCountMax: collection.vertexCountMax,
+      holeCountMax: collection.holeCountMax,
+      triangleCountMax: collection.triangleCountMax,
+    });
+  }
+
+  /**
+   * @param {BufferPolygonCollection} src
+   * @param {BufferPolygonCollection} dst
+   * @override
+   * @ignore
+   */
+  static _replaceBuffers(src, dst) {
+    super._replaceBuffers(src, dst);
+    dst._holeIndexView = src._holeIndexView;
+    dst._triangleIndexView = src._triangleIndexView;
+  }
+
+  /////////////////////////////////////////////////////////////////////////////
+  // PRIMITIVE LIFECYCLE
+
+  /**
+   * Adds a new polygon to the collection, with the specified options. A
+   * {@link BufferPolygon} instance is linked to the new polygon, using
+   * the 'result' argument if given, or a new instance if not. For repeated
+   * calls, prefer to reuse a single BufferPolygon instance rather than
+   * allocating a new instance on each call.
+   *
+   * @param {BufferPolygonOptions} options
+   * @param {BufferPolygon} result
+   * @returns {BufferPolygon}
+   * @override
+   */
+  add(options, result = new BufferPolygon()) {
+    super.add(options, result);
+
+    const vertexOffset = this._positionCount;
+    result._setUint32(BufferPolygon.Layout.POSITION_OFFSET_U32, vertexOffset);
+    result._setUint32(BufferPolygon.Layout.POSITION_COUNT_U32, 0);
+
+    const holeOffset = this._holeCount;
+    result._setUint32(BufferPolygon.Layout.HOLE_OFFSET_U32, holeOffset);
+    result._setUint32(BufferPolygon.Layout.HOLE_COUNT_U32, 0);
+
+    const triangleOffset = this._triangleCount;
+    result._setUint32(BufferPolygon.Layout.TRIANGLE_OFFSET_U32, triangleOffset);
+    result._setUint32(BufferPolygon.Layout.TRIANGLE_COUNT_U32, 0);
+
+    if (defined(options.positions)) {
+      result.setPositions(options.positions);
+    }
+
+    if (defined(options.holes)) {
+      result.setHoles(options.holes);
+    }
+
+    if (defined(options.triangles)) {
+      result.setTriangles(options.triangles);
+    }
+
+    return result;
+  }
+
+  /////////////////////////////////////////////////////////////////////////////
+  // RENDER
+
+  /**
+   * @param {FrameState} frameState
+   * @ignore
+   */
+  update(frameState) {
+    super.update(frameState);
+
+    const passes = frameState.passes;
+    if (this.show && (passes.render || passes.pick)) {
+      this._renderContext = renderPolygons(
+        this,
+        frameState,
+        this._renderContext,
+      );
+    }
+  }
+
+  /////////////////////////////////////////////////////////////////////////////
+  // ACCESSORS
+
+  /**
+   * Total byte length of buffers owned by this collection. Includes any unused
+   * space allocated by {@link primitiveCountMax}, even if no polygons have
+   * yet been added in that space.
+   *
+   * @type {number}
+   * @readonly
+   * @override
+   */
+  get byteLength() {
+    return (
+      super.byteLength +
+      this._holeIndexView.byteLength +
+      this._triangleIndexView.byteLength
+    );
+  }
+
+  /**
+   * Number of holes in collection. Must be <= {@link holeCountMax}.
+   *
+   * @type {number}
+   * @readonly
+   */
+  get holeCount() {
+    return this._holeCount;
+  }
+
+  /**
+   * Maximum number of holes in collection. Must be >= {@link holeCount}.
+   *
+   * @type {number}
+   * @readonly
+   * @default {@link BufferPrimitiveCollection.DEFAULT_CAPACITY}
+   */
+  get holeCountMax() {
+    return this._holeCountMax;
+  }
+
+  /**
+   * Number of triangles in collection. Must be <= {@link triangleCountMax}.
+   *
+   * @type {number}
+   * @readonly
+   */
+  get triangleCount() {
+    return this._triangleCount;
+  }
+
+  /**
+   * Maximum number of triangles in collection. Must be >= {@link triangleCount}.
+   *
+   * @type {number}
+   * @readonly
+   * @default {@link BufferPrimitiveCollection.DEFAULT_CAPACITY}
+   */
+  get triangleCountMax() {
+    return this._triangleCountMax;
+  }
+}
+export default BufferPolygonCollection;

package/Source/Scene/BufferPolygonMaterial.js

@@ -0,0 +1,41 @@
+// @ts-check
+
+import Frozen from "../Core/Frozen.js";
+import BufferPrimitiveMaterial from "./BufferPrimitiveMaterial.js";
+
+/** @import Color from "../Core/Color.js"; */
+/** @import BufferPolygon from "./BufferPolygon.js"; */
+
+/**
+ * @typedef {object} BufferPolygonMaterialOptions
+ * @property {Color} [color=Color.WHITE] Color of fill.
+ * @property {Color} [outlineColor=Color.WHITE] Color of outline.
+ * @property {number} [outlineWidth=0.0] Width of outline, 0-255px.
+ */
+
+/**
+ * Material description for a {@link BufferPolygon}.
+ *
+ * <p>BufferPolygonMaterial objects are {@link Packable|packable}, stored
+ * when calling {@link BufferPolygon#setMaterial}. Subsequent changes to the
+ * material will not affect the polygon until setMaterial() is called again.</p>
+ *
+ * @experimental This feature is not final and is subject to change without Cesium's standard deprecation policy.
+ * @extends BufferPrimitiveMaterial
+ */
+class BufferPolygonMaterial extends BufferPrimitiveMaterial {
+  /**
+   * @type {BufferPolygonMaterial}
+   * @ignore
+   */
+  static DEFAULT_MATERIAL = Object.freeze(new BufferPolygonMaterial());
+
+  /**
+   * @param {BufferPolygonMaterialOptions} [options]
+   */
+  constructor(options = Frozen.EMPTY_OBJECT) {
+    super(options);
+  }
+}
+
+export default BufferPolygonMaterial;

package/Source/Scene/BufferPolyline.js

@@ -0,0 +1,185 @@
+// @ts-check
+
+import BufferPrimitive from "./BufferPrimitive.js";
+import assert from "../Core/assert.js";
+import BufferPrimitiveCollection from "./BufferPrimitiveCollection.js";
+import defined from "../Core/defined.js";
+
+/** @import { TypedArray, TypedArrayConstructor } from "../Core/globalTypes.js"; */
+/** @import BufferPolylineCollection from "./BufferPolylineCollection.js"; */
+
+const { ERR_RESIZE, ERR_CAPACITY } = BufferPrimitiveCollection.Error;
+
+/**
+ * View bound to the underlying buffer data of a {@link BufferPolylineCollection}.
+ *
+ * <p>BufferPolyline instances are {@link https://en.wikipedia.org/wiki/Flyweight_pattern|flyweights}:
+ * a single BufferPolyline instance can be temporarily bound to any conceptual
+ * "polyline" in a BufferPolylineCollection, allowing very large collections to be
+ * iterated and updated with a minimal memory footprint.</p>
+ *
+ * Represented as two (2) or more positions.
+ *
+ * @see BufferPolylineCollection
+ * @see BufferPolylineMaterial
+ * @see BufferPrimitive
+ * @extends BufferPrimitive
+ * @experimental This feature is not final and is subject to change without Cesium's standard deprecation policy.
+ */
+class BufferPolyline extends BufferPrimitive {
+  /**
+   * @type {BufferPolylineCollection}
+   * @ignore
+   */
+  _collection = null;
+
+  /** @ignore */
+  static Layout = {
+    ...BufferPrimitive.Layout,
+
+    /**
+     * Offset in position array to first vertex in polyline, number of VEC3 elements.
+     * @type {number}
+     * @ignore
+     */
+    POSITION_OFFSET_U32: BufferPrimitive.Layout.__BYTE_LENGTH,
+
+    /**
+     * Count of positions (vertices) in this polyline, number of VEC3 elements.
+     * @type {number}
+     * @ignore
+     */
+    POSITION_COUNT_U32: BufferPrimitive.Layout.__BYTE_LENGTH + 4,
+
+    /**
+     * @type {number}
+     * @ignore
+     */
+    __BYTE_LENGTH: BufferPrimitive.Layout.__BYTE_LENGTH + 8,
+  };
+
+  /////////////////////////////////////////////////////////////////////////////
+  // LIFECYCLE
+
+  /**
+   * Copies data from source polyline to result. If the result polyline is not
+   * new (the last polyline in the collection) then source and result polylines
+   * must have the same vertex counts.
+   *
+   * @param {BufferPolyline} polyline
+   * @param {BufferPolyline} result
+   * @return {BufferPolyline}
+   * @override
+   */
+  static clone(polyline, result) {
+    super.clone(polyline, result);
+    result.setPositions(polyline.getPositions());
+    return result;
+  }
+
+  /////////////////////////////////////////////////////////////////////////////
+  // GEOMETRY
+
+  /**
+   * Offset in collection position array to first vertex in polyline, number
+   * of VEC3 elements.
+   *
+   * @type {number}
+   * @readonly
+   * @ignore
+   */
+  get vertexOffset() {
+    return this._getUint32(BufferPolyline.Layout.POSITION_OFFSET_U32);
+  }
+
+  /**
+   * Count of positions (vertices) in this polyline, number of VEC3 elements.
+   *
+   * @type {number}
+   * @readonly
+   */
+  get vertexCount() {
+    return this._getUint32(BufferPolyline.Layout.POSITION_COUNT_U32);
+  }
+
+  /**
+   * Returns an array view of this polyline's vertex positions. If 'result'
+   * argument is given, vertex positions are written to that array and returned.
+   * Otherwise, returns an ArrayView on collection memory — changes to this array
+   * will not trigger render updates, which requires `.setPositions()`.
+   *
+   * @param {TypedArray} [result]
+   * return {TypedArray}
+   */
+  getPositions(result) {
+    const { vertexOffset, vertexCount } = this;
+    const positionView = this._collection._positionView;
+
+    if (!defined(result)) {
+      const byteOffset =
+        positionView.byteOffset +
+        vertexOffset * 3 * positionView.BYTES_PER_ELEMENT;
+      const TypedArray = /** @type {TypedArrayConstructor} */ (
+        positionView.constructor
+      );
+      return new TypedArray(
+        /** @type {ArrayBuffer} */ (positionView.buffer),
+        byteOffset,
+        vertexCount * 3,
+      );
+    }
+
+    for (let i = 0; i < vertexCount; i++) {
+      result[i * 3] = positionView[(vertexOffset + i) * 3];
+      result[i * 3 + 1] = positionView[(vertexOffset + i) * 3 + 1];
+      result[i * 3 + 2] = positionView[(vertexOffset + i) * 3 + 2];
+    }
+    return result;
+  }
+
+  /** @param {TypedArray} positions */
+  setPositions(positions) {
+    const collection = this._collection;
+    const vertexOffset = this.vertexOffset;
+    const srcCount = this.vertexCount;
+    const dstCount = positions.length / 3;
+    const collectionCount = collection._positionCount + dstCount - srcCount;
+
+    //>>includeStart('debug', pragmas.debug);
+    assert(srcCount === dstCount || this._isResizable(), ERR_RESIZE);
+    assert(collectionCount <= collection.vertexCountMax, ERR_CAPACITY);
+    //>>includeEnd('debug');
+
+    collection._positionCount = collectionCount;
+    this._setUint32(BufferPolyline.Layout.POSITION_COUNT_U32, dstCount);
+
+    const positionView = collection._positionView;
+    for (let i = 0; i < dstCount; i++) {
+      positionView[(vertexOffset + i) * 3] = positions[i * 3];
+      positionView[(vertexOffset + i) * 3 + 1] = positions[i * 3 + 1];
+      positionView[(vertexOffset + i) * 3 + 2] = positions[i * 3 + 2];
+    }
+
+    collection._makeDirtyBoundingVolume();
+  }
+
+  /////////////////////////////////////////////////////////////////////////////
+  // DEBUG
+
+  /**
+   * Returns a JSON-serializable object representing the polyline. 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(),
+      positions: Array.from(this.getPositions()),
+    };
+  }
+}
+
+export default BufferPolyline;