001: /*
002: * $RCSfile: TileCodecDescriptor.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.image.SampleModel;
014: import javax.media.jai.RegistryElementDescriptor;
015: import javax.media.jai.ParameterListDescriptor;
016:
017: /**
018: * A class to describe a particular tile codec format. The <code>getName</code>
019: * method of <code>RegistryElementDescriptor</code> should be implemented
020: * to return the name of the format in an implementation of this interface.
021: * This name is also the String with which this
022: * <code>TileCodecDescriptor</code> is associated in the
023: * <code>OperationRegistry</code>. There are two
024: * complemetary modes that TileCodecs are expected to function in, the
025: * decoding mode specified by the "tileDecoder" String and the encoding
026: * mode specified by the "tileEncoder" String. It is not recommended that
027: * separate classes be used to implement the different modes, but if this
028: * is done, then <code>includesSampleModelInfo()</code> and
029: * <code>includesLocationInfo()</code> methods must return the same values
030: * from both the implementing classes.
031: *
032: * <p> In order to successfully decode an encoded tile data stream into a
033: * decoded <code>Raster</code>, at the very least, a <code>Point</code>
034: * specifying the top left corner of the <code>Raster</code>, a
035: * <code>SampleModel</code> specifying the data layout described minimally
036: * by the dataType, number of bands, width and height and a
037: * <code>DataBuffer</code> with the decoded pixel data are needed. The
038: * <code>DataBuffer</code> can be created from the information from the
039: * <code>SampleModel</code> and the decoded data. Therefore the absolute
040: * minimum information that is required in order to create a
041: * <code>Raster</code> upon decoding (aside from the decoded data itself)
042: * is the <code>Point</code> specifying the top left corner of the
043: * <code>Raster</code>, the <code>SampleModel</code> specifying the data
044: * layout. Some formats include this information about the layout of the
045: * tile while others don't. The formats that do include this information
046: * needed to create a <code>SampleModel</code> and a <code>Point</code>
047: * should return true from the <code>includesSampleModelInfo()</code> and
048: * <code>includesLocationInfo()</code> methods respectively. The formats
049: * that do not include this information in the encoded stream should return
050: * false. For decoding, the <code>TileCodecParameterList</code> providing the
051: * decoding parameters will in this case be expected to contain a parameter
052: * named "sampleModel" with a non-null <code>SampleModel</code> as its value.
053: * This <code>SampleModel</code> will be used to create the decoded
054: * <code>Raster</code> and is expected to be the same as the
055: * <code>SampleModel</code> of the tiles to be encoded.
056: *
057: * <p> All <code>String</code>s are treated in a case-retentive and
058: * case-insensitive manner.
059: *
060: * @see TileDecoder
061: * @see TileEncoder
062: * @since JAI 1.1
063: */
064: public interface TileCodecDescriptor extends RegistryElementDescriptor {
065:
066: /**
067: * Returns true if the format encodes layout information generally
068: * specified via the <code>SampleModel</code> in the encoded data stream.
069: */
070: boolean includesSampleModelInfo();
071:
072: /**
073: * Returns true if the format encodes in the data stream the location of
074: * the <code>Raster</code> with respect to its enclosing image.
075: */
076: boolean includesLocationInfo();
077:
078: /**
079: * Returns the default parameters for the specified modeName as an
080: * instance of the <code>TileCodecParameterList</code>.
081: *
082: * @throws IllegalArgumentException if <code>modeName</code> is null.
083: * @throws IllegalArgumentException if <code>modeName</code> is not
084: * one of the modes valid for this descriptor, i.e those returned
085: * from the getSupportedNames() method.
086: */
087: TileCodecParameterList getDefaultParameters(String modeName);
088:
089: /**
090: * Returns the default parameters for the specified modeName as an
091: * instance of the <code>TileCodecParameterList</code>, adding a
092: * "sampleModel" parameter with the specified value to the parameter
093: * list.
094: *
095: * <p> This method should be used when includesSampleModelInfo()
096: * returns false. If includesSampleModelInfo() returns true, the
097: * supplied <code>SampleModel</code> is ignored.
098: *
099: * <p> If a parameter named "sampleModel" exists in the default
100: * parameter list, the supplied <code>SampleModel</code> will override
101: * the value associated with this default parameter.
102: *
103: * @param sm The <code>SampleModel</code> used to create the
104: * default decoding parameter list.
105: *
106: * @throws IllegalArgumentException if <code>modeName</code> is null.
107: * @throws IllegalArgumentException if <code>modeName</code> is not
108: * one of the modes valid for this descriptor, i.e those returned
109: * from the getSupportedNames() method.
110: */
111: TileCodecParameterList getDefaultParameters(String modeName,
112: SampleModel sm);
113:
114: /**
115: * Returns a <code>TileCodecParameterList</code> valid for the
116: * specified modeName and compatible with the supplied
117: * <code>TileCodecParameterList</code>.
118: * For example, given a <code>TileCodecParameterList</code> used to
119: * encode a tile with the modeName being specified as "tileDecoder", this
120: * method will return a <code>TileCodecParameterList</code> sufficient
121: * to decode that same encoded tile.
122: *
123: * @param modeName The registry mode to return a valid parameter
124: * list for.
125: * @param otherParamList The parameter list for which a compatible
126: * parameter list for the specified modeName is
127: * to be returned.
128: *
129: * @throws IllegalArgumentException if <code>modeName</code> is null.
130: * @throws IllegalArgumentException if <code>modeName</code> is not
131: * one of the modes valid for this descriptor, i.e those returned
132: * from the getSupportedNames() method.
133: */
134: TileCodecParameterList getCompatibleParameters(String modeName,
135: TileCodecParameterList otherParamList);
136: }
|