com.sun.image.codec.jpeg
Interface JPEGImageEncoder

public abstract interface JPEGImageEncoder

JPEGImageEncoder encodes buffers of image data into JPEG data streams. Users of this interface are required to provide image data in a Raster or a BufferedImage, set the necessary parameters in the JPEGEncodeParams object and successfully open the OutputStream that is the destination of the encoded JPEG stream. The JPEGImageEncoder interface can encode image data into interchange, and abbreviated JPEG data streams that are written to the OutputStream provided to the encoder.

Note that the classes in the com.sun.image.codec.jpeg package are not part of the core Java APIs. They are a part of Sun's JDK and JRE distributions. Although other licensees may choose to distribute these classes, developers cannot depend on their availability in non-Sun implementations. We expect that equivalent functionality will eventually be available in a core API or standard extension.

See Also:

JPEGCodec, JPEGEncodeParam, Raster, BufferedImage, OutputStream

Method Summary

void	encode(BufferedImage bi) Encode a BufferedImage as a JPEG data stream.
void	encode(BufferedImage bi, JPEGEncodeParam jep) Encode a BufferedImage as a JPEG data stream.
void	encode(Raster ras) Encode a Raster as a JPEG data stream.
void	encode(Raster ras, JPEGEncodeParam jep) Encode a Raster as a JPEG data stream.
int	getDefaultColorId(ColorModel cm) Returns the 'default' encoded COLOR_ID for a given ColorModel.
JPEGEncodeParam	getDefaultJPEGEncodeParam(BufferedImage bi) This is a factory method for creating JPEGEncodeParam objects.
JPEGEncodeParam	getDefaultJPEGEncodeParam(int numBands, int colorID) This is a factory method for creating JPEGEncodeParam objects.
JPEGEncodeParam	getDefaultJPEGEncodeParam(JPEGDecodeParam jdp) This is a factory method for creating a JPEGEncodeParam from a JPEGDecodeParam.
JPEGEncodeParam	getDefaultJPEGEncodeParam(Raster ras, int colorID) This is a factory method for creating JPEGEncodeParam objects.
JPEGEncodeParam	getJPEGEncodeParam() This returns a copy of the current JPEGEncodeParam object, if you want changes to affect the encoding process you must 'set' it back into the encoder (either through setJPEGEncodeParam or by providing the modified param object in the call to encode.
OutputStream	getOutputStream() Return the stream the Encoder is currenlt associated with.
void	setJPEGEncodeParam(JPEGEncodeParam jep) Set the JPEGEncodeParam object that is to be used for future encoding operations.

Method Detail

getOutputStream

public OutputStream getOutputStream()

Return the stream the Encoder is currenlt associated with.

setJPEGEncodeParam

public void setJPEGEncodeParam(JPEGEncodeParam jep)

Set the JPEGEncodeParam object that is to be used for future encoding operations. 'jep' is copied so changes will not be tracked, unless you call this method again.

Parameters:

jep - The JPEGEncodeParam object to use for future encodings.

getJPEGEncodeParam

public JPEGEncodeParam getJPEGEncodeParam()

This returns a copy of the current JPEGEncodeParam object, if you want changes to affect the encoding process you must 'set' it back into the encoder (either through setJPEGEncodeParam or by providing the modified param object in the call to encode.

Returns:

A copy of the current JPEGEncodeParam object

getDefaultJPEGEncodeParam

public JPEGEncodeParam getDefaultJPEGEncodeParam(BufferedImage bi)
                                          throws ImageFormatException

This is a factory method for creating JPEGEncodeParam objects. The returned object will do a credible job of encoding the given BufferedImage.

encode

public void encode(BufferedImage bi)
            throws IOException,
                   ImageFormatException

Encode a BufferedImage as a JPEG data stream. Note, some color conversions may takes place. The current JPEGEncodeParam's encoded COLOR_ID should match the value returned by getDefaultColorID when given the BufferedImage's ColorModel.

If no JPEGEncodeParam object has been provided yet a default one will be created by calling getDefaultJPEGEncodeParam with bi.

Parameters:

bi - The BufferedImage to encode.

encode

public void encode(BufferedImage bi,
                   JPEGEncodeParam jep)
            throws IOException,
                   ImageFormatException

Encode a BufferedImage as a JPEG data stream. Note, some color conversions may takes place. The jep's encoded COLOR_ID should match the value returned by getDefaultColorID when given the BufferedImage's ColorModel.

This call also sets the current JPEGEncodeParam object. The given JPEGEncodeParam object will be used for this and future encodings. If jep is null then a new JPEGEncodeParam object will be created by calling getDefaultJPEGEncodeParam with bi.

Parameters:

bi - The BufferedImage to encode.

jep - The JPEGEncodeParam object used to control the encoding.

getDefaultColorId

public int getDefaultColorId(ColorModel cm)

Returns the 'default' encoded COLOR_ID for a given ColorModel. This method is not needed in the simple case of encoding Buffered Images (the library will figure things out for you). It can be useful for encoding Rasters. To determine what needs to be done to the image prior to encoding.

Parameters:

cm - The ColorModel to map to an jpeg encoded COLOR_ID.

Returns:

The default mapping of cm to a jpeg Color_ID note that in a few cases color conversion is required.

getDefaultJPEGEncodeParam

public JPEGEncodeParam getDefaultJPEGEncodeParam(Raster ras,
                                                 int colorID)
                                          throws ImageFormatException

This is a factory method for creating JPEGEncodeParam objects. It is the users responsiblity to match the colorID with the data contained in the Raster. Failure to do so may lead to either poor compression or poor image quality. If you don't understand much about JPEG it is strongly reccomended that you stick to the BufferedImage interfaces.

getDefaultJPEGEncodeParam

public JPEGEncodeParam getDefaultJPEGEncodeParam(int numBands,
                                                 int colorID)
                                          throws ImageFormatException

This is a factory method for creating JPEGEncodeParam objects. It is the users responsiblity to match the colorID with the given number of bands, which should match the data being encoded. Failure to do so may lead to poor compression and/or poor image quality. If you don't understand much about JPEG it is strongly recommended that you stick to the BufferedImage interface.

Parameters:

numBands - the number of bands that will be encoded (max of four).

colorID - the COLOR_ID for the encoded data. This is used to set reasonable defaults in the parameter object. This must match the number of bands given.

getDefaultJPEGEncodeParam

public JPEGEncodeParam getDefaultJPEGEncodeParam(JPEGDecodeParam jdp)
                                          throws ImageFormatException

This is a factory method for creating a JPEGEncodeParam from a JPEGDecodeParam. This will return a new JPEGEncodeParam object that is initialized from the JPEGDecodeParam object. All major pieces of information will be initialized from the DecodeParam (Markers, Tables, mappings).

Parameters:

jdp - The JPEGDecodeParam object to copy.

encode

public void encode(Raster ras)
            throws IOException,
                   ImageFormatException

Encode a Raster as a JPEG data stream. Note that no color conversion takes place. It is required that you match the Raster to the encoded COLOR_ID contained in the current JPEGEncodeParam object.

If no JPEGEncodeParam object has been provided yet a new JPEGEncodeParam object will be created by calling getDefaultJPEGEncodeParam with ras and COLOR_ID_UNKNOWN.

Parameters:

ras - The Raster to encode.

encode

public void encode(Raster ras,
                   JPEGEncodeParam jep)
            throws IOException,
                   ImageFormatException

Encode a Raster as a JPEG data stream. Note that no color conversion takes place. It is required that you match the Raster to the encoded COLOR_ID contained in the JPEGEncodeParam object. If jep is null a new JPEGEncodeParam object will be created by calling getDefaultJPEGEncodeParam with ras and COLOR_ID_UNKNOWN.

Parameters:

ras - The Raster to encode.

jep - The JPEGEncodeParam object used to control the encoding.