/*
 * Copyright (c) 2000, 2001, 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.Point;
import java.awt.Rectangle;

A superclass of all classes describing how streams should be
decoded or encoded.  This class contains all the variables and
methods that are shared by ImageReadParam and
ImageWriteParam.
 This class provides mechanisms to specify a source region and a
destination region.  When reading, the source is the stream and
the in-memory image is the destination.  When writing, these are
reversed.  In the case of writing, destination regions may be used
only with a writer that supports pixel replacement.

Decimation subsampling may be specified for both readers
and writers, using a movable subsampling grid.

Subsets of the source and destination bands may be selected.
/**
 * A superclass of all classes describing how streams should be
 * decoded or encoded.  This class contains all the variables and
 * methods that are shared by <code>ImageReadParam</code> and
 * <code>ImageWriteParam</code>.
 *
 * <p> This class provides mechanisms to specify a source region and a
 * destination region.  When reading, the source is the stream and
 * the in-memory image is the destination.  When writing, these are
 * reversed.  In the case of writing, destination regions may be used
 * only with a writer that supports pixel replacement.
 * <p>
 * Decimation subsampling may be specified for both readers
 * and writers, using a movable subsampling grid.
 * <p>
 * Subsets of the source and destination bands may be selected.
 *
 */
public abstract class IIOParam {

    
The source region, on null if none is set.
/**
     * The source region, on <code>null</code> if none is set.
     */
    protected Rectangle sourceRegion = null;

    
The decimation subsampling to be applied in the horizontal
direction.  By default, the value is 1.
The value must not be negative or 0.
/**
     * The decimation subsampling to be applied in the horizontal
     * direction.  By default, the value is <code>1</code>.
     * The value must not be negative or 0.
     */
    protected int sourceXSubsampling = 1;

    
The decimation subsampling to be applied in the vertical
direction.  By default, the value is 1.
The value must not be negative or 0.
/**
     * The decimation subsampling to be applied in the vertical
     * direction.  By default, the value is <code>1</code>.
     * The value must not be negative or 0.
     */
    protected int sourceYSubsampling = 1;

    
A horizontal offset to be applied to the subsampling grid before
subsampling.  The first pixel to be used will be offset this
amount from the origin of the region, or of the image if no
region is specified.
/**
     * A horizontal offset to be applied to the subsampling grid before
     * subsampling.  The first pixel to be used will be offset this
     * amount from the origin of the region, or of the image if no
     * region is specified.
     */
    protected int subsamplingXOffset = 0;

    
A vertical offset to be applied to the subsampling grid before
subsampling.  The first pixel to be used will be offset this
amount from the origin of the region, or of the image if no
region is specified.
/**
     * A vertical offset to be applied to the subsampling grid before
     * subsampling.  The first pixel to be used will be offset this
     * amount from the origin of the region, or of the image if no
     * region is specified.
     */
    protected int subsamplingYOffset = 0;

    
An array of ints indicating which source bands
will be used, or null.  If null, the
set of source bands to be used is as described in the comment
for the setSourceBands method.  No value should
be allowed to be negative.
/**
     * An array of <code>int</code>s indicating which source bands
     * will be used, or <code>null</code>.  If <code>null</code>, the
     * set of source bands to be used is as described in the comment
     * for the <code>setSourceBands</code> method.  No value should
     * be allowed to be negative.
     */
    protected int[] sourceBands = null;

    
An ImageTypeSpecifier to be used to generate a
destination image when reading, or to set the output color type
when writing.  If non has been setm the value will be
null.  By default, the value is null.
/**
     * An <code>ImageTypeSpecifier</code> to be used to generate a
     * destination image when reading, or to set the output color type
     * when writing.  If non has been setm the value will be
     * <code>null</code>.  By default, the value is <code>null</code>.
     */
    protected ImageTypeSpecifier destinationType = null;

    
The offset in the destination where the upper-left decoded
pixel should be placed.  By default, the value is (0, 0).
/**
     * The offset in the destination where the upper-left decoded
     * pixel should be placed.  By default, the value is (0, 0).
     */
    protected Point destinationOffset = new Point(0, 0);

    
The default IIOParamController that will be
used to provide settings for this IIOParam
object when the activateController method
is called.  This default should be set by subclasses
that choose to provide their own default controller,
usually a GUI, for setting parameters.
See Also:
IIOParamController
getDefaultController
activateController/**
     * The default <code>IIOParamController</code> that will be
     * used to provide settings for this <code>IIOParam</code>
     * object when the <code>activateController</code> method
     * is called.  This default should be set by subclasses
     * that choose to provide their own default controller,
     * usually a GUI, for setting parameters.
     *
     * @see IIOParamController
     * @see #getDefaultController
     * @see #activateController
     */
    protected IIOParamController defaultController = null;

    
The IIOParamController that will be
used to provide settings for this IIOParam
object when the activateController method
is called.  This value overrides any default controller,
even when null.
See Also:
IIOParamController
setController(IIOParamController)
hasController()
activateController()/**
     * The <code>IIOParamController</code> that will be
     * used to provide settings for this <code>IIOParam</code>
     * object when the <code>activateController</code> method
     * is called.  This value overrides any default controller,
     * even when null.
     *
     * @see IIOParamController
     * @see #setController(IIOParamController)
     * @see #hasController()
     * @see #activateController()
     */
    protected IIOParamController controller = null;

    
Protected constructor may be called only by subclasses.
/**
     * Protected constructor may be called only by subclasses.
     */
    protected IIOParam() {
        controller = defaultController;
    }

    
Sets the source region of interest.  The region of interest is
described as a rectangle, with the upper-left corner of the
source image as pixel (0, 0) and increasing values down and to
the right.  The actual number of pixels used will depend on
the subsampling factors set by setSourceSubsampling.
If subsampling has been set such that this number is zero,
an IllegalStateException will be thrown.
 The source region of interest specified by this method will
be clipped as needed to fit within the source bounds, as well
as the destination offsets, width, and height at the time of
actual I/O.
 A value of null for sourceRegion
will remove any region specification, causing the entire image
to be used.
Params:
sourceRegion – a Rectangle specifying the
source region of interest, or null.
Throws:
IllegalArgumentException – if
sourceRegion is non-null and either
sourceRegion.x or sourceRegion.y is
negative.
IllegalArgumentException – if
sourceRegion is non-null and either
sourceRegion.width or
sourceRegion.height is negative or 0.
IllegalStateException – if subsampling is such that
this region will have a subsampled width or height of zero.
See Also:
getSourceRegion
setSourceSubsampling
setDestinationOffset
getDestinationOffset/**
     * Sets the source region of interest.  The region of interest is
     * described as a rectangle, with the upper-left corner of the
     * source image as pixel (0, 0) and increasing values down and to
     * the right.  The actual number of pixels used will depend on
     * the subsampling factors set by <code>setSourceSubsampling</code>.
     * If subsampling has been set such that this number is zero,
     * an <code>IllegalStateException</code> will be thrown.
     *
     * <p> The source region of interest specified by this method will
     * be clipped as needed to fit within the source bounds, as well
     * as the destination offsets, width, and height at the time of
     * actual I/O.
     *
     * <p> A value of <code>null</code> for <code>sourceRegion</code>
     * will remove any region specification, causing the entire image
     * to be used.
     *
     * @param sourceRegion a <code>Rectangle</code> specifying the
     * source region of interest, or <code>null</code>.
     *
     * @exception IllegalArgumentException if
     * <code>sourceRegion</code> is non-<code>null</code> and either
     * <code>sourceRegion.x</code> or <code>sourceRegion.y</code> is
     * negative.
     * @exception IllegalArgumentException if
     * <code>sourceRegion</code> is non-<code>null</code> and either
     * <code>sourceRegion.width</code> or
     * <code>sourceRegion.height</code> is negative or 0.
     * @exception IllegalStateException if subsampling is such that
     * this region will have a subsampled width or height of zero.
     *
     * @see #getSourceRegion
     * @see #setSourceSubsampling
     * @see ImageReadParam#setDestinationOffset
     * @see ImageReadParam#getDestinationOffset
     */
    public void setSourceRegion(Rectangle sourceRegion) {
        if (sourceRegion == null) {
            this.sourceRegion = null;
            return;
        }

        if (sourceRegion.x < 0) {
            throw new IllegalArgumentException("sourceRegion.x < 0!");
        }
        if (sourceRegion.y < 0){
            throw new IllegalArgumentException("sourceRegion.y < 0!");
        }
        if (sourceRegion.width <= 0) {
            throw new IllegalArgumentException("sourceRegion.width <= 0!");
        }
        if (sourceRegion.height <= 0) {
            throw new IllegalArgumentException("sourceRegion.height <= 0!");
        }

        // Throw an IllegalStateException if region falls between subsamples
        if (sourceRegion.width <= subsamplingXOffset) {
            throw new IllegalStateException
                ("sourceRegion.width <= subsamplingXOffset!");
        }
        if (sourceRegion.height <= subsamplingYOffset) {
            throw new IllegalStateException
                ("sourceRegion.height <= subsamplingYOffset!");
        }

        this.sourceRegion = (Rectangle)sourceRegion.clone();
    }

    
Returns the source region to be used.  The returned value is
that set by the most recent call to
setSourceRegion, and will be null if
there is no region set.
See Also:
setSourceRegion
Returns:
the source region of interest as a
Rectangle, or null./**
     * Returns the source region to be used.  The returned value is
     * that set by the most recent call to
     * <code>setSourceRegion</code>, and will be <code>null</code> if
     * there is no region set.
     *
     * @return the source region of interest as a
     * <code>Rectangle</code>, or <code>null</code>.
     *
     * @see #setSourceRegion
     */
    public Rectangle getSourceRegion() {
        if (sourceRegion == null) {
            return null;
        }
        return (Rectangle)sourceRegion.clone();
    }

    
Specifies a decimation subsampling to apply on I/O.  The
sourceXSubsampling and
sourceYSubsampling parameters specify the
subsampling period (i.e., the number of rows and columns
to advance after every source pixel).  Specifically, a period of
1 will use every row or column; a period of 2 will use every
other row or column.  The subsamplingXOffset and
subsamplingYOffset parameters specify an offset
from the region (or image) origin for the first subsampled pixel.
Adjusting the origin of the subsample grid is useful for avoiding
seams when subsampling a very large source image into destination
regions that will be assembled into a complete subsampled image.
Most users will want to simply leave these parameters at 0.
 The number of pixels and scanlines to be used are calculated
as follows.

The number of subsampled pixels in a scanline is given by

truncate[(width - subsamplingXOffset + sourceXSubsampling - 1)
/ sourceXSubsampling].

If the region is such that this width is zero, an
IllegalStateException is thrown.

The number of scanlines to be used can be computed similarly.
The ability to set the subsampling grid to start somewhere
other than the source region origin is useful if the
region is being used to create subsampled tiles of a large image,
where the tile width and height are not multiples of the
subsampling periods.  If the subsampling grid does not remain
consistent from tile to tile, there will be artifacts at the tile
boundaries.  By adjusting the subsampling grid offset for each
tile to compensate, these artifacts can be avoided.  The tradeoff
is that in order to avoid these artifacts, the tiles are not all
the same size.  The grid offset to use in this case is given by:


grid offset = [period - (region offset modulo period)] modulo period)
 If either sourceXSubsampling or
sourceYSubsampling is 0 or negative, an
IllegalArgumentException will be thrown.
 If either subsamplingXOffset or
subsamplingYOffset is negative or greater than or
equal to the corresponding period, an
IllegalArgumentException will be thrown.
 There is no unsetSourceSubsampling method;
simply call setSourceSubsampling(1, 1, 0, 0) to
restore default values.
Params:
sourceXSubsampling – the number of columns to advance
between pixels.
sourceYSubsampling – the number of rows to advance between
pixels.
subsamplingXOffset – the horizontal offset of the first subsample
within the region, or within the image if no region is set.
subsamplingYOffset – the horizontal offset of the first subsample
within the region, or within the image if no region is set.
Throws:
IllegalArgumentException – if either period is
negative or 0, or if either grid offset is negative or greater than
the corresponding period.
IllegalStateException – if the source region is such that
the subsampled output would contain no pixels./**
     * Specifies a decimation subsampling to apply on I/O.  The
     * <code>sourceXSubsampling</code> and
     * <code>sourceYSubsampling</code> parameters specify the
     * subsampling period (<i>i.e.</i>, the number of rows and columns
     * to advance after every source pixel).  Specifically, a period of
     * 1 will use every row or column; a period of 2 will use every
     * other row or column.  The <code>subsamplingXOffset</code> and
     * <code>subsamplingYOffset</code> parameters specify an offset
     * from the region (or image) origin for the first subsampled pixel.
     * Adjusting the origin of the subsample grid is useful for avoiding
     * seams when subsampling a very large source image into destination
     * regions that will be assembled into a complete subsampled image.
     * Most users will want to simply leave these parameters at 0.
     *
     * <p> The number of pixels and scanlines to be used are calculated
     * as follows.
     * <p>
     * The number of subsampled pixels in a scanline is given by
     * <p>
     * <code>truncate[(width - subsamplingXOffset + sourceXSubsampling - 1)
     * / sourceXSubsampling]</code>.
     * <p>
     * If the region is such that this width is zero, an
     * <code>IllegalStateException</code> is thrown.
     * <p>
     * The number of scanlines to be used can be computed similarly.
     *
     * <p>The ability to set the subsampling grid to start somewhere
     * other than the source region origin is useful if the
     * region is being used to create subsampled tiles of a large image,
     * where the tile width and height are not multiples of the
     * subsampling periods.  If the subsampling grid does not remain
     * consistent from tile to tile, there will be artifacts at the tile
     * boundaries.  By adjusting the subsampling grid offset for each
     * tile to compensate, these artifacts can be avoided.  The tradeoff
     * is that in order to avoid these artifacts, the tiles are not all
     * the same size.  The grid offset to use in this case is given by:
     * <br>
     * grid offset = [period - (region offset modulo period)] modulo period)
     *
     * <p> If either <code>sourceXSubsampling</code> or
     * <code>sourceYSubsampling</code> is 0 or negative, an
     * <code>IllegalArgumentException</code> will be thrown.
     *
     * <p> If either <code>subsamplingXOffset</code> or
     * <code>subsamplingYOffset</code> is negative or greater than or
     * equal to the corresponding period, an
     * <code>IllegalArgumentException</code> will be thrown.
     *
     * <p> There is no <code>unsetSourceSubsampling</code> method;
     * simply call <code>setSourceSubsampling(1, 1, 0, 0)</code> to
     * restore default values.
     *
     * @param sourceXSubsampling the number of columns to advance
     * between pixels.
     * @param sourceYSubsampling the number of rows to advance between
     * pixels.
     * @param subsamplingXOffset the horizontal offset of the first subsample
     * within the region, or within the image if no region is set.
     * @param subsamplingYOffset the horizontal offset of the first subsample
     * within the region, or within the image if no region is set.
     * @exception IllegalArgumentException if either period is
     * negative or 0, or if either grid offset is negative or greater than
     * the corresponding period.
     * @exception IllegalStateException if the source region is such that
     * the subsampled output would contain no pixels.
     */
    public void setSourceSubsampling(int sourceXSubsampling,
                                     int sourceYSubsampling,
                                     int subsamplingXOffset,
                                     int subsamplingYOffset) {
        if (sourceXSubsampling <= 0) {
            throw new IllegalArgumentException("sourceXSubsampling <= 0!");
        }
        if (sourceYSubsampling <= 0) {
            throw new IllegalArgumentException("sourceYSubsampling <= 0!");
        }
        if (subsamplingXOffset < 0 ||
            subsamplingXOffset >= sourceXSubsampling) {
            throw new IllegalArgumentException
                ("subsamplingXOffset out of range!");
        }
        if (subsamplingYOffset < 0 ||
            subsamplingYOffset >= sourceYSubsampling) {
            throw new IllegalArgumentException
                ("subsamplingYOffset out of range!");
        }

        // Throw an IllegalStateException if region falls between subsamples
        if (sourceRegion != null) {
            if (subsamplingXOffset >= sourceRegion.width ||
                subsamplingYOffset >= sourceRegion.height) {
                throw new IllegalStateException("region contains no pixels!");
            }
        }

        this.sourceXSubsampling = sourceXSubsampling;
        this.sourceYSubsampling = sourceYSubsampling;
        this.subsamplingXOffset = subsamplingXOffset;
        this.subsamplingYOffset = subsamplingYOffset;
    }

    
