javax.imageio

Class ImageReader

Known Direct Subclasses:
BMPImageReader, GIFImageReader, JPEGImageReader, PNGImageReader

public abstract class ImageReader
extends Object

A class for decoding images within the ImageIO framework. An ImageReader for a given format is instantiated by an ImageReaderSpi for that format. ImageReaderSpis are registered with the IIORegistry. The ImageReader API supports reading animated images that may have multiple frames; to support such images many methods take an index parameter. Images may also be read in multiple passes, where each successive pass increases the level of detail in the destination image.

Field Summary

protected Locale[]
availableLocales
All locales available for localization of warning messages, or null if localization is not supported.
protected boolean
ignoreMetadata
true if the input source does not require metadata to be read, false otherwise.
protected Object
input
An ImageInputStream from which image data is read.
protected Locale
locale
The current locale used to localize warning messages, or null if no locale has been set.
protected int
minIndex
The minimum index at which data can be read.
protected ImageReaderSpi
originatingProvider
The image reader SPI that instantiated this reader.
protected List
progressListeners
A list of installed progress listeners.
protected boolean
seekForwardOnly
true if this reader should only read data further ahead in the stream than its current location. false if it can read backwards in the stream.
protected List
updateListeners
A list of installed update listeners.
protected List
warningListeners
A list of installed warning listeners.
protected List
warningLocales
A list of warning locales corresponding with the list of installed warning listeners.

Constructor Summary

ImageReader(ImageReaderSpi originatingProvider)
Construct an image reader.

Method Summary

void
abort()
Request that reading be aborted.
protected boolean
abortRequested()
Check if the abort flag is set.
void
addIIOReadProgressListener(IIOReadProgressListener listener)
Install a read progress listener.
void
addIIOReadUpdateListener(IIOReadUpdateListener listener)
Install a read update listener.
void
addIIOReadWarningListener(IIOReadWarningListener listener)
Install a read warning listener.
boolean
canReadRaster()
Check if this reader can handle raster data.
protected static void
checkReadParamBandSettings(ImageReadParam param, int numSrcBands, int numDstBands)
Check that the given read parameters have valid source and destination band settings.
protected void
clearAbortRequest()
Clear the abort flag.
protected static void
computeRegions(ImageReadParam param, int srcWidth, int srcHeight, BufferedImage image, Rectangle srcRegion, Rectangle destRegion)
Calcluate the source and destination regions that will be read from and written to, given image parameters and/or a destination buffered image.
void
dispose()
Releases any resources allocated to this object.
float
getAspectRatio(int imageIndex)
Returns the aspect ratio of this image, the ration of its width to its height.
Locale[]
getAvailableLocales()
Retrieve the available locales.
ImageReadParam
getDefaultReadParam()
Retrieve the default read parameters for this reader's image format.
protected static BufferedImage
getDestination(ImageReadParam param, Iterator imageTypes, int width, int height)
Return a suitable destination buffered image.
String
getFormatName()
Retrieve the format of the input source.
abstract int
getHeight(int imageIndex)
Get the height of the input image in pixels.
abstract IIOMetadata
getImageMetadata(int imageIndex)
Get the metadata associated with this image.
IIOMetadata
getImageMetadata(int imageIndex, String formatName, Set nodeNames)
Get the metadata associated with this image.
abstract Iterator
getImageTypes(int imageIndex)
Get an iterator over the collection of image types into which this reader can decode image data.
Object
getInput()
Get this reader's image input source. null is returned if the image source has not been set.
Locale
getLocale()
Get this reader's locale. null is returned if the locale has not been set.
int
getMinIndex()
Get the index at which the next image will be read.
abstract int
getNumImages(boolean allowSearch)
Return the number of images available from the image input source, not including thumbnails.
int
getNumThumbnails(int imageIndex)
Get the number of thumbnails associated with an image.
ImageReaderSpi
getOriginatingProvider()
Get the ImageReaderSpi that created this reader or null.
ImageTypeSpecifier
getRawImageType(int imageIndex)
Get the image type specifier that most closely represents the internal data representation used by this reader.
protected static Rectangle
getSourceRegion(ImageReadParam param, int srcWidth, int srcHeight)
Calculate a source region based on the given source image dimensions and parameters.
abstract IIOMetadata
getStreamMetadata()
Get the metadata associated with the image being read.
IIOMetadata
getStreamMetadata(String formatName, Set nodeNames)
Get the metadata associated with the image being read.
int
getThumbnailHeight(int imageIndex, int thumbnailIndex)
Get the height of a thumbnail image.
int
getThumbnailWidth(int imageIndex, int thumbnailIndex)
Get the width of a thumbnail image.
int
getTileGridXOffset(int imageIndex)
Get the X coordinate in pixels of the top-left corner of the first tile in this image.
int
getTileGridYOffset(int imageIndex)
Get the Y coordinate in pixels of the top-left corner of the first tile in this image.
int
getTileHeight(int imageIndex)
Get the height of an image tile.
int
getTileWidth(int imageIndex)
Get the width of an image tile.
abstract int
getWidth(int imageIndex)
Get the width of the input image in pixels.
boolean
hasThumbnails(int imageIndex)
Check whether or not the given image has thumbnails associated with it.
boolean
isIgnoringMetadata()
Check if this image reader ignores metadata.
boolean
isImageTiled(int imageIndex)
Check if the given image is sub-divided into equal-sized non-overlapping pixel rectangles.
boolean
isRandomAccessEasy(int imageIndex)
Check if all pixels in this image are readily accessible.
boolean
isSeekForwardOnly()
Check if this image reader may only seek forward within the input stream.
protected void
processImageComplete()
Notifies all installed read progress listeners that image loading has completed by calling their imageComplete methods.
protected void
processImageProgress(float percentageDone)
Notifies all installed read progress listeners that a certain percentage of the image has been loaded, by calling their imageProgress methods.
protected void
processImageStarted(int imageIndex)
Notifies all installed read progress listeners, by calling their imageStarted methods, that image loading has started on the given image.
protected void
processImageUpdate(BufferedImage image, int minX, int minY, int width, int height, int periodX, int periodY, int[] bands)
Notifies all installed read update listeners, by calling their imageUpdate methods, that the set of samples has changed.
protected void
processPassComplete(BufferedImage image)
Notifies all installed update progress listeners, by calling their passComplete methods, that a progressive pass has completed.
protected void
processPassStarted(BufferedImage image, int pass, int minPass, int maxPass, int minX, int minY, int periodX, int periodY, int[] bands)
Notifies all installed read update listeners, by calling their passStarted methods, that a new pass has begun.
protected void
processReadAborted()
Notifies all installed read progress listeners that image loading has been aborted by calling their readAborted methods.
protected void
processSequenceComplete()
Notifies all installed read progress listeners, by calling their sequenceComplete methods, that a sequence of images has completed loading.
protected void
processSequenceStarted(int minIndex)
Notifies all installed read progress listeners, by calling their sequenceStarted methods, a sequence of images has started loading.
protected void
processThumbnailComplete()
Notifies all installed read progress listeners, by calling their thumbnailComplete methods, that a thumbnail has completed loading.
protected void
processThumbnailPassComplete(BufferedImage thumbnail)
Notifies all installed update progress listeners, by calling their thumbnailPassComplete methods, that a progressive pass has completed on a thumbnail.
protected void
processThumbnailPassStarted(BufferedImage thumbnail, int pass, int minPass, int maxPass, int minX, int minY, int periodX, int periodY, int[] bands)
Notifies all installed read update listeners, by calling their thumbnailPassStarted methods, that a new pass has begun.
protected void
processThumbnailProgress(float percentageDone)
Notifies all installed read progress listeners that a certain percentage of a thumbnail has been loaded, by calling their thumbnailProgress methods.
protected void
processThumbnailStarted(int imageIndex, int thumbnailIndex)
Notifies all installed read progress listeners, by calling their imageStarted methods, that thumbnail loading has started on the given thumbnail of the given image.
protected void
processThumbnailUpdate(BufferedImage image, int minX, int minY, int width, int height, int periodX, int periodY, int[] bands)
Notifies all installed read update listeners, by calling their thumbnailUpdate methods, that the set of samples has changed.
protected void
processWarningOccurred(String warning)
Notifies all installed warning listeners, by calling their warningOccurred methods, that a warning message has been raised.
protected void
processWarningOccurred(String baseName, String keyword)
Notify all installed warning listeners, by calling their warningOccurred methods, that a warning message has been raised.
BufferedImage
read(int imageIndex)
Read the given frame all at once, using default image read parameters, and return a buffered image.
abstract BufferedImage
read(int imageIndex, ImageReadParam param)
Read the given frame into a buffered image using the given read parameters.
Iterator
readAll(ImageReadParam> params)
Read all image frames all at once, using the given image read parameters iterator, and return an iterator over a collection of IIOImages.
IIOImage
readAll(int imageIndex, ImageReadParam param)
Read the given frame all at once, using the given image read parameters, and return an IIOImage.
RenderedImage
readAsRenderedImage(int imageIndex, ImageReadParam param)
Read a rendered image.
Raster
readRaster(int imageIndex, ImageReadParam param)
Read raw raster data.
BufferedImage
readThumbnail(int imageIndex, int thumbnailIndex)
Read a thumbnail.
BufferedImage
readTile(int imageIndex, int tileX, int tileY)
Read the given tile into a buffered image.
Raster
readTileRaster(int imageIndex, int tileX, int tileY)
Read the given tile into a raster containing the raw image data.
boolean
readerSupportsThumbnails()
Check if this reader supports reading thumbnails.
void
removeAllIIOReadProgressListeners()
Uninstall all read progress listeners.
void
removeAllIIOReadUpdateListeners()
Uninstall all read update listeners.
void
removeAllIIOReadWarningListeners()
Uninstall all read warning listeners.
void
removeIIOReadProgressListener(IIOReadProgressListener listener)
Uninstall the given read progress listener.
void
removeIIOReadUpdateListener(IIOReadUpdateListener listener)
Uninstall the given read update listener.
void
removeIIOReadWarningListener(IIOReadWarningListener listener)
Uninstall the given read warning listener.
void
reset()
Reset this reader's internal state.
void
setInput(Object input)
Set the input source to the given object.
void
setInput(Object in, boolean seekForwardOnly)
Set the input source to the given object and specify whether this reader should be allowed to read input from the data stream more than once.
void
setInput(Object input, boolean seekForwardOnly, boolean ignoreMetadata)
Set the input source to the given object, specify whether this reader should be allowed to read input from the data stream more than once, and specify whether this reader should ignore metadata in the input stream.
void
setLocale(Locale locale)
Set the current locale or use the default locale.

Methods inherited from class java.lang.Object

clone, equals, extends Object> getClass, finalize, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

availableLocales

protected Locale[] availableLocales
All locales available for localization of warning messages, or null if localization is not supported.

ignoreMetadata

protected boolean ignoreMetadata
true if the input source does not require metadata to be read, false otherwise.

input

protected Object input
An ImageInputStream from which image data is read.

locale

protected Locale locale
The current locale used to localize warning messages, or null if no locale has been set.

minIndex

protected int minIndex
The minimum index at which data can be read. Constantly 0 if seekForwardOnly is false, always increasing if seekForwardOnly is true.

originatingProvider

protected ImageReaderSpi originatingProvider
The image reader SPI that instantiated this reader.

progressListeners

protected List progressListeners
A list of installed progress listeners. Initially null, meaning no installed listeners.

seekForwardOnly

protected boolean seekForwardOnly
true if this reader should only read data further ahead in the stream than its current location. false if it can read backwards in the stream. If this is true then caching can be avoided.

updateListeners

protected List updateListeners
A list of installed update listeners. Initially null, meaning no installed listeners.

warningListeners

protected List warningListeners
A list of installed warning listeners. Initially null, meaning no installed listeners.

warningLocales

protected List warningLocales
A list of warning locales corresponding with the list of installed warning listeners. Initially null, meaning no locales.

Constructor Details

ImageReader

protected ImageReader(ImageReaderSpi originatingProvider)
Construct an image reader.
Parameters:
originatingProvider - the provider that is constructing this image reader, or null

Method Details

abort

public void abort()
Request that reading be aborted. The unread contents of the image will be undefined. Readers should clear the abort flag before starting a read operation, then poll it periodically during the read operation.

abortRequested

protected boolean abortRequested()
Check if the abort flag is set.
Returns:
true if the current read operation should be aborted, false otherwise

addIIOReadProgressListener

public void addIIOReadProgressListener(IIOReadProgressListener listener)
Install a read progress listener. This method will return immediately if listener is null.
Parameters:
listener - a read progress listener or null

addIIOReadUpdateListener

public void addIIOReadUpdateListener(IIOReadUpdateListener listener)
Install a read update listener. This method will return immediately if listener is null.
Parameters:
listener - a read update listener

addIIOReadWarningListener

public void addIIOReadWarningListener(IIOReadWarningListener listener)
Install a read warning listener. This method will return immediately if listener is null. Warning messages sent to this listener will be localized using the current locale. If the current locale is null then this reader will select a sensible default.
Parameters:
listener - a read warning listener

canReadRaster

public boolean canReadRaster()
Check if this reader can handle raster data. Determines whether or not readRaster and readTileRaster throw UnsupportedOperationException.
Returns:
true if this reader supports raster data, false if not

checkReadParamBandSettings

protected static void checkReadParamBandSettings(ImageReadParam param,
                                                 int numSrcBands,
                                                 int numDstBands)
Check that the given read parameters have valid source and destination band settings. If the param.getSourceBands() returns null, the array is assumed to include all band indices, 0 to numSrcBands - 1; likewise if param.getDestinationBands() returns null, it is assumed to be an array containing indices 0 to numDstBands - 1. A failure will cause this method to throw IllegalArgumentException.
Parameters:
param - the image parameters to check
numSrcBands - the number of input source bands
numDstBands - the number of ouput destination bands
Throws:
IllegalArgumentException - if either the given source or destination band indices are invalid

clearAbortRequest

protected void clearAbortRequest()
Clear the abort flag.

computeRegions

protected static void computeRegions(ImageReadParam param,
                                     int srcWidth,
                                     int srcHeight,
                                     BufferedImage image,
                                     Rectangle srcRegion,
                                     Rectangle destRegion)
Calcluate the source and destination regions that will be read from and written to, given image parameters and/or a destination buffered image. The source region will be clipped if any of its bounds are outside the destination region. Clipping will account for subsampling and destination offsets. Likewise, the destination region is clipped to the given destination image, if it is not null, using the given image parameters, if they are not null. IllegalArgumentException is thrown if either region will contain 0 pixels after clipping.
Parameters:
param - read parameters, or null
srcWidth - the width of the source image
srcHeight - the height of the source image
image - the destination image, or null
srcRegion - a rectangle whose values will be set to the clipped source region
destRegion - a rectangle whose values will be set to the clipped destination region
Throws:
IllegalArgumentException - if either srcRegion or destRegion is null
IllegalArgumentException - if either of the calculated regions is empty

dispose

public void dispose()
Releases any resources allocated to this object. Subsequent calls to methods on this object will produce undefined results. The default implementation does nothing; subclasses should use this method ensure that native resources are released.

getAspectRatio

public float getAspectRatio(int imageIndex)
            throws IOException
Returns the aspect ratio of this image, the ration of its width to its height. The aspect ratio is useful when resizing an image while keeping its proportions constant.
Parameters:
imageIndex - the frame index
Returns:
the image's aspect ratio
Throws:
IllegalStateException - if input is null
IndexOutOfBoundsException - if the frame index is out-of-bounds
IOException - if a read error occurs

getAvailableLocales

public Locale[] getAvailableLocales()
Retrieve the available locales. Return null if no locales are available or a clone of availableLocales.
Returns:
an array of locales or null

getDefaultReadParam

