1 SEE INDEX.HTML FOR AN EASILY BROWSED HYPERTEXT VERSION OF THIS MANUAL.
3 * * *
5 gd 1.3
7 A graphics library for fast GIF creation
9 Follow this link to the latest version of this document.
11 Table of Contents
13 * Credits and license terms
14 * What's new in version 1.3?
15 * What is gd?
16 * What if I want to use another programming language?
17 * What else do I need to use gd?
18 * How do I get gd?
19 * How do I build gd?
20 * gd basics: using gd in your program
21 * webgif: a useful example
22 * Function and type reference by category
23 * About the additional .gd image file format
24 * Please tell us you're using gd!
25 * If you have problems
26 * Alphabetical quick index
28 Up to the Boutell.Com, Inc. Home Page
30 Credits and license terms
32 In order to resolve any possible confusion regarding the authorship of
33 gd, the following copyright statement covers all of the authors who
34 have required such a statement. Although his LZW compression code no
35 longer appears in gd, the authors wish to thank David Rowley for the
36 original LZW-based GIF compression code, which has been removed due to
37 patent concerns. If you are aware of any oversights in this copyright
38 notice, please contact Thomas Boutell who will be pleased to correct
39 them.
41 COPYRIGHT STATEMENT FOLLOWS THIS LINE
43 Portions copyright 1994, 1995, 1996, 1997, 1998, by Cold Spring
44 Harbor Laboratory. Funded under Grant P41-RR02188 by the National
45 Institutes of Health.
47 Portions copyright 1996, 1997, 1998, by Boutell.Com, Inc.
49 GIF decompression code copyright 1990, 1991, 1993, by David Koblas
50 (koblas@netcom.com).
52 Non-LZW-based GIF compression code copyright 1998, by Hutchison
53 Avenue Software Corporation (http://www.hasc.com/, info@hasc.com).
55 Permission has been granted to copy and distribute gd in any
56 context, including a commercial application, provided that this
57 notice is present in user-accessible supporting documentation.
59 This does not affect your ownership of the derived work itself, and
60 the intent is to assure proper credit for the authors of gd, not to
61 interfere with your productive use of gd. If you have questions,
62 ask. "Derived works" includes all programs that utilize the
63 library. Credit must be given in user-accessible documentation.
65 Permission to use, copy, modify, and distribute this software and
66 its documentation for any purpose and without fee is hereby
67 granted, provided that the above copyright notice appear in all
68 copies and that both that copyright notice and this permission
69 notice appear in supporting documentation. This software is
70 provided "as is" without express or implied warranty.
72 END OF COPYRIGHT STATEMENT
74 What is gd?
76 gd is a graphics library. It allows your code to quickly draw images
77 complete with lines, arcs, text, multiple colors, cut and paste from
78 other images, and flood fills, and write out the result as a .GIF
79 file. This is particularly useful in World Wide Web applications,
80 where .GIF is the format used for inline images.
82 gd is not a paint program. If you are looking for a paint program, you
83 are looking in the wrong place. If you are not a programmer, you are
84 looking in the wrong place.
86 gd does not provide for every possible desirable graphics operation.
87 It is not necessary or desirable for gd to become a kitchen-sink
88 graphics package, but version 1.3 incorporates most of the commonly
89 requested features for an 8-bit 2D package. Support for scalable
90 fonts, and truecolor images, JPEG and PNG is planned for version 2.0.
91 Version 1.3 was released to correct longstanding bugs and provide an
92 LZW-free GIF compression routine.
94 What if I want to use another programming language?
96 Perl
98 gd can also be used from Perl, courtesy of Lincoln Stein's GD.pm
99 library, which uses gd as the basis for a set of Perl 5.x classes.
100 GD.pm is based on gd 1.1.1 but gd 1.2 should be compatible.
102 Any Language
104 There are, at the moment, at least three simple interpreters that
105 perform gd operations. You can output the desired commands to a simple
106 text file from whatever scripting language you prefer to use, then
107 invoke the interpreter.
109 These packages are based on gd 1.2 as of this writing but should be
110 compatible with gd 1.3 with minimal tweaking.
111 * tgd, by Bradley K. Sherman
112 * fly, by Martin Gleeson
114 What's new in version 1.3?
116 Version 1.3 features the following changes:
118 Non-LZW-based GIF compression code
119 Version 1.3 contains GIF compression code that uses simple Run
120 Length Encoding instead of LZW compression, while still
121 retaining compatibility with normal LZW-based GIF decoders
122 (your browser will still like your GIFs). LZW compression is
123 patented by Unisys. This is why there have been no new versions
124 of gd for a long time. THANKS to Hutchison Avenue Software
125 Corporation for contributing this code. THE NEW CODE PRODUCES
126 LARGER GIFS AND IS NOT WELL SUITED TO PHOTOGRAPHIC IMAGES. THIS
127 IS A LEGAL ISSUE. IT IS NOT A QUESTION OF TECHNICAL SKILL.
128 PLEASE DON'T COMPLAIN ABOUT THE SIZE OF GIF OUTPUT. THANKS!
130 8-bit fonts, and 8-bit font support
131 This improves support for European languages. Thanks are due to
132 Honza Pazdziora and also to Jan Pazdziora . Also see the
133 provided bdftogd Perl script if you wish to convert fixed-width
134 X11 fonts to gd fonts.
136 16-bit font support (no fonts provided)
137 Although no such fonts are provided in the distribution, fonts
138 containing more than 256 characters should work if the
139 gdImageString16 and gdImageStringUp16 routines are used.
141 Improvements to the "webgif" example/utility
142 The "webgif" utility is now a slightly more useful application.
143 Thanks to Brian Dowling for this code.
145 Corrections to the color resolution field of GIF output
146 Thanks to Bruno Aureli.
148 Fixed polygon fills
149 A one-line patch for the infamous polygon fill bug, courtesy of
150 Jim Mason. I believe this fix is sufficient. However, if you
151 find a situation where polygon fills still fail to behave
152 properly, please send code that demonstrates the problem, and a
153 fix if you have one. Verifying the fix is important.
155 Row-major, not column-major
156 Internally, gd now represents the array of pixels as an array
157 of rows of pixels, rather than an array of columns of pixels.
158 This improves the performance of compression and decompression
159 routines slightly, because horizontally adjacent pixels are now
160 next to each other in memory. This should not affect properly
161 written gd applications, but applications that directly
162 manipulate the pixels array will require changes.
164 What else do I need to use gd?
166 To use gd, you will need an ANSI C compiler. All popular Windows 95
167 and NT C compilers are ANSI C compliant. Any full-ANSI-standard C
168 compiler should be adequate. The cc compiler released with SunOS 4.1.3
169 is not an ANSI C compiler. Most Unix users who do not already have gcc
170 should get it. gcc is free, ANSI compliant and a de facto industry
171 standard. Ask your ISP why it is missing.
173 You will also want a GIF viewer, if you do not already have one for
174 your system, since you will need a good way to check the results of
175 your work. Any web browser will work, but you might be happier with a
176 package like Lview Pro for Windows or xv for X. There are GIF viewers
177 available for every graphics-capable computer out there, so consult
178 newsgroups relevant to your particular system.
180 How do I get gd?
182 By HTTP
184 * Gzipped Tar File (Unix)
185 * .ZIP File (Windows)
187 By FTP
189 * Gzipped Tar File (Unix)
190 * .ZIP File (Windows)
192 How do I build gd?
194 In order to build gd, you must first unpack the archive you have
195 downloaded. If you are not familiar with tar and gunzip (Unix) or ZIP
196 (Windows), please consult with an experienced user of your system.
197 Sorry, we cannot answer questions about basic Internet skills.
199 Unpacking the archive will produce a directory called "gd1.3".
201 For Unix
203 cd to the gd1.3 directory and examine the Makefile, which you will
204 probably need to change slightly depending on your operating system
205 and your needs.
207 For Windows, Mac, Et Cetera
209 Create a project using your favorite programming environment. Copy all
210 of the gd files to the project directory. Add gd.c to your project.
211 Add other source files as appropriate. Learning the basic skills of
212 creating projects with your chosen C environment is up to you.
214 Now, to build the demonstration program, just type "make gddemo" if
215 you are working in a command-line environment, or build a project that
216 includes gddemo.c if you are using a graphical environment. If all
217 goes well, the program "gddemo" will be compiled and linked without
218 incident. Depending on your system you may need to edit the Makefile.
219 Understanding the basic techniques of compiling and linking programs
220 on your system is up to you.
222 You have now built a demonstration program which shows off the
223 capabilities of gd. To see it in action, type "gddemo".
225 gddemo should execute without incident, creating the file demoout.gif.
226 (Note there is also a file named demoin.gif, which is provided in the
227 package as part of the demonstration.)
229 Display demoout.gif in your GIF viewer. The image should be 128x128
230 pixels and should contain an image of the space shuttle with quite a
231 lot of graphical elements drawn on top of it.
233 (If you are missing the demoin.gif file, the other items should appear
234 anyway.)
236 Look at demoin.gif to see the original space shuttle image which was
237 scaled and copied into the output image.
239 gd basics: using gd in your program
241 gd lets you create GIF images on the fly. To use gd in your program,
242 include the file gd.h, and link with the libgd.a library produced by
243 "make libgd.a", under Unix. Under other operating systems you will add
244 gd.c to your own project.
246 If you want to use the provided fonts, include gdfontt.h, gdfonts.h,
247 gdfontmb.h, gdfontl.h and/or gdfontg.h. If you are not using the
248 provided Makefile and/or a library-based approach, be sure to include
249 the source modules as well in your project. (They may be too large for
250 16-bit memory models, that is, 16-bit DOS and Windows.)
252 Here is a short example program. (For a more advanced example, see
253 gddemo.c, included in the distribution. gddemo.c is NOT the same
254 program; it demonstrates additional features!)
256 /* Bring in gd library functions */
257 #include "gd.h"
259 /* Bring in standard I/O so we can output the GIF to a file */
260 #include <stdio.h>
262 int main() {
263 /* Declare the image */
264 gdImagePtr im;
265 /* Declare an output file */
266 FILE *out;
267 /* Declare color indexes */
268 int black;
269 int white;
271 /* Allocate the image: 64 pixels across by 64 pixels tall */
272 im = gdImageCreate(64, 64);
274 /* Allocate the color black (red, green and blue all minimum).
275 Since this is the first color in a new image, it will
276 be the background color. */
277 black = gdImageColorAllocate(im, 0, 0, 0);
279 /* Allocate the color white (red, green and blue all maximum). */
280 white = gdImageColorAllocate(im, 255, 255, 255);
282 /* Draw a line from the upper left to the lower right,
283 using white color index. */
284 gdImageLine(im, 0, 0, 63, 63, white);
286 /* Open a file for writing. "wb" means "write binary", important
287 under MSDOS, harmless under Unix. */
288 out = fopen("test.gif", "wb");
290 /* Output the image to the disk file. */
291 gdImageGif(im, out);
293 /* Close the file. */
294 fclose(out);
296 /* Destroy the image in memory. */
297 gdImageDestroy(im);
298 }
300 When executed, this program creates an image, allocates two colors
301 (the first color allocated becomes the background color), draws a
302 diagonal line (note that 0, 0 is the upper left corner), writes the
303 image to a GIF file, and destroys the image.
305 The above example program should give you an idea of how the package
306 works. gd provides many additional functions, which are listed in the
307 following reference chapters, complete with code snippets
308 demonstrating each. There is also an alphabetical index.
310 Webgif: a more powerful gd example
312 Webgif is a simple utility program to manipulate GIFs from the command
313 line. It is written for Unix and similar command-line systems, but
314 should be easily adapted for other environments. Webgif allows you to
315 set transparency and interlacing and output interesting information
316 about the GIF in question.
318 webgif.c is provided in the distribution. Unix users can simply type
319 "make webgif" to compile the program. Type "webgif" with no arguments
320 to see the available options.
322 Function and type reference
324 * Types
325 * Image creation, destruction, loading and saving
326 * Drawing, styling, brushing, tiling and filling functions
327 * Query functions (not color-related)
328 * Font and text-handling functions
329 * Color handling functions
330 * Copying and resizing functions
331 * Miscellaneous Functions
332 * Constants
334 Types
336 gdImage(TYPE)
337 The data structure in which gd stores images. gdImageCreate
338 returns a pointer to this type, and the other functions expect
339 to receive a pointer to this type as their first argument. You
340 may read the members sx (size on X axis), sy (size on Y axis),
341 colorsTotal (total colors), red (red component of colors; an
342 array of 256 integers between 0 and 255), green (green
343 component of colors, as above), blue (blue component of colors,
344 as above), and transparent (index of transparent color, -1 if
345 none); please do so using the macros provided. Do NOT set the
346 members directly from your code; use the functions provided.
349 typedef struct {
350 unsigned char ** pixels;
351 int sx;
352 int sy;
353 int colorsTotal;
354 int red[gdMaxColors];
355 int green[gdMaxColors];
356 int blue[gdMaxColors];
357 int open[gdMaxColors];
358 int transparent;
359 } gdImage;
361 gdImagePtr (TYPE)
362 A pointer to an image structure. gdImageCreate returns this
363 type, and the other functions expect it as the first argument.
365 gdFont (TYPE)
366 A font structure. Used to declare the characteristics of a
367 font. Plese see the files gdfontl.c and gdfontl.h for an
368 example of the proper declaration of this structure. You can
369 provide your own font data by providing such a structure and
370 the associated pixel array. You can determine the width and
371 height of a single character in a font by examining the w and h
372 members of the structure. If you will not be creating your own
373 fonts, you will not need to concern yourself with the rest of
374 the components of this structure.
377 typedef struct {
378 /* # of characters in font */
379 int nchars;
380 /* First character is numbered... (usually 32 = space) */
381 int offset;
382 /* Character width and height */
383 int w;
384 int h;
385 /* Font data; array of characters, one row after another.
386 Easily included in code, also easily loaded from
387 data files. */
388 char *data;
389 } gdFont;
391 gdFontPtr (TYPE)
392 A pointer to a font structure. Text-output functions expect
393 these as their second argument, following the gdImagePtr
394 argument. Two such pointers are declared in the provided
395 include files gdfonts.h and gdfontl.h.
397 gdPoint (TYPE)
398 Represents a point in the coordinate space of the image; used
399 by gdImagePolygon and gdImageFilledPolygon.
402 typedef struct {
403 int x, y;
404 } gdPoint, *gdPointPtr;
406 gdPointPtr (TYPE)
407 A pointer to a gdPoint structure; passed as an argument to
408 gdImagePolygon and gdImageFilledPolygon.
410 Image creation, destruction, loading and saving
412 gdImageCreate(sx, sy) (FUNCTION)
413 gdImageCreate is called to create images. Invoke gdImageCreate
414 with the x and y dimensions of the desired image. gdImageCreate
415 returns a gdImagePtr to the new image, or NULL if unable to
416 allocate the image. The image must eventually be destroyed
417 using gdImageDestroy().
420 ... inside a function ...
421 gdImagePtr im;
422 im = gdImageCreate(64, 64);
423 /* ... Use the image ... */
424 gdImageDestroy(im);
426 gdImageCreateFromGif(FILE *in) (FUNCTION)
427 gdImageCreateFromGif is called to load images from GIF format
428 files. Invoke gdImageCreateFromGif with an already opened
429 pointer to a file containing the desired image.
430 gdImageCreateFromGif returns a gdImagePtr to the new image, or
431 NULL if unable to load the image (most often because the file
432 is corrupt or does not contain a GIF image).
433 gdImageCreateFromGif does not close the file. You can inspect
434 the sx and sy members of the image to determine its size. The
435 image must eventually be destroyed using gdImageDestroy().
438 gdImagePtr im;
439 ... inside a function ...
440 FILE *in;
441 in = fopen("mygif.gif", "rb");
442 im = gdImageCreateFromGif(in);
443 fclose(in);
444 /* ... Use the image ... */
445 gdImageDestroy(im);
447 gdImageCreateFromGd(FILE *in) (FUNCTION)
448 gdImageCreateFromGd is called to load images from gd format
449 files. Invoke gdImageCreateFromGd with an already opened
450 pointer to a file containing the desired image in the gd file
451 format, which is specific to gd and intended for very fast
452 loading. (It is not intended for compression; for compression,
453 use GIF.) gdImageCreateFromGd returns a gdImagePtr to the new
454 image, or NULL if unable to load the image (most often because
455 the file is corrupt or does not contain a gd format image).
456 gdImageCreateFromGd does not close the file. You can inspect
457 the sx and sy members of the image to determine its size. The
458 image must eventually be destroyed using gdImageDestroy().
461 ... inside a function ...
462 gdImagePtr im;
463 FILE *in;
464 in = fopen("mygd.gd", "rb");
465 im = gdImageCreateFromGd(in);
466 fclose(in);
467 /* ... Use the image ... */
468 gdImageDestroy(im);
470 gdImageCreateFromXbm(FILE *in) (FUNCTION)
471 gdImageCreateFromXbm is called to load images from X bitmap
472 format files. Invoke gdImageCreateFromXbm with an already
473 opened pointer to a file containing the desired image.
474 gdImageCreateFromXbm returns a gdImagePtr to the new image, or
475 NULL if unable to load the image (most often because the file
476 is corrupt or does not contain an X bitmap format image).
477 gdImageCreateFromXbm does not close the file. You can inspect
478 the sx and sy members of the image to determine its size. The
479 image must eventually be destroyed using gdImageDestroy().
482 ... inside a function ...
483 gdImagePtr im;
484 FILE *in;
485 in = fopen("myxbm.xbm", "rb");
486 im = gdImageCreateFromXbm(in);
487 fclose(in);
488 /* ... Use the image ... */
489 gdImageDestroy(im);
491 gdImageDestroy(gdImagePtr im) (FUNCTION)
492 gdImageDestroy is used to free the memory associated with an
493 image. It is important to invoke gdImageDestroy before exiting
494 your program or assigning a new image to a gdImagePtr variable.
497 ... inside a function ...
498 gdImagePtr im;
499 im = gdImageCreate(10, 10);
500 /* ... Use the image ... */
501 /* Now destroy it */
502 gdImageDestroy(im);
504 void gdImageGif(gdImagePtr im, FILE *out) (FUNCTION)
505 gdImageGif outputs the specified image to the specified file in
506 GIF format. The file must be open for writing. Under MSDOS, it
507 is important to use "wb" as opposed to simply "w" as the mode
508 when opening the file, and under Unix there is no penalty for
509 doing so. gdImageGif does not close the file; your code must do
510 so.
513 ... inside a function ...
514 gdImagePtr im;
515 int black, white;
516 FILE *out;
517 /* Create the image */
518 im = gdImageCreate(100, 100);
519 /* Allocate background */
520 white = gdImageColorAllocate(im, 255, 255, 255);
521 /* Allocate drawing color */
522 black = gdImageColorAllocate(im, 0, 0, 0);
523 /* Draw rectangle */
524 gdImageRectangle(im, 0, 0, 99, 99, black);
525 /* Open output file in binary mode */
526 out = fopen("rect.gif", "wb");
527 /* Write GIF */
528 gdImageGif(im, out);
529 /* Close file */
530 fclose(out);
531 /* Destroy image */
532 gdImageDestroy(im);
534 void gdImageGd(gdImagePtr im, FILE *out) (FUNCTION)
535 gdImageGd outputs the specified image to the specified file in
536 the gd image format. The file must be open for writing. Under
537 MSDOS, it is important to use "wb" as opposed to simply "w" as
538 the mode when opening the file, and under Unix there is no
539 penalty for doing so. gdImageGif does not close the file; your
540 code must do so.
542 The gd image format is intended for fast reads and writes of
543 images your program will need frequently to build other images.
544 It is not a compressed format, and is not intended for general
545 use.
548 ... inside a function ...
549 gdImagePtr im;
550 int black, white;
551 FILE *out;
552 /* Create the image */
553 im = gdImageCreate(100, 100);
554 /* Allocate background */
555 white = gdImageColorAllocate(im, 255, 255, 255);
556 /* Allocate drawing color */
557 black = gdImageColorAllocate(im, 0, 0, 0);
558 /* Draw rectangle */
559 gdImageRectangle(im, 0, 0, 99, 99, black);
560 /* Open output file in binary mode */
561 out = fopen("rect.gd", "wb");
562 /* Write gd format file */
563 gdImageGd(im, out);
564 /* Close file */
565 fclose(out);
566 /* Destroy image */
567 gdImageDestroy(im);
569 Drawing Functions
571 void gdImageSetPixel(gdImagePtr im, int x, int y, int color)
572 (FUNCTION)
573 gdImageSetPixel sets a pixel to a particular color index.
574 Always use this function or one of the other drawing functions
575 to access pixels; do not access the pixels of the gdImage
576 structure directly.
579 ... inside a function ...
580 gdImagePtr im;
581 int black;
582 int white;
583 im = gdImageCreate(100, 100);
584 /* Background color (first allocated) */
585 black = gdImageColorAllocate(im, 0, 0, 0);
586 /* Allocate the color white (red, green and blue all maximum). */
587 white = gdImageColorAllocate(im, 255, 255, 255);
588 /* Set a pixel near the center. */
589 gdImageSetPixel(im, 50, 50, white);
590 /* ... Do something with the image, such as saving it to a file... */
591 /* Destroy it */
592 gdImageDestroy(im);
594 void gdImageLine(gdImagePtr im, int x1, int y1, int x2, int y2, int
595 color) (FUNCTION)
596 gdImageLine is used to draw a line between two endpoints (x1,y1
597 and x2, y2). The line is drawn using the color index specified.
598 Note that the color index can be an actual color returned by
599 gdImageColorAllocate or one of gdStyled, gdBrushed or
600 gdStyledBrushed.
603 ... inside a function ...
604 gdImagePtr im;
605 int black;
606 int white;
607 im = gdImageCreate(100, 100);
608 /* Background color (first allocated) */
609 black = gdImageColorAllocate(im, 0, 0, 0);
610 /* Allocate the color white (red, green and blue all maximum). */
611 white = gdImageColorAllocate(im, 255, 255, 255);
612 /* Draw a line from the upper left corner to the lower right corner. */
613 gdImageLine(im, 0, 0, 99, 99, white);
614 /* ... Do something with the image, such as saving it to a file... */
615 /* Destroy it */
616 gdImageDestroy(im);
618 void gdImageDashedLine(gdImagePtr im, int x1, int y1, int x2, int y2,
619 int color) (FUNCTION)
620 gdImageDashedLine is provided solely for backwards
621 compatibility with gd 1.0. New programs should draw dashed
622 lines using the normal gdImageLine function and the new
623 gdImageSetStyle function.
625 gdImageDashedLine is used to draw a dashed line between two
626 endpoints (x1,y1 and x2, y2). The line is drawn using the color
627 index specified. The portions of the line that are not drawn
628 are left transparent so the background is visible.
631 ... inside a function ...
632 gdImagePtr im;
633 int black;
634 int white;
635 im = gdImageCreate(100, 100);
636 /* Background color (first allocated) */
637 black = gdImageColorAllocate(im, 0, 0, 0);
638 /* Allocate the color white (red, green and blue all maximum). */
639 white = gdImageColorAllocate(im, 255, 255, 255);
640 /* Draw a dashed line from the upper left corner to the lower right corner. */
641 gdImageDashedLine(im, 0, 0, 99, 99);
642 /* ... Do something with the image, such as saving it to a file... */
643 /* Destroy it */
644 gdImageDestroy(im);
646 void gdImagePolygon(gdImagePtr im, gdPointPtr points, int pointsTotal,
647 int color) (FUNCTION)
648 gdImagePolygon is used to draw a polygon with the verticies (at
649 least 3) specified, using the color index specified. See also
650 gdImageFilledPolygon.
653 ... inside a function ...
654 gdImagePtr im;
655 int black;
656 int white;
657 /* Points of polygon */
658 gdPoint points[3];
659 im = gdImageCreate(100, 100);
660 /* Background color (first allocated) */
661 black = gdImageColorAllocate(im, 0, 0, 0);
662 /* Allocate the color white (red, green and blue all maximum). */
663 white = gdImageColorAllocate(im, 255, 255, 255);
664 /* Draw a triangle. */
665 points[0].x = 50;
666 points[0].y = 0;
667 points[1].x = 99;
668 points[1].y = 99;
669 points[2].x = 0;
670 points[2].y = 99;
671 gdImagePolygon(im, points, 3, white);
672 /* ... Do something with the image, such as saving it to a file... */
673 /* Destroy it */
674 gdImageDestroy(im);
676 void gdImageRectangle(gdImagePtr im, int x1, int y1, int x2, int y2,
677 int color) (FUNCTION)
678 gdImageRectangle is used to draw a rectangle with the two
679 corners (upper left first, then lower right) specified, using
680 the color index specified.
683 ... inside a function ...
684 gdImagePtr im;
685 int black;
686 int white;
687 im = gdImageCreate(100, 100);
688 /* Background color (first allocated) */
689 black = gdImageColorAllocate(im, 0, 0, 0);
690 /* Allocate the color white (red, green and blue all maximum). */
691 white = gdImageColorAllocate(im, 255, 255, 255);
692 /* Draw a rectangle occupying the central area. */
693 gdImageRectangle(im, 25, 25, 74, 74, white);
694 /* ... Do something with the image, such as saving it to a file... */
695 /* Destroy it */
696 gdImageDestroy(im);
698 void gdImageFilledPolygon(gdImagePtr im, gdPointPtr points, int
699 pointsTotal, int color) (FUNCTION)
700 gdImageFilledPolygon is used to fill a polygon with the
701 verticies (at least 3) specified, using the color index
702 specified. See also gdImagePolygon.
705 ... inside a function ...
706 gdImagePtr im;
707 int black;
708 int white;
709 int red;
710 /* Points of polygon */
711 gdPoint points[3];
712 im = gdImageCreate(100, 100);
713 /* Background color (first allocated) */
714 black = gdImageColorAllocate(im, 0, 0, 0);
715 /* Allocate the color white (red, green and blue all maximum). */
716 white = gdImageColorAllocate(im, 255, 255, 255);
717 /* Allocate the color red. */
718 red = gdImageColorAllocate(im, 255, 0, 0);
719 /* Draw a triangle. */
720 points[0].x = 50;
721 points[0].y = 0;
722 points[1].x = 99;
723 points[1].y = 99;
724 points[2].x = 0;
725 points[2].y = 99;
726 /* Paint it in white */
727 gdImageFilledPolygon(im, points, 3, white);
728 /* Outline it in red; must be done second */
729 gdImagePolygon(im, points, 3, red);
730 /* ... Do something with the image, such as saving it to a file... */
731 /* Destroy it */
732 gdImageDestroy(im);
734 void gdImageFilledRectangle(gdImagePtr im, int x1, int y1, int x2, int
735 y2, int color) (FUNCTION)
736 gdImageFilledRectangle is used to draw a solid rectangle with
737 the two corners (upper left first, then lower right) specified,
738 using the color index specified.
741 ... inside a function ...
742 gdImagePtr im;
743 int black;
744 int white;
745 im = gdImageCreate(100, 100);
746 /* Background color (first allocated) */
747 black = gdImageColorAllocate(im, 0, 0, 0);
748 /* Allocate the color white (red, green and blue all maximum). */
749 white = int gdImageColorAllocate(im, 255, 255, 255);
750 /* Draw a filled rectangle occupying the central area. */
751 gdImageFilledRectangle(im, 25, 25, 74, 74, white);
752 /* ... Do something with the image, such as saving it to a file... */
753 /* Destroy it */
754 gdImageDestroy(im);
756 void gdImageArc(gdImagePtr im, int cx, int cy, int w, int h, int s,
757 int e, int color) (FUNCTION)
758 gdImageArc is used to draw a partial ellipse centered at the
759 given point, with the specified width and height in pixels. The
760 arc begins at the position in degrees specified by s and ends
761 at the position specified by e. The arc is drawn in the color
762 specified by the last argument. A circle can be drawn by
763 beginning from 0 degrees and ending at 360 degrees, with width
764 and height being equal. e must be greater than s. Values
765 greater than 360 are interpreted modulo 360.
768 ... inside a function ...
769 gdImagePtr im;
770 int black;
771 int white;
772 im = gdImageCreate(100, 50);
773 /* Background color (first allocated) */
774 black = gdImageColorAllocate(im, 0, 0, 0);
775 /* Allocate the color white (red, green and blue all maximum). */
776 white = gdImageColorAllocate(im, 255, 255, 255);
777 /* Inscribe an ellipse in the image. */
778 gdImageArc(im, 50, 25, 98, 48, 0, 360, white);
779 /* ... Do something with the image, such as saving it to a file... */
780 /* Destroy it */
781 gdImageDestroy(im);
783 void gdImageFillToBorder(gdImagePtr im, int x, int y, int border, int
784 color) (FUNCTION)
785 gdImageFillToBorder floods a portion of the image with the
786 specified color, beginning at the specified point and stopping
787 at the specified border color. For a way of flooding an area
788 defined by the color of the starting point, see gdImageFill.
790 The border color cannot be a special color such as gdTiled; it
791 must be a proper solid color. The fill color can be, however.
793 Note that gdImageFillToBorder is recursive. It is not the most
794 naive implementation possible, and the implementation is
795 expected to improve, but there will always be degenerate cases
796 in which the stack can become very deep. This can be a problem
797 in MSDOS and MS Windows environments. (Of course, in a Unix or
798 NT environment with a proper stack, this is not a problem at
799 all.)
802 ... inside a function ...
803 gdImagePtr im;
804 int black;
805 int white;
806 int red;
807 im = gdImageCreate(100, 50);
808 /* Background color (first allocated) */
809 black = gdImageColorAllocate(im, 0, 0, 0);
810 /* Allocate the color white (red, green and blue all maximum). */
811 white = gdImageColorAllocate(im, 255, 255, 255);
812 /* Allocate the color red. */
813 red = gdImageColorAllocate(im, 255, 0, 0);
814 /* Inscribe an ellipse in the image. */
815 gdImageArc(im, 50, 25, 98, 48, 0, 360, white);
816 /* Flood-fill the ellipse. Fill color is red, border color is
817 white (ellipse). */
818 gdImageFillToBorder(im, 50, 50, white, red);
819 /* ... Do something with the image, such as saving it to a file... */
820 /* Destroy it */
821 gdImageDestroy(im);
823 void gdImageFill(gdImagePtr im, int x, int y, int color) (FUNCTION)
824 gdImageFill floods a portion of the image with the specified
825 color, beginning at the specified point and flooding the
826 surrounding region of the same color as the starting point. For
827 a way of flooding a region defined by a specific border color
828 rather than by its interior color, see gdImageFillToBorder.
830 The fill color can be gdTiled, resulting in a tile fill using
831 another image as the tile. However, the tile image cannot be
832 transparent. If the image you wish to fill with has a
833 transparent color index, call gdImageTransparent on the tile
834 image and set the transparent color index to -1 to turn off its
835 transparency.
837 Note that gdImageFill is recursive. It is not the most naive
838 implementation possible, and the implementation is expected to
839 improve, but there will always be degenerate cases in which the
840 stack can become very deep. This can be a problem in MSDOS and
841 MS Windows environments. (Of course, in a Unix or NT
842 environment with a proper stack, this is not a problem at all.)
845 ... inside a function ...
846 gdImagePtr im;
847 int black;
848 int white;
849 int red;
850 im = gdImageCreate(100, 50);
851 /* Background color (first allocated) */
852 black = gdImageColorAllocate(im, 0, 0, 0);
853 /* Allocate the color white (red, green and blue all maximum). */
854 white = gdImageColorAllocate(im, 255, 255, 255);
855 /* Allocate the color red. */
856 red = gdImageColorAllocate(im, 255, 0, 0);
857 /* Inscribe an ellipse in the image. */
858 gdImageArc(im, 50, 25, 98, 48, 0, 360, white);
859 /* Flood-fill the ellipse. Fill color is red, and will replace the
860 black interior of the ellipse. */
861 gdImageFill(im, 50, 50, red);
862 /* ... Do something with the image, such as saving it to a file... */
863 /* Destroy it */
864 gdImageDestroy(im);
866 void gdImageSetBrush(gdImagePtr im, gdImagePtr brush) (FUNCTION)
867 A "brush" is an image used to draw wide, shaped strokes in
868 another image. Just as a paintbrush is not a single point, a
869 brush image need not be a single pixel. Any gd image can be
870 used as a brush, and by setting the transparent color index of
871 the brush image with gdImageColorTransparent, a brush of any
872 shape can be created. All line-drawing functions, such as
873 gdImageLine and gdImagePolygon, will use the current brush if
874 the special "color" gdBrushed or gdStyledBrushed is used when
875 calling them.
877 gdImageSetBrush is used to specify the brush to be used in a
878 particular image. You can set any image to be the brush. If the
879 brush image does not have the same color map as the first
880 image, any colors missing from the first image will be
881 allocated. If not enough colors can be allocated, the closest
882 colors already available will be used. This allows arbitrary
883 GIFs to be used as brush images. It also means, however, that
884 you should not set a brush unless you will actually use it; if
885 you set a rapid succession of different brush images, you can
886 quickly fill your color map, and the results will not be
887 optimal.
889 You need not take any special action when you are finished with
890 a brush. As for any other image, if you will not be using the
891 brush image for any further purpose, you should call
892 gdImageDestroy. You must not use the color gdBrushed if the
893 current brush has been destroyed; you can of course set a new
894 brush to replace it.
897 ... inside a function ...
898 gdImagePtr im, brush;
899 FILE *in;
900 int black;
901 im = gdImageCreate(100, 100);
902 /* Open the brush GIF. For best results, portions of the
903 brush that should be transparent (ie, not part of the
904 brush shape) should have the transparent color index. */
905 in = fopen("star.gif", "rb");
906 brush = gdImageCreateFromGif(in);
907 /* Background color (first allocated) */
908 black = gdImageColorAllocate(im, 0, 0, 0);
909 gdImageSetBrush(im, brush);
910 /* Draw a line from the upper left corner to the lower right corner
911 using the brush. */
912 gdImageLine(im, 0, 0, 99, 99, gdBrushed);
913 /* ... Do something with the image, such as saving it to a file... */
914 /* Destroy it */
915 gdImageDestroy(im);
916 /* Destroy the brush image */
917 gdImageDestroy(brush);
919 void gdImageSetTile(gdImagePtr im, gdImagePtr tile) (FUNCTION)
920 A "tile" is an image used to fill an area with a repeated
921 pattern. Any gd image can be used as a tile, and by setting the
922 transparent color index of the tile image with
923 gdImageColorTransparent, a tile that allows certain parts of
924 the underlying area to shine through can be created. All
925 region-filling functions, such as gdImageFill and
926 gdImageFilledPolygon, will use the current tile if the special
927 "color" gdTiled is used when calling them.
929 gdImageSetTile is used to specify the tile to be used in a
930 particular image. You can set any image to be the tile. If the
931 tile image does not have the same color map as the first image,
932 any colors missing from the first image will be allocated. If
933 not enough colors can be allocated, the closest colors already
934 available will be used. This allows arbitrary GIFs to be used
935 as tile images. It also means, however, that you should not set
936 a tile unless you will actually use it; if you set a rapid
937 succession of different tile images, you can quickly fill your
938 color map, and the results will not be optimal.
940 You need not take any special action when you are finished with
941 a tile. As for any other image, if you will not be using the
942 tile image for any further purpose, you should call
943 gdImageDestroy. You must not use the color gdTiled if the
944 current tile has been destroyed; you can of course set a new
945 tile to replace it.
948 ... inside a function ...
949 gdImagePtr im, tile;
950 FILE *in;
951 int black;
952 im = gdImageCreate(100, 100);
953 /* Open the tile GIF. For best results, portions of the
954 tile that should be transparent (ie, allowing the
955 background to shine through) should have the transparent
956 color index. */
957 in = fopen("star.gif", "rb");
958 tile = gdImageCreateFromGif(in);
959 /* Background color (first allocated) */
960 black = gdImageColorAllocate(im, 0, 0, 0);
961 gdImageSetTile(im, tile);
962 /* Fill an area using the tile. */
963 gdImageFilledRectangle(im, 25, 25, 75, 75, gdTiled);
964 /* ... Do something with the image, such as saving it to a file... */
965 /* Destroy it */
966 gdImageDestroy(im);
967 /* Destroy the tile image */
968 gdImageDestroy(tile);
970 void gdImageSetStyle(gdImagePtr im, int *style, int styleLength)
971 (FUNCTION)
972 It is often desirable to draw dashed lines, dotted lines, and
973 other variations on a broken line. gdImageSetStyle can be used
974 to set any desired series of colors, including a special color
975 that leaves the background intact, to be repeated during the
976 drawing of a line.
978 To use gdImageSetStyle, create an array of integers and assign
979 them the desired series of color values to be repeated. You can
980 assign the special color value gdTransparent to indicate that
981 the existing color should be left unchanged for that particular
982 pixel (allowing a dashed line to be attractively drawn over an
983 existing image).
985 Then, to draw a line using the style, use the normal
986 gdImageLine function with the special color value gdStyled.
988 As of version 1.1.1, the style array is copied when you set the
989 style, so you need not be concerned with keeping the array
990 around indefinitely. This should not break existing code that
991 assumes styles are not copied.
993 You can also combine styles and brushes to draw the brush image
994 at intervals instead of in a continuous stroke. When creating a
995 style for use with a brush, the style values are interpreted
996 differently: zero (0) indicates pixels at which the brush
997 should not be drawn, while one (1) indicates pixels at which
998 the brush should be drawn. To draw a styled, brushed line, you
999 must use the special color value gdStyledBrushed. For an
1000 example of this feature in use, see gddemo.c (provided in the
1001 distribution).
1004 gdImagePtr im;
1005 int styleDotted[2], styleDashed[6];
1006 FILE *in;
1007 int black;
1008 int red;
1009 im = gdImageCreate(100, 100);
1010 /* Background color (first allocated) */
1011 black = gdImageColorAllocate(im, 0, 0, 0);
1012 red = gdImageColorAllocate(im, 255, 0, 0);
1013 /* Set up dotted style. Leave every other pixel alone. */
1014 styleDotted[0] = red;
1015 styleDotted[1] = gdTransparent;
1016 /* Set up dashed style. Three on, three off. */
1017 styleDashed[0] = red;
1018 styleDashed[1] = red;
1019 styleDashed[2] = red;
1020 styleDashed[3] = gdTransparent;
1021 styleDashed[4] = gdTransparent;
1022 styleDashed[5] = gdTransparent;
1023 /* Set dotted style. Note that we have to specify how many pixels are
1024 in the style! */
1025 gdImageSetStyle(im, styleDotted, 2);
1026 /* Draw a line from the upper left corner to the lower right corner. */
1027 gdImageLine(im, 0, 0, 99, 99, gdStyled);
1028 /* Now the dashed line. */
1029 gdImageSetStyle(im, styleDashed, 6);
1030 gdImageLine(im, 0, 99, 0, 99, gdStyled);
1032 /* ... Do something with the image, such as saving it to a file ... */
1034 /* Destroy it */
1035 gdImageDestroy(im);
1037 Query Functions
1039 int gdImageBlue(gdImagePtr im, int color) (MACRO)
1040 gdImageBlue is a macro which returns the blue component
1041 of the specified color index. Use this macro rather than
1042 accessing the structure members directly.
1044 int gdImageGetPixel(gdImagePtr im, int x, int y) (FUNCTION)
1045 gdImageGetPixel() retrieves the color index of a
1046 particular pixel. Always use this function to query
1047 pixels; do not access the pixels of the gdImage structure
1048 directly.
1051 ... inside a function ...
1052 FILE *in;
1053 gdImagePtr im;
1054 int c;
1055 in = fopen("mygif.gif", "rb");
1056 im = gdImageCreateFromGif(in);
1057 fclose(in);
1058 c = gdImageGetPixel(im, gdImageSX(im) / 2, gdImageSY(im) / 2);
1059 printf("The value of the center pixel is %d; RGB values are %d,%d,%d\n",
1060 c, im->red[c], im->green[c], im->blue[c]);
1061 gdImageDestroy(im);
1063 int gdImageBoundsSafe(gdImagePtr im, int x, int y) (FUNCTION)
1064 gdImageBoundsSafe returns true (1) if the specified point
1065 is within the bounds of the image, false (0) if not. This
1066 function is intended primarily for use by those who wish
1067 to add functions to gd. All of the gd drawing functions
1068 already clip safely to the edges of the image.
1071 ... inside a function ...
1072 gdImagePtr im;
1073 int black;
1074 int white;
1075 im = gdImageCreate(100, 100);
1076 if (gdImageBoundsSafe(im, 50, 50)) {
1077 printf("50, 50 is within the image bounds\n");
1078 } else {
1079 printf("50, 50 is outside the image bounds\n");
1080 }
1081 gdImageDestroy(im);
1083 int gdImageGreen(gdImagePtr im, int color) (MACRO)
1084 gdImageGreen is a macro which returns the green component
1085 of the specified color index. Use this macro rather than
1086 accessing the structure members directly.
1088 int gdImageRed(gdImagePtr im, int color) (MACRO)
1089 gdImageRed is a macro which returns the red component of
1090 the specified color index. Use this macro rather than
1091 accessing the structure members directly.
1093 int gdImageSX(gdImagePtr im) (MACRO)
1094 gdImageSX is a macro which returns the width of the image
1095 in pixels. Use this macro rather than accessing the
1096 structure members directly.
1098 int gdImageSY(gdImagePtr im) (MACRO)
1099 gdImageSY is a macro which returns the height of the
1100 image in pixels. Use this macro rather than accessing the
1101 structure members directly.
1103 Fonts and text-handling functions
1105 void gdImageChar(gdImagePtr im, gdFontPtr font, int x, int y, int
1106 c, int color) (FUNCTION)
1107 gdImageChar is used to draw single characters on the
1108 image. (To draw multiple characters, use gdImageString or
1109 gdImageString16.) The second argument is a pointer to a
1110 font definition structure; five fonts are provided with
1111 gd, gdFontTiny, gdFontSmall, gdFontMediumBold,
1112 gdFontLarge, and gdFontGiant. You must include the files
1113 "gdfontt.h", "gdfonts.h", "gdfontmb.h", "gdfontl.h" and
1114 "gdfontg.h" respectively and (if you are not using a
1115 library-based approach) link with the corresponding .c
1116 files to use the provided fonts. The character specified
1117 by the fifth argument is drawn from left to right in the
1118 specified color. (See gdImageCharUp for a way of drawing
1119 vertical text.) Pixels not set by a particular character
1120 retain their previous color.
1123 #include "gd.h"
1124 #include "gdfontl.h"
1125 ... inside a function ...
1126 gdImagePtr im;
1127 int black;
1128 int white;
1129 im = gdImageCreate(100, 100);
1130 /* Background color (first allocated) */
1131 black = gdImageColorAllocate(im, 0, 0, 0);
1132 /* Allocate the color white (red, green and blue all maximum). */
1133 white = gdImageColorAllocate(im, 255, 255, 255);
1134 /* Draw a character. */
1135 gdImageChar(im, gdFontLarge, 0, 0, 'Q', white);
1136 /* ... Do something with the image, such as saving it to a file... */
1137 /* Destroy it */
1138 gdImageDestroy(im);
1140 void gdImageCharUp(gdImagePtr im, gdFontPtr font, int x, int y,
1141 int c, int color) (FUNCTION)
1142 gdImageCharUp is used to draw single characters on the
1143 image, rotated 90 degrees. (To draw multiple characters,
1144 use gdImageStringUp or gdImageStringUp16.) The second
1145 argument is a pointer to a font definition structure;
1146 five fonts are provided with gd, gdFontTiny, gdFontSmall,
1147 gdFontMediumBold, gdFontLarge, and gdFontGiant. You must
1148 include the files "gdfontt.h", "gdfonts.h", "gdfontmb.h",
1149 "gdfontl.h" and "gdfontg.h" respectively and (if you are
1150 not using a library-based approach) link with the
1151 corresponding .c files to use the provided fonts. The
1152 character specified by the fifth argument is drawn from
1153 bottom to top, rotated at a 90-degree angle, in the
1154 specified color. (See gdImageChar for a way of drawing
1155 horizontal text.) Pixels not set by a particular
1156 character retain their previous color.
1159 #include "gd.h"
1160 #include "gdfontl.h"
1161 ... inside a function ...
1162 gdImagePtr im;
1163 int black;
1164 int white;
1165 im = gdImageCreate(100, 100);
1166 /* Background color (first allocated) */
1167 black = gdImageColorAllocate(im, 0, 0, 0);
1168 /* Allocate the color white (red, green and blue all maximum). */
1169 white = gdImageColorAllocate(im, 255, 255, 255);
1170 /* Draw a character upwards so it rests against the top of the image. */
1171 gdImageCharUp(im, gdFontLarge,
1172 0, gdFontLarge->h, 'Q', white);
1173 /* ... Do something with the image, such as saving it to a file... */
1174 /* Destroy it */
1175 gdImageDestroy(im);
1177 void gdImageString(gdImagePtr im, gdFontPtr font, int x, int y,
1178 unsigned char *s, int color) (FUNCTION)
1179 gdImageString is used to draw multiple characters on the
1180 image. (To draw single characters, use gdImageChar.) The
1181 second argument is a pointer to a font definition
1182 structure; five fonts are provided with gd, gdFontTiny,
1183 gdFontSmall, gdFontMediumBold, gdFontLarge, and
1184 gdFontGiant. You must include the files "gdfontt.h",
1185 "gdfonts.h", "gdfontmb.h", "gdfontl.h" and "gdfontg.h"
1186 respectively and (if you are not using a library-based
1187 approach) link with the corresponding .c files to use the
1188 provided fonts. The null-terminated C string specified by
1189 the fifth argument is drawn from left to right in the
1190 specified color. (See gdImageStringUp for a way of
1191 drawing vertical text.) Pixels not set by a particular
1192 character retain their previous color.
1195 #include "gd.h"
1196 #include "gdfontl.h"
1197 #include <string.h>
1198 ... inside a function ...
1199 gdImagePtr im;
1200 int black;
1201 int white;
1202 /* String to draw. */
1203 char *s = "Hello.";
1204 im = gdImageCreate(100, 100);
1205 /* Background color (first allocated) */
1206 black = gdImageColorAllocate(im, 0, 0, 0);
1207 /* Allocate the color white (red, green and blue all maximum). */
1208 white = gdImageColorAllocate(im, 255, 255, 255);
1209 /* Draw a centered string. */
1210 gdImageString(im, gdFontLarge,
1211 im->w / 2 - (strlen(s) * gdFontLarge->w / 2),
1212 im->h / 2 - gdFontLarge->h / 2,
1213 s, white);
1214 /* ... Do something with the image, such as saving it to a file... */
1215 /* Destroy it */
1216 gdImageDestroy(im);
1218 void gdImageString16(gdImagePtr im, gdFontPtr font, int x, int y,
1219 unsigned short *s, int color) (FUNCTION)
1220 gdImageString is used to draw multiple 16-bit characters
1221 on the image. (To draw single characters, use
1222 gdImageChar.) The second argument is a pointer to a font
1223 definition structure; five fonts are provided with gd,
1224 gdFontTiny, gdFontSmall, gdFontMediumBold, gdFontLarge,
1225 and gdFontGiant. You must include the files "gdfontt.h",
1226 "gdfonts.h", "gdfontmb.h", "gdfontl.h" and "gdfontg.h"
1227 respectively and (if you are not using a library-based
1228 approach) link with the corresponding .c files to use the
1229 provided fonts. The null-terminated string of characters
1230 represented as 16-bit unsigned short integers specified
1231 by the fifth argument is drawn from left to right in the
1232 specified color. (See gdImageStringUp16 for a way of
1233 drawing vertical text.) Pixels not set by a particular
1234 character retain their previous color.
1236 This function was added in gd1.3 to provide a means of
1237 rendering fonts with more than 256 characters for those
1238 who have them. A more frequently used routine is
1239 gdImageString.
1241 void gdImageStringUp(gdImagePtr im, gdFontPtr font, int x, int y,
1242 unsigned char *s, int color) (FUNCTION)
1243 gdImageStringUp is used to draw multiple characters on
1244 the image, rotated 90 degrees. (To draw single
1245 characters, use gdImageCharUp.) The second argument is a
1246 pointer to a font definition structure; five fonts are
1247 provided with gd, gdFontTiny, gdFontSmall,
1248 gdFontMediumBold, gdFontLarge, and gdFontGiant. You must
1249 include the files "gdfontt.h", "gdfonts.h", "gdfontmb.h",
1250 "gdfontl.h" and "gdfontg.h" respectively and (if you are
1251 not using a library-based approach) link with the
1252 corresponding .c files to use the provided fonts.The
1253 null-terminated C string specified by the fifth argument
1254 is drawn from bottom to top (rotated 90 degrees) in the
1255 specified color. (See gdImageString for a way of drawing
1256 horizontal text.) Pixels not set by a particular
1257 character retain their previous color.
1260 #include "gd.h"
1261 #include "gdfontl.h"
1262 #include <string.h>
1263 ... inside a function ...
1264 gdImagePtr im;
1265 int black;
1266 int white;
1267 /* String to draw. */
1268 char *s = "Hello.";
1269 im = gdImageCreate(100, 100);
1270 /* Background color (first allocated) */
1271 black = gdImageColorAllocate(im, 0, 0, 0);
1272 /* Allocate the color white (red, green and blue all maximum). */
1273 white = gdImageColorAllocate(im, 255, 255, 255);
1274 /* Draw a centered string going upwards. Axes are reversed,
1275 and Y axis is decreasing as the string is drawn. */
1276 gdImageStringUp(im, gdFontLarge,
1277 im->w / 2 - gdFontLarge->h / 2,
1278 im->h / 2 + (strlen(s) * gdFontLarge->w / 2),
1279 s, white);
1280 /* ... Do something with the image, such as saving it to a file... */
1281 /* Destroy it */
1282 gdImageDestroy(im);
1284 void gdImageStringUp16(gdImagePtr im, gdFontPtr font, int x, int
1285 y, unsigned short *s, int color) (FUNCTION)
1286 gdImageString is used to draw multiple 16-bit characters
1287 vertically on the image. (To draw single characters, use
1288 gdImageChar.) The second argument is a pointer to a font
1289 definition structure; five fonts are provided with gd,
1290 gdFontTiny, gdFontSmall, gdFontMediumBold, gdFontLarge,
1291 and gdFontGiant. You must include the files "gdfontt.h",
1292 "gdfonts.h", "gdfontmb.h", "gdfontl.h" and "gdfontg.h"
1293 respectively and (if you are not using a library-based
1294 approach) link with the corresponding .c files to use the
1295 provided fonts. The null-terminated string of characters
1296 represented as 16-bit unsigned short integers specified
1297 by the fifth argument is drawn from bottom to top in the
1298 specified color. (See gdImageStringUp16 for a way of
1299 drawing horizontal text.) Pixels not set by a particular
1300 character retain their previous color.
1302 This function was added in gd1.3 to provide a means of
1303 rendering fonts with more than 256 characters for those
1304 who have them. A more frequently used routine is
1305 gdImageStringUp.
1307 Color-handling functions
1309 int gdImageColorAllocate(gdImagePtr im, int r, int g, int b)
1310 (FUNCTION)
1311 gdImageColorAllocate finds the first available color
1312 index in the image specified, sets its RGB values to
1313 those requested (255 is the maximum for each), and
1314 returns the index of the new color table entry. When
1315 creating a new image, the first time you invoke this
1316 function, you are setting the background color for that
1317 image.
1319 In the event that all gdMaxColors colors (256) have
1320 already been allocated, gdImageColorAllocate will return
1321 -1 to indicate failure. (This is not uncommon when
1322 working with existing GIF files that already use 256
1323 colors.) Note that gdImageColorAllocate does not check
1324 for existing colors that match your request; see
1325 gdImageColorExact and gdImageColorClosest for ways to
1326 locate existing colors that approximate the color desired
1327 in situations where a new color is not available.
1330 ... inside a function ...
1331 gdImagePtr im;
1332 int black;
1333 int red;
1334 im = gdImageCreate(100, 100);
1335 /* Background color (first allocated) */
1336 black = gdImageColorAllocate(im, 0, 0, 0);
1337 /* Allocate the color red. */
1338 red = gdImageColorAllocate(im, 255, 0, 0);
1339 /* Draw a dashed line from the upper left corner to the lower right corner. */
1340 gdImageDashedLine(im, 0, 0, 99, 99, red);
1341 /* ... Do something with the image, such as saving it to a file... */
1342 /* Destroy it */
1343 gdImageDestroy(im);
1345 int gdImageColorClosest(gdImagePtr im, int r, int g, int b)
1346 (FUNCTION)
1347 gdImageColorClosest searches the colors which have been
1348 defined thus far in the image specified and returns the
1349 index of the color with RGB values closest to those of
1350 the request. (Closeness is determined by Euclidian
1351 distance, which is used to determine the distance in
1352 three-dimensional color space between colors.)
1354 If no colors have yet been allocated in the image,
1355 gdImageColorClosest returns -1.
1357 This function is most useful as a backup method for
1358 choosing a drawing color when an image already contains
1359 gdMaxColors (256) colors and no more can be allocated.
1360 (This is not uncommon when working with existing GIF
1361 files that already use many colors.) See
1362 gdImageColorExact for a method of locating exact matches
1363 only.
1366 ... inside a function ...
1367 gdImagePtr im;
1368 FILE *in;
1369 int red;
1370 /* Let's suppose that photo.gif is a scanned photograph with
1371 many colors. */
1372 in = fopen("photo.gif", "rb");
1373 im = gdImageCreateFromGif(in);
1374 fclose(in);
1375 /* Try to allocate red directly */
1376 red = gdImageColorAllocate(im, 255, 0, 0);
1377 /* If we fail to allocate red... */
1378 if (red == (-1)) {
1379 /* Find the closest color instead. */
1380 red = gdImageColorClosest(im, 255, 0, 0);
1381 }
1382 /* Draw a dashed line from the upper left corner to the lower right corner */
1383 gdImageDashedLine(im, 0, 0, 99, 99, red);
1384 /* ... Do something with the image, such as saving it to a file... */
1385 /* Destroy it */
1386 gdImageDestroy(im);
1388 int gdImageColorExact(gdImagePtr im, int r, int g, int b)
1389 (FUNCTION)
1390 gdImageColorExact searches the colors which have been
1391 defined thus far in the image specified and returns the
1392 index of the first color with RGB values which exactly
1393 match those of the request. If no allocated color matches
1394 the request precisely, gdImageColorExact returns -1. See
1395 gdImageColorClosest for a way to find the color closest
1396 to the color requested.
1399 ... inside a function ...
1400 gdImagePtr im;
1401 int red;
1402 in = fopen("photo.gif", "rb");
1403 im = gdImageCreateFromGif(in);
1404 fclose(in);
1405 /* The image may already contain red; if it does, we'll save a slot
1406 in the color table by using that color. */
1407 /* Try to allocate red directly */
1408 red = gdImageColorExact(im, 255, 0, 0);
1409 /* If red isn't already present... */
1410 if (red == (-1)) {
1411 /* Second best: try to allocate it directly. */
1412 red = gdImageColorAllocate(im, 255, 0, 0);
1413 /* Out of colors, so find the closest color instead. */
1414 red = gdImageColorClosest(im, 255, 0, 0);
1415 }
1416 /* Draw a dashed line from the upper left corner to the lower right corner */
1417 gdImageDashedLine(im, 0, 0, 99, 99, red);
1418 /* ... Do something with the image, such as saving it to a file... */
1419 /* Destroy it */
1420 gdImageDestroy(im);
1422 int gdImageColorsTotal(gdImagePtr im) (MACRO)
1423 gdImageColorsTotal is a macro which returns the number of
1424 colors currently allocated in the image. Use this macro
1425 to obtain this information; do not access the structure
1426 directly.
1428 int gdImageColorRed(gdImagePtr im, int c) (MACRO)
1429 gdImageColorRed is a macro which returns the red portion
1430 of the specified color in the image. Use this macro to
1431 obtain this information; do not access the structure
1432 directly.
1434 int gdImageColorGreen(gdImagePtr im, int c) (MACRO)
1435 gdImageColorGreen is a macro which returns the green
1436 portion of the specified color in the image. Use this
1437 macro to obtain this information; do not access the
1438 structure directly.
1440 int gdImageColorBlue(gdImagePtr im, int c) (MACRO)
1441 gdImageColorBlue is a macro which returns the green
1442 portion of the specified color in the image. Use this
1443 macro to obtain this information; do not access the
1444 structure directly.
1446 int gdImageGetInterlaced(gdImagePtr im) (MACRO)
1447 gdImageGetInterlaced is a macro which returns true (1) if
1448 the image is interlaced, false (0) if not. Use this macro
1449 to obtain this information; do not access the structure
1450 directly. See gdImageInterlace for a means of interlacing
1451 images.
1453 int gdImageGetTransparent(gdImagePtr im) (MACRO)
1454 gdImageGetTransparent is a macro which returns the
1455 current transparent color index in the image. If there is
1456 no transparent color, gdImageGetTransparent returns -1.
1457 Use this macro to obtain this information; do not access
1458 the structure directly.
1460 void gdImageColorDeallocate(gdImagePtr im, int color) (FUNCTION)
1461 gdImageColorDeallocate marks the specified color as being
1462 available for reuse. It does not attempt to determine
1463 whether the color index is still in use in the image.
1464 After a call to this function, the next call to
1465 gdImageColorAllocate for the same image will set new RGB
1466 values for that color index, changing the color of any
1467 pixels which have that index as a result. If multiple
1468 calls to gdImageColorDeallocate are made consecutively,
1469 the lowest-numbered index among them will be reused by
1470 the next gdImageColorAllocate call.
1473 ... inside a function ...
1474 gdImagePtr im;
1475 int red, blue;
1476 in = fopen("photo.gif", "rb");
1477 im = gdImageCreateFromGif(in);
1478 fclose(in);
1479 /* Look for red in the color table. */
1480 red = gdImageColorExact(im, 255, 0, 0);
1481 /* If red is present... */
1482 if (red != (-1)) {
1483 /* Deallocate it. */
1484 gdImageColorDeallocate(im, red);
1485 /* Allocate blue, reusing slot in table.
1486 Existing red pixels will change color. */
1487 blue = gdImageColorAllocate(im, 0, 0, 255);
1488 }
1489 /* ... Do something with the image, such as saving it to a file... */
1490 /* Destroy it */
1491 gdImageDestroy(im);
1493 void gdImageColorTransparent(gdImagePtr im, int color) (FUNCTION)
1495 gdImageColorTransparent sets the transparent color index
1496 for the specified image to the specified index. To
1497 indicate that there should be no transparent color,
1498 invoke gdImageColorTransparent with a color index of -1.
1500 The color index used should be an index allocated by
1501 gdImageColorAllocate, whether explicitly invoked by your
1502 code or implicitly invoked by loading an image. In order
1503 to ensure that your image has a reasonable appearance
1504 when viewed by users who do not have transparent
1505 background capabilities, be sure to give reasonable RGB
1506 values to the color you allocate for use as a transparent
1507 color, even though it will be transparent on systems that
1508 support transparency.
1511 ... inside a function ...
1512 gdImagePtr im;
1513 int black;
1514 FILE *in, *out;
1515 in = fopen("photo.gif", "rb");
1516 im = gdImageCreateFromGif(in);
1517 fclose(in);
1518 /* Look for black in the color table and make it transparent. */
1519 black = gdImageColorExact(im, 0, 0, 0);
1520 /* If black is present... */
1521 if (black != (-1)) {
1522 /* Make it transparent */
1523 gdImageColorTransparent(im, black);
1524 }
1525 /* Save the newly-transparent image back to the file */
1526 out = fopen("photo.gif", "wb");
1527 gdImageGif(im, out);
1528 fclose(out);
1529 /* Destroy it */
1530 gdImageDestroy(im);
1532 Copying and resizing functions
1534 void gdImageCopy(gdImagePtr dst, gdImagePtr src, int dstX, int
1535 dstY, int srcX, int srcY, int w, int h) (FUNCTION)
1536 gdImageCopy is used to copy a rectangular portion of one
1537 image to another image. (For a way of stretching or
1538 shrinking the image in the process, see
1539 gdImageCopyResized.)
1541 The dst argument is the destination image to which the
1542 region will be copied. The src argument is the source
1543 image from which the region is copied. The dstX and dstY
1544 arguments specify the point in the destination image to
1545 which the region will be copied. The srcX and srcY
1546 arguments specify the upper left corner of the region in
1547 the source image. The w and h arguments specify the width
1548 and height of the region.
1550 When you copy a region from one location in an image to
1551 another location in the same image, gdImageCopy will
1552 perform as expected unless the regions overlap, in which
1553 case the result is unpredictable.
1555 Important note on copying between images: since different
1556 images do not necessarily have the same color tables,
1557 pixels are not simply set to the same color index values
1558 to copy them. gdImageCopy will attempt to find an
1559 identical RGB value in the destination image for each
1560 pixel in the copied portion of the source image by
1561 invoking gdImageColorExact. If such a value is not found,
1562 gdImageCopy will attempt to allocate colors as needed
1563 using gdImageColorAllocate. If both of these methods
1564 fail, gdImageCopy will invoke gdImageColorClosest to find
1565 the color in the destination image which most closely
1566 approximates the color of the pixel being copied.
1569 ... Inside a function ...
1570 gdImagePtr im_in;
1571 gdImagePtr im_out;
1572 int x, y;
1573 FILE *in;
1574 FILE *out;
1575 /* Load a small gif to tile the larger one with */
1576 in = fopen("small.gif", "rb");
1577 im_in = gdImageCreateFromGif(in);
1578 fclose(in);
1579 /* Make the output image four times as large on both axes */
1580 im_out = gdImageCreate(im_in->sx * 4, im_in->sy * 4);
1581 /* Now tile the larger image using the smaller one */
1582 for (y = 0; (y < 4); y++) {
1583 for (x = 0; (x < 4); x++) {
1584 gdImageCopy(im_out, im_in,
1585 x * im_in->sx, y * im_in->sy,
1586 0, 0,
1587 im_in->sx, im_in->sy);
1588 }
1589 }
1590 out = fopen("tiled.gif", "wb");
1591 gdImageGif(im_out, out);
1592 fclose(out);
1593 gdImageDestroy(im_in);
1594 gdImageDestroy(im_out);
1596 void gdImageCopyResized(gdImagePtr dst, gdImagePtr src, int dstX,
1597 int dstY, int srcX, int srcY, int destW, int destH, int
1598 srcW, int srcH) (FUNCTION)
1599 gdImageCopyResized is used to copy a rectangular portion
1600 of one image to another image. The X and Y dimensions of
1601 the original region and the destination region can vary,
1602 resulting in stretching or shrinking of the region as
1603 appropriate. (For a simpler version of this function
1604 which does not deal with resizing, see gdImageCopy.)
1606 The dst argument is the destination image to which the
1607 region will be copied. The src argument is the source
1608 image from which the region is copied. The dstX and dstY
1609 arguments specify the point in the destination image to
1610 which the region will be copied. The srcX and srcY
1611 arguments specify the upper left corner of the region in
1612 the source image. The dstW and dstH arguments specify the
1613 width and height of the destination region. The srcW and
1614 srcH arguments specify the width and height of the source
1615 region and can differ from the destination size, allowing
1616 a region to be scaled during the copying process.
1618 When you copy a region from one location in an image to
1619 another location in the same image, gdImageCopy will
1620 perform as expected unless the regions overlap, in which
1621 case the result is unpredictable. If this presents a
1622 problem, create a scratch image in which to keep
1623 intermediate results.
1625 Important note on copying between images: since images do
1626 not necessarily have the same color tables, pixels are
1627 not simply set to the same color index values to copy
1628 them. gdImageCopy will attempt to find an identical RGB
1629 value in the destination image for each pixel in the
1630 copied portion of the source image by invoking
1631 gdImageColorExact. If such a value is not found,
1632 gdImageCopy will attempt to allocate colors as needed
1633 using gdImageColorAllocate. If both of these methods
1634 fail, gdImageCopy will invoke gdImageColorClosest to find
1635 the color in the destination image which most closely
1636 approximates the color of the pixel being copied.
1639 ... Inside a function ...
1640 gdImagePtr im_in;
1641 gdImagePtr im_out;
1642 int x, y;
1643 FILE *in;
1644 FILE *out;
1645 /* Load a small gif to expand in the larger one */
1646 in = fopen("small.gif", "rb");
1647 im_in = gdImageCreateFromGif(in);
1648 fclose(in);
1649 /* Make the output image four times as large on both axes */
1650 im_out = gdImageCreate(im_in->sx * 4, im_in->sy * 4);
1651 /* Now copy the smaller image, but four times larger */
1652 gdImageCopyResized(im_out, im_in, 0, 0, 0, 0,
1653 im_out->sx, im_out->sy,
1654 im_in->sx, im_in->sy);
1655 out = fopen("large.gif", "wb");
1656 gdImageGif(im_out, out);
1657 fclose(out);
1658 gdImageDestroy(im_in);
1659 gdImageDestroy(im_out);
1661 Miscellaneous Functions
1663 gdImageInterlace(gdImagePtr im, int interlace) (FUNCTION)
1664 gdImageInterlace is used to determine whether an
1665 image should be stored in a linear fashion, in
1666 which lines will appear on the display from first
1667 to last, or in an interlaced fashion, in which the
1668 image will "fade in" over several passes. By
1669 default, images are not interlaced.
1671 A nonzero value for the interlace argument turns on
1672 interlace; a zero value turns it off. Note that
1673 interlace has no effect on other functions, and has
1674 no meaning unless you save the image in GIF format;
1675 the gd and xbm formats do not support interlace.
1677 When a GIF is loaded with gdImageCreateFromGif ,
1678 interlace will be set according to the setting in
1679 the GIF file.
1681 Note that many GIF viewers and web browsers do not
1682 support interlace. However, the interlaced GIF
1683 should still display; it will simply appear all at
1684 once, just as other images do.
1687 gdImagePtr im;
1688 FILE *out;
1689 /* ... Create or load the image... */
1691 /* Now turn on interlace */
1692 gdImageInterlace(im, 1);
1693 /* And open an output file */
1694 out = fopen("test.gif", "wb");
1695 /* And save the image */
1696 gdImageGif(im, out);
1697 fclose(out);
1698 gdImageDestroy(im);
1700 Constants
1702 gdBrushed (CONSTANT)
1703 Used in place of a color when invoking a
1704 line-drawing function such as gdImageLine or
1705 gdImageRectangle. When gdBrushed is used as the
1706 color, the brush image set with gdImageSetBrush is
1707 drawn in place of each pixel of the line (the brush
1708 is usually larger than one pixel, creating the
1709 effect of a wide paintbrush). See also
1710 gdStyledBrushed for a way to draw broken lines with
1711 a series of distinct copies of an image.
1713 gdMaxColors(CONSTANT)
1714 The constant 256. This is the maximum number of
1715 colors in a GIF file according to the GIF standard,
1716 and is also the maximum number of colors in a gd
1717 image.
1719 gdStyled (CONSTANT)
1720 Used in place of a color when invoking a
1721 line-drawing function such as gdImageLine or
1722 gdImageRectangle. When gdStyled is used as the
1723 color, the colors of the pixels are drawn
1724 successively from the style that has been set with
1725 gdImageSetStyle. If the color of a pixel is equal
1726 to gdTransparent, that pixel is not altered. (This
1727 mechanism is completely unrelated to the
1728 "transparent color" of the image itself; see
1729 gdImageColorTransparent gdImageColorTransparent for
1730 that mechanism.) See also gdStyledBrushed.
1732 gdStyledBrushed (CONSTANT)
1733 Used in place of a color when invoking a
1734 line-drawing function such as gdImageLine or
1735 gdImageRectangle. When gdStyledBrushed is used as
1736 the color, the brush image set with gdImageSetBrush
1737 is drawn at each pixel of the line, providing that
1738 the style set with gdImageSetStyle contains a
1739 nonzero value (OR gdTransparent, which does not
1740 equal zero but is supported for consistency) for
1741 the current pixel. (Pixels are drawn successively
1742 from the style as the line is drawn, returning to
1743 the beginning when the available pixels in the
1744 style are exhausted.) Note that this differs from
1745 the behavior of gdStyled, in which the values in
1746 the style are used as actual pixel colors, except
1747 for gdTransparent.
1749 gdDashSize (CONSTANT)
1750 The length of a dash in a dashed line. Defined to
1751 be 4 for backwards compatibility with programs that
1752 use gdImageDashedLine. New programs should use
1753 gdImageSetStyle and call the standard gdImageLine
1754 function with the special "color" gdStyled or
1755 gdStyledBrushed.
1757 gdTiled (CONSTANT)
1758 Used in place of a normal color in
1759 gdImageFilledRectangle, gdImageFilledPolygon,
1760 gdImageFill, and gdImageFillToBorder. gdTiled
1761 selects a pixel from the tile image set with
1762 gdImageSetTile in such a way as to ensure that the
1763 filled area will be tiled with copies of the tile
1764 image. See the discussions of gdImageFill and
1765 gdImageFillToBorder for special restrictions
1766 regarding those functions.
1768 gdTransparent (CONSTANT)
1769 Used in place of a normal color in a style to be
1770 set with gdImageSetStyle. gdTransparent is not the
1771 transparent color index of the image; for that
1772 functionality please see gdImageColorTransparent.
1774 About the additional .gd image file format
1776 In addition to reading and writing the GIF format
1777 and reading the X Bitmap format, gd has the
1778 capability to read and write its own ".gd" format.
1779 This format is not intended for general purpose use
1780 and should never be used to distribute images. It
1781 is not a compressed format. Its purpose is solely
1782 to allow very fast loading of images your program
1783 needs often in order to build other images for
1784 output. If you are experiencing performance
1785 problems when loading large, fixed GIF images your
1786 program needs to produce its output images, you may
1787 wish to examine the functions gdImageCreateFromGd
1788 and gdImageGd, which read and write .gd format
1789 images.
1791 The program "giftogd.c" is provided as a simple way
1792 of converting .gif files to .gd format. I emphasize
1793 again that you will not need to use this format
1794 unless you have a need for high-speed loading of a
1795 few frequently-used images in your program.
1797 Please tell us you're using gd!
1799 When you contact us and let us know you are using
1800 gd, you help us justify the time spent in
1801 maintaining and improving it. So please let us
1802 know. If the results are publicly visible on the
1803 web, a URL is a wonderful thing to receive, but if
1804 it's not a publicly visible project, a simple note
1805 is just as welcome.
1807 If you have problems
1809 If you have any difficulties with gd, feel free to
1810 contact the author, Thomas Boutell. Be sure to read
1811 this manual carefully first.
1813 Alphabetical quick index
1815 gdBrushed | gdDashSize | gdFont | gdFontPtr |
1816 gdImage | gdImageArc | gdImageBlue |
1817 gdImageBoundsSafe | gdImageChar | gdImageCharUp |
1818 gdImageColorAllocate | gdImageColorClosest |
1819 gdImageColorDeallocate | gdImageColorExact |
1820 gdImageColorTransparent | gdImageCopy |
1821 gdImageCopyResized | gdImageCreate |
1822 gdImageCreateFromGd | gdImageCreateFromGif |
1823 gdImageCreateFromXbm | gdImageDashedLine |
1824 gdImageDestroy | gdImageFill | gdImageFillToBorder
1825 | gdImageFilledRectangle | gdImageGd |
1826 gdImageGetInterlaced | gdImageGetPixel |
1827 gdImageGetTransparent | gdImageGif | gdImageGreen |
1828 gdImageInterlace | gdImageLine |
1829 gdImageFilledPolygon | gdImagePolygon | gdImagePtr
1830 | gdImageRectangle | gdImageRed | gdImageSetBrush |
1831 gdImageSetPixel | gdImageSetStyle | gdImageSetTile
1832 | gdImageString | gdImageString16 | gdImageStringUp
1833 | gdImageStringUp16 | gdMaxColors | gdPoint |
1834 gdStyled | gdStyledBrushed | gdTiled |
1835 gdTransparent
1837 Boutell.Com, Inc.