Returns the number of source columns to advance for each pixel.
If setSourceSubsampling has not been called, 1
is returned (which is the correct value).
See Also:
setSourceSubsampling
getSourceYSubsampling
Returns:
the source subsampling X period./**
     * Returns the number of source columns to advance for each pixel.
     *
     * <p>If <code>setSourceSubsampling</code> has not been called, 1
     * is returned (which is the correct value).
     *
     * @return the source subsampling X period.
     *
     * @see #setSourceSubsampling
     * @see #getSourceYSubsampling
     */
    public int getSourceXSubsampling() {
        return sourceXSubsampling;
    }

    
Returns the number of rows to advance for each pixel.
If setSourceSubsampling has not been called, 1
is returned (which is the correct value).
See Also:
setSourceSubsampling
getSourceXSubsampling
Returns:
the source subsampling Y period./**
     * Returns the number of rows to advance for each pixel.
     *
     * <p>If <code>setSourceSubsampling</code> has not been called, 1
     * is returned (which is the correct value).
     *
     * @return the source subsampling Y period.
     *
     * @see #setSourceSubsampling
     * @see #getSourceXSubsampling
     */
    public int getSourceYSubsampling() {
        return sourceYSubsampling;
    }

    
Returns the horizontal offset of the subsampling grid.
If setSourceSubsampling has not been called, 0
is returned (which is the correct value).
See Also:
setSourceSubsampling
getSubsamplingYOffset
Returns:
the source subsampling grid X offset./**
     * Returns the horizontal offset of the subsampling grid.
     *
     * <p>If <code>setSourceSubsampling</code> has not been called, 0
     * is returned (which is the correct value).
     *
     * @return the source subsampling grid X offset.
     *
     * @see #setSourceSubsampling
     * @see #getSubsamplingYOffset
     */
    public int getSubsamplingXOffset() {
        return subsamplingXOffset;
    }

    
