AVIF IO

gdImagePtr gdImageCreateFromAvif( FILE  * infile )

gdImageCreateFromAvif is called to load truecolor images from AVIF format files.  Invoke gdImageCreateFromAvif with an already opened pointer to a file containing the desired image.  gdImageCreateFromAvif returns a gdImagePtr to the new truecolor image, or NULL if unable to load the image (most often because the file is corrupt or does not contain a AVIF image).  gdImageCreateFromAvif does not close the file.

This function creates a gdIOCtx struct from the file pointer it’s passed.  And then it relies on gdImageCreateFromAvifCtx to do the real decoding work.  If the file contains an image sequence, we simply read the first one, discarding the rest.

Variants

gdImageCreateFromAvifPtr creates an image from AVIF data already in memory.

gdImageCreateFromAvifCtx reads data from the function pointers in a gdIOCtx structure.

Parameters

Returns

A pointer to the new truecolor image.  This will need to be destroyed with gdImageDestroy once it is no longer needed.

On error, returns 0.

gdImagePtr gdImageCreateFromAvifPtr( int  size, void  * data )

See gdImageCreateFromAvif.

Parameters

gdImagePtr gdImageCreateFromAvifCtx ( gdIOCtx  * ctx )

See gdImageCreateFromAvif.

Additional details: the AVIF library comes with functions to create an IO object from a file and from a memory pointer.  Of course, it doesn’t have a way to create an IO object from a gdIOCtx.  So, here, we use our own helper function, <createAvifIOfromCtx>.

Otherwise, we create the image by calling AVIF library functions in order

• avifDecoderCreate(), to create the decoder
• avifDecoderSetIO(), to tell libavif how to read from our data structure
• avifDecoderParse(), to parse the image
• avifDecoderNextImage(), to read the first image from the decoder
• avifRGBImageSetDefaults(), to create the avifRGBImage
• avifRGBImageAllocatePixels(), to allocate memory for the pixels
• avifImageYUVToRGB(), to convert YUV to RGB

Finally, we create a new gd image and copy over the pixel data.

Parameters

gdImageAvifEx outputs the specified image to the specified file in AVIF format.  The file must be open for writing.  Under MSDOS and all versions of Windows, it is important to use “wb” as opposed to simply “w” as the mode when opening the file, and under Unix there is no penalty for doing so.  gdImageAvifEx does not close the file; your code must do so.

Variants

gdImageAvifEx writes the image to a file, encoding with the default quality and speed.

<gdImageAvifPtrEx> stores the image in RAM.

<gdImageAvifPtr> stores the image in RAM, encoding with the default quality and speed.

<gdImageAvifCtx> stores the image using a gdIOCtx struct.

Parameters

Notes on parameters

Qualities or speeds that are lower than the minimum value get clamped to the minimum value, abd qualities or speeds that are lower than the maximum value get clamped to the maxmum value.

Returns

• for gdImageAvifEx, <gdImageAvif>, and <gdImageAvifCtx>, nothing.
• for <gdImageAvifPtrEx> and <gdImageAvifPtr>, a pointer to the image in memory.

static avifBool _gdImageAvifCtx( gdImagePtr  im, gdIOCtx  * outfile, int  quality, int  speed )

We need this underscored function because gdImageAvifCtx() can’t return anything.  And our functions that operate on a memory buffer need to know whether the encoding has succeeded.

If we’re passed the QUALITY_DEFAULT of -1, set the quantizer params to QUANTIZER_DEFAULT.

This function returns 0 on success, or 1 on failure.