BufferPrimitiveCollection: Material API

packages/engine/Source/Scene/BufferPointCollection.js

@@ -5,16 +5,16 @@ 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 Color from "../Core/Color.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 {Color} [color=Color.WHITE]
+ * @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.
  */
@@ -68,6 +68,10 @@ class BufferPointCollection extends BufferPrimitiveCollection {
     return BufferPoint;
   }
 
+  _getMaterialClass() {
+    return BufferPointMaterial;
+  }
+
   /////////////////////////////////////////////////////////////////////////////
   // COLLECTION LIFECYCLE
 

packages/engine/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} [pixelSize=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,
+    PIXEL_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.pixelSize = options.pixelSize ?? 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.PIXEL_SIZE_U8 + byteOffset, material.pixelSize);
+  }
+
+  /**
+   * @override
+   * @param {DataView} view
+   * @param {number} byteOffset
+   * @param {BufferPointMaterial} result
+   * @returns {BufferPointMaterial}
+   * @override
+   */
+  static unpack(view, byteOffset, result) {
+    super.unpack(view, byteOffset, result);
+    result.pixelSize = view.getUint8(this.Layout.PIXEL_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(), pixelSize: this.pixelSize };
+  }
+}
+
+export default BufferPointMaterial;

packages/engine/Source/Scene/BufferPolygonCollection.js

@@ -7,9 +7,9 @@ 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 Color from "../Core/Color.js"; */
 /** @import Matrix4 from "../Core/Matrix4.js"; */
 /** @import FrameState from "./FrameState.js" */
 /** @import ComponentDatatype from "../Core/ComponentDatatype.js"; */
@@ -20,7 +20,7 @@ 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 {Color} [color=Color.WHITE]
+ * @property {BufferPolygonMaterial} [material=BufferPolygonMaterial.DEFAULT_MATERIAL]
  * @property {TypedArray} [positions]
  * @property {TypedArray} [holes]
  * @property {TypedArray} [triangles]
@@ -134,6 +134,10 @@ class BufferPolygonCollection extends BufferPrimitiveCollection {
     return BufferPolygon;
   }
 
+  _getMaterialClass() {
+    return BufferPolygonMaterial;
+  }
+
   /////////////////////////////////////////////////////////////////////////////
   // COLLECTION LIFECYCLE
 

packages/engine/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;

packages/engine/Source/Scene/BufferPolyline.js

@@ -51,17 +51,10 @@ class BufferPolyline extends BufferPrimitive {
     POSITION_COUNT_U32: BufferPrimitive.Layout.__BYTE_LENGTH + 4,
 
     /**
-     * Width of polyline, 0–255px.
      * @type {number}
      * @ignore
      */
-    WIDTH_U8: BufferPrimitive.Layout.__BYTE_LENGTH + 8,
-
-    /**
-     * @type {number}
-     * @ignore
-     */
-    __BYTE_LENGTH: BufferPrimitive.Layout.__BYTE_LENGTH + 12,
+    __BYTE_LENGTH: BufferPrimitive.Layout.__BYTE_LENGTH + 8,
   };
 
   /////////////////////////////////////////////////////////////////////////////
@@ -80,7 +73,6 @@ class BufferPolyline extends BufferPrimitive {
   static clone(polyline, result) {
     super.clone(polyline, result);
     result.setPositions(polyline.getPositions());
-    result.width = polyline.width;
     return result;
   }
 
@@ -170,21 +162,6 @@ class BufferPolyline extends BufferPrimitive {
     collection._makeDirtyBoundingVolume();
   }
 
-  /////////////////////////////////////////////////////////////////////////////
-  // ACCESSORS
-
-  /**
-   * Width of polyline, 0–255px.
-   * @type {number}
-   */
-  get width() {
-    return this._getUint8(BufferPolyline.Layout.WIDTH_U8);
-  }
-
-  set width(width) {
-    this._setUint8(BufferPolyline.Layout.WIDTH_U8, width);
-  }
-
   /////////////////////////////////////////////////////////////////////////////
   // DEBUG
 
@@ -200,7 +177,6 @@ class BufferPolyline extends BufferPrimitive {
     return {
       ...super.toJSON(),
       positions: Array.from(this.getPositions()),
-      width: this.width,
     };
   }
 }

packages/engine/Source/Scene/BufferPolylineCollection.js

@@ -4,17 +4,17 @@ 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 Color from "../Core/Color.js"; */
 /** @import Matrix4 from "../Core/Matrix4.js"; */
 /** @import FrameState from "./FrameState.js" */
 
 /**
  * @typedef {object} BufferPolylineOptions
  * @property {Matrix4} [options.modelMatrix=Matrix4.IDENTITY] Transforms geometry from model to world coordinates.
  * @property {boolean} [show=true]
- * @property {Color} [color=Color.WHITE]
+ * @property {BufferPolylineMaterial} [material=BufferPolylineMaterial.DEFAULT_MATERIAL]
  * @property {TypedArray} [positions]
  * @property {number} [width=1]
  * @experimental This feature is not final and is subject to change without Cesium's standard deprecation policy.
@@ -62,6 +62,10 @@ class BufferPolylineCollection extends BufferPrimitiveCollection {
     return BufferPolyline;
   }
 
+  _getMaterialClass() {
+    return BufferPolylineMaterial;
+  }
+
   /////////////////////////////////////////////////////////////////////////////
   // COLLECTION LIFECYCLE
 
@@ -100,8 +104,6 @@ class BufferPolylineCollection extends BufferPrimitiveCollection {
     result._setUint32(BufferPolyline.Layout.POSITION_OFFSET_U32, vertexOffset);
     result._setUint32(BufferPolyline.Layout.POSITION_COUNT_U32, 0);
 
-    result.width = options.width ?? 1;
-
     if (defined(options.positions)) {
       result.setPositions(options.positions);
     }

packages/engine/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;