public ImageReadParam getDefaultReadParam()
Retrieve the default read parameters for this reader's image format. The default implementation returns new ImageReadParam().
Returns:
image reading parameters

getDestination

protected static BufferedImage getDestination(ImageReadParam param,
                                              Iterator imageTypes,
                                              int width,
                                              int height)
            throws IIOException
Return a suitable destination buffered image. If param.getDestination() is non-null, then it is returned, otherwise a buffered image is created using param.getDestinationType() if it is non-null and also in the given imageTypes collection, or the first element of imageTypes otherwise.
Parameters:
param - image read parameters from which a destination image or image type is retrieved, or null
imageTypes - a collection of legal image types
width - the width of the source image
height - the height of the source image
Returns:
a suitable destination buffered image
Throws:
IIOException - if param.getDestinationType() does not return an image type in imageTypes
IllegalArgumentException - if imageTypes is null or empty, or if a non-ImageTypeSpecifier object is retrieved from imageTypes
IllegalArgumentException - if the resulting destination region is empty
IllegalArgumentException - if the product of width and height is greater than Integer.MAX_VALUE

getFormatName

public String getFormatName()
            throws IOException
Retrieve the format of the input source.
Returns:
the input source format name
Throws:
IOException - if a read error occurs

getHeight

public abstract int getHeight(int imageIndex)
            throws IOException
Get the height of the input image in pixels. If the input image is resizable then a default height is returned.
Parameters:
imageIndex - the frame index
Returns:
the height of the input image
Throws:
IllegalStateException - if input has not been set
IndexOutOfBoundsException - if the frame index is out-of-bounds
IOException - if a read error occurs

getImageMetadata

public abstract IIOMetadata getImageMetadata(int imageIndex)
            throws IOException
Get the metadata associated with this image. If the reader is set to ignore metadata or does not support reading metadata, or if no metadata is available then null is returned.
Parameters:
imageIndex - the frame index
Returns:
a metadata object, or null
Throws:
IllegalStateException - if input has not been set
IndexOutOfBoundsException - if the frame index is out-of-bounds
IOException - if a read error occurs

getImageMetadata

public IIOMetadata getImageMetadata(int imageIndex,
                                    String formatName,
                                    Set nodeNames)
            throws IOException
Get the metadata associated with this image. If the reader is set to ignore metadata or does not support reading metadata, or if no metadata is available then null is returned. This more specific version of getImageMetadata(int) can be used to restrict metadata retrieval to specific formats and node names, which can limit the amount of data that needs to be processed.
Parameters:
imageIndex - the frame index
formatName - the format of metadata requested
nodeNames - a set of Strings specifiying node names to be retrieved
Returns:
a metadata object, or null
Throws:
IllegalStateException - if input has not been set
IndexOutOfBoundsException - if the frame index is out-of-bounds
IllegalArgumentException - if formatName is null
IllegalArgumentException - if nodeNames is null
IOException - if a read error occurs

getImageTypes

public abstract Iterator getImageTypes(int imageIndex)
            throws IOException
Get an iterator over the collection of image types into which this reader can decode image data. This method is guaranteed to return at least one valid image type specifier. The elements of the iterator should be ordered; the first element should be the most appropriate image type for this decoder, followed by the second-most appropriate, and so on.
Parameters:
imageIndex - the frame index
Returns:
an iterator over a collection of image type specifiers
Throws:
IllegalStateException - if input has not been set
IndexOutOfBoundsException - if the frame index is out-of-bounds
IOException - if a read error occurs

getInput

public Object getInput()
Get this reader's image input source. null is returned if the image source has not been set.
Returns:
an image input source object, or null

getLocale

public Locale getLocale()
Get this reader's locale. null is returned if the locale has not been set.
Returns:
this reader's locale, or null

getMinIndex

public int getMinIndex()
Get the index at which the next image will be read. If seekForwardOnly is true then the returned value will increase monotonically each time an image frame is read. If seekForwardOnly is false then the returned value will always be 0.
Returns:
the current frame index

getNumImages

public abstract int getNumImages(boolean allowSearch)
            throws IOException
Return the number of images available from the image input source, not including thumbnails. This method will return 1 unless this reader is reading an animated image. Certain multi-image formats do not encode the total number of images. When reading images in those formats it may be necessary to repeatedly call read, incrementing the image index at each call, until an IndexOutOfBoundsException is thrown. The allowSearch parameter determines whether all images must be available at all times. When allowSearch is false, getNumImages will return -1 if the total number of images is unknown. Otherwise this method returns the number of images.
Parameters:
allowSearch - true if all images should be available at once, false otherwise
Returns:
-1 if allowSearch is false and the total number of images is currently unknown, or the number of images
Throws:
IllegalStateException - if input has not been set, or if seekForwardOnly is true
IOException - if a read error occurs

getNumThumbnails

public int getNumThumbnails(int imageIndex)
            throws IOException
Get the number of thumbnails associated with an image.
Parameters:
imageIndex - the frame index
Returns:
the number of thumbnails associated with this image

getOriginatingProvider

public ImageReaderSpi getOriginatingProvider()
Get the ImageReaderSpi that created this reader or null.
Returns:
an ImageReaderSpi, or null

getRawImageType

public ImageTypeSpecifier getRawImageType(int imageIndex)
            throws IOException
