typedef struct {
        int (*source) (void *context, char *buffer, int len);
        void *context;
} gdSource, *gdSourcePtr;

typedef struct {
        int (*sink) (void *context, char *buffer, int len);
        void *context;
} gdSink, *gdSinkPtr;

Image creation, destruction, loading and saving

gdImageCreate(sx, sy) (FUNCTION)

gdImageCreate is called to create palette-based images, with no more than 256 colors. Invoke gdImageCreate with the x and y dimensions of the desired image. gdImageCreate returns a gdImagePtr to the new image, or NULL if unable to allocate the image. The image must eventually be destroyed using gdImageDestroy().

... inside a function ...
gdImagePtr im;
im = gdImageCreate(64, 64);
/* ... Use the image ... */
gdImageDestroy(im);

gdImageCreateTrueColor(sx, sy) (FUNCTION)

gdImageCreateTrueColor is called to create truecolor images, with an essentially unlimited number of colors. Invoke gdImageCreateTrueColor with the x and y dimensions of the desired image. gdImageCreateTrueColor returns a gdImagePtr to the new image, or NULL if unable to allocate the image. The image must eventually be destroyed using gdImageDestroy().

Truecolor images are always filled with black at creation time. There is no concept of a "background" color index.

... inside a function ...
gdImagePtr im;
im = gdImageCreateTrueColor(64, 64);
/* ... Use the image ... */
gdImageDestroy(im);

gdImageCreateFromJpeg(FILE *in) (FUNCTION)
gdImageCreateFromJpegPtr(int size, void *data) (FUNCTION)
gdImageCreateFromJpegCtx(gdIOCtx *in) (FUNCTION)

gdImageCreateFromJpeg is called to load truecolor images from JPEG format files. Invoke gdImageCreateFromJpeg with an already opened pointer to a file containing the desired image. gdImageCreateFromJpeg returns a gdImagePtr to the new truecolor image, or NULL if unable to load the image (most often because the file is corrupt or does not contain a JPEG image). gdImageCreateFromJpeg 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(). The returned image is always a truecolor image.

If you already have the image file in memory, pass the size of the file and a pointer to the file's data to gdImageCreateFromJpegPtr, which is otherwise identical to gdImageCreateFromJpeg.

gdImagePtr im;
... inside a function ...
FILE *in;
in = fopen("myjpeg.jpg", "rb");
im = gdImageCreateFromJpeg(in);
fclose(in);
/* ... Use the image ... */
gdImageDestroy(im);

gdImageCreateFromPng(FILE *in) (FUNCTION)
gdImageCreateFromPngPtr(int size, void *data) (FUNCTION)
gdImageCreateFromPngCtx(gdIOCtx *in) (FUNCTION)

gdImageCreateFromPng is called to load images from PNG format files. Invoke gdImageCreateFromPng with an already opened pointer to a file containing the desired image. gdImageCreateFromPng 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 PNG image). gdImageCreateFromPng 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().

If you already have the image file in memory, pass the size of the file and a pointer to the file's data to gdImageCreateFromPngPtr, which is otherwise identical to gdImageCreateFromPng.

If the PNG image being loaded is a truecolor image, the resulting gdImagePtr will refer to a truecolor image. If the PNG image being loaded is a palette or grayscale image, the resulting gdImagePtr will refer to a palette image. gd retains only 8 bits of resolution for each of the red, green and blue channels, and only 7 bits of resolution for the alpha channel. The former restriction affects only a handful of very rare 48-bit color and 16-bit grayscale PNG images. The second restriction affects all semitransparent PNG images, but the difference is essentially invisible to the eye. 7 bits of alpha channel resolution is, in practice, quite a lot.

gdImagePtr im;
... inside a function ...
FILE *in;
in = fopen("mypng.png", "rb");
im = gdImageCreateFromPng(in);
fclose(in);
/* ... Use the image ... */
gdImageDestroy(im);

gdImageCreateFromPngSource(gdSourcePtr in) (FUNCTION)

Deprecated in favor of gdImageCreateFromPngCtx. Should not be used in new applications.

gdImageCreateFromPngSource is called to load a PNG from a data source other than a file. Usage is very similar to the gdImageCreateFromPng function, except that the programmer provides a custom data source.

The programmer must write an input function which accepts a context pointer, a buffer, and a number of bytes to be read as arguments. This function must read the number of bytes requested, unless the end of the file has been reached, in which case the function should return zero, or an error has occurred, in which case the function should return -1. The programmer then creates a gdSource structure and sets the source pointer to the input function and the context pointer to any value which is useful to the programmer.

The example below implements gdImageCreateFromPng by creating a custom data source and invoking gdImageCreateFromPngSource.

static int freadWrapper(void *context, char *buf, int len);

gdImagePtr gdImageCreateFromPng(FILE *in)
{
        gdSource s;
        s.source = freadWrapper;
        s.context = in;
        return gdImageCreateFromPngSource(&s);
}

static int freadWrapper(void *context, char *buf, int len)
{
        int got = fread(buf, 1, len, (FILE *) context);
        return got;
}

