@cesium/engine 23.0.1 → 24.0.0

package/Source/Scene/BufferPoint.js

@@ -0,0 +1,148 @@
+// @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 BufferPointMaterial
+ * @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._positionView;
+    // @ts-expect-error TODO(tsd-jsdoc): See https://github.com/CesiumGS/cesium/pull/13302.
+    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._positionView[vertexOffset * 3] = position.x;
+    collection._positionView[vertexOffset * 3 + 1] = position.y;
+    collection._positionView[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;

package/Source/Scene/BufferPointCollection.js

@@ -0,0 +1,135 @@
+// @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 renderPoints from "./renderBufferPointCollection.js";
+import BufferPointMaterial from "./BufferPointMaterial.js";
+
+/** @import Matrix4 from "../Core/Matrix4.js"; */
+/** @import FrameState from "./FrameState.js"; */
+
+/**
+ * @typedef {object} BufferPointOptions
+ * @property {Matrix4} [options.modelMatrix=Matrix4.IDENTITY] Transforms geometry from model to world coordinates.
+ * @property {boolean} [show=true]
+ * @property {BufferPointMaterial} [material=BufferPointMaterial.DEFAULT_MATERIAL]
+ * @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();
+ * const material = new BufferPointMaterial({color: Color.WHITE});
+ *
+ * // Create a new point, temporarily bound to 'point' local variable.
+ * collection.add({
+ *   position: new Cartesian3(0.0, 0.0, 0.0),
+ *   material
+ * }, point);
+ *
+ * // Iterate over all points in collection, temporarily binding 'point'
+ * // local variable to each, and updating point material.
+ * for (let i = 0; i < collection.primitiveCount; i++) {
+ *   collection.get(i, point);
+ *   point.setMaterial(material);
+ * }
+ *
+ * @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;
+  }
+
+  _getMaterialClass() {
+    return BufferPointMaterial;
+  }
+
+  /////////////////////////////////////////////////////////////////////////////
+  // 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);
+
+    const passes = frameState.passes;
+    if (this.show && (passes.render || passes.pick)) {
+      this._renderContext = renderPoints(this, frameState, this._renderContext);
+    }
+  }
+}
+
+export default BufferPointCollection;

package/Source/Scene/BufferPointMaterial.js

@@ -0,0 +1,95 @@
+// @ts-check
+
+import Frozen from "../Core/Frozen.js";
+import BufferPrimitiveMaterial from "./BufferPrimitiveMaterial.js";
+
+/** @import Color from "../Core/Color.js"; */
+/** @import BufferPoint from "./BufferPoint.js"; */
+
+/**
+ * @typedef {object} BufferPointMaterialOptions
+ * @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} [size=1.0] Size of point, 0-255px.
+ */
+
+/**
+ * Material description for a {@link BufferPoint}.
+ *
+ * <p>BufferPointMaterial objects are {@link Packable|packable}, stored
+ * when calling {@link BufferPoint#setMaterial}. Subsequent changes to the
+ * material will not affect the point 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 BufferPointMaterial extends BufferPrimitiveMaterial {
+  /** @ignore */
+  static Layout = {
+    ...BufferPrimitiveMaterial.Layout,
+    SIZE_U8: BufferPrimitiveMaterial.Layout.__BYTE_LENGTH,
+    __BYTE_LENGTH: BufferPrimitiveMaterial.Layout.__BYTE_LENGTH + 4,
+  };
+
+  /**
+   * @type {BufferPointMaterial}
+   * @ignore
+   */
+  static DEFAULT_MATERIAL = Object.freeze(new BufferPointMaterial());
+
+  /**
+   * @param {BufferPointMaterialOptions} [options]
+   */
+  constructor(options = Frozen.EMPTY_OBJECT) {
+    super(options);
+
+    /**
+     * Size of point, 0-255px.
+     * @type {number}
+     */
+    this.size = options.size ?? 1;
+  }
+
+  /**
+   * @override
+   * @param {BufferPointMaterial} material
+   * @param {DataView} view
+   * @param {number} byteOffset
+   * @override
+   */
+  static pack(material, view, byteOffset) {
+    super.pack(material, view, byteOffset);
+    view.setUint8(this.Layout.SIZE_U8 + byteOffset, material.size);
+  }
+
+  /**
+   * @override
+   * @param {DataView} view
+   * @param {number} byteOffset
+   * @param {BufferPointMaterial} result
+   * @returns {BufferPointMaterial}
+   * @override
+   */
+  static unpack(view, byteOffset, result) {
+    super.unpack(view, byteOffset, result);
+    result.size = view.getUint8(this.Layout.SIZE_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(), size: this.size };
+  }
+}
+
+export default BufferPointMaterial;