1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
2 <html>
3 <head>
4 <!--
5 Copyright (c) 2000, 2015, 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 <title>JPEG Metadata Format Specification and Usage Notes</title>
30 </head>
31
32 <body bgcolor="white">
33
34 <center><h1>
35 JPEG Metadata Format Specification and Usage Notes
36 </h1></center>
37
38 <p>
39 <a href=#metadata>JPEG Metadata</a><br>
40 <a href=#abbrev>Abbreviated Streams</a><br>
41 <a href=#tables>Sources of Tables</a><br>
42 <a href=#color>Colorspace Transformations and Conventional Markers</a><br>
43 <a href=#thumbs>Thumbnail Images</a><br>
44 <a href=#prog>Progressive Encoding</a><br>
45 <a href=#tree>Native Metadata Format Tree Structure and Editing</a><br>
46 <a href=#image>Image Metadata DTD</a><br>
47 <a href=#stream>Stream Metadata DTD</a>
48 <p>
49 <b>NOTE</b>: It is important to call <code>dispose()</code>
50 on the JPEG reader and writer objects when they are no longer needed, as
51 they consume significant native resources which are not adequately recovered
52 by garbage collection. Both reader and writer call <code>dispose()</code>
53 in their finalizers, but those finalizers may not be called before the native
54 code has exhausted native memory.
55
56 <p>
57
58 The JPEG writer does not support replacing pixels.
59
60 <h2>
61 <a name=metadata>JPEG Metadata</a>
62 </h2>
63 JPEG metadata consists of the data contained in marker segments in a JPEG
64 stream. The image metadata object returned from a read describes the
65 contents of the marker segments between the <code>SOI</code> marker and
66 the <code>EOI</code> marker for that image. The image metadata object
67 passed into a write determines the contents of the stream between the
68 <code>SOI</code> marker and the <code>EOI</code> marker for that image,
69 subject to the controls in any <code>ImageWriteParam</code>.
70
71 <p>
72 Stream metadata is used only for tables-only images found (or to be
73 placed) at the beginning of a stream containing abbreviated images.
74 Tables-only images are not treated as images and do not consume an
75 image index. The stream metadata object returned from a read describes the
76 contents of the marker segments between the <code>SOI</code> marker and
77 the <code>EOI</code> marker for the single tables-only image at the
78 beginning of the stream, if one is present. If no tables-only image is
79 present at the front of the stream, the <code>getStreamMetadata</code>
80 method of <code>ImageReader</code> returns <code>null</code>. If
81 stream metadata is provided to the writer, a single tables-only image
82 containing the tables from the stream metadata object will be written at
83 the beginning of the stream. If the stream metadata object contains no
84 tables, default tables will be written. As the sole purpose of stream
85 metadata is for specifying tables-only images at the front of abbreviated
86 streams, the stream metadata argument is useful only on the
87 <code>ImageWriter.prepareWriteSequence</code> method. It is ignored on all
88 other methods.
89
90 <p>
91 The <code>ImageWriter.getDefaultStreamMetadata</code> method returns an
92 object containing the tables from the <code>ImageWriteParam</code> argument,
93 if it is a <code>JPEGImageWriteParam</code> and contains tables. Otherwise,
94 the returned object will contain default tables.
95
96 <p>The <code>ImageWriter.getDefaultImageMetadata</code> method returns a
97 metadata object containing <b>no</b> tables if the
98 <code>ImageWriteParam</code> argument contains tables. Otherwise the
99 returned metadata object will contain default visually lossless tables.
100 Of course, only a <code>JPEGImageWriteParam</code> may contain tables.
101
102 <p>
103 If <code>ignoreMetadata</code> is set to <code>true</code> when the input
104 is set on the reader, stream metadata will not be available, but image
105 metadata will.
106
107 <h2>
108 <a name=abbrev>Abbreviated Streams</a>
109 </h2>
110 Both the reader and the writer retain their tables from one operation to the
111 next, thus permitting the use of abbreviated streams quite naturally, with a
112 few minor restrictions:
113 <ol>
114 <li> Abbreviated streams may contain only one tables-only image, which must
115 come first in the stream. Subsequent tables-only images will cause
116 undefined behavior.</li>
117 <li> Abbreviated streams must be read fully and in order. No random access
118 is allowed, in either direction. The same image may be read multiple
119 times. If a call is made with an image index that is not the same as
120 or one greater than the most recent call (or 0 if no calls have been
121 made), then an <code>IllegalArgumentException</code> is thrown.</li>
122 </ol>
123 These restrictions mean that streams may contain abbreviated images
124 interspersed with images containing tables. As required by JPEG, any tables
125 appearing in the stream override previous tables, regardless of the source
126 of the previous tables.
127
128 <p>
129 Note that once a tables-only image has been read, it's contents is available
130 as stream metadata from the reader until either another tables-only image
131 is read from another stream or the reader is reset. Changing the input does
132 not reset the stream metadata. This is useful for reading the tables from
133 one file, then changing the input to read an abbreviated stream containing
134 a sequence of images. The tables will be used automatically, and will remain
135 available as "stream" metadata.
136
137 <p>
138 Abbreviated streams are written using the sequence methods of
139 <code>ImageWriter</code>. Stream metadata is used to write a tables-only
140 image at the beginning of the stream, and the tables are set up for use, using
141 <code>ImageWriter.prepareWriteSequence</code>. If no stream metadata is
142 supplied to <code>ImageWriter.prepareWriteSequence</code>, then no
143 tables-only image is written. If stream metadata containing no tables is
144 supplied to <code>ImageWriter.prepareWriteSequence</code>, then a tables-only
145 image containing default visually lossless tables is written.
146
147 <h2>
148 <a name=tables>Sources of Tables</a>
149 </h2>
150 <p>
151 Images are written with tables if tables are present in their metadata objects
152 or without them if no tables are present in their metadata objects. If no
153 metadata object is present then the tables are written. The tables used for
154 compression are taken from one of the following sources, which are consulted
155 in order:
156 <ol>
157 <li> If there is an <code>ImageWriteParam</code> and the compression mode is
158 set to <code>EXPLICIT</code>, default tables constructed using the
159 quality setting are used. They are written only if the metadata
160 contains tables or if there is no metadata, but they replace the
161 tables in the metadata.</li>
162 <li> If there is an <code>ImageWriteParam</code> and the compression mode is
163 set to <code>DEFAULT</code>, default visually lossles tables are used.
164 They are written only if the metadata contains tables or if
165 there is no metadata, but they replace the tables in the
166 metadata.</li>
167 <li> Otherwise the compression mode on the <code>ImageWriteParam</code> must
168 be MODE_COPY_FROM_<code>METADATA</code>, in which case the following
169 are used:
170 <ol>
171 <li> the tables in the image metadata, if present</li>
172 <li> the tables in the stream metadata, if present</li>
173 <li> the tables in the <code>JPEGImageWriteParam</code>, if present</li>
174 <li> default visually lossless tables</li>
175 </ol> Tables are written only if they are taken from image metadata.
176 </li>
177 </ol>
178
179 This ordering implements the design intention that tables should be included
180 in <code>JPEGImageWriteParam</code>s only as a means of specifying tables
181 when no other source is available, and this can occur only when writing to an
182 abbreviated stream without tables using known non-standard tables for
183 compression.
184
185 <p>
186 When reading, tables in a <code>JPEGImageReadParam</code> are consulted only
187 if tables have not been set by any previous read. Tables set from a
188 <code>JPEGImageReadParam</code> are overridden by any tables present in the
189 stream being read.
190
191 <p>
192 Note that if no image metadata object is specified for a particular image, a
193 default object is used, which includes default tables.
194
195 <h2>
196 <a name=color>Colorspace Transformations and Conventional Markers</a>
197 </h2>
198 Colorspace transformations are controlled by the destination type for
199 both reading and writing of images. When <code>Raster</code>s are
200 read, no colorspace transformation is performed, and any destination type
201 is ignored. A warning is sent to any listeners if a destination type is
202 specified in this case. When <code>Raster</code>s are written, any
203 destination type is used to interpret the bands. This might result in a
204 JFIF or Adobe header being written, or different component ids being written
205 to the frame and scan headers. If values present in a metadata object do not
206 match the destination type, the destination type is used and a warning is sent
207 to any listeners.
208
209 <p>
210
211 <a name=optcolor><b>Optional ColorSpace support:</b></a>
212 Handling of PhotoYCC (YCC), PhotoYCCA (YCCA), RGBA and YCbCrA color spaces
213 by the standard plugin, as described below, is dependent on capabilities
214 of the libraries used to interpret the JPEG data. Thus all consequential
215 behaviors are optional. If the support is not available when decoding,
216 the color space will be treated as unrecognized and the appropriate
217 default color space for the specified number of component channels
218 may be used.
219 When writing, an Exception may be thrown if no suitable conversion
220 can be applied before encoding.
221 But where the support for these color spaces is available, the behavior
222 must be as documented.
223 <p>
224
225 When reading, the contents of the stream are interpreted by the usual
226 JPEG conventions, as follows:
227
228 <ul>
229 <li> If a JFIF <code>APP0</code> marker segment is present, the colorspace
230 is known to be either grayscale or YCbCr. If an <code>APP2</code>
231 marker segment containing an embedded ICC profile is also present, then
232 the YCbCr is converted to RGB according to the formulas given in the
233 JFIF spec, and the ICC profile is assumed to refer to the resulting RGB
234 space.
235 <li> If an Adobe <code>APP14</code> marker segment is present, the
236 colorspace is determined by consulting the <code>transform</code> flag.
237 The <code>transform</code> flag takes one of three values:
238 <ul>
239 <li> 2 - The image is encoded as YCCK (implicitly converted from
240 CMYK on encoding).
241
242 <li> 1 - The image is encoded as YCbCr (implicitly converted from RGB
243 on encoding).
244
245 <li> 0 - Unknown. 3-channel images are assumed to be RGB, 4-channel
246 images are assumed to be CMYK.
247 </ul>
248 <li> If neither marker segment is present, the following procedure is
249 followed: Single-channel images are assumed to be grayscale, and
250 2-channel images are assumed to be grayscale with an alpha channel.
251 For 3- and 4-channel images, the component ids are consulted. If these
252 values are 1-3 for a 3-channel image, then the image is assumed to be
253 YCbCr. Subject to the availability of the
254 <a href=#optcolor>optional color space support</a>
255 described above, if these values are 1-4 for a 4-channel image,
256 then the image is assumed to be YCbCrA.
257 If these values are > 4, they are checked
258 against the ASCII codes for 'R', 'G', 'B', 'A', 'C', 'c'. These can
259 encode the following colorspaces:
260 <p>
261 <br>RGB
262 <br>RGBA
263 <br>YCC (as 'Y','C','c'), assumed to be PhotoYCC
264 <br>YCCA (as 'Y','C','c','A'), assumed to be PhotoYCCA
265 <p>
266 Otherwise, 3-channel subsampled images are assumed to be YCbCr,
267 3-channel non-subsampled images are assumed to be RGB, 4-channel
268 subsampled images are assumed to be YCCK, and 4-channel, non-subsampled
269 images are assumed to be CMYK.
270
271 <li> All other images are declared uninterpretable and an exception is
272 thrown if an attempt is made to read one as a
273 <code>BufferedImage</code>. Such an image may be read only as a
274 <code>Raster</code>. If an image is interpretable but there is no Java
275 <code>ColorSpace</code> available corresponding to the encoded
276 colorspace (<i>e.g.</i> YCbCr), then
277 <code>ImageReader.getRawImageType</code> will return <code>null</code>.
278 </ul>
279
280 Once an encoded colorspace is determined, then the target colorspace is
281 determined as follows:
282
283 <ul>
284 <li> If a destination type is not set, then the following default
285 transformations take place after upsampling: YCbCr (and YCbCrA) images
286 are converted to RGB (and RGBA) using the conversion provided by the
287 underlying IJG library and either the built-in sRGB
288 <code>ColorSpace</code> or a custom RGB <code>ColorSpace</code> object
289 based on an embedded ICC profile is used to create the output
290 <code>ColorModel</code>. PhotoYCC and PhotoYCCA images are not
291 converted. CMYK and YCCK images are currently not supported.</li>
292
293 <li> If a destination image or type is set, it is used as follows:
294 If the IJG library provides an appropriate conversion, it is used.
295 Otherwise the default library conversion is followed by a colorspace
296 conversion in Java.</li>
297
298 <li> Bands are selected AFTER any library colorspace conversion. If a
299 subset of either source or destination bands is used, then the default
300 library conversions are used with no further conversion in Java,
301 regardless of any destination type.</li>
302
303 <li> An exception is thrown if an attempt is made to read an image in an
304 unsupported jpeg colorspace as a <code>BufferedImage</code>
305 (<i>e.g.</i> CMYK). Such images may be read as
306 <code>Raster</code>s. If an image colorspace is unsupported or
307 uninterpretable, then <code>ImageReader.getImageTypes</code> will
308 return an empty <code>Iterator</code>. If a subset of the raw bands
309 are required, a <code>Raster</code> must be obtained first and the
310 bands obtained from that. </li>
311 </ul>
312
313 <p>
314 For writing, the color transformation to apply is determined as
315 follows:
316
317 <p>
318 If a subset of the source bands is to be written, no color conversion is
319 performed. Any destination, if set, must match the number of bands that will
320 be written, and serves as an interpretation of the selected bands, rather than
321 a conversion request. This behavior is identical to that for
322 <code>Raster</code>s. If all the bands are to be written and an image
323 (as opposed to a <code>Raster</code>) is being written, any destination type
324 is ignored and a warning is sent to any listeners.
325
326 <p>
327 If a destination type is used and any aspect of the metadata object, if there
328 is one, is not compatible with that type, the destination type is used, the
329 metadata written is modified from that provided, and a warning is sent to
330 listeners. This includes the <code>app0JFIF</code> and
331 <code>app14Adobe</code> nodes. The component ids in the <code>sof</code> and
332 <code>sos</code> nodes are not modified, however, as unless a
333 <code>app0JFIF</code> node is present, any values may be used.
334 <p>
335
336 When a full image is written, a destination colorspace will be
337 chosen based on the image contents and the metadata settings, according to
338 the following algorithm:
339
340 <p>
341
342 If no metadata object is specified, then the following defaults apply:
343
344 <ul>
345 <li> Grayscale images are written with a JFIF <code>APP0</code> marker
346 segment. Grayscale images with alpha are written with no special
347 marker. As required by JFIF, the component ids in the frame and
348 scan header is set to 1.
349
350 <li> RGB images are converted to YCbCr, subsampled in the chrominance
351 channels by half both vertically and horizontally, and written with a
352 JFIF <code>APP0</code> marker segment. If the <code>ColorSpace</code>
353 of the image is based on an <code>ICCProfile</code> (it is an instance
354 of <code>ICC_ColorSpace</code>, but is not one of the standard built-in
355 <code>ColorSpaces</code>), then that profile is embedded in an
356 <code>APP2</code> marker segment. As required by JFIF, the
357 component ids in the frame and scan headers are set to 1, 2, and 3.
358
359
360 <li> Subject to the <a href=#optcolor>optional library support</a>
361 described above,
362 RGBA images are converted to YCbCrA, subsampled in the
363 chrominance channels by half both vertically and horizontally, and
364 written without any special marker segments. The component ids
365 in the frame and scan headers are set to 1, 2, 3, and 4.
366
367 <li> Subject to the <a href=#optcolor>optional library support</a>
368 described above,
369 PhotoYCC and YCCAimages are subsampled by half in the chrominance
370 channels both vertically and horizontally and written with an
371 Adobe <code>APP14</code> marker segment and 'Y','C', and 'c' (and
372 'A' if an alpha channel is present) as component ids in the frame
373 and scan headers.
374 </ul>
375
376 Default metadata objects for these image types will reflect these settings.
377
378 <p>
379
380 If a metadata object is specified, then the number of channels in the
381 frame and scan headers must always match the number of bands to be
382 written, or an exception is thrown. <code>app0JFIF</code> and
383 <code>app14Adobe</code> nodes may appear in the same metadata object only
384 if the <code>app14Adobe</code> node indicates YCbCr, and the component ids
385 are JFIF compatible (0-2). The various image types are processed in the
386 following ways:
387
388 <br>
389
390 (All multi-channel images are subsampled according to the sampling factors
391 in the frame header node of the metadata object, regardless of color space.)
392
393 <ul>
394 <li> Grayscale Images:
395 <ul>
396 <li> If an <code>app0JFIF</code> node is present in the metadata object,
397 a JFIF <code>APP0</code> marker segment is written.
398 <li> If an <code>app14Adobe</code> node is present in the metadata
399 object, it is checked for validity (<code>transform</code> must be
400 <code>UNKNOWN</code>) and written.
401 <li> If neither node is present in the metadata object, no special
402 marker segment is written.
403 </ul>
404
405 <li> Grayscale Images with an Alpha Channel:
406 <ul>
407 <li> If an <code>app0JFIF</code> node is present in the metadata object,
408 it is ignored and a warning is sent to listeners, as JFIF does not
409 support 2-channel images.
410 <li> If an <code>app14Adobe</code> node is present in the metadata
411 object, it is checked for validity (<code>transform</code> must be
412 <code>UNKNOWN</code>) and written. If <code>transform</code> is
413 not <code>UNKNOWN</code>, a warning is sent to listeners and the
414 correct transform is written.
415 <li> If neither node is present in the metadata object, no special
416 marker segment is written.
417 </ul>
418
419 <li> RGB Images:
420 <ul>
421 <li> If an <code>app0JFIF</code> node is present in the metadata object,
422 the image is converted to YCbCr and written with a JFIF
423 <code>APP0</code> marker segment. If the <code>ColorSpace</code>
424 of the image is based on a non-standard ICC Profile, then that
425 profile is embedded in an <code>APP2</code> marker segment. If the
426 <code>ColorSpace</code> is not based on a non-standard ICC Profile,
427 but an <code>app2ICC</code> node appears in the metadata, then an
428 <code>APP2</code> marker segment is written with the appropriate
429 standard profile. Note that the profile must specify an RGB color
430 space, as the file must be JFIF compliant.
431
432 <li> If an <code>app14Adobe</code> node is present in the metadata
433 object, the image is converted according to the color transform
434 setting and written with an Adobe <code>APP14</code> marker
435 segment. Component ids are written just as they appear in the
436 frame and scan headers. The color transform must be either YCbCr
437 or <code>UNKNOWN</code>. If it is <code>UNKNOWN</code>, the image
438 is not color converted.
439
440 <li> If neither node is present, the component ids in the frame
441 header are consulted. If these indicate a colorspace as described
442 above, then the image is converted to that colorspace if possible.
443 If the component ids do not indicate a colorspace, then the
444 sampling factors are consulted. If the image is to be subsampled,
445 it is converted to YCbCr first. If the image is not to be
446 subsampled, then no conversion is applied. No special marker
447 segmentss are written.
448 </ul>
449
450 <li> RGBA images:
451 Subject to the <a href=#optcolor>optional library support</a>
452 described above,
453 <ul>
454 <li> If an <code>app0JFIF</code> node is present in the metadata object,
455 it is ignored and a warning is sent to listeners, as JFIF does not
456 support 4-channel images.
457
458 <li> If an <code>app14Adobe</code> node is present in the metadata
459 object, the image is written with an Adobe <code>APP14</code> marker
460 segment. No colorspace conversion is performed. Component ids
461 are written just as they appear in the frame and scan headers.
462 The color transform must be <code>UNKNOWN</code>. If it is
463 not, a warning is sent to listeners.
464
465 <li> If no <code>app14Adobe</code> node is present, the component ids in
466 the frame header are consulted. If these indicate a colorspace as
467 described above, then the image is converted to that colorspace if
468 possible. If the component ids do not indicate a colorspace, then
469 the sampling factors are consulted. If the image is to be
470 subsampled, it is converted to YCbCrA. If the image is not to be
471 subsampled, then no conversion is applied. No special marker
472 segments are written.
473 </ul>
474
475 <li> PhotoYCC Images:
476 Subject to the <a href=#optcolor>optional library support</a>
477 described above,
478 <ul>
479 <li> If an <code>app0JFIF</code> node is present in the metadata object,
480 the image is converted to sRGB, and then to YCbCr during encoding,
481 and a JFIF <code>APP0</code> marker segment is written.
482
483 <li> If an <code>app14Adobe</code> node is present in the metadata
484 object, no conversion is applied, and an Adobe <code>APP14</code>
485 marker segment is written. The color transform must be YCC. If it
486 is not, a warning is sent to listeners.
487
488 <li> If neither node is present in the metadata object, no conversion
489 is applied, and no special marker segment is written.
490 </ul>
491
492 <li> PhotoYCCA Images:
493 Subject to the <a href=#optcolor>optional library support</a>
494 described above,
495 <ul>
496 <li> If an <code>app0JFIF</code> node is present in the metadata object,
497 it is ignored and a warning is sent to listeners, as JFIF does not
498 support 4-channel images.
499
500 <li> If an <code>app14Adobe</code> node is present in the metadata
501 object, no conversion is applied, and an Adobe <code>APP14</code>
502 marker segment is written. The color transform must be
503 <code>UNKNOWN</code>. If it is not, a warning is sent to
504 listeners.
505
506 <li> If neither node is present in the metadata object, no conversion
507 is applied, and no special marker segment is written.
508 </ul>
509 </ul>
510
511 <h2>
512 <a name=thumbs>Thumbnail Images</a>
513 </h2>
514 Thumbnails are supported by the use of JFIF and JFIF extension marker segments.
515 Thumbnails provided on the write methods determine the thumbnails that will be
516 included. <code>app0JFIF</code> and <code>app0JFXX</code> nodes present in
517 the metadata do not contain any thumbnail pixel data. However, the kinds of
518 thumbnails written depend on the contents of the metadata object, as follows.
519 Any thumbnail which is to be written as an indexed or RGB image and which is
520 larger than 255 by 255 will be clipped, not scaled, to 255 by 255. Thumbnails
521 written as JPEG images may be any size. A warning is sent to any listeners
522 whenever a thumbnail is clipped.
523 <ul>
524 <li> If there is a single thumbnail, it is processed as follows:
525 <ul>
526 <li> If the thumbnail image is an RGB palette image, it is processed as
527 follows:
528 <ul>
529 <li> If no <code>app0JFXX</code> node is present in the metadata, or
530 the first <code>app0JFXX</code> node present in the metadata
531 contains a <code>JFIFthumbPalette</code> element, a
532 palette thumbnail is written in a JFXX <code>APP0</code> marker
533 segment.
534 <li> If the first <code>app0JFXX</code> node present in the metadata
535 contains another thumbnail form (RGB or JPEG), the palette
536 image is expanded to RGB and the indicated thumbnail form is
537 written.
538 </ul>
539
540 <li> If the thumbnail image is an RGB image, it is processed as follows:
541 <ul>
542 <li> If no <code>app0JFXX</code> node is present in the metadata,
543 the thumbnail is written as part of the JFIF <code>APP0</code>
544 marker segment.
545 <li> If the first <code>app0JFXX</code> node present in the metadata
546 contains a <code>JFIFthumbRGB</code> element, an
547 RGB thumbnail is written in a JFXX <code>APP0</code> marker
548 segment.
549 <li> If the first <code>app0JFXX</code> node present in the metadata
550 contains a <code>JFIFthumbJPEG</code> element, a
551 JPEG thumbnail is written in a JFXX <code>APP0</code> marker
552 segment.
553 <li> If the first <code>app0JFXX</code> node present in the metadata
554 contains a <code>JFIFthumbPalette</code> element, an
555 RGB thumbnail is written in a JFXX <code>APP0</code> marker
556 segment and a warning is sent to any listeners.
557 </ul>
558
559 <li> If the thumbnail image is a grayscale image, it is processed as
560 follows:
561 <ul>
562 <li> If no <code>app0JFXX</code> node is present in the metadata,
563 the thumbnail is expanded to RGB and written as part of the
564 JFIF <code>APP0</code> marker segment.
565 <li> If the first <code>app0JFXX</code> node present in the metadata
566 contains a <code>JFIFthumbRGB</code> element, the thumbnail is
567 expanded to RGB and written in a separate <code>JFXX</code> RGB
568 marker segment.
569 <li> If the first <code>app0JFXX</code> node present in the metadata
570 contains a <code>JFIFthumbJPEG</code> element, a
571 JPEG thumbnail is written in a JFXX <code>APP0</code> marker
572 segment.
573 <li> If the first <code>app0JFXX</code> node present in the metadata
574 contains a <code>JFIFthumbPalette</code> element, a
575 JPEG thumbnail is written in a JFXX <code>APP0</code> marker
576 segment and a warning is sent to any listeners.
577 </ul>
578
579 <li> Any other thumbnail image types are ignored and a warning is sent
580 to any listeners.
581 </ul>
582
583 <li> If there are multiple thumbnails, each one is processed as above, except
584 that no thumbnail is placed in the JFIF <code>APP0</code> segment, and
585 the <code>app0JFXX</code> node consulted for each thumbnail is the
586 <code>app0JFXX</code> node from the metadata that occurs in the same
587 sequence as the thumbnail. <i>I.e.</i> the first
588 <code>app0JFXX</code> node applies to the first thumbnail, the second
589 node to the second thumbnail, and so on. If there are fewer
590 <code>app0JFXX</code> nodes in the metadata than thumbnails, then
591 those thumbnails are considered to have no matching
592 <code>app0JFXX</code> node. An RGB thumbnail with no matching
593 <code>app0JFXX</code> node is written in a JFXX <code>APP0</code> marker
594 segment. A grayscale thumbnail with no matching
595 <code>app0JFXX</code> node is written as a JPEG image to a JFXX
596 <code>APP0</code> marker segment.
597 </ul>
598 <p>
599
600 Note that as the only mechanism for storing thumbnails is via the
601 JFIF or JFIF extension marker segments, only grayscale or RGB images
602 may have thumbnails. If thumbnails are present when writing any other type
603 of image, the thumbnails are ignored and a warning is sent to any warning
604 listeners.
605
606 <h2>
607 <a name=prog>Progressive Encoding</a>
608 </h2>
609
610 Progressive encoding must be enabled on the <code>ImageWriteParam</code>
611 passed in to a write operation, or the image will be written sequentially,
612 regardless of the scan headers included in the metadata object. If
613 progressive encoding is enabled and set to copy from metadata, then
614 the sequence of scan headers from the metadata is used to write the
615 image. If progressive encoding is enabled and set to use a default,
616 then the scans in the metadata are ignored and a default set of scans
617 is used. Progressive encoding always forces optimized Huffman tables to
618 be used. Any Huffman tables present in the metadata will be ignored,
619 and a warning will be sent to any warning listeners.
620
621 If Huffman-table optimization is requested on the <code>ImageWriteParam</code>,
622 all Huffman tables in the metadata or in the <code>ImageWriteParam</code>
623 itself are ignored, and a warning will be sent to any warning listeners if
624 any such tables are present.
625
626 <h2>
627 <a name=tree>Native Metadata Format Tree Structure and Editing</a>
628 </h2>
629
630 The DTDs below describe just the trees of metadata objects actually returned
631 by the <code>IIOMetadata</code> object. They do not include nodes
632 corresponding to <code>SOI</code>, <code>EOI</code>, or <code>RST</code>
633 markers, as these parsing delimiters do not carry any meaningful metadata.
634 <p>
635
636 The first node is always a <code>JPEGvariety</code> node. In the
637 <code>javax_imageio_jpeg_image_1.0</code> version of the JPEG metadata
638 format, this node may have one child, an <code>app0JFIF</code> node,
639 indicating that the JPEG stream contains a JFIF marker segment and related
640 data, or no children, indicating that the stream contains no JFIF marker.
641 In future versions of the JPEG metadata format, other varieties of JPEG
642 metadata may be supported (e.g. Exif) by defining other types of nodes
643 which may appear as a child of the <code>JPEGvariety</code> node.
644 <p>
645
646 (Note that an application wishing to interpret Exif metadata given
647 a metadata tree structure in the <code>javax_imageio_jpeg_image_1.0</code>
648 format must check for an <code>unknown</code> marker segment with a tag
649 indicating an <code>APP1</code> marker and containing data identifying it
650 as an Exif marker segment. Then it may use application-specific code to
651 interpret the data in the marker segment. If such an application were
652 to encounter a metadata tree formatted according to a future version of
653 the JPEG metadata format, the Exif marker segment might not be
654 <code>unknown</code> in that format - it might be structured as a
655 child node of the <code>JPEGvariety</code> node. Thus, it is important
656 for an application to specify which version to use by passing the string
657 identifying the version to the method/constructor used to obtain an
658 <code>IIOMetadata</code> object.)
659
660 <p>
661
662 On reading, <code>JFXX</code> and <code>app2ICC</code> nodes occur as
663 children of an <code>app0JFIF</code> node.
664 This is true regardless of where the JFXX <code>APP0</code> and
665 <code>APP2</code> marker segments actually occur in the stream. The ordering
666 of nodes within the <code>markerSequence</code> node corresponds to the
667 ordering of marker segments found in the JPEG stream.
668 <p>
669 On writing, any <code>JFXX</code> and <code>app2ICC</code> nodes must
670 occur as children of an <code>app0JFIF</code> node, itself a child of a
671 <code>JPEGvariety</code> node, which must always be the first node.
672 (If the stream is not to be JFIF compliant, no <code>app0JFIF</code> node
673 should be provided, and the <code>JPEGvariety</code> node should have no
674 children.) Any
675 JFIF <code>APP0</code>, JFXX <code>APP0</code>, and <code>APP2</code> marker
676 segments are written first, followed by all Adobe <code>APP14</code>,
677 <code>APPn</code>, <code>COM</code> and unknown segments in the
678 order in which their corresponding nodes appear in the
679 <code>markerSequence</code> node, followed by <code>DQT</code> (and
680 <code>DHT</code> for non-progressive writes) marker segments, followed by the
681 <code>SOF</code> and <code>SOS</code> marker segments. For progressive writes
682 using metadata to control progression, the <code>SOS</code> segments are used
683 in the order in which their corresponding nodes occur in the
684 <code>markerSequence</code> node.
685 <p>
686
687 The <code>reset</code>, <code>mergeTree</code> and <code>setFromTree</code>
688 operations have the following semantics for the JPEG plug-in metadata object:
689
690 <p> <code>reset</code> - A call to <code>reset</code> will restore the
691 metadata object to the same state it had immediately after creation, whether
692 this came about from reading a stream or by obtaining a default object from
693 the <code>ImageWriter</code>. This is true regardless of how many times the
694 metadata object has been modified since creation.
695
696 <p> <code>mergeTree</code> - Native Format
697 <br> The <code>mergeTree</code> operation accepts valid trees conforming to
698 the DTD below, and merges the nodes using the following ordering rules. In
699 all cases, only data present in the new node is changed in a corresponding
700 existing node, if any. This means that nodes cannot be removed using
701 <code>mergeTree</code>. To remove nodes, use <code>setFromTree</code>. The
702 tree must consist of <code>IIOMetadataNode</code>s.
703 <ul>
704 <li> <code>app0JFIF</code>
705 <ul>
706 <li> If an <code>app0JFIF</code> node already exists, the contents
707 of the new one modify the existing one.
708 <li> If there is no such node, a new one is created and inserted in
709 the appropriate position.
710 </ul>
711 <li> <code>dqt</code>
712 <ul>
713 <li> If there already exist <code>dqt</code> nodes in the sequence,
714 then each table in the node replaces the first table, in any
715 <code>dqt</code> node, with the same table id.
716 <li> If none of the existing <code>dqt</code> nodes contain a table
717 with the same id, then the table is added to the last existing
718 <code>dqt</code> node.
719 <li> If there are no <code>dqt</code> nodes, then a new one is
720 created and added as follows:
721 <ul>
722 <li> If there are <code>dht</code> nodes, the new
723 <code>dqt</code> node is inserted before the first one.
724 <li> If there are no <code>dht</code> nodes, the new
725 <code>dqt</code> node is inserted before an
726 <code>sof</code> node, if there is one.
727 <li> If there is no <code>sof</code> node, the new
728 <code>dqt</code> node is inserted before the first
729 <code>sos</code> node, if there is one.
730 <li> If there is no <code>sos</code> node, the new
731 <code>dqt</code> node is added to the end of the sequence.
732 </ul>
733 </ul>
734 <li> <code>dht</code>
735 <ul>
736 <li> If there already exist <code>dht</code> nodes in the sequence,
737 then each table in the node replaces the first table, in any
738 <code>dht</code> node, with the same table class and table id.
739 <li> If none of the existing <code>dht</code> nodes contain a table
740 with the same class and id, then the table is added to the last
741 existing <code>dht</code> node.
742 <li> If there are no <code>dht</code> nodes, then a new one is
743 created and added as follows:
744 <ul>
745 <li> If there are <code>dqt</code> nodes, the new
746 <code>dht</code> node is inserted immediately following the
747 last <code>dqt</code> node.
748 <li> If there are no <code>dqt</code> nodes, the new
749 <code>dht</code> node is inserted before an
750 <code>sof</code> node, if there is one.
751 <li> If there is no <code>sof</code> node, the new
752 <code>dht</code> node is inserted before the first
753 <code>sos</code> node, if there is one.
754 <li> If there is no <code>sos</code> node, the new
755 <code>dht</code> node is added to the end of the sequence.
756 </ul>
757 </ul>
758 <li> <code>dri</code>
759 <ul>
760 <li> If there already exists a <code>dri</code> node, the restart
761 interval value is updated.
762 <li> If there is no <code>dri</code> node, then a new one is created
763 and added as follows:
764 <ul>
765 <li> If there is an <code>sof</code> node, the new
766 <code>dri</code> node is inserted before it.
767 <li> If there is no <code>sof</code> node, the new
768 <code>dri</code> node is inserted before the first
769 <code>sos</code> node, if there is one.
770 <li> If there is no <code>sos</code> node, the new
771 <code>dri</code> node is added to the end of the sequence.
772 </ul>
773 </ul>
774 <li> <code>com</code>
775 <br> A new <code>com</code> node is created and inserted as follows:
776 <ul>
777 <li> If there already exist <code>com</code> nodes, the new one is
778 inserted after the last one.
779 <li> If there are no <code>com</code> nodes, the new
780 <code>com</code> node is inserted after the
781 <code>app14Adobe</code> node, if there is one.
782 <li> If there is no <code>app14Adobe</code> node, the new
783 <code>com</code> node is inserted at the beginning of the
784 sequence.
785 </ul>
786 <li> <code>app14Adobe</code>
787 <ul>
788 <li> If there already exists an <code>app14Adobe</code> node, then
789 its attributes are updated from the node.
790 <li> If there is no <code>app14Adobe</code> node, then a new one is
791 created and added as follows:
792 <ul>
793 <li> The new <code>app14Adobe</code> node is inserted after the
794 last <code>unknown</code> node, if there are any.
795 <li> If there are no <code>unknown</code> nodes, the new
796 <code>app14Adobe</code> node is inserted at the beginning
797 of the sequence.
798 </ul>
799 </ul>
800 <li> <code>unknown</code>
801 <br> A new <code>unknown</code> node is created and added to the
802 sequence as follows:
803 <ul>
804 <li> If there already exist <code>unknown</code> marker nodes, the
805 new one is inserted after the last one.
806 <li> If there are no <code>unknown</code> nodes, the new
807 <code>unknown</code> node is inserted before the
808 <code>app14Adobe</code> node, if there is one.
809 <li> If there is no <code>app14Adobe</code> node, the new
810 <code>unknown</code> node is inserted at the beginning of the
811 sequence.
812 </ul>
813 <li> <code>sof</code>
814 <ul>
815 <li> If there already exists an <code>sof</code> node in the
816 sequence, then its values are updated from the node.
817 <li> If there is no <code>sof</code> node, then a new one is created
818 and added as follows:
819 <ul>
820 <li> If there are any <code>sos</code> nodes, the new
821 <code>sof</code> node is inserted before the first one.
822 <li> If there is no <code>sos</code> node, the new
823 <code>sof</code> node is added to the end of the sequence.
824 </ul>
825 </ul>
826 <li> <code>sos</code>
827 <ul>
828 <li> If there already exists a single <code>sos</code> node, then
829 the values are updated from the node.
830 <li> If there are more than one existing <code>sos</code> nodes,
831 then an <code>IIOInvalidTreeException</code> is thrown, as
832 <code>sos</code> nodes cannot be merged into a set of
833 progressive scans.
834 <li> If there are no <code>sos</code> nodes, a new one is created
835 and added to the end of the sequence.
836 </ul>
837 </ul>
838
839 <p> <code>mergeTree</code> - Standard Format
840 <br>
841 The <code>mergeTree</code> operation, when given a tree in the standard
842 format, will modify the native tree in the following ways:
843 <ul>
844 <li> <code>Chroma</code> - The <code>ColorSpaceType</code> subnode of a
845 <code>Chroma</code> node may change the target colorspace of the
846 compressed image. The selection of a new colorspace can cause a number
847 of changes, in keeping with the algorithms described above:
848 <code>app0JFIF</code> and <code>app14Adobe</code> nodes may be added
849 or removed, subsampling may be added or removed, component ids may
850 be changed, and <code>sof</code> and <code>sos</code> nodes will be
851 updated accordingly. If necessary, additional quantization and
852 huffman tables are added. In the case of quantization tables, the
853 default will be scaled to match the quality level of any existing
854 tables. No tables are added to metadata that does not already contain
855 tables. If the existing metadata specifies progressive encoding, then
856 the number of channels must not change. Any <code>Transparency</code>
857 node is also taken into account, as an explicit value of
858 <code>none</code> for the <code>Alpha</code> subnode can cause the
859 removal of an alpha channel, and anything other than <code>none</code>
860 can cause the addition of an alpha channel.
861 <li> <code>Dimension</code> - A <code>PixelAspectRatio</code> specification
862 can cause the contents of an <code>app0JFIF</code> node to change, if
863 there is one present, or the addition of an <code>app0JFIF</code> node
864 containing appropriate values, if there can be one. An appropriate
865 pair of integers is computed from the floating-point ratio for
866 inclusion in the node.
867 <li> <code>Text</code> - Each uncompressed text item is converted to a
868 <code>com</code> node and inserted according to the rules above for
869 merging <code>com</code> nodes.
870 </ul>
871
872 <p> <code>setFromTree</code> - Native Format
873 <br>
874 The <code>setFromTree</code> operation, when given a tree in the native
875 format described below, will simply replace the existing tree in its entirety
876 with the new one. The tree must consist of <code>IIOMetadataNode</code>s.
877
878 <p> <code>setFromTree</code> - Standard Format
879 <br>
880 The <code>setFromTree</code> operation, when given a tree in the standard
881 format, performs a <code>reset</code> followed by a merge of the new tree.
882
883 <h2>
884 <a name=image>Image Metadata DTD</a>
885 </h2>
886
887 <pre>
888 <!DOCTYPE "javax_imageio_jpeg_image_1.0" [
889
890 <!ELEMENT "javax_imageio_jpeg_image_1.0" (JPEGvariety, markerSequence)>
891
892 <!ELEMENT "JPEGvariety" (app0JFIF)>
893 <!-- A node grouping all marker segments specific to the variety of
894 stream being read/written (e.g. JFIF) - may be empty -->
895
896 <!ELEMENT "app0JFIF" (JFXX?, app2ICC?)>
897 <!ATTLIST "app0JFIF" "majorVersion" #CDATA "1">
898 <!-- The major JFIF version number -->
899 <!-- Data type: Integer -->
900 <!-- Min value: 0 (inclusive) -->
901 <!-- Max value: 255 (inclusive) -->
902 <!ATTLIST "app0JFIF" "minorVersion" #CDATA "2">
903 <!-- The minor JFIF version number -->
904 <!-- Data type: Integer -->
905 <!-- Min value: 0 (inclusive) -->
906 <!-- Max value: 255 (inclusive) -->
907 <!ATTLIST "app0JFIF" "resUnits" ("0" | "1" | "2") "0">
908 <!-- The resolution units for Xdensisty and Ydensity (0 = no
909 units, just aspect ratio; 1 = dots/inch; 2 = dots/cm) -->
910 <!ATTLIST "app0JFIF" "Xdensity" #CDATA "1">
911 <!-- The horizontal density or aspect ratio numerator -->
912 <!-- Data type: Integer -->
913 <!-- Min value: 1 (inclusive) -->
914 <!-- Max value: 65535 (inclusive) -->
915 <!ATTLIST "app0JFIF" "Ydensity" #CDATA "1">
916 <!-- The vertical density or aspect ratio denominator -->
917 <!-- Data type: Integer -->
918 <!-- Min value: 1 (inclusive) -->
919 <!-- Max value: 65535 (inclusive) -->
920 <!ATTLIST "app0JFIF" "thumbWidth" #CDATA "0">
921 <!-- The width of the thumbnail, or 0 if there isn't one -->
922 <!-- Data type: Integer -->
923 <!-- Min value: 0 (inclusive) -->
924 <!-- Max value: 255 (inclusive) -->
925 <!ATTLIST "app0JFIF" "thumbHeight" #CDATA "0">
926 <!-- The height of the thumbnail, or 0 if there isn't one -->
927 <!-- Data type: Integer -->
928 <!-- Min value: 0 (inclusive) -->
929 <!-- Max value: 255 (inclusive) -->
930
931 <!ELEMENT "JFXX" (app0JFXX)*>
932 <!-- Min children: 1 -->
933
934 <!ELEMENT "app0JFXX" (JFIFthumbJPEG | JFIFthumbPalette |
935 JFIFthumbRGB)>
936 <!-- A JFIF extension marker segment -->
937 <!ATTLIST "app0JFXX" "extensionCode" ("16" | "17" | "19")
938 #IMPLIED>
939 <!-- The JFXX extension code identifying thumbnail type: (16 =
940 JPEG, 17 = indexed, 19 = RGB -->
941
942 <!ELEMENT "JFIFthumbJPEG" (markerSequence?)>
943 <!-- A JFIF thumbnail in JPEG format (no JFIF segments
944 permitted) -->
945
946 <!ELEMENT "JFIFthumbPalette" EMPTY>
947 <!-- A JFIF thumbnail as an RGB indexed image -->
948 <!ATTLIST "JFIFthumbPalette" "thumbWidth" #CDATA #IMPLIED>
949 <!-- The width of the thumbnail -->
950 <!-- Data type: Integer -->
951 <!-- Min value: 0 (inclusive) -->
952 <!-- Max value: 255 (inclusive) -->
953 <!ATTLIST "JFIFthumbPalette" "thumbHeight" #CDATA #IMPLIED>
954 <!-- The height of the thumbnail -->
955 <!-- Data type: Integer -->
956 <!-- Min value: 0 (inclusive) -->
957 <!-- Max value: 255 (inclusive) -->
958
959 <!ELEMENT "JFIFthumbRGB" EMPTY>
960 <!-- A JFIF thumbnail as an RGB image -->
961 <!ATTLIST "JFIFthumbRGB" "thumbWidth" #CDATA #IMPLIED>
962 <!-- The width of the thumbnail -->
963 <!-- Data type: Integer -->
964 <!-- Min value: 0 (inclusive) -->
965 <!-- Max value: 255 (inclusive) -->
966 <!ATTLIST "JFIFthumbRGB" "thumbHeight" #CDATA #IMPLIED>
967 <!-- The height of the thumbnail -->
968 <!-- Data type: Integer -->
969 <!-- Min value: 0 (inclusive) -->
970 <!-- Max value: 255 (inclusive) -->
971
972 <!ELEMENT "app2ICC" EMPTY>
973 <!-- An ICC profile APP2 marker segment -->
974 <!-- Optional User object: java.awt.color.ICC_Profile -->
975
976 <!ELEMENT "markerSequence" (dqt | dht | dri | com | unknown |
977 app14Adobe | sof | sos)*>
978 <!-- A node grouping all non-jfif marker segments -->
979
980 <!ELEMENT "dqt" (dqtable)*>
981 <!-- A Define Quantization Table(s) marker segment -->
982 <!-- Min children: 1 -->
983 <!-- Max children: 4 -->
984
985 <!ELEMENT "dqtable" EMPTY>
986 <!-- A single quantization table -->
987 <!-- User object: javax.imageio.plugins.jpeg.JPEGQTable -->
988 <!ATTLIST "dqtable" "elementPrecision" #CDATA "0">
989 <!-- The number of bits in each table element (0 = 8, 1 = 16)
990 -->
991 <!-- Data type: Integer -->
992 <!ATTLIST "dqtable" "qtableId" ("0" | "1" | "2" | "3") #REQUIRED>
993
994 <!ELEMENT "dht" (dhtable)*>
995 <!-- A Define Huffman Table(s) marker segment -->
996 <!-- Min children: 1 -->
997 <!-- Max children: 4 -->
998
999 <!ELEMENT "dhtable" EMPTY>
1000 <!-- A single Huffman table -->
1001 <!-- User object: javax.imageio.plugins.jpeg.JPEGHuffmanTable -->
1002 <!ATTLIST "dhtable" "class" ("0" | "1") #REQUIRED>
1003 <!-- Indicates whether this is a DC (0) or an AC (1) table -->
1004 <!ATTLIST "dhtable" "htableId" ("0" | "1" | "2" | "3") #REQUIRED>
1005 <!-- The table id -->
1006
1007 <!ELEMENT "dri" EMPTY>
1008 <!-- A Define Restart Interval marker segment -->
1009 <!ATTLIST "dri" "interval" #CDATA #REQUIRED>
1010 <!-- The restart interval in MCUs -->
1011 <!-- Data type: Integer -->
1012 <!-- Min value: 0 (inclusive) -->
1013 <!-- Max value: 65535 (inclusive) -->
1014
1015 <!ELEMENT "com" EMPTY>
1016 <!-- A Comment marker segment. The user object contains the actual
1017 bytes. -->
1018 <!-- User object: array of [B -->
1019 <!-- Min length: 1 -->
1020 <!-- Max length: 65533 -->
1021 <!ATTLIST "com" "comment" #CDATA #IMPLIED>
1022 <!-- The comment as a string (used only if user object is null)
1023 -->
1024 <!-- Data type: String -->
1025
1026 <!ELEMENT "unknown" EMPTY>
1027 <!-- An unrecognized marker segment. The user object contains the
1028 data not including length. -->
1029 <!-- User object: array of [B -->
1030 <!-- Min length: 1 -->
1031 <!-- Max length: 65533 -->
1032 <!ATTLIST "unknown" "MarkerTag" #CDATA #REQUIRED>
1033 <!-- The tag identifying this marker segment -->
1034 <!-- Data type: Integer -->
1035 <!-- Min value: 0 (inclusive) -->
1036 <!-- Max value: 255 (inclusive) -->
1037
1038 <!ELEMENT "app14Adobe" EMPTY>
1039 <!-- An Adobe APP14 marker segment -->
1040 <!ATTLIST "app14Adobe" "version" #CDATA "100">
1041 <!-- The version of Adobe APP14 marker segment -->
1042 <!-- Data type: Integer -->
1043 <!-- Min value: 100 (inclusive) -->
1044 <!-- Max value: 255 (inclusive) -->
1045 <!ATTLIST "app14Adobe" "flags0" #CDATA "0">
1046 <!-- The flags0 variable of an APP14 marker segment -->
1047 <!-- Data type: Integer -->
1048 <!-- Min value: 0 (inclusive) -->
1049 <!-- Max value: 65535 (inclusive) -->
1050 <!ATTLIST "app14Adobe" "flags1" #CDATA "0">
1051 <!-- The flags1 variable of an APP14 marker segment -->
1052 <!-- Data type: Integer -->
1053 <!-- Min value: 0 (inclusive) -->
1054 <!-- Max value: 65535 (inclusive) -->
1055 <!ATTLIST "app14Adobe" "transform" ("0" | "1" | "2") #REQUIRED>
1056 <!-- The color transform applied to the image (0 = Unknown, 1 =
1057 YCbCr, 2 = YCCK) -->
1058
1059 <!ELEMENT "sof" (componentSpec)*>
1060 <!-- A Start Of Frame marker segment -->
1061 <!-- Min children: 1 -->
1062 <!-- Max children: 4 -->
1063 <!ATTLIST "sof" "process" ("0" | "1" | "2") #IMPLIED>
1064 <!-- The JPEG process (0 = Baseline sequential, 1 = Extended
1065 sequential, 2 = Progressive) -->
1066 <!ATTLIST "sof" "samplePrecision" #CDATA "8">
1067 <!-- The number of bits per sample -->
1068 <!-- Data type: Integer -->
1069 <!ATTLIST "sof" "numLines" #CDATA #IMPLIED>
1070 <!-- The number of lines in the image -->
1071 <!-- Data type: Integer -->
1072 <!-- Min value: 0 (inclusive) -->
1073 <!-- Max value: 65535 (inclusive) -->
1074 <!ATTLIST "sof" "samplesPerLine" #CDATA #IMPLIED>
1075 <!-- The number of samples per line -->
1076 <!-- Data type: Integer -->
1077 <!-- Min value: 0 (inclusive) -->
1078 <!-- Max value: 65535 (inclusive) -->
1079 <!ATTLIST "sof" "numFrameComponents" ("1" | "2" | "3" | "4")
1080 #IMPLIED>
1081 <!-- The number of components in the image -->
1082
1083 <!ELEMENT "componentSpec" EMPTY>
1084 <!-- A component specification for a frame -->
1085 <!ATTLIST "componentSpec" "componentId" #CDATA #REQUIRED>
1086 <!-- The id for this component -->
1087 <!-- Data type: Integer -->
1088 <!-- Min value: 0 (inclusive) -->
1089 <!-- Max value: 255 (inclusive) -->
1090 <!ATTLIST "componentSpec" "HsamplingFactor" #CDATA #REQUIRED>
1091 <!-- The horizontal sampling factor for this component -->
1092 <!-- Data type: Integer -->
1093 <!-- Min value: 1 (inclusive) -->
1094 <!-- Max value: 255 (inclusive) -->
1095 <!ATTLIST "componentSpec" "VsamplingFactor" #CDATA #REQUIRED>
1096 <!-- The vertical sampling factor for this component -->
1097 <!-- Data type: Integer -->
1098 <!-- Min value: 1 (inclusive) -->
1099 <!-- Max value: 255 (inclusive) -->
1100 <!ATTLIST "componentSpec" "QtableSelector" ("0" | "1" | "2" |
1101 "3") #REQUIRED>
1102 <!-- The quantization table to use for this component -->
1103
1104 <!ELEMENT "sos" (scanComponentSpec)*>
1105 <!-- A Start Of Scan marker segment -->
1106 <!-- Min children: 1 -->
1107 <!-- Max children: 4 -->
1108 <!ATTLIST "sos" "numScanComponents" ("1" | "2" | "3" | "4")
1109 #REQUIRED>
1110 <!-- The number of components in the scan -->
1111 <!ATTLIST "sos" "startSpectralSelection" #CDATA "0">
1112 <!-- The first spectral band included in this scan -->
1113 <!-- Data type: Integer -->
1114 <!-- Min value: 0 (inclusive) -->
1115 <!-- Max value: 63 (inclusive) -->
1116 <!ATTLIST "sos" "endSpectralSelection" #CDATA "63">
1117 <!-- The last spectral band included in this scan -->
1118 <!-- Data type: Integer -->
1119 <!-- Min value: 0 (inclusive) -->
1120 <!-- Max value: 63 (inclusive) -->
1121 <!ATTLIST "sos" "approxHigh" #CDATA "0">
1122 <!-- The highest bit position included in this scan -->
1123 <!-- Data type: Integer -->
1124 <!-- Min value: 0 (inclusive) -->
1125 <!-- Max value: 15 (inclusive) -->
1126 <!ATTLIST "sos" "approxLow" #CDATA "0">
1127 <!-- The lowest bit position included in this scan -->
1128 <!-- Data type: Integer -->
1129 <!-- Min value: 0 (inclusive) -->
1130 <!-- Max value: 15 (inclusive) -->
1131
1132 <!ELEMENT "scanComponentSpec" EMPTY>
1133 <!-- A component specification for a scan -->
1134 <!ATTLIST "scanComponentSpec" "componentSelector" #CDATA
1135 #REQUIRED>
1136 <!-- The id of this component -->
1137 <!-- Data type: Integer -->
1138 <!-- Min value: 0 (inclusive) -->
1139 <!-- Max value: 255 (inclusive) -->
1140 <!ATTLIST "scanComponentSpec" "dcHuffTable" ("0" | "1" | "2" |
1141 "3") #REQUIRED>
1142 <!-- The huffman table to use for encoding DC coefficients -->
1143 <!ATTLIST "scanComponentSpec" "acHuffTable" ("0" | "1" | "2" |
1144 "3") #REQUIRED>
1145 <!-- The huffman table to use for encoding AC coefficients -->
1146 ]>
1147 </pre>
1148
1149 <h2>
1150 <a name=stream>Stream Metadata DTD</a>
1151 </h2>
1152
1153 <pre>
1154 <!DOCTYPE "javax_imageio_jpeg_stream_1.0" [
1155 <!ELEMENT "javax_imageio_jpeg_stream_1.0" (dqt |
1156 dht |
1157 dri |
1158 com |
1159 unknown)*>
1160
1161 <!-- All elements are as defined above for image metadata -->
1162 ]>
1163 </pre>
1164
1165 </body>
1166 </html>