The following functions are part of GD.DLL: Functions dealing with creating and saving images: Functions that actually draw stuff on the image: Functions used to access information about the image (or parts of it): gdImageCopy gdImageCopyResized gdImageCreate gdImageCreateFromGd gdImageCreateFromGif gdImageCreateFromXbm gdImageDestroy gdImageGif gdImageGd gdImageInterlace gdImageFilledRectangle gdImagePolygon gdImageFilledPolygon gdImageArc gdImageRectangle gdImageLine gdImageFill gdImageFillToBorder gdImageGreen gdImageRed gdImageSX gdImageSY gdImageGetPixel gdImageBlue gdImageGetInterlaced gdImageGetTransparent gdImageBoundsSafe Functions used to set attributes: Functions used to write text to images: Functions used to access or modify the color palette gdImageSetBrush gdImageSetPixel gdImageSetStyle gdImageSetTile gdImageString gdImageStringUp gdImageChar gdImageCharUp gdImageColorAllocate gdImageColorClosest gdImageColorDeallocate gdImageColorExact gdImageColorTransparent gdImageArc(imgHnd, cx, cy, width, height, start, end, color)
	gdImageArc draws 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. The following code draws an ellipse on the screen. ... inside a function ... 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,... */ /* Destroy it */ gdImageDestroy(im);
gdImageFill(imgHnd, x, y, color)
	This function changes the color of an area. The pixel at x, y and all congruent pixels of the same color will be set to the color specified by color. 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 naïve 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 NT environment with a proper stack, this is not a problem at all.)
gdImageFilledRectangle(imgHnd, x1, y1, x2, y2, color)
	gdImageFilledRectangle() draws a solid rectangle with the upper left (x1,y1) and lower right corners (x2, y2) specified, in the specified color. ... inside a function ... 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 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);
gdImageFilledPolygon(gdImageHnd, gdPointPtr points, int pointsTotal, int color)
	gdImageFilledPolygon() fills a polygon defined by the points specified by the variable points. The polygon must have at least three points. It will be filled with the color specified by index. See also gdImagePolygon.
	... inside a function ... imgHnd = gdImageCreate(100, 100); Background color (first allocated) */ black = gdImageColorAllocate(imgHnd, 0, 0, 0); /* Allocate the color white (red, green and blue all maximum). */ white = gdImageColorAllocate(imgHnd, 255, 255, 255); /* Allocate the color red. */ red = gdImageColorAllocate(imgHnd, 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(imgHnd, points, 3, white); /* Outline it in red; must be done second */ gdImagePolygon(imgHnd, points, 3, red); /* ... Do something with the image... */ /* Destroy it */ gdImageDestroy(im);
gdImageLine(imgHnd, x1, y1, x2, y2, color)
	gdImageLine is used to draws a line between x1,y1 and x2, y2.The line is drawn using the color index specified. Note that color index can be a color returned by gdImageColorAllocate or one of gdStyled, gdBrushed or gdStyledBrushed. 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);
gdImagePolygon(gdImageHndl im, gdPointPtr points, int pointsTotal, int colorIndex)
	gdImagePolygon draws a polygon with the vertices specified by points, in the color specified by colorIndex. There must be at least three points. See also gdImageFilledPolygon. imgHnd = gdImageCreate(100, 100); /* Background color (first allocated) */ black = gdImageColorAllocate(imgHnd, 0, 0, 0); /* Allocate the color white (red, green and blue all maximum). */ white = gdImageColorAllocate(imgHnd, 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);
gdImageRectangle(imgHnd, x1, y1, x2, y2, color)
	gdImageRectangle draws a rectangle with the upper left (x1, y1) then lower right (y1,y2) corners specified, using the color index specified. 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);
gdImageCopy(destImgHnd, srcimgHnd, dx, dy, sx, sy, width, height)
	gdImageCopy copies a rectangular portion of srcimgHnd to destimgHng. (For a way of stretching or shrinking the image in the process, see gdImageCopyResized.) The dx and dy arguments specifies the upper left hand corner point in the destination image to which the region will be copied. The sx and sy arguments specify the upper left corner of the region in the source image. width and height specify the width and height of the region. When you copy a region from one location in an image to another location in the same image, gdImageCopy will perform as expected unless the regions overlap, in which case the result is unpredictable. Important note on copying between images: since different images do not necessarily have the same color tables, pixels are not simply set to the same color index values to copy them. gdImageCopy will attempt to find an identical RGB value in the destination image for each pixel in the copied portion of the source image by invoking gdImageColorExact. If such a value is not found, gdImageCopy will attempt to allocate colors as needed using gdImageColorAllocate. If both of these methods fail, gdImageCopy will invoke gdImageColorClosest to find the color in the destination image which most closely approximates the color of the pixel being copied. The example above takes a small gif file, and creates a larger one with the smaller image tiled on the background. /* Load a small gif to tile the larger one with */ in = fopen("small.gif", "rb"); im_in = gdImageCreateFromGif("small.gif"); /* Make the output image four times as large on both axes */ im_out = gdImageCreate(im_in->sx * 4, im_in->sy * 4); /* Now tile the larger image using the smaller one */ for (y = 0; (y < 4); y++) { for (x="0;" (x>< 4); x++) { gdImageCopy(im_out, im_in, x * im_in->sx, y * im_in->sy, 0, 0, im_in->sx, im_in->sy); } } gdImageGif(im_out, "tiled.gif"); gdImageDestroy(im_in); gdImageDestroy(im_out);
gdImageCopyResized(destImg, srcImg, dX, dY, sX, sY, dW, dH, sW, sH)
	gdImageCopyResized copies a rectangular portion of srcImg to destImg. dx and dy are the coordinates the upper left hand corner of the area being copied, and sx and sy are the coordinates the upper left hand corner of the region where the image is beng copied. The X and Y dimensions of the original region and the destination region can vary, resulting in stretching or shrinking of the region as appropriate. sw and sh are the width and height of the source image, and dw and dh are the width and height of the destination image.(For a simpler version of this function which does not deal with resizing, see gdImageCopy). dw and dh do not have to be equal to sw and sh, allowing a region to be scaled during the copying process. When you copy a region from one location in an image to anotherlocation in the same image, gdImageCopy will perform asexpected unless the regions overlap, in which case the result isunpredictable. If this presents a problem, create a scratch image inwhich to keep intermediate results. Important note on copying between images: since images do not necessarily have the same color tables, pixels are not simply set to the same color index values to copy them. gdImageCopyResized will attempt to find an identical RGB value in the destination image foreach pixel in the copied portion of the source image by invoking gdImageColorExact. If such a value is not found, gdImageCopyResized will attempt to allocate colors as needed using gdImageColorAllocate. If both of these methods fail, gdImageCopyResized will invoke gdImageColorClosest to find the colorin the destination image which most closely approximates the colorof the pixel being copied. /* Load a small gif to expand in the larger one */ im_in = gdImageCreateFromGif("small.gif"); fclose(in); /* Make the output image four times as large on both axes */ im_out = gdImageCreate(im_in->sx * 4, im_in->sy * 4); /* Now copy the smaller image, but four times larger */ gdImageCopyResized(im_out, im_in, 0, 0, 0, 0, im_out->sx, im_out->sy, im_in->sx, im_in->sy); gdImageGif(im_out, "large.gif"); gdImageDestroy(im_in); gdImageDestroy(im_out);
gdImageCreate(sx, sy)
	gdImageCreate creates an image that is x by y pixels. The image must eventually be destroyed with gdImageDestroy(). im = gdImageCreate(64, 64); /* ... Use the image ... */ gdImageDestroy(im);
gdImageCreateFromGd(filename)
	gdImageCreateFromGd() opens the file filename, which must be saved in gd format.You can inspect the sx and sy members of the image to determine its size. The image must eventually be destroyed with gdImageDestroy(). gdImageHndl im; fp = Clib.fopen("mygd.gd", "rb"); im = gdImageCreateFromGd(fp); fclose(fp); /* ... Use the image ... */ gdImageDestroy(im);
gdImageCreateFromGif(filename)
	gdImageCreateFromGif() loads the .gif file specified by filename for editing. It returns a handle to the file being opened, or NULL if it was unable to load the file (most likely because the file is corrupt or is not a valid .gif file). The image must eventually be destroyed with gdImageDestroy. fp = Clib.fopen("mygd.gd", "rb"); im = gdImageCreateFromGif(fp); fclose(fp); /* ... Use the image ... */ gdImageDestroy(im);
