cesium 0.13.0

data/app/assets/javascripts/Scene/ImageryLayerCollection.js

@@ -0,0 +1,403 @@
+/*global define*/
+define([
+        '../Core/DeveloperError',
+        '../Core/defaultValue',
+        '../Core/destroyObject',
+        '../Core/Event',
+        '../Core/Math',
+        './ImageryLayer'
+    ], function(
+        DeveloperError,
+        defaultValue,
+        destroyObject,
+        Event,
+        CesiumMath,
+        ImageryLayer) {
+    "use strict";
+
+    /**
+     * An ordered collection of imagery layers.
+     *
+     * @alias ImageryLayerCollection
+     * @constructor
+     */
+    var ImageryLayerCollection = function ImageryLayerCollection() {
+        this._layers = [];
+
+        /**
+         * An event that is raised when a layer is added to the collection.  Event handlers are passed the layer that
+         * was added and the index at which it was added.
+         * @type {Event}
+         */
+        this.layerAdded = new Event();
+
+        /**
+         * An event that is raised when a layer is removed from the collection.  Event handlers are passed the layer that
+         * was removed and the index from which it was removed.
+         * @type {Event}
+         */
+        this.layerRemoved = new Event();
+
+        /**
+         * An event that is raised when a layer changes position in the collection.  Event handlers are passed the layer that
+         * was moved, its new index after the move, and its old index prior to the move.
+         * @type {Event}
+         */
+        this.layerMoved = new Event();
+
+        /**
+         * An event that is raised when a layer is shown or hidden by setting the
+         * {@link ImageryLayer#show} property.  Event handlers are passed a reference to this layer,
+         * the index of the layer in the collection, and a flag that is true if the layer is now
+         * shown or false if it is now hidden.
+         *
+         * @type {Event}
+         */
+        this.layerShownOrHidden = new Event();
+    };
+
+    /**
+     * Adds a layer to the collection.
+     *
+     * @memberof ImageryLayerCollection
+     *
+     * @param {ImageryLayer} layer the layer to add.
+     * @param {Number} [index] the index to add the layer at.  If omitted, the layer will
+     *                         added on top of all existing layers.
+     *
+     * @exception {DeveloperError} layer is required.
+     * @exception {DeveloperError} index, if supplied, must be greater than or equal to zero and less than or equal to the number of the layers.
+     */
+    ImageryLayerCollection.prototype.add = function(layer, index) {
+        if (typeof layer === 'undefined') {
+            throw new DeveloperError('layer is required.');
+        }
+
+        if (typeof index === 'undefined') {
+            index = this._layers.length;
+            this._layers.push(layer);
+        } else {
+            if (index < 0) {
+                throw new DeveloperError('index must be greater than or equal to zero.');
+            } else if (index > this._layers.length) {
+                throw new DeveloperError('index must be less than or equal to the number of layers.');
+            }
+            this._layers.splice(index, 0, layer);
+        }
+
+        this._update();
+
+        this.layerAdded.raiseEvent(layer, index);
+    };
+
+    /**
+     * Creates a new layer using the given ImageryProvider and adds it to the collection.
+     *
+     * @memberof ImageryLayerCollection
+     *
+     * @param {ImageryProvider} imageryProvider the imagery provider to create a new layer for.
+     * @param {Number} [index] the index to add the layer at.  If omitted, the layer will
+     *                         added on top of all existing layers.
+     *
+     * @returns {ImageryLayer} The newly created layer.
+     *
+     * @exception {DeveloperError} imageryProvider is required.
+     */
+    ImageryLayerCollection.prototype.addImageryProvider = function(imageryProvider, index) {
+        if (typeof imageryProvider === 'undefined') {
+            throw new DeveloperError('imageryProvider is required.');
+        }
+
+        var layer = new ImageryLayer(imageryProvider);
+        this.add(layer, index);
+        return layer;
+    };
+
+    /**
+     * Removes a layer from this collection, if present.
+     *
+     * @memberof ImageryLayerCollection
+     *
+     * @param {ImageryLayer} layer The layer to remove.
+     * @param {Boolean} [destroy=true] whether to destroy the layers in addition to removing them.
+     *
+     * @returns {Boolean} true if the layer was in the collection and was removed,
+     *                    false if the layer was not in the collection.
+     */
+    ImageryLayerCollection.prototype.remove = function(layer, destroy) {
+        destroy = defaultValue(destroy, true);
+
+        var index = this._layers.indexOf(layer);
+        if (index !== -1) {
+            this._layers.splice(index, 1);
+
+            this._update();
+
+            this.layerRemoved.raiseEvent(layer, index);
+
+            if (destroy) {
+                layer.destroy();
+            }
+
+            return true;
+        }
+
+        return false;
+    };
+
+    /**
+     * Removes all layers from this collection.
+     *
+     * @memberof ImageryLayerCollection
+     *
+     * @param {Boolean} [destroy=true] whether to destroy the layers in addition to removing them.
+     */
+    ImageryLayerCollection.prototype.removeAll = function(destroy) {
+        destroy = defaultValue(destroy, true);
+
+        var layers = this._layers;
+        for ( var i = 0, len = layers.length; i < len; i++) {
+            var layer = layers[i];
+            this.layerRemoved.raiseEvent(layer, i);
+
+            if (destroy) {
+                layer.destroy();
+            }
+        }
+
+        this._layers = [];
+    };
+
+    /**
+     * Checks to see if the collection contains a given layer.
+     *
+     * @memberof ImageryLayerCollection
+     *
+     * @param {ImageryLayer} layer the layer to check for.
+     *
+     * @returns {Boolean} true if the collection contains the layer, false otherwise.
+     */
+    ImageryLayerCollection.prototype.contains = function(layer) {
+        return this.indexOf(layer) !== -1;
+    };
+
+    /**
+     * Determines the index of a given layer in the collection.
+     *
+     * @memberof ImageryLayerCollection
+     *
+     * @param {ImageryLayer} layer The layer to find the index of.
+     *
+     * @returns {Number} The index of the layer in the collection, or -1 if the layer does not exist in the collection.
+     */
+    ImageryLayerCollection.prototype.indexOf = function(layer) {
+        return this._layers.indexOf(layer);
+    };
+
+    /**
+     * Gets a layer by index from the collection.
+     *
+     * @memberof ImageryLayerCollection
+     *
+     * @param {Number} index the index to retrieve.
+     *
+     * @exception {DeveloperError} index is required.
+     * @exception {DeveloperError} This object was destroyed, i.e., destroy() was called.
+     */
+    ImageryLayerCollection.prototype.get = function(index) {
+        if (typeof index === 'undefined') {
+            throw new DeveloperError('index is required.', 'index');
+        }
+
+        return this._layers[index];
+    };
+
+    /**
+     * Gets the number of layers in this collection.
+     *
+     * @memberof ImageryLayerCollection
+     *
+     * @exception {DeveloperError} This object was destroyed, i.e., destroy() was called.
+     */
+    ImageryLayerCollection.prototype.getLength = function() {
+        return this._layers.length;
+    };
+
+    function getLayerIndex(layers, layer) {
+        if (typeof layer === 'undefined') {
+            throw new DeveloperError('layer is required.');
+        }
+
+        var index = layers.indexOf(layer);
+        if (index === -1) {
+            throw new DeveloperError('layer is not in this collection.');
+        }
+
+        return index;
+    }
+
+    function swapLayers(collection, i, j) {
+        var arr = collection._layers;
+        i = CesiumMath.clamp(i, 0, arr.length - 1);
+        j = CesiumMath.clamp(j, 0, arr.length - 1);
+
+        if (i === j) {
+            return;
+        }
+
+        var temp = arr[i];
+        arr[i] = arr[j];
+        arr[j] = temp;
+
+        collection._update();
+
+        collection.layerMoved.raiseEvent(temp, j, i);
+    }
+
+    /**
+     * Raises a layer up one position in the collection.
+     *
+     * @memberof ImageryLayerCollection
+     *
+     * @param {ImageryLayer} layer the layer to move.
+     *
+     * @exception {DeveloperError} layer is not in this collection.
+     * @exception {DeveloperError} This object was destroyed, i.e., destroy() was called.
+     */
+    ImageryLayerCollection.prototype.raise = function(layer) {
+        var index = getLayerIndex(this._layers, layer);
+        swapLayers(this, index, index + 1);
+    };
+
+    /**
+     * Lowers a layer down one position in the collection.
+     *
+     * @memberof ImageryLayerCollection
+     *
+     * @param {ImageryLayer} layer the layer to move.
+     *
+     * @exception {DeveloperError} layer is not in this collection.
+     * @exception {DeveloperError} This object was destroyed, i.e., destroy() was called.
+     */
+    ImageryLayerCollection.prototype.lower = function(layer) {
+        var index = getLayerIndex(this._layers, layer);
+        swapLayers(this, index, index - 1);
+    };
+
+    /**
+     * Raises a layer to the top of the collection.
+     *
+     * @memberof ImageryLayerCollection
+     *
+     * @param {ImageryLayer} layer the layer to move.
+     *
+     * @exception {DeveloperError} layer is not in this collection.
+     * @exception {DeveloperError} This object was destroyed, i.e., destroy() was called.
+     */
+    ImageryLayerCollection.prototype.raiseToTop = function(layer) {
+        var index = getLayerIndex(this._layers, layer);
+        this._layers.splice(index, 1);
+        this._layers.push(layer);
+
+        this._update();
+
+        this.layerMoved.raiseEvent(layer, this._layers.length - 1, index);
+    };
+
+    /**
+     * Lowers a layer to the bottom of the collection.
+     *
+     * @memberof ImageryLayerCollection
+     *
+     * @param {ImageryLayer} layer the layer to move.
+     *
+     * @exception {DeveloperError} layer is not in this collection.
+     * @exception {DeveloperError} This object was destroyed, i.e., destroy() was called.
+     */
+    ImageryLayerCollection.prototype.lowerToBottom = function(layer) {
+        var index = getLayerIndex(this._layers, layer);
+        this._layers.splice(index, 1);
+        this._layers.splice(0, 0, layer);
+
+        this._update();
+
+        this.layerMoved.raiseEvent(layer, 0, index);
+    };
+
+    /**
+     * Returns true if this object was destroyed; otherwise, false.
+     * <br /><br />
+     * If this object was destroyed, it should not be used; calling any function other than
+     * <code>isDestroyed</code> will result in a {@link DeveloperError} exception.
+     *
+     * @memberof ImageryLayerCollection
+     *
+     * @return {Boolean} true if this object was destroyed; otherwise, false.
+     *
+     * @see ImageryLayerCollection#destroy
+     */
+    ImageryLayerCollection.prototype.isDestroyed = function() {
+        return false;
+    };
+
+    /**
+     * Destroys the WebGL resources held by all layers in this collection.  Explicitly destroying this
+     * object allows for deterministic release of WebGL resources, instead of relying on the garbage
+     * collector.
+     * <br /><br />
+     * Once this object is destroyed, it should not be used; calling any function other than
+     * <code>isDestroyed</code> will result in a {@link DeveloperError} exception.  Therefore,
+     * assign the return value (<code>undefined</code>) to the object as done in the example.
+     *
+     * @memberof ImageryLayerCollection
+     *
+     * @return {undefined}
+     *
+     * @exception {DeveloperError} This object was destroyed, i.e., destroy() was called.
+     *
+     * @see ImageryLayerCollection#isDestroyed
+     *
+     * @example
+     * layerCollection = layerCollection && layerCollection.destroy();
+     */
+    ImageryLayerCollection.prototype.destroy = function() {
+        this.removeAll(true);
+        return destroyObject(this);
+    };
+
+    ImageryLayerCollection.prototype._update = function() {
+        var isBaseLayer = true;
+        var layers = this._layers;
+        var layersShownOrHidden;
+        var layer;
+        for (var i = 0, len = layers.length; i < len; ++i) {
+            layer = layers[i];
+
+            layer._layerIndex = i;
+
+            if (layer.show) {
+                layer._isBaseLayer = isBaseLayer;
+                isBaseLayer = false;
+            } else {
+                layer._isBaseLayer = false;
+            }
+
+            if (layer.show !== layer._show) {
+                layer._show = layer.show;
+                if (typeof layersShownOrHidden === 'undefined') {
+                    layersShownOrHidden = [];
+                }
+                layersShownOrHidden.push(layer);
+            }
+        }
+
+        if (typeof layersShownOrHidden !== 'undefined') {
+            for (i = 0, len = layersShownOrHidden.length; i < len; ++i) {
+                layer = layersShownOrHidden[i];
+                this.layerShownOrHidden.raiseEvent(layer, layer._layerIndex, layer.show);
+            }
+        }
+    };
+
+    return ImageryLayerCollection;
+});

