Add experimental 3D Tiles Next features to the documentation and changelog

CHANGES.md

@@ -1,6 +1,21 @@
 # Change Log
 
-### 1.87 - 2021-11-1
+### 1.87.1 - 2021-11-09
+
+##### Additions :tada:
+
+- Added experimental implementations of [3D Tiles Next](https://github.com/CesiumGS/3d-tiles/tree/main/next). The following extensions are supported:
+  - [3DTILES_content_gltf](https://github.com/CesiumGS/3d-tiles/tree/main/extensions/3DTILES_content_gltf) for using glTF models directly as tile contents
+  - [3DTILES_metadata](https://github.com/CesiumGS/3d-tiles/tree/main/extensions/3DTILES_metadata) for adding structured metadata to tilesets, tiles, or groups of tile content
+  - [EXT_mesh_features](https://github.com/KhronosGroup/glTF/pull/2082) for adding feature identification and feature metadata to glTF models
+  - [3DTILES_implicit_tiling](https://github.com/CesiumGS/3d-tiles/tree/main/extensions/3DTILES_implicit_tiling) for a compact representation of quadtrees and octrees
+  - [3DTILES_bounding_volume_S2](https://github.com/CesiumGS/3d-tiles/tree/main/extensions/3DTILES_bounding_volume_S2) for [S2](https://s2geometry.io/) bounding volumes
+  - [3DTILES_multiple_contents](https://github.com/CesiumGS/3d-tiles/tree/main/extensions/3DTILES_multiple_contents) for storing multiple contents within a single tile
+- Added `ModelExperimental`, a new experimental architecture for loading glTF models
+- Added `CustomShader` class for styling `Cesium3DTileset` or `ModelExperimental` with custom GLSL shaders
+- Added `ExperimentalFeatures.enableModelExperimental` for enabling certain experimental features. `ModelExperimental`, `EXT_mesh_features` and `CustomShader` are only enabled when this flag is set to true.
+
+### 1.87 - 2021-11-01
 
 ##### Additions :tada:
 

Source/Core/ExperimentalFeatures.js

@@ -13,14 +13,13 @@
  *   <li>To avoid cluttering the code, check the flag in as few places as possible. Ideally this would be a single place.</li>
  * </ul>
  *
- * @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.
  */
 var ExperimentalFeatures = {
   /**
    * Toggles the usage of the ModelExperimental class.
    *
    * @type {Boolean}
-   * @private
    */
   enableModelExperimental: false,
 };

Source/Scene/Cesium3DTileFeature.js

@@ -212,7 +212,35 @@ Cesium3DTileFeature.prototype.getProperty = function (name) {
 };
 
 /**
- * @private
+ * Returns a copy of the feature's property with the given name, examining all
+ * the metadata from 3D Tiles 1.0 formats, the EXT_mesh_features and legacy
+ * EXT_feature_metadata glTF extensions, and the 3DTILES_metadata 3D Tiles
+ * extension. Metadata is checked against name from most specific to most
+ * general and the first match is returned. Metadata is checked in this order:
+ *
+ * <ol>
+ *   <li>Batch table (feature metadata) property by semantic</li>
+ *   <li>Batch table (feature metadata) property by property ID</li>
+ *   <li>Tile metadata property by semantic</li>
+ *   <li>Tile metadata property by property ID</li>
+ *   <li>Group metadata property by semantic</li>
+ *   <li>Group metadata property by property ID</li>
+ *   <li>Tileset metadata property by semantic</li>
+ *   <li>Tileset metadata property by property ID</li>
+ *   <li>Otherwise, return undefined</li>
+ * </ol>
+ * <p>
+ * For 3D Tiles Next details, see the {@link https://github.com/CesiumGS/3d-tiles/tree/3d-tiles-next/extensions/3DTILES_metadata|3DTILES_metadata Extension}
+ * for 3D Tiles, as well as the {@link https://github.com/CesiumGS/glTF/tree/3d-tiles-next/extensions/2.0/Vendor/EXT_mesh_features|EXT_mesh_features Extension}
+ * for glTF. For the legacy glTF extension, see {@link https://github.com/CesiumGS/glTF/tree/3d-tiles-next/extensions/2.0/Vendor/EXT_feature_metadata|EXT_feature_metadata Extension}
+ * </p>
+ *
+ * @param {Cesium3DTileContent} content The content for accessing the metadata
+ * @param {Number} batchId The batch ID (or feature ID) of the feature to get a property for
+ * @param {String} name The semantic or property ID of the feature. Semantics are checked before property IDs in each granularity of metadata.
+ * @return {*} The value of the property or <code>undefined</code> if the feature does not have this property.
+ *
+ * @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.
  */
 Cesium3DTileFeature.getPropertyInherited = function (content, batchId, name) {
   var value;

Source/Scene/Cesium3DTileset.js

@@ -1316,17 +1316,19 @@ Object.defineProperties(Cesium3DTileset.prototype, {
   },
 
   /**
-   * A custom shader to apply to the tileset. Only used for contents that use
-   * {@link ModelExperimental}. Using custom shaders with a {@link Cesium3DTileStyle}
-   * may lead to undefined behavior.
+   * A custom shader to apply to all tiles in the tileset. Only used for
+   * contents that use {@link ModelExperimental}. Using custom shaders with a
+   * {@link Cesium3DTileStyle} may lead to undefined behavior.
+   * <p>
+   * To enable {@link ModelExperimental}, set {@link ExperimentalFeatures.enableModelExperimental} to <code>true</code>.
+   * </p>
    *
    * @memberof Cesium3DTileset.prototype
    *
    * @type {CustomShader|undefined}
    *
    * @default undefined
    *
-   * @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.
    */
   customShader: {

Source/Scene/FeatureMetadata.js

@@ -5,7 +5,8 @@ import defined from "../Core/defined.js";
 /**
  * An object containing feature metadata.
  * <p>
- * See the {@link https://github.com/CesiumGS/glTF/tree/3d-tiles-next/extensions/2.0/Vendor/EXT_feature_metadata|EXT_feature_metadata Extension} for glTF.
+ * See the {@link https://github.com/CesiumGS/glTF/tree/3d-tiles-next/extensions/2.0/Vendor/EXT_mesh_features|EXT_mesh_features Extension} as well as the
+ * previous {@link https://github.com/CesiumGS/glTF/tree/3d-tiles-next/extensions/2.0/Vendor/EXT_feature_metadata|EXT_feature_metadata Extension} for glTF.
  * </p>
  *
  * @param {Object} options Object with the following properties:

Source/Scene/ModelExperimental/CustomShader.js

@@ -13,7 +13,8 @@ import TextureManager from "./TextureManager.js";
  * @typedef {Object} UniformSpecifier
  * @property {UniformType} type The Glsl type of the uniform.
  * @property {Boolean|Number|Cartesian2|Cartesian3|Cartesian4|Matrix2|Matrix3|Matrix4|TextureUniform} value The initial value of the uniform
- * @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.
  */
 
 /**
@@ -64,6 +65,9 @@ import TextureManager from "./TextureManager.js";
  *      is responsible for calling this method.
  *   </li>
  * </ul>
+ * <p>
+ * To enable the use of {@link ModelExperimental} in {@link Cesium3DTileset}, set {@link ExperimentalFeatures.enableModelExperimental} to <code>true</code>.
+ * </p>
  *
  * @param {Object} options An object with the following options
  * @param {CustomShaderMode} [options.mode=CustomShaderMode.MODIFY_MATERIAL] The custom shader mode, which determines how the custom shader code is inserted into the fragment shader.
@@ -77,7 +81,6 @@ import TextureManager from "./TextureManager.js";
  * @alias CustomShader
  * @constructor
  *
- * @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.
  *
  * @example
@@ -120,7 +123,6 @@ export default function CustomShader(options) {
    *
    * @type {CustomShaderMode}
    * @readonly
-   * @private
    */
   this.mode = defaultValue(options.mode, CustomShaderMode.MODIFY_MATERIAL);
   /**
@@ -129,15 +131,13 @@ export default function CustomShader(options) {
    *
    * @type {LightingModel}
    * @readonly
-   * @private
    */
   this.lightingModel = options.lightingModel;
   /**
    * Additional uniforms as declared by the user.
    *
    * @type {Object.<String, UniformSpecifier>}
    * @readonly
-   * @private
    */
   this.uniforms = defaultValue(options.uniforms, defaultValue.EMPTY_OBJECT);
   /**
@@ -146,31 +146,27 @@ export default function CustomShader(options) {
    *
    * @type {Object.<String, VaryingType>}
    * @readonly
-   * @private
    */
   this.varyings = defaultValue(options.varyings, defaultValue.EMPTY_OBJECT);
   /**
    * The user-defined GLSL code for the vertex shader
    *
    * @type {String}
    * @readonly
-   * @private
    */
   this.vertexShaderText = options.vertexShaderText;
   /**
    * The user-defined GLSL code for the fragment shader
    *
    * @type {String}
    * @readonly
-   * @private
    */
   this.fragmentShaderText = options.fragmentShaderText;
   /**
    * Whether the shader should be rendered as translucent
    *
    * @type {Boolean}
    * @readonly
-   * @private
    */
   this.isTranslucent = defaultValue(options.isTranslucent, false);
 

Source/Scene/ModelExperimental/CustomShaderMode.js

@@ -4,7 +4,7 @@
  *
  * @enum {String}
  *
- * @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.
  */
 var CustomShaderMode = {
   /**
@@ -30,6 +30,8 @@ var CustomShaderMode = {
  * directives. For example:  <code>#define CUSTOM_SHADER_MODIFY_MATERIAL</code>
  * @param {CustomShaderMode} customShaderMode The shader mode
  * @return {String} The name of the GLSL macro to use
+ *
+ * @private
  */
 CustomShaderMode.getDefineName = function (customShaderMode) {
   return "CUSTOM_SHADER_" + customShaderMode;

Source/Scene/ModelExperimental/LightingModel.js

@@ -1,9 +1,9 @@
 /**
- * The lighting model to use for lighting a {@link ModelExperimental}. This
- * is applied in the {@link LightingPipelineStage}.
+ * The lighting model to use for lighting a {@link ModelExperimental}.
  *
  * @enum {Number}
- * @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.
  */
 var LightingModel = {
   /**

Source/Scene/ModelExperimental/ModelExperimental.js

@@ -17,15 +17,15 @@ import Color from "../../Core/Color.js";
 
 /**
  * A 3D model. This is a new architecture that is more decoupled than the older {@link Model}. This class is still experimental.
- *
+ * <p>
  * Do not call this function directly, instead use the `from` functions to create
  * the Model from your source data type.
+ * </p>
  *
  * @alias ModelExperimental
  * @constructor
  *
  * @param {Object} options Object with the following properties:
- * @param {ResourceLoader} options.loader The loader responsible for loading the 3D model.
  * @param {Resource} options.resource The Resource to the 3D model.
  * @param {Matrix4} [options.modelMatrix=Matrix4.IDENTITY]  The 4x4 transformation matrix that transforms the model from model to world coordinates.
  * @param {Boolean} [options.debugShowBoundingVolume=false] For debugging only. Draws the bounding sphere for each draw command in the model.
@@ -41,7 +41,6 @@ import Color from "../../Core/Color.js";
  * @param {Number} [options.featureIdAttributeIndex=0] The index of the feature ID attribute to use for picking features per-instance or per-primitive.
  * @param {Number} [options.featureIdTextureIndex=0] The index of the feature ID texture to use for picking features per-primitive.
  *
- * @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.
  */
 export default function ModelExperimental(options) {
@@ -53,6 +52,8 @@ export default function ModelExperimental(options) {
 
   /**
    * The loader used to load resources for this model.
+   * The corresponding constructor parameter is undocumented, since
+   * ResourceLoader is part of the private API.
    *
    * @type {ResourceLoader}
    *
@@ -288,9 +289,6 @@ Object.defineProperties(ModelExperimental.prototype, {
    * @memberof ModelExperimental.prototype
    *
    * @type {CustomShader}
-   * @readonly
-   *
-   * @private
    */
   customShader: {
     get: function () {
@@ -326,7 +324,6 @@ Object.defineProperties(ModelExperimental.prototype, {
    * @memberof ModelExperimental.prototype
    *
    * @type {Number}
-   * @readonly
    *
    * @private
    */
@@ -376,9 +373,6 @@ Object.defineProperties(ModelExperimental.prototype, {
    * The style to apply the to the features in the model. Cannot be applied if a {@link CustomShader} is also applied.
    *
    * @type {Cesium3DTileStyle}
-   * @readonly
-   *
-   * @private
    */
   style: {
     get: function () {
@@ -398,8 +392,6 @@ Object.defineProperties(ModelExperimental.prototype, {
    * @memberof ModelExperimental.prototype
    *
    * @type {Color}
-   *
-   * @private
    */
   color: {
     get: function () {
@@ -418,10 +410,8 @@ Object.defineProperties(ModelExperimental.prototype, {
    *
    * @memberof ModelExperimental.prototype
    *
-   * @type {Cesium3DTileColorBlend|ColorBlendMode}
+   * @type {Cesium3DTileColorBlendMode|ColorBlendMode}
    * @default ColorBlendMode.HIGHLIGHT
-   *
-   * @private
    */
   colorBlendMode: {
     get: function () {
@@ -439,8 +429,6 @@ Object.defineProperties(ModelExperimental.prototype, {
    *
    * @type {Number}
    * @default 0.5
-   *
-   * @private
    */
   colorBlendAmount: {
     get: function () {
@@ -458,8 +446,6 @@ Object.defineProperties(ModelExperimental.prototype, {
    *
    * @type {BoundingSphere}
    * @readonly
-   *
-   * @private
    */
   boundingSphere: {
     get: function () {
@@ -743,8 +729,6 @@ ModelExperimental.prototype.destroyResources = function () {
  * @param {Number} [options.featureIdTextureIndex=0] The index of the feature ID texture to use for picking features per-primitive.
  *
  * @returns {ModelExperimental} The newly created model.
- *
- * @private
  */
 ModelExperimental.fromGltf = function (options) {
   options = defaultValue(options, defaultValue.EMPTY_OBJECT);

Source/Scene/ModelExperimental/ModelFeature.js

@@ -10,8 +10,7 @@ import defined from "../../Core/defined.js";
  * Modifications to a <code>ModelFeature</code> object have the lifetime of the model.
  * </p>
  * <p>
- * Do not construct this directly. Access it through {@link ModelFeatureTable#getFeature}, {@link Cesium3DTileContent#getFeature} or
- * picking using {@link Scene#pick}.
+ * Do not construct this directly. Access it through picking using {@link Scene#pick}.
  * </p>
  *
  * @alias ModelFeature
@@ -20,7 +19,6 @@ import defined from "../../Core/defined.js";
  * @param {Object} options Object with the following properties:
  * @param {ModelExperimental} options.model The model the feature belongs to.
  * @param {Number} options.featureId The unique integral identifier for this feature.
- * @param {ModelFeatureTable} options.featureTable The {@link ModelFeatureTable} that this feature belongs to.
  *
  * @example
  * // On mouse over, display all the properties for a feature in the console log.
@@ -31,12 +29,15 @@ import defined from "../../Core/defined.js";
  *     }
  * }, Cesium.ScreenSpaceEventType.MOUSE_MOVE);
  *
- * @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.
  */
 export default function ModelFeature(options) {
   this._model = options.model;
+
+  // This ModelFeatureTable is not documented as an option since it is
+  // part of the private API and should not appear in the documentation.
   this._featureTable = options.featureTable;
+
   this._featureId = options.featureId;
   this._color = undefined; // for calling getColor
 }
@@ -147,7 +148,23 @@ ModelFeature.prototype.getProperty = function (name) {
 };
 
 /**
- * @private
+ * Returns a copy of the feature's property with the given name, examining all
+ * the metadata from the EXT_mesh_features and legacy EXT_feature_metadata glTF
+ * extensions. Metadata is checked against name from most specific to most
+ * general and the first match is returned. Metadata is checked in this order:
+ * <ol>
+ *   <li>Feature metadata property by semantic</li>
+ *   <li>Feature metadata property by property ID</li>
+ * </ol>
+ * <p>
+ * See the {@link https://github.com/CesiumGS/glTF/tree/3d-tiles-next/extensions/2.0/Vendor/EXT_mesh_features|EXT_mesh_features Extension} as well as the
+ * previous {@link https://github.com/CesiumGS/glTF/tree/3d-tiles-next/extensions/2.0/Vendor/EXT_feature_metadata|EXT_feature_metadata Extension} for glTF.
+ * </p>
+ *
+ * @param {String} name The semantic or property ID of the feature. Semantics are checked before property IDs in each granularity of metadata.
+ * @return {*} The value of the property or <code>undefined</code> if the feature does not have this property.
+ *
+ * @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.
  */
 ModelFeature.prototype.getPropertyInherited = function (name) {
   var value = this._featureTable.getPropertyBySemantic(this._featureId, name);