@cesium/engine 22.2.0 → 23.0.0

package/Source/Scene/Vector3DTilePolylines.js

@@ -4,7 +4,6 @@ import ComponentDatatype from "../Core/ComponentDatatype.js";
 import defined from "../Core/defined.js";
 import destroyObject from "../Core/destroyObject.js";
 import Ellipsoid from "../Core/Ellipsoid.js";
-import FeatureDetection from "../Core/FeatureDetection.js";
 import IndexDatatype from "../Core/IndexDatatype.js";
 import Matrix4 from "../Core/Matrix4.js";
 import Rectangle from "../Core/Rectangle.js";
@@ -456,10 +455,7 @@ function createShaders(primitive, context) {
   )(PolylineFS);
 
   const vs = new ShaderSource({
-    defines: [
-      "VECTOR_TILE",
-      !FeatureDetection.isInternetExplorer() ? "CLIP_POLYLINE" : "",
-    ],
+    defines: ["VECTOR_TILE", "CLIP_POLYLINE"],
     sources: [PolylineCommon, vsSource],
   });
   const fs = new ShaderSource({

package/Source/Scene/VoxelPrimitive.js

@@ -405,11 +405,7 @@ function VoxelPrimitive(options) {
     octreeLeafNodeTilesPerRow: 0,
     octreeLeafNodeTexelSizeUv: new Cartesian2(),
     megatextureTextures: [],
-    megatextureSliceDimensions: new Cartesian2(),
-    megatextureTileDimensions: new Cartesian2(),
-    megatextureVoxelSizeUv: new Cartesian2(),
-    megatextureSliceSizeUv: new Cartesian2(),
-    megatextureTileSizeUv: new Cartesian2(),
+    megatextureTileCounts: new Cartesian3(),
     dimensions: new Cartesian3(),
     inputDimensions: new Cartesian3(),
     paddingBefore: new Cartesian3(),
@@ -855,10 +851,7 @@ Object.defineProperties(VoxelPrimitive.prototype, {
       Check.typeOf.bool("nearestSampling", nearestSampling);
       //>>includeEnd('debug');
 
-      if (this._nearestSampling !== nearestSampling) {
-        this._nearestSampling = nearestSampling;
-        this._shaderDirty = true;
-      }
+      this._nearestSampling = nearestSampling;
     },
   },
 
@@ -1282,6 +1275,7 @@ VoxelPrimitive.prototype.update = function (frameState) {
   );
   uniforms.stepSize = this._stepSizeMultiplier;
 
+  updateNearestSampling(this);
   updateRenderBoundPlanes(this, frameState);
 
   // Render the primitive
@@ -1294,6 +1288,13 @@ VoxelPrimitive.prototype.update = function (frameState) {
   frameState.commandList.push(command);
 };
 
+function updateNearestSampling(primitive) {
+  const { megatextures } = primitive._traversal;
+  for (let i = 0; i < megatextures.length; ++i) {
+    megatextures[i].nearestSampling = primitive._nearestSampling;
+  }
+}
+
 function updateRenderBoundPlanes(primitive, frameState) {
   const uniforms = primitive._uniforms;
   const { renderBoundPlanes } = primitive._shape;
@@ -1689,33 +1690,15 @@ function setTraversalUniforms(traversal, uniforms) {
   );
   uniforms.octreeInternalNodeTilesPerRow = traversal.internalNodeTilesPerRow;
 
-  const megatextures = traversal.megatextures;
+  const { megatextures } = traversal;
   const megatexture = megatextures[0];
-  const megatextureLength = megatextures.length;
-  uniforms.megatextureTextures = new Array(megatextureLength);
-  for (let i = 0; i < megatextureLength; i++) {
+  uniforms.megatextureTextures = new Array(megatextures.length);
+  for (let i = 0; i < megatextures.length; i++) {
     uniforms.megatextureTextures[i] = megatextures[i].texture;
   }
-
-  uniforms.megatextureSliceDimensions = Cartesian2.clone(
-    megatexture.sliceCountPerRegion,
-    uniforms.megatextureSliceDimensions,
-  );
-  uniforms.megatextureTileDimensions = Cartesian2.clone(
-    megatexture.regionCountPerMegatexture,
-    uniforms.megatextureTileDimensions,
-  );
-  uniforms.megatextureVoxelSizeUv = Cartesian2.clone(
-    megatexture.voxelSizeUv,
-    uniforms.megatextureVoxelSizeUv,
-  );
-  uniforms.megatextureSliceSizeUv = Cartesian2.clone(
-    megatexture.sliceSizeUv,
-    uniforms.megatextureSliceSizeUv,
-  );
-  uniforms.megatextureTileSizeUv = Cartesian2.clone(
-    megatexture.regionSizeUv,
-    uniforms.megatextureTileSizeUv,
+  uniforms.megatextureTileCounts = Cartesian3.clone(
+    megatexture.tileCounts,
+    uniforms.megatextureTileCounts,
   );
 }
 

package/Source/Scene/VoxelRenderResources.js

@@ -62,7 +62,7 @@ function VoxelRenderResources(primitive) {
   // The reason this uniform is added by shader builder is because some of the
   // dynamically generated shader code reads from it.
   shaderBuilder.addUniform(
-    "sampler2D",
+    "sampler3D",
     "u_megatextureTextures[METADATA_COUNT]",
     ShaderDestination.FRAGMENT,
   );
@@ -241,13 +241,6 @@ function VoxelRenderResources(primitive) {
       ShaderDestination.FRAGMENT,
     );
   }
-  if (primitive._nearestSampling) {
-    shaderBuilder.addDefine(
-      "NEAREST_SAMPLING",
-      undefined,
-      ShaderDestination.FRAGMENT,
-    );
-  }
   const traversal = primitive._traversal;
   shaderBuilder.addDefine(
     "SAMPLE_COUNT",

package/Source/Scene/VoxelTraversal.js

@@ -1,5 +1,4 @@
 import Cartesian2 from "../Core/Cartesian2.js";
-import Cartesian3 from "../Core/Cartesian3.js";
 import CesiumMath from "../Core/Math.js";
 import CullingVolume from "../Core/CullingVolume.js";
 import defined from "../Core/defined.js";
@@ -16,7 +15,6 @@ import SpatialNode from "./SpatialNode.js";
 import Texture from "../Renderer/Texture.js";
 import TextureMagnificationFilter from "../Renderer/TextureMagnificationFilter.js";
 import TextureMinificationFilter from "../Renderer/TextureMinificationFilter.js";
-import VoxelMetadataOrder from "./VoxelMetadataOrder.js";
 
 /**
  * Handles tileset traversal, tile requests, and GPU resources. Intended to be
@@ -28,7 +26,7 @@ import VoxelMetadataOrder from "./VoxelMetadataOrder.js";
  * @param {VoxelPrimitive} primitive The voxel primitive for which this traversal will be used.
  * @param {Context} context The context in which to create GPU resources.
  * @param {number} keyframeCount The number of keyframes in the tileset.
- * @param {number} [maximumTextureMemoryByteLength] The maximum amount of memory to use for textures.
+ * @param {number} [maximumTextureMemoryByteLength=536870912] The maximum amount of memory to use for textures.
  *
  * @private
  */
@@ -38,32 +36,16 @@ function VoxelTraversal(
   keyframeCount,
   maximumTextureMemoryByteLength,
 ) {
-  const { provider, dimensions, paddingBefore, paddingAfter } = primitive;
-  const { types, componentTypes, metadataOrder } = provider;
+  const { provider, dimensions, inputDimensions } = primitive;
+  const { types, componentTypes } = provider;
 
-  const inputDimensions = Cartesian3.add(
-    dimensions,
-    paddingBefore,
-    new Cartesian3(),
-  );
-  Cartesian3.add(inputDimensions, paddingAfter, inputDimensions);
-
-  if (metadataOrder === VoxelMetadataOrder.Y_UP) {
-    const inputDimensionsY = inputDimensions.y;
-    inputDimensions.y = inputDimensions.z;
-    inputDimensions.z = inputDimensionsY;
-  }
-
-  if (
-    !defined(maximumTextureMemoryByteLength) &&
-    defined(provider.maximumTileCount)
-  ) {
-    maximumTextureMemoryByteLength = getApproximateTextureMemoryByteLength(
-      provider.maximumTileCount,
-      inputDimensions,
-      types,
-      componentTypes,
+  if (defined(maximumTextureMemoryByteLength)) {
+    maximumTextureMemoryByteLength = Math.min(
+      Math.max(0, maximumTextureMemoryByteLength),
+      512 * 1024 * 1024,
     );
+  } else {
+    maximumTextureMemoryByteLength = 128 * 1024 * 1024;
   }
 
   /**
@@ -84,7 +66,12 @@ function VoxelTraversal(
    */
   this.megatextures = new Array(types.length);
 
-  // TODO make sure to split the maximumTextureMemoryByteLength across all the megatextures
+  const providerTileCount = defined(provider.maximumTileCount)
+    ? provider.maximumTileCount
+    : defined(provider.availableLevels)
+      ? (8 ** provider.availableLevels - 1) / 7
+      : undefined;
+
   for (let i = 0; i < types.length; i++) {
     const type = types[i];
     const componentCount = MetadataType.getComponentCount(type);
@@ -96,6 +83,7 @@ function VoxelTraversal(
       componentCount,
       componentType,
       maximumTextureMemoryByteLength,
+      providerTileCount,
     );
 
     this.textureMemoryByteLength +=
@@ -1228,37 +1216,4 @@ function copyToLeafNodeTexture(data, texelsPerTile, tilesPerRow, texture) {
   texture.copyFrom(copyOptions);
 }
 
-/**
- * @param {number} tileCount
- * @param {Cartesian3} dimensions
- * @param {MetadataType[]} types
- * @param {MetadataComponentType[]} componentTypes
- * @private
- */
-function getApproximateTextureMemoryByteLength(
-  tileCount,
-  dimensions,
-  types,
-  componentTypes,
-) {
-  let textureMemoryByteLength = 0;
-
-  const length = types.length;
-  for (let i = 0; i < length; i++) {
-    const type = types[i];
-    const componentType = componentTypes[i];
-    const componentCount = MetadataType.getComponentCount(type);
-
-    textureMemoryByteLength +=
-      Megatexture.getApproximateTextureMemoryByteLength(
-        tileCount,
-        dimensions,
-        componentCount,
-        componentType,
-      );
-  }
-
-  return textureMemoryByteLength;
-}
-
 export default VoxelTraversal;

package/Source/Scene/WebMapTileServiceImageryProvider.js

@@ -51,7 +51,7 @@ const defaultParameters = Object.freeze({
  *
  * @param {WebMapTileServiceImageryProvider.ConstructorOptions} options Object describing initialization options
  *
- * @demo {@link https://sandcastle.cesium.com/index.html?src=Web%20Map%20Tile%20Service%20with%20Time.html|Cesium Sandcastle Web Map Tile Service with Time Demo}
+ * @demo {@link https://sandcastle.cesium.com/index.html?id=web-map-tile-service-with-time|Cesium Sandcastle Web Map Tile Service with Time Demo}
  *
  * @example
  * // Example 1. USGS shaded relief tiles (KVP)

package/Source/Scene/createElevationBandMaterial.js

@@ -435,7 +435,7 @@ function createLayeredEntries(layers) {
  * @param {createElevationBandMaterialBand[]} options.layers A list of bands ordered from lowest to highest precedence.
  * @returns {Material} A new {@link Material} instance.
  *
- * @demo {@link https://sandcastle.cesium.com/index.html?src=Elevation%20Band%20Material.html|Cesium Sandcastle Elevation Band Demo}
+ * @demo {@link https://sandcastle.cesium.com/index.html?id=elevation-band-material|Cesium Sandcastle Elevation Band Demo}
  *
  * @example
  * scene.globe.material = Cesium.createElevationBandMaterial({

package/Source/Scene/parseStructuralMetadata.js

@@ -6,6 +6,18 @@ import PropertyTexture from "./PropertyTexture.js";
 import PropertyAttribute from "./PropertyAttribute.js";
 import StructuralMetadata from "./StructuralMetadata.js";
 import MetadataTable from "./MetadataTable.js";
+import Sampler from "../Renderer/Sampler.js";
+import Texture from "../Renderer/Texture.js";
+import PixelFormat from "../Core/PixelFormat.js";
+import PixelDatatype from "../Renderer/PixelDatatype.js";
+import RuntimeError from "../Core/RuntimeError.js";
+import oneTimeWarning from "../Core/oneTimeWarning.js";
+import TextureWrap from "../Renderer/TextureWrap.js";
+import TextureMagnificationFilter from "../Renderer/TextureMagnificationFilter.js";
+import TextureMinificationFilter from "../Renderer/TextureMinificationFilter.js";
+import ContextLimits from "../Renderer/ContextLimits.js";
+import MetadataComponentType from "./MetadataComponentType.js";
+import MetadataType from "./MetadataType.js";
 
 /**
  * Parse the <code>EXT_structural_metadata</code> glTF extension to create a
@@ -16,6 +28,7 @@ import MetadataTable from "./MetadataTable.js";
  * @param {MetadataSchema} options.schema The parsed schema.
  * @param {Object<string, Uint8Array>} [options.bufferViews] An object mapping bufferView IDs to Uint8Array objects.
  * @param {Object<string, Texture>} [options.textures] An object mapping texture IDs to {@link Texture} objects.
+ * @param {Context} [options.context] The current rendering context.
  * @return {StructuralMetadata} A structural metadata object
  * @private
  * @experimental This feature is using part of the 3D Tiles spec that is not final and is subject to change without Cesium's standard deprecation policy.
@@ -38,12 +51,20 @@ function parseStructuralMetadata(options) {
     for (let i = 0; i < extension.propertyTables.length; i++) {
       const propertyTable = extension.propertyTables[i];
       const classDefinition = schema.classes[propertyTable.class];
+      const propertyTableTexture = createTextureForPropertyTable(
+        propertyTable,
+        options.bufferViews,
+        classDefinition,
+        options.context,
+      );
+
       const metadataTable = new MetadataTable({
         count: propertyTable.count,
         properties: propertyTable.properties,
         class: classDefinition,
         bufferViews: options.bufferViews,
       });
+
       propertyTables.push(
         new PropertyTable({
           id: i,
@@ -52,6 +73,7 @@ function parseStructuralMetadata(options) {
           metadataTable: metadataTable,
           extras: propertyTable.extras,
           extensions: propertyTable.extensions,
+          texture: propertyTableTexture,
         }),
       );
     }
@@ -99,4 +121,226 @@ function parseStructuralMetadata(options) {
   });
 }
 
+// Always use four channels for property table textures.
+const NUM_CHANNELS = 4;
+
+/**
+ * Creates a texture from a set of property table properties (those which are GPU compatible).
+ * Each row of the texture is a property, with each column corresponding to a given feature.
+ *
+ * @param {PropertyTable} propertyTable The property table.
+ * @param {Object<string, Uint8Array>} bufferViews An object mapping bufferView IDs to Uint8Array objects for the given property table.
+ * @param {MetadataClass} classDefinition Class defined in the schema
+ * @param {Context} context The rendering context.
+ * @returns {Texture|undefined} The created texture, or <code>undefined</code> if no properties are GPU compatible.
+ *
+ * @private
+ */
+function createTextureForPropertyTable(
+  propertyTable,
+  bufferViews,
+  classDefinition,
+  context,
+) {
+  const properties = propertyTable.properties;
+  if (!defined(properties)) {
+    return undefined;
+  }
+
+  const numFeatures = propertyTable.count;
+
+  let gpuCompatiblePropertyBufferViews;
+  try {
+    gpuCompatiblePropertyBufferViews = collectGpuCompatiblePropertyBufferViews(
+      properties,
+      bufferViews,
+      classDefinition,
+      numFeatures,
+    );
+  } catch (error) {
+    console.warn(
+      `Failed to create texture for property table "${propertyTable.name}": ${error.message}`,
+    );
+    return undefined;
+  }
+
+  const numGpuCompatibleProperties = gpuCompatiblePropertyBufferViews.length;
+
+  if (numGpuCompatibleProperties === 0) {
+    return undefined;
+  }
+
+  // In the future, we could use multiple textures if we would exceed the maximum texture size.
+  if (
+    numFeatures > ContextLimits.maximumTextureSize ||
+    numGpuCompatibleProperties > ContextLimits.maximumTextureSize
+  ) {
+    oneTimeWarning(
+      "PropertyTableTextureExceedsMaximumSize",
+      `Cannot create a texture for the property table "${propertyTable.name}" because it exceeds the maximum texture size of ${ContextLimits.maximumTextureSize}.`,
+    );
+    return undefined;
+  }
+
+  const packedBufferView = packPropertyTablePropertiesIntoRGBA8(
+    gpuCompatiblePropertyBufferViews,
+    numFeatures,
+  );
+
+  // Create a sampler fit for sampling raw data without mipmapping / filtering etc.
+  const sampler = new Sampler({
+    wrapS: TextureWrap.CLAMP_TO_EDGE,
+    wrapT: TextureWrap.CLAMP_TO_EDGE,
+    minificationFilter: TextureMinificationFilter.NEAREST,
+    magnificationFilter: TextureMagnificationFilter.NEAREST,
+  });
+
+  return Texture.create({
+    context: context,
+    pixelFormat: PixelFormat.RGBA,
+    pixelDatatype: PixelDatatype.UNSIGNED_BYTE,
+    sampler: sampler,
+    flipY: false,
+    source: {
+      width: numFeatures,
+      height: numGpuCompatibleProperties,
+      arrayBufferView: packedBufferView,
+    },
+  });
+}
+
+function collectGpuCompatiblePropertyBufferViews(
+  properties,
+  bufferViews,
+  classDefinition,
+  numFeatures,
+) {
+  const bufferViewsForThisTable = [];
+  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.
+  // For instance, the Design Tiler merges classes together by default, and omits properties in primitives that aren't used.
+  // To make the default values available to the GPU, and to avoid compiling different versions of the shader for each primitive,
+  // we iterate over _all_ class properties here - not just the properties in the property table.
+  for (const [propertyId, classProperty] of Object.entries(classProperties)) {
+    // Certain properties like strings, dynamic-sized arrays, and 64-bit types cannot be represented natively on the GPU.
+    if (!classProperty.isGpuCompatible(NUM_CHANNELS)) {
+      continue;
+    }
+
+    const property = properties[propertyId];
+    const bufferView = defined(property)
+      ? bufferViews[property.values]
+      : createNoDataBufferView(classProperty, numFeatures);
+
+    const bufferViewLength = bufferView.length;
+    const bytesPerElement = classProperty.bytesPerElement();
+    const numBufferElements = bufferViewLength / bytesPerElement;
+    if (numBufferElements !== numFeatures) {
+      throw new RuntimeError(
+        `Property with ID: "${propertyId}" has (${numBufferElements}), which does not match number of features in the property table: (${numFeatures}).`,
+      );
+    }
+
+    bufferViewsForThisTable.push({
+      view: bufferView,
+      bytesPerElement: bytesPerElement,
+    });
+  }
+
+  return bufferViewsForThisTable;
+}
+
+/**
+ * When a property is part of a tileset class schema but not used in a property table,
+ * we create a buffer view filled with the property's noData value.
+ *
+ * @param {MetadataClassProperty} classProperty The class property definition.
+ * @param {number} numFeatures The number of features in the property table.
+ *
+ * @returns {Uint8Array} A buffer view filled with the property's noData value.
+ *
+ * @private
+ */
+function createNoDataBufferView(classProperty, numFeatures) {
+  // noData can be a number, an array of numbers (e.g. for vecN types), or a nested array of numbers (e.g. for arrays of vecN types).
+  let noData = classProperty.noData;
+  const metadataComponentCount = MetadataType.getComponentCount(
+    classProperty.type,
+  );
+  const metadataArrayLength = classProperty.isArray
+    ? classProperty.arrayLength
+    : 1;
+
+  // Special case: noData enum values are specified as strings, so we need to convert them to numbers here.
+  if (classProperty.type === MetadataType.ENUM) {
+    const enumDefinition = classProperty.enumType;
+    noData = enumDefinition.valuesByName[noData];
+  }
+
+  // Wrap noData in an array (up to two times) so we can treat it uniformly in the loop below.
+  if (metadataComponentCount === 1) {
+    noData = [noData];
+  }
+
+  if (metadataArrayLength === 1) {
+    noData = [noData];
+  }
+
+  const bytesPerElement = classProperty.bytesPerElement();
+  const buffer = new ArrayBuffer(bytesPerElement * numFeatures);
+  const view = new DataView(buffer);
+  const setter = MetadataComponentType.getDataViewSetter(
+    view,
+    classProperty.componentType,
+  );
+
+  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]);
+      }
+    }
+  }
+
+  return new Uint8Array(buffer);
+}
+
+// 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;
+  const packedBufferView = new Uint8Array(
+    numGpuCompatibleProperties * numFeatures * NUM_CHANNELS,
+  );
+
+  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 j = 0; j < numElements; j++) {
+      const sourceOffset = j * bytesPerElement;
+      const destOffset = offset + j * NUM_CHANNELS;
+
+      packedBufferView.set(
+        bufferView.subarray(sourceOffset, sourceOffset + bytesPerElement),
+        destOffset,
+      );
+
+      // Pad remaining channels with 0
+      for (let k = bytesPerElement; k < NUM_CHANNELS; k++) {
+        packedBufferView[destOffset + k] = 0;
+      }
+    }
+
+    offset += numElements * NUM_CHANNELS;
+  }
+
+  return packedBufferView;
+}
+
 export default parseStructuralMetadata;

package/Source/Scene/processVoxelProperties.js

@@ -294,7 +294,7 @@ function processVoxelProperties(renderResources, primitive) {
     const functionId = "getPropertiesFromMegatextureAtUv";
     shaderBuilder.addFunction(
       functionId,
-      `${propertiesStructName} getPropertiesFromMegatextureAtUv(vec2 texcoord)`,
+      `${propertiesStructName} getPropertiesFromMegatextureAtUv(vec3 texcoord)`,
       ShaderDestination.FRAGMENT,
     );
     shaderBuilder.addFunctionLines(functionId, [