2 Up to the Boutell.Com, Inc. Home Page7 Credits and license terms
C In order to resolve any possible confusion regarding the authorship B of gd, the following copyright statement covers all of the authorsD who have required such a statement. Although his LZW compressionE code no longer appears in gd, the authors wish to thank David Rowley G for the original LZW-based GIF compression code, which has been removed G due to patent concerns. If you are aware of any oversights ) in this copyright notice, please contact D Thomas Boutell who will be ! pleased to correct them.
% COPYRIGHT STATEMENT FOLLOWS THIS LINE
? Portions copyright 1994, 1995, 1996, 1997, 1998, by Cold Spring B Harbor Laboratory. Funded under Grant P41-RR02188 by the National Institutes of Health.9 Portions copyright 1996, 1997, 1998, by Boutell.Com, Inc.
C GIF decompression code copyright 1990, 1991, 1993, by David Koblas (koblas@netcom.com).
G Non-LZW-based GIF compression code copyright 1998, by Hutchison Avenue N Software Corporation (http://www.hasc.com/, info@hasc.com).
E Permission has been granted to copy and distribute gd in any G context, including a commercial application, provided that this notice @ is present in user-accessible supporting documentation.
N This does not affect your ownership of the derived work itself, and the intentB is to assure proper credit for the authors of gd, not to interfere< with your productive use of gd. If you have questions, ask. @ "Derived works" includes all programs that utilize the library. 6 Credit must be given in user-accessible documentation.
F Permission to use, copy, modify, and distribute this software and its J documentation for any purpose and without fee is hereby granted, provided H that the above copyright notice appear in all copies and that both that A copyright notice and this permission notice appear in supporting E documentation. This software is provided "as is" without express or implied warranty.
END OF COPYRIGHT STATEMENT)
8 gd is a graphics library. It allows your code to quickly5 draw images complete with lines, arcs, text, multiple = colors, cut and paste from other images, and flood fills, and 9 write out the result as a .GIF file. This is particularly 8 useful in World Wide Web applications, where .GIF is the format used for inline images.
gd is not a paint program. : If you are looking for a paint program, you are looking in= the wrong place. If you are not a programmer, you are looking in the wrong place.
9 gd does not provide for every possible desirable graphics < operation. It is not necessary or desirable for gd to become= a kitchen-sink graphics package, but version 1.3 incorporates @ most of the commonly requested features for an 8-bit 2D package.> Support for scalable fonts, and truecolor images, JPEG and PNG? is planned for version 2.0. Version 1.3 was released to correct B longstanding bugs and provide an LZW-free GIF compression routine.
? What if I want to use another programming language?
@ These packages are based on gd 1.2 as of this writing but should1 be compatible with gd 1.3 with minimal tweaking.
@What's new in version 1.3?
+ Version 1.3 features the following changes:
pixels array will require changes. A To use gd, you will need an ANSI C compiler. All popular A Windows 95 and NT C compilers are ANSI C compliant. Any A full-ANSI-standard C compiler should be adequate. The cc > compiler released with SunOS 4.1.3 is not an ANSI C compiler. : Most Unix users who do not already have gcc should get it.= gcc is free, ANSI compliant and a de facto industry standard.r( Ask your ISP why it is missing.
t; You will also want a GIF viewer, if you do not already have @ one for your system, since you will need a good way to check the> results of your work. Any web browser will work, but you might7 be happier with a package like Lview Pro for Windows or=D xv for X. There are GIF viewers available for every graphics-capable5 computer out there, so consult newsgroups relevant tou your particular system.
e- How do I get gd?
<
a@ In order to build gd, you must first unpack the archive you have= downloaded. If you are not familiar with tar andn@ gunzip (Unix) or ZIP (Windows), pleaseA consult with an experienced user of your system. Sorry, we cannote- answer questions about basic Internet skills.e
o> Unpacking the archive will produce a directory called "gd1.3".
i
cd to the gd1.3 directory and examine the Makefile, which LE you will probably need to change slightly depending on your operatingo system and your needs.$ gd.c oD to your project. Add other source files as appropriate. Learning the@ basic skills of creating projects with your chosen C environment
is up to you.b r@ Now, to build the demonstration program, just type "make gddemo"D if you are working in a command-line environment, or build a projectH that includes gddemo.c if you are using a graphical environment. If all M goes well, the program "gddemo" will be compiled and linked without incident.g; Depending on your system you may need to edit the Makefile.=; Understanding the basic techniques of compiling and linkingo% programs on your system is up to you.
e: You have now built a demonstration program which shows off1 the capabilities of gd. To see it in action, type "gddemo".i
r9 gddemo should execute without incident, creating the filed9 demoout.gif. (Note there is also a file named demoin.gif,n? which is provided in the package as part of the demonstration.)o
i8 Display demoout.gif in your GIF viewer. The image should4 be 128x128 pixels and should contain an image of the: space shuttle with quite a lot of graphical elements drawn on top of it.t
8 (If you are missing the demoin.gif file, the other items should appear anyway.)
t4 Look at demoin.gif to see the original space shuttle8 image which was scaled and copied into the output image.
sA gd basics: using gd in your program
p; gd lets you create GIF images on the fly. To use gd in youre9 program, include the file gd.h, and link with the libgd.a/; library produced by "make libgd.a", under Unix. Under otherN8 operating systems you will add gd.c to your own project.
l. If you want to use the provided fonts, includeE gdfontt.h, gdfonts.h, gdfontmb.h, gdfontl.h and/or gdfontg.h. If you rG are not using the provided Makefile and/or a library-based approach, bel2 sure to include the source modules as well in your9 project. (They may be too large for 16-bit memory models,e! that is, 16-bit DOS and Windows.).
fF Here is a short example program. (For a more advanced example,N see gddemo.c, included in the distribution. gddemo.c is NOT the same program; . it demonstrates additional features!)
c
r# /* Bring in gd library functions */l #include "gd.h"e > /* Bring in standard I/O so we can output the GIF to a file */ #include <stdio.h> int main() { /* Declare the image */) gdImagePtr im;g /* Declare an output file */r FILE *out; /* Declare color indexes */ int black;t int white;n = /* Allocate the image: 64 pixels across by 64 pixels tall */o9 im = gdImageCreate(64, 64);a ? /* Allocate the color black (red, green and blue all minimum).s7 Since this is the first color in a new image, it will. be the background color. */lP black = gdImageColorAllocate(im, 0, 0, 0); B /* Allocate the color white (red, green and blue all maximum). */V white = gdImageColorAllocate(im, 255, 255, 255); 7 /* Draw a line from the upper left to the lower right,i using white color index. */cB gdImageLine(im, 0, 0, 63, 63, white); A /* Open a file for writing. "wb" means "write binary", importantd& under MSDOS, harmless under Unix. */ out = fopen("test.gif", "wb");h ) /* Output the image to the disk file. */d0 gdImageGif(im, out); /* Close the file. */
fclose(out);e # /* Destroy the image in memory. */<2 gdImageDestroy(im); }t 7 When executed, this program creates an image, allocatess< two colors (the first color allocated becomes the background: color), draws a diagonal line (note that 0, 0 is the upper1 left corner), writes the image to a GIF file, anda destroys the image.e o The above example program should* give you an idea of how the package works.7 gd provides many additional functions, which are listed 7 in the following reference chapters, complete with code - snippets demonstrating each. There is also anW) alphabetical index. @
o8 webgif.c is provided in the distribution. Unix users can6 simply type "make webgif" to compile the program. Type8 "webgif" with no arguments to see the available options.<
gdImage(TYPE)t sx (size on X axis),: sy (size on Y axis), colorsTotal: (total colors), red (red component of colors;? an array of 256 integers between 0 and 255), greenl8 (green component of colors, as above), blueB (blue component of colors, as above), and transparent6 (index of transparent color, -1 if none); please do so: using the macros provided. Do NOT set the members directly+ from your code; use the functions provided.q s typedef struct { unsigned char ** pixels;4 int sx; int sy; int colorsTotal;U int red[gdMaxColors]; int green[gdMaxColors]; int blue[gdMaxColors]; int open[gdMaxColors];s int transparent;
} gdImage; ? b 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;d: /* Font data; array of characters, one row after another.2 Easily included in code, also easily loaded from data files. */ char *data; } gdFont; = a typedef struct { int x, y;a } gdPoint, *gdPointPtr;h ? s ... inside a function ...e( gdImagePtr im; im = gdImageCreate(64, 64);h /* ... Use the image ... */ 1 gdImageDestroy(im);sF
a( gdImagePtr im; ... inside a function ...j FILE *in;m in = fopen("mygif.gif", "rb"); im = gdImageCreateFromGif(in); fclose(in);. /* ... Use the image ... */l1 gdImageDestroy(im);e D ... inside a function ...o( gdImagePtr im; FILE *in;5 in = fopen("mygd.gd", "rb"); im = gdImageCreateFromGd(in);g fclose(in); /* ... Use the image ... */R1 gdImageDestroy(im); F a ... inside a function ...i( gdImagePtr im; FILE *in;c in = fopen("myxbm.xbm", "rb"); im = gdImageCreateFromXbm(in); fclose(in);# /* ... Use the image ... */.1 gdImageDestroy(im); Z P ... inside a function ... ( gdImagePtr im;8 im = gdImageCreate(10, 10); /* ... Use the image ... */v /* Now destroy it */1 gdImageDestroy(im);<
n ... inside a function ...i( gdImagePtr im; int black, white;"
FILE *out; /* Create the image */: im = gdImageCreate(100, 100); /* Allocate background */TT white = gdImageColorAllocate(im, 255, 255, 255); /* Allocate drawing color */N black = gdImageColorAllocate(im, 0, 0, 0); /* Draw rectangle */J gdImageRectangle(im, 0, 0, 99, 99, black);% /* Open output file in binary mode */a out = fopen("rect.gif", "wb"); /* Write GIF */c gdImageGif(im, out); /* Close file */ fclose(out); /* Destroy image */01 gdImageDestroy(im); < The gd image format is intended for fast reads and writes of7 images your program will need frequently to build otherFC images. It is not a compressed format, and is not intendedr for general use.
h ... inside a function ...A( gdImagePtr im; int black, white;o
FILE *out; /* Create the image */: im = gdImageCreate(100, 100); /* Allocate background */ T white = gdImageColorAllocate(im, 255, 255, 255); /* Allocate drawing color */N black = gdImageColorAllocate(im, 0, 0, 0); /* Draw rectangle */J gdImageRectangle(im, 0, 0, 99, 99, black);% /* Open output file in binary mode */t out = fopen("rect.gd", "wb");t /* Write gd format file */ gdImageGd(im, out); /* Close file */ fclose(out); /* Destroy image */t1 gdImageDestroy(im);l # ... inside a function ...>( gdImagePtr im; int black; int white;: im = gdImageCreate(100, 100);( /* Background color (first allocated) */O black = gdImageColorAllocate(im, 0, 0, 0); eA /* Allocate the color white (red, green and blue all maximum). */dU white = gdImageColorAllocate(im, 255, 255, 255); o" /* Set a pixel near the center. */# gdImageSetPixel(im, 50, 50, white);/E /* ... Do something with the image, such as saving it to a file... */; /* Destroy it */1 gdImageDestroy(im);/h
A ... inside a function ...m( gdImagePtr im; int black; int white;: im = gdImageCreate(100, 100);( /* Background color (first allocated) */O black = gdImageColorAllocate(im, 0, 0, 0); iA /* Allocate the color white (red, green and blue all maximum). */)U white = gdImageColorAllocate(im, 255, 255, 255); gG /* Draw a line from the upper left corner to the lower right corner. */g% gdImageLine(im, 0, 0, 99, 99, white);GE /* ... Do something with the image, such as saving it to a file... */ /* Destroy it */1 gdImageDestroy(im);ot
F gdImageDashedLine is used to draw a dashed line between two endpoints (x1,y1 and x2, y2).>K The line is drawn using the color index specified. The portions of the lineNE that are not drawn are left transparent so the background is visible.o
r ... inside a function ...e( gdImagePtr im; int black; int white;: im = gdImageCreate(100, 100);( /* Background color (first allocated) */O black = gdImageColorAllocate(im, 0, 0, 0); mA /* Allocate the color white (red, green and blue all maximum). */mU white = gdImageColorAllocate(im, 255, 255, 255); fN /* Draw a dashed line from the upper left corner to the lower right corner. */$ gdImageDashedLine(im, 0, 0, 99, 99);E /* ... Do something with the image, such as saving it to a file... */r /* Destroy it */1 gdImageDestroy(im);=r
E ... inside a function ...O( gdImagePtr im; int black; int white; /* Points of polygon */e) gdPoint points[3];e: im = gdImageCreate(100, 100);( /* Background color (first allocated) */O black = gdImageColorAllocate(im, 0, 0, 0); mA /* Allocate the color white (red, green and blue all maximum). */aU white = gdImageColorAllocate(im, 255, 255, 255); c /* Draw a triangle. */ points[0].x = 50;m points[0].y = 0; points[1].x = 99;m points[1].y = 99;e points[2].x = 0; points[2].y = 99;r% gdImagePolygon(im, points, 3, white); E /* ... Do something with the image, such as saving it to a file... */* /* Destroy it */1 gdImageDestroy(im);r
x ... inside a function ...n( gdImagePtr im; int black; int white;: im = gdImageCreate(100, 100);( /* Background color (first allocated) */O black = gdImageColorAllocate(im, 0, 0, 0); yA /* Allocate the color white (red, green and blue all maximum). */ U white = gdImageColorAllocate(im, 255, 255, 255); N2 /* Draw a rectangle occupying the central area. */, gdImageRectangle(im, 25, 25, 74, 74, white);E /* ... Do something with the image, such as saving it to a file... */o /* Destroy it */1 gdImageDestroy(im);,~
C ... inside a function ...l( gdImagePtr im; int black; int white; int red; /* Points of polygon */>) gdPoint points[3];D: im = gdImageCreate(100, 100);( /* Background color (first allocated) */O black = gdImageColorAllocate(im, 0, 0, 0); A /* Allocate the color white (red, green and blue all maximum). */aU white = gdImageColorAllocate(im, 255, 255, 255); e /* Allocate the color red. */ O red = gdImageColorAllocate(im, 255, 0, 0); c /* Draw a triangle. */ points[0].x = 50;A points[0].y = 0; points[1].x = 99;. points[1].y = 99;e points[2].x = 0; points[2].y = 99; /* Paint it in white */*+ gdImageFilledPolygon(im, points, 3, white);i, /* Outline it in red; must be done second */A gdImagePolygon(im, points, 3, red);oE /* ... Do something with the image, such as saving it to a file... */a /* Destroy it */1 gdImageDestroy(im);t~
r ... inside a function ...a( gdImagePtr im; int black; int white;: im = gdImageCreate(100, 100);( /* Background color (first allocated) */O black = gdImageColorAllocate(im, 0, 0, 0); tA /* Allocate the color white (red, green and blue all maximum). */gY white = int gdImageColorAllocate(im, 255, 255, 255); t9 /* Draw a filled rectangle occupying the central area. */>2 gdImageFilledRectangle(im, 25, 25, 74, 74, white);E /* ... Do something with the image, such as saving it to a file... */e /* Destroy it */1 gdImageDestroy(im);Dr
s and ends atg= 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 G width and height being equal. e must be greater than s. Values greater l$ than 360 are interpreted modulo 360. a ... inside a function ... ( gdImagePtr im; int black; int white;9 im = gdImageCreate(100, 50);/( /* Background color (first allocated) */O black = gdImageColorAllocate(im, 0, 0, 0); A /* Allocate the color white (red, green and blue all maximum). */OU white = gdImageColorAllocate(im, 255, 255, 255); .' /* Inscribe an ellipse in the image. */ . gdImageArc(im, 50, 25, 98, 48, 0, 360, white);E /* ... Do something with the image, such as saving it to a file... */r /* Destroy it */1 gdImageDestroy(im);dn
color, beginning at the specified point and stopping at #A the specified border color. For a way of flooding anA4 area defined by the color of the starting point, see' gdImageFill.l e3 The border color cannot be a special colorD; such as gdTiled; it must be a propere, solid color. The fill color can be, however.
.> Note that gdImageFillToBorder is recursive. It is not the most8 naive implementation possible, and the implementation is8 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,d8 in a Unix or NT environment with a proper stack, this is not a problem at all.)
... inside a function ...a( gdImagePtr im; int black; int white; int red;9 im = gdImageCreate(100, 50);e( /* Background color (first allocated) */O black = gdImageColorAllocate(im, 0, 0, 0); eA /* Allocate the color white (red, green and blue all maximum). */NU white = gdImageColorAllocate(im, 255, 255, 255); n /* Allocate the color red. */#O red = gdImageColorAllocate(im, 255, 0, 0); a' /* Inscribe an ellipse in the image. */g. 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);E /* ... Do something with the image, such as saving it to a file... */, /* Destroy it */1 gdImageDestroy(im);tR
color, beginning at the specified point and flooding theg; surrounding region of the same color as the starting point.o; For a way of flooding a region defined by a specific border , color rather than by its interior color, see7 gdImageFillToBorder. l? The fill color can be gdTiled, resultingE8 in a tile fill using another image as the tile. However,; the tile image cannot be transparent. If the image you wish*0 to fill with has a transparent color index, call; gdImageTransparent on theB5 tile image and set the transparent color index to -1 # to turn off its transparency.l
o6 Note that gdImageFill is recursive. It is not the most8 naive implementation possible, and the implementation is8 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,.8 in a Unix or NT environment with a proper stack, this is not a problem at all.)
i ... inside a function ...g( gdImagePtr im; int black; int white; int red;9 im = gdImageCreate(100, 50); ( /* Background color (first allocated) */O black = gdImageColorAllocate(im, 0, 0, 0); RA /* Allocate the color white (red, green and blue all maximum). */lU white = gdImageColorAllocate(im, 255, 255, 255); . /* Allocate the color red. */EO red = gdImageColorAllocate(im, 255, 0, 0); e' /* Inscribe an ellipse in the image. */B. gdImageArc(im, 50, 25, 98, 48, 0, 360, white);B /* Flood-fill the ellipse. Fill color is red, and will replace the" black interior of the ellipse. */ gdImageFill(im, 50, 50, red);*E /* ... Do something with the image, such as saving it to a file... */, /* Destroy it */1 gdImageDestroy(im);/W
f< gdImageSetBrush is used to specify the brush to be used in a8 particular image. You can set any image to be the brush.: If the brush image does not have the same color map as the4 first image, any colors missing from the first image9 will be allocated. If not enough colors can be allocated, 7 the closest colors already available will be used. This>9 allows arbitrary GIFs to be used as brush images. It also0: means, however, that you should not set a brush unless you6 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.
H: You need not take any special action when you are finished5 with a brush. As for any other image, if you will noti1 be using the brush image for any further purpose,m= you should call gdImageDestroy.a= You must not use the color gdBrushedn3 if the current brush has been destroyed; you can of>% course set a new brush to replace it.e
g ... inside a function ...r/ gdImagePtr im, brush;, FILE *in;
int black;: im = gdImageCreate(100, 100);8 /* Open the brush GIF. For best results, portions of the6 brush that should be transparent (ie, not part of the9 brush shape) should have the transparent color index. */a in = fopen("star.gif", "rb");#E brush = gdImageCreateFromGif(in);c( /* Background color (first allocated) */O black = gdImageColorAllocate(im, 0, 0, 0); e gdImageSetBrush(im, brush);*C /* Draw a line from the upper left corner to the lower right cornere using the brush. */] gdImageLine(im, 0, 0, 99, 99, gdBrushed);sE /* ... Do something with the image, such as saving it to a file... */ /* Destroy it */1 gdImageDestroy(im);y /* Destroy the brush image */n4 gdImageDestroy(brush); T =: gdImageSetTile is used to specify the tile to be used in a7 particular image. You can set any image to be the tile.l9 If the tile image does not have the same color map as them4 first image, any colors missing from the first image9 will be allocated. If not enough colors can be allocated,47 the closest colors already available will be used. Thisu8 allows arbitrary GIFs to be used as tile images. It also9 means, however, that you should not set a tile unless youA6 will actually use it; if you set a rapid succession of; different tile images, you can quickly fill your color map,U$ and the results will not be optimal.
e: You need not take any special action when you are finished4 with a tile. As for any other image, if you will not0 be using the tile image for any further purpose,= you should call gdImageDestroy.a; You must not use the color gdTiledP2 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;m
int black;: im = gdImageCreate(100, 100);7 /* Open the tile GIF. For best results, portions of theb2 tile that should be transparent (ie, allowing the: background to shine through) should have the transparent color index. */ in = fopen("star.gif", "rb");aD tile = gdImageCreateFromGif(in);( /* Background color (first allocated) */O black = gdImageColorAllocate(im, 0, 0, 0); = gdImageSetTile(im, tile);d" /* Fill an area using the tile. */q gdImageFilledRectangle(im, 25, 25, 75, 75, gdTiled); E /* ... Do something with the image, such as saving it to a file... */t /* Destroy it */1 gdImageDestroy(im); /* Destroy the tile image */3 gdImageDestroy(tile);> b => To use gdImageSetStyle, create an array of integers and assign8 them the desired series of color values to be repeated. @ You can assign the special color value < gdTransparent to indicate that the existing color should> be left unchanged for that particular pixel (allowing a dashed7 line to be attractively drawn over an existing image). o
h4 Then, to draw a line using the style, use the normal8 gdImageLine function with the5 special color value gdStyled.n
l; As of version 1.1.1, the stylea7 array is copied when you set the style, so you need not 8 be concerned with keeping the array around indefinitely.7 This should not break existing code that assumes stylesa are not copied.a
c9 You can also combine styles and brushes to draw the brusho6 image at intervals instead of in a continuous stroke. / When creating a style for use with a brush, theo< style values are interpreted differently: zero (0) indicates= pixels at which the brush should not be drawn, while one (1) 5 indicates pixels at which the brush should be drawn. e0 To draw a styled, brushed line, you must use the/ special color value n3 gdStyledBrushed. For an example of this featurer4 in use, see gddemo.c (provided in the distribution).
I( gdImagePtr im;# int styleDotted[2], styleDashed[6]; FILE *in; int black; int red;: im = gdImageCreate(100, 100);( /* Background color (first allocated) */O black = gdImageColorAllocate(im, 0, 0, 0); >O red = gdImageColorAllocate(im, 255, 0, 0); l9 /* Set up dotted style. Leave every other pixel alone. */I styleDotted[0] = red;h styleDotted[1] = gdTransparent;2/ /* Set up dashed style. Three on, three off. */i styleDashed[0] = red; styleDashed[1] = red;b styleDashed[2] = red;l styleDashed[3] = gdTransparent; styleDashed[4] = gdTransparent;t styleDashed[5] = gdTransparent;fE /* Set dotted style. Note that we have to specify how many pixels are/ in the style! */D$ gdImageSetStyle(im, styleDotted, 2);G /* Draw a line from the upper left corner to the lower right corner. */O[ gdImageLine(im, 0, 0, 99, 99, gdStyled);s /* Now the dashed line. */$ gdImageSetStyle(im, styleDashed, 6);[ gdImageLine(im, 0, 99, 0, 99, gdStyled);o F /* ... Do something with the image, such as saving it to a file ... */ /* Destroy it */1 gdImageDestroy(im);n
F ... inside a function ...s FILE *in; gdImagePtr im; int c; in = fopen("mygif.gif", "rb");B im = gdImageCreateFromGif(in); fclose(in);s> c = gdImageGetPixel(im, gdImageSX(im) / 2, gdImageSY(im) / 2);H printf("The value of the center pixel is %d; RGB values are %d,%d,%d\n",+ c, im->red[c], im->green[c], im->blue[c]);f1 gdImageDestroy(im);r o ... inside a function ...i( gdImagePtr im;
int black;
int white;: im = gdImageCreate(100, 100);$ if (gdImageBoundsSafe(im, 50, 50)) {/ printf("50, 50 is within the image bounds\n");F } else {0 printf("50, 50 is outside the image bounds\n"); }c1 gdImageDestroy(im);o t #include "gd.h"a #include "gdfontl.h" ... inside a function ...l( gdImagePtr im; int black; int white;: im = gdImageCreate(100, 100);( /* Background color (first allocated) */O black = gdImageColorAllocate(im, 0, 0, 0); A /* Allocate the color white (red, green and blue all maximum). */tU white = gdImageColorAllocate(im, 255, 255, 255); /* Draw a character. */r/ gdImageChar(im, gdFontLarge, 0, 0, 'Q', white);cE /* ... Do something with the image, such as saving it to a file... */a /* Destroy it */1 gdImageDestroy(im);)
e #include "gd.h"h #include "gdfontl.h" ... inside a function ...g( gdImagePtr im; int black; int white;: im = gdImageCreate(100, 100);( /* Background color (first allocated) */O black = gdImageColorAllocate(im, 0, 0, 0); lA /* Allocate the color white (red, green and blue all maximum). */nU white = gdImageColorAllocate(im, 255, 255, 255); H /* Draw a character upwards so it rests against the top of the image. */ gdImageCharUp(im, gdFontLarge, m 0, gdFontLarge->h, 'Q', white);E /* ... Do something with the image, such as saving it to a file... */t /* Destroy it */1 gdImageDestroy(im);
#include "gd.h"g #include "gdfontl.h" #include <string.h> ... inside a function ...x( gdImagePtr im; int black; int white; /* String to draw. */h char *s = "Hello.";o: im = gdImageCreate(100, 100);( /* Background color (first allocated) */O black = gdImageColorAllocate(im, 0, 0, 0); ,A /* Allocate the color white (red, green and blue all maximum). */RU white = gdImageColorAllocate(im, 255, 255, 255); /* Draw a centered string. */i gdImageString(im, gdFontLarge,. im->w / 2 - (strlen(s) * gdFontLarge->w / 2), im->h / 2 - gdFontLarge->h / 2, s, white);DE /* ... Do something with the image, such as saving it to a file... */r /* Destroy it */1 gdImageDestroy(im);r
e@ This function was added in gd1.3 to provide a means of rendering> fonts with more than 256 characters for those who have them. AK more frequently used routine is gdImageString.
u #include "gd.h"t #include "gdfontl.h" #include <string.h>e ... inside a function ...M( gdImagePtr im; int black; int white; /* String to draw. */g char *s = "Hello.";r: im = gdImageCreate(100, 100);( /* Background color (first allocated) */O black = gdImageColorAllocate(im, 0, 0, 0); HA /* Allocate the color white (red, green and blue all maximum). */mU white = gdImageColorAllocate(im, 255, 255, 255); ; /* Draw a centered string going upwards. Axes are reversed,a4 and Y axis is decreasing as the string is drawn. */ gdImageStringUp(im, gdFontLarge, im->w / 2 - gdFontLarge->h / 2,. im->h / 2 + (strlen(s) * gdFontLarge->w / 2), s, white); E /* ... Do something with the image, such as saving it to a file... */o /* Destroy it */1 gdImageDestroy(im);n
.@ This function was added in gd1.3 to provide a means of rendering> fonts with more than 256 characters for those who have them. AT more frequently used routine is gdImageStringUp.
C In the event that all gdMaxColors colorss< (256) have already been allocated, gdImageColorAllocate will9 return -1 to indicate failure. (This is not uncommon whenp= working with existing GIF files that already use 256 colors.)e Note that gdImageColorAllocate; does not check for existing colors that match your request; 6 see gdImageColorExact: and gdImageColorClosest7 for ways to locate existing colors that approximate the>? color desired in situations where a new color is not available.g
< ... inside a function ...n( gdImagePtr im; int black; int red;: im = gdImageCreate(100, 100);( /* Background color (first allocated) */O black = gdImageColorAllocate(im, 0, 0, 0); , /* Allocate the color red. */hO red = gdImageColorAllocate(im, 255, 0, 0); dN /* Draw a dashed line from the upper left corner to the lower right corner. */) gdImageDashedLine(im, 0, 0, 99, 99, red);DE /* ... Do something with the image, such as saving it to a file... */> /* Destroy it */1 gdImageDestroy(im);o"
"2 If no colors have yet been allocated in the image, gdImageColorClosest returns -1.e
r< This function is most useful as a backup method for choosing. a drawing color when an image already contains7 gdMaxColors (256) colors andt4 no more can be allocated. (This is not uncommon when> working with existing GIF files that already use many colors.)6 See gdImageColorExact, for a method of locating exact matches only.
d ... inside a function ...n( gdImagePtr im; FILE *in;g int red;< /* Let's suppose that photo.gif is a scanned photograph with many colors. */ in = fopen("photo.gif", "rb");B im = gdImageCreateFromGif(in); fclose(in); " /* Try to allocate red directly */O red = gdImageColorAllocate(im, 255, 0, 0); n# /* If we fail to allocate red... */H if (red == (-1)) {/ /* Find the closest color instead. */5* red = gdImageColorClosest(im, 255, 0, 0); }rM /* Draw a dashed line from the upper left corner to the lower right corner */2) gdImageDashedLine(im, 0, 0, 99, 99, red);.E /* ... Do something with the image, such as saving it to a file... */s /* Destroy it */1 gdImageDestroy(im);> n ... inside a function ...g( gdImagePtr im; int red; in = fopen("photo.gif", "rb");B im = gdImageCreateFromGif(in); fclose(in);tC /* The image may already contain red; if it does, we'll save a slote+ in the color table by using that color. */f" /* Try to allocate red directly */' red = gdImageColorExact(im, 255, 0, 0);d% /* If red isn't already present... */i if (red == (-1)) {0 /* Second best: try to allocate it directly. */P red = gdImageColorAllocate(im, 255, 0, 0); A /* Out of colors, so find the closest color instead. */e* red = gdImageColorClosest(im, 255, 0, 0); }eM /* Draw a dashed line from the upper left corner to the lower right corner */I) gdImageDashedLine(im, 0, 0, 99, 99, red); E /* ... Do something with the image, such as saving it to a file... */T /* Destroy it */1 gdImageDestroy(im);t ! A ... inside a function ...r( gdImagePtr im; int red, blue; in = fopen("photo.gif", "rb");B im = gdImageCreateFromGif(in); fclose(in);h& /* Look for red in the color table. */' red = gdImageColorExact(im, 255, 0, 0);e /* If red is present... */ if (red != (-1)) { /* Deallocate it. */c! gdImageColorDeallocate(im, red);<) /* Allocate blue, reusing slot in table.t+ Existing red pixels will change color. */ , blue = gdImageColorAllocate(im, 0, 0, 255); } E /* ... Do something with the image, such as saving it to a file... */i /* Destroy it */1 gdImageDestroy(im);5 & ' The color index used should be an index F allocated by gdImageColorAllocate,5 whether explicitly invoked by your code or implicitlyq 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 backgroundo: capabilities, be sure to give reasonable RGB values to the2 color you allocate for use as a transparent color,1 even though it will be transparent on systems> that support transparency.<
" ... inside a function ...t( gdImagePtr im;
int black; FILE *in, *out;H in = fopen("photo.gif", "rb");B im = gdImageCreateFromGif(in); fclose(in);E@ /* Look for black in the color table and make it transparent. */H black = gdImageColorExact(im, 0, 0, 0); /* If black is present... */ if (black != (-1)) { /* Make it transparent */$ gdImageColorTransparent(im, black); } 7 /* Save the newly-transparent image back to the file */s out = fopen("photo.gif", "wb");M. gdImageGif(im, out); fclose(out); /* Destroy it */1 gdImageDestroy(im);m C The dst argument is the destination image to which the=B region will be copied. The src argument is the source< image from which the region is copied. The dstXD and dstY arguments specify the point in the destination? image to which the region will be copied. The srcXl= and srcY arguments specify the upper left cornerd5 of the region in the source image. The we9 and h arguments specify the width and height of the region.
.? When you copy a region from one location in an image to anotherr@ location in the same image, gdImageCopy will perform as expected7 unless the regions overlap, in which case the result ise unpredictable.
nA Important note on copying between images: since d different images do L 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 foro7 each pixel in the copied portion of the source image bys? invoking gdImageColorExact. Ifi6 such a value is not found, gdImageCopy will attempt to@ allocate colors as needed using 8 gdImageColorAllocate. If both of these methods fail,7 gdImageCopy will invoke c< gdImageColorClosest to find the color in the destination6 image which most closely approximates the color of the pixel being copied.h
u ... Inside a function ...E+ gdImagePtr im_in;l, gdImagePtr im_out; int x, y;o FILE *in;o
FILE *out;2 /* Load a small gif to tile the larger one with */ in = fopen("small.gif", "rb");E im_in = gdImageCreateFromGif(in);r fclose(in);g< /* Make the output image four times as large on both axes */S im_out = gdImageCreate(im_in->sx * 4, im_in->sy * 4); 5 /* Now tile the larger image using the smaller one */d 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);I } }o out = fopen("tiled.gif", "wb");A2 gdImageGif(im_out, out); fclose(out);4 gdImageDestroy(im_in);5 gdImageDestroy(im_out);f ª dC The dst argument is the destination image to which thelB region will be copied. The src argument is the source< image from which the region is copied. The dstXD and dstY arguments specify the point in the destination? image to which the region will be copied. The srcXM= and srcY arguments specify the upper left cornerr8 of the region in the source image. The dstW< and dstH arguments specify the width and height0 of the destination region. The srcW< and srcH arguments specify the width and height> of the source region and can differ from the destination size,: allowing a region to be scaled during the copying process.
U? When you copy a region from one location in an image to anotheru@ location in the same image, gdImageCopy will perform as expected7 unless the regions overlap, in which case the result isRA unpredictable. If this presents a problem, create a scratch image)& in which to keep intermediate results.
tH Important note on copying between images: since images I do not necessarily have the same color tables, pixels are not simply set eE to the same color index values to copy them. gdImageCopy will attemptd; to find an identical RGB value in the destination image forN7 each pixel in the copied portion of the source image bys? invoking gdImageColorExact. Ifi6 such a value is not found, gdImageCopy will attempt to@ allocate colors as needed using 8 gdImageColorAllocate. If both of these methods fail,7 gdImageCopy will invoke << gdImageColorClosest to find the color in the destination6 image which most closely approximates the color of the pixel being copied.m
e ... Inside a function ... + gdImagePtr im_in;a, gdImagePtr im_out; int x, y;g FILE *in;a
FILE *out;2 /* Load a small gif to expand in the larger one */ in = fopen("small.gif", "rb");E im_in = gdImageCreateFromGif(in);I fclose(in);l< /* Make the output image four times as large on both axes */S im_out = gdImageCreate(im_in->sx * 4, im_in->sy * 4); o7 /* Now copy the smaller image, but four times larger */e. gdImageCopyResized(im_out, im_in, 0, 0, 0, 0, im_out->sx, im_out->sy, im_in->sx, im_in->sy); r out = fopen("large.gif", "wb");e2 gdImageGif(im_out, out); fclose(out);4 gdImageDestroy(im_in);5 gdImageDestroy(im_out);( > A nonzero value for the interlace argument turns on interlace;< a zero value turns it off. Note that interlace has no effect: on other functions, and has no meaning unless you save the: image in GIF format; the gd and xbm formats do not support interlace. e
dN When a GIF is loaded with gdImageCreateFromGifE , interlace will be set according to the setting in the GIF file.n
C Note that many GIF viewers and web browsers do not supporta? interlace. However, the interlaced GIF should still display; itb8 will simply appear all at once, just as other images do.
o gdImagePtr im;
FILE *out;% /* ... Create or load the image... */t /* Now turn on interlace */ gdImageInterlace(im, 1); s /* And open an output file */i out = fopen("test.gif", "wb"); /* And save the image */. gdImageGif(im, out); fclose(out);1 gdImageDestroy(im);a gdMaxColors(CONSTANT)> eA The program "giftogd.c" is provided as a simple way of convertinge= .gif files to .gd format. I emphasize again that you will nothE need to use this format unless you have a need for high-speed loadinge0 of a few frequently-used images in your program.< Please tell us you're using gd!
5 When you contact us and let us know you are using gd,s? you help us justify the time spent in maintaining and improvingi6 it. So please let us know. If the results are publicly> visible on the web, a URL is a wonderful thing to receive, but> if it's not a publicly visible project, a simple note is just as welcome.l4 If you have problems
: If you have any difficulties with gd, feel free to contactJ the author, Thomas Boutell. , Be sure to read this manual carefully first.5