src/java.desktop/share/classes/javax/imageio/metadata/doc-files/gif_metadata.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/src/java.desktop/share/classes/javax/imageio/metadata/doc-files/gif_metadata.html Tue Sep 12 19:03:39 2017 +0200
@@ -0,0 +1,449 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<html>
+<head>
+<!--
+Copyright (c) 2000, 2015, Oracle and/or its affiliates. All rights reserved.
+DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+
+This code is free software; you can redistribute it and/or modify it
+under the terms of the GNU General Public License version 2 only, as
+published by the Free Software Foundation. Oracle designates this
+particular file as subject to the "Classpath" exception as provided
+by Oracle in the LICENSE file that accompanied this code.
+
+This code is distributed in the hope that it will be useful, but WITHOUT
+ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+version 2 for more details (a copy is included in the LICENSE file that
+accompanied this code).
+
+You should have received a copy of the GNU General Public License version
+2 along with this work; if not, write to the Free Software Foundation,
+Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+
+Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+or visit www.oracle.com if you need additional information or have any
+questions.
+-->
+
+<title>GIF Metadata Format Specification</title>
+</head>
+
+<body bgcolor="white">
+
+<center><h1>
+GIF Metadata Format Specification
+</h1></center>
+<a name="gif_stream_metadata_format"></a>
+<center><h2>
+GIF Stream Metadata Format Specification
+</h2></center>
+
+<p>
+
+The GIF stream metadata format encodes the information stored in the
+per-file header, namely the file version, logical screen descriptor,
+and the global color table.
+
+<p>
+
+The logical screen descriptor describes the overall width and height
+of an animated file, as well as information about the color resolution
+(number of bits per pixel) and pixel aspect ratio.
+
+<p>
+
+The global color table contains a color lookup table that is used for
+images that do not have their own local color table.
+
+<pre>
+<!DOCTYPE "javax_imageio_gif_stream_1.0" [
+
+ <!ELEMENT "javax_imageio_gif_stream_1.0" (Version?,
+ LogicalScreenDescriptor?, GlobalColorTable?)>
+
+ <!ELEMENT "Version" EMPTY>
+ <!-- The file version, either 87a or 89a -->
+ <!ATTLIST "Version" "value" ("87a" | "89a") #REQUIRED>
+ <!-- The version string -->
+
+ <!ELEMENT "LogicalScreenDescriptor" EMPTY>
+ <!-- The logical screen descriptor, except for the global color table -->
+ <!ATTLIST "LogicalScreenDescriptor" "logicalScreenWidth" #CDATA
+ #REQUIRED>
+ <!-- The width in pixels of the whole picture -->
+ <!-- Data type: Integer -->
+ <!-- Min value: 1 (inclusive) -->
+ <!-- Max value: 65535 (inclusive) -->
+ <!ATTLIST "LogicalScreenDescriptor" "logicalScreenHeight" #CDATA
+ #REQUIRED>
+ <!-- The height in pixels of the whole picture -->
+ <!-- Data type: Integer -->
+ <!-- Min value: 1 (inclusive) -->
+ <!-- Max value: 65535 (inclusive) -->
+ <!ATTLIST "LogicalScreenDescriptor" "colorResolution" #CDATA
+ #REQUIRED>
+ <!-- The number of bits of color resolution, beteen 1 and 8 -->
+ <!-- Data type: Integer -->
+ <!-- Min value: 1 (inclusive) -->
+ <!-- Max value: 8 (inclusive) -->
+ <!ATTLIST "LogicalScreenDescriptor" "pixelAspectRatio" #CDATA
+ #REQUIRED>
+ <!-- If 0, indicates square pixels, else W/H = (value + 15)/64 -->
+ <!-- Data type: Integer -->
+ <!-- Min value: 0 (inclusive) -->
+ <!-- Max value: 255 (inclusive) -->
+
+ <!ELEMENT "GlobalColorTable" (ColorTableEntry)*>
+ <!-- The global color table -->
+ <!-- Min children: 2 -->
+ <!-- Max children: 256 -->
+ <!ATTLIST "GlobalColorTable" "sizeOfGlobalColorTable" ("2" |
+ "4" | "8" | "16" | "32" | "64" | "128" | "256") #REQUIRED>
+ <!-- The number of entries in the global color table -->
+ <!ATTLIST "GlobalColorTable" "backgroundColorIndex" #CDATA
+ #REQUIRED>
+ <!-- The index of the color table entry to be used as a background -->
+ <!-- Data type: Integer -->
+ <!-- Min value: 0 (inclusive) -->
+ <!-- Max value: 255 (inclusive) -->
+ <!ATTLIST "GlobalColorTable" "sortFlag" ("TRUE" | "FALSE")
+ #REQUIRED>
+ <!-- True if the global color table is sorted by frequency -->
+
+ <!ELEMENT "ColorTableEntry" EMPTY>
+ <!-- A global color table entry -->
+ <!ATTLIST "ColorTableEntry" "index" #CDATA #REQUIRED>
+ <!-- The index of the color table entry -->
+ <!-- Data type: Integer -->
+ <!-- Min value: 0 (inclusive) -->
+ <!-- Max value: 255 (inclusive) -->
+ <!ATTLIST "ColorTableEntry" "red" #CDATA #REQUIRED>
+ <!-- The red value for the color table entry -->
+ <!-- Data type: Integer -->
+ <!-- Min value: 0 (inclusive) -->
+ <!-- Max value: 255 (inclusive) -->
+ <!ATTLIST "ColorTableEntry" "green" #CDATA #REQUIRED>
+ <!-- The green value for the color table entry -->
+ <!-- Data type: Integer -->
+ <!-- Min value: 0 (inclusive) -->
+ <!-- Max value: 255 (inclusive) -->
+ <!ATTLIST "ColorTableEntry" "blue" #CDATA #REQUIRED>
+ <!-- The blue value for the color table entry -->
+ <!-- Data type: Integer -->
+ <!-- Min value: 0 (inclusive) -->
+ <!-- Max value: 255 (inclusive) -->
+]>
+</pre>
+<a name="gif_image_metadata_format"></a>
+<center><h2>
+GIF Image Metadata Format Specification
+</h2></center>
+<p>
+
+The GIF image metadata format encodes the image descriptor, local
+color table, and extension information assciated with a single image
+within a GIF file, typically a frame of an animation.
+
+<p>
+
+The image description contains the offset of the frame within the
+logical screen described in the stream metadata, as well as the width
+and height of the frame and whether it is used interlaced encoding.
+
+<p>
+
+The local color table, if present, supersedes the global color table
+for the frame at hand.
+
+<p>
+
+The graphic control extension contains information on how the frame is
+to be incorporated into the animation. The disposal method indicates
+whether the current frame should remain in place
+(<code>doNotDispose</code>), be restored to the backgound color as
+specified in the stream metadata
+(<code>restoreToBackgroundColor</code>), or be restored to the
+previous frame contents (<code>restoreToPrevious</code>) prior to
+displaying the subsequent frame.
+
+<p>
+
+The user input flag indicates whether the animation should pause for
+user input before advancing to the next frame. The transparent color
+flag and index indicate a color index for which pixels of the frame
+should not be drawn. The delay time indicates how long the frame
+should be displayed, in hundredths of a second. If the user input
+flag is set and the delay time is 0, the frame is intended to be
+advanced only on user input.
+
+<pre>
+<!DOCTYPE "javax_imageio_gif_image_1.0" [
+
+ <!ELEMENT "javax_imageio_gif_image_1.0" (ImageDescriptor?,
+ LocalColorTable?, GraphicControlExtension?, PlainTextExtension?,
+ ApplicationExtensions?, CommentExtensions?)>
+
+ <!ELEMENT "ImageDescriptor" EMPTY>
+ <!-- The image descriptor -->
+ <!ATTLIST "ImageDescriptor" "imageLeftPosition" #CDATA #REQUIRED>
+ <!-- The X offset of the image relative to the screen origin -->
+ <!-- Data type: Integer -->
+ <!-- Min value: 0 (inclusive) -->
+ <!-- Max value: 65535 (inclusive) -->
+ <!ATTLIST "ImageDescriptor" "imageTopPosition" #CDATA #REQUIRED>
+ <!-- The Y offset of the image relative to the screen origin -->
+ <!-- Data type: Integer -->
+ <!-- Min value: 0 (inclusive) -->
+ <!-- Max value: 65535 (inclusive) -->
+ <!ATTLIST "ImageDescriptor" "imageWidth" #CDATA #REQUIRED>
+ <!-- The width of the image -->
+ <!-- Data type: Integer -->
+ <!-- Min value: 1 (inclusive) -->
+ <!-- Max value: 65535 (inclusive) -->
+ <!ATTLIST "ImageDescriptor" "imageHeight" #CDATA #REQUIRED>
+ <!-- The height of the image -->
+ <!-- Data type: Integer -->
+ <!-- Min value: 1 (inclusive) -->
+ <!-- Max value: 65535 (inclusive) -->
+ <!ATTLIST "ImageDescriptor" "interlaceFlag" ("TRUE" | "FALSE")
+ #REQUIRED>
+ <!-- True if the image is stored using interlacing -->
+
+ <!ELEMENT "LocalColorTable" (ColorTableEntry)*>
+ <!-- The local color table -->
+ <!-- Min children: 2 -->
+ <!-- Max children: 256 -->
+ <!ATTLIST "LocalColorTable" "sizeOfLocalColorTable" ("2" |
+ "4" | "8" | "16" | "32" | "64" | "128" | "256") #REQUIRED>
+ <!-- The number of entries in the local color table -->
+ <!ATTLIST "LocalColorTable" "sortFlag" ("TRUE" | "FALSE")
+ #REQUIRED>
+ <!-- True if the local color table is sorted by frequency -->
+
+ <!ELEMENT "ColorTableEntry" EMPTY>
+ <!-- A local color table entry -->
+ <!ATTLIST "ColorTableEntry" "index" #CDATA #REQUIRED>
+ <!-- The index of the color table entry -->
+ <!-- Data type: Integer -->
+ <!-- Min value: 0 (inclusive) -->
+ <!-- Max value: 255 (inclusive) -->
+ <!ATTLIST "ColorTableEntry" "red" #CDATA #REQUIRED>
+ <!-- The red value for the color table entry -->
+ <!-- Data type: Integer -->
+ <!-- Min value: 0 (inclusive) -->
+ <!-- Max value: 255 (inclusive) -->
+ <!ATTLIST "ColorTableEntry" "green" #CDATA #REQUIRED>
+ <!-- The green value for the color table entry -->
+ <!-- Data type: Integer -->
+ <!-- Min value: 0 (inclusive) -->
+ <!-- Max value: 255 (inclusive) -->
+ <!ATTLIST "ColorTableEntry" "blue" #CDATA #REQUIRED>
+ <!-- The blue value for the color table entry -->
+ <!-- Data type: Integer -->
+ <!-- Min value: 0 (inclusive) -->
+ <!-- Max value: 255 (inclusive) -->
+
+ <!ELEMENT "GraphicControlExtension" EMPTY>
+ <!-- A graphic control extension -->
+ <!ATTLIST "GraphicControlExtension" "disposalMethod" ("none" |
+ "doNotDispose" | "restoreToBackgroundColor" |
+ "restoreToPrevious" | "undefinedDisposalMethod4" |
+ "undefinedDisposalMethod5" | "undefinedDisposalMethod6" |
+ "undefinedDisposalMethod7") #REQUIRED>
+ <!-- The disposal method for this frame -->
+ <!ATTLIST "GraphicControlExtension" "userInputFlag" ("TRUE" |
+ "FALSE") #REQUIRED>
+ <!-- True if the frame should be advanced based on user input -->
+ <!ATTLIST "GraphicControlExtension" "transparentColorFlag" (
+ "TRUE" | "FALSE") #REQUIRED>
+ <!-- True if a transparent color exists -->
+ <!ATTLIST "GraphicControlExtension" "delayTime" #CDATA #REQUIRED>
+ <!-- The time to delay between frames, in hundredths of a second -->
+ <!-- Data type: Integer -->
+ <!-- Min value: 0 (inclusive) -->
+ <!-- Max value: 65535 (inclusive) -->
+ <!ATTLIST "GraphicControlExtension" "transparentColorIndex"
+ #CDATA #REQUIRED>
+ <!-- The transparent color, if transparentColorFlag is true -->
+ <!-- Data type: Integer -->
+ <!-- Min value: 0 (inclusive) -->
+ <!-- Max value: 255 (inclusive) -->
+
+ <!ELEMENT "PlainTextExtension" EMPTY>
+ <!-- A plain text (text grid) extension -->
+ <!ATTLIST "PlainTextExtension" "textGridLeft" #CDATA #REQUIRED>
+ <!-- The X offset of the text grid -->
+ <!-- Data type: Integer -->
+ <!-- Min value: 0 (inclusive) -->
+ <!-- Max value: 65535 (inclusive) -->
+ <!ATTLIST "PlainTextExtension" "textGridTop" #CDATA #REQUIRED>
+ <!-- The Y offset of the text grid -->
+ <!-- Data type: Integer -->
+ <!-- Min value: 0 (inclusive) -->
+ <!-- Max value: 65535 (inclusive) -->
+ <!ATTLIST "PlainTextExtension" "textGridWidth" #CDATA #REQUIRED>
+ <!-- The number of columns in the text grid -->
+ <!-- Data type: Integer -->
+ <!-- Min value: 1 (inclusive) -->
+ <!-- Max value: 65535 (inclusive) -->
+ <!ATTLIST "PlainTextExtension" "textGridHeight" #CDATA #REQUIRED>
+ <!-- The number of rows in the text grid -->
+ <!-- Data type: Integer -->
+ <!-- Min value: 1 (inclusive) -->
+ <!-- Max value: 65535 (inclusive) -->
+ <!ATTLIST "PlainTextExtension" "characterCellWidth" #CDATA
+ #REQUIRED>
+ <!-- The width of a character cell -->
+ <!-- Data type: Integer -->
+ <!-- Min value: 1 (inclusive) -->
+ <!-- Max value: 65535 (inclusive) -->
+ <!ATTLIST "PlainTextExtension" "characterCellHeight" #CDATA
+ #REQUIRED>
+ <!-- The height of a character cell -->
+ <!-- Data type: Integer -->
+ <!-- Min value: 1 (inclusive) -->
+ <!-- Max value: 65535 (inclusive) -->
+ <!ATTLIST "PlainTextExtension" "textForegroundColor" #CDATA
+ #REQUIRED>
+ <!-- The text foreground color index -->
+ <!-- Data type: Integer -->
+ <!-- Min value: 0 (inclusive) -->
+ <!-- Max value: 255 (inclusive) -->
+ <!ATTLIST "PlainTextExtension" "textBackgroundColor" #CDATA
+ #REQUIRED>
+ <!-- The text background color index -->
+ <!-- Data type: Integer -->
+ <!-- Min value: 0 (inclusive) -->
+ <!-- Max value: 255 (inclusive) -->
+
+ <!ELEMENT "ApplicationExtensions" (ApplicationExtension)*>
+ <!-- A set of application extensions -->
+ <!-- Min children: 1 -->
+ <!-- Max children: 2147483647 -->
+
+ <!ELEMENT "ApplicationExtension" EMPTY>
+ <!-- An application extension -->
+ <!-- User object: array of byte -->
+ <!-- Min length: 0 -->
+ <!-- Max length: 2147483647 -->
+ <!ATTLIST "ApplicationExtension" "applicationID" #CDATA
+ #REQUIRED>
+ <!-- The application ID -->
+ <!-- Data type: String -->
+ <!ATTLIST "ApplicationExtension" "authenticationCode" #CDATA
+ #REQUIRED>
+ <!-- The authentication code -->
+ <!-- Data type: String -->
+
+ <!ELEMENT "CommentExtensions" (CommentExtension)*>
+ <!-- A set of comments -->
+ <!-- Min children: 1 -->
+ <!-- Max children: 2147483647 -->
+
+ <!ELEMENT "CommentExtension" EMPTY>
+ <!-- A comment -->
+ <!ATTLIST "CommentExtension" "value" #CDATA #REQUIRED>
+ <!-- The comment -->
+ <!-- Data type: String -->
+]>
+</pre>
+
+<p>
+<a name="mapping"></a>
+<center>
+<table border=1>
+<caption><b>Mapping of Standard to GIF Native Stream Metadata</b></caption>
+<tr>
+<th>Standard Metadata Component</th>
+<th>GIF Native Stream Metadata Component</th>
+</tr>
+<tr>
+<td>/Chroma/Palette/PaletteEntry@index</td>
+<td>/GlobalColorTable/ColorTableEntry@index</td>
+</tr>
+<tr>
+<td>/Chroma/Palette/PaletteEntry@red</td>
+<td>/GlobalColorTable/ColorTableEntry@red</td>
+</tr>
+<tr>
+<td>/Chroma/Palette/PaletteEntry@green</td>
+<td>/GlobalColorTable/ColorTableEntry@green</td>
+</tr>
+<tr>
+<td>/Chroma/Palette/PaletteEntry@blue</td>
+<td>/GlobalColorTable/ColorTableEntry@blue</td>
+</tr>
+<tr>
+<td>/Chroma/BackgroundIndex@value</td>
+<td>/GlobalColorTable@backgroundColorIndex</td>
+</tr>
+<tr>
+<td>/Data/BitsPerSample@value</td>
+<td>/LogicalScreenDescriptor@colorResolution</td>
+</tr>
+<tr>
+<td>/Dimension/PixelAspectRatio@value</td>
+<td>/LogicalScreenDescriptor@pixelAspectRatio</td>
+</tr>
+<tr>
+<td>/Dimension/HorizontalScreenSize@value</td>
+<td>/LogicalScreenDescriptor@logicalScreenWidth</td>
+</tr>
+<tr>
+<td>/Dimension/VerticalScreenSize@value</td>
+<td>/LogicalScreenDescriptor@logicalScreenHeight</td>
+</tr>
+<tr>
+<td>/Document/FormatVersion@value</td>
+<td>/Version@value</td>
+</tr>
+</table>
+</center>
+
+<center>
+<table border=1>
+<caption><b>Mapping of Standard to GIF Native Image Metadata</b></caption>
+<tr>
+<th>Standard Metadata Component</th>
+<th>GIF Native Image Metadata Component</th>
+</tr>
+<tr>
+<td>/Chroma/Palette/PaletteEntry@index</td>
+<td>/LocalColorTable/ColorTableEntry@index</td>
+</tr>
+<tr>
+<td>/Chroma/Palette/PaletteEntry@red</td>
+<td>/LocalColorTable/ColorTableEntry@red</td>
+</tr>
+<tr>
+<td>/Chroma/Palette/PaletteEntry@green</td>
+<td>/LocalColorTable/ColorTableEntry@green</td>
+</tr>
+<tr>
+<td>/Chroma/Palette/PaletteEntry@blue</td>
+<td>/LocalColorTable/ColorTableEntry@blue</td>
+</tr>
+<tr>
+<td>/Dimension/HorizontalPixelOffset@value</td>
+<td>/ImageDescriptor@imageLeftPosition</td>
+</tr>
+<tr>
+<td>/Dimension/VerticalPixelOffset@value</td>
+<td>/ImageDescriptor@imageTopPosition</td>
+</tr>
+<tr>
+<td>/Text/TextEntry@value</td>
+<td>/CommentExtensions/CommentExtension@value</td>
+</tr>
+<tr>
+<td>/Transparency/TransparentIndex@value</td>
+<td>/GraphicControlExtension@transparentColorIndex
+(/GraphicControlExtension@transparentColorFlag is also set to
+"TRUE")</td>
+</tr>
+</table>
+</center>
+
+</body>
+</html>