@cesium/engine 6.2.0 → 8.0.0

package/Source/Scene/Composite3DTileContent.js

@@ -1,3 +1,4 @@
+import Cartesian3 from "../Core/Cartesian3.js";
 import defaultValue from "../Core/defaultValue.js";
 import defined from "../Core/defined.js";
 import destroyObject from "../Core/destroyObject.js";
@@ -347,6 +348,47 @@ Composite3DTileContent.prototype.update = function (tileset, frameState) {
   }
 };
 
+/**
+ * Find an intersection between a ray and the tile content surface that was rendered. The ray must be given in world coordinates.
+ *
+ * @param {Ray} ray The ray to test for intersection.
+ * @param {FrameState} frameState The frame state.
+ * @param {Cartesian3|undefined} [result] The intersection or <code>undefined</code> if none was found.
+ * @returns {Cartesian3|undefined} The intersection or <code>undefined</code> if none was found.
+ *
+ * @private
+ */
+Composite3DTileContent.prototype.pick = function (ray, frameState, result) {
+  if (!this._ready) {
+    return undefined;
+  }
+
+  let intersection;
+  let minDistance = Number.POSITIVE_INFINITY;
+  const contents = this._contents;
+  const length = contents.length;
+
+  for (let i = 0; i < length; ++i) {
+    const candidate = contents[i].pick(ray, frameState, result);
+
+    if (!defined(candidate)) {
+      continue;
+    }
+
+    const distance = Cartesian3.distance(ray.origin, candidate);
+    if (distance < minDistance) {
+      intersection = candidate;
+      minDistance = distance;
+    }
+  }
+
+  if (!defined(intersection)) {
+    return undefined;
+  }
+
+  return result;
+};
+
 Composite3DTileContent.prototype.isDestroyed = function () {
   return false;
 };

package/Source/Scene/DynamicAtmosphereLightingType.js

@@ -0,0 +1,56 @@
+/**
+ * Atmosphere lighting effects (sky atmosphere, ground atmosphere, fog) can be
+ * further modified with dynamic lighting from the sun or other light source
+ * that changes over time. This enum determines which light source to use.
+ *
+ * @enum {number}
+ */
+const DynamicAtmosphereLightingType = {
+  /**
+   * Do not use dynamic atmosphere lighting. Atmosphere lighting effects will
+   * be lit from directly above rather than using the scene's light source.
+   *
+   * @type {number}
+   * @constant
+   */
+  NONE: 0,
+  /**
+   * Use the scene's current light source for dynamic atmosphere lighting.
+   *
+   * @type {number}
+   * @constant
+   */
+  SCENE_LIGHT: 1,
+  /**
+   * Force the dynamic atmosphere lighting to always use the sunlight direction,
+   * even if the scene uses a different light source.
+   *
+   * @type {number}
+   * @constant
+   */
+  SUNLIGHT: 2,
+};
+
+/**
+ * Get the lighting enum from the older globe flags
+ *
+ * @param {Globe} globe The globe
+ * @return {DynamicAtmosphereLightingType} The corresponding enum value
+ *
+ * @private
+ */
+DynamicAtmosphereLightingType.fromGlobeFlags = function (globe) {
+  const lightingOn = globe.enableLighting && globe.dynamicAtmosphereLighting;
+  if (!lightingOn) {
+    return DynamicAtmosphereLightingType.NONE;
+  }
+
+  // Force sunlight
+  if (globe.dynamicAtmosphereLightingFromSun) {
+    return DynamicAtmosphereLightingType.SUNLIGHT;
+  }
+
+  return DynamicAtmosphereLightingType.SCENE_LIGHT;
+};
+
+export default Object.freeze(DynamicAtmosphereLightingType);

package/Source/Scene/Empty3DTileContent.js

@@ -150,6 +150,10 @@ Empty3DTileContent.prototype.applyStyle = function (style) {};
 
 Empty3DTileContent.prototype.update = function (tileset, frameState) {};
 
+Empty3DTileContent.prototype.pick = function (ray, frameState, result) {
+  return undefined;
+};
+
 Empty3DTileContent.prototype.isDestroyed = function () {
   return false;
 };

package/Source/Scene/Fog.js

@@ -173,6 +173,7 @@ Fog.prototype.update = function (frameState) {
     frameState.mode !== SceneMode.SCENE3D
   ) {
     frameState.fog.enabled = false;
+    frameState.fog.density = 0;
     return;
   }
 

package/Source/Scene/FrameState.js

