## javax.media.jai.tilecodec
Interface TileDecoder

All Known Implementing Classes:
  TileDecoderImpl

public interface TileDecoder

An interface describing objects that transform an `InputStream` into a `Raster`.

This interface is designed to allow decoding of formats that include information about the format of the encoded tile as well as ones that don't. In order to create a `Raster`, at the very least, a `Point` specifying the top left corner of the `Raster`, a `SampleModel` specifying the data layout 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` on decoding (aside from the decoded data itself) is a `Point` specifying the top left corner of the `Raster` and a `SampleModel` specifying the data layout. The formats that do include this information should return true from the `includesSampleModelInfo()` and `includesLocationInfo()` from the associated `TileCodecDescriptor` if they include information needed to create a `SampleModel` and information needed to create the `Point` respectively. The formats that do not include this information in the encoded stream should return false. 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`.

The formats that return true from `includesSampleModelInfo()` should use the `decode()` method to cause the decoding to take place, the ones that return false should specify the `Point` location to the decoding process by using the `decode(Point)` method. Similarly the `SampleModel` must be specified as a parameter with a non-null value on the `TileCodecParameterList` passed to this `TileDecoder` if `includesSampleModelInfo()` returns false. It is expected that the `SampleModel` specified in the parameter list is the `SampleModel` of the encoded tiles, in order to get a decoded `Raster` that is equivalent to the one encoded. If the `SampleModel` specified through the parameter list is different from those of the encoded tiles, the result of decoding is undefined.

If `includesSampleModelInfo()` returns true, the `SampleModel` (if present) on the `TileCodecParameterList` is ignored.

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

Method Summary
`java.awt.image.Raster` `decode()` Returns a `Raster` that contains the decoded contents of the `InputStream` associated with this `TileDecoder`.
`java.awt.image.Raster` `decode(java.awt.Point location)` Returns a `Raster` that contains the decoded contents of the `InputStream` associated with this `TileDecoder`.
`TileCodecParameterList` `getDecodeParameterList()` Returns the current parameters as an instance of the `TileCodecParameterList` interface.
`java.lang.String` `getFormatName()` Returns the name of the format.
`java.io.InputStream` `getInputStream()` Returns the `InputStream` containing the encoded data.

Method Detail

### getFormatName

    public java.lang.String getFormatName()

  Returns the name of the format.

### getDecodeParameterList

    public TileCodecParameterList getDecodeParameterList()

  Returns the current parameters as an instance of the `TileCodecParameterList` interface.

### getInputStream

    public java.io.InputStream getInputStream()

  Returns the `InputStream` containing the encoded data.

### decode

    public java.awt.image.Raster decode()
                                 throws java.io.IOException

  Returns a `Raster` that contains the decoded contents of the `InputStream` associated with this `TileDecoder`.

  This method can perform the decoding correctly only when `includesLocationInfo()` returns true.

  Throws:
    `java.io.IOException` - if an I/O error occurs while reading from the associated InputStream.
    `java.lang.IllegalArgumentException` - if the associated TileCodecDescriptor's includesLocationInfo() returns false.

### decode

    public java.awt.image.Raster decode(java.awt.Point location)
                                 throws java.io.IOException

  Returns a `Raster` that contains the decoded contents of the `InputStream` associated with this `TileDecoder`.

  This method should be used when `includesLocationInfo()` returns false. If `includesLocationInfo()` returns true, then the supplied `Point` is ignored.

  Parameters:
    `location` - The `Point` specifying the upper left corner of the Raster.
  Throws:
    `java.io.IOException` - if an I/O error occurs while reading from the associated InputStream.
    `java.lang.IllegalArgumentException` - if includesLocationInfo() returns false and location is null.