@cesium/engine 0.1.0 → 1.1.0

package/Source/Renderer/Context.js

@@ -1,10 +1,10 @@
 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";
 import defaultValue from "../Core/defaultValue.js";
 import defined from "../Core/defined.js";
+import deprecationWarning from "../Core/deprecationWarning.js";
 import destroyObject from "../Core/destroyObject.js";
 import DeveloperError from "../Core/DeveloperError.js";
 import Geometry from "../Core/Geometry.js";
@@ -31,183 +31,52 @@ 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;
+  let requestWebgl2 = false;
+  if (defined(options) && defined(options.requestWebgl2)) {
+    requestWebgl2 = options.requestWebgl2;
+    Context._deprecationWarning(
+      "ContextOptions.requestWebgl2",
+      "Cesium.requestWebgl2 was deprecated in CesiumJS 1.101 and will be removed in 1.102. Use Cesium.requestWebgl1 to request a WebGL1 or WebGL2 context."
+    );
+  }
 
-  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,
+    requestWebgl1 = !requestWebgl2,
+    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, requestWebgl1);
+
+  // 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 +204,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 +371,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,
+    requestWebgl1: requestWebgl1,
+    webgl: webglOptions,
+    allowTextureFilterAnisotropic: allowTextureFilterAnisotropic,
+  };
 
   /**
    * A cache of objects tied to this context.  Just before the Context is destroyed,
@@ -532,6 +396,191 @@ 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} [requestWebgl1 = true] If true and the browser supports it, use a WebGL 1 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} requestWebgl1 Whether to request a WebGLRenderingContext or a WebGL2RenderingContext.
+ * @returns {WebGLRenderingContext|WebGL2RenderingContext}
+ */
+function getWebGLContext(canvas, webglOptions, requestWebgl1) {
+  if (typeof WebGLRenderingContext === "undefined") {
+    throw new RuntimeError(
+      "The browser does not support WebGL.  Visit http://get.webgl.org."
+    );
+  }
+
+  // Ensure that WebGL 2 is supported when it is requested. Otherwise, fall back to WebGL 1.
+  const webgl2Supported = typeof WebGL2RenderingContext !== "undefined";
+  if (!requestWebgl1 && !webgl2Supported) {
+    requestWebgl1 = true;
+  }
+
+  const contextType = requestWebgl1 ? "webgl" : "webgl2";
+  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, {
@@ -1598,4 +1647,8 @@ Context.prototype.destroy = function () {
 
   return destroyObject(this);
 };
+
+// Used for specs.
+Context._deprecationWarning = deprecationWarning;
+
 export default Context;

package/Source/Renderer/Pass.js

@@ -20,7 +20,8 @@ const Pass = {
   CESIUM_3D_TILE_CLASSIFICATION_IGNORE_SHOW: 6,
   OPAQUE: 7,
   TRANSLUCENT: 8,
-  OVERLAY: 9,
-  NUMBER_OF_PASSES: 10,
+  VOXELS: 9,
+  OVERLAY: 10,
+  NUMBER_OF_PASSES: 11,
 };
 export default Object.freeze(Pass);

package/Source/Scene/Cesium3DTileContentType.js

@@ -132,6 +132,24 @@ const Cesium3DTileContentType = {
    * @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.
    */
   GEOJSON: "geoJson",
+  /**
+   * Binary voxel content for <code>3DTILES_content_voxels</code> extension.
+   *
+   * @type {String}
+   * @constant
+   * @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.
+   */
+  VOXEL_BINARY: "voxl",
+  /**
+   * Binary voxel content for <code>3DTILES_content_voxels</code> extension.
+   *
+   * @type {String}
+   * @constant
+   * @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.
+   */
+  VOXEL_JSON: "voxelJson",
 };
 
 /**
@@ -150,6 +168,7 @@ Cesium3DTileContentType.isBinaryFormat = function (contentType) {
     case Cesium3DTileContentType.VECTOR:
     case Cesium3DTileContentType.GEOMETRY:
     case Cesium3DTileContentType.IMPLICIT_SUBTREE:
+    case Cesium3DTileContentType.VOXEL_BINARY:
     case Cesium3DTileContentType.GLTF_BINARY:
       return true;
     default: