001/* IIOImage.java --
002   Copyright (C) 2003 Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038
039package javax.imageio;
040
041import java.awt.image.BufferedImage;
042import java.awt.image.Raster;
043import java.awt.image.RenderedImage;
044import java.util.List;
045
046import javax.imageio.metadata.IIOMetadata;
047
048/**
049 * IIOImage is a container class for components of an image file that
050 * stores image data, image metadata and thumbnails.
051 *
052 * The image data can be either a RenderedImage or a Raster but not
053 * both.  Image readers that produce IIOImages will always produce
054 * BufferedImages from the RenderedImage field.  Image writers that
055 * accept IIOImages will always accept RenderedImages and may
056 * optionally accept Rasters.
057 *
058 * @author Thomas Fitzsimmons (fitzsim@redhat.com)
059 */
060public class IIOImage
061{
062  /**
063   * Image data as a RenderedImage.  null if this IIOImage uses the
064   * Raster representation.
065   */
066  protected RenderedImage image;
067
068  /**
069   * Image metadata.
070   */
071  protected IIOMetadata metadata;
072
073  /**
074   * Image data as a Raster.  null if this IIOImage uses the
075   * RenderedImage representation.
076   */
077  protected Raster raster;
078
079  /**
080   * A list of BufferedImage thumbnails of this image.
081   */
082  protected List<? extends BufferedImage> thumbnails;
083
084  /**
085   * Construct an IIOImage containing raster image data, thumbnails
086   * and metadata.
087   *
088   * @param raster image data
089   * @param thumbnails a list of BufferedImage thumbnails or null
090   * @param metadata image metadata or null
091   *
092   * @exception IllegalArgumentException if raster is null
093   */
094  public IIOImage (Raster raster, List<? extends BufferedImage> thumbnails,
095                   IIOMetadata metadata)
096  {
097    if (raster == null)
098      throw new IllegalArgumentException ("raster may not be null");
099
100    this.raster = raster;
101    this.thumbnails = thumbnails;
102    this.metadata = metadata;
103  }
104
105  /**
106   * Construct an IIOImage containing rendered image data, thumbnails
107   * and metadata.
108   *
109   * @param image rendered image data
110   * @param thumbnails a list of BufferedImage thumbnails or null
111   * @param metadata image metadata or null
112   *
113   * @exception IllegalArgumentException if image is null
114   */
115  public IIOImage (RenderedImage image, List<? extends BufferedImage> thumbnails,
116                   IIOMetadata metadata)
117  {
118    if (image == null)
119      throw new IllegalArgumentException ("image may not be null");
120
121    this.image = image;
122    this.thumbnails = thumbnails;
123    this.metadata = metadata;
124  }
125
126  /**
127   * Retrieve the image metadata or null if there is no metadata
128   * associated with this IIOImage.
129   *
130   * @return image metadata or null
131   */
132  public IIOMetadata getMetadata()
133  {
134    return metadata;
135  }
136
137  /**
138   * Retrieve the number of thumbnails in this IIOImage.
139   *
140   * @return the number of thumbnails
141   */
142  public int getNumThumbnails()
143  {
144    return thumbnails == null ? 0 : thumbnails.size();
145  }
146
147  /**
148   * Retrieve the raster image data stored in this IIOImage or null if
149   * this image stores data using the RenderedImage representation.
150   *
151   * @return the raster image data or null
152   */
153  public Raster getRaster()
154  {
155    return raster;
156  }
157
158  /**
159   * Retrieve the rendered image data stored in this IIOImage or null
160   * if this image stores data using the Raster representation.
161   *
162   * @return the rendered image data or null
163   */
164  public RenderedImage getRenderedImage()
165  {
166    return image;
167  }
168
169  /**
170   * Retrieve the thumbnail stored at the specified index in the
171   * thumbnails list.
172   *
173   * @param index the index of the thumbnail to retrieve
174   *
175   * @return the buffered image thumbnail
176   *
177   * @exception IndexOutOfBoundsException if index is out-of-bounds
178   * @exception ClassCastException if the object returned from the
179   * thumbnails list is not a BufferedImage
180   */
181  public BufferedImage getThumbnail (int index)
182  {
183    // This throws a ClassCastException if the returned object is not
184    // a BufferedImage or an IndexOutOfBoundsException if index is
185    // out-of-bounds.
186    return (BufferedImage) thumbnails.get (index);
187  }
188
189  /**
190   * Retrieve the list of thumbnails or null if there are no
191   * thumbnails associated with this IIOImage.  The returned reference
192   * can be used to update the thumbnails list.
193   *
194   * @return a list of thumbnails or null
195   */
196  public List<? extends BufferedImage> getThumbnails()
197  {
198    return thumbnails;
199  }
200
201  /**
202   * Check whether this IIOImage stores its image data as a Raster or
203   * as a RenderedImage.
204   *
205   * @return true if this IIOImage uses the Raster representation,
206   * false if it uses the RenderedImage representation.
207   */
208  public boolean hasRaster()
209  {
210    return raster != null;
211  }
212
213  /**
214   * Set this IIOImage's metadata.
215   *
216   * @param metadata the image metadata
217   */
218  public void setMetadata (IIOMetadata metadata)
219  {
220    this.metadata = metadata;
221  }
222
223  /**
224   * Set the raster data for this image.  This disposes of any
225   * existing rendered image data stored in this IIOImage.
226   *
227   * @param raster the image raster data
228   *
229   * @exception IllegalArgumentException if raster is null
230   */
231  public void setRaster (Raster raster)
232  {
233    if (raster == null)
234      throw new IllegalArgumentException ("raster may not be null");
235
236    this.image = null;
237    this.raster = raster;
238  }
239
240  /**
241   * Set the rendered image data for this image.  This disposes of any
242   * existing raster data stored in this IIOImage.
243   *
244   * @param image the rendered image data
245   *
246   * @exception IllegalArgumentException if image is null
247   */
248  public void setRenderedImage (RenderedImage image)
249  {
250    if (image == null)
251      throw new IllegalArgumentException ("image may not be null");
252
253    this.image = image;
254    this.raster = null;
255  }
256
257  /**
258   * Set the list of thumbnails for this IIOImage to a new list of
259   * BufferedImages or to null.  Any existing thumbnails list is
260   * disposed.
261   *
262   * @param thumbnails a new list of thumbnails or null
263   */
264  public void setThumbnails (List<? extends BufferedImage> thumbnails)
265  {
266    this.thumbnails = thumbnails;
267  }
268}