From 0a44585457a53a564e94e5b486aa3a378a1e480c Mon Sep 17 00:00:00 2001
From: thejohnhoffer <hoffexi@gmail.com>
Date: Thu, 3 Nov 2016 22:39:00 -0400
Subject: [PATCH] documentation of opacity and preload relations

---
 src/openseadragon.js |  5 +++--
 src/tiledimage.js    | 10 +++++-----
 src/viewer.js        |  4 ++--
 3 files changed, 10 insertions(+), 9 deletions(-)

diff --git a/src/openseadragon.js b/src/openseadragon.js
index fac2dc98..cdaee4e5 100644
--- a/src/openseadragon.js
+++ b/src/openseadragon.js
@@ -185,10 +185,11 @@
   *     If 0, adjusts to fit viewer.
   *
   * @property {Number} [opacity=1]
-  *     Default opacity of the tiled images (1=opaque, 0=transparent)
+  *     Default proportional opacity of the tiled images (1=opaque, 0=hidden)
+  *     Hidden images do not draw and only load when preloading is allowed.
   *
   * @property {Boolean} [preload=false]
-  *     If true, tiles in image load without drawing. Defaults to false, so tiles are loaded and drawn.
+  *     Default switch for loading hidden images (true loads, false blocks)
   *
   * @property {String} [compositeOperation=null]
   *     Valid values are 'source-over', 'source-atop', 'source-in', 'source-out',
diff --git a/src/tiledimage.js b/src/tiledimage.js
index 99a7c1f6..11d96928 100644
--- a/src/tiledimage.js
+++ b/src/tiledimage.js
@@ -70,8 +70,8 @@
  * @param {Number} [options.minPixelRatio] - See {@link OpenSeadragon.Options}.
  * @param {Number} [options.smoothTileEdgesMinZoom] - See {@link OpenSeadragon.Options}.
  * @param {Boolean} [options.iOSDevice] - See {@link OpenSeadragon.Options}.
- * @param {Number} [options.opacity=1] - Opacity the tiled image should be drawn at.
- * @param {Boolean} [options.preload=false] - If true, tiles in image load without drawing. Defaults to false, so tiles are loaded and drawn.
+ * @param {Number} [options.opacity=1] - Set to draw at proportional opacity. If zero, images will not draw.
+ * @param {Boolean} [options.preload=false] - Set true to load even when the image is hidden by zero opacity.
  * @param {String} [options.compositeOperation] - How the image is composited onto other images; see compositeOperation in {@link OpenSeadragon.Options} for possible values.
  * @param {Boolean} [options.debugMode] - See {@link OpenSeadragon.Options}.
  * @param {String|CanvasGradient|CanvasPattern|Function} [options.placeholderFillStyle] - See {@link OpenSeadragon.Options}.
@@ -770,15 +770,15 @@ $.extend($.TiledImage.prototype, $.EventSource.prototype, /** @lends OpenSeadrag
     },
 
     /**
-     * @returns {Boolean} whether the tiledImage is set to load tiles without drawing them.
+     * @returns {Boolean} whether the tiledImage can load hidden tiles of zero opacity.
      */
     getPreload: function() {
         return this.preload;
     },
 
     /**
-     * Set true to load without drawing. Set false for default loading and drawing.
-     * @param {Boolean} whether to load tiles without drawing in this tiledImage.
+     * Set true to load even when hidden. Set false to block loading when hidden.
+     * @param {Boolean}  whether the tiledImage can load hidden tiles of zero opacity.
      */
     setPreload: function(preload) {
         this.preload = !!preload;
diff --git a/src/viewer.js b/src/viewer.js
index 4d2a7358..78357873 100644
--- a/src/viewer.js
+++ b/src/viewer.js
@@ -1227,8 +1227,8 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
      * @param {OpenSeadragon.Rect} [options.clip] - An area, in image pixels, to clip to
      * (portions of the image outside of this area will not be visible). Only works on
      * browsers that support the HTML5 canvas.
-     * @param {Number} [options.opacity=1] Opacity the tiled image should be drawn at by default.
-     * @param {Boolean} [options.preload=false]  If true, tiles in image load without drawing by default.
+     * @param {Number} [options.opacity=1] Default proportional opacity of the tiled images (1=opaque, 0=hidden)
+     * @param {Boolean} [options.preload=false]  Default switch for loading hidden images (true loads, false blocks)
      * @param {Number} [options.degrees=0] Initial rotation of the tiled image around
      * its top left corner in degrees.
      * @param {String} [options.compositeOperation] How the image is composited onto other images.