gdImageCreateFromGd(FILE *in) (FUNCTION)

gdImageCreateFromGdPtr(int size, void *data) (FUNCTION)
gdImageCreateFromGdCtx(gdIOCtx *in) (FUNCTION)

gdImageCreateFromGd is called to load images from gd format files. Invoke gdImageCreateFromGd with an already opened pointer to a file containing the desired image in the gd file format, which is specific to gd and intended for very fast loading. (It is not intended for compression; for compression, use PNG or JPEG.)

If you already have the image file in memory, pass the size of the file and a pointer to the file's data to gdImageCreateFromGdPtr, which is otherwise identical to gdImageCreateFromGd.

gdImageCreateFromGd 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). gdImageCreateFromGd 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().

... inside a function ...
gdImagePtr im;
FILE *in;
in = fopen("mygd.gd", "rb");
im = gdImageCreateFromGd(in);
fclose(in);
/* ... Use the image ... */
gdImageDestroy(im);

gdImageCreateFromGd2(FILE *in) (FUNCTION)
gdImageCreateFromGd2Ptr(int size, void *data) (FUNCTION)
gdImageCreateFromGd2Ctx(gdIOCtx *in) (FUNCTION)

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.)

If you already have the image file in memory, pass the size of the file and a pointer to the file's data to gdImageCreateFromGd2Ptr, which is otherwise identical to gdImageCreateFromGd2.

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().

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

gdImageCreateFromGd2Part(FILE *in, int srcX, int srcY, int w, int h) (FUNCTION)
gdImageCreateFromGd2PartPtr(int size, void *data, int srcX, int srcY, int w, int h) (FUNCTION)
gdImageCreateFromGd2PartCtx(gdIOCtx *in) (FUNCTION)

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().

If you already have the image file in memory, you may use gdImageCreateFromGd2PartPtr. Pass the size of the image file, in bytes, as the first argument and the pointer to the image file data as the second argument.

gdImageCreateFromWBMP(FILE *in) (FUNCTION)
gdImageCreateFromWBMPPtr(int size, void *data) (FUNCTION)
gdImageCreateFromWBMPCtx(gdIOCtx *in) (FUNCTION)

gdImageCreateFromWBMP is called to load images from WBMP format files. Invoke gdImageCreateFromWBMP with an already opened pointer to a file containing the desired image. gdImageCreateFromWBMP 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 PNG image). gdImageCreateFromWBMP 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().

If you already have the image file in memory, pass the size of the file and a pointer to the file's data to gdImageCreateFromWBMPPtr, which is otherwise identical to gdImageCreateFromWBMP.

gdImagePtr im;
... inside a function ...
FILE *in;
in = fopen("mywbmp.wbmp", "rb");
im = gdImageCreateFromWBMP(in);
fclose(in);
/* ... Use the image ... */
gdImageDestroy(im);

gdImageCreateFromXbm(FILE *in) (FUNCTION)

gdImageCreateFromXbm is called to load images from X bitmap format files. Invoke gdImageCreateFromXbm with an already opened pointer to a file containing the desired image. gdImageCreateFromXbm 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 an X bitmap format image). gdImageCreateFromXbm 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().

... inside a function ...
gdImagePtr im;
FILE *in;
in = fopen("myxbm.xbm", "rb");
im = gdImageCreateFromXbm(in);
fclose(in);
/* ... Use the image ... */
gdImageDestroy(im);

gdImageCreateFromXpm(char *filename) (FUNCTION)

gdImageCreateFromXbm is called to load images from XPM X Window System color bitmap format files. This function is available only if HAVE_XPM is selected in the Makefile and the Xpm library is linked with the application. Unlike most gd file functions, the Xpm functions require filenames, not file pointers. gdImageCreateFromXpm 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 an XPM bitmap format image). You can inspect the sx and sy members of the image to determine its size. The image must eventually be destroyed using gdImageDestroy().

... inside a function ...
gdImagePtr im;
FILE *in;
in = fopen("myxpm.xpm", "rb");
im = gdImageCreateFromXpm(in);
fclose(in);
/* ... Use the image ... */
gdImageDestroy(im);

gdImageDestroy(gdImagePtr im) (FUNCTION)

gdImageDestroy is used to free the memory associated with an image. It is important to invoke gdImageDestroy before exiting your program or assigning a new image to a gdImagePtr variable.

... inside a function ...
gdImagePtr im;
im = gdImageCreate(10, 10);
/* ... Use the image ... */
/* Now destroy it */
gdImageDestroy(im);

void gdImageJpeg(gdImagePtr im, FILE *out, int quality) (FUNCTION)
void gdImageJpegCtx(gdImagePtr im, gdIOCtx *out, int quality) (FUNCTION)

gdImageJpeg outputs the specified image to the specified file in JPEG format. The file must be open for writing. Under MSDOS and all versions of Windows, it is important to use "wb" as opposed to simply "w" as the mode when opening the file, and under Unix there is no penalty for doing so. gdImageJpeg does not close the file; your code must do so.