data/app/assets/javascripts/Scene/ImageryProvider.js

@@ -0,0 +1,185 @@
+/*global define*/
+define([
+        '../Core/loadImage',
+        '../Core/DeveloperError',
+        '../Core/throttleRequestByServer'
+    ], function(
+        loadImage,
+        DeveloperError,
+        throttleRequestByServer) {
+    "use strict";
+
+    /**
+     * Provides imagery to be displayed on the surface of an ellipsoid.  This type describes an
+     * interface and is not intended to be instantiated directly.
+     *
+     * @alias ImageryProvider
+     * @constructor
+     *
+     * @see ArcGisMapServerImageryProvider
+     * @see SingleTileImageryProvider
+     * @see BingMapsImageryProvider
+     * @see OpenStreetMapImageryProvider
+     * @see WebMapServiceImageryProvider
+     */
+    var ImageryProvider = function ImageryProvider() {
+        throw new DeveloperError('This type should not be instantiated directly.');
+    };
+
+    /**
+     * Gets a value indicating whether or not the provider is ready for use.
+     *
+     * @returns {Boolean} True if the provider is ready to use; otherwise, false.
+     */
+    ImageryProvider.prototype.isReady = function() {
+        throw new DeveloperError('This type should not be instantiated directly.');
+    };
+
+    /**
+     * Gets the extent, in radians, of the imagery provided by this instance.  This function should
+     * not be called before {@link ImageryProvider#isReady} returns true.
+     *
+     * @returns {Extent} The extent.
+     *
+     * @exception {DeveloperError} <code>getExtent</code> must not be called before the imagery provider is ready.
+     */
+    ImageryProvider.prototype.getExtent = function() {
+        throw new DeveloperError('This type should not be instantiated directly.');
+    };
+
+    /**
+     * Gets the width of each tile, in pixels.  This function should
+     * not be called before {@link ImageryProvider#isReady} returns true.
+     *
+     * @returns {Number} The width.
+     *
+     * @exception {DeveloperError} <code>getTileWidth</code> must not be called before the imagery provider is ready.
+     */
+    ImageryProvider.prototype.getTileWidth = function() {
+        throw new DeveloperError('This type should not be instantiated directly.');
+    };
+
+    /**
+     * Gets the height of each tile, in pixels.  This function should
+     * not be called before {@link ImageryProvider#isReady} returns true.
+     *
+     * @returns {Number} The height.
+     *
+     * @exception {DeveloperError} <code>getTileHeight</code> must not be called before the imagery provider is ready.
+     */
+    ImageryProvider.prototype.getTileHeight = function() {
+        throw new DeveloperError('This type should not be instantiated directly.');
+    };
+
+    /**
+     * Gets the maximum level-of-detail that can be requested.  This function should
+     * not be called before {@link ImageryProvider#isReady} returns true.
+     *
+     * @returns {Number} The maximum level, or undefined if there is no maximum level.
+     *
+     * @exception {DeveloperError} <code>getMaximumLevel</code> must not be called before the imagery provider is ready.
+     */
+    ImageryProvider.prototype.getMaximumLevel = function() {
+        throw new DeveloperError('This type should not be instantiated directly.');
+    };
+
+    /**
+     * Gets the tiling scheme used by this provider.  This function should
+     * not be called before {@link ImageryProvider#isReady} returns true.
+     *
+     * @returns {TilingScheme} The tiling scheme.
+     * @see WebMercatorTilingScheme
+     * @see GeographicTilingScheme
+     *
+     * @exception {DeveloperError} <code>getTilingScheme</code> must not be called before the imagery provider is ready.
+     */
+    ImageryProvider.prototype.getTilingScheme = function() {
+        throw new DeveloperError('This type should not be instantiated directly.');
+    };
+
+    /**
+     * Gets the tile discard policy.  If not undefined, the discard policy is responsible
+     * for filtering out "missing" tiles via its shouldDiscardImage function.  If this function
+     * returns undefined, no tiles are filtered.  This function should
+     * not be called before {@link ImageryProvider#isReady} returns true.
+     *
+     * @memberof ImageryProvider
+     *
+     * @returns {TileDiscardPolicy} The discard policy.
+     *
+     * @see DiscardMissingTileImagePolicy
+     * @see NeverTileDiscardPolicy
+     *
+     * @exception {DeveloperError} <code>getTileDiscardPolicy</code> must not be called before the imagery provider is ready.
+     */
+    ImageryProvider.prototype.getTileDiscardPolicy = function() {
+        throw new DeveloperError('This type should not be instantiated directly.');
+    };
+
+    /**
+     * Gets an event that is raised when the imagery provider encounters an asynchronous error.  By subscribing
+     * to the event, you will be notified of the error and can potentially recover from it.  Event listeners
+     * are passed an instance of {@link ImageryProviderError}.
+     *
+     * @memberof ImageryProvider
+     *
+     * @returns {Event} The event.
+     */
+    ImageryProvider.prototype.getErrorEvent = function() {
+        throw new DeveloperError('This type should not be instantiated directly.');
+    };
+
+    /**
+     * Gets the logo to display when this imagery provider is active.  Typically this is used to credit
+     * the source of the imagery.  This function should not be called before {@link ImageryProvider#isReady} returns true.
+     *
+     * @memberof ImageryProvider
+     *
+     * @returns {Image|Canvas} A canvas or image containing the log to display, or undefined if there is no logo.
+     *
+     * @exception {DeveloperError} <code>getLogo</code> must not be called before the imagery provider is ready.
+     */
+    ImageryProvider.prototype.getLogo = function() {
+        throw new DeveloperError('This type should not be instantiated directly.');
+    };
+
+    /**
+     * Requests the image for a given tile.  This function should
+     * not be called before {@link ImageryProvider#isReady} returns true.
+     *
+     * @memberof ImageryProvider
+     *
+     * @param {Number} x The tile X coordinate.
+     * @param {Number} y The tile Y coordinate.
+     * @param {Number} level The tile level.
+     *
+     * @returns {Promise} A promise for the image that will resolve when the image is available, or
+     *          undefined if there are too many active requests to the server, and the request
+     *          should be retried later.  The resolved image may be either an
+     *          Image or a Canvas DOM object.
+     *
+     * @exception {DeveloperError} <code>requestImage</code> must not be called before the imagery provider is ready.
+     */
+    ImageryProvider.prototype.requestImage = function(hostnames, hostnameIndex, x, y, level) {
+        throw new DeveloperError('This type should not be instantiated directly.');
+    };
+
+    /**
+     * Loads an image from a given URL.  If the server referenced by the URL already has
+     * too many requests pending, this function will instead return undefined, indicating
+     * that the request should be retried later.
+     *
+     * @memberof ImageryProvider
+     *
+     * @param url {String} The URL of the image.
+     * @returns {Promise} A promise for the image that will resolve when the image is available, or
+     *          undefined if there are too many active requests to the server, and the request
+     *          should be retried later.  The resolved image may be either an
+     *          Image or a Canvas DOM object.
+     */
+    ImageryProvider.loadImage = function(url) {
+        return throttleRequestByServer(url, loadImage);
+    };
+
+    return ImageryProvider;
+});