Summary
-------

Define a multi-resolution image API so that images with resolution
variants can easily be manipulated and displayed.


Description
-----------

The new API, to be defined in the `java.awt.image` package, will allow a
set of images with different resolutions to be encapsulated into a single
multi-resolution image.

The basic operations on a multi-resolution image are:

  - Retrieve a resolution-specific image variant based on a given DPI
    metric and set of image transformations, and

  - Retrieve all of the variants in the image.

Aside from these operations a multi-resolution image will otherwise
behave in the same way as an ordinary image.  The `java.awt.Graphics`
class will retrieve the necessary variant from a multi-resolution image
based upon the current display DPI metric and any applied
transformations.

Proposed API sketch:

    package java.awt.image;

    /**
     * This interface is designed to provide a set of images at various resolutions.
     *
     * The {@code MultiResolutionImage} interface should be implemented by any
     * class whose instances are intended to provide image resolution variants
     * according to the given image width and height.
     *
     * @since 1.9
     */
    public interface MultiResolutionImage {

        /**
         * Gets a specific image that is the best variant to represent
         * this logical image at the indicated size.
         *
         * @param destImageWidth the width of the destination image, in pixels.
         * @param destImageHeight the height of the destination image, in pixels.
         * @return image resolution variant.
         *
         * @since 1.9
         */
        Image getResolutionVariant(float destImageWidth, float destImageHeight);

        /**
         * Gets a readable list of all resolution variants.
         * Note that many implementations might return an unmodifiable list.
         *
         * @return list of resolution variants.
         * @since 1.9
         */
        public List<Image> getResolutionVariants();
    }


Alternatives
------------

In the current Java 2D API there is no way to detect if a high-resolution
display is being used.  At the very least, the DPI scale factor must be
provided.  Developers could use the scale factor to draw an image with
the necessary resolution, but that can be very tedious.


Testing
-------

The new API will need to be tested on Mac OS X with a Retina display and
on Windows with a HiDPI display.

The following scenarios can be tested:

  - Create a multi-resolution image from a set of images,

  - Create a multi-resolution image from images on the file system that
    follow the usual scaling naming conventions,

  - Create a multi-resolution image based on another multi-resolution
    image, and

  - Draw multi-resolution images with different DPI metrics and applied
    transform.