libavif avifDecoder Struct Explained

This article provides a comprehensive overview of the avifDecoder struct in the libavif library, which serves as the central hub for managing the decoding process of AVIF images. By examining its internal fields, developers can understand how the decoder manages input/output operations, configures codec choices, stores image dimensions, tracks animation playback states, and handles error diagnostics.

The avifDecoder struct is defined in the core avif/avif.h header file of the libavif library. It coordinates the lifecycle of decoding a container file (ISOBMFF) and the underlying compressed AV1 payloads.

1. Configuration and Control Fields

These fields allow developers to customize how the decoding engine behaves before processing an image file:

• codecChoice: Specifies which underlying AV1 decoding codec to use (e.g., AVIF_CODEC_CHOICE_AUTO, AVIF_CODEC_CHOICE_AOM, AVIF_CODEC_CHOICE_DAV1D).
• maxThreads: Limits the number of worker threads the decoder can spawn to process the image.
• requestedSource: Controls which source track or item inside the AVIF container should be decoded (e.g., the primary item, a specific track, or auto-selected).
• strictFlags: Enforces strict compliance with the AVIF specification. If set, the decoder will reject files with minor structural anomalies.
• ignoreExif / ignoreXMP: Boolean flags that tell the decoder to skip parsing metadata payloads, saving processing time and memory if they are not needed.
• imageSizeLimit / imageDimensionLimit: Security boundaries that prevent out-of-memory exploits by rejecting images with dimensions or total pixel areas that exceed specified thresholds.

2. Image and Frame Metadata

These fields store information about the loaded asset once the file header has been parsed:

• image: A pointer to an avifImage struct. This is where the output of the decoded pixels, color profiles (ICC profiles or NCLX), and alpha channels are stored.
• imageCount: The total number of frames in the image sequence or animation. For static images, this value is 1.
• imageIndex: Tracks the index of the currently decoded frame (0-indexed).
• allowProgressive: A boolean indicating whether progressive decoding is allowed for images encoded with multiple layers.
• allowIncremental: Allows the decoder to output partially received data, which is useful for progressive web rendering of large images.

3. Animation Timing

When dealing with animated AVIF sequences, the avifDecoder tracks playback timing through these specific variables:

• timescale: The media timescale of the file, defining how many time units pass per second.
• duration: The total playback duration of the animation in seconds.
• durationInTimescale: The overall duration of the animation expressed in timescale units.
• imageTiming: An instance of the avifImageTiming struct that holds the exact presentation timestamp (PTS) and duration for the currently active frame.

4. Input/Output and Internal State

To process the physical data stream and maintain internal tracking, the struct references helper interfaces and private structures:

• io: A pointer to an avifIO struct, which contains custom read, write, and size callbacks. This allows developers to stream data from memory, files, or custom network protocols directly into the decoder.
• diag: An instance of avifDiagnostics. If a decoding operation fails, this struct is populated with detailed, human-readable error messages explaining exactly where the parsing failed.
• data: A pointer to an internal, private avifDecoderData structure. This hides the complex parser implementation details—such as BMFF box structures, track definitions, and codec-specific state objects—away from the public API.