gdImageCreateFromXbm(filename)
	gdImageCreateFromXbm() loads images from X bitmap format files. imgHnd = gdImageCreateFromXbm("myxbm.xbm"); /* ...use the image... */ gdImageDestroy(imgHnd);
gdImageDestroy(imgHnd)
	gdImageDestroy() frees the memory allocated for the image. You must destroy all images created during your scripting session. gdImageHndl im; im = gdImageCreate(10, 10); /* ... Use the image ... */ /* Now destroy it */ gdImageDestroy(im);
gdImageGd(gdImageHndl im, string filename)
	gdImageGd() saves the image specified by imgHnd as the file filename in GD format. GD format is used by this library to quickly open and close images. /* 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); /* Write gd format file */ gdImageGd(im, "rect.gd"); /* Destroy image */ gdImageDestroy(im);
gdImageGif(imgHnd , filename)
	gdImageGif() saves the image specified by imgHnd as the file filename in GIF format. /* 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); /* Write GIF */ gdImageGif(im, "rect.gif"); /* Destroy image */ gdImageDestroy(im);
gdImageInterlace(imgHnd, interlace)
	gdImageInterlace is used to determine whether an image should be stored in a linear fashion, in which lines will appear on the display from first to last, or in an interlaced fashion, in which the image will "fade in" over several passes. Passing a non-zero value sets interlace to ON; a zero value turns it off. Note that only .gif images support interlace; if the file is saved in other formats this information will be lost. By default, images are not interlaced. Images loaded with gdImageGif() will have the interlace value set in the GIF file. /* ... Create or load the image... */ /* Now turn on interlace */ gdImageInterlace(im, 1); /* And save the image */ gdImageGif(im, "test.gif"); gdImageDestroy(im);
gdImageBlue(imgHnd, colorIndex)
	gdImageBlue returns the blue component of the specified color index. Use this macro rather than accessing the image directly.
gdImageBoundsSafe(imgHnd, x, y)
	gdImageBoundsSafe() returns true if the point x,y is within the bounds of the image specified by imgHnd; otherwise it returns false if it is not. This function is intended primarily for those who wish to add their own functions to the library; all of the functions in this document clip safely to the image. im = gdImageCreate(100, 100); if (gdImageBoundsSafe(im, 50, 50)) { printf("50, 50 is within the image bounds\n"); } else { printf("50, 50 is outside the image bounds\n"); }
gdImageGetInterlaced(imgHnd)
	This function returns true if the image specified by imgHnd is interlaced, and false if it is not. The interlaced format only applies to .gif images. See gdImageInterlace for a means of interlacing images.
gdImageGetPixel(imgHnd, x, y)
	gdImageGetPixel() retrieves the color index of the pixel at the coordinates x,y.
gdImageGetTransparent(imgHnd)
	This function returns the color index of the trasparent color in the image specified by imgHnd, or -1 if there is no transparent color.
gdImageGreen(imgHnd, colorIndex)
	gdImageGreen() returns the green component of the specified color index. Use this macro rather than accessing the image directly.
gdImageRed(imgHnd, colorIndex)
	gdImageRed() returns the red component of the specified color index. Use this macro rather than accessing the image directly.
gdImageSX(imgHnd, colorIndex)
	gdImageSX() returns the width of the image of the specified specified by imgHnd. Use this macro rather than accessing the image directly.
gdImageSY(imgHnd, colorIndex)
	gdImageSY() returns the height of the image of the specified specified by imgHnd. Use this macro rather than accessing the image directly.
gdImageSetBrush(imgHnd, brush)
	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. 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 GIFs 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. im = gdImageCreate(100, 100); /* Open the brush GIF. For best results, portions of the brush that should be transparent (i.e., not part of the brush shape) should have the transparent color index. */ in = fopen("star.gif", "rb"); brush = gdImageCreateFromGif(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);
gdImageSetPixel(imgHnd, x, y, colorIndex)
	This function sets the pixel at x,y to the color specified by colorIndex. 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);
