com.sun.media.jai.codec
Class ImageCodec

java.lang.Object
  |
  +--com.sun.media.jai.codec.ImageCodec

public abstract class ImageCodec

extends Object

An abstract class allowing the creation of image decoders and encoders. Instances of ImageCodec may be registered. Once a codec has been registered, the format name associated with it may be used as the name parameter in the createImageEncoder() and createImageDecoder() methods.

Additionally, subclasses of ImageCodec are able to perform recognition of their particular format, wither by inspection of a fixed-length file header or by arbitrary access to the source data stream.

Format recognition is performed by two variants of the isFormatRecognized() method. Which variant should be called is determined by the output of the codec's getNumHeaderBytes() method, which returns 0 if arbitrary access to the stream is required, and otherwise returns the number of header bytes required to recognize the format. Each subclass of ImageCodec needs to implement only one of the two variants.

This class is not a committed part of the JAI API. It may be removed or changed in future releases of JAI.

Constructor Summary

protected

ImageCodec() Allow only subclasses to instantiate this class.

Method Summary

abstract boolean	canEncodeImage(RenderedImage im, ImageEncodeParam param) Returns true if the given image and encoder param object are suitable for encoding by this ImageCodec.
static ColorModel	createComponentColorModel(SampleModel sm) A convenience method to create an instance of ComponentColorModel suitable for use with the given SampleModel.
static ColorModel	createGrayIndexColorModel(SampleModel sm, boolean blackIsZero) A convenience methods to create an instance of IndexColorModel suitable for the given 1-banded SampleModel.
protected ImageDecoder	createImageDecoder(File src, ImageDecodeParam param) Returns an implementation of the ImageDecoder interface appropriate for that codec.
protected ImageDecoder	createImageDecoder(InputStream src, ImageDecodeParam param) Returns an implementation of the ImageDecoder interface appropriate for that codec.
protected abstract ImageDecoder	createImageDecoder(SeekableStream src, ImageDecodeParam param) In a concrete subclass of ImageCodec, returns an implementation of the ImageDecoder interface appropriate for that codec.
static ImageDecoder	createImageDecoder(String name, File src, ImageDecodeParam param) Returns an ImageDecoder object suitable for decoding from the supplied File, using the supplied ImageDecodeParam object.
static ImageDecoder	createImageDecoder(String name, InputStream src, ImageDecodeParam param) Returns an ImageDecoder object suitable for decoding from the supplied InputStream, using the supplied ImageDecodeParam object.
static ImageDecoder	createImageDecoder(String name, SeekableStream src, ImageDecodeParam param) Returns an ImageDecoder object suitable for decoding from the supplied SeekableStream, using the supplied ImageDecodeParam object.
protected abstract ImageEncoder	createImageEncoder(OutputStream dst, ImageEncodeParam param) In a concrete subclass of ImageCodec, returns an implementation of the ImageEncoder interface appropriate for that codec.
static ImageEncoder	createImageEncoder(String name, OutputStream dst, ImageEncodeParam param) Returns an ImageEncoder object suitable for encoding to the supplied OutputStream, using the supplied ImageEncoderParam object.
static ImageCodec	getCodec(String name) Returns the ImageCodec associated with the given name.
static Enumeration	getCodecs() Returns an Enumeration of all regstered ImageCodec objects.
protected abstract Class	getDecodeParamClass() Returns a Class object indicating the proper subclass of ImageDecodeParam to be used with this ImageCodec.
static String[]	getDecoderNames(SeekableStream src) Returns an array of Strings indicating the names of registered ImageCodecs that may be appropriate for reading the given SeekableStream.
protected abstract Class	getEncodeParamClass() Returns a Class object indicating the proper subclass of ImageEncodeParam to be used with this ImageCodec.
static String[]	getEncoderNames(RenderedImage im, ImageEncodeParam param) Returns an array of Strings indicating the names of registered ImageCodecs that may be appropriate for writing the given RenderedImage, using the optional ImageEncodeParam, which may be null.
abstract String	getFormatName() Returns the name of this image format.
int	getNumHeaderBytes() Returns the number of bytes of header needed to recognize the format, or 0 if an arbitrary number of bytes may be needed.
boolean	isFormatRecognized(byte[] header) Returns true if the format is recognized in the initial portion of a stream.
boolean	isFormatRecognized(SeekableStream src) Returns true if the format is recognized in the input data stream.
static void	registerCodec(ImageCodec codec) Associates an ImageCodec with its format name, as determined by its getFormatName() method.
static void	unregisterCodec(String name) Unregisters the ImageCodec object currently responsible for handling the named format.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ImageCodec

