APNG Specification: Difference between revisions

Jump to navigation Jump to search

APNG Specification (view source)

Revision as of 05:09, 2 August 2006

327 bytes added ,  2 August 2006
→‎2. Structure
(Importing APNG spec)
 
Line 13: Line 13:
= 2. Structure =
= 2. Structure =


An APNG stream is a normal PNG stream as defined in the [PNG Specification][pngspec], with two additional chunks describing the animation and providing additional frame data.  The first frame of an animation, frame 0, is encoded as a normal PNG.  This frame is what decoders that do not understand the APNG chunks will display.
An APNG stream is a normal PNG stream as defined in the [PNG Specification][pngspec], with four additional chunks describing the animation and providing additional frame data.  The first frame of an animation, frame 0, is encoded as a normal PNG.  This frame is what decoders that do not understand the APNG chunks will display.


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.
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 `aCTL` chunk should appear the stream before any `IDAT` chunks. If an `aCTL` appears after an `IDAT` chunk, a decoder must ignore it and treat the stream as a single-frame PNG.  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.


A `fCTL` 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.
An `fCTL` 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 `aDAT` chunks, containing information about placement and rendering of a frame in `fCTL` chunks, as well as frame data encoded as normal PNG streams.  The full layout of the `aDAT` chunk is described in section 2.2.
Subsequent frames are encoded in `aDAT` chunks, containing information about placement and rendering of a frame in `fCTL` chunks, as well as frame data encoded as normal PNG streams.  The full layout of the `aDAT` 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.


== 2.1. `aCTL`: The Animation Control Chunk ==
== 2.1. `aCTL`: The Animation Control Chunk ==


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.
The `aCTL` chunk is an ancillary chunk as defined in the PNG Specification. It must appear before the first `IDAT` chunk within a valid PNG stream.


The `aCTL` chunk is an ancillary chunk as defined in the PNG Specification.  It must appear before an `IDAT` chunk within a valid PNG stream.
The `aCTL` chunk contains:


Format:
    byte
    0    num_frames        (unsigned int)    Number of frames
    4    num_iterations    (unsigned int)    Number of times to loop this APNG.  0 indicates infinite looping.


    byte
`num_frames` indicates the total number of frames in the animation, that is the first frame plus the number of aDAT 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.
      0   num_iterations    (unsigned int)    Number of times to loop this APNG. 0 indicates infinite looping.


`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.
`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.


== 2.2 `aDAT`: The Animation Data Chunk ==
== 2.2 `fCTL`: The Frame Control Chunk ==
 
The `aDAT` chunk contains a stream of images to be used as frames for the animation.  Any `aDAT` chunks must follow any `IDAT` chunks.
 
Format:
 
    byte
      0    sequence_number  (unsigned int)    Sequence number of this aDAT chunk, starting with 0
      4    remaining stream data


The `sequence_number` shall begin with 0 for the first `aDAT` in the PNG stream, and increase by one with each subsequent PNG stream.  The length of the stream data is determined by the length of the `aDAT` chunk, minus the size of the `sequence_number`.  If only one `aDAT` chunk is present in the PNG stream, all frames must be encoded within its data section. If more than one `aDAT` chunk is present, the first chunk (that is, the chunk with `sequence_number` 0) must have empty stream data to allow the decoder to check for the most common out-of-order errors by looking at the `sequence_number` of the next frame.  All `aDAT` chunks must be adjacent in the PNG stream.
The `fCTL` 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:


The stream data within the `aDAT` consists of a stream of PNG chunks, with each frame beginning with a `fCTL` chunk, followed by an `IHDR`, and then containing normal PNG image chunks followed by one or more `IDAT` chunks providing the data for the frame.  No `IEND` is to be written for these embedded streams; instead, a `fCTL` chunk indicates that the frame has ended and provides control information for the next frame.  For the final frame of the image, its end is indicated by an end of the `aDAT` data section, and a PNG chunk after the `aDAT` that is not another `aDAT`. **(??? Do we want an explicit `fEND` or something here?)**
* 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 `aDAT` chunk.


Each frame must be of the same color type as the parent stream.  Each frame's region, as defined by its width and height (specified in the `IHDR`) and its x and y offset (specified in the `fCTL`, described below) must lie within the first image canvas.
The `fCTL` chunk is mandatory for every frame. More than one `fCTL` chunk per frame is not allowed.
 
Encoders are strongly encouraged to use a single `aDAT` chunk whenever possible,
to remove the chance of out of order chunks.  Should a decoder receive an APNG stream with missing or out of order `aDAT` chunks, it is under no obligation to attempt to reorder the chunks and may treat that case as an error condition.
 
== 2.3 `fCTL`: The Frame Control Chunk ==


Format:
Format:


     byte
     byte
     0    x_offset          (unsigned int)      X position at which to render this frame
     0   sequence_number  (unsigned int)      Sequence number of the frame, starting from 0
     4   y_offset          (unsigned int)      Y position at which to render this frame
    4   x_offset          (unsigned int)      X position at which to render this frame
    8   delay_num        (unsigned short)    Frame delay fraction numerator
     8   y_offset          (unsigned int)      Y position at which to render this frame
     10   delay_den        (unsigned short)    Frame delay fraction denominator
    12   delay_num        (unsigned short)    Frame delay fraction numerator
     12   render_op        (byte)              Type of canvas area disposal to be done after rendering this frame
     14   delay_den        (unsigned short)    Frame delay fraction denominator
     16   render_op        (byte)              Type of canvas area disposal to be done after rendering this frame


The `delay_num` and `delay_den` parameters together specify a fraction indicating the delay after the current frame, in seconds.  If the denominator is 0, it is to be treated as if it were 100 (that is, delay_num then specifies 1/100ths of a second).  If the the value of the numerator is 0 the decoder should render the next frame as quickly as possible, though viewers may impose a reasonable lower bound on the delay.
The `sequence_number` shall begin with 0 for the first `aDAT` in the PNG stream, and increase by one with each subsequent frame.


The frame is rendered within the region defined by the `x_offset` and `y_offset` from the `fCTL`, 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
The frame must be rendered within the region defined by the `x_offset` and `y_offset` from the `fCTL`, 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.
of the region fall outside the canvas defined by frame 0, rendering is to be clipped to that canvas.


The `render_op` parameter specifies contains flags describing how the frame is to be disposed before rendering the next frame; it also specifies whether the frame is to be alpha blended into the current canvas content, or whether it should completely replace its region in the canvas.  Valid render_op flags are:
The `delay_num` and `delay_den` parameters together specify a fraction indicating the delay after the current frame, in seconds.  If the denominator is 0, it is to be treated as if it were 100 (that is, delay_num then specifies 1/100ths of a second).  If the the value of the numerator is 0 the decoder should render the next frame as quickly as possible, though viewers may impose a reasonable lower bound on the delay.
 
The `render_op` parameter contains flags describing how the frame is to be disposed before rendering the next frame; it also specifies whether the frame is to be alpha blended into the current canvas content, or whether it should completely replace its region in the canvas.  Valid render_op flags are:


     bit
     bit
Line 106: Line 100:


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.
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.
== 2.3 `aDAT`: The Animation Data Chunk ==
The `aDAT` chunk contains one frame for the animation. Any `aDAT` chunks must follow any `IDAT` chunks. All `aDAT` chunks must be adjacent in the PNG stream. Should a decoder receive an APNG stream with missing or out of order `aDAT` chunks, it is under no obligation to attempt to reorder the chunks and may treat that case as an error condition.
Format:
    byte
    0    `fCTL` chunk  29 bytes    `fCTL` 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 `aDAT` must follow all the rules in section 5 of the PNG specification, except 5.6 Chunk Ordering. The order of chunks within the `aDAT` is fixed.
The frame data within the `aDAT` 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 `aDAT` chunk. Only one `fEND` per `aDAT` 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 (`aDAT`) and every chunk within (`fCTL`, `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.


= 3. Interaction with other PNG chunks =
= 3. Interaction with other PNG chunks =
Andrew
48

edits

Retrieved from "https://wiki.mozilla.org/Special:MobileDiff/30430"

Navigation menu