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 there are multiple compression types but none has been set, an IllegalStateException is thrown.

The default implementation checks that compression is supported and the compression mode is MODE_EXPLICIT. If so, if getCompressionTypes() is null or getCompressionType() is non-null, and quality is within bounds, it returns -1.0.
Returns: an estimate of the compressed bit rate, or -1.0F if no estimate is available.
Parameters:
- quality - the quality setting whose bit rate is to be queried.
Throws:
- UnsupportedOperationException - if the writer does not support compression.
- IllegalStateException - if the compression mode is not MODE_EXPLICIT.
- IllegalStateException - if the set of legal compression types is non-null and the current compression type is null.
- IllegalArgumentException - if quality is not between 0and 1, inclusive.

If there are multiple compression types but none has been set, an IllegalStateException is thrown.

The default implementation checks that compression is supported and that the compression mode is MODE_EXPLICIT. If so, if getCompressionTypes() is null or getCompressionType() is non-null, it returns the value of the compressionQuality instance variable.
Returns: the current compression quality setting.
Throws:
- UnsupportedOperationException - if the writer does not support compression.
- IllegalStateException - if the compression mode is not MODE_EXPLICIT.
- IllegalStateException - if the set of legal compression types is non-null and the current compression type is null.
See Also: ImageWriteParam.setCompressionQuality(float),

The default implementation checks whether compression is supported and the compression mode is MODE_EXPLICIT. If so, it returns the value of the compressionType instance variable.
Returns: the current compression type as a String, or null if no type is set.
Throws:
- UnsupportedOperationException - if the writer does not support compression.
- IllegalStateException - if the compression mode is not MODE_EXPLICIT.
See Also: ImageWriteParam.setCompressionType(java.lang.String),

If the writer only offers a single, mandatory form of compression, it is not necessary to provide any named compression types. Named compression types should only be used where the user is able to make a meaningful choice between different schemes.

The default implementation checks if compression is supported and throws an UnsupportedOperationException if not. Otherwise, it returns a clone of the compressionTypes instance variable if it is non-null, or else returns null.
Returns: an array of Strings containing the (non-localized) names of available compression types, or null.
Throws:
- UnsupportedOperationException - if the writer does not support compression.

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

The default implementation checks whether compression is supported and the compression mode is MODE_EXPLICIT. If so, if compressionType is non-null the value of getCompressionType is returned as a convenience.
Returns: a String containing a localized version of the name of the current compression type.
Throws:
- UnsupportedOperationException - if the writer does not support compression.
- IllegalStateException - if the compression mode is not MODE_EXPLICIT.
- IllegalStateException - if no compression type is set.

The information is returned as a set of pairs; the first element of a pair contains an (inclusive) minimum width and height, and the second element contains an (inclusive) maximum width and height. Together, each pair defines a valid range of sizes. To specify a fixed size, use the same width and height for both elements. To specify an arbitrary range, a value of null is used in place of an actual array of Dimensions.

If no array is specified on the constructor, but tiling is allowed, then this method returns null.
Returns: an array of Dimensions with an even length of at least two, or null.
Throws:
- UnsupportedOperationException - if the plug-in does not support tiling.

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(),

• MODE_DISABLED - If the mode is set to MODE_DISABLED, methods that query or modify the compression type or parameters will throw an IllegalStateException (if compression is normally supported by the plug-in). Some writers, such as JPEG, do not normally offer uncompressed output. In this case, attempting to set the mode to MODE_DISABLED will throw an UnsupportedOperationException and the mode will not be changed.
• MODE_EXPLICIT - Compress using the compression type and quality settings specified in this ImageWriteParam. Any previously set compression parameters are discarded.
• MODE_COPY_FROM_METADATA - Use whatever compression parameters are specified in metadata objects passed in to the writer.
• MODE_DEFAULT - Use default compression parameters.

The default is MODE_COPY_FROM_METADATA.
Parameters:
- mode - The mode for setting compression in the output stream.
Throws:
- UnsupportedOperationException - if the writer does not support compression, or does not support the requested mode.
- IllegalArgumentException - if mode is not one of the modes listed above.
See Also: ImageWriteParam.getCompressionMode(),

A compression quality setting of 0.0 is most generically interpreted as "high compression is important," while a setting of 1.0 is most generically interpreted as "high image quality is important."

If there are multiple compression types but none has been set, an IllegalStateException is thrown.

