@cesium/engine 23.0.1 → 25.0.0

package/Source/Scene/GltfVertexBufferLoader.js

@@ -135,7 +135,6 @@ class GltfVertexBufferLoader extends ResourceLoader {
   /**
    * The cache key of the resource.
    *
-   * @memberof GltfVertexBufferLoader.prototype
    *
    * @type {string}
    * @readonly
@@ -148,7 +147,6 @@ class GltfVertexBufferLoader extends ResourceLoader {
   /**
    * The vertex buffer. This is only defined when <code>loadAsTypedArray</code> is false.
    *
-   * @memberof GltfVertexBufferLoader.prototype
    *
    * @type {Buffer}
    * @readonly
@@ -161,7 +159,6 @@ class GltfVertexBufferLoader extends ResourceLoader {
   /**
    * The typed array containing vertex buffer data. This is only defined when <code>loadAsTypedArray</code> is true.
    *
-   * @memberof GltfVertexBufferLoader.prototype
    *
    * @type {Uint8Array}
    * @readonly
@@ -174,7 +171,6 @@ class GltfVertexBufferLoader extends ResourceLoader {
   /**
    * Information about the quantized vertex attribute after Draco decode.
    *
-   * @memberof GltfVertexBufferLoader.prototype
    *
    * @type {ModelComponents.Quantization}
    * @readonly

package/Source/Scene/HeightReference.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 /**
  * Represents the position relative to the terrain.
  *
@@ -54,7 +56,9 @@ const HeightReference = {
   RELATIVE_TO_3D_TILE: 6,
 };
 
-export default Object.freeze(HeightReference);
+Object.freeze(HeightReference);
+
+export default HeightReference;
 
 /**
  * Returns true if the height should be clamped to the surface

package/Source/Scene/HorizontalOrigin.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 /**
  * The horizontal location of an origin relative to an object, e.g., a {@link Billboard}
  * or {@link Label}.  For example, setting the horizontal origin to <code>LEFT</code>
@@ -38,4 +40,7 @@ const HorizontalOrigin = {
    */
   RIGHT: -1,
 };
-export default Object.freeze(HorizontalOrigin);
+
+Object.freeze(HorizontalOrigin);
+
+export default HorizontalOrigin;

package/Source/Scene/ITwinData.js

@@ -138,6 +138,7 @@ ITwinData.createTilesetForRealityDataId = async function ({
     ITwinPlatform.RealityDataType.PNTS,
     ITwinPlatform.RealityDataType.RealityMesh3DTiles,
     ITwinPlatform.RealityDataType.Terrain3DTiles,
+    ITwinPlatform.RealityDataType.GaussianSplat3DTiles,
   ];
 
   if (!supportedRealityDataTypes.includes(type)) {

package/Source/Scene/ImageryProvider.js

@@ -5,7 +5,7 @@ import loadKTX2 from "../Core/loadKTX2.js";
 import Resource from "../Core/Resource.js";
 
 /**
- * @typedef {HTMLImageElement|HTMLCanvasElement|ImageBitmap} ImageryTypes
+ * @typedef {HTMLImageElement|HTMLCanvasElement|ImageBitmap|OffscreenCanvas} ImageryTypes
  *
  * The format in which {@link ImageryProvider} methods return an image may
  * vary by provider, configuration, or server settings.  Most common are

package/Source/Scene/ImageryState.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 /**
  * @private
  */
@@ -11,4 +13,7 @@ const ImageryState = {
   INVALID: 6,
   PLACEHOLDER: 7,
 };
-export default Object.freeze(ImageryState);
+
+Object.freeze(ImageryState);
+
+export default ImageryState;

package/Source/Scene/ImplicitSubdivisionScheme.js

@@ -45,4 +45,6 @@ ImplicitSubdivisionScheme.getBranchingFactor = function (subdivisionScheme) {
   }
 };
 
-export default Object.freeze(ImplicitSubdivisionScheme);
+Object.freeze(ImplicitSubdivisionScheme);
+
+export default ImplicitSubdivisionScheme;

package/Source/Scene/InstanceAttributeSemantic.js

@@ -76,4 +76,6 @@ InstanceAttributeSemantic.fromGltfSemantic = function (gltfSemantic) {
   return undefined;
 };
 
-export default Object.freeze(InstanceAttributeSemantic);
+Object.freeze(InstanceAttributeSemantic);
+
+export default InstanceAttributeSemantic;

package/Source/Scene/IonWorldImageryStyle.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 // Note, these values map directly to ion asset ids.
 
 /**
@@ -30,4 +32,7 @@ const IonWorldImageryStyle = {
    */
   ROAD: 4,
 };
