JPEG XL image reading, writing, and animation support. More...

Collaboration diagram for JPEG XL:

Data Structures
struct	gdJxlWriteOptions
	JPEG XL still-image writer options. More...

struct	gdJxlInfo
	JPEG XL top-level file information. More...

struct	gdJxlFrameInfo
	JPEG XL raw frame information. More...

struct	gdJxlReadOptions
	JPEG XL multi-image/animation reader options. More...

struct	gdJxlAnimWriteOptions
	JPEG XL animation writer options. More...

JPEG XL File Information And Animation Types
enum	{ gdJxlBlendReplace , gdJxlBlendAdd , gdJxlBlendBlend , gdJxlBlendMuladd , gdJxlBlendMul }
	JPEG XL raw frame blend modes. More...

typedef struct gdJxlRead *	gdJxlReadPtr
	Opaque JPEG XL multi-image/animation reader handle.

typedef struct gdJxlWrite *	gdJxlWritePtr
	Opaque JPEG XL multi-image/animation writer handle.

void	gdJxlReadOptionsInit (gdJxlReadOptions *options)
	Initialize JPEG XL multi-image/animation read options with gd defaults.

void	gdJxlAnimWriteOptionsInit (gdJxlAnimWriteOptions *options)
	Initialize JPEG XL multi-image/animation write options with gd defaults.

JPEG XL Single-Image Reading
gdImagePtr	gdImageCreateFromJxl (FILE *inFile)
	Create a truecolor image from a JPEG XL stdio file.

gdImagePtr	gdImageCreateFromJxlPtr (int size, void *data)
	Create a truecolor image from a JPEG XL memory buffer.

gdImagePtr	gdImageCreateFromJxlCtx (gdIOCtxPtr infile)
	Create a truecolor image from JPEG XL data read through a gdIOCtx.

JPEG XL Single-Image Writing
void	gdImageJxl (gdImagePtr im, FILE *outFile)
	Write an image as JPEG XL data to a stdio file.

void	gdImageJxlEx (gdImagePtr im, FILE *outFile, int lossless, float distance, int effort)
	Write an image as JPEG XL data to a stdio file with encoder settings.

void *	gdImageJxlPtr (gdImagePtr im, int *size)
	Write an image as JPEG XL data to a newly allocated memory buffer.

void *	gdImageJxlPtrEx (gdImagePtr im, int *size, int lossless, float distance, int effort)
	Write an image as JPEG XL data to a newly allocated memory buffer with encoder settings.

void	gdImageJxlCtx (gdImagePtr im, gdIOCtxPtr outfile)
	Write an image as JPEG XL data to a gdIOCtx.

void	gdImageJxlCtxEx (gdImagePtr im, gdIOCtxPtr outfile, int lossless, float distance, int effort)
	Write an image as JPEG XL data to a gdIOCtx with encoder settings.

void	gdJxlWriteOptionsInit (gdJxlWriteOptions *options)
	Initialize JPEG XL still-image write options with gd defaults.

int	gdImageJxlWithOptions (gdImagePtr im, FILE outFile, const gdJxlWriteOptions options)
	Write an image as JPEG XL data to a stdio file with write options.

int	gdImageJxlCtxWithOptions (gdImagePtr im, gdIOCtxPtr outfile, const gdJxlWriteOptions *options)
	Write an image as JPEG XL data to a gdIOCtx with write options.

void *	gdImageJxlPtrWithOptions (gdImagePtr im, int size, const gdJxlWriteOptions options)
	Write an image as JPEG XL data to a newly allocated memory buffer with write options.

JPEG XL Multi-Image/Animation Reading
gdJxlReadPtr	gdJxlReadOpen (FILE inFile, const gdJxlReadOptions options)
	Open a JPEG XL multi-image/animation reader from a stdio file.

gdJxlReadPtr	gdJxlReadOpenCtx (gdIOCtxPtr inCtx, const gdJxlReadOptions *options)
	Open a JPEG XL multi-image/animation reader from a gdIOCtx.

gdJxlReadPtr	gdJxlReadOpenPtr (int size, void data, const gdJxlReadOptions options)
	Open a JPEG XL multi-image/animation reader from a memory buffer.

int	gdJxlReadGetInfo (gdJxlReadPtr reader, gdJxlInfo *info)
	Get JPEG XL image or animation information from a reader.

