/*
* Copyright (c) 2000, 2014, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package javax.imageio;
import java.awt.Dimension;
import java.util.Locale;
/**
* 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 {@code ImageWriter}.
*
* <p> A plug-in for a specific image format may define a subclass of
* this class, and return objects of that class from the
* {@code getDefaultWriteParam} method of its
* {@code ImageWriter} implementation. For example, the built-in
* JPEG writer plug-in will return instances of
* {@code javax.imageio.plugins.jpeg.JPEGImageWriteParam}.
*
* <p> The region of the image to be written is determined by first
* intersecting the actual bounds of the image with the rectangle
* specified by {@code IIOParam.setSourceRegion}, if any. If the
* resulting rectangle has a width or height of zero, the writer will
* throw an {@code 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 {@link IIOParam#setSourceSubsampling
* IIOParam.setSourceSubsampling}.
*
* <p> Individual features such as tiling, progressive encoding, and
* compression may be set in one of four modes.
* {@code MODE_DISABLED} disables the features;
* {@code MODE_DEFAULT} enables the feature with
* writer-controlled parameter values; {@code MODE_EXPLICIT}
* enables the feature and allows the use of a {@code set} method
* to provide additional parameters; and
* {@code 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
* {@code MODE_COPY_FROM_METADATA}. Non-standard features
* supplied in subclasses are encouraged, but not required to use a
* similar scheme.
*
* <p> Plug-in writers may extend the functionality of
* {@code 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
* {@code ImageWriteParam} subclass of which they are not aware.
* Also, they may ignore any optional features that they normally
* disable when creating their own {@code ImageWriteParam}
* instances via {@code getDefaultWriteParam}.
*
* <p> Note that unless a query method exists for a capability, it must
* be supported by all {@code ImageWriter} implementations
* (<i>e.g.</i> progressive encoding is optional, but subsampling must be
* supported).
*
*
* @see ImageReadParam
*/
public class ImageWriteParam extends IIOParam {
/**
* A constant value that may be passed into methods such as
* {@code setTilingMode}, {@code setProgressiveMode},
* and {@code setCompressionMode} to disable a feature for
* future writes. That is, when this mode is set the stream will
* <b>not</b> be tiled, progressive, or compressed, and the
* relevant accessor methods will throw an
* {@code IllegalStateException}.
*
* @see #MODE_EXPLICIT
* @see #MODE_COPY_FROM_METADATA
* @see #MODE_DEFAULT
* @see #setProgressiveMode
* @see #getProgressiveMode
* @see #setTilingMode
* @see #getTilingMode
* @see #setCompressionMode
* @see #getCompressionMode
*/
public static final int MODE_DISABLED = 0;
/**
* A constant value that may be passed into methods such as
* {@code setTilingMode},
* {@code setProgressiveMode}, and
* {@code 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 {@code IllegalStateException}.
*
* @see #MODE_DISABLED
* @see #MODE_EXPLICIT
* @see #MODE_COPY_FROM_METADATA
* @see #setProgressiveMode
* @see #getProgressiveMode
* @see #setTilingMode
* @see #getTilingMode
* @see #setCompressionMode
* @see #getCompressionMode
*/
public static final int MODE_DEFAULT = 1;
/**
* A constant value that may be passed into methods such as
* {@code setTilingMode} or {@code 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
* {@code set} methods in this class and retrievable from the
* corresponding {@code get} methods. Note that this mode is
* not supported for progressive output.
*
* @see #MODE_DISABLED
* @see #MODE_COPY_FROM_METADATA
* @see #MODE_DEFAULT
* @see #setProgressiveMode
* @see #getProgressiveMode
* @see #setTilingMode
* @see #getTilingMode
* @see #setCompressionMode
* @see #getCompressionMode
*/
public static final int MODE_EXPLICIT = 2;
/**
* A constant value that may be passed into methods such as
* {@code setTilingMode}, {@code setProgressiveMode}, or
* {@code setCompressionMode} 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 an
* {@code IllegalStateException}.
*
* <p> 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 #MODE_DISABLED
* @see #MODE_EXPLICIT
* @see #MODE_DEFAULT
* @see #setProgressiveMode
* @see #getProgressiveMode
* @see #setTilingMode
* @see #getTilingMode
* @see #setCompressionMode
* @see #getCompressionMode
*/
public static final int MODE_COPY_FROM_METADATA = 3;
// If more modes are added, this should be updated.
private static final int MAX_MODE = MODE_COPY_FROM_METADATA;
/**
* A {@code boolean} that is {@code true} if this
* {@code ImageWriteParam} allows tile width and tile height
* parameters to be set. By default, the value is
* {@code false}. Subclasses must set the value manually.
*
* <p> Subclasses that do not support writing tiles should ensure
* that this value is set to {@code false}.
*/
protected boolean canWriteTiles = false;
/**
* The mode controlling tiling settings, which Must be
* set to one of the four {@code MODE_*} values. The default
* is {@code MODE_COPY_FROM_METADATA}.
*
* <p> Subclasses that do not writing tiles may ignore this value.
*
* @see #MODE_DISABLED
* @see #MODE_EXPLICIT
* @see #MODE_COPY_FROM_METADATA
* @see #MODE_DEFAULT
* @see #setTilingMode
* @see #getTilingMode
*/
protected int tilingMode = MODE_COPY_FROM_METADATA;
/**
* An array of preferred tile size range pairs. The default value
* is {@code null}, which indicates that there are no
* preferred sizes. If the value is non-{@code null}, it
* must have an even length of at least two.
*
* <p> Subclasses that do not support writing tiles may ignore
* this value.
*
* @see #getPreferredTileSizes
*/
protected Dimension[] preferredTileSizes = null;
/**
* A {@code boolean} that is {@code true} if tiling
* parameters have been specified.
*
* <p> Subclasses that do not support writing tiles may ignore
* this value.
*/
protected boolean tilingSet = false;
/**
* The width of each tile if tiling has been set, or 0 otherwise.
*
* <p> Subclasses that do not support tiling may ignore this
* value.
*/
protected int tileWidth = 0;
/**
* The height of each tile if tiling has been set, or 0 otherwise.
* The initial value is {@code 0}.
*
* <p> Subclasses that do not support tiling may ignore this
* value.
*/
protected int tileHeight = 0;
/**
* A {@code boolean} that is {@code true} if this
* {@code ImageWriteParam} allows tiling grid offset
* parameters to be set. By default, the value is
* {@code false}. Subclasses must set the value manually.
*
* <p> Subclasses that do not support writing tiles, or that
* support writing but not offsetting tiles must ensure that this
* value is set to {@code false}.
*/
protected boolean canOffsetTiles = false;
/**
* The 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 is {@code 0}.
*
* <p> Subclasses that do not support offsetting tiles may ignore
* this value.
*/
protected int tileGridXOffset = 0;
/**
* The 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 is {@code 0}.
*
* <p> Subclasses that do not support offsetting tiles may ignore
* this value.
*/
protected int tileGridYOffset = 0;
/**
* A {@code boolean} that is {@code true} if this
* {@code ImageWriteParam} allows images to be written as a
* progressive sequence of increasing quality passes. By default,
* the value is {@code false}. Subclasses must set the value
* manually.
*
* <p> Subclasses that do not support progressive encoding must
* ensure that this value is set to {@code false}.
*/
protected boolean canWriteProgressive = false;
/**
* The mode controlling progressive encoding, which must be set to
* one of the four {@code MODE_*} values, except
* {@code MODE_EXPLICIT}. The default is
* {@code MODE_COPY_FROM_METADATA}.
*
* <p> Subclasses that do not support progressive encoding may
* ignore this value.
*
* @see #MODE_DISABLED
* @see #MODE_EXPLICIT
* @see #MODE_COPY_FROM_METADATA
* @see #MODE_DEFAULT
* @see #setProgressiveMode
* @see #getProgressiveMode
*/
protected int progressiveMode = MODE_COPY_FROM_METADATA;
/**
* A {@code boolean} that is {@code true} if this writer
* can write images using compression. By default, the value is
* {@code false}. Subclasses must set the value manually.
*
* <p> Subclasses that do not support compression must ensure that
* this value is set to {@code false}.
*/
protected boolean canWriteCompressed = false;
/**
* The mode controlling compression settings, which must be set to
* one of the four {@code MODE_*} values. The default is
* {@code MODE_COPY_FROM_METADATA}.
*
* <p> Subclasses that do not support compression may ignore this
* value.
*
* @see #MODE_DISABLED
* @see #MODE_EXPLICIT
* @see #MODE_COPY_FROM_METADATA
* @see #MODE_DEFAULT
* @see #setCompressionMode
* @see #getCompressionMode
*/
protected int compressionMode = MODE_COPY_FROM_METADATA;
/**
* An array of {@code String}s containing the names of the
* available compression types. Subclasses must set the value
* manually.
*
* <p> Subclasses that do not support compression may ignore this
* value.
*/
protected String[] compressionTypes = null;
/**
* A {@code String} containing the name of the current
* compression type, or {@code null} if none is set.
*
* <p> Subclasses that do not support compression may ignore this
* value.
*/
protected String compressionType = null;
/**
* A {@code float} containing the current compression quality
* setting. The initial value is {@code 1.0F}.
*
* <p> Subclasses that do not support compression may ignore this
* value.
*/
protected float compressionQuality = 1.0F;
/**
* A {@code Locale} to be used to localize compression type
* names and quality descriptions, or {@code null} to use a
* default {@code Locale}. Subclasses must set the value
* manually.
*/
protected Locale locale = null;
/**
* Constructs an empty {@code ImageWriteParam}. It is up to
* the subclass to set up the instance variables properly.
*/
protected ImageWriteParam() {}
/**
* Constructs an {@code ImageWriteParam} set to use a
* given {@code Locale}.
*
* @param locale a {@code Locale} to be used to localize
* compression type names and quality descriptions, or
* {@code null}.
*/
public ImageWriteParam(Locale locale) {
this.locale = locale;
}
// Return a deep copy of the array
private static Dimension[] clonePreferredTileSizes(Dimension[] sizes) {
if (sizes == null) {
return null;
}
Dimension[] temp = new Dimension[sizes.length];
for (int i = 0; i < sizes.length; i++) {
temp[i] = new Dimension(sizes[i]);
}
return temp;
}
/**
* Returns the currently set {@code Locale}, or
* {@code null} if only a default {@code Locale} is
* supported.
*
* @return the current {@code Locale}, or {@code null}.
*/
public Locale getLocale() {
return locale;
}
/**
* Returns {@code true} if the writer can perform tiling
* while writing. If this method returns {@code false}, then
* {@code setTiling} will throw an
* {@code UnsupportedOperationException}.
*
* @return {@code true} if the writer supports tiling.
*
* @see #canOffsetTiles()
* @see #setTiling(int, int, int, int)
*/
public boolean canWriteTiles() {
return canWriteTiles;
}
/**
* Returns {@code true} if the writer can perform tiling with
* non-zero grid offsets while writing. If this method returns
* {@code false}, then {@code setTiling} will throw an
* {@code UnsupportedOperationException} if the grid offset
* arguments are not both zero. If {@code canWriteTiles}
* returns {@code false}, this method will return
* {@code false} as well.
*
* @return {@code true} if the writer supports non-zero tile
* offsets.
*
* @see #canWriteTiles()
* @see #setTiling(int, int, int, int)
*/
public boolean canOffsetTiles() {
return canOffsetTiles;
}
/**
* 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:
*
* <ul>
*
* <li>{@code MODE_DISABLED} - The image will not be tiled.
* {@code setTiling} will throw an
* {@code IllegalStateException}.
*
* <li>{@code MODE_DEFAULT} - The image will be tiled using
* default parameters. {@code setTiling} will throw an
* {@code IllegalStateException}.
*
* <li>{@code MODE_EXPLICIT} - The image will be tiled
* according to parameters given in the {@link #setTiling setTiling}
* method. Any previously set tiling parameters are discarded.
*
* <li>{@code MODE_COPY_FROM_METADATA} - The image will
* conform to the metadata object passed in to a write.
* {@code setTiling} will throw an
* {@code IllegalStateException}.
*
* </ul>
*
* @param mode The mode to use for tiling.
*
* @exception UnsupportedOperationException if
* {@code canWriteTiles} returns {@code false}.
* @exception IllegalArgumentException if {@code mode} is not
* one of the modes listed above.
*
* @see #setTiling
* @see #getTilingMode
*/
public void setTilingMode(int mode) {
if (canWriteTiles() == false) {
throw new UnsupportedOperationException("Tiling not supported!");
}
if (mode < MODE_DISABLED || mode > MAX_MODE) {
throw new IllegalArgumentException("Illegal value for mode!");
}
this.tilingMode = mode;
if (mode == MODE_EXPLICIT) {
unsetTiling();
}
}
/**
* Returns the current tiling mode, if tiling is supported.
* Otherwise throws an {@code UnsupportedOperationException}.
*
* @return the current tiling mode.
*
* @exception UnsupportedOperationException if
* {@code canWriteTiles} returns {@code false}.
*
* @see #setTilingMode
*/
public int getTilingMode() {
if (!canWriteTiles()) {
throw new UnsupportedOperationException("Tiling not supported");
}
return tilingMode;
}
/**
* Returns an array of {@code Dimension}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.
*
* <p> 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
* {@code null} is used in place of an actual array of
* {@code Dimension}s.
*
* <p> If no array is specified on the constructor, but tiling is
* allowed, then this method returns {@code null}.
*
* @exception UnsupportedOperationException if the plug-in does
* not support tiling.
*
* @return an array of {@code Dimension}s with an even length
* of at least two, or {@code null}.
*/
public Dimension[] getPreferredTileSizes() {
if (!canWriteTiles()) {
throw new UnsupportedOperationException("Tiling not supported");
}
return clonePreferredTileSizes(preferredTileSizes);
}
/**
* Specifies that the image should be tiled in the output stream.
* The {@code tileWidth} and {@code tileHeight}
* 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.
*
* <p> If {@code canOffsetTiles} returns {@code false},
* then the {@code tileGridXOffset} and
* {@code tileGridYOffset} parameters must be zero.
*
* @param tileWidth the width of each tile.
* @param tileHeight the height of each tile.
* @param tileGridXOffset the horizontal offset of the tile grid.
* @param tileGridYOffset the vertical offset of the tile grid.
*
* @exception UnsupportedOperationException if the plug-in does not
* support tiling.
* @exception IllegalStateException if the tiling mode is not
* {@code MODE_EXPLICIT}.
* @exception UnsupportedOperationException if the plug-in does not
* support grid offsets, and the grid offsets are not both zero.
* @exception IllegalArgumentException if the tile size is not
* within one of the allowable ranges returned by
* {@code getPreferredTileSizes}.
* @exception IllegalArgumentException if {@code tileWidth}
* or {@code tileHeight} is less than or equal to 0.
*
* @see #canWriteTiles
* @see #canOffsetTiles
* @see #getTileWidth()
* @see #getTileHeight()
* @see #getTileGridXOffset()
* @see #getTileGridYOffset()
*/
public void setTiling(int tileWidth,
int tileHeight,
int tileGridXOffset,
int tileGridYOffset) {
if (!canWriteTiles()) {
throw new UnsupportedOperationException("Tiling not supported!");
}
if (getTilingMode() != MODE_EXPLICIT) {
throw new IllegalStateException("Tiling mode not MODE_EXPLICIT!");
}
if (tileWidth <= 0 || tileHeight <= 0) {
throw new IllegalArgumentException
("tile dimensions are non-positive!");
}
boolean tilesOffset = (tileGridXOffset != 0) || (tileGridYOffset != 0);
if (!canOffsetTiles() && tilesOffset) {
throw new UnsupportedOperationException("Can't offset tiles!");
}
if (preferredTileSizes != null) {
boolean ok = true;
for (int i = 0; i < preferredTileSizes.length; i += 2) {
Dimension min = preferredTileSizes[i];
Dimension max = preferredTileSizes[i+1];
if ((tileWidth < min.width) ||
(tileWidth > max.width) ||
(tileHeight < min.height) ||
(tileHeight > max.height)) {
ok = false;
break;
}
}
if (!ok) {
throw new IllegalArgumentException("Illegal tile size!");
}
}
this.tilingSet = true;
this.tileWidth = tileWidth;
this.tileHeight = tileHeight;
this.tileGridXOffset = tileGridXOffset;
this.tileGridYOffset = tileGridYOffset;
}
/**
* Removes any previous tile grid parameters specified by calls to
* {@code setTiling}.
*
* <p> The default implementation sets the instance variables
* {@code tileWidth}, {@code tileHeight},
* {@code tileGridXOffset}, and
* {@code tileGridYOffset} to {@code 0}.
*
* @exception UnsupportedOperationException if the plug-in does not
* support tiling.
* @exception IllegalStateException if the tiling mode is not
* {@code MODE_EXPLICIT}.
*
* @see #setTiling(int, int, int, int)
*/
public void unsetTiling() {
if (!canWriteTiles()) {
throw new UnsupportedOperationException("Tiling not supported!");
}
if (getTilingMode() != MODE_EXPLICIT) {
throw new IllegalStateException("Tiling mode not MODE_EXPLICIT!");
}
this.tilingSet = false;
this.tileWidth = 0;
this.tileHeight = 0;
this.tileGridXOffset = 0;
this.tileGridYOffset = 0;
}
/**
* 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, an {@code IllegalStateException} is thrown.
*
* @return the tile width to be used for encoding.
*
* @exception UnsupportedOperationException if the plug-in does not
* support tiling.
* @exception IllegalStateException if the tiling mode is not
* {@code MODE_EXPLICIT}.
* @exception IllegalStateException if the tiling parameters have
* not been set.
*
* @see #setTiling(int, int, int, int)
* @see #getTileHeight()
*/
public int getTileWidth() {
if (!canWriteTiles()) {
throw new UnsupportedOperationException("Tiling not supported!");
}
if (getTilingMode() != MODE_EXPLICIT) {
throw new IllegalStateException("Tiling mode not MODE_EXPLICIT!");
}
if (!tilingSet) {
throw new IllegalStateException("Tiling parameters not set!");
}
return tileWidth;
}
/**
* 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, an {@code IllegalStateException} is thrown.
*
* @return the tile height to be used for encoding.
*
* @exception UnsupportedOperationException if the plug-in does not
* support tiling.
* @exception IllegalStateException if the tiling mode is not
* {@code MODE_EXPLICIT}.
* @exception IllegalStateException if the tiling parameters have
* not been set.
*
* @see #setTiling(int, int, int, int)
* @see #getTileWidth()
*/
public int getTileHeight() {
if (!canWriteTiles()) {
throw new UnsupportedOperationException("Tiling not supported!");
}
if (getTilingMode() != MODE_EXPLICIT) {
throw new IllegalStateException("Tiling mode not MODE_EXPLICIT!");
}
if (!tilingSet) {
throw new IllegalStateException("Tiling parameters not set!");
}
return tileHeight;
}
/**
* 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, an {@code IllegalStateException} is thrown.
*
* @return the tile grid X offset to be used for encoding.
*
* @exception UnsupportedOperationException if the plug-in does not
* support tiling.
* @exception IllegalStateException if the tiling mode is not
* {@code MODE_EXPLICIT}.
* @exception IllegalStateException if the tiling parameters have
* not been set.
*
* @see #setTiling(int, int, int, int)
* @see #getTileGridYOffset()
*/
public int getTileGridXOffset() {
if (!canWriteTiles()) {
throw new UnsupportedOperationException("Tiling not supported!");
}
if (getTilingMode() != MODE_EXPLICIT) {
throw new IllegalStateException("Tiling mode not MODE_EXPLICIT!");
}
if (!tilingSet) {
throw new IllegalStateException("Tiling parameters not set!");
}
return tileGridXOffset;
}
/**
* 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, an {@code IllegalStateException} is thrown.
*
* @return the tile grid Y offset to be used for encoding.
*
* @exception UnsupportedOperationException if the plug-in does not
* support tiling.
* @exception IllegalStateException if the tiling mode is not
* {@code MODE_EXPLICIT}.
* @exception IllegalStateException if the tiling parameters have
* not been set.
*
* @see #setTiling(int, int, int, int)
* @see #getTileGridXOffset()
*/
public int getTileGridYOffset() {
if (!canWriteTiles()) {
throw new UnsupportedOperationException("Tiling not supported!");
}
if (getTilingMode() != MODE_EXPLICIT) {
throw new IllegalStateException("Tiling mode not MODE_EXPLICIT!");
}
if (!tilingSet) {
throw new IllegalStateException("Tiling parameters not set!");
}
return tileGridYOffset;
}
/**
* Returns {@code true} if the writer can write out images
* as a series of passes of progressively increasing quality.
*
* @return {@code true} if the writer supports progressive
* encoding.
*
* @see #setProgressiveMode
* @see #getProgressiveMode
*/
public boolean canWriteProgressive() {
return canWriteProgressive;
}
/**
* 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 {@code UnsupportedOperationException} will
* be thrown.
*
* <p> The mode argument determines how
* the progression parameters are chosen, and must be either
* {@code MODE_DISABLED},
* {@code MODE_COPY_FROM_METADATA}, or
* {@code MODE_DEFAULT}. Otherwise an
* {@code IllegalArgumentException} is thrown.
*
* <p> The modes are interpreted as follows:
*
* <ul>
* <li>{@code MODE_DISABLED} - No progression. Use this to
* turn off progression.
*
* <li>{@code MODE_COPY_FROM_METADATA} - The output image
* will use whatever progression parameters are found in the
* metadata objects passed into the writer.
*
* <li>{@code MODE_DEFAULT} - The image will be written
* progressively, with parameters chosen by the writer.
* </ul>
*
* <p> The default is {@code MODE_COPY_FROM_METADATA}.
*
* @param mode The mode for setting progression in the output
* stream.
*
* @exception UnsupportedOperationException if the writer does not
* support progressive encoding.
* @exception IllegalArgumentException if {@code mode} is not
* one of the modes listed above.
*
* @see #getProgressiveMode
*/
public void setProgressiveMode(int mode) {
if (!canWriteProgressive()) {
throw new UnsupportedOperationException(
"Progressive output not supported");
}
if (mode < MODE_DISABLED || mode > MAX_MODE) {
throw new IllegalArgumentException("Illegal value for mode!");
}
if (mode == MODE_EXPLICIT) {
throw new IllegalArgumentException(
"MODE_EXPLICIT not supported for progressive output");
}
this.progressiveMode = mode;
}
/**
* Returns the current mode for writing the stream in a
* progressive manner.
*
* @return the current mode for progressive encoding.
*
* @exception UnsupportedOperationException if the writer does not
* support progressive encoding.
*
* @see #setProgressiveMode
*/
public int getProgressiveMode() {
if (!canWriteProgressive()) {
throw new UnsupportedOperationException
("Progressive output not supported");
}
return progressiveMode;
}
/**
* Returns {@code true} if this writer supports compression.
*
* @return {@code true} if the writer supports compression.
*/
public boolean canWriteCompressed() {
return canWriteCompressed;
}
/**
* Specifies whether compression is to be performed, and if so how
* compression parameters are to be determined. The {@code mode}
* argument must be one of the four modes, interpreted as follows:
*
* <ul>
* <li>{@code MODE_DISABLED} - If the mode is set to
* {@code MODE_DISABLED}, methods that query or modify the
* compression type or parameters will throw an
* {@code 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 {@code MODE_DISABLED} will throw an
* {@code UnsupportedOperationException} and the mode will not be
* changed.
*
* <li>{@code MODE_EXPLICIT} - Compress using the
* compression type and quality settings specified in this
* {@code ImageWriteParam}. Any previously set compression
* parameters are discarded.
*
* <li>{@code MODE_COPY_FROM_METADATA} - Use whatever
* compression parameters are specified in metadata objects
* passed in to the writer.
*
* <li>{@code MODE_DEFAULT} - Use default compression
* parameters.
* </ul>
*
* <p> The default is {@code MODE_COPY_FROM_METADATA}.
*
* @param mode The mode for setting compression in the output
* stream.
*
* @exception UnsupportedOperationException if the writer does not
* support compression, or does not support the requested mode.
* @exception IllegalArgumentException if {@code mode} is not
* one of the modes listed above.
*
* @see #getCompressionMode
*/
public void setCompressionMode(int mode) {
if (!canWriteCompressed()) {
throw new UnsupportedOperationException(
"Compression not supported.");
}
if (mode < MODE_DISABLED || mode > MAX_MODE) {
throw new IllegalArgumentException("Illegal value for mode!");
}
this.compressionMode = mode;
if (mode == MODE_EXPLICIT) {
unsetCompression();
}
}
/**
* Returns the current compression mode, if compression is
* supported.
*
* @return the current compression mode.
*
* @exception UnsupportedOperationException if the writer does not
* support compression.
*
* @see #setCompressionMode
*/
public int getCompressionMode() {
if (!canWriteCompressed()) {
throw new UnsupportedOperationException(
"Compression not supported.");
}
return compressionMode;
}
/**
* Returns a list of available compression types, as an array or
* {@code String}s, or {@code null} if a compression
* type may not be chosen using these interfaces. The array
* returned is a copy.
*
* <p> 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.
*
* <p> The default implementation checks if compression is
* supported and throws an
* {@code UnsupportedOperationException} if not. Otherwise,
* it returns a clone of the {@code compressionTypes}
* instance variable if it is non-{@code null}, or else
* returns {@code null}.
*
* @return an array of {@code String}s containing the
* (non-localized) names of available compression types, or
* {@code null}.
*
* @exception UnsupportedOperationException if the writer does not
* support compression.
*/
public String[] getCompressionTypes() {
if (!canWriteCompressed()) {
throw new UnsupportedOperationException(
"Compression not supported");
}
if (compressionTypes == null) {
return null;
}
return compressionTypes.clone();
}
/**
* Sets the compression type to one of the values indicated by
* {@code getCompressionTypes}. If a value of
* {@code null} is passed in, any previous setting is
* removed.
*
* <p> The default implementation checks whether compression is
* supported and the compression mode is
* {@code MODE_EXPLICIT}. If so, it calls
* {@code getCompressionTypes} and checks if
* {@code compressionType} is one of the legal values. If it
* is, the {@code compressionType} instance variable is set.
* If {@code compressionType} is {@code null}, the
* instance variable is set without performing any checking.
*
* @param compressionType one of the {@code String}s returned
* by {@code getCompressionTypes}, or {@code null} to
* remove any previous setting.
*
* @exception UnsupportedOperationException if the writer does not
* support compression.
* @exception IllegalStateException if the compression mode is not
* {@code MODE_EXPLICIT}.
* @exception UnsupportedOperationException if there are no
* settable compression types.
* @exception IllegalArgumentException if
* {@code compressionType} is non-{@code null} but is not
* one of the values returned by {@code getCompressionTypes}.
*
* @see #getCompressionTypes
* @see #getCompressionType
* @see #unsetCompression
*/
public void setCompressionType(String compressionType) {
if (!canWriteCompressed()) {
throw new UnsupportedOperationException(
"Compression not supported");
}
if (getCompressionMode() != MODE_EXPLICIT) {
throw new IllegalStateException
("Compression mode not MODE_EXPLICIT!");
}
String[] legalTypes = getCompressionTypes();
if (legalTypes == null) {
throw new UnsupportedOperationException(
"No settable compression types");
}
if (compressionType != null) {
boolean found = false;
if (legalTypes != null) {
for (int i = 0; i < legalTypes.length; i++) {
if (compressionType.equals(legalTypes[i])) {
found = true;
break;
}
}
}
if (!found) {
throw new IllegalArgumentException("Unknown compression type!");
}
}
this.compressionType = compressionType;
}
/**
* Returns the currently set compression type, or
* {@code null} if none has been set. The type is returned
* as a {@code String} from among those returned by
* {@code getCompressionTypes}.
* If no compression type has been set, {@code null} is
* returned.
*
* <p> The default implementation checks whether compression is
* supported and the compression mode is
* {@code MODE_EXPLICIT}. If so, it returns the value of the
* {@code compressionType} instance variable.
*
* @return the current compression type as a {@code String},
* or {@code null} if no type is set.
*
* @exception UnsupportedOperationException if the writer does not
* support compression.
* @exception IllegalStateException if the compression mode is not
* {@code MODE_EXPLICIT}.
*
* @see #setCompressionType
*/
public String getCompressionType() {
if (!canWriteCompressed()) {
throw new UnsupportedOperationException(
"Compression not supported.");
}
if (getCompressionMode() != MODE_EXPLICIT) {
throw new IllegalStateException
("Compression mode not MODE_EXPLICIT!");
}
return compressionType;
}
/**
* Removes any previous compression type and quality settings.
*
* <p> The default implementation sets the instance variable
* {@code compressionType} to {@code null}, and the
* instance variable {@code compressionQuality} to
* {@code 1.0F}.
*
* @exception UnsupportedOperationException if the plug-in does not
* support compression.
* @exception IllegalStateException if the compression mode is not
* {@code MODE_EXPLICIT}.
*
* @see #setCompressionType
* @see #setCompressionQuality
*/
public void unsetCompression() {
if (!canWriteCompressed()) {
throw new UnsupportedOperationException(
"Compression not supported");
}
if (getCompressionMode() != MODE_EXPLICIT) {
throw new IllegalStateException
("Compression mode not MODE_EXPLICIT!");
}
this.compressionType = null;
this.compressionQuality = 1.0F;
}
/**
* Returns a localized version of the name of the current
* compression type, using the {@code Locale} returned by
* {@code getLocale}.
*
* <p> The default implementation checks whether compression is
* supported and the compression mode is
* {@code MODE_EXPLICIT}. If so, if
* {@code compressionType} is {@code non-null} the value
* of {@code getCompressionType} is returned as a
* convenience.
*
* @return a {@code String} containing a localized version of
* the name of the current compression type.
*
* @exception UnsupportedOperationException if the writer does not
* support compression.
* @exception IllegalStateException if the compression mode is not
* {@code MODE_EXPLICIT}.
* @exception IllegalStateException if no compression type is set.
*/
public String getLocalizedCompressionTypeName() {
if (!canWriteCompressed()) {
throw new UnsupportedOperationException(
"Compression not supported.");
}
if (getCompressionMode() != MODE_EXPLICIT) {
throw new IllegalStateException
("Compression mode not MODE_EXPLICIT!");
}
if (getCompressionType() == null) {
throw new IllegalStateException("No compression type set!");
}
return getCompressionType();
}
/**
* Returns {@code true} 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 calling {@code setCompressionType} first.
*
* <p> If there are multiple compression types but none has
* been set, an {@code IllegalStateException} is thrown.
*
* <p> The default implementation checks whether compression is
* supported and the compression mode is
* {@code MODE_EXPLICIT}. If so, if
* {@code getCompressionTypes()} is {@code null} or
* {@code getCompressionType()} is non-{@code null}
* {@code true} is returned as a convenience.
*
* @return {@code true} if the current compression type is
* lossless.
*
* @exception UnsupportedOperationException if the writer does not
* support compression.
* @exception IllegalStateException if the compression mode is not
* {@code MODE_EXPLICIT}.
* @exception IllegalStateException if the set of legal
* compression types is non-{@code null} and the current
* compression type is {@code null}.
*/
public boolean isCompressionLossless() {
if (!canWriteCompressed()) {
throw new UnsupportedOperationException(
"Compression not supported");
}
if (getCompressionMode() != MODE_EXPLICIT) {
throw new IllegalStateException
("Compression mode not MODE_EXPLICIT!");
}
if ((getCompressionTypes() != null) &&
(getCompressionType() == null)) {
throw new IllegalStateException("No compression type set!");
}
return true;
}
/**
* Sets the compression quality to a value between {@code 0}
* and {@code 1}. Only a single compression quality setting
* is supported by default; writers can provide extended versions
* of {@code 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).
*
* <p> 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."
*
* <p> If there are multiple compression types but none has been
* set, an {@code IllegalStateException} is thrown.
*
* <p> The default implementation checks that compression is
* supported, and that the compression mode is
* {@code MODE_EXPLICIT}. If so, if
* {@code getCompressionTypes()} returns {@code null} or
* {@code compressionType} is non-{@code null} it sets
* the {@code compressionQuality} instance variable.
*
* @param quality a {@code float} between {@code 0} and
* {@code 1} indicating the desired quality level.
*
* @exception UnsupportedOperationException if the writer does not
* support compression.
* @exception IllegalStateException if the compression mode is not
* {@code MODE_EXPLICIT}.
* @exception IllegalStateException if the set of legal
* compression types is non-{@code null} and the current
* compression type is {@code null}.
* @exception IllegalArgumentException if {@code quality} is
* not between {@code 0} and {@code 1}, inclusive.
*
* @see #getCompressionQuality
*/
public void setCompressionQuality(float quality) {
if (!canWriteCompressed()) {
throw new UnsupportedOperationException(
"Compression not supported");
}
if (getCompressionMode() != MODE_EXPLICIT) {
throw new IllegalStateException
("Compression mode not MODE_EXPLICIT!");
}
if (getCompressionTypes() != null && getCompressionType() == null) {
throw new IllegalStateException("No compression type set!");
}
if (quality < 0.0F || quality > 1.0F) {
throw new IllegalArgumentException("Quality out-of-bounds!");
}
this.compressionQuality = quality;
}
/**
* Returns the current compression quality setting.
*
* <p> If there are multiple compression types but none has been
* set, an {@code IllegalStateException} is thrown.
*
* <p> The default implementation checks that compression is
* supported and that the compression mode is
* {@code MODE_EXPLICIT}. If so, if
* {@code getCompressionTypes()} is {@code null} or
* {@code getCompressionType()} is non-{@code null}, it
* returns the value of the {@code compressionQuality}
* instance variable.
*
* @return the current compression quality setting.
*
* @exception UnsupportedOperationException if the writer does not
* support compression.
* @exception IllegalStateException if the compression mode is not
* {@code MODE_EXPLICIT}.
* @exception IllegalStateException if the set of legal
* compression types is non-{@code null} and the current
* compression type is {@code null}.
*
* @see #setCompressionQuality
*/
public float getCompressionQuality() {
if (!canWriteCompressed()) {
throw new UnsupportedOperationException(
"Compression not supported.");
}
if (getCompressionMode() != MODE_EXPLICIT) {
throw new IllegalStateException
("Compression mode not MODE_EXPLICIT!");
}
if ((getCompressionTypes() != null) &&
(getCompressionType() == null)) {
throw new IllegalStateException("No compression type set!");
}
return compressionQuality;
}
/**
* Returns a {@code 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 {@code 0} and {@code 1}, with smaller values
* indicating more compression. A special value of
* {@code -1.0F} is used to indicate that no estimate is
* available.
*
* <p> If there are multiple compression types but none has been set,
* an {@code IllegalStateException} is thrown.
*
* <p> The default implementation checks that compression is
* supported and the compression mode is
* {@code MODE_EXPLICIT}. If so, if
* {@code getCompressionTypes()} is {@code null} or
* {@code getCompressionType()} is non-{@code null}, and
* {@code quality} is within bounds, it returns
* {@code -1.0}.
*
* @param quality the quality setting whose bit rate is to be
* queried.
*
* @return an estimate of the compressed bit rate, or
* {@code -1.0F} if no estimate is available.
*
* @exception UnsupportedOperationException if the writer does not
* support compression.
* @exception IllegalStateException if the compression mode is not
* {@code MODE_EXPLICIT}.
* @exception IllegalStateException if the set of legal
* compression types is non-{@code null} and the current
* compression type is {@code null}.
* @exception IllegalArgumentException if {@code quality} is
* not between {@code 0} and {@code 1}, inclusive.
*/
public float getBitRate(float quality) {
if (!canWriteCompressed()) {
throw new UnsupportedOperationException(
"Compression not supported.");
}
if (getCompressionMode() != MODE_EXPLICIT) {
throw new IllegalStateException
("Compression mode not MODE_EXPLICIT!");
}
if ((getCompressionTypes() != null) &&
(getCompressionType() == null)) {
throw new IllegalStateException("No compression type set!");
}
if (quality < 0.0F || quality > 1.0F) {
throw new IllegalArgumentException("Quality out-of-bounds!");
}
return -1.0F;
}
/**
* Returns an array of {@code String}s that may be used along
* with {@code getCompressionQualityValues} as part of a user
* interface for setting or displaying the compression quality
* level. The {@code String} with index {@code i}
* provides a description of the range of quality levels between
* {@code getCompressionQualityValues[i]} and
* {@code getCompressionQualityValues[i + 1]}. Note that the
* length of the array returned from
* {@code getCompressionQualityValues} will always be one
* greater than that returned from
* {@code getCompressionQualityDescriptions}.
*
* <p> As an example, the strings "Good", "Better", and "Best"
* could be associated with the ranges {@code [0, .33)},
* {@code [.33, .66)}, and {@code [.66, 1.0]}. In this
* case, {@code getCompressionQualityDescriptions} would
* return {@code { "Good", "Better", "Best" }} and
* {@code getCompressionQualityValues} would return
* {@code { 0.0F, .33F, .66F, 1.0F }}.
*
* <p> If no descriptions are available, {@code null} is
* returned. If {@code null} is returned from
* {@code getCompressionQualityValues}, this method must also
* return {@code null}.
*
* <p> The descriptions should be localized for the
* {@code Locale} returned by {@code getLocale}, if it
* is non-{@code null}.
*
* <p> If there are multiple compression types but none has been set,
* an {@code IllegalStateException} is thrown.
*
* <p> The default implementation checks that compression is
* supported and that the compression mode is
* {@code MODE_EXPLICIT}. If so, if
* {@code getCompressionTypes()} is {@code null} or
* {@code getCompressionType()} is non-{@code null}, it
* returns {@code null}.
*
* @return an array of {@code String}s containing localized
* descriptions of the compression quality levels.
*
* @exception UnsupportedOperationException if the writer does not
* support compression.
* @exception IllegalStateException if the compression mode is not
* {@code MODE_EXPLICIT}.
* @exception IllegalStateException if the set of legal
* compression types is non-{@code null} and the current
* compression type is {@code null}.
*
* @see #getCompressionQualityValues
*/
public String[] getCompressionQualityDescriptions() {
if (!canWriteCompressed()) {
throw new UnsupportedOperationException(
"Compression not supported.");
}
if (getCompressionMode() != MODE_EXPLICIT) {
throw new IllegalStateException
("Compression mode not MODE_EXPLICIT!");
}
if ((getCompressionTypes() != null) &&
(getCompressionType() == null)) {
throw new IllegalStateException("No compression type set!");
}
return null;
}
/**
* Returns an array of {@code float}s that may be used along
* with {@code getCompressionQualityDescriptions} as part of a user
* interface for setting or displaying the compression quality
* level. See {@link #getCompressionQualityDescriptions
* getCompressionQualityDescriptions} for more information.
*
* <p> If no descriptions are available, {@code null} is
* returned. If {@code null} is returned from
* {@code getCompressionQualityDescriptions}, this method
* must also return {@code null}.
*
* <p> If there are multiple compression types but none has been set,
* an {@code IllegalStateException} is thrown.
*
* <p> The default implementation checks that compression is
* supported and that the compression mode is
* {@code MODE_EXPLICIT}. If so, if
* {@code getCompressionTypes()} is {@code null} or
* {@code getCompressionType()} is non-{@code null}, it
* returns {@code null}.
*
* @return an array of {@code float}s indicating the
* boundaries between the compression quality levels as described
* by the {@code String}s from
* {@code getCompressionQualityDescriptions}.
*
* @exception UnsupportedOperationException if the writer does not
* support compression.
* @exception IllegalStateException if the compression mode is not
* {@code MODE_EXPLICIT}.
* @exception IllegalStateException if the set of legal
* compression types is non-{@code null} and the current
* compression type is {@code null}.
*
* @see #getCompressionQualityDescriptions
*/
public float[] getCompressionQualityValues() {
if (!canWriteCompressed()) {
throw new UnsupportedOperationException(
"Compression not supported.");
}
if (getCompressionMode() != MODE_EXPLICIT) {
throw new IllegalStateException
("Compression mode not MODE_EXPLICIT!");
}
if ((getCompressionTypes() != null) &&
(getCompressionType() == null)) {
throw new IllegalStateException("No compression type set!");
}
return null;
}
}