Renamed subPixelRounding to subPixelRoundingForTransparency, changed fallback to '*', introduced SUBPIXEL_ROUNDING_OCCURRENCES numbers, added support for simple mode

src/openseadragon.js

@@ -209,12 +209,16 @@
   *     You can pass a CSS color value like "#FF8800".
   *     When passing a function the tiledImage and canvas context are available as argument which is useful when you draw a gradient or pattern.
   *
-  * @property {Object} [subPixelRounding=null]
+  * @property {Object} [subPixelRoundingForTransparency=null]
-  *     Determines when subpixel rounding should be applied for tiles rendering.
+  *     Determines when subpixel rounding should be applied for tiles when rendering images that support transparency.
-  *     This property is a subpixel rounding enum values dictionary [number] --> string.
+  *     This property is a subpixel rounding enum values dictionary [{@link BROWSERS}] --> {@link SUBPIXEL_ROUNDING_OCCURRENCES}.
-  *     The key is a $.BROWSERS value, and the value is one of 'ALWAYS', 'ONLY_AT_REST' or 'NEVER',
+  *     The key is a {@link BROWSERS} value, and the value is one of {@link SUBPIXEL_ROUNDING_OCCURRENCES},
   *     indicating, for a given browser, when to apply subpixel rounding.
-  *     Key '' is the fallback value for any browser not specified in the dictionary.
+  *     Key '*' is the fallback value for any browser not specified in the dictionary.
+  *     This property has a simple mode, and one can set it directly to
+  *     {@link SUBPIXEL_ROUNDING_OCCURRENCES.NEVER}, {@link SUBPIXEL_ROUNDING_OCCURRENCES.ONLY_AT_REST} or {@link SUBPIXEL_ROUNDING_OCCURRENCES.ALWAYS}
+  *     in order to apply this rule for all browser. The values {@link SUBPIXEL_ROUNDING_OCCURRENCES.ALWAYS} would be equivalent to { '*', SUBPIXEL_ROUNDING_OCCURRENCES.ALWAYS }.
+  *     The default is {@link SUBPIXEL_ROUNDING_OCCURRENCES.NEVER} for all browsers, for backward compatibility reason.
   *
   * @property {Number} [degrees=0]
   *     Initial rotation.
