OpenJDK 27 · javax.imageio.ImageReadParam · APIdia, the JavaDoc alternative

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).

Modifier and Type	Field and Description
protected boolean	canSetSourceRenderSize `true` if this `ImageReadParam` allows the source rendering dimensions to be set.
protected BufferedImage	destination The current destination `BufferedImage`, or `null` if none has been set.
protected int[]	destinationBands The set of destination bands to be used, as an array of `int`s.
protected int	minProgressivePass The minimum index of a progressive pass to read from the source.
protected int	numProgressivePasses The maximum number of progressive passes to read from the source.
protected Dimension	sourceRenderSize The desired rendering width and height of the source, if `canSetSourceRenderSize` is `true`, or `null`.

Constructor Summary

Access	Constructor and Description
public	ImageReadParam() Constructs an `ImageReadParam`.

Method Summary

Modifier and Type	Method and Description
public boolean	Returns: `true` if setting source rendering size is supported. canSetSourceRenderSize() Returns `true` if this reader allows the source image to be rendered at an arbitrary size as part of the decoding process, by means of the `setSourceRenderSize` method.
public BufferedImage	Returns: the BufferedImage to be written to. getDestination() Returns the `BufferedImage` currently set by the `setDestination` method, or `null` if none is set.
public int[]	Returns: the indices of the destination bands to be used, or `null`. getDestinationBands() Returns the set of band indices where data will be placed.
public int	Returns: the index of the last pass to be read, or `Integer.MAX_VALUE`. getSourceMaxProgressivePass() If `getSourceNumProgressivePasses` is equal to `Integer.MAX_VALUE`, returns `Integer.MAX_VALUE`.
public int	Returns: the index of the first pass that will be decoded. getSourceMinProgressivePass() Returns the index of the first progressive pass that will be decoded.
public int	Returns: the number of the passes that will be decoded. getSourceNumProgressivePasses() Returns the number of the progressive passes that will be decoded.
public Dimension	Returns: the rendered width and height of the source image as a `Dimension`. getSourceRenderSize() Returns the width and height of the source image as it will be rendered during decoding, if they have been set via the `setSourceRenderSize` method.
public void	setDestination(BufferedImage the BufferedImage to be written to, or `null`. destination) Supplies a `BufferedImage` to be used as the destination for decoded pixel data.
public void	setDestinationBands(int[] an array of integer band indices to be used. destinationBands) Sets the indices of the destination bands where data will be placed.
public void	setDestinationType(ImageTypeSpecifier destinationType) Overrides javax.imageio.IIOParam.setDestinationType. Sets the desired image type for the destination image, using an `ImageTypeSpecifier`.
public void	setSourceProgressivePasses(int the index of the first pass to be decoded. minPass, int the maximum number of passes to be decoded. numPasses) Sets the range of progressive passes that will be decoded.
public void	setSourceRenderSize(Dimension a `Dimension` indicating the desired width and height. size) If the image is able to be rendered at an arbitrary size, sets the source width and height to the supplied values.

Inherited from javax.imageio.IIOParam:: activateController getController getDefaultController getDestinationOffset getDestinationType getSourceBands getSourceRegion getSourceXSubsampling getSourceYSubsampling getSubsamplingXOffset getSubsamplingYOffset hasController setController setDestinationOffset setSourceBands setSourceRegion setSourceSubsampling

Field Detail

canSetSourceRenderSize back to summary

canSetSourceRenderSize	back to summary
protected boolean canSetSourceRenderSize `true` if this `ImageReadParam` allows the source rendering dimensions to be set. By default, the value is `false`. Subclasses must set this value manually. `ImageReader`s that do not support setting of the source render size should set this value to `false`.

protected boolean canSetSourceRenderSize

true if this ImageReadParam allows 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 false.

destination	back to summary
protected BufferedImage destination The current destination `BufferedImage`, or `null` if none has been set. By default, the value is `null`.

destinationBands	back to summary
protected int[] destinationBands The set of destination bands to be used, as an array of `int`s. By default, the value is `null`, indicating all destination bands should be written in order.

minProgressivePass	back to summary
protected int minProgressivePass The minimum index of a progressive pass to read from the source. By default, the value is set to 0, which indicates that passes starting with the first available pass should be decoded. Subclasses should ensure that this value is non-negative.

