JEP 251: Multi-Resolution Images

AuthorsAlexander Scherbatiy, Jim Graham
OwnerAlexander Scherbatiy
Created2014/06/05 08:23
Updated2016/08/16 17:47
TypeFeature
StatusClosed / Delivered
Componentclient-libs / 2d
ScopeSE
Discussion2d dash dev at openjdk dot java dot net
EffortM
DurationM
Priority3
Reviewed byJim Graham, Philip Race
Endorsed byKevin Rushforth
Release9
Issue8046010

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:

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: