JEP 251: Multi-Resolution Images

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


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


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();


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.


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: