JPEGDecodeParam


1   /*
2    * @(#)JPEGDecodeParam.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  
23   * JPEGDecodeParam encapsulates tables and options necessary to
24   * control decoding JPEG datastreams. Parameters are either set explicitly
25   * by the application for encoding, or read from the JPEG header for
26   * decoding.  In the case of decoding abbreviated data streams the
27   * application may need to set some/all of the values it's self.  <p>
28  
29   * When working with BufferedImages (@see
30   * JPEGImageDecoder.decodeBufferedImage), the codec will attempt to
31   * generate an appropriate ColorModel for the JPEG COLOR_ID. This is
32   * not always possible (example mappings are listed below) .  In cases
33   * where unsupported conversions are required, or unknown encoded
34   * COLOR_ID's are in use, the user must request the data as a Raster
35   * and perform the transformations themselves.  When decoding into a
36   * raster (@see JPEGImageDecoder.decodeRaster) no ColorSpace
37   * adjustments are made.
38   
39   * Note: The color ids described herein are simply enumerated values
40   * that influence data processing by the JPEG codec.  JPEG compression
41   * is by definition color blind.  These values are used as hints when
42   * decompressing JPEG data.  Of particular interest is the default
43   * conversion from YCbCr to sRGB when decoding buffered Images.<P>
44  
45   * Note: because JPEG is mostly color-blind color fidelity can not be
46   * garunteed.  This will hopefully be rectified in the near future by
47   * the wide spread inclusion of ICC-profiles in the JPEG data stream
48   * (as a special marker).
49  
50   * The following is an example of the conversions that take place.
51   * This is only a guide to the types of conversions that are allowed.
52   * This list is likely to change in the future so it is
53   * <B>strongly</B> recommended that you check for thrown
54   * ImageFormatExceptions and check the actual ColorModel associated
55   * with the BufferedImage returned rather than make assumtions.
56   * <pre>
57      DECODING:
58      
59      JPEG (Encoded) Color ID         BufferedImage ColorSpace
60      =======================         ========================
61      COLOR_ID_UNKNOWN                ** Invalid **
62      COLOR_ID_GRAY                   CS_GRAY
63      COLOR_ID_RGB                    CS_sRGB
64      COLOR_ID_YCbCr                  CS_sRGB
65      COLOR_ID_CMYK                   ** Invalid **
66      COLOR_ID_PYCC                   CS_PYCC
67      COLOR_ID_RGBA                   CS_sRGB (w/ alpha)
68      COLOR_ID_YCbCrA                 CS_sRGB (w/ alpha)
69      COLOR_ID_RGBA_INVERTED          ** Invalid **
70      COLOR_ID_YCbCrA_INVERTED        ** Invalid **
71      COLOR_ID_PYCCA                  CS_PYCC (w/ alpha)
72      COLOR_ID_YCCK                   ** Invalid **
73      </pre>
74  
75   * If the user needs better control over conversion, the user must
76   * request the data as a Raster and handle the conversion of the image
77   * data themselves.<p>
78  
79   * When decoding JFIF files the encoded COLOR_ID will always be one
80   * of: COLOR_ID_UNKNOWN, COLOR_ID_GRAY, COLOR_ID_RGB, COLOR_ID_YCbCr,
81   * COLOR_ID_CMYK, or COLOR_ID_YCCK
82   * <p>
83   * Note that the classes in the com.sun.image.codec.jpeg package are not
84   * part of the core Java APIs.  They are a part of Sun's JDK and JRE
85   * distributions.  Although other licensees may choose to distribute these
86   * classes, developers cannot depend on their availability in non-Sun
87   * implementations.  We expect that equivalent functionality will eventually
88   * be available in a core API or standard extension.
89   * <p>
90   */
91  
92  public interface JPEGDecodeParam extends Cloneable   {
93      /** Unknown or Undefined Color ID */
94      public final static int COLOR_ID_UNKNOWN = 0;
95      
96      /** Monochrome */
97      public final static int COLOR_ID_GRAY = 1;
98  
99      /** Red, Green, and Blue */
100     public final static int COLOR_ID_RGB = 2;
101 
102     /** YCbCr */
103     public final static int COLOR_ID_YCbCr = 3;
104 
105     /** CMYK */
106     public final static int COLOR_ID_CMYK = 4;
107 
108     /** PhotoYCC */
109     public final static int COLOR_ID_PYCC = 5;
110  
111     /** RGB-Alpha */
112     public final static int COLOR_ID_RGBA = 6;
113  
114     /** YCbCr-Alpha */
115     public final static int COLOR_ID_YCbCrA = 7;
116 
117     /** RGB-Alpha with R, G, and B inverted.*/
118     public final static int COLOR_ID_RGBA_INVERTED = 8;
119  
120     /** YCbCr-Alpha with Y, Cb, and Cr inverted.*/
121     public final static int COLOR_ID_YCbCrA_INVERTED = 9;
122     
123     /** PhotoYCC-Alpha */
124     public final static int COLOR_ID_PYCCA = 10;
125 
126     /** YCbCrK */
127     public final static int COLOR_ID_YCCK = 11;     
128 
129     /** Number of color ids defined. */
130     final static int NUM_COLOR_ID = 12;
131 
132     /** Number of allowed Huffman and Quantization Tables */
133     final static int  NUM_TABLES = 4;  
134     
135     /** The X and Y units simply indicate the aspect ratio of the pixels. */
136     public  final static int DENSITY_UNIT_ASPECT_RATIO = 0;
137     /** Pixel density is in pixels per inch. */
138     public  final static int DENSITY_UNIT_DOTS_INCH    = 1;
139     /** Pixel density is in pixels per centemeter. */
140     public  final static int DENSITY_UNIT_DOTS_CM      = 2;
141     /** The max known value for DENSITY_UNIT */
142     final static int NUM_DENSITY_UNIT = 3;
143 
144     /** APP0 marker - JFIF info */
145     public final static int APP0_MARKER  = 0xE0;
146     /** APP1 marker */
147     public final static int APP1_MARKER  = 0xE1;
148     /** APP2 marker */
149     public final static int APP2_MARKER  = 0xE2;
150     /** APP3 marker */
151     public final static int APP3_MARKER  = 0xE3;
152     /** APP4 marker */
153     public final static int APP4_MARKER  = 0xE4;
154     /** APP5 marker */
155     public final static int APP5_MARKER  = 0xE5;
156     /** APP6 marker */
157     public final static int APP6_MARKER  = 0xE6;
158     /** APP7 marker */
159     public final static int APP7_MARKER  = 0xE7;
160     /** APP8 marker */
161     public final static int APP8_MARKER  = 0xE8;
162     /** APP9 marker */
163     public final static int APP9_MARKER  = 0xE9;
164     /** APPA marker */
165     public final static int APPA_MARKER  = 0xEA;
166     /** APPB marker */
167     public final static int APPB_MARKER  = 0xEB;
168     /** APPC marker */
169     public final static int APPC_MARKER  = 0xEC;
170     /** APPD marker */
171     public final static int APPD_MARKER  = 0xED;
172     /** APPE marker - Adobe info */
173     public final static int APPE_MARKER  = 0xEE;
174     /** APPF marker */
175     public final static int APPF_MARKER  = 0xEF;
176 
177     /** Adobe marker indicates presence/need for Adobe marker. */
178     public final static int COMMENT_MARKER = 0XFE;
179 
180     public Object   clone();
181     
182     /** 
183      * Get the image width
184      * @return int the width of the image data in pixels.
185      */
186     public int  getWidth();
187     /** Get the image height
188      * @return The height of the image data in pixels.
189      */
190     public int  getHeight();
191 
192     /** 
193      * Return the Horizontal subsampling factor for requested
194      * Component.  The Subsample factor is the number of input pixels
195      * that contribute to each output pixel.  This is distinct from
196      * the way the JPEG to each output pixel.  This is distinct from
197      * the way the JPEG standard defines this quantity, because
198      * fractional subsampling factors are not allowed, and it was felt
199      * @param component The component of the encoded image to return
200      * the subsampling factor for.
201      * @return The subsample factor.
202      */
203     public int getHorizontalSubsampling(int component);
204 
205     /** 
206      * Return the Vertical subsampling factor for requested
207      * Component.  The Subsample factor is the number of input pixels
208      * that contribute to each output pixel.  This is distinct from
209      * the way the JPEG to each output pixel.  This is distinct from
210      * the way the JPEG standard defines this quantity, because
211      * fractional subsampling factors are not allowed, and it was felt
212      * @param component The component of the encoded image to return
213      * the subsampling factor for.
214      * @return The subsample factor.
215      */
216     public int getVerticalSubsampling(int component);
217 
218 
219     /** 
220      * Returns the coefficient quantization tables or NULL if not
221      * defined. tableNum must range in value from 0 - 3.
222      * @param tableNum the index of the table to be returned.
223      * @return Quantization table stored at index tableNum.
224      */
225     public JPEGQTable  getQTable(int tableNum );
226 
227     /**
228      * Returns the Quantization table for the requested component.
229      * @param component the image component of interest.
230      * @return Quantization table associated with component
231      */ 
232     public JPEGQTable getQTableForComponent(int component);
233 
234     /** 
235      * Returns the DC Huffman coding table requested or null if
236      * not defined
237      * @param tableNum the index of the table to be returned.
238      * @return Huffman table stored at index tableNum.  
239      */ 
240     public JPEGHuffmanTable getDCHuffmanTable( int tableNum );
241     /**
242      * Returns the DC Huffman coding table for the requested component.
243      * @param component the image component of interest.
244      * @return Huffman table associated with component
245      */ 
246     public JPEGHuffmanTable getDCHuffmanTableForComponent(int component);
247 
248         
249     /** 
250      * Returns the AC Huffman coding table requested or null if
251      * not defined
252      * @param tableNum the index of the table to be returned.
253      * @return Huffman table stored at index tableNum.  
254      */ 
255     public JPEGHuffmanTable getACHuffmanTable( int tableNum );
256     /**  
257      * Returns the AC Huffman coding table for the requested component.
258      * @param component the image component of interest.
259      * @return Huffman table associated with component
260      */ 
261     public JPEGHuffmanTable getACHuffmanTableForComponent(int component);
262 
263 
264 
265     /**
266      * Get the number of the DC Huffman table that will be used for
267      * a particular component.
268      * @param component The Component of interest.
269      * @return The table number of the DC Huffman table for component.
270      */
271     public int getDCHuffmanComponentMapping(int component);
272     /**
273      * Get the number of the AC Huffman table that will be used for
274      * a particular component.
275      * @param component The Component of interest.
276      * @return The table number of the AC Huffman table for component.
277      */
278     public int getACHuffmanComponentMapping(int component);
279     /**
280      * Get the number of the quantization table that will be used for
281      * a particular component.
282      * @param component The Component of interest.
283      * @return The table number of the Quantization table for component.
284      */
285     public int getQTableComponentMapping(int component);
286 
287     /**
288      * Returns true if the image information in the ParamBlock is
289      * currently valid.  This indicates if image data was read from
290      * the stream for decoding and weather image data should be
291      * written when encoding.
292      */
293     public boolean isImageInfoValid();
294 
295     /** 
296      * Returns true if the tables in the ParamBlock are currently
297      * valid.  This indicates that tables were read from the stream
298      * for decoding. When encoding this indicates wether tables should
299      * be written to the stream.
300      */
301     public boolean isTableInfoValid();
302 
303     /** 
304      * Returns true if at least one instance of the marker is present
305      * in the Parameter object.  For encoding returns true if there
306      * is at least one instance of the marker to be written.
307      * @param marker The marker of interest.
308      */
309     public boolean getMarker(int marker);
310 
311     /**
312      * Returns a 'byte[][]' associated with the requested marker in
313      * the parameter object.  Each entry in the 'byte[][]' is the data
314      * associated with one instance of the marker (each marker can
315      * theoretically appear any number of times in a stream).
316      * @param marker The marker of interest.
317      * @return The 'byte[][]' for this marker or null if none
318      *         available.
319      */
320     public byte[][] getMarkerData(int marker);
321 
322     /** 
323      * Returns the JPEG Encoded color id. This is generally
324      * speaking only used if you are decoding into Rasters.  Note
325      * that when decoding into a Raster no color conversion is
326      * performed.
327      * @return The value of the JPEG encoded data's color id.
328      */
329     public int getEncodedColorID();
330 
331     /**
332      * Returns the number of components for the current encoding
333      * COLOR_ID.
334      * @return the number of Components
335      */
336     public int getNumComponents();
337 
338     /** 
339      * Get the MCUs per restart marker.
340      * @return The number of MCUs between restart markers.
341      */
342     public int getRestartInterval();
343 
344     /** 
345      * Get the code for pixel size units This value is copied from the
346      * APP0 marker. It isn't used by the JPEG codec.  If the APP0
347      * marker wasn't present then you can not rely on this value.
348      * @return Value indicating the density unit one of the
349      * DENSITY_UNIT_* constants.
350      */
351     public int getDensityUnit();
352 
353     /** 
354      * Get the horizontal pixel density This value is copied from the
355      * APP0 marker. It isn't used by the JPEG code.  If the APP0
356      * marker wasn't present then you can not rely on this value.
357      * @return The horizontal pixel density, in units described by
358      * @see #getDensityUnit()
359      */
360     public int getXDensity();
361     /** 
362      * Get the vertical pixel density This value is copied into the
363      * APP0 marker. It isn't used by the JPEG code. If the APP0 marker
364      * wasn't present then you can not rely on this value.
365      * @return The verticle pixel density, in units described by
366      * @see #getDensityUnit()
367      */
368     public int getYDensity();
369 
370     
371 }
372
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags