Ordinarily, the controller will be a GUI providing a user interface for a subclass of IIOParam for a particular plug-in. Controllers need not be GUIs, however.
Returns: true if the controller completed normally.
Throws:
- IllegalStateException - if there is no controller currently installed.
See Also: IIOParamController, IIOParam.setController(IIOParamController), IIOParam.getController(), IIOParam.getDefaultController(), IIOParam.hasController(),

If setDestinationOffsets has not been called, a Point with zero X and Y values is returned (which is the correct value).
Returns: the destination offset as a Point.
See Also: IIOParam.setDestinationOffset(java.awt.Point),

Semantically, the array returned is a copy; changes to array contents subsequent to this call have no effect on this IIOParam.
Returns: the set of source bands to be used, or null.
See Also: IIOParam.setSourceBands(int[]),

If setSourceSubsampling has not been called, 1 is returned (which is the correct value).
Returns: the source subsampling X period.
See Also: IIOParam.setSourceSubsampling(int, int, int, int), IIOParam.getSourceYSubsampling(),

If setSourceSubsampling has not been called, 1 is returned (which is the correct value).
Returns: the source subsampling Y period.
See Also: IIOParam.setSourceSubsampling(int, int, int, int), IIOParam.getSourceXSubsampling(),

If setSourceSubsampling has not been called, 0 is returned (which is the correct value).
Returns: the source subsampling grid X offset.
See Also: IIOParam.setSourceSubsampling(int, int, int, int), IIOParam.getSubsamplingYOffset(),

If setSourceSubsampling has not been called, 0 is returned (which is the correct value).
Returns: the source subsampling grid Y offset.
See Also: IIOParam.setSourceSubsampling(int, int, int, int), IIOParam.getSubsamplingXOffset(),

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 - the BufferedImage to be written to, or null.
See Also: ImageReadParam.getDestination(),

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 - an array of integer band indices to be used.
Throws:
- IllegalArgumentException - if destinationBands contains a negative or duplicate value.
See Also: ImageReadParam.getDestinationBands(), IIOParam.getSourceBands(), ImageReader.checkReadParamBandSettings(javax.imageio.ImageReadParam, int, int),

When reading, the region to be written within the destination BufferedImage will start at this offset and have a width and height determined by the source region of interest, the subsampling parameters, and the destination bounds.

Normal writes are not affected by this method, only writes performed using ImageWriter.replacePixels. For such writes, the offset specified is within the output stream image whose pixels are being modified.

There is no unsetDestinationOffset method; simply call setDestinationOffset(new Point(0, 0)) to restore default values.
Parameters:
- destinationOffset - the offset in the destination, as a Point.
Throws:
- IllegalArgumentException - if destinationOffset is null.
See Also: IIOParam.getDestinationOffset(), ImageWriter.replacePixels(java.awt.image.RenderedImage, javax.imageio.ImageWriteParam),

A null value indicates that all source bands will be used.

At the time of reading, an IllegalArgumentException will be thrown by the reader or writer if a value larger than the largest available source 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.

Semantically, a copy is made of the array; changes to the array contents subsequent to this call have no effect on this IIOParam.
Parameters:
- sourceBands - an array of integer band indices to be used.
Throws:
- IllegalArgumentException - if sourceBands contains a negative or duplicate value.
See Also: IIOParam.getSourceBands(), ImageReadParam.setDestinationBands(int[]), ImageReader.checkReadParamBandSettings(javax.imageio.ImageReadParam, int, int),

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 - the index of the first pass to be decoded.
- numPasses - the maximum number of passes to be decoded.
Throws:
- 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: ImageReadParam.getSourceMinProgressivePass(), ImageReadParam.getSourceMaxProgressivePass(),

The source region of interest specified by this method will be clipped as needed to fit within the source bounds, as well as the destination offsets, width, and height at the time of actual I/O.

A value of null for sourceRegion will remove any region specification, causing the entire image to be used.
Parameters:
- sourceRegion - a Rectangle specifying the source region of interest, or null.
Throws:
- IllegalArgumentException - if sourceRegion is non-null and either sourceRegion.x or sourceRegion.y is negative.
- IllegalArgumentException - if sourceRegion is non-null and either sourceRegion.width or sourceRegion.height is negative or 0.
- IllegalStateException - if subsampling is such that this region will have a subsampled width or height of zero.
See Also: IIOParam.getSourceRegion(), IIOParam.setSourceSubsampling(int, int, int, int), IIOParam.setDestinationOffset(java.awt.Point), IIOParam.getDestinationOffset(),

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 - a Dimension indicating the desired width and height.
Throws:
- IllegalArgumentException - if either the width or the height is negative or 0.
- UnsupportedOperationException - if image resizing is not supported by this plug-in.
See Also: ImageReadParam.getSourceRenderSize(), ImageReader.getWidth(int), ImageReader.getHeight(int), ImageReader.getAspectRatio(int),

The number of pixels and scanlines to be used are calculated as follows.

The number of subsampled pixels in a scanline is given by

truncate[(width - subsamplingXOffset + sourceXSubsampling - 1) / sourceXSubsampling].

If the region is such that this width is zero, an IllegalStateException is thrown.

The number of scanlines to be used can be computed similarly.

The ability to set the subsampling grid to start somewhere other than the source region origin is useful if the region is being used to create subsampled tiles of a large image, where the tile width and height are not multiples of the subsampling periods. If the subsampling grid does not remain consistent from tile to tile, there will be artifacts at the tile boundaries. By adjusting the subsampling grid offset for each tile to compensate, these artifacts can be avoided. The tradeoff is that in order to avoid these artifacts, the tiles are not all the same size. The grid offset to use in this case is given by:
grid offset = [period - (region offset modulo period)] modulo period)

If either sourceXSubsampling or sourceYSubsampling is 0 or negative, an IllegalArgumentException will be thrown.

If either subsamplingXOffset or subsamplingYOffset is negative or greater than or equal to the corresponding period, an IllegalArgumentException will be thrown.

There is no unsetSourceSubsampling method; simply call setSourceSubsampling(1, 1, 0, 0) to restore default values.
Parameters:
- sourceXSubsampling - the number of columns to advance between pixels.
- sourceYSubsampling - the number of rows to advance between pixels.
- subsamplingXOffset - the horizontal offset of the first subsample within the region, or within the image if no region is set.
- subsamplingYOffset - the horizontal offset of the first subsample within the region, or within the image if no region is set.
Throws:
- IllegalArgumentException - if either period is negative or 0, or if either grid offset is negative or greater than the corresponding period.
- IllegalStateException - if the source region is such that the subsampled output would contain no pixels.