|
Préférences
Moteurs de recherche
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
JavaTM 2 Platform Std. Ed. v1.5.0
javax.imageio
|
Field Summary | |
---|---|
protected Locale[] |
availableLocales
An array of Locale s 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<IIOReadProgressListener> |
progressListeners
A List of currently registered
IIOReadProgressListener s, 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<IIOReadUpdateListener> |
updateListeners
A List of currently registered
IIOReadUpdateListener s, initialized by default to
null , which is synonymous with an empty
List . |
protected List<IIOReadWarningListener> |
warningListeners
A List of currently registered
IIOReadWarningListener s, initialized by default to
null , which is synonymous with an empty
List . |
protected List<Locale> |
warningLocales
A List of the Locale s 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 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 Locale s 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<ImageTypeSpecifier> 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<String> 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<ImageTypeSpecifier> |
getImageTypes(int imageIndex)
Returns an Iterator containing possible image
types to which the given image may be decoded, in the form of
ImageTypeSpecifiers s. |
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<String> 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 IIOReadProgressListener s by calling their
imageComplete method. |
protected void |
processImageProgress(float percentageDone)
Broadcasts the current percentage of image completion to all registered IIOReadProgressListener s by calling
their imageProgress method. |
protected void |
processImageStarted(int imageIndex)
Broadcasts the start of an image read to all registered IIOReadProgressListener s 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 IIOReadUpdateListener s by calling their
imageUpdate method. |
protected void |
processPassComplete(BufferedImage theImage)
Broadcasts the end of a progressive pass to all registered IIOReadUpdateListener s 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 IIOReadUpdateListener s by calling their
passStarted method. |
protected void |
processReadAborted()
Broadcasts that the read has been aborted to all registered IIOReadProgressListener s by calling their
readAborted method. |
protected void |
processSequenceComplete()
Broadcasts the completion of an sequence of image reads to all registered IIOReadProgressListener s by calling
their sequenceComplete method. |
protected void |
processSequenceStarted(int minIndex)
Broadcasts the start of an sequence of image reads to all registered IIOReadProgressListener s by calling
their sequenceStarted method. |
protected void |
processThumbnailComplete()
Broadcasts the completion of a thumbnail read to all registered IIOReadProgressListener s by calling their
thumbnailComplete method. |
protected void |
processThumbnailPassComplete(BufferedImage theThumbnail)
Broadcasts the end of a thumbnail progressive pass to all registered IIOReadUpdateListener s 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 IIOReadUpdateListener s by calling their
thumbnailPassStarted method. |
protected void |
processThumbnailProgress(float percentageDone)
Broadcasts the current percentage of thumbnail completion to all registered IIOReadProgressListener s by calling
their thumbnailProgress method. |
protected void |
processThumbnailStarted(int imageIndex,
int thumbnailIndex)
Broadcasts the start of a thumbnail read to all registered IIOReadProgressListener s 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 IIOReadUpdateListener s by
calling their thumbnailUpdate method. |
protected void |
processWarningOccurred(String warning)
Broadcasts a warning message to all registered IIOReadWarningListener s by calling their
warningOccurred method. |
protected void |
processWarningOccurred(String baseName,
String keyword)
Broadcasts a localized warning message to all registered IIOReadWarningListener s 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<IIOImage> |
readAll(Iterator<? extends ImageReadParam> 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
ImageReaderSpi
that instantiated this object,
or null
if its identity is not known or none
exists. By default it is initialized to null
.
protected Object input
ImageInputStream
or other
Object
by setInput
and retrieved
by getInput
. By default it is initialized to
null
.
protected boolean seekForwardOnly
true
if the current input source has been marked
as allowing only forward seeking by setInput
. By
default, the value is false
.
protected boolean ignoreMetadata
true
if the current input source has been marked
as allowing metadata to be ignored by setInput
.
By default, the value is false
.
protected int minIndex
seekForwardOnly
is true
, various methods
may throw an IndexOutOfBoundsException
on an
attempt to access data associate with an image having a lower
index.
protected Locale[] availableLocales
Locale
s which may be used to localize
warning messages, or null
if localization is not
supported.
protected Locale locale
Locale
to be used for localization, or
null
if none has been set.
protected List<IIOReadWarningListener> warningListeners
List
of currently registered
IIOReadWarningListener
s, initialized by default to
null
, which is synonymous with an empty
List
.
protected List<Locale> warningLocales
List
of the Locale
s associated with
each currently registered IIOReadWarningListener
,
initialized by default to null
, which is
synonymous with an empty List
.
protected List<IIOReadProgressListener> progressListeners
List
of currently registered
IIOReadProgressListener
s, initialized by default
to null
, which is synonymous with an empty
List
.
protected List<IIOReadUpdateListener> updateListeners
List
of currently registered
IIOReadUpdateListener
s, initialized by default to
null
, which is synonymous with an empty
List
.
Constructor Detail |
---|
protected ImageReader(ImageReaderSpi originatingProvider)
ImageReader
and sets its
originatingProvider
field to the supplied value.
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.
originatingProvider
- the ImageReaderSpi
that is
invoking this constructor, or null
.Method Detail |
---|
public String getFormatName() throws IOException
String
identifying the format of the
input source.
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.
String
.
IOException
- if an error occurs reading the
information from the input source.public ImageReaderSpi getOriginatingProvider()
ImageReaderSpi
that was passed in on
the constructor. Note that this value may be null
.
ImageReaderSpi
, or null
.ImageReaderSpi
public void setInput(Object input, boolean seekForwardOnly, boolean ignoreMetadata)
ImageInputStream
or other Object
.
The input source must be set before any of the query or read
methods are used. If input
is null
,
any currently set input source will be removed. In any case,
the value of minIndex
will be initialized to 0.
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
.
input
- the ImageInputStream
or other
Object
to use for future decoding.seekForwardOnly
- if true
, images and metadata
may only be read in ascending order from this input source.ignoreMetadata
- if true
, metadata
may be ignored during reads.
IllegalArgumentException
- if input
is
not an instance of one of the classes returned by the
originating service provider's getInputTypes
method, or is not an ImageInputStream
.ImageInputStream
,
getInput()
,
ImageReaderSpi.getInputTypes()
public void setInput(Object input, boolean seekForwardOnly)
ImageInputStream
or other Object
.
The input source must be set before any of the query or read
methods are used. If input
is null
,
any currently set input source will be removed. In any case,
the value of minIndex
will be initialized to 0.
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)
.
input
- the ImageInputStream
or other
Object
to use for future decoding.seekForwardOnly
- if true
, images and metadata
may only be read in ascending order from this input source.
IllegalArgumentException
- if input
is
not an instance of one of the classes returned by the
originating service provider's getInputTypes
method, or is not an ImageInputStream
.getInput()
public void setInput(Object input)
ImageInputStream
or other Object
.
The input source must be set before any of the query or read
methods are used. If input
is null
,
any currently set input source will be removed. In any case,
the value of minIndex
will be initialized to 0.
This method is equivalent to setInput(input, false,
false)
.
input
- the ImageInputStream
or other
Object
to use for future decoding.
IllegalArgumentException
- if input
is
not an instance of one of the classes returned by the
originating service provider's getInputTypes
method, or is not an ImageInputStream
.getInput()
public Object getInput()
ImageInputStream
or other
Object
previously set as the input source. If the
input source has not been set, null
is returned.
Object
that will be used for future
decoding, or null
.ImageInputStream
,
setInput(java.lang.Object, boolean, boolean)
public boolean isSeekForwardOnly()
true
if the current input source has been
marked as seek forward only by passing true
as the
seekForwardOnly
argument to the
setInput
method.
true
if the input source is seek forward
only.setInput(java.lang.Object, boolean, boolean)
public boolean isIgnoringMetadata()
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.
true
if the metadata may be ignored.setInput(java.lang.Object, boolean, boolean)
public int getMinIndex()
seekForwardOnly()
is
false
, this value will typically remain 0,
indicating that random access is possible. Otherwise, it will
contain the value of the most recently accessed index, and
increase in a monotonic fashion.
public Locale[] getAvailableLocales()
Locale
s that may be used to
localize warning listeners and compression settings. A return
value of null
indicates that localization is not
supported.
The default implementation returns a clone of the
availableLocales
instance variable if it is
non-null
, or else returns null
.
Locale
s that may be used as
arguments to setLocale
, or null
.public void setLocale(Locale locale)
Locale
of this
ImageReader
to the given value. A value of
null
removes any previous setting, and indicates
that the reader should localize as it sees fit.
locale
- the desired Locale
, or
null
.
IllegalArgumentException
- if locale
is
non-null
but is not one of the values returned by
getAvailableLocales
.getLocale()
public Locale getLocale()
Locale
, or
null
if none has been set.
Locale
, or null
.setLocale(java.util.Locale)
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
.
allowSearch
- if true
, the true number of
images will be returned even if a search is required. If
false
, the reader may return -1
without performing the search.
int
, or
-1
if allowSearch
is
false
and a search would be required.
IllegalStateException
- if the input source has not been set,
or if the input has been specified with seekForwardOnly
set to true
.
IOException
- if an error occurs reading the
information from the input source.setInput(java.lang.Object, boolean, boolean)
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.
imageIndex
- the index of the image to be queried.
int
.
IllegalStateException
- if the input source has not been set.
IndexOutOfBoundsException
- if the supplied index is
out of bounds.
IOException
- if an error occurs reading the width
information from the input source.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.
imageIndex
- the index of the image to be queried.
int
.
IllegalStateException
- if the input source has not been set.
IndexOutOfBoundsException
- if the supplied index is
out of bounds.
IOException
- if an error occurs reading the height
information from the input source.public boolean isRandomAccessEasy(int imageIndex) throws IOException
true
if the storage format of the given
image places no inherent impediment on random access to pixels.
For most compressed formats, such as JPEG, this method should
return false
, as a large section of the image in
addition to the region of interest may need to be decoded.
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
.
imageIndex
- the index of the image to be queried.
true
if reading a region of interest of
the given image is likely to be efficient.
IllegalStateException
- if an input source is required
to determine the return value, but none has been set.
IndexOutOfBoundsException
- if an image must be
accessed to determine the return value, but the supplied index
is out of bounds.
IOException
- if an error occurs during reading.public float getAspectRatio(int imageIndex) throws IOException
float
. For images
that are inherently resizable, this method provides a way to
determine the appropriate width given a deired height, or vice
versa. For non-resizable images, the true width and height
are used.
The default implementation simply returns
(float)getWidth(imageIndex)/getHeight(imageIndex)
.
imageIndex
- the index of the image to be queried.
float
indicating the aspect ratio of the
given image.
IllegalStateException
- if the input source has not been set.
IndexOutOfBoundsException
- if the supplied index is
out of bounds.
IOException
- if an error occurs during reading.public ImageTypeSpecifier getRawImageType(int imageIndex) throws IOException
ImageTypeSpecifier
indicating the
SampleModel
and ColorModel
which most
closely represents the "raw" internal format of the image. For
example, for a JPEG image the raw type might have a YCbCr color
space even though the image would conventionally be transformed
into an RGB color space prior to display. The returned value
should also be included in the list of values returned by
getImageTypes
.
The default implementation simply returns the first entry
from the list provided by getImageType
.
imageIndex
- the index of the image to be queried.
ImageTypeSpecifier
.
IllegalStateException
- if the input source has not been set.
IndexOutOfBoundsException
- if the supplied index is
out of bounds.
IOException
- if an error occurs reading the format
information from the input source.public abstract Iterator<ImageTypeSpecifier> getImageTypes(int imageIndex) throws IOException
Iterator
containing possible image
types to which the given image may be decoded, in the form of
ImageTypeSpecifiers
s. At least one legal image
type will be returned.
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.
imageIndex
- the index of the image to be
retrieved
.
Iterator
containing at least one
ImageTypeSpecifier
representing suggested image
types for decoding the current given image.
IllegalStateException
- if the input source has not been set.
IndexOutOfBoundsException
- if the supplied index is
out of bounds.
IOException
- if an error occurs reading the format
information from the input source.ImageReadParam.setDestination(BufferedImage)
,
ImageReadParam.setDestinationType(ImageTypeSpecifier)
public ImageReadParam getDefaultReadParam()
ImageReadParam
object
appropriate for this format. All subclasses should define a
set of default values for all parameters and return them with
this call. This method may be called before the input source
is set.
The default implementation constructs and returns a new
ImageReadParam
object that does not allow source
scaling (i.e., it returns new
ImageReadParam()
.
ImageReadParam
object which may be used
to control the decoding process using a set of default settings.public abstract IIOMetadata getStreamMetadata() throws IOException
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
object, or null
.
IOException
- if an error occurs during reading.public IIOMetadata getStreamMetadata(String formatName, Set<String> nodeNames) throws IOException
IIOMetadata
object representing the
metadata associated with the input source as a whole (i.e.,
not associated with any particular image). If no such data
exists, null
is returned.
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.
formatName
- a metadata format name that may be used to retrieve
a document from the returned IIOMetadata
object.nodeNames
- a Set
containing the names of
nodes that may be contained in a retrieved document.
IIOMetadata
object, or null
.
IllegalArgumentException
- if formatName
is null
.
IllegalArgumentException
- if nodeNames
is null
.
IOException
- if an error occurs during reading.public abstract IIOMetadata getImageMetadata(int imageIndex) throws IOException
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.
imageIndex
- the index of the image whose metadata is to
be retrieved.
IIOMetadata
object, or
null
.
IllegalStateException
- if the input source has not been
set.
IndexOutOfBoundsException
- if the supplied index is
out of bounds.
IOException
- if an error occurs during reading.public IIOMetadata getImageMetadata(int imageIndex, String formatName, Set<String> nodeNames) throws IOException
IIOMetadata
object representing the
metadata associated with the given image, or null
if the reader does not support reading metadata or none
is available.
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.
imageIndex
- the index of the image whose metadata is to
be retrieved.formatName
- a metadata format name that may be used to retrieve
a document from the returned IIOMetadata
object.nodeNames
- a Set
containing the names of
nodes that may be contained in a retrieved document.
IIOMetadata
object, or null
.
IllegalStateException
- if the input source has not been
set.
IndexOutOfBoundsException
- if the supplied index is
out of bounds.
IllegalArgumentException
- if formatName
is null
.
IllegalArgumentException
- if nodeNames
is null
.
IOException
- if an error occurs during reading.public BufferedImage read(int imageIndex) throws IOException
imageIndex
and returns
it as a complete BufferedImage
, using a default
ImageReadParam
. This is a convenience method
that calls read(imageIndex, null)
.
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.
imageIndex
- the index of the image to be retrieved.
BufferedImage
.
IllegalStateException
- if the input source has not been
set.
IndexOutOfBoundsException
- if the supplied index is
out of bounds.
IOException
- if an error occurs during reading.public abstract BufferedImage read(int imageIndex, ImageReadParam param) throws IOException
imageIndex
and returns
it as a complete BufferedImage
, using a supplied
ImageReadParam
.
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), they will
be ignored.
imageIndex
- the index of the image to be retrieved.param
- an ImageReadParam
used to control
the reading process, or null
.
BufferedImage
.
IllegalStateException
- if the input source has not been
set.
IndexOutOfBoundsException
- if the supplied index is
out of bounds.
IllegalArgumentException
- if the set of source and
destination bands specified by
param.getSourceBands
and
param.getDestinationBands
differ in length or
include indices that are out of bounds.
IllegalArgumentException
- if the resulting image would
have a width or height less than 1.
IOException
- if an error occurs during reading.public IIOImage readAll(int imageIndex, ImageReadParam param) throws IOException
imageIndex
and returns
an IIOImage
containing the image, thumbnails, and
associated image metadata, using a supplied
ImageReadParam
.
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), those
values will be ignored.
imageIndex
- the index of the image to be retrieved.param
- an ImageReadParam
used to control
the reading process, or null
.
IIOImage
containing the desired portion
of the image, a set of thumbnails, and associated image
metadata.
IllegalStateException
- if the input source has not been
set.
IndexOutOfBoundsException
- if the supplied index is
out of bounds.
IllegalArgumentException
- if the set of source and
destination bands specified by
param.getSourceBands
and
param.getDestinationBands
differ in length or
include indices that are out of bounds.
IllegalArgumentException
- if the resulting image
would have a width or height less than 1.
IOException
- if an error occurs during reading.public Iterator<IIOImage> readAll(Iterator<? extends ImageReadParam> params) throws IOException
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. An Iterator
containing ImageReadParam
objects is supplied; one
element is consumed for each image read from the input source
until no more images are available. If the read param
Iterator
runs out of elements, but there are still
more images available from the input source, default read
params are used for the remaining images.
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 ImageReadParam
s contain
optional setting values not supported by this reader (e.g.
source render size or any format-specific settings), they will
be ignored.
params
- an Iterator
containing
ImageReadParam
objects.
Iterator
representing the
contents of the input source as IIOImage
s.
IllegalStateException
- if the input source has not been
set.
IllegalArgumentException
- if any
non-null
element of params
is not an
ImageReadParam
.
IllegalArgumentException
- if the set of source and
destination bands specified by
param.getSourceBands
and
param.getDestinationBands
differ in length or
include indices that are out of bounds.
IllegalArgumentException
- if a resulting image would
have a width or height less than 1.
IOException
- if an error occurs during reading.ImageReadParam
,
IIOImage
public boolean canReadRaster()
true
if this plug-in supports reading
just a Raster
of pixel data.
If this method returns false
, calls to
readRaster
or readTileRaster
will throw an
UnsupportedOperationException
.
The default implementation returns false
.
true
if this plug-in supports reading raw
Raster
s.readRaster(int, javax.imageio.ImageReadParam)
,
readTileRaster(int, int, int)
public Raster readRaster(int imageIndex, ImageReadParam param) throws IOException
Raster
object containing the raw pixel data
from the image stream, without any color conversion applied. The
application must determine how to interpret the pixel data by other
means. Any destination or image-type parameters in the supplied
ImageReadParam
object are ignored, but all other
parameters are used exactly as in the read
method, except that any destination offset is used as a logical rather
than a physical offset. The size of the returned Raster
will always be that of the source region clipped to the actual image.
Logical offsets in the stream itself are ignored.
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 readUpdateListener
s are ignored, as
there is no BufferedImage
, but all other listeners are
called exactly as they are for the
method.
read
If
returns
canReadRaster()
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), they will
be ignored.
The default implementation throws an
UnsupportedOperationException
.
imageIndex
- the index of the image to be read.param
- an ImageReadParam
used to control
the reading process, or null
.
Raster
.
UnsupportedOperationException
- if this plug-in does not
support reading raw Raster
s.
IllegalStateException
- if the input source has not been
set.
IndexOutOfBoundsException
- if the supplied index is
out of bounds.
IOException
- if an error occurs during reading.canReadRaster()
,
read(int)
,
Raster
public boolean isImageTiled(int imageIndex) throws IOException
true
if the image is organized into
tiles, that is, equal-sized non-overlapping rectangles.
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
.
imageIndex
- the index of the image to be queried.
true
if the image is tiled.
IllegalStateException
- if an input source is required
to determine the return value, but none has been set.
IndexOutOfBoundsException
- if an image must be
accessed to determine the return value, but the supplied index
is out of bounds.
IOException
- if an error occurs during reading.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.
imageIndex
- the index of the image to be queried.
IllegalStateException
- if the input source has not been set.
IndexOutOfBoundsException
- if the supplied index is
out of bounds.
IOException
- if an error occurs during reading.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.
imageIndex
- the index of the image to be queried.
IllegalStateException
- if the input source has not been set.
IndexOutOfBoundsException
- if the supplied index is
out of bounds.
IOException
- if an error occurs during reading.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.
imageIndex
- the index of the image to be queried.
IllegalStateException
- if an input source is required
to determine the return value, but none has been set.
IndexOutOfBoundsException
- if an image must be
accessed to determine the return value, but the supplied index
is out of bounds.
IOException
- if an error occurs during reading.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.
imageIndex
- the index of the image to be queried.
IllegalStateException
- if an input source is required
to determine the return value, but none has been set.
IndexOutOfBoundsException
- if an image must be
accessed to determine the return value, but the supplied index
is out of bounds.
IOException
- if an error occurs during reading.public BufferedImage readTile(int imageIndex, int tileX, int tileY) throws IOException
tileX
and
tileY
arguments, returning it as a
BufferedImage
. If the arguments are out of range,
an IllegalArgumentException
is thrown. If the
image is not tiled, the values 0, 0 will return the entire
image; any other values will cause an
IllegalArgumentException
to be thrown.
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.
imageIndex
- the index of the image to be retrieved.tileX
- the column index (starting with 0) of the tile
to be retrieved.tileY
- the row index (starting with 0) of the tile
to be retrieved.
BufferedImage
.
IllegalStateException
- if the input source has not been
set.
IndexOutOfBoundsException
- if imageIndex
is out of bounds.
IllegalArgumentException
- if the tile indices are
out of bounds.
IOException
- if an error occurs during reading.public Raster readTileRaster(int imageIndex, int tileX, int tileY) throws IOException
Raster
object containing the raw
pixel data from the tile, without any color conversion applied.
The application must determine how to interpret the pixel data by other
means.
If
returns
canReadRaster()
false
, this method throws an
UnsupportedOperationException
.
The default implementation checks if reading
Raster
s is supported, and if so calls
if
readRaster(imageIndex, null)
tileX
and tileY
are 0, or throws an
IllegalArgumentException
otherwise.
imageIndex
- the index of the image to be retrieved.tileX
- the column index (starting with 0) of the tile
to be retrieved.tileY
- the row index (starting with 0) of the tile
to be retrieved.
Raster
.
UnsupportedOperationException
- if this plug-in does not
support reading raw Raster
s.
IllegalArgumentException
- if the tile indices are
out of bounds.
IllegalStateException
- if the input source has not been
set.
IndexOutOfBoundsException
- if imageIndex
is out of bounds.
IOException
- if an error occurs during reading.readTile(int, int, int)
,
readRaster(int, javax.imageio.ImageReadParam)
,
Raster
public RenderedImage readAsRenderedImage(int imageIndex, ImageReadParam param) throws IOException
RenderedImage
object that contains the
contents of the image indexed by imageIndex
. By
default, the returned image is simply the
BufferedImage
returned by read(imageIndex,
param)
.
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), they will
be ignored.
The default implementation just calls
.
read(imageIndex, param)
imageIndex
- the index of the image to be retrieved.param
- an ImageReadParam
used to control
the reading process, or null
.
RenderedImage
object providing a view of
the image.
IllegalStateException
- if the input source has not been
set.
IndexOutOfBoundsException
- if the supplied index is
out of bounds.
IllegalArgumentException
- if the set of source and
destination bands specified by
param.getSourceBands
and
param.getDestinationBands
differ in length or
include indices that are out of bounds.
IllegalArgumentException
- if the resulting image
would have a width or height less than 1.
IOException
- if an error occurs during reading.public boolean readerSupportsThumbnails()
true
if the image format understood by
this reader supports thumbnail preview images associated with
it. The default implementation returns false
.
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.
true
if thumbnails are supported.public boolean hasThumbnails(int imageIndex) throws IOException
true
if the given image has thumbnail
preview images associated with it. If the format does not
support thumbnails (readerSupportsThumbnails
returns false
), false
will be
returned regardless of whether an input source has been set or
whether imageIndex
is in bounds.
The default implementation returns true
if
getNumThumbnails
returns a value greater than 0.
imageIndex
- the index of the image being queried.
true
if the given image has thumbnails.
IllegalStateException
- if the reader supports
thumbnails but the input source has not been set.
IndexOutOfBoundsException
- if the reader supports
thumbnails but imageIndex
is out of bounds.
IOException
- if an error occurs during reading.public int getNumThumbnails(int imageIndex) throws IOException
readerSupportsThumbnails
returns
false
), 0
will be returned regardless
of whether an input source has been set or whether
imageIndex
is in bounds.
The default implementation returns 0 without checking its argument.
imageIndex
- the index of the image being queried.
IllegalStateException
- if the reader supports
thumbnails but the input source has not been set.
IndexOutOfBoundsException
- if the reader supports
thumbnails but imageIndex
is out of bounds.
IOException
- if an error occurs during reading.public int getThumbnailWidth(int imageIndex, int thumbnailIndex) throws IOException
thumbnailIndex
, associated with the image indexed
by ImageIndex
.
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.
imageIndex
- the index of the image to be retrieved.thumbnailIndex
- the index of the thumbnail to be retrieved.
int
.
UnsupportedOperationException
- if thumbnails are not
supported.
IllegalStateException
- if the input source has not been set.
IndexOutOfBoundsException
- if either of the supplied
indices are out of bounds.
IOException
- if an error occurs during reading.public int getThumbnailHeight(int imageIndex, int thumbnailIndex) throws IOException
thumbnailIndex
, associated with the image indexed
by ImageIndex
.
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.
imageIndex
- the index of the image to be retrieved.thumbnailIndex
- the index of the thumbnail to be retrieved.
int
.
UnsupportedOperationException
- if thumbnails are not
supported.
IllegalStateException
- if the input source has not been set.
IndexOutOfBoundsException
- if either of the supplied
indices are out of bounds.
IOException
- if an error occurs during reading.public BufferedImage readThumbnail(int imageIndex, int thumbnailIndex) throws IOException
thumbnailIndex
, associated with the image indexed
by ImageIndex
as a BufferedImage
.
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
.
imageIndex
- the index of the image to be retrieved.thumbnailIndex
- the index of the thumbnail to be retrieved.
BufferedImage
.
UnsupportedOperationException
- if thumbnails are not
supported.
IllegalStateException
- if the input source has not been set.
IndexOutOfBoundsException
- if either of the supplied
indices are out of bounds.
IOException
- if an error occurs during reading.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()
true
if a request to abort the current
read operation has been made since the reader was instantiated or
clearAbortRequest
was called.
true
if the current read operation should
be aborted.abort()
,
clearAbortRequest()
protected void clearAbortRequest()
abortRequested
will return
false
.
abort()
,
abortRequested()
public void addIIOReadWarningListener(IIOReadWarningListener listener)
IIOReadWarningListener
to the list of
registered warning listeners. If listener
is
null
, no exception will be thrown and no action
will be taken. Messages sent to the given listener will be
localized, if possible, to match the current
Locale
. If no Locale
has been set,
warning messages may be localized as the reader sees fit.
listener
- an IIOReadWarningListener
to be registered.removeIIOReadWarningListener(javax.imageio.event.IIOReadWarningListener)
public void removeIIOReadWarningListener(IIOReadWarningListener listener)
IIOReadWarningListener
from the list of
registered error listeners. If the listener was not previously
registered, or if listener
is null
,
no exception will be thrown and no action will be taken.
listener
- an IIOReadWarningListener to be unregistered.addIIOReadWarningListener(javax.imageio.event.IIOReadWarningListener)
public void removeAllIIOReadWarningListeners()
IIOReadWarningListener
objects.
The default implementation sets the
warningListeners
and warningLocales
instance variables to null
.
public void addIIOReadProgressListener(IIOReadProgressListener listener)
IIOReadProgressListener
to the list of
registered progress listeners. If listener
is
null
, no exception will be thrown and no action
will be taken.
listener
- an IIOReadProgressListener to be registered.removeIIOReadProgressListener(javax.imageio.event.IIOReadProgressListener)
public void removeIIOReadProgressListener(IIOReadProgressListener listener)
IIOReadProgressListener
from the list
of registered progress listeners. If the listener was not
previously registered, or if listener
is
null
, no exception will be thrown and no action
will be taken.
listener
- an IIOReadProgressListener to be unregistered.addIIOReadProgressListener(javax.imageio.event.IIOReadProgressListener)
public void removeAllIIOReadProgressListeners()
IIOReadProgressListener
objects.
The default implementation sets the
progressListeners
instance variable to
null
.
public void addIIOReadUpdateListener(IIOReadUpdateListener listener)
IIOReadUpdateListener
to the list of
registered update listeners. If listener
is
null
, no exception will be thrown and no action
will be taken. The listener will receive notification of pixel
updates as images and thumbnails are decoded, including the
starts and ends of progressive passes.
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
IIOReadUpdateListener
s. 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.
listener
- an IIOReadUpdateListener to be registered.removeIIOReadUpdateListener(javax.imageio.event.IIOReadUpdateListener)
public void removeIIOReadUpdateListener(IIOReadUpdateListener listener)
IIOReadUpdateListener
from the list of
registered update listeners. If the listener was not
previously registered, or if listener
is
null
, no exception will be thrown and no action
will be taken.
listener
- an IIOReadUpdateListener to be unregistered.addIIOReadUpdateListener(javax.imageio.event.IIOReadUpdateListener)
public void removeAllIIOReadUpdateListeners()
IIOReadUpdateListener
objects.
The default implementation sets the
updateListeners
instance variable to
null
.
protected void processSequenceStarted(int minIndex)
IIOReadProgressListener
s by calling
their sequenceStarted
method. Subclasses may use
this method as a convenience.
minIndex
- the lowest index being read.protected void processSequenceComplete()
IIOReadProgressListener
s by calling
their sequenceComplete
method. Subclasses may use
this method as a convenience.
protected void processImageStarted(int imageIndex)
IIOReadProgressListener
s by calling their
imageStarted
method. Subclasses may use this
method as a convenience.
imageIndex
- the index of the image about to be read.protected void processImageProgress(float percentageDone)
IIOReadProgressListener
s by calling
their imageProgress
method. Subclasses may use
this method as a convenience.
percentageDone
- the current percentage of completion,
as a float
.protected void processImageComplete()
IIOReadProgressListener
s by calling their
imageComplete
method. Subclasses may use this
method as a convenience.
protected void processThumbnailStarted(int imageIndex, int thumbnailIndex)
IIOReadProgressListener
s by calling their
thumbnailStarted
method. Subclasses may use this
method as a convenience.
imageIndex
- the index of the image associated with the
thumbnail.thumbnailIndex
- the index of the thumbnail.protected void processThumbnailProgress(float percentageDone)
IIOReadProgressListener
s by calling
their thumbnailProgress
method. Subclasses may
use this method as a convenience.
percentageDone
- the current percentage of completion,
as a float
.protected void processThumbnailComplete()
IIOReadProgressListener
s by calling their
thumbnailComplete
method. Subclasses may use this
method as a convenience.
protected void processReadAborted()
IIOReadProgressListener
s by calling their
readAborted
method. Subclasses may use this
method as a convenience.
protected void processPassStarted(BufferedImage theImage, int pass, int minPass, int maxPass, int minX, int minY, int periodX, int periodY, int[] bands)
IIOReadUpdateListener
s by calling their
passStarted
method. Subclasses may use this
method as a convenience.
theImage
- the BufferedImage
being updated.pass
- the index of the current pass, starting with 0.minPass
- the index of the first pass that will be decoded.maxPass
- the index of the last pass that will be decoded.minX
- the X coordinate of the upper-left pixel included
in the pass.minY
- the X coordinate of the upper-left pixel included
in the pass.periodX
- the horizontal separation between pixels.periodY
- the vertical separation between pixels.bands
- an array of int
s indicating the
set of affected bands of the destination.protected void processImageUpdate(BufferedImage theImage, int minX, int minY, int width, int height, int periodX, int periodY, int[] bands)
IIOReadUpdateListener
s by calling their
imageUpdate
method. Subclasses may use this
method as a convenience.
theImage
- the BufferedImage
being updated.minX
- the X coordinate of the upper-left pixel included
in the pass.minY
- the X coordinate of the upper-left pixel included
in the pass.width
- the total width of the area being updated, including
pixels being skipped if periodX > 1
.height
- the total height of the area being updated,
including pixels being skipped if periodY > 1
.periodX
- the horizontal separation between pixels.periodY
- the vertical separation between pixels.bands
- an array of int
s indicating the
set of affected bands of the destination.protected void processPassComplete(BufferedImage theImage)
IIOReadUpdateListener
s by calling their
passComplete
method. Subclasses may use this
method as a convenience.
theImage
- the BufferedImage
being updated.protected void processThumbnailPassStarted(BufferedImage theThumbnail, int pass, int minPass, int maxPass, int minX, int minY, int periodX, int periodY, int[] bands)
IIOReadUpdateListener
s by calling their
thumbnailPassStarted
method. Subclasses may use this
method as a convenience.
theThumbnail
- the BufferedImage
thumbnail
being updated.pass
- the index of the current pass, starting with 0.minPass
- the index of the first pass that will be decoded.maxPass
- the index of the last pass that will be decoded.minX
- the X coordinate of the upper-left pixel included
in the pass.minY
- the X coordinate of the upper-left pixel included
in the pass.periodX
- the horizontal separation between pixels.periodY
- the vertical separation between pixels.bands
- an array of int
s indicating the
set of affected bands of the destination.protected void processThumbnailUpdate(BufferedImage theThumbnail, int minX, int minY, int width, int height, int periodX, int periodY, int[] bands)
IIOReadUpdateListener
s by
calling their thumbnailUpdate
method. Subclasses may
use this method as a convenience.
theThumbnail
- the BufferedImage
thumbnail
being updated.minX
- the X coordinate of the upper-left pixel included
in the pass.minY
- the X coordinate of the upper-left pixel included
in the pass.width
- the total width of the area being updated, including
pixels being skipped if periodX > 1
.height
- the total height of the area being updated,
including pixels being skipped if periodY > 1
.periodX
- the horizontal separation between pixels.periodY
- the vertical separation between pixels.bands
- an array of int
s indicating the
set of affected bands of the destination.protected void processThumbnailPassComplete(BufferedImage theThumbnail)
IIOReadUpdateListener
s by calling their
thumbnailPassComplete
method. Subclasses may use this
method as a convenience.
theThumbnail
- the BufferedImage
thumbnail
being updated.protected void processWarningOccurred(String warning)
IIOReadWarningListener
s by calling their
warningOccurred
method. Subclasses may use this
method as a convenience.
warning
- the warning message to send.
IllegalArgumentException
- if warning
is null
.protected void processWarningOccurred(String baseName, String keyword)
IIOReadWarningListener
s by calling their
warningOccurred
method with a string taken
from a ResourceBundle
. Subclasses may use this
method as a convenience.
baseName
- the base name of a set of
ResourceBundle
s containing localized warning
messages.keyword
- the keyword used to index the warning message
within the set of ResourceBundle
s.
IllegalArgumentException
- if baseName
is null
.
IllegalArgumentException
- if keyword
is null
.
IllegalArgumentException
- if no appropriate
ResourceBundle
may be located.
IllegalArgumentException
- if the named resource is
not found in the located ResourceBundle
.
IllegalArgumentException
- if the object retrieved
from the ResourceBundle
is not a
String
.public void reset()
ImageReader
to its initial state.
The default implementation calls setInput(null,
false)
, setLocale(null)
,
removeAllIIOReadUpdateListeners()
,
removeAllIIOReadWarningListeners()
,
removeAllIIOReadProgressListeners()
, and
clearAbortRequest
.
public void dispose()
finalize
) subsequent to a call to this method
is undefined.
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)
ImageReadParam
. The actual
subsampling factors, destination size, and destination offset
are not taken into consideration, thus further
clipping must take place. The computeRegions
method performs all necessary
clipping.
param
- the ImageReadParam
being used, or
null
.srcWidth
- the width of the source image.srcHeight
- the height of the source image.
Rectangle
.protected static void computeRegions(ImageReadParam param, int srcWidth, int srcHeight, BufferedImage image, Rectangle srcRegion, Rectangle destRegion)
ImageReadParam
into account. The source region
begins with the entire source image. Then that is clipped to
the source region specified in the ImageReadParam
,
if one is specified.
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
method may be used if only source clipping is desired.
getSourceRegion
param
- an ImageReadParam
, or null
.srcWidth
- the width of the source image.srcHeight
- the height of the source image.image
- a BufferedImage
that will be the
destination image, or null
.srcRegion
- a Rectangle
that will be filled with
the source region of interest.destRegion
- a Rectangle
that will be filled with
the destination region of interest.
IllegalArgumentException
- if srcRegion
is null
.
IllegalArgumentException
- if dstRegion
is null
.
IllegalArgumentException
- if the resulting source or
destination region is empty.protected static void checkReadParamBandSettings(ImageReadParam param, int numSrcBands, int numDstBands)
ImageReadParam
. This method may be called as soon
as the reader knows both the number of bands of the source
image as it exists in the input stream, and the number of bands
of the destination image that being written.
The method retrieves the source and destination band
setting arrays from param using the getSourceBands
and getDestinationBands
methods (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.
param
- the ImageReadParam
being used to read
the image.numSrcBands
- the number of bands of the image as it exists
int the input source.numDstBands
- the number of bands in the destination image
being written.
IllegalArgumentException
- if param
contains an invalid specification of a source and/or
destination band subset.protected static BufferedImage getDestination(ImageReadParam param, Iterator<ImageTypeSpecifier> imageTypes, int width, int height) throws IIOException
BufferedImage
to which decoded pixel
data should be written. The image is determined by inspecting
the supplied ImageReadParam
if it is
non-null
; if its getDestination
method returns a non-null
value, that image is
simply returned. Otherwise,
param.getDestinationType
method is called to
determine if a particular image type has been specified. If
so, the returned ImageTypeSpecifier
is used after
checking that it is equal to one of those included in
imageTypes
.
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.
param
- an ImageReadParam
to be used to get
the destination image or image type, or null
.imageTypes
- an Iterator
of
ImageTypeSpecifier
s indicating the legal image
types, with the default first.width
- the true width of the image or tile begin decoded.height
- the true width of the image or tile being decoded.
BufferedImage
to which decoded pixel
data should be written.
IIOException
- if the ImageTypeSpecifier
specified by param
does not match any of the legal
ones from imageTypes
.
IllegalArgumentException
- if imageTypes
is null
or empty, or if an object not of type
ImageTypeSpecifier
is retrieved from it.
IllegalArgumentException
- if the resulting image would
have a width or height less than 1.
IllegalArgumentException
- if the product of
width
and height
is greater than
Integer.MAX_VALUE
.