Returns the vertical offset of the subsampling grid.
If setSourceSubsampling has not been called, 0
is returned (which is the correct value).
See Also:
setSourceSubsampling
getSubsamplingXOffset
Returns:
the source subsampling grid Y offset./**
     * Returns the vertical offset of the subsampling grid.
     *
     * <p>If <code>setSourceSubsampling</code> has not been called, 0
     * is returned (which is the correct value).
     *
     * @return the source subsampling grid Y offset.
     *
     * @see #setSourceSubsampling
     * @see #getSubsamplingXOffset
     */
    public int getSubsamplingYOffset() {
        return subsamplingYOffset;
    }

    
Sets the indices of the source bands to be used.  Duplicate
indices are not allowed.
 A null value indicates that all source bands
will be used.
 At the time of reading, an
IllegalArgumentException will be thrown by the
reader or writer if a value larger than the largest available
source band index has been specified or if the number of source
bands and destination bands to be used differ.  The
ImageReader.checkReadParamBandSettings method may
be used to automate this test.
 Semantically, a copy is made of the array; changes to the
array contents subsequent to this call have no effect on
this IIOParam.
Params:
sourceBands – an array of integer band indices to be
used.
Throws:
IllegalArgumentException – if sourceBands
contains a negative or duplicate value.
See Also:
getSourceBands
ImageReadParam.setDestinationBands
ImageReader.checkReadParamBandSettings/**
     * Sets the indices of the source bands to be used.  Duplicate
     * indices are not allowed.
     *
     * <p> A <code>null</code> value indicates that all source bands
     * will be used.
     *
     * <p> At the time of reading, an
     * <code>IllegalArgumentException</code> will be thrown by the
     * reader or writer if a value larger than the largest available
     * source band index has been specified or if the number of source
     * bands and destination bands to be used differ.  The
     * <code>ImageReader.checkReadParamBandSettings</code> method may
     * be used to automate this test.
     *
     * <p> Semantically, a copy is made of the array; changes to the
     * array contents subsequent to this call have no effect on
     * this <code>IIOParam</code>.
     *
     * @param sourceBands an array of integer band indices to be
     * used.
     *
     * @exception IllegalArgumentException if <code>sourceBands</code>
     * contains a negative or duplicate value.
     *
     * @see #getSourceBands
     * @see ImageReadParam#setDestinationBands
     * @see ImageReader#checkReadParamBandSettings
     */
    public void setSourceBands(int[] sourceBands) {
        if (sourceBands == null) {
            this.sourceBands = null;
        } else {
            int numBands = sourceBands.length;
            for (int i = 0; i < numBands; i++) {
                int band = sourceBands[i];
                if (band < 0) {
                    throw new IllegalArgumentException("Band value < 0!");
                }
                for (int j = i + 1; j < numBands; j++) {
                    if (band == sourceBands[j]) {
                        throw new IllegalArgumentException("Duplicate band value!");
                    }
                }

            }
            this.sourceBands = (int[])(sourceBands.clone());
        }
    }

    
