javax.imageio
Class ImageWriteParam

java.lang.Object   
  javax.imageio.IIOParam   
      javax.imageio.ImageWriteParam

Direct Known Subclasses:

BMPImageWriteParam , JPEGImageWriteParam

public class ImageWriteParam
extends IIOParam   

A class describing how a stream is to be encoded. Instances of this class or its subclasses are used to supply prescriptive "how-to" information to instances of ImageWriter.

A plug-in for a specific image format may define a subclass of this class, and return objects of that class from the getDefaultWriteParam method of its ImageWriter implementation. For example, the built-in JPEG writer plug-in will return instances of javax.imageio.plugins.jpeg.JPEGImageWriteParam.

The region of the image to be written is determined by first intersecting the actual bounds of the image with the rectangle specified by IIOParam.setSourceRegion, if any. If the resulting rectangle has a width or height of zero, the writer will throw an IIOException. If the intersection is non-empty, writing will commence with the first subsampled pixel and include additional pixels within the intersected bounds according to the horizontal and vertical subsampling factors specified by IIOParam.setSourceSubsampling .

Individual features such as tiling, progressive encoding, and compression may be set in one of four modes. MODE_DISABLED disables the features; MODE_DEFAULT enables the feature with writer-controlled parameter values; MODE_EXPLICIT enables the feature and allows the use of a set method to provide additional parameters; and MODE_COPY_FROM_METADATA copies relevant parameter values from the stream and image metadata objects passed to the writer. The default for all features is MODE_COPY_FROM_METADATA. Non-standard features supplied in subclasses are encouraged, but not required to use a similar scheme.

Plug-in writers may extend the functionality of ImageWriteParam 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. Writers will silently ignore any extended features of an ImageWriteParam subclass of which they are not aware. Also, they may ignore any optional features that they normally disable when creating their own ImageWriteParam instances via getDefaultWriteParam.

Note that unless a query method exists for a capability, it must be supported by all ImageWriter implementations (e.g. progressive encoding is optional, but subsampling must be supported).

See Also:

ImageReadParam

Field Summary

protected boolean	canOffsetTiles A boolean that is true if this ImageWriteParam allows tiling grid offset parameters to be set.
protected boolean	canWriteCompressed A boolean that is true if this writer can write images using compression.
protected boolean	canWriteProgressive A boolean that is true if this ImageWriteParam allows images to be written as a progressive sequence of increasing quality passes.
protected boolean	canWriteTiles A boolean that is true if this ImageWriteParam allows tile width and tile height parameters to be set.
protected int	compressionMode The mode controlling compression settings, which must be set to one of the four MODE_* values.
protected float	compressionQuality A float containing the current compression quality setting.
protected String	compressionType A String containing the name of the current compression type, or null if none is set.
protected String []	compressionTypes An array of Strings containing the names of the available compression types.
protected Locale	locale A Locale to be used to localize compression type names and quality descriptions, or null to use a default Locale.
static int	MODE_COPY_FROM_METADATA A constant value that may be passed into methods such as setTilingMode, setProgressiveMode, or setCompressionMode to enable that feature for future writes.
static int	MODE_DEFAULT A constant value that may be passed into methods such as setTilingMode, setProgressiveMode, and setCompressionMode to enable that feature for future writes.
static int	MODE_DISABLED A constant value that may be passed into methods such as setTilingMode, setProgressiveMode, and setCompressionMode to disable a feature for future writes.
static int	MODE_EXPLICIT A constant value that may be passed into methods such as setTilingMode or setCompressionMode to enable a feature for future writes.
protected Dimension []	preferredTileSizes An array of preferred tile size range pairs.
protected int	progressiveMode The mode controlling progressive encoding, which must be set to one of the four MODE_* values, except MODE_EXPLICIT.
protected int	tileGridXOffset The amount by which the tile grid origin should be offset horizontally from the image origin if tiling has been set, or 0 otherwise.
protected int	tileGridYOffset The amount by which the tile grid origin should be offset vertically from the image origin if tiling has been set, or 0 otherwise.
protected int	tileHeight The height of each tile if tiling has been set, or 0 otherwise.
protected int	tileWidth The width of each tile if tiling has been set, or 0 otherwise.
protected int	tilingMode The mode controlling tiling settings, which Must be set to one of the four MODE_* values.
protected boolean	tilingSet A boolean that is true if tiling parameters have been specified.

Fields inherited from class javax.imageio.IIOParam

controller , defaultController , destinationOffset , destinationType , sourceBands , sourceRegion , sourceXSubsampling , sourceYSubsampling , subsamplingXOffset , subsamplingYOffset

Constructor Summary

protected	ImageWriteParam () Constructs an empty ImageWriteParam.
	ImageWriteParam (Locale locale) Constructs an ImageWriteParam set to use a given Locale.

Method Summary

