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>GIF Metadata Format Specification</title>
  30 </head>
  31 
  32 <body bgcolor="white">
  33 
  34 <center><h1>
  35 GIF Metadata Format Specification
  36 </h1></center>
  37 <a name="gif_stream_metadata_format"></a>
  38 <center><h2>
  39 GIF Stream Metadata Format Specification
  40 </h2></center>
  41 
  42 <p>
  43 
  44 The GIF stream metadata format encodes the information stored in the
  45 per-file header, namely the file version, logical screen descriptor,
  46 and the global color table.
  47 
  48 <p>
  49 
  50 The logical screen descriptor describes the overall width and height
  51 of an animated file, as well as information about the color resolution
  52 (number of bits per pixel) and pixel aspect ratio.
  53 
  54 <p>
  55 
  56 The global color table contains a color lookup table that is used for
  57 images that do not have their own local color table.
  58 
  59 <pre>
  60 &lt;!DOCTYPE "javax_imageio_gif_stream_1.0" [
  61 
  62   &lt;!ELEMENT "javax_imageio_gif_stream_1.0" (Version?, 
  63     LogicalScreenDescriptor?, GlobalColorTable?)&gt;
  64 
  65     &lt;!ELEMENT "Version" EMPTY&gt;
  66       &lt;!-- The file version, either 87a or 89a --&gt;
  67       &lt;!ATTLIST "Version" "value" ("87a" | "89a") #REQUIRED&gt;
  68         &lt;!-- The version string --&gt;
  69 
  70     &lt;!ELEMENT "LogicalScreenDescriptor" EMPTY&gt;
  71       &lt;!-- The logical screen descriptor, except for the global color table --&gt;
  72       &lt;!ATTLIST "LogicalScreenDescriptor" "logicalScreenWidth" #CDATA
  73          #REQUIRED&gt;
  74         &lt;!-- The width in pixels of the whole picture --&gt;
  75         &lt;!-- Data type: Integer --&gt;
  76         &lt;!-- Min value: 1 (inclusive) --&gt;
  77         &lt;!-- Max value: 65535 (inclusive) --&gt;
  78       &lt;!ATTLIST "LogicalScreenDescriptor" "logicalScreenHeight" #CDATA
  79          #REQUIRED&gt;
  80         &lt;!-- The height in pixels of the whole picture --&gt;
  81         &lt;!-- Data type: Integer --&gt;
  82         &lt;!-- Min value: 1 (inclusive) --&gt;
  83         &lt;!-- Max value: 65535 (inclusive) --&gt;
  84       &lt;!ATTLIST "LogicalScreenDescriptor" "colorResolution" #CDATA
  85          #REQUIRED&gt;
  86         &lt;!-- The number of bits of color resolution, beteen 1 and 8 --&gt;
  87         &lt;!-- Data type: Integer --&gt;
  88         &lt;!-- Min value: 1 (inclusive) --&gt;
  89         &lt;!-- Max value: 8 (inclusive) --&gt;
  90       &lt;!ATTLIST "LogicalScreenDescriptor" "pixelAspectRatio" #CDATA
  91          #REQUIRED&gt;
  92         &lt;!-- If 0, indicates square pixels, else W/H = (value + 15)/64 --&gt;
  93         &lt;!-- Data type: Integer --&gt;
  94         &lt;!-- Min value: 0 (inclusive) --&gt;
  95         &lt;!-- Max value: 255 (inclusive) --&gt;
  96 
  97     &lt;!ELEMENT "GlobalColorTable" (ColorTableEntry)*&gt;
  98       &lt;!-- The global color table --&gt;
  99       &lt;!-- Min children: 2 --&gt;
 100       &lt;!-- Max children: 256 --&gt;
 101       &lt;!ATTLIST "GlobalColorTable" "sizeOfGlobalColorTable" ("2" | 
 102         "4" | "8" | "16" | "32" | "64" | "128" | "256") #REQUIRED&gt;
 103         &lt;!-- The number of entries in the global color table --&gt;
 104       &lt;!ATTLIST "GlobalColorTable" "backgroundColorIndex" #CDATA
 105          #REQUIRED&gt;
 106         &lt;!-- The index of the color table entry to be used as a background --&gt;
 107         &lt;!-- Data type: Integer --&gt;
 108         &lt;!-- Min value: 0 (inclusive) --&gt;
 109         &lt;!-- Max value: 255 (inclusive) --&gt;
 110       &lt;!ATTLIST "GlobalColorTable" "sortFlag" ("TRUE" | "FALSE")
 111          #REQUIRED&gt;
 112         &lt;!-- True if the global color table is sorted by frequency --&gt;
 113 
 114       &lt;!ELEMENT "ColorTableEntry" EMPTY&gt;
 115         &lt;!-- A global color table entry --&gt;
 116         &lt;!ATTLIST "ColorTableEntry" "index" #CDATA #REQUIRED&gt;
 117           &lt;!-- The index of the color table entry --&gt;
 118           &lt;!-- Data type: Integer --&gt;
 119           &lt;!-- Min value: 0 (inclusive) --&gt;
 120           &lt;!-- Max value: 255 (inclusive) --&gt;
 121         &lt;!ATTLIST "ColorTableEntry" "red" #CDATA #REQUIRED&gt;
 122           &lt;!-- The red value for the color table entry --&gt;
 123           &lt;!-- Data type: Integer --&gt;
 124           &lt;!-- Min value: 0 (inclusive) --&gt;
 125           &lt;!-- Max value: 255 (inclusive) --&gt;
 126         &lt;!ATTLIST "ColorTableEntry" "green" #CDATA #REQUIRED&gt;
 127           &lt;!-- The green value for the color table entry --&gt;
 128           &lt;!-- Data type: Integer --&gt;
 129           &lt;!-- Min value: 0 (inclusive) --&gt;
 130           &lt;!-- Max value: 255 (inclusive) --&gt;
 131         &lt;!ATTLIST "ColorTableEntry" "blue" #CDATA #REQUIRED&gt;
 132           &lt;!-- The blue value for the color table entry --&gt;
 133           &lt;!-- Data type: Integer --&gt;
 134           &lt;!-- Min value: 0 (inclusive) --&gt;
 135           &lt;!-- Max value: 255 (inclusive) --&gt;
 136 ]&gt;
 137 </pre>
 138 <a name="gif_image_metadata_format"></a>
 139 <center><h2>
 140 GIF Image Metadata Format Specification
 141 </h2></center>
 142 <p>
 143 
 144 The GIF image metadata format encodes the image descriptor, local
 145 color table, and extension information assciated with a single image
 146 within a GIF file, typically a frame of an animation.
 147 
 148 <p>
 149 
 150 The image description contains the offset of the frame within the
 151 logical screen described in the stream metadata, as well as the width
 152 and height of the frame and whether it is used interlaced encoding.
 153 
 154 <p>
 155 
 156 The local color table, if present, supersedes the global color table
 157 for the frame at hand.
 158 
 159 <p>
 160 
 161 The graphic control extension contains information on how the frame is
 162 to be incorporated into the animation.  The disposal method indicates
 163 whether the current frame should remain in place
 164 (<code>doNotDispose</code>), be restored to the backgound color as
 165 specified in the stream metadata
 166 (<code>restoreToBackgroundColor</code>), or be restored to the
 167 previous frame contents (<code>restoreToPrevious</code>) prior to
 168 displaying the subsequent frame.
 169 
 170 <p>
 171 
 172 The user input flag indicates whether the animation should pause for
 173 user input before advancing to the next frame.  The transparent color
 174 flag and index indicate a color index for which pixels of the frame
 175 should not be drawn.  The delay time indicates how long the frame
 176 should be displayed, in hundredths of a second.  If the user input
 177 flag is set and the delay time is 0, the frame is intended to be
 178 advanced only on user input.
 179 
 180 <pre>
 181 &lt;!DOCTYPE "javax_imageio_gif_image_1.0" [
 182 
 183   &lt;!ELEMENT "javax_imageio_gif_image_1.0" (ImageDescriptor?, 
 184     LocalColorTable?, GraphicControlExtension?, PlainTextExtension?, 
 185     ApplicationExtensions?, CommentExtensions?)&gt;
 186 
 187     &lt;!ELEMENT "ImageDescriptor" EMPTY&gt;
 188       &lt;!-- The image descriptor --&gt;
 189       &lt;!ATTLIST "ImageDescriptor" "imageLeftPosition" #CDATA #REQUIRED&gt;
 190         &lt;!-- The X offset of the image relative to the screen origin --&gt;
 191         &lt;!-- Data type: Integer --&gt;
 192         &lt;!-- Min value: 0 (inclusive) --&gt;
 193         &lt;!-- Max value: 65535 (inclusive) --&gt;
 194       &lt;!ATTLIST "ImageDescriptor" "imageTopPosition" #CDATA #REQUIRED&gt;
 195         &lt;!-- The Y offset of the image relative to the screen origin --&gt;
 196         &lt;!-- Data type: Integer --&gt;
 197         &lt;!-- Min value: 0 (inclusive) --&gt;
 198         &lt;!-- Max value: 65535 (inclusive) --&gt;
 199       &lt;!ATTLIST "ImageDescriptor" "imageWidth" #CDATA #REQUIRED&gt;
 200         &lt;!-- The width of the image --&gt;
 201         &lt;!-- Data type: Integer --&gt;
 202         &lt;!-- Min value: 1 (inclusive) --&gt;
 203         &lt;!-- Max value: 65535 (inclusive) --&gt;
 204       &lt;!ATTLIST "ImageDescriptor" "imageHeight" #CDATA #REQUIRED&gt;
 205         &lt;!-- The height of the image --&gt;
 206         &lt;!-- Data type: Integer --&gt;
 207         &lt;!-- Min value: 1 (inclusive) --&gt;
 208         &lt;!-- Max value: 65535 (inclusive) --&gt;
 209       &lt;!ATTLIST "ImageDescriptor" "interlaceFlag" ("TRUE" | "FALSE")
 210          #REQUIRED&gt;
 211         &lt;!-- True if the image is stored using interlacing --&gt;
 212 
 213     &lt;!ELEMENT "LocalColorTable" (ColorTableEntry)*&gt;
 214       &lt;!-- The local color table --&gt;
 215       &lt;!-- Min children: 2 --&gt;
 216       &lt;!-- Max children: 256 --&gt;
 217       &lt;!ATTLIST "LocalColorTable" "sizeOfLocalColorTable" ("2" | 
 218         "4" | "8" | "16" | "32" | "64" | "128" | "256") #REQUIRED&gt;
 219         &lt;!-- The number of entries in the local color table --&gt;
 220       &lt;!ATTLIST "LocalColorTable" "sortFlag" ("TRUE" | "FALSE")
 221          #REQUIRED&gt;
 222         &lt;!-- True if the local color table is sorted by frequency --&gt;
 223 
 224       &lt;!ELEMENT "ColorTableEntry" EMPTY&gt;
 225         &lt;!-- A local color table entry --&gt;
 226         &lt;!ATTLIST "ColorTableEntry" "index" #CDATA #REQUIRED&gt;
 227           &lt;!-- The index of the color table entry --&gt;
 228           &lt;!-- Data type: Integer --&gt;
 229           &lt;!-- Min value: 0 (inclusive) --&gt;
 230           &lt;!-- Max value: 255 (inclusive) --&gt;
 231         &lt;!ATTLIST "ColorTableEntry" "red" #CDATA #REQUIRED&gt;
 232           &lt;!-- The red value for the color table entry --&gt;
 233           &lt;!-- Data type: Integer --&gt;
 234           &lt;!-- Min value: 0 (inclusive) --&gt;
 235           &lt;!-- Max value: 255 (inclusive) --&gt;
 236         &lt;!ATTLIST "ColorTableEntry" "green" #CDATA #REQUIRED&gt;
 237           &lt;!-- The green value for the color table entry --&gt;
 238           &lt;!-- Data type: Integer --&gt;
 239           &lt;!-- Min value: 0 (inclusive) --&gt;
 240           &lt;!-- Max value: 255 (inclusive) --&gt;
 241         &lt;!ATTLIST "ColorTableEntry" "blue" #CDATA #REQUIRED&gt;
 242           &lt;!-- The blue value for the color table entry --&gt;
 243           &lt;!-- Data type: Integer --&gt;
 244           &lt;!-- Min value: 0 (inclusive) --&gt;
 245           &lt;!-- Max value: 255 (inclusive) --&gt;
 246 
 247     &lt;!ELEMENT "GraphicControlExtension" EMPTY&gt;
 248       &lt;!-- A graphic control extension --&gt;
 249       &lt;!ATTLIST "GraphicControlExtension" "disposalMethod" ("none" | 
 250         "doNotDispose" | "restoreToBackgroundColor" | 
 251         "restoreToPrevious" | "undefinedDisposalMethod4" | 
 252         "undefinedDisposalMethod5" | "undefinedDisposalMethod6" | 
 253         "undefinedDisposalMethod7") #REQUIRED&gt;
 254         &lt;!-- The disposal method for this frame --&gt;
 255       &lt;!ATTLIST "GraphicControlExtension" "userInputFlag" ("TRUE" | 
 256         "FALSE") #REQUIRED&gt;
 257         &lt;!-- True if the frame should be advanced based on user input --&gt;
 258       &lt;!ATTLIST "GraphicControlExtension" "transparentColorFlag" (
 259         "TRUE" | "FALSE") #REQUIRED&gt;
 260         &lt;!-- True if a transparent color exists --&gt;
 261       &lt;!ATTLIST "GraphicControlExtension" "delayTime" #CDATA #REQUIRED&gt;
 262         &lt;!-- The time to delay between frames, in hundredths of a second --&gt;
 263         &lt;!-- Data type: Integer --&gt;
 264         &lt;!-- Min value: 0 (inclusive) --&gt;
 265         &lt;!-- Max value: 65535 (inclusive) --&gt;
 266       &lt;!ATTLIST "GraphicControlExtension" "transparentColorIndex"
 267          #CDATA #REQUIRED&gt;
 268         &lt;!-- The transparent color, if transparentColorFlag is true --&gt;
 269         &lt;!-- Data type: Integer --&gt;
 270         &lt;!-- Min value: 0 (inclusive) --&gt;
 271         &lt;!-- Max value: 255 (inclusive) --&gt;
 272 
 273     &lt;!ELEMENT "PlainTextExtension" EMPTY&gt;
 274       &lt;!-- A plain text (text grid) extension --&gt;
 275       &lt;!ATTLIST "PlainTextExtension" "textGridLeft" #CDATA #REQUIRED&gt;
 276         &lt;!-- The X offset of the text grid --&gt;
 277         &lt;!-- Data type: Integer --&gt;
 278         &lt;!-- Min value: 0 (inclusive) --&gt;
 279         &lt;!-- Max value: 65535 (inclusive) --&gt;
 280       &lt;!ATTLIST "PlainTextExtension" "textGridTop" #CDATA #REQUIRED&gt;
 281         &lt;!-- The Y offset of the text grid --&gt;
 282         &lt;!-- Data type: Integer --&gt;
 283         &lt;!-- Min value: 0 (inclusive) --&gt;
 284         &lt;!-- Max value: 65535 (inclusive) --&gt;
 285       &lt;!ATTLIST "PlainTextExtension" "textGridWidth" #CDATA #REQUIRED&gt;
 286         &lt;!-- The number of columns in the text grid --&gt;
 287         &lt;!-- Data type: Integer --&gt;
 288         &lt;!-- Min value: 1 (inclusive) --&gt;
 289         &lt;!-- Max value: 65535 (inclusive) --&gt;
 290       &lt;!ATTLIST "PlainTextExtension" "textGridHeight" #CDATA #REQUIRED&gt;
 291         &lt;!-- The number of rows in the text grid --&gt;
 292         &lt;!-- Data type: Integer --&gt;
 293         &lt;!-- Min value: 1 (inclusive) --&gt;
 294         &lt;!-- Max value: 65535 (inclusive) --&gt;
 295       &lt;!ATTLIST "PlainTextExtension" "characterCellWidth" #CDATA
 296          #REQUIRED&gt;
 297         &lt;!-- The width of a character cell --&gt;
 298         &lt;!-- Data type: Integer --&gt;
 299         &lt;!-- Min value: 1 (inclusive) --&gt;
 300         &lt;!-- Max value: 65535 (inclusive) --&gt;
 301       &lt;!ATTLIST "PlainTextExtension" "characterCellHeight" #CDATA
 302          #REQUIRED&gt;
 303         &lt;!-- The height of a character cell --&gt;
 304         &lt;!-- Data type: Integer --&gt;
 305         &lt;!-- Min value: 1 (inclusive) --&gt;
 306         &lt;!-- Max value: 65535 (inclusive) --&gt;
 307       &lt;!ATTLIST "PlainTextExtension" "textForegroundColor" #CDATA
 308          #REQUIRED&gt;
 309         &lt;!-- The text foreground color index --&gt;
 310         &lt;!-- Data type: Integer --&gt;
 311         &lt;!-- Min value: 0 (inclusive) --&gt;
 312         &lt;!-- Max value: 255 (inclusive) --&gt;
 313       &lt;!ATTLIST "PlainTextExtension" "textBackgroundColor" #CDATA
 314          #REQUIRED&gt;
 315         &lt;!-- The text background color index --&gt;
 316         &lt;!-- Data type: Integer --&gt;
 317         &lt;!-- Min value: 0 (inclusive) --&gt;
 318         &lt;!-- Max value: 255 (inclusive) --&gt;
 319 
 320     &lt;!ELEMENT "ApplicationExtensions" (ApplicationExtension)*&gt;
 321       &lt;!-- A set of application extensions --&gt;
 322       &lt;!-- Min children: 1 --&gt;
 323       &lt;!-- Max children: 2147483647 --&gt;
 324 
 325       &lt;!ELEMENT "ApplicationExtension" EMPTY&gt;
 326         &lt;!-- An application extension --&gt;
 327         &lt;!-- User object: array of byte --&gt;
 328         &lt;!-- Min length: 0 --&gt;
 329         &lt;!-- Max length: 2147483647 --&gt;
 330         &lt;!ATTLIST "ApplicationExtension" "applicationID" #CDATA
 331            #REQUIRED&gt;
 332           &lt;!-- The application ID --&gt;
 333           &lt;!-- Data type: String --&gt;
 334         &lt;!ATTLIST "ApplicationExtension" "authenticationCode" #CDATA
 335            #REQUIRED&gt;
 336           &lt;!-- The authentication code --&gt;
 337           &lt;!-- Data type: String --&gt;
 338 
 339     &lt;!ELEMENT "CommentExtensions" (CommentExtension)*&gt;
 340       &lt;!-- A set of comments --&gt;
 341       &lt;!-- Min children: 1 --&gt;
 342       &lt;!-- Max children: 2147483647 --&gt;
 343 
 344       &lt;!ELEMENT "CommentExtension" EMPTY&gt;
 345         &lt;!-- A comment --&gt;
 346         &lt;!ATTLIST "CommentExtension" "value" #CDATA #REQUIRED&gt;
 347           &lt;!-- The comment --&gt;
 348           &lt;!-- Data type: String --&gt;
 349 ]&gt;
 350 </pre>
 351 
 352 <p>
 353 <a name="mapping"></a>
 354 <center>
 355 <table border=1>
 356 <caption><b>Mapping of Standard to GIF Native Stream Metadata</b></caption>
 357 <tr>
 358 <th>Standard Metadata Component</th>
 359 <th>GIF Native Stream Metadata Component</th>
 360 </tr>
 361 <tr>
 362 <td>/Chroma/Palette/PaletteEntry@index</td>
 363 <td>/GlobalColorTable/ColorTableEntry@index</td>
 364 </tr>
 365 <tr>
 366 <td>/Chroma/Palette/PaletteEntry@red</td>
 367 <td>/GlobalColorTable/ColorTableEntry@red</td>
 368 </tr>
 369 <tr>
 370 <td>/Chroma/Palette/PaletteEntry@green</td>
 371 <td>/GlobalColorTable/ColorTableEntry@green</td>
 372 </tr>
 373 <tr>
 374 <td>/Chroma/Palette/PaletteEntry@blue</td>
 375 <td>/GlobalColorTable/ColorTableEntry@blue</td>
 376 </tr>
 377 <tr>
 378 <td>/Chroma/BackgroundIndex@value</td>
 379 <td>/GlobalColorTable@backgroundColorIndex</td>
 380 </tr>
 381 <tr>
 382 <td>/Data/BitsPerSample@value</td>
 383 <td>/LogicalScreenDescriptor@colorResolution</td>
 384 </tr>
 385 <tr>
 386 <td>/Dimension/PixelAspectRatio@value</td>
 387 <td>/LogicalScreenDescriptor@pixelAspectRatio</td>
 388 </tr>
 389 <tr>
 390 <td>/Dimension/HorizontalScreenSize@value</td>
 391 <td>/LogicalScreenDescriptor@logicalScreenWidth</td>
 392 </tr>
 393 <tr>
 394 <td>/Dimension/VerticalScreenSize@value</td>
 395 <td>/LogicalScreenDescriptor@logicalScreenHeight</td>
 396 </tr>
 397 <tr>
 398 <td>/Document/FormatVersion@value</td>
 399 <td>/Version@value</td>
 400 </tr>
 401 </table>
 402 </center>
 403 
 404 <center>
 405 <table border=1>
 406 <caption><b>Mapping of Standard to GIF Native Image Metadata</b></caption>
 407 <tr>
 408 <th>Standard Metadata Component</th>
 409 <th>GIF Native Image Metadata Component</th>
 410 </tr>
 411 <tr>
 412 <td>/Chroma/Palette/PaletteEntry@index</td>
 413 <td>/LocalColorTable/ColorTableEntry@index</td>
 414 </tr>
 415 <tr>
 416 <td>/Chroma/Palette/PaletteEntry@red</td>
 417 <td>/LocalColorTable/ColorTableEntry@red</td>
 418 </tr>
 419 <tr>
 420 <td>/Chroma/Palette/PaletteEntry@green</td>
 421 <td>/LocalColorTable/ColorTableEntry@green</td>
 422 </tr>
 423 <tr>
 424 <td>/Chroma/Palette/PaletteEntry@blue</td>
 425 <td>/LocalColorTable/ColorTableEntry@blue</td>
 426 </tr>
 427 <tr>
 428 <td>/Dimension/HorizontalPixelOffset@value</td>
 429 <td>/ImageDescriptor@imageLeftPosition</td>
 430 </tr>
 431 <tr>
 432 <td>/Dimension/VerticalPixelOffset@value</td>
 433 <td>/ImageDescriptor@imageTopPosition</td>
 434 </tr>
 435 <tr>
 436 <td>/Text/TextEntry@value</td>
 437 <td>/CommentExtensions/CommentExtension@value</td>
 438 </tr>
 439 <tr>
 440 <td>/Transparency/TransparentIndex@value</td>
 441 <td>/GraphicControlExtension@transparentColorIndex
 442 (/GraphicControlExtension@transparentColorFlag is also set to
 443 "TRUE")</td>
 444 </tr>
 445 </table>
 446 </center>
 447 
 448 </body>
 449 </html>
--- EOF ---