javax.imageio
Class ImageWriteParam

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

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.

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 progressive encoding, and compression may be set in one of three 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. Non-standard features supplied in subclasses are encouraged, but not required to use a similar scheme.

See Also:

ImageReadParam

Field Summary

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 int	compressionMode The mode controlling compression settings, which must be set to one of the three MODE_* values.
protected float	compressionQuality A float containing the current compression quality setting.
protected java.lang.String	compressionType A String containing the name of the current compression type, or null if none is set.
protected java.lang.String[]	compressionTypes An array of Strings containing the names of the available compression types.
protected java.util.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_DEFAULT A constant value that may be passed into methods such as 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 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 setCompressionMode to enable a feature for future writes.
protected int	progressiveMode The mode controlling progressive encoding, which must be set to one of the three MODE_* values, except MODE_EXPLICIT.

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(java.util.Locale locale) Constructs an ImageWriteParam set to use a given Locale.

Method Summary

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.
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.
java.lang.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.
java.lang.String	getCompressionType() Returns the currently set compression type, or null if none has been set.
java.lang.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.
java.util.Locale	getLocale() Returns the currently set Locale, or null if only a default Locale is supported.
java.lang.String	getLocalizedCompressionTypeName() Returns a localized version of the name of the current compression type, using the Locale returned by getLocale.
int	getProgressiveMode() Returns the current mode for writing the stream in a progressive manner.
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(java.lang.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	unsetCompression() Removes any previous compression type and quality settings.

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 setProgressiveMode, and setCompressionMode to disable a feature for future writes. That is, when this mode is set the stream will not be progressive, or compressed, and the relevant accessor methods will throw an IllegalStateException.

See Also:

MODE_EXPLICIT, MODE_DEFAULT, setProgressiveMode(int), getProgressiveMode(), 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 setProgressiveMode, and setCompressionMode to enable that feature for future writes. That is, when this mode is enabled the stream will be progressive, or compressed according to a sensible default chosen internally by the writer and the relevant accessor methods will throw an IllegalStateException.

See Also:

MODE_DISABLED, MODE_EXPLICIT, setProgressiveMode(int), getProgressiveMode(), 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 setCompressionMode to enable a feature for future writes. That is, when this mode is set the stream will be 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_DEFAULT, setProgressiveMode(int), getProgressiveMode(), setCompressionMode(int), getCompressionMode(), Constant Field Values

canWriteProgressive

protected boolean canWriteProgressive

A boolean that is true if this ImageWriteParam allows images to be written as a progressive sequence of increasing quality passes. By default, the value is false. Subclasses must set the value manually.

Subclasses that do not support progressive encoding must ensure that this value is set to false.

progressiveMode

protected int progressiveMode

The mode controlling progressive encoding, which must be set to one of the three MODE_* values, except MODE_EXPLICIT.

Subclasses that do not support progressive encoding may ignore this value. The default is MODE_DEFAULT.

See Also:

MODE_DISABLED, MODE_EXPLICIT, MODE_DEFAULT, setProgressiveMode(int), getProgressiveMode()

canWriteCompressed

protected boolean canWriteCompressed

A boolean that is true if this writer can write images using compression. By default, the value is false. Subclasses must set the value manually.

Subclasses that do not support compression must ensure that this value is set to false.

compressionMode

protected int compressionMode

The mode controlling compression settings, which must be set to one of the three MODE_* values.

Subclasses that do not support compression may ignore this value. The default is MODE_DEFAULT.

See Also:

MODE_DISABLED, MODE_EXPLICIT, MODE_DEFAULT, setCompressionMode(int), getCompressionMode()

compressionTypes

protected java.lang.String[] compressionTypes

An array of Strings containing the names of the available compression types. Subclasses must set the value manually.

Subclasses that do not support compression may ignore this value.

compressionType

protected java.lang.String compressionType

A String containing the name of the current compression type, or null if none is set.

Subclasses that do not support compression may ignore this value.

compressionQuality

protected float compressionQuality

A float containing the current compression quality setting. The initial value is 1.0F.

Subclasses that do not support compression may ignore this value.

locale

protected java.util.Locale locale

A Locale to be used to localize compression type names and quality descriptions, or null to use a default Locale. Subclasses must set the value manually.

Constructor Detail

ImageWriteParam

protected ImageWriteParam()

Constructs an empty ImageWriteParam. It is up to the subclass to set up the instance variables properly.

ImageWriteParam

public ImageWriteParam(java.util.Locale locale)

Constructs an ImageWriteParam set to use a given Locale.

Parameters:

locale - a Locale to be used to localize compression type names and quality descriptions, or null.

Method Detail

getLocale

public java.util.Locale getLocale()

Returns the currently set Locale, or null if only a default Locale is supported.

Returns:

the current Locale, or null.

canWriteProgressive

public boolean canWriteProgressive()

Returns true if the writer can write out images as a series of passes of progressively increasing quality.

Returns:

true if the writer supports progressive encoding.

See Also:

setProgressiveMode(int), getProgressiveMode()

setProgressiveMode

public 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. If progressive encoding is not supported, an UnsupportedOperationException will be thrown.

The mode argument determines how the progression parameters are chosen, and must be either MODE_DISABLED, 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_DEFAULT - The image will be written progressively, with parameters chosen by the writer.

Parameters:

mode - The mode for setting progression in the output stream.

Throws:

java.lang.UnsupportedOperationException - if the writer does not support progressive encoding.

java.lang.IllegalArgumentException - if mode is not one of the modes listed above.

See Also:

getProgressiveMode()

getProgressiveMode

public int getProgressiveMode()

Returns the current mode for writing the stream in a progressive manner.

Returns:

the current mode for progressive encoding.

Throws:

java.lang.UnsupportedOperationException - if the writer does not support progressive encoding.

See Also:

setProgressiveMode(int)

canWriteCompressed

public boolean canWriteCompressed()

Returns true if this writer supports compression.

Returns:

true if the writer supports compression.

setCompressionMode

public void setCompressionMode(int mode)

Specifies whether compression is to be performed, and if so how compression parameters are to be determined. The mode argument must be one of the three modes, interpreted as follows:

• MODE_DISABLED - Do not compress. This may not be permitted by some writers, such as JPEG, which do not normally offer uncompressed output. The corresponding set and get methods will throw an IllegalStateException.
• MODE_EXPLICIT - Compress using the compression type and quality settings specified in this ImageWriteParam. Any previously set compression parameters are discarded.
• MODE_DEFAULT - Use default compression parameters.

Parameters:

mode - The mode for setting compression in the output stream.

Throws:

java.lang.UnsupportedOperationException - if the writer does not support compression, or does not support the requested mode.

java.lang.IllegalArgumentException - if mode is not one of the modes listed above.

See Also:

getCompressionMode()

getCompressionMode

public int getCompressionMode()

Returns the current compression mode, if compression is supported.

Returns:

the current compression mode.

Throws:

java.lang.UnsupportedOperationException - if the writer does not support compression.

See Also:

setCompressionMode(int)

getCompressionTypes

public java.lang.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. The array returned is a copy.

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:

java.lang.UnsupportedOperationException - if the writer does not support compression.

setCompressionType

public void setCompressionType(java.lang.String compressionType)

Sets the compression type to one of the values indicated by getCompressionTypes. If a value of null is passed in, any previous setting is removed.

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:

java.lang.UnsupportedOperationException - if the writer does not support compression.

java.lang.IllegalStateException - if the compression mode is not MODE_EXPLICIT.

java.lang.UnsupportedOperationException - if there are no settable compression types.

java.lang.IllegalArgumentException - if compressionType is non-null but is not one of the values returned by getCompressionTypes.

See Also:

getCompressionTypes(), getCompressionType(), unsetCompression()

getCompressionType

public java.lang.String getCompressionType()

Returns the currently set compression type, or null if none has been set. The type is returned as a String from among those returned by getCompressionTypes. If no compression type has been set, null is returned.

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:

java.lang.UnsupportedOperationException - if the writer does not support compression.

java.lang.IllegalStateException - if the compression mode is not MODE_EXPLICIT.

See Also:

setCompressionType(java.lang.String)

unsetCompression

public void unsetCompression()

Removes any previous compression type and quality settings.

The default implementation sets the instance variable compressionType to null, and the instance variable compressionQuality to 1.0F.

Throws:

java.lang.IllegalStateException - if the compression mode is not MODE_EXPLICIT.

See Also:

setCompressionType(java.lang.String), setCompressionQuality(float)

getLocalizedCompressionTypeName

public java.lang.String getLocalizedCompressionTypeName()

Returns a localized version of the name of the current compression type, using the Locale returned by getLocale.

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:

java.lang.UnsupportedOperationException - if the writer does not support compression.

java.lang.IllegalStateException - if the compression mode is not MODE_EXPLICIT.

java.lang.IllegalStateException - if no compression type is set.

isCompressionLossless

public boolean isCompressionLossless()

Returns true if the current compression type provides lossless compression.

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

The default implementation checks whether compression is supported and the compression mode is MODE_EXPLICIT. If so, if getCompressionTypes() is null or getCompressionType() is non-null true is returned as a convenience.

Returns:

true if the current compression type is lossless.

Throws:

java.lang.UnsupportedOperationException - if the writer does not support compression.

java.lang.IllegalStateException - if the compression mode is not MODE_EXPLICIT.

java.lang.IllegalStateException - if the set of legal compression types is non-null and the current compression type is null.

setCompressionQuality

public void setCompressionQuality(float quality)

Sets the compression quality to a value between 0 and 1. Only a single compression quality setting is supported by default; writers can provide extended versions of ImageWriteParam that offer more control. For lossy compression schemes, the compression quality should control the tradeoff between file size and image quality (for example, by choosing quantization tables when writing JPEG images). For lossless schemes, the compression quality may be used to control the tradeoff between file size and time taken to perform the compression (for example, by optimizing row filters and setting the ZLIB compression level when writing PNG images).

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:

java.lang.UnsupportedOperationException - if the writer does not support compression.

java.lang.IllegalStateException - if the compression mode is not MODE_EXPLICIT.

java.lang.IllegalStateException - if the set of legal compression types is non-null and the current compression type is null.

java.lang.IllegalArgumentException - if quality is not between 0and 1, inclusive.

See Also:

getCompressionQuality()

getCompressionQuality

public float getCompressionQuality()

Returns the current compression quality setting.

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:

java.lang.UnsupportedOperationException - if the writer does not support compression.

java.lang.IllegalStateException - if the compression mode is not MODE_EXPLICIT.

java.lang.IllegalStateException - if the set of legal compression types is non-null and the current compression type is null.

See Also:

setCompressionQuality(float)

getBitRate

public 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. The value will typically lie between 0 and 1, with smaller values indicating more compression. A special value of -1.0F is used to indicate that no estimate is available.

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.

Parameters:

quality - the quality setting whose bit rate is to be queried.

Returns:

an estimate of the compressed bit rate, or -1.0F if no estimate is available.

Throws:

java.lang.UnsupportedOperationException - if the writer does not support compression.

java.lang.IllegalStateException - if the compression mode is not MODE_EXPLICIT.

java.lang.IllegalStateException - if the set of legal compression types is non-null and the current compression type is null.

java.lang.IllegalArgumentException - if quality is not between 0and 1, inclusive.

getCompressionQualityDescriptions

public java.lang.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. The String with index i provides a description of the range of quality levels between getCompressionQualityValues[i] and getCompressionQualityValues[i + 1]. Note that the length of the array returned from getCompressionQualityValues will always be one greater than that returned from getCompressionQualityDescriptions.

As an example, the strings "Good", "Better", and "Best" could be associated with the ranges [0, .33), [.33, .66), and [.66, 1.0]. In this case, getCompressionQualityDescriptions would return { "Good", "Better", "Best" } and getCompressionQualityValues would return { 0.0F, .33F, .66F, 1.0F }.

If no descriptions are available, null is returned. If null is returned from getCompressionQualityValues, this method must also return null.

The descriptions should be localized for the Locale returned by getLocale, if it is non-null.

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

Returns:

an array of Strings containing localized descriptions of the compression quality levels.

Throws:

java.lang.UnsupportedOperationException - if the writer does not support compression.

java.lang.IllegalStateException - if the compression mode is not MODE_EXPLICIT.

java.lang.IllegalStateException - if the set of legal compression types is non-null and the current compression type is null.

See Also:

getCompressionQualityValues()

getCompressionQualityValues

public 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. See getCompressionQualityDescriptions for more information.

If no descriptions are available, null is returned. If null is returned from getCompressionQualityDescriptions, this method must also return null.

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

Returns:

an array of floats indicating the boundaries between the compression quality levels as described by the Strings from getCompressionQualityDescriptions.

Throws:

java.lang.UnsupportedOperationException - if the writer does not support compression.

java.lang.IllegalStateException - if the compression mode is not MODE_EXPLICIT.

java.lang.IllegalStateException - if the set of legal compression types is non-null and the current compression type is null.

See Also:

getCompressionQualityDescriptions()