@cesium/engine 1.0.0 → 1.1.0

package/Source/Scene/VoxelProvider.js

@@ -0,0 +1,255 @@
+import DeveloperError from "../Core/DeveloperError.js";
+
+/**
+ * Provides voxel data. Intended to be used with {@link VoxelPrimitive}.
+ * This type describes an interface and is not intended to be instantiated directly.
+ *
+ * @alias VoxelProvider
+ * @constructor
+ *
+ * @see Cesium3DTilesVoxelProvider
+ * @see VoxelPrimitive
+ * @see VoxelShapeType
+ *
+ * @experimental This feature is not final and is subject to change without Cesium's standard deprecation policy.
+ */
+function VoxelProvider() {
+  DeveloperError.throwInstantiationError();
+}
+
+Object.defineProperties(VoxelProvider.prototype, {
+  /**
+   * Gets a value indicating whether or not the provider is ready for use.
+   *
+   * @memberof VoxelProvider.prototype
+   * @type {Boolean}
+   * @readonly
+   */
+  ready: {
+    get: DeveloperError.throwInstantiationError,
+  },
+
+  /**
+   * Gets the promise that will be resolved when the provider is ready for use.
+   *
+   * @memberof VoxelProvider.prototype
+   * @type {Promise.<VoxelProvider>}
+   * @readonly
+   */
+  readyPromise: {
+    get: DeveloperError.throwInstantiationError,
+  },
+
+  /**
+   * A transform from local space to global space. If undefined, the identity matrix will be used instead.
+   *
+   * @memberof VoxelProvider.prototype
+   * @type {Matrix4|undefined}
+   * @readonly
+   */
+  globalTransform: {
+    get: DeveloperError.throwInstantiationError,
+  },
+
+  /**
+   * A transform from shape space to local space. If undefined, the identity matrix will be used instead.
+   *
+   * @memberof VoxelProvider.prototype
+   * @type {Matrix4|undefined}
+   * @readonly
+   */
+  shapeTransform: {
+    get: DeveloperError.throwInstantiationError,
+  },
+
+  /**
+   * Gets the {@link VoxelShapeType}
+   * This should not be called before {@link VoxelProvider#ready} returns true.
+   *
+   * @memberof VoxelProvider.prototype
+   * @type {VoxelShapeType}
+   * @readonly
+   */
+  shape: {
+    get: DeveloperError.throwInstantiationError,
+  },
+
+  /**
+   * Gets the minimum bounds.
+   * If undefined, the shape's default minimum bounds will be used instead.
+   * This should not be called before {@link VoxelProvider#ready} returns true.
+   *
+   * @memberof VoxelProvider.prototype
+   * @type {Cartesian3|undefined}
+   * @readonly
+   */
+  minBounds: {
+    get: DeveloperError.throwInstantiationError,
+  },
+
+  /**
+   * Gets the maximum bounds.
+   * If undefined, the shape's default maximum bounds will be used instead.
+   * This should not be called before {@link VoxelProvider#ready} returns true.
+   *
+   * @memberof VoxelProvider.prototype
+   * @type {Cartesian3|undefined}
+   * @readonly
+   */
+  maxBounds: {
+    get: DeveloperError.throwInstantiationError,
+  },
+
+  /**
+   * Gets the number of voxels per dimension of a tile. This is the same for all tiles in the dataset.
+   * This should not be called before {@link VoxelProvider#ready} returns true.
+   *
+   * @memberof VoxelProvider.prototype
+   * @type {Cartesian3}
+   * @readonly
+   */
+  dimensions: {
+    get: DeveloperError.throwInstantiationError,
+  },
+
+  /**
+   * Gets the number of padding voxels before the tile. This improves rendering quality when sampling the edge of a tile, but it increases memory usage.
+   * This should not be called before {@link VoxelProvider#ready} returns true.
+   *
+   * @memberof VoxelProvider.prototype
+   * @type {Cartesian3|undefined}
+   * @readonly
+   */
+  paddingBefore: {
+    get: DeveloperError.throwInstantiationError,
+  },
+
+  /**
+   * Gets the number of padding voxels after the tile. This improves rendering quality when sampling the edge of a tile, but it increases memory usage.
+   * This should not be called before {@link VoxelProvider#ready} returns true.
+   *
+   * @memberof VoxelProvider.prototype
+   * @type {Cartesian3|undefined}
+   * @readonly
+   */
+  paddingAfter: {
+    get: DeveloperError.throwInstantiationError,
+  },
+
+  /**
+   * Gets the metadata names.
+   * This should not be called before {@link VoxelProvider#ready} returns true.
+   *
+   * @memberof VoxelProvider.prototype
+   * @type {String[]}
+   * @readonly
+   */
+  names: {
+    get: DeveloperError.throwInstantiationError,
+  },
+
+  /**
+   * Gets the metadata types.
+   * This should not be called before {@link VoxelProvider#ready} returns true.
+   *
+   * @memberof VoxelProvider.prototype
+   * @type {MetadataType[]}
+   * @readonly
+   */
+  types: {
+    get: DeveloperError.throwInstantiationError,
+  },
+
+  /**
+   * Gets the metadata component types.
+   * This should not be called before {@link VoxelProvider#ready} returns true.
+   *
+   * @memberof VoxelProvider.prototype
+   * @type {MetadataComponentType[]}
+   * @readonly
+   */
+  componentTypes: {
+    get: DeveloperError.throwInstantiationError,
+  },
+
+  /**
+   * Gets the metadata minimum values.
+   * This should not be called before {@link VoxelProvider#ready} returns true.
+   *
+   * @memberof VoxelProvider.prototype
+   * @type {Number[][]|undefined}
+   * @readonly
+   */
+  minimumValues: {
+    get: DeveloperError.throwInstantiationError,
+  },
+
+  /**
+   * Gets the metadata maximum values.
+   * This should not be called before {@link VoxelProvider#ready} returns true.
+   *
+   * @memberof VoxelProvider.prototype
+   * @type {Number[][]|undefined}
+   * @readonly
+   */
+  maximumValues: {
+    get: DeveloperError.throwInstantiationError,
+  },
+
+  /**
+   * The maximum number of tiles that exist for this provider. This value is used as a hint to the voxel renderer to allocate an appropriate amount of GPU memory. If this value is not known it can be undefined.
+   * This should not be called before {@link VoxelProvider#ready} returns true.
+   *
+   * @memberof VoxelProvider.prototype
+   * @type {Number|undefined}
+   * @readonly
+   */
+  maximumTileCount: {
+    get: DeveloperError.throwInstantiationError,
+  },
+
+  /**
+   * Gets the number of keyframes in the dataset.
+   * This should not be called before {@link VoxelProvider#ready} returns true.
+   *
+   * @memberof VoxelProvider.prototype
+   * @type {Number}
+   * @readonly
+   * @private
+   */
+  keyframeCount: {
+    get: DeveloperError.throwInstantiationError,
+  },
+
+  /**
+   * Gets the {@link TimeIntervalCollection} for the dataset, or undefined if it doesn't have timestamps.
+   * This should not be called before {@link VoxelProvider#ready} returns true.
+   *
+   * @memberof VoxelProvider.prototype
+   * @type {TimeIntervalCollection}
+   * @readonly
+   * @private
+   */
+  timeIntervalCollection: {
+    get: DeveloperError.throwInstantiationError,
+  },
+});
+
+/**
+ * Requests the data for a given tile. The data is a flattened 3D array ordered by X, then Y, then Z.
+ * This function should not be called before {@link VoxelProvider#ready} returns true.
+ * @function
+ *
+ * @param {Object} [options] Object with the following properties:
+ * @param {Number} [options.tileLevel=0] The tile's level.
+ * @param {Number} [options.tileX=0] The tile's X coordinate.
+ * @param {Number} [options.tileY=0] The tile's Y coordinate.
+ * @param {Number} [options.tileZ=0] The tile's Z coordinate.
+ * @privateparam {Number} [options.keyframe=0] The requested keyframe.
+ * @returns {Promise<Array[]>|undefined} A promise to an array of typed arrays containing the requested voxel data or undefined if there was a problem loading the data.
+ *
+ * @exception {DeveloperError} The provider must be ready.
+ */
+VoxelProvider.prototype.requestData = DeveloperError.throwInstantiationError;
+
+export default VoxelProvider;

