## javax.media.jai.tilecodec
Interface TileCodecDescriptor

All Superinterfaces:
  RegistryElementDescriptor

All Known Implementing Classes:
  TileCodecDescriptorImpl

public interface TileCodecDescriptor
extends RegistryElementDescriptor

A class to describe a particular tile codec format. The `getName` method of `RegistryElementDescriptor` should be implemented to return the name of the format in an implementation of this interface. This name is also the String with which this `TileCodecDescriptor` is associated in the `OperationRegistry`. There are two complemetary modes that TileCodecs are expected to function in, the decoding mode specified by the "tileDecoder" String and the encoding mode specified by the "tileEncoder" String. It is not recommended that separate classes be used to implement the different modes, but if this is done, then `includesSampleModelInfo()` and `includesLocationInfo()` methods must return the same values from both the implementing classes.

In order to successfully decode an encoded tile data stream into a decoded `Raster`, at the very least, a `Point` specifying the top left corner of the `Raster`, a `SampleModel` specifying the data layout described minimally by the dataType, number of bands, width and height and a `DataBuffer` with the decoded pixel data are needed. The `DataBuffer` can be created from the information from the `SampleModel` and the decoded data. Therefore the absolute minimum information that is required in order to create a `Raster` upon decoding (aside from the decoded data itself) is the `Point` specifying the top left corner of the `Raster`, the `SampleModel` specifying the data layout. Some formats include this information about the layout of the tile while others don't. The formats that do include this information needed to create a `SampleModel` and a `Point` should return true from the `includesSampleModelInfo()` and `includesLocationInfo()` methods respectively. The formats that do not include this information in the encoded stream should return false. For decoding, the `TileCodecParameterList` providing the decoding parameters will in this case be expected to contain a parameter named "sampleModel" with a non-null `SampleModel` as its value. This `SampleModel` will be used to create the decoded `Raster` and is expected to be the same as the `SampleModel` of the tiles to be encoded.

All `String`s are treated in a case-retentive and case-insensitive manner.

Since:
  1.1
See Also:
  `TileDecoder`, `TileEncoder`

Method Summary
`TileCodecParameterList` `getCompatibleParameters(java.lang.String modeName, TileCodecParameterList otherParamList)` Returns a `TileCodecParameterList` valid for the specified modeName and compatible with the supplied `TileCodecParameterList`.
`TileCodecParameterList` `getDefaultParameters(java.lang.String modeName)` Returns the default parameters for the specified modeName as an instance of the `TileCodecParameterList`.
`TileCodecParameterList` `getDefaultParameters(java.lang.String modeName, java.awt.image.SampleModel sm)` Returns the default parameters for the specified modeName as an instance of the `TileCodecParameterList`, adding a "sampleModel" parameter with the specified value to the parameter list.
`boolean` `includesLocationInfo()` Returns true if the format encodes in the data stream the location of the `Raster` with respect to its enclosing image.
`boolean` `includesSampleModelInfo()` Returns true if the format encodes layout information generally specified via the `SampleModel` in the encoded data stream.

Methods inherited from interface javax.media.jai.RegistryElementDescriptor
`arePropertiesSupported, getName, getParameterListDescriptor, getPropertyGenerators, getSupportedModes, isModeSupported`

Method Detail

### includesSampleModelInfo

    public boolean includesSampleModelInfo()

  Returns true if the format encodes layout information generally specified via the `SampleModel` in the encoded data stream.

### includesLocationInfo

    public boolean includesLocationInfo()

  Returns true if the format encodes in the data stream the location of the `Raster` with respect to its enclosing image.

### getDefaultParameters

    public TileCodecParameterList getDefaultParameters(java.lang.String modeName)

  Returns the default parameters for the specified modeName as an instance of the `TileCodecParameterList`.
  Throws:
    `java.lang.IllegalArgumentException` - if `modeName` is null.
    `java.lang.IllegalArgumentException` - if `modeName` is not one of the modes valid for this descriptor, i.e those returned from the getSupportedNames() method.

### getDefaultParameters

    public TileCodecParameterList getDefaultParameters(java.lang.String modeName,
                                                       java.awt.image.SampleModel sm)

  Returns the default parameters for the specified modeName as an instance of the `TileCodecParameterList`, adding a "sampleModel" parameter with the specified value to the parameter list.

  This method should be used when includesSampleModelInfo() returns false. If includesSampleModelInfo() returns true, the supplied `SampleModel` is ignored.

  If a parameter named "sampleModel" exists in the default parameter list, the supplied `SampleModel` will override the value associated with this default parameter.

  Parameters:
    `sm` - The `SampleModel` used to create the default decoding parameter list.
  Throws:
    `java.lang.IllegalArgumentException` - if `modeName` is null.
    `java.lang.IllegalArgumentException` - if `modeName` is not one of the modes valid for this descriptor, i.e those returned from the getSupportedNames() method.

### getCompatibleParameters

    public TileCodecParameterList getCompatibleParameters(java.lang.String modeName,
                                                          TileCodecParameterList otherParamList)

  Returns a `TileCodecParameterList` valid for the specified modeName and compatible with the supplied `TileCodecParameterList`. For example, given a `TileCodecParameterList` used to encode a tile with the modeName being specified as "tileDecoder", this method will return a `TileCodecParameterList` sufficient to decode that same encoded tile.
  Parameters:
    `modeName` - The registry mode to return a valid parameter list for.
    `otherParamList` - The parameter list for which a compatible parameter list for the specified modeName is to be returned.
  Throws:
    `java.lang.IllegalArgumentException` - if `modeName` is null.
    `java.lang.IllegalArgumentException` - if `modeName` is not one of the modes valid for this descriptor, i.e those returned from the getSupportedNames() method.