001: /*
002: * $RCSfile: TileDecoder.java,v $
003: *
004: * Copyright (c) 2005 Sun Microsystems, Inc. All rights reserved.
005: *
006: * Use is subject to license terms.
007: *
008: * $Revision: 1.1 $
009: * $Date: 2005/02/11 04:57:55 $
010: * $State: Exp $
011: */package javax.media.jai.tilecodec;
012:
013: import java.awt.Point;
014: import java.awt.image.Raster;
015: import java.awt.image.SampleModel;
016: import java.io.IOException;
017: import java.io.InputStream;
018: import javax.media.jai.remote.NegotiableCapability;
019:
020: /**
021: * An interface describing objects that transform an <code>InputStream</code>
022: * into a <code>Raster</code>.
023: *
024: * <p>This interface is designed to allow decoding of formats that
025: * include information about the format of the encoded tile as well as ones
026: * that don't. In order to create a <code>Raster</code>, at the very least,
027: * a <code>Point</code> specifying the top left corner of the
028: * <code>Raster</code>, a <code>SampleModel</code> specifying the data layout
029: * and a <code>DataBuffer</code> with the decoded pixel data are
030: * needed. The <code>DataBuffer</code> can be created from the
031: * information from the <code>SampleModel</code> and the decoded data.
032: * Therefore the absolute minimum information that is required in order to
033: * create a <code>Raster</code> on decoding (aside from the decoded data
034: * itself) is a <code>Point</code> specifying the top left corner of the
035: * <code>Raster</code> and a <code>SampleModel</code> specifying the data
036: * layout. The formats that do include this information should return true
037: * from the <code>includesSampleModelInfo()</code> and
038: * <code>includesLocationInfo()</code> from the associated
039: * <code>TileCodecDescriptor</code> if they include information needed to
040: * create a <code>SampleModel</code> and information needed to
041: * create the <code>Point</code> respectively. The formats that do not
042: * include this information in the encoded stream should return false. The
043: * <code>TileCodecParameterList</code> providing the decoding parameters
044: * will in this case be expected to contain a parameter named "sampleModel"
045: * with a non-null <code>SampleModel</code> as its value. This
046: * <code>SampleModel</code> will be used to create the decoded
047: * <code>Raster</code>.
048: *
049: * <p> The formats that return true from <code>includesSampleModelInfo()</code>
050: * should use the <code>decode()</code> method to cause the decoding to take
051: * place, the ones that return false should specify the <code>Point</code>
052: * location to the decoding process by using the <code>decode(Point)</code>
053: * method. Similarly the <code>SampleModel</code> must be specified as a
054: * parameter with a non-null value on the <code>TileCodecParameterList</code>
055: * passed to this <code>TileDecoder</code> if
056: * <code>includesSampleModelInfo()</code> returns false. It is expected that
057: * the <code>SampleModel</code> specified in the parameter list is the
058: * <code>SampleModel</code> of the encoded tiles, in order to get a
059: * decoded <code>Raster</code> that is equivalent to the one encoded. If the
060: * <code>SampleModel</code> specified through the parameter list is different
061: * from those of the encoded tiles, the result of decoding is undefined.
062: *
063: * <p> If <code>includesSampleModelInfo()</code> returns true, the
064: * <code>SampleModel</code> (if present) on the
065: * <code>TileCodecParameterList</code> is ignored.
066: *
067: * @see TileCodecDescriptor
068: * @see TileEncoder
069: *
070: * @since JAI 1.1
071: */
072: public interface TileDecoder {
073:
074: /**
075: * Returns the name of the format.
076: */
077: String getFormatName();
078:
079: /**
080: * Returns the current parameters as an instance of the
081: * <code>TileCodecParameterList</code> interface.
082: */
083: TileCodecParameterList getDecodeParameterList();
084:
085: /**
086: * Returns the <code>InputStream</code> containing the encoded data.
087: */
088: InputStream getInputStream();
089:
090: /**
091: * Returns a <code>Raster</code> that contains the decoded contents
092: * of the <code>InputStream</code> associated with this
093: * <code>TileDecoder</code>.
094: *
095: * <p>This method can perform the decoding correctly only when
096: * <code>includesLocationInfo()</code> returns true.
097: *
098: * @throws IOException if an I/O error occurs while reading from the
099: * associated InputStream.
100: * @throws IllegalArgumentException if the associated
101: * TileCodecDescriptor's includesLocationInfo() returns false.
102: */
103: Raster decode() throws IOException;
104:
105: /**
106: * Returns a <code>Raster</code> that contains the decoded contents
107: * of the <code>InputStream</code> associated with this
108: * <code>TileDecoder</code>.
109: *
110: * <p>This method should be used when <code>includesLocationInfo()</code>
111: * returns false. If <code>includesLocationInfo()</code> returns true, then
112: * the supplied <code>Point</code> is ignored.
113: *
114: * @param location The <code>Point</code> specifying the upper
115: * left corner of the Raster.
116: * @throws IOException if an I/O error occurs while reading from the
117: * associated InputStream.
118: * @throws IllegalArgumentException if includesLocationInfo() returns false
119: * and location is null.
120: */
121: Raster decode(Point location) throws IOException;
122: }
|