Get the image type specifier that most closely represents the internal data representation used by this reader. This value should be included in the return value of getImageTypes.
Parameters:
imageIndex - the frame index
Returns:
an image type specifier
Throws:
IllegalStateException - if input has not been set
IndexOutOfBoundsException - if the frame index is out-of-bounds
IOException - if a read error occurs

getSourceRegion

protected static Rectangle getSourceRegion(ImageReadParam param,
                                           int srcWidth,
                                           int srcHeight)
Calculate a source region based on the given source image dimensions and parameters. Subsampling offsets and a source region are taken from the given image read parameters and used to clip the given image dimensions, returning a new rectangular region as a result.
Parameters:
param - image parameters, or null
srcWidth - the width of the source image
srcHeight - the height of the source image
Returns:
a clipped rectangle

getStreamMetadata

public abstract IIOMetadata getStreamMetadata()
            throws IOException
Get the metadata associated with the image being read. If the reader is set to ignore metadata or does not support reading metadata, or if no metadata is available then null is returned. This method returns metadata associated with the entirety of the image data, whereas getImageMetadata(int) returns metadata associated with a frame within a multi-image data stream.
Returns:
metadata associated with the image being read, or null
Throws:
IOException - if a read error occurs

getStreamMetadata

public IIOMetadata getStreamMetadata(String formatName,
                                     Set nodeNames)
            throws IOException
Get the metadata associated with the image being read. If the reader is set to ignore metadata or does not support reading metadata, or if no metadata is available then null is returned. This method returns metadata associated with the entirety of the image data, whereas getStreamMetadata() returns metadata associated with a frame within a multi-image data stream. This more specific version of getStreamMetadata() can be used to restrict metadata retrieval to specific formats and node names, which can limit the amount of data that needs to be processed.
Parameters:
formatName - the format of metadata requested
nodeNames - a set of Strings specifiying node names to be retrieved
Returns:
metadata associated with the image being read, or null
Throws:
IllegalArgumentException - if formatName is null
IllegalArgumentException - if nodeNames is null
IOException - if a read error occurs

getThumbnailHeight

public int getThumbnailHeight(int imageIndex,
                              int thumbnailIndex)
            throws IOException
Get the height of a thumbnail image.
Parameters:
imageIndex - the frame index
thumbnailIndex - the thumbnail index
Returns:
the height of the thumbnail image
Throws:
UnsupportedOperationException - if this reader does not support thumbnails
IllegalStateException - if input is null
IndexOutOfBoundsException - if either index is out-of-bounds
IOException - if a read error occurs

getThumbnailWidth

public int getThumbnailWidth(int imageIndex,
                             int thumbnailIndex)
            throws IOException
Get the width of a thumbnail image.
Parameters:
imageIndex - the frame index
thumbnailIndex - the thumbnail index
Returns:
the width of the thumbnail image
Throws:
UnsupportedOperationException - if this reader does not support thumbnails
IllegalStateException - if input is null
IndexOutOfBoundsException - if either index is out-of-bounds
IOException - if a read error occurs

getTileGridXOffset

public int getTileGridXOffset(int imageIndex)
            throws IOException
Get the X coordinate in pixels of the top-left corner of the first tile in this image.
Parameters:
imageIndex - the frame index
Returns:
the X coordinate of this image's first tile
Throws:
IllegalStateException - if input is needed but the input source is not set
IndexOutOfBoundsException - if the frame index is out-of-bounds
IOException - if a read error occurs

getTileGridYOffset

public int getTileGridYOffset(int imageIndex)
            throws IOException
Get the Y coordinate in pixels of the top-left corner of the first tile in this image.
Parameters:
imageIndex - the frame index
Returns:
the Y coordinate of this image's first tile
Throws:
IllegalStateException - if input is needed but the input source is not set
IndexOutOfBoundsException - if the frame index is out-of-bounds
IOException - if a read error occurs

getTileHeight

public int getTileHeight(int imageIndex)
            throws IOException
Get the height of an image tile.
Parameters:
imageIndex - the frame index
Returns:
the tile height for the given image
Throws:
IllegalStateException - if input is null
IndexOutOfBoundsException - if the frame index is out-of-bounds
IOException - if a read error occurs

getTileWidth

public int getTileWidth(int imageIndex)
            throws IOException
Get the width of an image tile.
Parameters:
imageIndex - the frame index
Returns:
the tile width for the given image
Throws:
IllegalStateException - if input is null
IndexOutOfBoundsException - if the frame index is out-of-bounds
IOException - if a read error occurs

getWidth

public abstract int getWidth(int imageIndex)
            throws IOException
Get the width of the input image in pixels. If the input image is resizable then a default width is returned.
Parameters:
imageIndex - the image's index
Returns:
the width of the input image
Throws:
IllegalStateException - if input has not been set
IndexOutOfBoundsException - if the frame index is out-of-bounds
IOException - if a read error occurs

hasThumbnails

public boolean hasThumbnails(int imageIndex)
            throws IOException
Check whether or not the given image has thumbnails associated with it.
Returns:
true if the given image has thumbnails, false otherwise
Throws:
IllegalStateException - if input is null
IndexOutOfBoundsException - if the frame index is out-of-bounds
IOException - if a read error occurs

isIgnoringMetadata

public boolean isIgnoringMetadata()
Check if this image reader ignores metadata. This method simply returns the value of ignoreMetadata.
Returns:
true if metadata is being ignored, false otherwise

isImageTiled

public boolean isImageTiled(int imageIndex)
            throws IOException