Returns the set of of source bands to be used. The returned
value is that set by the most recent call to
setSourceBands, or null if there have
been no calls to setSourceBands.
 Semantically, the array returned is a copy; changes to
array contents subsequent to this call have no effect on this
IIOParam.
See Also:
setSourceBands
Returns:
the set of source bands to be used, or
null./**
     * Returns the set of of source bands to be used. The returned
     * value is that set by the most recent call to
     * <code>setSourceBands</code>, or <code>null</code> if there have
     * been no calls to <code>setSourceBands</code>.
     *
     * <p> Semantically, the array returned is a copy; changes to
     * array contents subsequent to this call have no effect on this
     * <code>IIOParam</code>.
     *
     * @return the set of source bands to be used, or
     * <code>null</code>.
     *
     * @see #setSourceBands
     */
    public int[] getSourceBands() {
        if (sourceBands == null) {
            return null;
        }
        return (int[])(sourceBands.clone());
    }

    
Sets the desired image type for the destination image, using an
ImageTypeSpecifier.
 When reading, if the layout of the destination has been set
using this method, each call to an ImageReader
read method will return a new
BufferedImage using the format specified by the
supplied type specifier.  As a side effect, any destination
BufferedImage set by
ImageReadParam.setDestination(BufferedImage) will
no longer be set as the destination.  In other words, this
method may be thought of as calling
setDestination((BufferedImage)null).
 When writing, the destination type maybe used to determine