int	gdJxlReadGetMetadata (gdJxlReadPtr reader, gdImageMetadata *metadata)
	Extract supported still-image metadata from a JPEG XL reader.

int	gdJxlReadNextImage (gdJxlReadPtr reader, int delay_ms, gdImagePtr image)
	Read the next coalesced JPEG XL image.

int	gdJxlReadNextFrame (gdJxlReadPtr reader, gdJxlFrameInfo info, gdImagePtr frame)
	Read the next raw JPEG XL frame rectangle.

void	gdJxlReadClose (gdJxlReadPtr reader)
	Close a JPEG XL multi-image reader.

JPEG XL Multi-Image/Animation Writing
gdJxlWritePtr	gdJxlWriteOpen (FILE outFile, const gdJxlAnimWriteOptions options)
	Open a JPEG XL multi-image/animation writer for a stdio file.

gdJxlWritePtr	gdJxlWriteOpenCtx (gdIOCtxPtr outCtx, const gdJxlAnimWriteOptions *options)
	Open a JPEG XL multi-image/animation writer for a gdIOCtx.

gdJxlWritePtr	gdJxlWriteOpenPtr (const gdJxlAnimWriteOptions *options)
	Open a JPEG XL multi-image/animation writer that returns a memory buffer.

int	gdJxlWriteAddImage (gdJxlWritePtr writer, gdImagePtr image, int delay_ms)
	Add a full-canvas image to a JPEG XL multi-image/animation writer.

void	gdJxlWriteClose (gdJxlWritePtr writer)
	Add a full-canvas image to a JPEG XL multi-image/animation writer.

void *	gdJxlWritePtrFinish (gdJxlWritePtr writer, int *size)
	Finish a JPEG XL multi-image/animation memory writer and return the encoded buffer.

Detailed Description

JPEG XL image reading, writing, and animation support.

JPEG XL support reads still images as truecolor gd images and writes still images with either lossy distance settings or lossless encoding. Animation readers can return coalesced full-canvas images or raw frame rectangles, and animation writers accept full-canvas truecolor frames.

gdImagePtr first, second, image;
gdJxlAnimWriteOptions write_options;
gdJxlWritePtr writer;
gdJxlReadPtr reader;
void *data;
int size, delay_ms, result;
 
first = gdImageCreateTrueColor(32, 24);
second = gdImageCreateTrueColor(32, 24);
if (first == NULL || second == NULL) {
  exit(1);
}
 
gdImageFilledRectangle(first, 0, 0, 31, 23, gdTrueColor(255, 0, 0));
gdImageFilledRectangle(second, 0, 0, 31, 23, gdTrueColor(0, 0, 255));
 
gdJxlAnimWriteOptionsInit(&write_options);
write_options.lossless = 1;
write_options.loopCount = 0;
writer = gdJxlWriteOpenPtr(&write_options);
if (writer == NULL) {
  gdImageDestroy(first);
  gdImageDestroy(second);
  exit(1);
}
gdJxlWriteAddImage(writer, first, 120);
gdJxlWriteAddImage(writer, second, 80);
data = gdJxlWritePtrFinish(writer, &size);
 
reader = gdJxlReadOpenPtr(size, data, NULL);
while ((result = gdJxlReadNextImage(reader, &delay_ms, &image)) == 1) {
  gdImageDestroy(image);
}
gdJxlReadClose(reader);
gdFree(data);
gdImageDestroy(first);
gdImageDestroy(second);

Typedef Documentation

◆ gdJxlReadPtr

typedef struct gdJxlRead* gdJxlReadPtr

Opaque JPEG XL multi-image/animation reader handle.

Handles returned by gdJxlReadOpen, gdJxlReadOpenCtx(), or gdJxlReadOpenPtr must be closed with gdJxlReadClose.

◆ gdJxlWritePtr

typedef struct gdJxlWrite* gdJxlWritePtr

Opaque JPEG XL multi-image/animation writer handle.

Handles returned by gdJxlWriteOpen or gdJxlWriteOpenCtx must be closed with gdJxlWriteClose. Handles returned by gdJxlWriteOpenPtr must be finished with gdJxlWritePtrFinish.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

JPEG XL raw frame blend modes.

Enumerator
gdJxlBlendReplace	Replace the frame rectangle with the new frame.
gdJxlBlendAdd	Add the new frame to the existing canvas.
gdJxlBlendBlend	Blend the new frame over the existing canvas.
gdJxlBlendMuladd	Multiply then add the new frame with the existing canvas.
gdJxlBlendMul	Multiply the new frame with the existing canvas.

Function Documentation

◆ gdImageCreateFromJxl()

gdImagePtr gdImageCreateFromJxl ( FILE * inFile )

Create a truecolor image from a JPEG XL stdio file.

gdImageCreateFromJxl() does not close inFile. The returned image is caller-owned and must be destroyed with gdImageDestroy.

Parameters

inFile Pointer to the input FILE stream.

Returns: Returns a gdImagePtr on success, or NULL on failure.

◆ gdImageCreateFromJxlCtx()

gdImagePtr gdImageCreateFromJxlCtx ( gdIOCtxPtr infile )

Create a truecolor image from JPEG XL data read through a gdIOCtx.

gdImageCreateFromJxlCtx() does not close infile. The returned image is caller-owned and must be destroyed with gdImageDestroy.

Parameters

infile Pointer to the gdIOCtx input context.

Returns: Returns a gdImagePtr on success, or NULL on failure.

◆ gdImageCreateFromJxlPtr()

gdImagePtr gdImageCreateFromJxlPtr	(	int	size,
		void *	data
	)

Create a truecolor image from a JPEG XL memory buffer.

The data buffer is borrowed for the duration of the call. The returned image is caller-owned and must be destroyed with gdImageDestroy.

Parameters

size	Size of the JPEG XL memory buffer in bytes.
data	Pointer to the JPEG XL memory buffer.

Returns: Returns a gdImagePtr on success, or NULL on failure.

◆ gdImageJxl()

void gdImageJxl	(	gdImagePtr	im,
		FILE *	outFile
	)

Write an image as JPEG XL data to a stdio file.

gdImageJxl() does not close outFile. The image is borrowed for the duration of the call; palette images may be converted to truecolor internally.

Parameters

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

◆ gdImageJxlCtx()

void gdImageJxlCtx	(	gdImagePtr	im,
		gdIOCtxPtr	outfile
	)

Write an image as JPEG XL data to a gdIOCtx.

gdImageJxlCtx() does not close outfile. The image is borrowed for the duration of the call; palette images may be converted to truecolor internally.

Parameters

im	The image to write.
outfile	Pointer to the gdIOCtx output context.

◆ gdImageJxlCtxEx()

void gdImageJxlCtxEx	(	gdImagePtr	im,
		gdIOCtxPtr	outfile,
		int	lossless,
		float	distance,
		int	effort
	)

Write an image as JPEG XL data to a gdIOCtx with encoder settings.

gdImageJxlCtxEx() does not close outfile. The image is borrowed for the duration of the call; palette images may be converted to truecolor internally.

Parameters

im	The image to write.
outfile	Pointer to the gdIOCtx output context.
lossless	Non-zero to use lossless JPEG XL encoding.
distance	Lossy encoding distance when lossless is zero.
effort	Encoder effort setting.

◆ gdImageJxlCtxWithOptions()

int gdImageJxlCtxWithOptions	(	gdImagePtr	im,
		gdIOCtxPtr	outfile,
		const gdJxlWriteOptions *	options
	)

Write an image as JPEG XL data to a gdIOCtx with write options.

Parameters

im	The image to write.
outfile	Pointer to the gdIOCtx output context.
options	Pointer to the JPEG XL write options.

Returns: Returns non-zero on success, or zero on failure.

◆ gdImageJxlEx()

void gdImageJxlEx	(	gdImagePtr	im,
		FILE *	outFile,
		int	lossless,
		float	distance,
		int	effort
	)

Write an image as JPEG XL data to a stdio file with encoder settings.

gdImageJxlEx() does not close outFile. The image is borrowed for the duration of the call; palette images may be converted to truecolor internally.

Parameters

im	The image to write.
outFile	Pointer to the output FILE stream.
lossless	Non-zero to use lossless JPEG XL encoding.
distance	Lossy encoding distance when lossless is zero.
effort	Encoder effort setting.

◆ gdImageJxlPtr()

void * gdImageJxlPtr	(	gdImagePtr	im,
		int *	size
	)

Write an image as JPEG XL data to a newly allocated memory buffer.

The image is borrowed for the duration of the call; palette images may be converted to truecolor internally. The returned buffer is caller-owned and must be freed with gdFree().

Parameters

im	The image to write.
size	Pointer to an integer that receives the returned buffer size.

Returns: Returns a pointer to the newly allocated JPEG XL buffer, or NULL on failure.

◆ gdImageJxlPtrEx()

void * gdImageJxlPtrEx	(	gdImagePtr	im,
		int *	size,
		int	lossless,
		float	distance,
		int	effort
	)

Write an image as JPEG XL data to a newly allocated memory buffer with encoder settings.

The image is borrowed for the duration of the call; palette images may be converted to truecolor internally. The returned buffer is caller-owned and must be freed with gdFree().

Parameters

im	The image to write.
size	Pointer to an integer that receives the returned buffer size.
lossless	Non-zero to use lossless JPEG XL encoding.
distance	Lossy encoding distance when lossless is zero.
effort	Encoder effort setting.

Returns: Returns a pointer to the newly allocated JPEG XL buffer, or NULL on failure.

◆ gdImageJxlPtrWithOptions()

void * gdImageJxlPtrWithOptions	(	gdImagePtr	im,
		int *	size,
		const gdJxlWriteOptions *	options
	)

Write an image as JPEG XL data to a newly allocated memory buffer with write options.

The image is borrowed for the duration of the call; palette images may be converted to truecolor internally. The returned buffer is caller-owned and must be freed with gdFree().

Parameters

im	The image to write.
size	Pointer to an integer that receives the returned buffer size.
options	Pointer to the JPEG XL write options.

Returns: Returns a pointer to the newly allocated memory buffer, or NULL on failure.

◆ gdImageJxlWithOptions()

int gdImageJxlWithOptions	(	gdImagePtr	im,
		FILE *	outFile,
		const gdJxlWriteOptions *	options
	)

Write an image as JPEG XL data to a stdio file with write options.

Parameters

im	The image to write.
outFile	Pointer to the output FILE stream.
options	Pointer to the JPEG XL write options.

Returns: Returns non-zero on success, or zero on failure.

◆ gdJxlAnimWriteOptionsInit()

void gdJxlAnimWriteOptionsInit ( gdJxlAnimWriteOptions * options )

Initialize JPEG XL multi-image/animation write options with gd defaults.

The default writer infers the canvas size from the first frame, writes lossy JPEG XL with distance 1.0 and effort 7, and uses loopCount 0 for infinite looping.

Parameters

options Pointer to the write options structure to initialize.

◆ gdJxlReadClose()

void gdJxlReadClose ( gdJxlReadPtr reader )

Close a JPEG XL multi-image reader.

Parameters

reader JPEG XL reader handle to close, or NULL.

◆ gdJxlReadGetInfo()

int gdJxlReadGetInfo	(	gdJxlReadPtr	reader,
		gdJxlInfo *	info
	)

Get JPEG XL image or animation information from a reader.

The returned gdJxlInfo describes the canvas size and animation loop count reported by the JPEG XL stream.

Parameters

reader	JPEG XL reader handle.
info	Pointer to a gdJxlInfo structure to receive image information.

Returns: Returns 1 on success, or 0 on failure.

◆ gdJxlReadGetMetadata()

int gdJxlReadGetMetadata	(	gdJxlReadPtr	reader,
		gdImageMetadata *	metadata
	)

Extract supported still-image metadata from a JPEG XL reader.

The caller owns the metadata object. Animation metadata is not exposed.

◆ gdJxlReadNextFrame()

int gdJxlReadNextFrame	(	gdJxlReadPtr	reader,
		gdJxlFrameInfo *	info,
		gdImagePtr *	frame
	)

Read the next raw JPEG XL frame rectangle.

This function is used with non-coalesced readers. When frame is not NULL and the function returns 1, *frame receives a caller-owned truecolor frame rectangle that must be destroyed with gdImageDestroy. Passing NULL for frame advances the reader without returning the decoded image.

Parameters

reader	JPEG XL reader handle opened with raw-frame mode.
info	Pointer to receive raw frame information.
frame	Pointer to receive the caller-owned frame image, or NULL.

