|
2
|
1 |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
|
|
|
2 |
<html>
|
|
|
3 |
<head>
|
|
|
4 |
<!--
|
|
5506
|
5 |
Copyright (c) 2000, 2007, Oracle and/or its affiliates. All rights reserved.
|
|
2
|
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
|
|
5506
|
10 |
published by the Free Software Foundation. Oracle designates this
|
|
2
|
11 |
particular file as subject to the "Classpath" exception as provided
|
|
5506
|
12 |
by Oracle in the LICENSE file that accompanied this code.
|
|
2
|
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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
|
|
|
25 |
CA 95054 USA or visit www.sun.com if you need additional information or
|
|
|
26 |
have any 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> </p>
|
|
|
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>
|