@cesium/engine 0.1.0 → 1.1.0

package/Source/Scene/Scene.js

@@ -81,50 +81,13 @@ const requestRenderAfterFrame = function (scene) {
 /**
  * The container for all 3D graphical objects and state in a Cesium virtual scene.  Generally,
  * a scene is not created directly; instead, it is implicitly created by {@link CesiumWidget}.
- * <p>
- * <em><code>contextOptions</code> parameter details:</em>
- * </p>
- * <p>
- * The default values are:
- * <code>
- * {
- *   webgl : {
- *     alpha : false,
- *     depth : true,
- *     stencil : false,
- *     antialias : true,
- *     powerPreference: 'high-performance',
- *     premultipliedAlpha : true,
- *     preserveDrawingBuffer : false,
- *     failIfMajorPerformanceCaveat : false
- *   },
- *   allowTextureFilterAnisotropic : true
- * }
- * </code>
- * </p>
- * <p>
- * The <code>webgl</code> property corresponds to the {@link http://www.khronos.org/registry/webgl/specs/latest/#5.2|WebGLContextAttributes}
- * object used to create the WebGL context.
- * </p>
- * <p>
- * <code>webgl.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>webgl.alpha</code> to true.
- * </p>
- * <p>
- * The other <code>webgl</code> properties match the WebGL defaults for {@link http://www.khronos.org/registry/webgl/specs/latest/#5.2|WebGLContextAttributes}.
- * </p>
- * <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>
  *
  * @alias Scene
  * @constructor
  *
  * @param {Object} options Object with the following properties:
  * @param {HTMLCanvasElement} options.canvas The HTML canvas element to create the scene for.
- * @param {Object} [options.contextOptions] Context and WebGL creation properties.  See details above.
+ * @param {ContextOptions} [options.contextOptions] Context and WebGL creation properties.
  * @param {Element} [options.creditContainer] The HTML element in which the credits will be displayed.
  * @param {Element} [options.creditViewport] The HTML element in which to display the credit popup.  If not specified, the viewport will be a added as a sibling of the canvas.
  * @param {MapProjection} [options.mapProjection=new GeographicProjection()] The map projection to use in 2D and Columbus View modes.
@@ -134,7 +97,7 @@ const requestRenderAfterFrame = function (scene) {
  * @param {MapMode2D} [options.mapMode2D=MapMode2D.INFINITE_SCROLL] Determines if the 2D map is rotatable or can be scrolled infinitely in the horizontal direction.
  * @param {Boolean} [options.requestRenderMode=false] If true, rendering a frame will only occur when needed as determined by changes within the scene. Enabling improves performance of the application, but requires using {@link Scene#requestRender} to render a new frame explicitly in this mode. This will be necessary in many cases after making changes to the scene in other parts of the API. See {@link https://cesium.com/blog/2018/01/24/cesium-scene-rendering-performance/|Improving Performance with Explicit Rendering}.
  * @param {Number} [options.maximumRenderTimeChange=0.0] If requestRenderMode is true, this value defines the maximum change in simulation time allowed before a render is requested. See {@link https://cesium.com/blog/2018/01/24/cesium-scene-rendering-performance/|Improving Performance with Explicit Rendering}.
- * @param {Number} [depthPlaneEllipsoidOffset=0.0] Adjust the DepthPlane to address rendering artefacts below ellipsoid zero elevation.
+ * @param {Number} [options.depthPlaneEllipsoidOffset=0.0] Adjust the DepthPlane to address rendering artefacts below ellipsoid zero elevation.
  * @param {Number} [options.msaaSamples=1] If provided, this value controls the rate of multisample antialiasing. Typical multisampling rates are 2, 4, and sometimes 8 samples per pixel. Higher sampling rates of MSAA may impact performance in exchange for improved visual quality. This value only applies to WebGL2 contexts that support multisample render targets.
  *
  * @see CesiumWidget
@@ -157,17 +120,7 @@ function Scene(options) {
   let creditContainer = options.creditContainer;
   let creditViewport = options.creditViewport;
 
-  let contextOptions = clone(options.contextOptions);
-  if (!defined(contextOptions)) {
-    contextOptions = {};
-  }
-  if (!defined(contextOptions.webgl)) {
-    contextOptions.webgl = {};
-  }
-  contextOptions.webgl.powerPreference = defaultValue(
-    contextOptions.webgl.powerPreference,
-    "high-performance"
-  );
+  const contextOptions = clone(options.contextOptions);
 
   //>>includeStart('debug', pragmas.debug);
   if (!defined(canvas)) {
@@ -2262,6 +2215,17 @@ function executeTranslucentCommandsFrontToBack(
   }
 }
 
+function executeVoxelCommands(scene, executeFunction, passState, commands) {
+  const context = scene.context;
+
+  mergeSort(commands, backToFront, scene.camera.positionWC);
+
+  const length = commands.length;
+  for (let i = 0; i < length; ++i) {
+    executeFunction(commands[i], scene, context, passState);
+  }
+}
+
 const scratchPerspectiveFrustum = new PerspectiveFrustum();
 const scratchPerspectiveOffCenterFrustum = new PerspectiveOffCenterFrustum();
 const scratchOrthographicFrustum = new OrthographicFrustum();
@@ -2670,6 +2634,12 @@ function executeCommands(scene, passState) {
       pickDepth.executeCopyDepth(context, passState);
     }
 
+    us.updatePass(Pass.VOXELS);
+    commands = frustumCommands.commands[Pass.VOXELS];
+    length = frustumCommands.indices[Pass.VOXELS];
+    commands.length = length;
+    executeVoxelCommands(scene, executeCommand, passState, commands);
+
     if (picking || !usePostProcessSelected) {
       continue;
     }

package/Source/Scene/SpatialNode.js

@@ -0,0 +1,375 @@
+import binarySearch from "../Core/binarySearch.js";
+import Cartesian3 from "../Core/Cartesian3.js";
+import CesiumMath from "../Core/Math.js";
+import defined from "../Core/defined.js";
+import DeveloperError from "../Core/DeveloperError.js";
+import KeyframeNode from "./KeyframeNode.js";
+import Matrix3 from "../Core/Matrix3.js";
+import OrientedBoundingBox from "../Core/OrientedBoundingBox.js";
+
+/**
+ * @alias SpatialNode
+ * @constructor
+ *
+ * @param {Number} level
+ * @param {Number} x
+ * @param {Number} y
+ * @param {Number} z
+ * @param {SpatialNode} parent
+ * @param {VoxelShapeType} shape
+ * @param {Cartesian3} voxelDimensions
+ *
+ * @private
+ */
+function SpatialNode(level, x, y, z, parent, shape, voxelDimensions) {
+  /**
+   * @ignore
+   * @type {SpatialNode[]}
+   */
+  this.children = undefined;
+  this.parent = parent;
+
+  this.level = level;
+  this.x = x;
+  this.y = y;
+  this.z = z;
+
+  /**
+   * @ignore
+   * @type {KeyframeNode[]}
+   */
+  this.keyframeNodes = [];
+  /**
+   * @ignore
+   * @type {KeyframeNode[]}
+   */
+  this.renderableKeyframeNodes = [];
+
+  this.renderableKeyframeNodeLerp = 0.0;
+  /**
+   * @ignore
+   * @type {KeyframeNode}
+   */
+  this.renderableKeyframeNodePrevious = undefined;
+  /**
+   * @ignore
+   * @type {KeyframeNode}
+   */
+  this.renderableKeyframeNodeNext = undefined;
+
+  this.orientedBoundingBox = new OrientedBoundingBox();
+  this.approximateVoxelSize = 0.0;
+  this.screenSpaceError = 0.0;
+  this.visitedFrameNumber = -1;
+
+  this.computeBoundingVolumes(shape, voxelDimensions);
+}
+
+/**
+ * @param {SpatialNode} a
+ * @param {SpatialNode} b
+ * @returns {Boolean}
+ */
+SpatialNode.spatialComparator = function (a, b) {
+  // The higher of the two screen space errors is prioritized
+  return b.screenSpaceError - a.screenSpaceError;
+};
+
+const scratchObbHalfScale = new Cartesian3();
+
+/**
+ * @param {VoxelShape} shape
+ * @param {Cartesian3} voxelDimensions
+ */
+SpatialNode.prototype.computeBoundingVolumes = function (
+  shape,
+  voxelDimensions
+) {
+  this.orientedBoundingBox = shape.computeOrientedBoundingBoxForTile(
+    this.level,
+    this.x,
+    this.y,
+    this.z,
+    this.orientedBoundingBox
+  );
+
+  const halfScale = Matrix3.getScale(
+    this.orientedBoundingBox.halfAxes,
+    scratchObbHalfScale
+  );
+  const maximumScale = 2.0 * Cartesian3.maximumComponent(halfScale);
+  this.approximateVoxelSize =
+    maximumScale / Cartesian3.minimumComponent(voxelDimensions);
+};
+
+/**
+ * @param {FrameState} frameState
+ * @param {Number} visibilityPlaneMask
+ * @returns {Number} A plane mask as described in {@link CullingVolume#computeVisibilityWithPlaneMask}.
+ */
+SpatialNode.prototype.visibility = function (frameState, visibilityPlaneMask) {
+  const obb = this.orientedBoundingBox;
+  const cullingVolume = frameState.cullingVolume;
+  return cullingVolume.computeVisibilityWithPlaneMask(obb, visibilityPlaneMask);
+};
+
+/**
+ * @param {Cartesian3} cameraPosition
+ * @param {Number} screenSpaceErrorMultiplier
+ */
+SpatialNode.prototype.computeScreenSpaceError = function (
+  cameraPosition,
+  screenSpaceErrorMultiplier
+) {
+  const obb = this.orientedBoundingBox;
+
+  let distance = Math.sqrt(obb.distanceSquaredTo(cameraPosition));
+  // Avoid divide-by-zero when viewer is inside the tile.
+  distance = Math.max(distance, CesiumMath.EPSILON7);
+  const approximateVoxelSize = this.approximateVoxelSize;
+  const error = screenSpaceErrorMultiplier * (approximateVoxelSize / distance);
+  this.screenSpaceError = error;
+};
+
+// This object imitates a KeyframeNode. Only used for binary search function.
+const scratchBinarySearchKeyframeNode = {
+  keyframe: 0,
+};
+
+/**
+ * Find the index of a given key frame position within an array of KeyframeNodes,
+ * or the complement (~) of the index where it would be in the sorted array.
+ * @param {Number} keyframe
+ * @param {KeyframeNode[]} keyframeNodes
+ * @returns {Number}
+ * @private
+ */
+function findKeyframeIndex(keyframe, keyframeNodes) {
+  scratchBinarySearchKeyframeNode.keyframe = keyframe;
+  return binarySearch(
+    keyframeNodes,
+    scratchBinarySearchKeyframeNode,
+    KeyframeNode.searchComparator
+  );
+}
+
+/**
+ * Computes the most suitable keyframes for rendering, balancing between temporal and visual quality.
+ *
+ * @param {Number} keyframeLocation
+ */
+SpatialNode.prototype.computeSurroundingRenderableKeyframeNodes = function (
+  keyframeLocation
+) {
+  let spatialNode = this;
+  const startLevel = spatialNode.level;
+
+  const targetKeyframePrev = Math.floor(keyframeLocation);
+  const targetKeyframeNext = Math.ceil(keyframeLocation);
+
+  let bestKeyframeNodePrev;
+  let bestKeyframeNodeNext;
+  let minimumDistancePrev = +Number.MAX_VALUE;
+  let minimumDistanceNext = +Number.MAX_VALUE;
+
+  while (defined(spatialNode)) {
+    const renderableKeyframeNodes = spatialNode.renderableKeyframeNodes;
+
+    if (renderableKeyframeNodes.length >= 1) {
+      let keyframeNodeIndexPrev = findKeyframeIndex(
+        targetKeyframePrev,
+        renderableKeyframeNodes
+      );
+      if (keyframeNodeIndexPrev < 0) {
+        keyframeNodeIndexPrev = CesiumMath.clamp(
+          ~keyframeNodeIndexPrev - 1,
+          0,
+          renderableKeyframeNodes.length - 1
+        );
+      }
+      const keyframeNodePrev = renderableKeyframeNodes[keyframeNodeIndexPrev];
+      const keyframePrev = keyframeNodePrev.keyframe;
+
+      let keyframeNodeNext;
+      if (
+        targetKeyframeNext === targetKeyframePrev ||
+        targetKeyframePrev < keyframePrev
+      ) {
+        keyframeNodeNext = keyframeNodePrev;
+      } else {
+        const keyframeNodeIndexNext = Math.min(
+          keyframeNodeIndexPrev + 1,
+          renderableKeyframeNodes.length - 1
+        );
+        keyframeNodeNext = renderableKeyframeNodes[keyframeNodeIndexNext];
+      }
+      const keyframeNext = keyframeNodeNext.keyframe;
+
+      const keyframeDistancePrev = targetKeyframePrev - keyframePrev;
+      const keyframeDistanceNext = keyframeNext - targetKeyframeNext;
+      const levelDistance = startLevel - spatialNode.level;
+
+      // Balance temporal and visual quality
+      const levelWeight = Math.exp(levelDistance * 4.0);
+      const normalKeyframeWeight = 1.0;
+      const reverseKeyframeWeight = 200.0; // Keyframes on the opposite of the desired direction are deprioritized.
+      const distancePrev =
+        levelDistance * levelWeight +
+        (keyframeDistancePrev >= 0
+          ? keyframeDistancePrev * normalKeyframeWeight
+          : -keyframeDistancePrev * reverseKeyframeWeight);
+      const distanceNext =
+        levelDistance * levelWeight +
+        (keyframeDistanceNext >= 0
+          ? keyframeDistanceNext * normalKeyframeWeight
+          : -keyframeDistanceNext * reverseKeyframeWeight);
+
+      if (distancePrev < minimumDistancePrev) {
+        minimumDistancePrev = distancePrev;
+        bestKeyframeNodePrev = keyframeNodePrev;
+      }
+      if (distanceNext < minimumDistanceNext) {
+        minimumDistanceNext = distanceNext;
+        bestKeyframeNodeNext = keyframeNodeNext;
+      }
+      if (keyframeDistancePrev === 0 && keyframeDistanceNext === 0) {
+        // Nothing higher up will be better, so break early.
+        break;
+      }
+    }
+
+    spatialNode = spatialNode.parent;
+  }
+
+  this.renderableKeyframeNodePrevious = bestKeyframeNodePrev;
+  this.renderableKeyframeNodeNext = bestKeyframeNodeNext;
+  if (defined(bestKeyframeNodePrev) && defined(bestKeyframeNodeNext)) {
+    const bestKeyframePrev = bestKeyframeNodePrev.keyframe;
+    const bestKeyframeNext = bestKeyframeNodeNext.keyframe;
+    this.renderableKeyframeNodeLerp =
+      bestKeyframePrev === bestKeyframeNext
+        ? 0.0
+        : CesiumMath.clamp(
+            (keyframeLocation - bestKeyframePrev) /
+              (bestKeyframeNext - bestKeyframePrev),
+            0.0,
+            1.0
+          );
+  }
+};
+
+/**
+ * @param {Number} frameNumber
+ * @returns {Boolean}
+ */
+SpatialNode.prototype.isVisited = function (frameNumber) {
+  return this.visitedFrameNumber === frameNumber;
+};
+
+/**
+ * @param {Number} keyframe
+ */
+SpatialNode.prototype.createKeyframeNode = function (keyframe) {
+  let index = findKeyframeIndex(keyframe, this.keyframeNodes);
+  if (index < 0) {
+    index = ~index; // convert to insertion index
+    const keyframeNode = new KeyframeNode(this, keyframe);
+    this.keyframeNodes.splice(index, 0, keyframeNode);
+  }
+};
+
+/**
+ * @param {KeyframeNode} keyframeNode
+ * @param {Megatexture[]} megatextures
+ */
+SpatialNode.prototype.destroyKeyframeNode = function (
+  keyframeNode,
+  megatextures
+) {
+  const keyframe = keyframeNode.keyframe;
+  const keyframeIndex = findKeyframeIndex(keyframe, this.keyframeNodes);
+  if (keyframeIndex < 0) {
+    throw new DeveloperError("Keyframe node does not exist.");
+  }
+
+  this.keyframeNodes.splice(keyframeIndex, 1);
+
+  if (keyframeNode.megatextureIndex !== -1) {
+    for (let i = 0; i < megatextures.length; i++) {
+      megatextures[i].remove(keyframeNode.megatextureIndex);
+    }
+
+    const renderableKeyframeNodeIndex = findKeyframeIndex(
+      keyframe,
+      this.renderableKeyframeNodes
+    );
+    if (renderableKeyframeNodeIndex < 0) {
+      throw new DeveloperError("Renderable keyframe node does not exist.");
+    }
+
+    this.renderableKeyframeNodes.splice(renderableKeyframeNodeIndex, 1);
+  }
+
+  keyframeNode.spatialNode = undefined;
+  keyframeNode.state = KeyframeNode.LoadState.UNLOADED;
+  keyframeNode.metadatas = {};
+  keyframeNode.megatextureIndex = -1;
+  keyframeNode.priority = -Number.MAX_VALUE;
+  keyframeNode.highPriorityFrameNumber = -1;
+};
+
+/**
+ * @param {KeyframeNode} keyframeNode
+ * @param {Megatexture[]} megatextures
+ */
+SpatialNode.prototype.addKeyframeNodeToMegatextures = function (
+  keyframeNode,
+  megatextures
+) {
+  if (
+    keyframeNode.state !== KeyframeNode.LoadState.RECEIVED ||
+    keyframeNode.megatextureIndex !== -1 ||
+    keyframeNode.metadatas.length !== megatextures.length
+  ) {
+    throw new DeveloperError("Keyframe node cannot be added to megatexture");
+  }
+
+  for (let i = 0; i < megatextures.length; i++) {
+    const megatexture = megatextures[i];
+    keyframeNode.megatextureIndex = megatexture.add(keyframeNode.metadatas[i]);
+    keyframeNode.metadatas[i] = undefined; // data is in megatexture so no need to hold onto it
+  }
+
+  keyframeNode.state = KeyframeNode.LoadState.LOADED;
+
+  const renderableKeyframeNodes = this.renderableKeyframeNodes;
+  let renderableKeyframeNodeIndex = findKeyframeIndex(
+    keyframeNode.keyframe,
+    renderableKeyframeNodes
+  );
+  if (renderableKeyframeNodeIndex >= 0) {
+    throw new DeveloperError("Keyframe already renderable");
+  }
+  renderableKeyframeNodeIndex = ~renderableKeyframeNodeIndex;
+  renderableKeyframeNodes.splice(renderableKeyframeNodeIndex, 0, keyframeNode);
+};
+
+/**
+ * @param {Number} frameNumber
+ * @returns Boolean
+ */
+SpatialNode.prototype.isRenderable = function (frameNumber) {
+  const previousNode = this.renderableKeyframeNodePrevious;
+  const nextNode = this.renderableKeyframeNodeNext;
+  const level = this.level;
+
+  return (
+    defined(previousNode) &&
+    defined(nextNode) &&
+    (previousNode.spatialNode.level === level ||
+      nextNode.spatialNode.level === level) &&
+    this.visitedFrameNumber === frameNumber
+  );
+};
+
+export default SpatialNode;

package/Source/Scene/StructuralMetadata.js

@@ -76,7 +76,7 @@ Object.defineProperties(StructuralMetadata.prototype, {
   },
 
   /**
-   * Extras in the JSON object.
+   * Extra user-defined properties.
    *
    * @memberof StructuralMetadata.prototype
    * @type {*}
@@ -90,7 +90,7 @@ Object.defineProperties(StructuralMetadata.prototype, {
   },
 
   /**
-   * Extensions in the JSON object.
+   * An object containing extensions.
    *
    * @memberof StructuralMetadata.prototype
    * @type {Object}

package/Source/Scene/TileMetadata.js

@@ -50,7 +50,7 @@ Object.defineProperties(TileMetadata.prototype, {
   },
 
   /**
-   * Extras in the JSON object.
+   * Extra user-defined properties.
    *
    * @memberof TileMetadata.prototype
    * @type {Object}
@@ -64,7 +64,7 @@ Object.defineProperties(TileMetadata.prototype, {
   },
 
   /**
-   * Extensions in the JSON object.
+   * An object containing extensions.
    *
    * @memberof TileMetadata.prototype
    * @type {Object}

package/Source/Scene/TilesetMetadata.js

@@ -52,7 +52,7 @@ Object.defineProperties(TilesetMetadata.prototype, {
   },
 
   /**
-   * Extras in the JSON object.
+   * Extra user-defined properties.
    *
    * @memberof TilesetMetadata.prototype
    * @type {*}
@@ -66,7 +66,7 @@ Object.defineProperties(TilesetMetadata.prototype, {
   },
 
   /**
-   * Extensions in the JSON object.
+   * An object containing extensions.
    *
    * @memberof TilesetMetadata.prototype
    * @type {Object}