-export default Object.freeze(IonWorldImageryStyle);
+
+Object.freeze(IonWorldImageryStyle);
+
+export default IonWorldImageryStyle;

package/Source/Scene/JobType.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 /**
  * @private
  */
@@ -7,4 +9,7 @@ const JobType = {
   BUFFER: 2,
   NUMBER_OF_JOB_TYPES: 3,
 };
-export default Object.freeze(JobType);
+
+Object.freeze(JobType);
+
+export default JobType;

package/Source/Scene/Label.js

@@ -1186,6 +1186,38 @@ Object.defineProperties(Label.prototype, {
       }
     },
   },
+
+  /**
+   * When <code>true</code>, this label is ready to render, i.e., the glyphs have been mapped and the WebGL resources are created. This property is exposed for testing purposes.
+   * @memberof Label.prototype
+   * @type {boolean}
+   * @readonly
+   * @private
+   */
+  ready: {
+    get: function () {
+      if (this._rebindAllGlyphs || this._repositionAllGlyphs) {
+        return false;
+      }
+
+      if (
+        defined(this._backgroundBillboard) &&
+        !this._backgroundBillboard.ready
+      ) {
+        return false;
+      }
+
+      const glyphs = this._glyphs;
+      for (let i = 0, len = glyphs.length; i < len; i++) {
+        const glyph = glyphs[i];
+        if (defined(glyph.billboard) && !glyph.billboard.ready) {
+          return false;
+        }
+      }
+
+      return true;
+    },
+  },
 });
 
 Label.prototype._updateClamping = function () {

package/Source/Scene/LabelCollection.js

@@ -85,6 +85,8 @@ function getWhitePixelBillboard(billboardCollection, labelCollection) {
   });
 
   billboard.setImageTexture(billboardTexture);
+  billboard._positionFromParent = true;
+  billboard._labelTranslate = new Cartesian2();
 
   return billboard;
 }
@@ -288,6 +290,9 @@ function rebindAllGlyphs(labelCollection, label) {
     billboard.horizontalOrigin = HorizontalOrigin.LEFT;
     billboard.verticalOrigin = label._verticalOrigin;
     billboard.heightReference = label._heightReference;
+    if (defined(label._clampedPosition)) {
+      billboard._clampedPosition = label._clampedPosition;
+    }
     billboard.scale = label.totalScale;
     billboard.pickPrimitive = label;
     billboard.id = label._id;
@@ -342,6 +347,9 @@ function updateBackgroundBillboard(
   backgroundBillboard.horizontalOrigin = HorizontalOrigin.LEFT;
   backgroundBillboard.verticalOrigin = label._verticalOrigin;
   backgroundBillboard.heightReference = label._heightReference;
+  if (defined(label._clampedPosition)) {
+    backgroundBillboard._clampedPosition = label._clampedPosition;
+  }
   backgroundBillboard.scale = label.totalScale;
   backgroundBillboard.pickPrimitive = label;
   backgroundBillboard.id = label._id;
@@ -493,6 +501,12 @@ function repositionAllGlyphs(label) {
         glyph.billboard._labelDimensions.x = totalLineWidth;
         glyph.billboard._labelDimensions.y = totalLineHeight;
         glyph.billboard._labelHorizontalOrigin = horizontalOrigin;
+        if (isHeightReferenceClamp(label.heightReference)) {
+          glyph.billboard._labelTranslate = Cartesian2.clone(
+            glyphPixelOffset,
+            glyph.billboard._labelTranslate,
+          );
+        }
       }
 
       //Compute the next x offset taking into account the kerning performed
@@ -536,19 +550,6 @@ function repositionAllGlyphs(label) {
       backgroundBillboard._labelTranslate,
     );
   }
-
-  if (isHeightReferenceClamp(label.heightReference)) {
-    for (let glyphIndex = 0; glyphIndex < glyphLength; ++glyphIndex) {
-      const glyph = glyphs[glyphIndex];
-      const billboard = glyph.billboard;
-      if (defined(billboard)) {
-        billboard._labelTranslate = Cartesian2.clone(
-          glyphPixelOffset,
-          billboard._labelTranslate,
-        );
-      }
-    }
-  }
 }
 
 function destroyLabel(labelCollection, label) {

package/Source/Scene/LabelStyle.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 /**
  * Describes how to draw a label.
  *
@@ -30,4 +32,7 @@ const LabelStyle = {
    */
   FILL_AND_OUTLINE: 2,
 };
-export default Object.freeze(LabelStyle);
+
+Object.freeze(LabelStyle);
+
+export default LabelStyle;

package/Source/Scene/MapMode2D.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 /**
  * Describes how the map will operate in 2D.
  *
@@ -20,4 +22,7 @@ const MapMode2D = {
    */
   INFINITE_SCROLL: 1,
 };
-export default Object.freeze(MapMode2D);
+
+Object.freeze(MapMode2D);
+
+export default MapMode2D;

package/Source/Scene/Material.js

@@ -354,6 +354,7 @@ function Material(options) {
 
     /**
      * The {@link TextureMinificationFilter} to apply to this material's textures.
+     * @memberof Material.prototype
      * @type {TextureMinificationFilter}
      * @default TextureMinificationFilter.LINEAR
      */
@@ -368,6 +369,7 @@ function Material(options) {
 
     /**
      * The {@link TextureMagnificationFilter} to apply to this material's textures.
+     * @memberof Material.prototype
      * @type {TextureMagnificationFilter}
      * @default TextureMagnificationFilter.LINEAR
      */

package/Source/Scene/Megatexture.js

@@ -158,6 +158,7 @@ function Megatexture(
 Object.defineProperties(Megatexture.prototype, {
   /**
    * Gets or sets the nearest sampling flag.
+   * @memberof Megatexture.prototype
    * @type {boolean}
    */
   nearestSampling: {

package/Source/Scene/MetadataClassProperty.js

@@ -1191,21 +1191,36 @@ MetadataClassProperty.valueTransformInPlace = function (
 };
 
 /**
- * Determines the byte size of a single property element.
+ * Determines the byte size of a single property element, stored on the CPU.
  * 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;
+MetadataClassProperty.prototype.cpuBytesPerElement = function () {
+  return bytesPerElement(this, this.valueType);
+};
+
+/**
+ * Determines the byte size of a single property element, stored on the GPU.
+ * This differs from the CPU byte size if the element type is a 64-bit type that can be
+ * downcast to a 32-bit type for texture packing (only relevant for textures created from property tables).
+ *
+ * @returns {number} The byte size of a single property element on the GPU.
+ */
+MetadataClassProperty.prototype.gpuBytesPerElement = function () {
+  const packedType = MetadataComponentType.gpuComponentType(this.valueType);
+  return bytesPerElement(this, packedType);
+};
+
+function bytesPerElement(classProperty, valueType) {
+  const type = classProperty.type;
   const componentCount = MetadataType.getComponentCount(type);
-  const arrayLength = this.isArray ? this.arrayLength : 1;
+  const arrayLength = classProperty.isArray ? classProperty.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
@@ -1240,9 +1255,8 @@ MetadataClassProperty.prototype.isGpuCompatible = function (channelsLength) {
   }
 
   // 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) {
+  // (64-bit types can be downcast to 32-bit types for texture packing. In the future, support for full 64-bit types may be added)
+  if (this.gpuBytesPerElement() > channelsLength) {
     return false;
   }
 
@@ -1317,7 +1331,7 @@ MetadataClassProperty.prototype.unpackTextureInShader = function (
   shaderLines,
 ) {
   const glslType = this.getGlslType();
-  const valueType = this.valueType;
+  const valueType = MetadataComponentType.gpuComponentType(this.valueType);
   const numChannels = channelsString.length;
   const type = this.type;
 

package/Source/Scene/MetadataComponentType.js

@@ -139,6 +139,8 @@ MetadataComponentType.typeInfo = {
     maximumValue: BigInt("9223372036854775807"),
     minimumValue: BigInt("-9223372036854775808"),
     category: ScalarCategories.INTEGER,
+    downcastFunction: (value) =>
+      MetadataComponentType.clampToLimits(value, MetadataComponentType.INT32),
   },
   UINT64: {
     vectorCompatible: false,
@@ -146,6 +148,8 @@ MetadataComponentType.typeInfo = {
     maximumValue: BigInt("18446744073709551615"),
     minimumValue: BigInt(0),
     category: ScalarCategories.UNSIGNED_INTEGER,
+    downcastFunction: (value) =>
+      MetadataComponentType.clampToLimits(value, MetadataComponentType.UINT32),
   },
   FLOAT32: {
     vectorCompatible: true,
@@ -160,6 +164,7 @@ MetadataComponentType.typeInfo = {
     maximumValue: Number.MAX_VALUE,
     minimumValue: -Number.MAX_VALUE,
     category: ScalarCategories.FLOAT,
+    downcastFunction: (value) => Math.fround(value),
   },
 };
 
@@ -283,6 +288,25 @@ MetadataComponentType.category = function (type) {
   return typeInfo.category;
 };
 
+/**
+ * Gets the component type as represented on the GPU (that is, taking downcasting into account).
+ * This is different from getting the glsl variable type of an entire metadata property. This is only for a component.
+ * @param {MetadataComponentType} type The component type.
+ * @returns {MetadataComponentType} The GPU component type.
+ */
+MetadataComponentType.gpuComponentType = function (type) {
+  switch (type) {
+    case MetadataComponentType.INT64:
+      return "INT32";
+    case MetadataComponentType.UINT64:
+      return "UINT32";
+    case MetadataComponentType.FLOAT64:
+      return "FLOAT32";
+    default:
+      return type;
+  }
+};
+
 /**
  * Normalizes signed integers to the range [-1.0, 1.0] and unsigned integers to
  * the range [0.0, 1.0].
@@ -401,6 +425,52 @@ MetadataComponentType.getSizeInBytes = function (type) {
   return MetadataComponentType.typeInfo[type].size;
 };
 
+/**
+ * Clamps a value to the minimum and maximum limits of the given component type.
+ *
+ * @param {number|bigint} value The value to clamp.
+ * @param {MetadataComponentType} type The component type.
+ * @returns {number} The clamped value.
+ *
+ * @private
+ */
+MetadataComponentType.clampToLimits = function (value, type) {
+  const min = MetadataComponentType.getMinimum(type);
+  const max = MetadataComponentType.getMaximum(type);
+
+  if (typeof value === "bigint") {
+    const minBigInt = BigInt(min);
+    const maxBigInt = BigInt(max);
+
+    if (value < minBigInt) {
+      return min;
+    }
+    if (value > maxBigInt) {
+      return max;
+    }
+
+    return Number(value);
+  }
+
+  return Math.max(min, Math.min(max, value));
+};
+
+MetadataComponentType.downcastFunction = function (type) {
+  const typeInfo = MetadataComponentType.typeInfo[type];
+  //>>includeStart('debug', pragmas.debug);
+  if (!defined(typeInfo)) {
+    throw new DeveloperError("type must be a valid MetadataComponentType");
+  }
+  //>>includeEnd('debug');
+
+  const func = typeInfo.downcastFunction;
+  if (!defined(func)) {
+    return (value) => value;
+  }
+
+  return func;
+};
+
 /**
  * Gets the {@link MetadataComponentType} from a {@link ComponentDatatype}.
  *
@@ -468,37 +538,61 @@ MetadataComponentType.toComponentDatatype = function (type) {
 };
 
 /**
- * Gets a function for setting values of the given component type on a DataView.
+ * Gets functions for getting and 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.
+ * @returns {Object} An object containing the getter and setter functions.
  *
  * @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),
+MetadataComponentType.getDataViewAccessors = function (view, componentType) {
+  const accessors = {
+    [MetadataComponentType.UINT8]: {
+      get: view.getUint8.bind(view),
+      set: view.setUint8.bind(view),
+    },
+    [MetadataComponentType.INT8]: {
+      get: view.getInt8.bind(view),
+      set: view.setInt8.bind(view),
+    },
+    [MetadataComponentType.UINT16]: {
+      get: (offset) => view.getUint16(offset, true),
+      set: (offset, value) => view.setUint16(offset, value, true),
+    },
+    [MetadataComponentType.INT16]: {
+      get: (offset) => view.getInt16(offset, true),
+      set: (offset, value) => view.setInt16(offset, value, true),
+    },
+    [MetadataComponentType.UINT32]: {
+      get: (offset) => view.getUint32(offset, true),
+      set: (offset, value) => view.setUint32(offset, value, true),
+    },
+    [MetadataComponentType.INT32]: {
+      get: (offset) => view.getInt32(offset, true),
+      set: (offset, value) => view.setInt32(offset, value, true),
+    },
+    [MetadataComponentType.FLOAT32]: {
+      get: (offset) => view.getFloat32(offset, true),
+      set: (offset, value) => view.setFloat32(offset, value, true),
+    },
+    [MetadataComponentType.FLOAT64]: {
+      get: (offset) => view.getFloat64(offset, true),
+      set: (offset, value) => view.setFloat64(offset, value, true),
+    },
+    [MetadataComponentType.UINT64]: {
+      get: (offset) => view.getBigUint64(offset, true),
+      set: (offset, value) => view.setBigUint64(offset, BigInt(value), true),
+    },
+    [MetadataComponentType.INT64]: {
+      get: (offset) => view.getBigInt64(offset, true),
+      set: (offset, value) => view.setBigInt64(offset, BigInt(value), true),
+    },
   };
 
-  return setters[componentType];
+  return accessors[componentType];
 };
 
-export default Object.freeze(MetadataComponentType);
+Object.freeze(MetadataComponentType);
+
+export default MetadataComponentType;

package/Source/Scene/MetadataSchemaLoader.js

@@ -51,7 +51,6 @@ class MetadataSchemaLoader extends ResourceLoader {
   /**
    * The cache key of the resource.
    *
-   * @memberof MetadataSchemaLoader.prototype
    *
    * @type {string}
    * @readonly
@@ -64,7 +63,6 @@ class MetadataSchemaLoader extends ResourceLoader {
   /**
    * The metadata schema object.
    *
-   * @memberof MetadataSchemaLoader.prototype
    *
    * @type {MetadataSchema}
    * @readonly

package/Source/Scene/MetadataSemantic.js

@@ -1,7 +1,9 @@
+// @ts-check
+
 /**
  * An enum of built-in semantics.
  *
- * @enum MetadataSemantic
+ * @enum {string}
  *
  * @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.
@@ -150,4 +152,6 @@ const MetadataSemantic = {
   CONTENT_HORIZON_OCCLUSION_POINT: "CONTENT_HORIZON_OCCLUSION_POINT",
 };
 
-export default Object.freeze(MetadataSemantic);
+Object.freeze(MetadataSemantic);
+
+export default MetadataSemantic;

package/Source/Scene/MetadataType.js

@@ -217,4 +217,6 @@ MetadataType.getMathType = function (type) {
   }
 };
 
-export default Object.freeze(MetadataType);
+Object.freeze(MetadataType);
+
+export default MetadataType;

package/Source/Scene/Model/B3dmLoader.js

@@ -118,7 +118,6 @@ class B3dmLoader extends ResourceLoader {
   /**
    * true if textures are loaded, useful when incrementallyLoadTextures is true
    *
-   * @memberof B3dmLoader.prototype
    *
    * @type {boolean}
    * @readonly
@@ -131,7 +130,6 @@ class B3dmLoader extends ResourceLoader {
   /**
    * The cache key of the resource
    *
-   * @memberof B3dmLoader.prototype
    *
    * @type {string}
    * @readonly
@@ -144,7 +142,6 @@ class B3dmLoader extends ResourceLoader {
   /**
    * The loaded components.
    *
-   * @memberof B3dmLoader.prototype
    *
    * @type {ModelComponents.Components}
    * @readonly

package/Source/Scene/Model/CustomShaderMode.js

@@ -37,4 +37,6 @@ CustomShaderMode.getDefineName = function (customShaderMode) {
   return `CUSTOM_SHADER_${customShaderMode}`;
 };
 
-export default Object.freeze(CustomShaderMode);
+Object.freeze(CustomShaderMode);
+
+export default CustomShaderMode;

package/Source/Scene/Model/CustomShaderPipelineStage.js

@@ -730,7 +730,9 @@ function getAllPropertyIds(primitive, structuralMetadata) {
   function addUsedPropertyIds(propertyContainerIds, propertyContainers) {
     for (const id of propertyContainerIds) {
       const propertyContainer = propertyContainers[id];
-      Object.keys(propertyContainer.properties).forEach((propertyId) =>
+      const classProperties = propertyContainer.class.properties;
+
+      Object.keys(classProperties).forEach((propertyId) =>
         primitivePropertyIds.add(propertyId),
       );
     }

package/Source/Scene/Model/CustomShaderTranslucencyMode.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 /**
  * An enum for controling how {@link CustomShader} handles translucency compared with the original
  * primitive.
@@ -32,4 +34,6 @@ const CustomShaderTranslucencyMode = {
   TRANSLUCENT: 2,
 };
 
-export default Object.freeze(CustomShaderTranslucencyMode);
+Object.freeze(CustomShaderTranslucencyMode);
+
+export default CustomShaderTranslucencyMode;