If quality is negative, the default IJG JPEG quality value (which should yield a good general quality / size tradeoff for most situations) is used. Otherwise, for practical purposes, quality should be a value in the range 0-95, higher quality values usually implying both higher quality and larger image sizes.

If you have set image interlacing using gdImageInterlace, this function will interpret that to mean you wish to output a progressive JPEG. Some programs (e.g., Web browsers) can display progressive JPEGs incrementally; this can be useful when browsing over a relatively slow communications link, for example. Progressive JPEGs can also be slightly smaller than sequential (non-progressive) JPEGs.

... inside a function ...
gdImagePtr im;
int black, white;
FILE *out;
/* Create the image */
im = gdImageCreate(100, 100);
/* Allocate background */
white = gdImageColorAllocate(im, 255, 255, 255);
/* Allocate drawing color */
black = gdImageColorAllocate(im, 0, 0, 0);
/* Draw rectangle */
gdImageRectangle(im, 0, 0, 99, 99, black);
/* Open output file in binary mode */
out = fopen("rect.jpg", "wb");
/* Write JPEG using default quality */
gdImageJpeg(im, out, -1);
/* Close file */
fclose(out);
/* Destroy image */
gdImageDestroy(im);

void* gdImageJpegPtr(gdImagePtr im, int *size, int quality) (FUNCTION)

Identical to gdImageJpeg except that it returns a pointer to a memory area with the JPEG data. This memory must be freed by the caller when it is no longer needed. The caller must invoke gdFree(), not free(), unless the caller is absolutely certain that the same implementations of malloc, free, etc. are used both at library build time and at application build time. The 'size' parameter receives the total size of the block of memory.

void gdImagePng(gdImagePtr im, FILE *out)
void gdImagePngCtx(gdImagePtr im, gdIOCtx *out) (FUNCTION)

gdImagePng outputs the specified image to the specified file in PNG format. The file must be open for writing. Under MSDOS and all versions of Windows, it is important to use "wb" as opposed to simply "w" as the mode when opening the file, and under Unix there is no penalty for doing so. gdImagePng does not close the file; your code must do so.

... inside a function ...
gdImagePtr im;
int black, white;
FILE *out;
/* Create the image */
im = gdImageCreate(100, 100);
/* Allocate background */
white = gdImageColorAllocate(im, 255, 255, 255);
/* Allocate drawing color */
black = gdImageColorAllocate(im, 0, 0, 0);
/* Draw rectangle */
gdImageRectangle(im, 0, 0, 99, 99, black);
/* Open output file in binary mode */
out = fopen("rect.png", "wb");
/* Write PNG */
gdImagePng(im, out);
/* Close file */
fclose(out);
/* Destroy image */
gdImageDestroy(im);

void gdImagePngEx(gdImagePtr im, FILE *out, int level)
void gdImagePngCtxEx(gdImagePtr im, gdIOCtx *out, int level) (FUNCTION)

Like gdImagePng, gdImagePngEx outputs the specified image to the specified file in PNG format. In addition, gdImagePngEx allows the level of compression to be specified. A compression level of 0 means "no compression." A compression level of 1 means "compressed, but as quickly as possible." A compression level of 9 means "compressed as much as possible to produce the smallest possible file." A compression level of -1 will use the default compression level at the time zlib was compiled on your system.

For more information, see gdImagePng.

void* gdImagePngPtr(gdImagePtr im, int *size) (FUNCTION)

Identical to gdImagePng except that it returns a pointer to a memory area with the PNG data. This memory must be freed by the caller when it is no longer needed. The caller must invoke gdFree(), not free(), unless the caller is absolutely certain that the same implementations of malloc, free, etc. are used both at library build time and at application build time. The 'size' parameter receives the total size of the block of memory.

void* gdImagePngPtrEx(gdImagePtr im, int *size, int level) (FUNCTION)

Like gdImagePngPtr, gdImagePngPtrEx returns a pointer to a PNG image in allocated memory. In addition, gdImagePngPtrEx allows the level of compression to be specified. A compression level of 0 means "no compression." A compression level of 1 means "compressed, but as quickly as possible." A compression level of 9 means "compressed as much as possible to produce the smallest possible file." A compression level of -1 will use the default compression level at the time zlib was compiled on your system.

For more information, see gdImagePngPtr.

gdImagePngToSink(gdImagePtr im, gdSinkPtr out) (FUNCTION)

gdImagePngToSink is called to write a PNG to a data "sink" (destination) other than a file. Usage is very similar to the gdImagePng function, except that the programmer provides a custom data sink.

The programmer must write an output function which accepts a context pointer, a buffer, and a number of bytes to be written as arguments. This function must write the number of bytes requested and return that number, unless an error has occurred, in which case the function should return -1. The programmer then creates a gdSink structure and sets the sink pointer to the output function and the context pointer to any value which is useful to the programmer.

The example below implements gdImagePng by creating a custom data source and invoking gdImagePngFromSink.

static int stdioSink(void *context, char *buffer, int len)
{
  return fwrite(buffer, 1, len, (FILE *) context);
}

void gdImagePng(gdImagePtr im, FILE *out)
{
  gdSink mySink;
  mySink.context = (void *) out;
  mySink.sink = stdioSink;
  gdImagePngToSink(im, &mySink);
}

void gdImageWBMP(gdImagePtr im, int fg, FILE *out)
gdImageWBMPCtx(gdIOCtx *out) (FUNCTION)(FUNCTION)

gdImageWBMP outputs the specified image to the specified file in WBMP format. The file must be open for writing. Under MSDOS and all versions of Windows, it is important to use "wb" as opposed to simply "w" as the mode when opening the file, and under Unix there is no penalty for doing so. gdImageWBMP does not close the file; your code must do so.

WBMP file support is black and white only. The color index specified by the fg argument is the "foreground," and only pixels of this color will be set in the WBMP file. All other pixels will be considered "background."

... inside a function ...
gdImagePtr im;
int black, white;
FILE *out;
/* Create the image */
im = gdImageCreate(100, 100);
/* Allocate background */
white = gdImageColorAllocate(im, 255, 255, 255);
/* Allocate drawing color */
black = gdImageColorAllocate(im, 0, 0, 0);
/* Draw rectangle */
gdImageRectangle(im, 0, 0, 99, 99, black);
/* Open output file in binary mode */
out = fopen("rect.wbmp", "wb");
/* Write WBMP, with black as foreground */
gdImageWBMP(im, black, out);
/* Close file */
fclose(out);
/* Destroy image */
gdImageDestroy(im);

void* gdImageWBMPPtr(gdImagePtr im, int *size) (FUNCTION)

Identical to gdImageWBMP except that it returns a pointer to a memory area with the WBMP data. This memory must be freed by the caller when it is no longer needed. The caller must invoke gdFree(), not free(), unless the caller is absolutely certain that the same implementations of malloc, free, etc. are used both at library build time and at application build time. The 'size' parameter receives the total size of the block of memory.

void gdImageGd(gdImagePtr im, FILE *out) (FUNCTION)

gdImageGd outputs the specified image to the specified file in the gd image format. The file must be open for writing. Under MSDOS and all versions of Windows, it is important to use "wb" as opposed to simply "w" as the mode when opening the file, and under Unix there is no penalty for doing so. gdImagePng does not close the file; your code must do so.

The gd image format is intended for fast reads and writes of images your program will need frequently to build other images. It is not a compressed format, and is not intended for general use.

... inside a function ...
gdImagePtr im;
int black, white;
FILE *out;
/* Create the image */
im = gdImageCreate(100, 100);
/* Allocate background */
white = gdImageColorAllocate(im, 255, 255, 255);
/* Allocate drawing color */
black = gdImageColorAllocate(im, 0, 0, 0);
/* Draw rectangle */
gdImageRectangle(im, 0, 0, 99, 99, black);
/* Open output file in binary mode */
out = fopen("rect.gd", "wb");
/* Write gd format file */
gdImageGd(im, out);
/* Close file */
fclose(out);
/* Destroy image */
gdImageDestroy(im);

void* gdImageGdPtr(gdImagePtr im, int *size) (FUNCTION)

Identical to gdImageGd except that it returns a pointer to a memory area with the GD data. This memory must be freed by the caller when it is no longer needed. The caller must invoke gdFree(), not free(), unless the caller is absolutely certain that the same implementations of malloc, free, etc. are used both at library build time and at application build time. The 'size' parameter receives the total size of the block of memory.

void gdImageGd2(gdImagePtr im, FILE *out, int chunkSize, int fmt)
void gdImageGd2Ctx(gdImagePtr im, gdIOCtx *out, int chunkSize, int fmt) (FUNCTION)

gdImageGd2 outputs the specified image to the specified file in the gd2 image format. The file must be open for writing. Under MSDOS and all versions of Windows, it is important to use "wb" as opposed to simply "w" as the mode when opening the file, and under Unix there is no penalty for doing so. gdImageGd2 does not close the file; your code must do so.

The gd2 image format is intended for fast reads and writes of parts of images. It is a compressed format, and well suited to retrieving smll sections of much larger images. The third and fourth parameters are the 'chunk size' and format resposectively.

The file is stored as a series of compressed subimages, and the Chunk Size determines the sub-image size - a value of zero causes the GD library to use the default.

It is also possible to store GD2 files in an uncompressed format, in which case the fourth parameter should be GD2_FMT_RAW.

... inside a function ...
gdImagePtr im;
int black, white;
FILE *out;
/* Create the image */
im = gdImageCreate(100, 100);
/* Allocate background */
white = gdImageColorAllocate(im, 255, 255, 255);
/* Allocate drawing color */
black = gdImageColorAllocate(im, 0, 0, 0);
/* Draw rectangle */
gdImageRectangle(im, 0, 0, 99, 99, black);
/* Open output file in binary mode */
out = fopen("rect.gd", "wb");
/* Write gd2 format file */
gdImageGd2(im, out, 0, GD2_FMT_COMPRESSED);
/* Close file */
fclose(out);
/* Destroy image */
gdImageDestroy(im);

