@cesium/engine 23.0.1 → 25.0.0

package/Source/Scene/BufferPolylineCollection.js

@@ -0,0 +1,138 @@
+// @ts-check
+
+import defined from "../Core/defined.js";
+import BufferPrimitiveCollection from "./BufferPrimitiveCollection.js";
+import BufferPolyline from "./BufferPolyline.js";
+import renderPolylines from "./renderBufferPolylineCollection.js";
+import BufferPolylineMaterial from "./BufferPolylineMaterial.js";
+
+/** @import { TypedArray } from "../Core/globalTypes.js"; */
+/** @import Matrix4 from "../Core/Matrix4.js"; */
+/** @import FrameState from "./FrameState.js" */
+
+/**
+ * @typedef {object} BufferPolylineOptions
+ * @property {Matrix4} [modelMatrix=Matrix4.IDENTITY] Transforms geometry from model to world coordinates.
+ * @property {boolean} [show=true]
+ * @property {BufferPolylineMaterial} [material=BufferPolylineMaterial.DEFAULT_MATERIAL]
+ * @property {number} [featureId]
+ * @property {object} [pickObject]
+ * @property {TypedArray} [positions]
+ * @experimental This feature is not final and is subject to change without Cesium's standard deprecation policy.
+ */
+
+/**
+ * Collection of polylines 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 BufferPolylineCollection({
+ *   primitiveCountMax: 1024,
+ *   vertexCountMax: 4096,
+ * });
+ *
+ * const polyline = new BufferPolyline();
+ * const material = new BufferPolylineMaterial({color: Color.WHITE});
+ *
+ * // Create a new polyline, temporarily bound to 'polyline' local variable.
+ * collection.add({
+ *   positions: new Float64Array([ ... ]),
+ *   material,
+ * }, polyline);
+ *
+ * // Iterate over all polylines in collection, temporarily binding 'polyline'
+ * // local variable to each, and updating polyline material.
+ * for (let i = 0; i < collection.primitiveCount; i++) {
+ *   collection.get(i, polyline);
+ *   polyline.setMaterial(material);
+ * }
+ *
+ * @see BufferPolyline
+ * @see BufferPolylineMaterial
+ * @see BufferPrimitiveCollection
+ * @extends BufferPrimitiveCollection<BufferPolyline>
+ * @experimental This feature is not final and is subject to change without Cesium's standard deprecation policy.
+ */
+class BufferPolylineCollection extends BufferPrimitiveCollection {
+  _getCollectionClass() {
+    return BufferPolylineCollection;
+  }
+
+  _getPrimitiveClass() {
+    return BufferPolyline;
+  }
+
+  _getMaterialClass() {
+    return BufferPolylineMaterial;
+  }
+
+  /////////////////////////////////////////////////////////////////////////////
+  // COLLECTION LIFECYCLE
+
+  /**
+   * @param {BufferPolylineCollection} collection
+   * @returns {BufferPolylineCollection}
+   * @override
+   * @ignore
+   */
+  static _cloneEmpty(collection) {
+    return new BufferPolylineCollection({
+      primitiveCountMax: collection.primitiveCountMax,
+      vertexCountMax: collection.vertexCountMax,
+    });
+  }
+
+  /////////////////////////////////////////////////////////////////////////////
+  // PRIMITIVE LIFECYCLE
+
+  /**
+   * Adds a new polyline to the collection, with the specified options. A
+   * {@link BufferPolyline} instance is linked to the new polyline, using
+   * the 'result' argument if given, or a new instance if not. For repeated
+   * calls, prefer to reuse a single BufferPolyline instance rather than
+   * allocating a new instance on each call.
+   *
+   * @param {BufferPolylineOptions} options
+   * @param {BufferPolyline} result
+   * @returns {BufferPolyline}
+   * @override
+   */
+  add(options, result = new BufferPolyline()) {
+    super.add(options, result);
+
+    const vertexOffset = this._positionCount;
+    result._setUint32(BufferPolyline.Layout.POSITION_OFFSET_U32, vertexOffset);
+    result._setUint32(BufferPolyline.Layout.POSITION_COUNT_U32, 0);
+
+    if (defined(options.positions)) {
+      result.setPositions(options.positions);
+    }
+
+    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 = renderPolylines(
+        this,
+        frameState,
+        this._renderContext,
+      );
+    }
+  }
+}
+
+export default BufferPolylineCollection;

package/Source/Scene/BufferPolylineMaterial.js

