18
edits
Changes
m
Replace "placeholder image" with "default image"
== Terminology ==
The "placeholder 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.
== 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 placeholder default image. A decoder which detects an error before the animation has started should display the placeholder default image. An error message may be displayed to the user if appropriate.
= Structure =
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 placeholder default image defines the boundaries of the entire animation; hence, the placeholder 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.
The placeholder default image may be treated included as the first frame of the animation by the presence of a single `fcTL` chunk before `IDAT`. Otherwise, the placeholder 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.
The tables below illustrates the use of sequence numbers for images with more than one frame and more than one `fdAT` chunk.
If the placeholder default image is the first frame:
Sequence number Chunk
....
If the placeholder default image is not part of the animation:
Sequence number Chunk
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 placeholder 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 non-placeholder 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.
* Other ancillary chunks are allowed to appear among the APNG chunks, including between `fdAT` chunks.
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 placeholder default image.
Constraints on frame regions:
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 placeholder default image has additional restrictions, if it exists:
* The `x_offset` and `y_offset` fields must be 0.
* The `width` and `height` fields must equal the corresponding fields from the `IHDR` chunk.
* `dispose_op` must not be APNG_DISPOSE_OP_PREVIOUS
As noted earlier, if a `fcTL` chunk does not precede `IDAT`, the placeholder 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.
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 placeholder default image.
Format:
