Request Scheduler Prioritization

CHANGES.md

@@ -10,6 +10,8 @@ Change Log
 
 * Breaking changes
     * Removed `OpenStreetMapImageryProvider`. Use `createOpenStreetMapImageryProvider` instead.
+* Deprecated
+    * Deprecated `throttleRequests` flag in `TerrainProvider`. It is replaced by an optional `Request` object that stores information used to prioritize requests.
 * Reduced the amount of CPU memory used by terrain by ~25% in Chrome.
 * Fixed a picking problem ([#3386](https://github.com/AnalyticalGraphicsInc/cesium/issues/3386)) that sometimes prevented objects being selected.
 * Added `Scene.useDepthPicking` to enable or disable picking using the depth buffer. [#3390](https://github.com/AnalyticalGraphicsInc/cesium/pull/3390)

Source/Core/ArcGisImageServerTerrainProvider.js

@@ -13,7 +13,9 @@ define([
         './HeightmapTerrainData',
         './loadImage',
         './Math',
+        './Request',
         './RequestScheduler',
+        './RequestType',
         './TerrainProvider'
     ], function(
         when,
@@ -29,7 +31,9 @@ define([
         HeightmapTerrainData,
         loadImage,
         CesiumMath,
+        Request,
         RequestScheduler,
+        RequestType,
         TerrainProvider) {
     "use strict";
 
@@ -200,11 +204,13 @@ define([
      * @param {Number} x The X coordinate of the tile for which to request geometry.
      * @param {Number} y The Y coordinate of the tile for which to request geometry.
      * @param {Number} level The level of the tile for which to request geometry.
+     * @param {Request} [request] The request object.
+     *
      * @returns {Promise.<TerrainData>|undefined} A promise for the requested geometry.  If this method
      *          returns undefined instead of a promise, it is an indication that too many requests are already
      *          pending and the request will be retried later.
      */
-    ArcGisImageServerTerrainProvider.prototype.requestTileGeometry = function(x, y, level) {
+    ArcGisImageServerTerrainProvider.prototype.requestTileGeometry = function(x, y, level, request) {
         var rectangle = this._tilingScheme.tileXYToRectangle(x, y, level);
 
         // Each pixel in the heightmap represents the height at the center of that
@@ -231,7 +237,19 @@ define([
             url = proxy.getURL(url);
         }
 
-        var promise = RequestScheduler.throttleRequest(url, loadImage);
+        // TODO : request used to be a boolean called throttleRequest. Continue to handle that case until it is deprecated.
+        if (!defined(request) || (request === false)) {
+            // If a request object isn't provided, perform an immediate request
+            request = new Request({
+                defer : true
+            });
+        }
+
+        request.url = url;
+        request.requestFunction = loadImage;
+        request.type = RequestType.TERRAIN;
+
+        var promise = RequestScheduler.schedule(request);
         if (!defined(promise)) {
             return undefined;
         }

Source/Core/CesiumTerrainProvider.js

@@ -20,7 +20,9 @@ define([
         './Matrix3',
         './OrientedBoundingBox',
         './QuantizedMeshTerrainData',
+        './Request',
         './RequestScheduler',
+        './RequestType',
         './RuntimeError',
         './TerrainProvider',
         './TileProviderError'
@@ -45,7 +47,9 @@ define([
         Matrix3,
         OrientedBoundingBox,
         QuantizedMeshTerrainData,
+        Request,
         RequestScheduler,
+        RequestType,
         RuntimeError,
         TerrainProvider,
         TileProviderError) {
@@ -246,7 +250,7 @@ define([
         }
 
         function requestMetadata() {
-            var metadata = loadJson(metadataUrl);
+            var metadata = RequestScheduler.request(metadataUrl, loadJson);
             when(metadata, metadataSuccess, metadataFailure);
         }
 
@@ -474,17 +478,16 @@ define([
      * @param {Number} x The X coordinate of the tile for which to request geometry.
      * @param {Number} y The Y coordinate of the tile for which to request geometry.
      * @param {Number} level The level of the tile for which to request geometry.
-     * @param {Boolean} [throttleRequests=true] True if the number of simultaneous requests should be limited,
-     *                  or false if the request should be initiated regardless of the number of requests
-     *                  already in progress.
+     * @param {Request} [request] The request object.
+     *
      * @returns {Promise.<TerrainData>|undefined} A promise for the requested geometry.  If this method
      *          returns undefined instead of a promise, it is an indication that too many requests are already
      *          pending and the request will be retried later.
      *
      * @exception {DeveloperError} This function must not be called before {@link CesiumTerrainProvider#ready}
      *            returns true.
      */
-    CesiumTerrainProvider.prototype.requestTileGeometry = function(x, y, level, throttleRequests) {
+    CesiumTerrainProvider.prototype.requestTileGeometry = function(x, y, level, request) {
         //>>includeStart('debug', pragmas.debug)
         if (!this._ready) {
             throw new DeveloperError('requestTileGeometry must not be called before the terrain provider is ready.');
@@ -507,8 +510,6 @@ define([
             url = proxy.getURL(url);
         }
 
-        var promise;
-
         var extensionList = [];
         if (this._requestVertexNormals && this._hasVertexNormals) {
             extensionList.push(this._littleEndianExtensionSize ? "octvertexnormals" : "vertexnormals");
@@ -520,14 +521,22 @@ define([
         function tileLoader(tileUrl) {
             return loadArrayBuffer(tileUrl, getRequestHeader(extensionList));
         }
-        throttleRequests = defaultValue(throttleRequests, true);
-        if (throttleRequests) {
-            promise = RequestScheduler.throttleRequest(url, tileLoader);
-            if (!defined(promise)) {
-                return undefined;
-            }
-        } else {
-            promise = tileLoader(url);
+
+        // TODO : request used to be a boolean called throttleRequest. Continue to handle that case until it is deprecated.
+        if (!defined(request) || (request === false)) {
+            // If a request object isn't provided, perform an immediate request
+            request = new Request({
+                defer : true
+            });
+        }
+
+        request.url = url;
+        request.requestFunction = tileLoader;
+        request.type = RequestType.TERRAIN;
+
+        var promise = RequestScheduler.schedule(request);
+        if (!defined(promise)) {
+            return undefined;
         }
 
         var that = this;

Source/Core/EarthOrientationParameters.js

@@ -9,6 +9,7 @@ define([
         './JulianDate',
         './LeapSecond',
         './loadJson',
+        './RequestScheduler',
         './RuntimeError',
         './TimeConstants',
         './TimeStandard'
@@ -22,6 +23,7 @@ define([
         JulianDate,
         LeapSecond,
         loadJson,
+        RequestScheduler,
         RuntimeError,
         TimeConstants,
         TimeStandard) {
@@ -96,7 +98,7 @@ define([
         } else if (defined(options.url)) {
             // Download EOP data.
             var that = this;
-            this._downloadPromise = when(loadJson(options.url), function(eopData) {
+            this._downloadPromise = when(RequestScheduler.request(options.url, loadJson), function(eopData) {
                 onDataReady(that, eopData);
             }, function() {
                 that._dataError = 'An error occurred while retrieving the EOP data from the URL ' + options.url + '.';

Source/Core/EllipsoidTerrainProvider.js

@@ -160,14 +160,13 @@ define([
      * @param {Number} x The X coordinate of the tile for which to request geometry.
      * @param {Number} y The Y coordinate of the tile for which to request geometry.
      * @param {Number} level The level of the tile for which to request geometry.
-     * @param {Boolean} [throttleRequests=true] True if the number of simultaneous requests should be limited,
-     *                  or false if the request should be initiated regardless of the number of requests
-     *                  already in progress.
+     * @param {Request} [request] The request object.
+     *
      * @returns {Promise.<TerrainData>|undefined} A promise for the requested geometry.  If this method
      *          returns undefined instead of a promise, it is an indication that too many requests are already
      *          pending and the request will be retried later.
      */
-    EllipsoidTerrainProvider.prototype.requestTileGeometry = function(x, y, level, throttleRequests) {
+    EllipsoidTerrainProvider.prototype.requestTileGeometry = function(x, y, level, request) {
         return this._terrainData;
     };
 

Source/Core/Iau2006XysData.js

@@ -7,6 +7,7 @@ define([
         './Iau2006XysSample',
         './JulianDate',
         './loadJson',
+        './RequestScheduler',
         './TimeStandard'
     ], function(
         when,
@@ -16,6 +17,7 @@ define([
         Iau2006XysSample,
         JulianDate,
         loadJson,
+        RequestScheduler,
         TimeStandard) {
     "use strict";
 
@@ -244,7 +246,7 @@ define([
             chunkUrl = buildModuleUrl('Assets/IAU2006_XYS/IAU2006_XYS_' + chunkIndex + '.json');
         }
 
-        when(loadJson(chunkUrl), function(chunk) {
+        when(RequestScheduler.request(chunkUrl, loadJson), function(chunk) {
             xysData._chunkDownloadsInProgress[chunkIndex] = false;
 
             var samples = xysData._samples;

Source/Core/Request.js

@@ -0,0 +1,80 @@
+/*global define*/
+define([
+        './defaultValue'
+    ], function(
+        defaultValue) {
+    "use strict";
+
+    /**
+     * Stores information for making a request using {@link RequestScheduler}.
+     *
+     * @exports Request
+     *
+     * @private
+     */
+    function Request(options) {
+        options = defaultValue(options, defaultValue.EMPTY_OBJECT);
+
+        /**
+         * The URL to request.
+         *
+         * @private
+         */
+        this.url = options.url;
+
+        /**
+         * Extra parameters to send with the request. For example, HTTP headers or jsonp parameters.
+         *
+         * @private
+         */
+        this.parameters = options.parameters;
+
+        /**
+         * The actual function that makes the request.
+         *
+         * @private
+         */
+        this.requestFunction = options.requestFunction;
+
+        /**
+         * Type of request. Used for more fine-grained priority sorting.
+         *
+         * @private
+         */
+        this.type = options.type;
+
+        /**
+         * Specifies that the request should be deferred until an open slot is available.
+         * A deferred request will always return a promise, which is suitable for data
+         * sources and utility functions.
+         *
+         * @private
+         */
+        this.defer = defaultValue(options.defer, false);
+
+        /**
+         * The distance from the camera, used to prioritize requests.
+         *
+         * @private
+         */
+        this.distance = defaultValue(options.distance, 0.0);
+
+        // Helper members for RequestScheduler
+
+        /**
+         * A promise for when a deferred request can start.
+         *
+         * @private
+         */
+        this.startPromise = undefined;
+
+        /**
+         * Reference to a {@link RequestScheduler~RequestServer}.
+         *
+         * @private
+         */
+        this.server = options.server;
+    }
+
+    return Request;
+});