What is the avifImage Struct in libavif C API

This article explains the purpose, structure, and usage of the avifImage struct in the libavif C library. You will learn how this central data container manages uncompressed image pixels, color profiles, alpha channels, and metadata during the AVIF encoding and decoding processes.

The avifImage struct is the foundational data structure in the libavif C API used to represent an uncompressed image in memory. It acts as the bridge between raw pixel data and the compressed AVIF container, serving as the input for the encoder and the output for the decoder.

Core Purposes of the avifImage Struct

1. Managing Pixel Buffers and Formats

The primary job of avifImage is to hold the raw pixel data. It supports various pixel layouts and chroma subsampling formats, which are defined within the struct. * Planes: It manages pointers to the individual color planes (such as Y, U, and V for YUV formats, or R, G, and B if transformed). * Chroma Subsampling: It defines how the chroma channels are subsampled (e.g., YUV 444, 422, 420, or grayscale 400). * Bit Depth: It specifies the color depth of the image, supporting 8, 10, and 12 bits per channel.

2. Handling Alpha (Transparency)

The struct natively supports transparency by maintaining a dedicated, optional alpha plane. If an image contains transparency, avifImage stores this auxiliary data alongside the primary color channels, allowing encoders to compress the alpha channel separately or decoders to extract it seamlessly.

3. Preserving Color Space and Color Profiles

To ensure accurate color reproduction across different displays, avifImage contains color management information: * CICPs (Color Infrastructure Characterization Points): It stores integer values for Color Primaries, Transfer Characteristics, and Matrix Coefficients. * ICC Profiles: It holds raw ICC profile payloads for advanced color management workflows.

4. Storing Image Metadata

Beyond pixel data, avifImage acts as a carrier for non-pixel metadata. It contains dedicated buffers for: * Exif Data: Camera settings, orientation, and capture time. * XMP Data: XML-based metadata for digital asset management.

Role in the libavif Workflow

In a typical libavif application, the avifImage struct goes through a simple allocation, configuration, and deallocation lifecycle:

• During Decoding: The application initializes an avifDecoder. When a frame is decoded, the library populates an avifImage struct with the resulting uncompressed pixels, dimensions, and color properties for the application to read and render.
• During Encoding: The developer allocates an empty avifImage using avifImageCreate(), sets its dimensions and format, populates its plane pointers with raw pixel data, and passes it to the avifEncoder to generate the final AVIF file.
• Memory Management: Because the struct dynamically allocates memory for pixels and metadata, developers must free it using avifImageDestroy() to prevent memory leaks.