From 39461a7983421bb353c718060ccf1183cfd68d2a Mon Sep 17 00:00:00 2001 From: Peter Gagliardi Date: Mon, 8 Nov 2021 08:58:56 -0500 Subject: [PATCH 1/8] Expose public details of ModelExperimental and CustomShader --- Source/Core/ExperimentalFeatures.js | 3 -- Source/Scene/Cesium3DTileset.js | 8 +++++ .../Scene/ModelExperimental/CustomShader.js | 11 ++----- .../ModelExperimental/CustomShaderMode.js | 4 ++- .../Scene/ModelExperimental/LightingModel.js | 6 ++-- .../ModelExperimental/ModelExperimental.js | 30 ++++--------------- .../Scene/ModelExperimental/TextureUniform.js | 1 - Source/Scene/ModelExperimental/UniformType.js | 2 +- Source/Scene/ModelExperimental/VaryingType.js | 2 +- 9 files changed, 23 insertions(+), 44 deletions(-) diff --git a/Source/Core/ExperimentalFeatures.js b/Source/Core/ExperimentalFeatures.js index 27feb4639c8f..75714247e440 100644 --- a/Source/Core/ExperimentalFeatures.js +++ b/Source/Core/ExperimentalFeatures.js @@ -12,15 +12,12 @@ *
  • Experimental flags should be short-lived. Make it clear in the PR what it would take to promote the feature to a regular feature.
    • *
  • To avoid cluttering the code, check the flag in as few places as possible. Ideally this would be a single place.
    • * - * - * @private */ var ExperimentalFeatures = { /** * Toggles the usage of the ModelExperimental class. * * @type {Boolean} - * @private */ enableModelExperimental: false, }; diff --git a/Source/Scene/Cesium3DTileset.js b/Source/Scene/Cesium3DTileset.js index bbdc58f79b1c..9fc9e81a1099 100644 --- a/Source/Scene/Cesium3DTileset.js +++ b/Source/Scene/Cesium3DTileset.js @@ -951,6 +951,14 @@ function Cesium3DTileset(options) { */ this.metadata = undefined; + /** + * A {@link CustomShader} that will be applied to every tile content in the + * tileset. Any primitives within the tiles that are not compatible with the + * shader code will be rendered as if no custom shader is applied. + * + * @type {CustomShader|undefined} + * @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. + */ this._customShader = options.customShader; this._schemaLoader = undefined; diff --git a/Source/Scene/ModelExperimental/CustomShader.js b/Source/Scene/ModelExperimental/CustomShader.js index d4be04c67b4f..13c39f4d7c7b 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. */ /** @@ -77,7 +78,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 +120,6 @@ export default function CustomShader(options) { * * @type {CustomShaderMode} * @readonly - * @private */ this.mode = defaultValue(options.mode, CustomShaderMode.MODIFY_MATERIAL); /** @@ -129,7 +128,6 @@ export default function CustomShader(options) { * * @type {LightingModel} * @readonly - * @private */ this.lightingModel = options.lightingModel; /** @@ -137,7 +135,6 @@ export default function CustomShader(options) { * * @type {Object.} * @readonly - * @private */ this.uniforms = defaultValue(options.uniforms, defaultValue.EMPTY_OBJECT); /** @@ -146,7 +143,6 @@ export default function CustomShader(options) { * * @type {Object.} * @readonly - * @private */ this.varyings = defaultValue(options.varyings, defaultValue.EMPTY_OBJECT); /** @@ -154,7 +150,6 @@ export default function CustomShader(options) { * * @type {String} * @readonly - * @private */ this.vertexShaderText = options.vertexShaderText; /** @@ -162,7 +157,6 @@ export default function CustomShader(options) { * * @type {String} * @readonly - * @private */ this.fragmentShaderText = options.fragmentShaderText; /** @@ -170,7 +164,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..e276c5eae143 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 () { @@ -311,8 +309,6 @@ Object.defineProperties(ModelExperimental.prototype, { * * @type {Cesium3DTileContent} * @readonly - * - * @private */ content: { get: function () { @@ -326,9 +322,6 @@ Object.defineProperties(ModelExperimental.prototype, { * @memberof ModelExperimental.prototype * * @type {Number} - * @readonly - * - * @private */ featureTableId: { get: function () { @@ -376,9 +369,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 +388,6 @@ Object.defineProperties(ModelExperimental.prototype, { * @memberof ModelExperimental.prototype * * @type {Color} - * - * @private */ color: { get: function () { @@ -418,10 +406,8 @@ Object.defineProperties(ModelExperimental.prototype, { * * @memberof ModelExperimental.prototype * - * @type {Cesium3DTileColorBlend|ColorBlendMode} + * @type {Cesium3DTileColorBlendMode|ColorBlendMode} * @default ColorBlendMode.HIGHLIGHT - * - * @private */ colorBlendMode: { get: function () { @@ -439,8 +425,6 @@ Object.defineProperties(ModelExperimental.prototype, { * * @type {Number} * @default 0.5 - * - * @private */ colorBlendAmount: { get: function () { @@ -458,8 +442,6 @@ Object.defineProperties(ModelExperimental.prototype, { * * @type {BoundingSphere} * @readonly - * - * @private */ boundingSphere: { get: function () { @@ -743,8 +725,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/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 = { /** From 749873fe72e0ee1279e7cac9271b5ce31bdf85a9 Mon Sep 17 00:00:00 2001 From: Peter Gagliardi Date: Mon, 8 Nov 2021 10:44:54 -0500 Subject: [PATCH 2/8] Expose methods on features --- Source/Scene/Cesium3DTileFeature.js | 25 ++++++++++++++++++- Source/Scene/Cesium3DTileset.js | 17 ++++--------- .../Scene/ModelExperimental/ModelFeature.js | 23 ++++++++++++++--- 3 files changed, 48 insertions(+), 17 deletions(-) diff --git a/Source/Scene/Cesium3DTileFeature.js b/Source/Scene/Cesium3DTileFeature.js index 2bedb8a1b1ef..509f2b5f7201 100644 --- a/Source/Scene/Cesium3DTileFeature.js +++ b/Source/Scene/Cesium3DTileFeature.js @@ -212,7 +212,30 @@ 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. + *
    + * + * @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 9fc9e81a1099..3a2a64c54e1c 100644 --- a/Source/Scene/Cesium3DTileset.js +++ b/Source/Scene/Cesium3DTileset.js @@ -951,14 +951,6 @@ function Cesium3DTileset(options) { */ this.metadata = undefined; - /** - * A {@link CustomShader} that will be applied to every tile content in the - * tileset. Any primitives within the tiles that are not compatible with the - * shader code will be rendered as if no custom shader is applied. - * - * @type {CustomShader|undefined} - * @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. - */ this._customShader = options.customShader; this._schemaLoader = undefined; @@ -1324,9 +1316,11 @@ 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. Any primitive + * that is incompatible with the custom shader code (e.g. due to missing + * vertex attributes) will be rendered as if no custom shader were applied. * * @memberof Cesium3DTileset.prototype * @@ -1334,7 +1328,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/ModelExperimental/ModelFeature.js b/Source/Scene/ModelExperimental/ModelFeature.js index 847bf8011ad0..7472ffc9535f 100644 --- a/Source/Scene/ModelExperimental/ModelFeature.js +++ b/Source/Scene/ModelExperimental/ModelFeature.js @@ -10,7 +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 + * Do not construct this directly. Access it through {@link Cesium3DTileContent#getFeature} or * picking using {@link Scene#pick}. *

    * @@ -20,7 +20,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 +30,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 +149,20 @@ 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. + *
    + * + * @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); From d217c4c7873bd3d59830156ffb9018c176aa5d90 Mon Sep 17 00:00:00 2001 From: Peter Gagliardi Date: Mon, 8 Nov 2021 10:45:34 -0500 Subject: [PATCH 3/8] Update changelog --- CHANGES.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/CHANGES.md b/CHANGES.md index 4fecfc3af3c6..8a0199e7b7bf 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -1,6 +1,20 @@ # Change Log -### 1.87 - 2021-11-1 +### 1.87.1 - 2021-11-09 + +##### Additions :tada: + +- Added experimental class `ModelExperimental`, a new architecture for `Model` to support new glTF extensions. +- Added experimental implementation of [3D Tiles Next extensions](https://github.com/CesiumGS/3d-tiles/tree/main/next) for 3D Tiles and glTF: + - [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 + - [3DTILES_multiple_contents](https://github.com/CesiumGS/3d-tiles/tree/main/extensions/3DTILES_multiple_contents) for storing multiple contents within a single tile + - (glTF extension) [EXT_mesh_features](https://github.com/KhronosGroup/glTF/pull/2082) for adding semantic metadata to glTF models and tile contents. This is the glTF equivalent of `3DTILES_metadata`. Requires use of `ModelExperimental`. + - [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. These + - [3DTILES_content_gltf](https://github.com/CesiumGS/3d-tiles/tree/main/extensions/3DTILES_content_gltf) for using glTF models directly as tile contents +- Added experimental `CustomShader` class for styling `Cesium3DTileset` or `ModelExperimental` with custom GLSL shaders. + +### 1.87 - 2021-11-01 ##### Additions :tada: From 42bd7c85d6dc5bca48c67a6aa31b53101ca23171 Mon Sep 17 00:00:00 2001 From: Peter Gagliardi Date: Mon, 8 Nov 2021 11:56:15 -0500 Subject: [PATCH 4/8] Initial pass of PR feedback --- CHANGES.md | 4 ++-- Source/Core/ExperimentalFeatures.js | 2 ++ Source/Scene/Cesium3DTileset.js | 3 +++ Source/Scene/ModelExperimental/CustomShader.js | 3 +++ Source/Scene/ModelExperimental/ModelFeature.js | 1 - 5 files changed, 10 insertions(+), 3 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index 8a0199e7b7bf..87998b69f0fd 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -8,9 +8,9 @@ - Added experimental implementation of [3D Tiles Next extensions](https://github.com/CesiumGS/3d-tiles/tree/main/next) for 3D Tiles and glTF: - [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 - [3DTILES_multiple_contents](https://github.com/CesiumGS/3d-tiles/tree/main/extensions/3DTILES_multiple_contents) for storing multiple contents within a single tile - - (glTF extension) [EXT_mesh_features](https://github.com/KhronosGroup/glTF/pull/2082) for adding semantic metadata to glTF models and tile contents. This is the glTF equivalent of `3DTILES_metadata`. Requires use of `ModelExperimental`. + - [EXT_mesh_features](https://github.com/KhronosGroup/glTF/pull/2082) (glTF extension) for adding semantic metadata to glTF models and tile contents. This is the glTF equivalent of `3DTILES_metadata`. Requires use of `ModelExperimental`. - [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. These + - [3DTILES_bounding_volume_S2](https://github.com/CesiumGS/3d-tiles/tree/main/extensions/3DTILES_bounding_volume_S2) for [S2](https://s2geometry.io/) bounding volumes. These bounding volumes have minimal distortion at the north and south poles. - [3DTILES_content_gltf](https://github.com/CesiumGS/3d-tiles/tree/main/extensions/3DTILES_content_gltf) for using glTF models directly as tile contents - Added experimental `CustomShader` class for styling `Cesium3DTileset` or `ModelExperimental` with custom GLSL shaders. diff --git a/Source/Core/ExperimentalFeatures.js b/Source/Core/ExperimentalFeatures.js index 75714247e440..cc941020e68d 100644 --- a/Source/Core/ExperimentalFeatures.js +++ b/Source/Core/ExperimentalFeatures.js @@ -12,6 +12,8 @@ *
  • Experimental flags should be short-lived. Make it clear in the PR what it would take to promote the feature to a regular feature.
    • *
  • To avoid cluttering the code, check the flag in as few places as possible. Ideally this would be a single place.
    • * + * + * @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 = { /** diff --git a/Source/Scene/Cesium3DTileset.js b/Source/Scene/Cesium3DTileset.js index 3a2a64c54e1c..efcf2f9ae1fb 100644 --- a/Source/Scene/Cesium3DTileset.js +++ b/Source/Scene/Cesium3DTileset.js @@ -1321,6 +1321,9 @@ Object.defineProperties(Cesium3DTileset.prototype, { * {@link Cesium3DTileStyle} may lead to undefined behavior. Any primitive * that is incompatible with the custom shader code (e.g. due to missing * vertex attributes) will be rendered as if no custom shader were applied. + *

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

    * * @memberof Cesium3DTileset.prototype * diff --git a/Source/Scene/ModelExperimental/CustomShader.js b/Source/Scene/ModelExperimental/CustomShader.js index 13c39f4d7c7b..0803666247f8 100644 --- a/Source/Scene/ModelExperimental/CustomShader.js +++ b/Source/Scene/ModelExperimental/CustomShader.js @@ -65,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. diff --git a/Source/Scene/ModelExperimental/ModelFeature.js b/Source/Scene/ModelExperimental/ModelFeature.js index 7472ffc9535f..646da7e7a800 100644 --- a/Source/Scene/ModelExperimental/ModelFeature.js +++ b/Source/Scene/ModelExperimental/ModelFeature.js @@ -153,7 +153,6 @@ ModelFeature.prototype.getProperty = function (name) { * 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. From dcf6ed906c5dbb902a2e0387365a3e2330bd6a0f Mon Sep 17 00:00:00 2001 From: Peter Gagliardi Date: Mon, 8 Nov 2021 12:33:21 -0500 Subject: [PATCH 5/8] Revise changelog --- CHANGES.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index 87998b69f0fd..4ef1c13d711c 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -4,15 +4,16 @@ ##### Additions :tada: -- Added experimental class `ModelExperimental`, a new architecture for `Model` to support new glTF extensions. -- Added experimental implementation of [3D Tiles Next extensions](https://github.com/CesiumGS/3d-tiles/tree/main/next) for 3D Tiles and glTF: +- 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 - - [3DTILES_multiple_contents](https://github.com/CesiumGS/3d-tiles/tree/main/extensions/3DTILES_multiple_contents) for storing multiple contents within a single tile - - [EXT_mesh_features](https://github.com/KhronosGroup/glTF/pull/2082) (glTF extension) for adding semantic metadata to glTF models and tile contents. This is the glTF equivalent of `3DTILES_metadata`. Requires use of `ModelExperimental`. + - [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. These bounding volumes have minimal distortion at the north and south poles. - - [3DTILES_content_gltf](https://github.com/CesiumGS/3d-tiles/tree/main/extensions/3DTILES_content_gltf) for using glTF models directly as tile contents -- Added experimental `CustomShader` class for styling `Cesium3DTileset` or `ModelExperimental` with custom GLSL shaders. + - [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 From f33e8f1952fa6cacbad6bd6fc46bc6ede12840df Mon Sep 17 00:00:00 2001 From: Peter Gagliardi Date: Mon, 8 Nov 2021 12:37:51 -0500 Subject: [PATCH 6/8] More PR feedback --- Source/Scene/ModelExperimental/ModelExperimental.js | 4 ++++ Source/Scene/ModelExperimental/ModelFeature.js | 3 +-- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/Source/Scene/ModelExperimental/ModelExperimental.js b/Source/Scene/ModelExperimental/ModelExperimental.js index e276c5eae143..0c56d2820a08 100644 --- a/Source/Scene/ModelExperimental/ModelExperimental.js +++ b/Source/Scene/ModelExperimental/ModelExperimental.js @@ -309,6 +309,8 @@ Object.defineProperties(ModelExperimental.prototype, { * * @type {Cesium3DTileContent} * @readonly + * + * @private */ content: { get: function () { @@ -322,6 +324,8 @@ Object.defineProperties(ModelExperimental.prototype, { * @memberof ModelExperimental.prototype * * @type {Number} + * + * @private */ featureTableId: { get: function () { diff --git a/Source/Scene/ModelExperimental/ModelFeature.js b/Source/Scene/ModelExperimental/ModelFeature.js index 646da7e7a800..a389923126b4 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 Cesium3DTileContent#getFeature} or - * picking using {@link Scene#pick}. + * Do not construct this directly. Access it through picking using {@link Scene#pick}. *

      * * @alias ModelFeature From b701e991d2c6f39666c0c1ada3551c86ab630db9 Mon Sep 17 00:00:00 2001 From: Peter Gagliardi Date: Mon, 8 Nov 2021 13:17:07 -0500 Subject: [PATCH 7/8] Don't mention some of the internal details of custom shaders --- Source/Scene/Cesium3DTileset.js | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/Source/Scene/Cesium3DTileset.js b/Source/Scene/Cesium3DTileset.js index efcf2f9ae1fb..5310ca7f4cfa 100644 --- a/Source/Scene/Cesium3DTileset.js +++ b/Source/Scene/Cesium3DTileset.js @@ -1318,9 +1318,7 @@ Object.defineProperties(Cesium3DTileset.prototype, { /** * 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. Any primitive - * that is incompatible with the custom shader code (e.g. due to missing - * vertex attributes) will be rendered as if no custom shader were applied. + * {@link Cesium3DTileStyle} may lead to undefined behavior. *

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

      From 5891378d23e1c5a1e04b0870250b2e0c1c42c67e Mon Sep 17 00:00:00 2001 From: Peter Gagliardi Date: Mon, 8 Nov 2021 13:23:22 -0500 Subject: [PATCH 8/8] Add links to specs --- Source/Scene/Cesium3DTileFeature.js | 5 +++++ Source/Scene/FeatureMetadata.js | 3 ++- Source/Scene/ModelExperimental/ModelFeature.js | 4 ++++ Source/Scene/PropertyTextureProperty.js | 4 +++- 4 files changed, 14 insertions(+), 2 deletions(-) diff --git a/Source/Scene/Cesium3DTileFeature.js b/Source/Scene/Cesium3DTileFeature.js index 509f2b5f7201..f230ce33ad23 100644 --- a/Source/Scene/Cesium3DTileFeature.js +++ b/Source/Scene/Cesium3DTileFeature.js @@ -229,6 +229,11 @@ Cesium3DTileFeature.prototype.getProperty = function (name) { *
    3. Tileset metadata property by property ID
      4. *
    4. Otherwise, return undefined
      5. *
    + *

    + * 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 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/ModelFeature.js b/Source/Scene/ModelExperimental/ModelFeature.js index a389923126b4..a6f73614efdf 100644 --- a/Source/Scene/ModelExperimental/ModelFeature.js +++ b/Source/Scene/ModelExperimental/ModelFeature.js @@ -156,6 +156,10 @@ ModelFeature.prototype.getProperty = function (name) { *
  • Feature metadata property by semantic
    • *
  • Feature metadata property by property ID
    • * + *

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