void* gdImageGd2Ptr(gdImagePtr im, int chunkSize, int fmt, int *size) (FUNCTION)

Identical to gdImageGd2 except that it returns a pointer to a memory area with the GD2 data. This memory must be freed by the caller when it is no longer needed. The caller must invoke gdFree(), not free(), unless the caller is absolutely certain that the same implementations of malloc, free, etc. are used both at library build time and at application build time. The 'size' parameter receives the total size of the block of memory.

void gdImageTrueColorToPalette(gdImagePtr im, int ditherFlag, int colorsWanted) (FUNCTION)

Converts a truecolor image to a palette-based image, using a high-quality two-pass quantization routine. If ditherFlag is set, the image will be dithered to approximate colors better, at the expense of some obvious "speckling." colorsWanted can be anything up to 256. If the original source image includes photographic information or anything that came out of a JPEG, 256 is strongly recommended. 100% transparency of a single transparent color in the original truecolor image will be preserved. There is no other support for preservation of alpha channel or transparency in the destination image.

For best results, don't use this function -- write real truecolor PNGs and JPEGs. The disk space gain of conversion to palette is not great (for small images it can be negative) and the quality loss is ugly. However, the version of this function included in version 2.0.12 and later does do a better job than the version included prior to 2.0.12.

Drawing Functions

void gdImageSetPixel(gdImagePtr im, int x, int y, int color) (FUNCTION)

gdImageSetPixel sets a pixel to a particular color index. Always use this function or one of the other drawing functions to access pixels; do not access the pixels of the gdImage structure directly.

... inside a function ...
gdImagePtr im;
int black;
int white;
im = gdImageCreate(100, 100);
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0);  
/* Allocate the color white (red, green and blue all maximum). */
white = gdImageColorAllocate(im, 255, 255, 255);  
/* Set a pixel near the center. */
gdImageSetPixel(im, 50, 50, white);
/* ... Do something with the image, such as 
  saving it to a file... */
/* Destroy it */
gdImageDestroy(im);

void gdImageLine(gdImagePtr im, int x1, int y1, int x2, int y2, int color) (FUNCTION)

gdImageLine is used to draw a line between two endpoints (x1,y1 and x2, y2). The line is drawn using the color index specified. Note that the color index can be an actual color returned by gdImageColorAllocate or one of gdStyled, gdBrushed or gdStyledBrushed.

... inside a function ...
gdImagePtr im;
int black;
int white;
im = gdImageCreate(100, 100);
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0);  
/* Allocate the color white (red, green 
  and blue all maximum). */
white = gdImageColorAllocate(im, 255, 255, 255);  
/* Draw a line from the upper left corner to the 
  lower right corner. */
gdImageLine(im, 0, 0, 99, 99, white);
/* ... Do something with the image, such as 
  saving it to a file... */
/* Destroy it */
gdImageDestroy(im);

void gdImageDashedLine(gdImagePtr im, int x1, int y1, int x2, int y2, int color) (FUNCTION)

gdImageDashedLine is provided solely for backwards compatibility with gd 1.0. New programs should draw dashed lines using the normal gdImageLine function and the new gdImageSetStyle function.

gdImageDashedLine is used to draw a dashed line between two endpoints (x1,y1 and x2, y2). The line is drawn using the color index specified. The portions of the line that are not drawn are left transparent so the background is visible.

... inside a function ...
gdImagePtr im;
int black;
int white;
im = gdImageCreate(100, 100);
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0);  
/* Allocate the color white (red, green and blue 
  all maximum). */
white = gdImageColorAllocate(im, 255, 255, 255);  
/* Draw a dashed line from the upper left corner 
  to the lower right corner. */
gdImageDashedLine(im, 0, 0, 99, 99);
/* ... Do something with the image, such as 
  saving it to a file... */
/* Destroy it */
gdImageDestroy(im);

void gdImagePolygon(gdImagePtr im, gdPointPtr points, int pointsTotal, int color) (FUNCTION)

gdImagePolygon is used to draw a polygon with the verticies (at least 3) specified, using the color index specified. See also gdImageFilledPolygon.

... inside a function ...
gdImagePtr im;
int black;
int white;
/* Points of polygon */
gdPoint points[3];
im = gdImageCreate(100, 100);
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0);  
/* Allocate the color white (red, green and 
  blue all maximum). */
white = gdImageColorAllocate(im, 255, 255, 255);  
/* Draw a triangle. */
points[0].x = 50;
points[0].y = 0;
points[1].x = 99;
points[1].y = 99;
points[2].x = 0;
points[2].y = 99;
gdImagePolygon(im, points, 3, white);
/* ... Do something with the image, such as 
  saving it to a file... */
/* Destroy it */
gdImageDestroy(im);

void gdImageRectangle(gdImagePtr im, int x1, int y1, int x2, int y2, int color) (FUNCTION)

gdImageRectangle is used to draw a rectangle with the two corners (upper left first, then lower right) specified, using the color index specified.

... inside a function ...
gdImagePtr im;
int black;
int white;
im = gdImageCreate(100, 100);
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0);  
/* Allocate the color white (red, green and blue all maximum). */
white = gdImageColorAllocate(im, 255, 255, 255);  
/* Draw a rectangle occupying the central area. */
gdImageRectangle(im, 25, 25, 74, 74, white);
/* ... Do something with the image, such as 
  saving it to a file... */
/* Destroy it */
gdImageDestroy(im);

void gdImageFilledPolygon(gdImagePtr im, gdPointPtr points, int pointsTotal, int color) (FUNCTION)

gdImageFilledPolygon is used to fill a polygon with the verticies (at least 3) specified, using the color index specified. See also gdImagePolygon.

... inside a function ...
gdImagePtr im;
int black;
int white;
int red;
/* Points of polygon */
gdPoint points[3];
im = gdImageCreate(100, 100);
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0);  
/* Allocate the color white (red, green and blue all maximum). */
white = gdImageColorAllocate(im, 255, 255, 255);  
/* Allocate the color red. */
red = gdImageColorAllocate(im, 255, 0, 0);  
/* Draw a triangle. */
points[0].x = 50;
points[0].y = 0;
points[1].x = 99;
points[1].y = 99;
points[2].x = 0;
points[2].y = 99;
/* Paint it in white */
gdImageFilledPolygon(im, points, 3, white);
/* Outline it in red; must be done second */
gdImagePolygon(im, points, 3, red);
/* ... Do something with the image, such as 
  saving it to a file... */
/* Destroy it */
gdImageDestroy(im);

void gdImageFilledRectangle(gdImagePtr im, int x1, int y1, int x2, int y2, int color) (FUNCTION)

gdImageFilledRectangle is used to draw a solid rectangle with the two corners (upper left first, then lower right) specified, using the color index specified.

... inside a function ...
gdImagePtr im;
int black;
int white;
im = gdImageCreate(100, 100);
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0);  
/* Allocate the color white (red, green and blue all maximum). */
white = int gdImageColorAllocate(im, 255, 255, 255);  
/* Draw a filled rectangle occupying the central area. */
gdImageFilledRectangle(im, 25, 25, 74, 74, white);
/* ... Do something with the image, such as 
  saving it to a file... */
/* Destroy it */
gdImageDestroy(im);

void gdImageArc(gdImagePtr im, int cx, int cy, int w, int h, int s, int e, int color) (FUNCTION)

gdImageArc is used to draw a partial ellipse centered at the given point, with the specified width and height in pixels. The arc begins at the position in degrees specified by s and ends at the position specified by e. The arc is drawn in the color specified by the last argument. A circle can be drawn by beginning from 0 degrees and ending at 360 degrees, with width and height being equal. e must be greater than s. Values greater than 360 are interpreted modulo 360.

... inside a function ...
gdImagePtr im;
int black;
int white;
im = gdImageCreate(100, 50);
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0);  
/* Allocate the color white (red, green and blue all maximum). */
white = gdImageColorAllocate(im, 255, 255, 255);  
/* Inscribe an ellipse in the image. */
gdImageArc(im, 50, 25, 98, 48, 0, 360, white);
/* ... Do something with the image, such as 
  saving it to a file... */
/* Destroy it */
gdImageDestroy(im);

void gdImageFilledArc(gdImagePtr im, int cx, int cy, int w, int h, int s, int e, int color, int style) (FUNCTION)

gdImageFilledArc is used to draw a partial ellipse centered at the given point, with the specified width and height in pixels. The arc begins at the position in degrees specified by s and ends at the position specified by e. The arc is filled in the color specified by the second to last argument. A circle can be drawn by beginning from 0 degrees and ending at 360 degrees, with width and height being equal. e must be greater than s. Values greater than 360 are interpreted modulo 360. The last argument is a bitwise OR of the following possibilities:

• gdArc
• gdChord
• gdPie (synonym for gdChord)
• gdNoFill
• gdEdged

gdArc and gdChord are mutually exclusive; gdChord just connects the starting and ending angles with a straight line, while gdArc produces a rounded edge. gdPie is a synonym for gdArc. gdNoFill indicates that the arc or chord should be outlined, not filled. gdEdged, used together with gdNoFill, indicates that the beginning and ending angles should be connected to the center; this is a good way to outline (rather than fill) a 'pie slice'.

... inside a function ...
gdImagePtr im;
int black;
int white;
im = gdImageCreate(100, 50);
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0);  
/* Allocate the color white (red, green and blue all maximum). */
white = gdImageColorAllocate(im, 255, 255, 255);  
/* Inscribe a filled pie slice in the image. */
gdImageFilledArc(im, 50, 25, 98, 48, 0, 45, white, gdArc);
/* ... Do something with the image, such as 
  saving it to a file... */
/* Destroy it */
gdImageDestroy(im);

