diff --git a/doc/webp-container-spec.txt b/doc/webp-container-spec.txt index 3e665266..a43a8cf0 100644 --- a/doc/webp-container-spec.txt +++ b/doc/webp-container-spec.txt @@ -21,7 +21,7 @@ Introduction ------------ WebP is an image format that uses either (i) the VP8 key frame encoding to -compress image data in a lossy way, or (ii) the WebP lossless encoding. These +compress image data in a lossy way or (ii) the WebP lossless encoding. These encoding schemes should make it more efficient than older formats such as JPEG, GIF and PNG. It is optimized for fast image transfer over the network (for example, for websites). The WebP format has feature parity (color profile, @@ -31,19 +31,20 @@ the structure of a WebP file. The WebP container (that is, the RIFF container for WebP) allows feature support over and above the basic use case of WebP (that is, a file containing a single image encoded as a VP8 key frame). The WebP container provides additional -support for: +support for the following: - * **Lossless compression.** An image can be losslessly compressed, using the + * Lossless Compression: An image can be losslessly compressed, using the WebP Lossless Format. - * **Metadata.** An image may have metadata stored in Exif or XMP formats. + * Metadata: An image may have metadata stored in Exchangeable Image File + Format (Exif) or Extensible Metadata Platform (XMP) format. - * **Transparency.** An image may have transparency, that is, an alpha channel. + * Transparency: An image may have transparency, that is, an alpha channel. - * **Color Profile.** An image may have an embedded ICC profile as described + * Color Profile: An image may have an embedded ICC profile as described by the [International Color Consortium][iccspec]. - * **Animation.** An image may have multiple frames with pauses between them, + * Animation: An image may have multiple frames with pauses between them, making it an animation. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", @@ -52,15 +53,15 @@ document are to be interpreted as described in BCP 14 [RFC 2119][] [RFC 8174][] when, and only when, they appear in all capitals, as shown here. Bit numbering in chunk diagrams starts at `0` for the most significant bit -('MSB 0') as described in [RFC 1166][]. +('MSB 0'), as described in [RFC 1166][]. Terminology & Basics -------------------- A WebP file contains either a still image (that is, an encoded matrix of pixels) or an [animation](#animation). Optionally, it can also contain transparency -information, color profile and metadata. We refer to the matrix of pixels as the -_canvas_ of the image. +information, a color profile and metadata. We refer to the matrix of pixels as +the _canvas_ of the image. Below are additional terms used throughout this document: @@ -83,7 +84,7 @@ _uint32_ _FourCC_ -: A _FourCC_ (four-character code) is a _uint32_ created by concatenating four +: A four-character code (FourCC) is a _uint32_ created by concatenating four ASCII characters in little-endian order. This means 'aaaa' (0x61616161) and 'AAAA' (0x41414141) are treated as different _FourCCs_. @@ -94,9 +95,8 @@ _1-based_ _ChunkHeader('ABCD')_ -: This is used to describe the _FourCC_ and _Chunk Size_ header of individual - chunks, where 'ABCD' is the FourCC for the chunk. This element's size is 8 - bytes. +: Used to describe the _FourCC_ and _Chunk Size_ header of individual chunks, + where 'ABCD' is the FourCC for the chunk. This element's size is 8 bytes. RIFF File Format @@ -124,11 +124,11 @@ Chunk FourCC: 32 bits Chunk Size: 32 bits (_uint32_) : The size of the chunk in bytes, not including this field, the chunk - identifier or padding. + identifier, or padding. Chunk Payload: _Chunk Size_ bytes -: The data payload. If _Chunk Size_ is odd, a single padding byte -- that MUST +: The data payload. If _Chunk Size_ is odd, a single padding byte -- which MUST be `0` to conform with RIFF -- is added. **Note:** RIFF has a convention that all-uppercase chunk FourCCs are standard @@ -151,17 +151,17 @@ WebP File Header 'RIFF': 32 bits -: The ASCII characters 'R' 'I' 'F' 'F'. +: The ASCII characters 'R', 'I', 'F', 'F'. File Size: 32 bits (_uint32_) -: The size of the file in bytes starting at offset 8. The maximum value of +: The size of the file in bytes, starting at offset 8. The maximum value of this field is 2^32 minus 10 bytes and thus the size of the whole file is at - most 4GiB minus 2 bytes. + most 4 GiB minus 2 bytes. 'WEBP': 32 bits -: The ASCII characters 'W' 'E' 'B' 'P'. +: The ASCII characters 'W', 'E', 'B', 'P'. A WebP file MUST begin with a RIFF header with the FourCC 'WEBP'. The file size in the header is the total size of the chunks that follow plus `4` bytes for @@ -206,15 +206,15 @@ VP8 data: _Chunk Size_ bytes : VP8 bitstream data. -Note the fourth character in the 'VP8 ' FourCC is an ASCII space (0x20). +Note that the fourth character in the 'VP8 ' FourCC is an ASCII space (0x20). -The VP8 bitstream format specification can be found at [VP8 Data Format and -Decoding Guide][vp8spec]. Note that the VP8 frame header contains the VP8 frame +The VP8 bitstream format specification is described in [VP8 Data Format and +Decoding Guide][rfc 6386]. Note that the VP8 frame header contains the VP8 frame width and height. That is assumed to be the width and height of the canvas. The VP8 specification describes how to decode the image into Y'CbCr format. To -convert to RGB, Rec. 601 SHOULD be used. Applications MAY use another -conversion method, but visual results may differ among decoders. +convert to RGB, [Recommendation BT.601][rec601] SHOULD be used. Applications MAY +use another conversion method, but visual results may differ among decoders. Simple File Format (Lossless) @@ -326,7 +326,7 @@ Reserved (Rsv): 2 bits ICC profile (I): 1 bit -: Set if the file contains an ICC profile. +: Set if the file contains an 'ICCP' Chunk. Alpha (L): 1 bit @@ -396,14 +396,14 @@ Background Color: 32 bits (_uint32_) : The default background color of the canvas in \[Blue, Green, Red, Alpha\] byte order. This color MAY be used to fill the unused space on the canvas around the frames, as well as the transparent pixels of the first frame. - Background color is also used when disposal method is `1`. + The background color is also used when the Disposal method is `1`. **Note**: - * Background color MAY contain a non-opaque alpha value, even if the _Alpha_ - flag in [VP8X chunk](#extended_header) is unset. + * The background color MAY contain a non-opaque alpha value, even if the + _Alpha_ flag in the ['VP8X' Chunk](#extended_header) is unset. - * Viewer applications SHOULD treat the background color value as a hint, and + * Viewer applications SHOULD treat the background color value as a hint and are not required to use it. * The canvas is cleared at the start of each loop. The background color MAY be @@ -411,7 +411,8 @@ Background Color: 32 bits (_uint32_) Loop Count: 16 bits (_uint16_) -: The number of times to loop the animation. `0` means infinitely. +: The number of times to loop the animation. If it is `0`, this means + infinitely. This chunk MUST appear if the _Animation_ flag in the VP8X chunk is set. If the _Animation_ flag is not set and this chunk is present, it MUST be @@ -459,10 +460,10 @@ Frame Height Minus One: 24 bits (_uint24_) Frame Duration: 24 bits (_uint24_) -: The time to wait before displaying the next frame, in 1 millisecond units. - Note the interpretation of frame duration of 0 (and often <= 10) is - implementation defined. Many tools and browsers assign a minimum duration - similar to GIF. +: The time to wait before displaying the next frame, in 1-millisecond units. + Note that the interpretation of the Frame Duration of 0 (and often <= 10) is + defined by the implementation. Many tools and browsers assign a minimum + duration similar to GIF. Reserved: 6 bits @@ -473,10 +474,10 @@ Blending method (B): 1 bit : Indicates how transparent pixels of _the current frame_ are to be blended with corresponding pixels of the previous canvas: - * `0`: Use alpha blending. After disposing of the previous frame, render the + * `0`: Use alpha-blending. After disposing of the previous frame, render the current frame on the canvas using [alpha-blending](#alpha-blending). If - the current frame does not have an alpha channel, assume alpha value of - 255, effectively replacing the rectangle. + the current frame does not have an alpha channel, assume the alpha value + is 255, effectively replacing the rectangle. * `1`: Do not blend. After disposing of the previous frame, render the current frame on the canvas by overwriting the rectangle covered by the @@ -489,20 +490,20 @@ Disposal method (D): 1 bit * `0`: Do not dispose. Leave the canvas as is. - * `1`: Dispose to background color. Fill the _rectangle_ on the canvas - covered by the _current frame_ with background color specified in the - [ANIM chunk](#anim_chunk). + * `1`: Dispose to the background color. Fill the _rectangle_ on the canvas + covered by the _current frame_ with the background color specified in the + ['ANIM' Chunk](#anim_chunk). **Notes**: * The frame disposal only applies to the _frame rectangle_, that is, the - rectangle defined by _Frame X_, _Frame Y_, _frame width_ and _frame height_. - It may or may not cover the whole canvas. + rectangle defined by _Frame X_, _Frame Y_, _frame width_, and _frame + height_. It may or may not cover the whole canvas. {:#alpha-blending} - * **Alpha-blending**: + * Alpha-blending: - Given that each of the R, G, B and A channels is 8-bit, and the RGB + Given that each of the R, G, B, and A channels is 8 bits, and the RGB channels are _not premultiplied_ by alpha, the formula for blending 'dst' onto 'src' is: @@ -518,8 +519,8 @@ Disposal method (D): 1 bit * Alpha-blending SHOULD be done in linear color space, by taking into account the [color profile](#color-profile) of the image. If the color profile is - not present, sRGB is to be assumed. (Note that sRGB also needs to be - linearized due to a gamma of ~2.2). + not present, standard RGB (sRGB) is to be assumed. (Note that sRGB also + needs to be linearized due to a gamma of ~2.2.) Frame Data: _Chunk Size_ - `16` bytes @@ -532,7 +533,7 @@ Frame Data: _Chunk Size_ - `16` bytes * An optional list of [unknown chunks](#unknown-chunks). **Note**: The 'ANMF' payload, _Frame Data_ above, consists of individual -_padded_ chunks as described by the [RIFF file format](#riff-file-format). +_padded_ chunks, as described by the [RIFF file format](#riff-file-format). #### Alpha @@ -549,18 +550,18 @@ Reserved (Rsv): 2 bits : MUST be `0`. Readers MUST ignore this field. -Pre-processing (P): 2 bits +Preprocessing (P): 2 bits -: These _informative_ bits are used to signal the pre-processing that has +: These _informative_ bits are used to signal the preprocessing that has been performed during compression. The decoder can use this information to for example, dither the values or smooth the gradients prior to display. - * `0`: No pre-processing. + * `0`: No preprocessing. * `1`: Level reduction. Filtering method (F): 2 bits -: The filtering method used: +: The filtering methods used are described as follows: * `0`: None. * `1`: Horizontal filter. @@ -584,8 +585,8 @@ made depending on the filtering method: where `clip(v)` is equal to: - * 0 if v < 0 - * 255 if v > 255 + * 0 if v < 0, + * 255 if v > 255, or * v otherwise The final value is derived by adding the decompressed value `X` to the @@ -594,9 +595,10 @@ into the \[0..255\] one: `alpha = (predictor + X) % 256` -There are special cases for the left-most and top-most pixel positions: +There are special cases for the left-most and top-most pixel positions. For +example, the top-left value at location (0, 0) uses 0 as the predictor value. +Otherwise: - * The top-left value at location (0, 0) uses 0 as predictor value. Otherwise, * For horizontal or gradient filtering methods, the left-most pixels at location (0, y) are predicted using the location (0, y-1) just above. * For vertical or gradient filtering methods, the top-most pixels at @@ -622,27 +624,27 @@ containing a 'VP8L' chunk SHOULD NOT contain this chunk. **Rationale**: The transparency information is already part of the 'VP8L' chunk. -The alpha channel data is stored as uncompressed raw data (when +The alpha channel data is stored as uncompressed raw data (when the compression method is '0') or compressed using the lossless format (when the compression method is '1'). - * Raw data: consists of a byte sequence of length width * height, + * Raw data: This consists of a byte sequence of length = width * height, containing all the 8-bit transparency values in scan order. - * Lossless format compression: the byte sequence is a compressed - image-stream (as described in the [WebP Lossless Bitstream Format] - [webpllspec]) of implicit dimension width x height. That is, this - image-stream does NOT contain any headers describing the image dimension. + * Lossless format compression: The byte sequence is a compressed + image-stream (as described in ["WebP Lossless Bitstream Format"] + [webpllspec]) of implicit dimensions width x height. That is, this + image-stream does NOT contain any headers describing the image dimensions. - **Rationale**: the dimension is already known from other sources, - so storing it again would be redundant and error-prone. + **Rationale**: The dimensions are already known from other sources, + so storing them again would be redundant and prone to error. - Once the image-stream is decoded into ARGB color values, following - the process described in the lossless format specification, the - transparency information must be extracted from the *green* channel - of the ARGB quadruplet. + Once the image-stream is decoded into Alpha, Red, Green, Blue (ARGB) color + values, following the process described in the lossless format + specification, the transparency information must be extracted from the + *green* channel of the ARGB quadruplet. - **Rationale**: the green channel is allowed extra transformation + **Rationale**: The green channel is allowed extra transformation steps in the specification -- unlike the other channels -- that can improve compression. @@ -650,13 +652,13 @@ compression method is '0') or compressed using the lossless format This chunk contains compressed bitstream data for a single frame. -A bitstream chunk may be either (i) a VP8 chunk, using "VP8 " (note the -significant fourth-character space) as its tag _or_ (ii) a VP8L chunk, using -"VP8L" as its tag. +A bitstream chunk may be either (i) a 'VP8 ' Chunk, using 'VP8 ' (note the +significant fourth-character space) as its FourCC, _or_ (ii) a 'VP8L' Chunk, +using 'VP8L' as its FourCC. -The formats of VP8 and VP8L chunks are as described in sections +The formats of 'VP8 ' and 'VP8L' Chunks are as described in sections [Simple File Format (Lossy)](#simple-file-format-lossy) -and [Simple File Format (Lossless)](#simple-file-format-lossless) respectively. +and [Simple File Format (Lossless)](#simple-file-format-lossless), respectively. #### Color Profile @@ -720,59 +722,59 @@ XMP Metadata: _Chunk Size_ bytes : Image metadata in XMP format. -Note the fourth character in the 'XMP ' FourCC is an ASCII space (0x20). +Note that the fourth character in the 'XMP ' FourCC is an ASCII space (0x20). Additional guidance about handling metadata can be found in the -Metadata Working Group's [Guidelines for Handling Metadata][metadata]. +Metadata Working Group's ["Guidelines for Handling Metadata"][metadata]. #### Unknown Chunks -A RIFF chunk (described in [this](#terminology-amp-basics) section) whose _chunk -tag_ is different from any of the chunks described in this document, is +A RIFF chunk (described in the [RIFF File Format](#riff-file-format) section) +whose FourCC is different from any of the chunks described in this document, is considered an _unknown chunk_. **Rationale**: Allowing unknown chunks gives a provision for future extension -of the format, and also allows storage of any application-specific data. +of the format and also allows storage of any application-specific data. A file MAY contain unknown chunks: - * At the end of the file as described in [Extended WebP file - header](#extended_header) section. - * At the end of ANMF chunks as described in the + * at the end of the file, as described in [Extended WebP file + header](#extended_header) section, or + * at the end of 'ANMF' Chunks, as described in the [Animation](#animation) section. Readers SHOULD ignore these chunks. Writers SHOULD preserve them in their original order (unless they specifically intend to modify these chunks). -### Assembling the Canvas From Frames +### Canvas Assembly from Frames Here we provide an overview of how a reader MUST assemble a canvas in the case of an animated image. The process begins with creating a canvas using the dimensions given in the -'VP8X' chunk, `Canvas Width Minus One + 1` pixels wide by `Canvas Height Minus -One + 1` pixels high. The `Loop Count` field from the 'ANIM' chunk controls how +'VP8X' Chunk, `Canvas Width Minus One + 1` pixels wide by `Canvas Height Minus +One + 1` pixels high. The `Loop Count` field from the 'ANIM' Chunk controls how many times the animation process is repeated. This is `Loop Count - 1` for -non-zero `Loop Count` values or infinitely if `Loop Count` is zero. +nonzero `Loop Count` values or infinite if the `Loop Count` is zero. -At the beginning of each loop iteration the canvas is filled using the -background color from the 'ANIM' chunk or an application defined color. +At the beginning of each loop iteration, the canvas is filled using the +background color from the 'ANIM' Chunk or an application-defined color. -'ANMF' chunks contain individual frames given in display order. Before rendering +'ANMF' Chunks contain individual frames given in display order. Before rendering each frame, the previous frame's `Disposal method` is applied. The rendering of the decoded frame begins at the Cartesian coordinates (`2 * -Frame X`, `2 * Frame Y`) using the top-left corner of the canvas as the origin. +Frame X`, `2 * Frame Y`), using the top-left corner of the canvas as the origin. `Frame Width Minus One + 1` pixels wide by `Frame Height Minus One + 1` pixels high are rendered onto the canvas using the `Blending method`. The canvas is displayed for `Frame Duration` milliseconds. This continues until -all frames given by 'ANMF' chunks have been displayed. A new loop iteration is -then begun or the canvas is left in its final state if all iterations have been +all frames given by 'ANMF' Chunks have been displayed. A new loop iteration is +then begun, or the canvas is left in its final state if all iterations have been completed. The following pseudocode illustrates the rendering process. The notation -_VP8X.field_ means the field in the 'VP8X' chunk with the same description. +_VP8X.field_ means the field in the 'VP8X' Chunk with the same description. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ assert VP8X.flags.hasAnimation @@ -785,7 +787,7 @@ if loop_count == 0: frame_params ← nil assert next chunk in image_data is ANMF for loop = 0..loop_count - 1 - clear canvas to ANIM.background_color or application defined color + clear canvas to ANIM.background_color or application-defined color until eof or non-ANMF chunk frame_params.frameX = Frame X frame_params.frameY = Frame Y @@ -805,11 +807,11 @@ for loop = 0..loop_count - 1 frame_params.bitstream = bitstream_data render frame with frame_params.alpha and frame_params.bitstream on canvas with top-left corner at (frame_params.frameX, - frame_params.frameY), using blending method + frame_params.frameY), using Blending method frame_params.blendingMethod. canvas contains the decoded image. Show the contents of the canvas for - frame_params.frameDuration * 1ms. + frame_params.frameDuration * 1 ms. dispose_method = frame_params.disposeMethod ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -817,7 +819,7 @@ for loop = 0..loop_count - 1 Example File Layouts -------------------- -A lossy encoded image with alpha may look as follows: +A lossy-encoded image with alpha may look as follows: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ RIFF/WEBP @@ -826,7 +828,7 @@ RIFF/WEBP +- VP8 (bitstream) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -A losslessly encoded image may look as follows: +A lossless-encoded image may look as follows: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ RIFF/WEBP @@ -835,7 +837,7 @@ RIFF/WEBP +- VP8L (lossless bitstream) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -A lossless image with ICC profile and XMP metadata may +A lossless image with an ICC profile and XMP metadata may look as follows: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -859,10 +861,11 @@ RIFF/WEBP +- EXIF (metadata) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -[vp8spec]: https://datatracker.ietf.org/doc/html/rfc6386 [webpllspec]: https://chromium.googlesource.com/webm/libwebp/+/HEAD/doc/webp-lossless-bitstream-spec.txt [iccspec]: https://www.color.org/icc_specs2.xalter [metadata]: https://web.archive.org/web/20180919181934/http://www.metadataworkinggroup.org/pdf/mwg_guidance.pdf +[rec601]: https://www.itu.int/rec/R-REC-BT.601 [rfc 1166]: https://datatracker.ietf.org/doc/html/rfc1166 [rfc 2119]: https://datatracker.ietf.org/doc/html/rfc2119 +[rfc 6386]: https://datatracker.ietf.org/doc/html/rfc6386 [rfc 8174]: https://datatracker.ietf.org/doc/html/rfc8174