boolean	canOffsetTiles () Returns true if the writer can perform tiling with non-zero grid offsets while writing.
boolean	canWriteCompressed () Returns true if this writer supports compression.
boolean	canWriteProgressive () Returns true if the writer can write out images as a series of passes of progressively increasing quality.
boolean	canWriteTiles () Returns true if the writer can perform tiling while writing.
float	getBitRate (float quality) Returns a float indicating an estimate of the number of bits of output data for each bit of input image data at the given quality level.
int	getCompressionMode () Returns the current compression mode, if compression is supported.
float	getCompressionQuality () Returns the current compression quality setting.
String []	getCompressionQualityDescriptions () Returns an array of Strings that may be used along with getCompressionQualityValues as part of a user interface for setting or displaying the compression quality level.
float[]	getCompressionQualityValues () Returns an array of floats that may be used along with getCompressionQualityDescriptions as part of a user interface for setting or displaying the compression quality level.
String	getCompressionType () Returns the currently set compression type, or null if none has been set.
String []	getCompressionTypes () Returns a list of available compression types, as an array or Strings, or null if a compression type may not be chosen using these interfaces.
Locale	getLocale () Returns the currently set Locale, or null if only a default Locale is supported.
String	getLocalizedCompressionTypeName () Returns a localized version of the name of the current compression type, using the Locale returned by getLocale.
Dimension []	getPreferredTileSizes () Returns an array of Dimensions indicating the legal size ranges for tiles as they will be encoded in the output file or stream.
int	getProgressiveMode () Returns the current mode for writing the stream in a progressive manner.
int	getTileGridXOffset () Returns the horizontal tile grid offset of an image as it will be written to the output stream.
int	getTileGridYOffset () Returns the vertical tile grid offset of an image as it will be written to the output stream.
int	getTileHeight () Returns the height of each tile in an image as it will be written to the output stream.
int	getTileWidth () Returns the width of each tile in an image as it will be written to the output stream.
int	getTilingMode () Returns the current tiling mode, if tiling is supported.
boolean	isCompressionLossless () Returns true if the current compression type provides lossless compression.
void	setCompressionMode (int mode) Specifies whether compression is to be performed, and if so how compression parameters are to be determined.
void	setCompressionQuality (float quality) Sets the compression quality to a value between 0 and 1.
void	setCompressionType (String compressionType) Sets the compression type to one of the values indicated by getCompressionTypes.
void	setProgressiveMode (int mode) Specifies that the writer is to write the image out in a progressive mode such that the stream will contain a series of scans of increasing quality.
void	setTiling (int tileWidth, int tileHeight, int tileGridXOffset, int tileGridYOffset) Specifies that the image should be tiled in the output stream.
void	setTilingMode (int mode) Determines whether the image will be tiled in the output stream and, if it will, how the tiling parameters will be determined.
void	unsetCompression () Removes any previous compression type and quality settings.
void	unsetTiling () Removes any previous tile grid parameters specified by calls to setTiling.

Methods inherited from class javax.imageio.IIOParam

activateController , getController , getDefaultController , getDestinationOffset , getDestinationType , getSourceBands , getSourceRegion , getSourceXSubsampling , getSourceYSubsampling , getSubsamplingXOffset , getSubsamplingYOffset , hasController , setController , setDestinationOffset , setDestinationType , setSourceBands , setSourceRegion , setSourceSubsampling

Methods inherited from class java.lang.Object

clone , equals , finalize , getClass , hashCode , notify , notifyAll , toString , wait , wait , wait

Field Detail

MODE_DISABLED

public static final int MODE_DISABLED

A constant value that may be passed into methods such as setTilingMode, setProgressiveMode, and setCompressionMode to disable a feature for future writes. That is, when this mode is set the stream will not be tiled, progressive, or compressed, and the relevant accessor methods will throw an IllegalStateException.

See Also:

MODE_EXPLICIT , MODE_COPY_FROM_METADATA , MODE_DEFAULT , setProgressiveMode(int) , getProgressiveMode() , setTilingMode(int) , getTilingMode() , setCompressionMode(int) , getCompressionMode() , Constant Field Values

MODE_DEFAULT

public static final int MODE_DEFAULT

A constant value that may be passed into methods such as setTilingMode, setProgressiveMode, and setCompressionMode to enable that feature for future writes. That is, when this mode is enabled the stream will be tiled, progressive, or compressed according to a sensible default chosen internally by the writer in a plug-in dependent way, and the relevant accessor methods will throw an IllegalStateException.

See Also:

MODE_DISABLED , MODE_EXPLICIT , MODE_COPY_FROM_METADATA , setProgressiveMode(int) , getProgressiveMode() , setTilingMode(int) , getTilingMode() , setCompressionMode(int) , getCompressionMode() , Constant Field Values

MODE_EXPLICIT

public static final int MODE_EXPLICIT

A constant value that may be passed into methods such as setTilingMode or setCompressionMode to enable a feature for future writes. That is, when this mode is set the stream will be tiled or compressed according to additional information supplied to the corresponding set methods in this class and retrievable from the corresponding get methods. Note that this mode is not supported for progressive output.

See Also:

MODE_DISABLED , MODE_COPY_FROM_METADATA , MODE_DEFAULT , setProgressiveMode(int) , getProgressiveMode() , setTilingMode(int) , getTilingMode() , setCompressionMode(int) , getCompressionMode() , Constant Field Values

MODE_COPY_FROM_METADATA