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> </th> <th>Reading</th> <th>Writing</th> 59 <th>Notes</th> <th>Metadata</th> 60 </tr> 61 <!-- JPEG plugin --> 62 <tr> 63 <td> <a href="http://www.jpeg.org">JPEG</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/jpeg_metadata.html'> 68 JPEG metadata format</a></td> 69 </tr> 70 <!-- PNG plugin --> 71 <tr> 72 <td><a href="http://www.libpng.org/pub/png/spec/">PNG</a></td> 73 <td align='center'>yes</td> 74 <td align='center'>yes</td> 75 <td align='center'>none</td> 76 <td align='center'><a href='metadata/doc-files/png_metadata.html'> 77 PNG metadata format</a></td> 78 </tr> 79 <!-- BMP plugin --> 80 <tr> 81 <td>BMP</td> 82 <td align='center'>yes</td> 83 <td align='center'>yes</td> 84 <td align='center'>none</td> 85 <td align='center'><a href='metadata/doc-files/bmp_metadata.html'> 86 BMP metadata format</a></td> 87 </tr> 88 <!-- WBMP plugin --> 89 <tr> 90 <td><a href="http://www.wapforum.org/what/technical/SPEC-WAESpec-19990524.pdf">WBMP</a></td> 91 <td align='center'>yes</td> 92 <td align='center'>yes</td> 93 <td align='center'>none</td> 94 <td align='center'><a href='metadata/doc-files/wbmp_metadata.html'> 95 WBMP metadata format</a></td> 96 </tr> 97 <!-- GIF plugin --> 98 <tr> 99 <td><a href="http://www.w3.org/Graphics/GIF/spec-gif89a.txt">GIF</a></td> 100 <td align='center'>yes</td> 101 <td align='center'>yes</td> 102 <td align='center'><a href="#gif_plugin_notes"> 103 GIF plug-in notes</a></td> 104 <td align='center'><a href='metadata/doc-files/gif_metadata.html'> 105 GIF metadata format</a></td> 106 </tr> 107 </table> 108 </div> 109 <BR> 110 <BR> 111 <BR> 112 113 <h2> Standard Plug-in Notes</h2> 114 <h3><a name="gif_plugin_notes">Standard plug-in for GIF image format</a></h3> 115 116 117 <p> 118 ImageIO provides <code>ImageReader</code> and <code>ImageWriter</code> 119 plug-ins for the <a href="http://www.w3.org/Graphics/GIF/spec-gif89a.txt"> 120 Graphics Interchange Format (GIF)</a> image format. 121 122 These are the "standard" GIF plug-ins, meaning those that are included in the 123 JRE, as distinct from those included in standard extensions, or 3rd party 124 plug-ins. The following notes and metadata specification apply to the 125 standard plug-ins. 126 127 <h3>Writing GIF images</h3> 128 The GIF image writer plug-in guarantees lossless writing for images which meet 129 the following requirements: 130 <ul> 131 <li>the number of bands is 1; 132 <li>the number of bits per sample is not greater than 8; 133 <li>the size of a color component is not greater than 8; 134 </ul> 135 136 <p> 137 By default the GIF writer plug-in creates version "89a" images. This can be 138 changed to "87a" by explicitly setting the version in the 139 stream metadata (see <a 140 href="metadata/doc-files/gif_metadata.html#gif_stream_metadata_format"> 141 GIF Stream Metadata Format Specification</a>). 142 </p> 143 144 145 <!-- animated images --> 146 <p> 147 The GIF writer plug-in supports the creation of animated GIF images through 148 the standard sequence writing methods defined in the 149 <code>ImageWriter</code> class. 150 151 <!-- TODO: add example here --> 152 </p> 153 154 <!-- color tables --> 155 <p> 156 A global color table is written to the output stream if one of the 157 following conditions is met: 158 <ul> 159 <li> stream metadata containing a GlobalColorTable element is 160 supplied; </li> 161 <li> a sequence is being written and image metadata containing a 162 LocalColorTable element is supplied for the first image in the 163 sequence;</li> 164 <li>image metadata is not supplied or does not contain a LocalColorTable 165 element. </li> 166 </ul> 167 168 <p> 169 In the first case the global color table in the stream metadata is 170 used, in the second the local color table in the image metadata is 171 used, and in the third a global color table is created from the 172 ColorModel or SampleModel of the (first) image. 173 </p> 174 175 <p> 176 A local color table is written to the output stream only if image 177 metadata containing a LocalColorTable element is supplied to the 178 writer, or no image metadata is supplied to the writer and the local 179 color table which would be generated from the image itself is not 180 equal to the global color table. 181 </p> 182 183 <p> 184 A Graphic Control Extension block is written to the output stream only 185 if image metadata containing a GraphicControlExtension element is 186 supplied to the writer, or no image metadata is supplied and the 187 local color table generated from the image requires a transparent 188 index. Application, Plain Text, and Comment Extension blocks are 189 written only if they are supplied to the writer via image metadata. 190 191 </p> 192 193 <!-- writing interlaced images --> 194 <p> 195 196 The writing of interlaced images can be controlled by the progressive 197 mode of the provided <code>ImageWriteParam</code> instance. 198 If progressive mode is 199 <code>MODE_DISABLED</code> then a non-interlaced image will be written. If 200 progressive mode is <code>MODE_DEFAULT</code> then an interlaced image will 201 be written. If progressive mode is <code>MODE_COPY_FROM_METADATA</code>, then 202 the metadata setting is used (if it is provided, otherwise an interlaced 203 image will be written). 204 </p> 205 206 <p> 207 The GIF image writer plug-in supports setting output stream metadata from 208 metadata supplied to the writer in either the native GIF stream 209 metadata format <a href="metadata/doc-files/gif_metadata.html#gif_stream_metadata_format"> 210 javax_imageio_gif_stream_1.0 </a> or the standard metadata format 211 <a href="metadata/doc-files/standard_metadata.html"> 212 javax_imageio_1.0</a>, and setting 213 output image metadata from metadata supplied to the writer in either 214 the native GIF image metadata format <a href="metadata/doc-files/gif_metadata.html#gif_image_metadata_format"> 215 javax_imageio_gif_image_1.0 </a> or the standard metadata format 216 <a href="metadata/doc-files/standard_metadata.html">javax_imageio_1.0</a>. 217 218 The mapping of standard metadata format to the GIF native stream and 219 image metadata formats is given in the tables <a 220 href="metadata/doc-files/gif_metadata.html#mapping"> here </a>. 221 </p> 222 223 224 <!-- 225 226 <HR> 227 228 Java<SUP><FONT SIZE="-2">TM</FONT></SUP> Image I/O API Specification 229 <BR> 230 <BR> 231 Public Draft 2 (specification version 0.5) 232 <BR> 233 Release: October 1, 2000 234 <BR> 235 <BR> 236 237 <HR> 238 239 --> 240 241 @since 1.4 242 </body> 243 </html>