Merge remote-tracking branch 'origin/rectangle-when-empty' into rectangle-when-empty

src/drawer.js

@@ -232,6 +232,23 @@ $.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{
         }
     },
 
+    /**
+     * Translates from OpenSeadragon viewer rectangle to drawer rectangle.
+     * @param {OpenSeadragon.Rect} rectangle - The rectangle in viewport coordinate system.
+     * @return {OpenSeadragon.Rect} Rectangle in drawer coordinate system.
+     */
+    viewportToDrawerRectangle: function(rectangle) {
+        var topLeft = this.viewport.pixelFromPoint(rectangle.getTopLeft(), true);
+        var size = this.viewport.deltaPixelsFromPoints(rectangle.getSize(), true);
+
+        return new $.Rect(
+            topLeft.x * $.pixelDensityRatio,
+            topLeft.y * $.pixelDensityRatio,
+            size.x    * $.pixelDensityRatio,
+            size.y    * $.pixelDensityRatio
+        );
+    },
+
     /**
      * Draws the given tile.
      * @param {OpenSeadragon.Tile} tile - The tile to draw.
@@ -287,6 +304,24 @@ $.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{
         this.context.clip();
     },
 
+    // private
+    drawPlaceholder: function(rect, fillStyle) {
+        if (!this.useCanvas) {
+            return;
+        }
+
+
+        this.saveContext();
+        if ( typeof fillStyle === "function" ) {
+            this.context.fillStyle = fillStyle(this.context);
+        }
+        else {
+            this.context.fillStyle = fillStyle;
+        }
+        this.context.fillRect(rect.x, rect.y, rect.width, rect.height);
+        this.restoreContext();
+    },
+
     // private
     drawDebugInfo: function( tile, count, i ){
         if ( this.useCanvas ) {

src/openseadragon.js

@@ -206,6 +206,11 @@
   * @property {Number} [opacity=1]
   *     Opacity of the drawer (1=opaque, 0=transparent)
   *
+  * @property {String|CanvasGradient|CanvasPattern|Function} [placeholderFillStyle=null]
+  *     Draws a colored rectangle behind the tile if it is not loaded yet.
+  *     You can pass a CSS color value like "#FF8800".
+  *     When passing a function the canvas context is available as argument which is useful when you draw a gradient or pattern.
+  *
   * @property {Number} [degrees=0]
   *     Initial rotation.
   *
@@ -1017,6 +1022,7 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
 
             // APPEARANCE
             opacity:                    1,
+            placeholderFillStyle:       null,
 
             //REFERENCE STRIP SETTINGS
             showReferenceStrip:          false,

src/tiledimage.js

@@ -65,6 +65,7 @@
  * @param {Boolean} [options.alwaysBlend] - See {@link OpenSeadragon.Options}.
  * @param {Number} [options.minPixelRatio] - See {@link OpenSeadragon.Options}.
  * @param {Boolean} [options.debugMode] - See {@link OpenSeadragon.Options}.
+ * @param {String|CanvasGradient|CanvasPattern|Function} [options.placeholderFillStyle] - See {@link OpenSeadragon.Options}.
  * @param {String|Boolean} [options.crossOriginPolicy] - See {@link OpenSeadragon.Options}.
  */
 $.TiledImage = function( options ) {
@@ -140,7 +141,8 @@ $.TiledImage = function( options ) {
         alwaysBlend:          $.DEFAULT_SETTINGS.alwaysBlend,
         minPixelRatio:        $.DEFAULT_SETTINGS.minPixelRatio,
         debugMode:            $.DEFAULT_SETTINGS.debugMode,
-        crossOriginPolicy:  $.DEFAULT_SETTINGS.crossOriginPolicy
+        crossOriginPolicy:    $.DEFAULT_SETTINGS.crossOriginPolicy,
+        placeholderFillStyle: $.DEFAULT_SETTINGS.placeholderFillStyle
 
     }, options );
 
@@ -1155,22 +1157,25 @@ function drawTiles( tiledImage, lastDrawn ){
         viewer,
         viewport,
         position,
-        tileSource;
+        tileSource,
+        contextSaved = false;
 
     var usedClip = false;
     if ( tiledImage._clip ) {
         tiledImage._drawer.saveContext();
+
         var box = tiledImage.imageToViewportRectangle(tiledImage._clip, true);
-        var topLeft = tiledImage.viewport.pixelFromPoint(box.getTopLeft(), true);
-        var size = tiledImage.viewport.deltaPixelsFromPoints(box.getSize(), true);
-        box = new OpenSeadragon.Rect(topLeft.x * $.pixelDensityRatio,
-            topLeft.y * $.pixelDensityRatio,
-            size.x * $.pixelDensityRatio,
-            size.y * $.pixelDensityRatio);
-        tiledImage._drawer.setClip(box);
+        var clipRect = tiledImage._drawer.viewportToDrawerRectangle(box);
+        tiledImage._drawer.setClip(clipRect);
+
         usedClip = true;
     }
 
+    if ( tiledImage.placeholderFillStyle && lastDrawn.length === 0 ) {
+        var placeholderRect = tiledImage._drawer.viewportToDrawerRectangle(tiledImage.getBounds(true));
+        tiledImage._drawer.drawPlaceholder(placeholderRect, tiledImage.placeholderFillStyle);
+    }
+
     for ( i = lastDrawn.length - 1; i >= 0; i-- ) {
         tile = lastDrawn[ i ];
         tiledImage._drawer.drawTile( tile, tiledImage._drawingHandler );

src/viewer.js

@@ -1206,6 +1206,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
      * and "source" properties.
      * @param {Boolean} [options.collectionImmediately=false] If collectionMode is on,
      * specifies whether to snap to the new arrangement immediately or to animate to it.
+     * @param {String|CanvasGradient|CanvasPattern|Function} [options.placeholderFillStyle] - See {@link OpenSeadragon.Options}.
      * @fires OpenSeadragon.World.event:add-item
      * @fires OpenSeadragon.Viewer.event:add-item-failed
      */
@@ -1217,6 +1218,10 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
 
         this._hideMessage();
 
+        if (options.placeholderFillStyle === undefined) {
+            options.placeholderFillStyle = this.placeholderFillStyle;
+        }
+
         var myQueueItem = {
             options: options
         };
@@ -1284,6 +1289,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
                     width: queueItem.options.width,
                     height: queueItem.options.height,
                     clip: queueItem.options.clip,
+                    placeholderFillStyle: queueItem.options.placeholderFillStyle,
                     springStiffness: _this.springStiffness,
                     animationTime: _this.animationTime,
                     minZoomImageRatio: _this.minZoomImageRatio,