protected ImageCodec()

Allow only subclasses to instantiate this class.

Method Detail

getCodec

public static ImageCodec getCodec(String name)

Returns the ImageCodec associated with the given name. null is returned if no codec is registered with the given name. Case is not significant.

Parameters:

name - The name associated with the codec.

Returns:

The associated ImageCodec, or null.

registerCodec

public static void registerCodec(ImageCodec codec)

Associates an ImageCodec with its format name, as determined by its getFormatName() method. Case is not significant. Any codec previously associated with the name is discarded.

Parameters:

codec - The ImageCodec object to be registered.

unregisterCodec

public static void unregisterCodec(String name)

Unregisters the ImageCodec object currently responsible for handling the named format. Case is not significant.

Parameters:

name - The name associated with the codec to be removed.

getCodecs

public static Enumeration getCodecs()

Returns an Enumeration of all regstered ImageCodec objects.

createImageEncoder

public static ImageEncoder createImageEncoder(String name,
                                              OutputStream dst,
                                              ImageEncodeParam param)

Returns an ImageEncoder object suitable for encoding to the supplied OutputStream, using the supplied ImageEncoderParam object.

Parameters:

name - The name associated with the codec.

dst - An OutputStream to write to.

param - An instance of ImageEncoderParam suitable for use with the named codec, or null.

Returns:

An instance of ImageEncoder, or null.

createImageDecoder

public static ImageDecoder createImageDecoder(String name,
                                              InputStream src,
                                              ImageDecodeParam param)

Returns an ImageDecoder object suitable for decoding from the supplied InputStream, using the supplied ImageDecodeParam object.

Parameters:

name - The name associated with the codec.

src - An InputStream to read from.

param - An instance of ImageDecodeParam suitable for use with the named codec, or null.

Returns:

An instance of ImageDecoder, or null.

createImageDecoder

public static ImageDecoder createImageDecoder(String name,
                                              File src,
                                              ImageDecodeParam param)
                                       throws IOException

Returns an ImageDecoder object suitable for decoding from the supplied File, using the supplied ImageDecodeParam object.

Parameters:

name - The name associated with the codec.

src - A File to read from.

param - An instance of ImageDecodeParam suitable for use with the named codec, or null.

Returns:

An instance of ImageDecoder, or null.

createImageDecoder

public static ImageDecoder createImageDecoder(String name,
                                              SeekableStream src,
                                              ImageDecodeParam param)

Returns an ImageDecoder object suitable for decoding from the supplied SeekableStream, using the supplied ImageDecodeParam object.

Parameters:

name - The name associated with the codec.

src - A SeekableStream to read from.

param - An instance of ImageDecodeParam suitable for use with the named codec, or null.

Returns:

An instance of ImageDecoder, or null.

getDecoderNames

public static String[] getDecoderNames(SeekableStream src)

Returns an array of Strings indicating the names of registered ImageCodecs that may be appropriate for reading the given SeekableStream.

If the src SeekableStream does not support seeking backwards (that is, its canSeekBackwards() method returns false) then only FormatRecognizers that require only a fixed-length header will be checked.

If the src stream does not support seeking backwards, it must support marking, as determined by its markSupported() method.

Parameters:

src - A SeekableStream which optionally supports seeking backwards.

Returns:

An array of Strings.

Throws:

IllegalArgumentException - if src supports neither seeking backwards nor marking.

getEncoderNames

public static String[] getEncoderNames(RenderedImage im,
                                       ImageEncodeParam param)

Returns an array of Strings indicating the names of registered ImageCodecs that may be appropriate for writing the given RenderedImage, using the optional ImageEncodeParam, which may be null.

Parameters:

im - A RenderedImage to be encodec.

param - An ImageEncodeParam, or null.

Returns:

An array of Strings.

getFormatName

public abstract String getFormatName()

Returns the name of this image format.

Returns:

A String containing the name of the image format supported by this codec.

getNumHeaderBytes

public int getNumHeaderBytes()

Returns the number of bytes of header needed to recognize the format, or 0 if an arbitrary number of bytes may be needed. The default implementation returns 0.

The return value must be a constant for all instances of each particular subclass of ImageCodec.

Although it is legal to always return 0, in some cases processing may be more efficient if the number of bytes needed is known in advance.

isFormatRecognized

public boolean isFormatRecognized(byte[] header)

Returns true if the format is recognized in the initial portion of a stream. The header will be passed in as a byte array of length getNumHeaderBytes(). This method should be called only if getNumHeaderBytes() returns a value greater than 0.

The default implementation throws an exception to indicate that it should never be called.

