diff --git a/CHANGES.md b/CHANGES.md index 4fecfc3af3c6..4ef1c13d711c 100644 --- a/CHANGES.md +++ b/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: diff --git a/Source/Core/ExperimentalFeatures.js b/Source/Core/ExperimentalFeatures.js index 27feb4639c8f..cc941020e68d 100644 --- a/Source/Core/ExperimentalFeatures.js +++ b/Source/Core/ExperimentalFeatures.js @@ -13,14 +13,13 @@ *
  • To avoid cluttering the code, check the flag in as few places as possible. Ideally this would be a single place.
    • * * - * @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, }; diff --git a/Source/Scene/Cesium3DTileFeature.js b/Source/Scene/Cesium3DTileFeature.js index 2bedb8a1b1ef..f230ce33ad23 100644 --- a/Source/Scene/Cesium3DTileFeature.js +++ b/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: + * + *
      + *
    1. Batch table (feature metadata) property by semantic
      2. + *
    2. Batch table (feature metadata) property by property ID
      3. + *
    3. Tile metadata property by semantic
      4. + *
    4. Tile metadata property by property ID
      5. + *
    5. Group metadata property by semantic
      6. + *
    6. Group metadata property by property ID
      7. + *
    7. Tileset metadata property by semantic
      8. + *
    8. Tileset metadata property by property ID
      9. + *
    9. Otherwise, return undefined
      10. + *
    + *

    + * 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} + *

    + * + * @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 undefined 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; diff --git a/Source/Scene/Cesium3DTileset.js b/Source/Scene/Cesium3DTileset.js index bbdc58f79b1c..5310ca7f4cfa 100644 --- a/Source/Scene/Cesium3DTileset.js +++ b/Source/Scene/Cesium3DTileset.js @@ -1316,9 +1316,12 @@ 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. + *

    + * To enable {@link ModelExperimental}, set {@link ExperimentalFeatures.enableModelExperimental} to true. + *

    * * @memberof Cesium3DTileset.prototype * @@ -1326,7 +1329,6 @@ Object.defineProperties(Cesium3DTileset.prototype, { * * @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: { diff --git a/Source/Scene/FeatureMetadata.js b/Source/Scene/FeatureMetadata.js index 6e1379a006ee..f3310d75ac47 100644 --- a/Source/Scene/FeatureMetadata.js +++ b/Source/Scene/FeatureMetadata.js @@ -5,7 +5,8 @@ import defined from "../Core/defined.js"; /** * An object containing feature metadata. *

    - * 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. *

    * * @param {Object} options Object with the following properties: diff --git a/Source/Scene/ModelExperimental/CustomShader.js b/Source/Scene/ModelExperimental/CustomShader.js index d4be04c67b4f..0803666247f8 100644 --- a/Source/Scene/ModelExperimental/CustomShader.js +++ b/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. * * + *

    + * To enable the use of {@link ModelExperimental} in {@link Cesium3DTileset}, set {@link ExperimentalFeatures.enableModelExperimental} to true. + *

    * * @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,7 +131,6 @@ export default function CustomShader(options) { * * @type {LightingModel} * @readonly - * @private */ this.lightingModel = options.lightingModel; /** @@ -137,7 +138,6 @@ export default function CustomShader(options) { * * @type {Object.} * @readonly - * @private */ this.uniforms = defaultValue(options.uniforms, defaultValue.EMPTY_OBJECT); /** @@ -146,7 +146,6 @@ export default function CustomShader(options) { * * @type {Object.} * @readonly - * @private */ this.varyings = defaultValue(options.varyings, defaultValue.EMPTY_OBJECT); /** @@ -154,7 +153,6 @@ export default function CustomShader(options) { * * @type {String} * @readonly - * @private */ this.vertexShaderText = options.vertexShaderText; /** @@ -162,7 +160,6 @@ export default function CustomShader(options) { * * @type {String} * @readonly - * @private */ this.fragmentShaderText = options.fragmentShaderText; /** @@ -170,7 +167,6 @@ export default function CustomShader(options) { * * @type {Boolean} * @readonly - * @private */ this.isTranslucent = defaultValue(options.isTranslucent, false); diff --git a/Source/Scene/ModelExperimental/CustomShaderMode.js b/Source/Scene/ModelExperimental/CustomShaderMode.js index d16955b10781..589df91f1e47 100644 --- a/Source/Scene/ModelExperimental/CustomShaderMode.js +++ b/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: #define CUSTOM_SHADER_MODIFY_MATERIAL * @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; diff --git a/Source/Scene/ModelExperimental/LightingModel.js b/Source/Scene/ModelExperimental/LightingModel.js index 9e30fa095de1..3e805c1622c2 100644 --- a/Source/Scene/ModelExperimental/LightingModel.js +++ b/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 = { /** diff --git a/Source/Scene/ModelExperimental/ModelExperimental.js b/Source/Scene/ModelExperimental/ModelExperimental.js index 46d67b64e590..0c56d2820a08 100644 --- a/Source/Scene/ModelExperimental/ModelExperimental.js +++ b/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. - * + *

    * Do not call this function directly, instead use the `from` functions to create * the Model from your source data type. + *

    * * @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); diff --git a/Source/Scene/ModelExperimental/ModelFeature.js b/Source/Scene/ModelExperimental/ModelFeature.js index 847bf8011ad0..a6f73614efdf 100644 --- a/Source/Scene/ModelExperimental/ModelFeature.js +++ b/Source/Scene/ModelExperimental/ModelFeature.js @@ -10,8 +10,7 @@ import defined from "../../Core/defined.js"; * Modifications to a ModelFeature object have the lifetime of the model. *

    *

    - * 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}. *

    * * @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: + *
      + *
    1. Feature metadata property by semantic
      2. + *
    2. Feature metadata property by property ID
      3. + *
    + *

    + * 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. + *

    + * + * @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 undefined 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); diff --git a/Source/Scene/ModelExperimental/TextureUniform.js b/Source/Scene/ModelExperimental/TextureUniform.js index aea0f9d5254f..b587b0b80dc3 100644 --- a/Source/Scene/ModelExperimental/TextureUniform.js +++ b/Source/Scene/ModelExperimental/TextureUniform.js @@ -26,7 +26,6 @@ import TextureWrap from "../../Renderer/TextureWrap.js"; * @alias TextureUniform * @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. */ export default function TextureUniform(options) { diff --git a/Source/Scene/ModelExperimental/UniformType.js b/Source/Scene/ModelExperimental/UniformType.js index 75eedd11b804..19c9e0d4c382 100644 --- a/Source/Scene/ModelExperimental/UniformType.js +++ b/Source/Scene/ModelExperimental/UniformType.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 UniformType = { /** diff --git a/Source/Scene/ModelExperimental/VaryingType.js b/Source/Scene/ModelExperimental/VaryingType.js index 94bd3c80bcdb..5ba2b6e6cb66 100644 --- a/Source/Scene/ModelExperimental/VaryingType.js +++ b/Source/Scene/ModelExperimental/VaryingType.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 VaryingType = { /** diff --git a/Source/Scene/PropertyTextureProperty.js b/Source/Scene/PropertyTextureProperty.js index 3f72aee648ae..ea3e4f770a61 100644 --- a/Source/Scene/PropertyTextureProperty.js +++ b/Source/Scene/PropertyTextureProperty.js @@ -4,8 +4,10 @@ import GltfLoaderUtil from "./GltfLoaderUtil.js"; /** * A property in a feature texture. + * *

    - * 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. *

    * * @param {Object} options Object with the following properties: