@cesium/engine 0.1.0 → 1.1.0

package/Source/Scene/Megatexture.js

@@ -0,0 +1,490 @@
+import Cartesian2 from "../Core/Cartesian2.js";
+import Cartesian3 from "../Core/Cartesian3.js";
+import ComponentDatatype from "../Core/ComponentDatatype.js";
+import ContextLimits from "../Renderer/ContextLimits.js";
+import defaultValue from "../Core/defaultValue.js";
+import defined from "../Core/defined.js";
+import destroyObject from "../Core/destroyObject.js";
+import DeveloperError from "../Core/DeveloperError.js";
+import CesiumMath from "../Core/Math.js";
+import MetadataComponentType from "./MetadataComponentType.js";
+import PixelDatatype from "../Renderer/PixelDatatype.js";
+import PixelFormat from "../Core/PixelFormat.js";
+import RuntimeError from "../Core/RuntimeError.js";
+import Sampler from "../Renderer/Sampler.js";
+import Texture from "../Renderer/Texture.js";
+import TextureMagnificationFilter from "../Renderer/TextureMagnificationFilter.js";
+import TextureMinificationFilter from "../Renderer/TextureMinificationFilter.js";
+import TextureWrap from "../Renderer/TextureWrap.js";
+
+/**
+ * @alias Megatexture
+ * @constructor
+ *
+ * @param {Context} context
+ * @param {Cartesian3} dimensions
+ * @param {Number} channelCount
+ * @param {MetadataComponentType} componentType
+ * @param {Number} [textureMemoryByteLength]
+ *
+ * @private
+ */
+function Megatexture(
+  context,
+  dimensions,
+  channelCount,
+  componentType,
+  textureMemoryByteLength
+) {
+  // TODO there are a lot of texture packing rules, see https://github.com/CesiumGS/cesium/issues/9572
+  // Unsigned short textures not allowed in webgl 1, so treat as float
+  if (componentType === MetadataComponentType.UNSIGNED_SHORT) {
+    componentType = MetadataComponentType.FLOAT32;
+  }
+
+  const supportsFloatingPointTexture = context.floatingPointTexture;
+  if (
+    componentType === MetadataComponentType.FLOAT32 &&
+    !supportsFloatingPointTexture
+  ) {
+    throw new RuntimeError("Floating point texture not supported");
+  }
+
+  // TODO support more
+  let pixelType;
+  if (
+    componentType === MetadataComponentType.FLOAT32 ||
+    componentType === MetadataComponentType.FLOAT64
+  ) {
+    pixelType = PixelDatatype.FLOAT;
+  } else if (componentType === MetadataComponentType.UINT8) {
+    pixelType = PixelDatatype.UNSIGNED_BYTE;
+  }
+
+  let pixelFormat;
+  if (channelCount === 1) {
+    pixelFormat = PixelFormat.LUMINANCE;
+  } else if (channelCount === 2) {
+    pixelFormat = PixelFormat.LUMINANCE_ALPHA;
+  } else if (channelCount === 3) {
+    pixelFormat = PixelFormat.RGB;
+  } else if (channelCount === 4) {
+    pixelFormat = PixelFormat.RGBA;
+  }
+
+  const maximumTextureMemoryByteLength = 512 * 1024 * 1024;
+  const defaultTextureMemoryByteLength = 128 * 1024 * 1024;
+  textureMemoryByteLength = Math.min(
+    defaultValue(textureMemoryByteLength, defaultTextureMemoryByteLength),
+    maximumTextureMemoryByteLength
+  );
+  const maximumTextureDimensionContext = ContextLimits.maximumTextureSize;
+  const componentTypeByteLength = MetadataComponentType.getSizeInBytes(
+    componentType
+  );
+  const texelCount = Math.floor(
+    textureMemoryByteLength / (channelCount * componentTypeByteLength)
+  );
+  const textureDimension = Math.min(
+    maximumTextureDimensionContext,
+    CesiumMath.previousPowerOfTwo(Math.floor(Math.sqrt(texelCount)))
+  );
+
+  const sliceCountPerRegionX = Math.ceil(Math.sqrt(dimensions.x));
+  const sliceCountPerRegionY = Math.ceil(dimensions.z / sliceCountPerRegionX);
+  const voxelCountPerRegionX = sliceCountPerRegionX * dimensions.x;
+  const voxelCountPerRegionY = sliceCountPerRegionY * dimensions.y;
+  const regionCountPerMegatextureX = Math.floor(
+    textureDimension / voxelCountPerRegionX
+  );
+  const regionCountPerMegatextureY = Math.floor(
+    textureDimension / voxelCountPerRegionY
+  );
+
+  if (regionCountPerMegatextureX === 0 || regionCountPerMegatextureY === 0) {
+    throw new RuntimeError("Tileset is too large to fit into megatexture");
+  }
+
+  /**
+   * @type {Number}
+   * @readonly
+   */
+  this.channelCount = channelCount;
+
+  /**
+   * @type {MetadataComponentType}
+   * @readonly
+   */
+  this.componentType = componentType;
+
+  /**
+   * @type {Cartesian3}
+   * @readonly
+   */
+  this.voxelCountPerTile = Cartesian3.clone(dimensions, new Cartesian3());
+
+  /**
+   * @type {Number}
+   * @readonly
+   */
+  this.maximumTileCount =
+    regionCountPerMegatextureX * regionCountPerMegatextureY;
+
+  /**
+   * @type {Cartesian2}
+   * @readonly
+   */
+  this.regionCountPerMegatexture = new Cartesian2(
+    regionCountPerMegatextureX,
+    regionCountPerMegatextureY
+  );
+
+  /**
+   * @type {Cartesian2}
+   * @readonly
+   */
+  this.voxelCountPerRegion = new Cartesian2(
+    voxelCountPerRegionX,
+    voxelCountPerRegionY
+  );
+
+  /**
+   * @type {Cartesian2}
+   * @readonly
+   */
+  this.sliceCountPerRegion = new Cartesian2(
+    sliceCountPerRegionX,
+    sliceCountPerRegionY
+  );
+
+  /**
+   * @type {Cartesian2}
+   * @readonly
+   */
+  this.voxelSizeUv = new Cartesian2(
+    1.0 / textureDimension,
+    1.0 / textureDimension
+  );
+
+  /**
+   * @type {Cartesian2}
+   * @readonly
+   */
+  this.sliceSizeUv = new Cartesian2(
+    dimensions.x / textureDimension,
+    dimensions.y / textureDimension
+  );
+
+  /**
+   * @type {Cartesian2}
+   * @readonly
+   */
+  this.regionSizeUv = new Cartesian2(
+    voxelCountPerRegionX / textureDimension,
+    voxelCountPerRegionY / textureDimension
+  );
+
+  /**
+   * @type {Texture}
+   * @readonly
+   */
+  this.texture = new Texture({
+    context: context,
+    pixelFormat: pixelFormat,
+    pixelDatatype: pixelType,
+    flipY: false,
+    width: textureDimension,
+    height: textureDimension,
+    sampler: new Sampler({
+      wrapS: TextureWrap.CLAMP_TO_EDGE,
+      wrapT: TextureWrap.CLAMP_TO_EDGE,
+      minificationFilter: TextureMinificationFilter.LINEAR,
+      magnificationFilter: TextureMagnificationFilter.LINEAR,
+    }),
+  });
+
+  const componentDatatype = MetadataComponentType.toComponentDatatype(
+    componentType
+  );
+
+  /**
+   * @type {Array}
+   */
+  this.tileVoxelDataTemp = ComponentDatatype.createTypedArray(
+    componentDatatype,
+    voxelCountPerRegionX * voxelCountPerRegionY * channelCount
+  );
+
+  /**
+   * @type {MegatextureNode[]}
+   * @readonly
+   */
+  this.nodes = new Array(this.maximumTileCount);
+  for (let tileIndex = 0; tileIndex < this.maximumTileCount; tileIndex++) {
+    this.nodes[tileIndex] = new MegatextureNode(tileIndex);
+  }
+  for (let tileIndex = 0; tileIndex < this.maximumTileCount; tileIndex++) {
+    const node = this.nodes[tileIndex];
+    node.previousNode = tileIndex > 0 ? this.nodes[tileIndex - 1] : undefined;
+    node.nextNode =
+      tileIndex < this.maximumTileCount - 1
+        ? this.nodes[tileIndex + 1]
+        : undefined;
+  }
+
+  /**
+   * @type {MegatextureNode}
+   * @readonly
+   */
+  this.occupiedList = undefined;
+
+  /**
+   * @type {MegatextureNode}
+   * @readonly
+   */
+  this.emptyList = this.nodes[0];
+
+  /**
+   * @type {Number}
+   * @readonly
+   */
+  this.occupiedCount = 0;
+}
+
+/**
+ * @alias MegatextureNode
+ * @constructor
+ *
+ * @param {Number} index
+ *
+ * @private
+ */
+function MegatextureNode(index) {
+  /**
+   * @type {Number}
+   */
+  this.index = index;
+
+  /**
+   * @type {MegatextureNode}
+   */
+  this.nextNode = undefined;
+
+  /**
+   * @type {MegatextureNode}
+   */
+  this.previousNode = undefined;
+}
+
+/**
+ * @param {Array} data
+ * @returns {Number}
+ */
+Megatexture.prototype.add = function (data) {
+  if (this.isFull()) {
+    throw new DeveloperError("Trying to add when there are no empty spots");
+  }
+
+  // remove head of empty list
+  const node = this.emptyList;
+  this.emptyList = this.emptyList.nextNode;
+  if (defined(this.emptyList)) {
+    this.emptyList.previousNode = undefined;
+  }
+
+  // make head of occupied list
+  node.nextNode = this.occupiedList;
+  if (defined(node.nextNode)) {
+    node.nextNode.previousNode = node;
+  }
+  this.occupiedList = node;
+
+  const index = node.index;
+  this.writeDataToTexture(index, data);
+
+  this.occupiedCount++;
+  return index;
+};
+
+/**
+ * @param {Number} index
+ */
+Megatexture.prototype.remove = function (index) {
+  if (index < 0 || index >= this.maximumTileCount) {
+    throw new DeveloperError("Megatexture index out of bounds");
+  }
+
+  // remove from list
+  const node = this.nodes[index];
+  if (defined(node.previousNode)) {
+    node.previousNode.nextNode = node.nextNode;
+  }
+  if (defined(node.nextNode)) {
+    node.nextNode.previousNode = node.previousNode;
+  }
+
+  // make head of empty list
+  node.nextNode = this.emptyList;
+  if (defined(node.nextNode)) {
+    node.nextNode.previousNode = node;
+  }
+  node.previousNode = undefined;
+  this.emptyList = node;
+  this.occupiedCount--;
+};
+
+/**
+ * @returns {Boolean}
+ */
+Megatexture.prototype.isFull = function () {
+  return this.emptyList === undefined;
+};
+
+/**
+ * @param {Number} tileCount
+ * @param {Cartesian3} dimensions
+ * @param {Number} channelCount number of channels in the metadata. Must be 1 to 4.
+ * @param {MetadataComponentType} componentType
+ * @returns {Number}
+ */
+Megatexture.getApproximateTextureMemoryByteLength = function (
+  tileCount,
+  dimensions,
+  channelCount,
+  componentType
+) {
+  // TODO there's a lot of code duplicate with Megatexture constructor
+
+  // Unsigned short textures not allowed in webgl 1, so treat as float
+  if (componentType === MetadataComponentType.UNSIGNED_SHORT) {
+    componentType = MetadataComponentType.FLOAT32;
+  }
+
+  const datatypeSizeInBytes = MetadataComponentType.getSizeInBytes(
+    componentType
+  );
+  const voxelCountTotal =
+    tileCount * dimensions.x * dimensions.y * dimensions.z;
+
+  const sliceCountPerRegionX = Math.ceil(Math.sqrt(dimensions.z));
+  const sliceCountPerRegionY = Math.ceil(dimensions.z / sliceCountPerRegionX);
+  const voxelCountPerRegionX = sliceCountPerRegionX * dimensions.x;
+  const voxelCountPerRegionY = sliceCountPerRegionY * dimensions.y;
+
+  // Find the power of two that can fit all tile data, accounting for slices.
+  // There's probably a non-iterative solution for this, but this is good enough for now.
+  let textureDimension = CesiumMath.previousPowerOfTwo(
+    Math.floor(Math.sqrt(voxelCountTotal))
+  );
+  for (;;) {
+    const regionCountX = Math.floor(textureDimension / voxelCountPerRegionX);
+    const regionCountY = Math.floor(textureDimension / voxelCountPerRegionY);
+    const regionCount = regionCountX * regionCountY;
+    if (regionCount >= tileCount) {
+      break;
+    } else {
+      textureDimension *= 2;
+    }
+  }
+
+  const textureMemoryByteLength =
+    textureDimension * textureDimension * channelCount * datatypeSizeInBytes;
+  return textureMemoryByteLength;
+};
+
+/**
+ * @param {Number} index
+ * @param {Float32Array|Uint16Array|Uint8Array} data
+ */
+Megatexture.prototype.writeDataToTexture = function (index, data) {
+  // Unsigned short textures not allowed in webgl 1, so treat as float
+  const tileData =
+    data.constructor === Uint16Array ? new Float32Array(data) : data;
+
+  const voxelDimensionsPerTile = this.voxelCountPerTile;
+  const sliceDimensionsPerRegion = this.sliceCountPerRegion;
+  const voxelDimensionsPerRegion = this.voxelCountPerRegion;
+  const channelCount = this.channelCount;
+
+  const tileVoxelData = this.tileVoxelDataTemp;
+  for (let z = 0; z < voxelDimensionsPerTile.z; z++) {
+    const sliceVoxelOffsetX =
+      (z % sliceDimensionsPerRegion.x) * voxelDimensionsPerTile.x;
+    const sliceVoxelOffsetY =
+      Math.floor(z / sliceDimensionsPerRegion.x) * voxelDimensionsPerTile.y;
+    for (let y = 0; y < voxelDimensionsPerTile.y; y++) {
+      for (let x = 0; x < voxelDimensionsPerTile.x; x++) {
+        const readIndex =
+          z * voxelDimensionsPerTile.y * voxelDimensionsPerTile.x +
+          y * voxelDimensionsPerTile.x +
+          x;
+        const writeIndex =
+          (sliceVoxelOffsetY + y) * voxelDimensionsPerRegion.x +
+          (sliceVoxelOffsetX + x);
+        for (let c = 0; c < channelCount; c++) {
+          tileVoxelData[writeIndex * channelCount + c] =
+            tileData[readIndex * channelCount + c];
+        }
+      }
+    }
+  }
+
+  const regionDimensionsPerMegatexture = this.regionCountPerMegatexture;
+  const voxelWidth = voxelDimensionsPerRegion.x;
+  const voxelHeight = voxelDimensionsPerRegion.y;
+  const voxelOffsetX =
+    (index % regionDimensionsPerMegatexture.x) * voxelDimensionsPerRegion.x;
+  const voxelOffsetY =
+    Math.floor(index / regionDimensionsPerMegatexture.x) *
+    voxelDimensionsPerRegion.y;
+
+  const source = {
+    arrayBufferView: tileVoxelData,
+    width: voxelWidth,
+    height: voxelHeight,
+  };
+
+  const copyOptions = {
+    source: source,
+    xOffset: voxelOffsetX,
+    yOffset: voxelOffsetY,
+  };
+
+  this.texture.copyFrom(copyOptions);
+};
+
+/**
+ * Returns true if this object was destroyed; otherwise, false.
+ * <br /><br />
+ * If this object was destroyed, it should not be used; calling any function other than
+ * <code>isDestroyed</code> will result in a {@link DeveloperError} exception.
+ *
+ * @returns {Boolean} <code>true</code> if this object was destroyed; otherwise, <code>false</code>.
+ *
+ * @see Megatexture#destroy
+ */
+Megatexture.prototype.isDestroyed = function () {
+  return false;
+};
+
+/**
+ * Destroys the WebGL resources held by this object.  Destroying an object allows for deterministic
+ * release of WebGL resources, instead of relying on the garbage collector to destroy this object.
+ * <br /><br />
+ * Once an object is destroyed, it should not be used; calling any function other than
+ * <code>isDestroyed</code> will result in a {@link DeveloperError} exception.  Therefore,
+ * assign the return value (<code>undefined</code>) to the object as done in the example.
+ *
+ * @exception {DeveloperError} This object was destroyed, i.e., destroy() was called.
+ *
+ * @see Megatexture#isDestroyed
+ *
+ * @example
+ * megatexture = megatexture && megatexture.destroy();
+ */
+Megatexture.prototype.destroy = function () {
+  this.texture = this.texture && this.texture.destroy();
+  return destroyObject(this);
+};
+
+export default Megatexture;