the color type of the image.  The SampleModel
information will be ignored, and may be null.  For
example, a 4-banded image could represent either CMYK or RGBA
data.  If a destination type is set, its
ColorModel will override any
ColorModel on the image itself.  This is crucial
when setSourceBands is used since the image's
ColorModel will refer to the entire image rather
than to the subset of bands being written.
Params:
destinationType – the ImageTypeSpecifier to
be used to determine the destination layout and color type.
See Also:
getDestinationType/**
     * Sets the desired image type for the destination image, using an
     * <code>ImageTypeSpecifier</code>.
     *
     * <p> When reading, if the layout of the destination has been set
     * using this method, each call to an <code>ImageReader</code>
     * <code>read</code> method will return a new
     * <code>BufferedImage</code> using the format specified by the
     * supplied type specifier.  As a side effect, any destination
     * <code>BufferedImage</code> set by
     * <code>ImageReadParam.setDestination(BufferedImage)</code> will
     * no longer be set as the destination.  In other words, this
     * method may be thought of as calling
     * <code>setDestination((BufferedImage)null)</code>.
     *
     * <p> When writing, the destination type maybe used to determine
     * the color type of the image.  The <code>SampleModel</code>
     * information will be ignored, and may be <code>null</code>.  For
     * example, a 4-banded image could represent either CMYK or RGBA
     * data.  If a destination type is set, its
     * <code>ColorModel</code> will override any
     * <code>ColorModel</code> on the image itself.  This is crucial
     * when <code>setSourceBands</code> is used since the image's
     * <code>ColorModel</code> will refer to the entire image rather
     * than to the subset of bands being written.
     *
     * @param destinationType the <code>ImageTypeSpecifier</code> to
     * be used to determine the destination layout and color type.
     *
     * @see #getDestinationType
     */
    public void setDestinationType(ImageTypeSpecifier destinationType) {
        this.destinationType = destinationType;
    }

    