package/Source/Scene/VoxelRenderResources.js

@@ -0,0 +1,224 @@
+import Cartesian3 from "../Core/Cartesian3.js";
+import combine from "../Core/combine.js";
+import defined from "../Core/defined.js";
+import ShaderBuilder from "../Renderer/ShaderBuilder.js";
+import ShaderDestination from "../Renderer/ShaderDestination.js";
+import VoxelFS from "../Shaders/Voxels/VoxelFS.js";
+import VoxelVS from "../Shaders/Voxels/VoxelVS.js";
+import IntersectionUtils from "../Shaders/Voxels/IntersectionUtils.js";
+import IntersectDepth from "../Shaders/Voxels/IntersectDepth.js";
+import IntersectClippingPlanes from "../Shaders/Voxels/IntersectClippingPlanes.js";
+import IntersectBox from "../Shaders/Voxels/IntersectBox.js";
+import IntersectCylinder from "../Shaders/Voxels/IntersectCylinder.js";
+import IntersectEllipsoid from "../Shaders/Voxels/IntersectEllipsoid.js";
+import Intersection from "../Shaders/Voxels/Intersection.js";
+import convertUvToBox from "../Shaders/Voxels/convertUvToBox.js";
+import convertUvToCylinder from "../Shaders/Voxels/convertUvToCylinder.js";
+import convertUvToEllipsoid from "../Shaders/Voxels/convertUvToEllipsoid.js";
+import Octree from "../Shaders/Voxels/Octree.js";
+import Megatexture from "../Shaders/Voxels/Megatexture.js";
+
+/**
+ * Set up render resources, including basic shader code, for rendering
+ * a Voxel primitive.
+ * The shader code generated by this function may be modified in later stages.
+ * @constructor
+ * @param {VoxelPrimitive} primitive
+ *
+ * @private
+ */
+function VoxelRenderResources(primitive) {
+  const shaderBuilder = new ShaderBuilder();
+  /**
+   * An object used to build a shader incrementally. Each pipeline stage
+   * may add lines of shader code to this object.
+   *
+   * @type {ShaderBuilder}
+   * @readonly
+   *
+   * @private
+   */
+  this.shaderBuilder = shaderBuilder;
+
+  // Custom shader uniforms
+  const customShader = primitive._customShader;
+  const uniformMap = combine(primitive._uniformMap, customShader.uniformMap);
+  primitive._uniformMap = uniformMap;
+
+  const customShaderUniforms = customShader.uniforms;
+  for (const uniformName in customShaderUniforms) {
+    if (customShaderUniforms.hasOwnProperty(uniformName)) {
+      const uniform = customShaderUniforms[uniformName];
+      shaderBuilder.addUniform(
+        uniform.type,
+        uniformName,
+        ShaderDestination.FRAGMENT
+      );
+    }
+  }
+  // The reason this uniform is added by shader builder is because some of the
+  // dynamically generated shader code reads from it.
+  shaderBuilder.addUniform(
+    "sampler2D",
+    "u_megatextureTextures[METADATA_COUNT]",
+    ShaderDestination.FRAGMENT
+  );
+
+  /**
+   * A dictionary mapping uniform name to functions that return the uniform
+   * values.
+   *
+   * @type {Object.<String, Function>}
+   */
+  this.uniformMap = uniformMap;
+
+  const clippingPlanes = primitive._clippingPlanes;
+  const clippingPlanesLength =
+    defined(clippingPlanes) && clippingPlanes.enabled
+      ? clippingPlanes.length
+      : 0;
+
+  this.clippingPlanes = clippingPlanes;
+  this.clippingPlanesLength = clippingPlanesLength;
+
+  // Build shader
+  shaderBuilder.addVertexLines([VoxelVS]);
+
+  shaderBuilder.addFragmentLines([
+    customShader.fragmentShaderText,
+    "#line 0",
+    IntersectionUtils,
+  ]);
+
+  if (clippingPlanesLength > 0) {
+    shaderBuilder.addDefine(
+      "CLIPPING_PLANES",
+      undefined,
+      ShaderDestination.FRAGMENT
+    );
+    shaderBuilder.addDefine(
+      "CLIPPING_PLANES_COUNT",
+      clippingPlanesLength,
+      ShaderDestination.FRAGMENT
+    );
+    if (clippingPlanes.unionClippingRegions) {
+      shaderBuilder.addDefine(
+        "CLIPPING_PLANES_UNION",
+        undefined,
+        ShaderDestination.FRAGMENT
+      );
+    }
+    shaderBuilder.addFragmentLines([IntersectClippingPlanes]);
+  }
+  if (primitive._depthTest) {
+    shaderBuilder.addDefine(
+      "DEPTH_TEST",
+      undefined,
+      ShaderDestination.FRAGMENT
+    );
+    shaderBuilder.addFragmentLines([IntersectDepth]);
+  }
+
+  const shapeType = primitive._provider.shape;
+  if (shapeType === "BOX") {
+    shaderBuilder.addFragmentLines([
+      IntersectBox,
+      Intersection,
+      convertUvToBox,
+    ]);
+  } else if (shapeType === "CYLINDER") {
+    shaderBuilder.addFragmentLines([
+      IntersectCylinder,
+      Intersection,
+      convertUvToCylinder,
+    ]);
+  } else if (shapeType === "ELLIPSOID") {
+    shaderBuilder.addFragmentLines([
+      IntersectEllipsoid,
+      Intersection,
+      convertUvToEllipsoid,
+    ]);
+  }
+
+  shaderBuilder.addFragmentLines([Octree, Megatexture, VoxelFS]);
+
+  const shape = primitive._shape;
+  const shapeDefines = shape.shaderDefines;
+  for (const key in shapeDefines) {
+    if (shapeDefines.hasOwnProperty(key)) {
+      let value = shapeDefines[key];
+      // if value is undefined, don't define it
+      // if value is true, define it to nothing
+      if (defined(value)) {
+        value = value === true ? undefined : value;
+        shaderBuilder.addDefine(key, value, ShaderDestination.FRAGMENT);
+      }
+    }
+  }
+
+  // Count how many intersections the shader will do.
+  let intersectionCount = shape.shaderMaximumIntersectionsLength;
+  if (clippingPlanesLength > 0) {
+    shaderBuilder.addDefine(
+      "CLIPPING_PLANES_INTERSECTION_INDEX",
+      intersectionCount,
+      ShaderDestination.FRAGMENT
+    );
+    if (clippingPlanesLength === 1) {
+      intersectionCount += 1;
+    } else if (clippingPlanes.unionClippingRegions) {
+      intersectionCount += 2;
+    } else {
+      intersectionCount += 1;
+    }
+  }
+  if (primitive._depthTest) {
+    shaderBuilder.addDefine(
+      "DEPTH_INTERSECTION_INDEX",
+      intersectionCount,
+      ShaderDestination.FRAGMENT
+    );
+    intersectionCount += 1;
+  }
+  shaderBuilder.addDefine(
+    "INTERSECTION_COUNT",
+    intersectionCount,
+    ShaderDestination.FRAGMENT
+  );
+
+  // Additional fragment shader defines
+  if (
+    !Cartesian3.equals(primitive.paddingBefore, Cartesian3.ZERO) ||
+    !Cartesian3.equals(primitive.paddingAfter, Cartesian3.ZERO)
+  ) {
+    shaderBuilder.addDefine("PADDING", undefined, ShaderDestination.FRAGMENT);
+  }
+  // Allow reading from log depth texture, but don't write log depth anywhere.
+  // Note: This needs to be set even if depthTest is off because it affects the
+  // derived command system.
+  if (primitive._useLogDepth) {
+    shaderBuilder.addDefine(
+      "LOG_DEPTH_READ_ONLY",
+      undefined,
+      ShaderDestination.FRAGMENT
+    );
+  }
+  if (primitive._jitter) {
+    shaderBuilder.addDefine("JITTER", undefined, ShaderDestination.FRAGMENT);
+  }
+  if (primitive._nearestSampling) {
+    shaderBuilder.addDefine(
+      "NEAREST_SAMPLING",
+      undefined,
+      ShaderDestination.FRAGMENT
+    );
+  }
+  const traversal = primitive._traversal;
+  shaderBuilder.addDefine(
+    "SAMPLE_COUNT",
+    `${traversal._sampleCount}`,
+    ShaderDestination.FRAGMENT
+  );
+}
+
+export default VoxelRenderResources;

