GD2 IO

Read and write GD2 images.

The GD2 image format is a proprietary image format of libgd.  It has to be regarded as being obsolete, and should only be used for development and testing purposes.

Structure of a GD2 image file

  • file header
  • chunk headers (only for compressed data)
  • color header (either truecolor or palette)
  • chunks of image data (chunk-row-major, top to bottom, left to right)

All numbers are stored in big-endian format.

File header structure

signature4 bytes (always “gd2\0”)
version1 word (e.g.  “\0\002”)
width1 word
height1 word
chunk_size1 word
format1 word
x_chunk_count1 word
y_chunk_count1 word

Recognized formats

1raw palette image data
2compressed palette image data
3raw truecolor image data
4compressed truecolor image data

Chunk header

offset1 dword
size1 dword

There are x_chunk_count * y_chunk_count chunk headers.

Truecolor image color header

truecolor1 byte (always “\001”)
transparent1 dword (ARGB color)

Palette image color header

truecolor1 byte (always “\0”)
count1 word (the number of used palette colors)
transparent1 dword (ARGB color)
palette256 dwords (RGBA colors)

Chunk structure

Sequential pixel data of a rectangular area (chunk_size x chunk_size), row-major from top to bottom, left to right:

  • 1 byte per pixel for palette images
  • 1 dword (ARGB) per pixel for truecolor images

Depending on format, the chunk may be ZLIB compressed.

Summary
GD2 IORead and write GD2 images.
Functions
gdImageCreateFromGd2gdImageCreateFromGd2 is called to load images from gd2 format files.
gdImageCreateFromGd2Ptr
gdImageCreateFromGd2CtxReads in a GD2 image via a gdIOCtx struct.
gdImageCreateFromGd2PartgdImageCreateFromGd2Part is called to load parts of images from gd2 format files.
gdImageCreateFromGd2PartPtr
gdImageCreateFromGd2PartCtx
gdImageGd2
gdImageGd2Ptr

Functions

gdImageCreateFromGd2

gdImagePtr gdImageCreateFromGd2 (FILE *inFile)

gdImageCreateFromGd2 is called to load images from gd2 format files.  Invoke gdImageCreateFromGd2 with an already opened pointer to a file containing the desired image in the gd2 file format, which is specific to gd2 and intended for fast loading of parts of large images.  (It is a compressed format, but generally not as good as maximum compression of the entire image would be.)

gdImageCreateFromGd2 returns a gdImagePtr to the new image, or NULL if unable to load the image (most often because the file is corrupt or does not contain a gd format image).  gdImageCreateFromGd2 does not close the file.  You can inspect the sx and sy members of the image to determine its size.  The image must eventually be destroyed using gdImageDestroy.

Variants

gdImageCreateFromGd2Ptr creates an image from GD data (i.e. the contents of a GD2 file) already in memory.

gdImageCreateFromGd2Ctx reads in an image using the functions in a gdIOCtx struct.

Parameters

infileThe input FILE pointer

Returns

A pointer to the new image or NULL if an error occurred.

Example

gdImagePtr im;
FILE *in;
in = fopen("mygd.gd2", "rb");
im = gdImageCreateFromGd2(in);
fclose(in);
// ... Use the image ...
gdImageDestroy(im);

gdImageCreateFromGd2Ptr

gdImagePtr gdImageCreateFromGd2Ptr (int size,
void *data)

Parameters

sizesize of GD2 data in bytes.
dataGD2 data (i.e. contents of a GIF file).

See gdImageCreateFromGd2.

gdImageCreateFromGd2Ctx

gdImagePtr gdImageCreateFromGd2Ctx (gdIOCtxPtr in)

Reads in a GD2 image via a gdIOCtx struct.  See gdImageCreateFromGd2.

gdImageCreateFromGd2Part

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

gdImageCreateFromGd2Part is called to load parts of images from gd2 format files.  Invoked in the same way as gdImageCreateFromGd2, but with extra parameters indicating the source (x, y) and width/height of the desired image.  gdImageCreateFromGd2Part returns a gdImagePtr to the new image, or NULL if unable to load the image.  The image must eventually be destroyed using gdImageDestroy.

Variants

gdImageCreateFromGd2PartPtr creates an image from GD2 data (i.e. the contents of a GD2 file) already in memory.

gdImageCreateFromGd2Ctx reads in an image using the functions in a gdIOCtx struct.

Parameters

infileThe input FILE pointer
srcx, srcyThe source X and Y coordinates
w, hThe resulting image’s width and height

Returns

A pointer to the new image or NULL if an error occurred.

gdImageCreateFromGd2PartPtr

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

Parameters

sizesize of GD data in bytes.
dataGD data (i.e. contents of a GIF file).
srcx, srcyThe source X and Y coordinates
w, hThe resulting image’s width and height

Reads in part of a GD2 image file stored from memory.  See gdImageCreateFromGd2Part.

gdImageCreateFromGd2PartCtx

gdImagePtr gdImageCreateFromGd2PartCtx (gdIOCtx *in,
int srcx,
int srcy,
int w,
int h)

Parameters

inThe data source.
srcx, srcyThe source X and Y coordinates
w, hThe resulting image’s width and height

Reads in part of a GD2 data image file via a gdIOCtx struct.  See gdImageCreateFromGd2Part.

gdImageGd2

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

gdImageGd2Ptr

void * gdImageGd2Ptr (gdImagePtr im,
int cs,
int fmt,
int *size)
gdImagePtr gdImageCreateFromGd2 (FILE *inFile)
gdImageCreateFromGd2 is called to load images from gd2 format files.
gdImagePtr gdImageCreateFromGd2Ptr (int size,
void *data)
gdImagePtr gdImageCreateFromGd2Ctx (gdIOCtxPtr in)
Reads in a GD2 image via a gdIOCtx struct.
gdIOCtx structures hold function pointers for doing image IO.
gdImagePtr gdImageCreateFromGd2Part (FILE *inFile,
int srcx,
int srcy,
int w,
int h)
gdImageCreateFromGd2Part is called to load parts of images from gd2 format files.
gdImagePtr gdImageCreateFromGd2PartPtr (int size,
void *data,
int srcx,
int srcy,
int w,
int h)
gdImagePtr gdImageCreateFromGd2PartCtx (gdIOCtx *in,
int srcx,
int srcy,
int w,
int h)
void gdImageGd2 (gdImagePtr im,
FILE *outFile,
int cs,
int fmt)
void * gdImageGd2Ptr (gdImagePtr im,
int cs,
int fmt,
int *size)
The data structure in which gd stores images.
void gdImageDestroy (gdImagePtr im)
gdImageDestroy is used to free the memory associated with an image.
Close