@cesium/engine 22.3.0 → 23.0.0

package/Source/Scene/MetadataClassProperty.js

@@ -10,7 +10,9 @@ import Matrix2 from "../Core/Matrix2.js";
 import Matrix3 from "../Core/Matrix3.js";
 import Matrix4 from "../Core/Matrix4.js";
 import MetadataType from "./MetadataType.js";
-import MetadataComponentType from "./MetadataComponentType.js";
+import MetadataComponentType, {
+  ScalarCategories,
+} from "./MetadataComponentType.js";
 
 /**
  * A metadata property, as part of a {@link MetadataClass}.
@@ -31,8 +33,8 @@ import MetadataComponentType from "./MetadataComponentType.js";
  * @param {number|number[]|number[][]} [options.max] A number or an array of numbers storing the maximum allowable value of this property. Only defined when type is a numeric type.
  * @param {number|number[]|number[][]} [options.offset] The offset to be added to property values as part of the value transform.
  * @param {number|number[]|number[][]} [options.scale] The scale to be multiplied to property values as part of the value transform.
- * @param {boolean|number|string|Array} [options.noData] The no-data sentinel value that represents null values.
- * @param {boolean|number|string|Array} [options.default] A default value to use when an entity's property value is not defined.
+ * @param {number|string|Array} [options.noData] The no-data sentinel value that represents null values.
+ * @param {number|string|Array} [options.default] A default value to use when an entity's property value is not defined.
  * @param {boolean} [options.required=false] Whether the property is required.
  * @param {string} [options.name] The name of the property.
  * @param {string} [options.description] The description of the property.
@@ -59,8 +61,8 @@ function MetadataClassProperty(options) {
 
   const normalized =
     defined(componentType) &&
-    MetadataComponentType.isIntegerType(componentType) &&
-    (options.normalized ?? false);
+    (options.normalized ?? false) &&
+    MetadataComponentType.isIntegerType(componentType);
 
   // Basic information about this property
   this._id = id;
@@ -369,7 +371,7 @@ Object.defineProperties(MetadataClassProperty.prototype, {
    * The no-data sentinel value that represents null values
    *
    * @memberof MetadataClassProperty.prototype
-   * @type {boolean|number|string|Array}
+   * @type {number|string|Array}
    * @readonly
    */
   noData: {
@@ -382,7 +384,7 @@ Object.defineProperties(MetadataClassProperty.prototype, {
    * A default value to use when an entity's property value is not defined.
    *
    * @memberof MetadataClassProperty.prototype
-   * @type {boolean|number|string|Array}
+   * @type {number|string|Array}
    * @readonly
    */
   default: {
@@ -1188,4 +1190,207 @@ MetadataClassProperty.valueTransformInPlace = function (
   return values;
 };
 
+/**
+ * Determines the byte size of a single property element.
+ * For example, if the metadata type is VEC3 and the component type is FLOAT32, this would return 12 bytes.
+ *
+ * @returns {number} The byte size of a single property element.
+ *
+ * @private
+ */
+MetadataClassProperty.prototype.bytesPerElement = function () {
+  const type = this.type;
+  const valueType = this.valueType;
+  const componentCount = MetadataType.getComponentCount(type);
+  const arrayLength = this.isArray ? this.arrayLength : 1;
+  const bytesPerComponent = MetadataComponentType.getSizeInBytes(valueType);
+  return componentCount * arrayLength * bytesPerComponent;
+};
+
+/**
+ * Determines whether this property can be stored in a texture, given the property's datatype and the number of
+ * texture channels dedicated property value.
+ *
+ * @param {Number} channelsLength The number of texture channels to pack each property value into
+ * @returns {boolean} true if the property can be stored in a texture with the given number of channels, false otherwise
+ *
+ * @private
+ */
+MetadataClassProperty.prototype.isGpuCompatible = function (channelsLength) {
+  //>>includeStart('debug', pragmas.debug);
+  if (!defined(channelsLength) || channelsLength <= 0) {
+    throw new DeveloperError("channelsLength must be a positive number.");
+  }
+  //>>includeEnd('debug');
+
+  const type = this.type;
+
+  if (this.isVariableLengthArray) {
+    return false;
+  }
+
+  if (type === MetadataType.STRING) {
+    return false;
+  }
+
+  // For the time being, boolean properties are not considered GPU compatible, because they are
+  // packed as bitstreams and the texture-unpacking logic does not currently support this.
+  if (type === MetadataType.BOOLEAN) {
+    return false;
+  }
+
+  // For all other properties, make sure the components fit in the sampled channels.
+  // (Note that it's possible to treat 64-bit types as two 32-bit components, but for now that's not supported)
+  const elementSizeInBytes = this.bytesPerElement();
+  if (elementSizeInBytes > channelsLength) {
+    return false;
+  }
+
+  return true;
+};
+
+const floatTypesByComponentCount = [undefined, "float", "vec2", "vec3", "vec4"];
+
+const integerTypesByComponentCount = [
+  undefined,
+  "int",
+  "ivec2",
+  "ivec3",
+  "ivec4",
+];
+
+const unsignedIntegerTypesByComponentCount = [
+  undefined,
+  "uint",
+  "uvec2",
+  "uvec3",
+  "uvec4",
+];
+
+// Map from scalar component type to the GLSL function used to reinterpret from uint bits to the scalar type
+const uintBitsToScalarType = {
+  [ScalarCategories.FLOAT]: "uintBitsToFloat",
+  [ScalarCategories.INTEGER]: "int",
+  [ScalarCategories.UNSIGNED_INTEGER]: "",
+};
+
+MetadataClassProperty.prototype.getGlslTypeWebGL1 = function () {
+  let componentCount = MetadataType.getComponentCount(this.type);
+  if (this.isArray) {
+    // fixed-sized arrays of length 2-4 UINT8s are represented as vectors as the
+    // shader since those are more useful in GLSL.
+    componentCount = this.arrayLength;
+  }
+
+  // Normalized UINT8 properties are float types in the shader
+  if (this.normalized) {
+    return floatTypesByComponentCount[componentCount];
+  }
+
+  // other UINT8-based properties are represented as integer types.
+  return integerTypesByComponentCount[componentCount];
+};
+
+MetadataClassProperty.prototype.getGlslType = function () {
+  const valueType = this.valueType;
+
+  let componentCount = MetadataType.getComponentCount(this.type);
+  const arrayLength = this.isArray ? this.arrayLength : 1;
+  componentCount *= arrayLength;
+
+  // Normalized fields are integers represented as float types ([0, 1] or [-1, 1] depending if signed)
+  if (!MetadataComponentType.isIntegerType(valueType) || this.normalized) {
+    return floatTypesByComponentCount[componentCount];
+  }
+
+  if (MetadataComponentType.isUnsignedIntegerType(valueType)) {
+    return unsignedIntegerTypesByComponentCount[componentCount];
+  }
+
+  return integerTypesByComponentCount[componentCount];
+};
+
+MetadataClassProperty.prototype.unpackTextureInShader = function (
+  sampledTextureExpression,
+  channelsString,
+  metadataVariableName,
+  shaderLines,
+) {
+  const glslType = this.getGlslType();
+  const valueType = this.valueType;
+  const numChannels = channelsString.length;
+  const type = this.type;
+
+  // Calculate total number of components
+  // (e.g. a length-2 fixed-sized array of VEC2 has 4 components - isGpuCompatible checks this fits in the channels)
+  const componentCount =
+    MetadataType.getComponentCount(type) *
+    (this.isArray ? this.arrayLength : 1);
+  const channelsPerComponent = Math.floor(numChannels / componentCount);
+
+  const rawChannelsName = `${metadataVariableName}_rawChannels`;
+  const rawBitsName = `${metadataVariableName}_rawBits`;
+  const unpackedValueName = `${metadataVariableName}_unpackedValue`;
+
+  const declareUnpackedValueLine = `${glslType} ${unpackedValueName};`;
+  const declareRawBitsLine = `uint ${rawBitsName};`;
+  shaderLines.push(declareUnpackedValueLine);
+  shaderLines.push(declareRawBitsLine);
+
+  // Sample all (specified) channels of the texture
+  const assignRawValuesLine = `${floatTypesByComponentCount[numChannels]} ${rawChannelsName} = ${sampledTextureExpression};`;
+  shaderLines.push(assignRawValuesLine);
+
+  const castFunction =
+    uintBitsToScalarType[MetadataComponentType.category(valueType)];
+  const hasMultipleComponents = componentCount > 1;
+
+  // Unpack each component of the output property from the raw channel values
+  // E.g. if the output type is a vec2, and 4 channels are given, unpack x from `rg` and y from `ba`
+  for (let i = 0; i < componentCount; i++) {
+    const channelSlice = "rgba".slice(
+      i * channelsPerComponent,
+      (i + 1) * channelsPerComponent,
+    );
+    const subChannels = numChannels > 1 ? `.${channelSlice}` : "";
+    const assignRawBitsLine = `${rawBitsName} = czm_unpackTexture(${rawChannelsName}${subChannels});`;
+
+    let indexExpression = "";
+    if (hasMultipleComponents) {
+      indexExpression = `[${i}]`;
+    }
+
+    let normalize = "";
+    let toFloatIfNormalize = "";
+    if (this.normalized) {
+      const maxValue = MetadataComponentType.getMaximum(valueType);
+      normalize = ` * ${1.0 / Number(maxValue)}`;
+      toFloatIfNormalize = "float";
+    }
+
+    const assignUnpackedValueLine = `${unpackedValueName}${indexExpression} = ${toFloatIfNormalize}(${castFunction}(${rawBitsName}))${normalize};`;
+
+    shaderLines.push(assignRawBitsLine);
+    shaderLines.push(assignUnpackedValueLine);
+  }
+
+  return unpackedValueName;
+};
+
+// In WebGL 1, we limit property texture support to UINT8 properties.
+MetadataClassProperty.prototype.unpackTextureInShaderWebGL1 = function (
+  sampledTextureExpression,
+) {
+  // no unpacking needed if for normalized types
+  if (this.normalized) {
+    return sampledTextureExpression;
+  }
+
+  // integer types are read from the texture as normalized float values.
+  // these need to be rescaled to [0, 255] and cast to the appropriate integer
+  // type.
+  const glslType = this.getGlslTypeWebGL1();
+  return `${glslType}(255.0 * ${sampledTextureExpression})`;
+};
+
 export default MetadataClassProperty;

package/Source/Scene/MetadataComponentType.js

@@ -3,6 +3,7 @@ import Check from "../Core/Check.js";
 import ComponentDatatype from "../Core/ComponentDatatype.js";
 import DeveloperError from "../Core/DeveloperError.js";
 import FeatureDetection from "../Core/FeatureDetection.js";
+import defined from "../Core/defined.js";
 
 /**
  * An enum of metadata component types.
@@ -54,18 +55,14 @@ const MetadataComponentType = {
    */
   UINT32: "UINT32",
   /**
-   * A 64-bit signed integer. This type requires BigInt support.
-   *
-   * @see FeatureDetection.supportsBigInt
+   * A 64-bit signed integer.
    *
    * @type {string}
    * @constant
    */
   INT64: "INT64",
   /**
-   * A 64-bit signed integer. This type requires BigInt support
-   *
-   * @see FeatureDetection.supportsBigInt
+   * A 64-bit signed integer.
    *
    * @type {string}
    * @constant
@@ -87,11 +84,89 @@ const MetadataComponentType = {
   FLOAT64: "FLOAT64",
 };
 
+export const ScalarCategories = {
+  INTEGER: "int",
+  UNSIGNED_INTEGER: "uint",
+  FLOAT: "float",
+};
+
+MetadataComponentType.typeInfo = {
+  INT8: {
+    vectorCompatible: true,
+    size: 1,
+    maximumValue: 127,
+    minimumValue: -128,
+    category: ScalarCategories.INTEGER,
+  },
+  UINT8: {
+    vectorCompatible: true,
+    size: 1,
+    maximumValue: 255,
+    minimumValue: 0,
+    category: ScalarCategories.UNSIGNED_INTEGER,
+  },
+  INT16: {
+    vectorCompatible: true,
+    size: 2,
+    maximumValue: 32767,
+    minimumValue: -32768,
+    category: ScalarCategories.INTEGER,
+  },
+  UINT16: {
+    vectorCompatible: true,
+    size: 2,
+    maximumValue: 65535,
+    minimumValue: 0,
+    category: ScalarCategories.UNSIGNED_INTEGER,
+  },
+  INT32: {
+    vectorCompatible: true,
+    size: 4,
+    maximumValue: 2147483647,
+    minimumValue: -2147483648,
+    category: ScalarCategories.INTEGER,
+  },
+  UINT32: {
+    vectorCompatible: true,
+    size: 4,
+    maximumValue: 4294967295,
+    minimumValue: 0,
+    category: ScalarCategories.UNSIGNED_INTEGER,
+  },
+  INT64: {
+    vectorCompatible: false,
+    size: 8,
+    maximumValue: BigInt("9223372036854775807"),
+    minimumValue: BigInt("-9223372036854775808"),
+    category: ScalarCategories.INTEGER,
+  },
+  UINT64: {
+    vectorCompatible: false,
+    size: 8,
+    maximumValue: BigInt("18446744073709551615"),
+    minimumValue: BigInt(0),
+    category: ScalarCategories.UNSIGNED_INTEGER,
+  },
+  FLOAT32: {
+    vectorCompatible: true,
+    size: 4,
+    maximumValue: 340282346638528859811704183484516925440.0,
+    minimumValue: -340282346638528859811704183484516925440.0,
+    category: ScalarCategories.FLOAT,
+  },
+  FLOAT64: {
+    vectorCompatible: true,
+    size: 8,
+    maximumValue: Number.MAX_VALUE,
+    minimumValue: -Number.MAX_VALUE,
+    category: ScalarCategories.FLOAT,
+  },
+};
+
 /**
  * Gets the minimum value for the numeric type.
  * <p>
- * Returns a BigInt for the INT64 and UINT64 types if BigInt is supported on this platform.
- * Otherwise an approximate number is returned.
+ * Returns a BigInt for the INT64 and UINT64 types.
  * </p>
  *
  * @param {MetadataComponentType} type The type.
@@ -100,46 +175,21 @@ const MetadataComponentType = {
  * @private
  */
 MetadataComponentType.getMinimum = function (type) {
+  const typeInfo = MetadataComponentType.typeInfo[type];
+
   //>>includeStart('debug', pragmas.debug);
-  Check.typeOf.string("type", type);
+  if (!defined(typeInfo)) {
+    throw new DeveloperError(`Invalid MetadataComponentType: ${type}`);
+  }
   //>>includeEnd('debug');
 
-  switch (type) {
-    case MetadataComponentType.INT8:
-      return -128;
-    case MetadataComponentType.UINT8:
-      return 0;
-    case MetadataComponentType.INT16:
-      return -32768;
-    case MetadataComponentType.UINT16:
-      return 0;
-    case MetadataComponentType.INT32:
-      return -2147483648;
-    case MetadataComponentType.UINT32:
-      return 0;
-    case MetadataComponentType.INT64:
-      if (FeatureDetection.supportsBigInt()) {
-        return BigInt("-9223372036854775808");
-      }
-      return -Math.pow(2, 63);
-    case MetadataComponentType.UINT64:
-      if (FeatureDetection.supportsBigInt()) {
-        return BigInt(0);
-      }
-      return 0;
-    case MetadataComponentType.FLOAT32:
-      // Maximum 32-bit floating point number. This value will be converted to the nearest 64-bit Number
-      return -340282346638528859811704183484516925440.0;
-    case MetadataComponentType.FLOAT64:
-      return -Number.MAX_VALUE;
-  }
+  return typeInfo.minimumValue;
 };
 
 /**
  * Gets the maximum value for the numeric type.
  * <p>
- * Returns a BigInt for the INT64 and UINT64 types if BigInt is supported on this platform.
- * Otherwise an approximate number is returned.
+ * Returns a BigInt for the INT64 and UINT64 types.
  * </p>
  *
  * @param {MetadataComponentType} type The type.
@@ -148,41 +198,15 @@ MetadataComponentType.getMinimum = function (type) {
  * @private
  */
 MetadataComponentType.getMaximum = function (type) {
+  const typeInfo = MetadataComponentType.typeInfo[type];
+
   //>>includeStart('debug', pragmas.debug);
-  Check.typeOf.string("type", type);
+  if (!defined(typeInfo)) {
+    throw new DeveloperError(`Invalid MetadataComponentType: ${type}`);
+  }
   //>>includeEnd('debug');
 
-  switch (type) {
-    case MetadataComponentType.INT8:
-      return 127;
-    case MetadataComponentType.UINT8:
-      return 255;
-    case MetadataComponentType.INT16:
-      return 32767;
-    case MetadataComponentType.UINT16:
-      return 65535;
-    case MetadataComponentType.INT32:
-      return 2147483647;
-    case MetadataComponentType.UINT32:
-      return 4294967295;
-    case MetadataComponentType.INT64:
-      if (FeatureDetection.supportsBigInt()) {
-        // Need to initialize with a string otherwise the value will be 9223372036854775808
-        return BigInt("9223372036854775807");
-      }
-      return Math.pow(2, 63) - 1;
-    case MetadataComponentType.UINT64:
-      if (FeatureDetection.supportsBigInt()) {
-        // Need to initialize with a string otherwise the value will be 18446744073709551616
-        return BigInt("18446744073709551615");
-      }
-      return Math.pow(2, 64) - 1;
-    case MetadataComponentType.FLOAT32:
-      // Maximum 32-bit floating point number
-      return 340282346638528859811704183484516925440.0;
-    case MetadataComponentType.FLOAT64:
-      return Number.MAX_VALUE;
-  }
+  return typeInfo.maximumValue;
 };
 
 /**
@@ -194,23 +218,14 @@ MetadataComponentType.getMaximum = function (type) {
  * @private
  */
 MetadataComponentType.isIntegerType = function (type) {
+  const typeInfo = MetadataComponentType.typeInfo[type];
   //>>includeStart('debug', pragmas.debug);
-  Check.typeOf.string("type", type);
+  if (!defined(typeInfo)) {
+    throw new DeveloperError(`Invalid MetadataComponentType: ${type}`);
+  }
   //>>includeEnd('debug');
 
-  switch (type) {
-    case MetadataComponentType.INT8:
-    case MetadataComponentType.UINT8:
-    case MetadataComponentType.INT16:
-    case MetadataComponentType.UINT16:
-    case MetadataComponentType.INT32:
-    case MetadataComponentType.UINT32:
-    case MetadataComponentType.INT64:
-    case MetadataComponentType.UINT64:
-      return true;
-    default:
-      return false;
-  }
+  return typeInfo.category !== ScalarCategories.FLOAT;
 };
 
 /**
@@ -222,19 +237,14 @@ MetadataComponentType.isIntegerType = function (type) {
  * @private
  */
 MetadataComponentType.isUnsignedIntegerType = function (type) {
+  const typeInfo = MetadataComponentType.typeInfo[type];
   //>>includeStart('debug', pragmas.debug);
-  Check.typeOf.string("type", type);
+  if (!defined(typeInfo)) {
+    throw new DeveloperError(`Invalid MetadataComponentType: ${type}`);
+  }
   //>>includeEnd('debug');
 
-  switch (type) {
-    case MetadataComponentType.UINT8:
-    case MetadataComponentType.UINT16:
-    case MetadataComponentType.UINT32:
-    case MetadataComponentType.UINT64:
-      return true;
-    default:
-      return false;
-  }
+  return typeInfo.category === ScalarCategories.UNSIGNED_INTEGER;
 };
 
 /**
@@ -246,23 +256,31 @@ MetadataComponentType.isUnsignedIntegerType = function (type) {
  * @private
  */
 MetadataComponentType.isVectorCompatible = function (type) {
+  const typeInfo = MetadataComponentType.typeInfo[type];
+
   //>>includeStart('debug', pragmas.debug);
-  Check.typeOf.string("type", type);
+  if (!defined(typeInfo)) {
+    throw new DeveloperError(`Invalid MetadataComponentType: ${type}`);
+  }
   //>>includeEnd('debug');
 
-  switch (type) {
-    case MetadataComponentType.INT8:
-    case MetadataComponentType.UINT8:
-    case MetadataComponentType.INT16:
-    case MetadataComponentType.UINT16:
-    case MetadataComponentType.INT32:
-    case MetadataComponentType.UINT32:
-    case MetadataComponentType.FLOAT32:
-    case MetadataComponentType.FLOAT64:
-      return true;
-    default:
-      return false;
+  return typeInfo.vectorCompatible;
+};
+
+/**
+ * Gets the category of the numeric type (signed integer, unsigned integer, or float).
+ * @param {MetadataComponentType} type The type.
+ * @returns {ScalarCategories} The category.
+ */
+MetadataComponentType.category = function (type) {
+  const typeInfo = MetadataComponentType.typeInfo[type];
+  //>>includeStart('debug', pragmas.debug);
+  if (!defined(typeInfo)) {
+    throw new DeveloperError(`Invalid MetadataComponentType: ${type}`);
   }
+  //>>includeEnd('debug');
+
+  return typeInfo.category;
 };
 
 /**
@@ -380,24 +398,7 @@ MetadataComponentType.getSizeInBytes = function (type) {
   Check.typeOf.string("type", type);
   //>>includeEnd('debug');
 
-  switch (type) {
-    case MetadataComponentType.INT8:
-    case MetadataComponentType.UINT8:
-      return 1;
-    case MetadataComponentType.INT16:
-    case MetadataComponentType.UINT16:
-      return 2;
-    case MetadataComponentType.INT32:
-    case MetadataComponentType.UINT32:
-      return 4;
-    case MetadataComponentType.INT64:
-    case MetadataComponentType.UINT64:
-      return 8;
-    case MetadataComponentType.FLOAT32:
-      return 4;
-    case MetadataComponentType.FLOAT64:
-      return 8;
-  }
+  return MetadataComponentType.typeInfo[type].size;
 };
 
 /**
@@ -466,4 +467,38 @@ MetadataComponentType.toComponentDatatype = function (type) {
   }
 };
 
+/**
+ * Gets a function for setting values of the given component type on a DataView.
+ *
+ * @param {DataView} view The DataView.
+ * @param {MetadataComponentType} componentType The component type.
+ * @returns {Function} The setter function.
+ *
+ * @private
+ */
+MetadataComponentType.getDataViewSetter = function (view, componentType) {
+  const setters = {
+    [MetadataComponentType.UINT8]: view.setUint8.bind(view),
+    [MetadataComponentType.INT8]: view.setInt8.bind(view),
+    [MetadataComponentType.UINT16]: (offset, value) =>
+      view.setUint16(offset, value, true /* little-endian */),
+    [MetadataComponentType.INT16]: (offset, value) =>
+      view.setInt16(offset, value, true),
+    [MetadataComponentType.UINT32]: (offset, value) =>
+      view.setUint32(offset, value, true),
+    [MetadataComponentType.INT32]: (offset, value) =>
+      view.setInt32(offset, value, true),
+    [MetadataComponentType.FLOAT32]: (offset, value) =>
+      view.setFloat32(offset, value, true),
+    [MetadataComponentType.FLOAT64]: (offset, value) =>
+      view.setFloat64(offset, value, true),
+    [MetadataComponentType.UINT64]: (offset, value) =>
+      view.setBigUint64(offset, BigInt(value), true),
+    [MetadataComponentType.INT64]: (offset, value) =>
+      view.setBigInt64(offset, BigInt(value), true),
+  };
+
+  return setters[componentType];
+};
+
 export default Object.freeze(MetadataComponentType);