1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
   2 <html>
   3 <head>
   4 <!--
   5 Copyright (c) 2000, 2007, Oracle and/or its affiliates. All rights reserved.
   6 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   7 
   8 This code is free software; you can redistribute it and/or modify it
   9 under the terms of the GNU General Public License version 2 only, as
  10 published by the Free Software Foundation.  Oracle designates this
  11 particular file as subject to the "Classpath" exception as provided
  12 by Oracle in the LICENSE file that accompanied this code.
  13 
  14 This code is distributed in the hope that it will be useful, but WITHOUT
  15 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  16 FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  17 version 2 for more details (a copy is included in the LICENSE file that
  18 accompanied this code).
  19 
  20 You should have received a copy of the GNU General Public License version
  21 2 along with this work; if not, write to the Free Software Foundation,
  22 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  23 
  24 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  25 or visit www.oracle.com if you need additional information or have any
  26 questions.
  27 -->
  28 
  29 </head>
  30 
  31 <body bgcolor="white">
  32 
  33 The main package of the Java Image I/O API.
  34 
  35 <p>
  36 
  37 Many common image I/O operations may be performed using the static
  38 methods of the <code>ImageIO</code> class.
  39 
  40 <p>
  41 
  42 This package contains the basic classes and interfaces for describing
  43 the contents of image files, including metadata and thumbnails
  44 (<code>IIOImage</code>); for controlling the image reading process
  45 (<code>ImageReader</code>, <code>ImageReadParam</code>, and
  46 <code>ImageTypeSpecifier</code>) and image writing process
  47 (<code>ImageWriter</code> and <code>ImageWriteParam</code>); for
  48 performing transcoding between formats (<code>ImageTranscoder</code>),
  49 and for reporting errors (<code>IIOException</code>).
  50 
  51 <p>
  52 All implementations of javax.imageio provide the following standard
  53 image format plug-ins:
  54 </p>
  55 <div>
  56 <table border=1 align='center' cellpadding=5>
  57 <tr>
  58     <th>&nbsp;</th> <th>Reading</th> <th>Writing</th>
  59     <th>Notes</th> <th>Metadata</th>
  60 </tr>
  61 <!-- BMP plugin -->
  62 <tr>
  63     <td><a href="https://msdn.microsoft.com/en-us/library/dd183391(v=vs.85).aspx">BMP</a></td>
  64     <td align='center'>yes</td>
  65     <td align='center'>yes</td>
  66     <td align='center'>none</td>
  67     <td align='center'><a href='metadata/doc-files/bmp_metadata.html'>
  68     BMP metadata format</a></td>
  69 </tr>
  70 <!-- GIF plugin -->
  71 <tr>
  72     <td><a href="http://www.w3.org/Graphics/GIF/spec-gif89a.txt">GIF</a></td>
  73     <td align='center'>yes</td>
  74     <td align='center'>yes</td>
  75     <td align='center'><a href="#gif_plugin_notes">
  76     GIF plug-in notes</a></td>
  77     <td align='center'><a href='metadata/doc-files/gif_metadata.html'>
  78     GIF metadata format</a></td>
  79 </tr>
  80 <!-- JPEG plugin -->
  81 <tr>
  82     <td> <a href="http://www.jpeg.org">JPEG</a></td>
  83     <td align='center'>yes</td>
  84     <td align='center'>yes</td>
  85     <td align='center'>none</td>
  86     <td align='center'><a href='metadata/doc-files/jpeg_metadata.html'>
  87     JPEG metadata format</a></td>
  88 </tr>
  89 <!-- PNG plugin -->
  90 <tr>
  91     <td><a href="http://www.libpng.org/pub/png/spec/">PNG</a></td>
  92     <td align='center'>yes</td>
  93     <td align='center'>yes</td>
  94     <td align='center'>none</td>
  95     <td align='center'><a href='metadata/doc-files/png_metadata.html'>
  96     PNG metadata format</a></td>
  97 </tr>
  98 <!-- TIFF plugin -->
  99 <tr>
 100     <td><a href="https://partners.adobe.com/public/developer/en/tiff/TIFF6.pdf">TIFF</a></td>
 101     <td align='center'>yes</td>
 102     <td align='center'>yes</td>
 103     <td align='center'><a href='metadata/doc-files/tiff_metadata.html#Reading'>
 104     TIFF plug-in notes</td>
 105     <td align='center'><a href='metadata/doc-files/tiff_metadata.html#StreamMetadata'>
 106     TIFF metadata format</a></td>
 107 </tr>
 108 <!-- WBMP plugin -->
 109 <tr>
 110     <td><a href="http://www.wapforum.org/what/technical/SPEC-WAESpec-19990524.pdf">WBMP</a></td>
 111     <td align='center'>yes</td>
 112     <td align='center'>yes</td>
 113     <td align='center'>none</td>
 114     <td align='center'><a href='metadata/doc-files/wbmp_metadata.html'>
 115     WBMP metadata format</a></td>
 116 </tr>
 117 </table>
 118 </div>
 119 <BR>
 120 <BR>
 121 <BR>
 122 
 123 <h2> Standard Plug-in Notes</h2>
 124 <h3><a name="gif_plugin_notes">Standard plug-in for GIF image format</a></h3>
 125 
 126 
 127 <p>
 128 ImageIO provides <code>ImageReader</code> and <code>ImageWriter</code>
 129 plug-ins for the <a href="http://www.w3.org/Graphics/GIF/spec-gif89a.txt">
 130 Graphics Interchange Format (GIF)</a> image format.
 131 
 132 These are the "standard" GIF plug-ins, meaning those that are included in the
 133 JRE, as distinct from those included in standard extensions, or 3rd party
 134 plug-ins. The following notes and metadata specification apply to the
 135 standard plug-ins.
 136 
 137 <h3>Writing GIF images</h3>
 138  The GIF image writer plug-in guarantees lossless writing for images which meet
 139  the following requirements:
 140 <ul>
 141 <li>the number of bands is 1;
 142 <li>the number of bits per sample is not greater than 8;
 143 <li>the size of a color component is not greater than 8;
 144 </ul>
 145 
 146 <p>
 147  By default the GIF writer plug-in creates version "89a" images. This can be
 148  changed to "87a" by explicitly setting the version in the
 149  stream metadata (see <a
 150  href="metadata/doc-files/gif_metadata.html#gif_stream_metadata_format">
 151  GIF Stream Metadata Format Specification</a>).
 152 </p> 
 153  
 154  
 155 <!-- animated images -->
 156 <p>
 157  The GIF writer plug-in supports the creation of animated GIF images through
 158  the standard sequence writing methods defined in the
 159  <code>ImageWriter</code> class.
 160  
 161  <!-- TODO: add example here --> 
 162 </p>
 163  
 164 <!--  color tables -->
 165 <p>
 166  A global color table is written to the output stream if one of the
 167  following conditions is met:
 168  <ul>
 169  <li> stream metadata containing a GlobalColorTable element is
 170   supplied; </li>
 171  <li> a sequence is being written and image metadata containing a
 172   LocalColorTable element is supplied for the first image in the
 173   sequence;</li>
 174  <li>image metadata is not supplied or does not contain a LocalColorTable
 175   element. </li>
 176  </ul>
 177  
 178  <p>
 179  In the first case the global color table in the stream metadata is
 180   used, in the second the local color table in the image metadata is
 181   used, and in the third a global color table is created from the
 182   ColorModel or SampleModel of the (first) image.
 183  </p>
 184  
 185  <p>
 186  A local color table is written to the output stream only if image
 187   metadata containing a LocalColorTable element is supplied to the
 188   writer, or no image metadata is supplied to the writer and the local
 189   color table which would be generated from the image itself is not
 190   equal to the global color table.
 191  </p>
 192  
 193  <p>
 194  A Graphic Control Extension block is written to the output stream only
 195   if image metadata containing a GraphicControlExtension element is
 196   supplied to the writer, or no image metadata is supplied and the
 197   local color table generated from the image requires a transparent
 198   index. Application, Plain Text, and Comment Extension blocks are
 199   written only if they are supplied to the writer via image metadata. 
 200  
 201  </p>
 202  
 203  <!-- writing interlaced images -->
 204  <p>
 205  
 206   The writing of interlaced images can be controlled by the progressive
 207   mode of the provided <code>ImageWriteParam</code> instance.
 208   If progressive mode is
 209   <code>MODE_DISABLED</code> then a non-interlaced image will be written. If
 210   progressive mode is <code>MODE_DEFAULT</code> then an interlaced image will
 211   be written. If progressive mode is <code>MODE_COPY_FROM_METADATA</code>, then
 212   the metadata setting is used (if it is provided, otherwise an interlaced
 213   image will be written).
 214  </p>
 215  
 216  <p>
 217  The GIF image writer plug-in supports setting output stream metadata from
 218  metadata supplied to the writer in either the native GIF stream
 219  metadata format <a href="metadata/doc-files/gif_metadata.html#gif_stream_metadata_format">
 220  javax_imageio_gif_stream_1.0 </a> or the standard metadata format
 221  <a href="metadata/doc-files/standard_metadata.html">
 222  javax_imageio_1.0</a>, and setting
 223  output image metadata from metadata supplied to the writer in either
 224  the native GIF image metadata format <a href="metadata/doc-files/gif_metadata.html#gif_image_metadata_format">
 225  javax_imageio_gif_image_1.0 </a> or the standard metadata format
 226  <a href="metadata/doc-files/standard_metadata.html">javax_imageio_1.0</a>.
 227   
 228  The mapping of standard metadata format to the GIF native stream and
 229  image metadata formats is given in the tables <a
 230  href="metadata/doc-files/gif_metadata.html#mapping"> here </a>.
 231  </p>
 232 
 233 
 234 <!--
 235 
 236 <HR>
 237 
 238 Java<SUP><FONT SIZE="-2">TM</FONT></SUP> Image I/O API Specification
 239 <BR>
 240 <BR>
 241 Public Draft 2 (specification version 0.5)
 242 <BR>
 243 Release: October 1, 2000
 244 <BR>
 245 <BR>
 246 
 247 <HR>
 248 
 249 -->
 250 
 251 @since 1.4
 252 </body>
 253 </html>