void gdImageFilledEllipse(gdImagePtr im, int cx, int cy, int w, int h, int color) (FUNCTION)

gdImageFilledEllipse is used to draw an ellipse centered at the given point, with the specified width and height in pixels. The ellipse is filled in the color specified by the last argument.

... inside a function ...
gdImagePtr im;
int black;
int white;
im = gdImageCreate(100, 50);
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0);  
/* Allocate the color white (red, green and blue all maximum). */
white = gdImageColorAllocate(im, 255, 255, 255);  
/* Inscribe a filled ellipse in the image. */
gdImageFilledEllipse(im, 50, 25, 98, 48, white);
/* ... Do something with the image, such as 
  saving it to a file... */
/* Destroy it */
gdImageDestroy(im);

void gdImageFillToBorder(gdImagePtr im, int x, int y, int border, int color) (FUNCTION)

gdImageFillToBorder floods a portion of the image with the specified color, beginning at the specified point and stopping at the specified border color. For a way of flooding an area defined by the color of the starting point, see gdImageFill.

The border color cannot be a special color such as gdTiled; it must be a proper solid color. The fill color can be, however.

Note that gdImageFillToBorder is recursive. It is not the most naive implementation possible, and the implementation is expected to improve, but there will always be degenerate cases in which the stack can become very deep. This can be a problem in MSDOS and MS Windows 3.1 environments. (Of course, in a Unix or Windows 95/98/NT environment with a proper stack, this is not a problem at all.)

... inside a function ...
gdImagePtr im;
int black;
int white;
int red;
im = gdImageCreate(100, 50);
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0);  
/* Allocate the color white (red, green and blue all maximum). */
white = gdImageColorAllocate(im, 255, 255, 255);  
/* Allocate the color red. */
red = gdImageColorAllocate(im, 255, 0, 0);  
/* Inscribe an ellipse in the image. */
gdImageArc(im, 50, 25, 98, 48, 0, 360, white);
/* Flood-fill the ellipse. Fill color is red, border color is
  white (ellipse). */
gdImageFillToBorder(im, 50, 50, white, red);
/* ... Do something with the image, such as 
  saving it to a file... */
/* Destroy it */
gdImageDestroy(im);

void gdImageFill(gdImagePtr im, int x, int y, int color) (FUNCTION)

gdImageFill floods a portion of the image with the specified color, beginning at the specified point and flooding the surrounding region of the same color as the starting point. For a way of flooding a region defined by a specific border color rather than by its interior color, see gdImageFillToBorder.

The fill color can be gdTiled, resulting in a tile fill using another image as the tile. However, the tile image cannot be transparent. If the image you wish to fill with has a transparent color index, call gdImageTransparent on the tile image and set the transparent color index to -1 to turn off its transparency.

Note that gdImageFill is recursive. It is not the most naive implementation possible, and the implementation is expected to improve, but there will always be degenerate cases in which the stack can become very deep. This can be a problem in MSDOS and MS Windows environments. (Of course, in a Unix or Windows 95/98/NT environment with a proper stack, this is not a problem at all.)

... inside a function ...
gdImagePtr im;
int black;
int white;
int red;
im = gdImageCreate(100, 50);
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0);  
/* Allocate the color white (red, green and blue all maximum). */
white = gdImageColorAllocate(im, 255, 255, 255);  
/* Allocate the color red. */
red = gdImageColorAllocate(im, 255, 0, 0);  
/* Inscribe an ellipse in the image. */
gdImageArc(im, 50, 25, 98, 48, 0, 360, white);
/* Flood-fill the ellipse. Fill color is red, and will replace the
  black interior of the ellipse. */
gdImageFill(im, 50, 50, red);
/* ... Do something with the image, such as 
  saving it to a file... */
/* Destroy it */
gdImageDestroy(im);

void gdImageSetAntiAliased(gdImagePtr im, int c) (FUNCTION)

"Antialiasing" is a process by which jagged edges associated with line drawing can be reduced by blending the foreground color with an appropriate percentage of the background, depending on how much of the pixel in question is actually within the boundaries of the line being drawn. All line-drawing functions, such as gdImageLine and gdImagePolygon, will draw antialiased lines if the special "color" gdAntiAliased is used when calling them.

gdImageSetAntiAliased is used to specify the actual foreground color to be used when drawing antialiased lines. You may set any color to be the foreground, however as of version 2.0.12 an alpha channel component is not supported.

Antialiased lines can be drawn on both truecolor and palette-based images. However, attempts to draw antialiased lines on highly complex palette-based backgrounds may not give satisfactory results, due to the limited number of colors available in the palette. Antialiased line-drawing on simple backgrounds should work well with palette-based images; otherwise create or fetch a truecolor image instead.

You need not take any special action when you are finished with antialised line drawing.

... inside a function ...
gdImagePtr im, brush;
int black;
int blue;
im = gdImageCreate(100, 100);
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0);  
blue = gdImageColorAllocate(im, 0, 0, 255);
gdImageSetAntiAliased(im, blue);
/* Draw a smooth line from the upper left corner to the 
  lower right corner. */
gdImageLine(im, 0, 0, 99, 99, gdAntiAliased);
/* ... Do something with the image, such as 
  saving it to a file... */
/* Destroy it */
gdImageDestroy(im);

See also gdAntiAliased and gdSetAntiAliasedDontBlend.

void gdImageSetAntiAliasedDontBlend(gdImagePtr im, int c) (FUNCTION)

Normally, when drawing lines with the special gdAntiAliased "color," blending with the background to reduce jagged edges is the desired behavior. However, when it is desired that lines not be blended with one particular color when it is encountered in the background, the gdImageSetAntiAliasedDontBlend function can be used to indicate the special color that the foreground should stand out more clearly against.

... inside a function ...
gdImagePtr im, brush;
int black;
int blue;
int white;
im = gdImageCreate(100, 100);
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0);  
blue = gdImageColorAllocate(im, 0, 0, 255);
white = gdImageColorAllocate(im, 255, 255, 255);

gdImageSetAntiAliased(im, blue);
/* The portion of the line that crosses this white rectangle will
  not be blended smoothly */
gdImageSetAntiAliasedDontBlend(im, white);
gdImageFilledRectangle(im, 25, 25, 75, 75, white);
/* Draw a smooth line from the upper left corner 
  to the lower right corner. */
gdImageLine(im, 0, 0, 99, 99, gdAntiAliased);
/* ... Do something with the image, such as 
  saving it to a file... */
/* Destroy it */
gdImageDestroy(im);

See also gdAntiAliased and gdSetAntiAliased.

void gdImageSetBrush(gdImagePtr im, gdImagePtr brush) (FUNCTION)

A "brush" is an image used to draw wide, shaped strokes in another image. Just as a paintbrush is not a single point, a brush image need not be a single pixel. Any gd image can be used as a brush, and by setting the transparent color index of the brush image with gdImageColorTransparent, a brush of any shape can be created. All line-drawing functions, such as gdImageLine and gdImagePolygon, will use the current brush if the special "color" gdBrushed or gdStyledBrushed is used when calling them.

gdImageSetBrush is used to specify the brush to be used in a particular image. You can set any image to be the brush. If the brush image does not have the same color map as the first image, any colors missing from the first image will be allocated. If not enough colors can be allocated, the closest colors already available will be used. This allows arbitrary PNGs to be used as brush images. It also means, however, that you should not set a brush unless you will actually use it; if you set a rapid succession of different brush images, you can quickly fill your color map, and the results will not be optimal.

You need not take any special action when you are finished with a brush. As for any other image, if you will not be using the brush image for any further purpose, you should call gdImageDestroy. You must not use the color gdBrushed if the current brush has been destroyed; you can of course set a new brush to replace it.

... inside a function ...
gdImagePtr im, brush;
FILE *in;
int black;
im = gdImageCreate(100, 100);
/* Open the brush PNG. For best results, portions of the
  brush that should be transparent (ie, not part of the
  brush shape) should have the transparent color index. */
in = fopen("star.png", "rb");
brush = gdImageCreateFromPng(in);
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0);  
gdImageSetBrush(im, brush);
/* Draw a line from the upper left corner to the lower right corner
  using the brush. */
gdImageLine(im, 0, 0, 99, 99, gdBrushed);
/* ... Do something with the image, such as 
  saving it to a file... */
/* Destroy it */
gdImageDestroy(im);
/* Destroy the brush image */
gdImageDestroy(brush);

void gdImageSetTile(gdImagePtr im, gdImagePtr tile) (FUNCTION)

A "tile" is an image used to fill an area with a repeated pattern. Any gd image can be used as a tile, and by setting the transparent color index of the tile image with gdImageColorTransparent, a tile that allows certain parts of the underlying area to shine through can be created. All region-filling functions, such as gdImageFill and gdImageFilledPolygon, will use the current tile if the special "color" gdTiled is used when calling them.

gdImageSetTile is used to specify the tile to be used in a particular image. You can set any image to be the tile. If the tile image does not have the same color map as the first image, any colors missing from the first image will be allocated. If not enough colors can be allocated, the closest colors already available will be used. This allows arbitrary PNGs to be used as tile images. It also means, however, that you should not set a tile unless you will actually use it; if you set a rapid succession of different tile images, you can quickly fill your color map, and the results will not be optimal.

You need not take any special action when you are finished with a tile. As for any other image, if you will not be using the tile image for any further purpose, you should call gdImageDestroy. You must not use the color gdTiled if the current tile has been destroyed; you can of course set a new tile to replace it.

... inside a function ...
gdImagePtr im, tile;
FILE *in;
int black;
im = gdImageCreate(100, 100);
/* Open the tile PNG. For best results, portions of the
  tile that should be transparent (ie, allowing the
  background to shine through) should have the transparent
  color index. */
in = fopen("star.png", "rb");
tile = gdImageCreateFromPng(in);
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0);  
gdImageSetTile(im, tile);
/* Fill