KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > sun > image > codec > jpeg > JPEGEncodeParam


1 /*
2  * @(#)JPEGEncodeParam.java 1.8 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  * JPEGEncodeParam encapsulates tables and options necessary to
23  * control encoding of JPEG data streams. Parameters are either set
24  * explicitly by the application for encoding, or read from another
25  * JPEG header.<p>
26
27  * When working with BufferedImages, the codec will attempt to match
28  * the encoded JPEG COLOR_ID with the ColorModel in the BufferedImage.
29  * This is not always possible (the default mappings are listed
30  * below). In cases where unsupported conversions are required (or
31  * odd image colorspaces are in use) the user must either convert the
32  * image data to a known ColorSpace or encode the data from a raster.
33  * When encoding rasters no colorspace adjustments are made, so the
34  * user must do any conversions required to get to the encoded
35  * COLOR_ID.
36  
37  * The COLOR_ID for the encoded images is used to control the JPEG
38  * codec's inital values for Huffman and Quantization Tables as well
39  * as subsampling factors. It is also used to determine what color
40  * conversion should be performed to obtain the best encoding.<p>
41
42  * Note: The color ids described herein are simply enumerated values
43  * that influence data processing by the JPEG codec. JPEG compression
44  * is, by definition, color blind. These values are used as hints when
45  * compressing JPEG data. Through these values the JPEG codec can
46  * perform some default rotation of data into spaces that will aid in
47  * getting better compression ratios.<P>
48
49  * Example behaviour is described below. Since these mappings are
50  * likely to change in the future it is strongly recommended that you
51  * make use of the @see JPEGImageEncoder.getDefaultParamBlock calls
52  * and check the encodedColorID for your particular BufferedImage.
53
54  * In extreme cases is may be necessary for the user to convert the
55  * image to the desired colorspace, and encode it from a Raster. In
56  * this case the API programmer must specify the colorID of the data
57  * in the Raster and no color conversion will take place.
58  <pre>
59  ENCODING:
60  
61  BufferedImage Type/Instance JPEG (Encoded) Color ID
62  ======================== =======================
63  TYPE_GRAY COLOR_ID_GRAYSCALE
64  TYPE_RGB COLOR_ID_YCbCr
65  TYPE_YCbCr COLOR_ID_YCbCr
66  TYPE_YCbCr/CS_PYCC COLOR_ID_PYCC
67  TYPE_CMYK COLOR_ID_CMYK
68  TYPE_RGB (w/ alpha) COLOR_ID_YCbCrA
69  TYPE_YCbCr (w/ alpha) COLOR_ID_YCbCrA
70  TYPE_YCbCr/CS_PYCC (w/ alpha) COLOR_ID_PYCCA
71  ** Any Other ** COLOR_ID_UNKNOWN
72  </pre>
73
74  * When the user wants more control than the BufferedImage conversions
75  * provide, the user must encode the data from a Raster. In this case
76  * the data undergoes no color conversion at all. It is the user's
77  * responsiblity to perform the desired conversions.<P>
78  
79  * If you intend to write a JFIF image (by including the APP0_MARKER)
80  * the encoded COLOR_ID must be one of: COLOR_ID_UNKNOWN,
81  * COLOR_ID_GRAYSCALE, COLOR_ID_YCbCr, or COLOR_ID_CMYK. In all other
82  * instances an ImageformatException will be thrown.<P>
83
84  * <B>IMPORTANT:</B> an Alpha RGB BufferedImage will not map to a
85  * valid JFIF stream, you must strip off the alpha prior to encoding
86  * if you want a JFIF file. If the APP0 marker is set and you do not
87  * strip off the Alpha, an ImageFormatException will be thrown.
88  * <p>
89  * Note that the classes in the com.sun.image.codec.jpeg package are not
90  * part of the core Java APIs. They are a part of Sun's JDK and JRE
91  * distributions. Although other licensees may choose to distribute these
92  * classes, developers cannot depend on their availability in non-Sun
93  * implementations. We expect that equivalent functionality will eventually
94  * be available in a core API or standard extension.
95  * <p>
96  */
97
98 public interface JPEGEncodeParam
99     extends Cloneable JavaDoc, JPEGDecodeParam
100 {
101     public Object JavaDoc clone();
102
103     /**
104      * Set the horizontal subsample factor for the given component.
105      * Note that the subsample factor is the number of input pixels
106      * that contribute to each output pixel (ussually 2 for YCC).
107      * @param component The component being specified.
108      * @param subsample The subsampling factor being specified.
109      */
110     public void setHorizontalSubsampling(int component,
111                                          int subsample);
112     
113     /**
114      * Set the vertical subsample factor for the given component. Note that
115      * the subsample factor is the number of input pixels that
116      * contribute to each output pixel (ussually 2 for YCC).
117      * @param component The component being specified.
118      * @param subsample The subsampling factor being specified.
119      */
120     public void setVerticalSubsampling(int component,
121                                        int subsample);
122     
123     /**
124      * Sets the coefficient quantization tables at index
125      * passed. tableNum must range in value from 0 - 3.
126      * @param qtable that will be used.
127      * @param tableNum the index of the table to be set.
128      */
129     public void setQTable( int tableNum, JPEGQTable qTable );
130
131     /** Sets the DC Huffman coding table at index to the table provided.
132      * @param huffTable JPEGHuffmanTable that will be assigned
133      * to index tableNum.
134      * @param tableNum - the index of the table to be set.
135      * @exception IllegalArgumentException - thrown if the tableNum
136      * is out of range. Index must range in value from 0 - 3.
137      */
138     public void setDCHuffmanTable( int tableNum,
139                                    JPEGHuffmanTable huffTable);
140
141     /** Sets the AC Huffman coding table at index to the table provided.
142      * @param huffTable JPEGHuffmanTable that will be assigned
143      * to index tableNum.
144      * @param tableNum - the index of the table to be set.
145      * @exception IllegalArgumentException - thrown if the tableNum
146      * is out of range. Index must range in value from 0 - 3.
147      */
148     public void setACHuffmanTable( int tableNum,
149                                    JPEGHuffmanTable huffTable);
150
151
152     /**
153      * Sets the mapping between a component and it's DC Huffman Table.
154      * @param component The component to set the mapping for
155      * @param table The DC Huffman table to use for component
156      */
157     public void setDCHuffmanComponentMapping( int component, int table);
158     /**
159      * Sets the mapping between a component and it's AC Huffman Table.
160      * @param component The component to set the mapping for
161      * @param table The AC Huffman table to use for component
162      */
163     public void setACHuffmanComponentMapping( int component, int table);
164     /**
165      * Sets the mapping between a component and it's Quantization Table.
166      * @param component The component to set the mapping for
167      * @param table The Quantization Table to use for component
168      */
169     public void setQTableComponentMapping( int component, int table);
170
171     /**
172      * Set the flag indicating the validity of the table information
173      * in the ParamBlock. This is used to indicate if tables should
174      * be included when encoding.
175      */
176     public void setImageInfoValid(boolean flag);
177
178     /**
179      * Set the flag indicating the validity of the image information
180      * in the ParamBlock. This is used to indicates if image data
181      * should be written when encoding.
182      */
183     public void setTableInfoValid(boolean flag);
184
185     /**
186      * Sets the marker data to be written to the output data stream.
187      * This removes any existing marker data in the JPEParm object.
188      * This can be used to remove the default APP0 marker by calling
189      * it with data set to null.
190      * @param marker The marker to set the data for.
191      * @param data the new set of data to be written.
192      */
193     public void setMarkerData(int marker, byte[][] data);
194
195     /**
196      * Appends 'data' to the array of byte[] associated with
197      * marker. This will result in additional instance of the marker
198      * being written (one for each byte[] in the array.).
199      * @param marker The marker to add and instance of.
200      * @param data the data to be written.
201      */
202     public void addMarkerData(int marker, byte []data);
203
204     /**
205      * Set the MCUs per restart, or 0 for no restart markers.
206      * @param restartInterval number MCUs per restart marker.
207      */
208     public void setRestartInterval( int restartInterval );
209
210
211     /**
212      * Set the pixel size units This value is copied into the APP0
213      * marker (if that marker is written). This value isn't used by
214      * the JPEG code.
215      * @param unit One of the DENSITY_UNIT_* values.
216      */
217     public void setDensityUnit( int unit);
218     /**
219      * Set the horizontal pixel density This value is written into the
220      * APP0 marker. It isn't used by the JPEG code.
221      * @param density the horizontal pixel density, in units
222      * described by @see JPEGParam.getDensityUnit.
223      */
224     public void setXDensity( int density );
225     /**
226      * Set the vertical pixel density. This value is copied into
227      * the JFIF APP0 marker. It isn't used by the JPEG code.
228      * @param density The verticle pixel density, in units
229      * described by @see JPEGParam.getDensityUnit.
230      */
231     public void setYDensity( int density );
232
233     /**
234      * This creates new Quantization tables that replace the currently
235      * installed Quantization tables. It also updates the Component
236      * QTable mapping to the default for the current encoded COLOR_ID.
237
238      * The Created Quantization table varies from very high
239      * compression, very low quality, (0.0) to low compression, very
240      * high quality (1.0) based on the quality parameter.<P>
241      
242      * At a quality level of 1.0 the table will be all 1's which will
243      * lead to no loss of data due to quantization (however chrominace
244      * subsampling, if used, and roundoff error in the DCT will still
245      * degrade the image some what).<P>
246
247      * This is a linear manipulation of the standard Chrominance
248      * Q-Table.<P>
249
250      * <pre>Some guidelines: 0.75 high quality
251      * 0.5 medium quality
252      * 0.25 low quality
253      * </pre>
254      * @param quality 0.0-1.0 setting of desired quality level.
255      * @param forceBaseline force baseline quantization table
256      */
257     public void setQuality(float quality, boolean forceBaseline );
258 }
259
Popular Tags