gd Reference Guide

Types

gdImage
gdImagePtr
gdFont
gdFontPtr
gdPoint
gdPointPtr

Functions
Drawing Functions
Constants

F

gd Reference Guide

This appendix provides a very quick reference to Thomas Boutell's gd library, a C programming library for dynamically creating and modifying GIF images. Thomas has provided excellent electronic documentation for this library, which is included on the CD-ROM that accompanies this book and is also available at

URL:http://www.boutell.com/gd/

Getting Started

To install gd, you first need to uncompress and untar it using the following commands:

uncompress gd1.2.tar.gz
tar xvof gd1.2.tar

After you have unpacked the library, you compile the library by editing the Makefile and typing the following:

make all

To compile a program that uses gd, make sure you include the proper header files and that the header files and library are in the proper path. You can link your program with the library using the following:

cc -o filename filename.o -lgd

Types and Functions

The following sections list and explain types and functions found in gd.

Types

The following are the types defined in gd.

gdImage

gdImage is the image data structure for the gd library, defined as the following:

typedef struct {
  unsigned char ** pixels;
  int sx;
  int sy;
  int colorsTotal;
  int red[gdMaxColors];
  int green[gdMaxColors];
  int blue[gdMaxColors];
  int open[gdMaxColors];
  int transparent;
} gdImage;

Set the members of this type by using the functions provided by the gd library.

gdImagePtr

gdImagePtr is a pointer to a structure of type gdImage.

gdFont

gdFont is a font structure defined as the following:

typedef struct {
  /* # of characters in font */
  int nchars;
  /* First character is numbered... (usually 32 = space) */
  int offset;
  /* Character width and height */
  int w;
  int h;
  /* Font data; array of characters, one row after another.
     Easily included in code, also easily loaded from
     data files. */
  char *data;
} gdFont;

Once again, use the supplied functions to change the parameters of this type.

gdFontPtr

gdFontPtr is a pointer to type gdFont.

gdPoint

gdPoint is a point in the coordinate space defined as the following:

typedef struct {
   int x, y;
} gdPoint;

gdPointPtr

gdPointPtr is a pointer to gdPoint.

Functions

Table F.1 lists gd functions, their types and arguments in the first column, and their description in the second column.

Table F.1. Image creation, destruction, loading, and saving.

Function, type, argument	Description
gdImagePtr gdImageCreate(sx, sy)	Creates an image of width sx and height sy.
gdImagePtr gdImageCreateFromGif(FILE *in)	Creates an image from a GIF file.
gdImagePtr gdImageCreateFromGd(FILE *in)	Creates an image from a gd file.
gdImagePtr gdImageCreateFromXbm(FILE *in)	Creates an image from an X bitmap file.
gdImageDestroy(gdImagePtr im)	Frees memory associated with an image. Invoke this function before exiting the program or reusing an image pointer gdImagePtr.
void gdImageGif(gdImagePtr im, FILE *out)	Writes a GIF image to the file handle out.
void gdImageGd(gdImagePtr im, FILE *out)	Writes a gd image to the file handle out.

Drawing Functions

Table F.2 lists and describes drawing functions. These enable you to draw lines, points, polygons and circles of all sorts.

Table F.2. Drawing functions.

Function	Description
void gdImageSetPixel(gdImagePtr im, int x, int y, int color)	Sets the pixel located at (x,y) to the color color.
void gdImageLine(gdImagePtr im, int x1, int y1, int x2, int y2, int color)	Draw a line between (x1,y1) and (x2,y2) of color color.
void gdImagePolygon(gdImagePtr im, gdPointPtr points, int pointsTotal, int color)	Draw a polygon with at least three vertices.
void gdImageRectangle (gdImagePtr im, int x1, int y1, int x2, int y2, int color)	Draw a rectangle with the upper-left corner (x1,y1) and the lower-right corner (x2,y2).

void gdImageFilledPolygon (gdImagePtr im, gdPointPtr points, int pointsTotal, int color)	Draw a filled polygon (equivalent to gdImagePolygon()).
void gdImageFilledRectangle (gdImagePtr im, int x1, int y1, int x2, int y2, int color)	Draw a solid rectangle ( to gdImageRectangle()).
void gdImageArc(gdImagePtr im, int cx, int cy, int w, int h, int s, int e, int color)	Draw a partial ellipse centered (cx,cy) with width w, height h, and position in degrees specified by starting degree s and ending degree e.
void gdImageFillToBorder (gdImagePtr im, int x, int y, int border, int color)	Fills an image to the specified border color.
void gdImageFill(gdImagePtr im, int x, int y, int color)	Fills an image with the same surrounding color
void gdImageSetBrush (gdImagePtr im, gdImagePtr brush)	Defines a brush image for use with line drawing and other functions.
void gdImageSetTile(gdImagePtr im, gdImagePtr tile)	Defines a tile image for image fills.
void gdImageSetStyle (gdImagePtr im, int *style, int styleLength)	Set lien style (that is, dashed lines, etc.)

Table F.3 contains query functions (which enable you to determine current states) and their descriptions.

Table F.3. Query functions.

Function	Description
int gdImageBlue(gdImagePtr im, int color)	Returns the blue component of the specified color index.
int gdImageGreen(gdImagePtr im, int color)	Returns the green component of the specified color index.
int gdImageRed(gdImagePtr im, int color)	Returns the red component of the specified color index.
int gdImageGetPixel(gdImagePtr im, int x, int y)	Retrieves the color index of a pixel.
int gdImageBoundsSafe (gdImagePtr im, int x, int y)	Returns true if point is bounded; false otherwise.
int gdImageSX(gdImagePtr im)	Returns the width of the image in pixels.
int gdImageSY(gdImagePtr im)	Returns the height of the image in pixels.

Table F.4 contains font- and text-handling functions and their descriptions. They enable you to manipulate text and fonts in images.

Table F.4. Font/text-handling functions.

Function   Description

void gdImageChar(gdImagePtr im, gdFontPtr font, int x, int y, int c, int color) Draw a single character on an image.

void gdImageCharUp(gdImagePtr im, gdFontPtr font, int x, int y, int c, int color) Draw a single character rotated 90 degrees.

void gdImageString(gdImagePtr im, gdFontPtr font, int x, int y, char *s, int color) Draw a string on an image.

void gdImageStringUp(gdImagePtr im, gdFontPtr font, int x, int y, char *s, int color) Draw a string rotated 90 degrees.

Table F.5 contains color-handling functions and their descriptions.

Table F.5. Color-handling functions.

Table F.6 lists the copying and resizing functions and their descriptions.

Table F.6. The copying/resizing functions.

Function Description

void gdImageCopy(gdImagePtr dst, Copy rectangular portion of one
gdImagePtr src, int dstX, image to another image.
int dstY, int srcX, int srcY,
int w, int h)

void gdImageCopyResized Copy rectangular portion from one
(gdImagePtr dst, gdImagePtr src, image, resize it, and paste it to
int dstX, int dstY, int srcX, another image.
int srcY, int destW, int destH,
int srcW, int srcH)

Finally, Table F.7 shows a function that didn't fit into the preceding categories.

Table F.7. Miscellaneous.

Function Description

gdImageInterlace(gdImagePtr im, int interlace) If interlace is non-zero, the image is

Function	Description
int gdImageColorAllocate (gdImagePtr im, int r, int g, int b)	Allocates a color index to the RGB value specified by r, g, and b.
int gdImageColorClosest (gdImagePtr im, int r, int g, int b)	Finds the closest allocated color to r, g, and b.
int gdImageColorExact (gdImagePtr im, int r, int g, int b)	Finds the color index for the color r, g, and b.
int gdImageColorsTotal (gdImagePtr im)	Returns the number of allocated colors.
int gdImageColorRed (gdImagePtr im, int c)	Returns the red portion of a specified color.
int gdImageColorGreen (gdImagePtr im, int c)	Returns the green portion of a specified color.
int gdImageColorBlue (gdImagePtr im, int c)	Returns the blue portion of a specified color.
int gdImageGetInterlaced (gdImagePtr im)	Returns true if the image is interlaced; false otherwise.
int gdImageGetTransparent (gdImagePtr im)	Returns true if the image is transparent; false otherwise.
void gdImageColorDeallocate (gdImagePtr im, int color)	Deallocates a color for reuse.
void gdImageColorTransparent (gdImagePtr im, int color)	Sets the transparent color index to the specified color otherwise, it is notindex interlaced;

Constants

Table F.8 lists constants used in gd and their descriptions.

Table F.8. Constants.

Constant	Description
gdBrushed	Used instead of a color for line drawing functions in order to use a brush image rather than a pixel.
gdMaxColors	Maximum number of colors in a GIF file according to the standard.
gdStyled	Use instead of a color for line drawing functions in order to use a style set by gdImageSetStyle().
gdStyledBrushed	Use instead of a color for line drawing functions in order to use both style and brush.
gdDashSize	Length of a dash in a dashed line.
gdTiled	Use instead of a color for filling functions to use tiled image for filling rather than solid colors.
gdTransparent	Used instead of a color in style setting.