Check if the given image is sub-divided into equal-sized non-overlapping pixel rectangles. A reader may expose tiling in the underlying format, hide it, or simulate tiling even if the underlying format is not tiled.
Returns:
true if the given image is tiled, false otherwise
Throws:
IllegalStateException - if input is null
IndexOutOfBoundsException - if the frame index is out-of-bounds
IOException - if a read error occurs

isRandomAccessEasy

public boolean isRandomAccessEasy(int imageIndex)
            throws IOException
Check if all pixels in this image are readily accessible. This method should return false for compressed formats. The return value is a hint as to the efficiency of certain image reader operations.
Parameters:
imageIndex - the frame index
Returns:
true if random pixel access is fast, false otherwise
Throws:
IllegalStateException - if input is null and it is needed to determine the return value
IndexOutOfBoundsException - if the frame index is out-of-bounds but the frame data must be accessed to determine the return value
IOException - if a read error occurs

isSeekForwardOnly

public boolean isSeekForwardOnly()
Check if this image reader may only seek forward within the input stream.
Returns:
true if this reader may only seek forward, false otherwise

processImageComplete

protected void processImageComplete()
Notifies all installed read progress listeners that image loading has completed by calling their imageComplete methods.

processImageProgress

protected void processImageProgress(float percentageDone)
Notifies all installed read progress listeners that a certain percentage of the image has been loaded, by calling their imageProgress methods.
Parameters:
percentageDone - the percentage of image data that has been loaded

processImageStarted

protected void processImageStarted(int imageIndex)
Notifies all installed read progress listeners, by calling their imageStarted methods, that image loading has started on the given image.
Parameters:
imageIndex - the frame index of the image that has started loading

processImageUpdate

protected void processImageUpdate(BufferedImage image,
                                  int minX,
                                  int minY,
                                  int width,
                                  int height,
                                  int periodX,
                                  int periodY,
                                  int[] bands)
Notifies all installed read update listeners, by calling their imageUpdate methods, that the set of samples has changed.
Parameters:
image - the buffered image that is being updated
minX - the X coordinate of the top-left pixel in this pass
minY - the Y coordinate of the top-left pixel in this pass
width - the total width of the rectangle covered by this pass, including skipped pixels
height - the total height of the rectangle covered by this pass, including skipped pixels
periodX - the horizontal sample interval
periodY - the vertical sample interval
bands - the affected bands in the destination

processPassComplete

protected void processPassComplete(BufferedImage image)
Notifies all installed update progress listeners, by calling their passComplete methods, that a progressive pass has completed.
Parameters:
image - the image that has being updated

processPassStarted

protected void processPassStarted(BufferedImage image,
                                  int pass,
                                  int minPass,
                                  int maxPass,
                                  int minX,
                                  int minY,
                                  int periodX,
                                  int periodY,
                                  int[] bands)
Notifies all installed read update listeners, by calling their passStarted methods, that a new pass has begun.
Parameters:
image - the buffered image that is being updated
pass - the current pass number
minPass - the pass at which decoding will begin
maxPass - the pass at which decoding will end
minX - the X coordinate of the top-left pixel in this pass
minY - the Y coordinate of the top-left pixel in this pass
periodX - the horizontal sample interval
periodY - the vertical sample interval
bands - the affected bands in the destination

processReadAborted

protected void processReadAborted()
Notifies all installed read progress listeners that image loading has been aborted by calling their readAborted methods.

processSequenceComplete

protected void processSequenceComplete()
Notifies all installed read progress listeners, by calling their sequenceComplete methods, that a sequence of images has completed loading.

processSequenceStarted

protected void processSequenceStarted(int minIndex)
Notifies all installed read progress listeners, by calling their sequenceStarted methods, a sequence of images has started loading.
Parameters:
minIndex - the index of the first image in the sequence

processThumbnailComplete

protected void processThumbnailComplete()
Notifies all installed read progress listeners, by calling their thumbnailComplete methods, that a thumbnail has completed loading.

processThumbnailPassComplete

protected void processThumbnailPassComplete(BufferedImage thumbnail)
Notifies all installed update progress listeners, by calling their thumbnailPassComplete methods, that a progressive pass has completed on a thumbnail.
Parameters:
thumbnail - the thumbnail that has being updated

processThumbnailPassStarted

protected void processThumbnailPassStarted(BufferedImage thumbnail,
                                           int pass,
                                           int minPass,
                                           int maxPass,
                                           int minX,
                                           int minY,
                                           int periodX,
                                           int periodY,
                                           int[] bands)
Notifies all installed read update listeners, by calling their thumbnailPassStarted methods, that a new pass has begun.
Parameters:
thumbnail - the thumbnail that is being updated
pass - the current pass number
minPass - the pass at which decoding will begin
maxPass - the pass at which decoding will end
minX - the X coordinate of the top-left pixel in this pass
minY - the Y coordinate of the top-left pixel in this pass
periodX - the horizontal sample interval
periodY - the vertical sample interval
bands - the affected bands in the destination

processThumbnailProgress

protected void processThumbnailProgress(float percentageDone)
Notifies all installed read progress listeners that a certain percentage of a thumbnail has been loaded, by calling their thumbnailProgress methods.
Parameters:
percentageDone - the percentage of thumbnail data that has been loaded

processThumbnailStarted

protected void processThumbnailStarted(int imageIndex,
                                       int thumbnailIndex)
