Merge remote-tracking branch 'agi/3d-tiles' into improved-tile-loading

Author: austinEng

Source/Scene/Cesium3DTileset.js

@@ -2,6 +2,7 @@
 define([
         '../Core/Cartesian3',
         '../Core/Cartographic',
+        '../Core/Check',
         '../Core/Color',
         '../Core/clone',
         '../Core/defaultValue',
@@ -51,6 +52,7 @@ define([
     ], function(
         Cartesian3,
         Cartographic,
+        Check,
         Color,
         clone,
         defaultValue,
@@ -111,6 +113,7 @@ define([
      * @param {Boolean} [options.show=true] Determines if the tileset will be shown.
      * @param {Matrix4} [options.modelMatrix=Matrix4.IDENTITY] A 4x4 transformation matrix that transforms the tileset's root tile.
      * @param {Number} [options.maximumScreenSpaceError=16] The maximum screen-space error used to drive level-of-detail refinement.
+     * @param {Number} [options.maximumMemoryUsage=512] The maximum amount of memory in MB that can be used by the tileset.
      * @param {Boolean} [options.refineToVisible=false] Whether replacement refinement should refine when all visible children are ready. An experimental optimization.
      * @param {Boolean} [options.cullWithChildrenBounds=true] Whether to cull tiles using the union of their children bounding volumes.
      * @param {Boolean} [options.dynamicScreenSpaceError=false] Reduce the screen space error for tiles that are further away from the camera.
@@ -271,6 +274,7 @@ define([
         this._maximumScreenSpaceError = defaultValue(options.maximumScreenSpaceError, 16);
         this._baseScreenSpaceError = defaultValue(options.baseScreenSpaceError, 1024);
         this._maximumNumberOfLoadedTiles = defaultValue(options.maximumNumberOfLoadedTiles, 256);
+        this._maximumMemoryUsage = defaultValue(options.maximumMemoryUsage, 512);
         this._styleEngine = new Cesium3DTileStyleEngine();
 
         /**
@@ -497,7 +501,7 @@ define([
          *     console.log('A tile was unloaded from the cache.');
          * });
          *
-         * @see Cesium3DTileset#maximumNumberOfLoadedTiles
+         * @see Cesium3DTileset#maximumMemoryUsage
          * @see Cesium3DTileset#trimLoadedTiles
          */
         this.tileUnload = new Event();
@@ -844,38 +848,38 @@ define([
         },
 
         /**
-         * The maximum number of tiles to load.  Tiles not in view are unloaded to enforce this.
+         * The maximum amount of memory in MB that can be used by the tileset.
+         * Tiles not in view are unloaded to enforce this.
          * <p>
          * If decreasing this value results in unloading tiles, the tiles are unloaded the next frame.
          * </p>
          * <p>
-         * If more tiles than <code>maximumNumberOfLoadedTiles</code> are needed
+         * If tiles sized more than <code>maximumMemoryUsage</code> are needed
          * to meet the desired screen-space error, determined by {@link Cesium3DTileset#maximumScreenSpaceError},
-         * for the current view than the number of tiles loaded will exceed
-         * <code>maximumNumberOfLoadedTiles</code>.  For example, if the maximum is 128 tiles, but
-         * 150 tiles are needed to meet the screen-space error, then 150 tiles may be loaded.  When
+         * for the current view, then the memory usage of the tiles loaded will exceed
+         * <code>maximumMemoryUsage</code>.  For example, if the maximum is 256 MB, but
+         * 300 MB of tiles are needed to meet the screen-space error, then 300 MB of tiles may be loaded.  When
          * these tiles go out of view, they will be unloaded.
          * </p>
          *
          * @memberof Cesium3DTileset.prototype
          *
          * @type {Number}
-         * @default 256
+         * @default 512
          *
-         * @exception {DeveloperError} <code>maximumNumberOfLoadedTiles</code> must be greater than or equal to zero.
+         * @exception {DeveloperError} <code>maximumMemoryUsage</code> must be greater than or equal to zero.
+         * @see Cesium3DTileset#totalMemoryUsageInBytes
          */
-        maximumNumberOfLoadedTiles : {
+        maximumMemoryUsage : {
             get : function() {
-                return this._maximumNumberOfLoadedTiles;
+                return this._maximumMemoryUsage;
             },
             set : function(value) {
                 //>>includeStart('debug', pragmas.debug);
-                if (value < 0) {
-                    throw new DeveloperError('maximumNumberOfLoadedTiles must be greater than or equal to zero');
-                }
+                Check.typeOf.number.greaterThanOrEquals('value', value, 0);
                 //>>includeEnd('debug');
 
-                this._maximumNumberOfLoadedTiles = value;
+                this._maximumMemoryUsage = value;
             }
         },
 
@@ -1010,6 +1014,21 @@ define([
             set : function(value) {
                 this._skipLevels = value;
             }
+        },
+
+        /**
+         * Returns the total amount of memory used in bytes by the tileset.
+         * This is calculated as the sum of the vertex and index buffer, texture memory and batch table size
+         * of the loaded tiles in the tileset.
+         *
+         * @type {Number}
+         * @see Cesium3DTileset#maximumMemoryUsage
+         */
+        totalMemoryUsageInBytes : {
+            get : function() {
+                var stats = this._statistics;
+                return stats.textureMemorySizeInBytes + stats.vertexMemorySizeInBytes + stats.batchTableMemorySizeInBytes;
+            }
         }
     });
 
@@ -1533,17 +1552,19 @@ define([
         tileset._trimTiles = false;
 
         var stats = tileset._statistics;
-        var maximumNumberOfLoadedTiles = tileset._maximumNumberOfLoadedTiles + 1; // + 1 to account for sentinel
         var replacementList = tileset._replacementList;
         var tileUnload = tileset.tileUnload;
 
+        var totalMemoryUsageInBytes = tileset.totalMemoryUsageInBytes;
+        var maximumMemoryUsageInBytes = tileset._maximumMemoryUsage * 1024 * 1024;
+
         // Traverse the list only to the sentinel since tiles/nodes to the
         // right of the sentinel were used this frame.
         //
         // The sub-list to the left of the sentinel is ordered from LRU to MRU.
         var sentinel = tileset._replacementSentinel;
         var node = replacementList.head;
-        while ((node !== sentinel) && ((replacementList.length > maximumNumberOfLoadedTiles) || trimTiles)) {
+        while ((node !== sentinel) && ((totalMemoryUsageInBytes > maximumMemoryUsageInBytes) || trimTiles)) {
             var tile = node.item;
 
             decrementPointAndFeatureLoadCounts(tileset, tile.content);
@@ -1555,13 +1576,14 @@ define([
             replacementList.remove(currentNode);
 
             --stats.numberContentReady;
+            totalMemoryUsageInBytes = tileset.totalMemoryUsageInBytes;
         }
     }
 
     /**
      * Unloads all tiles that weren't selected the previous frame.  This can be used to
      * explicitly manage the tile cache and reduce the total number of tiles loaded below
-     * {@link Cesium3DTileset#maximumNumberOfLoadedTiles}.
+     * {@link Cesium3DTileset#maximumMemoryUsage}.
      * <p>
      * Tile unloads occur at the next frame to keep all the WebGL delete calls
      * within the render loop.

Specs/Scene/Cesium3DTilesetSpec.js

@@ -2009,9 +2009,9 @@ defineSuite([
     ///////////////////////////////////////////////////////////////////////////
     // Cache replacement tests
 
-    it('Unload all cached tiles not required to meet SSE', function() {
+    it('Unload all cached tiles not required to meet SSE using maximumMemoryUsage', function() {
         return Cesium3DTilesTester.loadTileset(scene, tilesetUrl).then(function(tileset) {
-            tileset.maximumNumberOfLoadedTiles = 1;
+            tileset.maximumMemoryUsage = 0;
 
             // Render parent and four children (using additive refinement)
             viewAllTiles();
@@ -2020,28 +2020,31 @@ defineSuite([
             var stats = tileset._statistics;
             expect(stats.numberOfCommands).toEqual(5);
             expect(stats.numberContentReady).toEqual(5); // Five loaded tiles
+            expect(tileset.totalMemoryUsageInBytes).toEqual(44400); // Specific to this tileset
 
             // Zoom out so only root tile is needed to meet SSE.  This unloads
-            // the four children since the max number of loaded tiles is one.
+            // the four children since the maximum memory usage is zero.
             viewRootOnly();
             scene.renderForSpecs();
 
             expect(stats.numberOfCommands).toEqual(1);
             expect(stats.numberContentReady).toEqual(1);
+            expect(tileset.totalMemoryUsageInBytes).toEqual(8880); // Specific to this tileset
 
             // Zoom back in so all four children are re-requested.
             viewAllTiles();
 
             return Cesium3DTilesTester.waitForTilesLoaded(scene, tileset).then(function() {
                 expect(stats.numberOfCommands).toEqual(5);
                 expect(stats.numberContentReady).toEqual(5); // Five loaded tiles
+                expect(tileset.totalMemoryUsageInBytes).toEqual(44400); // Specific to this tileset
             });
         });
     });
 
-    it('Unload some cached tiles not required to meet SSE', function() {
+    it('Unload some cached tiles not required to meet SSE using maximumMemoryUsage', function() {
         return Cesium3DTilesTester.loadTileset(scene, tilesetUrl).then(function(tileset) {
-            tileset.maximumNumberOfLoadedTiles = 3;
+            tileset.maximumMemoryUsage = 0.03;  // Just enough memory to allow 3 tiles to remain
 
             // Render parent and four children (using additive refinement)
             viewAllTiles();
@@ -2053,7 +2056,7 @@ defineSuite([
 
             // Zoom out so only root tile is needed to meet SSE.  This unloads
             // two of the four children so three tiles are still loaded (the
-            // root and two children) since the max number of loaded tiles is three.
+            // root and two children) since the maximum memory usage is sufficient.
             viewRootOnly();
             scene.renderForSpecs();
 
@@ -2070,9 +2073,9 @@ defineSuite([
         });
     });
 
-    it('Unloads cached tiles outside of the view frustum', function() {
+    it('Unloads cached tiles outside of the view frustum using maximumMemoryUsage', function() {
         return Cesium3DTilesTester.loadTileset(scene, tilesetUrl).then(function(tileset) {
-            tileset.maximumNumberOfLoadedTiles = 0;
+            tileset.maximumMemoryUsage = 0;
 
             scene.renderForSpecs();
             var stats = tileset._statistics;
@@ -2098,12 +2101,12 @@ defineSuite([
         });
     });
 
-    it('Unloads cached tiles in a tileset with external tileset.json', function() {
+    it('Unloads cached tiles in a tileset with external tileset.json using maximumMemoryUsage', function() {
         return Cesium3DTilesTester.loadTileset(scene, tilesetOfTilesetsUrl).then(function(tileset) {
             var stats = tileset._statistics;
             var replacementList = tileset._replacementList;
 
-            tileset.maximumNumberOfLoadedTiles = 2;
+            tileset.maximumMemoryUsage = 0.025;
 
             scene.renderForSpecs();
             expect(stats.numberOfCommands).toEqual(5);
@@ -2131,11 +2134,11 @@ defineSuite([
         });
     });
 
-    it('Unloads cached tiles in a tileset with empty tiles', function() {
+    it('Unloads cached tiles in a tileset with empty tiles using maximumMemoryUsage', function() {
         return Cesium3DTilesTester.loadTileset(scene, tilesetEmptyRootUrl).then(function(tileset) {
             var stats = tileset._statistics;
 
-            tileset.maximumNumberOfLoadedTiles = 2;
+            tileset.maximumMemoryUsage = 0.025;
 
             scene.renderForSpecs();
             expect(stats.numberOfCommands).toEqual(4);
@@ -2160,15 +2163,15 @@ defineSuite([
         });
     });
 
-    it('Unload cached tiles when a tileset uses replacement refinement', function() {
+    it('Unload cached tiles when a tileset uses replacement refinement using maximumMemoryUsage', function() {
         // No children have content, but all grandchildren have content
         //
         //          C
         //      E       E
         //    C   C   C   C
         //
         return Cesium3DTilesTester.loadTileset(scene, tilesetReplacement1Url).then(function(tileset) {
-            tileset.maximumNumberOfLoadedTiles = 1;
+            tileset.maximumMemoryUsage = 0; // Only root needs to be visible
 
             // Render parent and four children (using additive refinement)
             viewAllTiles();
@@ -2198,7 +2201,7 @@ defineSuite([
 
     it('Explicitly unloads cached tiles with trimLoadedTiles', function() {
         return Cesium3DTilesTester.loadTileset(scene, tilesetUrl).then(function(tileset) {
-            tileset.maximumNumberOfLoadedTiles = 5;
+            tileset.maximumMemoryUsage = 0.05;
 
             // Render parent and four children (using additive refinement)
             viewAllTiles();
@@ -2226,7 +2229,7 @@ defineSuite([
 
     it('tileUnload event is raised', function() {
         return Cesium3DTilesTester.loadTileset(scene, tilesetUrl).then(function(tileset) {
-            tileset.maximumNumberOfLoadedTiles = 1;
+            tileset.maximumMemoryUsage = 0;
 
             // Render parent and four children (using additive refinement)
             viewAllTiles();
@@ -2252,12 +2255,12 @@ defineSuite([
         });
     });
 
-    it('maximumNumberOfLoadedTiles throws when negative', function() {
+    it('maximumMemoryUsage throws when negative', function() {
         var tileset = new Cesium3DTileset({
             url : tilesetUrl
         });
         expect(function() {
-            tileset.maximumNumberOfLoadedTiles = -1;
+            tileset.maximumMemoryUsage = -1;
         }).toThrowDeveloperError();
     });