/*
 * @(#)ImageReadParam.java	1.59 05/11/17
 *
 * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 */

package javax.imageio;

import java.awt.Dimension;
import java.awt.image.BufferedImage;

/**
 * A class describing how a stream is to be decoded.  Instances of
 * this class or its subclasses are used to supply prescriptive
 * "how-to" information to instances of <code>ImageReader</code>.
 *
 * <p> An image encoded as part of a file or stream may be thought of
 * extending out in multiple dimensions: the spatial dimensions of
 * width and height, a number of bands, and a number of progressive
 * decoding passes.  This class allows a contiguous (hyper)rectangular
 * subarea of the image in all of these dimensions to be selected for
 * decoding.  Additionally, the spatial dimensions may be subsampled
 * discontinuously.  Finally, color and format conversions may be
 * specified by controlling the <code>ColorModel</code> and
 * <code>SampleModel</code> of the destination image, either by
 * providing a <code>BufferedImage</code> or by using an
 * <code>ImageTypeSpecifier</code>.
 *
 * <p> An <code>ImageReadParam</code> object is used to specify how an
 * image, or a set of images, will be converted on input from
 * a stream in the context of the Java Image I/O framework.  A plug-in for a
 * specific image format will return instances of
 * <code>ImageReadParam</code> from the
 * <code>getDefaultReadParam</code> method of its
 * <code>ImageReader</code> implementation.
 *
 * <p> The state maintained by an instance of
 * <code>ImageReadParam</code> is independent of any particular image
 * being decoded.  When actual decoding takes place, the values set in
 * the read param are combined with the actual properties of the image
 * being decoded from the stream and the destination
 * <code>BufferedImage</code> that will receive the decoded pixel
 * data.  For example, the source region set using
 * <code>setSourceRegion</code> will first be intersected with the
 * actual valid source area.  The result will be translated by the
 * value returned by <code>getDestinationOffset</code>, and the
 * resulting rectangle intersected with the actual valid destination
 * area to yield the destination area that will be written.
 *
 * <p> The parameters specified by an <code>ImageReadParam</code> are
 * applied to an image as follows.  First, if a rendering size has
 * been set by <code>setSourceRenderSize</code>, the entire decoded
 * image is rendered at the size given by
 * <code>getSourceRenderSize</code>.  Otherwise, the image has its
 * natural size given by <code>ImageReader.getWidth</code> and
 * <code>ImageReader.getHeight</code>.
 *
 * <p> Next, the image is clipped against the source region
 * specified by <code>getSourceXOffset</code>, <code>getSourceYOffset</code>,
 * <code>getSourceWidth</code>, and <code>getSourceHeight</code>.
 *
 * <p> The resulting region is then subsampled according to the
 * factors given in {@link IIOParam#setSourceSubsampling 
 * <code>IIOParam.setSourceSubsampling</code>}.  The first pixel,
 * the number of pixels per row, and the number of rows all depend
 * on the subsampling settings.
 * Call the minimum X and Y coordinates of the resulting rectangle
 * (<code>minX</code>, <code>minY</code>), its width <code>w</code>
 * and its height <code>h</code>.
 *
 * <p> This rectangle is offset by
 * (<code>getDestinationOffset().x</code>,
 * <code>getDestinationOffset().y</code>) and clipped against the
 * destination bounds.  If no destination image has been set, the
 * destination is defined to have a width of
 * <code>getDestinationOffset().x</code> + <code>w</code>, and a
 * height of <code>getDestinationOffset().y</code> + <code>h</code> so
 * that all pixels of the source region may be written to the
 * destination.
 *
 * <p> Pixels that land, after subsampling, within the destination
 * image, and that are written in one of the progressive passes
 * specified by <code>getSourceMinProgressivePass</code> and
 * <code>getSourceNumProgressivePasses</code> are passed along to the
 * next step.
 *
 * <p> Finally, the source samples of each pixel are mapped into
 * destination bands according to the algorithm described in the
 * comment for <code>setDestinationBands</code>.
 *
 * <p> Plug-in writers may extend the functionality of
 * <code>ImageReadParam</code> 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.  Readers will silently ignore any extended features of an
 * <code>ImageReadParam</code> subclass of which they are not aware.
 * Also, they may ignore any optional features that they normally
 * disable when creating their own <code>ImageReadParam</code>
 * instances via <code>getDefaultReadParam</code>.