minProgressivePass

back to summary

protected int minProgressivePass

The minimum index of a progressive pass to read from the source. By default, the value is set to 0, which indicates that passes starting with the first available pass should be decoded.

Subclasses should ensure that this value is non-negative.

numProgressivePasses back to summary

numProgressivePasses	back to summary
protected int numProgressivePasses The maximum number of progressive passes to read from the source. By default, the value is set to `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 `Integer.MAX_VALUE`, then `minProgressivePass + numProgressivePasses - 1` should not exceed `Integer.MAX_VALUE`.

protected int numProgressivePasses

The maximum number of progressive passes to read from the source. By default, the value is set to 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 Integer.MAX_VALUE, then minProgressivePass + numProgressivePasses - 1 should not exceed Integer.MAX_VALUE.

sourceRenderSize back to summary

sourceRenderSize	back to summary
protected Dimension sourceRenderSize The desired rendering width and height of the source, if `canSetSourceRenderSize` is `true`, or `null`. `ImageReader`s that do not support setting of the source render size may ignore this value.

protected Dimension sourceRenderSize

The desired rendering width and height of the source, if canSetSourceRenderSize is true, or null.

ImageReaders that do not support setting of the source render size may ignore this value.

Constructor Detail

ImageReadParam	back to summary
public ImageReadParam() Constructs an `ImageReadParam`.

Method Detail

canSetSourceRenderSize back to summary

canSetSourceRenderSize	back to summary
public boolean canSetSourceRenderSize() Returns `true` if this reader allows the source image to be rendered at an arbitrary size as part of the decoding process, by means of the `setSourceRenderSize` method. If this method returns `false`, calls to `setSourceRenderSize` will throw an `UnsupportedOperationException`. Returns:boolean `true` if setting source rendering size is supported. See Also `setSourceRenderSize`

public boolean canSetSourceRenderSize()

Returns true if this reader allows the source image to be rendered at an arbitrary size as part of the decoding process, by means of the setSourceRenderSize method. If this method returns false, calls to setSourceRenderSize will throw an UnsupportedOperationException.

Returns:boolean: true if setting source rendering size is supported.
See Also: setSourceRenderSize

getDestination back to summary

getDestination	back to summary
public BufferedImage getDestination() Returns the `BufferedImage` currently set by the `setDestination` method, or `null` if none is set. Returns:BufferedImage the BufferedImage to be written to. See Also `setDestination`

public BufferedImage getDestination()

Returns the BufferedImage currently set by the setDestination method, or null if none is set.

Returns:BufferedImage: the BufferedImage to be written to.
See Also: setDestination

getDestinationBands back to summary

getDestinationBands	back to summary
public int[] getDestinationBands() Returns the set of band indices where data will be placed. If no value has been set, `null` is returned to indicate that all destination bands will be used. Returns:int[] the indices of the destination bands to be used, or `null`. See Also `setDestinationBands`

public int[] getDestinationBands()

Returns the set of band indices where data will be placed. If no value has been set, null is returned to indicate that all destination bands will be used.

Returns:int[]: the indices of the destination bands to be used, or null.
See Also: setDestinationBands

getSourceMaxProgressivePass back to summary

getSourceMaxProgressivePass	back to summary
public int getSourceMaxProgressivePass() If `getSourceNumProgressivePasses` is equal to `Integer.MAX_VALUE`, returns `Integer.MAX_VALUE`. Otherwise, returns `getSourceMinProgressivePass() + getSourceNumProgressivePasses() - 1`. Returns:int the index of the last pass to be read, or `Integer.MAX_VALUE`.

public int getSourceMaxProgressivePass()

If getSourceNumProgressivePasses is equal to Integer.MAX_VALUE, returns Integer.MAX_VALUE. Otherwise, returns getSourceMinProgressivePass() + getSourceNumProgressivePasses() - 1.

Returns:int: the index of the last pass to be read, or Integer.MAX_VALUE.

getSourceMinProgressivePass back to summary

getSourceMinProgressivePass	back to summary
public int getSourceMinProgressivePass() Returns the index of the first progressive pass that will be decoded. If no value has been set, 0 will be returned (which is the correct value). Returns:int the index of the first pass that will be decoded. See Also `setSourceProgressivePasses`, `getSourceNumProgressivePasses`

public int getSourceMinProgressivePass()

Returns the index of the first progressive pass that will be decoded. If no value has been set, 0 will be returned (which is the correct value).

Returns:int: the index of the first pass that will be decoded.
See Also: setSourceProgressivePasses, getSourceNumProgressivePasses

getSourceNumProgressivePasses back to summary

getSourceNumProgressivePasses	back to summary
public int getSourceNumProgressivePasses() Returns the number of the progressive passes that will be decoded. If no value has been set, `Integer.MAX_VALUE` will be returned (which is the correct value). Returns:int the number of the passes that will be decoded. See Also `setSourceProgressivePasses`, `getSourceMinProgressivePass`

public int getSourceNumProgressivePasses()

Returns the number of the progressive passes that will be decoded. If no value has been set, Integer.MAX_VALUE will be returned (which is the correct value).

Returns:int: the number of the passes that will be decoded.
See Also: setSourceProgressivePasses, getSourceMinProgressivePass

getSourceRenderSize back to summary

getSourceRenderSize	back to summary
public Dimension getSourceRenderSize() Returns the width and height of the source image as it will be rendered during decoding, if they have been set via the `setSourceRenderSize` method. A `null` value indicates that no setting has been made. Returns:Dimension the rendered width and height of the source image as a `Dimension`. See Also `setSourceRenderSize`

public Dimension getSourceRenderSize()

Returns the width and height of the source image as it will be rendered during decoding, if they have been set via the setSourceRenderSize method. A null value indicates that no setting has been made.

Returns:Dimension: the rendered width and height of the source image as a Dimension.
See Also: setSourceRenderSize

setDestination back to summary

setDestination	back to summary
public void setDestination(BufferedImage destination) Supplies a `BufferedImage` to be used as the destination for decoded pixel data. The currently set image will be written to by the `read`, `readAll`, and `readRaster` methods, 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 `getDestinationOffset`. If `destination` is `null`, a newly-created `BufferedImage` will be returned by those methods. At the time of reading, the image is checked to verify that its `ColorModel` and `SampleModel` correspond to one of the `ImageTypeSpecifier`s returned from the `ImageReader`'s `getImageTypes` method. If it does not, the reader will throw an `IIOException`. Parameters destination:BufferedImage the BufferedImage to be written to, or `null`. See Also `getDestination`

public void setDestination(BufferedImage destination)

Supplies a BufferedImage to be used as the destination for decoded pixel data. The currently set image will be written to by the read, readAll, and readRaster methods, 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 getDestinationOffset.

If destination is null, a newly-created BufferedImage will be returned by those methods.

At the time of reading, the image is checked to verify that its ColorModel and SampleModel correspond to one of the ImageTypeSpecifiers returned from the ImageReader's getImageTypes method. If it does not, the reader will throw an IIOException.

Parameters

destination:BufferedImage: the BufferedImage to be written to, or null.

See Also

getDestination

setDestinationBands back to summary

setDestinationBands	back to summary
public void setDestinationBands(int[] destinationBands) Sets the indices of the destination bands where data will be placed. Duplicate indices are not allowed. A `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 `ImageReadParam.setDestination` method. 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. Parameters destinationBands:int[] an array of integer band indices to be used. Exceptions IllegalArgumentException: if `destinationBands` contains a negative or duplicate value. See Also `getDestinationBands`, `getSourceBands`, `ImageReader#checkReadParamBandSettings`

