03. Preview images

Preview image support is new in version 3.0.0. The aim is to allow a low resolution preview to be displayed and touch gestures to be enabled while a very large image is loaded, so the view appears more responsive.

When a preview image is supplied, it is loaded and displayed before the full size image, and the view is initialised assuming the image dimensions you provided are correct. While the BitmapRegionDecoder is initialised for the full size image and the low resolution base layer tiles are loaded, the user can interact with the view. The preview is then replaced with the base layer when it's ready.

Using a preview is rarely worthwhile for images under ~8000x8000, which will load within a few seconds on the majority of modern phones. For smaller images, the delay caused by loading the preview is proportionally greater.

Usage

Here we have two images in assets, one full size and one preview. The dimensions of the full size image must be declared on the corresponding ImageSource.

view.setImage(
    ImageSource.asset("map.png").dimensions(7557, 5669),
    ImageSource.asset("map_preview.png")
);

You can supply a preview image from any source, it doesn't have to be from the same source as the full size image. You can also use a pre-loaded bitmap.

Note: even if you are using EXIF or manual rotation, you should provide the native dimensions of the image file.

Requirements

• You must know the dimensions of the full size image. If you provide incorrect dimensions, the view will reset when the BitmapRegionDecoder initialises and the true dimensions are known.
• The preview must have the same aspect ratio as the full size image, otherwise it will be distorted.
• The preview and original must have the same orientation.

Restrictions

The tiling flag of the ImageSource you provide for a preview is ignored. Preview images cannot be subsampled or tiled, so you must ensure they are smaller than the Canvas maximum bitmap size. As a rule, never use a preview over 2048px wide or tall.

Generally, 1000px will be more than enough for any device, and you can use drawable resources to provide smaller images for small and low resolution devices. Bear in mind that large preview images will take longer to load and may cause OutOfMemoryErrors.