package/Source/Scene/VoxelShape.js

@@ -0,0 +1,152 @@
+import DeveloperError from "../Core/DeveloperError.js";
+
+/**
+ * Controls per-shape behavior for culling and rendering voxel grids.
+ * This type describes an interface and is not intended to be instantiated directly.
+ *
+ * @alias VoxelShape
+ * @constructor
+ *
+ * @see VoxelBoxShape
+ * @see VoxelEllipsoidShape
+ * @see VoxelCylinderShape
+ * @see VoxelShapeType
+ *
+ * @private
+ */
+function VoxelShape() {
+  DeveloperError.throwInstantiationError();
+}
+
+Object.defineProperties(VoxelShape.prototype, {
+  /**
+   * An oriented bounding box containing the bounded shape.
+   * The update function must be called before accessing this value.
+   *
+   * @memberof VoxelShape.prototype
+   * @type {OrientedBoundingBox}
+   * @readonly
+   */
+  orientedBoundingBox: {
+    get: DeveloperError.throwInstantiationError,
+  },
+
+  /**
+   * A bounding sphere containing the bounded shape.
+   * The update function must be called before accessing this value.
+   *
+   * @memberof VoxelShape.prototype
+   * @type {BoundingSphere}
+   * @readonly
+   */
+  boundingSphere: {
+    get: DeveloperError.throwInstantiationError,
+  },
+
+  /**
+   * A transformation matrix containing the bounded shape.
+   * The update function must be called before accessing this value.
+   *
+   * @memberof VoxelShape.prototype
+   * @type {Matrix4}
+   * @readonly
+   */
+  boundTransform: {
+    get: DeveloperError.throwInstantiationError,
+  },
+
+  /**
+   * A transformation matrix containing the shape, ignoring the bounds.
+   * The update function must be called before accessing this value.
+   *
+   * @memberof VoxelShape.prototype
+   * @type {Matrix4}
+   * @readonly
+   */
+  shapeTransform: {
+    get: DeveloperError.throwInstantiationError,
+  },
+
+  /**
+   * @type {Object.<string, any>}
+   * @readonly
+   */
+  shaderUniforms: {
+    get: DeveloperError.throwInstantiationError,
+  },
+
+  /**
+   * @type {Object.<string, any>}
+   * @readonly
+   */
+  shaderDefines: {
+    get: DeveloperError.throwInstantiationError,
+  },
+
+  /**
+   * The maximum number of intersections against the shape for any ray direction.
+   * @type {Number}
+   * @readonly
+   */
+  shaderMaximumIntersectionsLength: {
+    get: DeveloperError.throwInstantiationError,
+  },
+});
+
+/**
+ * Update the shape's state.
+ *
+ * @param {Matrix4} modelMatrix The model matrix.
+ * @param {Cartesian3} minBounds The minimum bounds.
+ * @param {Cartesian3} maxBounds The maximum bounds.
+ * @returns {Boolean} Whether the shape is visible.
+ */
+VoxelShape.prototype.update = DeveloperError.throwInstantiationError;
+
+/**
+ * Computes an oriented bounding box for a specified tile.
+ * The update function must be called before calling this function.
+ *
+ * @param {Number} tileLevel The tile's level.
+ * @param {Number} tileX The tile's x coordinate.
+ * @param {Number} tileY The tile's y coordinate.
+ * @param {Number} tileZ The tile's z coordinate.
+ * @param {OrientedBoundingBox} result The oriented bounding box that will be set to enclose the specified tile.
+ * @returns {OrientedBoundingBox} The oriented bounding box.
+ */
+VoxelShape.prototype.computeOrientedBoundingBoxForTile =
+  DeveloperError.throwInstantiationError;
+
+/**
+ * Computes an approximate step size for raymarching the root tile of a voxel grid.
+ * The update function must be called before calling this function.
+ *
+ * @param {Cartesian3} voxelDimensions The voxel grid dimensions for a tile.
+ * @returns {Number} The step size.
+ */
+VoxelShape.prototype.computeApproximateStepSize =
+  DeveloperError.throwInstantiationError;
+
+/**
+ * Defines the minimum bounds of the shape. The meaning can vary per-shape.
+ *
+ * @type {Cartesian3}
+ * @constant
+ * @readonly
+ *
+ * @private
+ */
+VoxelShape.DefaultMinBounds = DeveloperError.throwInstantiationError;
+
+/**
+ * Defines the maximum bounds of the shape. The meaning can vary per-shape.
+ *
+ * @type {Cartesian3}
+ * @constant
+ * @readonly
+ *
+ * @private
+ */
+VoxelShape.DefaultMaxBounds = DeveloperError.throwInstantiationError;
+
+export default VoxelShape;