public void setDestinationBands(int[] destinationBands)

Sets the indices of the destination bands where data will be placed. Duplicate indices are not allowed.

A 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 ImageReadParam.setDestination method.

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.

Parameters

destinationBands:int[]: an array of integer band indices to be used.

Exceptions

IllegalArgumentException:: if destinationBands contains a negative or duplicate value.

setDestinationType back to summary

setDestinationType	back to summary
public void setDestinationType(ImageTypeSpecifier destinationType) Overrides javax.imageio.IIOParam.setDestinationType. Doc from javax.imageio.IIOParam.setDestinationType. Sets the desired image type for the destination image, using an `ImageTypeSpecifier`. When reading, if the layout of the destination has been set using this method, each call to an `ImageReader` `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 `ImageReadParam.setDestination(BufferedImage)` will no longer be set as the destination. In other words, this method may be thought of as calling `setDestination((BufferedImage)null)`. When writing, the destination type maybe used to determine the color type of the image. The `SampleModel` information will be ignored, and may be `null`. For 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 when `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 setDestinationType(ImageTypeSpecifier destinationType)

Overrides javax.imageio.IIOParam.setDestinationType.

Doc from javax.imageio.IIOParam.setDestinationType.

Sets the desired image type for the destination image, using an ImageTypeSpecifier.