gdImageSetStyle(imgHnd, *style, styleLength)
	gdImageSetStyle() lets you draw dashed lines, dotted lines, and other variations on a broken line. It sets any desired series of colors (including a special color that leaves the background intact) to serve as a template for drawing the line. var imgHnd; imgHnd = gdImageCreate(100, 100); /* Background color (first allocated) */ black = gdImageColorAllocate(imgHnd, 0, 0, 0); red = gdImageColorAllocate(imgHnd, 255, 0, 0); /* Set up dotted style. Leave every other pixel alone. */ styleDotted[0] = red; styleDotted[1] = gdTransparent; /* Set up dashed style. Three on, three off. */ styleDashed[0] = red; styleDashed[1] = red; styleDashed[2] = red; styleDashed[3] = gdTransparent; styleDashed[4] = gdTransparent; styleDashed[5] = gdTransparent; /* Set dotted style. Note that we have to specify how many pixels are in the style! */ gdImageSetStyle(imgHnd, styleDotted, 2); /* Draw a line from the upper left corner to the lower right corner. */ gdImageLine(imgHnd, 0, 0, 99, 99, gdStyled); /* Now the dashed line. */ gdImageSetStyle(imgHnd, styleDashed, 6); gdImageLine(imgHnd, 0, 99, 0, 99, gdStyled); /* ... Do something with the image, such as saving it to a file ... */ /* Destroy it */ gdImageDestroy(imgHnd);
gdImageSetTile(imgHnd, imgTile)
	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. 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 GIFs 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. im = gdImageCreate(100, 100); /* Open the tile GIF. For best results, portions of the tile that should be transparent (i.e., allowing the background to shine through) should have the transparent color index. */ tile = gdImageCreateFromGif("star.gif"); /* Background color (first allocated) */ black = gdImageColorAllocate(imgHnd, 0, 0, 0); gdImageSetTile(imgHnd, tile); /* Fill an area using the tile. */ gdImageFilledRectangle(imgHnd, 25, 25, 75, 75, gdTiled); /* ... Do something with the image, such as saving it to a file... */ /* Destroy it */ gdImageDestroy(imgHnd); /* Destroy the tile image */ gdImageDestroy(tile);
gdImageString(imgHnd, fontPtr, x, y, string, colorIndex)
	gdImageString() writes the contents of string on the image specified by imgHnd. The string will be drawn from left to right in the color indicated by color starting at the point x,y. Pixels not set by a particular character retain their previous color. The second argument is a pointer to a font definition structure. Five fonts are provided with gd: gdFontTiny, gdFontSmall, gdFontMediumBold, gdFontLarge, and gdFontGiant. See gdImageStringUp for a way of drawing vertical text, and gdImageChar for drawing single characters. /* String to draw. */ s = "Hello."; 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 centered string. */ gdImageString(im, gdFontLarge, im->w / 2 - (strlen(s) * gdFontLarge->w / 2), im->h / 2 - gdFontLarge->h / 2, s, white); /* ... Do something with the image, such as saving it to a file... */ /* Destroy it */ gdImageDestroy(im);
gdImageChar(imgHnd, fontPtr, x, y, c, color)
	gdImageChar() writes the character c on the image specified by imgHnd. The character will be drawn in the color indicated by color starting at the point x,y. Pixels not set by a particular character retain their previous color. The second argument is a pointer to a font definition structure. Five fonts are provided with gd: gdFontTiny, gdFontSmall, gdFontMediumBold, gdFontLarge, and gdFontGiant. See gdImageCharUp for a way of drawing vertical text, and gdImageString for drawing multiple characters (strings). 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 character. */ gdImageChar(im, gdFontLarge, 0, 0, 'Q', white); /* ... Do something with the image, such as saving it to a file... */ /* Destroy it */ gdImageDestroy(im);
gdImageCharUp(imgHnd, fontPtr, x, y, c, color)
	gdImageCharUp() writes the character c vertically on the image specified by imgHnd. The string will be drawn from left to right in the color indicated by color starting at the point x,y. Pixels not set by a particular character retain their previous color. The second argument is a pointer to a font definition structure. Five fonts are provided with gd: gdFontTiny, gdFontSmall, gdFontMediumBold, gdFontLarge, and gdFontGiant. See gdImageChar for a way of drawing horizontal text, and gdImageString() and gdImageStringUp() for drawing multiple characters (strings).
gdImageStringUp(imgHnd, fontPtr, x, y, string, colorIndex)
	gdImageString() writes the contents of string on the image specified by imgHnd. The string will be drawn from left to right in the color indicated by color starting at the point x,y. Pixels not set by a particular character retain their previous color. The second argument is a pointer to a font definition structure. Five fonts are provided with gd: gdFontTiny, gdFontSmall, gdFontMediumBold, gdFontLarge, and gdFontGiant. See gdImageStringUp for a way of drawing vertical text, and gdImageChar for drawing single characters. var imgHnd; var black; var white; /* String to draw. */ string = "Hello."; imgHnd = 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(imgHnd, 255, 255, 255); /* Draw a centered string going upwards. Axes are reversed, and Y axis is decreasing as the string is drawn. */ gdImageStringUp(imgHnd, gdFontLarge, imgHnd->w / 2 - gdFontLarge->h / 2, imgHnd->h / 2 + (strlen(s) * gdFontLarge->w / 2), string, white); /* ... Do something with the image... */ /* Destroy it */ gdImageDestroy(im);
gdImageColorAllocate(imgHnd, r, g, b)
	gdImageColorAllocate finds the first available color index in the image specified, sets its RGB values to those requested (255 is the maximum for each), and returns the index of the new color table entry. When creating a new image, the first time you invoke this function you are setting the background color for this image. r, g, and b are integers representing the red, green and blue components of the color being allocated. The index of the new color table entry. In the event that all gdMaxColors colors (256) have already been allocated, gdImageColorAllocate will return -1 to indicate failure. (This is not uncommon when working with existing GIF files that already use 256 colors.) Note that gdImageColorAllocate does not check for existing colors that match your request; see gdImageColorExact and gdImageColorClosest for ways to locate existing colors that approximate the color desired in situations where a new color is not available. im = gdImageCreate(100, 100); /* Background color (first allocated) */ black = gdImageColorAllocate(im, 0, 0, 0); /* Allocate the color red. */ red = gdImageColorAllocate(im, 255, 0, 0); /* Draw a dashed line from the one corner to the other. */ gdImageDashedLine(im, 0, 0, 99, 99, red); /* ... Do something with the image... */ /* Destroy it */ gdImageDestroy(im);
gdImageColorClosest(imgHnd, r, g, b)
	gdImageColorClosest searches the colors which have been defined thus far in the image specified and returns the index of the color with RGB values closest to those of the request. Closeness is determined by Euclidean distance, which is used to determine the distance in three-dimensional color space between colors. It returns the index of the color with RGB values closest to those of the request. If no colors have yet been allocated in the image, gdImageColorClosest returns -1. This function is most useful for choosing a drawing color when an image already contains gdMaxColors (256) colors and no more can be allocated. (This is not uncommon when working with existing GIF files that already use many colors.) See gdImageColorExact for a method of locating exact matches only. /* Suppose photo.gif is an image with many colors. */ in = Clib.fopen("photo.gif", "rb"); imgHnd = gdImageCreateFromGif("photo.gif"); /* Try to allocate red directly */ red = gdImageColorAllocate(imgHnd, 255, 0, 0); /* If we fail to allocate red... */ if (red == (-1)) { /* Find the closest color instead. */ red = gdImageColorClosest(imgHnd, 255, 0, 0); } /* Draw a dashed line from one corner to the other */ gdImageDashedLine(imgHnd, 0, 0, 99, 99, red); /* ... Do something with the image... */ /* Destroy it */ gdImageDestroy(imgHnd);
gdImageColorDeallocate(gdImageHndl im, int color)
	gdImageColorDeallocate marks the specified color as being available for reuse. It does not attempt to determine whether the color index is still in use in the image. After a call to this function, the next call to gdImageColorAllocate for the same image will set new RGB values for that color index, changing the color of any pixels which have that index as a result. If multiple calls to gdImageColorDeallocate are made consecutively, the lowest-numbered index among them will be reused by the next gdImageColorAllocate call. im = gdImageCreateFromGif("photo.gif"); /* Look for red in the color table. */ red = gdImageColorExact(im, 255, 0, 0); /* If red is present... */ if (red != (-1)) { /* Deallocate it. */ gdImageColorDeallocate(im, red); /* Allocate blue, reusing slot in table. Existing red pixels will change color. */ blue = gdImageColorAllocate(im, 0, 0, 255); } /* ... Do something with the image... */ /* Destroy it */ gdImageDestroy(im);
