Class ImageWriteParam
- Direct Known Subclasses:
BMPImageWriteParam
,JPEGImageWriteParam
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:
-
Field Summary
Modifier and TypeFieldDescriptionprotected boolean
Aboolean
that istrue
if thisImageWriteParam
allows tiling grid offset parameters to be set.protected boolean
Aboolean
that istrue
if this writer can write images using compression.protected boolean
Aboolean
that istrue
if thisImageWriteParam
allows images to be written as a progressive sequence of increasing quality passes.protected boolean
Aboolean
that istrue
if thisImageWriteParam
allows tile width and tile height parameters to be set.protected int
The mode controlling compression settings, which must be set to one of the fourMODE_*
values.protected float
Afloat
containing the current compression quality setting.protected String
AString
containing the name of the current compression type, ornull
if none is set.protected String[]
An array ofString
s containing the names of the available compression types.protected Locale
ALocale
to be used to localize compression type names and quality descriptions, ornull
to use a defaultLocale
.static final int
A constant value that may be passed into methods such assetTilingMode
,setProgressiveMode
, orsetCompressionMode
to enable that feature for future writes.static final int
A constant value that may be passed into methods such assetTilingMode
,setProgressiveMode
, andsetCompressionMode
to enable that feature for future writes.static final int
A constant value that may be passed into methods such assetTilingMode
,setProgressiveMode
, andsetCompressionMode
to disable a feature for future writes.static final int
A constant value that may be passed into methods such assetTilingMode
orsetCompressionMode
to enable a feature for future writes.protected Dimension[]
An array of preferred tile size range pairs.protected int
The mode controlling progressive encoding, which must be set to one of the fourMODE_*
values, exceptMODE_EXPLICIT
.protected int
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
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
The height of each tile if tiling has been set, or 0 otherwise.protected int
The width of each tile if tiling has been set, or 0 otherwise.protected int
The mode controlling tiling settings, which Must be set to one of the fourMODE_*
values.protected boolean
Aboolean
that istrue
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
ModifierConstructorDescriptionprotected
Constructs an emptyImageWriteParam
.ImageWriteParam
(Locale locale) Constructs anImageWriteParam
set to use a givenLocale
. -
Method Summary
Modifier and TypeMethodDescriptionboolean
Returnstrue
if the writer can perform tiling with non-zero grid offsets while writing.boolean
Returnstrue
if this writer supports compression.boolean
Returnstrue
if the writer can write out images as a series of passes of progressively increasing quality.boolean
Returnstrue
if the writer can perform tiling while writing.float
getBitRate
(float quality) Returns afloat
indicating an estimate of the number of bits of output data for each bit of input image data at the given quality level.int
Returns the current compression mode, if compression is supported.float
Returns the current compression quality setting.String[]
Returns an array ofString
s that may be used along withgetCompressionQualityValues
as part of a user interface for setting or displaying the compression quality level.float[]
Returns an array offloat
s that may be used along withgetCompressionQualityDescriptions
as part of a user interface for setting or displaying the compression quality level.Returns the currently set compression type, ornull
if none has been set.String[]
Returns a list of available compression types, as an array orString
s, ornull
if a compression type may not be chosen using these interfaces.Returns the currently setLocale
, ornull
if only a defaultLocale
is supported.Returns a localized version of the name of the current compression type, using theLocale
returned bygetLocale
.Returns an array ofDimension
s indicating the legal size ranges for tiles as they will be encoded in the output file or stream.int
Returns the current mode for writing the stream in a progressive manner.int
Returns the horizontal tile grid offset of an image as it will be written to the output stream.int
Returns the vertical tile grid offset of an image as it will be written to the output stream.int
Returns the height of each tile in an image as it will be written to the output stream.int
Returns the width of each tile in an image as it will be written to the output stream.int
Returns the current tiling mode, if tiling is supported.boolean
Returnstrue
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 between0
and1
.void
setCompressionType
(String compressionType) Sets the compression type to one of the values indicated bygetCompressionTypes
.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
Removes any previous compression type and quality settings.void
Removes any previous tile grid parameters specified by calls tosetTiling
.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
-
Field Details
-
MODE_DISABLED
public static final int MODE_DISABLEDA constant value that may be passed into methods such assetTilingMode
,setProgressiveMode
, andsetCompressionMode
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 anIllegalStateException
.- See Also:
-
MODE_DEFAULT
public static final int MODE_DEFAULTA constant value that may be passed into methods such assetTilingMode
,setProgressiveMode
, andsetCompressionMode
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 anIllegalStateException
.- See Also:
-
MODE_EXPLICIT
public static final int MODE_EXPLICITA constant value that may be passed into methods such assetTilingMode
orsetCompressionMode
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 correspondingset
methods in this class and retrievable from the correspondingget
methods. Note that this mode is not supported for progressive output.- See Also:
-
MODE_COPY_FROM_METADATA
public static final int MODE_COPY_FROM_METADATAA constant value that may be passed into methods such assetTilingMode
,setProgressiveMode
, orsetCompressionMode
to enable that feature for future writes. That is, when this mode is enabled the stream will be tiled, progressive, or compressed based on the contents of stream and/or image metadata passed into the write operation, and any relevant accessor methods will throw anIllegalStateException
.This is the default mode for all features, so that a read including metadata followed by a write including metadata will preserve as much information as possible.
- See Also:
-
canWriteTiles
protected boolean canWriteTilesAboolean
that istrue
if thisImageWriteParam
allows tile width and tile height parameters to be set. By default, the value isfalse
. Subclasses must set the value manually.Subclasses that do not support writing tiles should ensure that this value is set to
false
. -
tilingMode
protected int tilingModeThe mode controlling tiling settings, which Must be set to one of the fourMODE_*
values. The default isMODE_COPY_FROM_METADATA
.Subclasses that do not writing tiles may ignore this value.
- See Also:
-
preferredTileSizes
An array of preferred tile size range pairs. The default value isnull
, which indicates that there are no preferred sizes. If the value is non-null
, it must have an even length of at least two.Subclasses that do not support writing tiles may ignore this value.
- See Also:
-
tilingSet
protected boolean tilingSetAboolean
that istrue
if tiling parameters have been specified.Subclasses that do not support writing tiles may ignore this value.
-
tileWidth
protected int tileWidthThe width of each tile if tiling has been set, or 0 otherwise.Subclasses that do not support tiling may ignore this value.
-
tileHeight
protected int tileHeightThe height of each tile if tiling has been set, or 0 otherwise. The initial value is0
.Subclasses that do not support tiling may ignore this value.
-
canOffsetTiles
protected boolean canOffsetTilesAboolean
that istrue
if thisImageWriteParam
allows tiling grid offset parameters to be set. By default, the value isfalse
. Subclasses must set the value manually.Subclasses that do not support writing tiles, or that support writing but not offsetting tiles must ensure that this value is set to
false
. -
tileGridXOffset
protected int tileGridXOffsetThe amount by which the tile grid origin should be offset horizontally from the image origin if tiling has been set, or 0 otherwise. The initial value is0
.Subclasses that do not support offsetting tiles may ignore this value.
-
tileGridYOffset
protected int tileGridYOffsetThe amount by which the tile grid origin should be offset vertically from the image origin if tiling has been set, or 0 otherwise. The initial value is0
.Subclasses that do not support offsetting tiles may ignore this value.
-
canWriteProgressive
protected boolean canWriteProgressiveAboolean
that istrue
if thisImageWriteParam
allows images to be written as a progressive sequence of increasing quality passes. By default, the value isfalse
. 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 progressiveModeThe mode controlling progressive encoding, which must be set to one of the fourMODE_*
values, exceptMODE_EXPLICIT
. The default isMODE_COPY_FROM_METADATA
.Subclasses that do not support progressive encoding may ignore this value.
- See Also:
-
canWriteCompressed
protected boolean canWriteCompressedAboolean
that istrue
if this writer can write images using compression. By default, the value isfalse
. Subclasses must set the value manually.Subclasses that do not support compression must ensure that this value is set to
false
. -
compressionMode
protected int compressionModeThe mode controlling compression settings, which must be set to one of the fourMODE_*
values. The default isMODE_COPY_FROM_METADATA
.Subclasses that do not support compression may ignore this value.
- See Also:
-
compressionTypes
An array ofString
s 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
AString
containing the name of the current compression type, ornull
if none is set.Subclasses that do not support compression may ignore this value.
-
compressionQuality
protected float compressionQualityAfloat
containing the current compression quality setting. The initial value is1.0F
.Subclasses that do not support compression may ignore this value.
-
locale
ALocale
to be used to localize compression type names and quality descriptions, ornull
to use a defaultLocale
. Subclasses must set the value manually.
-
-
Constructor Details
-
ImageWriteParam
protected ImageWriteParam()Constructs an emptyImageWriteParam
. It is up to the subclass to set up the instance variables properly. -
ImageWriteParam
Constructs anImageWriteParam
set to use a givenLocale
.- Parameters:
locale
- aLocale
to be used to localize compression type names and quality descriptions, ornull
.
-
-
Method Details
-
getLocale
Returns the currently setLocale
, ornull
if only a defaultLocale
is supported.- Returns:
- the current
Locale
, ornull
.
-
canWriteTiles
public boolean canWriteTiles()Returnstrue
if the writer can perform tiling while writing. If this method returnsfalse
, thensetTiling
will throw anUnsupportedOperationException
.- Returns:
true
if the writer supports tiling.- See Also:
-
canOffsetTiles
public boolean canOffsetTiles()Returnstrue
if the writer can perform tiling with non-zero grid offsets while writing. If this method returnsfalse
, thensetTiling
will throw anUnsupportedOperationException
if the grid offset arguments are not both zero. IfcanWriteTiles
returnsfalse
, this method will returnfalse
as well.- Returns:
true
if the writer supports non-zero tile offsets.- See Also:
-
setTilingMode
public 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. The modes are interpreted as follows:MODE_DISABLED
- The image will not be tiled.setTiling
will throw anIllegalStateException
.MODE_DEFAULT
- The image will be tiled using default parameters.setTiling
will throw anIllegalStateException
.MODE_EXPLICIT
- The image will be tiled according to parameters given in thesetTiling
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 anIllegalStateException
.
- Parameters:
mode
- The mode to use for tiling.- Throws:
UnsupportedOperationException
- ifcanWriteTiles
returnsfalse
.IllegalArgumentException
- ifmode
is not one of the modes listed above.- See Also:
-
getTilingMode
public int getTilingMode()Returns the current tiling mode, if tiling is supported. Otherwise throws anUnsupportedOperationException
.- Returns:
- the current tiling mode.
- Throws:
UnsupportedOperationException
- ifcanWriteTiles
returnsfalse
.- See Also:
-
getPreferredTileSizes
Returns an array ofDimension
s indicating the legal size ranges for tiles as they will be encoded in the output file or stream. The returned array is a copy.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 ofDimension
s.If no array is specified on the constructor, but tiling is allowed, then this method returns
null
.- Returns:
- an array of
Dimension
s with an even length of at least two, ornull
. - Throws:
UnsupportedOperationException
- if the plug-in does not support tiling.
-
setTiling
public void setTiling(int tileWidth, int tileHeight, int tileGridXOffset, int tileGridYOffset) Specifies that the image should be tiled in the output stream. ThetileWidth
andtileHeight
parameters specify the width and height of the tiles in the file. If the tile width or height is greater than the width or height of the image, the image is not tiled in that dimension.If
canOffsetTiles
returnsfalse
, then thetileGridXOffset
andtileGridYOffset
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 notMODE_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 bygetPreferredTileSizes
.IllegalArgumentException
- iftileWidth
ortileHeight
is less than or equal to 0.- See Also:
-
unsetTiling
public void unsetTiling()Removes any previous tile grid parameters specified by calls tosetTiling
.The default implementation sets the instance variables
tileWidth
,tileHeight
,tileGridXOffset
, andtileGridYOffset
to0
.- Throws:
UnsupportedOperationException
- if the plug-in does not support tiling.IllegalStateException
- if the tiling mode is notMODE_EXPLICIT
.- See Also:
-
getTileWidth
public int getTileWidth()Returns the width of each tile in an image as it will be written to the output stream. If tiling parameters have not been set, anIllegalStateException
is thrown.- Returns:
- the tile width to be used for encoding.
- Throws:
UnsupportedOperationException
- if the plug-in does not support tiling.IllegalStateException
- if the tiling mode is notMODE_EXPLICIT
.IllegalStateException
- if the tiling parameters have not been set.- See Also:
-
getTileHeight
public int getTileHeight()Returns the height of each tile in an image as it will be written to the output stream. If tiling parameters have not been set, anIllegalStateException
is thrown.- Returns:
- the tile height to be used for encoding.
- Throws:
UnsupportedOperationException
- if the plug-in does not support tiling.IllegalStateException
- if the tiling mode is notMODE_EXPLICIT
.IllegalStateException
- if the tiling parameters have not been set.- See Also:
-
getTileGridXOffset
public int getTileGridXOffset()Returns the horizontal tile grid offset of an image as it will be written to the output stream. If tiling parameters have not been set, anIllegalStateException
is thrown.- Returns:
- the tile grid X offset to be used for encoding.
- Throws:
UnsupportedOperationException
- if the plug-in does not support tiling.IllegalStateException
- if the tiling mode is notMODE_EXPLICIT
.IllegalStateException
- if the tiling parameters have not been set.- See Also:
-
getTileGridYOffset
public int getTileGridYOffset()Returns the vertical tile grid offset of an image as it will be written to the output stream. If tiling parameters have not been set, anIllegalStateException
is thrown.- Returns:
- the tile grid Y offset to be used for encoding.
- Throws:
UnsupportedOperationException
- if the plug-in does not support tiling.IllegalStateException
- if the tiling mode is notMODE_EXPLICIT
.IllegalStateException
- if the tiling parameters have not been set.- See Also:
-
canWriteProgressive
public boolean canWriteProgressive()Returnstrue
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
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, anUnsupportedOperationException
will be thrown.The mode argument determines how the progression parameters are chosen, and must be either
MODE_DISABLED
,MODE_COPY_FROM_METADATA
, orMODE_DEFAULT
. Otherwise anIllegalArgumentException
is thrown.The modes are interpreted as follows:
MODE_DISABLED
- No progression. Use this to turn off progression.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
- ifmode
is not one of the modes listed above.- See Also:
-
getProgressiveMode
public int getProgressiveMode()Returns the current mode for writing the stream in a progressive manner.- Returns:
- the current mode for progressive encoding.
- Throws:
UnsupportedOperationException
- if the writer does not support progressive encoding.- See Also:
-
canWriteCompressed
public boolean canWriteCompressed()Returnstrue
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. Themode
argument must be one of the four modes, interpreted as follows:MODE_DISABLED
- If the mode is set toMODE_DISABLED
, methods that query or modify the compression type or parameters will throw anIllegalStateException
(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 toMODE_DISABLED
will throw anUnsupportedOperationException
and the mode will not be changed.MODE_EXPLICIT
- Compress using the compression type and quality settings specified in thisImageWriteParam
. 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
- ifmode
is not one of the modes listed above.- See Also:
-
getCompressionMode
public int getCompressionMode()Returns the current compression mode, if compression is supported.- Returns:
- the current compression mode.
- Throws:
UnsupportedOperationException
- if the writer does not support compression.- See Also:
-
getCompressionTypes
Returns a list of available compression types, as an array orString
s, ornull
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 thecompressionTypes
instance variable if it is non-null
, or else returnsnull
.- Returns:
- an array of
String
s containing the (non-localized) names of available compression types, ornull
. - Throws:
UnsupportedOperationException
- if the writer does not support compression.
-
setCompressionType
Sets the compression type to one of the values indicated bygetCompressionTypes
. If a value ofnull
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 callsgetCompressionTypes
and checks ifcompressionType
is one of the legal values. If it is, thecompressionType
instance variable is set. IfcompressionType
isnull
, the instance variable is set without performing any checking.- Parameters:
compressionType
- one of theString
s returned bygetCompressionTypes
, ornull
to remove any previous setting.- Throws:
UnsupportedOperationException
- if the writer does not support compression.IllegalStateException
- if the compression mode is notMODE_EXPLICIT
.UnsupportedOperationException
- if there are no settable compression types.IllegalArgumentException
- ifcompressionType
is non-null
but is not one of the values returned bygetCompressionTypes
.- See Also:
-
getCompressionType
Returns the currently set compression type, ornull
if none has been set. The type is returned as aString
from among those returned bygetCompressionTypes
. 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 thecompressionType
instance variable.- Returns:
- the current compression type as a
String
, ornull
if no type is set. - Throws:
UnsupportedOperationException
- if the writer does not support compression.IllegalStateException
- if the compression mode is notMODE_EXPLICIT
.- See Also:
-
unsetCompression
public void unsetCompression()Removes any previous compression type and quality settings.The default implementation sets the instance variable
compressionType
tonull
, and the instance variablecompressionQuality
to1.0F
.- Throws:
UnsupportedOperationException
- if the plug-in does not support compression.IllegalStateException
- if the compression mode is notMODE_EXPLICIT
.- See Also:
-
getLocalizedCompressionTypeName
Returns a localized version of the name of the current compression type, using theLocale
returned bygetLocale
.The default implementation checks whether compression is supported and the compression mode is
MODE_EXPLICIT
. If so, ifcompressionType
isnon-null
the value ofgetCompressionType
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 notMODE_EXPLICIT
.IllegalStateException
- if no compression type is set.
-
isCompressionLossless
public boolean isCompressionLossless()Returnstrue
if the current compression type provides lossless compression. If a plug-in provides only one mandatory compression type, then this method may be called without callingsetCompressionType
first.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, ifgetCompressionTypes()
isnull
orgetCompressionType()
is non-null
true
is returned as a convenience.- Returns:
true
if the current compression type is lossless.- Throws:
UnsupportedOperationException
- if the writer does not support compression.IllegalStateException
- if the compression mode is notMODE_EXPLICIT
.IllegalStateException
- if the set of legal compression types is non-null
and the current compression type isnull
.
-
setCompressionQuality
public void setCompressionQuality(float quality) Sets the compression quality to a value between0
and1
. Only a single compression quality setting is supported by default; writers can provide extended versions ofImageWriteParam
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, ifgetCompressionTypes()
returnsnull
orcompressionType
is non-null
it sets thecompressionQuality
instance variable.- Parameters:
quality
- afloat
between0
and1
indicating the desired quality level.- Throws:
UnsupportedOperationException
- if the writer does not support compression.IllegalStateException
- if the compression mode is notMODE_EXPLICIT
.IllegalStateException
- if the set of legal compression types is non-null
and the current compression type isnull
.IllegalArgumentException
- ifquality
is not between0
and1
, inclusive.- See Also:
-
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, ifgetCompressionTypes()
isnull
orgetCompressionType()
is non-null
, it returns the value of thecompressionQuality
instance variable.- Returns:
- the current compression quality setting.
- Throws:
UnsupportedOperationException
- if the writer does not support compression.IllegalStateException
- if the compression mode is notMODE_EXPLICIT
.IllegalStateException
- if the set of legal compression types is non-null
and the current compression type isnull
.- See Also:
-
getBitRate
public float getBitRate(float quality) Returns afloat
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 between0
and1
, 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, ifgetCompressionTypes()
isnull
orgetCompressionType()
is non-null
, andquality
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:
UnsupportedOperationException
- if the writer does not support compression.IllegalStateException
- if the compression mode is notMODE_EXPLICIT
.IllegalStateException
- if the set of legal compression types is non-null
and the current compression type isnull
.IllegalArgumentException
- ifquality
is not between0
and1
, inclusive.
-
getCompressionQualityDescriptions
Returns an array ofString
s that may be used along withgetCompressionQualityValues
as part of a user interface for setting or displaying the compression quality level. TheString
with indexi
provides a description of the range of quality levels betweengetCompressionQualityValues[i]
andgetCompressionQualityValues[i + 1]
. Note that the length of the array returned fromgetCompressionQualityValues
will always be one greater than that returned fromgetCompressionQualityDescriptions
.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" }
andgetCompressionQualityValues
would return{ 0.0F, .33F, .66F, 1.0F }
.If no descriptions are available,
null
is returned. Ifnull
is returned fromgetCompressionQualityValues
, this method must also returnnull
.The descriptions should be localized for the
Locale
returned bygetLocale
, 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, ifgetCompressionTypes()
isnull
orgetCompressionType()
is non-null
, it returnsnull
.- Returns:
- an array of
String
s containing localized descriptions of the compression quality levels. - Throws:
UnsupportedOperationException
- if the writer does not support compression.IllegalStateException
- if the compression mode is notMODE_EXPLICIT
.IllegalStateException
- if the set of legal compression types is non-null
and the current compression type isnull
.- See Also:
-
getCompressionQualityValues
public float[] getCompressionQualityValues()Returns an array offloat
s that may be used along withgetCompressionQualityDescriptions
as part of a user interface for setting or displaying the compression quality level. SeegetCompressionQualityDescriptions
for more information.If no descriptions are available,
null
is returned. Ifnull
is returned fromgetCompressionQualityDescriptions
, this method must also returnnull
.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, ifgetCompressionTypes()
isnull
orgetCompressionType()
is non-null
, it returnsnull
.- Returns:
- an array of
float
s indicating the boundaries between the compression quality levels as described by theString
s fromgetCompressionQualityDescriptions
. - Throws:
UnsupportedOperationException
- if the writer does not support compression.IllegalStateException
- if the compression mode is notMODE_EXPLICIT
.IllegalStateException
- if the set of legal compression types is non-null
and the current compression type isnull
.- See Also:
-