Updated readme for 2.3.0

Author: davemorrissey

README.md

@@ -1,9 +1,9 @@
 Subsampling Zoom Image View
 ===========================
 
-Custom image views for Android with pinch to zoom, panning, rotation and animation support, with easy extension so you can add your own overlays and touch event detection.
+Custom image views for Android, designed for photo galleries and displaying huge images (e.g. maps and building plans) without `OutOfMemoryError`s. Includes pinch to zoom, panning, rotation and animation support, and allows easy extension so you can add your own overlays and touch event detection.
 
-This library includes two classes, `ScaleImageView` and `SubsamplingScaleImageView`. `SubsamplingScaleImageView` is best for large images but doesn't support display of `Bitmap` objects or resources, and `ScaleImageView` supports `Bitmap` objects but not subsampling or large images. To decide which is best for you, see below.
+This library includes two view classes. `SubsamplingScaleImageView` uses subsampling and tiles to support large images - as you zoom in, the low resolution initial image is overlaid with smaller high resolution tiles to avoid holding too much data in memory. It's ideal for displaying large images while allowing you to zoom in to the high resolution details. `ScaleImageView` doesn't subsample images but can display `Bitmap` objects and supports all the same features. To decide which is best for you, see below.
 
 #### Download the sample app
 
@@ -17,28 +17,23 @@ This library includes two classes, `ScaleImageView` and `SubsamplingScaleImageVi
 | ------------- | ------------- | ------------- | ------------- |
 | **Fourth Mate** | **Journal** | **Clover** | **Tag Gallery** |
 
-#### About
-
-`SubsamplingScaleImageView` uses subsampling and tiles to support large images. While zooming in, the
-low resolution, full size base layer is overlaid with smaller tiles at least as high resolution as the screen, and
-tiles are loaded and discarded during panning to avoid holding too much bitmap data in memory. This is ideal for use in image gallery apps where the size of the images may be large enough to require subsampling, and where
-pinch to zoom is required to view the high resolution detail.
-
-*These views don't extend `ImageView` and aren't intended as a general purpose replacement for it. They're specialised for the display of photos and other large images, not the display of 9-patches, shapes and the other types of drawable that ImageView supports.*
+## Features
 
 #### Image display
 
-* Display images from assets or the file system
+* Display images from assets, resources or the file system
 * Automatically rotate images from the file system (e.g. the camera or gallery) according to EXIF
 * Manually rotate images in 90° increments
 * Swap images at runtime
+* Use a custom bitmap decoder
 
 *`SubsamplingScaleImageView` only:*
 
 * Display huge images, larger than can be loaded into memory
 * Show high resolution detail on zooming in
 * Tested up to 20,000x13,000px, though larger images are slower
 
+*These views don't extend `ImageView` and aren't intended as a general purpose replacement for it. They're specialised for the display of photos and other large images, not the display of 9-patches, shapes and the other types of drawable that ImageView supports.*
 
 #### Gesture detection
 * One finger pan
@@ -67,10 +62,10 @@ pinch to zoom is required to view the high resolution detail.
 
 #### Limitations
 * `SubsamplingScaleImageView` requires SDK 10 (Gingerbread).
-* `SubsamplingScaleImageView` cannot decode an image from resources or display a `Bitmap` object - the image file needs to be in assets or external storage.
-* `SubsamplingScaleImageView` cannot display grayscale PNGs on Android Lollipop, due to bugs in the skia library and/or BitmapRegionDecoder. Earlier versions of Android also have issues displaying some grayscale PNGs, but not all. I have reported these bugs to Google.
+* `SubsamplingScaleImageView` cannot display a `Bitmap` object - the image file needs to be in assets, resources or external storage.
+* `SubsamplingScaleImageView` cannot display grayscale PNGs on Android Lollipop, due to bugs in the skia library and/or BitmapRegionDecoder. Earlier versions of Android also have issues displaying some grayscale PNGs, but not all. I have reported these bugs to Google. For a workaround, see the section on custom bitmap decoders below.
 * These views do not extend ImageView so attributes including android:tint, android:scaleType and android:src are not supported.
-* Images stored in assets cannot be rotated based on EXIF, you'll need to do it manually. You probably know the orientation of your own assets :-)
+* Images stored in resources and assets cannot be rotated based on EXIF, you'll need to do it manually. You probably know the orientation of your own files :-)
 
 ## Which view is best?
 
@@ -89,18 +84,11 @@ Use `ScaleImageView` if:
 * Your images are no larger than 2048px, or you are able to scale them down.
 * You need to support devices older than SDK 10.
 
-## Quality notes
-
-Images are decoded as dithered RGB_565 bitmaps by default, because this requires half as much memory as ARGB_8888. For most
-JPGs you won't notice the difference in quality. If you are displaying large PNGs with alpha channels, Android will probably
-decode them as ARGB_8888, and this may cause `OutOfMemoryError`s. **If possible, remove the alpha channel from PNGs larger than about 2,000x2,000.**
-This allows them to be decoded as RGB_565.
-
-## Basic setup
+## Installation
 
 Add the library to your app using one of these methods:
 
-* Add `com.davemorrissey.labs:subsampling-scale-image-view:2.2.1` as a dependency in your build.gradle file
+* Add `com.davemorrissey.labs:subsampling-scale-image-view:2.3.0` as a dependency in your build.gradle file
 * *or* download the library aar file from the releases page and add to your app manually
 * *or* clone the project and import the library subproject as a module in your app
 * *or* clone the project and copy the resources and classes from `com.davemorrissey.labs.subscaleview` into your project
@@ -118,12 +106,14 @@ Add the view to your layout XML as shown below. Normally you should set width an
 
     </RelativeLayout>
 
-Now, in your fragment or activity, set the image asset name or file path.
+Now, in your fragment or activity, set the image resource, asset name or file path.
 
     SubsamplingScaleImageView imageView = (SubsamplingScaleImageView)findViewById(id.imageView);
+    imageView.setImageResource(R.drawable.monkey);
+    // ... or ...
     imageView.setImageAsset("map.png");
     // ... or ...
-    imageView.setImageFile("/sdcard/DCIM/DSCM00123.JPG");
+    imageView.setImageUri("/sdcard/DCIM/DSCM00123.JPG");
 
 That's it! Keep reading for some more options.
 
@@ -177,12 +167,29 @@ If you want the current scale, center and orientation to be preserved when the s
         }
     }
 
+## Custom bitmap decoders
+
+Android's `BitmapRegionDecoder` class is based on the Skia library. Some users have reported problems with this library, particularly when displaying grayscale JPGs. Unfortunately it seems to be less reliable in recent versions of Android. If you don't control the format of the images displayed in your app (for example, they are user generated content) you may require a more reliable decoder.
+
+To use your own decoder based on a different library, implement the `ImageRegionDecoder` class (do not include a constructor) and enable it using this call:
+
+    imageView.setDecoderClass(MyImageRegionDecoder.class);
+    
+As an example, see the [`RapidImageRegionDecoder`](https://github.com/davemorrissey/subsampling-scale-image-view/blob/master/sample/src/com/davemorrissey/labs/subscaleview/sample/imagedisplay/decoders/RapidImageRegionDecoder.java) class, which is based on [RapidDecoder](https://github.com/suckgamony/RapidDecoder). This library is better at decoding grayscale JPG images but does not handle large images as well as `BitmapRegionDecoder` - it is significantly slower and more likely to throw out of memory errors. It appears to be very fast and reliable for PNG images. If you can detect the size and type of an image before displaying it, you can use different decoders for different images to get the best results.
+
+Whenever possible, convert your images to a format Android's Skia library can support, and test with a variety of devices.
+
+## Quality notes
+
+Images are decoded as dithered RGB_565 bitmaps by default, because this requires half as much memory as ARGB_8888. For most
+JPGs you won't notice the difference in quality. If you are displaying large PNGs with alpha channels, Android will probably
+decode them as ARGB_8888, and this may cause `OutOfMemoryError`s. **If possible, remove the alpha channel from PNGs larger than about 2,000x2,000.**
+This allows them to be decoded as RGB_565.
+
 ## Extending functionality
 
 Take a look at the sample app for examples of classes that overlay graphics on top of the image so that they move and scale with it. `FreehandView` adds event detection, capturing only the touch events it needs so pan and zoom still work normally.
 
 ## About
 
-Copyright 2014 David Morrissey, and licensed under the Apache License, Version 2.0. No attribution is necessary but it's very much appreciated. Star this project to show your gratitude.
-
-This project started life as a way of showing very large images (e.g. a large building floor plan) with gestures to pan and zoom, with support for extensions that showed overlays (location pins, annotations) aligned with the image. It's grown massively, but for the moment I am keeping everything in one class to prevent subclasses and extensions breaking the assumptions (or violating invariants) on which the class depends.
+Copyright 2014 David Morrissey, and licensed under the Apache License, Version 2.0. No attribution is necessary but it's very much appreciated. Star this project if you like it, and send a link to your project on GitHub or app in Google Play if you'd like me to add it to this page.