Multi-Resolution Images API – Java 9

Java 9 introduced a new interface called MultiResolutionImage (JEP 251) to encapsulate a set of images with different resolutions into a single multi-resolution image. The APIs related to multi-resolution images are available under java.awt.image package and helps us to programmatically:

  • Get all variants of a particular image.
  • Get an image specific to the resolution required based on DPI metric and image transformations.

Let us learn more about the APIs for multi-resolution images introduced in Java 9.

MultiResolutionImage Interface

There are two important functions in the MultiResolutionImage.

  • getResolutionVariant() – This method returns an instance of java.awt.Image from the set of variants based on the width and height of the image given as parameters to the function. It will throw an IllegalArgumentException if the double values representing the dimensions are zero, negative, infinity or Not A Number.
  • getResolutionVariants() – This method returns all the variants available for the given image. It returns a List containing objects of type java.awt.Image.

AbstractMultiResolutionImage Class

As the name suggests, the AbstractMultiResolutionImage class is an extension of java.awt.Image class. It implements the MultiResolutionImage interface. It gives default implementations for many methods from java.awt.Image class and enables the users to extend this class to provide a custom concrete class defining additional methods to handle multi-resolution images.

Important methods of this class are:

  • getBaseImage() –  returns the base image, which is of type java.awt.Image with the best resolution available among the list of variants. It is the only abstract method in this class and should be implemented by all concrete classes that extends the AbstractMultiResolutionImage class. Other methods of this class delegates the respective calls to corresponding methods invoked on the base image object returned by this method. It is a protected method.
  • getHeight() – delegates method call to getBaseImage().getHeight() and returns an integer value.
  • getWidth() – delegates method call to getBaseImage().getWidth() and returns an integer value.
  • getProperty() – delegates method call to getBaseImage().getProperty() and returns the value for the String property name that we pass as parameter to this method.
  • getSource() – delegates method call to getBaseImage().getSource() and returns the object that produces the pixels on the image. The object returned will be of type java.awt.image.ImageProducer.
  • getGraphics() – will always throw UnsupportedOperationException in contrast to what happens when java.awt.Image.getGraphics() is called. This is because only off-screen images can return a Graphics object.

BaseMultiResolutionImage Class

This is a concrete class that extends the AbstractMultiResolutionImage class. It implements the methods available in MultiResolutionImage interface – getResolutionVariant() and getResolutionVariants().

MultiResolutionImage In Action

Let us learn more about MultiResolutionImages by creating a sample project.

Before we jump into code development, we need to keep test data ready using the method that is described next.

From an internet browser, access Wikipedia page for eagle. Click on the image of an eagle on the right-hand side. We should be able to navigate to the page containing the file details.

Right below the image, we can see various resolutions for the given images. Download the files that we would like to include in our sample project and save them to disk.

Now, create a new java project in Eclipse IDE with JRE set to java 9. Under the java project base folder, copy the images that we downloaded from Wikimedia.

Create a new class named The project structure should look as follows:


project structure
project structure

Notice that the image with the largest resolution is named without adding prefix for the resolution. This is to show that it is the highest resolution image available.

Modify the file to include the code required for processing multi-resolution images that we have in the project:

Output for the above code will be as follows:

From the above example, it is evident that for a given resolution, the image variant is returned in such a way that there is very less amount of pixel size difference between the intended resolution and the variant obtained. This is done so that the returned image can fit properly in the device from which the image variant was requested. The MultiResolutionImage object mrImages has retained data of all the five variants fed to it in the sample program.

We have used files available on the local machine as input to simplify the example. But that is not the only way we can fetch input data for creating a MultiReolutionImage object.

It is possible to use images from the internet also as input for the multiresolution image. To do so, the imageLocations and images lists in the above example need to be changed as shown:

The sample program will give the same output as mentioned earlier with the above changes.


The Multi-resolution API will allow the encapsulation of a set of images having different resolutions into a single multi-resolution image object. Thus, a developer can retrieve an image that is resolution-specific. And can also retrieve all variants within the image. This will make it very easy to have different resolution images for different displays and hence would be a very helpful feature for developers.

4 thoughts on “Multi-Resolution Images API – Java 9”

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: