GD2

Read and write libgd's chunked native .gd2 image format. More...

Collaboration diagram for GD2:

GD2 Reading
gdImagePtr	gdImageCreateFromGd2 (FILE *in)
	Create an image from a GD2 stdio file.
gdImagePtr	gdImageCreateFromGd2Ctx (gdIOCtxPtr in)
	Create an image from GD2 data read through a gdIOCtx.
gdImagePtr	gdImageCreateFromGd2Ptr (int size, void *data)
	Create an image from a GD2 memory buffer.
gdImagePtr	gdImageCreateFromGd2Part (FILE *in, int srcx, int srcy, int w, int h)
	Create an image from a rectangular region of a GD2 stdio file.
gdImagePtr	gdImageCreateFromGd2PartCtx (gdIOCtxPtr in, int srcx, int srcy, int w, int h)
	Create an image from a rectangular GD2 region read through a gdIOCtx.
gdImagePtr	gdImageCreateFromGd2PartPtr (int size, void *data, int srcx, int srcy, int w, int h)
	Create an image from a rectangular region of a GD2 memory buffer.

GD2 Writing
void	gdImageGd2 (gdImagePtr im, FILE *out, int cs, int fmt)
	Write an image as GD2 data to a stdio file.
void *	gdImageGd2Ptr (gdImagePtr im, int cs, int fmt, int *size)
	Write an image as GD2 data to a newly allocated memory buffer.

GD2 Constants
#define	GD2_CHUNKSIZE   128
#define	GD2_CHUNKSIZE_MIN   64
#define	GD2_CHUNKSIZE_MAX   4096
#define	GD2_VERS   2
#define	GD2_ID   "gd2"
#define	GD2_FMT_RAW   1
#define	GD2_FMT_COMPRESSED   2

Detailed Description

Read and write libgd's chunked native .gd2 image format.

Deprecated:

GD and GD2 formats are in favor of more suitable and future proof like QOI or WebP for lossless usage or similar.

GD2 is libgd's historical chunked image dump format. It is obsolete for general interchange and should generally be used only for development, testing, or compatibility with existing .gd2 assets. Unlike the simpler GD format, GD2 stores image data in chunks and can read a rectangular region without decoding the entire image. Compressed GD2 support requires libz; when GD2 support is not available the functions fail and report an error through gd's error mechanism.

GD2 readers accept palette and truecolor GD2 files. The whole-image readers return the full image, while the part readers return a newly allocated image containing the requested rectangle. Returned gdImagePtr images are owned by the caller and must be destroyed with gdImageDestroy. The writer emits GD2 data using a public format selector of GD2_FMT_RAW or GD2_FMT_COMPRESSED; truecolor images are written with the corresponding internal truecolor GD2 format automatically.

gdImagePtr im, roundtrip;
void *data;
int size;
 
im = gdImageCreate(100, 100);
gdImageColorAllocate(im, 255, 255, 255);
gdImageColorAllocate(im, 0, 0, 0);
gdImageLine(im, 0, 0, 99, 99, 1);
 
data = gdImageGd2Ptr(im, GD2_CHUNKSIZE, GD2_FMT_COMPRESSED, &size);
if (data != NULL) {
       roundtrip = gdImageCreateFromGd2PartPtr(size, data, 0, 0, 50, 50);
       gdFree(data);
       if (roundtrip != NULL) {
               gdImageDestroy(roundtrip);
       }
}
 
gdImageDestroy(im);

Macro Definition Documentation

GD2_CHUNKSIZE

#define GD2_CHUNKSIZE   128

Default GD2 chunk size in pixels.

GD2_CHUNKSIZE_MAX

#define GD2_CHUNKSIZE_MAX   4096

Maximum accepted GD2 chunk size in pixels.

GD2_CHUNKSIZE_MIN

#define GD2_CHUNKSIZE_MIN   64

Minimum accepted GD2 chunk size in pixels.

GD2_FMT_COMPRESSED

#define GD2_FMT_COMPRESSED   2

Write zlib-compressed GD2 chunks.

GD2_FMT_RAW

#define GD2_FMT_RAW   1

Write uncompressed GD2 chunks.

GD2_ID

#define GD2_ID   "gd2"

GD2 file signature string.

GD2_VERS

#define GD2_VERS   2

Current GD2 file format version written by gd.

Function Documentation

gdImageCreateFromGd2()

gdImagePtr gdImageCreateFromGd2

(

FILE *

in

)

Create an image from a GD2 stdio file.

gdImageCreateFromGd2() reads from the current position of in and does not close it. On success, the returned image is owned by the caller and must be destroyed with gdImageDestroy.

Parameters

in	Pointer to the GD2 FILE stream to read.

Returns

A newly allocated image, or NULL on error.

gdImageCreateFromGd2Ctx()

gdImagePtr gdImageCreateFromGd2Ctx

(

gdIOCtxPtr

in

)

Create an image from GD2 data read through a gdIOCtx.

gdImageCreateFromGd2Ctx() reads from in and does not close it. On success, the returned image is owned by the caller and must be destroyed with gdImageDestroy.

Parameters

in	Pointer to the gdIOCtx input context.

Returns

A newly allocated image, or NULL on error.

gdImageCreateFromGd2Part()

gdImagePtr gdImageCreateFromGd2Part	(	FILE *	in,
		int	srcx,
		int	srcy,
		int	w,
		int	h
	)

Create an image from a rectangular region of a GD2 stdio file.

gdImageCreateFromGd2Part() reads the region beginning at srcx, srcy with dimensions w by h. The input stream is borrowed and is not closed by gd. On success, the returned image is owned by the caller and must be destroyed with gdImageDestroy.

Parameters

in	Pointer to the GD2 FILE stream to read.
srcx	Left coordinate of the source rectangle.
srcy	Top coordinate of the source rectangle.
w	Width of the source rectangle in pixels.
h	Height of the source rectangle in pixels.

Returns

A newly allocated image containing the requested region, or NULL on error.

gdImageCreateFromGd2PartCtx()

gdImagePtr gdImageCreateFromGd2PartCtx	(	gdIOCtxPtr	in,
		int	srcx,
		int	srcy,
		int	w,
		int	h
	)

Create an image from a rectangular GD2 region read through a gdIOCtx.

gdImageCreateFromGd2PartCtx() reads the region beginning at srcx, srcy with dimensions w by h. The input context is borrowed and is not closed by gd. On success, the returned image is owned by the caller and must be destroyed with gdImageDestroy.

Parameters

in	Pointer to the gdIOCtx input context.
srcx	Left coordinate of the source rectangle.
srcy	Top coordinate of the source rectangle.
w	Width of the source rectangle in pixels.
h	Height of the source rectangle in pixels.

Returns

A newly allocated image containing the requested region, or NULL on error.

gdImageCreateFromGd2PartPtr()

gdImagePtr gdImageCreateFromGd2PartPtr	(	int	size,
		void *	data,
		int	srcx,
		int	srcy,
		int	w,
		int	h
	)

Create an image from a rectangular region of a GD2 memory buffer.

gdImageCreateFromGd2PartPtr() borrows data for the duration of the call. The caller retains ownership of the input buffer. On success, the returned image is owned by the caller and must be destroyed with gdImageDestroy.

Parameters

size	Size of the GD2 memory buffer in bytes.
data	Pointer to the GD2 memory buffer.
srcx	Left coordinate of the source rectangle.
srcy	Top coordinate of the source rectangle.
w	Width of the source rectangle in pixels.
h	Height of the source rectangle in pixels.

Returns

A newly allocated image containing the requested region, or NULL on error.

gdImageCreateFromGd2Ptr()

gdImagePtr gdImageCreateFromGd2Ptr	(	int	size,
		void *	data
	)

Create an image from a GD2 memory buffer.

gdImageCreateFromGd2Ptr() borrows data for the duration of the call. The caller retains ownership of the input buffer. On success, the returned image is owned by the caller and must be destroyed with gdImageDestroy.

Parameters

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

Returns

A newly allocated image, or NULL on error.

gdImageGd2()

void gdImageGd2	(	gdImagePtr	im,
		FILE *	out,
		int	cs,
		int	fmt
	)

Write an image as GD2 data to a stdio file.

Deprecated:

gdImageGd2() borrows im and out for the duration of the call and does not close out. Pass cs as 0 to use GD2_CHUNKSIZE; otherwise values outside the GD2_CHUNKSIZE_MIN to GD2_CHUNKSIZE_MAX range are clamped. The public fmt values are GD2_FMT_RAW and GD2_FMT_COMPRESSED. For truecolor images, gd writes the corresponding internal truecolor GD2 format automatically.

Parameters

im	The image to write.
out	Pointer to the output FILE stream.
cs	Requested chunk size in pixels, or 0 for GD2_CHUNKSIZE.
fmt	Output format, GD2_FMT_RAW or GD2_FMT_COMPRESSED.

gdImageGd2Ptr()

void * gdImageGd2Ptr	(	gdImagePtr	im,
		int	cs,
		int	fmt,
		int *	size
	)

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

Deprecated:

gdImageGd2Ptr() borrows im for the duration of the call. Pass cs as 0 to use GD2_CHUNKSIZE; otherwise values outside the GD2_CHUNKSIZE_MIN to GD2_CHUNKSIZE_MAX range are clamped. The public fmt values are GD2_FMT_RAW and GD2_FMT_COMPRESSED. On success, the returned buffer is owned by the caller and must be freed with gdFree().

Parameters

im	The image to write.
cs	Requested chunk size in pixels, or 0 for GD2_CHUNKSIZE.
fmt	Output format, GD2_FMT_RAW or GD2_FMT_COMPRESSED.
size	Output location for the returned buffer size in bytes.

Returns

A newly allocated GD2 buffer, or NULL on error.