@cesium/engine 23.0.0 → 24.0.0

package/Source/Scene/parseStructuralMetadata.js

@@ -149,9 +149,9 @@ function createTextureForPropertyTable(
 
   const numFeatures = propertyTable.count;
 
-  let gpuCompatiblePropertyBufferViews;
+  let gpuCompatiblePropertyInfo;
   try {
-    gpuCompatiblePropertyBufferViews = collectGpuCompatiblePropertyBufferViews(
+    gpuCompatiblePropertyInfo = collectGpuCompatiblePropertyInfo(
       properties,
       bufferViews,
       classDefinition,
@@ -164,7 +164,7 @@ function createTextureForPropertyTable(
     return undefined;
   }
 
-  const numGpuCompatibleProperties = gpuCompatiblePropertyBufferViews.length;
+  const numGpuCompatibleProperties = gpuCompatiblePropertyInfo.length;
 
   if (numGpuCompatibleProperties === 0) {
     return undefined;
@@ -183,7 +183,7 @@ function createTextureForPropertyTable(
   }
 
   const packedBufferView = packPropertyTablePropertiesIntoRGBA8(
-    gpuCompatiblePropertyBufferViews,
+    gpuCompatiblePropertyInfo,
     numFeatures,
   );
 
@@ -209,13 +209,13 @@ function createTextureForPropertyTable(
   });
 }
 
-function collectGpuCompatiblePropertyBufferViews(
+function collectGpuCompatiblePropertyInfo(
   properties,
   bufferViews,
   classDefinition,
   numFeatures,
 ) {
-  const bufferViewsForThisTable = [];
+  const propertyInfos = [];
   const classProperties = classDefinition.properties;
 
   // It's possible for a primitive in a tileset to only use a subset of the class properties defined in the schema.
@@ -234,7 +234,7 @@ function collectGpuCompatiblePropertyBufferViews(
       : createNoDataBufferView(classProperty, numFeatures);
 
     const bufferViewLength = bufferView.length;
-    const bytesPerElement = classProperty.bytesPerElement();
+    const bytesPerElement = classProperty.cpuBytesPerElement();
     const numBufferElements = bufferViewLength / bytesPerElement;
     if (numBufferElements !== numFeatures) {
       throw new RuntimeError(
@@ -242,13 +242,13 @@ function collectGpuCompatiblePropertyBufferViews(
       );
     }
 
-    bufferViewsForThisTable.push({
+    propertyInfos.push({
       view: bufferView,
-      bytesPerElement: bytesPerElement,
+      classProperty: classProperty,
     });
   }
 
-  return bufferViewsForThisTable;
+  return propertyInfos;
 }
 
 /**
@@ -287,18 +287,25 @@ function createNoDataBufferView(classProperty, numFeatures) {
     noData = [noData];
   }
 
-  const bytesPerElement = classProperty.bytesPerElement();
+  const bytesPerElement = classProperty.cpuBytesPerElement();
+  const bytesPerComponent = MetadataComponentType.getSizeInBytes(
+    classProperty.valueType,
+  );
   const buffer = new ArrayBuffer(bytesPerElement * numFeatures);
   const view = new DataView(buffer);
-  const setter = MetadataComponentType.getDataViewSetter(
+  const accessors = MetadataComponentType.getDataViewAccessors(
     view,
-    classProperty.componentType,
+    classProperty.valueType,
   );
 
   for (let i = 0; i < numFeatures; i++) {
     for (let j = 0; j < metadataArrayLength; j++) {
       for (let k = 0; k < metadataComponentCount; k++) {
-        setter(bytesPerElement * i + j + k, noData[j][k]);
+        const componentIdx = j * metadataComponentCount + k;
+        accessors.set(
+          bytesPerElement * i + componentIdx * bytesPerComponent,
+          noData[j][k],
+        );
       }
     }
   }
@@ -308,39 +315,92 @@ function createNoDataBufferView(classProperty, numFeatures) {
 
 // Make one big buffer view to load into the texture
 // Since each texel is always 4 bytes (RGBA8 format), elements less than 4 bytes need to be padded (respecting little-endian order).
-function packPropertyTablePropertiesIntoRGBA8(
-  bufferViewsForThisTable,
-  numFeatures,
-) {
-  const numGpuCompatibleProperties = bufferViewsForThisTable.length;
+// Exception: single-component 64-bit types can be downcast to 32-bit for GPU compatibility (with potential loss of precision / range).
+function packPropertyTablePropertiesIntoRGBA8(propertyInfos, numFeatures) {
+  const numGpuCompatibleProperties = propertyInfos.length;
   const packedBufferView = new Uint8Array(
     numGpuCompatibleProperties * numFeatures * NUM_CHANNELS,
   );
+  const packedDataView = new DataView(
+    packedBufferView.buffer,
+    packedBufferView.byteOffset,
+    packedBufferView.byteLength,
+  );
 
-  for (let i = 0, offset = 0; i < bufferViewsForThisTable.length; i++) {
-    const bufferView = bufferViewsForThisTable[i].view;
-    const bytesPerElement = bufferViewsForThisTable[i].bytesPerElement;
-    const numElements = bufferView.length / bytesPerElement;
+  for (
+    let propertyIndex = 0;
+    propertyIndex < numGpuCompatibleProperties;
+    propertyIndex++
+  ) {
+    const propertyInfo = propertyInfos[propertyIndex];
+    const classProperty = propertyInfo.classProperty;
+    const rowOffset = propertyIndex * numFeatures * NUM_CHANNELS;
+    const sourceType = classProperty.valueType;
+    const packedType = MetadataComponentType.gpuComponentType(sourceType);
+
+    // E.g. When the source component type is INT64, we first downcast each element to INT32 before packing into the GPU buffer.
+    if (sourceType !== packedType) {
+      downcastAndPackProperty(propertyInfo, packedDataView, rowOffset);
+      continue;
+    }
 
-    for (let j = 0; j < numElements; j++) {
-      const sourceOffset = j * bytesPerElement;
-      const destOffset = offset + j * NUM_CHANNELS;
+    packProperty(propertyInfo, packedBufferView, rowOffset);
+  }
 
-      packedBufferView.set(
-        bufferView.subarray(sourceOffset, sourceOffset + bytesPerElement),
-        destOffset,
-      );
+  return packedBufferView;
+}
 
-      // Pad remaining channels with 0
-      for (let k = bytesPerElement; k < NUM_CHANNELS; k++) {
-        packedBufferView[destOffset + k] = 0;
-      }
-    }
+function packProperty(propertyInfo, packedBufferView, rowOffset) {
+  const bufferView = propertyInfo.view;
+  const bytesPerElement = propertyInfo.classProperty.cpuBytesPerElement();
+  const numElements = bufferView.length / bytesPerElement;
+
+  for (let elementIndex = 0; elementIndex < numElements; elementIndex++) {
+    const sourceOffset = elementIndex * bytesPerElement;
+    const destinationOffset = rowOffset + elementIndex * NUM_CHANNELS;
 
-    offset += numElements * NUM_CHANNELS;
+    packedBufferView.set(
+      bufferView.subarray(sourceOffset, sourceOffset + bytesPerElement),
+      destinationOffset,
+    );
   }
+}
 
-  return packedBufferView;
+// This is the slow path - rather than doing a straight copy, we need to interpret and downcast each element before packing it into the GPU buffer.
+// Note: this function does not handle properties with multiple components per element (or arrays). While not complete, this is OK because
+// multi-component properties with 64-bit types - even when downcast to 32 bits - cannot fit into a single RGBA8 texel.
+function downcastAndPackProperty(propertyInfo, packedDataView, rowOffset) {
+  const classProperty = propertyInfo.classProperty;
+  const bufferView = propertyInfo.view;
+  const sourceType = classProperty.valueType;
+  const packedType = MetadataComponentType.gpuComponentType(sourceType);
+
+  const bytesPerElement = classProperty.cpuBytesPerElement();
+  const numElements = bufferView.length / bytesPerElement;
+
+  const sourceDataView = new DataView(
+    bufferView.buffer,
+    bufferView.byteOffset,
+    bufferView.byteLength,
+  );
+  const sourceAccessors = MetadataComponentType.getDataViewAccessors(
+    sourceDataView,
+    sourceType,
+  );
+  const packedAccessors = MetadataComponentType.getDataViewAccessors(
+    packedDataView,
+    packedType,
+  );
+
+  const downcastFunction = MetadataComponentType.downcastFunction(sourceType);
+
+  for (let elementIndex = 0; elementIndex < numElements; elementIndex++) {
+    const sourceElementOffset = elementIndex * bytesPerElement;
+    const destinationElementOffset = rowOffset + elementIndex * NUM_CHANNELS;
+
+    const value = sourceAccessors.get(sourceElementOffset);
+    packedAccessors.set(destinationElementOffset, downcastFunction(value));
+  }
 }
 
 export default parseStructuralMetadata;

package/Source/Scene/renderBufferPointCollection.js

@@ -0,0 +1,334 @@
+// @ts-check
+
+import defined from "../Core/defined.js";
+import Cartesian3 from "../Core/Cartesian3.js";
+import Color from "../Core/Color.js";
+import BufferPoint from "./BufferPoint.js";
+import Buffer from "../Renderer/Buffer.js";
+import BufferUsage from "../Renderer/BufferUsage.js";
+import VertexArray from "../Renderer/VertexArray.js";
+import ComponentDatatype from "../Core/ComponentDatatype.js";
+import RenderState from "../Renderer/RenderState.js";
+import BlendingState from "./BlendingState.js";
+import ShaderSource from "../Renderer/ShaderSource.js";
+import ShaderProgram from "../Renderer/ShaderProgram.js";
+import DrawCommand from "../Renderer/DrawCommand.js";
+import Pass from "../Renderer/Pass.js";
+import PrimitiveType from "../Core/PrimitiveType.js";
+import BufferPointMaterialVS from "../Shaders/BufferPointMaterialVS.js";
+import BufferPointMaterialFS from "../Shaders/BufferPointMaterialFS.js";
+import EncodedCartesian3 from "../Core/EncodedCartesian3.js";
+import AttributeCompression from "../Core/AttributeCompression.js";
+import Matrix4 from "../Core/Matrix4.js";
+import BoundingSphere from "../Core/BoundingSphere.js";
+import BufferPointMaterial from "./BufferPointMaterial.js";
+
+/** @import FrameState from "./FrameState.js"; */
+/** @import BufferPointCollection from "./BufferPointCollection.js"; */
+/** @import {Destroyable, TypedArray} from "../Core/globalTypes.js"; */
+
+/**
+ * TODO(PR#13211): Need 'keyof' syntax to avoid duplicating attribute names.
+ * @typedef {'positionHigh' | 'positionLow' | 'pickColor' | 'showSizeAndColor' | 'outlineWidthAndOutlineColor'} BufferPointAttribute
+ * @ignore
+ */
+
+/**
+ * @type {Record<BufferPointAttribute, number>}
+ * @ignore
+ */
+const BufferPointAttributeLocations = {
+  positionHigh: 0,
+  positionLow: 1,
+  pickColor: 2,
+  showSizeAndColor: 3,
+  outlineWidthAndOutlineColor: 4,
+};
+
+/**
+ * @typedef {object} BufferPointRenderContext
+ * @property {VertexArray} [vertexArray]
+ * @property {Record<BufferPointAttribute, TypedArray>} [attributeArrays]
+ * @property {RenderState} [renderState]
+ * @property {ShaderProgram} [shaderProgram]
+ * @property {DrawCommand} [command]
+ * @property {Destroyable[]} [pickIds] Unordered list of collection PickIds.
+ * @property {Function} destroy
+ * @ignore
+ */
+
+// Scratch variables.
+const point = new BufferPoint();
+const material = new BufferPointMaterial();
+const pickColor = new Color();
+const cartesian = new Cartesian3();
+const encodedCartesian = new EncodedCartesian3();
+
+/**
+ * @param {BufferPointCollection} collection
+ * @param {FrameState} frameState
+ * @param {BufferPointRenderContext} [renderContext]
+ * @returns {BufferPointRenderContext}
+ * @ignore
+ */
+function renderBufferPointCollection(collection, frameState, renderContext) {
+  const context = frameState.context;
+  renderContext = renderContext || { destroy: destroyRenderContext };
+
+  if (!defined(renderContext.attributeArrays)) {
+    const featureCountMax = collection.primitiveCountMax;
+
+    renderContext.attributeArrays = {
+      positionHigh: new Float32Array(featureCountMax * 3),
+      positionLow: new Float32Array(featureCountMax * 3),
+      pickColor: new Uint8Array(featureCountMax * 4),
+      showSizeAndColor: new Float32Array(featureCountMax * 3),
+      outlineWidthAndOutlineColor: new Float32Array(featureCountMax * 2),
+    };
+  }
+
+  if (!defined(renderContext.pickIds)) {
+    renderContext.pickIds = [];
+  }
+
+  if (collection._dirtyCount > 0) {
+    const { attributeArrays, pickIds } = renderContext;
+
+    const positionHighArray = attributeArrays.positionHigh;
+    const positionLowArray = attributeArrays.positionLow;
+    const pickColorArray = attributeArrays.pickColor;
+    const showSizeAndColorArray = attributeArrays.showSizeAndColor;
+    const outlineWidthAndOutlineColorArray =
+      attributeArrays.outlineWidthAndOutlineColor;
+
+    const { _dirtyOffset, _dirtyCount } = collection;
+
+    for (let i = _dirtyOffset, il = _dirtyOffset + _dirtyCount; i < il; i++) {
+      collection.get(i, point);
+
+      if (!point._dirty) {
+        continue;
+      }
+
+      if (collection._allowPicking && point._pickId === 0) {
+        const pickId = context.createPickId({
+          collection,
+          index: i,
+          get primitive() {
+            // Cannot reuse primitives; scene.drillPick() appends to a list.
+            return collection.get(this.index, new BufferPoint());
+          },
+        });
+        point._pickId = pickId.key;
+        pickIds.push(pickId);
+      }
+
+      point.getPosition(cartesian);
+      EncodedCartesian3.fromCartesian(cartesian, encodedCartesian);
+      point.getMaterial(material);
+      Color.fromRgba(point._pickId, pickColor);
+
+      positionHighArray[i * 3] = encodedCartesian.high.x;
+      positionHighArray[i * 3 + 1] = encodedCartesian.high.y;
+      positionHighArray[i * 3 + 2] = encodedCartesian.high.z;
+
+      positionLowArray[i * 3] = encodedCartesian.low.x;
+      positionLowArray[i * 3 + 1] = encodedCartesian.low.y;
+      positionLowArray[i * 3 + 2] = encodedCartesian.low.z;
+
+      pickColorArray[i * 4] = Color.floatToByte(pickColor.red);
+      pickColorArray[i * 4 + 1] = Color.floatToByte(pickColor.green);
+      pickColorArray[i * 4 + 2] = Color.floatToByte(pickColor.blue);
+      pickColorArray[i * 4 + 3] = Color.floatToByte(pickColor.alpha);
+
+      showSizeAndColorArray[i * 3] = point.show ? 1 : 0;
+      showSizeAndColorArray[i * 3 + 1] = material.size;
+      showSizeAndColorArray[i * 3 + 2] = AttributeCompression.encodeRGB8(
+        material.color,
+      );
+
+      outlineWidthAndOutlineColorArray[i * 2] = material.outlineWidth;
+      outlineWidthAndOutlineColorArray[i * 2 + 1] =
+        AttributeCompression.encodeRGB8(material.outlineColor);
+
+      point._dirty = false;
+    }
+  }
+
+  if (!defined(renderContext.vertexArray)) {
+    const { attributeArrays } = renderContext;
+
+    renderContext.vertexArray = new VertexArray({
+      context,
+      attributes: [
+        {
+          index: BufferPointAttributeLocations.positionHigh,
+          componentDatatype: ComponentDatatype.FLOAT,
+          componentsPerAttribute: 3,
+          vertexBuffer: Buffer.createVertexBuffer({
+            typedArray: attributeArrays.positionHigh,
+            context,
+            // @ts-expect-error Requires https://github.com/CesiumGS/cesium/pull/13203.
+            usage: BufferUsage.STATIC_DRAW,
+          }),
+        },
+        {
+          index: BufferPointAttributeLocations.positionLow,
+          componentDatatype: ComponentDatatype.FLOAT,
+          componentsPerAttribute: 3,
+          vertexBuffer: Buffer.createVertexBuffer({
+            typedArray: attributeArrays.positionLow,
+            context,
+            // @ts-expect-error Requires https://github.com/CesiumGS/cesium/pull/13203.
+            usage: BufferUsage.STATIC_DRAW,
+          }),
+        },
+        {
+          index: BufferPointAttributeLocations.pickColor,
+          componentDatatype: ComponentDatatype.UNSIGNED_BYTE,
+          componentsPerAttribute: 4,
+          vertexBuffer: Buffer.createVertexBuffer({
+            typedArray: attributeArrays.pickColor,
+            context,
+            // @ts-expect-error Requires https://github.com/CesiumGS/cesium/pull/13203.
+            usage: BufferUsage.STATIC_DRAW,
+          }),
+        },
+        {
+          index: BufferPointAttributeLocations.showSizeAndColor,
+          componentDatatype: ComponentDatatype.FLOAT,
+          componentsPerAttribute: 3,
+          vertexBuffer: Buffer.createVertexBuffer({
+            typedArray: attributeArrays.showSizeAndColor,
+            context,
+            // @ts-expect-error Requires https://github.com/CesiumGS/cesium/pull/13203.
+            usage: BufferUsage.STATIC_DRAW,
+          }),
+        },
+        {
+          index: BufferPointAttributeLocations.outlineWidthAndOutlineColor,
+          componentDatatype: ComponentDatatype.FLOAT,
+          componentsPerAttribute: 2,
+          vertexBuffer: Buffer.createVertexBuffer({
+            typedArray: attributeArrays.outlineWidthAndOutlineColor,
+            context,
+            // @ts-expect-error Requires https://github.com/CesiumGS/cesium/pull/13203.
+            usage: BufferUsage.STATIC_DRAW,
+          }),
+        },
+      ],
+    });
+  } else if (collection._dirtyCount > 0) {
+    for (const key in BufferPointAttributeLocations) {
+      if (Object.hasOwn(BufferPointAttributeLocations, key)) {
+        const attribute = /** @type {BufferPointAttribute} */ (key);
+        renderContext.vertexArray.copyAttributeFromRange(
+          BufferPointAttributeLocations[attribute],
+          renderContext.attributeArrays[attribute],
+          collection._dirtyOffset,
+          collection._dirtyCount,
+        );
+      }
+    }
+  }
+
+  if (!defined(renderContext.renderState)) {
+    renderContext.renderState = RenderState.fromCache({
+      blending: BlendingState.ALPHA_BLEND,
+      depthTest: { enabled: true },
+    });
+  }
+
+  if (!defined(renderContext.shaderProgram)) {
+    renderContext.shaderProgram = ShaderProgram.fromCache({
+      context,
+      vertexShaderSource: new ShaderSource({
+        sources: [BufferPointMaterialVS],
+      }),
+      fragmentShaderSource: new ShaderSource({
+        sources: [BufferPointMaterialFS],
+      }),
+      attributeLocations: BufferPointAttributeLocations,
+    });
+  }
+
+  if (
+    !defined(renderContext.command) ||
+    isCommandDirty(collection, renderContext.command)
+  ) {
+    renderContext.command = new DrawCommand({
+      vertexArray: renderContext.vertexArray,
+      renderState: renderContext.renderState,
+      shaderProgram: renderContext.shaderProgram,
+      primitiveType: PrimitiveType.POINTS,
+      pass: Pass.OPAQUE,
+      pickId: "v_pickColor",
+      owner: collection,
+      count: collection.primitiveCount,
+      modelMatrix: collection.modelMatrix,
+      boundingVolume: collection.boundingVolumeWC,
+      debugShowBoundingVolume: collection.debugShowBoundingVolume,
+    });
+  }
+
+  frameState.commandList.push(renderContext.command);
+
+  collection._dirtyCount = 0;
+  collection._dirtyOffset = 0;
+
+  return renderContext;
+}
+
+/**
+ * Returns true if DrawCommand is out of date for the given collection.
+ * @param {BufferPointCollection} collection
+ * @param {DrawCommand} command
+ * @ignore
+ */
+function isCommandDirty(collection, command) {
+  const isModelMatrixEqual = Matrix4.equals(
+    collection.modelMatrix,
+    command._modelMatrix,
+  );
+
+  const isBoundingVolumeEqual = BoundingSphere.equals(
+    collection.boundingVolumeWC,
+    command._boundingVolume,
+  );
+
+  return (
+    collection.primitiveCount !== command._count ||
+    collection.debugShowBoundingVolume !== command.debugShowBoundingVolume ||
+    !isModelMatrixEqual ||
+    !isBoundingVolumeEqual
+  );
+}
+
+/**
+ * Destroys render context resources. Deleting properties from the context
+ * object isn't necessary, as collection.destroy() will discard the object.
+ * @ignore
+ */
+function destroyRenderContext() {
+  const context = /** @type {BufferPointRenderContext} */ (this);
+
+  if (defined(context.vertexArray)) {
+    context.vertexArray.destroy();
+  }
+
+  if (defined(context.shaderProgram)) {
+    context.shaderProgram.destroy();
+  }
+
+  if (defined(context.renderState)) {
+    RenderState.removeFromCache(context.renderState);
+  }
+
+  if (defined(context.pickIds)) {
+    for (const pickId of context.pickIds) {
+      pickId.destroy();
+    }
+  }
+}
+
+export default renderBufferPointCollection;