@@ -182,6 +182,7 @@ function FrameState(context, creditDisplay, jobScheduler) {
    * @type {object}
    * @property {boolean} render <code>true</code> if the primitive should update for a render pass, <code>false</code> otherwise.
    * @property {boolean} pick <code>true</code> if the primitive should update for a picking pass, <code>false</code> otherwise.
+   * @property {boolean} pickVoxel <code>true</code> if the primitive should update for a voxel picking pass, <code>false</code> otherwise.
    * @property {boolean} depth <code>true</code> if the primitive should update for a depth only pass, <code>false</code> otherwise.
    * @property {boolean} postProcess <code>true</code> if the primitive should update for a per-feature post-process pass, <code>false</code> otherwise.
    * @property {boolean} offscreen <code>true</code> if the primitive should update for an offscreen pass, <code>false</code> otherwise.
@@ -199,6 +200,10 @@ function FrameState(context, creditDisplay, jobScheduler) {
      * @default false
      */
     pick: false,
+    /**
+     * @default false
+     */
+    pickVoxel: false,
     /**
      * @default false
      */
@@ -254,7 +259,8 @@ function FrameState(context, creditDisplay, jobScheduler) {
   /**
    * @typedef FrameState.Fog
    * @type {object}
-   * @property {boolean} enabled <code>true</code> if fog is enabled, <code>false</code> otherwise.
+   * @property {boolean} enabled <code>true</code> if fog is enabled, <code>false</code> otherwise. This affects both fog culling and rendering.
+   * @property {boolean} renderable <code>true</code> if fog should be rendered, <code>false</code> if not. This flag should be checked in combination with fog.enabled.
    * @property {number} density A positive number used to mix the color and fog color based on camera distance.
    * @property {number} sse A scalar used to modify the screen space error of geometry partially in fog.
    * @property {number} minimumBrightness The minimum brightness of terrain with fog applied.
@@ -269,11 +275,18 @@ function FrameState(context, creditDisplay, jobScheduler) {
      * @default false
      */
     enabled: false,
+    renderable: false,
     density: undefined,
     sse: undefined,
     minimumBrightness: undefined,
   };
 
+  /**
+   * The current Atmosphere
+   * @type {Atmosphere}
+   */
+  this.atmosphere = undefined;
+
   /**
    * A scalar used to vertically exaggerate the scene
    * @type {number}

package/Source/Scene/Geometry3DTileContent.js

@@ -525,6 +525,10 @@ Geometry3DTileContent.prototype.update = function (tileset, frameState) {
   }
 };
 
+Geometry3DTileContent.prototype.pick = function (ray, frameState, result) {
+  return undefined;
+};
+
 Geometry3DTileContent.prototype.isDestroyed = function () {
   return false;
 };

package/Source/Scene/Globe.js

@@ -691,8 +691,8 @@ function makeShadersDirty(globe) {
 
   const requireNormals =
     defined(globe._material) &&
-    (globe._material.shaderSource.match(/slope/) ||
-      globe._material.shaderSource.match("normalEC"));
+    (defined(globe._material.shaderSource.match(/slope/)) ||
+      defined(globe._material.shaderSource.match("normalEC")));
 
   const fragmentSources = [AtmosphereCommon, GroundAtmosphere];
   if (
@@ -1106,6 +1106,7 @@ Globe.prototype.beginFrame = function (frameState) {
     tileProvider.undergroundColor = this._undergroundColor;
     tileProvider.undergroundColorAlphaByDistance = this._undergroundColorAlphaByDistance;
     tileProvider.lambertDiffuseMultiplier = this.lambertDiffuseMultiplier;
+
     surface.beginFrame(frameState);
   }
 };

package/Source/Scene/GlobeSurfaceTileProvider.js

@@ -2502,7 +2502,9 @@ function addDrawCommandsForTile(tileProvider, tile, frameState) {
       uniformMapProperties.localizedTranslucencyRectangle
     );
 
-    // For performance, use fog in the shader only when the tile is in fog.
+    // For performance, render fog only when fog is enabled and the effect of
+    // fog would be non-negligible. This prevents the shader from running when
+    // the camera is in space, for example.
     const applyFog =
       enableFog &&
       CesiumMath.fog(tile._distance, frameState.fog.density) >

package/Source/Scene/GlobeTranslucencyState.js

@@ -930,7 +930,7 @@ GlobeTranslucencyState.prototype.pushDerivedCommands = function (
   isBlendCommand,
   frameState
 ) {
-  const picking = frameState.passes.pick;
+  const picking = frameState.passes.pick || frameState.passes.pickVoxel;
   if (picking && isBlendCommand) {
     // No need to push blend commands in the pick pass
     return;

package/Source/Scene/GltfLoader.js

@@ -179,6 +179,7 @@ const GltfLoaderState = {
  * @param {Axis} [options.forwardAxis=Axis.Z] The forward-axis of the glTF model.
  * @param {boolean} [options.loadAttributesAsTypedArray=false] Load all attributes and indices as typed arrays instead of GPU buffers. If the attributes are interleaved in the glTF they will be de-interleaved in the typed array.
  * @param {boolean} [options.loadAttributesFor2D=false] If <code>true</code>, load the positions buffer and any instanced attribute buffers as typed arrays for accurately projecting models to 2D.
+ * @param {boolean} [options.enablePick=false]  If <code>true</code>, load the positions buffer, any instanced attribute buffers, and index buffer as typed arrays for CPU-enabled picking in WebGL1.
  * @param {boolean} [options.loadIndicesForWireframe=false] If <code>true</code>, load the index buffer as both a buffer and typed array. The latter is useful for creating wireframe indices in WebGL1.
  * @param {boolean} [options.loadPrimitiveOutline=true] If <code>true</code>, load outlines from the {@link https://github.com/KhronosGroup/glTF/tree/master/extensions/2.0/Vendor/CESIUM_primitive_outline|CESIUM_primitive_outline} extension. This can be set false to avoid post-processing geometry at load time.
  * @param {boolean} [options.loadForClassification=false] If <code>true</code> and if the model has feature IDs, load the feature IDs and indices as typed arrays. This is useful for batching features for classification.
@@ -203,6 +204,7 @@ function GltfLoader(options) {
     false
   );
   const loadAttributesFor2D = defaultValue(options.loadAttributesFor2D, false);
+  const enablePick = defaultValue(options.enablePick);
   const loadIndicesForWireframe = defaultValue(
     options.loadIndicesForWireframe,
     false
@@ -234,6 +236,7 @@ function GltfLoader(options) {
   this._forwardAxis = forwardAxis;
   this._loadAttributesAsTypedArray = loadAttributesAsTypedArray;
   this._loadAttributesFor2D = loadAttributesFor2D;
+  this._enablePick = enablePick;
   this._loadIndicesForWireframe = loadIndicesForWireframe;
   this._loadPrimitiveOutline = loadPrimitiveOutline;
   this._loadForClassification = loadForClassification;
@@ -1241,6 +1244,8 @@ function loadVertexAttribute(
     !hasInstances &&
     loader._loadAttributesFor2D &&
     !frameState.scene3DOnly;
+  const loadTypedArrayForPicking =
+    isPositionAttribute && loader._enablePick && !frameState.context.webgl2;
 
   const loadTypedArrayForClassification =
     loader._loadForClassification && isFeatureIdAttribute;
@@ -1252,6 +1257,7 @@ function loadVertexAttribute(
   const outputTypedArray =
     outputTypedArrayOnly ||
     loadTypedArrayFor2D ||
+    loadTypedArrayForPicking ||
     loadTypedArrayForClassification;
 
   // Determine what to load right now:
@@ -1319,6 +1325,8 @@ function loadInstancedAttribute(
     loader._loadAttributesAsTypedArray ||
     (hasRotation && isTransformAttribute) ||
     !frameState.context.instancedArrays;
+  const loadTypedArrayForPicking =
+    loader._enablePick && !frameState.context.webgl2;
 
   const loadBuffer = !loadAsTypedArrayOnly;
 
@@ -1328,7 +1336,8 @@ function loadInstancedAttribute(
   // - the model will be projected to 2D.
   const loadFor2D = loader._loadAttributesFor2D && !frameState.scene3DOnly;
   const loadTranslationAsTypedArray =
-    isTranslationAttribute && (!hasTranslationMinMax || loadFor2D);
+    isTranslationAttribute &&
+    (!hasTranslationMinMax || loadFor2D || loadTypedArrayForPicking);
 
   const loadTypedArray = loadAsTypedArrayOnly || loadTranslationAsTypedArray;
 
@@ -1365,9 +1374,10 @@ function loadIndices(
   indices.count = accessor.count;
 
   const loadAttributesAsTypedArray = loader._loadAttributesAsTypedArray;
-  // Load the index buffer as a typed array to generate wireframes in WebGL1.
-  const loadForWireframe =
-    loader._loadIndicesForWireframe && !frameState.context.webgl2;
+  // Load the index buffer as a typed array to generate wireframes or pick in WebGL1.
+  const loadForCpuOperations =
+    (loader._loadIndicesForWireframe || loader._enablePick) &&
+    !frameState.context.webgl2;
 
   // Load the index buffer as a typed array to batch features together for classification.
   const loadForClassification = loader._loadForClassification && hasFeatureIds;
@@ -1377,7 +1387,7 @@ function loadIndices(
   const outputTypedArrayOnly = loadAttributesAsTypedArray;
   const outputBuffer = !outputTypedArrayOnly;
   const outputTypedArray =
-    loadAttributesAsTypedArray || loadForWireframe || loadForClassification;
+    loadAttributesAsTypedArray || loadForCpuOperations || loadForClassification;
 
   // Determine what to load right now:
   //

package/Source/Scene/GltfPipeline/updateVersion.js

@@ -1079,6 +1079,26 @@ function convertTechniquesToPbr(gltf, options) {
   removeExtension(gltf, "KHR_blend");
 }
 
+function assignAsBaseColor(material, baseColor) {
+  if (defined(baseColor)) {
+    if (isVec4(baseColor)) {
+      material.pbrMetallicRoughness.baseColorFactor = srgbToLinear(baseColor);
+    } else if (isTexture(baseColor)) {
+      material.pbrMetallicRoughness.baseColorTexture = baseColor;
+    }
+  }
+}
+
+function assignAsEmissive(material, emissive) {
+  if (defined(emissive)) {
+    if (isVec4(emissive)) {
+      material.emissiveFactor = emissive.slice(0, 3);
+    } else if (isTexture(emissive)) {
+      material.emissiveTexture = emissive;
+    }
+  }
+}
+
 function convertMaterialsCommonToPbr(gltf) {
   // Future work: convert KHR_materials_common lights to KHR_lights_punctual
   ForEach.material(gltf, function (material) {
@@ -1086,80 +1106,61 @@ function convertMaterialsCommonToPbr(gltf) {
       material.extensions,
       defaultValue.EMPTY_OBJECT
     ).KHR_materials_common;
+    if (!defined(materialsCommon)) {
+      // Nothing to do
+      return;
+    }
 
-    if (defined(materialsCommon)) {
-      const technique = materialsCommon.technique;
-      if (technique === "CONSTANT") {
-        // Add the KHR_materials_unlit extension
-        addExtensionsUsed(gltf, "KHR_materials_unlit");
-        material.extensions = defined(material.extensions)
-          ? material.extensions
-          : {};
-        material.extensions["KHR_materials_unlit"] = {};
-      }
-
-      const values = defined(materialsCommon.values)
-        ? materialsCommon.values
+    const values = defaultValue(materialsCommon.values, {});
+    const ambient = values.ambient;
+    const diffuse = values.diffuse;
+    const emission = values.emission;
+    const transparency = values.transparency;
+
+    // These actually exist on the extension object, not the values object despite what's shown in the spec
+    const doubleSided = materialsCommon.doubleSided;
+    const transparent = materialsCommon.transparent;
+
+    // Ignore specular and shininess for now because the conversion to PBR
+    // isn't straightforward and depends on the technique
+    initializePbrMaterial(material);
+
+    const technique = materialsCommon.technique;
+    if (technique === "CONSTANT") {
+      // Add the KHR_materials_unlit extension
+      addExtensionsUsed(gltf, "KHR_materials_unlit");
+      material.extensions = defined(material.extensions)
+        ? material.extensions
         : {};
+      material.extensions["KHR_materials_unlit"] = {};
 
-      const ambient = values.ambient;
-      const diffuse = values.diffuse;
-      const emission = values.emission;
-      const transparency = values.transparency;
-
-      // These actually exist on the extension object, not the values object despite what's shown in the spec
-      const doubleSided = materialsCommon.doubleSided;
-      const transparent = materialsCommon.transparent;
-
-      // Ignore specular and shininess for now because the conversion to PBR
-      // isn't straightforward and depends on the technique
-      initializePbrMaterial(material);
-
-      if (defined(ambient)) {
-        if (isVec4(ambient)) {
-          material.emissiveFactor = ambient.slice(0, 3);
-        } else if (isTexture(ambient)) {
-          material.emissiveTexture = ambient;
-        }
-      }
-
-      if (defined(diffuse)) {
-        if (isVec4(diffuse)) {
-          material.pbrMetallicRoughness.baseColorFactor = srgbToLinear(diffuse);
-        } else if (isTexture(diffuse)) {
-          material.pbrMetallicRoughness.baseColorTexture = diffuse;
-        }
-      }
-
-      if (defined(doubleSided)) {
-        material.doubleSided = doubleSided;
-      }
-
-      if (defined(emission)) {
-        if (isVec4(emission)) {
-          material.emissiveFactor = emission.slice(0, 3);
-        } else if (isTexture(emission)) {
-          material.emissiveTexture = emission;
-        }
-      }
-
-      if (defined(transparency)) {
-        if (defined(material.pbrMetallicRoughness.baseColorFactor)) {
-          material.pbrMetallicRoughness.baseColorFactor[3] *= transparency;
-        } else {
-          material.pbrMetallicRoughness.baseColorFactor = [
-            1,
-            1,
-            1,
-            transparency,
-          ];
-        }
-      }
+      // The CONSTANT technique does not support 'diffuse', so
+      // assign either the 'emission' or the 'ambient' as the
+      // base color
+      assignAsBaseColor(material, emission);
+      assignAsBaseColor(material, ambient);
+    } else {
+      // Assign the 'diffuse' as the base color, and
+      // the 'ambient' or 'emissive' as the emissive
+      // part if they are present.
+      assignAsBaseColor(material, diffuse);
+      assignAsEmissive(material, ambient);
+      assignAsEmissive(material, emission);
+    }
 
-      if (defined(transparent)) {
-        material.alphaMode = transparent ? "BLEND" : "OPAQUE";
+    if (defined(doubleSided)) {
+      material.doubleSided = doubleSided;
+    }
+    if (defined(transparency)) {
+      if (defined(material.pbrMetallicRoughness.baseColorFactor)) {
+        material.pbrMetallicRoughness.baseColorFactor[3] *= transparency;
+      } else {
+        material.pbrMetallicRoughness.baseColorFactor = [1, 1, 1, transparency];
       }
     }
+    if (defined(transparent)) {
+      material.alphaMode = transparent ? "BLEND" : "OPAQUE";
+    }
   });
 
   removeExtension(gltf, "KHR_materials_common");

package/Source/Scene/HeightReference.js

@@ -12,17 +12,74 @@ const HeightReference = {
   NONE: 0,
 
   /**
-   * The position is clamped to the terrain.
+   * The position is clamped to the terrain and 3D Tiles.
    * @type {number}
    * @constant
    */
   CLAMP_TO_GROUND: 1,
 
   /**
-   * The position height is the height above the terrain.
+   * The position height is the height above the terrain and 3D Tiles.
    * @type {number}
    * @constant
    */
   RELATIVE_TO_GROUND: 2,
+
+  /**
+   * The position is clamped to terain.
+   * @type {number}
+   * @constant
+   */
+  CLAMP_TO_TERRAIN: 3,
+
+  /**
+   * The position height is the height above terrain.
+   * @type {number}
+   * @constant
+   */
+  RELATIVE_TO_TERRAIN: 4,
+
+  /**
+   * The position is clamped to 3D Tiles.
+   * @type {number}
+   * @constant
+   */
+  CLAMP_TO_3D_TILE: 5,
+
+  /**
+   * The position height is the height above 3D Tiles.
+   * @type {number}
+   * @constant
+   */
+  RELATIVE_TO_3D_TILE: 6,
 };
+
 export default Object.freeze(HeightReference);
+
+/**
+ * Returns true if the height should be clamped to the surface
+ * @param {HeightReference} heightReference
+ * @returns true if the height should be clamped to the surface
+ * @private
+ */
+export function isHeightReferenceClamp(heightReference) {
+  return (
+    heightReference === HeightReference.CLAMP_TO_GROUND ||
+    heightReference === HeightReference.CLAMP_TO_3D_TILE ||
+    heightReference === HeightReference.CLAMP_TO_TERRAIN
+  );
+}
+
+/**
+ * Returns true if the height should be offset relative to the surface
+ * @param {HeightReference} heightReference
+ * @returns true if the height should be offset relative to the surface
+ * @private
+ */
+export function isHeightReferenceRelative(heightReference) {
+  return (
+    heightReference === HeightReference.RELATIVE_TO_GROUND ||
+    heightReference === HeightReference.RELATIVE_TO_3D_TILE ||
+    heightReference === HeightReference.RELATIVE_TO_TERRAIN
+  );
+}