Returns: Returns 1 when a frame is read, 0 at end of stream, or -1 on error.

◆ gdJxlReadNextImage()

int gdJxlReadNextImage	(	gdJxlReadPtr	reader,
		int *	delay_ms,
		gdImagePtr *	image
	)

Read the next coalesced JPEG XL image.

This function is used with coalesced readers. When image is not NULL and the function returns 1, *image receives a caller-owned full-canvas truecolor image that must be destroyed with gdImageDestroy. Passing NULL for image advances the reader without returning the decoded image.

Parameters

reader	JPEG XL reader handle opened with coalesced mode.
delay_ms	Pointer to receive the frame duration in milliseconds, or NULL.
image	Pointer to receive the caller-owned image, or NULL.

Returns: Returns 1 when an image is read, 0 at end of stream, or -1 on error.

◆ gdJxlReadOpen()

gdJxlReadPtr gdJxlReadOpen	(	FILE *	inFile,
		const gdJxlReadOptions *	options
	)

Open a JPEG XL multi-image/animation reader from a stdio file.

gdJxlReadOpen() reads the JPEG XL data into the reader and does not close inFile. Pass NULL for options to use gd defaults. The returned handle must be closed with gdJxlReadClose().

Parameters

inFile	Pointer to the input FILE stream.
options	Pointer to read options, or NULL for defaults.

Returns: Returns a JPEG XL reader handle on success, or NULL on failure.

◆ gdJxlReadOpenCtx()

gdJxlReadPtr gdJxlReadOpenCtx	(	gdIOCtxPtr	inCtx,
		const gdJxlReadOptions *	options
	)

Open a JPEG XL multi-image/animation reader from a gdIOCtx.

gdJxlReadOpenCtx() reads the JPEG XL data into the reader and does not close inCtx. Pass NULL for options to use gd defaults. The returned handle must be closed with gdJxlReadClose().

Parameters

inCtx	Pointer to the gdIOCtx input context.
options	Pointer to read options, or NULL for defaults.

Returns: Returns a JPEG XL reader handle on success, or NULL on failure.

◆ gdJxlReadOpenPtr()

gdJxlReadPtr gdJxlReadOpenPtr	(	int	size,
		void *	data,
		const gdJxlReadOptions *	options
	)

Open a JPEG XL multi-image/animation reader from a memory buffer.

The data buffer is borrowed for the duration of the call. Pass NULL for options to use gd defaults. The returned handle owns its copy of the JPEG XL data and must be closed with gdJxlReadClose.

Parameters

size	Size of the JPEG XL memory buffer in bytes.
data	Pointer to the JPEG XL memory buffer.
options	Pointer to read options, or NULL for defaults.

Returns: Returns a JPEG XL reader handle on success, or NULL on failure.

◆ gdJxlReadOptionsInit()

void gdJxlReadOptionsInit ( gdJxlReadOptions * options )

Initialize JPEG XL multi-image/animation read options with gd defaults.

The default reader mode is coalesced, so gdJxlReadNextImage returns full-canvas rendered images. Set gdJxlReadOptions::coalesced to zero before opening the reader to read raw frame rectangles with gdJxlReadNextFrame.

Parameters

options Pointer to the read options structure to initialize.

◆ gdJxlWriteAddImage()

int gdJxlWriteAddImage	(	gdJxlWritePtr	writer,
		gdImagePtr	image,
		int	delay_ms
	)

Add a full-canvas image to a JPEG XL multi-image/animation writer.

The image is borrowed for the duration of the call and remains owned by the caller. The image must be truecolor. All images must match the resolved canvas size; when the writer canvas is zero, the first image sets it.

Parameters

writer	JPEG XL writer handle.
image	Image to add as the next frame.
delay_ms	Frame duration in milliseconds.

Returns: Returns 1 on success, or 0 on failure.

◆ gdJxlWriteClose()

void gdJxlWriteClose ( gdJxlWritePtr writer )

Add a full-canvas image to a JPEG XL multi-image/animation writer.

Use this for handles returned by gdJxlWriteOpen() or gdJxlWriteOpenCtx(). For memory writers returned by gdJxlWriteOpenPtr, use gdJxlWritePtrFinish.

