Understanding avifImageCopy in libavif

This article provides a clear overview of the avifImageCopy function in the libavif library, detailing its purpose, how it manages memory, and its role in duplicating AVIF image structures. You will learn how this function enables developers to safely duplicate pixel data and metadata for image processing.

What is avifImageCopy?

The avifImageCopy function is a core utility in libavif, the library used to encode and decode AV1 Image File Format (AVIF) files. The primary purpose of avifImageCopy is to perform a “deep copy” of an avifImage structure.

In C programming, simply assigning one structure pointer to another only copies the memory address (a shallow copy). If the original image memory is freed or modified, the copy becomes invalid or corrupted. avifImageCopy solves this by allocating new memory for the destination image and copying all actual pixel data and metadata from the source image.

What Data Does It Copy?

When avifImageCopy is called, it duplicates all essential components of the AVIF container, including:

• Pixel Planes: It copies the YUV (luma and chroma) or RGB color channels, as well as the alpha (transparency) channel if present.
• Metadata: It transfers metadata packets, such as Exif data, XMP profiles, and ICC color profiles.
• Color Properties: It preserves color space information, including Color Primaries, Transfer Characteristics, and Matrix Coefficients (CICP).
• Image Dimensions: It copies width, height, depth (bit depth), and pixel aspect ratio.

Function Signature and Parameter Control

The function is defined in the libavif API as follows:

avifResult avifImageCopy(avifImage * dstImage, const avifImage * srcImage, avifPlanesFlags planes);

• dstImage: A pointer to the destination avifImage struct where the data will be copied.
• srcImage: A pointer to the source avifImage struct containing the original image.
• planes: A bitmask flag that allows developers to choose exactly which planes to copy (for example, copying only the YUV planes, only the alpha channel, or all available planes).

Key Benefits and Use Cases

Using avifImageCopy is critical in several common image processing scenarios:

• Non-Destructive Editing: Developers can keep the original decoded image in memory as a backup while modifying a copy (e.g., cropping, resizing, or applying filters).
• Thread Safety: Because the function creates an independent copy of the image data in a new memory space, different threads can process the source and destination images simultaneously without resource conflicts.
• Memory Management: The function automatically handles the allocation of plane buffers in the destination image to match the source image dimensions and format, reducing boilerplate code and the risk of memory leaks.