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