JPEGImageEncoder


1   /*
2    * @(#)JPEGImageEncoder.java    1.7 03/12/19
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   /**********************************************************************
9    **********************************************************************
10   **********************************************************************
11   *** COPYRIGHT (c) 1997-1998 Eastman Kodak Company.                 ***
12   *** As  an unpublished  work pursuant to Title 17 of the United    ***
13   *** States Code.  All rights reserved.                             ***
14   **********************************************************************
15   **********************************************************************
16   **********************************************************************/
17  
18  package com.sun.image.codec.jpeg;
19  
20  
21  /**
22   * JPEGImageEncoder Interface
23   * 
24   * JPEGImageEncoder compresses images into JPEG data streams and
25   * writes the JPEG stream to an OutputStream.  Image data that is to
26   * be encoded can be passed in as a Raster of image data or as a
27   * BufferedImage.  Encoding or the image data into the output JPEG
28   * stream is controlled by the parameters setting found in the
29   * JPEGEncodeParam object.<P>
30   * 
31   * ColorSpace comments: First off JPEG by specification is color
32   * blind!  That said, this interface will perform some color space
33   * conversion in the name of better compression ratios.  There is no
34   * explicit mechanism in the JPEGEncodeParam interface for controlling
35   * the Encoded ColorSpace of the data when it is written to the JPEG
36   * data stream.  If an approriate colorspace setting is not already
37   * defined it is recommended that colorspace unknown is used.  Some
38   * updates to the standard color space designations have been made to
39   * allow this decoder to handle alpha channels.  See the
40   * JPEGEncodeParam description for more details on additional color
41   * space designations ( @see JPEGEncodeParam ).<P>
42   * 
43   * This encoder will process interchange, and abbreviated JPEG
44   * streams.
45   */
46  
47  import java.io.OutputStream  ;
48  import java.io.IOException  ;
49  import java.awt.image.BufferedImage  ;
50  import java.awt.image.ColorModel  ;
51  import java.awt.image.Raster  ;
52  
53  /**
54   * JPEGImageEncoder encodes buffers of image data into JPEG data
55   * streams.  Users of this interface are required to provide image data in
56   * a Raster or a BufferedImage, set the necessary parameters in the
57   * JPEGEncodeParams object and successfully open the
58   * <code>OutputStream</code> that is the destination of the encoded
59   * JPEG stream.
60   *
61   * The JPEGImageEncoder interface can encode image data into interchange,
62   * and abbreviated JPEG data streams that are written to the
63   * OutputStream provided to the encoder.
64   * <p>
65   * Note that the classes in the com.sun.image.codec.jpeg package are not
66   * part of the core Java APIs.  They are a part of Sun's JDK and JRE
67   * distributions.  Although other licensees may choose to distribute these
68   * classes, developers cannot depend on their availability in non-Sun
69   * implementations.  We expect that equivalent functionality will eventually
70   * be available in a core API or standard extension.
71   * <p>
72   * 
73   * @see     JPEGCodec
74   * @see     JPEGEncodeParam
75   * @see     Raster
76   * @see     BufferedImage
77   * @see     OutputStream
78   */
79  
80  public interface JPEGImageEncoder {
81      /**
82       * Return the stream the Encoder is currenlt associated with.
83       */
84      public OutputStream   getOutputStream();
85  
86      /**
87       * Set the JPEGEncodeParam object that is to be used for future
88       * encoding operations. 'jep' is copied so changes will not be
89       * tracked, unless you call this method again.
90       * @param jep The JPEGEncodeParam object to use for future encodings.
91       *        
92       */
93      public void setJPEGEncodeParam(JPEGEncodeParam jep);
94  
95      /**
96       * This returns a copy of the current JPEGEncodeParam object, if
97       * you want changes to affect the encoding process you must 'set'
98       * it back into the encoder (either through setJPEGEncodeParam or
99       * by providing the modified param object in the call to encode.
100      * @return A copy of the current JPEGEncodeParam object
101      */
102     public JPEGEncodeParam getJPEGEncodeParam();
103 
104     /**
105      * This is a factory method for creating JPEGEncodeParam objects.
106      * The returned object will do a credible job of encoding the
107      * given BufferedImage.
108      */
109     public JPEGEncodeParam getDefaultJPEGEncodeParam(BufferedImage   bi)
110         throws ImageFormatException;
111 
112     /** 
113      * Encode a BufferedImage as a JPEG data stream.  Note, some color
114      * conversions may takes place.  The current JPEGEncodeParam's
115      * encoded COLOR_ID should match the value returned by
116      * getDefaultColorID when given the BufferedImage's ColorModel.<P>
117 
118      * If no JPEGEncodeParam object has been provided yet a default
119      * one will be created by calling getDefaultJPEGEncodeParam with
120      * bi.
121 
122      * @param bi The BufferedImage to encode.
123      */
124     public void encode(BufferedImage   bi)
125         throws IOException  , ImageFormatException;
126 
127     /** 
128      * Encode a BufferedImage as a JPEG data stream.  Note, some color
129      * conversions may takes place.  The jep's encoded COLOR_ID should
130      * match the value returned by getDefaultColorID when given the
131      * BufferedImage's ColorModel.<P>
132 
133      * This call also sets the current JPEGEncodeParam object.  The
134      * given JPEGEncodeParam object will be used for this and future
135      * encodings.  If jep is null then a new JPEGEncodeParam object
136      * will be created by calling getDefaultJPEGEncodeParam with bi.
137 
138      * @param bi  The BufferedImage to encode.
139      * @param jep The JPEGEncodeParam object used to control the encoding.
140      */
141     public void encode(BufferedImage   bi, JPEGEncodeParam jep)
142         throws IOException  , ImageFormatException;
143 
144     /** 
145      * Returns the 'default' encoded COLOR_ID for a given ColorModel.
146      * This method is not needed in the simple case of encoding
147      * Buffered Images (the library will figure things out for you).
148      * It can be useful for encoding Rasters.  To determine what needs
149      * to be done to the image prior to encoding.
150 
151      * @param cm The ColorModel to map to an jpeg encoded COLOR_ID.
152      * @return The default mapping of cm to a jpeg Color_ID note that
153      * in a few cases color conversion is required.
154      */
155     public int getDefaultColorId(ColorModel   cm);
156 
157     /**
158      * This is a factory method for creating JPEGEncodeParam objects.
159      * It is the users responsiblity to match the colorID with the
160      * data contained in the Raster.  Failure to do so may lead to
161      * either poor compression or poor image quality.  If you don't
162      * understand much about JPEG it is strongly reccomended that you
163      * stick to the BufferedImage interfaces.
164      */
165     public JPEGEncodeParam getDefaultJPEGEncodeParam(Raster   ras, int colorID)
166         throws ImageFormatException;
167 
168     /**
169       * This is a factory method for creating JPEGEncodeParam objects.  It
170       * is the users responsiblity to match the colorID with the given
171       * number of bands, which should match the data being encoded.
172       * Failure to do so may lead to poor compression and/or poor image
173       * quality.  If you don't understand much about JPEG it is strongly
174       * recommended that you stick to the BufferedImage interface.
175       *
176       * @param numBands the number of bands that will be encoded (max of
177       * four).
178       * @param colorID the COLOR_ID for the encoded data.  This is used to
179       * set reasonable defaults in the parameter object.  This must match
180       * the number of bands given.
181       */
182     public JPEGEncodeParam getDefaultJPEGEncodeParam(int numBands,
183                                                          int colorID)
184                 throws ImageFormatException;
185 
186     /**
187      * This is a factory method for creating a JPEGEncodeParam from a
188      * JPEGDecodeParam.  This will return a new JPEGEncodeParam object
189      * that is initialized from the JPEGDecodeParam object.  All major
190      * pieces of information will be initialized from the DecodeParam
191      * (Markers, Tables, mappings).
192      * @param jdp The JPEGDecodeParam object to copy.
193      */
194     public JPEGEncodeParam getDefaultJPEGEncodeParam(JPEGDecodeParam jdp)
195         throws ImageFormatException;
196 
197     /** 
198      * Encode a Raster as a JPEG data stream.  Note that no color
199      * conversion takes place.  It is required that you match the
200      * Raster to the encoded COLOR_ID contained in the current
201      * JPEGEncodeParam object.<P>
202 
203      * If no JPEGEncodeParam object has been provided yet a
204      * new JPEGEncodeParam object will be created by calling
205      * getDefaultJPEGEncodeParam with ras and COLOR_ID_UNKNOWN.
206 
207      * @param ras The Raster to encode.
208      */
209     public void encode(Raster   ras) 
210           throws IOException  , ImageFormatException;
211 
212     /** 
213      * Encode a Raster as a JPEG data stream.  Note that no color
214      * conversion takes place.  It is required that you match the
215      * Raster to the encoded COLOR_ID contained in the JPEGEncodeParam
216      * object.
217 
218      * If jep is null a new JPEGEncodeParam object will be created by
219      * calling getDefaultJPEGEncodeParam with ras and
220      * COLOR_ID_UNKNOWN.
221 
222      * @param ras The Raster to encode.
223      * @param jep The JPEGEncodeParam object used to control the encoding.
224      */
225     public void encode(Raster   ras, JPEGEncodeParam jep) 
226         throws IOException  , ImageFormatException;
227 }
228 
229 
230 
231 
232 
233
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags