java.lang.Object javax.imageio.ImageReader
An abstract superclass for parsing and decoding of images. This class must be subclassed by classes that read in images in the context of the Java Image I/O framework.
ImageReader objects are normally instantiated by the service provider interface (SPI) class for the specific format. Service provider classes (e.g., instances of ImageReaderSpi) are registered with the IIORegistry, which uses them for format recognition and presentation of available format readers and writers.
When an input source is set (using the setInput method), it may be marked as "seek forward only". This setting means that images contained within the input source will only be read in order, possibly allowing the reader to avoid caching portions of the input containing data associated with images that have been read previously.
Field Summary | |
---|---|
protected Locale [] |
availableLocales
An array of Locales which may be used to localize warning messages, or null if localization is not supported. |
protected boolean |
ignoreMetadata
true if the current input source has been marked as allowing metadata to be ignored by setInput. |
protected Object |
input
The ImageInputStream or other Object by setInput and retrieved by getInput. |
protected Locale |
locale
The current Locale to be used for localization, or null if none has been set. |
protected int |
minIndex
The smallest valid index for reading, initially 0. |
protected ImageReaderSpi |
originatingProvider
The ImageReaderSpi that instantiated this object, or null if its identity is not known or none exists. |
protected List |
progressListeners
A List of currently registered IIOReadProgressListeners, initialized by default to null, which is synonymous with an empty List. |
protected boolean |
seekForwardOnly
true if the current input source has been marked as allowing only forward seeking by setInput. |
protected List |
updateListeners
A List of currently registered IIOReadUpdateListeners, initialized by default to null, which is synonymous with an empty List. |
protected List |
warningListeners
A List of currently registered IIOReadWarningListeners, initialized by default to null, which is synonymous with an empty List. |
protected List |
warningLocales
A List of the Locales associated with each currently registered IIOReadWarningListener, initialized by default to null, which is synonymous with an empty List. |
Constructor Summary | |
---|---|
protected |
ImageReader
(
ImageReaderSpi
originatingProvider) Constructs an ImageReader and sets its originatingProvider field to the supplied value. |
Method Summary | |
---|---|
void |
abort
() Requests that any current read operation be aborted. |
protected boolean |
abortRequested
() Returns true if a request to abort the current read operation has been made since the reader was instantiated or clearAbortRequest was called. |
void |
addIIOReadProgressListener
(
IIOReadProgressListener
listener) Adds an IIOReadProgressListener to the list of registered progress listeners. |
void |
addIIOReadUpdateListener
(
IIOReadUpdateListener
listener) Adds an IIOReadUpdateListener to the list of registered update listeners. |
void |
addIIOReadWarningListener
(
IIOReadWarningListener
listener) Adds an IIOReadWarningListener to the list of registered warning listeners. |
boolean |
canReadRaster
() Returns true if this plug-in supports reading just a Raster of pixel data. |
protected static void |
checkReadParamBandSettings
(
ImageReadParam
param, int numSrcBands, int numDstBands) A utility method that may be used by readers to test the validity of the source and destination band settings of an ImageReadParam. |
protected void |
clearAbortRequest
() Clears any previous abort request. |
protected static void |
computeRegions
(
ImageReadParam
param, int srcWidth, int srcHeight,
BufferedImage
image,
Rectangle
srcRegion,
Rectangle
destRegion) Computes the source region of interest and the destination region of interest, taking the width and height of the source image, an optional destination image, and an optional ImageReadParam into account. |
void |
dispose
() Allows any resources held by this object to be released. |
float |
getAspectRatio
(int imageIndex) Returns the aspect ratio of the given image (that is, its width divided by its height) as a float. |
Locale [] |
getAvailableLocales
() Returns an array of Locales that may be used to localize warning listeners and compression settings. |
ImageReadParam |
getDefaultReadParam
() Returns a default ImageReadParam object appropriate for this format. |
protected static BufferedImage |
getDestination
(
ImageReadParam
param,
Iterator
imageTypes, int width, int height) Returns the BufferedImage to which decoded pixel data should be written. |
String |
getFormatName
() Returns a String identifying the format of the input source. |
abstract int |
getHeight
(int imageIndex) Returns the height in pixels of the given image within the input source. |
abstract IIOMetadata |
getImageMetadata
(int imageIndex) Returns an IIOMetadata object containing metadata associated with the given image, or null if the reader does not support reading metadata, is set to ignore metadata, or if no metadata is available. |
IIOMetadata |
getImageMetadata
(int imageIndex,
String
formatName,
Set
nodeNames) Returns an IIOMetadata object representing the metadata associated with the given image, or null if the reader does not support reading metadata or none is available. |
abstract Iterator |
getImageTypes
(int imageIndex) Returns an Iterator containing possible image types to which the given image may be decoded, in the form of ImageTypeSpecifierss. |
Object |
getInput
() Returns the ImageInputStream or other Object previously set as the input source. |
Locale |
getLocale
() Returns the currently set Locale, or null if none has been set. |
int |
getMinIndex
() Returns the lowest valid index for reading an image, thumbnail, or image metadata. |
abstract int |
getNumImages
(boolean allowSearch) Returns the number of images, not including thumbnails, available from the current input source. |
int |
getNumThumbnails
(int imageIndex) Returns the number of thumbnail preview images associated with the given image. |
ImageReaderSpi |
getOriginatingProvider
() Returns the ImageReaderSpi that was passed in on the constructor. |
ImageTypeSpecifier |
getRawImageType
(int imageIndex) Returns an ImageTypeSpecifier indicating the SampleModel and ColorModel which most closely represents the "raw" internal format of the image. |
protected static Rectangle |
getSourceRegion
(
ImageReadParam
param, int srcWidth, int srcHeight) A utility method that may be used by readers to compute the region of the source image that should be read, taking into account any source region and subsampling offset settings in the supplied ImageReadParam. |
abstract IIOMetadata |
getStreamMetadata
() Returns an IIOMetadata object representing the metadata associated with the input source as a whole (i.e., not associated with any particular image), or null if the reader does not support reading metadata, is set to ignore metadata, or if no metadata is available. |
IIOMetadata |
getStreamMetadata
(
String
formatName,
Set
nodeNames) Returns an IIOMetadata object representing the metadata associated with the input source as a whole (i.e., not associated with any particular image). |
int |
getThumbnailHeight
(int imageIndex, int thumbnailIndex) Returns the height of the thumbnail preview image indexed by thumbnailIndex, associated with the image indexed by ImageIndex. |
int |
getThumbnailWidth
(int imageIndex, int thumbnailIndex) Returns the width of the thumbnail preview image indexed by thumbnailIndex, associated with the image indexed by ImageIndex. |
int |
getTileGridXOffset
(int imageIndex) Returns the X coordinate of the upper-left corner of tile (0, 0) in the given image. |
int |
getTileGridYOffset
(int imageIndex) Returns the Y coordinate of the upper-left corner of tile (0, 0) in the given image. |
int |
getTileHeight
(int imageIndex) Returns the height of a tile in the given image. |
int |
getTileWidth
(int imageIndex) Returns the width of a tile in the given image. |
abstract int |
getWidth
(int imageIndex) Returns the width in pixels of the given image within the input source. |
boolean |
hasThumbnails
(int imageIndex) Returns true if the given image has thumbnail preview images associated with it. |
boolean |
isIgnoringMetadata
() Returns true if the current input source has been marked as allowing metadata to be ignored by passing true as the ignoreMetadata argument to the setInput method. |
boolean |
isImageTiled
(int imageIndex) Returns true if the image is organized into tiles , that is, equal-sized non-overlapping rectangles. |
boolean |
isRandomAccessEasy
(int imageIndex) Returns true if the storage format of the given image places no inherent impediment on random access to pixels. |
boolean |
isSeekForwardOnly
() Returns true if the current input source has been marked as seek forward only by passing true as the seekForwardOnly argument to the setInput method. |
protected void |
processImageComplete
() Broadcasts the completion of an image read to all registered IIOReadProgressListeners by calling their imageComplete method. |
protected void |
processImageProgress
(float percentageDone) Broadcasts the current percentage of image completion to all registered IIOReadProgressListeners by calling their imageProgress method. |
protected void |
processImageStarted
(int imageIndex) Broadcasts the start of an image read to all registered IIOReadProgressListeners by calling their imageStarted method. |
protected void |
processImageUpdate
(
BufferedImage
theImage, int minX, int minY, int width, int height, int periodX, int periodY, int[] bands) Broadcasts the update of a set of samples to all registered IIOReadUpdateListeners by calling their imageUpdate method. |
protected void |
processPassComplete
(
BufferedImage
theImage) Broadcasts the end of a progressive pass to all registered IIOReadUpdateListeners by calling their passComplete method. |
protected void |
processPassStarted
(
BufferedImage
theImage, int pass, int minPass, int maxPass, int minX, int minY, int periodX, int periodY, int[] bands) Broadcasts the beginning of a progressive pass to all registered IIOReadUpdateListeners by calling their passStarted method. |
protected void |
processReadAborted
() Broadcasts that the read has been aborted to all registered IIOReadProgressListeners by calling their readAborted method. |
protected void |
processSequenceComplete
() Broadcasts the completion of an sequence of image reads to all registered IIOReadProgressListeners by calling their sequenceComplete method. |
protected void |
processSequenceStarted
(int minIndex) Broadcasts the start of an sequence of image reads to all registered IIOReadProgressListeners by calling their sequenceStarted method. |
protected void |
processThumbnailComplete
() Broadcasts the completion of a thumbnail read to all registered IIOReadProgressListeners by calling their thumbnailComplete method. |
protected void |
processThumbnailPassComplete
(
BufferedImage
theThumbnail) Broadcasts the end of a thumbnail progressive pass to all registered IIOReadUpdateListeners by calling their thumbnailPassComplete method. |
protected void |
processThumbnailPassStarted
(
BufferedImage
theThumbnail, int pass, int minPass, int maxPass, int minX, int minY, int periodX, int periodY, int[] bands) Broadcasts the beginning of a thumbnail progressive pass to all registered IIOReadUpdateListeners by calling their thumbnailPassStarted method. |
protected void |
processThumbnailProgress
(float percentageDone) Broadcasts the current percentage of thumbnail completion to all registered IIOReadProgressListeners by calling their thumbnailProgress method. |
protected void |
processThumbnailStarted
(int imageIndex, int thumbnailIndex) Broadcasts the start of a thumbnail read to all registered IIOReadProgressListeners by calling their thumbnailStarted method. |
protected void |
processThumbnailUpdate
(
BufferedImage
theThumbnail, int minX, int minY, int width, int height, int periodX, int periodY, int[] bands) Broadcasts the update of a set of samples in a thumbnail image to all registered IIOReadUpdateListeners by calling their thumbnailUpdate method. |
protected void |
processWarningOccurred
(
String
warning) Broadcasts a warning message to all registered IIOReadWarningListeners by calling their warningOccurred method. |
protected void |
processWarningOccurred
(
String
baseName,
String
keyword) Broadcasts a localized warning message to all registered IIOReadWarningListeners by calling their warningOccurred method with a string taken from a ResourceBundle. |
BufferedImage |
read
(int imageIndex) Reads the image indexed by imageIndex and returns it as a complete BufferedImage, using a default ImageReadParam. |
abstract BufferedImage |
read
(int imageIndex,
ImageReadParam
param) Reads the image indexed by imageIndex and returns it as a complete BufferedImage, using a supplied ImageReadParam. |
IIOImage |
readAll
(int imageIndex,
ImageReadParam
param) Reads the image indexed by imageIndex and returns an IIOImage containing the image, thumbnails, and associated image metadata, using a supplied ImageReadParam. |
Iterator |
readAll
(
Iterator
params) Returns an Iterator containing all the images, thumbnails, and metadata, starting at the index given by getMinIndex, from the input source in the form of IIOImage objects. |
RenderedImage |
readAsRenderedImage
(int imageIndex,
ImageReadParam
param) Returns a RenderedImage object that contains the contents of the image indexed by imageIndex. |
boolean |
readerSupportsThumbnails
() Returns true if the image format understood by this reader supports thumbnail preview images associated with it. |
Raster |
readRaster
(int imageIndex,
ImageReadParam
param) Returns a new Raster object containing the raw pixel data from the image stream, without any color conversion applied. |
BufferedImage |
readThumbnail
(int imageIndex, int thumbnailIndex) Returns the thumbnail preview image indexed by thumbnailIndex, associated with the image indexed by ImageIndex as a BufferedImage. |
BufferedImage |
readTile
(int imageIndex, int tileX, int tileY) Reads the tile indicated by the tileX and tileY arguments, returning it as a BufferedImage. |
Raster |
readTileRaster
(int imageIndex, int tileX, int tileY) Returns a new Raster object containing the raw pixel data from the tile, without any color conversion applied. |
void |
removeAllIIOReadProgressListeners
() Removes all currently registered IIOReadProgressListener objects. |
void |
removeAllIIOReadUpdateListeners
() Removes all currently registered IIOReadUpdateListener objects. |
void |
removeAllIIOReadWarningListeners
() Removes all currently registered IIOReadWarningListener objects. |
void |
removeIIOReadProgressListener
(
IIOReadProgressListener
listener) Removes an IIOReadProgressListener from the list of registered progress listeners. |
void |
removeIIOReadUpdateListener
(
IIOReadUpdateListener
listener) Removes an IIOReadUpdateListener from the list of registered update listeners. |
void |
removeIIOReadWarningListener
(
IIOReadWarningListener
listener) Removes an IIOReadWarningListener from the list of registered error listeners. |
void |
reset
() Restores the ImageReader to its initial state. |
void |
setInput
(
Object
input) Sets the input source to use to the given ImageInputStream or other Object. |
void |
setInput
(
Object
input, boolean seekForwardOnly) Sets the input source to use to the given ImageInputStream or other Object. |
void |
setInput
(
Object
input, boolean seekForwardOnly, boolean ignoreMetadata) Sets the input source to use to the given ImageInputStream or other Object. |
void |
setLocale
(
Locale
locale) Sets the current Locale of this ImageReader to the given value. |
Methods inherited from class java.lang. Object |
---|
clone , equals , finalize , getClass , hashCode , notify , notifyAll , toString , wait , wait , wait |
Field Detail |
---|
protected ImageReaderSpi originatingProvider
protected Object input
protected boolean seekForwardOnly
protected boolean ignoreMetadata
protected int minIndex
protected Locale[] availableLocales
protected Locale locale
protected List warningListeners
protected List warningLocales
protected List progressListeners
protected List updateListeners
Constructor Detail |
---|
protected ImageReader(ImageReaderSpi originatingProvider)
Subclasses that make use of extensions should provide a constructor with signature (ImageReaderSpi, Object) in order to retrieve the extension object. If the extension object is unsuitable, an IllegalArgumentException should be thrown.
Method Detail |
---|
public String getFormatName() throws IOException
The default implementation returns originatingProvider.getFormatNames()[0]. Implementations that may not have an originating service provider, or which desire a different naming policy should override this method.
public ImageReaderSpi getOriginatingProvider()
public void setInput(Object input, boolean seekForwardOnly, boolean ignoreMetadata)
The seekForwardOnly parameter controls whether the value returned by getMinIndex will be increased as each image (or thumbnail, or image metadata) is read. If seekForwardOnly is true, then a call to read(index) will throw an IndexOutOfBoundsException if index < this.minIndex; otherwise, the value of minIndex will be set to index. If seekForwardOnly is false, the value of minIndex will remain 0 regardless of any read operations.
The ignoreMetadata parameter, if set to true, allows the reader to disregard any metadata encountered during the read. Subsequent calls to the getStreamMetadata and getImageMetadata methods may return null, and an IIOImage returned from readAll may return null from their getMetadata method. Setting this parameter may allow the reader to work more efficiently. The reader may choose to disregard this setting and return metadata normally.
Subclasses should take care to remove any cached information based on the previous stream, such as header information or partially decoded image data.
Use of a general Object other than an ImageInputStream is intended for readers that interact directly with a capture device or imaging protocol. The set of legal classes is advertised by the reader's service provider's getInputTypes method; most readers will return a single-element array containing only ImageInputStream.class to indicate that they accept only an ImageInputStream.
The default implementation checks the input argument against the list returned by originatingProvider.getInputTypes() and fails if the argument is not an instance of one of the classes in the list. If the originating provider is set to null, the input is accepted only if it is an ImageInputStream.
public void setInput(Object input, boolean seekForwardOnly)
The seekForwardOnly parameter controls whether the value returned by getMinIndex will be increased as each image (or thumbnail, or image metadata) is read. If seekForwardOnly is true, then a call to read(index) will throw an IndexOutOfBoundsException if index < this.minIndex; otherwise, the value of minIndex will be set to index. If seekForwardOnly is false, the value of minIndex will remain 0 regardless of any read operations.
This method is equivalent to setInput(input, seekForwardOnly, false).
public void setInput(Object input)
This method is equivalent to setInput(input, false, false).
public Object getInput()
public boolean isSeekForwardOnly()
public boolean isIgnoringMetadata()
public int getMinIndex()
public Locale[] getAvailableLocales()
The default implementation returns a clone of the availableLocales instance variable if it is non-null, or else returns null.
public void setLocale(Locale locale)
public Locale getLocale()
public abstract int getNumImages(boolean allowSearch) throws IOException
Note that some image formats (such as animated GIF) do not specify how many images are present in the stream. Thus determining the number of images will require the entire stream to be scanned and may require memory for buffering. If images are to be processed in order, it may be more efficient to simply call read with increasing indices until an IndexOutOfBoundsException is thrown to indicate that no more images are available. The allowSearch parameter may be set to false to indicate that an exhaustive search is not desired; the return value will be -1 to indicate that a search is necessary. If the input has been specified with seekForwardOnly set to true, this method throws an IllegalStateException if allowSearch is set to true.
public abstract int getWidth(int imageIndex) throws IOException
If the image can be rendered to a user-specified size, then this method returns the default width.
public abstract int getHeight(int imageIndex) throws IOException
If the image can be rendered to a user-specified size, then this method returns the default height.
public boolean isRandomAccessEasy(int imageIndex) throws IOException
This is merely a hint for programs that wish to be efficient; all readers must be able to read arbitrary regions as specified in an ImageReadParam.
Note that formats that return false from this method may nonetheless allow tiling ( e.g. Restart Markers in JPEG), and random access will likely be reasonably efficient on tiles. See isImageTiled .
A reader for which all images are guaranteed to support easy random access, or are guaranteed not to support easy random access, may return true or false respectively without accessing any image data. In such cases, it is not necessary to throw an exception even if no input source has been set or the image index is out of bounds.
The default implementation returns false.
public float getAspectRatio(int imageIndex) throws IOException
The default implementation simply returns (float)getWidth(imageIndex)/getHeight(imageIndex).
public ImageTypeSpecifier getRawImageType(int imageIndex) throws IOException
The default implementation simply returns the first entry from the list provided by getImageType.
public abstract Iterator getImageTypes(int imageIndex) throws IOException
The first element of the iterator should be the most "natural" type for decoding the image with as little loss as possible. For example, for a JPEG image the first entry should be an RGB image, even though the image data is stored internally in a YCbCr color space.
public ImageReadParam getDefaultReadParam()
The default implementation constructs and returns a new ImageReadParam object that does not allow source scaling ( i.e. , it returns new ImageReadParam().
public abstract IIOMetadata getStreamMetadata() throws IOException
public IIOMetadata getStreamMetadata(String formatName, Set nodeNames) throws IOException
The resuting metadata object is only responsible for returning documents in the format named by formatName. Within any documents that are returned, only nodes whose names are members of nodeNames are required to be returned. In this way, the amount of metadata processing done by the reader may be kept to a minimum, based on what information is actually needed.
If formatName is not the name of a supported metadata format, null is returned.
In all cases, it is legal to return a more capable metadata object than strictly necessary. The format name and node names are merely hints that may be used to reduce the reader's workload.
The default implementation simply returns the result of calling getStreamMetadata(), after checking that the format name is supported. If it is not, null is returned.
public abstract IIOMetadata getImageMetadata(int imageIndex) throws IOException
public IIOMetadata getImageMetadata(int imageIndex, String formatName, Set nodeNames) throws IOException
The resuting metadata object is only responsible for returning documents in the format named by formatName. Within any documents that are returned, only nodes whose names are members of nodeNames are required to be returned. In this way, the amount of metadata processing done by the reader may be kept to a minimum, based on what information is actually needed.
If formatName is not the name of a supported metadata format, null may be returned.
In all cases, it is legal to return a more capable metadata object than strictly necessary. The format name and node names are merely hints that may be used to reduce the reader's workload.
The default implementation simply returns the result of calling getImageMetadata(imageIndex), after checking that the format name is supported. If it is not, null is returned.
public BufferedImage read(int imageIndex) throws IOException
The image returned will be formatted according to the first ImageTypeSpecifier returned from getImageTypes.
Any registered IIOReadProgressListener objects will be notified by calling their imageStarted method, followed by calls to their imageProgress method as the read progresses. Finally their imageComplete method will be called. IIOReadUpdateListener objects may be updated at other times during the read as pixels are decoded. Finally, IIOReadWarningListener objects will receive notification of any non-fatal warnings that occur during decoding.
public abstract BufferedImage read(int imageIndex, ImageReadParam param) throws IOException
The actual BufferedImage returned will be chosen using the algorithm defined by the getDestination method.
Any registered IIOReadProgressListener objects will be notified by calling their imageStarted method, followed by calls to their imageProgress method as the read progresses. Finally their imageComplete method will be called. IIOReadUpdateListener objects may be updated at other times during the read as pixels are decoded. Finally, IIOReadWarningListener objects will receive notification of any non-fatal warnings that occur during decoding.
The set of source bands to be read and destination bands to be written is determined by calling getSourceBands and getDestinationBands on the supplied ImageReadParam. If the lengths of the arrays returned by these methods differ, the set of source bands contains an index larger that the largest available source index, or the set of destination bands contains an index larger than the largest legal destination index, an IllegalArgumentException is thrown.
If the supplied ImageReadParam contains optional setting values not supported by this
reader (
e.g.
source render size or any format-specific settings),
reader,
they will be ignored.
public IIOImage readAll(int imageIndex, ImageReadParam param) throws IOException
The actual BufferedImage referenced by the returned IIOImage will be chosen using the algorithm defined by the getDestination method.
Any registered IIOReadProgressListener objects will be notified by calling their imageStarted method, followed by calls to their imageProgress method as the read progresses. Finally their imageComplete method will be called. IIOReadUpdateListener objects may be updated at other times during the read as pixels are decoded. Finally, IIOReadWarningListener objects will receive notification of any non-fatal warnings that occur during decoding.
The set of source bands to be read and destination bands to be written is determined by calling getSourceBands and getDestinationBands on the supplied ImageReadParam. If the lengths of the arrays returned by these methods differ, the set of source bands contains an index larger that the largest available source index, or the set of destination bands contains an index larger than the largest legal destination index, an IllegalArgumentException is thrown.
Thumbnails will be returned in their entirety regardless of the region settings.
If the supplied ImageReadParam contains optional setting values not supported by this
reader (
e.g.
source render size or any format-specific settings),
reader,
those values will be ignored.
public Iterator readAll(Iterator params) throws IOException
If params is null, a default read param will be used for all images.
The actual BufferedImage referenced by the returned IIOImage will be chosen using the algorithm defined by the getDestination method.
Any registered IIOReadProgressListener objects will be notified by calling their sequenceStarted method once. Then, for each image decoded, there will be a call to imageStarted, followed by calls to imageProgress as the read progresses, and finally to imageComplete. The sequenceComplete method will be called after the last image has been decoded. IIOReadUpdateListener objects may be updated at other times during the read as pixels are decoded. Finally, IIOReadWarningListener objects will receive notification of any non-fatal warnings that occur during decoding.
The set of source bands to be read and destination bands to be written is determined by calling getSourceBands and getDestinationBands on the supplied ImageReadParam. If the lengths of the arrays returned by these methods differ, the set of source bands contains an index larger that the largest available source index, or the set of destination bands contains an index larger than the largest legal destination index, an IllegalArgumentException is thrown.
Thumbnails will be returned in their entirety regardless of the region settings.
If any of the supplied ImageReadParams contain optional setting values not supported by this
reader (
e.g.
source render size or any format-specific settings),
reader,
they will be ignored.
public boolean canReadRaster()
The default implementation returns false.
public Raster readRaster(int imageIndex, ImageReadParam param) throws IOException
This method allows formats that normally apply a color conversion, such as JPEG, and formats that do not normally have an associated colorspace, such as remote sensing or medical imaging data, to provide access to raw pixel data.
Any registered readUpdateListeners are ignored, as there is no BufferedImage, but all other listeners are called exactly as they are for the read method.
If canReadRaster() returns false, this method throws an UnsupportedOperationException.
If the supplied ImageReadParam contains optional setting values not supported by this
reader (
e.g.
source render size or any format-specific settings),
reader,
they will be ignored.
The default implementation throws an UnsupportedOperationException.
public boolean isImageTiled(int imageIndex) throws IOException
A reader plug-in may choose whether or not to expose tiling that is present in the image as it is stored. It may even choose to advertise tiling when none is explicitly present. In general, tiling should only be advertised if there is some advantage (in speed or space) to accessing individual tiles. Regardless of whether the reader advertises tiling, it must be capable of reading an arbitrary rectangular region specified in an ImageReadParam.
A reader for which all images are guaranteed to be tiled, or are guaranteed not to be tiled, may return true or false respectively without accessing any image data. In such cases, it is not necessary to throw an exception even if no input source has been set or the image index is out of bounds.
The default implementation just returns false.
public int getTileWidth(int imageIndex) throws IOException
The default implementation simply returns getWidth(imageIndex), which is correct for non-tiled images. Readers that support tiling should override this method.
public int getTileHeight(int imageIndex) throws IOException
The default implementation simply returns getHeight(imageIndex), which is correct for non-tiled images. Readers that support tiling should override this method.
public int getTileGridXOffset(int imageIndex) throws IOException
A reader for which the tile grid X offset always has the same value (usually 0), may return the value without accessing any image data. In such cases, it is not necessary to throw an exception even if no input source has been set or the image index is out of bounds.
The default implementation simply returns 0, which is correct for non-tiled images and tiled images in most formats. Readers that support tiling with non-(0, 0) offsets should override this method.
public int getTileGridYOffset(int imageIndex) throws IOException
A reader for which the tile grid Y offset always has the same value (usually 0), may return the value without accessing any image data. In such cases, it is not necessary to throw an exception even if no input source has been set or the image index is out of bounds.
The default implementation simply returns 0, which is correct for non-tiled images and tiled images in most formats. Readers that support tiling with non-(0, 0) offsets should override this method.
public BufferedImage readTile(int imageIndex, int tileX, int tileY) throws IOException
This method is merely a convenience equivalent to calling read(int, ImageReadParam) with a read param specifiying a source region having offsets of tileX*getTileWidth(imageIndex), tileY*getTileHeight(imageIndex) and width and height of getTileWidth(imageIndex), getTileHeight(imageIndex); and subsampling factors of 1 and offsets of 0. To subsample a tile, call read with a read param specifying this region and different subsampling parameters.
The default implementation returns the entire image if tileX and tileY are 0, or throws an IllegalArgumentException otherwise.
public Raster readTileRaster(int imageIndex, int tileX, int tileY) throws IOException
If canReadRaster() returns false, this method throws an UnsupportedOperationException.
The default implementation checks if reading Rasters is supported, and if so calls readRaster(imageIndex, null) if tileX and tileY are 0, or throws an IllegalArgumentException otherwise.
public RenderedImage readAsRenderedImage(int imageIndex, ImageReadParam param) throws IOException
The semantics of this method may differ from those of the other read methods in several ways. First, any destination image and/or image type set in the ImageReadParam may be ignored. Second, the usual listener calls are not guaranteed to be made, or to be meaningful if they are. This is because the returned image may not be fully populated with pixel data at the time it is returned, or indeed at any time.
If the supplied ImageReadParam contains optional setting values not supported by this
reader (
e.g.
source render size or any format-specific settings),
reader,
they will be ignored.
The default implementation just calls read(imageIndex, param) .
public boolean readerSupportsThumbnails()
If this method returns false, hasThumbnails and getNumThumbnails will return false and 0, respectively, and readThumbnail will throw an UnsupportedOperationException, regardless of their arguments.
A reader that does not support thumbnails need not implement any of the thumbnail-related methods.
public boolean hasThumbnails(int imageIndex) throws IOException
The default implementation returns true if getNumThumbnails returns a value greater than 0.
public int getNumThumbnails(int imageIndex) throws IOException
The default implementation returns 0 without checking its argument.
public int getThumbnailWidth(int imageIndex, int thumbnailIndex) throws IOException
If the reader does not support thumbnails, (readerSupportsThumbnails returns false), an UnsupportedOperationException will be thrown.
The default implementation simply returns readThumbnail(imageindex, thumbnailIndex).getWidth(). Subclasses should therefore override this method if possible in order to avoid forcing the thumbnail to be read.
public int getThumbnailHeight(int imageIndex, int thumbnailIndex) throws IOException
If the reader does not support thumbnails, (readerSupportsThumbnails returns false), an UnsupportedOperationException will be thrown.
The default implementation simply returns readThumbnail(imageindex, thumbnailIndex).getHeight(). Subclasses should therefore override this method if possible in order to avoid forcing the thumbnail to be read.
public BufferedImage readThumbnail(int imageIndex, int thumbnailIndex) throws IOException
Any registered IIOReadProgressListener objects will be notified by calling their thumbnailStarted, thumbnailProgress, and thumbnailComplete methods.
If the reader does not support thumbnails, (readerSupportsThumbnails returns false), an UnsupportedOperationException will be thrown regardless of whether an input source has been set or whether the indices are in bounds.
The default implementation throws an UnsupportedOperationException.
public void abort()
Readers should call clearAbortRequest at the beginning of each read operation, and poll the value of abortRequested regularly during the read.
protected boolean abortRequested()
protected void clearAbortRequest()
public void addIIOReadWarningListener(IIOReadWarningListener listener)
public void removeIIOReadWarningListener(IIOReadWarningListener listener)
public void removeAllIIOReadWarningListeners()
The default implementation sets the warningListeners and warningLocales instance variables to null.
public void addIIOReadProgressListener(IIOReadProgressListener listener)
public void removeIIOReadProgressListener(IIOReadProgressListener listener)
public void removeAllIIOReadProgressListeners()
The default implementation sets the progressListeners instance variable to null.
public void addIIOReadUpdateListener(IIOReadUpdateListener listener)
If no update listeners are present, the reader may choose to perform fewer updates to the pixels of the destination images and/or thumbnails, which may result in more efficient decoding.
For example, in progressive JPEG decoding each pass contains updates to a set of coefficients, which would have to be transformed into pixel values and converted to an RGB color space for each pass if listeners are present. If no listeners are present, the coefficients may simply be accumulated and the final results transformed and color converted one time only.
The final results of decoding will be the same whether or not intermediate updates are performed. Thus if only the final image is desired it may be perferable not to register any IIOReadUpdateListeners. In general, progressive updating is most effective when fetching images over a network connection that is very slow compared to local CPU processing; over a fast connection, progressive updates may actually slow down the presentation of the image.
public void removeIIOReadUpdateListener(IIOReadUpdateListener listener)
public void removeAllIIOReadUpdateListeners()
The default implementation sets the updateListeners instance variable to null.
protected void processSequenceStarted(int minIndex)
protected void processSequenceComplete()
protected void processImageStarted(int imageIndex)
protected void processImageProgress(float percentageDone)
protected void processImageComplete()
protected void processThumbnailStarted(int imageIndex, int thumbnailIndex)
protected void processThumbnailProgress(float percentageDone)
protected void processThumbnailComplete()
protected void processReadAborted()
protected void processPassStarted(BufferedImage theImage, int pass, int minPass, int maxPass, int minX, int minY, int periodX, int periodY, int[] bands)
protected void processImageUpdate(BufferedImage theImage, int minX, int minY, int width, int height, int periodX, int periodY, int[] bands)
protected void processPassComplete(BufferedImage theImage)
protected void processThumbnailPassStarted(BufferedImage theThumbnail, int pass, int minPass, int maxPass, int minX, int minY, int periodX, int periodY, int[] bands)
protected void processThumbnailUpdate(BufferedImage theThumbnail, int minX, int minY, int width, int height, int periodX, int periodY, int[] bands)
protected void processThumbnailPassComplete(BufferedImage theThumbnail)
protected void processWarningOccurred(String warning)
protected void processWarningOccurred(String baseName, String keyword)
public void reset()
The default implementation calls setInput(null, false), setLocale(null), removeAllIIOReadUpdateListeners(), removeAllIIOReadWarningListeners(), removeAllIIOReadProgressListeners(), and clearAbortRequest.
public void dispose()
It is important for applications to call this method when they know they will no longer be using this ImageReader. Otherwise, the reader may continue to hold on to resources indefinitely.
The default implementation of this method in the superclass does nothing. Subclass implementations should ensure that all resources, especially native resources, are released.
protected static Rectangle getSourceRegion(ImageReadParam param, int srcWidth, int srcHeight)
protected static void computeRegions(ImageReadParam param, int srcWidth, int srcHeight, BufferedImage image, Rectangle srcRegion, Rectangle destRegion)
If either of the destination offsets are negative, the source region is clipped so that its top left will coincide with the top left of the destination image, taking subsampling into account. Then the result is clipped to the destination image on the right and bottom, if one is specified, taking subsampling and destination offsets into account.
Similarly, the destination region begins with the source image, is translated to the destination offset given in the ImageReadParam if there is one, and finally is clipped to the destination image, if there is one.
If either the source or destination regions end up having a width or height of 0, an IllegalArgumentException is thrown.
The getSourceRegion method may be used if only source clipping is desired.
protected static void checkReadParamBandSettings(ImageReadParam param, int numSrcBands, int numDstBands)
The method retrieves the source and destination band setting arrays from param using the getSourceBands and getDestinationBandsmethods (or considers them to be null if param is null). If the source band setting array is null, it is considered to be equal to the array { 0, 1, ..., numSrcBands - 1 }, and similarly for the destination band setting array.
The method then tests that both arrays are equal in length, and that neither array contains a value larger than the largest available band index.
Any failure results in an IllegalArgumentException being thrown; success results in the method returning silently.
protected static BufferedImage getDestination(ImageReadParam param, Iterator imageTypes, int width, int height) throws IIOException
If param is null or the above steps have not yielded an image or an ImageTypeSpecifier, the first value obtained from the imageTypes parameter is used. Typically, the caller will set imageTypes to the value of getImageTypes(imageIndex).
Next, the dimensions of the image are determined by a call to computeRegions. The actual width and height of the image being decoded are passed in as the width and height parameters.