The default implementation checks that compression is supported, and that the compression mode is MODE_EXPLICIT. If so, if getCompressionTypes() returns null or compressionType is non-null it sets the compressionQuality instance variable.
Parameters:
- quality - a float between 0and 1 indicating the desired quality level.
Throws:
- UnsupportedOperationException - if the writer does not support compression.
- IllegalStateException - if the compression mode is not MODE_EXPLICIT.
- IllegalStateException - if the set of legal compression types is non-null and the current compression type is null.
- IllegalArgumentException - if quality is not between 0and 1, inclusive.
See Also: ImageWriteParam.getCompressionQuality(),

The default implementation checks whether compression is supported and the compression mode is MODE_EXPLICIT. If so, it calls getCompressionTypes and checks if compressionType is one of the legal values. If it is, the compressionType instance variable is set. If compressionType is null, the instance variable is set without performing any checking.
Parameters:
- compressionType - one of the Strings returned by getCompressionTypes, or null to remove any previous setting.
Throws:
- UnsupportedOperationException - if the writer does not support compression.
- IllegalStateException - if the compression mode is not MODE_EXPLICIT.
- UnsupportedOperationException - if there are no settable compression types.
- IllegalArgumentException - if compressionType is non-null but is not one of the values returned by getCompressionTypes.
See Also: ImageWriteParam.getCompressionTypes(), ImageWriteParam.getCompressionType(), ImageWriteParam.unsetCompression(),

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

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.
Parameters:
- destinationType - the ImageTypeSpecifier to be used to determine the destination layout and color type.
See Also: IIOParam.getDestinationType(),

The mode argument determines how the progression parameters are chosen, and must be either MODE_DISABLED, MODE_COPY_FROM_METADATA, or MODE_DEFAULT. Otherwise an IllegalArgumentException is thrown.

The modes are interpreted as follows:

• MODE_DISABLED - No progression. Use this to turn off progession.
• MODE_COPY_FROM_METADATA - The output image will use whatever progression parameters are found in the metadata objects passed into the writer.
• MODE_DEFAULT - The image will be written progressively, with parameters chosen by the writer.

The default is MODE_COPY_FROM_METADATA.
Parameters:
- mode - The mode for setting progression in the output stream.
Throws:
- UnsupportedOperationException - if the writer does not support progressive encoding.
- IllegalArgumentException - if mode is not one of the modes listed above.
See Also: ImageWriteParam.getProgressiveMode(),

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

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(),

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.

If canOffsetTiles returns false, then the tileGridXOffset and tileGridYOffset parameters must be zero.
Parameters:
- tileWidth - the width of each tile.
- tileHeight - the height of each tile.
- tileGridXOffset - the horizontal offset of the tile grid.
- tileGridYOffset - the vertical offset of the tile grid.
Throws:
- UnsupportedOperationException - if the plug-in does not support tiling.
- IllegalStateException - if the tiling mode is not MODE_EXPLICIT.
- UnsupportedOperationException - if the plug-in does not support grid offsets, and the grid offsets are not both zero.
- IllegalArgumentException - if the tile size is not within one of the allowable ranges returned by getPreferredTileSizes.
- IllegalArgumentException - if tileWidth or tileHeight is less than or equal to 0.
See Also: ImageWriteParam.canWriteTiles, ImageWriteParam.canOffsetTiles, ImageWriteParam.getTileWidth(), ImageWriteParam.getTileHeight(), ImageWriteParam.getTileGridXOffset(), ImageWriteParam.getTileGridYOffset(),

• MODE_DISABLED - The image will not be tiled.
  setTiling will throw an
  IllegalStateException.
  
  
• MODE_DEFAULT - The image will be tiled using
  default parameters. setTiling will throw an
  IllegalStateException.
  
  
• MODE_EXPLICIT - The image will be tiled
  according to parameters given in the setTiling method. Any previously set tiling
  parameters are discarded.
  
  
• MODE_COPY_FROM_METADATA - The image will
  conform to the metadata object passed in to a write.
  setTiling will throw an
  IllegalStateException.
  
  

The default implementation sets the instance variables tileWidth, tileHeight, tileGridXOffset, and tileGridYOffset to 0.
Throws:
- UnsupportedOperationException - if the plug-in does not support tiling.
- IllegalStateException - if the tiling mode is not MODE_EXPLICIT.
See Also: ImageWriteParam.setTiling(int, int, int, int),