A class describing how a stream is to be decoded. Instances of
this class or its subclasses are used to supply prescriptive
"how-to" information to instances of
ImageReader
.
An image encoded as part of a file or stream may be thought of
extending out in multiple dimensions: the spatial dimensions of
width and height, a number of bands, and a number of progressive
decoding passes. This class allows a contiguous (hyper)rectangular
subarea of the image in all of these dimensions to be selected for
decoding. Additionally, the spatial dimensions may be subsampled
discontinuously. Finally, color and format conversions may be
specified by controlling the ColorModel
and
SampleModel
of the destination image, either by
providing a BufferedImage
or by using an
ImageTypeSpecifier
.
An ImageReadParam
object is used to specify how an
image, or a set of images, will be converted on input from
a stream in the context of the Java Image I/O framework. A plug-in for a
specific image format will return instances of
ImageReadParam
from the
getDefaultReadParam
method of its
ImageReader
implementation.
The state maintained by an instance of
ImageReadParam
is independent of any particular image
being decoded. When actual decoding takes place, the values set in
the read param are combined with the actual properties of the image
being decoded from the stream and the destination
BufferedImage
that will receive the decoded pixel
data. For example, the source region set using
setSourceRegion
will first be intersected with the
actual valid source area. The result will be translated by the
value returned by getDestinationOffset
, and the
resulting rectangle intersected with the actual valid destination
area to yield the destination area that will be written.
The parameters specified by an ImageReadParam
are
applied to an image as follows. First, if a rendering size has
been set by setSourceRenderSize
, the entire decoded
image is rendered at the size given by
getSourceRenderSize
. Otherwise, the image has its
natural size given by ImageReader.getWidth
and
ImageReader.getHeight
.
Next, the image is clipped against the source region
specified by getSourceXOffset
, getSourceYOffset
,
getSourceWidth
, and getSourceHeight
.
The resulting region is then subsampled according to the
factors given in IIOParam.setSourceSubsampling
. The first pixel,
the number of pixels per row, and the number of rows all depend
on the subsampling settings.
Call the minimum X and Y coordinates of the resulting rectangle
(minX
, minY
), its width w
and its height h
.
This rectangle is offset by
(getDestinationOffset().x
,
getDestinationOffset().y
) and clipped against the
destination bounds. If no destination image has been set, the
destination is defined to have a width of
getDestinationOffset().x
+ w
, and a
height of getDestinationOffset().y
+ h
so
that all pixels of the source region may be written to the
destination.
Pixels that land, after subsampling, within the destination
image, and that are written in one of the progressive passes
specified by getSourceMinProgressivePass
and
getSourceNumProgressivePasses
are passed along to the
next step.
Finally, the source samples of each pixel are mapped into
destination bands according to the algorithm described in the
comment for setDestinationBands
.
Plug-in writers may extend the functionality of
ImageReadParam
by providing a subclass that implements
additional, plug-in specific interfaces. It is up to the plug-in
to document what interfaces are available and how they are to be
used. Readers will silently ignore any extended features of an
ImageReadParam
subclass of which they are not aware.
Also, they may ignore any optional features that they normally
disable when creating their own ImageReadParam
instances via getDefaultReadParam
.
Note that unless a query method exists for a capability, it must
be supported by all ImageReader
implementations
(e.g. source render size is optional, but subsampling must be
supported).