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  *
  43  * <table class="striped">
  44  * <caption>Standard image format plug-ins</caption>
  45  * <thead>
  46  *   <tr>
  47  *     <th scope="col">Image format
  48  *     <th scope="col">Reading
  49  *     <th scope="col">Writing
  50  *     <th scope="col">Notes
  51  *     <th scope="col">Metadata
  52  * </thead>
  53  * <tbody>
  54  * <!-- BMP plugin -->
  55  *   <tr>
  56  *     <th scope="row">
  57  *     <a href="https://msdn.microsoft.com/en-us/library/dd183391.aspx">BMP</a>
  58  *     <td>yes
  59  *     <td>yes
  60  *     <td>none
  61  *     <td><a href='metadata/doc-files/bmp_metadata.html'>BMP
  62  *     metadata format</a>
  63  * <!-- GIF plugin -->
  64  *   <tr>
  65  *     <th scope="row">
  66  *     <a href="http://www.w3.org/Graphics/GIF/spec-gif89a.txt">GIF</a>
  67  *     <td>yes
  68  *     <td>yes
  69  *     <td><a href="#gif_plugin_notes">GIF plug-in notes</a>
  70  *     <td><a href='metadata/doc-files/gif_metadata.html'>GIF
  71  *     metadata format</a>
  72  * <!-- JPEG plugin -->
  73  *   <tr>
  74  *     <th scope="row"><a href="http://www.jpeg.org">JPEG</a>
  75  *     <td>yes
  76  *     <td>yes
  77  *     <td>none
  78  *     <td><a href='metadata/doc-files/jpeg_metadata.html'>
  79  *     JPEG metadata format</a>
  80  * <!-- PNG plugin -->
  81  *   <tr>
  82  *     <th scope="row"><a href="http://www.libpng.org/pub/png/spec/">PNG</a>
  83  *     <td>yes
  84  *     <td>yes
  85  *     <td>none
  86  *     <td><a href='metadata/doc-files/png_metadata.html'>PNG
  87  *     metadata format</a>
  88  * <!-- TIFF plugin -->
  89  *   <tr>
  90  *     <th scope="row">
  91  *     <a href="https://partners.adobe.com/public/developer/en/tiff/TIFF6.pdf">
  92  *     TIFF</a>
  93  *     <td>yes
  94  *     <td>yes
  95  *     <td>
  96  *     <a href='metadata/doc-files/tiff_metadata.html#Reading'>TIFF plug-in
  97  *     notes</a>
  98  *     <td>
  99  *     <a href='metadata/doc-files/tiff_metadata.html#StreamMetadata'>TIFF
 100  *     metadata format</a>
 101  * <!-- WBMP plugin -->
 102  *   <tr>
 103  *     <th scope="row">
 104  *     <a href="http://www.wapforum.org/what/technical/SPEC-WAESpec-19990524.pdf">
 105  *     WBMP</a>
 106  *     <td>yes
 107  *     <td>yes
 108  *     <td>none
 109  *     <td><a href='metadata/doc-files/wbmp_metadata.html'>
 110  *     WBMP metadata format</a>
 111  * </tbody>
 112  * </table>
 113  *
 114  * <h2> Standard Plug-in Notes</h2>
 115  *
 116  * <h3><a id="gif_plugin_notes">Standard plug-in for GIF image format</a></h3>
 117  * ImageIO provides {@code ImageReader} and {@code ImageWriter}plug-ins for the
 118  * <a href="http://www.w3.org/Graphics/GIF/spec-gif89a.txt"> Graphics
 119  * Interchange Format (GIF)</a> image format. These are the "standard" GIF
 120  * plug-ins, meaning those that are included in the JRE, as distinct from those
 121  * included in standard extensions, or 3rd party plug-ins. The following notes
 122  * and metadata specification apply to the standard plug-ins.
 123  *
 124  * <h3>Writing GIF images</h3>
 125  * The GIF image writer plug-in guarantees lossless writing for images which
 126  * meet the following requirements:
 127  * <ul>
 128  *     <li>the number of bands is 1;</li>
 129  *     <li>the number of bits per sample is not greater than 8;</li>
 130  *     <li>the size of a color component is not greater than 8;</li>
 131  * </ul>
 132  * <p>
 133  * By default the GIF writer plug-in creates version "89a" images. This can be
 134  * changed to "87a" by explicitly setting the version in the stream metadata
 135  * (see
 136  * <a href="metadata/doc-files/gif_metadata.html#gif_stream_metadata_format">
 137  * GIF Stream Metadata Format Specification</a>).
 138  *
 139  * <!-- animated images -->
 140  * <p>
 141  * The GIF writer plug-in supports the creation of animated GIF images through
 142  * the standard sequence writing methods defined in the {@code ImageWriter}
 143  * class.
 144  *
 145  * <!-- TODO: add example here -->
 146  *
 147  * <!--  color tables -->
 148  * <p>
 149  * A global color table is written to the output stream if one of the following
 150  * conditions is met:
 151  * <ul>
 152  *     <li>stream metadata containing a GlobalColorTable element is supplied;
 153  *     </li>
 154  *     <li>a sequence is being written and image metadata containing a
 155  *     LocalColorTable element is supplied for the first image in the sequence;
 156  *     </li>
 157  *     <li>image metadata is not supplied or does not contain a LocalColorTable
 158  *     element.</li>
 159  * </ul>
 160  * <p>
 161  * In the first case the global color table in the stream metadata is used, in
 162  * the second the local color table in the image metadata is used, and in the
 163  * third a global color table is created from the ColorModel or SampleModel of
 164  * the (first) image.
 165  * <p>
 166  * A local color table is written to the output stream only if image metadata
 167  * containing a LocalColorTable element is supplied to the writer, or no image
 168  * metadata is supplied to the writer and the local color table which would be
 169  * generated from the image itself is not equal to the global color table.
 170  * <p>
 171  * A Graphic Control Extension block is written to the output stream only if
 172  * image metadata containing a GraphicControlExtension element is supplied to
 173  * the writer, or no image metadata is supplied and the local color table
 174  * generated from the image requires a transparent index. Application, Plain
 175  * Text, and Comment Extension blocks are written only if they are supplied to
 176  * the writer via image metadata.
 177  *
 178  * <!-- writing interlaced images -->
 179  * <p>
 180  * The writing of interlaced images can be controlled by the progressive mode of
 181  * the provided {@code ImageWriteParam} instance. If progressive mode is
 182  * {@code MODE_DISABLED} then a non-interlaced image will be written. If
 183  * progressive mode is {@code MODE_DEFAULT} then an interlaced image will be
 184  * written. If progressive mode is {@code MODE_COPY_FROM_METADATA}, then the
 185  * metadata setting is used (if it is provided, otherwise an interlaced image
 186  * will be written).
 187  * <p>
 188  * The GIF image writer plug-in supports setting output stream metadata from
 189  * metadata supplied to the writer in either the native GIF stream metadata
 190  * format
 191  * <a href="metadata/doc-files/gif_metadata.html#gif_stream_metadata_format">
 192  * javax_imageio_gif_stream_1.0</a> or the standard metadata format
 193  * <a href="metadata/doc-files/standard_metadata.html">javax_imageio_1.0</a>,
 194  * and setting output image metadata from metadata supplied to the writer in
 195  * either the native GIF image metadata format
 196  * <a href="metadata/doc-files/gif_metadata.html#gif_image_metadata_format">
 197  * javax_imageio_gif_image_1.0</a> or the standard metadata format
 198  * <a href="metadata/doc-files/standard_metadata.html">javax_imageio_1.0</a>.
 199  * The mapping of standard metadata format to the GIF native stream and image
 200  * metadata formats is given in the tables
 201  * <a href="metadata/doc-files/gif_metadata.html#mapping">here</a>.
 202  *
 203  * @since 1.4
 204  */
 205 package javax.imageio;