@@ -0,0 +1,93 @@
+// @ts-check
+
+import Frozen from "../Core/Frozen.js";
+import BufferPrimitiveMaterial from "./BufferPrimitiveMaterial.js";
+
+/** @import Color from "../Core/Color.js"; */
+/** @import BufferPolyline from "./BufferPolyline.js"; */
+
+/**
+ * @typedef {object} BufferPolylineMaterialOptions
+ * @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.
+ * @property {number} [width=1.0] Width of line, 0-255px.
+ */
+
+/**
+ * Material description for a {@link BufferPolyline}.
+ *
+ * <p>BufferPolylineMaterial objects are {@link Packable|packable}, stored
+ * when calling {@link BufferPolyline#setMaterial}. Subsequent changes to the
+ * material will not affect the polyline 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 BufferPolylineMaterial extends BufferPrimitiveMaterial {
+  /** @ignore */
+  static Layout = {
+    ...BufferPrimitiveMaterial.Layout,
+    WIDTH_U8: BufferPrimitiveMaterial.Layout.__BYTE_LENGTH,
+    __BYTE_LENGTH: BufferPrimitiveMaterial.Layout.__BYTE_LENGTH + 4,
+  };
+
+  /**
+   * @type {BufferPolylineMaterial}
+   * @ignore
+   */
+  static DEFAULT_MATERIAL = Object.freeze(new BufferPolylineMaterial());
+
+  /**
+   * @param {BufferPolylineMaterialOptions} [options]
+   */
+  constructor(options = Frozen.EMPTY_OBJECT) {
+    super(options);
+
+    /**
+     * Width of polyline, 0–255px.
+     * @type {number}
+     */
+    this.width = options.width ?? 1;
+  }
+
+  /**
+   * @param {BufferPolylineMaterial} material
+   * @param {DataView} view
+   * @param {number} byteOffset
+   * @override
+   */
+  static pack(material, view, byteOffset) {
+    super.pack(material, view, byteOffset);
+    view.setUint8(this.Layout.WIDTH_U8 + byteOffset, material.width);
+  }
+
+  /**
+   * @param {DataView} view
+   * @param {number} byteOffset
+   * @param {BufferPolylineMaterial} result
+   * @returns {BufferPolylineMaterial}
+   * @override
+   */
+  static unpack(view, byteOffset, result) {
+    super.unpack(view, byteOffset, result);
+    result.width = view.getUint8(this.Layout.WIDTH_U8 + byteOffset);
+    return result;
+  }
+
+  /////////////////////////////////////////////////////////////////////////////
+  // DEBUG
+
+  /**
+   * Returns a JSON-serializable object representing the material. This encoding
+   * is not memory-efficient, and should generally be used for debugging and
+   * testing.
+   *
+   * @returns {Object} JSON-serializable object.
+   */
+  toJSON() {
+    return { ...super.toJSON(), width: this.width };
+  }
+}
+
+export default BufferPolylineMaterial;

package/Source/Scene/BufferPrimitive.js

