Merge pull request #3473 from AnalyticalGraphicsInc/3d-tiles-doc-2

3D Tiles feature renames

Apps/Sandcastle/gallery/3D Tiles.html

@@ -427,9 +427,9 @@
     if (Cesium.defined(batchTableResources)) {
         // Does it have a per-model height property?
         if (batchTableResources.hasProperty(currentPropertyName)) {
-            var length = Cesium.defaultValue(content.batchLength, content.instancesLength);
+            var length = content.featuresLength;
             for (var i = 0; i < length; ++i) {
-                var building = content.getModel(i);
+                var building = content.getFeature(i);
                 var value = building.getProperty(currentPropertyName);
 
 // TODO: we could also fix these server side

CHANGES.md

@@ -6,14 +6,14 @@ Change Log
 * Added support for [3D Tiles](https://github.com/AnalyticalGraphicsInc/3d-tiles/blob/master/README.md) for streaming massive heterogeneous 3D geospatial datasets.  The new Cesium types are:
    * `Cesium3DTileset`
    * `Cesium3DTile`
+   * `Cesium3DTileFeature`
+   * `Cesium3DTileBatchTableResources`
    * `Batched3DModel3DTileContentProvider`
    * `Instanced3DModel3DTileContentProvider`
    * `Points3DTileContentProvider`
    * `Composite3DTileContentProvider`
    * `Tileset3DTileContentProvider`
    * `Empty3DTileContentProvider`
-   * `BatchedModel`
-   * `Cesium3DTileBatchTableResources`
 
 TODO: these are still private:
 * Added `vertexShaderLoaded`, `fragmentShaderLoaded`, `uniformMapLoaded`, `pickVertexShaderLoaded`, `pickFragmentShaderLoaded`, and `pickUniformMapLoaded` callbacks to the `Model` constructor and `Model.fromGltf`.

Source/Scene/Batched3DModel3DTileContentProvider.js

@@ -13,7 +13,7 @@ define([
         '../Core/RequestScheduler',
         '../Core/RequestType',
         '../ThirdParty/when',
-        './BatchedModel',
+        './Cesium3DTileFeature',
         './Cesium3DTileBatchTableResources',
         './Cesium3DTileContentState',
         './Model'
@@ -31,7 +31,7 @@ define([
         RequestScheduler,
         RequestType,
         when,
-        BatchedModel,
+        Cesium3DTileFeature,
         Cesium3DTileBatchTableResources,
         Cesium3DTileContentState,
         Model) {
@@ -78,23 +78,23 @@ define([
          */
         this.readyPromise = when.defer();
 
-        this._batchLength = 0;
+        this._featuresLength = 0;
         this._batchTableResources = undefined;
-        this._models = undefined;
+        this._features = undefined;
     }
 
     defineProperties(Batched3DModel3DTileContentProvider.prototype, {
         /**
-         * DOC_TBA
+         * Gets the number of features in the tile, i.e., the number of 3D models in the batch.
          *
          * @memberof Batched3DModel3DTileContentProvider.prototype
          *
          * @type {Number}
          * @readonly
          */
-        batchLength : {
+        featuresLength : {
             get : function() {
-                return this._batchLength;
+                return this._featuresLength;
             }
         },
 
@@ -108,31 +108,31 @@ define([
         }
     });
 
-    function createModels(content) {
+    function createFeatures(content) {
         var tileset = content._tileset;
-        var batchLength = content._batchLength;
-        if (!defined(content._models) && (batchLength > 0)) {
-            var models = new Array(batchLength);
-            for (var i = 0; i < batchLength; ++i) {
-                models[i] = new BatchedModel(tileset, content._batchTableResources, i);
+        var featuresLength = content._featuresLength;
+        if (!defined(content._features) && (featuresLength > 0)) {
+            var features = new Array(featuresLength);
+            for (var i = 0; i < featuresLength; ++i) {
+                features[i] = new Cesium3DTileFeature(tileset, content._batchTableResources, i);
             }
-            content._models = models;
+            content._features = features;
         }
     }
 
     /**
      * DOC_TBA
      */
-    Batched3DModel3DTileContentProvider.prototype.getModel = function(batchId) {
-        var batchLength = this._batchLength;
+    Batched3DModel3DTileContentProvider.prototype.getFeature = function(batchId) {
+        var featuresLength = this._featuresLength;
         //>>includeStart('debug', pragmas.debug);
-        if (!defined(batchId) || (batchId < 0) || (batchId >= batchLength)) {
-            throw new DeveloperError('batchId is required and between zero and batchLength - 1 (' + (batchLength - 1) + ').');
+        if (!defined(batchId) || (batchId < 0) || (batchId >= featuresLength)) {
+            throw new DeveloperError('batchId is required and between zero and featuresLength - 1 (' + (featuresLength - 1) + ').');
         }
         //>>includeEnd('debug');
 
-        createModels(this);
-        return this._models[batchId];
+        createFeatures(this);
+        return this._features[batchId];
     };
 
     var sizeOfUint32 = Uint32Array.BYTES_PER_ELEMENT;
@@ -197,7 +197,7 @@ define([
         byteOffset += sizeOfUint32;
 
         var batchLength = view.getUint32(byteOffset, true);
-        this._batchLength = batchLength;
+        this._featuresLength = batchLength;
         byteOffset += sizeOfUint32;
 
         var batchTableResources = new Cesium3DTileBatchTableResources(this, batchLength);

Source/Scene/Cesium3DTileBatchTableResources.js

@@ -42,8 +42,9 @@ define([
     /**
      * DOC_TBA
      */
-    function Cesium3DTileBatchTableResources(contentProvider, size) {
-        this._batchLength = defaultValue(size, 0);
+    function Cesium3DTileBatchTableResources(contentProvider, featuresLength) {
+        featuresLength = defaultValue(featuresLength, 0);
+        this._featuresLength = featuresLength;
         this._batchValues = undefined;  // Per-model show/color
         this._batchValuesDirty = false;
         this._batchTexture = undefined;
@@ -59,12 +60,11 @@ define([
         var textureDimensions;
         var textureStep;
 
-        var batchLength = this._batchLength;
-        if (batchLength > 0) {
+        if (featuresLength > 0) {
             // PERFORMANCE_IDEA: this can waste memory in the last row in the uncommon case
             // when more than one row is needed (e.g., > 16K models in one tile)
-            var width = Math.min(batchLength, ContextLimits.maximumTextureSize);
-            var height = Math.ceil(batchLength / ContextLimits.maximumTextureSize);
+            var width = Math.min(featuresLength, ContextLimits.maximumTextureSize);
+            var height = Math.ceil(featuresLength / ContextLimits.maximumTextureSize);
             var stepX = 1.0 / width;
             var centerX = stepX * 0.5;
             var stepY = 1.0 / height;
@@ -87,9 +87,9 @@ define([
          * @type {Number}
          * @readonly
          */
-        batchLength : {
+        featuresLength : {
             get : function() {
-                return this._batchLength;
+                return this._featuresLength;
             }
         },
 
@@ -134,10 +134,10 @@ define([
      * DOC_TBA
      */
     Cesium3DTileBatchTableResources.prototype.setShow = function(batchId, value) {
-        var batchLength = this._batchLength;
+        var featuresLength = this._featuresLength;
         //>>includeStart('debug', pragmas.debug);
-        if (!defined(batchId) || (batchId < 0) || (batchId > batchLength)) {
-            throw new DeveloperError('batchId is required and between zero and batchLength - 1 (' + batchLength - + ').');
+        if (!defined(batchId) || (batchId < 0) || (batchId > featuresLength)) {
+            throw new DeveloperError('batchId is required and between zero and featuresLength - 1 (' + featuresLength - + ').');
         }
 
         if (!defined(value)) {
@@ -164,10 +164,10 @@ define([
      * DOC_TBA
      */
     Cesium3DTileBatchTableResources.prototype.getShow = function(batchId) {
-        var batchLength = this._batchLength;
+        var featuresLength = this._featuresLength;
         //>>includeStart('debug', pragmas.debug);
-        if (!defined(batchId) || (batchId < 0) || (batchId > batchLength)) {
-            throw new DeveloperError('batchId is required and between zero and batchLength - 1 (' + batchLength - + ').');
+        if (!defined(batchId) || (batchId < 0) || (batchId > featuresLength)) {
+            throw new DeveloperError('batchId is required and between zero and featuresLength - 1 (' + featuresLength - + ').');
         }
         //>>includeEnd('debug');
 
@@ -186,10 +186,10 @@ define([
      * DOC_TBA
      */
     Cesium3DTileBatchTableResources.prototype.setColor = function(batchId, value) {
-        var batchLength = this._batchLength;
+        var featuresLength = this._featuresLength;
         //>>includeStart('debug', pragmas.debug);
-        if (!defined(batchId) || (batchId < 0) || (batchId > batchLength)) {
-            throw new DeveloperError('batchId is required and between zero and batchLength - 1 (' + batchLength - + ').');
+        if (!defined(batchId) || (batchId < 0) || (batchId > featuresLength)) {
+            throw new DeveloperError('batchId is required and between zero and featuresLength - 1 (' + featuresLength - + ').');
         }
 
         if (!defined(value)) {
@@ -226,8 +226,8 @@ define([
         }
         //>>includeEnd('debug');
 
-        var batchLength = this._batchLength;
-        for (var i = 0; i < batchLength; ++i) {
+        var featuresLength = this._featuresLength;
+        for (var i = 0; i < featuresLength; ++i) {
             // PERFORMANCE_IDEA: duplicate part of setColor here to factor things out of the loop
             this.setColor(i, value);
         }
@@ -237,10 +237,10 @@ define([
      * DOC_TBA
      */
     Cesium3DTileBatchTableResources.prototype.getColor = function(batchId, result) {
-        var batchLength = this._batchLength;
+        var featuresLength = this._featuresLength;
         //>>includeStart('debug', pragmas.debug);
-        if (!defined(batchId) || (batchId < 0) || (batchId > batchLength)) {
-            throw new DeveloperError('batchId is required and between zero and batchLength - 1 (' + batchLength - + ').');
+        if (!defined(batchId) || (batchId < 0) || (batchId > featuresLength)) {
+            throw new DeveloperError('batchId is required and between zero and featuresLength - 1 (' + featuresLength - + ').');
         }
 
         if (!defined(result)) {
@@ -296,10 +296,10 @@ define([
      * DOC_TBA
      */
     Cesium3DTileBatchTableResources.prototype.getProperty = function(batchId, name) {
-        var batchLength = this._batchLength;
+        var featuresLength = this._featuresLength;
         //>>includeStart('debug', pragmas.debug);
-        if (!defined(batchId) || (batchId < 0) || (batchId > batchLength)) {
-            throw new DeveloperError('batchId is required and between zero and batchLength - 1 (' + batchLength - + ').');
+        if (!defined(batchId) || (batchId < 0) || (batchId > featuresLength)) {
+            throw new DeveloperError('batchId is required and between zero and featuresLength - 1 (' + featuresLength - + ').');
         }
 
         if (!defined(name)) {
@@ -324,10 +324,10 @@ define([
      * DOC_TBA
      */
     Cesium3DTileBatchTableResources.prototype.setProperty = function(batchId, name, value) {
-        var batchLength = this._batchLength;
+        var featuresLength = this._featuresLength;
         //>>includeStart('debug', pragmas.debug);
-        if (!defined(batchId) || (batchId < 0) || (batchId > batchLength)) {
-            throw new DeveloperError('batchId is required and between zero and batchLength - 1 (' + batchLength - + ').');
+        if (!defined(batchId) || (batchId < 0) || (batchId > featuresLength)) {
+            throw new DeveloperError('batchId is required and between zero and featuresLength - 1 (' + featuresLength - + ').');
         }
 
         if (!defined(name)) {
@@ -344,15 +344,15 @@ define([
 
         if (!defined(propertyValues)) {
             // Property does not exist.  Create it.
-            this._batchTable[name] = new Array(batchLength);
+            this._batchTable[name] = new Array(featuresLength);
             propertyValues = this._batchTable[name];
         }
 
         propertyValues[batchId] = clone(value, true);
     };
 
     function getGlslComputeSt(batchTableResources) {
-        // GLSL batchId is zero-based: [0, batchLength - 1]
+        // GLSL batchId is zero-based: [0, featuresLength - 1]
         if (batchTableResources._textureDimensions.y === 1) {
             return 'uniform vec4 tiles3d_textureStep; \n' +
                 'vec2 computeSt(float batchId) \n' +
@@ -381,7 +381,7 @@ define([
      * @private
      */
     Cesium3DTileBatchTableResources.prototype.getVertexShaderCallback = function() {
-        if (this._batchLength === 0) {
+        if (this._featuresLength === 0) {
             // Do not change vertex shader source; the model was not batched
             return undefined;
         }
@@ -423,7 +423,7 @@ define([
      * @private
      */
     Cesium3DTileBatchTableResources.prototype.getFragmentShaderCallback = function() {
-        if (this._batchLength === 0) {
+        if (this._featuresLength === 0) {
             // Do not change fragment shader source; the model was not batched
             return undefined;
         }
@@ -491,7 +491,7 @@ define([
      * @private
      */
     Cesium3DTileBatchTableResources.prototype.getUniformMapCallback = function() {
-        if (this._batchLength === 0) {
+        if (this._featuresLength === 0) {
             // Do not change the uniform map; the model was not batched
             return undefined;
         }
@@ -519,7 +519,7 @@ define([
      * @private
      */
     Cesium3DTileBatchTableResources.prototype.getPickVertexShaderCallback = function() {
-        if (this._batchLength === 0) {
+        if (this._featuresLength === 0) {
             // Do not change vertex shader source; the model was not batched
             return undefined;
         }
@@ -561,7 +561,7 @@ define([
      * @private
      */
     Cesium3DTileBatchTableResources.prototype.getPickFragmentShaderCallback = function() {
-        if (this._batchLength === 0) {
+        if (this._featuresLength === 0) {
             // Do not change fragment shader source; the model was not batched
             return undefined;
         }
@@ -611,7 +611,7 @@ define([
      * @private
      */
     Cesium3DTileBatchTableResources.prototype.getPickUniformMapCallback = function() {
-        if (this._batchLength === 0) {
+        if (this._featuresLength === 0) {
             // Do not change the uniform map; the model was not batched
             return undefined;
         }
@@ -658,8 +658,8 @@ define([
     }
 
     function createPickTexture(batchTableResources, context) {
-        var batchLength = batchTableResources._batchLength;
-        if (!defined(batchTableResources._pickTexture) && (batchLength > 0)) {
+        var featuresLength = batchTableResources._featuresLength;
+        if (!defined(batchTableResources._pickTexture) && (featuresLength > 0)) {
             var pickIds = batchTableResources._pickIds;
             var byteLength = getByteLength(batchTableResources);
             var bytes = new Uint8Array(byteLength);
@@ -669,8 +669,8 @@ define([
             // a continuous range of pickIds and then converting the base pickId + batchId
             // to RGBA in the shader.  The only consider is precision issues, which might
             // not be an issue in WebGL 2.
-            for (var i = 0; i < batchLength; ++i) {
-                var pickId = context.createPickId(contentProvider.getModel(i));
+            for (var i = 0; i < featuresLength; ++i) {
+                var pickId = context.createPickId(contentProvider.getFeature(i));
                 pickIds.push(pickId);
 
                 var pickColor = pickId.color;