Read and write High Efficiency Image File Format images. More...

Collaboration diagram for HEIF:

Data Structures
struct	gdHeifReadOptions
	HEIF decoder options used by gdImageCreateFromHeifPtrWithOptions(). More...

struct	gdHeifWriteOptions
	HEIF encoder options used by gdImageHeifPtrWithOptions(). More...

struct	gdHeifInfo
	Information extracted from a HEIF image and its container. More...

HEIF Constants and Options
enum	gdHeifCodec { GD_HEIF_CODEC_UNKNOWN = 0 , GD_HEIF_CODEC_HEVC , GD_HEIF_CODEC_AV1 = 4 }
	HEIF coding formats for gdHeifWriteOptions::codec. More...

typedef const char *	gdHeifChroma
	HEIF chroma-subsampling string used by gdHeifWriteOptions::chroma.

void	gdHeifInfoInit (gdHeifInfo *info)
	Initialize HEIF information with gd defaults.

int	gdHeifGetInfo (FILE inFile, gdHeifInfo info)
	Read HEIF information from a stdio stream.

int	gdHeifGetInfoCtx (gdIOCtxPtr in, gdHeifInfo *info)
	Read HEIF information from a gdIOCtx without closing it.

int	gdHeifGetInfoPtr (int size, const void data, gdHeifInfo info)
	Read HEIF information from an in-memory buffer without taking ownership.

void	gdHeifReadOptionsInit (gdHeifReadOptions *options)
	Initialize HEIF read options with gd defaults.

void	gdHeifWriteOptionsInit (gdHeifWriteOptions *options)
	Initialize HEIF write options with gd defaults.

#define	GD_HEIF_CHROMA_420 "420"

#define	GD_HEIF_CHROMA_422 "422"

#define	GD_HEIF_CHROMA_444 "444"

HEIF Reading
gdImagePtr	gdImageCreateFromHeif (FILE *inFile)
	Create a truecolor image from HEIF data in a stdio stream.

gdImagePtr	gdImageCreateFromHeifPtr (int size, void *data)
	Create a truecolor image from HEIF data in memory.

gdImagePtr	gdImageCreateFromHeifPtrWithOptions (int size, void data, const gdHeifReadOptions options)
	Create a truecolor image from HEIF data in memory using read options.

gdImagePtr	gdImageCreateFromHeifCtx (gdIOCtxPtr infile)
	Create a truecolor image from HEIF data in an IO context.

HEIF Writing
void	gdImageHeifEx (gdImagePtr im, FILE *outFile, int quality, gdHeifCodec codec, gdHeifChroma chroma)
	Write a truecolor image as HEIF data to a stdio stream.

void	gdImageHeif (gdImagePtr im, FILE *outFile)
	Write a truecolor image as HEIF data to a stdio stream.

void *	gdImageHeifPtr (gdImagePtr im, int *size)
	Encode a truecolor image as HEIF data in memory.

void *	gdImageHeifPtrEx (gdImagePtr im, int *size, int quality, gdHeifCodec codec, gdHeifChroma chroma)
	Encode a truecolor image as HEIF data in memory.

void *	gdImageHeifPtrWithOptions (gdImagePtr im, int size, const gdHeifWriteOptions options)
	Encode a truecolor image as HEIF data in memory using write options.

int	gdImageHeifWithOptions (gdImagePtr im, FILE outFile, const gdHeifWriteOptions options)
	Write HEIF data to a stdio stream using write options.

int	gdImageHeifCtxWithOptions (gdImagePtr im, gdIOCtxPtr outfile, const gdHeifWriteOptions *options)
	Write HEIF data to a gdIOCtx using write options.

void	gdImageHeifCtx (gdImagePtr im, gdIOCtxPtr outfile, int quality, gdHeifCodec codec, gdHeifChroma chroma)
	Write a truecolor image as HEIF data to an IO context.

Detailed Description

Read and write High Efficiency Image File Format images.

HEIF support reads HEIF-family files from stdio streams, memory buffers, or gd IO contexts and returns truecolor images. The reader accepts AVIF, MIF1, HEIC, and HEIX brands and decodes the primary image. HEIF writing accepts truecolor images and can write to stdio streams, memory buffers, or gd IO contexts with explicit codec, quality, lossless, and chroma-subsampling options.

FILE *in;
gdImagePtr im;
gdHeifWriteOptions options;
void *data;
int size;
 
in = fopen("input.heic", "rb");
if (in == NULL) {
    return 1;
}
 
im = gdImageCreateFromHeif(in);
fclose(in);
if (im == NULL) {
    return 1;
}
 
gdHeifWriteOptionsInit(&options);
options.quality = 90;
options.codec = GD_HEIF_CODEC_HEVC;
options.chroma = GD_HEIF_CHROMA_444;
 
data = gdImageHeifPtrWithOptions(im, &size, &options);
if (data != NULL) {
    gdFree(data);
}
 
gdImageDestroy(im);

Macro Definition Documentation

◆ GD_HEIF_CHROMA_420

#define GD_HEIF_CHROMA_420 "420"

Use 4:2:0 chroma subsampling for HEIF output.

◆ GD_HEIF_CHROMA_422

#define GD_HEIF_CHROMA_422 "422"

Use 4:2:2 chroma subsampling for HEIF output.

◆ GD_HEIF_CHROMA_444

#define GD_HEIF_CHROMA_444 "444"

Use 4:4:4 chroma subsampling for HEIF output.

Enumeration Type Documentation

◆ gdHeifCodec

enum gdHeifCodec

HEIF coding formats for gdHeifWriteOptions::codec.

Enumerator
GD_HEIF_CODEC_UNKNOWN	Unknown or unspecified HEIF codec.
GD_HEIF_CODEC_HEVC	HEVC/H.265 HEIF codec.
GD_HEIF_CODEC_AV1	AV1 HEIF codec.

Function Documentation

◆ gdHeifGetInfo()

int gdHeifGetInfo	(	FILE *	inFile,
		gdHeifInfo *	info
	)

Read HEIF information from a stdio stream.

The input stream is borrowed and remains open. Returns GD_META_OK on success; otherwise returns a GD_META_* error code.

◆ gdHeifInfoInit()

void gdHeifInfoInit ( gdHeifInfo * info )

Initialize HEIF information with gd defaults.

Set info->metadata to a caller-owned metadata object after initialization when metadata should be collected.

◆ gdHeifReadOptionsInit()

void gdHeifReadOptionsInit ( gdHeifReadOptions * options )

Initialize HEIF read options with gd defaults.

Call this before changing selected gdHeifReadOptions fields and passing the structure to gdImageCreateFromHeifPtrWithOptions().

Parameters

options Pointer to the read options structure to initialize.

◆ gdHeifWriteOptionsInit()

void gdHeifWriteOptionsInit ( gdHeifWriteOptions * options )

Initialize HEIF write options with gd defaults.

Call this before changing selected gdHeifWriteOptions fields and passing the structure to gdImageHeifPtrWithOptions().

Parameters

options Pointer to the write options structure to initialize.

◆ gdImageCreateFromHeif()

gdImagePtr gdImageCreateFromHeif ( FILE * inFile )

Create a truecolor image from HEIF data in a stdio stream.

gdImageCreateFromHeif() does not close inFile. It decodes the primary image and returns a new truecolor image. On success, the returned image is owned by the caller and must be destroyed with gdImageDestroy.

Parameters

inFile Pointer to the input FILE stream.

Returns: A newly allocated truecolor image, or NULL on error.

◆ gdImageCreateFromHeifCtx()

gdImagePtr gdImageCreateFromHeifCtx ( gdIOCtxPtr infile )

Create a truecolor image from HEIF data in an IO context.

gdImageCreateFromHeifCtx() reads from infile without closing it. It decodes the primary image and returns a new truecolor image. On success, the returned image is owned by the caller and must be destroyed with gdImageDestroy.

Parameters

infile The input IO context.

Returns: A newly allocated truecolor image, or NULL on error.

◆ gdImageCreateFromHeifPtr()

gdImagePtr gdImageCreateFromHeifPtr	(	int	size,
		void *	data
	)

Create a truecolor image from HEIF data in memory.

gdImageCreateFromHeifPtr() reads size bytes from data without taking ownership of the buffer. It decodes the primary image and returns a new truecolor image. On success, the returned image is owned by the caller and must be destroyed with gdImageDestroy.

Parameters

size	Size of data in bytes.
data	Pointer to the HEIF data.

Returns: A newly allocated truecolor image, or NULL on error.

◆ gdImageCreateFromHeifPtrWithOptions()

gdImagePtr gdImageCreateFromHeifPtrWithOptions	(	int	size,
		void *	data,
		const gdHeifReadOptions *	options
	)

Create a truecolor image from HEIF data in memory using read options.

gdImageCreateFromHeifPtrWithOptions() reads size bytes from data without taking ownership of the buffer. It borrows options for the duration of the call; pass NULL for gd defaults. On success, the returned image is owned by the caller and must be destroyed with gdImageDestroy.

Parameters

size	Size of data in bytes.
data	Pointer to the HEIF data.
options	HEIF read options, or NULL for defaults.

Returns: A newly allocated truecolor image, or NULL on error.

◆ gdImageHeif()

void gdImageHeif	(	gdImagePtr	im,
		FILE *	outFile
	)

Write a truecolor image as HEIF data to a stdio stream.

gdImageHeif() uses gd's default HEIF write settings: default lossy quality, HEVC codec, and 4:4:4 chroma subsampling. The image is borrowed for the duration of the call, and outFile is not closed.

Parameters

im	The truecolor image to write.
outFile	Pointer to the output FILE stream.

◆ gdImageHeifCtx()

void gdImageHeifCtx	(	gdImagePtr	im,
		gdIOCtxPtr	outfile,
		int	quality,
		gdHeifCodec	codec,
		gdHeifChroma	chroma
	)

Write a truecolor image as HEIF data to an IO context.

gdImageHeifCtx() writes im with explicit quality, codec, and chroma settings. Quality may be 0 to 100 for lossy output, -1 for gd's default lossy quality, or 200 for lossless output. The image is borrowed for the duration of the call, and outfile is not closed.

Parameters

im	The truecolor image to write.
outfile	The output IO context.
quality	Lossy quality from 0 to 100, -1 for the default, or 200 for lossless.
codec	HEIF codec to use for output.
chroma	Chroma-subsampling string for output.

◆ gdImageHeifCtxWithOptions()

int gdImageHeifCtxWithOptions	(	gdImagePtr	im,
		gdIOCtxPtr	outfile,
		const gdHeifWriteOptions *	options
	)

Write HEIF data to a gdIOCtx using write options.

The context is borrowed and remains open. Returns 0 on success and nonzero on failure. Pass NULL for options to use gd defaults.

◆ gdImageHeifEx()

void gdImageHeifEx	(	gdImagePtr	im,
		FILE *	outFile,
		int	quality,
		gdHeifCodec	codec,
		gdHeifChroma	chroma
	)

Write a truecolor image as HEIF data to a stdio stream.

gdImageHeifEx() writes im with explicit quality, codec, and chroma settings. Quality may be 0 to 100 for lossy output, -1 for gd's default lossy quality, or 200 for lossless output. The image is borrowed for the duration of the call, and outFile is not closed.

Parameters

im	The truecolor image to write.
outFile	Pointer to the output FILE stream.
quality	Lossy quality from 0 to 100, -1 for the default, or 200 for lossless.
codec	HEIF codec to use for output.
chroma	Chroma-subsampling string for output.

◆ gdImageHeifPtr()

void * gdImageHeifPtr	(	gdImagePtr	im,
		int *	size
	)

Encode a truecolor image as HEIF data in memory.

gdImageHeifPtr() uses gd's default HEIF write settings. The image is borrowed for the duration of the call. On success, the returned buffer is owned by the caller and must be freed with gdFree().

Parameters

im	The truecolor image to encode.
size	Pointer that receives the encoded buffer size in bytes.

Returns: A newly allocated HEIF data buffer, or NULL on error.

◆ gdImageHeifPtrEx()

void * gdImageHeifPtrEx	(	gdImagePtr	im,
		int *	size,
		int	quality,
		gdHeifCodec	codec,
		gdHeifChroma	chroma
	)

Encode a truecolor image as HEIF data in memory.

gdImageHeifPtrEx() writes im with explicit quality, codec, and chroma settings. Quality may be 0 to 100 for lossy output, -1 for gd's default lossy quality, or 200 for lossless output. The image is borrowed for the duration of the call. On success, the returned buffer is owned by the caller and must be freed with gdFree().

Parameters

im	The truecolor image to encode.
size	Pointer that receives the encoded buffer size in bytes.
quality	Lossy quality from 0 to 100, -1 for the default, or 200 for lossless.
codec	HEIF codec to use for output.
chroma	Chroma-subsampling string for output.

Returns: A newly allocated HEIF data buffer, or NULL on error.

◆ gdImageHeifPtrWithOptions()

void * gdImageHeifPtrWithOptions	(	gdImagePtr	im,
		int *	size,
		const gdHeifWriteOptions *	options
	)

Encode a truecolor image as HEIF data in memory using write options.

gdImageHeifPtrWithOptions() borrows im and options for the duration of the call. Pass NULL for options to use gd defaults. On success, the returned buffer is owned by the caller and must be freed with gdFree().

Parameters

im	The truecolor image to encode.
size	Pointer that receives the encoded buffer size in bytes.
options	HEIF encoder options, or NULL for defaults.

Returns: A newly allocated HEIF data buffer, or NULL on error.

◆ gdImageHeifWithOptions()

int gdImageHeifWithOptions	(	gdImagePtr	im,
		FILE *	outFile,
		const gdHeifWriteOptions *	options
	)

Write HEIF data to a stdio stream using write options.

The stream is borrowed and remains open. Returns 0 on success and nonzero on failure. Pass NULL for options to use gd defaults.

Data Structures

HEIF Constants and Options

HEIF Reading

HEIF Writing

Detailed Description

Macro Definition Documentation

◆ GD_HEIF_CHROMA_420

◆ GD_HEIF_CHROMA_422

◆ GD_HEIF_CHROMA_444

Enumeration Type Documentation

◆ gdHeifCodec

Function Documentation

◆ gdHeifGetInfo()

◆ gdHeifInfoInit()

◆ gdHeifReadOptionsInit()

◆ gdHeifWriteOptionsInit()

◆ gdImageCreateFromHeif()

◆ gdImageCreateFromHeifCtx()

◆ gdImageCreateFromHeifPtr()

◆ gdImageCreateFromHeifPtrWithOptions()

◆ gdImageHeif()

◆ gdImageHeifCtx()

◆ gdImageHeifCtxWithOptions()

◆ gdImageHeifEx()

◆ gdImageHeifPtr()

◆ gdImageHeifPtrEx()

◆ gdImageHeifPtrWithOptions()

◆ gdImageHeifWithOptions()