Image File Convenience APIs

Convenience APIs for reading and writing images by filename or signature. More...

Macros
#define	GD_IMAGE_READ_RESTRICT_CODEC_API   1

Enumerations
enum	gdImageReadStatus {   gdImageReadStatusOk = 0 , gdImageReadStatusUnrecognized , gdImageReadStatusUnsupportedFormat , gdImageReadStatusCodecUnavailable ,   gdImageReadStatusDecodeFailed }
	Status values for extended automatic image readers. More...

Functions
gdImagePtr	gdImageCreateFromFile (const char *filename)
	Create an image from a file using the filename extension.
gdImagePtr	gdImageReadFile (const char *filename)
	Read an image file by probing its binary signature.
gdImagePtr	gdImageReadCtx (gdIOCtxPtr ctx)
	Read an image from a gdIOCtx by probing its binary signature.
gdImagePtr	gdImageReadCtxEx (gdIOCtxPtr ctx, int flags, gdImageReadStatus *status, const char **format_name)
	Read an image from a gdIOCtx with extended status information.
int	gdImageFile (gdImagePtr im, const char *filename)
	Write an image to a file in the format indicated by the filename.
int	gdSupportsFileType (const char *filename, int writing)
	Test if a given file type is supported by GD.

Detailed Description

Convenience APIs for reading and writing images by filename or signature.

These APIs are helpers around the format-specific codec functions. For reading existing files, gdImageReadFile is preferred over gdImageCreateFromFile because it detects image type from binary signatures rather than trusting the filename extension.

Macro Definition Documentation

GD_IMAGE_READ_RESTRICT_CODEC_API

#define GD_IMAGE_READ_RESTRICT_CODEC_API   1

Restrict extended automatic reading to codec APIs that match the input source.

Enumeration Type Documentation

gdImageReadStatus

enum gdImageReadStatus

Status values for extended automatic image readers.

Enumerator
gdImageReadStatusOk	The image was read successfully.
gdImageReadStatusUnrecognized	No known binary signature matched the input.
gdImageReadStatusUnsupportedFormat	The signature matched a format that cannot be read through the requested API.
gdImageReadStatusCodecUnavailable	The matching codec is not available in this gd build.
gdImageReadStatusDecodeFailed	The matching codec was available but failed to decode the image.

Function Documentation

gdImageCreateFromFile()

gdImagePtr gdImageCreateFromFile

(

const char *

filename

)

Create an image from a file using the filename extension.

gdImageCreateFromFile() chooses the reader from the filename extension using the same extension table as gdSupportsFileType. The returned image is caller-owned and must be destroyed with gdImageDestroy().

Note

For new code, prefer gdImageReadFile when reading existing files. gdImageReadFile() checks binary signatures instead of trusting the filename extension, which is safer and more reliable when files are mislabeled or supplied by users.

Parameters

filename

Path to the input image file.

Returns

A newly allocated image, or NULL on error or unsupported extension.

gdImageFile()

int gdImageFile	(	gdImagePtr	im,
		const char *	filename
	)

Write an image to a file in the format indicated by the filename.

File type is determined by the extension of the file name. See gdSupportsFileType for an overview of the parsing. This is appropriate for writing, where the filename normally chooses the intended output format.

For file types that require extra arguments, gdImageFile() attempts to use sane defaults:

• gdImageGd2 - chunk size = 0, compression is enabled.
• gdImageJpeg - quality = -1 (i.e. the reasonable default)
• gdImageWBMP - foreground is the darkest available color

Everything else is called with the two-argument function and so will use the default values. gdImageFile has some rudimentary error detection and will return GD_FALSE (0) if a detectable error occurred. However, the image loaders do not normally return their error status so a result of GD_TRUE (1) does not mean the file was saved successfully.

Parameters

im	The image to save.
filename	The path to the file to which the image is saved.

Returns

GD_TRUE on apparent success, or GD_FALSE if the filename extension is unsupported or the output file could not be opened.

gdImageReadCtx()

gdImagePtr gdImageReadCtx

(

gdIOCtxPtr

ctx

)

Read an image from a gdIOCtx by probing its binary signature.

gdImageReadCtx() borrows ctx for the duration of the call and does not close it. The input context must support seeking because gd reads a probe buffer and then seeks back to the start before dispatching to the codec reader. Formats without gdIOCtx readers, currently XPM and XBM, are not supported by this function; use gdImageReadFile for those file formats.

The returned image is caller-owned and must be destroyed with gdImageDestroy().

Parameters

ctx	Pointer to the input gdIOCtx.

Returns

A newly allocated image, or NULL on error, unknown format, disabled codec, unsupported context reader, or decode failure.

gdImageReadCtxEx()

gdImagePtr gdImageReadCtxEx	(	gdIOCtxPtr	ctx,
		int	flags,
		gdImageReadStatus *	status,
		const char **	format_name
	)

Read an image from a gdIOCtx with extended status information.

gdImageReadCtxEx() is the extended form of gdImageReadCtx. It accepts option flags and can report a gdImageReadStatus value and detected format name to the caller. The input context is borrowed for the duration of the call and is not closed.

Parameters

ctx	Pointer to the input gdIOCtx.
flags	Bitmask of GD_IMAGE_READ_* flags.
status	Optional pointer that receives the read status.
format_name	Optional pointer that receives the detected format name.

Returns

A newly allocated image, or NULL on error.

gdImageReadFile()

gdImagePtr gdImageReadFile

(

const char *

filename

)

Read an image file by probing its binary signature.

gdImageReadFile() opens filename, reads the first bytes of the file, detects the image format by known binary signatures, and dispatches to the matching codec reader. It falls back to the filename-based XPM reader and FILE-based XBM reader for those formats because they do not have gdIOCtx readers.

Supported detected formats depend on the codecs compiled into gd and include PNG, JPEG, GIF, BMP, TIFF, WebP, AVIF, HEIC, JXL, GD, GD2, QOI, XPM, and XBM. The returned image is caller-owned and must be destroyed with gdImageDestroy().

Parameters

filename

Path to the input image file.

Returns

A newly allocated image, or NULL on error, unknown format, disabled codec, or decode failure.

gdSupportsFileType()

int gdSupportsFileType	(	const char *	filename,
		int	writing
	)

Test if a given file type is supported by GD.

gdSupportsFileType() tests the filename extension using the same extension table as gdImageCreateFromFile and gdImageFile. The file does not need to exist. If writing is nonzero, the function returns true only when gdImageFile() can write that extension; otherwise it returns true when gdImageCreateFromFile() can read that extension.

Extension parsing has the same limitations as the extension-based helpers. Use gdImageReadFile when reading an actual file and reliable format detection matters.

Parameters

filename	Filename whose extension should be tested.
writing	Nonzero to test write support; zero to test read support.

Returns

GD_TRUE (1) if the file type is supported, GD_FALSE (0) if not.