When reading, if the layout of the destination has been set using this method, each call to an ImageReader 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 ImageReadParam.setDestination(BufferedImage) will no longer be set as the destination. In other words, this method may be thought of as calling setDestination((BufferedImage)null).

When writing, the destination type maybe used to determine the color type of the image. The SampleModel information will be ignored, and may be null. For 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 when setSourceBands is used since the image's ColorModel will refer to the entire image rather than to the subset of bands being written.

setSourceProgressivePasses back to summary

setSourceProgressivePasses	back to summary
public void setSourceProgressivePasses(int minPass, int numPasses) Sets the range of progressive passes that will be decoded. Passes outside of this range will be ignored. 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 `numPasses` 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 `Integer.MAX_VALUE`. There is no `unsetSourceProgressivePasses` method; the same effect may be obtained by calling `setSourceProgressivePasses(0, Integer.MAX_VALUE)`. Parameters minPass:int the index of the first pass to be decoded. numPasses:int the maximum number of passes to be decoded. Exceptions IllegalArgumentException: if `minPass` is negative, `numPasses` is negative or 0, or `numPasses` is smaller than `Integer.MAX_VALUE` but `minPass + numPasses - 1` is greater than `INTEGER.MAX_VALUE`. See Also `getSourceMinProgressivePass`, `getSourceMaxProgressivePass`

public void setSourceProgressivePasses(int minPass, int numPasses)

Sets the range of progressive passes that will be decoded. Passes outside of this range will be ignored.

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 numPasses 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 Integer.MAX_VALUE.

There is no unsetSourceProgressivePasses method; the same effect may be obtained by calling setSourceProgressivePasses(0, Integer.MAX_VALUE).

Parameters

minPass:int: the index of the first pass to be decoded.
numPasses:int: the maximum number of passes to be decoded.

Exceptions

IllegalArgumentException:: if minPass is negative, numPasses is negative or 0, or numPasses is smaller than Integer.MAX_VALUE but minPass + numPasses - 1 is greater than INTEGER.MAX_VALUE.

setSourceRenderSize back to summary

setSourceRenderSize	back to summary
public void setSourceRenderSize(Dimension size) throws UnsupportedOperationException If the image is able to be rendered at an arbitrary size, sets the source width and height to the supplied values. Note that the values returned from the `getWidth` and `getHeight` methods on `ImageReader` are 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 `ImageReader.getAspectRatio`. If this plug-in does not allow the rendering size to be set, an `UnsupportedOperationException` will be thrown. To remove the render size setting, pass in a value of `null` for `size`. Parameters size:Dimension a `Dimension` indicating the desired width and height. Exceptions UnsupportedOperationException: if image resizing is not supported by this plug-in. IllegalArgumentException: if either the width or the height is negative or 0. See Also `getSourceRenderSize`, `ImageReader#getWidth`, `ImageReader#getHeight`, `ImageReader#getAspectRatio`

public void setSourceRenderSize(Dimension size) throws UnsupportedOperationException

If the image is able to be rendered at an arbitrary size, sets the source width and height to the supplied values. Note that the values returned from the getWidth and getHeight methods on ImageReader are 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 ImageReader.getAspectRatio.

If this plug-in does not allow the rendering size to be set, an UnsupportedOperationException will be thrown.

To remove the render size setting, pass in a value of null for size.

Parameters

size:Dimension: a Dimension indicating the desired width and height.

Exceptions

UnsupportedOperationException:: if image resizing is not supported by this plug-in.
IllegalArgumentException:: if either the width or the height is negative or 0.

public Class ImageReadParam

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail