IIOImage (Java SE 25 & JDK 25)
Description: declaration: module: java.desktop, package: javax.imageio, class: IIOImage
Keywords: javax.imageio.IIOImage class

# 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

  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 declared in class Object

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

- ## Field Details

  - ### 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 Details

  - ### 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 Details

  - ### 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(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(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(List)`

  - ### 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(List)`

  - ### 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(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()`