Parameters

writer JPEG XL writer handle to finish and close, or NULL.

◆ gdJxlWriteOpen()

gdJxlWritePtr gdJxlWriteOpen	(	FILE *	outFile,
		const gdJxlAnimWriteOptions *	options
	)

Open a JPEG XL multi-image/animation writer for a stdio file.

gdJxlWriteOpen does not close outFile. Pass NULL for options to use gd defaults. The returned handle must be closed with gdJxlWriteClose.

Parameters

outFile	Pointer to the output FILE stream.
options	Pointer to write options, or NULL for defaults.

Returns: Returns a JPEG XL writer handle on success, or NULL on failure.

◆ gdJxlWriteOpenCtx()

gdJxlWritePtr gdJxlWriteOpenCtx	(	gdIOCtxPtr	outCtx,
		const gdJxlAnimWriteOptions *	options
	)

Open a JPEG XL multi-image/animation writer for a gdIOCtx.

The output context is borrowed and is not closed by gdJxlWriteClose. Pass NULL for options to use gd defaults. The returned handle must be closed with gdJxlWriteClose.

Parameters

outCtx	Pointer to the gdIOCtx output context.
options	Pointer to write options, or NULL for defaults.

Returns: Returns a JPEG XL writer handle on success, or NULL on failure.

◆ gdJxlWriteOpenPtr()

gdJxlWritePtr gdJxlWriteOpenPtr ( const gdJxlAnimWriteOptions * options )

Open a JPEG XL multi-image/animation writer that returns a memory buffer.

Pass NULL for options to use gd defaults. The returned handle must be finished with gdJxlWritePtrFinish.

Parameters

options Pointer to write options, or NULL for defaults.

Returns: Returns a JPEG XL memory writer handle on success, or NULL on failure.

◆ gdJxlWriteOptionsInit()

void gdJxlWriteOptionsInit ( gdJxlWriteOptions * options )

Initialize JPEG XL still-image write options with gd defaults.

Parameters

options Pointer to the write options structure to initialize.

◆ gdJxlWritePtrFinish()

void * gdJxlWritePtrFinish	(	gdJxlWritePtr	writer,
		int *	size
	)

Finish a JPEG XL multi-image/animation memory writer and return the encoded buffer.

This closes writer whether encoding succeeds or fails. The returned buffer is caller-owned and must be freed with gdFree().

Parameters

writer	JPEG XL memory writer handle returned by gdJxlWriteOpenPtr.
size	Pointer to an integer that receives the returned buffer size.

Returns: Returns a pointer to the newly allocated JPEG XL buffer, or NULL on failure.

Data Structures

JPEG XL File Information And Animation Types

JPEG XL Single-Image Reading

JPEG XL Single-Image Writing

JPEG XL Multi-Image/Animation Reading

JPEG XL Multi-Image/Animation Writing

Detailed Description

Typedef Documentation

◆ gdJxlReadPtr

◆ gdJxlWritePtr

Enumeration Type Documentation

◆ anonymous enum

Function Documentation

◆ gdImageCreateFromJxl()

◆ gdImageCreateFromJxlCtx()

◆ gdImageCreateFromJxlPtr()

◆ gdImageJxl()

◆ gdImageJxlCtx()

◆ gdImageJxlCtxEx()

◆ gdImageJxlCtxWithOptions()

◆ gdImageJxlEx()

◆ gdImageJxlPtr()

◆ gdImageJxlPtrEx()

◆ gdImageJxlPtrWithOptions()

◆ gdImageJxlWithOptions()

◆ gdJxlAnimWriteOptionsInit()

◆ gdJxlReadClose()

◆ gdJxlReadGetInfo()

◆ gdJxlReadGetMetadata()

◆ gdJxlReadNextFrame()

◆ gdJxlReadNextImage()

◆ gdJxlReadOpen()

◆ gdJxlReadOpenCtx()

◆ gdJxlReadOpenPtr()

◆ gdJxlReadOptionsInit()

◆ gdJxlWriteAddImage()

◆ gdJxlWriteClose()

◆ gdJxlWriteOpen()

◆ gdJxlWriteOpenCtx()

◆ gdJxlWriteOpenPtr()

◆ gdJxlWriteOptionsInit()

◆ gdJxlWritePtrFinish()