source: trunk/tools/database/gd/index.html@ 9164

Last change on this file since 9164 was 829, checked in by bird, 26 years ago

gifdraw (gd) v1.2 - initial checkin.
File size: 88.8 KB
Line 
1<HTML>
2<HEAD>
3<TITLE>gd 1.2</TITLE>
4</HEAD>
5<BODY>
6<H1>gd 1.2</H1>
7<H2>A graphics library for fast GIF creation</H2>
8<H2>Follow this link to the
9<A HREF="http://www.boutell.com/gd/">latest version
10of this document</A>.</H2>
11<H3>Table of Contents</H3>
12<UL>
13<LI><A HREF="#notice">Credits and license terms</A>
14<LI><A HREF="#whatsnew1.2">What's new in version 1.2?</A>
15<LI><A HREF="#whatsnew1.1.1">What's new in version 1.1.1?</A>
16<LI><A HREF="#whatis">What is gd?</A>
17<LI><A HREF="#gdperl">What if I want to use Perl instead of C?</A>
18<LI><A HREF="#gdtcl">What if I want to use Tcl instead of C?</A>
19<LI><A HREF="#gdit">What if I want to use another scripting language?</A>
20<LI><A HREF="#required">What else do I need to use gd?</A>
21<LI><A HREF="#getgd">How do I get gd?</A>
22<LI><A HREF="#buildgd">How do I build gd?</A>
23<LI><A HREF="#basics">gd basics: using gd in your program</A>
24<LI><A HREF="#webgif">webgif: a useful example</A>
25<LI><A HREF="#reference">Function and type reference by category</A>
26<LI><A HREF="#gdformat">About the additional .gd image file format</A>
27<LI><A HREF="#informing"><strong>Please</strong>
28 tell us you're using gd!</A>
29<LI><A HREF="#problems">If you have problems</A>
30<LI><A HREF="#languages">Using gd from tcl</A></LI>
31<LI><A HREF="#index">Alphabetical quick index</A>
32</UL>
33<P><A HREF="http://www.boutell.com/">
34Up to the <EM>boutell.com, Inc. Home Page</EM></A>
35<A NAME="notice"><H3>Credits and license terms</A></H3>
36<P>
37gd 1.2 is copyright 1994, 1995, Quest Protein Database Center,
38Cold Spring Harbor Labs. Permission granted to copy and distribute
39this work provided that this notice remains intact. Credit
40for the library must be given to the Quest Protein Database Center,
41Cold Spring Harbor Labs, in all derived works. This does not
42affect your ownership of the derived work itself, and the intent
43is to assure proper credit for Quest, not to interfere with your
44use of gd. If you have questions, ask. ("Derived works"
45includes all programs that utilize the library. Credit must
46be given in user-visible documentation.)
47<p>
48gd 1.2 was written by Thomas Boutell and is currently
49distributed by boutell.com, Inc.
50<P>
51If you wish to release modifications to gd,
52please clear them first by sending email to
53boutell@boutell.com; if this is not done, any modified version of the gd
54library must be clearly labeled as such.
55<P>
56The Quest Protein Database Center is funded under Grant P41-RR02188 by
57the National Institutes of Health.
58<P>
59Written by <A HREF="http://sunsite.unc.edu/boutell/index.html">
60Thomas Boutell</A>, 2/94 - 8/95.
61<P>
62The GIF compression code is based on that found in the pbmplus
63utilities, which in turn is based on GIFENCOD by David Rowley. See the
64notice below:
65
66<PRE>
67/*
68** Based on GIFENCOD by David Rowley <mgardi@watdscu.waterloo.edu>.A
69** Lempel-Zim compression based on "compress".
70**
71** Modified by Marcel Wijkstra <wijkstra@fwi.uva.nl>
72**
73** Copyright (C) 1989 by Jef Poskanzer.
74**
75** Permission to use, copy, modify, and distribute this software and its
76** documentation for any purpose and without fee is hereby granted, provided
77** that the above copyright notice appear in all copies and that both that
78** copyright notice and this permission notice appear in supporting
79** documentation. This software is provided "as is" without express or
80** implied warranty.
81**
82** The Graphics Interchange Format(c) is the Copyright property of
83** CompuServe Incorporated. GIF(sm) is a Service Mark property of
84** CompuServe Incorporated.
85*/
86</PRE>
87<P>
88<A NAME="koblas">
89The GIF decompression is based on that found in the pbmplus
90utilities, which in turn is based on GIFDECOD by David Koblas. See the
91notice below:
92<PRE>
93/* +-------------------------------------------------------------------+ */
94/* | Copyright 1990, 1991, 1993, David Koblas. (koblas@netcom.com) | */
95/* | Permission to use, copy, modify, and distribute this software | */
96/* | and its documentation for any purpose and without fee is hereby | */
97/* | granted, provided that the above copyright notice appear in all | */
98/* | copies and that both that copyright notice and this permission | */
99/* | notice appear in supporting documentation. This software is | */
100/* | provided "as is" without express or implied warranty. | */
101/* +-------------------------------------------------------------------+ */
102</PRE>
103</A>
104<A NAME="whatis"><H3>What is gd?</H3></A>
105<P>
106gd is a graphics library. It allows your code to quickly
107draw images complete with lines, arcs, text, multiple
108colors, cut and paste from other images, and flood fills, and
109write out the result as a .GIF file. This is particularly
110useful in World Wide Web applications, where .GIF is the
111format used for inline images.
112<P>
113gd is not a paint program.
114If you are looking for a paint program, try xpaint by David
115Koblas, available by <A HREF="ftp://ftp.netcom.com/pub/ko/koblas">
116anonymous FTP</A> from ftp.netcom.com in pub/ko/koblas.
117(That package is for the X Window System; for the Mac and the PC, paint
118programs are considerably easier to find.)
119<P>
120gd does not provide for every possible desirable graphics
121operation. It is not necessary or desirable for gd to become
122a kitchen-sink graphics package, but version 1.2 incorporates
123most of the commonly requested features for a 2D package.
124Font support does need improvement, and support for the PNG
125graphics format will arrive in a forthcoming release.
126<P>
127<A NAME="gdperl"><H3>What if I want to use Perl instead of C?</H3></A>
128gd can also be used from Perl, courtesy of
129Lincoln Stein's
130<a href="http://www-genome.wi.mit.edu/ftp/pub/software/WWW/GD.html">
131GD.pm</a> library, which uses gd as the basis for a set of
132Perl 5.x classes. GD.pm is based on gd 1.1.1 but gd 1.2 should
133be compatible.
134<A NAME="gdtcl"><H3>What if I want to use Tcl instead of C?</H3></A>
135gd can also be used from Tcl by way of the
136<a href="http://guraldi.hgp.med.umich.edu/gdtcl.html">gdtcl</a>
137Tcl extension.
138<A NAME="gdit"><H3>What if I want to use another scripting language?</H3></A>
139There are, at the moment, at least three simple interpreters that
140perform gd operations. You can output the desired commands to a simple
141text file from whatever scripting language you prefer to use, then
142invoke the interpreter.
143<p>
144These packages are based on gd 1.1.1 as of this writing but should
145be compatible with gd 1.2 with minimal tweaking.
146<ul>
147<li><a href="http://www.demon.co.uk/3Wiz/gdit/">gdit</a>, by David
148Harvey-George
149<li><a href="http://s27w007.pswfs.gov/tgd/">tgd</a>, by Bradley K. Sherman
150<li><a href="http://www.unimelb.edu.au/fly/fly.html">fly</a>, by Martin Gleeson
151</ul>
152<P><A NAME="whatsnew1.2"><H3>What's new in version 1.2?</H3></A>
153Version 1.2 is another fine-tuning release. The next major release
154will after 1.2 will be version 2.0 and will feature support for
155the new <a href="http://sunsite.unc.edu/boutell/png.html">PNG</a>
156graphics format as well as improved font support. gd 1.2 does
157add several new fonts in the meantime.
158<p>
159Version 1.2 moves gd to ANSI standard C. Non-ANSI C compilers,
160such as the old SunOS 4.1.3 cc compiler, will not work. The use
161of pre-ANSI C led to several long-standing bugs, and the ANSI C
162standard has been with us for nearly ten years now. If your compiler
163does not support ANSI, upgrade to a recent release of your compiler,
164or get gcc, which is free and does support ANSI C.
165<P>
166The provided Unix Makefile has been changed to be a bit
167more broadly compatible, and to acknowledge the changes that
168may be necessary on various systems.
169<P>
170Version 1.2 also includes the following improvements:
171<P>
172<ul>
173<li><a href="#gdImageCopy">gdImageCopy</a> and
174<a href="#gdImageCopyResized">gdImageCopyResized</a> now ignore
175pixels which are transparent in the source image. This is allows
176easy copying of non-square regions, which could previously be
177accomplished only with brushes.
178<li><a href="#gdImageFilledPolygon">gdImageFilledPolygon</a>
179now draws horizontal edges correctly, correcting a
180long-standing bug. In addition, gdImageFilledPolygon copes
181with polygons which have several horizontal segments on
182the same scan line. There can still be a few pixels of
183disagreement between gdImagePolygon and gdImageFilledPolygon
184with regard to the borders of the polygon, however.
185<li>Several new public-domain fonts are included, courtesy of
186Joseph M. Orost at AT&T.
187<li>gd now properly recognizes an existing image with a
188high color slot number transparent.
189<li>Bugs in the <a href="#gdImageCreateFromXbm">gdImageCreateFromXbm</a>
190function have been corrected. Previously the function was incorrect
191for image widths not evenly divisible by eight.
192</ul>
193<P>
194<A NAME="whatsnew1.1.1"><H3>What's new in version 1.1.1?</H3></A>
195A fine-tuning and bug-fixing release.
196<P>
197<A HREF="#gdImageSetStyle">gdImageSetStyle</A> now copies
198the style array to make it easier to take advantage of
199the line styling feature; it is now safe to free the memory
200associated with your style array after setting a style
201(or allocate styles on the stack...). This should not break
202existing code.
203<P>
204<A HREF="#webgif">webgif</A>, a small but powerful GIF-manipulating
205utility program, has been added as an additional code example.
206<P>
207An access macro to determine
208whether an image is interlaced has been added; see
209<A HREF="gdImageGetInterlaced">gdImageGetInterlaced</A>.
210<P>
211A better Unix Makefile, provided by Mark Scott. Note that
212an actual library (libgd.a) is now produced; you will want
213to link with this library in your own gd apps, in the same
214manner that gddemo and giftogd link with it. You no longer
215need to explicitly list the standard font files on the link
216line. No doubt many users have already made this enhancement
217themselves.
218<p>
219<strong>Important:</strong> depending on your system you may
220need to rewrite this Makefile. Basic code-compiling skills
221are expected for the use of this library.
222<P>
223<A HREF="#koblas">David Koblas</A> has been given proper credit
224for the original GIF decoding routine; previously I erroneously
225credited David Rowley with both the encoder and the decoder.
226<P>
227<A HREF="#gdImageFill">gdImageFill</A> no longer crashes when
228attempting to fill a region with the color it already has.
229Also, attempting to fill a region with the special color
230<A HREF="#gdTiled">gdTiled</A> no longer crashes.
231<P>
232However, filling a region with a transparent tile has been
233forbidden (gdImageFill simply draws nothing in this case).
234Otherwise, gd would not know when to stop drawing
235without the use of an additional image to keep track of
236which pixels have been visited.
237<P>
238Invoking <A HREF="#gdImageFillToBorder">gdImageFillToBorder</A>
239with a special border color such as <A HREF="#gdTiled">gdTiled</A>
240now fails, for similar reasons. However, the color
241you are filling <em>with</em> can be <A HREF="#gdTiled">gdTiled</A>,
242even if it is transparent. See the discussion of
243<A HREF="#gdImageFillToBorder">gdImageFillToBorder</A> for
244additional caveats.
245<P>
246Many documentation fixes.
247<P>
248<A NAME="whatsnew1.1"><H3>What's new in version 1.1?</H3></A>
249<P>
250<UL>
251<LI><A HREF="#gdImageFilledPolygon">Polygon fills</A></LI>
252<LI><A HREF="#gdImageSetStyle">Line styling</A></LI>
253<LI><A HREF="#gdImageSetBrush">"Brushing" of lines with a brush image</A></LI>
254<LI><A HREF="#gdImageSetTile">Tiling of polygon, rectangle and flood-fills</A>
255<LI><A HREF="#gdImageInterlace">Interlaced GIFs for gradual fade-in</A></LI>
256</LI>
257<LI>Macros to access <A HREF="#gdImageSX">image size</A>, etc.</LI>
258</UL>
259<P>
260<A NAME="required"><H3>What else do I need to use gd?</H3></A>
261<P>
262To use gd, you will need an ANSI C compiler. Any full-ANSI-standard
263C compiler should be adequate, although those with PCs will need to replace
264the Makefile with one of their own. <strong>The cc compiler released
265with SunOS 4.1.3 is not an ANSI C compiler. Get gcc, which is freely
266available. See the Sun-related newsgroups for more information.</strong>
267<P>
268You will also want a GIF viewer, if you do not already have
269one for your system, since you will need a good way to check the
270results of your work. lview is a good package for
271Windows PCs; xv is a good package for X11. There are
272GIF viewers available for every graphics-capable
273computer out there, so consult newsgroups relevant to
274your particular system.
275<P>
276<A NAME="getgd"><H3>How do I get gd?</H3></A>
277<P>
278You can
279<A HREF="http://www.boutell.com/gd/gd1.2.tar.Z">
280fetch gd as a compressed tar file</A> from www.boutell.com.
281<A NAME="buildgd"><H3>How do I build gd?</H3></A>
282<P>
283In order to build gd, first uncompress and untar the gd.tar file with the
284following commands:
285<P>
286<em>Note:</em> if you have a non-Unix system, you will need
287to acquire versions of "uncompress" and "tar" suitable for
288your system. Both have been ported to PC and Mac
289environments. Consult newsgroups relevant to your
290particular system.
291<PRE>
292uncompress gd1.2.tar.Z
293tar -xf gd1.2.tar
294</PRE>
295This will create the directory "gd1.2" beneath the current
296directory.
297<P>
298cd to this directory and examine the Makefile, which you may need
299to change slightly depending on your installation (or more than
300slightly for a Windows or Mac environment).
301<P>
302Now, to build the demonstration program, just type "make gddemo"
303if you are working in a command-line environment. If all goes well,
304the program "gddemo" will be compiled and linked without incident.
305Depending on your system you may need to edit the Makefile.
306Understanding the basic techniques of compiling and linking
307programs on your system is up to you.
308<P>
309You have now built a demonstration program which shows off
310the capabilities of gd. To see it in action, type
311"gddemo".
312<P>
313gddemo should execute without incident, creating the file
314demoout.gif. (Note there is also a file named demoin.gif,
315which is provided in the package as part of the demonstration.)
316<P>
317Display demoout.gif in your GIF viewer. The image should
318be 128x128 pixels and should contain an image of the
319space shuttle with the word "hi" written in the upper
320left corner twice (once across and once upwards),
321an arc in the middle and an oval intersecting the arc
322(these are somewhat faint).
323<p>
324In addition, a diagonal line made up of tiny space shuttle
325images should appear from the lower left to the upper
326right corner. A blue frame with green interior trim should
327surround the picture.
328<P>
329(If you are missing the demoin.gif file, the other items
330should appear anyway.)
331<P>
332Look at demoin.gif to see the original space shuttle
333image which was scaled and copied into the output image.
334<P>
335<A NAME="basics"><H3>gd basics: using gd in your program</H3></A>
336gd lets you create GIF images on the fly. To use gd in your
337program, include the file gd.h, and link with the libgd.a
338library produced by "make libgd.a", under Unix. You will
339need to adapt the makefile for your needs if you are using
340a non-Unix operating system, but this is very straightforward.
341<P>
342If you want to use the provided fonts, include
343gdfontt.h, gdfonts.h, gdfontmb.h, gdfontl.h and/or gdfontg.h. If you
344are not using the provided Makefile and/or a library-based approach, be
345sure to include the source modules as well in your
346project. (They may be too large for 16-bit memory models,
347that is, 16-bit DOS and Windows.)
348<P>
349Here is a short example program. <strong>(For a more advanced example,
350see gddemo.c, included in the distribution. gddemo.c is NOT the same program;
351it demonstrates additional features!)</strong>
352<P>
353<PRE>
354/* Bring in gd library functions */
355#include "gd.h"
356
357/* Bring in standard I/O so we can output the GIF to a file */
358#include &lt;stdio.h&gt;
359
360int main() {
361 /* Declare the image */
362 <A HREF="#gdImagePtr">gdImagePtr</A> im;
363 /* Declare an output file */
364 FILE *out;
365 /* Declare color indexes */
366 int black;
367 int white;
368
369 /* Allocate the image: 64 pixels across by 64 pixels tall */
370 im = <A HREF="#gdImageCreate">gdImageCreate</A>(64, 64);
371
372 /* Allocate the color black (red, green and blue all minimum).
373 Since this is the first color in a new image, it will
374 be the background color. */
375 black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
376
377 /* Allocate the color white (red, green and blue all maximum). */
378 white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
379
380 /* Draw a line from the upper left to the lower right,
381 using white color index. */
382 <A HREF="#gdImageLine">gdImageLine</A>(im, 0, 0, 63, 63, white);
383
384 /* Open a file for writing. "wb" means "write binary", important
385 under MSDOS, harmless under Unix. */
386 out = fopen("test.gif", "wb");
387
388 /* Output the image to the disk file. */
389 <A HREF="#gdImageGif">gdImageGif</A>(im, out);
390
391 /* Close the file. */
392 fclose(out);
393
394 /* Destroy the image in memory. */
395 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
396}
397</PRE>
398When executed, this program creates an image, allocates
399two colors (the first color allocated becomes the background
400color), draws a diagonal line (note that 0, 0 is the upper
401left corner), writes the image to a GIF file, and
402destroys the image.
403<P>
404The above example program should
405give you an idea of how the package works.
406gd provides many additional functions, which are listed
407in the following reference chapters, complete with code
408snippets demonstrating each. There is also an
409<A HREF="#index">alphabetical index</A>.
410<H3><A NAME="webgif">Webgif: a more powerful gd example</A></H3>
411Webgif is a simple utility program to manipulate GIFs from the
412command line. It is written for Unix and similar command-line
413systems, but should be easily adapted for other environments.
414Webgif allows you to set transparency and interlacing and
415output interesting information about the GIF in question.
416<P>
417webgif.c is provided in the distribution. Unix users can
418simply type "make webgif" to compile the program. Type
419"webgif" with no arguments to see the available options.
420A discussion of the code follows.
421<PRE>
422/* Bring in the gd library functions */
423#include "gd.h"
424
425/* Bring in standard I/O and string manipulation functions */
426#include <stdio.h>
427#include <string.h>
428
429int main(argc, argv)
430 int argc;
431 char *argv[];
432{
433 FILE *in;
434 FILE *out;
435 /* Declare our image pointer */
436 <A HREF="#gdImagePtr">gdImagePtr</A> im = 0;
437 int i;
438 /* We'll clear 'no' once we know the user has made a
439 reasonable request. */
440 int no = 1;
441 /* We'll set 'write' once we know the user's request
442 requires that the image be written back to disk. */
443 int write = 0;
444 /* C programs always get at least one argument; we want at
445 least one more (the image), more in practice. */
446 if (argc < 2) {
447 no = 1;
448 goto usage;
449 }
450 /* The last argument should be the image. Open the file. */
451 in = fopen(argv[argc-1], "rb");
452 if (!in) {
453 fprintf(stderr,
454 "Error: can't open file %s.\n", argv[argc-1]);
455 }
456 /* Now load the image. */
457 im = <A HREF="#gdImageCreateFromGif">gdImageCreateFromGif</A>(in);
458 fclose(in);
459 /* If the load failed, it must not be a GIF file. */
460 if (!im) {
461 fprintf(stderr,
462 "Error: %s is not a valid gif file.\n", argv[1]);
463 exit(1);
464 }
465 /* Consider each argument in turn. */
466 for (i=1; (i < (argc-1)); i++) {
467 /* -i turns on and off interlacing. */
468 if (!strcmp(argv[i], "-i")) {
469 if (i == (argc-2)) {
470 fprintf(stderr,
471 "Error: -i specified without y or n.\n");
472 no = 1;
473 goto usage;
474 }
475 if (!strcmp(argv[i+1], "y")) {
476 /* Set interlace. */
477 <A HREF="#gdImageInterlace">gdImageInterlace</A>(im, 1);
478 } else if (!strcmp(argv[i+1], "n")) {
479 /* Clear interlace. */
480 <A HREF="#gdImageInterlace">gdImageInterlace</A>(im, 0);
481 } else {
482 fprintf(stderr,
483 "Error: -i specified without y or n.\n");
484 no = 1;
485 goto usage;
486 }
487 i++;
488 no = 0;
489 write = 1;
490 } else if (!strcmp(argv[i], "-t")) {
491 /* Set transparent index (or none). */
492 int index;
493 if (i == (argc-2)) {
494 fprintf(stderr,
495 "Error: -t specified without a color table index.\n");
496 no = 1;
497 goto usage;
498 }
499 if (!strcmp(argv[i+1], "none")) {
500 /* -1 means not transparent. */
501 <A HREF="#gdImageColorTransparent">gdImageColorTransparent</A>(im, -1);
502 } else {
503 /* OK, get an integer and set the index. */
504 index = atoi(argv[i+1]);
505 <A HREF="#gdImageColorTransparent">gdImageColorTransparent</A>(im, index);
506 }
507 i++;
508 write = 1;
509 no = 0;
510 } else if (!strcmp(argv[i], "-l")) {
511 /* List the colors in the color table. */
512 int j;
513 /* Tabs used below. */
514 printf("Index Red Green Blue\n");
515 for (j=0; (j < <A HREF="#gdImageColorsTotal">gdImageColorsTotal</A>(im)); j++) {
516 /* Use access macros to learn colors. */
517 printf("%d %d %d %d\n",
518 j,
519 <A HREF="#gdImageRed">gdImageRed</A>(im, j),
520 <A HREF="#gdImageGreen">gdImageGreen</A>(im, j),
521 <A HREF="#gdImageBlue">gdImageBlue</A>(im, j));
522 }
523 no = 0;
524 } else if (!strcmp(argv[i], "-d")) {
525 /* Output dimensions, etc. */
526 int t;
527 printf("Width: %d Height: %d Colors: %d\n",
528 <A HREF="#gdImageSX">gdImageSX</A>(im), <A HREF="#gdImageSY">gdImageSY</A>(im),
529 <A HREF="#gdImageColorsTotal">gdImageColorsTotal</A>(im));
530 t = <A HREF="#gdImageGetTransparent">gdImageGetTransparent</A>(im);
531 if (t != (-1)) {
532 printf("Transparent index: %d\n", t);
533 } else {
534 /* -1 means the image is not transparent. */
535 printf("Transparent index: none\n");
536 }
537 if (<A HREF="#gdImageGetInterlaced">gdImageGetInterlaced</A>(im)) {
538 printf("Interlaced: yes\n");
539 } else {
540 printf("Interlaced: no\n");
541 }
542 no = 0;
543 } else {
544 fprintf(stderr, "Unknown argument: %s\n", argv[i]);
545 break;
546 }
547 }
548usage:
549 if (no) {
550 /* If the command failed, output an explanation. */
551 fprintf(stderr,
552 "Usage: webgif [-i y|n ] [-l] [-t index|off ] [-d] gifname.gif\n");
553 fprintf(stderr,
554 "Where -i controls interlace (specify y or n for yes or no),\n");
555 fprintf(stderr,
556 "-l outputs a table of color indexes, -t sets the specified\n");
557 fprintf(stderr,
558 "color index (0-255 or none) to be the transparent color, and\n");
559 fprintf(stderr,
560 "-d reports the dimensions and other characteristics of the image.\n");
561 fprintf(stderr,
562 "Note: you may wish to pipe to \"more\" when using the -l option.\n");
563 }
564 if (write) {
565 /* Open a temporary file. */
566 out = fopen("temp.tmp", "wb");
567 if (!out) {
568 fprintf(stderr,
569 "Unable to write to temp.tmp -- exiting\n");
570 exit(1);
571 }
572 /* Write the new gif. */
573 <A HREF="#gdImageGif">gdImageGif</A>(im, out);
574 fclose(out);
575 /* Erase the old gif. */
576 unlink(argv[argc-1]);
577 /* Rename the new to the old. */
578 rename("temp.tmp", argv[argc-1]);
579 }
580 /* Delete the image from memory. */
581 if (im) {
582 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
583 }
584 /* All's well that ends well. */
585 return 0;
586}
587</PRE>
588<H2><A NAME="reference">Function and type reference</A></H2>
589<UL>
590<LI><A HREF="#types">Types</A></LI>
591<LI><A HREF="#creating">Image creation, destruction, loading and saving</A></LI>
592<LI><A HREF="#drawing">Drawing, styling, brushing, tiling and
593filling functions</A></LI>
594<LI><A HREF="#query">Query functions (not color-related)</A></LI>
595<LI><A HREF="#fonts">Font and text-handling functions</A></LI>
596<LI><A HREF="#colors">Color handling functions</A></LI>
597<LI><A HREF="#copying">Copying and resizing functions</A></LI>
598<LI><A HREF="#misc">Miscellaneous Functions</A></LI>
599<LI><A HREF="#constants">Constants</A></LI>
600</UL>
601<H3><A NAME="types">Types</A></H3>
602<DL>
603<DT><A NAME="gdImage"><code>gdImage</code><strong>(TYPE)</strong></A>
604<DD>
605The data structure in which gd stores images. <A HREF="#gdImageCreate">
606gdImageCreate</A> returns
607a pointer to this type, and the other functions expect to receive
608a pointer to this type as their first argument. You may
609read the members <code>sx</code> (size on X axis),
610<code>sy</code> (size on Y axis), <code>colorsTotal</code>
611(total colors), <code>red</code> (red component of colors;
612an array of 256 integers between 0 and 255), <code>green</code>
613(green component of colors, as above), <code>blue</code>
614(blue component of colors, as above), and <code>transparent</code>
615(index of transparent color, -1 if none); please do so
616using the macros provided. Do NOT set the members directly
617from your code; use the functions provided.
618<PRE>
619typedef struct {
620 unsigned char ** pixels;
621 int sx;
622 int sy;
623 int colorsTotal;
624 int red[gdMaxColors];
625 int green[gdMaxColors];
626 int blue[gdMaxColors];
627 int open[gdMaxColors];
628 int transparent;
629} gdImage;
630</PRE>
631<DT><A NAME="gdImagePtr">gdImagePtr</A> <strong>(TYPE)</strong>
632<DD>
633A pointer to an image structure. <A HREF="#gdImageCreate">gdImageCreate</A>
634returns this type, and the other functions expect it as the first
635argument.
636<DT><A NAME="gdFont">gdFont</A> <strong>(TYPE)</strong>
637<DD>
638A font structure. Used to declare the characteristics of a font.
639Plese see the files gdfontl.c and gdfontl.h for an example of the
640proper declaration of this structure. You can provide your
641own font data by providing such a structure and the associated
642pixel array. You can determine the width and height of a single
643character in a font by examining the w and h members of the
644structure. If you will not be creating your own fonts, you will
645not need to concern yourself with the rest of the components of this
646structure.
647<PRE>
648typedef struct {
649 /* # of characters in font */
650 int nchars;
651 /* First character is numbered... (usually 32 = space) */
652 int offset;
653 /* Character width and height */
654 int w;
655 int h;
656 /* Font data; array of characters, one row after another.
657 Easily included in code, also easily loaded from
658 data files. */
659 char *data;
660} gdFont;
661</PRE>
662<DT><A NAME="gdFontPtr">gdFontPtr</A> <strong>(TYPE)</strong>
663<DD>
664A pointer to a font structure. Text-output functions expect these
665as their second argument, following the <A HREF="#gdImagePtr">
666gdImagePtr</A> argument. Two such pointers are declared in the
667provided include files gdfonts.h and gdfontl.h.
668<DT><A NAME="gdPoint">gdPoint</A> <strong>(TYPE)</strong>
669<DD>
670Represents a point in the coordinate space of the image; used
671by <A HREF="#gdImagePolygon">gdImagePolygon</A> and
672<A HREF="#gdImageFilledPolygon">gdImageFilledPolygon</A>.
673<PRE>
674typedef struct {
675 int x, y;
676} gdPoint, *gdPointPtr;
677</PRE>
678<DT><A NAME="gdPointPtr">gdPointPtr</A> <strong>(TYPE)</strong>
679<DD>
680A pointer to a <A HREF="#gdPoint">gdPoint</A> structure; passed
681as an argument to <A HREF="#gdImagePolygon">gdImagePolygon</A>
682and <A HREF="#gdImageFilledPolygon">gdImageFilledPolygon</A>.
683</DL>
684<H3><A NAME="creating">Image creation, destruction, loading and saving</A></H3>
685<DL>
686<DT><A NAME="gdImageCreate">gdImageCreate(sx, sy)</A>
687<strong>(FUNCTION)</strong>
688<DD>
689gdImageCreate is called to create images. Invoke gdImageCreate
690with the x and y dimensions of the desired image. gdImageCreate
691returns a <A HREF="#gdImagePtr">gdImagePtr</A> to the new image, or
692NULL if unable to
693allocate the image. The image must eventually be destroyed
694using <A HREF="#gdImageDestroy">gdImageDestroy()</A>.
695<PRE>
696... inside a function ...
697<A HREF="#gdImagePtr">gdImagePtr</A> im;
698im = gdImageCreate(64, 64);
699/* ... Use the image ... */
700<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
701</PRE>
702<DT><A NAME="gdImageCreateFromGif">gdImageCreateFromGif(FILE *in)</A>
703<strong>(FUNCTION)</strong>
704<DD>
705gdImageCreateFromGif is called to load images from GIF format files.
706Invoke gdImageCreateFromGif with an already opened pointer to a file
707containing the desired image.
708gdImageCreateFromGif
709returns a <A HREF="#gdImagePtr">gdImagePtr</A> to the new image, or NULL
710if unable to load the image (most often because the file is corrupt or
711does not contain a GIF image). gdImageCreateFromGif does <em>not</em>
712close the file. You can inspect the sx and sy members of the
713image to determine its size. The image must eventually be destroyed
714using <A HREF="#gdImageDestroy">gdImageDestroy()</A>.
715<PRE>
716<A HREF="#gdImagePtr">gdImagePtr</A> im;
717... inside a function ...
718FILE *in;
719in = fopen("mygif.gif", "rb");
720im = gdImageCreateFromGif(in);
721fclose(in);
722/* ... Use the image ... */
723<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
724</PRE>
725<DT><A NAME="gdImageCreateFromGd">gdImageCreateFromGd(FILE *in)</A>
726<strong>(FUNCTION)</strong>
727<DD>
728gdImageCreateFromGd is called to load images from gd format files.
729Invoke gdImageCreateFromGd
730with an already opened pointer to a file containing the desired image
731in the <A HREF="#gdformat">gd file format</A>, which is specific to
732gd and intended for very fast loading. (It is <em>not</em> intended for
733compression; for compression, use GIF.)
734gdImageCreateFromGd
735returns a <A HREF="#gdImagePtr">gdImagePtr</A> to the new image, or NULL
736if unable to load the image (most often because the file is corrupt or
737does not contain a gd format image). gdImageCreateFromGd does <em>not</em>
738close the file. You can inspect the sx and sy members of the
739image to determine its size. The image must eventually be destroyed
740using <A HREF="#gdImageDestroy">gdImageDestroy()</A>.
741<PRE>
742... inside a function ...
743<A HREF="#gdImagePtr">gdImagePtr</A> im;
744FILE *in;
745in = fopen("mygd.gd", "rb");
746im = gdImageCreateFromGd(in);
747fclose(in);
748/* ... Use the image ... */
749<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
750</PRE>
751<DT><A NAME="gdImageCreateFromXbm">gdImageCreateFromXbm(FILE *in)</A>
752<strong>(FUNCTION)</strong>
753<DD>
754gdImageCreateFromXbm is called to load images from X bitmap format
755files. Invoke gdImageCreateFromXbm
756with an already opened pointer to a file containing the desired image.
757gdImageCreateFromXbm
758returns a <A HREF="#gdImagePtr">gdImagePtr</A> to the new image, or NULL
759if unable to load the image (most often because the file is corrupt or
760does not contain an X bitmap format image). gdImageCreateFromXbm does
761<em>not</em> close the file. You can inspect the sx and sy members of the
762image to determine its size. The image must eventually be destroyed
763using <A HREF="#gdImageDestroy">gdImageDestroy()</A>.
764<PRE>
765... inside a function ...
766<A HREF="#gdImagePtr">gdImagePtr</A> im;
767FILE *in;
768in = fopen("myxbm.xbm", "rb");
769im = gdImageCreateFromXbm(in);
770fclose(in);
771/* ... Use the image ... */
772<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
773</PRE>
774<DT><A NAME="gdImageDestroy">gdImageDestroy(gdImagePtr im)</A> <STRONG>(FUNCTION)</STRONG>
775<DD>gdImageDestroy is used to free the memory associated with
776an image. It is important to invoke gdImageDestroy before
777exiting your program or assigning a new image to
778a <A HREF="#gdImagePtr">gdImagePtr</A> variable.
779<PRE>
780... inside a function ...
781<A HREF="#gdImagePtr">gdImagePtr</A> im;
782im = <A HREF="#gdImageCreate">gdImageCreate</A>(10, 10);
783/* ... Use the image ... */
784/* Now destroy it */
785<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
786</PRE>
787<DT><A NAME="gdImageGif">
788void gdImageGif(gdImagePtr im, FILE *out)</A>
789<STRONG>(FUNCTION)</STRONG>
790<DD>
791gdImageGif outputs the specified image to the specified
792file in GIF format. The file must be open for writing. Under MSDOS,
793it is important to use "wb" as opposed to simply "w"
794as the mode when opening the file, and under Unix there
795is no penalty for doing so. gdImageGif does <em>not</em>
796close the file; your code must do so.
797<PRE>
798... inside a function ...
799<A HREF="#gdImagePtr">gdImagePtr</A> im;
800int black, white;
801FILE *out;
802/* Create the image */
803im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
804/* Allocate background */
805white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
806/* Allocate drawing color */
807black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
808/* Draw rectangle */
809<A HREF="#gdImageRectangle">gdImageRectangle</A>(im, 0, 0, 99, 99, black);
810/* Open output file in binary mode */
811out = fopen("rect.gif", "wb");
812/* Write GIF */
813gdImageGif(im, out);
814/* Close file */
815fclose(out);
816/* Destroy image */
817<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
818</PRE>
819<DT><A NAME="gdImageGd">
820void gdImageGd(gdImagePtr im, FILE *out)</A>
821<STRONG>(FUNCTION)</STRONG>
822<DD>
823gdImageGd outputs the specified image to the specified
824file in the <A HREF="#gdformat">gd image format</A>. The file must
825be open for writing. Under MSDOS, it is important to use "wb" as
826opposed to simply "w" as the mode when opening the file, and under
827Unix there is no penalty for doing so. gdImageGif does <em>not</em>
828close the file; your code must do so.
829<P>
830The gd image format is intended for fast reads and writes of
831images your program will need frequently to build other
832images. It is <em>not</em> a compressed format, and is not intended
833for general use.
834<PRE>
835... inside a function ...
836<A HREF="#gdImagePtr">gdImagePtr</A> im;
837int black, white;
838FILE *out;
839/* Create the image */
840im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
841/* Allocate background */
842white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
843/* Allocate drawing color */
844black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
845/* Draw rectangle */
846<A HREF="#gdImageRectangle">gdImageRectangle</A>(im, 0, 0, 99, 99, black);
847/* Open output file in binary mode */
848out = fopen("rect.gd", "wb");
849/* Write gd format file */
850gdImageGd(im, out);
851/* Close file */
852fclose(out);
853/* Destroy image */
854<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
855</PRE>
856</DL>
857<H3><A NAME="drawing">Drawing Functions</A></H3>
858<DL>
859<DT><A NAME="gdImageSetPixel">void gdImageSetPixel(gdImagePtr im, int x, int y, int color)</A> <STRONG>(FUNCTION)</STRONG>
860<DD>gdImageSetPixel sets a pixel to a particular color index. Always use
861this function or one of the other drawing functions to access pixels;
862do not access the pixels of the <A HREF="#gdImage">gdImage</A> structure
863directly.
864<PRE>
865... inside a function ...
866<A HREF="#gdImagePtr">gdImagePtr</A> im;
867int black;
868int white;
869im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
870/* Background color (first allocated) */
871black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
872/* Allocate the color white (red, green and blue all maximum). */
873white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
874/* Set a pixel near the center. */
875gdImageSetPixel(im, 50, 50, white);
876/* ... Do something with the image, such as saving it to a file... */
877/* Destroy it */
878<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
879</PRE>
880<DT><A NAME="gdImageLine">void gdImageLine(gdImagePtr im, int x1, int y1, int x2, int y2, int color)</A>
881<STRONG>(FUNCTION)</STRONG>
882<DD>
883gdImageLine is used to draw a line between two endpoints (x1,y1 and x2, y2).
884The line is drawn using the color index specified. Note that the color
885index can be an actual color returned by <A HREF="#gdImageColorAllocate">
886gdImageColorAllocate</A> or one of <A HREF="#gdStyled">gdStyled</A>,
887<A HREF="#gdBrushed">gdBrushed</A> or <A HREF="#gdStyledBrushed">
888gdStyledBrushed</A>.
889<PRE>
890... inside a function ...
891<A HREF="#gdImagePtr">gdImagePtr</A> im;
892int black;
893int white;
894im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
895/* Background color (first allocated) */
896black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
897/* Allocate the color white (red, green and blue all maximum). */
898white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
899/* Draw a line from the upper left corner to the lower right corner. */
900gdImageLine(im, 0, 0, 99, 99, white);
901/* ... Do something with the image, such as saving it to a file... */
902/* Destroy it */
903<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
904</PRE>
905<DT><A NAME="gdImageDashedLine">void gdImageDashedLine(gdImagePtr im, int x1, int y1, int x2, int y2, int color)</A>
906<STRONG>(FUNCTION)</STRONG>
907<DD>
908gdImageDashedLine is provided <strong>solely for backwards compatibility
909</strong> with gd 1.0. New programs should draw dashed lines using
910the normal <A HREF="#gdImageLine">gdImageLine</A> function and the
911new <A HREF="#gdImageSetStyle">gdImageSetStyle</A> function.
912<P>
913gdImageDashedLine is used to draw a dashed line between two endpoints
914(x1,y1 and x2, y2).
915The line is drawn using the color index specified. The portions of the line
916that are not drawn are left transparent so the background is visible.
917<PRE>
918... inside a function ...
919<A HREF="#gdImagePtr">gdImagePtr</A> im;
920int black;
921int white;
922im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
923/* Background color (first allocated) */
924black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
925/* Allocate the color white (red, green and blue all maximum). */
926white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
927/* Draw a dashed line from the upper left corner to the lower right corner. */
928gdImageDashedLine(im, 0, 0, 99, 99);
929/* ... Do something with the image, such as saving it to a file... */
930/* Destroy it */
931<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
932</PRE>
933<DT><A NAME="gdImagePolygon">void gdImagePolygon(gdImagePtr im, gdPointPtr points, int pointsTotal, int color)</A>
934<STRONG>(FUNCTION)</STRONG>
935<DD>
936gdImagePolygon is used to draw a polygon with the verticies
937(at least 3) specified, using the color index specified.
938See also <A HREF="#gdImageFilledPolygon">gdImageFilledPolygon</A>.
939<PRE>
940... inside a function ...
941<A HREF="#gdImagePtr">gdImagePtr</A> im;
942int black;
943int white;
944/* Points of polygon */
945<A HREF="#gdPoint">gdPoint</A> points[3];
946im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
947/* Background color (first allocated) */
948black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
949/* Allocate the color white (red, green and blue all maximum). */
950white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
951/* Draw a triangle. */
952points[0].x = 50;
953points[0].y = 0;
954points[1].x = 99;
955points[1].y = 99;
956points[2].x = 0;
957points[2].y = 99;
958gdImagePolygon(im, points, 3, white);
959/* ... Do something with the image, such as saving it to a file... */
960/* Destroy it */
961<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
962</PRE>
963<DT><A NAME="gdImageRectangle">void gdImageRectangle(gdImagePtr im, int x1, int y1, int x2, int y2, int color)</A>
964<STRONG>(FUNCTION)</STRONG>
965<DD>
966gdImageRectangle is used to draw a rectangle with the two corners
967(upper left first, then lower right) specified, using the
968color index specified.
969<PRE>
970... inside a function ...
971<A HREF="#gdImagePtr">gdImagePtr</A> im;
972int black;
973int white;
974im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
975/* Background color (first allocated) */
976black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
977/* Allocate the color white (red, green and blue all maximum). */
978white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
979/* Draw a rectangle occupying the central area. */
980gdImageRectangle(im, 25, 25, 74, 74, white);
981/* ... Do something with the image, such as saving it to a file... */
982/* Destroy it */
983<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
984</PRE>
985<DT><A NAME="gdImageFilledPolygon">void gdImageFilledPolygon(gdImagePtr im, gdPointPtr points, int pointsTotal, int color)</A>
986<STRONG>(FUNCTION)</STRONG>
987<DD>
988gdImageFilledPolygon is used to fill a polygon with the verticies
989(at least 3) specified, using the color index specified.
990See also <A HREF="#gdImageFilledPolygon">gdImagePolygon</A>.
991<PRE>
992... inside a function ...
993<A HREF="#gdImagePtr">gdImagePtr</A> im;
994int black;
995int white;
996int red;
997/* Points of polygon */
998<A HREF="#gdPoint">gdPoint</A> points[3];
999im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
1000/* Background color (first allocated) */
1001black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
1002/* Allocate the color white (red, green and blue all maximum). */
1003white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
1004/* Allocate the color red. */
1005red = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 0, 0);
1006/* Draw a triangle. */
1007points[0].x = 50;
1008points[0].y = 0;
1009points[1].x = 99;
1010points[1].y = 99;
1011points[2].x = 0;
1012points[2].y = 99;
1013/* Paint it in white */
1014gdImageFilledPolygon(im, points, 3, white);
1015/* Outline it in red; must be done second */
1016<A HREF="#gdImagePolygon">gdImagePolygon</A>(im, points, 3, red);
1017/* ... Do something with the image, such as saving it to a file... */
1018/* Destroy it */
1019<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
1020</PRE>
1021<DT><A NAME="gdImageFilledRectangle">void gdImageFilledRectangle(gdImagePtr im, int x1, int y1, int x2, int y2, int color)</A>
1022<STRONG>(FUNCTION)</STRONG>
1023<DD>
1024gdImageFilledRectangle is used to draw a solid rectangle with the two corners
1025(upper left first, then lower right) specified, using the
1026color index specified.
1027<PRE>
1028... inside a function ...
1029<A HREF="#gdImagePtr">gdImagePtr</A> im;
1030int black;
1031int white;
1032im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
1033/* Background color (first allocated) */
1034black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
1035/* Allocate the color white (red, green and blue all maximum). */
1036white = <A HREF="#gdImageColorAllocate">int gdImageColorAllocate</A>(im, 255, 255, 255);
1037/* Draw a filled rectangle occupying the central area. */
1038gdImageFilledRectangle(im, 25, 25, 74, 74, white);
1039/* ... Do something with the image, such as saving it to a file... */
1040/* Destroy it */
1041<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
1042</PRE>
1043<DT><A NAME="gdImageArc">void gdImageArc(gdImagePtr im, int cx, int cy, int w, int h, int s, int e, int color)</A>
1044<STRONG> (FUNCTION)</STRONG>
1045<DD>
1046gdImageArc is used to draw a partial ellipse centered at the given point,
1047with the specified width and height in pixels. The arc begins at
1048the position in degrees specified by <code>s</code> and ends at
1049the position specified by <code>e</code>. The arc is drawn in
1050the color specified by the last argument. A circle can be drawn
1051by beginning from 0 degrees and ending at 360 degrees, with
1052width and height being equal. e must be greater than s. Values greater
1053than 360 are interpreted modulo 360.
1054<PRE>
1055... inside a function ...
1056<A HREF="#gdImagePtr">gdImagePtr</A> im;
1057int black;
1058int white;
1059im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 50);
1060/* Background color (first allocated) */
1061black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
1062/* Allocate the color white (red, green and blue all maximum). */
1063white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
1064/* Inscribe an ellipse in the image. */
1065gdImageArc(im, 50, 25, 98, 48, 0, 360, white);
1066/* ... Do something with the image, such as saving it to a file... */
1067/* Destroy it */
1068<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
1069</PRE>
1070<DT><A NAME="gdImageFillToBorder">void gdImageFillToBorder(gdImagePtr im, int x, int y, int border, int color)
1071<STRONG> (FUNCTION)</STRONG>
1072<DD>
1073gdImageFillToBorder floods a portion of the image with the specified
1074<code>color</code>, beginning at the specified point and stopping at
1075the specified <code>border</code> color. For a way of flooding an
1076area defined by the color of the starting point, see
1077<A HREF="#gdImageFill">gdImageFill</A>.
1078<P>
1079The border color <em>cannot</em> be a special color
1080such as <A HREF="#gdTiled">gdTiled</A>; it must be a proper
1081solid color. The fill color can be, however.
1082<P>
1083Note that gdImageFillToBorder is recursive. It is not the most
1084naive implementation possible, and the implementation is
1085expected to improve, but there will always be degenerate
1086cases in which the stack can become very deep. This can be
1087a problem in MSDOS and MS Windows environments. (Of course,
1088in a Unix or NT environment with a proper stack, this is
1089not a problem at all.)
1090<PRE>
1091... inside a function ...
1092<A HREF="#gdImagePtr">gdImagePtr</A> im;
1093int black;
1094int white;
1095int red;
1096im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 50);
1097/* Background color (first allocated) */
1098black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
1099/* Allocate the color white (red, green and blue all maximum). */
1100white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
1101/* Allocate the color red. */
1102red = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 0, 0);
1103/* Inscribe an ellipse in the image. */
1104gdImageArc(im, 50, 25, 98, 48, 0, 360, white);
1105/* Flood-fill the ellipse. Fill color is red, border color is
1106 white (ellipse). */
1107gdImageFillToBorder(im, 50, 50, white, red);
1108/* ... Do something with the image, such as saving it to a file... */
1109/* Destroy it */
1110<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
1111</PRE>
1112<DT><A NAME="gdImageFill">void gdImageFill(gdImagePtr im, int x, int y, int color)
1113<STRONG> (FUNCTION)</STRONG>
1114<DD>
1115gdImageFill floods a portion of the image with the specified
1116<code>color</code>, beginning at the specified point and flooding the
1117surrounding region of the same color as the starting point.
1118For a way of flooding a region defined by a specific border
1119color rather than by its interior color, see
1120<A HREF="#gdImageFillToBorder">gdImageFillToBorder</A>.
1121<P>
1122The fill color can be <A HREF="#gdTiled">gdTiled</A>, resulting
1123in a tile fill using another image as the tile. However,
1124the tile image cannot be transparent. If the image you wish
1125to fill with has a transparent color index, call
1126<A HREF="#gdImageTransparent">gdImageTransparent</A> on the
1127tile image and set the transparent color index to -1
1128to turn off its transparency.
1129<P>
1130Note that gdImageFill is recursive. It is not the most
1131naive implementation possible, and the implementation is
1132expected to improve, but there will always be degenerate
1133cases in which the stack can become very deep. This can be
1134a problem in MSDOS and MS Windows environments. (Of course,
1135in a Unix or NT environment with a proper stack, this is
1136not a problem at all.)
1137<PRE>
1138... inside a function ...
1139<A HREF="#gdImagePtr">gdImagePtr</A> im;
1140int black;
1141int white;
1142int red;
1143im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 50);
1144/* Background color (first allocated) */
1145black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
1146/* Allocate the color white (red, green and blue all maximum). */
1147white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
1148/* Allocate the color red. */
1149red = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 0, 0);
1150/* Inscribe an ellipse in the image. */
1151gdImageArc(im, 50, 25, 98, 48, 0, 360, white);
1152/* Flood-fill the ellipse. Fill color is red, and will replace the
1153 black interior of the ellipse. */
1154gdImageFill(im, 50, 50, red);
1155/* ... Do something with the image, such as saving it to a file... */
1156/* Destroy it */
1157<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
1158</PRE>
1159<DT><A NAME="gdImageSetBrush">void gdImageSetBrush(gdImagePtr im, gdImagePtr brush)</A>
1160<STRONG>(FUNCTION)</STRONG>
1161<DD>
1162A "brush" is an image used to draw wide, shaped strokes in another image. Just
1163as a paintbrush is not a single point, a brush image need not be
1164a single pixel. <em>Any</em> gd image can be used as a brush, and by
1165setting the transparent color index of the brush image with
1166<A HREF="#gdImageColorTransparent">gdImageColorTransparent</A>,
1167a brush of any shape can be created. All line-drawing functions,
1168such as <A HREF="#gdImageLine">gdImageLine</A> and
1169<A HREF="#gdImagePolygon">gdImagePolygon</A>, will use the
1170current brush if the special "color" <A HREF="#gdBrushed">
1171gdBrushed</A> or <A HREF="#gdStyledBrushed">gdStyledBrushed</A>
1172is used when calling them.
1173<P>
1174gdImageSetBrush is used to specify the brush to be used in a
1175particular image. You can set any image to be the brush.
1176If the brush image does not have the same color map as the
1177first image, any colors missing from the first image
1178will be allocated. If not enough colors can be allocated,
1179the closest colors already available will be used. This
1180allows arbitrary GIFs to be used as brush images. It also
1181means, however, that you should not set a brush unless you
1182will actually use it; if you set a rapid succession of
1183different brush images, you can quickly fill your color map,
1184and the results will not be optimal.
1185<P>
1186You need not take any special action when you are finished
1187with a brush. As for any other image, if you will not
1188be using the brush image for any further purpose,
1189you should call <A HREF="#gdImageDestroy">gdImageDestroy</A>.
1190You must not use the color <A HREF="#gdBrushed">gdBrushed</A>
1191if the current brush has been destroyed; you can of
1192course set a new brush to replace it.
1193<PRE>
1194... inside a function ...
1195<A HREF="#gdImagePtr">gdImagePtr</A> im, brush;
1196FILE *in;
1197int black;
1198im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
1199/* Open the brush GIF. For best results, portions of the
1200 brush that should be transparent (ie, not part of the
1201 brush shape) should have the transparent color index. */
1202in = fopen("star.gif", "rb");
1203brush = <A HREF="#gdImageCreateFromGif">gdImageCreateFromGif</A>(in);
1204/* Background color (first allocated) */
1205black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
1206gdImageSetBrush(im, brush);
1207/* Draw a line from the upper left corner to the lower right corner
1208 using the brush. */
1209<A HREF="#gdImageLine">gdImageLine</A>(im, 0, 0, 99, 99, <A HREF="#gdBrushed">gdBrushed</A>);
1210/* ... Do something with the image, such as saving it to a file... */
1211/* Destroy it */
1212<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
1213/* Destroy the brush image */
1214<A HREF="#gdImageDestroy">gdImageDestroy</A>(brush);
1215</PRE>
1216<DT><A NAME="gdImageSetTile">void gdImageSetTile(gdImagePtr im, gdImagePtr tile)</A>
1217<STRONG>(FUNCTION)</STRONG>
1218<DD>
1219A "tile" is an image used to fill an area with a repeated pattern.
1220<em>Any</em> gd image can be used as a tile, and by
1221setting the transparent color index of the tile image with
1222<A HREF="#gdImageColorTransparent">gdImageColorTransparent</A>,
1223a tile that allows certain parts of the underlying area to shine
1224through can be created. All region-filling functions,
1225such as <A HREF="#gdImageFill">gdImageFill</A> and
1226<A HREF="#gdImageFilledPolygon">gdImageFilledPolygon</A>, will use the
1227current tile if the special "color" <A HREF="#gdTiled">
1228gdTiled</A> is used when calling them.
1229<P>
1230gdImageSetTile is used to specify the tile to be used in a
1231particular image. You can set any image to be the tile.
1232If the tile image does not have the same color map as the
1233first image, any colors missing from the first image
1234will be allocated. If not enough colors can be allocated,
1235the closest colors already available will be used. This
1236allows arbitrary GIFs to be used as tile images. It also
1237means, however, that you should not set a tile unless you
1238will actually use it; if you set a rapid succession of
1239different tile images, you can quickly fill your color map,
1240and the results will not be optimal.
1241<P>
1242You need not take any special action when you are finished
1243with a tile. As for any other image, if you will not
1244be using the tile image for any further purpose,
1245you should call <A HREF="#gdImageDestroy">gdImageDestroy</A>.
1246You must not use the color <A HREF="#gdBrushed">gdTiled</A>
1247if the current tile has been destroyed; you can of
1248course set a new tile to replace it.
1249<PRE>
1250... inside a function ...
1251<A HREF="#gdImagePtr">gdImagePtr</A> im, tile;
1252FILE *in;
1253int black;
1254im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
1255/* Open the tile GIF. For best results, portions of the
1256 tile that should be transparent (ie, allowing the
1257 background to shine through) should have the transparent
1258 color index. */
1259in = fopen("star.gif", "rb");
1260tile = <A HREF="#gdImageCreateFromGif">gdImageCreateFromGif</A>(in);
1261/* Background color (first allocated) */
1262black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
1263gdImageSetTile(im, tile);
1264/* Fill an area using the tile. */
1265<A HREF="#gdImageFilledRectangle">gdImageFilledRectangle</A>(im, 25, 25, 75, 75, <A HREF="#gdTiled">gdTiled</A>);
1266/* ... Do something with the image, such as saving it to a file... */
1267/* Destroy it */
1268<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
1269/* Destroy the tile image */
1270<A HREF="#gdImageDestroy">gdImageDestroy</A>(tile);
1271</PRE>
1272<DT><A NAME="gdImageSetStyle">void gdImageSetStyle(gdImagePtr im, int *style, int styleLength)</A>
1273<STRONG>(FUNCTION)</STRONG>
1274<DD>
1275It is often desirable to draw dashed lines, dotted lines, and other
1276variations on a broken line. gdImageSetStyle can be used to set
1277any desired series of colors, including a special color that
1278leaves the background intact, to be repeated during the drawing
1279of a line.
1280<P>
1281To use gdImageSetStyle, create an array of integers and assign
1282them the desired series of color values to be repeated.
1283You can assign the special color value <A HREF="#gdTransparent">
1284gdTransparent</A> to indicate that the existing color should
1285be left unchanged for that particular pixel (allowing a dashed
1286line to be attractively drawn over an existing image).
1287<P>
1288Then, to draw a line using the style, use the normal
1289<A HREF="#gdImageLine">gdImageLine</A> function with the
1290special color value <A HREF="#gdStyled">gdStyled</A>.
1291<P>
1292As of <A HREF="#whatsnew1.1.1">version 1.1.1</A>, the style
1293array is copied when you set the style, so you need not
1294be concerned with keeping the array around indefinitely.
1295This should not break existing code that assumes styles
1296are not copied.
1297<P>
1298You can also combine styles and brushes to draw the brush
1299image at intervals instead of in a continuous stroke.
1300When creating a style for use with a brush, the
1301style values are interpreted differently: zero (0) indicates
1302pixels at which the brush should not be drawn, while one (1)
1303indicates pixels at which the brush should be drawn.
1304To draw a styled, brushed line, you must use the
1305special color value <A HREF="#gdStyledBrushed">
1306gdStyledBrushed</A>. For an example of this feature
1307in use, see gddemo.c (provided in the distribution).
1308<PRE>
1309<A HREF="#gdImagePtr">gdImagePtr</A> im;
1310int styleDotted[2], styleDashed[6];
1311FILE *in;
1312int black;
1313int red;
1314im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
1315/* Background color (first allocated) */
1316black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
1317red = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 0, 0);
1318/* Set up dotted style. Leave every other pixel alone. */
1319styleDotted[0] = red;
1320styleDotted[1] = gdTransparent;
1321/* Set up dashed style. Three on, three off. */
1322styleDashed[0] = red;
1323styleDashed[1] = red;
1324styleDashed[2] = red;
1325styleDashed[3] = gdTransparent;
1326styleDashed[4] = gdTransparent;
1327styleDashed[5] = gdTransparent;
1328/* Set dotted style. Note that we have to specify how many pixels are
1329 in the style! */
1330gdImageSetStyle(im, styleDotted, 2);
1331/* Draw a line from the upper left corner to the lower right corner. */
1332<A HREF="#gdImageLine">gdImageLine</A>(im, 0, 0, 99, 99, <A HREF="#gdStyled">gdStyled</A>);
1333/* Now the dashed line. */
1334gdImageSetStyle(im, styleDashed, 6);
1335<A HREF="#gdImageLine">gdImageLine</A>(im, 0, 99, 0, 99, <A HREF="#gdStyled">gdStyled</A>);
1336
1337/* ... Do something with the image, such as saving it to a file ... */
1338
1339/* Destroy it */
1340<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
1341</PRE>
1342</DL>
1343<H3><A NAME="query">Query Functions</A></H3>
1344<DL>
1345<DT><A NAME="gdImageBlue">
1346int gdImageBlue(gdImagePtr im, int color)</A>
1347<STRONG>(MACRO)</STRONG>
1348<DD>
1349gdImageBlue is a macro which returns the blue component of
1350the specified color index. Use this macro rather than accessing the
1351structure members directly.
1352<DT><A NAME="gdImageGetPixel">int gdImageGetPixel(gdImagePtr im, int x, int y)</A>
1353<STRONG>(FUNCTION)</STRONG>
1354<DD>
1355gdImageGetPixel() retrieves the color index of a particular
1356pixel. Always use this function to query pixels;
1357do not access the pixels of the <A HREF="#gdImage">gdImage</A> structure
1358directly.
1359<PRE>
1360... inside a function ...
1361FILE *in;
1362gdImagePtr im;
1363int c;
1364in = fopen("mygif.gif", "rb");
1365im = <A HREF="#gdImageCreateFromGif">gdImageCreateFromGif</A>(in);
1366fclose(in);
1367c = gdImageGetPixel(im, gdImageSX(im) / 2, gdImageSY(im) / 2);
1368printf("The value of the center pixel is %d; RGB values are %d,%d,%d\n",
1369 c, im->red[c], im->green[c], im->blue[c]);
1370<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
1371</PRE>
1372<DT><A NAME="gdImageBoundsSafe">
1373int gdImageBoundsSafe(gdImagePtr im, int x, int y)</A>
1374<STRONG>(FUNCTION)</STRONG>
1375<DD>
1376gdImageBoundsSafe returns true (1) if the specified point is within the bounds
1377of the image, false (0) if not. This function is intended primarily for
1378use by those who wish to add functions to gd. All of the gd drawing
1379functions already clip safely to the edges of the image.
1380<PRE>
1381... inside a function ...
1382<A HREF="#gdImagePtr">gdImagePtr</A> im;
1383int black;
1384int white;
1385im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
1386if (gdImageBoundsSafe(im, 50, 50)) {
1387 printf("50, 50 is within the image bounds\n");
1388} else {
1389 printf("50, 50 is outside the image bounds\n");
1390}
1391<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
1392</PRE>
1393<DT><A NAME="gdImageGreen">
1394int gdImageGreen(gdImagePtr im, int color)</A>
1395<STRONG>(MACRO)</STRONG>
1396<DD>
1397gdImageGreen is a macro which returns the green component of
1398the specified color index. Use this macro rather than accessing the
1399structure members directly.
1400<DT><A NAME="gdImageRed">
1401int gdImageRed(gdImagePtr im, int color)</A>
1402<STRONG>(MACRO)</STRONG>
1403<DD>
1404gdImageRed is a macro which returns the red component of
1405the specified color index. Use this macro rather than accessing the
1406structure members directly.
1407<DT><A NAME="gdImageSX">
1408int gdImageSX(gdImagePtr im)</A>
1409<STRONG>(MACRO)</STRONG>
1410<DD>
1411gdImageSX is a macro which returns the width of the image
1412in pixels. Use this macro rather than accessing the
1413structure members directly.
1414<DT><A NAME="gdImageSY">
1415int gdImageSY(gdImagePtr im)</A>
1416<STRONG>(MACRO)</STRONG>
1417<DD>
1418gdImageSY is a macro which returns the height of the image
1419in pixels. Use this macro rather than accessing the
1420structure members directly.
1421</DL>
1422<H3><A NAME="fonts">Fonts and text-handling functions</A></H3>
1423<DL>
1424<DT><A NAME="gdImageChar">
1425void gdImageChar(gdImagePtr im, gdFontPtr font, int x, int y,
1426 int c, int color)</A>
1427<STRONG>(FUNCTION)</STRONG>
1428<DD>
1429gdImageChar is used to draw single characters on the image.
1430(To draw multiple characters, use <A HREF="#gdImageString">
1431gdImageString</A>.) The second argument is a
1432pointer to a font definition structure; five fonts are
1433provided with gd, gdFontTiny, gdFontSmall, gdFontMediumBold,
1434gdFontLarge, and gdFontGiant. You must
1435include the files "gdfontt.h", "gdfonts.h", "gdfontmb.h",
1436"gdfontl.h" and "gdfontg.h" respectively
1437and (if you are not using a library-based approach) link with the
1438corresponding .c files to use the provided fonts.
1439The character specified by the fifth
1440argument is drawn from left to right in the specified
1441color. (See <A HREF="#gdImageCharUp">gdImageCharUp</A> for a way
1442of drawing vertical text.) Pixels not
1443set by a particular character retain their previous color.
1444<PRE>
1445#include "gd.h"
1446#include "gdfontl.h"
1447... inside a function ...
1448<A HREF="#gdImagePtr">gdImagePtr</A> im;
1449int black;
1450int white;
1451im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
1452/* Background color (first allocated) */
1453black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
1454/* Allocate the color white (red, green and blue all maximum). */
1455white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
1456/* Draw a character. */
1457gdImageChar(im, gdFontLarge, 0, 0, 'Q', white);
1458/* ... Do something with the image, such as saving it to a file... */
1459/* Destroy it */
1460<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
1461</PRE>
1462<DT><A NAME="gdImageCharUp">
1463void gdImageCharUp(gdImagePtr im, gdFontPtr font, int x, int y,
1464int c, int color)</A>
1465<STRONG>(FUNCTION)</STRONG>
1466<DD>
1467gdImageCharUp is used to draw single characters on the image,
1468rotated 90 degrees.
1469(To draw multiple characters, use <A HREF="#gdImageStringUp">
1470gdImageStringUp</A>.) The second argument is a
1471pointer to a font definition structure; five fonts are
1472provided with gd, gdFontTiny, gdFontSmall, gdFontMediumBold,
1473gdFontLarge, and gdFontGiant. You must
1474include the files "gdfontt.h", "gdfonts.h", "gdfontmb.h",
1475"gdfontl.h" and "gdfontg.h" respectively
1476and (if you are not using a library-based approach) link with the
1477corresponding .c files to use the provided fonts. The character specified by
1478the fifth argument is drawn
1479from bottom to top, rotated at a 90-degree angle, in the specified
1480color. (See <A HREF="#gdImageChar">gdImageChar</A> for a way
1481of drawing horizontal text.) Pixels not
1482set by a particular character retain their previous color.
1483<PRE>
1484#include "gd.h"
1485#include "gdfontl.h"
1486... inside a function ...
1487<A HREF="#gdImagePtr">gdImagePtr</A> im;
1488int black;
1489int white;
1490im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
1491/* Background color (first allocated) */
1492black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
1493/* Allocate the color white (red, green and blue all maximum). */
1494white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
1495/* Draw a character upwards so it rests against the top of the image. */
1496gdImageCharUp(im, gdFontLarge,
1497 0, gdFontLarge->h, 'Q', white);
1498/* ... Do something with the image, such as saving it to a file... */
1499/* Destroy it */
1500<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
1501</PRE>
1502<DT><A NAME="gdImageString">
1503void gdImageString(gdImagePtr im, gdFontPtr font, int x, int y,
1504char *s, int color)</A>
1505<STRONG>(FUNCTION)</STRONG>
1506<DD>
1507gdImageString is used to draw multiple characters on the image.
1508(To draw single characters, use <A HREF="#gdImageChar">
1509gdImageChar</A>.) The second argument is a
1510pointer to a font definition structure; five fonts are
1511provided with gd, gdFontTiny, gdFontSmall, gdFontMediumBold,
1512gdFontLarge, and gdFontGiant. You must
1513include the files "gdfontt.h", "gdfonts.h", "gdfontmb.h",
1514"gdfontl.h" and "gdfontg.h" respectively
1515and (if you are not using a library-based approach) link with the
1516corresponding .c files to use the provided fonts.
1517The null-terminated C string specified
1518by the fifth argument is drawn from left to right in the specified
1519color. (See <A HREF="#gdImageStringUp">gdImageStringUp</A> for a way
1520of drawing vertical text.) Pixels not
1521set by a particular character retain their previous color.
1522<PRE>
1523#include "gd.h"
1524#include "gdfontl.h"
1525#include &lt;string.h&gt;
1526... inside a function ...
1527<A HREF="#gdImagePtr">gdImagePtr</A> im;
1528int black;
1529int white;
1530/* String to draw. */
1531char *s = "Hello.";
1532im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
1533/* Background color (first allocated) */
1534black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
1535/* Allocate the color white (red, green and blue all maximum). */
1536white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
1537/* Draw a centered string. */
1538gdImageString(im, gdFontLarge,
1539 im->w / 2 - (strlen(s) * gdFontLarge->w / 2),
1540 im->h / 2 - gdFontLarge->h / 2,
1541 s, white);
1542/* ... Do something with the image, such as saving it to a file... */
1543/* Destroy it */
1544<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
1545</PRE>
1546<DT><A NAME="gdImageStringUp">
1547void gdImageStringUp(gdImagePtr im, gdFontPtr font, int x, int y,
1548char *s, int color)</A>
1549<STRONG>(FUNCTION)</STRONG>
1550<DD>
1551gdImageStringUp is used to draw multiple characters on the image,
1552rotated 90 degrees.
1553(To draw single characters, use <A HREF="#gdImageCharUp">
1554gdImageCharUp</A>.) The second argument is a
1555pointer to a font definition structure; five fonts are
1556provided with gd, gdFontTiny, gdFontSmall, gdFontMediumBold,
1557gdFontLarge, and gdFontGiant. You must
1558include the files "gdfontt.h", "gdfonts.h", "gdfontmb.h",
1559"gdfontl.h" and "gdfontg.h" respectively
1560and (if you are not using a library-based approach) link with the
1561corresponding .c files to use the provided fonts.The null-terminated C string specified
1562by the fifth argument is drawn from bottom to top (rotated
156390 degrees) in the specified color. (See
1564<A HREF="#gdImageString">gdImageString</A> for a way
1565of drawing horizontal text.) Pixels not
1566set by a particular character retain their previous color.
1567<PRE>
1568#include "gd.h"
1569#include "gdfontl.h"
1570#include &lt;string.h&gt;
1571... inside a function ...
1572<A HREF="#gdImagePtr">gdImagePtr</A> im;
1573int black;
1574int white;
1575/* String to draw. */
1576char *s = "Hello.";
1577im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
1578/* Background color (first allocated) */
1579black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
1580/* Allocate the color white (red, green and blue all maximum). */
1581white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
1582/* Draw a centered string going upwards. Axes are reversed,
1583 and Y axis is decreasing as the string is drawn. */
1584gdImageStringUp(im, gdFontLarge,
1585 im->w / 2 - gdFontLarge->h / 2,
1586 im->h / 2 + (strlen(s) * gdFontLarge->w / 2),
1587 s, white);
1588/* ... Do something with the image, such as saving it to a file... */
1589/* Destroy it */
1590<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
1591</PRE>
1592</DL>
1593<H3><A NAME="colors">Color-handling functions</A></H3>
1594<DL>
1595<DT><A NAME="gdImageColorAllocate">
1596int gdImageColorAllocate(gdImagePtr im, int r, int g, int b)</A>
1597<STRONG>(FUNCTION)</STRONG>
1598<DD>
1599gdImageColorAllocate finds the first available color index in
1600the image specified, sets its RGB values to those requested
1601(255 is the maximum for each),
1602and returns the index of the new color table entry. When
1603creating a new image, the first time you invoke this function,
1604you are setting the background color for that image.
1605<P>
1606In the event that all <A HREF="#gdMaxColors">gdMaxColors</A> colors
1607(256) have already been allocated, gdImageColorAllocate will
1608return -1 to indicate failure. (This is not uncommon when
1609working with existing GIF files that already use 256 colors.)
1610Note that gdImageColorAllocate
1611does not check for existing colors that match your request;
1612see <A HREF="#gdImageColorExact">gdImageColorExact</A>
1613and <A HREF="#gdImageColorClosest">gdImageColorClosest</A>
1614for ways to locate existing colors that approximate the
1615color desired in situations where a new color is not available.
1616<PRE>
1617... inside a function ...
1618<A HREF="#gdImagePtr">gdImagePtr</A> im;
1619int black;
1620int red;
1621im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
1622/* Background color (first allocated) */
1623black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
1624/* Allocate the color red. */
1625red = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 0, 0);
1626/* Draw a dashed line from the upper left corner to the lower right corner. */
1627gdImageDashedLine(im, 0, 0, 99, 99, red);
1628/* ... Do something with the image, such as saving it to a file... */
1629/* Destroy it */
1630<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
1631</PRE>
1632<DT><A NAME="gdImageColorClosest">
1633int gdImageColorClosest(gdImagePtr im, int r, int g, int b)</A>
1634<STRONG>(FUNCTION)</STRONG>
1635<DD>
1636gdImageColorClosest searches the colors which have been
1637defined thus far in the image specified and returns the
1638index of the color with RGB values closest to those of the
1639request. (Closeness is determined by Euclidian distance,
1640which is used to determine the distance in three-dimensional color
1641space between colors.)
1642<P>
1643If no colors have yet been allocated in the image,
1644gdImageColorClosest returns -1.
1645<P>
1646This function is most useful as a backup method for choosing
1647a drawing color when an image already contains
1648<A HREF="#gdMaxColors">gdMaxColors</A> (256) colors and
1649no more can be allocated. (This is not uncommon when
1650working with existing GIF files that already use many colors.)
1651See <A HREF="#gdImageColorExact">gdImageColorExact</A>
1652for a method of locating exact matches only.
1653<PRE>
1654... inside a function ...
1655<A HREF="#gdImagePtr">gdImagePtr</A> im;
1656FILE *in;
1657int red;
1658/* Let's suppose that photo.gif is a scanned photograph with
1659 many colors. */
1660in = fopen("photo.gif", "rb");
1661im = <A HREF="#gdImageCreateFromGif">gdImageCreateFromGif</A>(in);
1662fclose(in);
1663/* Try to allocate red directly */
1664red = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 0, 0);
1665/* If we fail to allocate red... */
1666if (red == (-1)) {
1667 /* Find the <em>closest</em> color instead. */
1668 red = gdImageColorClosest(im, 255, 0, 0);
1669}
1670/* Draw a dashed line from the upper left corner to the lower right corner */
1671gdImageDashedLine(im, 0, 0, 99, 99, red);
1672/* ... Do something with the image, such as saving it to a file... */
1673/* Destroy it */
1674<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
1675</PRE>
1676<DT><A NAME="gdImageColorExact">
1677int gdImageColorExact(gdImagePtr im, int r, int g, int b)</A>
1678<STRONG>(FUNCTION)</STRONG>
1679<DD>
1680gdImageColorExact searches the colors which have been
1681defined thus far in the image specified and returns the
1682index of the first color with RGB values which exactly
1683match those of the request. If no allocated color matches the
1684request precisely, gdImageColorExact returns -1.
1685See <A HREF="#gdImageColorClosest">gdImageColorClosest</A>
1686for a way to find the color closest to the color requested.
1687<PRE>
1688... inside a function ...
1689<A HREF="#gdImagePtr">gdImagePtr</A> im;
1690int red;
1691in = fopen("photo.gif", "rb");
1692im = <A HREF="#gdImageCreateFromGif">gdImageCreateFromGif</A>(in);
1693fclose(in);
1694/* The image may already contain red; if it does, we'll save a slot
1695 in the color table by using that color. */
1696/* Try to allocate red directly */
1697red = gdImageColorExact(im, 255, 0, 0);
1698/* If red isn't already present... */
1699if (red == (-1)) {
1700 /* Second best: try to allocate it directly. */
1701 red = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 0, 0);
1702 /* Out of colors, so find the <em>closest</em> color instead. */
1703 red = gdImageColorClosest(im, 255, 0, 0);
1704}
1705/* Draw a dashed line from the upper left corner to the lower right corner */
1706gdImageDashedLine(im, 0, 0, 99, 99, red);
1707/* ... Do something with the image, such as saving it to a file... */
1708/* Destroy it */
1709<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
1710</PRE>
1711<DT><A NAME="gdImageColorsTotal">
1712int gdImageColorsTotal(gdImagePtr im)</A>
1713<STRONG>(MACRO)</STRONG>
1714<DD>
1715gdImageColorsTotal is a macro which returns the number of
1716colors currently allocated in the image. Use this macro
1717to obtain this information; do not access the structure
1718directly.
1719<DT><A NAME="gdImageColorRed">
1720int gdImageColorRed(gdImagePtr im, int c)</A>
1721<STRONG>(MACRO)</STRONG>
1722<DD>
1723gdImageColorRed is a macro which returns the red portion
1724of the specified color in the image. Use this macro
1725to obtain this information; do not access the structure
1726directly.
1727<DT><A NAME="gdImageColorGreen">
1728int gdImageColorGreen(gdImagePtr im, int c)</A>
1729<STRONG>(MACRO)</STRONG>
1730<DD>
1731gdImageColorGreen is a macro which returns the green portion
1732of the specified color in the image. Use this macro
1733to obtain this information; do not access the structure
1734directly.
1735<DT><A NAME="gdImageColorBlue">
1736int gdImageColorBlue(gdImagePtr im, int c)</A>
1737<STRONG>(MACRO)</STRONG>
1738<DD>
1739gdImageColorBlue is a macro which returns the green portion
1740of the specified color in the image. Use this macro
1741to obtain this information; do not access the structure
1742directly.
1743<DT><A NAME="gdImageGetInterlaced">
1744int gdImageGetInterlaced(gdImagePtr im)</A>
1745<STRONG>(MACRO)</STRONG>
1746<DD>
1747gdImageGetInterlaced is a macro which returns true (1)
1748if the image is interlaced, false (0) if not.
1749Use this macro to obtain this information; do not
1750access the structure directly.
1751See <A NAME="gdImageInterlace">gdImageInterlace</A> for
1752a means of interlacing images.
1753<DT><A NAME="gdImageGetTransparent">
1754int gdImageGetTransparent(gdImagePtr im)</A>
1755<STRONG>(MACRO)</STRONG>
1756<DD>
1757gdImageGetTransparent is a macro which returns the
1758current transparent color index in the image.
1759If there is no transparent color, gdImageGetTransparent
1760returns -1. Use this macro to obtain this information; do not
1761access the structure directly.
1762<DT><A NAME="gdImageColorDeallocate">
1763void gdImageColorDeallocate(gdImagePtr im, int color)</A>
1764<STRONG>(FUNCTION)</STRONG>
1765<DD>
1766gdImageColorDeallocate marks the specified color as being
1767available for reuse. It does not attempt to determine whether
1768the color index is still in use in the image. After a call
1769to this function, the next call to
1770<A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>
1771for the same image will set new RGB values for that
1772color index, changing the color of any pixels which
1773have that index as a result. If multiple calls to
1774gdImageColorDeallocate are made consecutively, the lowest-numbered
1775index among them will be reused by the next
1776<A HREF="#gdImageColorAllocate"> gdImageColorAllocate</A> call.
1777<PRE>
1778... inside a function ...
1779<A HREF="#gdImagePtr">gdImagePtr</A> im;
1780int red, blue;
1781in = fopen("photo.gif", "rb");
1782im = <A HREF="#gdImageCreateFromGif">gdImageCreateFromGif</A>(in);
1783fclose(in);
1784/* Look for red in the color table. */
1785red = gdImageColorExact(im, 255, 0, 0);
1786/* If red is present... */
1787if (red != (-1)) {
1788 /* Deallocate it. */
1789 gdImageColorDeallocate(im, red);
1790 /* Allocate blue, reusing slot in table.
1791 Existing red pixels will change color. */
1792 blue = gdImageColorAllocate(im, 0, 0, 255);
1793}
1794/* ... Do something with the image, such as saving it to a file... */
1795/* Destroy it */
1796<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
1797</PRE>
1798<DT><A NAME="gdImageColorTransparent">
1799void gdImageColorTransparent(gdImagePtr im, int color)</A>
1800<STRONG>(FUNCTION)</STRONG>
1801<DD>
1802gdImageColorTransparent sets the transparent color index
1803for the specified image to the specified index. To indicate
1804that there should be <em>no</em> transparent color, invoke
1805gdImageColorTransparent with a color index of -1.
1806<P>
1807The color index used should be an index
1808allocated by <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>,
1809whether explicitly invoked by your code or implicitly
1810invoked by loading an image.
1811In order to ensure that your image has a reasonable appearance
1812when viewed by users who do not have transparent background
1813capabilities, be sure to give reasonable RGB values to the
1814color you allocate for use as a transparent color,
1815<em>even though it will be transparent on systems
1816that support transparency</em>.
1817<PRE>
1818... inside a function ...
1819<A HREF="#gdImagePtr">gdImagePtr</A> im;
1820int black;
1821FILE *in, *out;
1822in = fopen("photo.gif", "rb");
1823im = <A HREF="#gdImageCreateFromGif">gdImageCreateFromGif</A>(in);
1824fclose(in);
1825/* Look for black in the color table and make it transparent. */
1826black = <A HREF="#gdImageColorExact">gdImageColorExact</A>(im, 0, 0, 0);
1827/* If black is present... */
1828if (black != (-1)) {
1829 /* Make it transparent */
1830 gdImageColorTransparent(im, black);
1831}
1832/* Save the newly-transparent image back to the file */
1833out = fopen("photo.gif", "wb");
1834<A HREF="#gdImageGif">gdImageGif</A>(im, out);
1835fclose(out);
1836/* Destroy it */
1837<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
1838</PRE>
1839</DL>
1840<H3><A NAME="copying">Copying and resizing functions</A></H3>
1841<DL>
1842<DT><A NAME="gdImageCopy">void gdImageCopy(gdImagePtr dst, gdImagePtr src, int dstX, int dstY, int srcX, int srcY, int w, int h)
1843<STRONG> (FUNCTION)</STRONG>
1844<DD>
1845gdImageCopy is used to copy a rectangular portion of one image to
1846another image. (For a way of stretching or shrinking the image
1847in the process, see <A HREF="#gdImageCopyResized">
1848gdImageCopyResized</A>.)
1849<P>
1850The <code>dst</code> argument is the destination image to which the
1851region will be copied. The <code>src</code> argument is the source
1852image from which the region is copied. The <code>dstX</code>
1853and <code>dstY</code> arguments specify the point in the destination
1854image to which the region will be copied. The <code>srcX</code>
1855and <code>srcY</code> arguments specify the upper left corner
1856of the region in the source image. The <code>w</code>
1857and <code>h</code> arguments specify the width and height
1858of the region.
1859<P>
1860When you copy a region from one location in an image to another
1861location in the same image, gdImageCopy will perform as expected
1862unless the regions overlap, in which case the result is
1863unpredictable.
1864<P>
1865<strong>Important note on copying between images:</strong> since
1866different images do
1867not necessarily have the same color tables, pixels are not simply set to the
1868same color index values to copy them. gdImageCopy will attempt
1869to find an identical RGB value in the destination image for
1870each pixel in the copied portion of the source image by
1871invoking <A HREF="#gdImageColorExact">gdImageColorExact</A>. If
1872such a value is not found, gdImageCopy will attempt to
1873allocate colors as needed using <A HREF="#gdImageColorAllocate">
1874gdImageColorAllocate</A>. If both of these methods fail,
1875gdImageCopy will invoke <A HREF="#gdImageColorClosest">
1876gdImageColorClosest</A> to find the color in the destination
1877image which most closely approximates the color of the
1878pixel being copied.
1879<PRE>
1880... Inside a function ...
1881<A HREF="#gdImagePtr">gdImagePtr</A> im_in;
1882<A HREF="#gdImagePtr">gdImagePtr</A> im_out;
1883int x, y;
1884FILE *in;
1885FILE *out;
1886/* Load a small gif to tile the larger one with */
1887in = fopen("small.gif", "rb");
1888im_in = <A HREF="#gdImageCreateFromGif">gdImageCreateFromGif</A>(in);
1889fclose(in);
1890/* Make the output image four times as large on both axes */
1891im_out = <A HREF="#gdImageCreate">gdImageCreate</A>(im_in->sx * 4, im_in->sy * 4);
1892/* Now tile the larger image using the smaller one */
1893for (y = 0; (y < 4); y++) {
1894 for (x = 0; (x < 4); x++) {
1895 gdImageCopy(im_out, im_in,
1896 x * im_in->sx, y * im_in->sy,
1897 0, 0,
1898 im_in->sx, im_in->sy);
1899 }
1900}
1901out = fopen("tiled.gif", "wb");
1902<A HREF="#gdImageGif">gdImageGif</A>(im_out, out);
1903fclose(out);
1904<A HREF="#gdImageDestroy">gdImageDestroy</A>(im_in);
1905<A HREF="#gdImageDestroy">gdImageDestroy</A>(im_out);
1906</PRE>
1907<DT><A NAME="gdImageCopyResized">void gdImageCopyResized(gdImagePtr dst, gdImagePtr src, int dstX, int dstY, int srcX, int srcY, int destW, int destH, int srcW, int srcH)
1908<STRONG> (FUNCTION)</STRONG>
1909<DD>
1910gdImageCopyResized is used to copy a rectangular portion of one image to
1911another image. The X and Y dimensions of the original region and the
1912destination region can vary, resulting in stretching or shrinking of
1913the region as appropriate. (For a simpler version of this function
1914which does not deal with resizing, see <A HREF="#gdImageCopy">
1915gdImageCopy</A>.)
1916<P>
1917The <code>dst</code> argument is the destination image to which the
1918region will be copied. The <code>src</code> argument is the source
1919image from which the region is copied. The <code>dstX</code>
1920and <code>dstY</code> arguments specify the point in the destination
1921image to which the region will be copied. The <code>srcX</code>
1922and <code>srcY</code> arguments specify the upper left corner
1923of the region in the source image. The <code>dstW</code>
1924and <code>dstH</code> arguments specify the width and height
1925of the destination region. The <code>srcW</code>
1926and <code>srcH</code> arguments specify the width and height
1927of the source region and can differ from the destination size,
1928allowing a region to be scaled during the copying process.
1929<P>
1930When you copy a region from one location in an image to another
1931location in the same image, gdImageCopy will perform as expected
1932unless the regions overlap, in which case the result is
1933unpredictable. If this presents a problem, create a scratch image
1934in which to keep intermediate results.
1935<P>
1936<strong>Important note on copying between images:</strong> since images
1937do not necessarily have the same color tables, pixels are not simply set
1938to the same color index values to copy them. gdImageCopy will attempt
1939to find an identical RGB value in the destination image for
1940each pixel in the copied portion of the source image by
1941invoking <A HREF="#gdImageColorExact">gdImageColorExact</A>. If
1942such a value is not found, gdImageCopy will attempt to
1943allocate colors as needed using <A HREF="#gdImageColorAllocate">
1944gdImageColorAllocate</A>. If both of these methods fail,
1945gdImageCopy will invoke <A HREF="#gdImageColorClosest">
1946gdImageColorClosest</A> to find the color in the destination
1947image which most closely approximates the color of the
1948pixel being copied.
1949<PRE>
1950... Inside a function ...
1951<A HREF="#gdImagePtr">gdImagePtr</A> im_in;
1952<A HREF="#gdImagePtr">gdImagePtr</A> im_out;
1953int x, y;
1954FILE *in;
1955FILE *out;
1956/* Load a small gif to expand in the larger one */
1957in = fopen("small.gif", "rb");
1958im_in = <A HREF="#gdImageCreateFromGif">gdImageCreateFromGif</A>(in);
1959fclose(in);
1960/* Make the output image four times as large on both axes */
1961im_out = <A HREF="#gdImageCreate">gdImageCreate</A>(im_in->sx * 4, im_in->sy * 4);
1962/* Now copy the smaller image, but four times larger */
1963gdImageCopyResized(im_out, im_in, 0, 0, 0, 0,
1964 im_out->sx, im_out->sy,
1965 im_in->sx, im_in->sy);
1966out = fopen("large.gif", "wb");
1967<A HREF="#gdImageGif">gdImageGif</A>(im_out, out);
1968fclose(out);
1969<A HREF="#gdImageDestroy">gdImageDestroy</A>(im_in);
1970<A HREF="#gdImageDestroy">gdImageDestroy</A>(im_out);
1971</PRE>
1972</DL>
1973<H3><A NAME="misc">Miscellaneous Functions</A></H3>
1974<DL>
1975<DT><A NAME="gdImageInterlace">gdImageInterlace(gdImagePtr im, int interlace)</A> <strong>(FUNCTION)</strong>
1976<DD>
1977gdImageInterlace is used to determine whether an image should be stored
1978in a linear fashion, in which lines will appear on the display from
1979first to last, or in an interlaced fashion, in which the image
1980will "fade in" over several passes. By default, images are not
1981interlaced.
1982<P>
1983A nonzero value for the interlace argument turns on interlace;
1984a zero value turns it off. Note that interlace has no effect
1985on other functions, and has no meaning unless you save the
1986image in GIF format; the gd and xbm formats do not support
1987interlace.
1988<P>
1989When a GIF is loaded with <A HREF="#gdImageCreateFromGif">gdImageCreateFromGif
1990</A>, interlace will be set according to the setting in the GIF file.
1991<P>
1992Note that many GIF viewers and web browsers do <em>not</em> support
1993interlace. However, the interlaced GIF should still display; it
1994will simply appear all at once, just as other images do.
1995<PRE>
1996gdImagePtr im;
1997FILE *out;
1998/* ... Create or load the image... */
1999
2000/* Now turn on interlace */
2001gdImageInterlace(im, 1);
2002/* And open an output file */
2003out = fopen("test.gif", "wb");
2004/* And save the image */
2005<A HREF="#gdImageGif">gdImageGif</A>(im, out);
2006fclose(out);
2007<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
2008</PRE>
2009</DL>
2010<H3><A NAME="constants">Constants</A></H3>
2011<DL>
2012<DT><A NAME="gdBrushed">gdBrushed</A> <strong>(CONSTANT)</strong>
2013<DD>
2014Used in place of a color when invoking a line-drawing
2015function such as <A HREF="#gdImageLine">gdImageLine</A>
2016or <A HREF="#gdImageRectangle">gdImageRectangle</A>.
2017When gdBrushed is used as the color, the brush
2018image set with <A HREF="#gdImageSetBrush">gdImageSetBrush</A>
2019is drawn in place of each pixel of the line (the brush is
2020usually larger than one pixel, creating the effect
2021of a wide paintbrush). See also
2022<A HREF="#gdStyledBrushed">gdStyledBrushed</A> for a way
2023to draw broken lines with a series of distinct copies of an image.
2024<DT><A NAME="gdMaxColors"><code>gdMaxColors</code><strong>(CONSTANT)</strong>
2025<DD>
2026The constant 256. This is the maximum number of colors in a GIF file
2027according to the GIF standard, and is also the maximum number of
2028colors in a gd image.
2029<DT><A NAME="gdStyled">gdStyled</A> <strong>(CONSTANT)</strong>
2030<DD>
2031Used in place of a color when invoking a line-drawing
2032function such as <A HREF="#gdImageLine">gdImageLine</A>
2033or <A HREF="#gdImageRectangle">gdImageRectangle</A>.
2034When gdStyled is used as the color, the colors of the pixels are
2035drawn successively from the style that has been
2036set with <A HREF="#gdImageSetStyle">gdImageSetStyle</A>.
2037If the color of a pixel is equal to
2038<A HREF="#gdTransparent">gdTransparent</A>, that pixel
2039is not altered. (This mechanism is completely unrelated
2040to the "transparent color" of the image itself; see
2041<A HREF="#gdImageColorTransparent">gdImageColorTransparent</A>
2042gdImageColorTransparent for that mechanism.) See also
2043<A NAME="#gdStyledBrushed"> gdStyledBrushed</A>.
2044<DT><A NAME="gdStyledBrushed">gdStyledBrushed</A> <strong>(CONSTANT)</strong>
2045<DD>
2046Used in place of a color when invoking a line-drawing
2047function such as <A HREF="#gdImageLine">gdImageLine</A>
2048or <A HREF="#gdImageRectangle">gdImageRectangle</A>.
2049When gdStyledBrushed is used as the color, the brush
2050image set with <A HREF="#gdImageSetBrush">gdImageSetBrush</A>
2051is drawn at each pixel of the line, providing that the
2052style set with <A HREF="#gdImageSetStyle">gdImageSetStyle</A>
2053contains a nonzero value (OR gdTransparent, which
2054does not equal zero but is supported for consistency)
2055for the current pixel. (Pixels are drawn successively from the style as the
2056line is drawn, returning to the beginning when the
2057available pixels in the style are exhausted.) Note that
2058this differs from the behavior of <A HREF="#gdStyled">gdStyled</A>,
2059in which the values in the style are used as actual
2060pixel colors, except for gdTransparent.
2061<DT><A NAME="gdDashSize">gdDashSize</A> <strong>(CONSTANT)</strong>
2062<DD>
2063The length of a dash in a dashed line. Defined to be 4 for
2064backwards compatibility with programs that use
2065<A NAME="gdImageDashedLine">gdImageDashedLine</A>. New
2066programs should use <A NAME="gdImageSetStyle">
2067gdImageSetStyle</A> and call the standard
2068<A NAME="gdImageLine">gdImageLine</A> function
2069with the special "color" <A NAME="gdStyled">
2070gdStyled</A> or <A NAME="gdStyledBrushed">gdStyledBrushed</A>.
2071<DT><A NAME="gdTiled">gdTiled</A> <strong>(CONSTANT)</strong>
2072<DD>
2073Used in place of a normal color in <A HREF="#gdImageFilledRectangle">
2074gdImageFilledRectangle</A>, <A HREF="#gdImageFilledPolygon">
2075gdImageFilledPolygon</A>,
2076<A HREF="#gdImageFill">gdImageFill</A>, and <A HREF="#gdImageFillToBorder">
2077gdImageFillToBorder</A>. gdTiled selects a pixel from the
2078tile image set with <A HREF="#gdImageSetTile">gdImageSetTile</A>
2079in such a way as to ensure that the filled area will be
2080tiled with copies of the tile image. See the discussions of
2081<A HREF="#gdImageFill">gdImageFill</A> and
2082<A HREF="#gdImageFillToBorder">gdImageFillToBorder</A> for special
2083restrictions regarding those functions.
2084<DT><A NAME="gdTransparent">gdTransparent</A> <strong>(CONSTANT)</strong>
2085<DD>
2086Used in place of a normal color in a style to be set with
2087<A HREF="#gdImageSetStyle">gdImageSetStyle</A>.
2088gdTransparent is <strong>not</strong> the transparent
2089color index of the image; for that functionality please
2090see <A HREF="gdImageColorTransparent">gdImageColorTransparent</A>.
2091</DL>
2092<A NAME="gdformat"><H3>About the additional .gd image file format</H3></A>
2093In addition to reading and writing the GIF format and reading the
2094X Bitmap format, gd has the capability to read and write its
2095own ".gd" format. This format is <em>not</em> intended for
2096general purpose use and should never be used to distribute
2097images. It is not a compressed format. Its purpose is solely to
2098allow very fast loading of images your program needs often in
2099order to build other images for output. If you are experiencing
2100performance problems when loading large, fixed GIF images your
2101program needs to produce its output images, you may wish
2102to examine the functions <A HREF="#gdImageCreateFromGd">
2103gdImageCreateFromGd</A> and <A HREF="#gdImageGd">gdImageGd</A>,
2104which read and write .gd format images.
2105<P>
2106The program "giftogd.c" is provided as a simple way of converting
2107.gif files to .gd format. I emphasize again that you will not
2108need to use this format unless you have a need for high-speed loading
2109of a few frequently-used images in your program.
2110<A NAME="informing"><H3>Please tell us you're using gd!</H3>
2111When you contact us and let us know you are using gd,
2112you help us justify the time spent in maintaining and improving
2113it. So please let us know. If the results are publicly
2114visible on the web, a URL is a wonderful thing to receive, but
2115if it's not a publicly visible project, a simple note is just
2116as welcome.
2117<A NAME="languages"><H3>Using gd with TCL</H3></A>
2118If you prefer TCL to C, you can use gd from your tcl program
2119thanks to the <A HREF="http://guraldi.hgp.med.umich.edu/gdtcl.html">
2120TCL gd extension</A> by Spencer W. Thomas, available at the link
2121above or by anonymous FTP to guraldi.hgp.med.umich.edu
2122in the directory pub/gdtcl.shar.
2123<A NAME="problems"><H3>If you have problems</H3></A>
2124If you have any difficulties with gd, feel free to contact
2125the author, <A HREF="http://sunsite.unc.edu/boutell/index.html">
2126Thomas Boutell</A>. Be sure to read this manual
2127carefully first.
2128<H3><A NAME="index">Alphabetical quick index</A></H3>
2129<A HREF="#gdBrushed">gdBrushed</A> |
2130<A HREF="#gdDashSize">gdDashSize</A> |
2131<A HREF="#gdFont">gdFont</A> |
2132<A HREF="#gdFontPtr">gdFontPtr</A> |
2133<A HREF="#gdImage">gdImage</A> |
2134<A HREF="#gdImageArc">gdImageArc</A> |
2135<A HREF="#gdImageBlue">gdImageBlue</A> |
2136<A HREF="#gdImageBoundsSafe">gdImageBoundsSafe</A> |
2137<A HREF="#gdImageChar">gdImageChar</A> |
2138<A HREF="#gdImageCharUp">gdImageCharUp</A> |
2139<A HREF="#gdImageColorAllocate">gdImageColorAllocate</A> |
2140<A HREF="#gdImageColorClosest">gdImageColorClosest</A> |
2141<A HREF="#gdImageColorDeallocate">gdImageColorDeallocate</A> |
2142<A HREF="#gdImageColorExact">gdImageColorExact</A> |
2143<A HREF="#gdImageColorTransparent">gdImageColorTransparent</A> |
2144<A HREF="#gdImageCopy">gdImageCopy</A> |
2145<A HREF="#gdImageCopyResized">gdImageCopyResized</A> |
2146<A HREF="#gdImageCreate">gdImageCreate</A> |
2147<A HREF="#gdImageCreateFromGd">gdImageCreateFromGd</A> |
2148<A HREF="#gdImageCreateFromGif">gdImageCreateFromGif</A> |
2149<A HREF="#gdImageCreateFromXbm">gdImageCreateFromXbm</A> |
2150<A HREF="#gdImageDashedLine">gdImageDashedLine</A> |
2151<A HREF="#gdImageDestroy">gdImageDestroy</A> |
2152<A HREF="#gdImageFill">gdImageFill</A> |
2153<A HREF="#gdImageFillToBorder">gdImageFillToBorder</A> |
2154<A HREF="#gdImageFilledRectangle">gdImageFilledRectangle</A> |
2155<A HREF="#gdImageGd">gdImageGd</A> |
2156<A HREF="#gdImageGetInterlaced">gdImageGetInterlaced</A> |
2157<A HREF="#gdImageGetPixel">gdImageGetPixel</A> |
2158<A HREF="#gdImageGetTransparent">gdImageGetTransparent</A> |
2159<A HREF="#gdImageGif">gdImageGif</A> |
2160<A HREF="#gdImageGreen">gdImageGreen</A> |
2161<A HREF="#gdImageInterlace">gdImageInterlace</A> |
2162<A HREF="#gdImageLine">gdImageLine</A> |
2163<A HREF="#gdImageFilledPolygon">gdImageFilledPolygon</A> |
2164<A HREF="#gdImagePolygon">gdImagePolygon</A> |
2165<A HREF="#gdImagePtr">gdImagePtr</A> |
2166<A HREF="#gdImageRectangle">gdImageRectangle</A> |
2167<A HREF="#gdImageRed">gdImageRed</A> |
2168<A HREF="#gdImageSetBrush">gdImageSetBrush</A> |
2169<A HREF="#gdImageSetPixel">gdImageSetPixel</A> |
2170<A HREF="#gdImageSetStyle">gdImageSetStyle</A> |
2171<A HREF="#gdImageSetTile">gdImageSetTile</A> |
2172<A HREF="#gdImageString">gdImageString</A> |
2173<A HREF="#gdImageStringUp">gdImageStringUp</A> |
2174<A HREF="#gdMaxColors">gdMaxColors</A> |
2175<A HREF="#gdPoint">gdPoint</A> |
2176<A HREF="#gdStyled">gdStyled</A> |
2177<A HREF="#gdStyledBrushed">gdStyledBrushed</A> |
2178<A HREF="#gdTiled">gdTiled</A> |
2179<A HREF="#gdTransparent">gdTransparent</A>
2180<P>
2181<em><A HREF="http://sunsite.unc.edu/boutell/index.html">
2182Thomas Boutell, boutell@netcom.com</A></em>
2183</BODY>
2184</HTML>
Note: See TracBrowser for help on using the repository browser.