libraries/gd1.3/index.html

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