@cesium/engine 0.1.0 → 1.0.0

package/Source/Renderer/Context.js

@@ -1,5 +1,4 @@
 import Check from "../Core/Check.js";
-import clone from "../Core/clone.js";
 import Color from "../Core/Color.js";
 import ComponentDatatype from "../Core/ComponentDatatype.js";
 import createGuid from "../Core/createGuid.js";
@@ -31,183 +30,43 @@ import TextureCache from "./TextureCache.js";
 import UniformState from "./UniformState.js";
 import VertexArray from "./VertexArray.js";
 
-function errorToString(gl, error) {
-  let message = "WebGL Error:  ";
-  switch (error) {
-    case gl.INVALID_ENUM:
-      message += "INVALID_ENUM";
-      break;
-    case gl.INVALID_VALUE:
-      message += "INVALID_VALUE";
-      break;
-    case gl.INVALID_OPERATION:
-      message += "INVALID_OPERATION";
-      break;
-    case gl.OUT_OF_MEMORY:
-      message += "OUT_OF_MEMORY";
-      break;
-    case gl.CONTEXT_LOST_WEBGL:
-      message += "CONTEXT_LOST_WEBGL lost";
-      break;
-    default:
-      message += `Unknown (${error})`;
-  }
-
-  return message;
-}
-
-function createErrorMessage(gl, glFunc, glFuncArguments, error) {
-  let message = `${errorToString(gl, error)}: ${glFunc.name}(`;
-
-  for (let i = 0; i < glFuncArguments.length; ++i) {
-    if (i !== 0) {
-      message += ", ";
-    }
-    message += glFuncArguments[i];
-  }
-  message += ");";
-
-  return message;
-}
-
-function throwOnError(gl, glFunc, glFuncArguments) {
-  const error = gl.getError();
-  if (error !== gl.NO_ERROR) {
-    throw new RuntimeError(
-      createErrorMessage(gl, glFunc, glFuncArguments, error)
-    );
-  }
-}
-
-function makeGetterSetter(gl, propertyName, logFunction) {
-  return {
-    get: function () {
-      const value = gl[propertyName];
-      logFunction(gl, `get: ${propertyName}`, value);
-      return gl[propertyName];
-    },
-    set: function (value) {
-      gl[propertyName] = value;
-      logFunction(gl, `set: ${propertyName}`, value);
-    },
-  };
-}
-
-function wrapGL(gl, logFunction) {
-  if (!defined(logFunction)) {
-    return gl;
-  }
-
-  function wrapFunction(property) {
-    return function () {
-      const result = property.apply(gl, arguments);
-      logFunction(gl, property, arguments);
-      return result;
-    };
-  }
-
-  const glWrapper = {};
-
-  // JavaScript linters normally demand that a for..in loop must directly contain an if,
-  // but in our loop below, we actually intend to iterate all properties, including
-  // those in the prototype.
-  /*eslint-disable guard-for-in*/
-  for (const propertyName in gl) {
-    const property = gl[propertyName];
-
-    // wrap any functions we encounter, otherwise just copy the property to the wrapper.
-    if (property instanceof Function) {
-      glWrapper[propertyName] = wrapFunction(property);
-    } else {
-      Object.defineProperty(
-        glWrapper,
-        propertyName,
-        makeGetterSetter(gl, propertyName, logFunction)
-      );
-    }
-  }
-  /*eslint-enable guard-for-in*/
-
-  return glWrapper;
-}
-
-function getExtension(gl, names) {
-  const length = names.length;
-  for (let i = 0; i < length; ++i) {
-    const extension = gl.getExtension(names[i]);
-    if (extension) {
-      return extension;
-    }
-  }
-
-  return undefined;
-}
-
 /**
  * @private
  * @constructor
+ *
+ * @param {HTMLCanvasElement} canvas The canvas element to which the context will be associated
+ * @param {ContextOptions} [options] Options to control WebGL settings for the context
  */
 function Context(canvas, options) {
-  // this check must use typeof, not defined, because defined doesn't work with undeclared variables.
-  if (typeof WebGLRenderingContext === "undefined") {
-    throw new RuntimeError(
-      "The browser does not support WebGL.  Visit http://get.webgl.org."
-    );
-  }
-
   //>>includeStart('debug', pragmas.debug);
   Check.defined("canvas", canvas);
   //>>includeEnd('debug');
 
-  this._canvas = canvas;
-
-  options = clone(options, true);
-  // Don't use defaultValue.EMPTY_OBJECT here because the options object gets modified in the next line.
-  options = defaultValue(options, {});
-  options.allowTextureFilterAnisotropic = defaultValue(
-    options.allowTextureFilterAnisotropic,
-    true
-  );
-  const webglOptions = defaultValue(options.webgl, {});
+  const {
+    getWebGLStub,
+    requestWebgl2 = false,
+    webgl: webglOptions = {},
+    allowTextureFilterAnisotropic = true,
+  } = defaultValue(options, {});
 
   // Override select WebGL defaults
   webglOptions.alpha = defaultValue(webglOptions.alpha, false); // WebGL default is true
   webglOptions.stencil = defaultValue(webglOptions.stencil, true); // WebGL default is false
+  webglOptions.powerPreference = defaultValue(
+    webglOptions.powerPreference,
+    "high-performance"
+  ); // WebGL default is "default"
 
-  const requestWebgl2 =
-    defaultValue(options.requestWebgl2, false) &&
-    typeof WebGL2RenderingContext !== "undefined";
-  let webgl2 = false;
-
-  let glContext;
-  const getWebGLStub = options.getWebGLStub;
-
-  if (!defined(getWebGLStub)) {
-    if (requestWebgl2) {
-      glContext =
-        canvas.getContext("webgl2", webglOptions) ||
-        canvas.getContext("experimental-webgl2", webglOptions) ||
-        undefined;
-      if (defined(glContext)) {
-        webgl2 = true;
-      }
-    }
-    if (!defined(glContext)) {
-      glContext =
-        canvas.getContext("webgl", webglOptions) ||
-        canvas.getContext("experimental-webgl", webglOptions) ||
-        undefined;
-    }
-    if (!defined(glContext)) {
-      throw new RuntimeError(
-        "The browser supports WebGL, but initialization failed."
-      );
-    }
-  } else {
-    // Use WebGL stub when requested for unit tests
-    glContext = getWebGLStub(canvas, webglOptions);
-  }
+  const glContext = defined(getWebGLStub)
+    ? getWebGLStub(canvas, webglOptions)
+    : getWebGLContext(canvas, webglOptions, requestWebgl2);
+
+  // Get context type. instanceof will throw if WebGL2 is not supported
+  const webgl2 =
+    typeof WebGL2RenderingContext !== "undefined" &&
+    glContext instanceof WebGL2RenderingContext;
 
+  this._canvas = canvas;
   this._originalGLContext = glContext;
   this._gl = glContext;
   this._webgl2 = webgl2;
@@ -335,7 +194,7 @@ function Context(canvas, options) {
     this._bc7
   );
 
-  const textureFilterAnisotropic = options.allowTextureFilterAnisotropic
+  const textureFilterAnisotropic = allowTextureFilterAnisotropic
     ? getExtension(gl, [
         "EXT_texture_filter_anisotropic",
         "WEBKIT_EXT_texture_filter_anisotropic",
@@ -502,21 +361,16 @@ function Context(canvas, options) {
   this._nextPickColor = new Uint32Array(1);
 
   /**
-   * @example
-   * {
-   *   webgl : {
-   *     alpha : false,
-   *     depth : true,
-   *     stencil : false,
-   *     antialias : true,
-   *     premultipliedAlpha : true,
-   *     preserveDrawingBuffer : false,
-   *     failIfMajorPerformanceCaveat : true
-   *   },
-   *   allowTextureFilterAnisotropic : true
-   * }
+   * The options used to construct this context
+   *
+   * @type {ContextOptions}
    */
-  this.options = options;
+  this.options = {
+    getWebGLStub: getWebGLStub,
+    requestWebgl2: requestWebgl2,
+    webgl: webglOptions,
+    allowTextureFilterAnisotropic: allowTextureFilterAnisotropic,
+  };
 
   /**
    * A cache of objects tied to this context.  Just before the Context is destroyed,
@@ -532,6 +386,187 @@ function Context(canvas, options) {
   RenderState.apply(gl, rs, ps);
 }
 
+/**
+ * @typedef {Object} ContextOptions
+ *
+ * Options to control the setting up of a WebGL Context.
+ * <p>
+ * <code>allowTextureFilterAnisotropic</code> defaults to true, which enables
+ * anisotropic texture filtering when the WebGL extension is supported.
+ * Setting this to false will improve performance, but hurt visual quality,
+ * especially for horizon views.
+ * </p>
+ *
+ * @property {Boolean} [requestWebGl2 = false] If true and the browser supports it, use a WebGL 2 rendering context
+ * @property {Boolean} [allowTextureFilterAnisotropic=true] If true, use anisotropic filtering during texture sampling
+ * @property {WebGLOptions} [webgl] WebGL options to be passed on to canvas.getContext
+ * @property {Function} [getWebGLStub] A function to create a WebGL stub for testing
+ */
+
+/**
+ * @private
+ * @param {HTMLCanvasElement} canvas The canvas element to which the context will be associated
+ * @param {WebGLOptions} webglOptions WebGL options to be passed on to HTMLCanvasElement.getContext()
+ * @param {Boolean} requestWebgl2 Whether to request a WebGL2RenderingContext
+ * @returns {WebGLRenderingContext|WebGL2RenderingContext}
+ */
+function getWebGLContext(canvas, webglOptions, requestWebgl2) {
+  if (typeof WebGLRenderingContext === "undefined") {
+    throw new RuntimeError(
+      "The browser does not support WebGL.  Visit http://get.webgl.org."
+    );
+  }
+
+  requestWebgl2 =
+    requestWebgl2 && typeof WebGL2RenderingContext !== "undefined";
+  const contextType = requestWebgl2 ? "webgl2" : "webgl";
+  const glContext = canvas.getContext(contextType, webglOptions);
+
+  if (!defined(glContext)) {
+    throw new RuntimeError(
+      "The browser supports WebGL, but initialization failed."
+    );
+  }
+
+  return glContext;
+}
+
+/**
+ * @typedef {Object} WebGLOptions
+ *
+ * WebGL options to be passed on to HTMLCanvasElement.getContext().
+ * See {@link https://registry.khronos.org/webgl/specs/latest/1.0/#5.2|WebGLContextAttributes}
+ * but note the modified defaults for 'alpha', 'stencil', and 'powerPreference'
+ *
+ * <p>
+ * <code>alpha</code> defaults to false, which can improve performance
+ * compared to the standard WebGL default of true.  If an application needs
+ * to composite Cesium above other HTML elements using alpha-blending, set
+ * <code>alpha</code> to true.
+ * </p>
+ *
+ * @property {Boolean} [alpha=false]
+ * @property {Boolean} [depth=true]
+ * @property {Boolean} [stencil=false]
+ * @property {Boolean} [antialias=true]
+ * @property {Boolean} [premultipliedAlpha=true]
+ * @property {Boolean} [preserveDrawingBuffer=false]
+ * @property {("default"|"low-power"|"high-performance")} [powerPreference="high-performance"]
+ * @property {Boolean} [failIfMajorPerformanceCaveat=false]
+ */
+
+function errorToString(gl, error) {
+  let message = "WebGL Error:  ";
+  switch (error) {
+    case gl.INVALID_ENUM:
+      message += "INVALID_ENUM";
+      break;
+    case gl.INVALID_VALUE:
+      message += "INVALID_VALUE";
+      break;
+    case gl.INVALID_OPERATION:
+      message += "INVALID_OPERATION";
+      break;
+    case gl.OUT_OF_MEMORY:
+      message += "OUT_OF_MEMORY";
+      break;
+    case gl.CONTEXT_LOST_WEBGL:
+      message += "CONTEXT_LOST_WEBGL lost";
+      break;
+    default:
+      message += `Unknown (${error})`;
+  }
+
+  return message;
+}
+
+function createErrorMessage(gl, glFunc, glFuncArguments, error) {
+  let message = `${errorToString(gl, error)}: ${glFunc.name}(`;
+
+  for (let i = 0; i < glFuncArguments.length; ++i) {
+    if (i !== 0) {
+      message += ", ";
+    }
+    message += glFuncArguments[i];
+  }
+  message += ");";
+
+  return message;
+}
+
+function throwOnError(gl, glFunc, glFuncArguments) {
+  const error = gl.getError();
+  if (error !== gl.NO_ERROR) {
+    throw new RuntimeError(
+      createErrorMessage(gl, glFunc, glFuncArguments, error)
+    );
+  }
+}
+
+function makeGetterSetter(gl, propertyName, logFunction) {
+  return {
+    get: function () {
+      const value = gl[propertyName];
+      logFunction(gl, `get: ${propertyName}`, value);
+      return gl[propertyName];
+    },
+    set: function (value) {
+      gl[propertyName] = value;
+      logFunction(gl, `set: ${propertyName}`, value);
+    },
+  };
+}
+
+function wrapGL(gl, logFunction) {
+  if (!defined(logFunction)) {
+    return gl;
+  }
+
+  function wrapFunction(property) {
+    return function () {
+      const result = property.apply(gl, arguments);
+      logFunction(gl, property, arguments);
+      return result;
+    };
+  }
+
+  const glWrapper = {};
+
+  // JavaScript linters normally demand that a for..in loop must directly contain an if,
+  // but in our loop below, we actually intend to iterate all properties, including
+  // those in the prototype.
+  /*eslint-disable guard-for-in*/
+  for (const propertyName in gl) {
+    const property = gl[propertyName];
+
+    // wrap any functions we encounter, otherwise just copy the property to the wrapper.
+    if (property instanceof Function) {
+      glWrapper[propertyName] = wrapFunction(property);
+    } else {
+      Object.defineProperty(
+        glWrapper,
+        propertyName,
+        makeGetterSetter(gl, propertyName, logFunction)
+      );
+    }
+  }
+  /*eslint-enable guard-for-in*/
+
+  return glWrapper;
+}
+
+function getExtension(gl, names) {
+  const length = names.length;
+  for (let i = 0; i < length; ++i) {
+    const extension = gl.getExtension(names[i]);
+    if (extension) {
+      return extension;
+    }
+  }
+
+  return undefined;
+}
+
 const defaultFramebufferMarker = {};
 
 Object.defineProperties(Context.prototype, {

package/Source/Scene/I3SDataProvider.js

@@ -626,7 +626,8 @@ I3SDataProvider.prototype._loadGeoidData = function () {
     console.log(
       "No Geoid Terrain service provided - no geoid conversion will be performed."
     );
-    return Promise.resolve();
+    this._geoidDataIsReadyPromise = Promise.resolve();
+    return this._geoidDataIsReadyPromise;
   }
 
   this._geoidDataIsReadyPromise = geoidTerrainProvider.readyPromise.then(

package/Source/Scene/I3SFeature.js

@@ -49,7 +49,7 @@ Object.defineProperties(I3SFeature.prototype, {
 
 /**
  * Loads the content.
- * @returns {Promise.<Object>} A promise that is resolved when the data of the I3S feature is loaded
+ * @returns {Promise} A promise that is resolved when the data of the I3S feature is loaded
  * @private
  */
 I3SFeature.prototype.load = function () {

package/Source/Scene/I3SLayer.js

@@ -35,6 +35,11 @@ function I3SLayer(dataProvider, layerData, index) {
       .concat(`${layerData.href}`);
   }
 
+  this._version = layerData.store.version;
+  const splitVersion = this._version.split(".");
+  this._majorVersion = parseInt(splitVersion[0]);
+  this._minorVersion = splitVersion.length > 1 ? parseInt(splitVersion[1]) : 0;
+
   this._resource = new Resource({ url: tilesetUrl });
   this._resource.setQueryParameters(
     this._dataProvider.resource.queryParameters
@@ -98,11 +103,68 @@ Object.defineProperties(I3SLayer.prototype, {
       return this._data;
     },
   },
+
+  /**
+   * The version string of the loaded I3S dataset
+   * @memberof I3SLayer.prototype
+   * @type {String}
+   * @readonly
+   */
+  version: {
+    get: function () {
+      return this._version;
+    },
+  },
+
+  /**
+   * The major version number of the loaded I3S dataset
+   * @memberof I3SLayer.prototype
+   * @type {Number}
+   * @readonly
+   */
+  majorVersion: {
+    get: function () {
+      return this._majorVersion;
+    },
+  },
+
+  /**
+   * The minor version number of the loaded I3S dataset
+   * @memberof I3SLayer.prototype
+   * @type {Number}
+   * @readonly
+   */
+  minorVersion: {
+    get: function () {
+      return this._minorVersion;
+    },
+  },
+
+  /**
+   * When <code>true</code>, when the loaded I3S version is 1.6 or older
+   * @memberof I3SLayer.prototype
+   * @type {Boolean}
+   * @readonly
+   */
+  legacyVersion16: {
+    get: function () {
+      if (!defined(this.version)) {
+        return undefined;
+      }
+      if (
+        this.majorVersion < 1 ||
+        (this.majorVersion === 1 && this.minorVersion <= 6)
+      ) {
+        return true;
+      }
+      return false;
+    },
+  },
 });
 
 /**
  * Loads the content, including the root node definition and its children
- * @returns {Promise.<void>} A promise that is resolved when the layer data is loaded
+ * @returns {Promise} A promise that is resolved when the layer data is loaded
  * @private
  */
 I3SLayer.prototype.load = function () {
@@ -121,7 +183,7 @@ I3SLayer.prototype.load = function () {
       return that._tileset.readyPromise.then(function () {
         that._rootNode._tile = that._tileset._root;
         that._tileset._root._i3sNode = that._rootNode;
-        if (that._data.store.version === "1.6") {
+        if (that.legacyVersion16) {
           return that._rootNode._loadChildren();
         }
       });

package/Source/Scene/I3SNode.js

@@ -240,6 +240,52 @@ I3SNode.prototype.loadFields = function () {
   return Promise.all(promises);
 };
 
+/**
+ * Returns the fields for a given picked position
+ * @param {Cartesian3} pickedPosition The picked position
+ * @returns {Object} Object containing field names and their values
+ */
+I3SNode.prototype.getFieldsForPickedPosition = function (pickedPosition) {
+  const geometry = this.geometryData[0];
+  if (!defined(geometry.customAttributes.featureIndex)) {
+    return {};
+  }
+
+  const location = geometry.getClosestPointIndexOnTriangle(
+    pickedPosition.x,
+    pickedPosition.y,
+    pickedPosition.z
+  );
+
+  if (
+    location.index === -1 ||
+    location.index > geometry.customAttributes.featureIndex.length
+  ) {
+    return {};
+  }
+
+  const featureIndex = geometry.customAttributes.featureIndex[location.index];
+  return this.getFieldsForFeature(featureIndex);
+};
+
+/**
+ * Returns the fields for a given feature
+ * @param {Number} featureIndex Index of the feature whose attributes we want to get
+ * @returns {Object} Object containing field names and their values
+ */
+I3SNode.prototype.getFieldsForFeature = function (featureIndex) {
+  const featureFields = {};
+  for (const fieldName in this.fields) {
+    if (this.fields.hasOwnProperty(fieldName)) {
+      const field = this.fields[fieldName];
+      if (featureIndex >= 0 && featureIndex < field.values.length) {
+        featureFields[field.name] = field.values[featureIndex];
+      }
+    }
+  }
+  return featureFields;
+};
+
 /**
  * @private
  */
@@ -336,11 +382,6 @@ I3SNode.prototype._loadFeatureData = function () {
       this._featureData.push(newFeatureData);
       featurePromises.push(newFeatureData.load());
     }
-  } else if (defined(this._data.mesh) && defined(this._data.mesh.attribute)) {
-    const featureURI = `./features/0`;
-    const newFeatureData = new I3SFeature(this, featureURI);
-    this._featureData.push(newFeatureData);
-    featurePromises.push(newFeatureData.load());
   }
 
   return Promise.all(featurePromises);
@@ -661,7 +702,10 @@ I3SNode.prototype._createContentURL = function () {
   };
 
   // Load the geometry data
-  const dataPromises = [this._loadFeatureData(), this._loadGeometryData()];
+  const dataPromises = [this._loadGeometryData()];
+  if (this._dataProvider.legacyVersion16) {
+    dataPromises.push(this._loadFeatureData());
+  }
 
   const that = this;
   return Promise.all(dataPromises).then(function () {

package/Source/Scene/Model/Model.js

@@ -49,22 +49,55 @@ import StyleCommandsNeeded from "./StyleCommandsNeeded.js";
  *  {@link https://github.com/KhronosGroup/glTF/tree/master/extensions/2.0/Vendor/AGI_articulations/README.md|AGI_articulations}
  *  </li>
  *  <li>
+ *  {@link https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Vendor/CESIUM_primitive_outline|CESIUM_primitive_outline}
+ *  </li>
+ *  <li>
+ *  {@link https://github.com/KhronosGroup/glTF/blob/master/extensions/1.0/Vendor/CESIUM_RTC/README.md|CESIUM_RTC}
+ *  </li>
+ *  <li>
+ *  {@link https://github.com/CesiumGS/glTF/tree/3d-tiles-next/extensions/2.0/Vendor/EXT_instance_features|EXT_instance_features}
+ *  </li>
+ *  <li>
+ *  {@link https://github.com/CesiumGS/glTF/tree/3d-tiles-next/extensions/2.0/Vendor/EXT_mesh_features|EXT_mesh_features}
+ *  </li>
+ *  <li>
+ *  {@link https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Vendor/EXT_mesh_gpu_instancing|EXT_mesh_gpu_instancing}
+ *  </li>
+ *  <li>
+ *  {@link https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Vendor/EXT_meshopt_compression|EXT_meshopt_compression}
+ *  </li>
+ *  <li>
+ *  {@link https://github.com/CesiumGS/glTF/tree/3d-tiles-next/extensions/2.0/Vendor/EXT_structural_metadata|EXT_structural_metadata}
+ *  </li>
+ *  <li>
+ *  {@link https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Vendor/EXT_texture_webp|EXT_texture_webp}
+ *  </li>
+ *  <li>
  *  {@link https://github.com/KhronosGroup/glTF/blob/master/extensions/2.0/Khronos/KHR_draco_mesh_compression/README.md|KHR_draco_mesh_compression}
  *  </li>
  *  <li>
- *  {@link https://github.com/KhronosGroup/glTF/tree/master/extensions/2.0/Khronos/KHR_materials_pbrSpecularGlossiness/README.md|KHR_materials_pbrSpecularGlossiness}
+ *  {@link https://github.com/KhronosGroup/glTF/blob/main/extensions/2.0/Archived/KHR_techniques_webgl/README.md|KHR_techniques_webgl}
+ *  </li>
+ *  <li>
+ *  {@link https://github.com/KhronosGroup/glTF/blob/main/extensions/1.0/Khronos/KHR_materials_common/README.md|KHR_materials_common}
+ *  </li>
+ *  <li>
+ *  {@link https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Archived/KHR_materials_pbrSpecularGlossiness|KHR_materials_pbrSpecularGlossiness}
  *  </li>
  *  <li>
  *  {@link https://github.com/KhronosGroup/glTF/tree/master/extensions/2.0/Khronos/KHR_materials_unlit/README.md|KHR_materials_unlit}
  *  </li>
  *  <li>
- *  {@link https://github.com/KhronosGroup/glTF/blob/master/extensions/2.0/Khronos/KHR_texture_transform/README.md|KHR_texture_transform}
+ *  {@link https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Khronos/KHR_mesh_quantization|KHR_mesh_quantization}
  *  </li>
  *  <li>
  *  {@link https://github.com/KhronosGroup/glTF/blob/master/extensions/2.0/Khronos/KHR_texture_basisu|KHR_texture_basisu}
  *  </li>
  *  <li>
- *  {@link https://github.com/KhronosGroup/glTF/blob/master/extensions/1.0/Vendor/CESIUM_RTC/README.md|CESIUM_RTC}
+ *  {@link https://github.com/KhronosGroup/glTF/blob/master/extensions/2.0/Khronos/KHR_texture_transform/README.md|KHR_texture_transform}
+ *  </li>
+ *  <li>
+ *  {@link https://github.com/KhronosGroup/glTF/blob/main/extensions/1.0/Vendor/WEB3D_quantized_attributes/README.md|WEB3D_quantized_attributes}
  *  </li>
  * </ul>
  * </p>