Returns the type of image to be returned by the read, if one
was set by a call to
setDestination(ImageTypeSpecifier), as an
ImageTypeSpecifier.  If none was set,
null is returned.
See Also:
setDestinationType
Returns:
an ImageTypeSpecifier describing the
destination type, or null./**
     * Returns the type of image to be returned by the read, if one
     * was set by a call to
     * <code>setDestination(ImageTypeSpecifier)</code>, as an
     * <code>ImageTypeSpecifier</code>.  If none was set,
     * <code>null</code> is returned.
     *
     * @return an <code>ImageTypeSpecifier</code> describing the
     * destination type, or <code>null</code>.
     *
     * @see #setDestinationType
     */
    public ImageTypeSpecifier getDestinationType() {
        return destinationType;
    }

    
Specifies the offset in the destination image at which future
decoded pixels are to be placed, when reading, or where a
region will be written, when writing.
 When reading, the region to be written within the
destination BufferedImage will start at this
offset and have a width and height determined by the source
region of interest, the subsampling parameters, and the
destination bounds.
 Normal writes are not affected by this method, only writes
performed using ImageWriter.replacePixels.  For
such writes, the offset specified is within the output stream
image whose pixels are being modified.
 There is no unsetDestinationOffset method;
simply call setDestinationOffset(new Point(0, 0)) to
restore default values.
Params:
destinationOffset – the offset in the destination, as a
Point.
Throws:
IllegalArgumentException – if
destinationOffset is null.
See Also:
getDestinationOffset
ImageWriter.replacePixels/**
     * Specifies the offset in the destination image at which future
     * decoded pixels are to be placed, when reading, or where a
     * region will be written, when writing.
     *
     * <p> When reading, the region to be written within the
     * destination <code>BufferedImage</code> will start at this
     * offset and have a width and height determined by the source
     * region of interest, the subsampling parameters, and the
     * destination bounds.
     *
     * <p> Normal writes are not affected by this method, only writes
     * performed using <code>ImageWriter.replacePixels</code>.  For
     * such writes, the offset specified is within the output stream
     * image whose pixels are being modified.
     *
     * <p> There is no <code>unsetDestinationOffset</code> method;
     * simply call <code>setDestinationOffset(new Point(0, 0))</code> to
     * restore default values.
     *
     * @param destinationOffset the offset in the destination, as a
     * <code>Point</code>.
     *
     * @exception IllegalArgumentException if
     * <code>destinationOffset</code> is <code>null</code>.
     *
     * @see #getDestinationOffset
     * @see ImageWriter#replacePixels
     */
    public void setDestinationOffset(Point destinationOffset) {
        if (destinationOffset == null) {
            throw new IllegalArgumentException("destinationOffset == null!");
        }
        this.destinationOffset = (Point)destinationOffset.clone();
    }

    
Returns the offset in the destination image at which pixels are
to be placed.
 If setDestinationOffsets has not been called,
a Point with zero X and Y values is returned
(which is the correct value).
See Also:
setDestinationOffset
Returns:
the destination offset as a Point./**
     * Returns the offset in the destination image at which pixels are
     * to be placed.
     *
     * <p> If <code>setDestinationOffsets</code> has not been called,
     * a <code>Point</code> with zero X and Y values is returned
     * (which is the correct value).
     *
     * @return the destination offset as a <code>Point</code>.
     *
     * @see #setDestinationOffset
     */
    public Point getDestinationOffset() {
        return (Point)destinationOffset.clone();
    }

    
Sets the IIOParamController to be used
to provide settings for this IIOParam
object when the activateController method
is called, overriding any default controller.  If the
argument is null, no controller will be
used, including any default.  To restore the default, use
setController(getDefaultController()).
Params:
controller – An appropriate
IIOParamController, or null.
See Also:
IIOParamController
getController
getDefaultController
hasController
activateController()/**
     * Sets the <code>IIOParamController</code> to be used
     * to provide settings for this <code>IIOParam</code>
     * object when the <code>activateController</code> method
     * is called, overriding any default controller.  If the
     * argument is <code>null</code>, no controller will be
     * used, including any default.  To restore the default, use
     * <code>setController(getDefaultController())</code>.
     *
     * @param controller An appropriate
     * <code>IIOParamController</code>, or <code>null</code>.
     *
     * @see IIOParamController
     * @see #getController
     * @see #getDefaultController
     * @see #hasController
     * @see #activateController()
     */
    public void setController(IIOParamController controller) {
        this.controller = controller;
    }

    
Returns whatever IIOParamController is currently
installed.  This could be the default if there is one,
null, or the argument of the most recent call
to setController.
See Also:
IIOParamController
setController
getDefaultController
hasController
activateController()
Returns:
the currently installed
IIOParamController, or null./**
     * Returns whatever <code>IIOParamController</code> is currently
     * installed.  This could be the default if there is one,
     * <code>null</code>, or the argument of the most recent call
     * to <code>setController</code>.
     *
     * @return the currently installed
     * <code>IIOParamController</code>, or <code>null</code>.
     *
     * @see IIOParamController
     * @see #setController
     * @see #getDefaultController
     * @see #hasController
     * @see #activateController()
     */
    public IIOParamController getController() {
        return controller;
    }

    
Returns the default IIOParamController, if there
is one, regardless of the currently installed controller.  If
there is no default controller, returns null.
See Also:
IIOParamController
setController(IIOParamController)
getController
hasController
activateController()
Returns:
the default IIOParamController, or
null./**
     * Returns the default <code>IIOParamController</code>, if there
     * is one, regardless of the currently installed controller.  If
     * there is no default controller, returns <code>null</code>.
     *
     * @return the default <code>IIOParamController</code>, or
     * <code>null</code>.
     *
     * @see IIOParamController
     * @see #setController(IIOParamController)
     * @see #getController
     * @see #hasController
     * @see #activateController()
     */
    public IIOParamController getDefaultController() {
        return defaultController;
    }

    
Returns true if there is a controller installed
for this IIOParam object.  This will return
true if getController would not
return null.
See Also:
IIOParamController
setController(IIOParamController)
getController
getDefaultController
activateController()
Returns:
true if a controller is installed./**
     * Returns <code>true</code> if there is a controller installed
     * for this <code>IIOParam</code> object.  This will return
     * <code>true</code> if <code>getController</code> would not
     * return <code>null</code>.
     *
     * @return <code>true</code> if a controller is installed.
     *
     * @see IIOParamController
     * @see #setController(IIOParamController)
     * @see #getController
     * @see #getDefaultController
     * @see #activateController()
     */
    public boolean hasController() {
        return (controller != null);
    }

    
Activates the installed IIOParamController for
this IIOParam object and returns the resulting
value.  When this method returns true, all values
for this IIOParam object will be ready for the
next read or write operation.  If false is
returned, no settings in this object will have been disturbed
(i.e., the user canceled the operation).
 Ordinarily, the controller will be a GUI providing a user
interface for a subclass of IIOParam for a
particular plug-in.  Controllers need not be GUIs, however.
Throws:
IllegalStateException – if there is no controller
currently installed.
See Also:
IIOParamController
setController(IIOParamController)
getController
getDefaultController
hasController
Returns:
true if the controller completed normally./**
     * Activates the installed <code>IIOParamController</code> for
     * this <code>IIOParam</code> object and returns the resulting
     * value.  When this method returns <code>true</code>, all values
     * for this <code>IIOParam</code> object will be ready for the
     * next read or write operation.  If <code>false</code> is
     * returned, no settings in this object will have been disturbed
     * (<i>i.e.</i>, the user canceled the operation).
     *
     * <p> Ordinarily, the controller will be a GUI providing a user
     * interface for a subclass of <code>IIOParam</code> for a
     * particular plug-in.  Controllers need not be GUIs, however.
     *
     * @return <code>true</code> if the controller completed normally.
     *
     * @exception IllegalStateException if there is no controller
     * currently installed.
     *
     * @see IIOParamController
     * @see #setController(IIOParamController)
     * @see #getController
     * @see #getDefaultController
     * @see #hasController
     */
    public boolean activateController() {
        if (!hasController()) {
            throw new IllegalStateException("hasController() == false!");
        }
        return getController().activate(this);
    }
}