src/SDL2/external/libwebp-0.3.0/doc/webp-container-spec.txt

   1 <!--
   2
   3 Although you may be viewing an alternate representation, this document
   4 is sourced in Markdown, a light-duty markup scheme, and is optimized for
   5 the [kramdown](http://kramdown.rubyforge.org/) transformer.
   6
   7 See the accompanying README. External link targets are referenced at the
   8 end of this file.
   9
  10 -->
  11
  12
  13 WebP Container Specification
  14 ============================
  15
  16 * TOC placeholder
  17 {:toc}
  18
  19
  20 Introduction
  21 ------------
  22
  23 WebP is an image format that uses either (i) the VP8 key frame encoding
  24 to compress image data in a lossy way, or (ii) the WebP lossless encoding
  25 (and possibly other encodings in the future). These encoding schemes should
  26 make it more efficient than currently used formats. It is optimized for fast
  27 image transfer over the network (e.g., for websites). The WebP format has
  28 feature parity (color profile, metadata, animation etc) with other formats as
  29 well. This document describes the structure of a WebP file.
  30
  31 The WebP container (i.e., RIFF container for WebP) allows feature support over
  32 and above the basic use case of WebP (i.e., a file containing a single image
  33 encoded as a VP8 key frame). The WebP container provides additional support
  34 for:
  35
  36   * **Lossless compression.** An image can be losslessly compressed, using the
  37     WebP Lossless Format.
  38
  39   * **Metadata.** An image may have metadata stored in EXIF or XMP formats.
  40
  41   * **Transparency.** An image may have transparency, i.e., an alpha channel.
  42
  43   * **Color Profile.** An image may have an embedded ICC profile as described
  44     by the [International Color Consortium][iccspec].
  45
  46   * **Animation.** An image may have multiple frames with pauses between them,
  47     making it an animation.
  48
  49   * **Image Fragmentation.** A single bitstream in WebP has an inherent
  50     limitation for width or height of 2^14 pixels, and, when using VP8, a 512
  51     KiB limit on the size of the first compressed partition. To support larger
  52     images, the format supports images that are composed of multiple fragments,
  53     each encoded as a separate bitstream. All fragments logically form a single
  54     image: they have common metadata, color profile, etc. Image fragmentation
  55     may also improve efficiency for larger images, e.g., grass can be encoded
  56     differently than sky.
  57
  58 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
  59 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
  60 document are to be interpreted as described in [RFC 2119][].
  61
  62 **Note:** Out of the features mentioned above, lossy compression, lossless
  63 compression, transparency, metadata, color profile and animation are finalized
  64 and are to be considered stable. On the other hand, image fragmentation is
  65 experimental as of now, and is open to discussion, feedback and comments.
  66 The same is indicated using annotation "_status: experimental_" in the relevant
  67 sections of this document.
  68
  69 Terminology &amp; Basics
  70 ------------------------
  71
  72 A WebP file contains either a still image (i.e., an encoded matrix of pixels)
  73 or an [animation](#animation). Optionally, it can also contain transparency
  74 information, color profile and metadata. In case we need to refer only to the
  75 matrix of pixels, we will call it the _canvas_ of the image.
  76
  77 Below are additional terms used throughout this document:
  78
  79 _Reader/Writer_
  80
  81 : Code that reads WebP files is referred to as a _reader_, while code that
  82 writes them is referred to as a _writer_.
  83
  84 _uint16_
  85
  86 : A 16-bit, little-endian, unsigned integer.
  87
  88 _uint24_
  89
  90 : A 24-bit, little-endian, unsigned integer.
  91
  92 _uint32_
  93
  94 : A 32-bit, little-endian, unsigned integer.
  95
  96 _FourCC_
  97
  98 : A _FourCC_ (four-character code) is a _uint32_ created by concatenating four
  99   ASCII characters in little-endian order.
 100
 101 _1-based_
 102
 103 : An unsigned integer field storing values offset by `-1`. e.g., Such a field
 104 would store value _25_ as _24_.
 105
 106 RIFF file format
 107 ----------------
 108 The WebP file format is based on the RIFF (resource interchange file format)
 109 document format.
 110
 111 The basic element of a RIFF file is a _chunk_. It consists of:
 112
 113      0                   1                   2                   3
 114      0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
 115     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 116     |                         Chunk FourCC                          |
 117     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 118     |                          Chunk Size                           |
 119     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 120     |                         Chunk Payload                         |
 121     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 122
 123 Chunk FourCC: 32 bits
 124
 125 : ASCII four-character code used for chunk identification.
 126
 127 Chunk Size: 32 bits (_uint32_)
 128
 129 : The size of the chunk not including this field, the chunk identifier or
 130   padding.
 131
 132 Chunk Payload: _Chunk Size_ bytes
 133
 134 : The data payload. If _Chunk Size_ is odd, a single padding byte -- that
 135   SHOULD be `0` -- is added.
 136
 137 _ChunkHeader('ABCD')_
 138
 139 : This is used to describe the _FourCC_ and _Chunk Size_ header of individual
 140   chunks, where 'ABCD' is the FourCC for the chunk. This element's
 141   size is 8 bytes.
 142
 143 **Note:** RIFF has a convention that all-uppercase chunk FourCCs are standard
 144 chunks that apply to any RIFF file format, while FourCCs specific to a file
 145 format are all lowercase. WebP does not follow this convention.
 146
 147 WebP file header
 148 ----------------
 149
 150      0                   1                   2                   3
 151      0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
 152     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 153     |      'R'      |      'I'      |      'F'      |      'F'      |
 154     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 155     |                           File Size                           |
 156     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 157     |      'W'      |      'E'      |      'B'      |      'P'      |
 158     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 159
 160 'RIFF': 32 bits
 161
 162 : The ASCII characters 'R' 'I' 'F' 'F'.
 163
 164 File Size: 32 bits (_uint32_)
 165
 166 : The size of the file in bytes starting at offset 8. The maximum value of
 167 this field is 2^32 minus 10 bytes and thus the size of the whole file is at
 168 most 4GiB minus 2 bytes.
 169
 170 'WEBP': 32 bits
 171
 172 : The ASCII characters 'W' 'E' 'B' 'P'.
 173
 174 A WebP file MUST begin with a RIFF header with the FourCC 'WEBP'. The file size
 175 in the header is the total size of the chunks that follow plus `4` bytes for
 176 the 'WEBP' FourCC. The file SHOULD NOT contain anything after it. As the size
 177 of any chunk is even, the size given by the RIFF header is also even. The
 178 contents of individual chunks will be described in the following sections.
 179
 180 Simple file format (lossy)
 181 --------------------------
 182
 183 This layout SHOULD be used if the image requires _lossy_ encoding and does not
 184 require transparency or other advanced features provided by the extended format.
 185 Files with this layout are smaller and supported by older software.
 186
 187 Simple WebP (lossy) file format:
 188
 189      0                   1                   2                   3
 190      0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
 191     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 192     |                    WebP file header (12 bytes)                |
 193     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 194     |                          VP8 chunk                            |
 195     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 196
 197 VP8 chunk:
 198
 199      0                   1                   2                   3
 200      0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
 201     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 202     |                      ChunkHeader('VP8 ')                      |
 203     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 204     |                           VP8 data                            |
 205     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 206
 207 VP8 data: _Chunk Size_ bytes
 208
 209 : VP8 bitstream data.
 210
 211 The VP8 bitstream format specification can be found at [VP8 Data Format and
 212 Decoding Guide][vp8spec]. Note that the VP8 frame header contains the VP8 frame
 213 width and height. That is assumed to be the width and height of the canvas.
 214
 215 The VP8 specification describes how to decode the image into Y'CbCr
 216 format. To convert to RGB, Rec. 601 SHOULD be used.
 217
 218 Simple file format (lossless)
 219 -----------------------------
 220
 221 **Note:** Older readers may not support files using the lossless format.
 222
 223 This layout SHOULD be used if the image requires _lossless_ encoding (with an
 224 optional transparency channel) and does not require advanced features provided
 225 by the extended format.
 226
 227 Simple WebP (lossless) file format:
 228
 229      0                   1                   2                   3
 230      0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
 231     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 232     |                    WebP file header (12 bytes)                |
 233     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 234     |                          VP8L chunk                           |
 235     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 236
 237 VP8L chunk:
 238
 239      0                   1                   2                   3
 240      0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
 241     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 242     |                      ChunkHeader('VP8L')                      |
 243     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 244     |                           VP8L data                           |
 245     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 246
 247 VP8L data: _Chunk Size_ bytes
 248
 249 : VP8L bitstream data.
 250
 251 The current specification of the VP8L bitstream can be found at
 252 [WebP Lossless Bitstream Format][webpllspec]. Note that the VP8L header
 253 contains the VP8L image width and height. That is assumed to be the width
 254 and height of the canvas.
 255
 256 Extended file format
 257 --------------------
 258
 259 **Note:** Older readers may not support files using the extended format.
 260
 261 An extended format file consists of:
 262
 263   * A 'VP8X' chunk with information about features used in the file.
 264
 265   * An optional 'ICCP' chunk with color profile.
 266
 267   * An optional 'ANIM' chunk with animation control data.
 268
 269   * Image data.
 270
 271   * An optional 'EXIF' chunk with EXIF metadata.
 272
 273   * An optional 'XMP ' chunk with XMP metadata.
 274
 275   * An optional list of [unknown chunks](#unknown-chunks). _\[status: experimental\]_
 276
 277 For a _still image_, the _image data_ consists of a single frame, whereas for
 278 an _animated image_, it consists of multiple frames. More details about frames
 279 can be found in the [Animation](#animation) section.
 280
 281 Moreover, each frame can be fragmented or non-fragmented, as will be described
 282 in the [Extended WebP file header](#extended_header) section. More details about
 283 fragments can be found in the [Fragments](#fragments) section.
 284
 285 All chunks SHOULD be placed in the same order as listed above. If a chunk
 286 appears in the wrong place, the file is invalid, but readers MAY parse the
 287 file, ignoring the chunks that come too late.
 288
 289 **Rationale:** Setting the order of chunks should allow quicker file
 290 parsing. For example, if an 'ALPH' chunk does not appear in its required
 291 position, a decoder can choose to stop searching for it. The rule of
 292 ignoring late chunks should make programs that need to do a full search
 293 give the same results as the ones stopping early.
 294
 295 Extended WebP file header:
 296 {:#extended_header}
 297
 298      0                   1                   2                   3
 299      0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
 300     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 301     |                   WebP file header (12 bytes)                 |
 302     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 303     |                      ChunkHeader('VP8X')                      |
 304     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 305     |Rsv|I|L|E|X|A|F|                   Reserved                    |
 306     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 307     |          Canvas Width Minus One               |             ...
 308     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 309     ...  Canvas Height Minus One    |
 310     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 311
 312 Reserved (Rsv): 2 bits
 313
 314 : SHOULD be `0`.
 315
 316 ICC profile (I): 1 bit
 317
 318 : Set if the file contains an ICC profile.
 319
 320 Alpha (L): 1 bit
 321
 322 : Set if any of the frames of the image contain transparency information
 323 ("alpha").
 324
 325 EXIF metadata (E): 1 bit
 326
 327 : Set if the file contains EXIF metadata.
 328
 329 XMP metadata (X): 1 bit
 330
 331 : Set if the file contains XMP metadata.
 332
 333 Animation (A): 1 bit
 334
 335 : Set if this is an animated image. Data in 'ANIM' and 'ANMF' chunks should be
 336 used to control the animation.
 337
 338 Image Fragmentation (F): 1 bit _\[status: experimental\]_
 339
 340 : Set if any of the frames in the image are represented by fragments.
 341
 342 Reserved: 24 bits
 343
 344 : SHOULD be `0`.
 345
 346 Canvas Width Minus One: 24 bits
 347
 348 : _1-based_ width of the canvas in pixels.
 349   The actual canvas width is '1 + Canvas Width Minus One'
 350
 351 Canvas Height Minus One: 24 bits
 352
 353 : _1-based_ height of the canvas in pixels.
 354   The actual canvas height is '1 + Canvas Height Minus One'
 355
 356 The product of _Canvas Width_ and _Canvas Height_ MUST be at most `2^32 - 1`.
 357
 358 Future specifications MAY add more fields.
 359
 360 ### Chunks
 361
 362 #### Animation
 363
 364 An animation is controlled by ANIM and ANMF chunks.
 365
 366 ANIM Chunk:
 367 {:#anim_chunk}
 368
 369 For an animated image, this chunk contains the _global parameters_ of the
 370 animation.
 371
 372      0                   1                   2                   3
 373      0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
 374     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 375     |                      ChunkHeader('ANIM')                      |
 376     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 377     |                       Background Color                        |
 378     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 379     |          Loop Count           |
 380     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 381
 382 Background Color: 32 bits (_uint32_)
 383
 384 : The default background color of the canvas in \[Blue, Green, Red, Alpha\]
 385 byte order. This color is used to fill the unused space on the canvas around the
 386 frames, as well as the transparent pixels of the first frame. Background color
 387 is also used when disposal method is `1`.
 388
 389 **Note**: Viewers that have a preferred background against which to present the
 390 images (web browsers, for example) should ignore this value and use their
 391 preferred background color instead.
 392
 393 Loop Count: 16 bits (_uint16_)
 394
 395 : The number of times to loop the animation. `0` means infinitely.
 396
 397 This chunk MUST appear if the _Animation_ flag in the VP8X chunk is set.
 398 If the _Animation_ flag is not set and this chunk is present, it
 399 SHOULD be ignored.
 400
 401
 402 ANMF chunk:
 403
 404 For animated images, this chunk contains information about a _single_ frame.
 405 If the _Animation flag_ is not set, then this chunk SHOULD NOT be present.
 406
 407      0                   1                   2                   3
 408      0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
 409     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 410     |                      ChunkHeader('ANMF')                      |
 411     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 412     |                        Frame X                |             ...
 413     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 414     ...          Frame Y            |   Frame Width Minus One     ...
 415     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 416     ...             |           Frame Height Minus One              |
 417     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 418     |                 Frame Duration                |  Reserved   |D|
 419     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 420     |                         Frame Data                            |
 421     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 422
 423 Frame X: 24 bits (_uint24_)
 424
 425 : The X coordinate of the upper left corner of the frame is `Frame X * 2`
 426
 427 Frame Y: 24 bits (_uint24_)
 428
 429 : The Y coordinate of the upper left corner of the frame is `Frame Y * 2`
 430
 431 Frame Width Minus One: 24 bits (_uint24_)
 432
 433 : The _1-based_ width of the frame.
 434   The frame width is `1 + Frame Width Minus One`
 435
 436 Frame Height Minus One: 24 bits (_uint24_)
 437
 438 : The _1-based_ height of the frame.
 439   The frame height is `1 + Frame Height Minus One`
 440
 441 Frame Duration: 24 bits (_uint24_)
 442
 443 : The time to wait before displaying the next frame, in 1 millisecond units.
 444 In particular, frame duration of 0 is useful when one wants to update multiple
 445 areas of the canvas at once during the animation.
 446
 447 Reserved: 7 bits
 448
 449 : SHOULD be 0.
 450
 451 Disposal method (D): 1 bit
 452
 453 : Indicates how _the current frame_ is to be treated after it has been displayed
 454 (before rendering the next frame) on the canvas:
 455
 456   * `0`: Do not dispose. Leave the canvas as is.
 457
 458   * `1`: Dispose to background color. Fill the _rectangle_ on the canvas covered
 459     by the _current frame_ with background color specified in the
 460     [ANIM chunk](#anim_chunk).
 461
 462 After disposing the current frame, render the next frame on the canvas using
 463 [alpha-blending](#alpha-blending). If the next frame does not have an alpha
 464 channel, assume alpha value of 255, effectively replacing the rectangle.
 465
 466 **Notes**:
 467
 468   * The frame disposal only applies to the _frame rectangle_, that is, the
 469     rectangle defined by _Frame X_, _Frame Y_, _frame width_ and _frame height_.
 470     It may or may not cover the whole canvas.
 471
 472 {:#alpha-blending}
 473   * **Alpha-blending**:
 474
 475     Given that each of the R, G, B and A channels is 8-bit, and the RGB
 476     channels are _not premultiplied_ by alpha, the formula for blending
 477     'dst' onto 'src' is:
 478
 479 ~~~~~
 480     blend.A = src.A + dst.A * (1 - src.A / 255)
 481     if blend.A = 0 then
 482       blend.RGB = 0
 483     else
 484       blend.RGB = (src.RGB * src.A +
 485                    dst.RGB * dst.A * (1 - src.A / 255)) / blend.A
 486 ~~~~~
 487
 488   * Alpha-blending SHOULD be done in linear color space, by taking into account
 489     the [color profile](#color-profile) of the image. If the color profile is
 490     not present, sRGB is to be assumed. (Note that sRGB also needs to be
 491     linearized due to a gamma of ~2.2).
 492
 493 Frame Data: _Chunk Size_ - `16` bytes
 494
 495 : For a fragmented frame, it consists of multiple [fragment chunks](#fragments).
 496
 497 : For a non-fragmented frame, it consists of:
 498
 499   * An optional [alpha subchunk](#alpha) for the frame.
 500
 501   * A [bitstream subchunk](#bitstream-vp8vp8l) for the frame.
 502
 503   * An optional list of [unknown chunks](#unknown-chunks).
 504
 505 **Note**: The 'ANMF' payload, _Frame Data_ above, consists of individual
 506 _padded_ chunks as described by the [RIFF file format](#riff-file-format).
 507
 508 #### Fragments _\[status: experimental\]_
 509
 510 For images that are represented by fragments, this chunk contains data for
 511 a single fragment. If the _Image Fragmentation Flag_ is not set, then this chunk
 512 SHOULD NOT be present.
 513
 514      0                   1                   2                   3
 515      0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
 516     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 517     |                      ChunkHeader('FRGM')                      |
 518     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 519     |                  Fragment X                   |             ...
 520     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 521     ...       Fragment Y            |         Fragment Data         |
 522     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 523
 524 Fragment X: 24 bits (_uint24_)
 525
 526 : The X coordinate of the upper left corner of the fragment is `Fragment X * 2`
 527
 528 Fragment Y: 24 bits (_uint24_)
 529
 530 : The Y coordinate of the upper left corner of the fragment is `Fragment Y * 2`
 531
 532 Fragment Data: _Chunk Size_ - `6` bytes
 533
 534 : It contains:
 535
 536   * An optional [alpha subchunk](#alpha) for the fragment.
 537   * The [bitstream subchunk](#bitstream-vp8vp8l) for the fragment.
 538   * An optional list of [unknown chunks](#unknown-chunks).
 539
 540 Note: The width and height of the fragment is obtained from the bitstream
 541 subchunk.
 542
 543 The fragments of a frame SHOULD have the following properties:
 544
 545   * They collectively cover the whole frame.
 546
 547   * No pair of fragments have any overlapping region on the frame.
 548
 549   * No portion of any fragment should be located outside of the canvas.
 550
 551 #### Alpha
 552
 553      0                   1                   2                   3
 554      0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
 555     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 556     |                      ChunkHeader('ALPH')                      |
 557     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 558     |Rsv| P | F | C |     Alpha Bitstream...                        |
 559     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 560
 561 Reserved (Rsv): 2 bits
 562
 563 : SHOULD be `0`.
 564
 565 Pre-processing (P): 2 bits
 566
 567 : These INFORMATIVE bits are used to signal the pre-processing that has
 568 been performed during compression. The decoder can use this information to
 569 e.g. dither the values or smooth the gradients prior to display.
 570
 571   * `0`: no pre-processing
 572   * `1`: level reduction
 573
 574 Filtering method (F): 2 bits
 575
 576 : The filtering method used:
 577
 578   * `0`: None.
 579   * `1`: Horizontal filter.
 580   * `2`: Vertical filter.
 581   * `3`: Gradient filter.
 582
 583 For each pixel, filtering is performed using the following calculations.
 584 Assume the alpha values surrounding the current `X` position are labeled as:
 585
 586      C | B |
 587     ---+---+
 588      A | X |
 589
 590 We seek to compute the alpha value at position `X`. First, a prediction is
 591 made depending on the filtering method:
 592
 593   * Method `0`: predictor = 0
 594   * Method `1`: predictor = A
 595   * Method `2`: predictor = B
 596   * Method `3`: predictor = clip(A + B - C)
 597
 598 where `clip(v)` is equal to:
 599
 600   * 0    if v < 0
 601   * 255  if v > 255
 602   * v    otherwise
 603
 604 The final value is derived by adding the decompressed value `X` to the
 605 predictor and using modulo-256 arithmetic to wrap the \[256-511\] range
 606 into the \[0-255\] one:
 607
 608 `alpha = (predictor + X) % 256`
 609
 610 There are special cases for left-most and top-most pixel positions:
 611
 612   * Top-left value at location (0,0) uses 0 as predictor value. Otherwise,
 613   * For horizontal or gradient filtering methods, the left-most pixels at
 614     location (0, y) are predicted using the location (0, y-1) just above.
 615   * For vertical or gradient filtering methods, the top-most pixels at
 616     location (x, 0) are predicted using the location (x-1, 0) on the left.
 617
 618
 619 Decoders are not required to use this information in any specified way.
 620
 621 Compression method (C): 2 bits
 622
 623 : The compression method used:
 624
 625   * `0`: No compression.
 626   * `1`: Compressed using the WebP lossless format.
 627
 628 Alpha bitstream: _Chunk Size_ - `1` bytes
 629
 630 : Encoded alpha bitstream.
 631
 632 This optional chunk contains encoded alpha data for this frame/fragment. A
 633 frame/fragment containing a 'VP8L' chunk SHOULD NOT contain this chunk.
 634
 635 **Rationale**: The transparency information is already part of the 'VP8L'
 636 chunk.
 637
 638 The alpha channel data is stored as uncompressed raw data (when
 639 compression method is '0') or compressed using the lossless format
 640 (when the compression method is '1').
 641
 642   * Raw data: consists of a byte sequence of length width * height,
 643     containing all the 8-bit transparency values in scan order.
 644
 645   * Lossless format compression: the byte sequence is a compressed
 646     image-stream (as described in the [WebP Lossless Bitstream Format]
 647     [webpllspec]) of implicit dimension width x height. That is, this
 648     image-stream does NOT contain any headers describing the image dimension.
 649
 650     **Rationale**: the dimension is already known from other sources,
 651     so storing it again would be redundant and error-prone.
 652
 653     Once the image-stream is decoded into ARGB color values, following
 654     the process described in the lossless format specification, the
 655     transparency information must be extracted from the *green* channel
 656     of the ARGB quadruplet.
 657
 658     **Rationale**: the green channel is allowed extra transformation
 659     steps in the specification -- unlike the other channels -- that can
 660     improve compression.
 661
 662 #### Bitstream (VP8/VP8L)
 663
 664 This chunk contains compressed bitstream data for a single frame/fragment.
 665
 666 A bitstream chunk may be either (i) a VP8 chunk, using "VP8 " (note the
 667 significant fourth-character space) as its tag _or_ (ii) a VP8L chunk, using
 668 "VP8L" as its tag.
 669
 670 The formats of VP8 and VP8L chunks are as described in sections
 671 [Simple file format (lossy)](#simple-file-format-lossy)
 672 and [Simple file format (lossless)](#simple-file-format-lossless) respectively.
 673
 674 #### Color profile
 675
 676      0                   1                   2                   3
 677      0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
 678     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 679     |                      ChunkHeader('ICCP')                      |
 680     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 681     |                       Color Profile                           |
 682     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 683
 684 Color Profile: _Chunk Size_ bytes
 685
 686 : ICC profile.
 687
 688 This chunk MUST appear before the image data.
 689
 690 There SHOULD be at most one such chunk. If there are more such chunks, readers
 691 MAY ignore all except the first one.
 692 See the [ICC Specification][iccspec] for details.
 693
 694 If this chunk is not present, sRGB SHOULD be assumed.
 695
 696 #### Metadata
 697
 698 Metadata can be stored in 'EXIF' or 'XMP ' chunks.
 699
 700 There SHOULD be at most one chunk of each type ('EXIF' and 'XMP '). If there
 701 are more such chunks, readers MAY ignore all except the first one. Also, a file
 702 may possibly contain both 'EXIF' and 'XMP ' chunks.
 703
 704 The chunks are defined as follows:
 705
 706 EXIF chunk:
 707
 708      0                   1                   2                   3
 709      0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
 710     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 711     |                      ChunkHeader('EXIF')                      |
 712     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 713     |                        EXIF Metadata                          |
 714     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 715
 716 EXIF Metadata: _Chunk Size_ bytes
 717
 718 : image metadata in EXIF format.
 719
 720
 721 XMP chunk:
 722
 723      0                   1                   2                   3
 724      0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
 725     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 726     |                      ChunkHeader('XMP ')                      |
 727     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 728     |                        XMP Metadata                           |
 729     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 730
 731 XMP Metadata: _Chunk Size_ bytes
 732
 733 : image metadata in XMP format.
 734
 735 Additional guidance about handling metadata can be found in the
 736 Metadata Working Group's [Guidelines for Handling Metadata][metadata].
 737
 738 #### Unknown Chunks _\[status: experimental\]_
 739
 740 A RIFF chunk (described in [this](#terminology-amp-basics) section) whose _chunk
 741 tag_ is different from any of the chunks described in this document, is
 742 considered an _unknown chunk_.
 743
 744 **Rationale**: Allowing unknown chunks gives a provision for future extension
 745 of the format, and also allows storage of any application-specific data.
 746
 747 A file MAY contain unknown chunks:
 748
 749   * At the end of the file as described in [Extended WebP file
 750     header](#extended_header) section.
 751   * At the end of FRGM and ANMF chunks as described in [Fragments](#fragments)
 752     and [Animation](#animation) sections.
 753
 754 Readers SHOULD ignore these chunks. Writers SHOULD preserve them in their
 755 original order (unless they specifically intend to modify these chunks).
 756
 757 ### Assembling the Canvas from fragments/frames
 758
 759 Here we provide an overview of how a reader should assemble a canvas in case
 760 of a fragmented-image and in case of an animated image. The notation
 761 _VP8X.field_ means the field in the 'VP8X' chunk with the same description.
 762
 763 Displaying a _fragmented image_ canvas MUST be equivalent to the following
 764 pseudocode: _\[status: experimental\]_
 765
 766 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 767 assert VP8X.flags.hasFragments
 768 canvas ← new black image of size VP8X.canvasWidth x VP8X.canvasHeight.
 769 frgm_params ← nil
 770 for chunk in image_data:
 771     assert chunk.tag is "FRGM"
 772     frgm_params.fragmentX = Fragment X
 773     frgm_params.fragmentY = Fragment Y
 774     for subchunk in 'Fragment Data':
 775         if subchunk.tag == "ALPH":
 776             assert alpha subchunks not found in 'Fragment Data' earlier
 777             frgm_params.alpha = alpha_data
 778         else if subchunk.tag == "VP8 " OR subchunk.tag == "VP8L":
 779             assert bitstream subchunks not found in 'Fragment Data' earlier
 780             frgm_params.bitstream = bitstream_data
 781     frgm_params.fragmentWidth = Width extracted from bitstream subchunk
 782     frgm_params.fragmentHeight = Height extracted from bitstream subchunk
 783     assert VP8X.canvasWidth >=
 784         frgm_params.fragmentX + frgm_params.fragmentWidth
 785     assert VP8X.canvasHeight >=
 786         frgm_params.fragmentY + frgm_params.fragmentHeight
 787     assert fragment has the properties mentioned in "Image Fragments" section.
 788     render fragment with frame_params.alpha and frame_params.bitstream on canvas
 789     with top-left corner in (frgm_params.fragmentX, frgm_params.fragmentY).
 790 canvas contains the decoded canvas.
 791 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 792
 793 Displaying an _animated image_ canvas MUST be equivalent to the following
 794 pseudocode:
 795
 796 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 797 assert VP8X.flags.hasAnimation
 798 canvas ← new image of size VP8X.canvasWidth x VP8X.canvasHeight with
 799 background color ANIM.background_color.
 800 loop_count ← ANIM.loopCount
 801 dispose_method ← ANIM.disposeMethod
 802 if loop_count == 0:
 803     loop_count = ∞
 804 frame_params ← nil
 805 for loop = 0, ..., loop_count - 1
 806     assert next chunk in image_data is ANMF
 807     frame_params.frameX = Frame X
 808     frame_params.frameY = Frame Y
 809     frame_params.frameWidth = Frame Width Minus One + 1
 810     frame_params.frameHeight = Frame Height Minus One + 1
 811     frame_params.frameDuration = Frame Duration
 812     assert VP8X.canvasWidth >= frame_params.frameX + frame_params.frameWidth
 813     assert VP8X.canvasHeight >= frame_params.frameY + frame_params.frameHeight
 814     if VP8X.flags.hasFragments and first subchunk in 'Frame Data' is FRGM
 815         // Fragmented frame.
 816         frame_params.{bitstream,alpha} = canvas decoded from subchunks in
 817                                          'Frame Data' as per the pseudocode for
 818                                          _fragmented image_ above.
 819     else
 820         // Non-fragmented frame.
 821         for subchunk in 'Frame Data':
 822             if subchunk.tag == "ALPH":
 823                 assert alpha subchunks not found in 'Frame Data' earlier
 824                 frame_params.alpha = alpha_data
 825             else if subchunk.tag == "VP8 " OR subchunk.tag == "VP8L":
 826                 assert bitstream subchunks not found in 'Frame Data' earlier
 827                 frame_params.bitstream = bitstream_data
 828     render frame with frame_params.alpha and frame_params.bitstream on canvas
 829     with top-left corner in (frame_params.frameX, frame_params.frameY), using
 830     dispose method dispose_method.
 831     Show the contents of the image for frame_params.frameDuration * 1ms.
 832 canvas contains the decoded canvas.
 833 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 834
 835 Example file layouts
 836 --------------------
 837
 838 A lossy encoded image with alpha may look as follows:
 839
 840 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 841 RIFF/WEBP
 842 +- VP8X (descriptions of features used)
 843 +- ALPH (alpha bitstream)
 844 +- VP8 (bitstream)
 845 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 846
 847 A losslessly encoded image may look as follows:
 848
 849 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 850 RIFF/WEBP
 851 +- VP8X (descriptions of features used)
 852 +- XYZW (unknown chunk)
 853 +- VP8L (lossless bitstream)
 854 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 855
 856 A lossless image with ICC profile and XMP metadata may
 857 look as follows:
 858
 859 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 860 RIFF/WEBP
 861 +- VP8X (descriptions of features used)
 862 +- ICCP (color profile)
 863 +- VP8L (lossless bitstream)
 864 +- XMP  (metadata)
 865 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 866
 867 A fragmented image may look as follows:
 868
 869 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 870 RIFF/WEBP
 871 +- VP8X (descriptions of features used)
 872 +- FRGM (fragment1 parameters + data)
 873 +- FRGM (fragment2 parameters + data)
 874 +- FRGM (fragment3 parameters + data)
 875 +- FRGM (fragment4 parameters + data)
 876 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 877
 878 An animated image with EXIF metadata may look as follows:
 879
 880 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 881 RIFF/WEBP
 882 +- VP8X (descriptions of features used)
 883 +- ANIM (global animation parameters)
 884 +- ANMF (frame1 parameters + data)
 885 +- ANMF (frame2 parameters + data)
 886 +- ANMF (frame3 parameters + data)
 887 +- ANMF (frame4 parameters + data)
 888 +- EXIF (metadata)
 889 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 890
 891 [vp8spec]:  http://tools.ietf.org/html/rfc6386
 892 [webpllspec]: https://gerrit.chromium.org/gerrit/gitweb?p=webm/libwebp.git;a=blob;f=doc/webp-lossless-bitstream-spec.txt;hb=master
 893 [iccspec]: http://www.color.org/icc_specs2.xalter
 894 [metadata]: http://www.metadataworkinggroup.org/pdf/mwg_guidance.pdf
 895 [rfc 2119]: http://tools.ietf.org/html/rfc2119