# 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

signature | 4 bytes (always “gd2\0”)
version | 1 word (e.g. “\0\002”)
width | 1 word
height | 1 word
chunk_size | 1 word
format | 1 word
x_chunk_count | 1 word
y_chunk_count | 1 word

#### Recognized formats

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

#### Chunk header

offset | 1 dword
size | 1 dword

There are x_chunk_count * y_chunk_count chunk headers.

#### Truecolor image color header

truecolor | 1 byte (always “\001”)
transparent | 1 dword (ARGB color)

#### Palette image color header

truecolor | 1 byte (always “\0”)
count | 1 word (the number of used palette colors)
transparent | 1 dword (ARGB color)
palette | 256 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 IO | Read and write GD2 images.
Functions |
gdImageCreateFromGd2 | gdImageCreateFromGd2 is called to load images from gd2 format files.
gdImageCreateFromGd2Ptr |
gdImageCreateFromGd2Ctx | Reads in a GD2 image via a gdIOCtx struct.
gdImageCreateFromGd2Part | gdImageCreateFromGd2Part 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

infile | The 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

size | size of GD2 data in bytes.
data | GD2 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

infile | The input FILE pointer
srcx, srcy | The source X and Y coordinates
w, h | The 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

size | size of GD data in bytes.
data | GD data (i.e. contents of a GIF file).
srcx, srcy | The source X and Y coordinates
w, h | The 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

in | The data source.
srcx, srcy | The source X and Y coordinates
w, h | The 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