Cleanup

CHANGES.md

@@ -5,8 +5,10 @@ Change Log
 
 * Deprecated
    * `GoogleEarthImageryProvider` has been deprecated and will be removed in Cesium 1.37, use `GoogleEarthEnterpriseMapsProvider` instead. 
-   * The `throttleRequest` parameter for `TerrainProvider.requestTileGeometry`, `CesiumTerrainProvider.requestTileGeometry`, `VRTheWorldTerrainProvider.requestTileGeometry`, and `EllipsoidTerrainProvider.requestTileGeometry` is deprecated and will be replaced with an optional `Request` object. The `throttleRequests` parameter will be removed in 1.36, instead to throttle requests set the request's `throttle` property to `true`. 
-   * The ability to provide a Promise for the `options.url` parameter of `loadWithXhr` is deprecated. The same applies for the `url` parameter for `loadArrayBuffer`, `loadBlob`, `loadImageViaBlob`, `loadText`, `loadJson`, `loadXML`, `loadImage`, `loadCRN`, `loadKTX`, and `loadCubeMap`. This will be removed in 1.36, instead `url` must be a string.
+   * The `throttleRequest` parameter for `TerrainProvider.requestTileGeometry`, `CesiumTerrainProvider.requestTileGeometry`, `VRTheWorldTerrainProvider.requestTileGeometry`, and `EllipsoidTerrainProvider.requestTileGeometry` is deprecated and will be replaced with an optional `Request` object. The `throttleRequests` parameter will be removed in 1.37. Instead to throttle requests set the request's `throttle` property to `true`.
+   * The ability to provide a Promise for the `options.url` parameter of `loadWithXhr` and for the `url` parameter of `loadArrayBuffer`, `loadBlob`, `loadImageViaBlob`, `loadText`, `loadJson`, `loadXML`, `loadImage`, `loadCRN`, `loadKTX`, and `loadCubeMap` is deprecated. This will be removed in 1.37, instead `url` must be a string.
+
+* Added an `options.request` parameter to `loadWithXhr` and a `request` parameter to `loadArrayBuffer`, `loadBlob`, `loadImageViaBlob`, `loadText`, `loadJson`, `loadJsonp`, `loadXML`, `loadImageFromTypedArray`, `loadImage`, `loadCRN`, and `loadKTX`.
 
 ### 1.34 - 2017-06-01
 

Source/Core/CesiumTerrainProvider.js

@@ -493,7 +493,7 @@ 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.
+     * @param {Request} [request] The request object. Intended for internal use only.
      *
      * @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
