public class ImageReadParam extends IIOParam
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
SampleModel of the destination image, either by
BufferedImage or by using 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
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
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
Next, the image is clipped against the source region
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
minY), its width
and its height
This rectangle is offset by
getDestinationOffset().y) and clipped against the
destination bounds. If no destination image has been set, the
destination is defined to have a width of
w, and a
that all pixels of the source region may be written to the
Pixels that land, after subsampling, within the destination
image, and that are written in one of the progressive passes
getSourceNumProgressivePasses are passed along to the
Finally, the source samples of each pixel are mapped into
destination bands according to the algorithm described in the
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
Note that unless a query method exists for a capability, it must
be supported by all
(e.g. source render size is optional, but subsampling must be
|Modifier and Type||Field and Description|
The current destination
The set of destination bands to be used, as an array of
The minimum index of a progressive pass to read from the source.
The maximum number of progressive passes to read from the source.
The desired rendering width and height of the source, if
|Constructor and Description|
|Modifier and Type||Method and Description|
Returns the set of band indices where data will be placed.
Returns the index of the first progressive pass that will be decoded.
Returns the number of the progressive passes that will be decoded.
Returns the width and height of the source image as it will be rendered during decoding, if they have been set via the
Sets the indices of the destination bands where data will be placed.
Sets the desired image type for the destination image, using an
Sets the range of progressive passes that will be decoded.
If the image is able to be rendered at an arbitrary size, sets the source width and height to the supplied values.
activateController, getController, getDefaultController, getDestinationOffset, getDestinationType, getSourceBands, getSourceRegion, getSourceXSubsampling, getSourceYSubsampling, getSubsamplingXOffset, getSubsamplingYOffset, hasController, setController, setDestinationOffset, setSourceBands, setSourceRegion, setSourceSubsampling
protected boolean canSetSourceRenderSize
ImageReadParamallows the source rendering dimensions to be set. By default, the value is
false. Subclasses must set this value manually.
ImageReaders that do not support setting of
the source render size should set this value to
protected Dimension sourceRenderSize
ImageReaders that do not support setting of
the source render size may ignore this value.
protected BufferedImage destination
nullif none has been set. By default, the value is
protected int destinationBands
ints. By default, the value is
null, indicating all destination bands should be written in order.
protected int minProgressivePass
Subclasses should ensure that this value is non-negative.
protected int numProgressivePasses
Integer.MAX_VALUE, which indicates that passes up to and including the last available pass should be decoded.
Subclasses should ensure that this value is positive.
Additionally, if the value is not
numProgressivePasses - 1 should not exceed
public void setDestinationType(ImageTypeSpecifier destinationType)
When reading, if the layout of the destination has been set
using this method, each call to an
read method will return a new
BufferedImage using the format specified by the
supplied type specifier. As a side effect, any destination
BufferedImage set by
no longer be set as the destination. In other words, this
method may be thought of as calling
When writing, the destination type maybe used to determine
the color type of the image. The
information will be ignored, and may be
example, a 4-banded image could represent either CMYK or RGBA
data. If a destination type is set, its
ColorModel will override any
ColorModel on the image itself. This is crucial
setSourceBands is used since the image's
ColorModel will refer to the entire image rather
than to the subset of bands being written.
public void setDestination(BufferedImage destination)
BufferedImageto be used as the destination for decoded pixel data. The currently set image will be written to by the
readRastermethods, and a reference to it will be returned by those methods.
Pixel data from the aforementioned methods will be written
starting at the offset specified by
BufferedImage will be returned by
At the time of reading, the image is checked to verify that
correspond to one of the
returned from the
getImageTypes method. If it does not, the reader
will throw an
destination- the BufferedImage to be written to, or
public BufferedImage getDestination()
BufferedImagecurrently set by the
nullif none is set.
public void setDestinationBands(int destinationBands)
null value indicates that all destination
bands will be used.
Choosing a destination band subset will not affect the
number of bands in the output image of a read if no destination
image is specified; the created destination image will still
have the same number of bands as if this method had never been
called. If a different number of bands in the destination
image is desired, an image must be supplied using the
At the time of reading or writing, an
IllegalArgumentException will be thrown by the
reader or writer if a value larger than the largest destination
band index has been specified, or if the number of source bands
and destination bands to be used differ. The
ImageReader.checkReadParamBandSettings method may
be used to automate this test.
destinationBands- an array of integer band indices to be used.
destinationBandscontains a negative or duplicate value.
ImageReader.checkReadParamBandSettings(javax.imageio.ImageReadParam, int, int)
public int getDestinationBands()
nullis returned to indicate that all destination bands will be used.
public boolean canSetSourceRenderSize()
trueif this reader allows the source image to be rendered at an arbitrary size as part of the decoding process, by means of the
setSourceRenderSizemethod. If this method returns
false, calls to
setSourceRenderSizewill throw an
trueif setting source rendering size is supported.
public void setSourceRenderSize(Dimension size) throws UnsupportedOperationException
ImageReaderare not affected by this method; they will continue to return the default size for the image. Similarly, if the image is also tiled the tile width and height are given in terms of the default size.
Typically, the width and height should be chosen such that
the ratio of width to height closely approximates the aspect
ratio of the image, as returned from
If this plug-in does not allow the rendering size to be
UnsupportedOperationException will be
To remove the render size setting, pass in a value of
Dimensionindicating the desired width and height.
IllegalArgumentException- if either the width or the height is negative or 0.
UnsupportedOperationException- if image resizing is not supported by this plug-in.
public Dimension getSourceRenderSize()
nullvalue indicates that no setting has been made.
public void setSourceProgressivePasses(int minPass, int numPasses)
A progressive pass is a re-encoding of the entire image, generally at progressively higher effective resolutions, but requiring greater transmission bandwidth. The most common use of progressive encoding is found in the JPEG format, where successive passes include more detailed representations of the high-frequency image content.
The actual number of passes to be decoded is determined
during decoding, based on the number of actual passes available
in the stream. Thus if
minPass + numPasses - 1 is
larger than the index of the last available passes, decoding
will end with that pass.
A value of
Integer.MAX_VALUE indicates that all passes from
minPass forward should be read. Otherwise, the
index of the last pass (i.e.,
minPass + numPasses
- 1) must not exceed
There is no
method; the same effect may be obtained by calling
minPass- the index of the first pass to be decoded.
numPasses- the maximum number of passes to be decoded.
numPassesis negative or 0, or
numPassesis smaller than
minPass + numPasses - 1is greater than
public int getSourceMinProgressivePass()
public int getSourceMaxProgressivePass()
getSourceNumProgressivePassesis equal to
Integer.MAX_VALUE. Otherwise, returns
getSourceMinProgressivePass() + getSourceNumProgressivePasses() - 1.
public int getSourceNumProgressivePasses()
Integer.MAX_VALUEwill be returned (which is the correct value).
Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2023, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.