Parameters:

header - An array of bytes containing the input stream header.

Returns:

true if the format is recognized.

isFormatRecognized

public boolean isFormatRecognized(SeekableStream src)
                           throws IOException

Returns true if the format is recognized in the input data stream. This method should be called only if getNumHeaderBytesNeeded() returns 0.

The source SeekableStream is guaranteed to support seeking backwards, and should be seeked to 0 prior to calling this method.

The default implementation throws an exception to indicate that it should never be called.

Parameters:

src - A SeekableStream containing the input data.

Returns:

true if the format is recognized.

getEncodeParamClass

protected abstract Class getEncodeParamClass()

Returns a Class object indicating the proper subclass of ImageEncodeParam to be used with this ImageCodec. If encoding is not supported by this codec, null is returned. If encoding is supported, but a parameter object is not used during encoding, Object.class is returned to signal this fact.

getDecodeParamClass

protected abstract Class getDecodeParamClass()

Returns a Class object indicating the proper subclass of ImageDecodeParam to be used with this ImageCodec. If encoding is not supported by this codec, null is returned. If decoding is supported, but a parameter object is not used during decoding, Object.class is returned to signal this fact.

createImageEncoder

protected abstract ImageEncoder createImageEncoder(OutputStream dst,
                                                   ImageEncodeParam param)

In a concrete subclass of ImageCodec, returns an implementation of the ImageEncoder interface appropriate for that codec.

Parameters:

dst - An OutputStream to write to.

param - An instance of ImageEncoderParam suitable for use with the ImageCodec subclass, or null.

Returns:

An instance of ImageEncoder.

canEncodeImage

public abstract boolean canEncodeImage(RenderedImage im,
                                       ImageEncodeParam param)

Returns true if the given image and encoder param object are suitable for encoding by this ImageCodec. For example, some codecs may only deal with images with a certain number of bands; an attempt to encode an image with an unsupported number of bands will fail.

Parameters:

im - a RenderedImage whose ability to be encoded is to be determined.

param - a suitable ImageEncodeParam object, or null.

createImageDecoder

protected ImageDecoder createImageDecoder(InputStream src,
                                          ImageDecodeParam param)

Returns an implementation of the ImageDecoder interface appropriate for that codec. Subclasses of ImageCodec may override this method if they wish to accept data directly from an InputStream; otherwise, this method will convert the source into a backwards-seekable SeekableStream and call the appropriate version of createImageDecoder for that data type.

Instances of ImageCodec that do not require the ability to seek backwards in their source SeekableStream should override this method in order to avoid the default call to SeekableStream.wrapInputStream(src, true).

Parameters:

dst - An InputStream to read from.

param - An instance of ImageDecodeParam suitable for use with the ImageCodec subclass, or null.

Returns:

An instance of ImageDecoder.

createImageDecoder

protected ImageDecoder createImageDecoder(File src,
                                          ImageDecodeParam param)
                                   throws IOException

Returns an implementation of the ImageDecoder interface appropriate for that codec. Subclasses of ImageCodec may override this method if they wish to accept data directly from a File; otherwise, this method will convert the source into a SeekableStream and call the appropriate version of createImageDecoder for that data type.

Parameters:

dst - A File to read from.

param - An instance of ImageDecodeParam suitable for use with the ImageCodec subclass, or null.

Returns:

An instance of ImageDecoder.

createImageDecoder

protected abstract ImageDecoder createImageDecoder(SeekableStream src,
                                                   ImageDecodeParam param)

In a concrete subclass of ImageCodec, returns an implementation of the ImageDecoder interface appropriate for that codec.

Parameters:

dst - A SeekableStream to read from.

param - An instance of ImageDecodeParam suitable for use with the ImageCodec subclass, or null.

Returns:

An instance of ImageDecoder.

createGrayIndexColorModel

public static ColorModel createGrayIndexColorModel(SampleModel sm,
                                                   boolean blackIsZero)

A convenience methods to create an instance of IndexColorModel suitable for the given 1-banded SampleModel.

Parameters:

sm - a 1-banded SampleModel.

blackIsZero - true if the gray ramp should go from black to white, falseotherwise.

createComponentColorModel

public static ColorModel createComponentColorModel(SampleModel sm)

A convenience method to create an instance of ComponentColorModel suitable for use with the given SampleModel. The SampleModel should have a data type of DataBuffer.TYPE_BYTE, TYPE_USHORT, or TYPE_INT and between 1 and 4 bands. Depending on the number of bands of the SampleModel, either a gray, gray+alpha, rgb, or rgb+alpha ColorModel is returned.