18
edits
APNG Specification: Difference between revisions
Jump to navigation
Jump to search
m
Replace "placeholder image" with "default image"
Herbyderby (talk | contribs) (clarify that disposal happens to the output buffer before rendering the next frame) |
Herbyderby (talk | contribs) m (Replace "placeholder image" with "default image") |
||
| Line 20: | Line 20: | ||
== Terminology == | == Terminology == | ||
The " | The "default image" is the image described by the standard `IDAT` chunks, and is the image that displayed by decoders that do not support APNG. | ||
The "canvas" is the area on the output device on which the frames are to be displayed. The contents of the canvas are not necessarily available to the decoder. As per the PNG Specification, if a `bKGD` chunk exists it may be used to fill the canvas if there is no preferrable background. | The "canvas" is the area on the output device on which the frames are to be displayed. The contents of the canvas are not necessarily available to the decoder. As per the PNG Specification, if a `bKGD` chunk exists it may be used to fill the canvas if there is no preferrable background. | ||
| Line 32: | Line 32: | ||
== Error Handling == | == Error Handling == | ||
APNG is designed to allow incremental display of frames before the entire image has been read. This implies that some errors may not be detected until partway through the animation. It is strongly recommended that when any error is encountered decoders should discard all subsequent frames, stop the animation, and revert to displaying the | APNG is designed to allow incremental display of frames before the entire image has been read. This implies that some errors may not be detected until partway through the animation. It is strongly recommended that when any error is encountered decoders should discard all subsequent frames, stop the animation, and revert to displaying the default image. A decoder which detects an error before the animation has started should display the default image. An error message may be displayed to the user if appropriate. | ||
= Structure = | = Structure = | ||
| Line 38: | Line 38: | ||
An APNG stream is a normal PNG stream as defined in the [PNG Specification][pngspec], with three additional chunk types describing the animation and providing additional frame data. | An APNG stream is a normal PNG stream as defined in the [PNG Specification][pngspec], with three additional chunk types describing the animation and providing additional frame data. | ||
The size of the | The size of the default image defines the boundaries of the entire animation; hence, the default image should be appropriately padded with fully transparent pixels if extra space will be needed for later frames. | ||
To be recognized as an APNG, an `acTL` chunk must appear in the stream before any `IDAT` chunks. The `acTL` structure is described in the next section. | To be recognized as an APNG, an `acTL` chunk must appear in the stream before any `IDAT` chunks. The `acTL` structure is described in the next section. | ||
The | The default image may be included as the first frame of the animation by the presence of a single `fcTL` chunk before `IDAT`. Otherwise, the default image is not part of the animation, and the output buffer must be completely initialized to fully transparent black at the beginning of each iteration. | ||
Subsequent frames are encoded in `fdAT` chunks containing almost the same structure of content as `IDAT` chunks. Information for each frame about placement and rendering is stored in `fcTL` chunks. The full layout of `fdAT` and `fcTL` chunks is described below. | Subsequent frames are encoded in `fdAT` chunks containing almost the same structure of content as `IDAT` chunks. Information for each frame about placement and rendering is stored in `fcTL` chunks. The full layout of `fdAT` and `fcTL` chunks is described below. | ||
| Line 54: | Line 54: | ||
The tables below illustrates the use of sequence numbers for images with more than one frame and more than one `fdAT` chunk. | The tables below illustrates the use of sequence numbers for images with more than one frame and more than one `fdAT` chunk. | ||
If the | If the default image is the first frame: | ||
Sequence number Chunk | Sequence number Chunk | ||
| Line 63: | Line 63: | ||
.... | .... | ||
If the | If the default image is not part of the animation: | ||
Sequence number Chunk | Sequence number Chunk | ||
| Line 91: | Line 91: | ||
The `fcTL` chunk is an ancillary chunk as defined in the PNG Specification. It must appear before the `IDAT` or `fdAT` chunks of the frame to which it applies, specifically: | The `fcTL` chunk is an ancillary chunk as defined in the PNG Specification. It must appear before the `IDAT` or `fdAT` chunks of the frame to which it applies, specifically: | ||
* For the | * For the default image, if a `fcTL` chunk is present it must appear before the first `IDAT` chunk. Position relative to the `acTL` chunk is not specified. | ||
* For the first | * For the first frame excluding the default image (which may be either the first or second frame), the `fcTL` chunk must appear after all `IDAT` chunks and before the `fdAT` chunks for the frame. | ||
* For all subsequent frames, the `fcTL` chunk for frame N must appear after the `fdAT` chunks from frame N-1 and before the `fdAT` chunks for frame N. | * For all subsequent frames, the `fcTL` chunk for frame N must appear after the `fdAT` chunks from frame N-1 and before the `fdAT` chunks for frame N. | ||
* Other ancillary chunks are allowed to appear among the APNG chunks, including between `fdAT` chunks. | * Other ancillary chunks are allowed to appear among the APNG chunks, including between `fdAT` chunks. | ||
| Line 111: | Line 111: | ||
25 blend_op (byte) Type of frame area rendering for this frame | 25 blend_op (byte) Type of frame area rendering for this frame | ||
The frame must be rendered within the region defined by `x_offset`, `y_offset`, `width`, and `height`. The offsets must be non-negative, the dimensions must be positive, and the region may not fall outside of the | The frame must be rendered within the region defined by `x_offset`, `y_offset`, `width`, and `height`. The offsets must be non-negative, the dimensions must be positive, and the region may not fall outside of the default image. | ||
Constraints on frame regions: | Constraints on frame regions: | ||
| Line 147: | Line 147: | ||
If `blend_op` is APNG_BLEND_OP_SOURCE all color components of the frame, including alpha, overwrite the current contents of the frame's output buffer region. If `blend_op` is APNG_BLEND_OP_OVER the frame should be composited onto the output buffer based on its alpha, using a simple OVER operation as described in the "Alpha Channel Processing" section of the PNG specification [PNG-1.2]. Note that Variation 2 of the sample code is applicable. | If `blend_op` is APNG_BLEND_OP_SOURCE all color components of the frame, including alpha, overwrite the current contents of the frame's output buffer region. If `blend_op` is APNG_BLEND_OP_OVER the frame should be composited onto the output buffer based on its alpha, using a simple OVER operation as described in the "Alpha Channel Processing" section of the PNG specification [PNG-1.2]. Note that Variation 2 of the sample code is applicable. | ||
The `fcTL` chunk corresponding to the | The `fcTL` chunk corresponding to the default image has additional restrictions, if it exists: | ||
* The `x_offset` and `y_offset` fields must be 0. | * The `x_offset` and `y_offset` fields must be 0. | ||
* The `width` and `height` fields must equal the corresponding fields from the `IHDR` chunk. | * The `width` and `height` fields must equal the corresponding fields from the `IHDR` chunk. | ||
| Line 153: | Line 153: | ||
* `dispose_op` must not be APNG_DISPOSE_OP_PREVIOUS | * `dispose_op` must not be APNG_DISPOSE_OP_PREVIOUS | ||
As noted earlier, if a `fcTL` chunk does not precede `IDAT`, the | As noted earlier, if a `fcTL` chunk does not precede `IDAT`, the default image is not part of the animation, and the output buffer must be completely initialized to fully transparent black at the beginning of each iteration. | ||
Together these requirements serve to ensure that each iteration of the animation will be identical. | Together these requirements serve to ensure that each iteration of the animation will be identical. | ||
| Line 161: | Line 161: | ||
The `fdAT` chunk has the same purpose as an `IDAT` chunk. It has the same structure as an `IDAT` chunk, except preceded by a sequence number. | The `fdAT` chunk has the same purpose as an `IDAT` chunk. It has the same structure as an `IDAT` chunk, except preceded by a sequence number. | ||
Each frame must contain at least one `fdAT` chunk. The compressed datastream is then the concatenation of the contents of the data fields of all the `fdAT` chunks within a frame. When decompressed, the datastream is a complete PNG image, including the filter byte at the beginning of each scanline. It utilizes the same bit depth, color type, compression method, filter method, interlace method, and palette (if any) as the | Each frame must contain at least one `fdAT` chunk. The compressed datastream is then the concatenation of the contents of the data fields of all the `fdAT` chunks within a frame. When decompressed, the datastream is a complete PNG image, including the filter byte at the beginning of each scanline. It utilizes the same bit depth, color type, compression method, filter method, interlace method, and palette (if any) as the default image. | ||
Format: | Format: | ||