@@ -0,0 +1,347 @@
+// @ts-check
+
+import assert from "../Core/assert.js";
+
+/** @import BufferPrimitiveCollection from './BufferPrimitiveCollection.js'; */
+/** @import BufferPrimitiveMaterial from "./BufferPrimitiveMaterial.js"; */
+
+/**
+ * View bound to the underlying buffer data of a {@link BufferPrimitiveCollection}. Abstract.
+ *
+ * <p>BufferPrimitive instances are intended to be reused when iterating over large collections,
+ * and temporarily bound to a primitive index while performing read/write operations on that primitive,
+ * before being rebound to the next primitive, using the
+ * {@link https://en.wikipedia.org/wiki/Flyweight_pattern|flyweight pattern}.</p>
+ *
+ * @see BufferPrimitiveCollection
+ * @see BufferPrimitiveMaterial
+ * @see BufferPoint
+ * @see BufferPolyline
+ * @see BufferPolygon
+ *
+ * @abstract
+ * @experimental This feature is not final and is subject to change without Cesium's standard deprecation policy.
+ */
+class BufferPrimitive {
+  /**
+   * Collecton containing the primitive(s) for which this instance currently
+   * provides a view.
+   *
+   * @type {BufferPrimitiveCollection<BufferPrimitive>}
+   * @ignore
+   */
+  _collection = null;
+
+  /**
+   * Index of the primitive for which this instance currently provides a view.
+   *
+   * @type {number}
+   * @ignore
+   */
+  _index = -1;
+
+  /**
+   * Byte offset, into the collection's primitive buffer, of the primitive for
+   * which this instance currently provides a view.
+   *
+   * @type {number}
+   * @ignore
+   */
+  _byteOffset = -1;
+
+  /**
+   * Binary layout for this primitive type in collection's primitive buffer.
+   * Each `Layout.MY_KEY_U32` entry is an offset in bytes, relative to the
+   * start offset of the primitive, with the suffix indicating the data type
+   * stored at that offset.
+   *
+   * The final entry, `__BYTE_LENGTH`, is not a pointer into a buffer — its
+   * literal value is the total byte length of one primitive in the primitive
+   * buffer, exclusive of other buffers.
+   *
+   * @ignore
+   */
+  static Layout = {
+    /**
+     * Feature ID associated with the primitive; not required to be unique.
+     * @type {number}
+     * @ignore
+     */
+    FEATURE_ID_U32: 0,
+
+    /**
+     * Boolean (0 or 1) flag indicating whether primitive is shown.
+     * @type {number}
+     * @ignore
+     */
+    SHOW_U8: 4,
+
+    /**
+     * Boolean (0 or 1) flag indicating whether primitive is dirty.
+     * @type {number}
+     * @ignore
+     */
+    DIRTY_U8: 5,
+
+    /**
+     * Pick ID (uint32) of primitive.
+     * @type {number}
+     * @ignore
+     */
+    PICK_ID_U32: 8,
+
+    /**
+     * Byte length of one primitive in the primitive buffer, exclusive of
+     * other buffers. Literal value, not a pointer.
+     * @type {number}
+     * @ignore
+     */
+    __BYTE_LENGTH: 12,
+  };
+
+  /////////////////////////////////////////////////////////////////////////////
+  // LIFECYCLE
+
+  /**
+   * Copies data from source primitive to result. If the result primitive is not
+   * new (the last primitive in the collection) then source and result primitives
+   * must have the same vertex counts.
+   *
+   * @param {BufferPrimitive} primitive
+   * @param {BufferPrimitive} result
+   * @returns {BufferPrimitive}
+   */
+  static clone(primitive, result) {
+    const SrcMaterialClass = primitive._collection._getMaterialClass();
+
+    //>>includeStart('debug', pragmas.debug);
+    const DstMaterialClass = result._collection._getMaterialClass();
+    assert(SrcMaterialClass === DstMaterialClass, "Incompatible materials");
+    //>>includeEnd('debug');
+
+    result.featureId = primitive.featureId;
+    result.show = primitive.show;
+    result.setMaterial(primitive.getMaterial(new SrcMaterialClass()));
+    return result;
+  }
+
+  /**
+   * Returns true if this primitive's memory footprint is resizable. Only the
+   * newest (most recently created) primitive in a collection can be resized,
+   * to guarantee fast and stable performance.
+   *
+   * @returns {boolean}
+   * @protected
+   * @ignore
+   */
+  _isResizable() {
+    return this._index === this._collection.primitiveCount - 1;
+  }
+
+  /////////////////////////////////////////////////////////////////////////////
+  // ACCESSORS
+
+  /**
+   * Feature ID associated with the primitive; not required to be unique.
+   * @type {number}
+   */
+  get featureId() {
+    return this._getUint32(BufferPrimitive.Layout.FEATURE_ID_U32);
+  }
+
+  set featureId(featureId) {
+    this._setUint32(BufferPrimitive.Layout.FEATURE_ID_U32, featureId);
+  }
+
+  /**
+   * Whether primitive is shown.
+   * @type {boolean}
+   */
+  get show() {
+    return this._getUint8(BufferPrimitive.Layout.SHOW_U8) === 1;
+  }
+
+  set show(show) {
+    this._setUint8(BufferPrimitive.Layout.SHOW_U8, show ? 1 : 0);
+  }
+
+  /**
+   * @param {BufferPrimitiveMaterial} result
+   * @returns {BufferPrimitiveMaterial}
+   */
+  getMaterial(result) {
+    const collection = this._collection;
+    const MaterialClass = collection._getMaterialClass();
+
+    return MaterialClass.unpack(
+      collection._materialView,
+      this._index * MaterialClass.packedLength,
+      result,
+    );
+  }
+
+  /**
+   * @param {BufferPrimitiveMaterial} material
+   */
+  setMaterial(material) {
+    const collection = this._collection;
+    const MaterialClass = collection._getMaterialClass();
+
+    MaterialClass.pack(
+      material,
+      collection._materialView,
+      this._index * MaterialClass.packedLength,
+    );
+
+    this._dirty = true;
+
+    return material;
+  }
+
+  /**
+   * Whether the primitive requires an update on next render. Renderers should
+   * _not_ iterate over all primitives each frame, but must instead inspect
+   * only the dirty range of the parent collection. This flag is managed
+   * automatically, by primitive setters and collection renderers.
+   *
+   * @type {boolean}
+   * @ignore
+   *
+   * @see BufferPrimitiveCollection#_dirtyOffset
+   * @see BufferPrimitiveCollection#_dirtyCount
+   */
+  get _dirty() {
+    return this._getUint8(BufferPrimitive.Layout.DIRTY_U8) === 1;
+  }
+
+  set _dirty(dirty) {
+    // Avoid `._setUint8()` here, which would infinitely loop `._dirty = true`.
+    this._collection._primitiveView.setUint8(
+      this._byteOffset + BufferPrimitive.Layout.DIRTY_U8,
+      dirty ? 1 : 0,
+    );
+
+    // A 'dirty' primitive is responsible for notifying the collection. Applying
+    // updates and marking the primitive 'clean' will be handled by the collection,
+    // so we don't notify the collection here in that case.
+    if (dirty) {
+      this._collection._makeDirty(this._index);
+    }
+  }
+
+  /**
+   * Pick ID (uint32) of primitive.
+   * @type {number}
+   * @ignore
+   */
+  get _pickId() {
+    return this._getUint32(BufferPrimitive.Layout.PICK_ID_U32);
+  }
+
+  set _pickId(pickId) {
+    this._setUint32(BufferPrimitive.Layout.PICK_ID_U32, pickId);
+  }
+
+  /////////////////////////////////////////////////////////////////////////////
+  // BUFFER ACCESSORS
+
+  /**
+   * @param {number} itemByteOffset
+   * @returns {number}
+   * @ignore
+   */
+  _getUint8(itemByteOffset) {
+    return this._collection._primitiveView.getUint8(
+      this._byteOffset + itemByteOffset,
+    );
+  }
+
+  /**
+   * @param {number} itemByteOffset
+   * @param {number} itemValue
+   * @ignore
+   */
+  _setUint8(itemByteOffset, itemValue) {
+    this._collection._primitiveView.setUint8(
+      this._byteOffset + itemByteOffset,
+      itemValue,
+    );
+    this._dirty = true;
+  }
+
+  /**
+   * @param {number} itemByteOffset
+   * @returns {number}
+   * @ignore
+   */
+  _getUint32(itemByteOffset) {
+    return this._collection._primitiveView.getUint32(
+      this._byteOffset + itemByteOffset,
+      true,
+    );
+  }
+
+  /**
+   * @param {number} itemByteOffset
+   * @param {number} itemValue
+   * @ignore
+   */
+  _setUint32(itemByteOffset, itemValue) {
+    this._collection._primitiveView.setUint32(
+      this._byteOffset + itemByteOffset,
+      itemValue,
+      true,
+    );
+    this._dirty = true;
+  }
+
+  /**
+   * @param {number} itemByteOffset
+   * @returns {number}
+   * @ignore
+   */
+  _getFloat32(itemByteOffset) {
+    return this._collection._primitiveView.getFloat32(
+      this._byteOffset + itemByteOffset,
+      true,
+    );
+  }
+
+  /**
+   * @param {number} itemByteOffset
+   * @param {number} itemValue
+   * @ignore
+   */
+  _setFloat32(itemByteOffset, itemValue) {
+    this._collection._primitiveView.setFloat32(
+      this._byteOffset + itemByteOffset,
+      itemValue,
+      true,
+    );
+    this._dirty = true;
+  }
+
+  /////////////////////////////////////////////////////////////////////////////
+  // DEBUG
+
+  /**
+   * Returns a JSON-serializable object representing the primitive. This encoding
+   * is not memory-efficient, and should generally be used for debugging and
+   * testing.
+   *
+   * @returns {Object} JSON-serializable object.
+   */
+  toJSON() {
+    const collection = this._collection;
+    const MaterialClass = collection._getMaterialClass();
+
+    return {
+      featureId: this.featureId,
+      show: this.show,
+      dirty: this._dirty,
+      material: this.getMaterial(new MaterialClass()).toJSON(),
+    };
+  }
+}
+
+export default BufferPrimitive;