@@ -1270,7 +1274,7 @@ function OpenSeadragon( options ){
             compositeOperation:                null,
             imageSmoothingEnabled:             true,
             placeholderFillStyle:              null,
-            subPixelRounding:           null,
+            subPixelRoundingForTransparency:   null,
 
             //REFERENCE STRIP SETTINGS
             showReferenceStrip:          false,
@@ -1411,6 +1415,20 @@ function OpenSeadragon( options ){
             CHROMEEDGE: 7
         },
 
+        /**
+         * An enumeration of Browser vendors.
+         * @static
+         * @type {Object}
+         * @property {Number} NEVER Never apply subpixel rounding for transparency.
+         * @property {Number} ONLY_AT_REST Do not apply subpixel rounding for transparency during animation (panning, zoom, rotation) and apply it once animation is over.
+         * @property {Number} ALWAYS Apply subpixel rounding for transparency during animation and when animation is over.
+         */
+        SUBPIXEL_ROUNDING_OCCURRENCES: {
+            NEVER:          0,
+            ONLY_AT_REST:   1,
+            ALWAYS:         2
+        },
+
         /**
          * Keep track of which {@link Viewer}s have been created.
          * - Key: {@link Element} to which a Viewer is attached.

src/tiledimage.js

@@ -178,7 +178,7 @@ $.TiledImage = function( options ) {
         opacity:                           $.DEFAULT_SETTINGS.opacity,
         preload:                           $.DEFAULT_SETTINGS.preload,
         compositeOperation:                $.DEFAULT_SETTINGS.compositeOperation,
-        subPixelRounding:       $.DEFAULT_SETTINGS.subPixelRounding
+        subPixelRoundingForTransparency:   $.DEFAULT_SETTINGS.subPixelRoundingForTransparency
     }, options );
 
     this._preload = this.preload;
@@ -1958,39 +1958,39 @@ function compareTiles( previousBest, tile ) {
  * Defines the value for subpixel rounding to fallback to in case of missing or
  * invalid value.
  */
-var DEFAULT_SUBPIXEL_ROUNDING_RULE = 'NEVER';
+var DEFAULT_SUBPIXEL_ROUNDING_RULE = $.SUBPIXEL_ROUNDING_OCCURRENCES.NEVER;
 
 /**
  * @private
  * @inner
- * Determines whether the subpixel rounding enum value is 'ALWAYS' or not.
+ * Determines whether the subpixel rounding enum value is {@link SUBPIXEL_ROUNDING_OCCURRENCES.ALWAYS} or not.
  *
- * @param {string} value - The subpixel rounding enum value to check, case sensitive.
+ * @param {SUBPIXEL_ROUNDING_OCCURRENCES} value - The subpixel rounding enum value to check.
- * @returns {Boolean} True if input value is 'ALWAYS', false otherwise.
+ * @returns {Boolean} True if input value is {@link SUBPIXEL_ROUNDING_OCCURRENCES.ALWAYS}, false otherwise.
  */
 function isSubPixelRoundingRuleAlways(value) {
-    return value === 'ALWAYS';
+    return value === $.SUBPIXEL_ROUNDING_OCCURRENCES.ALWAYS;
 }
 
 /**
  * @private
  * @inner
- * Determines whether the subpixel rounding enum value is 'ONLY_AT_REST' or not.
+ * Determines whether the subpixel rounding enum value is {@link SUBPIXEL_ROUNDING_OCCURRENCES.ONLY_AT_REST} or not.
  *
- * @param {string} value - The subpixel rounding enum value to check, case sensitive.
+ * @param {SUBPIXEL_ROUNDING_OCCURRENCES} value - The subpixel rounding enum value to check.
- * @returns {Boolean} True if input value is 'ONLY_AT_REST', false otherwise.
+ * @returns {Boolean} True if input value is {@link SUBPIXEL_ROUNDING_OCCURRENCES.ONLY_AT_REST}, false otherwise.
  */
  function isSubPixelRoundingRuleOnlyAtRest(value) {
-    return value === 'ONLY_AT_REST';
+    return value === $.SUBPIXEL_ROUNDING_OCCURRENCES.ONLY_AT_REST;
 }
 
 /**
  * @private
  * @inner
- * Determines whether the subpixel rounding enum value is 'NEVER' or not.
+ * Determines whether the subpixel rounding enum value is {@link SUBPIXEL_ROUNDING_OCCURRENCES.NEVER} or not.
  *
- * @param {string} value - The subpixel rounding enum value to check, case sensitive.
+ * @param {SUBPIXEL_ROUNDING_OCCURRENCES} value - The subpixel rounding enum value to check.
- * @returns {Boolean} True if input value is 'NEVER', false otherwise.
+ * @returns {Boolean} True if input value is {@link SUBPIXEL_ROUNDING_OCCURRENCES.NEVER}, false otherwise.
  */
  function isSubPixelRoundingRuleNever(value) {
     return value === DEFAULT_SUBPIXEL_ROUNDING_RULE;
@@ -2001,12 +2001,9 @@ function isSubPixelRoundingRuleAlways(value) {
  * @inner
  * Checks whether the input value is an invalid subpixel rounding enum value.
  *
- * @param {string} value - The subpixel rounding enum value to check, case sensitive.
+ * @param {SUBPIXEL_ROUNDING_OCCURRENCES} value - The subpixel rounding enum value to check.
  * @returns {Boolean} Returns true if the input value is none of the expected
- * 'ALWAYS', 'ONLY_AT_REST' or 'NEVER' value.
+ * {@link SUBPIXEL_ROUNDING_OCCURRENCES.ALWAYS}, {@link SUBPIXEL_ROUNDING_OCCURRENCES.ONLY_AT_REST} or {@link SUBPIXEL_ROUNDING_OCCURRENCES.NEVER} value.
- * Note that if passed a valid value but with the incorrect casing, the return
- * value will be true. If input is 'always', then true is returned, indicating
- * it is an unknown value.
  */
  function isSubPixelRoundingRuleUnknown(value) {
     return !isSubPixelRoundingRuleAlways(value) &&
@@ -2018,13 +2015,10 @@ function isSubPixelRoundingRuleAlways(value) {
  * @private
  * @inner
  * Ensures the returned value is always a valid subpixel rounding enum value,
- * defaulting to 'NEVER' if input is missing or invalid.
+ * defaulting to {@link SUBPIXEL_ROUNDING_OCCURRENCES.NEVER} if input is missing or invalid.
  *
- * @param {string} value - The subpixel rounding enum value to normalize, case sensitive.
+ * @param {SUBPIXEL_ROUNDING_OCCURRENCES} value - The subpixel rounding enum value to normalize.
- * @returns {string} Returns a valid subpixel rounding enum value.
+ * @returns {SUBPIXEL_ROUNDING_OCCURRENCES} Returns a valid subpixel rounding enum value.
- * Note that if passed a valid value but with the incorrect casing, the return
- * value will be the default 'NEVER'. If input is 'always', then 'NEVER' is
- * returned.
  */
  function normalizeSubPixelRoundingRule(value) {
     if (isSubPixelRoundingRuleUnknown(value)) {
@@ -2039,19 +2033,23 @@ function isSubPixelRoundingRuleAlways(value) {
  * Ensures the returned value is always a valid subpixel rounding enum value,
  * defaulting to 'NEVER' if input is missing or invalid.
  *
- * @param {Object} subPixelRoundingRules - A subpixel rounding enum values dictionary [number] --> string.
+ * @param {Object} subPixelRoundingRules - A subpixel rounding enum values dictionary [{@link BROWSERS}] --> {@link SUBPIXEL_ROUNDING_OCCURRENCES}.
- * @returns {string} Returns the determined subpixel rounding enum value for the
+ * @returns {SUBPIXEL_ROUNDING_OCCURRENCES} Returns the determined subpixel rounding enum value for the
  * current browser.
  */
 function determineSubPixelRoundingRule(subPixelRoundingRules) {
+    if (typeof subPixelRoundingRules === 'number') {
+        return normalizeSubPixelRoundingRule(subPixelRoundingRules);
+    }
+
     if (!subPixelRoundingRules || !$.Browser) {
         return DEFAULT_SUBPIXEL_ROUNDING_RULE;
     }
 
     var subPixelRoundingRule = subPixelRoundingRules[$.Browser.vendor];
 
-    if (!subPixelRoundingRule || isSubPixelRoundingRuleUnknown(subPixelRoundingRule)) {
+    if (isSubPixelRoundingRuleUnknown(subPixelRoundingRule)) {
-        subPixelRoundingRule = subPixelRoundingRules[''];
+        subPixelRoundingRule = subPixelRoundingRules['*'];
     }
 
     return normalizeSubPixelRoundingRule(subPixelRoundingRule);
@@ -2205,7 +2203,7 @@ function drawTiles( tiledImage, lastDrawn ) {
         tiledImage._drawer.drawRectangle(placeholderRect, fillStyle, useSketch);
     }
 
-    var subPixelRoundingRule = determineSubPixelRoundingRule(tiledImage.subPixelRounding);
+    var subPixelRoundingRule = determineSubPixelRoundingRule(tiledImage.subPixelRoundingForTransparency);
 
     var shouldRoundPositionAndSize = false;
 

src/viewer.js

@@ -1495,7 +1495,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
                     loadTilesWithAjax: queueItem.options.loadTilesWithAjax,
                     ajaxHeaders: queueItem.options.ajaxHeaders,
                     debugMode: _this.debugMode,
-                    subPixelRounding: _this.subPixelRounding
+                    subPixelRoundingForTransparency: _this.subPixelRoundingForTransparency
                 });
 
                 if (_this.collectionMode) {