48
edits
Changes
no edit summary
APNG 0.4 6 <i>[DRAFT]</i>
Authors:
The size of the first frame defines the boundaries of the entire animation; hence, if extra space will be needed for later frames that is unused in the first frame, the first frame should be appropriately padded with fully transparent regions.
To be recognized as an APNG, an `acTLacTl` chunk must appear in the stream before any `IDAT` chunks. The `acTLacTl` structure is described in the next section.
An `fcTLfcTl` chunk must also appear before `IDAT`, providing frame information for the first frame encoded in the PNG stream's `IDAT` chunks, known as frame 0.
Subsequent frames are encoded in `fdATfdAt` chunks, containing information about placement and rendering of a frame in `fcTLfcTl` chunks, as well as frame data encoded as normal PNG streams. The full layout of the `fdATfdAt` chunk is described in section 2.3.
Note: For purposes of chunk descriptions, an "unsigned int" shall be a 32-bit unsigned integer in network byte order; a "signed int" shall be a 32-bit signed integer in network byte order; an "unsigned short" shall be a 16-bit unsigned integer in network byte order; a "byte" shall be a 8-bit unsigned integer.
== `acTLacTl`: The Animation Control Chunk ==
The `acTLacTl` chunk is an ancillary chunk as defined in the PNG Specification. It must appear before the first `IDAT` chunk within a valid PNG stream. If the color type of the image is PNG_COLOR_TYPE_PALETTE the `acTl` chunk must appear after the `PLTE` chunk.
The `acTLacTl` chunk contains:
byte
`num_frames` indicates the total number of frames in the animation, that is the first frame plus the number of fdAT fdAt chunks. 0 is not a valid value. 1 is a valid value for a single-frame APNG. In case this number does not match the actual number of frames, behaviour of the implementation is not specified.
`num_iterations` indicates the number of iterations that this animation should play; if it is 0, the animation should play indefinitely. If nonzero, the animation should come to rest on the final non-skipped frame at the end of the last iteration.
The `fcTLfcTl` chunk is an ancillary chunk as defined in the PNG Specification. It must appear before the IDAT chunks of the frame to which it applies, specifically: * For the first frame, the `fcTl` chunk must appear before the first `IDAT` chunk. Position relative to the `acTl` chunk is not specified.* For any subsequent frames, the `fcTl` chunk must be first in the data part of the `fdAt` chunk. The `fcTl` chunk is mandatory for every frame. More than one `fcTLfcTl` chunk per frame is not allowed.
Format:
16 render_op (byte) Type of canvas area disposal to be done after rendering this frame
The `sequence_number` shall begin with 0 for the first `fdATfdAt` in the PNG stream, and increase by one with each subsequent frame.
The frame must be rendered within the region defined by the `x_offset` and `y_offset` from the `fcTLfcTl`, and the width and height from this frame's `IHDR`. For frame 0, the `x_offset` and `y_offset` fields must be 0. Should parts
of the region fall outside the canvas defined by frame 0, rendering is to be clipped to that canvas.
* `APNG_RENDER_OP_DISPOSE_PREVIOUS`: the frame's region is to be reverted to the previous contents.
`APNG_RENDER_OP_BLEND_FLAG` may be added to any of the above disposal perationsoperations. If this flag is not set, all color components of the frame, including alpha, overwrite the current contents of the frame's canvas region. If the BLEND_FLAG is set the frame should be composited onto the canvas based on its alpha, using a simple OVER operation:
Csrc - component of pixel in the frame
If `APNG_RENDER_OP_SKIP_FRAME` is present, then the decoder should not render the current frame as part of the animation. Though this flag can be set on any frame and must be honored, it is most useful for frame 0, to prevent the frame that would be visible to PNG viewers not supporting animation from being part of the animated frame set. If animation in the viewer is not desired or explicitly disabled by the user, the viewer should display frame 0 even if `SKIP_FRAME` is set on frame 0. This provides content authors with a means to provide a still image to be used in lieu of the full animation.
== `fdATfdAt`: The Frame Data Chunk ==
The `fdATfdAt` chunk contains one frame for the animation. Any `fdATfdAt` chunks must follow any `IDAT` chunks. All `fdATfdAt` chunks must be adjacent in the PNG stream. Should a decoder receive an APNG stream with missing or out of order `fdATfdAt` chunks, it is under no obligation to attempt to reorder the chunks and may treat that case as an error condition.
Format:
byte
0 `fcTLfcTl` chunk 29 bytes `fcTLfcTl` chunk for this frame
29 `IDAT` chunks X bytes Frame data for this frame
29+X `feND` chunk 12 bytes `feND` chunk to mark the end of the frame data
Each of the chunks contained in the data section of the `fdATfdAt` must follow all the rules in section 5 of the PNG specification, except 5.6 Chunk Ordering. The order of chunks within the `fdATfdAt` is fixed.
The frame data within the `fdATfdAt` consists of a series of `IDAT` chunks, following the rules from section 11.2.4 of the PNG Specification.
The `feND` is an ancillary, zero-length data field chunk, used to mark the end of the frame data. The `feND` chunk is a mandatory last chunk in the data part of the `fdATfdAt` chunk. Only one `feND` per `fdATfdAt` is allowed.
Each frame inherits every property specified by any critical or ancillary chunks before the first IDAT in the file.
Note: both the container chunk (`fdATfdAt`) and every chunk within (`fcTLfcTl`, `IDAT`s, `feND`) must specify the length of its own data field and the CRC over its own chunk name + chunk data as required by section 5.3 of the PNG Specification.
= Revisions to this Specification ==
* Renamed aCTL to acTL, fCTL to fcTL, aDAT to fdAT and fEND to feND to comply with the PNG spec chunk naming requirements
== From 0.5 ==
* Added the IHDR and PLTE CRCs to the acTl chunk
* The acTL fcTL and adAT are now copy safe, renamed them to acTl, fcTl and adAt
= Test Encoder and Sample Images =
= A. References =