package/Source/Scene/MetadataClass.js

@@ -1,4 +1,5 @@
 import Check from "../Core/Check.js";
+import clone from "../Core/clone.js";
 import defaultValue from "../Core/defaultValue.js";
 import defined from "../Core/defined.js";
 import MetadataClassProperty from "./MetadataClassProperty.js";
@@ -7,22 +8,65 @@ import MetadataClassProperty from "./MetadataClassProperty.js";
  * A metadata class.
  *
  * <p>
- * See the {@link https://github.com/CesiumGS/3d-tiles/tree/main/extensions/3DTILES_metadata|3DTILES_metadata Extension} for 3D Tiles
+ * See the {@link https://github.com/CesiumGS/3d-tiles/tree/main/specification/Metadata|3D Metadata Specification} for 3D Tiles
  * </p>
  *
  * @param {Object} options Object with the following properties:
  * @param {String} options.id The ID of the class.
- * @param {Object} options.class The class JSON object.
- * @param {Object.<String, MetadataEnum>} [options.enums] A dictionary of enums.
+ * @param {String} [options.name] The name of the class.
+ * @param {String} [options.description] The description of the class.
+ * @param {Object.<String, MetadataClassProperty>} [options.properties] The class properties, where each key is the property ID.
+ * @param {*} [options.extras] Extra user-defined properties.
+ * @param {Object} [options.extensions] An object containing extensions.
  *
  * @alias MetadataClass
  * @constructor
- * @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.
  */
 function MetadataClass(options) {
   options = defaultValue(options, defaultValue.EMPTY_OBJECT);
   const id = options.id;
+
+  //>>includeStart('debug', pragmas.debug);
+  Check.typeOf.string("options.id", id);
+  //>>includeEnd('debug');
+
+  const properties = defaultValue(options.properties, {});
+  const propertiesBySemantic = {};
+  for (const propertyId in properties) {
+    if (properties.hasOwnProperty(propertyId)) {
+      const property = properties[propertyId];
+      if (defined(property.semantic)) {
+        propertiesBySemantic[property.semantic] = property;
+      }
+    }
+  }
+
+  this._id = id;
+  this._name = options.name;
+  this._description = options.description;
+  this._properties = properties;
+  this._propertiesBySemantic = propertiesBySemantic;
+  this._extras = clone(options.extras, true);
+  this._extensions = clone(options.extensions, true);
+}
+
+/**
+ * Creates a {@link MetadataClass} from either 3D Tiles 1.1, 3DTILES_metadata, EXT_structural_metadata, or EXT_feature_metadata.
+ *
+ * @param {Object} options Object with the following properties:
+ * @param {String} options.id The ID of the class.
+ * @param {Object} options.class The class JSON object.
+ * @param {Object.<String, MetadataEnum>} [options.enums] A dictionary of enums.
+ *
+ * @returns {MetadataClass} The newly created metadata class.
+ *
+ * @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.
+ */
+MetadataClass.fromJson = function (options) {
+  options = defaultValue(options, defaultValue.EMPTY_OBJECT);
+  const id = options.id;
   const classDefinition = options.class;
 
   //>>includeStart('debug', pragmas.debug);
@@ -31,29 +75,26 @@ function MetadataClass(options) {
   //>>includeEnd('debug');
 
   const properties = {};
-  const propertiesBySemantic = {};
   for (const propertyId in classDefinition.properties) {
     if (classDefinition.properties.hasOwnProperty(propertyId)) {
-      const property = new MetadataClassProperty({
+      const property = MetadataClassProperty.fromJson({
         id: propertyId,
         property: classDefinition.properties[propertyId],
         enums: options.enums,
       });
       properties[propertyId] = property;
-      if (defined(property.semantic)) {
-        propertiesBySemantic[property.semantic] = property;
-      }
     }
   }
 
-  this._properties = properties;
-  this._propertiesBySemantic = propertiesBySemantic;
-  this._id = id;
-  this._name = classDefinition.name;
-  this._description = classDefinition.description;
-  this._extras = classDefinition.extras;
-  this._extensions = classDefinition.extensions;
-}
+  return new MetadataClass({
+    id: id,
+    name: classDefinition.name,
+    description: classDefinition.description,
+    properties: properties,
+    extras: classDefinition.extras,
+    extensions: classDefinition.extensions,
+  });
+};
 
 Object.defineProperties(MetadataClass.prototype, {
   /**
@@ -62,7 +103,6 @@ Object.defineProperties(MetadataClass.prototype, {
    * @memberof MetadataClass.prototype
    * @type {Object.<String, MetadataClassProperty>}
    * @readonly
-   * @private
    */
   properties: {
     get: function () {
@@ -91,7 +131,6 @@ Object.defineProperties(MetadataClass.prototype, {
    * @memberof MetadataClass.prototype
    * @type {String}
    * @readonly
-   * @private
    */
   id: {
     get: function () {
@@ -105,7 +144,6 @@ Object.defineProperties(MetadataClass.prototype, {
    * @memberof MetadataClass.prototype
    * @type {String}
    * @readonly
-   * @private
    */
   name: {
     get: function () {
@@ -119,7 +157,6 @@ Object.defineProperties(MetadataClass.prototype, {
    * @memberof MetadataClass.prototype
    * @type {String}
    * @readonly
-   * @private
    */
   description: {
     get: function () {
@@ -128,12 +165,11 @@ Object.defineProperties(MetadataClass.prototype, {
   },
 
   /**
-   * Extras in the JSON object.
+   * Extra user-defined properties.
    *
    * @memberof MetadataClass.prototype
    * @type {*}
    * @readonly
-   * @private
    */
   extras: {
     get: function () {
@@ -142,12 +178,11 @@ Object.defineProperties(MetadataClass.prototype, {
   },
 
   /**
-   * Extensions in the JSON object.
+   * An object containing extensions.
    *
    * @memberof MetadataClass.prototype
    * @type {Object}
    * @readonly
-   * @private
    */
   extensions: {
     get: function () {