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 Strings are treated in a case-retentive and case-insensitive manner.

Since:

JAI 1.1

See Also:

TileDecoder, TileEncoder

Method Summary

TileCodecParameterList	getCompatibleParameters(String modeName, TileCodecParameterList otherParamList) Returns a TileCodecParameterList valid for the specified modeName and compatible with the supplied TileCodecParameterList.
TileCodecParameterList	getDefaultParameters(String modeName) Returns the default parameters for the specified modeName as an instance of the TileCodecParameterList.
TileCodecParameterList	getDefaultParameters(String modeName, 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(String modeName)

Returns the default parameters for the specified modeName as an instance of the TileCodecParameterList.

Throws:

IllegalArgumentException - if modeName is null.

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(String modeName,
                                                   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:

IllegalArgumentException - if modeName is null.

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(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:

IllegalArgumentException - if modeName is null.

IllegalArgumentException - if modeName is not one of the modes valid for this descriptor, i.e those returned from the getSupportedNames() method.