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