gdImageColorExact(gdImageHndl im, int r, int g, int b)
	gdImageColorExact searches the colors which have been defined thus far in the image specified. It returns the index of the first color with RGB values that exactly match those of the request. If no allocated color matches the request precisely, gdImageColorExact returns -1. im = gdImageCreateFromGif("photo.gif"); /*The image may already contain red; if it does, we'll save a slot in the color table by using that color. */ /* Try to allocate red directly */> red = gdImageColorExact(im, 255, 0, 0); /* If red isn't already present... */ if (red == (-1)) { /* Second best: try to allocate it directly. */ red = gdImageColorAllocate(im, 255, 0, 0); /* Out of colors, so find the closest color instead. */ red = gdImageColorClosest(im, 255, 0, 0); } /* Draw a dashed line from one corner to the other*/ gdImageDashedLine(im, 0, 0, 99, 99, red); /* ... Do something with the image */ /* Destroy it */ gdImageDestroy(im);
gdImageColorTransparent(gdImageHndl im, int color)
	gdImageColorTransparent sets the transparent color index for the specified image to the specified index. To indicate that there should be no transparent color, invoke gdImageColorTransparent with a color index of -1. The color index used should be an index allocated by gdImageColorAllocate, whether explicitly invoked by your code or implicitly invoked by loading an image. In order to ensure that your image has a reasonable appearance when viewed by users who do not have transparent background capabilities, be sure to give reasonable RGB values to the color you allocate for use as a transparent color, even though it will be transparent on systems that support transparency. im = gdImageCreateFromGif("photo.gif"); /* Look for black in the color table and make it transparent. */ black = gdImageColorExact(im, 0, 0, 0); /* If black is present... */ if (black != (-1)) { /* Make it transparent */ gdImageColorTransparent(im, black); } /* Save the newly-transparent image back to the file */ gdImageGif(im, "photo.gif"); /* Destroy it */ gdImageDestroy(im);
gdBrushed
	This value may ve used in place of a color when invoking a line-drawing function such as gdImageLine or gdImageRectangle. When gdBrushed is used as the color, the brush image (set with gdImageSetBrush) is drawn in place of each pixel of the line (the brush is usually larger than one pixel, creating the effect of a wide paintbrush). See also gdStyledBrushed for a way to draw broken lines with a series of distinct copies of an image.()
gdDashSize
	The length of a dash in a dashed line. Defined to be 4 for backwards compatibility with programs that use gdImageDashedLine. New programs should use gdImageSetStyle and call the standard gdImageLine function with the special "color" gdStyled or gdStyledBrushed.
gdMaxColors
	The constant 256. This is the maximum number of colors in a GIF file according to the GIF standard, and is also the maximum number of colors in a gd image.
gdStyled
	Used in place of a color when invoking a line-drawing function such as gdImageLine or gdImageRectangle. When gdStyled is used as the color, the colors of the pixels are drawn successively from the style that has been set with gdImageSetStyle. If the color of a pixel is equal to gdTransparent, that pixel is not altered. (This mechanism is completely unrelated to the "transparent color" of the image itself; see gdImageColorTransparent for that mechanism.) See also gdStyledBrushed.
gdStyledBrushed
	Used in place of a color when invoking a line-drawing function such as gdImageLine or gdImageRectangle. When gdStyledBrushed is used as the color, the brush image set with gdImageSetBrush is drawn at each pixel of the line, providing that the style set with gdImageSetStyle contains a nonzero value (OR gdTransparent, which does not equal zero but is supported for consistency) for the current pixel. (Pixels are drawn successively from the style as the line is drawn, returning to the beginning when the available pixels in the style are exhausted.) Note that this differs from the behavior of gdStyled, in which the values in the style are used as actual pixel colors, except for gdTransparent.
gdTiled
	Used in place of a normal color in gdImageFilledRectangle, gdImageFilledPolygon, gdImageFill, and gdImageFillToBorder. gdTiled selects a pixel from the tile image set with gdImageSetTile in such a way as to ensure that the filled area will be tiled with copies of the tile image. See the discussions of gdImageFill and gdImageFillToBorder for special restrictions regarding those functions.
gdTransparent
	Used in place of a normal color in a style to be set with gdImageSetStyle. gdTransparent is not the transparent color index of the image; for that functionality please see gdImageColorTransparent.