@@ -534,7 +534,7 @@ define([
         }
 
         if (typeof request === 'boolean') {
-            deprecationWarning('throttleRequests', 'The throttleRequest parameter for requestTileGeometry was deprecated in Cesium 1.35.  It will be removed in 1.36.');
+            deprecationWarning('throttleRequests', 'The throttleRequest parameter for requestTileGeometry was deprecated in Cesium 1.35.  It will be removed in 1.37.');
             request = new Request({
                 throttle : request,
                 throttleByServer : request,

Source/Core/EllipsoidTerrainProvider.js

@@ -152,7 +152,7 @@ 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.
+     * @param {Request} [request] The request object. Intended for internal use only.
      *
      * @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

Source/Core/GoogleEarthEnterpriseMetadata.js

@@ -294,7 +294,7 @@ define([
      *
      * @param {String} [quadKey=''] The quadkey to retrieve the packet for.
      * @param {Number} [version=1] The cnode version to be used in the request.
-     * @param {Request} [request] The request object.
+     * @param {Request} [request] The request object. Intended for internal use only.
      *
      * @private
      */
@@ -373,7 +373,7 @@ define([
      * @param {Number} x The tile X coordinate.
      * @param {Number} y The tile Y coordinate.
      * @param {Number} level The tile level.
-     * @param {Request} [request] The request object.
+     * @param {Request} [request] The request object. Intended for internal use only.
      *
      * @returns {Promise<GoogleEarthEnterpriseTileInformation>} A promise that resolves to the tile info for the requested quad key
      *
@@ -409,7 +409,7 @@ define([
                         throttle : request.throttle,
                         throttleByServer : request.throttleByServer,
                         type : request.type,
-                        distance : request.distance
+                        priorityFunction : request.priorityFunction
                     });
                     return populateSubtree(that, quadKey, subtreeRequest);
                 });
@@ -439,7 +439,7 @@ define([
                     throttle : request.throttle,
                     throttleByServer : request.throttleByServer,
                     type : request.type,
-                    distance : request.distance
+                    priorityFunction : request.priorityFunction
                 });
                 return populateSubtree(that, quadKey, subtreeRequest);
             })

Source/Core/GoogleEarthEnterpriseTerrainProvider.js

@@ -346,7 +346,7 @@ 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.
+     * @param {Request} [request] The request object. Intended for internal use only.
      * @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.
@@ -448,7 +448,7 @@ define([
             sharedRequest = terrainRequests[q];
         } else { // Create new request for terrain
             if (typeof request === 'boolean') {
-                deprecationWarning('throttleRequests', 'The throttleRequest parameter for requestTileGeometry was deprecated in Cesium 1.35.  It will be removed in 1.36.');
+                deprecationWarning('throttleRequests', 'The throttleRequest parameter for requestTileGeometry was deprecated in Cesium 1.35.  It will be removed in 1.37.');
                 request = new Request({
                     throttle : request,
                     throttleByServer : request,

Source/Core/Heap.js

@@ -18,14 +18,16 @@ define([
      * @constructor
      * @private
      *
-     * @param {Function} comparator The comparator to use for the heap. If comparator(a, b) is less than 0, sort a to a lower index than b, otherwise sort to a higher index.
+     * @param {Object} options Object with the following properties:
+     * @param {Function} options.comparator The comparator to use for the heap. If comparator(a, b) is less than 0, sort a to a lower index than b, otherwise sort to a higher index.
      */
-    function Heap(comparator) {
+    function Heap(options) {
         //>>includeStart('debug', pragmas.debug);
-        Check.defined('comparator', comparator);
+        Check.typeOf.object('options', options);
+        Check.defined('options.comparator', options.comparator);
         //>>includeEnd('debug');
 
-        this._comparator = comparator;
+        this._comparator = options.comparator;
         this._array = [];
         this._length = 0;
         this._maximumLength = undefined;
@@ -78,6 +80,19 @@ define([
                     this._array.length = value;
                 }
             }
+        },
+
+        /**
+         * The comparator to use for the heap. If comparator(a, b) is less than 0, sort a to a lower index than b, otherwise sort to a higher index.
+         *
+         * @memberof Heap.prototype
+         *
+         * @type (Function}
+         */
+        comparator : {
+            get : function() {
+                return this._comparator;
+            }
         }
     });
 
@@ -156,6 +171,7 @@ define([
 
         var array = this._array;
         var comparator = this._comparator;
+        var maximumLength = this._maximumLength;
 
         var index = this._length++;
         if (index < array.length) {
@@ -176,9 +192,9 @@ define([
 
         var removedElement;
 
-        if (defined(this._maximumLength) && (this._length > this._maximumLength)) {
-            removedElement = array[this.maximumLength];
-            this._length = this._maximumLength;
+        if (defined(maximumLength) && (this._length > maximumLength)) {
+            removedElement = array[maximumLength];
+            this._length = maximumLength;
         }
 
         return removedElement;

Source/Core/Request.js

@@ -14,19 +14,20 @@ define([
     'use strict';
 
     /**
-     * Stores information for making a request. This should not be constructed directly. Instead, call the appropriate load function, like `loadWithXhr`, `loadImage`, etc.
+     * Stores information for making a request. In general this does not need to be constructed directly.
      *
      * @alias Request
      * @constructor
      *
      * @param {Object} [options] An object with the following properties:
      * @param {Boolean} [options.url] The url to request.
      * @param {Function} [options.requestFunction] The actual function that makes the request. The function takes no arguments and returns a promise for the requested data.
+     * @param {Function} [options.cancelFunction] Function to call when a request is cancelled. The function takes no arguments.
+     * @param {Function} [options.priorityFunction] Function that is called when the request is updated. The function takes no arguments and returns the updated priority value.
+     * @param {Number} [options.priority=0.0] The initial priority of the request.
      * @param {Boolean} [options.throttle=false] Whether to throttle and prioritize the request. If false, the request will be sent immediately. If true, the request will be throttled and sent based on priority.
      * @param {Boolean} [options.throttleByServer=false] Whether to throttle the request by server.
      * @param {RequestType} [options.type=RequestType.OTHER] The type of request.
-     * @param {Number} [options.distance=0.0] The distance from the camera, used to prioritize requests.
-     * @param {Number} [options.screenSpaceError=0.0] The screen space error, used to prioritize requests.
      */
     function Request(options) {
         options = defaultValue(options, defaultValue.EMPTY_OBJECT);
@@ -45,11 +46,35 @@ define([
          * The actual function that makes the request. The function takes no arguments and returns a promise for the requested data.
          *
          * @type {Function}
-         *
-         * @private
          */
         this.requestFunction = options.requestFunction;
 
+        /**
+         * Function to call when a request is cancelled. The function takes no arguments.
+         *
+         * @type {Function}
+         */
+        this.cancelFunction = options.cancelFunction;
+
+        /**
+         * Function that is called when the request is updated. The function takes no arguments and returns the updated priority value.
+         *
+         * @type {Function}
+         */
+        this.priorityFunction = options.priorityFunction;
+
+        /**
+         * Priority is a unit-less value where lower values represent higher priority.
+         * For world-based objects, this is usually the distance from the camera.
+         * A request that does not have a priority function defaults to a priority of 0.
+         *
+         * If priorityFunction is defined, this value is updated every frame with the result of that call.
+         *
+         * @type {Number}
+         * @default 0.0
+         */
+        this.priority = defaultValue(options.priority, 0.0);
+
         /**
          * Whether to throttle and prioritize the request. If false, the request will be sent immediately. If true, the
          * request will be throttled and sent based on priority.
@@ -84,52 +109,22 @@ define([
         this.type = defaultValue(options.type, RequestType.OTHER);
 
         /**
-         * The distance from the camera, used to prioritize requests. This value may be edited continually to update
-         * the request's priority.
-         *
-         * @type {Number}
-         *
-         * @default 0.0
-         */
-        this.distance = defaultValue(options.distance, 0.0);
-
-        /**
-         * The screen space error, used to prioritize requests. This value may be edited continually to update
-         * the request's priority.
-         *
-         * @type {Number}
-         *
-         * @default 0.0
-         */
-        this.screenSpaceError = defaultValue(options.screenSpaceError, 0.0);
-
-        /**
-         * The request server, derived from the url.
+         * A key used to identify the server that a request is going to. It is derived from the url's authority and scheme.
          *
          * @type {String}
          *
          * @private
          */
-        this.server = undefined;
+        this.serverKey = undefined;
 
         /**
          * The current state of the request.
          *
          * @type {RequestState}
-         *
-         * @private
+         * @readonly
          */
         this.state = RequestState.UNISSUED;
 
-        /**
-         * Reference to the underlying XMLHttpRequest so that it may be aborted in RequestScheduler.
-         *
-         * @type {Object}
-         *
-         * @private
-         */
-        this.xhr = undefined;
-
         /**
          * The requests's deferred promise.
          *