Notifies all installed read progress listeners, by calling their imageStarted methods, that thumbnail loading has started on the given thumbnail of the given image.
Parameters:
imageIndex - the frame index of the image one of who's thumbnails has started loading
thumbnailIndex - the index of the thumbnail that has started loading

processThumbnailUpdate

protected void processThumbnailUpdate(BufferedImage image,
                                      int minX,
                                      int minY,
                                      int width,
                                      int height,
                                      int periodX,
                                      int periodY,
                                      int[] bands)
Notifies all installed read update listeners, by calling their thumbnailUpdate methods, that the set of samples has changed.
Parameters:
image - the buffered image that is being updated
minX - the X coordinate of the top-left pixel in this pass
minY - the Y coordinate of the top-left pixel in this pass
width - the total width of the rectangle covered by this pass, including skipped pixels
height - the total height of the rectangle covered by this pass, including skipped pixels
periodX - the horizontal sample interval
periodY - the vertical sample interval
bands - the affected bands in the destination

processWarningOccurred

protected void processWarningOccurred(String warning)
Notifies all installed warning listeners, by calling their warningOccurred methods, that a warning message has been raised.
Parameters:
warning - the warning message
Throws:
IllegalArgumentException - if warning is null

processWarningOccurred

protected void processWarningOccurred(String baseName,
                                      String keyword)
Notify all installed warning listeners, by calling their warningOccurred methods, that a warning message has been raised. The warning message is retrieved from a resource bundle, using the given basename and keyword.
Parameters:
baseName - the basename of the resource from which to retrieve the warning message
keyword - the keyword used to retrieve the warning from the resource bundle
Throws:
IllegalArgumentException - if either baseName or keyword is null
IllegalArgumentException - if no resource bundle is found using baseName
IllegalArgumentException - if the given keyword produces no results from the resource bundle
IllegalArgumentException - if the retrieved object is not a String

read

public BufferedImage read(int imageIndex)
            throws IOException
Read the given frame all at once, using default image read parameters, and return a buffered image. The returned image will be formatted according to the currently-preferred image type specifier. Installed read progress listeners, update progress listeners and warning listeners will be notified of read progress, changes in sample sets and warnings respectively.
Parameters:
imageIndex - the index of the image frame to read
Returns:
a buffered image
Throws:
IllegalStateException - if input has not been set
IndexOutOfBoundsException - if the frame index is out-of-bounds
IOException - if a read error occurs

read

public abstract BufferedImage read(int imageIndex,
                                   ImageReadParam param)
            throws IOException
Read the given frame into a buffered image using the given read parameters. Listeners will be notified of image loading progress and warnings.
Parameters:
imageIndex - the index of the frame to read
param - the image read parameters to use when reading
Returns:
a buffered image
Throws:
IllegalStateException - if input is null
IndexOutOfBoundsException - if the frame index is out-of-bounds
IOException - if a read error occurs

readAll

public Iterator readAll(ImageReadParam> params)
            throws IOException
Read all image frames all at once, using the given image read parameters iterator, and return an iterator over a collection of IIOImages. Each IIOImage in the collection will contain a buffered image as returned by getDestination. Installed read progress listeners, update progress listeners and warning listeners will be notified of read progress, changes in sample sets and warnings respectively. Each set of source and destination band settings are checked with a call to checkReadParamBandSettings.
Parameters:
params - iterator over the image read parameters
Returns:
an IIOImage
Throws:
IllegalStateException - if input has not been set
IllegalArgumentException - if a non-ImageReadParam is found in params
IllegalArgumentException - if param.getSourceBands() and param.getDestinationBands() are incompatible
IllegalArgumentException - if either the source or destination image regions are empty
IOException - if a read error occurs

readAll

public IIOImage readAll(int imageIndex,
                        ImageReadParam param)
            throws IOException
Read the given frame all at once, using the given image read parameters, and return an IIOImage. The IIOImage will contain a buffered image as returned by getDestination. Installed read progress listeners, update progress listeners and warning listeners will be notified of read progress, changes in sample sets and warnings respectively. The source and destination band settings are checked with a call to checkReadParamBandSettings.
Parameters:
imageIndex - the index of the image frame to read
param - the image read parameters
Returns:
an IIOImage
Throws:
IllegalStateException - if input has not been set
IndexOutOfBoundsException - if the frame index is out-of-bounds
IllegalArgumentException - if param.getSourceBands() and param.getDestinationBands() are incompatible
IllegalArgumentException - if either the source or destination image regions are empty
IOException - if a read error occurs

readAsRenderedImage

public RenderedImage readAsRenderedImage(int imageIndex,
                                         ImageReadParam param)
            throws IOException
Read a rendered image. This is a more general counterpart to read (int, ImageReadParam). All image data may not be read before this method returns and so listeners will not necessarily be notified.
Parameters:
imageIndex - the index of the image frame to read
param - the image read parameters
Returns:
a rendered image
Throws:
IllegalStateException - if input is null
IndexOutOfBoundsException - if the frame index is out-of-bounds
IllegalArgumentException - if param.getSourceBands() and param.getDestinationBands() are incompatible
IllegalArgumentException - if either the source or destination image regions are empty
IOException - if a read error occurs

readRaster

public Raster readRaster(int imageIndex,
                         ImageReadParam param)
            throws IOException
Read raw raster data. The image type specifier in param is ignored but all other parameters are used. Offset parameters are translated into the raster's coordinate space. This method may be implemented by image readers that want to provide direct access to raw image data.
Parameters:
imageIndex - the frame index
param - the image read parameters
Returns:
a raster containing the read image data
Throws:
UnsupportedOperationException - if this reader doesn't support rasters
IllegalStateException - if input is null
IndexOutOfBoundsException - if the frame index is out-of-bounds
IOException - if a read error occurs

readThumbnail

public BufferedImage readThumbnail(int imageIndex,
                                   int thumbnailIndex)
            throws IOException
Read a thumbnail.
Parameters:
imageIndex - the frame index
thumbnailIndex - the thumbnail index
Returns:
a buffered image of the thumbnail
Throws:
UnsupportedOperationException - if this reader doesn't support thumbnails
IllegalStateException - if input is null
IndexOutOfBoundsException - if either the frame index or the thumbnail index is out-of-bounds
IOException - if a read error occurs

readTile

public BufferedImage readTile(int imageIndex,
                              int tileX,
                              int tileY)
            throws IOException
Read the given tile into a buffered image. If the tile coordinates are out-of-bounds an exception is thrown. If the image is not tiled then the coordinates 0, 0 are expected and the entire image will be read.
Parameters:
imageIndex - the frame index
tileX - the horizontal tile coordinate
tileY - the vertical tile coordinate
Returns:
the contents of the tile as a buffered image
Throws:
IllegalStateException - if input is null
IndexOutOfBoundsException - if the frame index is out-of-bounds
IllegalArgumentException - if the tile coordinates are out-of-bounds
IOException - if a read error occurs

readTileRaster

public Raster readTileRaster(int imageIndex,
                             int tileX,
                             int tileY)
            throws IOException
Read the given tile into a raster containing the raw image data. If the tile coordinates are out-of-bounds an exception is thrown. If the image is not tiled then the coordinates 0, 0 are expected and the entire image will be read.
Parameters:
imageIndex - the frame index
tileX - the horizontal tile coordinate
tileY - the vertical tile coordinate
Returns:
the contents of the tile as a raster
Throws:
UnsupportedOperationException - if rasters are not supported
IllegalStateException - if input is null
IndexOutOfBoundsException - if the frame index is out-of-bounds
IllegalArgumentException - if the tile coordinates are out-of-bounds
IOException - if a read error occurs

readerSupportsThumbnails

public boolean readerSupportsThumbnails()
Check if this reader supports reading thumbnails.
Returns:
true if this reader supports reading thumbnails, false otherwise

removeAllIIOReadProgressListeners

public void removeAllIIOReadProgressListeners()
Uninstall all read progress listeners.

removeAllIIOReadUpdateListeners

public void removeAllIIOReadUpdateListeners()
Uninstall all read update listeners.

removeAllIIOReadWarningListeners

public void removeAllIIOReadWarningListeners()
Uninstall all read warning listeners.

removeIIOReadProgressListener

public void removeIIOReadProgressListener(IIOReadProgressListener listener)
Uninstall the given read progress listener.
Parameters:
listener - the listener to remove

removeIIOReadUpdateListener

public void removeIIOReadUpdateListener(IIOReadUpdateListener listener)
Uninstall the given read update listener.
Parameters:
listener - the listener to remove

removeIIOReadWarningListener

public void removeIIOReadWarningListener(IIOReadWarningListener listener)
Uninstall the given read warning listener.
Parameters:
listener - the listener to remove

reset

public void reset()
Reset this reader's internal state.

setInput

public void setInput(Object input)
Set the input source to the given object. The input source must be set before many methods can be called on this reader. (see all ImageReader methods that throw IllegalStateException). If input is null then the current input source will be removed.
Parameters:
input - the input source object
Throws:
IllegalArgumentException - if input is not a valid input source for this reader and is not an ImageInputStream

setInput

public void setInput(Object in,
                     boolean seekForwardOnly)
Set the input source to the given object and specify whether this reader should be allowed to read input from the data stream more than once. The input source must be set before many methods can be called on this reader. (see all ImageReader methods that throw IllegalStateException). If input is null then the current input source will be removed.
Parameters:
in - the input source object
seekForwardOnly - true if this reader should be allowed to read input from the data stream more than once, false otherwise
Throws:
IllegalArgumentException - if input is not a valid input source for this reader and is not an ImageInputStream

setInput

public void setInput(Object input,
                     boolean seekForwardOnly,
                     boolean ignoreMetadata)
Set the input source to the given object, specify whether this reader should be allowed to read input from the data stream more than once, and specify whether this reader should ignore metadata in the input stream. The input source must be set before many methods can be called on this reader. (see all ImageReader methods that throw IllegalStateException). If input is null then the current input source will be removed. Unless this reader has direct access with imaging hardware, input should be an ImageInputStream.
Parameters:
input - the input source object
seekForwardOnly - true if this reader should be allowed to read input from the data stream more than once, false otherwise
ignoreMetadata - true if this reader should ignore metadata associated with the input source, false otherwise
Throws:
IllegalArgumentException - if input is not a valid input source for this reader and is not an ImageInputStream

setLocale

public void setLocale(Locale locale)
Set the current locale or use the default locale.
Parameters:
locale - the locale to set, or null

ImageReader.java -- Decodes raster images. Copyright (C) 2004, 2005 Free Software Foundation, Inc. This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.