javax.imageio

## Class IIOImage

- java.lang.Object
- - javax.imageio.IIOImage

-     public class IIOImage
      extends Object

  A simple container class to aggregate an image, a set of thumbnail (preview) images, and an object representing metadata associated with the image.

  The image data may take the form of either a `RenderedImage`, or a `Raster`. Reader methods that return an `IIOImage` will always return a `BufferedImage` using the `RenderedImage` reference. Writer methods that accept an `IIOImage` will always accept a `RenderedImage`, and may optionally accept a `Raster`.

  Exactly one of `getRenderedImage` and `getRaster` will return a non-`null` value. Subclasses are responsible for ensuring this behavior.

  See Also:
    `ImageReader.readAll(int, ImageReadParam)`, `ImageReader.readAll(java.util.Iterator)`, `ImageWriter.write(javax.imageio.metadata.IIOMetadata, IIOImage, ImageWriteParam)`, `ImageWriter.write(IIOImage)`, `ImageWriter.writeToSequence(IIOImage, ImageWriteParam)`, `ImageWriter.writeInsert(int, IIOImage, ImageWriteParam)`

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected RenderedImage` | `image` | The `RenderedImage` being referenced.
    `protected IIOMetadata` | `metadata` | An `IIOMetadata` object containing metadata associated with the image.
    `protected Raster` | `raster` | The `Raster` being referenced.
    `protected List<? extends BufferedImage>` | `thumbnails` | A `List` of `BufferedImage` thumbnails, or `null`.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `IIOImage(Raster raster, List<? extends BufferedImage> thumbnails, IIOMetadata metadata)` | Constructs an `IIOImage` containing a `Raster`, and thumbnails and metadata associated with it.
    `IIOImage(RenderedImage image, List<? extends BufferedImage> thumbnails, IIOMetadata metadata)` | Constructs an `IIOImage` containing a `RenderedImage`, and thumbnails and metadata associated with it.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `IIOMetadata` | `getMetadata()` | Returns a reference to the current `IIOMetadata` object, or `null` is none is set.
    `int` | `getNumThumbnails()` | Returns the number of thumbnails stored in this `IIOImage`.
    `Raster` | `getRaster()` | Returns the currently set `Raster`, or `null` if only a `RenderedImage` is available.
    `RenderedImage` | `getRenderedImage()` | Returns the currently set `RenderedImage`, or `null` if only a `Raster` is available.
    `BufferedImage` | `getThumbnail(int index)` | Returns a thumbnail associated with the main image.
    `List<? extends BufferedImage>` | `getThumbnails()` | Returns the current `List` of thumbnail `BufferedImage`s, or `null` if none is set.
    `boolean` | `hasRaster()` | Returns `true` if this `IIOImage` stores a `Raster` rather than a `RenderedImage`.
    `void` | `setMetadata(IIOMetadata metadata)` | Sets the `IIOMetadata` to a new object, or `null`.
    `void` | `setRaster(Raster raster)` | Sets the current `Raster`.
    `void` | `setRenderedImage(RenderedImage image)` | Sets the current `RenderedImage`.
    `void` | `setThumbnails(List<? extends BufferedImage> thumbnails)` | Sets the list of thumbnails to a new `List` of `BufferedImage`s, or to `null`.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### image

          protected RenderedImage image

      The `RenderedImage` being referenced.

    - #### raster

          protected Raster raster

      The `Raster` being referenced.

    - #### thumbnails

          protected List<? extends BufferedImage> thumbnails

      A `List` of `BufferedImage` thumbnails, or `null`. Non-`BufferedImage` objects must not be stored in this `List`.

    - #### metadata

          protected IIOMetadata metadata

      An `IIOMetadata` object containing metadata associated with the image.

  - ### Constructor Detail

    - #### IIOImage

          public IIOImage(RenderedImage image,
                          List<? extends BufferedImage> thumbnails,
                          IIOMetadata metadata)

      Constructs an `IIOImage` containing a `RenderedImage`, and thumbnails and metadata associated with it.

      All parameters are stored by reference.

      The `thumbnails` argument must either be `null` or contain only `BufferedImage` objects.

      Parameters:
        `image` - a `RenderedImage`.
        `thumbnails` - a `List` of `BufferedImage`s, or `null`.
        `metadata` - an `IIOMetadata` object, or `null`.
      Throws:
        `IllegalArgumentException` - if `image` is `null`.

    - #### IIOImage

          public IIOImage(Raster raster,
                          List<? extends BufferedImage> thumbnails,
                          IIOMetadata metadata)

      Constructs an `IIOImage` containing a `Raster`, and thumbnails and metadata associated with it.

      All parameters are stored by reference.

      Parameters:
        `raster` - a `Raster`.
        `thumbnails` - a `List` of `BufferedImage`s, or `null`.
        `metadata` - an `IIOMetadata` object, or `null`.
      Throws:
        `IllegalArgumentException` - if `raster` is `null`.

  - ### Method Detail

    - #### getRenderedImage

          public RenderedImage getRenderedImage()

      Returns the currently set `RenderedImage`, or `null` if only a `Raster` is available.
      Returns:
        a `RenderedImage`, or `null`.
      See Also:
        `setRenderedImage(java.awt.image.RenderedImage)`

    - #### setRenderedImage

          public void setRenderedImage(RenderedImage image)

      Sets the current `RenderedImage`. The value is stored by reference. Any existing `Raster` is discarded.
      Parameters:
        `image` - a `RenderedImage`.
      Throws:
        `IllegalArgumentException` - if `image` is `null`.
      See Also:
        `getRenderedImage()`

    - #### hasRaster

          public boolean hasRaster()

      Returns `true` if this `IIOImage` stores a `Raster` rather than a `RenderedImage`.
      Returns:
        `true` if a `Raster` is available.

    - #### getRaster

          public Raster getRaster()

      Returns the currently set `Raster`, or `null` if only a `RenderedImage` is available.
      Returns:
        a `Raster`, or `null`.
      See Also:
        `setRaster(java.awt.image.Raster)`

    - #### setRaster

          public void setRaster(Raster raster)

      Sets the current `Raster`. The value is stored by reference. Any existing `RenderedImage` is discarded.
      Parameters:
        `raster` - a `Raster`.
      Throws:
        `IllegalArgumentException` - if `raster` is `null`.
      See Also:
        `getRaster()`

    - #### getNumThumbnails

          public int getNumThumbnails()

      Returns the number of thumbnails stored in this `IIOImage`.
      Returns:
        the number of thumbnails, as an `int`.

    - #### getThumbnail

          public BufferedImage getThumbnail(int index)

      Returns a thumbnail associated with the main image.
      Parameters:
        `index` - the index of the desired thumbnail image.
      Returns:
        a thumbnail image, as a `BufferedImage`.
      Throws:
        `IndexOutOfBoundsException` - if the supplied index is negative or larger than the largest valid index.
        `ClassCastException` - if a non-`BufferedImage` object is encountered in the list of thumbnails at the given index.
      See Also:
        `getThumbnails()`, `setThumbnails(java.util.List<? extends java.awt.image.BufferedImage>)`

    - #### getThumbnails

          public List<? extends BufferedImage> getThumbnails()

      Returns the current `List` of thumbnail `BufferedImage`s, or `null` if none is set. A live reference is returned.
      Returns:
        the current `List` of `BufferedImage` thumbnails, or `null`.
      See Also:
        `getThumbnail(int)`, `setThumbnails(java.util.List<? extends java.awt.image.BufferedImage>)`

    - #### setThumbnails

          public void setThumbnails(List<? extends BufferedImage> thumbnails)

      Sets the list of thumbnails to a new `List` of `BufferedImage`s, or to `null`. The reference to the previous `List` is discarded.

      The `thumbnails` argument must either be `null` or contain only `BufferedImage` objects.

      Parameters:
        `thumbnails` - a `List` of `BufferedImage` thumbnails, or `null`.
      See Also:
        `getThumbnail(int)`, `getThumbnails()`

    - #### getMetadata

          public IIOMetadata getMetadata()

      Returns a reference to the current `IIOMetadata` object, or `null` is none is set.
      Returns:
        an `IIOMetadata` object, or `null`.
      See Also:
        `setMetadata(javax.imageio.metadata.IIOMetadata)`

    - #### setMetadata

          public void setMetadata(IIOMetadata metadata)

      Sets the `IIOMetadata` to a new object, or `null`.
      Parameters:
        `metadata` - an `IIOMetadata` object, or `null`.
      See Also:
        `getMetadata()`

Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2026, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.