camir-aes2014: toolboxes/graph_visualisation/share/graphviz/doc/html/gd.html annotate

annotate toolboxes/graph_visualisation/share/graphviz/doc/html/gd.html @ 0:e9a9cd732c1e tip

first hg version after svn

author	wolffd
date	Tue, 10 Feb 2015 15:05:51 +0000
parents
children

rev	line source
wolffd@0	1 <!-- REMEMBER TO EDIT index.html.source -->
wolffd@0	2 <head>
wolffd@0	3 <TITLE>gd 2.0.34</TITLE>
wolffd@0	4 </head>
wolffd@0	5 <body bgcolor="#FFFFFF">
wolffd@0	6 <!-- BANNER HERE -->
wolffd@0	7 <H2>gd 2.0.33</H2>
wolffd@0	8 <H3>A graphics library for fast image creation</H3>
wolffd@0	9 <H3>Follow this link to the
wolffd@0	10 <A HREF="http://libgd.org">latest version
wolffd@0	11 of this document</A>.</H3>
wolffd@0	12 <blockquote>
wolffd@0	13 <strong>UPGRADING UNIX USERS: READ THIS FIRST!</strong>
wolffd@0	14 Modern versions of gd install by default to /usr/local/lib and
wolffd@0	15 /usr/local/include. If you already have an older version of gd
wolffd@0	16 in /usr/lib and /usr/include, you may wish to use:
wolffd@0	17 <pre>
wolffd@0	18 ./configure --prefix=/usr</pre>
wolffd@0	19 To ensure that your
wolffd@0	20 new installation overwrites the old.
wolffd@0	21 <p>
wolffd@0	22 <strong>GIF support has been restored in gd 2.0.28 and above.</strong>
wolffd@0	23 The well-known patents on LZW compression held by Unisys
wolffd@0	24 have expired in all countries. British Telecom and IBM may hold related
wolffd@0	25 patents but have never chosen to require royalties for GIF applications,
wolffd@0	26 to the best of my knowledge. I am not a lawyer and cannot give
wolffd@0	27 legal advice regarding this issue. PNG remains a superior format especially
wolffd@0	28 if lossless truecolor images are needed.
wolffd@0	29 <p>
wolffd@0	30 When building from soruce, gd 2.0.33 <strong>requires</strong> that the
wolffd@0	31 following libraries also be installed, in order to produce the related
wolffd@0	32 image formats. The win32 binary release (bgd) already contains the
wolffd@0	33 appropriate libraries.
wolffd@0	34 You may skip libraries associated with formats you do not use:
wolffd@0	35 <p>
wolffd@0	36 libpng (see the <a href="http://www.libpng.org/pub/png/">libpng home page</a>), if you want PNG
wolffd@0	37 <p>
wolffd@0	38 zlib (see the <a href="http://www.info-zip.org/pub/infozip/zlib/">info-zip home page</a>), if you want PNG
wolffd@0	39 <p>
wolffd@0	40 jpeg-6b or later, if desired (see the <a href="http://www.ijg.org/">Independent JPEG Group home page</a>), if you want JPEG
wolffd@0	41 <p>
wolffd@0	42 If you want to use the TrueType font support, you must also
wolffd@0	43 install the <strong>FreeType 2.x library</strong>, including
wolffd@0	44 the header files. See the <a href="http://www.freetype.org/">Freetype
wolffd@0	45 Home Page</a>, or <a href="http://freetype.sourceforge.net/">SourceForge</a>.
wolffd@0	46 No, I cannot explain why that site is down on a particular day, and no, I
wolffd@0	47 can't send you a copy.
wolffd@0	48 <p>
wolffd@0	49 If you want to use the Xpm color bitmap loading support, you must also
wolffd@0	50 have the X Window System and the Xpm library installed (Xpm is often
wolffd@0	51 included in modern X distributions). Most of the time you won't
wolffd@0	52 need Xpm.
wolffd@0	53 <p>
wolffd@0	54 Please read the documentation and install the required libraries.
wolffd@0	55 Do not send email asking why <code>png.h</code> is not found.
wolffd@0	56 Do not send email asking why <code>libgd.so</code> is not found, either.
wolffd@0	57 See the <a href="#required">requirements section</a> for more
wolffd@0	58 information. Thank you!
wolffd@0	59 </blockquote>
wolffd@0	60 <H3>Table of Contents</H3>
wolffd@0	61 <UL>
wolffd@0	62 <LI><A HREF="#notice">Credits and license terms</A>
wolffd@0	63 <LI><A HREF="#whatsnew2.0.34">What's new in version "XYZ" of GD?</A>
wolffd@0	64 <LI><A HREF="#whatis">What is gd?</A>
wolffd@0	65 <LI><A HREF="#gdother">What if I want to use another programming language?</A>
wolffd@0	66 <LI><A HREF="#required">What else do I need to use gd?</A>
wolffd@0	67 <LI><A HREF="#getgd">How do I get gd?</A>
wolffd@0	68 <LI><A HREF="#buildgd">How do I build gd?</A>
wolffd@0	69 <LI><A HREF="#basics">gd basics: using gd in your program</A>
wolffd@0	70 <LI><A HREF="#webpng">webpng: a useful example</A>
wolffd@0	71 <LI><A HREF="#reference">Function and type reference by category</A>
wolffd@0	72 <LI><A HREF="#gdformat">About the additional .gd image file format</A>
wolffd@0	73 <LI><A HREF="#informing"><strong>Please</strong>
wolffd@0	74 tell us you're using gd!</A>
wolffd@0	75 <LI><A HREF="#support">How do I get support?</A>
wolffd@0	76 <LI><A HREF="#issues">How do I report issues, bugs or features request?</A>
wolffd@0	77 <LI><A HREF="#index">Alphabetical quick index</A>
wolffd@0	78 </UL>
wolffd@0	79 <P><A HREF="http://www.libgd.org/">
wolffd@0	80 Up to the <EM>LibGD Homepage</EM></A>
wolffd@0	81 <A NAME="notice"><H3>Credits and license terms</A></H3>
wolffd@0	82 <P>
wolffd@0	83 In order to resolve any possible confusion regarding the authorship
wolffd@0	84 of gd, the following copyright statement covers all of the authors
wolffd@0	85 who have required such a statement. <strong>If you are aware of any oversights
wolffd@0	86 in this copyright notice, please contact <A HREF="http://libgd.org/Contact">Pierre-A. Joye</A> who will be
wolffd@0	87 pleased to correct them.</strong>
wolffd@0	88 <pre>
wolffd@0	89 COPYRIGHT STATEMENT FOLLOWS THIS LINE
wolffd@0	90 </pre>
wolffd@0	91 <blockquote>
wolffd@0	92
wolffd@0	93 Portions copyright 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004 by Cold Spring
wolffd@0	94 Harbor Laboratory. Funded under Grant P41-RR02188 by the National
wolffd@0	95 Institutes of Health.
wolffd@0	96 <P>
wolffd@0	97 Portions copyright 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004 by Boutell.Com, Inc.
wolffd@0	98 <p>
wolffd@0	99 Portions relating to GD2 format copyright 1999, 2000, 2001, 2002, 2003, 2004 Philip Warner.
wolffd@0	100 <p>
wolffd@0	101 Portions relating to PNG copyright 1999, 2000, 2001, 2002, 2003, 2004 Greg Roelofs.
wolffd@0	102 <p>
wolffd@0	103 Portions relating to gdttf.c copyright 1999, 2000, 2001, 2002, 2003, 2004 John Ellson (ellson@graphviz.org).
wolffd@0	104 <p>
wolffd@0	105 Portions relating to gdft.c copyright 2001, 2002, 2003, 2004 John Ellson (ellson@graphviz.org).
wolffd@0	106 <p>
wolffd@0	107 Portions copyright 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Pierre-Alain Joye (pierre@libgd.org).
wolffd@0	108
wolffd@0	109 <p>
wolffd@0	110 Portions relating to JPEG and to color quantization copyright 2000, 2001, 2002, 2003, 2004, Doug Becker and copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004 Thomas G. Lane. This software is based
wolffd@0	111 in part on the work of the Independent JPEG Group. See the file
wolffd@0	112 README-JPEG.TXT for more information.
wolffd@0	113 <p>
wolffd@0	114 Portions relating to GIF compression copyright 1989 by Jef
wolffd@0	115 Poskanzer and David Rowley, with modifications for thread safety
wolffd@0	116 by Thomas Boutell.
wolffd@0	117 <p>
wolffd@0	118 Portions relating to GIF decompression copyright 1990, 1991, 1993
wolffd@0	119 by David Koblas, with modifications for thread safety by
wolffd@0	120 Thomas Boutell.
wolffd@0	121 <p>
wolffd@0	122 Portions relating to WBMP copyright 2000, 2001, 2002, 2003, 2004 Maurice Szmurlo and Johan Van
wolffd@0	123 den Brande.
wolffd@0	124 <p>
wolffd@0	125 Portions relating to GIF animations copyright 2004 Jaakko Hyvätti (jaakko.hyvatti@iki.fi)
wolffd@0	126 <p>
wolffd@0	127 <strong>Permission has been granted to copy, distribute and modify gd in any
wolffd@0	128 context without fee, including a commercial application, provided that this notice
wolffd@0	129 is present in user-accessible supporting documentation.</strong>
wolffd@0	130 <p>
wolffd@0	131 This does not affect your ownership of the derived work itself, and the intent
wolffd@0	132 is to assure proper credit for the authors of gd, not to interfere
wolffd@0	133 with your productive use of gd. If you have questions, ask.
wolffd@0	134 "Derived works" includes all programs that utilize the library.
wolffd@0	135 Credit must be given in user-accessible documentation.
wolffd@0	136 <p>
wolffd@0	137 <strong>This software is provided "AS IS."</strong>
wolffd@0	138 The copyright holders disclaim all warranties, either express or implied,
wolffd@0	139 including but not limited to implied warranties of merchantability and
wolffd@0	140 fitness for a particular purpose, with respect to this code and accompanying
wolffd@0	141 documentation.
wolffd@0	142 <p>
wolffd@0	143 Although their code does not appear in the current release, the authors
wolffd@0	144 also wish to thank Hutchison Avenue Software Corporation for their
wolffd@0	145 prior contributions.
wolffd@0	146 </blockquote>
wolffd@0	147 <pre>
wolffd@0	148 END OF COPYRIGHT STATEMENT
wolffd@0	149 </pre>
wolffd@0	150 <A NAME="whatis"><H3>What is gd?</H3></A>
wolffd@0	151 <P>
wolffd@0	152 gd is a graphics library. It allows your code to quickly
wolffd@0	153 draw images complete with lines, arcs, text, multiple
wolffd@0	154 colors, cut and paste from other images, and flood fills, and
wolffd@0	155 write out the result as a PNG or JPEG file. This is particularly
wolffd@0	156 useful in World Wide Web applications, where PNG and JPEG are two
wolffd@0	157 of the formats accepted for inline images by most browsers.
wolffd@0	158 <P>
wolffd@0	159 gd is not a paint program.
wolffd@0	160 If you are looking for a paint program, you are looking in
wolffd@0	161 the wrong place. If you are not a programmer, you are looking
wolffd@0	162 in the wrong place, unless you are installing a required
wolffd@0	163 library in order to run an application.
wolffd@0	164 <P>
wolffd@0	165 gd does not provide for every possible desirable graphics
wolffd@0	166 operation. It is not necessary or desirable for gd to become
wolffd@0	167 a kitchen-sink graphics package, but version 2.0 does include
wolffd@0	168 most frequently requested features, including both truecolor and
wolffd@0	169 palette images, resampling (smooth resizing of truecolor images)
wolffd@0	170 and so forth.
wolffd@0	171 <P>
wolffd@0	172 <A NAME="gdother"><H3>What if I want to use another programming
wolffd@0	173 language?</h3></A>
wolffd@0	174 Not all of these tools are necessarily up to date and fully compatible
wolffd@0	175 with 2.0.33.
wolffd@0	176 <h4>PHP</h4>
wolffd@0	177 A variant of gd 2.x is included in PHP 4.3.0. It is also possible
wolffd@0	178 to patch PHP 4.2.3 for use with gd 2.0.33; see the
wolffd@0	179 <a href="http://www.libgd.org/">gd home page</a> for a link to
wolffd@0	180 that information. It would be a Good Idea to merge all of the things
wolffd@0	181 that are better in mainstream gd and all of the things that are
wolffd@0	182 better in PHP gd at some point in the near future.
wolffd@0	183 <h4>Perl</h4>
wolffd@0	184 gd can also be used from Perl, courtesy of
wolffd@0	185 Lincoln Stein's
wolffd@0	186 <a href="http://stein.cshl.org/WWW/software/GD/">
wolffd@0	187 GD.pm</a> library, which uses gd as the basis for a set of
wolffd@0	188 Perl 5.x classes. Highly recommended.
wolffd@0	189 <h4>OCaml</h4>
wolffd@0	190 gd can be used from OCaml, thanks to
wolffd@0	191 <a href="http://gd4o.sourceforge.net/">Matt Gushee's GD4O project</a>.
wolffd@0	192 <h4>Tcl</h4>
wolffd@0	193 gd can be used from Tcl with John Ellson's
wolffd@0	194 <a href=http://www.graphviz.org/pub/>Gdtclft</a>
wolffd@0	195 dynamically loaded extension package.
wolffd@0	196 <h4>Pascal</h4>
wolffd@0	197 Pascal enthusiasts should look into the
wolffd@0	198 <a href="http://www.freepascal.org/">freepascal</a> project, a
wolffd@0	199 free Pascal compiler that includes gd support.
wolffd@0	200 <h4>REXX</h4>
wolffd@0	201 A
wolffd@0	202 <a href="http://www.lightlink.com/hessling/RexxGd/index.html">gd interface
wolffd@0	203 for the REXX language</a> is available.
wolffd@0	204 <h4>Any Language</h4>
wolffd@0	205 The "fly" interpreter performs gd operations specified in a text file.
wolffd@0	206 You can output the desired commands to a simple
wolffd@0	207 text file from whatever scripting language you prefer to use, then
wolffd@0	208 invoke the interpreter.
wolffd@0	209 <p>
wolffd@0	210 <ul>
wolffd@0	211 <li><a href="http://martin.gleeson.com/fly/">fly</a>, by Martin Gleeson
wolffd@0	212 </ul>
wolffd@0	213 <p>
wolffd@0	214 <A NAME="whatsnew2.0.34"><h3>What's new in version 2.0.34?</h3></a>
wolffd@0	215 <p>
wolffd@0	216 From 2.0.34 and later, please check the ISSUES and ChangeLog as well as
wolffd@0	217 the releases announcements.
wolffd@0	218 <p>
wolffd@0	219 <A NAME="whatsnew2.0.33"><h3>What's new in version 2.0.33?</h3></a>
wolffd@0	220 <p>
wolffd@0	221 Version 2.0.33 restores compatibility with older releases
wolffd@0	222 of Freetype 2.x in addition to the latest release. Thanks to
wolffd@0	223 John Ellson and the graphviz project.
wolffd@0	224 <p>
wolffd@0	225 <A NAME="whatsnew2.0.32"><h3>What's new in version 2.0.32?</h3></a>
wolffd@0	226 <p>
wolffd@0	227 Version 2.0.32 restores correct detection of Unicode character sets
wolffd@0	228 for freetype fonts, which repairs a bug that prevented umlauts from
wolffd@0	229 displaying properly. Thanks to John Ellson and the graphviz project.
wolffd@0	230 Also, version 2.0.32 builds all test programs
wolffd@0	231 smoothly in the absence of libpng.
wolffd@0	232 <p>
wolffd@0	233 <A NAME="whatsnew2.0.31"><h3>What's new in version 2.0.31?</h3></a>
wolffd@0	234 <p>
wolffd@0	235 A minor type naming conflict prevented bgd.dll from compiling, and it
wolffd@0	236 was left out of the distribution as a result. This has been corrected.
wolffd@0	237 <p>
wolffd@0	238 <A NAME="whatsnew2.0.30"><h3>What's new in version 2.0.30?</h3></a>
wolffd@0	239 <p>
wolffd@0	240 2.0.29 did not compile correctly when freetype was not available.
wolffd@0	241 This has been corrected. Thanks to Alessandro Ranellucci.
wolffd@0	242 <p>
wolffd@0	243 <A NAME="whatsnew2.0.29"><h3>What's new in version 2.0.29?</h3></a>
wolffd@0	244 <p>
wolffd@0	245 <ul>
wolffd@0	246 <li>A 32-bit multiplication overflow vulnerability reported on
wolffd@0	247 the Bugtraq mailing list has been corrected, along with a number
wolffd@0	248 of similar issues. These bugs come into play only when attempting
wolffd@0	249 to deal with images with <i>extremely large</i> dimensions.
wolffd@0	250 The relevant functions now fail gracefully when such extreme
wolffd@0	251 parameters are specified. The code in question is also
wolffd@0	252 correct for systems with larger bit depths. Thanks to Phil Knirsch,
wolffd@0	253 Alan Cox and infamous41md.
wolffd@0	254 Since exploits are theoretically possible, upgrading is recommended.
wolffd@0	255 <li>Support for the fontconfig library, when available.
wolffd@0	256 When fontconfig is available and gdFTUseFontConfig(1) has been invoked
wolffd@0	257 or the gdFTEX_FONTCONFIG flag has been set for a particular call, fontconfig
wolffd@0	258 patterns can be used to fetch the best available font.
wolffd@0	259 For instance, "arial:bold:italic" does the right thing (or as close as
wolffd@0	260 the available fonts permit). Also, standard
wolffd@0	261 PostScript font names can be mapped to an appropriate font by
wolffd@0	262 gdImageStringFTEx and relatives.
wolffd@0	263 When fontconfig is available <tt>gdlib-config --features</tt> will list
wolffd@0	264 the GD_FONTCONFIG feature. For more information about fontconfig, see the
wolffd@0	265 <a href="http://freedesktop.org/software/fontconfig">fontconfig pages</a>.
wolffd@0	266 <p>
wolffd@0	267 The actual resolved font filename can be returned in the gdFTStringExtra
wolffd@0	268 structure as the fontpath element if the gdFTEX_RETURNFONTPATHNAME flag
wolffd@0	269 is set. Also, a
wolffd@0	270 vector of character position advances can be retrieved if gdFTEX_XSHOW is set
wolffd@0	271 in the flags element. .afm files (font metrics) are now used to adjust size
wolffd@0	272 calculations
wolffd@0	273 when available. When fontconfig is not available, gd falls back to its
wolffd@0	274 usual behavior and requires a specific font file name. One can
wolffd@0	275 still fetch fonts by filename when gdFTUseFontConfig(1) is in effect, by
wolffd@0	276 setting the gdFTEX_FONTPATHNAME flag
wolffd@0	277 in the flag element of the gdFTStringExtra structure. Thanks to
wolffd@0	278 Dag Lem and John Ellson.
wolffd@0	279 <li>Additional freetype fixes: fixed width fonts are now the right
wolffd@0	280 size, horizontal advance calculations now better match the
wolffd@0	281 PostScript equivalent, and various compiler warning fixes. Also,
wolffd@0	282 a fix to the encoding table selection in the was made, addressing a problem
wolffd@0	283 with latin1 font encodings. Thanks to Dag Lem and John Ellson.
wolffd@0	284 <li>Improved tolerance when reading JPEG files containing some garbage as well
wolffd@0	285 as valid image data.
wolffd@0	286 <li>Easier compilation on Windows: no errno.h in gd_gd2.c.
wolffd@0	287 <li>Support for creating optimized GIF animations has been added
wolffd@0	288 by Jaakko Hyvätti. See
wolffd@0	289 <A HREF="#gdImageGifAnimAdd">gdImageGifAnimAdd</A>,
wolffd@0	290 <A HREF="#gdImageGifAnimAddCtx">gdImageGifAnimAddCtx</A>,
wolffd@0	291 <A HREF="#gdImageGifAnimAddPtr">gdImageGifAnimAddPtr</A>,
wolffd@0	292 <A HREF="#gdImageGifAnimBegin">gdImageGifAnimBegin</A>,
wolffd@0	293 <A HREF="#gdImageGifAnimBeginCtx">gdImageGifAnimBeginCtx</A>,
wolffd@0	294 <A HREF="#gdImageGifAnimBeginPtr">gdImageGifAnimBeginPtr</A>,
wolffd@0	295 <A HREF="#gdImageGifAnimEnd">gdImageGifAnimEnd</A>,
wolffd@0	296 <A HREF="#gdImageGifAnimEndCtx">gdImageGifAnimEndCtx</A>, and
wolffd@0	297 <A HREF="#gdImageGifAnimEndPtr">gdImageGifAnimEndPtr</A>.
wolffd@0	298 <li><A HREF="#gdImageOpenPolygon">gdImageOpenPolygon</A> has been
wolffd@0	299 added to allow consecutive line segments to be drawn without
wolffd@0	300 connecting the end points to form a closed polygon. Thanks to
wolffd@0	301 Jaakko Hyvätti.
wolffd@0	302 <li>Better alpha channel blending when the destination color
wolffd@0	303 contains an alpha channel. Also, quicker handling of the
wolffd@0	304 most common cases. Thanks to Frank Warmerdam.
wolffd@0	305 </ul>
wolffd@0	306 <P>
wolffd@0	307 <A NAME="whatsnew2.0.28"><H3>What's new in version 2.0.28?</H3></A>
wolffd@0	308 <P>
wolffd@0	309 <ul>
wolffd@0	310 <li>GIF support has been restored. See
wolffd@0	311 <a href="#gdImageGif">gdImageGif</a>,
wolffd@0	312 <a href="#gdImageGifCtx">gdImageGifCtx</a>,
wolffd@0	313 <a href="#gdImageGifPtr">gdImageGifPtr</a>,
wolffd@0	314 <a href="#gdImageCreateFromGif">gdImageCreateFromGif</a>,
wolffd@0	315 <a href="#gdImageCreateFromGifCtx">gdImageCreateFromGifCtx</a>,
wolffd@0	316 and <a href="#gdImageCreateFromGifPtr">gdImageCreateFromGifPtr</a>.
wolffd@0	317 These functions are now thread-safe, similar to the PNG and JPEG
wolffd@0	318 manipulation functions.
wolffd@0	319 <li>The new <a href="#gdImageCreatePaletteFromTrueColor">gdImageCreatePaletteFromTrueColor</a> function is identical to <a href="#gdImageTrueColorToPalette">gdImageTrueColorToPalette</a>, except that it returns a new image rather than permanently modifying the original.
wolffd@0	320 </ul>
wolffd@0	321 <P>
wolffd@0	322 <A NAME="whatsnew2.0.27"><H3>What's new in version 2.0.27?</H3></A>
wolffd@0	323 <P>
wolffd@0	324 <ul>
wolffd@0	325 <li>In gd 2.0.26, there was potential for out of bounds fills, and therefore
wolffd@0	326 crashes, in the horizontalLine function used by gdImageFilledPolygon.
wolffd@0	327 Fixed by John Ellson.
wolffd@0	328 <li>The order of the points returned in the bounding rectangle by
wolffd@0	329 gdImageStringFT was incorrect in version 2.0.26. This has been
wolffd@0	330 corrected in version 2.0.27. Thanks to Riccardo Cohen for pointing
wolffd@0	331 this out, and to John Ellson for verifying and fixing it.
wolffd@0	332 </ul>
wolffd@0	333 <P>
wolffd@0	334 <A NAME="whatsnew2.0.26"><H3>What's new in version 2.0.26?</H3></A>
wolffd@0	335 <P>
wolffd@0	336 The following enhancements and fixes:
wolffd@0	337 <ul>
wolffd@0	338 <li>Drastically faster, less memory-intensive antialiased drawing, thanks to
wolffd@0	339 Pierre-Alain Joye. This code was imported from the PHP "fork"
wolffd@0	340 of gd. The API for antialiased drawing has not changed, however the
wolffd@0	341 implementation has been completely replaced.
wolffd@0	342 Antialiased line drawing does not support widths other
wolffd@0	343 than 1, however this did not work properly with the other
wolffd@0	344 implementation of antialiasing either. Support has been included
wolffd@0	345 for the "non-blending color" option introduced by the previous
wolffd@0	346 implementation of antialiased drawing.
wolffd@0	347 <li><code>gdlib-config</code>, which has been installed by
wolffd@0	348 <code>make install</code> for some time now, has gained
wolffd@0	349 a <code>--features</code> option. This option produces a space-separated
wolffd@0	350 list of optional features with which the gd library was compiled.
wolffd@0	351 Typical usage looks like this:
wolffd@0	352 <pre>
wolffd@0	353 % gdlib-config --features
wolffd@0	354 GD_XPM GD_JPEG GD_FREETYPE GD_PNG GD_GIF
wolffd@0	355 </pre>
wolffd@0	356 Other <code>configure</code> scripts can conveniently define
wolffd@0	357 preprocessor symbols based on this list in order to conditionally
wolffd@0	358 compile code. For instance, if
wolffd@0	359 GD_PNG is not reported by --features, then gdImagePng is not
wolffd@0	360 included in the library.
wolffd@0	361 <p>
wolffd@0	362 Thanks to Lars Hecking and Lincoln Stein for their advice on
wolffd@0	363 implementing this feature. Any blame for the actual implementation
wolffd@0	364 is entirely due to me (TBB).
wolffd@0	365 <li>Fixes to the behavior of the bounding rectangle returned by
wolffd@0	366 gdImageStringFT and relatives when the string is rotated.
wolffd@0	367 See fontwheeltest.c. Thanks to John Ellson.
wolffd@0	368 <li>Previously, gdImageStringFT and friends accepted either
wolffd@0	369 a full path to a font file, or the name of a font with no
wolffd@0	370 extension, in which case the GDFONTPATH environment variable
wolffd@0	371 and then the compiled-in DEFAULT_FONTPATH was searched. In addition,
wolffd@0	372 a font filename with an extension but no full path can now be
wolffd@0	373 automatically searched for in the same fashion. Thanks to John Ellson.
wolffd@0	374
wolffd@0	375 <li>Fixes to freetype antialiased text against a transparent
wolffd@0	376 background. See testtr.c. Thanks to John Ellson.
wolffd@0	377
wolffd@0	378 <li>Support for named entities like &amp; and hex-coded
wolffd@0	379 entities such as &#x6C34; in text
wolffd@0	380 strings passed to gdImageStringFT and relatives, adding to the
wolffd@0	381 previous support for decimal-coded entities like &#197;.
wolffd@0	382 These were extracted from entities.html (from the W3C) via
wolffd@0	383 the script entities.tcl, which is included for the curious and
wolffd@0	384 those with other entities they need support for. Thanks to John Ellson.
wolffd@0	385
wolffd@0	386 <li>Optimization: gdImageSetPixel no longer calls gdImageAlphaBlend
wolffd@0	387 when either the source or the destination pixel is 100% transparent.
wolffd@0	388 Thanks to John Ellson.
wolffd@0	389
wolffd@0	390 <li>Optimization: gdImageLine is potentially faster now in the most
wolffd@0	391 common cases.
wolffd@0	392 Thanks to John Ellson.
wolffd@0	393 <li>Documentation of the entities feature of gdImageStringFT.
wolffd@0	394 <li>autoconf/configure fixes. Thanks to many who pointed out an oversight
wolffd@0	395 in handling libpng flags.
wolffd@0	396 </ul>
wolffd@0	397 <P>
wolffd@0	398 <A NAME="whatsnew2.0.25"><H3>What's new in version 2.0.25?</H3></A>
wolffd@0	399 <P>
wolffd@0	400 Owing to an oversight while making changes to better accommodate the use
wolffd@0	401 of gd as a DLL, the <b>extern</b> qualifier was dropped from the
wolffd@0	402 declarations of font pointers in 2.0.24. This has been corrected.
wolffd@0	403 Thanks to Richard ("OpenMacNews").
wolffd@0	404 <P>
wolffd@0	405 <A NAME="whatsnew2.0.24"><H3>What's new in version 2.0.24?</H3></A>
wolffd@0	406 <P>
wolffd@0	407 <b>Windows DLL now uses __stdcall calling convention.</b> Existing
wolffd@0	408 applications will require a recompile, using the new version of gd.h,
wolffd@0	409 in order to use this version of the DLL. However, Visual BASIC and other
wolffd@0	410 non-C programmers will now be able to use the DLL, which is an enormous
wolffd@0	411 benefit and justifies the one-time inconvenience to existing DLL users.
wolffd@0	412 <p>
wolffd@0	413 The elaborate #ifdef test for older versions of Freetype without
wolffd@0	414 FT_ENCODING_MS_SYMBOL was needed in a second place also. Thanks to
wolffd@0	415 David R. Morrison.
wolffd@0	416 <p>
wolffd@0	417 An off-by-one error in gdImageToPalette caused transparency to be applied
wolffd@0	418 to the wrong pixels. Thanks to "Super Pikeman."
wolffd@0	419 <P>
wolffd@0	420 <A NAME="whatsnew2.0.23"><H3>What's new in version 2.0.23?</H3></A>
wolffd@0	421 <P>
wolffd@0	422 Output dpi specification option added to the
wolffd@0	423 <code>gdFTStringExtra</code> structure, thanks to
wolffd@0	424 Mark Shackelford. See <a href="#gdImageStringFTEx">gdImageStringFTEx</a>.
wolffd@0	425 <P>
wolffd@0	426 <A NAME="whatsnew2.0.22"><H3>What's new in version 2.0.22?</H3></A>
wolffd@0	427 <P>
wolffd@0	428 <ul>
wolffd@0	429 <li>Win32 DLL users: working with pointers exported by DLLs is
wolffd@0	430 difficult and causes unexpected results. gd 2.0.22 exports new
wolffd@0	431 functions for retrieving the basic gd fonts:
wolffd@0	432 <a href="#gdFontGetTiny">gdFontGetTiny()</a>,
wolffd@0	433 <a href="#gdFontGetSmall">gdFontGetSmall()</a>,
wolffd@0	434 <a href="#gdFontGetMediumBold">gdFontGetMediumBold()</a>,
wolffd@0	435 <a href="#gdFontGetLarge">gdFontGetLarge()</a>, and
wolffd@0	436 <a href="#gdFontGetHuge">gdFontGetHuge()</a>. You may safely assign the
wolffd@0	437 return values from these functions to a local <code>gdFontPtr</code>.
wolffd@0	438 Direct use of <code>gdFontLarge</code>, etc. is strongly deprecated
wolffd@0	439 for users of <code>bgd.dll</code>; use these new functions instead.
wolffd@0	440 <li>Basic support for loading CMYK-colorspace JPEG images. They are
wolffd@0	441 of course converted to RGB which is a lossy process, however the
wolffd@0	442 results do look quite good and are certainly fine for thumbnails and
wolffd@0	443 web previews of DTP work.
wolffd@0	444 <li>"make" no longer fails on <code>circletexttest</code> if
wolffd@0	445 PNG support is missing.
wolffd@0	446 <li>Small performance improvements to gdImageCopyResampled; larger
wolffd@0	447 improvements are forthcoming.
wolffd@0	448 </ul>
wolffd@0	449 <P>
wolffd@0	450 <A NAME="whatsnew2.0.21"><H3>What's new in version 2.0.21?</H3></A>
wolffd@0	451 <P>
wolffd@0	452 <ul>
wolffd@0	453 <li>Version 2.0.21 adds a <code>gdImageCreateFrom*Ptr</code> family
wolffd@0	454 of functions which make it convenient to load an image in any
wolffd@0	455 GD-supported format directly from memory.
wolffd@0	456 <li>The new <code>gdNewDynamicCtxEx</code> function was added to
wolffd@0	457 support the easy implementation of the above functions and to
wolffd@0	458 correct a design problem which made life unpleasant for those passing
wolffd@0	459 in memory not originally allocated by gd to the
wolffd@0	460 <code>gdNewDynamicCtx</code> function by provoding a way to specify
wolffd@0	461 that gd should never free or reallocate a particular block of memory.
wolffd@0	462 The <code>gdNewDynamicCtx</code> function and its relatives, although
wolffd@0	463 still exported for ABI compatibility, are now <b>deprecated</b> except
wolffd@0	464 for internal use, in favor of <a href="#gdImageCreateFromPngPtr"><code>gdImageCreateFromPngPtr</code></a>
wolffd@0	465 and its relatives.
wolffd@0	466 <li>Version 2.0.21 includes a new patch from Ethan A. Merritt to
wolffd@0	467 correct a bug in the conditional compilation of support for
wolffd@0	468 symbol fonts in gdft.c. Symbol fonts should now work correctly.
wolffd@0	469 Thanks to Mr. Merritt.
wolffd@0	470 <li>Version 2.0.20 restores the <code>gdFreeFontCache</code> function,
wolffd@0	471 an undocumented function added in an earlier release which now simply
wolffd@0	472 calls <code>gdFontCacheShutdown</code> for backwards compatibility.
wolffd@0	473 This repairs build problems when compiling PHP against the latest gd.
wolffd@0	474 <li>Documentation improvements.
wolffd@0	475 </ul>
wolffd@0	476 <P>
wolffd@0	477 <A NAME="whatsnew2.0.20"><H3>What's new in version 2.0.20?</H3></A>
wolffd@0	478 <P>
wolffd@0	479 <ul>
wolffd@0	480 <li>Version 2.0.20 restores the <code>gdFreeFontCache</code> function,
wolffd@0	481 an undocumented function added in an earlier release which now simply
wolffd@0	482 calls <code>gdFontCacheShutdown</code> for backwards compatibility.
wolffd@0	483 This repairs build problems when compiling PHP against the latest gd.
wolffd@0	484 </ul>
wolffd@0	485 <P>
wolffd@0	486 <A NAME="whatsnew2.0.19"><H3>What's new in version 2.0.19?</H3></A>
wolffd@0	487 <P>
wolffd@0	488 <ul>
wolffd@0	489 <li>Version 2.0.19 restored <code>extern</code> declarations for the
wolffd@0	490 gd font pointers inadvertently removed in 2.0.18.
wolffd@0	491 </ul>
wolffd@0	492 <P>
wolffd@0	493 <A NAME="whatsnew2.0.18"><H3>What's new in version 2.0.18?</H3></A>
wolffd@0	494 <P>
wolffd@0	495 <ul>
wolffd@0	496 <li>A Win32 binary distribution of "bgd.dll," built with mingw32 and
wolffd@0	497 tested with win32 versions of the demo programs as console applications,
wolffd@0	498 is now available.
wolffd@0	499 <li>Semicolon rather than space used as the default separator of
wolffd@0	500 alternative font file paths in <a href="#gdImageStringFT">gdImageStringFT</a>,
wolffd@0	501 for better compatibility with Windows and other environments where
wolffd@0	502 spaces are common in paths.
wolffd@0	503 <li>The circletexttest demo no longer fails to compile when JPEG
wolffd@0	504 support happens to be absent.
wolffd@0	505 </ul>
wolffd@0	506 <P>
wolffd@0	507 <A NAME="whatsnew2.0.17"><H3>What's new in version 2.0.17?</H3></A>
wolffd@0	508 <P>
wolffd@0	509 Minor compilation and packaging problems with 2.0.16 were corrected.
wolffd@0	510 If 2.0.16 compiled without errors for you, then you don't need
wolffd@0	511 to upgrade to 2.0.17.
wolffd@0	512 <P>
wolffd@0	513 <A NAME="whatsnew2.0.16"><H3>What's new in version 2.0.16?</H3></A>
wolffd@0	514 <P>
wolffd@0	515 <ul>
wolffd@0	516 <li>Thread safety for freetype text output. Background: all gd functions
wolffd@0	517 were already thread safe, as long as only one thread manipulates each
wolffd@0	518 image -- except for gdImageStringFT and gdImageStringFTEx. This is because
wolffd@0	519 of a shared freetype font cache. Sharing the cache between images
wolffd@0	520 is worthwhile, so "configure" now detects pthreads and uses it to
wolffd@0	521 wrap freetype text output in a critical section if available. There is
wolffd@0	522 also critical section support under WIN32. Those who wish to be
wolffd@0	523 strictly thread-safe should call the new function
wolffd@0	524 <a href="#gdFontCacheSetup">gdFontCacheSetup</a> before allowing any
wolffd@0	525 thread to use freetype text calls. Otherwise this function is automatically
wolffd@0	526 invoked on the first use of freetype, with a very small but real chance
wolffd@0	527 of a race condition.
wolffd@0	528 <li><a href="#gdImageSquareToCircle">gdImageSquareToCircle</a> performs
wolffd@0	529 a "polar coordinate transform," returning a new image in which the
wolffd@0	530 X axis of the original has been remapped to theta (angle) and the
wolffd@0	531 Y axis of the original has been remapped to rho (distance from center).
wolffd@0	532 <li><a href="#gdImageStringFTCircle">gdImageStringFTCircle</a> wraps
wolffd@0	533 text in a circle around a specified center point. This function
wolffd@0	534 takes advantage of <a href="#gdImageSquareToCircle">gdImageSquareToCircle</a>.
wolffd@0	535 The result is very smooth, although it takes some time to compute.
wolffd@0	536 Thanks to Steve Bassi for sponsoring this work.
wolffd@0	537 <li><a href="#gdImageSharpen">gdImageSharpen</a>, contributed by
wolffd@0	538 Paul Troughton. Thank you.
wolffd@0	539 <li>Christophe Thomas corrected gdft.c to include freetype header
wolffd@0	540 files in the way that is now mandatory in freetype 2.1.6 and above.
wolffd@0	541 <li>Gustavo Scotti fixed a memory leak in gdft.c.
wolffd@0	542 <li>Clipping rectangle respected in freetype text output. Thanks to Matt
wolffd@0	543 McNabb.
wolffd@0	544 <li>Paul den Dulk found a degenerate case that crashes
wolffd@0	545 gdImageToPalette. Fixed.
wolffd@0	546 <li>Optimization by Ilia Chipitsine to avoid wasting time with
wolffd@0	547 offscreen scanlines during polygon rasterization.
wolffd@0	548 <li>Optimized PNG saving by Phong Tran. Speeds up saves a
wolffd@0	549 little bit.
wolffd@0	550 <li>Bug in gdImageCopyResized fixed by Mao Morimoto.
wolffd@0	551 </ul>
wolffd@0	552 <P>
wolffd@0	553 <A NAME="whatsnew2.0.15"><H3>What's new in version 2.0.15?</H3></A>
wolffd@0	554 <P>
wolffd@0	555 <ul>
wolffd@0	556 <li>gd.c in 2.0.14 contained an instance of declaring variables
wolffd@0	557 after the first line of executable code appears. This is of course
wolffd@0	558 not allowed by ANSI C, although many compilers accept it.
wolffd@0	559 My apologies. Thanks to Jeff Vendetti for reporting this quickly.
wolffd@0	560 </ul>
wolffd@0	561 <P>
wolffd@0	562 <A NAME="whatsnew2.0.14"><H3>What's new in version 2.0.14?</H3></A>
wolffd@0	563 <P>
wolffd@0	564 <ul>
wolffd@0	565 <li>2.0.13 was available for mere minutes due to a typo
wolffd@0	566 in the new bounds-checking code for antialiased line drawing. Fixed.
wolffd@0	567 <li>Not all platforms -- notably msys/mingw -- have an ssize_t type.
wolffd@0	568 We now call an int an int in gd_jpeg.c, with good results.
wolffd@0	569 (Note: ssize_t is signed, unlike size_t, and it needs to be here.)
wolffd@0	570 </ul>
wolffd@0	571 <P>
wolffd@0	572 <A NAME="whatsnew2.0.13"><H3>What's new in version 2.0.13?</H3></A>
wolffd@0	573 <P>
wolffd@0	574 <ul>
wolffd@0	575 <li>The <code>main()</code> function of one of the test programs
wolffd@0	576 was accidentally included in the gd shared library, causing problems
wolffd@0	577 on some platforms. This has been corrected. Thanks to many people
wolffd@0	578 who pointed this out.
wolffd@0	579 <li>The antialiased drawing functions now have proper bounds
wolffd@0	580 checking. Thanks to Arne Jorgensen.
wolffd@0	581 <li>A void function returned a value in gd_png.c, causing warnings
wolffd@0	582 and, on some platforms, compilation errors but no reported runtime problems.
wolffd@0	583 Thanks to Kevin Smith, among others.
wolffd@0	584 <li>Autohinting was being forced ON for freetype text output. This is
wolffd@0	585 apparently meant only for testing freetype and does not look as good
wolffd@0	586 as the default behavior (FT_LOAD_DEFAULT). Thanks to Bob Ostermann.
wolffd@0	587 <li>penf.x is properly reset when newlines are encountered in freetype
wolffd@0	588 text output. Thanks to Christopher J. Grayce.
wolffd@0	589 </ul>
wolffd@0	590 <P>
wolffd@0	591 <A NAME="whatsnew2.0.12"><H3>What's new in version 2.0.12?</H3></A>
wolffd@0	592 <P>
wolffd@0	593 <ul>
wolffd@0	594 <li>Small but numerous code cleanups by Dr. Martin Zinser.
wolffd@0	595 <li><a href="#gdImageSetClip">gdImageSetClip</a> and
wolffd@0	596 <a href="#gdImageGetClip">gdImageGetClip</a> have been added. All
wolffd@0	597 drawing routines now stay within the specified clipping rectangle.
wolffd@0	598 Note that the <a href="#gdImageBoundsSafe">gdImageBoundsSafe</a> function
wolffd@0	599 now returns true only if the specified location is within the
wolffd@0	600 clipping rectangle. Of course, the default clipping area is the
wolffd@0	601 entire image. The behavior of existing gd applications does not change.
wolffd@0	602 <li>Support for fast drawing of antialiased lines and polygons,
wolffd@0	603 by Bright Fulton and Frank Faubert. To learn more about this feature,
wolffd@0	604 read about the <a href="#gdImageSetAntiAliased">gdImageSetAntiAliased</a>
wolffd@0	605 function, which is used to set the foreground color for antialiasing,
wolffd@0	606 as well as the <a href="#gdAntiAliased">gdAntiAliased</a> constant, which
wolffd@0	607 is passed to line- and polygon-drawing functions in place of a color.
wolffd@0	608 This code does not currently support an alpha channel component in the
wolffd@0	609 specified foreground color, or in the existing background image,
wolffd@0	610 but <em>does</em> perform alpha blending against an opaque background.
wolffd@0	611 Also see the
wolffd@0	612 <a href="#gdImageSetAntiAliasedDontBlend">gdImageSetAntiAliasedDontBlend</a>
wolffd@0	613 function, which allows the specification of a special background
wolffd@0	614 color that should never be blended with the foreground.
wolffd@0	615 <li>Fixes to color mapping in <a href="#gdImageCopyMergeGray">gdImageCopyMergeGray</a>. Thanks to Philip Warner.
wolffd@0	616 <li><a href="#gdImageStringFTEx">gdImageStringFTEx</a> now supports
wolffd@0	617 explicit specification of the desired character mapping.
wolffd@0	618 This is useful when a font offers more than one of Unicode,
wolffd@0	619 Shift_JIS, and Big5.
wolffd@0	620 <li>The PNG compression level can now be specified when writing PNG
wolffd@0	621 images. See the new <a href="#gdImagePngEx">gdImagePngEx</a>,
wolffd@0	622 <a href="#gdImagePngEx">gdImagePngEx</a>,
wolffd@0	623 <a href="#gdImagePngCtxEx">gdImagePngCtxEx</a>, and
wolffd@0	624 <a href="#gdImagePngPtrEx">gdImagePngPtrEx</a> functions.
wolffd@0	625 <li>The annotate utility builds without error in the absence of
wolffd@0	626 freetype, although of course it is not useful without freetype.
wolffd@0	627 <li>Thorben Kundinger fixed a bug relating to the use of palette-based
wolffd@0	628 images as brushes when drawing on truecolor images.
wolffd@0	629 <li>Michael Schwartz corrected a problem with his code for drawing
wolffd@0	630 thick lines.
wolffd@0	631 <li>Prior to 2.0.12, any alpha channel component in the
wolffd@0	632 <em>destination</em> image was ignored when drawing with
wolffd@0	633 alpha blending in effect (see
wolffd@0	634 <a href="#gdImageAlphaBlending">gdImageAlphaBlending</a>). 2.0.12
wolffd@0	635 correctly preserves an appropriate proportion of the alpha component
wolffd@0	636 of the destination, just as it preserves an appropriate proportion
wolffd@0	637 of the red, green and blue components, depending on the opacity
wolffd@0	638 of the foreground. Thanks to Frank Warmerdam for pointing out the issue.
wolffd@0	639 <li>Memory leaks on failed attempts to load fonts
wolffd@0	640 in <a href="#gdImageStringFTEx">gdImageStringFTEx</a> were corrected.
wolffd@0	641 Thanks to Frank Faubert.
wolffd@0	642 <li>The impact of kerning is now correctly included in the calculation
wolffd@0	643 of the bounding box returned by the freetype text routines. This issue
wolffd@0	644 was pointed out by several individuals.
wolffd@0	645 <li>Color problems with the <code>gd2</code> file format routines
wolffd@0	646 were fixed by Steven Brown. These problems were due to the
wolffd@0	647 incorrect use of a signed integer.
wolffd@0	648 <li>Version 2.0.12 supports the <code>gd</code> file format correctly
wolffd@0	649 for truecolor images. Truecolor <code>gd</code> files created with
wolffd@0	650 earlier releases in the 2.0 series must be written again. The <code>gd</code>
wolffd@0	651 file format is used to quickly load an entire uncompressed image, typically
wolffd@0	652 an existing background to which additional material will be added; it is not a
wolffd@0	653 general purpose file format. More advanced capabilities are also available
wolffd@0	654 via the <code>gd2</code> format. Thanks to Andreas Pfaller for reporting
wolffd@0	655 the problem.
wolffd@0	656 <li>Signed vs. unsigned problem caused misbehavior when attempting to
wolffd@0	657 load a bad JPEG image. Thanks to Geert Jansen.
wolffd@0	658 <li>Existing truecolor PNG images with simple single-color transparency are
wolffd@0	659 now loaded properly, thanks to Slaven Rezic.
wolffd@0	660 <li>The <a href="#gdImageTrueColorToPalette">gdImageTrueColorToPalette</a>
wolffd@0	661 function no longer attempts to preserve an alpha channel in the original.
wolffd@0	662 My attempt to do so resulted in significantly inferior output even if no
wolffd@0	663 alpha channel was present in the original. Thanks to Barend Gehrels for
wolffd@0	664 submitting a new adaptation of Tom Lane's jquant2.c which does a very
wolffd@0	665 high-quality job of palette conversion. Thanks also to Steven Brown, who
wolffd@0	666 submitted patches allowing a single 100% transparent color in the
wolffd@0	667 original truecolor image to be preserved. In practice, more complex
wolffd@0	668 alpha channels in palettes are ill-supported and difficult to
wolffd@0	669 allocate skillfully.
wolffd@0	670 </ul>
wolffd@0	671 <P>
wolffd@0	672 <A NAME="whatsnew2.0.11"><H3>What's new in version 2.0.11?</H3></A>
wolffd@0	673 <P>
wolffd@0	674 <ul>
wolffd@0	675 <li>Support for the "gd2" file format, which allows fast loading of all or
wolffd@0	676 only part of an existing image, has been properly debugged for use with
wolffd@0	677 truecolor images. (Palette images already worked properly, except for a
wolffd@0	678 bug when loading from a regular file with gdImageCreateFromGd2Part, which
wolffd@0	679 has also been fixed.) .gd2 files can be either compressed or uncompressed,
wolffd@0	680 and they allow useful tricks such as fast loading of a 500x500 pixel
wolffd@0	681 region of a 6000x3000 pixel image, without uncompressing <em>all</em> of the
wolffd@0	682 image. .gd2 is NOT a general purpose file format and should only be used
wolffd@0	683 where quick loading of a background image or subset of a larger image
wolffd@0	684 is required. For more information, see
wolffd@0	685 <a href="#gdImageGd2">gdImageGd2</a>,
wolffd@0	686 <a href="#gdImageCreateFromGd2">gdImageCreateFromGd2</a>,
wolffd@0	687 and
wolffd@0	688 <a href="#gdImageCreateFromGd2Part">gdImageCreateFromGd2Part</a>.
wolffd@0	689 <li>The gd2topng utility has been extended to support extraction of
wolffd@0	690 only part of an image from a .gd2 file. This is both a demonstration and
wolffd@0	691 a practical tool.
wolffd@0	692 <li>Additional <code>configure</code> improvements by Lars Hecking.
wolffd@0	693 </ul>
wolffd@0	694 <P>
wolffd@0	695 <A NAME="whatsnew2.0.10"><H3>What's new in version 2.0.10?</H3></A>
wolffd@0	696 <P>
wolffd@0	697 <ul>
wolffd@0	698 <li>gdImageLine now clips to the edges of the image before drawing
wolffd@0	699 lines, which greatly improves performance when many lines extend
wolffd@0	700 outside or are entirely outside the actual image. Thanks to
wolffd@0	701 Nick Atty for this code.
wolffd@0	702 <li>gdImageBoundsSafe is replaced with a macro when called internally;
wolffd@0	703 this improves the performance of gdImageSetPixel and gdImageGetPixel
wolffd@0	704 a little bit, and therefore everything else as well. Thanks to
wolffd@0	705 Nicky Atty for the idea.
wolffd@0	706 <li>Transparent indexes are handled properly with non-truecolor
wolffd@0	707 source images in gdImageCopy. Thanks to Frank Warmerdam.
wolffd@0	708 <li>floor() replaced with a cast to long in gdImageCopyResampled,
wolffd@0	709 for a roughly 35% performance boost. Thanks to John Buckman.
wolffd@0	710 <li>gdft.c builds correctly on WIN32 without patches.
wolffd@0	711 <li>Much faster gdImageCreateFromJpeg routines, thanks to Christian
wolffd@0	712 Aberger for more efficient pointer arithmetic.
wolffd@0	713 <li>gdtestft correctly builds without PNG tests if PNG support is not present.
wolffd@0	714 Thanks to Gabriele Verzeletti.
wolffd@0	715 </ul>
wolffd@0	716 <P>
wolffd@0	717 <A NAME="whatsnew2.0.9"><H3>What's new in version 2.0.9?</H3></A>
wolffd@0	718 <P>
wolffd@0	719 <ul>
wolffd@0	720 <li>Version 2.0.9 contains a fix to gdImageCopyResized which allows
wolffd@0	721 correct results when copying a palette-based image with a single
wolffd@0	722 transparent index into a truecolor image. Thanks to Thorben
wolffd@0	723 Kundinger.
wolffd@0	724 <li>More <code>configure</code> fixes from Lars Hecking. Thanks, Lars.
wolffd@0	725 </ul>
wolffd@0	726 <P>
wolffd@0	727 <A NAME="whatsnew2.0.8"><H3>What's new in version 2.0.8?</H3></A>
wolffd@0	728 <P>
wolffd@0	729 <ul>
wolffd@0	730 <li>Version 2.0.8 contains additional fixes to the 'configure' script,
wolffd@0	731 allowing a clean out-of-the-box build on more systems.
wolffd@0	732 <li>Version 2.0.8 adds the new
wolffd@0	733 <a href="#gdImageCopyRotated">gdImageCopyRotated</a> function, which
wolffd@0	734 can rotate any rectangular image region by an arbitrary number of degrees.
wolffd@0	735 </ul>
wolffd@0	736 <P>
wolffd@0	737 <A NAME="whatsnew2.0.7"><H3>What's new in version 2.0.7?</H3></A>
wolffd@0	738 <P>
wolffd@0	739 Version 2.0.7 corrects a problem which caused 'configure' to complain
wolffd@0	740 that the directory NONE was not found, in various places, causing
wolffd@0	741 the configuration process to stop. There are no code changes.
wolffd@0	742 <P>
wolffd@0	743 <A NAME="whatsnew2.0.6"><H3>What's new in version 2.0.6?</H3></A>
wolffd@0	744 <P>
wolffd@0	745 <ul>
wolffd@0	746 <li>
wolffd@0	747 Fixed a compilation problem with gdft.c. A declaration appeared
wolffd@0	748 after executable code, and gcc let it slide by, so it made it
wolffd@0	749 out the door. My apologies!
wolffd@0	750 <li>As penance, I have seen to it that the entire library
wolffd@0	751 now compiles cleanly with the <code>-Wall</code>, <code>-ansi</code>
wolffd@0	752 and <code>-pedantic</code> options enabled.
wolffd@0	753 </ul>
wolffd@0	754 <p>
wolffd@0	755 <A NAME="whatsnew2.0.5"><H3>What's new in version 2.0.5?</H3></A>
wolffd@0	756 <ul>
wolffd@0	757 <li>libgd 2.0.5 INSTALLS IN /usr/local/lib BY DEFAULT. IF YOU WANT
wolffd@0	758 IT TO INSTALL IN /usr/lib, YOU MUST SPECIFY THIS at
wolffd@0	759 <code>configure</code> time using this syntax:
wolffd@0	760 <p>
wolffd@0	761 <code>./configure --prefix=/usr</code>
wolffd@0	762 <li>gd now uses GNU autoconf. This means that the provided
wolffd@0	763 <code>configure</code> script should be compatible with all standard
wolffd@0	764 GNU configure options and will figure out the correct settings for a
wolffd@0	765 much wider range of operating systems. Many, many thanks to
wolffd@0	766 Lars Hecking for taking care of this.
wolffd@0	767 <li>The <a href="#gdImageStringFTEx">gdImageStringFTEx</a> function
wolffd@0	768 is now included, thanks to Wez Furlong. My apologies to Wez for the
wolffd@0	769 unreasonable amount of time this patch has sat in my queue.
wolffd@0	770 <li>Additional fixes from Wez Furlong.
wolffd@0	771 <li>Arithmetic cleanup by Doug Claar.
wolffd@0	772 <li>Corrections to loading and saving of alpha channel
wolffd@0	773 information in PNG files, by Andrew Hull.
wolffd@0	774 <li>gdImageTrueColorToPalette does not contain
wolffd@0	775 unneeded test code.
wolffd@0	776 <li>gdImageCopyResized works properly again when copying
wolffd@0	777 from a non-truecolor source.
wolffd@0	778 </ul>
wolffd@0	779 <P>
wolffd@0	780 <A NAME="whatsnew2.0.4"><H3>What's new in version 2.0.4?</H3></A>
wolffd@0	781 The following contributions from John Ellson:
wolffd@0	782 <ul>
wolffd@0	783 <li>Various test programs now compile in the absence
wolffd@0	784 of PNG support
wolffd@0	785 <li>gdIOCtx correctly calls gdFree rather than free
wolffd@0	786 <li>Various cleanups to pass -Wall without warnings
wolffd@0	787 <li>Support for Adobe-style Type 1 fonts (.pfa and .pfb files)
wolffd@0	788 via freetype
wolffd@0	789 <li>gdImageColorResolve and gdImageColorResolveAlpha will not
wolffd@0	790 attempt to resolve a color request to the transparent color index
wolffd@0	791 (for palette-based images)
wolffd@0	792 <li>Improved font search path support
wolffd@0	793 <li>Antialiased freetype text on palette images works properly
wolffd@0	794 when more than one image is created in a single program lifetime
wolffd@0	795 with different color indexes
wolffd@0	796 <li>Better threshold for two-color "mono" images
wolffd@0	797 <li>Memory leak fixes
wolffd@0	798 <li>Text rotation fix
wolffd@0	799 <li>More extensive default font path
wolffd@0	800 <li>fontwheeltest and fontsizetest test programs for freetype
wolffd@0	801 </ul>
wolffd@0	802 And the following additional fixes:
wolffd@0	803 <ul>
wolffd@0	804 <li><code>configure</code> now correctly detects and provides
wolffd@0	805 support for the Xpm library and its dependencies (Len Makin)
wolffd@0	806 </ul>
wolffd@0	807 <A NAME="whatsnew2.0.3"><H3>What's new in version 2.0.3?</H3></A>
wolffd@0	808 <ul>
wolffd@0	809 <li>The <code>configure</code> script has been extensively modified
wolffd@0	810 to work properly in tests with both Solaris and Linux. Other platforms
wolffd@0	811 should also work based on feedback received and integrated to date.
wolffd@0	812 <li>The <code>--prefix</code> option to <code>configure</code>
wolffd@0	813 works properly.
wolffd@0	814 <li>The <code>annotate</code> utility has been added. This is a
wolffd@0	815 very handy tool for adding freetype text to existing JPEGs. After
wolffd@0	816 <code>make install</code>, type <code>annotate -h</code> for more
wolffd@0	817 information. Thanks to Joel Dubiner.
wolffd@0	818 </ul>
wolffd@0	819 <P>
wolffd@0	820 <A NAME="whatsnew2.0.2"><H3>What's new in version 2.0.2?</H3></A>
wolffd@0	821 <ul>
wolffd@0	822 <li>A "configure" script has been added. After wrestling with GNU
wolffd@0	823 autoconf for a while, I got tired of trying to make it detect libraries
wolffd@0	824 but accept their absence gracefully, and so on. Instead, I wrote a short
wolffd@0	825 Perl script which does the job and builds a reasonable Makefile. Those
wolffd@0	826 who find it doesn't detect their system's needs properly are welcome
wolffd@0	827 to contribute patches or the necessary commands.
wolffd@0	828 <li>Antialiased freetype text output now works properly in both
wolffd@0	829 truecolor and non-truecolor contexts! Hurrah! On a truecolor image
wolffd@0	830 it is possible, for instance, to draw antialiased text on an arbitrarily
wolffd@0	831 complex background with 50% alpha blending (transparency), and get the
wolffd@0	832 expected pretty results. Thanks to Joel Dubiner for his support of this work.
wolffd@0	833 <li><strong>By default, alpha blending is now done within the library.</strong>
wolffd@0	834 Also, by default, alpha channel is not saved with PNG images. This means
wolffd@0	835 that programmers who try loading a JPEG, scribbling some pretty antialiased
wolffd@0	836 text on it, and saving the JPEG again will now get the results they
wolffd@0	837 expected. It also means that, by default, users will not run afoul of
wolffd@0	838 the fact that many web browsers don't properly support full PNG alpha
wolffd@0	839 channel.
wolffd@0	840 <li>Various submitted bug fixes have been incorporated.
wolffd@0	841 <li>Various other submitted changes have not been incorporated. Sorry.
wolffd@0	842 The interval between 2.0.1 and 2.0.2 was simply too long, and changes
wolffd@0	843 accumulated which were not mutually compatible. I'll do better in
wolffd@0	844 the future, especially with bug fixes.
wolffd@0	845 </ul>
wolffd@0	846 <P><A NAME="whatsnew2.0.1"><H3>What's new in version 2.0.1?</H3></A>
wolffd@0	847 <ul>
wolffd@0	848 <li>Workaround for a bug in gcc, apparently found in gcc 2.7.2 and up.
wolffd@0	849 I reproduced and fixed it while using gcc 2.9.5.2. The bug occurred only
wolffd@0	850 when the -g option was in use. This problem caused gcc to spew
wolffd@0	851 internal error messages unrelated to the correctness of the code
wolffd@0	852 in gd_gd2.c. Howard Jones was first to report it.
wolffd@0	853 <li><a href="#gdImageFilledEllipse">gdImageFilledEllipse</a> documented
wolffd@0	854 and altered; no longer requires a superfluous style argument. Thanks to
wolffd@0	855 Francis James Franklin.
wolffd@0	856 <li>The Makefile now offers the correct syntax for
wolffd@0	857 optionally creating a static library. Thanks to Jean-Lous Regez,
wolffd@0	858 among others.
wolffd@0	859 <li>A nested comment, an attempt to return the value of a void function,
wolffd@0	860 and a potentially significant error in gdImageCopyResampled were fixed
wolffd@0	861 thanks to Joseph Shirley.
wolffd@0	862 <li>A bug preventing proper truecolor text rendering was fixed,
wolffd@0	863 thanks to Jason Gallagher.
wolffd@0	864 <li><a href="#gdImageStringFT">gdImageStringFT</a> (FreeType) should
wolffd@0	865 now work better against a transparent or semitransparent background,
wolffd@0	866 and should act in a manner consistent with the most recent
wolffd@0	867 <a href="#gdImageAlphaBlending">gdImageAlphaBlending</a> setting.
wolffd@0	868 Antialiasing is now done via the alpha channel mechanism if the
wolffd@0	869 image is a truecolor image.
wolffd@0	870 <li>Bugs in the output of gdImageArc and gdImageFilledArc were reported
wolffd@0	871 by Bruce Verderaime. A simple and correct but inefficient implementation
wolffd@0	872 has been substituted until fixes are contributed for the faster code,
wolffd@0	873 which is in gd_arc_f_buggy.c along with the test program that reproduces
wolffd@0	874 the bug(s).
wolffd@0	875 <li><a href="#gdImageFilledArc">gdImageFilledArc</a> now offers additional
wolffd@0	876 style options, which can be combined to produce various effects.
wolffd@0	877 <li>Masahito Yamaga (ma@yama-ga.com) sent a patch to improve
wolffd@0	878 support for Japanese output via <a href="#gdImageStringFT">gdImageStringFT</a>.
wolffd@0	879 He also added a new <code>readme.jpn</code> file.
wolffd@0	880 <li>Zillions of documentation fixes.
wolffd@0	881 </ul>
wolffd@0	882 <P><A NAME="whatsnew2.0"><H3>What's new in version 2.0?</H3></A>
wolffd@0	883 <ul>
wolffd@0	884 <li><strong>Support for truecolor images!</strong> Version 2.0 can
wolffd@0	885 load truecolor PNGs with no loss of color information, and almost
wolffd@0	886 no loss of alpha channel information. Version 2.0 can also load
wolffd@0	887 truecolor JPEGs with as little loss as possible; however, bear in
wolffd@0	888 mind that JPEG is a lossy format, so repeated load/save cycles
wolffd@0	889 always reduce image quality. This is not a bug. To create
wolffd@0	890 a truecolor image from scratch, call the new
wolffd@0	891 <a href="#gdImageCreateTrueColor">gdImageCreateTrueColor</a>
wolffd@0	892 function. The <a href="#gdImageCreate">gdImageCreate</a> function
wolffd@0	893 is still available to create palette images, and may also be
wolffd@0	894 referred to as <a href="#gdImageCreatePalette">gdImageCreatePalette</a>.
wolffd@0	895 <li><strong>Support for alpha channels!</strong> In addition to
wolffd@0	896 24 bits of color information for each pixel (eight bits of
wolffd@0	897 red, green, and blue respectively), version 2.0 supports
wolffd@0	898 7 bits of "alpha channel" information. This is used to determine
wolffd@0	899 exactly how transparent the pixel should be. There is also support
wolffd@0	900 for a full 7 bits of transparency for each individual palette index
wolffd@0	901 in a palette-based image. Please note that, as of this writing,
wolffd@0	902 only Macintosh Internet Explorer 5.x and Mozilla/Netscape 6.x
wolffd@0	903 display partial transparency properly.
wolffd@0	904 <li>The new <a href="#gdImageAlphaBlending">gdImageAlphaBlending</a>
wolffd@0	905 function allows for two different modes of drawing. In blending mode,
wolffd@0	906 the alpha channel component of the color supplied to all drawing
wolffd@0	907 functions, such as <a href="#gdImageSetPixel">gdImageSetPixel</a>,
wolffd@0	908 determines how much of the underlying color should be allowed to
wolffd@0	909 shine through. The resulting image is not transparent. In non-blending
wolffd@0	910 mode, drawing color is copied literally with the alpha channel
wolffd@0	911 information, resulting in a transparent image. Blending mode is
wolffd@0	912 not available when drawing on palette images.
wolffd@0	913 <li>The <a href="#gdImageCopyResampled">gdImageCopyResampled</a>
wolffd@0	914 function provides "smooth" copying from a large image to a smaller
wolffd@0	915 one, using a weighted average of the pixels of the source area rather
wolffd@0	916 than selecting one representative pixel. This function is identical
wolffd@0	917 to <a href="#gdImageCopyResized">gdImageCopyResized</a> when the
wolffd@0	918 destination image is a palette image.
wolffd@0	919 <li>The <a href="#gdImageTrueColorToPalette">gdImageTrueColorToPalette</a>
wolffd@0	920 function converts a truecolor image to a palette image. The code for
wolffd@0	921 this function was originally drawn from the Independent JPEG Group library
wolffd@0	922 code, which is excellent. The code has been modified to preserve as much
wolffd@0	923 alpha channel information as possible in the resulting palette, in addition
wolffd@0	924 to preserving colors as well as possible. This does not work as well as
wolffd@0	925 might be hoped. It is usually best to simply produce a truecolor
wolffd@0	926 output image instead, which guarantees the highest output quality.
wolffd@0	927 <li>A very high degree of backwards compatibility with existing
wolffd@0	928 gd 1.x code has been maintained, at both the source code and binary
wolffd@0	929 level. <strong>Code which directly accesses the <code>pixels</code> array
wolffd@0	930 will fail only if it encounters an existing truecolor image</strong>, which may
wolffd@0	931 happen if the code attempts to open and modify an existing JPEG or
wolffd@0	932 truecolor PNG. Such code should be modified to check the
wolffd@0	933 <code>trueColor</code> flag of the <code>gdImage</code> structure, and
wolffd@0	934 refer to the <code>tpixels</code> array instead when it is set.
wolffd@0	935 <li>gd is now compiled and installed as a shared library. However,
wolffd@0	936 gd still does not use autoconf, because I (TBB) have very limited
wolffd@0	937 patience with autoconf. These days, most Unix systems provide a fairly
wolffd@0	938 POSIX-standard environment, and the provided Makefile is likely to work well
wolffd@0	939 if users read it and follow the instructions at the top.
wolffd@0	940 <li>Support for line thickness was added by Michael Schwartz. My apologies
wolffd@0	941 to him for sitting on his patches for so long. See the new
wolffd@0	942 <a href="#gdImageSetThickness">gdImageSetThickness</a> function, which
wolffd@0	943 affects all standard gd functions that draw lines and curves. In addition,
wolffd@0	944 Michael added a convenient <a href="#gdImageEllipse">gdImageEllipse</a>
wolffd@0	945 function.
wolffd@0	946 <li>The new <a href="#gdImageFilledArc">gdImageFilledArc</a> function
wolffd@0	947 provides a straightforward way to draw filled arcs. Also,
wolffd@0	948 <a href="#gdImageFilledEllipse">gdImageFilledEllipse</a> is a
wolffd@0	949 convenient way to fill an ellipse without specifying starting
wolffd@0	950 and ending angles. Thanks go out to F J Franklin.
wolffd@0	951 <li>To put an end to the confusion, TrueType 1.x support has been
wolffd@0	952 removed in favor of TrueType 2.x support. The old
wolffd@0	953 gdImageStringTTF function simply invokes gdImageStringFT.
wolffd@0	954 <li>The specialized .gd and .gd2 file formats have been upgraded to support
wolffd@0	955 truecolor. New images written by the versions of these functions
wolffd@0	956 found in 2.0 will be rejected, with varying degrees of grace, by
wolffd@0	957 older versions of gd. THIS AFFECTS THE .GD and .GD2 FORMATS ONLY. IF YOU
wolffd@0	958 ARE CONFUSED BY THIS PARAGRAPH, IT PROBABLY DOESN'T APPLY TO ANYTHING
wolffd@0	959 YOU WILL EVER ENCOUNTER. Since these file formats are absolutely,
wolffd@0	960 positively not designed for distributing images, just for
wolffd@0	961 preprocessing them, this should not be a big problem. gd 2.0 should
wolffd@0	962 read old .gd and .gd2 files correctly.
wolffd@0	963 </ul>
wolffd@0	964 <P><A NAME="whatsnew1.8.4"><H3>What's new in version 1.8.4?</H3></A>
wolffd@0	965 <ul>
wolffd@0	966 <li>Add support for FreeType2 (John Ellson ellson@graphviz.org)
wolffd@0	967 <li>Add support for finding in fonts in a builtin DEFAULT_FONTPATH,
wolffd@0	968 or in a path from the GDFONTPATH environment variable.
wolffd@0	969 <li>remove some unused symbols to reduce compiler warnings
wolffd@0	970 <li>bugfix in size comparisons in gdImageCompare
wolffd@0	971 <li>REXX now mentioned
wolffd@0	972 <li>All memory allocation functions are now wrapped within the
wolffd@0	973 library; gdFree is exported and recommended for freeing memory
wolffd@0	974 returned by the gdImage(Something)Ptr family of functions.
wolffd@0	975 </ul>
wolffd@0	976 <P><A NAME="whatsnew1.8.3"><H3>What's new in version 1.8.3?</H3></A>
wolffd@0	977 <ul>
wolffd@0	978 <li>WBMP output memory leak fixed
wolffd@0	979 <li><code>#include <gd.h></code> corrected to <code>#include "gd.h"</code> in gd_wbmp.c
wolffd@0	980 <li>Documented the fact that the source and output images shouldn't
wolffd@0	981 match in the WBMP test except for black and white source images
wolffd@0	982 </ul>
wolffd@0	983 <P>
wolffd@0	984 <A NAME="whatsnew1.8.2"><H3>What's new in version 1.8.2?</H3></A>
wolffd@0	985 <ul>
wolffd@0	986 <li>WBMP support debugged and improved by Johann Van den Brande
wolffd@0	987 <li>WBMP tests added to gdtest.c by Thomas Boutell
wolffd@0	988 <li>Use of platform-dependent 'install' command removed by Thomas Boutell
wolffd@0	989 <li>Comments added to Makefile warning users to juggle the order of the
wolffd@0	990 libraries if the linker complains; is there any portable way to do this
wolffd@0	991 automatically, short of using autoconf?
wolffd@0	992 <li>Documentation of <a href="#gdImageCreateFromXpm">gdImageCreateFromXpm</a>
wolffd@0	993 corrected
wolffd@0	994 <li>Updated links to fast-moving, always dodging libpng and zlib web sites
wolffd@0	995 </ul>
wolffd@0	996 <P><A NAME="whatsnew1.8.1"><H3>What's new in version 1.8.1?</H3></A>
wolffd@0	997 <ul>
wolffd@0	998 <li>Optional components no longer built by default (following the
wolffd@0	999 documentation)
wolffd@0	1000 <li>JPEG code no longer requires inappropriate header files
wolffd@0	1001 <li>Win32 patches from Joe Gregorio
wolffd@0	1002 <li>16-bit font support for bdftogd, from Honza Pazdziora
wolffd@0	1003 </ul>
wolffd@0	1004 <P><A NAME="whatsnew1.8"><H3>What's new in version 1.8?</H3></A>
wolffd@0	1005 <ul>
wolffd@0	1006 <li>Support for JPEG output, courtesy of Doug Becker
wolffd@0	1007 <li>A link to Michael Bradbery's Pascal wrapper
wolffd@0	1008 <li>Support for WBMP output, courtesy of Maurice Szmurlo
wolffd@0	1009 <li>gdImageColorClosestHWB function based on hue, whiteness, blackness,
wolffd@0	1010 superior to the regular gdImageColorClosest function, courtesy
wolffd@0	1011 of Philip Warner
wolffd@0	1012 <li>License clarification: yes, you can modify gd
wolffd@0	1013 </ul>
wolffd@0	1014 <h4>Additional JPEG Information</h4>
wolffd@0	1015 Support for reading and writing JPEG-format images is courtesy
wolffd@0	1016 of Doug Becker and the Independent JPEG Group / Thomas G. Lane. You
wolffd@0	1017 can get the latest version of the IJG JPEG software from <A
wolffd@0	1018 HREF="ftp://ftp.uu.net/graphics/jpeg/">ftp://ftp.uu.net/graphics/jpeg/</A>
wolffd@0	1019 (e.g., the <A
wolffd@0	1020 HREF="ftp://ftp.uu.net/graphics/jpeg/jpegsrc.v6b.tar.gz">jpegsrc.v6b.tar.gz</A>
wolffd@0	1021 file). You <strong>must</strong> use
wolffd@0	1022 version 6b or later of the IJG JPEG software. You might also consult
wolffd@0	1023 the <A HREF="http://www.faqs.org/faqs/jpeg-faq/">JPEG FAQ</A> at
wolffd@0	1024 <A HREF="http://www.faqs.org/faqs/jpeg-faq/">http://www.faqs.org/faqs/jpeg-faq/</A>.
wolffd@0	1025 <P><A NAME="whatsnew1.7.3"><H3>What's new in version 1.7.3?</H3></A>
wolffd@0	1026 Another attempt at Makefile fixes to permit
wolffd@0	1027 linking with all libraries required on platforms with order-
wolffd@0	1028 dependent linkers. Perhaps it will work this time.
wolffd@0	1029 <P><A NAME="whatsnew1.7.2"><H3>What's new in version 1.7.2?</H3></A>
wolffd@0	1030 An uninitialized-pointer bug in <code>gdtestttf.c</code> was corrected.
wolffd@0	1031 This bug caused crashes at the end of each call to gdImageStringTTF on
wolffd@0	1032 some platforms. Thanks to Wolfgang Haefelinger.
wolffd@0	1033 <p>
wolffd@0	1034 Documentation fixes. Thanks to Dohn Arms.
wolffd@0	1035 <p>
wolffd@0	1036 Makefile fixes to permit
wolffd@0	1037 linking with all libraries required on platforms with order-
wolffd@0	1038 dependent linkers.
wolffd@0	1039 <P><A NAME="whatsnew1.7.1"><H3>What's new in version 1.7.1?</H3></A>
wolffd@0	1040 A minor buglet in the Makefile was corrected, as well as an inaccurate
wolffd@0	1041 error message in <code>gdtestttf.c</code>. Thanks to Masahito Yamaga.
wolffd@0	1042 <P><A NAME="whatsnew1.7"><H3>What's new in version 1.7?</H3></A>
wolffd@0	1043 Version 1.7 contains the following changes:
wolffd@0	1044 <ul>
wolffd@0	1045 <li>Japanese language support for the TrueType functions.
wolffd@0	1046 Thanks to Masahito Yamaga.
wolffd@0	1047 <li><code>autoconf</code> and <code>configure</code> have been removed, in favor of a
wolffd@0	1048 carefully designed Makefile which produces and properly installs
wolffd@0	1049 the library and the binaries. System-dependent variables are
wolffd@0	1050 at the top of the Makefile for easy modification. I'm sorry,
wolffd@0	1051 folks, but autoconf generated <strong>many, many confused email
wolffd@0	1052 messages</strong> from people who didn't have things where autoconf
wolffd@0	1053 expected to find them. I am not an autoconf/automake wizard, and
wolffd@0	1054 gd is a simple, very compact library which does not need to
wolffd@0	1055 be a shared library. I <strong>did</strong> make many improvements
wolffd@0	1056 over the old gd 1.3 Makefile, which were directly inspired by the
wolffd@0	1057 autoconf version found in the 1.6 series (thanks to John Ellson).
wolffd@0	1058 <li>Completely ANSI C compliant, according to the <code>-pedantic-errors</code>
wolffd@0	1059 flag of gcc. Several pieces of not-quite-ANSI-C code were causing problems
wolffd@0	1060 for those with non-gcc compilers.
wolffd@0	1061 <li><code>gdttf.c</code> patched to allow the use of Windows symbol
wolffd@0	1062 fonts, when present (thanks to Joseph Peppin).
wolffd@0	1063 <li><code>extern "C"</code> wrappers added to <code>gd.h</code> and the
wolffd@0	1064 font header files for the convenience of C++ programmers.
wolffd@0	1065 <code>bdftogd</code> was also modified to automatically insert these
wolffd@0	1066 wrappers into future font header files. Thanks to John Lindal.
wolffd@0	1067 <li>Compiles correctly on platforms that don't define <code>SEEK_SET</code>.
wolffd@0	1068 Thanks to Robert Bonomi.
wolffd@0	1069 <li>Loads Xpm images via the
wolffd@0	1070 <a href="#gdImageCreateFromXpm"><code>gdImageCreateFromXpm</code></a>
wolffd@0	1071 function, if the Xpm library is available. Thanks to Caolan McNamara.
wolffd@0	1072 </ul>
wolffd@0	1073 <P><A NAME="whatsnew1.6.3"><H3>What's new in version 1.6.3?</H3></A>
wolffd@0	1074 Version 1.6.3 corrects a memory leak in gd_png.c. This leak caused
wolffd@0	1075 a significant amount of memory to be allocated and not freed when
wolffd@0	1076 writing a PNG image.
wolffd@0	1077 <P><A NAME="whatsnew1.6.2"><H3>What's new in version 1.6.2?</H3></A>
wolffd@0	1078 Version 1.6.2 from John Ellson <ellson@graphviz.org> adds two new functions:
wolffd@0	1079 <ul>
wolffd@0	1080 <li>gdImageStringTTF - scalable, rotatable, anti-aliased, TrueType strings using
wolffd@0	1081 the FreeType library, but only if libttf is found by configure.
wolffd@0	1082 <strong>We do not provide TrueType fonts. Obtaining them
wolffd@0	1083 is entirely up to you.</strong>
wolffd@0	1084 <li>gdImageColorResolve - an efficient alternative for the
wolffd@0	1085 common code fragment:
wolffd@0	1086 <pre>
wolffd@0	1087
wolffd@0	1088 if ((color=gdImageColorExact(im,R,G,B)) < 0)
wolffd@0	1089 if ((color=gdImageColorAllocate(im,R,G,B)) < 0)
wolffd@0	1090 color=gdImageColorClosest(im,R,G,B);
wolffd@0	1091 </pre>
wolffd@0	1092 </ul>
wolffd@0	1093 <p>
wolffd@0	1094 Also in this release the build process has been converted to
wolffd@0	1095 GNU autoconf/automake/libtool conventions so that both (or either)
wolffd@0	1096 static and shared libraries can be built.
wolffd@0	1097 <P><A NAME="whatsnew1.6.1"><H3>What's new in version 1.6.1?</H3></A>
wolffd@0	1098 Version 1.6.1 incorporates superior PNG reading and writing code
wolffd@0	1099 from Greg Roelofs, with minor modifications by Tom Boutell.
wolffd@0	1100 Specifically, I altered his code to read non-palette images
wolffd@0	1101 (converting them to palette images badly, by dithering them),
wolffd@0	1102 and to tolerate palette images with types of transparency that
wolffd@0	1103 gd doesn't actually support (it just ignores the advanced
wolffd@0	1104 transparency features). Any bugs in this area are therefore my
wolffd@0	1105 fault, not Greg's.
wolffd@0	1106 <p>
wolffd@0	1107 Unlike gd 1.6, users should have no trouble linking with
wolffd@0	1108 gd 1.6.1 if they follow the instructions and install all of
wolffd@0	1109 the pieces. However, <strong>If you get undefined symbol errors,
wolffd@0	1110 be sure to check for older versions of libpng in your
wolffd@0	1111 library directories!</strong>
wolffd@0	1112 <P><A NAME="whatsnew1.6"><H3>What's new in version 1.6?</H3></A>
wolffd@0	1113 Version 1.6 features the following changes:
wolffd@0	1114 <p>
wolffd@0	1115 <strong>Support for 8-bit palette PNG images has been added.
wolffd@0	1116 Support for GIF has been removed.</strong> This step was taken
wolffd@0	1117 to completely avoid the legal controversy regarding the LZW
wolffd@0	1118 compression algorithm used in GIF. Unisys holds a patent which
wolffd@0	1119 is relevant to LZW compression. PNG is a superior image format
wolffd@0	1120 in any case. Now that PNG is supported by both Microsoft
wolffd@0	1121 Internet Explorer and Netscape (in their recent releases),
wolffd@0	1122 we highly recommend that GD users upgrade in order to get
wolffd@0	1123 well-compressed images in a format which is legally unemcumbered.
wolffd@0	1124
wolffd@0	1125 <P><A NAME="whatsnew1.5"><H3>What's new in version 1.5?</H3></A>
wolffd@0	1126
wolffd@0	1127 Version 1.5 featured the following changes:
wolffd@0	1128
wolffd@0	1129 <dl>
wolffd@0	1130 <dt><b>New GD2 format</b>
wolffd@0	1131 <dd> An improvement over the GD format, the GD2 format uses the zlib
wolffd@0	1132 compression library to compress the image in chunks. This results
wolffd@0	1133 in file sizes comparable to GIFs, with the ability to access parts
wolffd@0	1134 of large images without having to read the entire image into memory.
wolffd@0	1135 <p>
wolffd@0	1136 This format also supports version numbers and rudimentary validity
wolffd@0	1137 checks, so it should be more 'supportable' than the previous GD format.
wolffd@0	1138 <p>
wolffd@0	1139 <dt><b>Re-arranged source files</b>
wolffd@0	1140 <dd> gd.c has been broken into constituant parts: io, gif, gd, gd2 and
wolffd@0	1141 graphics functions are now in separate files.
wolffd@0	1142 <p>
wolffd@0	1143 <dt><b>Extended I/O capabilities.</b>
wolffd@0	1144 <dd> The source/sink feature has been extended to support GD2 file formats (which
wolffd@0	1145 require seek/tell functions; seek must return 1 for success, 0 for failure), and to allow more general non-file I/O.
wolffd@0	1146 <p>
wolffd@0	1147 <dt><b>Better support for Lincoln Stein's Perl Module</b>
wolffd@0	1148 <dd> The new gdImage*Ptr function returns the chosen format stored in a block of memory.
wolffd@0	1149 This can be directly used by the GD perl module.
wolffd@0	1150 <p>
wolffd@0	1151 <dt><b>Added functions</b>
wolffd@0	1152 <dd>gdImageCreateFromGd2Part - allows retrieval of part of an image (good for huge images, like maps),
wolffd@0	1153 <br>gdImagePaletteCopy - Copies a palette from one image to another, doing it's best to match the colors in the target image to the colors in the source palette.
wolffd@0	1154 <br>gdImageGd2, gdImageCreateFromGd2 - Support for new format
wolffd@0	1155 <br>gdImageCopyMerge - Merges two images (useful to highlight part of an image)
wolffd@0	1156 <br>gdImageCopyMergeGray - Similar to gdImageCopyMerge, but tries to preserve source image hue.
wolffd@0	1157 <br>gdImagePngPtr, gdImageJpegPtr, gdImageWBMPPtr, gdImageGdPtr, gdImageGd2Ptr - return memory blocks for each type of image.
wolffd@0	1158 <br>gdImageCreateFromPngCtx, gdImageCreateFromGdCtx, gdImageCreateFromGd2Ctx, gdImageCreateFromGd2PartCtx - Support for new I/O context.
wolffd@0	1159
wolffd@0	1160 </dl>
wolffd@0	1161
wolffd@0	1162 <b>NOTE:</b> In fairness to Thomas Boutell, any bug/problems with any of the above features should
wolffd@0	1163 probably be reported to <a href=mailto:pjw@rhyme.com.au>Philip Warner</a>.
wolffd@0	1164
wolffd@0	1165 <P><A NAME="whatsnew1.4"><H3>What's new in version 1.4?</H3></A>
wolffd@0	1166
wolffd@0	1167 Version 1.4 features the following changes:
wolffd@0	1168 <dl>
wolffd@0	1169 <dt>Fixed polygon fill routine (again)
wolffd@0	1170 <dd>Thanks to Kirsten Schulz, version 1.4 is able to fill
wolffd@0	1171 numerous types of polygons that caused problems with
wolffd@0	1172 previous releases, including version 1.3.
wolffd@0	1173 <dt>Support for alternate data sources
wolffd@0	1174 <dd>Programmers who wish to load a GIF from something other
wolffd@0	1175 than a stdio FILE * stream can use the new
wolffd@0	1176 <a href="#gdImageCreateFromPngSource">gdImageCreateFromPngSource</a> function.
wolffd@0	1177 <dt>Support for alternate data destinations
wolffd@0	1178 <dd>Programmers who wish to write a GIF to something other
wolffd@0	1179 than a stdio FILE * stream can use the new
wolffd@0	1180 <a href="#gdImagePngToSink">gdImagePngToSink</a> function.
wolffd@0	1181 <dt>More tolerant when reading GIFs
wolffd@0	1182 <dd>
wolffd@0	1183 Version 1.4 does not crash when reading certain animated GIFs,
wolffd@0	1184 although it still only reads the first frame. Version 1.4 also has
wolffd@0	1185 overflow testing code to prevent crashes when reading
wolffd@0	1186 damaged GIFs.
wolffd@0	1187 </dl>
wolffd@0	1188 <P><A NAME="whatsnew1.3"><H3>What's new in version 1.3?</H3></A>
wolffd@0	1189 Version 1.3 features the following changes:
wolffd@0	1190 <dl>
wolffd@0	1191 <dt>Non-LZW-based GIF compression code
wolffd@0	1192 <dd>
wolffd@0	1193 Version 1.3 contained GIF compression code that uses simple Run Length
wolffd@0	1194 Encoding instead of LZW compression, while still retaining compatibility
wolffd@0	1195 with normal LZW-based GIF decoders (your browser will still like your GIFs).
wolffd@0	1196 <strong>LZW compression is patented by Unisys. We are currently reevaluating
wolffd@0	1197 the approach taken by gd 1.3. The current release of gd does not support
wolffd@0	1198 this approach. We recommend that you use the current release, and generate
wolffd@0	1199 PNG images.</strong> Thanks to
wolffd@0	1200 Hutchison Avenue Software Corporation for contributing
wolffd@0	1201 the RLE GIF code.
wolffd@0	1202 <dt>8-bit fonts, and 8-bit font support
wolffd@0	1203 <dd>This improves support for European languages. Thanks are due
wolffd@0	1204 to Honza Pazdziora <adelton@informatics.muni.cz> and also to
wolffd@0	1205 Jan Pazdziora <adelton@fi.muni.cz>. Also see the provided bdftogd
wolffd@0	1206 Perl script if you wish to convert fixed-width X11 fonts
wolffd@0	1207 to gd fonts.
wolffd@0	1208 <dt>16-bit font support (no fonts provided)
wolffd@0	1209 <dd>Although no such fonts are provided in the distribution,
wolffd@0	1210 fonts containing more than 256 characters should work if the
wolffd@0	1211 gdImageString16 and gdImageStringUp16 routines are used.
wolffd@0	1212 <dt>Improvements to the "webpng" example/utility
wolffd@0	1213 <dd>The "webpng" utility is now a slightly more useful application. Thanks to
wolffd@0	1214 Brian Dowling for this code.
wolffd@0	1215 <dt>Corrections to the color resolution field of GIF output
wolffd@0	1216 <dd>Thanks to Bruno Aureli.
wolffd@0	1217 <dt>Fixed polygon fills
wolffd@0	1218 <dd>A one-line patch for the infamous polygon fill bug, courtesy
wolffd@0	1219 of Jim Mason. I believe this fix is sufficient. However, if you
wolffd@0	1220 find a situation where polygon fills still fail to behave properly,
wolffd@0	1221 please send code that demonstrates the problem, <em>and</em> a fix if
wolffd@0	1222 you have one. Verifying the fix is important.
wolffd@0	1223 <dt>Row-major, not column-major
wolffd@0	1224 <dd>Internally, gd now represents the array of pixels as
wolffd@0	1225 an array of rows of pixels, rather than an array of columns
wolffd@0	1226 of pixels. This improves the performance of compression and
wolffd@0	1227 decompression routines slightly, because horizontally adjacent
wolffd@0	1228 pixels are now next to each other in memory. <strong>This should
wolffd@0	1229 not affect properly written gd applications, but applications that
wolffd@0	1230 directly manipulate the <code>pixels</code> array will require
wolffd@0	1231 changes.</strong>
wolffd@0	1232 </dl>
wolffd@0	1233 <A NAME="required"><H3>What else do I need to use gd?</H3></A>
wolffd@0	1234 <P>
wolffd@0	1235 To use gd, you will need an ANSI C compiler. <strong>All popular
wolffd@0	1236 Windows 95 and NT C compilers are ANSI C compliant.</strong> Any
wolffd@0	1237 full-ANSI-standard C compiler should be adequate. <strong>The cc
wolffd@0	1238 compiler released with SunOS 4.1.3 is not an ANSI C compiler.
wolffd@0	1239 Most Unix users who do not already have gcc should get it.
wolffd@0	1240 gcc is free, ANSI compliant and a de facto industry standard.
wolffd@0	1241 Ask your ISP why it is missing.</strong>
wolffd@0	1242 <P>
wolffd@0	1243 As of version 1.6, you also need the zlib compression library,
wolffd@0	1244 and the libpng library. As of version 1.6.2, you can draw text
wolffd@0	1245 using antialiased TrueType fonts if you also have the libttf
wolffd@0	1246 library installed, but this is not mandatory.
wolffd@0	1247 zlib is available for a variety of platforms from
wolffd@0	1248 <a href="http://www.freesoftware.com/pub/infozip/index.html">the zlib web site</a>.
wolffd@0	1249 libpng is available for a variety of platforms from
wolffd@0	1250 <a href="http://www.cdrom.com/pub/png/">the PNG web site</a>.
wolffd@0	1251
wolffd@0	1252 <P>
wolffd@0	1253 You will also want a PNG viewer, if you do not already have
wolffd@0	1254 one for your system, since you will need a good way to check the
wolffd@0	1255 results of your work. Netscape 4.04 and higher, and Microsoft
wolffd@0	1256 Internet Explorer 4.0 or higher, both support PNG.
wolffd@0	1257 <strong>Not every PNG-compatible viewer supports alpha channel
wolffd@0	1258 transparency,</strong> which is why gd 2.0.2 and above do alpha
wolffd@0	1259 blending in the library by default; it is possible to turn on the
wolffd@0	1260 saving of alpha channel information to the file instead.
wolffd@0	1261 <P>
wolffd@0	1262 <A NAME="getgd"><H3>How do I get gd?</H3></A>
wolffd@0	1263 <h4>Binaries (DLL for Windows programmers):</h4>
wolffd@0	1264 <ul>
wolffd@0	1265 <li><a href="http://www.libgd.org/Downloads">.ZIP File of DLL, Headers, Et Cetera</a>
wolffd@0	1266 <p>
wolffd@0	1267 </ul>
wolffd@0	1268 <h4>Source Code:</h4>
wolffd@0	1269 <ul>
wolffd@0	1270 <li><a href="http://www.libgd.org/Downloads">Gzipped Tar File (Unix)</a>
wolffd@0	1271 <li><a href="http://www.boutell.com/gd/http/gd-2.0.33.tar.gz">.ZIP File of SOURCE CODE (Windows)</a>
wolffd@0	1272 </ul>
wolffd@0	1273 <P>
wolffd@0	1274 <A NAME="buildgd"><H3>How do I build gd?</H3></A>
wolffd@0	1275 <blockquote>
wolffd@0	1276 Win32 DLL users: if you are using MSVC, use the provided batch file
wolffd@0	1277 <code>makemsvcimport.bat</code> to make a bgd.lib import library
wolffd@0	1278 corresponding to the provided bgd.dll. Copy bgd.dll to your
wolffd@0	1279 application directory, or to your Windows sytem directory. In the
wolffd@0	1280 settings of your MSVC project, you <b>MUST</b> choose the
wolffd@0	1281 "multithreaded DLL" library option under "code generation."
wolffd@0	1282 mingw32 and cygwin users can simply link with the provided libbgd.a
wolffd@0	1283 stub library in order to use the DLL.
wolffd@0	1284 </blockquote>
wolffd@0	1285 Building gd From the Source
wolffd@0	1286 <p>
wolffd@0	1287 In order to build gd, you must first unpack the archive you have
wolffd@0	1288 downloaded. If you are not familiar with <code>tar</code> and
wolffd@0	1289 <code>gunzip</code> (Unix) or <code>ZIP</code> (Windows), please
wolffd@0	1290 consult with an experienced user of your system. Sorry, we cannot
wolffd@0	1291 answer questions about basic Internet skills.
wolffd@0	1292 <p>
wolffd@0	1293 Unpacking the archive will produce a directory called "gd-2.0.33".
wolffd@0	1294 <p>
wolffd@0	1295 <h4>For Unix</h4>
wolffd@0	1296 <code>cd</code> to the 2.0.33 directory and type:
wolffd@0	1297 <p>
wolffd@0	1298 <code>./configure</code>
wolffd@0	1299 <P>
wolffd@0	1300 <blockquote>
wolffd@0	1301 <STRONG>NOTE: BY DEFAULT, THE LIBRARY IS INSTALLED IN
wolffd@0	1302 <code>/usr/local/lib</code></strong> and the include files are
wolffd@0	1303 installed in <code>/usr/local/include</code>. IF YOU ARE
wolffd@0	1304 UPGRADING, you may wish to use:
wolffd@0	1305 <pre>
wolffd@0	1306 ./configure --prefix=/usr
wolffd@0	1307 </pre>
wolffd@0	1308 Rather than just <code>./configure</code>, before typing
wolffd@0	1309 <code>make</code> and <code>make install</code>.
wolffd@0	1310 </blockquote>
wolffd@0	1311 <p>
wolffd@0	1312 If all goes well, this will create a Makefile. If all does not go well --
wolffd@0	1313 for instance, if neither the the JPEG nor the PNG and ZLIB libraries
wolffd@0	1314 are found -- you will need to install those libraries, then come back
wolffd@0	1315 and run <code>configure</code> again.
wolffd@0	1316 <p>
wolffd@0	1317 If necessary, make changes to the resulting Makefile. Then,
wolffd@0	1318 type "make". If there are no errors, follow this with "make install".
wolffd@0	1319 Because gd 2.0 and above installs as a shared library, it is necessary to
wolffd@0	1320 install the library properly before running gd-based programs.
wolffd@0	1321 <p>
wolffd@0	1322 If you get errors, type <code>./configure --help</code> for more
wolffd@0	1323 information about the available options. In the unlikely event
wolffd@0	1324 that the GNU autoconf-produced configure script does not work well
wolffd@0	1325 for you, you may wish to try <code>configure.pl</code>, a
wolffd@0	1326 simple Perl script with similar but less complete capabilities.
wolffd@0	1327 If all else fails, try renaming <code>makefile.sample</code>
wolffd@0	1328 to <code>Makefile</code>. However, <code>./configure</code> is
wolffd@0	1329 almost always your best bet.
wolffd@0	1330 <blockquote>
wolffd@0	1331 <h4>For Windows</h4>
wolffd@0	1332 Use the DLL version! See the paragraph at the beginning of this sectino.
wolffd@0	1333 If you really want to compile it yourself for some strange reason, read on.
wolffd@0	1334 <p>
wolffd@0	1335 Create a project using your favorite programming environment.
wolffd@0	1336 Copy all of the gd files to the project directory. Add <code>gd.c</code>
wolffd@0	1337 to your project. Add other source files as appropriate. Learning the
wolffd@0	1338 basic skills of creating projects with your chosen C environment
wolffd@0	1339 is up to you. Alternatively, use the free <code>mingw32</code>
wolffd@0	1340 or <code>cygwin</code> tools, which may prove to be compatible
wolffd@0	1341 with the provided <code>configure</code> script.
wolffd@0	1342 </blockquote>
wolffd@0	1343 <P>
wolffd@0	1344 If you wish to test the library, type "make test" AFTER you have
wolffd@0	1345 successfully executed "make install". This will build
wolffd@0	1346 several test programs, including "gddemo". (Not all of these
wolffd@0	1347 programs are expected to print completely successful messages,
wolffd@0	1348 depending on the nature of the image formats with which some of
wolffd@0	1349 the tests are tried; for instance, WBMP is a black and white
wolffd@0	1350 format, so loss of color information is expected there.)
wolffd@0	1351 Run gddemo to see some of the capabilities of gd. Run
wolffd@0	1352 gdtestft to play with the freetype support, if you have built
wolffd@0	1353 gd with it and have access to truetype fonts.
wolffd@0	1354 <P>
wolffd@0	1355 gddemo should execute without incident, creating the file
wolffd@0	1356 demoout.png. (Note there is also a file named demoin.png,
wolffd@0	1357 which is provided in the package as part of the demonstration.)
wolffd@0	1358 <P>
wolffd@0	1359 Display demoout.png in your PNG viewer. The image should
wolffd@0	1360 be 128x128 pixels and should contain an image of the
wolffd@0	1361 space shuttle with quite a lot of graphical elements drawn
wolffd@0	1362 on top of it.
wolffd@0	1363 <P>
wolffd@0	1364 (If you are missing the demoin.png file, the other items
wolffd@0	1365 should appear anyway.)
wolffd@0	1366 <P>
wolffd@0	1367 Look at demoin.png to see the original space shuttle
wolffd@0	1368 image which was scaled and copied into the output image.
wolffd@0	1369 <P>
wolffd@0	1370 <A NAME="basics"><H3>gd basics: using gd in your program</H3></A>
wolffd@0	1371 gd lets you create PNG or JPEG images on the fly. To use gd in your
wolffd@0	1372 program, include the file gd.h, and link with the gd
wolffd@0	1373 library and the other required libraries; the syntax for
wolffd@0	1374 most Unix flavors is:
wolffd@0	1375 <pre>
wolffd@0	1376 -lgd -lpng -lz -ljpeg -lfreetype -lm
wolffd@0	1377 </pre>
wolffd@0	1378 Assuming that all of these libraries are available.
wolffd@0	1379 <P>
wolffd@0	1380 If you want to use the provided simple fonts, include
wolffd@0	1381 gdfontt.h, gdfonts.h, gdfontmb.h, gdfontl.h and/or gdfontg.h. For
wolffd@0	1382 more impressive results, install FreeType 2.x and use the
wolffd@0	1383 <a href="#gdImageStringFT">gdImageStringFT</a>
wolffd@0	1384 function. If you are not using the provided Makefile and/or a
wolffd@0	1385 library-based approach, be sure to include the source modules as well in your
wolffd@0	1386 project. (They may be too large for 16-bit memory models,
wolffd@0	1387 that is, 16-bit DOS and Windows.)
wolffd@0	1388 <P>
wolffd@0	1389 Here is a short example program. <strong>(For a more advanced example,
wolffd@0	1390 see gddemo.c, included in the distribution. gddemo.c is NOT the same program;
wolffd@0	1391 it demonstrates additional features!)</strong>
wolffd@0	1392 <P>
wolffd@0	1393 <PRE>
wolffd@0	1394 /* Bring in gd library functions */
wolffd@0	1395 #include "gd.h"
wolffd@0	1396
wolffd@0	1397 /* Bring in standard I/O so we can output the PNG to a file */
wolffd@0	1398 #include <stdio.h>
wolffd@0	1399
wolffd@0	1400 int main() {
wolffd@0	1401 /* Declare the image */
wolffd@0	1402 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	1403 /* Declare output files */
wolffd@0	1404 FILE pngout, jpegout;
wolffd@0	1405 /* Declare color indexes */
wolffd@0	1406 int black;
wolffd@0	1407 int white;
wolffd@0	1408
wolffd@0	1409 /* Allocate the image: 64 pixels across by 64 pixels tall */
wolffd@0	1410 im = <A HREF="#gdImageCreate">gdImageCreate</A>(64, 64);
wolffd@0	1411
wolffd@0	1412 /* Allocate the color black (red, green and blue all minimum).
wolffd@0	1413 Since this is the first color in a new image, it will
wolffd@0	1414 be the background color. */
wolffd@0	1415 black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
wolffd@0	1416
wolffd@0	1417 /* Allocate the color white (red, green and blue all maximum). */
wolffd@0	1418 white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
wolffd@0	1419
wolffd@0	1420 /* Draw a line from the upper left to the lower right,
wolffd@0	1421 using white color index. */
wolffd@0	1422 <A HREF="#gdImageLine">gdImageLine</A>(im, 0, 0, 63, 63, white);
wolffd@0	1423
wolffd@0	1424 /* Open a file for writing. "wb" means "write binary", important
wolffd@0	1425 under MSDOS, harmless under Unix. */
wolffd@0	1426 pngout = fopen("test.png", "wb");
wolffd@0	1427
wolffd@0	1428 /* Do the same for a JPEG-format file. */
wolffd@0	1429 jpegout = fopen("test.jpg", "wb");
wolffd@0	1430
wolffd@0	1431 /* Output the image to the disk file in PNG format. */
wolffd@0	1432 <A HREF="#gdImagePng">gdImagePng</A>(im, pngout);
wolffd@0	1433
wolffd@0	1434 /* Output the same image in JPEG format, using the default
wolffd@0	1435 JPEG quality setting. */
wolffd@0	1436 <A HREF="#gdImageJpeg">gdImageJpeg</A>(im, jpegout, -1);
wolffd@0	1437
wolffd@0	1438 /* Close the files. */
wolffd@0	1439 fclose(pngout);
wolffd@0	1440 fclose(jpegout);
wolffd@0	1441
wolffd@0	1442 /* Destroy the image in memory. */
wolffd@0	1443 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	1444 }
wolffd@0	1445 </PRE>
wolffd@0	1446 When executed, this program creates an image, allocates
wolffd@0	1447 two colors (the first color allocated becomes the background
wolffd@0	1448 color), draws a diagonal line (note that 0, 0 is the upper
wolffd@0	1449 left corner), writes the image to PNG and JPEG files, and
wolffd@0	1450 destroys the image.
wolffd@0	1451 <P>
wolffd@0	1452 The above example program should
wolffd@0	1453 give you an idea of how the package works.
wolffd@0	1454 gd provides many additional functions, which are listed
wolffd@0	1455 in the following reference chapters, complete with code
wolffd@0	1456 snippets demonstrating each. There is also an
wolffd@0	1457 <A HREF="#index">alphabetical index</A>.
wolffd@0	1458 <H3><A NAME="webpng">Webpng: a more powerful gd example</A></H3>
wolffd@0	1459 Webpng is a simple utility program to manipulate PNGs from the
wolffd@0	1460 command line. It is written for Unix and similar command-line
wolffd@0	1461 systems, but should be easily adapted for other environments.
wolffd@0	1462 Webpng allows you to set transparency and interlacing and
wolffd@0	1463 output interesting information about the PNG in question.
wolffd@0	1464 <P>
wolffd@0	1465 webpng.c is provided in the distribution. Unix users can
wolffd@0	1466 simply type "make webpng" to compile the program. Type
wolffd@0	1467 "webpng" with no arguments to see the available options.
wolffd@0	1468 <H2><A NAME="reference">Function and type reference</A></H2>
wolffd@0	1469 <UL>
wolffd@0	1470 <LI><A HREF="#types">Types</A></LI>
wolffd@0	1471 <LI><A HREF="#creating">Image creation, destruction, loading and saving</A></LI>
wolffd@0	1472 <LI><A HREF="#drawing">Drawing, styling, brushing, tiling and
wolffd@0	1473 filling functions</A></LI>
wolffd@0	1474 <LI><A HREF="#query">Query functions (not color-related)</A></LI>
wolffd@0	1475 <LI><A HREF="#fonts">Font and text-handling functions</A></LI>
wolffd@0	1476 <LI><A HREF="#colors">Color handling functions</A></LI>
wolffd@0	1477 <LI><A HREF="#copying">Copying, resizing, rotating, deformation and filter
wolffd@0	1478 functions</A></LI>
wolffd@0	1479 <LI><A HREF="#misc">Miscellaneous Functions</A></LI>
wolffd@0	1480 <LI><A HREF="#constants">Constants</A></LI>
wolffd@0	1481 </UL>
wolffd@0	1482 <H3><A NAME="types">Types</A></H3>
wolffd@0	1483 <DL>
wolffd@0	1484 <DT><A NAME="gdImage"><code>gdImage</code><strong>(TYPE)</strong></A>
wolffd@0	1485 <DD>
wolffd@0	1486 The data structure in which gd stores images. <A HREF="#gdImageCreate">
wolffd@0	1487 gdImageCreate</A>, <a href="#gdImageCreateTrueColor">gdImageCreateTrueColor</a>
wolffd@0	1488 and the various image file-loading functions return
wolffd@0	1489 a pointer to this type, and the other functions expect to receive
wolffd@0	1490 a pointer to this type as their first argument. It is reasonably safe to
wolffd@0	1491 examine any of the members of this structure. It is also reasonably
wolffd@0	1492 safe to modify individual pixels within the <code>pixels</code>
wolffd@0	1493 or <code>tpixels</code> arrays. If the <code>trueColor</code> flag
wolffd@0	1494 is set, the <code>tpixels</code> array is valid; otherwise the
wolffd@0	1495 <code>pixels</code> array is valid.
wolffd@0	1496 <p>
wolffd@0	1497 The <code>colorsTotal</code>, <code>red</code>, <code>green</code>,
wolffd@0	1498 <code>blue</code>, <code>alpha</code> and <code>open</code> arrays
wolffd@0	1499 manage the palette. They are valid only when the <code>trueColor</code>
wolffd@0	1500 flag is not set.
wolffd@0	1501 The <code>transparent</code> value contains the palette index of the first
wolffd@0	1502 transparent color as read-only information for backwards compatibility;
wolffd@0	1503 gd 2.0 stores this information in the <code>alpha</code> array so that
wolffd@0	1504 variable transparency can be supported for each palette entry. However,
wolffd@0	1505 for truecolor images, <code>transparent</code> represents a single
wolffd@0	1506 RGB color which is <strong>always 100% transparent</strong>, and this
wolffd@0	1507 feature is generally supported by browsers which do not support
wolffd@0	1508 full alpha channels.
wolffd@0	1509 <PRE>
wolffd@0	1510 typedef struct {
wolffd@0	1511 /* Palette-based image pixels */
wolffd@0	1512 unsigned char ** pixels;
wolffd@0	1513 int sx;
wolffd@0	1514 int sy;
wolffd@0	1515 /* These are valid in palette images only. See also
wolffd@0	1516 /* 'alpha', which appears later in the structure to
wolffd@0	1517 preserve binary backwards compatibility */
wolffd@0	1518 int colorsTotal;
wolffd@0	1519 int red[gdMaxColors];
wolffd@0	1520 int green[gdMaxColors];
wolffd@0	1521 int blue[gdMaxColors];
wolffd@0	1522 int open[gdMaxColors];
wolffd@0	1523 /* For backwards compatibility, this is set to the
wolffd@0	1524 first palette entry with 100% transparency,
wolffd@0	1525 and is also set and reset by the
wolffd@0	1526 gdImageColorTransparent function. Newer
wolffd@0	1527 applications can allocate palette entries
wolffd@0	1528 with any desired level of transparency; however,
wolffd@0	1529 bear in mind that many viewers, notably
wolffd@0	1530 many web browsers, fail to implement
wolffd@0	1531 full alpha channel for PNG and provide
wolffd@0	1532 support for full opacity or transparency only. */
wolffd@0	1533 int transparent;
wolffd@0	1534 int *polyInts;
wolffd@0	1535 int polyAllocated;
wolffd@0	1536 struct gdImageStruct *brush;
wolffd@0	1537 struct gdImageStruct *tile;
wolffd@0	1538 int brushColorMap[gdMaxColors];
wolffd@0	1539 int tileColorMap[gdMaxColors];
wolffd@0	1540 int styleLength;
wolffd@0	1541 int stylePos;
wolffd@0	1542 int *style;
wolffd@0	1543 int interlace;
wolffd@0	1544 /* New in 2.0: alpha channel for palettes. Note that only
wolffd@0	1545 Macintosh Internet Explorer and (possibly) Netscape 6
wolffd@0	1546 really support multiple levels of transparency in
wolffd@0	1547 palettes, to my knowledge, as of 2/15/01. Most
wolffd@0	1548 common browsers will display 100% opaque and
wolffd@0	1549 100% transparent correctly, and do something
wolffd@0	1550 unpredictable and/or undesirable for levels
wolffd@0	1551 in between. TBB */
wolffd@0	1552 int alpha[gdMaxColors];
wolffd@0	1553 /* Truecolor flag and pixels. New 2.0 fields appear here at the
wolffd@0	1554 end to minimize breakage of existing object code. */
wolffd@0	1555 int trueColor;
wolffd@0	1556 int ** tpixels;
wolffd@0	1557 /* Should alpha channel be copied, or applied, each time a
wolffd@0	1558 pixel is drawn? This applies to truecolor images only.
wolffd@0	1559 No attempt is made to alpha-blend in palette images,
wolffd@0	1560 even if semitransparent palette entries exist.
wolffd@0	1561 To do that, build your image as a truecolor image,
wolffd@0	1562 then quantize down to 8 bits. */
wolffd@0	1563 int alphaBlendingFlag;
wolffd@0	1564 /* Should the alpha channel of the image be saved? This affects
wolffd@0	1565 PNG at the moment; other future formats may also
wolffd@0	1566 have that capability. JPEG doesn't. */
wolffd@0	1567 int saveAlphaFlag;
wolffd@0	1568 } gdImage;
wolffd@0	1569 </PRE>
wolffd@0	1570 <p>
wolffd@0	1571 The order of the structure members may appear confusing, but was chosen
wolffd@0	1572 deliberately to increase backwards compatibility with existing gd 1.x-based
wolffd@0	1573 binary code that references particular structure members.
wolffd@0	1574 <DT><A NAME="gdImagePtr">gdImagePtr</A> <strong>(TYPE)</strong>
wolffd@0	1575 <DD>
wolffd@0	1576 A pointer to an image structure. <A HREF="#gdImageCreate">gdImageCreate</A>
wolffd@0	1577 returns this type, and the other functions expect it as the first
wolffd@0	1578 argument.
wolffd@0	1579 <DT><A NAME="gdIoCtx">gdIOCtx</a> <strong>(TYPE)</strong>
wolffd@0	1580 <DD>
wolffd@0	1581 Most of the gd functions that read and write files, such as
wolffd@0	1582 <a href="#gdImagePng">gdImagePng</a> and <a href="#gdImageCreateFromJpeg"></a>,
wolffd@0	1583 also have variants that accept a gdIOCtx structure; see
wolffd@0	1584 <a href="#gdImagePngCtx">gdImagePngCtx</a> and
wolffd@0	1585 <a href="#gdImageCreateFromJpegCtx">gdImageCreateFromJpegCtx</a>. Those who wish to provide
wolffd@0	1586 their own custom routines to read and write images can populate a
wolffd@0	1587 gdIOCtx structure with functions of their own devising to
wolffd@0	1588 to read and write data. For image reading, the only mandatory
wolffd@0	1589 functions are getC and getBuf, which must return the number of
wolffd@0	1590 characters actually read, or a negative value on error or EOF.
wolffd@0	1591 These functions must read the number of characters requested
wolffd@0	1592 unless at the end of the file. For image writing, the only mandatory
wolffd@0	1593 functions are putC and putBuf, which return the number of
wolffd@0	1594 characters written; these functions must write the number of
wolffd@0	1595 characters requested except in the event of an error. The seek
wolffd@0	1596 and tell functions are only required in conjunction with the
wolffd@0	1597 <code>gd2</code> file format, which supports quick loading of
wolffd@0	1598 partial images. The gd_free function will not be invoked when
wolffd@0	1599 calling the standard Ctx functions; it is an implementation
wolffd@0	1600 convenience when adding new data types to gd. For examples,
wolffd@0	1601 see gd_png.c, gd_gd2.c, gd_jpeg.c, etc., all of which rely
wolffd@0	1602 on gdIOCtx to implement the standard image read and write functions.
wolffd@0	1603
wolffd@0	1604 <pre>
wolffd@0	1605 typedef struct gdIOCtx
wolffd@0	1606 {
wolffd@0	1607 int (getC) (struct gdIOCtx );
wolffd@0	1608 int (getBuf) (struct gdIOCtx , void *, int wanted);
wolffd@0	1609
wolffd@0	1610 void (putC) (struct gdIOCtx , int);
wolffd@0	1611 int (putBuf) (struct gdIOCtx , const void *, int wanted);
wolffd@0	1612
wolffd@0	1613 /* seek must return 1 on SUCCESS, 0 on FAILURE. Unlike fseek! */
wolffd@0	1614 int (seek) (struct gdIOCtx , const int);
wolffd@0	1615
wolffd@0	1616 long (tell) (struct gdIOCtx );
wolffd@0	1617
wolffd@0	1618 void (gd_free) (struct gdIOCtx );
wolffd@0	1619
wolffd@0	1620 } gdIOCtx;
wolffd@0	1621 </pre>
wolffd@0	1622
wolffd@0	1623
wolffd@0	1624 <DT><A NAME="gdFont">gdFont</A> <strong>(TYPE)</strong>
wolffd@0	1625 <DD>
wolffd@0	1626 A font structure. Used to declare the characteristics of a font.
wolffd@0	1627 Please see the files gdfontl.c and gdfontl.h for an example of the
wolffd@0	1628 proper declaration of this structure. You can provide your
wolffd@0	1629 own font data by providing such a structure and the associated
wolffd@0	1630 pixel array. You can determine the width and height of a single
wolffd@0	1631 character in a font by examining the w and h members of the
wolffd@0	1632 structure. If you will not be creating your own fonts, you will
wolffd@0	1633 not need to concern yourself with the rest of the components of this
wolffd@0	1634 structure.
wolffd@0	1635 <PRE>
wolffd@0	1636 typedef struct {
wolffd@0	1637 /* # of characters in font */
wolffd@0	1638 int nchars;
wolffd@0	1639 /* First character is numbered... (usually 32 = space) */
wolffd@0	1640 int offset;
wolffd@0	1641 /* Character width and height */
wolffd@0	1642 int w;
wolffd@0	1643 int h;
wolffd@0	1644 /* Font data; array of characters, one row after another.
wolffd@0	1645 Easily included in code, also easily loaded from
wolffd@0	1646 data files. */
wolffd@0	1647 char *data;
wolffd@0	1648 } gdFont;
wolffd@0	1649 </PRE>
wolffd@0	1650 <DT><A NAME="gdFontPtr">gdFontPtr</A> <strong>(TYPE)</strong>
wolffd@0	1651 <DD>
wolffd@0	1652 A pointer to a font structure. Text-output functions expect these
wolffd@0	1653 as their second argument, following the <A HREF="#gdImagePtr">
wolffd@0	1654 gdImagePtr</A> argument. Two such pointers are declared in the
wolffd@0	1655 provided include files gdfonts.h and gdfontl.h.
wolffd@0	1656 <DT><A NAME="gdPoint">gdPoint</A> <strong>(TYPE)</strong>
wolffd@0	1657 <DD>
wolffd@0	1658 Represents a point in the coordinate space of the image; used
wolffd@0	1659 by <A HREF="#gdImagePolygon">gdImagePolygon</A>,
wolffd@0	1660 <A HREF="#gdImageOpenPolygon">gdImageOpenPolygon</A> and
wolffd@0	1661 <A HREF="#gdImageFilledPolygon">gdImageFilledPolygon</A>.
wolffd@0	1662 <PRE>
wolffd@0	1663 typedef struct {
wolffd@0	1664 int x, y;
wolffd@0	1665 } gdPoint, *gdPointPtr;
wolffd@0	1666 </PRE>
wolffd@0	1667 <DT><A NAME="gdPointPtr">gdPointPtr</A> <strong>(TYPE)</strong>
wolffd@0	1668 <DD>
wolffd@0	1669 A pointer to a <A HREF="#gdPoint">gdPoint</A> structure; passed
wolffd@0	1670 as an argument to <A HREF="#gdImagePolygon">gdImagePolygon</A>,
wolffd@0	1671 <A HREF="#gdImageOpenPolygon">gdImageOpenPolygon</A>
wolffd@0	1672 and <A HREF="#gdImageFilledPolygon">gdImageFilledPolygon</A>.
wolffd@0	1673 </DL>
wolffd@0	1674 <DT><A NAME="gdFTStringExtra">gdFTStringExtra</a> <strong>(TYPE)</strong>
wolffd@0	1675 <DD>
wolffd@0	1676 A structure used to pass additional parameters to the
wolffd@0	1677 <a href="#gdImageStringFTEx">gdImageStringFTEx</a> function. See
wolffd@0	1678 <a href="#gdImageStringFTEx">gdImageStringFTEx</a> for the
wolffd@0	1679 structure definition.
wolffd@0	1680 </DD>
wolffd@0	1681 <DT><A NAME="gdFTStringExtraPtr">gdFTStringExtraPtr</a> <strong>(TYPE)</strong>
wolffd@0	1682 <DD>
wolffd@0	1683 A pointer to a structure used to pass additional parameters to the
wolffd@0	1684 <a href="#gdImageStringFTEx">gdImageStringFTEx</a> function. See
wolffd@0	1685 <a href="#gdImageStringFTEx">gdImageStringFTEx</a> for the
wolffd@0	1686 structure definition.
wolffd@0	1687 </DD>
wolffd@0	1688 <DT><A NAME="gdSource">gdSource</A> <strong>(TYPE)</strong>
wolffd@0	1689 <DD>
wolffd@0	1690 <pre>
wolffd@0	1691 typedef struct {
wolffd@0	1692 int (source) (void context, char *buffer, int len);
wolffd@0	1693 void *context;
wolffd@0	1694 } gdSource, *gdSourcePtr;
wolffd@0	1695 </pre>
wolffd@0	1696 Represents a source from which a PNG can be read.
wolffd@0	1697 Programmers who do not wish to read PNGs from a file can provide
wolffd@0	1698 their own alternate input mechanism, using the
wolffd@0	1699 <a href="#gdImageCreateFromPngSource">gdImageCreateFromPngSource</a> function.
wolffd@0	1700 See the documentation of that function for an example of the
wolffd@0	1701 proper use of this type.
wolffd@0	1702 <DT><A NAME="gdSink">gdSink</A> <strong>(TYPE)</strong>
wolffd@0	1703 <DD>
wolffd@0	1704 <PRE>
wolffd@0	1705 typedef struct {
wolffd@0	1706 int (sink) (void context, char *buffer, int len);
wolffd@0	1707 void *context;
wolffd@0	1708 } gdSink, *gdSinkPtr;
wolffd@0	1709 </PRE>
wolffd@0	1710 Represents a "sink" (destination) to which a PNG can be written.
wolffd@0	1711 Programmers who do not wish to write PNGs to a file can provide
wolffd@0	1712 their own alternate output mechanism, using the
wolffd@0	1713 <a href="#gdImagePngToSink">gdImagePngToSink</a> function.
wolffd@0	1714 See the documentation of that function for an example of the
wolffd@0	1715 proper use of this type.
wolffd@0	1716 <H3><A NAME="creating">Image creation, destruction, loading and saving</A></H3>
wolffd@0	1717 <DL>
wolffd@0	1718 <DT><A NAME="gdImageCreate">gdImageCreate(sx, sy)</A>
wolffd@0	1719 <strong>(FUNCTION)</strong>
wolffd@0	1720 <DD>
wolffd@0	1721 gdImageCreate is called to create palette-based images, with no
wolffd@0	1722 more than 256 colors. Invoke gdImageCreate
wolffd@0	1723 with the x and y dimensions of the desired image. gdImageCreate
wolffd@0	1724 returns a <A HREF="#gdImagePtr">gdImagePtr</A> to the new image, or
wolffd@0	1725 NULL if unable to
wolffd@0	1726 allocate the image. The image must eventually be destroyed
wolffd@0	1727 using <A HREF="#gdImageDestroy">gdImageDestroy()</A>.
wolffd@0	1728 <PRE>
wolffd@0	1729 ... inside a function ...
wolffd@0	1730 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	1731 im = gdImageCreate(64, 64);
wolffd@0	1732 /* ... Use the image ... */
wolffd@0	1733 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	1734 </PRE>
wolffd@0	1735 <DT><A NAME="gdImageCreateTrueColor">gdImageCreateTrueColor(sx, sy)</A>
wolffd@0	1736 <strong>(FUNCTION)</strong>
wolffd@0	1737 <DD>
wolffd@0	1738 gdImageCreateTrueColor is called to create truecolor images, with
wolffd@0	1739 an essentially unlimited number of colors. Invoke gdImageCreateTrueColor
wolffd@0	1740 with the x and y dimensions of the desired image. gdImageCreateTrueColor
wolffd@0	1741 returns a <A HREF="#gdImagePtr">gdImagePtr</A> to the new image, or
wolffd@0	1742 NULL if unable to
wolffd@0	1743 allocate the image. The image must eventually be destroyed
wolffd@0	1744 using <A HREF="#gdImageDestroy">gdImageDestroy()</A>.
wolffd@0	1745 <p>
wolffd@0	1746 Truecolor images are always filled with black at creation time.
wolffd@0	1747 There is no concept of a "background" color index.
wolffd@0	1748 <PRE>
wolffd@0	1749 ... inside a function ...
wolffd@0	1750 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	1751 im = gdImageCreateTrueColor(64, 64);
wolffd@0	1752 /* ... Use the image ... */
wolffd@0	1753 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	1754 </PRE>
wolffd@0	1755 <DT><A NAME="gdImageCreateFromJpeg">gdImageCreateFromJpeg(FILE *in)</A>
wolffd@0	1756 <strong>(FUNCTION)</strong>
wolffd@0	1757 <br>
wolffd@0	1758 <A NAME="gdImageCreateFromJpegPtr">gdImageCreateFromJpegPtr(int size, void *data)</A>
wolffd@0	1759 <strong>(FUNCTION)</strong>
wolffd@0	1760 <br>
wolffd@0	1761 <A NAME="gdImageCreateFromJpegCtx">gdImageCreateFromJpegCtx(gdIOCtx *in)</A>
wolffd@0	1762 <strong>(FUNCTION)</strong>
wolffd@0	1763 <p>
wolffd@0	1764 <DD>
wolffd@0	1765 gdImageCreateFromJpeg is called to load truecolor images from JPEG format files.
wolffd@0	1766 Invoke gdImageCreateFromJpeg with an already opened pointer to a file
wolffd@0	1767 containing the desired image.
wolffd@0	1768 gdImageCreateFromJpeg
wolffd@0	1769 returns a <A HREF="#gdImagePtr">gdImagePtr</A> to the new
wolffd@0	1770 truecolor image, or NULL
wolffd@0	1771 if unable to load the image (most often because the file is corrupt or
wolffd@0	1772 does not contain a JPEG image). gdImageCreateFromJpeg does <em>not</em>
wolffd@0	1773 close the file. You can inspect the sx and sy members of the
wolffd@0	1774 image to determine its size. The image must eventually be destroyed
wolffd@0	1775 using <A HREF="#gdImageDestroy">gdImageDestroy()</A>. <strong>The
wolffd@0	1776 returned image is always a truecolor image.</strong>
wolffd@0	1777 <p>
wolffd@0	1778 If you already have the
wolffd@0	1779 image file in memory, pass the size of the file and a pointer to the
wolffd@0	1780 file's data to gdImageCreateFromJpegPtr, which is otherwise identical
wolffd@0	1781 to gdImageCreateFromJpeg.
wolffd@0	1782 <p>
wolffd@0	1783 <PRE>
wolffd@0	1784 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	1785 ... inside a function ...
wolffd@0	1786 FILE *in;
wolffd@0	1787 in = fopen("myjpeg.jpg", "rb");
wolffd@0	1788 im = gdImageCreateFromJpeg(in);
wolffd@0	1789 fclose(in);
wolffd@0	1790 /* ... Use the image ... */
wolffd@0	1791 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	1792 </PRE>
wolffd@0	1793 <DT><A NAME="gdImageCreateFromPng">gdImageCreateFromPng(FILE *in)</A>
wolffd@0	1794 <strong>(FUNCTION)</strong>
wolffd@0	1795 <BR><A NAME="gdImageCreateFromPngPtr">gdImageCreateFromPngPtr(int size, void *data)</A>
wolffd@0	1796 <strong>(FUNCTION)</strong>
wolffd@0	1797 <BR><A NAME="gdImageCreateFromPngCtx">gdImageCreateFromPngCtx(<a href=#gdioctx>gdIOCtx</a> *in)</A>
wolffd@0	1798 <strong>(FUNCTION)</strong>
wolffd@0	1799 <p>
wolffd@0	1800 <DD>
wolffd@0	1801 gdImageCreateFromPng is called to load images from PNG format files.
wolffd@0	1802 Invoke gdImageCreateFromPng with an already opened pointer to a file
wolffd@0	1803 containing the desired image.
wolffd@0	1804 gdImageCreateFromPng
wolffd@0	1805 returns a <A HREF="#gdImagePtr">gdImagePtr</A> to the new image, or NULL
wolffd@0	1806 if unable to load the image (most often because the file is corrupt or
wolffd@0	1807 does not contain a PNG image). gdImageCreateFromPng does <em>not</em>
wolffd@0	1808 close the file. You can inspect the sx and sy members of the
wolffd@0	1809 image to determine its size. The image must eventually be destroyed
wolffd@0	1810 using <A HREF="#gdImageDestroy">gdImageDestroy()</A>.
wolffd@0	1811 <p>
wolffd@0	1812 If you already have the
wolffd@0	1813 image file in memory, pass the size of the file and a pointer to the
wolffd@0	1814 file's data to gdImageCreateFromPngPtr, which is otherwise identical
wolffd@0	1815 to gdImageCreateFromPng.
wolffd@0	1816 <p>
wolffd@0	1817 If the PNG image being loaded is a truecolor image, the resulting
wolffd@0	1818 gdImagePtr will refer to a truecolor image. If the PNG image
wolffd@0	1819 being loaded is a palette or grayscale image, the resulting
wolffd@0	1820 gdImagePtr will refer to a palette image. gd retains only 8 bits
wolffd@0	1821 of resolution for each of the red, green and blue channels, and
wolffd@0	1822 only 7 bits of resolution for the alpha channel. The former
wolffd@0	1823 restriction affects only a handful of very rare 48-bit color
wolffd@0	1824 and 16-bit grayscale PNG images. The second restriction affects
wolffd@0	1825 all semitransparent PNG images, but the difference is essentially
wolffd@0	1826 invisible to the eye. 7 bits of alpha channel resolution is,
wolffd@0	1827 in practice, quite a lot.
wolffd@0	1828 <PRE>
wolffd@0	1829 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	1830 ... inside a function ...
wolffd@0	1831 FILE *in;
wolffd@0	1832 in = fopen("mypng.png", "rb");
wolffd@0	1833 im = gdImageCreateFromPng(in);
wolffd@0	1834 fclose(in);
wolffd@0	1835 /* ... Use the image ... */
wolffd@0	1836 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	1837 </PRE>
wolffd@0	1838 <DT><A NAME="gdImageCreateFromPngSource">gdImageCreateFromPngSource(gdSourcePtr in)</A>
wolffd@0	1839 <strong>(FUNCTION)</strong>
wolffd@0	1840 <dd>
wolffd@0	1841 <b>Deprecated</b> in favor of
wolffd@0	1842 <a href="#gdImageCreateFromPngCtx">gdImageCreateFromPngCtx</a>. Should
wolffd@0	1843 not be used in new applications.
wolffd@0	1844 <p>
wolffd@0	1845 gdImageCreateFromPngSource is called to load a PNG from
wolffd@0	1846 a data source other than a file. Usage is very similar to
wolffd@0	1847 the <a href="#gdImageCreateFromPng">gdImageCreateFromPng</a> function,
wolffd@0	1848 except that the programmer provides a custom data source.
wolffd@0	1849 <p>
wolffd@0	1850 The programmer must write an input function which accepts
wolffd@0	1851 a context pointer, a buffer, and a number of bytes to be
wolffd@0	1852 read as arguments. This function must read the number of
wolffd@0	1853 bytes requested, unless the end of the file has been reached,
wolffd@0	1854 in which case the function should return zero, or an error
wolffd@0	1855 has occurred, in which case the function should return
wolffd@0	1856 <code>-1</code>. The programmer then creates a
wolffd@0	1857 <a href="#gdSource">gdSource</a> structure and sets
wolffd@0	1858 the <code>source</code> pointer to the input function and
wolffd@0	1859 the context pointer to any value which is useful to the
wolffd@0	1860 programmer.
wolffd@0	1861 <p>
wolffd@0	1862 The example below
wolffd@0	1863 implements <a href="#gdImageCreateFromPng">gdImageCreateFromPng</a>
wolffd@0	1864 by creating a custom data source and invoking gdImageCreateFromPngSource.
wolffd@0	1865 <pre>
wolffd@0	1866 static int freadWrapper(void context, char buf, int len);
wolffd@0	1867
wolffd@0	1868 gdImagePtr gdImageCreateFromPng(FILE *in)
wolffd@0	1869 {
wolffd@0	1870 gdSource s;
wolffd@0	1871 s.source = freadWrapper;
wolffd@0	1872 s.context = in;
wolffd@0	1873 return gdImageCreateFromPngSource(&s);
wolffd@0	1874 }
wolffd@0	1875
wolffd@0	1876 static int freadWrapper(void context, char buf, int len)
wolffd@0	1877 {
wolffd@0	1878 int got = fread(buf, 1, len, (FILE *) context);
wolffd@0	1879 return got;
wolffd@0	1880 }
wolffd@0	1881 </pre>
wolffd@0	1882 <DT><A NAME="gdImageCreateFromGif">gdImageCreateFromGif(FILE *in)</A>
wolffd@0	1883 <strong>(FUNCTION)</strong>
wolffd@0	1884 <BR><A NAME="gdImageCreateFromGifPtr">gdImageCreateFromGifPtr(int size, void *data)</A>
wolffd@0	1885 <strong>(FUNCTION)</strong>
wolffd@0	1886 <BR><A NAME="gdImageCreateFromGifCtx">gdImageCreateFromGifCtx(<a href=#gdioctx>gdIOCtx</a> *in)</A>
wolffd@0	1887 <strong>(FUNCTION)</strong>
wolffd@0	1888 <p>
wolffd@0	1889 <DD>
wolffd@0	1890 gdImageCreateFromGif is called to load images from GIF format files.
wolffd@0	1891 Invoke gdImageCreateFromGif with an already opened pointer to a file
wolffd@0	1892 containing the desired image.
wolffd@0	1893 gdImageCreateFromGif
wolffd@0	1894 returns a <A HREF="#gdImagePtr">gdImagePtr</A> to the new image, or NULL
wolffd@0	1895 if unable to load the image (most often because the file is corrupt or
wolffd@0	1896 does not contain a GIF image). gdImageCreateFromGif does <em>not</em>
wolffd@0	1897 close the file. You can inspect the sx and sy members of the
wolffd@0	1898 image to determine its size. The image must eventually be destroyed
wolffd@0	1899 using <A HREF="#gdImageDestroy">gdImageDestroy()</A>.
wolffd@0	1900 <p>
wolffd@0	1901 If you already have the
wolffd@0	1902 image file in memory, pass the size of the file and a pointer to the
wolffd@0	1903 file's data to gdImageCreateFromGifPtr, which is otherwise identical
wolffd@0	1904 to gdImageCreateFromGif.
wolffd@0	1905 <PRE>
wolffd@0	1906 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	1907 ... inside a function ...
wolffd@0	1908 FILE *in;
wolffd@0	1909 in = fopen("mygif.gif", "rb");
wolffd@0	1910 im = gdImageCreateFromGif(in);
wolffd@0	1911 fclose(in);
wolffd@0	1912 /* ... Use the image ... */
wolffd@0	1913 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	1914 </PRE>
wolffd@0	1915 <DT><A NAME="gdImageCreateFromGd">gdImageCreateFromGd(FILE *in)</A>
wolffd@0	1916 <strong>(FUNCTION)</strong>
wolffd@0	1917 <br><DT><A NAME="gdImageCreateFromGdPtr">gdImageCreateFromGdPtr(int size, void *data)</A>
wolffd@0	1918 <strong>(FUNCTION)</strong>
wolffd@0	1919 <BR><A NAME="gdImageCreateFromGdCtx">gdImageCreateFromGdCtx(<a href=#gdioctx>gdIOCtx</a> *in)</A>
wolffd@0	1920 <strong>(FUNCTION)</strong>
wolffd@0	1921 <p>
wolffd@0	1922 <DD>
wolffd@0	1923 gdImageCreateFromGd is called to load images from gd format files.
wolffd@0	1924 Invoke gdImageCreateFromGd
wolffd@0	1925 with an already opened pointer to a file containing the desired image
wolffd@0	1926 in the <A HREF="#gdformat">gd file format</A>, which is specific to
wolffd@0	1927 gd and intended for very fast loading. (It is <em>not</em> intended for
wolffd@0	1928 compression; for compression, use PNG or JPEG.)
wolffd@0	1929 <p>
wolffd@0	1930 If you already have the
wolffd@0	1931 image file in memory, pass the size of the file and a pointer to the
wolffd@0	1932 file's data to gdImageCreateFromGdPtr, which is otherwise identical
wolffd@0	1933 to gdImageCreateFromGd.
wolffd@0	1934 <p>
wolffd@0	1935 gdImageCreateFromGd
wolffd@0	1936 returns a <A HREF="#gdImagePtr">gdImagePtr</A> to the new image, or NULL
wolffd@0	1937 if unable to load the image (most often because the file is corrupt or
wolffd@0	1938 does not contain a gd format image). gdImageCreateFromGd does <em>not</em>
wolffd@0	1939 close the file. You can inspect the sx and sy members of the
wolffd@0	1940 image to determine its size. The image must eventually be destroyed
wolffd@0	1941 using <A HREF="#gdImageDestroy">gdImageDestroy()</A>.
wolffd@0	1942 <PRE>
wolffd@0	1943 ... inside a function ...
wolffd@0	1944 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	1945 FILE *in;
wolffd@0	1946 in = fopen("mygd.gd", "rb");
wolffd@0	1947 im = gdImageCreateFromGd(in);
wolffd@0	1948 fclose(in);
wolffd@0	1949 /* ... Use the image ... */
wolffd@0	1950 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	1951 </PRE>
wolffd@0	1952
wolffd@0	1953 <DT><A NAME="gdImageCreateFromGd2">gdImageCreateFromGd2(FILE *in)</A>
wolffd@0	1954 <strong>(FUNCTION)</strong>
wolffd@0	1955 <br><A NAME="gdImageCreateFromGd2Ptr">gdImageCreateFromGd2Ptr(int size, void *data)</A>
wolffd@0	1956 <strong>(FUNCTION)</strong>
wolffd@0	1957 <BR><A NAME="gdImageCreateFromGd2Ctx">gdImageCreateFromGd2Ctx(<a href=#gdioctx>gdIOCtx</a> *in)</A>
wolffd@0	1958 <strong>(FUNCTION)</strong>
wolffd@0	1959 <p>
wolffd@0	1960
wolffd@0	1961 <DD>
wolffd@0	1962 gdImageCreateFromGd2 is called to load images from gd2 format files.
wolffd@0	1963 Invoke gdImageCreateFromGd2
wolffd@0	1964 with an already opened pointer to a file containing the desired image
wolffd@0	1965 in the <A HREF="#gdformat">gd2 file format</A>, which is specific to
wolffd@0	1966 gd2 and intended for fast loading of parts of large images.
wolffd@0	1967 (It is a compressed format, but generally not as good as maximum
wolffd@0	1968 compression of the entire image would be.)
wolffd@0	1969 <p>
wolffd@0	1970 If you already have the
wolffd@0	1971 image file in memory, pass the size of the file and a pointer to the
wolffd@0	1972 file's data to gdImageCreateFromGd2Ptr, which is otherwise identical
wolffd@0	1973 to gdImageCreateFromGd2.
wolffd@0	1974 <p>
wolffd@0	1975 gdImageCreateFromGd2
wolffd@0	1976 returns a <A HREF="#gdImagePtr">gdImagePtr</A> to the new image, or NULL
wolffd@0	1977 if unable to load the image (most often because the file is corrupt or
wolffd@0	1978 does not contain a gd format image). gdImageCreateFromGd2 does <em>not</em>
wolffd@0	1979 close the file. You can inspect the sx and sy members of the
wolffd@0	1980 image to determine its size. The image must eventually be destroyed
wolffd@0	1981 using <A HREF="#gdImageDestroy">gdImageDestroy()</A>.
wolffd@0	1982 <PRE>
wolffd@0	1983 ... inside a function ...
wolffd@0	1984 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	1985 FILE *in;
wolffd@0	1986 in = fopen("mygd.gd2", "rb");
wolffd@0	1987 im = gdImageCreateFromGd2(in);
wolffd@0	1988 fclose(in);
wolffd@0	1989 /* ... Use the image ... */
wolffd@0	1990 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	1991 </PRE>
wolffd@0	1992
wolffd@0	1993 <DT><A NAME="gdImageCreateFromGd2Part">gdImageCreateFromGd2Part(FILE *in, int srcX, int srcY, int w, int h)</A>
wolffd@0	1994 <strong>(FUNCTION)</strong>
wolffd@0	1995 <br><A NAME="gdImageCreateFromGd2PartPtr">gdImageCreateFromGd2PartPtr(int size, void *data, int srcX, int srcY, int w, int h)</A>
wolffd@0	1996 <strong>(FUNCTION)</strong>
wolffd@0	1997 <BR><A NAME="gdImageCreateFromGd2PartCtx">gdImageCreateFromGd2PartCtx(<a href=#gdioctx>gdIOCtx</a> *in)</A>
wolffd@0	1998 <strong>(FUNCTION)</strong>
wolffd@0	1999 <p>
wolffd@0	2000
wolffd@0	2001 <DD>
wolffd@0	2002 gdImageCreateFromGd2Part is called to load parts of images from <A HREF="#gdformat">gd2 format files</a>.
wolffd@0	2003 Invoked in the same way as <a href=#gdImageCreateFromGd2>gdImageCreateFromGd2</a>,
wolffd@0	2004 but with extra parameters
wolffd@0	2005 indicating the source (x, y) and width/height of the desired image.
wolffd@0	2006 gdImageCreateFromGd2Part returns a <A HREF="#gdImagePtr">gdImagePtr</A> to the
wolffd@0	2007 new image, or NULL if unable to load the image.
wolffd@0	2008 The image must eventually be destroyed using <A HREF="#gdImageDestroy">gdImageDestroy()</A>.
wolffd@0	2009 <p>
wolffd@0	2010 If you already have the image file in memory, you may use
wolffd@0	2011 gdImageCreateFromGd2PartPtr. Pass the size of the image file,
wolffd@0	2012 in bytes, as the first argument and the pointer to the image file data
wolffd@0	2013 as the second argument.
wolffd@0	2014 <p>
wolffd@0	2015 <DT><A NAME="gdImageCreateFromWBMP">gdImageCreateFromWBMP(FILE *in)</A>
wolffd@0	2016 <strong>(FUNCTION)</strong>
wolffd@0	2017 <BR><A NAME="gdImageCreateFromWBMPPtr">gdImageCreateFromWBMPPtr(int size, void *data)</A>
wolffd@0	2018 <strong>(FUNCTION)</strong>
wolffd@0	2019 <BR><A NAME="gdImageCreateFromWBMPCtx">gdImageCreateFromWBMPCtx(<a href=#gdioctx>gdIOCtx</a> *in)</A>
wolffd@0	2020 <strong>(FUNCTION)</strong>
wolffd@0	2021 <p>
wolffd@0	2022 <DD>
wolffd@0	2023 gdImageCreateFromWBMP is called to load images from WBMP format files.
wolffd@0	2024 Invoke gdImageCreateFromWBMP with an already opened pointer to a file
wolffd@0	2025 containing the desired image.
wolffd@0	2026 gdImageCreateFromWBMP
wolffd@0	2027 returns a <A HREF="#gdImagePtr">gdImagePtr</A> to the new image, or NULL
wolffd@0	2028 if unable to load the image (most often because the file is corrupt or
wolffd@0	2029 does not contain a PNG image). gdImageCreateFromWBMP does <em>not</em>
wolffd@0	2030 close the file. You can inspect the sx and sy members of the
wolffd@0	2031 image to determine its size. The image must eventually be destroyed
wolffd@0	2032 using <A HREF="#gdImageDestroy">gdImageDestroy()</A>.
wolffd@0	2033 <p>
wolffd@0	2034 If you already have the
wolffd@0	2035 image file in memory, pass the size of the file and a pointer to the
wolffd@0	2036 file's data to gdImageCreateFromWBMPPtr, which is otherwise identical
wolffd@0	2037 to gdImageCreateFromWBMP.
wolffd@0	2038 <PRE>
wolffd@0	2039 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	2040 ... inside a function ...
wolffd@0	2041 FILE *in;
wolffd@0	2042 in = fopen("mywbmp.wbmp", "rb");
wolffd@0	2043 im = gdImageCreateFromWBMP(in);
wolffd@0	2044 fclose(in);
wolffd@0	2045 /* ... Use the image ... */
wolffd@0	2046 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	2047 </PRE>
wolffd@0	2048 <p>
wolffd@0	2049 <DT><A NAME="gdImageCreateFromXbm">gdImageCreateFromXbm(FILE *in)</A>
wolffd@0	2050 <strong>(FUNCTION)</strong>
wolffd@0	2051 <DD>
wolffd@0	2052 gdImageCreateFromXbm is called to load images from X bitmap format
wolffd@0	2053 files. Invoke gdImageCreateFromXbm
wolffd@0	2054 with an already opened pointer to a file containing the desired image.
wolffd@0	2055 gdImageCreateFromXbm
wolffd@0	2056 returns a <A HREF="#gdImagePtr">gdImagePtr</A> to the new image, or NULL
wolffd@0	2057 if unable to load the image (most often because the file is corrupt or
wolffd@0	2058 does not contain an X bitmap format image). gdImageCreateFromXbm does
wolffd@0	2059 <em>not</em> close the file. You can inspect the sx and sy members of the
wolffd@0	2060 image to determine its size. The image must eventually be destroyed
wolffd@0	2061 using <A HREF="#gdImageDestroy">gdImageDestroy()</A>.
wolffd@0	2062 <PRE>
wolffd@0	2063 ... inside a function ...
wolffd@0	2064 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	2065 FILE *in;
wolffd@0	2066 in = fopen("myxbm.xbm", "rb");
wolffd@0	2067 im = gdImageCreateFromXbm(in);
wolffd@0	2068 fclose(in);
wolffd@0	2069 /* ... Use the image ... */
wolffd@0	2070 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	2071 </PRE>
wolffd@0	2072 <DT><A NAME="gdImageCreateFromXpm">gdImageCreateFromXpm(char *filename)</A>
wolffd@0	2073 <strong>(FUNCTION)</strong>
wolffd@0	2074 <DD>
wolffd@0	2075 gdImageCreateFromXbm is called to load images from XPM X Window System
wolffd@0	2076 color bitmap format files. This function is available only if HAVE_XPM
wolffd@0	2077 is selected in the Makefile and the Xpm library is linked with the
wolffd@0	2078 application. Unlike most gd file functions, the Xpm functions require
wolffd@0	2079 filenames, not file pointers.
wolffd@0	2080 gdImageCreateFromXpm
wolffd@0	2081 returns a <A HREF="#gdImagePtr">gdImagePtr</A> to the new image, or NULL
wolffd@0	2082 if unable to load the image (most often because the file is corrupt or
wolffd@0	2083 does not contain an XPM bitmap format image). You can inspect the sx and sy members of the
wolffd@0	2084 image to determine its size. The image must eventually be destroyed
wolffd@0	2085 using <A HREF="#gdImageDestroy">gdImageDestroy()</A>.
wolffd@0	2086 <PRE>
wolffd@0	2087 ... inside a function ...
wolffd@0	2088 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	2089 FILE *in;
wolffd@0	2090 in = fopen("myxpm.xpm", "rb");
wolffd@0	2091 im = gdImageCreateFromXpm(in);
wolffd@0	2092 fclose(in);
wolffd@0	2093 /* ... Use the image ... */
wolffd@0	2094 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	2095 </PRE>
wolffd@0	2096 <DT><A NAME="gdImageDestroy">gdImageDestroy(gdImagePtr im)</A> <STRONG>(FUNCTION)</STRONG>
wolffd@0	2097 <DD>gdImageDestroy is used to free the memory associated with
wolffd@0	2098 an image. It is important to invoke gdImageDestroy before
wolffd@0	2099 exiting your program or assigning a new image to
wolffd@0	2100 a <A HREF="#gdImagePtr">gdImagePtr</A> variable.
wolffd@0	2101 <PRE>
wolffd@0	2102 ... inside a function ...
wolffd@0	2103 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	2104 im = <A HREF="#gdImageCreate">gdImageCreate</A>(10, 10);
wolffd@0	2105 /* ... Use the image ... */
wolffd@0	2106 /* Now destroy it */
wolffd@0	2107 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	2108 </PRE>
wolffd@0	2109 <DT><A NAME="gdImageJpeg">
wolffd@0	2110 void gdImageJpeg(gdImagePtr im, FILE *out, int quality)</A>
wolffd@0	2111 <STRONG>(FUNCTION)</STRONG><BR>
wolffd@0	2112 <a name="gdImageJpegCtx">void gdImageJpegCtx(gdImagePtr im, gdIOCtx *out, int quality)</A>
wolffd@0	2113 <STRONG>(FUNCTION)</STRONG><BR>
wolffd@0	2114 <DD>
wolffd@0	2115 gdImageJpeg outputs the specified image to the specified
wolffd@0	2116 file in JPEG format. The file must be open for writing. Under MSDOS
wolffd@0	2117 and all versions of Windows, it is important to use "wb" as opposed
wolffd@0	2118 to simply "w" as the mode when opening the file, and under Unix there
wolffd@0	2119 is no penalty for doing so. gdImageJpeg does <em>not</em>
wolffd@0	2120 close the file; your code must do so.
wolffd@0	2121 <P>
wolffd@0	2122 If quality is negative, the default IJG JPEG quality value (which
wolffd@0	2123 should yield a good general quality / size tradeoff for most
wolffd@0	2124 situations) is used. Otherwise, for practical purposes, quality
wolffd@0	2125 should be a value in the range 0-95, higher quality values usually
wolffd@0	2126 implying both higher quality and larger image sizes.
wolffd@0	2127 <P>
wolffd@0	2128 If you have set image interlacing using
wolffd@0	2129 <A HREF="#gdImageInterlace">gdImageInterlace</A>, this function will
wolffd@0	2130 interpret that to mean you wish to output a progressive JPEG. Some
wolffd@0	2131 programs (e.g., Web browsers) can display progressive JPEGs
wolffd@0	2132 incrementally; this can be useful when browsing over a relatively slow
wolffd@0	2133 communications link, for example. Progressive JPEGs can also be
wolffd@0	2134 slightly smaller than sequential (non-progressive) JPEGs.
wolffd@0	2135 <PRE>
wolffd@0	2136 ... inside a function ...
wolffd@0	2137 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	2138 int black, white;
wolffd@0	2139 FILE *out;
wolffd@0	2140 /* Create the image */
wolffd@0	2141 im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
wolffd@0	2142 /* Allocate background */
wolffd@0	2143 white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
wolffd@0	2144 /* Allocate drawing color */
wolffd@0	2145 black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
wolffd@0	2146 /* Draw rectangle */
wolffd@0	2147 <A HREF="#gdImageRectangle">gdImageRectangle</A>(im, 0, 0, 99, 99, black);
wolffd@0	2148 /* Open output file in binary mode */
wolffd@0	2149 out = fopen("rect.jpg", "wb");
wolffd@0	2150 /* Write JPEG using default quality */
wolffd@0	2151 gdImageJpeg(im, out, -1);
wolffd@0	2152 /* Close file */
wolffd@0	2153 fclose(out);
wolffd@0	2154 /* Destroy image */
wolffd@0	2155 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	2156 </PRE>
wolffd@0	2157 <DT><A NAME="gdImageJpegPtr">
wolffd@0	2158 void* gdImageJpegPtr(gdImagePtr im, int *size, int quality)</A>
wolffd@0	2159 <STRONG>(FUNCTION)</STRONG>
wolffd@0	2160 <DD>Identical to gdImageJpeg except that it returns a pointer to a memory
wolffd@0	2161 area with the JPEG data. This memory must be freed by the caller when it is
wolffd@0	2162 no longer needed. <strong>The caller must invoke gdFree(), not free(),
wolffd@0	2163 unless the caller is absolutely certain that the same implementations of
wolffd@0	2164 malloc, free, etc. are used both at library build time and at application
wolffd@0	2165 build time.</strong> The 'size' parameter receives the total size of the block
wolffd@0	2166 of memory.
wolffd@0	2167 <DT><A NAME="gdImageGif">
wolffd@0	2168 void gdImageGif(gdImagePtr im, FILE *out)</A>
wolffd@0	2169 <br>
wolffd@0	2170 <A NAME="gdImageGifCtx">
wolffd@0	2171 void gdImageGifCtx(gdImagePtr im, gdIOCtx *out)</A>
wolffd@0	2172
wolffd@0	2173 <STRONG>(FUNCTION)</STRONG>
wolffd@0	2174 <DD>
wolffd@0	2175 gdImageGif outputs the specified image to the specified
wolffd@0	2176 file in GIF format. The file must be open for writing. Under MSDOS
wolffd@0	2177 and all versions of Windows, it is important to use "wb" as opposed
wolffd@0	2178 to simply "w" as the mode when opening the file, and under Unix there
wolffd@0	2179 is no penalty for doing so. gdImageGif does <em>not</em>
wolffd@0	2180 close the file; your code must do so.
wolffd@0	2181 <p>
wolffd@0	2182 GIF does not support true color; GIF images can contain a maximum
wolffd@0	2183 of 256 colors. If the image to be written is a
wolffd@0	2184 truecolor image, such as those created with
wolffd@0	2185 <a href="#gdImageCreateTrueColor">gdImageCreateTrueColor</a> or loaded
wolffd@0	2186 from a JPEG or a truecolor PNG image file, a palette-based
wolffd@0	2187 temporary image will automatically be created internally using the
wolffd@0	2188 <a href="#gdImageCreatePaletteFromTrueColor">gdImageCreatePaletteFromTrueColor</a> function. The original image pixels are not modified. This conversion
wolffd@0	2189 produces high quality palettes but does require some CPU time. If you are
wolffd@0	2190 regularly converting truecolor to palette in this way, you should consider
wolffd@0	2191 creating your image as a palette-based image in the first place.
wolffd@0	2192 <PRE>
wolffd@0	2193 ... inside a function ...
wolffd@0	2194 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	2195 int black, white;
wolffd@0	2196 FILE *out;
wolffd@0	2197 /* Create the image */
wolffd@0	2198 im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
wolffd@0	2199 /* Allocate background */
wolffd@0	2200 white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
wolffd@0	2201 /* Allocate drawing color */
wolffd@0	2202 black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
wolffd@0	2203 /* Draw rectangle */
wolffd@0	2204 <A HREF="#gdImageRectangle">gdImageRectangle</A>(im, 0, 0, 99, 99, black);
wolffd@0	2205 /* Open output file in binary mode */
wolffd@0	2206 out = fopen("rect.gif", "wb");
wolffd@0	2207 /* Write GIF */
wolffd@0	2208 gdImageGif(im, out);
wolffd@0	2209 /* Close file */
wolffd@0	2210 fclose(out);
wolffd@0	2211 /* Destroy image */
wolffd@0	2212 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	2213 </PRE>
wolffd@0	2214 <DT><A NAME="gdImageGifPtr">
wolffd@0	2215 void* gdImageGifPtr(gdImagePtr im, int *size)</A>
wolffd@0	2216 <STRONG>(FUNCTION)</STRONG>
wolffd@0	2217 <DD>Identical to gdImageGif except that it returns a pointer to a memory
wolffd@0	2218 area with the GIF data. This memory must be freed by the caller when it is
wolffd@0	2219 no longer needed. <strong>The caller must invoke gdFree(), not free(),
wolffd@0	2220 unless the caller is absolutely certain that the same implementations of
wolffd@0	2221 malloc, free, etc. are used both at library build time and at application
wolffd@0	2222 build time.</strong> The 'size' parameter receives the total size of the block
wolffd@0	2223 of memory.
wolffd@0	2224
wolffd@0	2225 <DT><A NAME="gdImageGifAnimBegin">
wolffd@0	2226 void gdImageGifAnimBegin(gdImagePtr im, FILE *out, int GlobalCM, int Loops)</A>
wolffd@0	2227 <br>
wolffd@0	2228 <A NAME="gdImageGifAnimBeginCtx">
wolffd@0	2229 void gdImageGifAnimBeginCtx(gdImagePtr im, gdIOCtx *out, int GlobalCM, int Loops)</A>
wolffd@0	2230
wolffd@0	2231 <STRONG>(FUNCTION)</STRONG>
wolffd@0	2232
wolffd@0	2233 <DD>This function must be called as the first function when creating a
wolffd@0	2234 GIF animation. It writes the correct GIF file headers to selected
wolffd@0	2235 file output, and prepares for frames to be added for the animation.
wolffd@0	2236 The image argument is not used to produce an image frame to the file,
wolffd@0	2237 it is only used to establish the GIF animation frame size, interlacing
wolffd@0	2238 options and the color palette. gdImageGifAnimAdd is used to
wolffd@0	2239 add the first and subsequent frames to the animation, and the animation
wolffd@0	2240 must be terminated by writing a semicolon character (;) to it or by using
wolffd@0	2241 gdImageGifAnimEnd to do that.
wolffd@0	2242 <p>
wolffd@0	2243
wolffd@0	2244 The GlobalCM flag indicates if a global color map (or palette) is used
wolffd@0	2245 in the GIF89A header. A nonzero value specifies that a global color
wolffd@0	2246 map should be used to reduce the size of the animation.
wolffd@0	2247 Of course, if the color maps of
wolffd@0	2248 individual frames differ greatly, a global color map may not be a good idea.
wolffd@0	2249 GlobalCM=1 means write global color map, GlobalCM=0 means do not, and
wolffd@0	2250 GlobalCM=-1 means to do the default, which currently is to use a global
wolffd@0	2251 color map.
wolffd@0	2252
wolffd@0	2253 <p>
wolffd@0	2254
wolffd@0	2255 If Loops is 0 or greater, the Netscape 2.0 extension for animation
wolffd@0	2256 loop count is written. 0 means infinite loop count. -1 means that
wolffd@0	2257 the extension is not added which results in no looping. -1 is the
wolffd@0	2258 default.
wolffd@0	2259
wolffd@0	2260 <DT><A NAME="gdImageGifAnimBeginPtr">
wolffd@0	2261 void* gdImageGifAnimBeginPtr(gdImagePtr im, int *size, int GlobalCM, int Loops)</A>
wolffd@0	2262 <STRONG>(FUNCTION)</STRONG>
wolffd@0	2263 <DD>Identical to gdImageGifAnimBegin except that it returns a pointer
wolffd@0	2264 to a memory area with the GIF data. This memory must be freed by the
wolffd@0	2265 caller when it is no longer needed. <strong>The caller must invoke
wolffd@0	2266 gdFree(), not free(), unless the caller is absolutely certain that the
wolffd@0	2267 same implementations of malloc, free, etc. are used both at library
wolffd@0	2268 build time and at application build time.</strong> The 'size'
wolffd@0	2269 parameter receives the total size of the block of memory.
wolffd@0	2270
wolffd@0	2271 <DT><A NAME="gdImageGifAnimAdd">
wolffd@0	2272 void gdImageGifAnimAdd(gdImagePtr im, FILE *out, int LocalCM, int LeftOfs, int TopOfs, int Delay, int Disposal, gdImagePtr previm)</A>
wolffd@0	2273 <br>
wolffd@0	2274 <A NAME="gdImageGifAnimAddCtx">
wolffd@0	2275 void gdImageGifAnimAddCtx(gdImagePtr im, gdIOCtx *out, int LocalCM, int LeftOfs, int TopOfs, int Delay, int Disposal, gdImagePtr previm)</A>
wolffd@0	2276
wolffd@0	2277 <STRONG>(FUNCTION)</STRONG>
wolffd@0	2278
wolffd@0	2279 <DD> This function writes GIF animation frames to GIF animation, which
wolffd@0	2280 was initialized with <a
wolffd@0	2281 href="#gdImageGifAnimBegin">gdImageGifAnimBegin</a>. With LeftOfs and
wolffd@0	2282 TopOfs you can place this frame in different offset than (0,0) inside
wolffd@0	2283 the image screen as defined in gdImageGifAnimBegin. Delay between the
wolffd@0	2284 previous frame and this frame is in 1/100s units. Disposal is usually
wolffd@0	2285 <code>gdDisposalNone</code>, meaning that the pixels changed by this
wolffd@0	2286 frame should remain on the display when the next frame begins to render, but
wolffd@0	2287 can also be <code>gdDisposalUnknown</code> (not recommended),
wolffd@0	2288 <code>gdDisposalRestoreBackground</code> (restores the first
wolffd@0	2289 allocated color of the global palette), or
wolffd@0	2290 <code>gdDisposalRestorePrevious</code> (restores the appearance of the
wolffd@0	2291 affected area before the frame was rendered). Only
wolffd@0	2292 <code>gdDisposalNone</code> is a sensible choice for the first frame.
wolffd@0	2293 If <code>previm</code> is
wolffd@0	2294 passed, the built-in GIF optimizer will always use <code>gdDisposalNone</code>
wolffd@0	2295 regardless of the Disposal parameter.
wolffd@0	2296 <p>
wolffd@0	2297 Setting the LocalCM flag to 1 adds a local palette for this image to the
wolffd@0	2298 animation. Otherwise the global palette is assumed and the user must make
wolffd@0	2299 sure the palettes match. Use <A HREF="#gdImagePaletteCopy">gdImagePaletteCopy</A> to do that.
wolffd@0	2300
wolffd@0	2301 <p>
wolffd@0	2302
wolffd@0	2303 Automatic optimization is activated by giving the previous image as a
wolffd@0	2304 parameter. This function then compares the images and only writes the changed
wolffd@0	2305 pixels to the new frame in animation. The Disposal parameter for
wolffd@0	2306 optimized animations must be set to 1, also for the first frame.
wolffd@0	2307 LeftOfs and TopOfs parameters are ignored for optimized frames. To
wolffd@0	2308 achieve good optimization, it is usually best to use a single global
wolffd@0	2309 color map. To allow gdImageGifAnimAdd to compress unchanged pixels via
wolffd@0	2310 the use of a transparent color, the image must include a transparent color.
wolffd@0	2311
wolffd@0	2312 <PRE>
wolffd@0	2313 ... inside a function ...
wolffd@0	2314 gdImagePtr im, im2, im3;
wolffd@0	2315 int black, white, trans;
wolffd@0	2316 FILE *out;
wolffd@0	2317 /* Create the image */
wolffd@0	2318 im = gdImageCreate(100, 100);
wolffd@0	2319 /* Allocate background */
wolffd@0	2320 white = gdImageColorAllocate(im, 255, 255, 255);
wolffd@0	2321 /* Allocate drawing color */
wolffd@0	2322 black = gdImageColorAllocate(im, 0, 0, 0);
wolffd@0	2323 /* Allocate transparent color for animation compression */
wolffd@0	2324 trans = gdImageColorAllocate(im, 1, 1, 1);
wolffd@0	2325 /* Draw rectangle */
wolffd@0	2326 gdImageRectangle(im, 0, 0, 10, 10, black);
wolffd@0	2327 /* Open output file in binary mode */
wolffd@0	2328 out = fopen("anim.gif", "wb");
wolffd@0	2329 /* Write GIF header. Use global color map. Loop a few times */
wolffd@0	2330 gdImageGifAnimBegin(im, out, 1, 3);
wolffd@0	2331 /* Write the first frame. No local color map. Delay = 1s */
wolffd@0	2332 gdImageGifAnimAdd(im, out, 0, 0, 0, 100, 1, NULL);
wolffd@0	2333 /* construct the second frame */
wolffd@0	2334 im2 = gdImageCreate(100, 100);
wolffd@0	2335 /* Allocate background to make it white */
wolffd@0	2336 (void)gdImageColorAllocate(im2, 255, 255, 255);
wolffd@0	2337 /* Make sure the palette is identical */
wolffd@0	2338 gdImagePaletteCopy (im2, im);
wolffd@0	2339 /* Draw something */
wolffd@0	2340 gdImageRectangle(im2, 0, 0, 15, 15, black);
wolffd@0	2341 /* Allow animation compression with transparent pixels */
wolffd@0	2342 gdImageColorTransparent (im2, trans);
wolffd@0	2343 /* Add the second frame */
wolffd@0	2344 gdImageGifAnimAdd(im2, out, 0, 0, 0, 100, 1, im);
wolffd@0	2345 /* construct the second frame */
wolffd@0	2346 im3 = gdImageCreate(100, 100);
wolffd@0	2347 /* Allocate background to make it white */
wolffd@0	2348 (void)gdImageColorAllocate(im3, 255, 255, 255);
wolffd@0	2349 /* Make sure the palette is identical */
wolffd@0	2350 gdImagePaletteCopy (im3, im);
wolffd@0	2351 /* Draw something */
wolffd@0	2352 gdImageRectangle(im3, 0, 0, 15, 20, black);
wolffd@0	2353 /* Allow animation compression with transparent pixels */
wolffd@0	2354 gdImageColorTransparent (im3, trans);
wolffd@0	2355 /* Add the third frame, compressing against the second one */
wolffd@0	2356 gdImageGifAnimAdd(im3, out, 0, 0, 0, 100, 1, im2);
wolffd@0	2357 /* Write the end marker */
wolffd@0	2358 /* gdImageGifAnimEnd(out); is the same as the following: */
wolffd@0	2359 putc (';', out);
wolffd@0	2360 /* Close file */
wolffd@0	2361 fclose(out);
wolffd@0	2362 /* Destroy images */
wolffd@0	2363 gdImageDestroy(im);
wolffd@0	2364 gdImageDestroy(im2);
wolffd@0	2365 gdImageDestroy(im3);
wolffd@0	2366 </PRE>
wolffd@0	2367
wolffd@0	2368 <DT><A NAME="gdImageGifAnimAddPtr">
wolffd@0	2369 void* gdImageGifAnimAddPtr(gdImagePtr im, int *size, int LocalCM, int LeftOfs, int TopOfs, int Delay, int Disposal, gdImagePtr previm)</A>
wolffd@0	2370 <STRONG>(FUNCTION)</STRONG>
wolffd@0	2371 <DD>Identical to gdImageGifAnimAdd except that it returns a pointer
wolffd@0	2372 to a memory area with the GIF data. This memory must be freed by the
wolffd@0	2373 caller when it is no longer needed. <strong>The caller must invoke
wolffd@0	2374 gdFree(), not free(), unless the caller is absolutely certain that the
wolffd@0	2375 same implementations of malloc, free, etc. are used both at library
wolffd@0	2376 build time and at application build time.</strong> The 'size'
wolffd@0	2377 parameter receives the total size of the block of memory.
wolffd@0	2378
wolffd@0	2379 <DT><A NAME="gdImageGifAnimEnd">
wolffd@0	2380 void gdImageGifAnimEnd(FILE *out)</A>
wolffd@0	2381 <br>
wolffd@0	2382 <A NAME="gdImageGifAnimEndCtx">
wolffd@0	2383 void gdImageGifAnimEndCtx(gdIOCtx *out)</A>
wolffd@0	2384
wolffd@0	2385 <STRONG>(FUNCTION)</STRONG>
wolffd@0	2386
wolffd@0	2387 <DD>Writes semicolon character (;) to the output file. This
wolffd@0	2388 terminates the GIF file properly. You can omit the call to
wolffd@0	2389 gdImageGifAnimEnd and just print out the semicolon.
wolffd@0	2390
wolffd@0	2391 <DT><A NAME="gdImageGifAnimEndPtr">
wolffd@0	2392 void* gdImageGifAnimEndPtr(int *size)</A>
wolffd@0	2393 <STRONG>(FUNCTION)</STRONG>
wolffd@0	2394
wolffd@0	2395 <DD>Returns a one byte string containing the semicolon character (;).
wolffd@0	2396 Returns a pointer to a memory area with that string. This memory must
wolffd@0	2397 be freed by the caller when it is no longer needed. <strong>The caller
wolffd@0	2398 must invoke gdFree(), not free(), unless the caller is absolutely
wolffd@0	2399 certain that the same implementations of malloc, free, etc. are used
wolffd@0	2400 both at library build time and at application build time.</strong> The
wolffd@0	2401 'size' parameter receives the total size of the block of memory. The
wolffd@0	2402 string ";" can be used in place of this function.
wolffd@0	2403
wolffd@0	2404 <DT><A NAME="gdImagePng">
wolffd@0	2405 void gdImagePng(gdImagePtr im, FILE *out)</A>
wolffd@0	2406 <br>
wolffd@0	2407 <A NAME="gdImagePngCtx">
wolffd@0	2408 void gdImagePngCtx(gdImagePtr im, gdIOCtx *out)</A>
wolffd@0	2409
wolffd@0	2410 <STRONG>(FUNCTION)</STRONG>
wolffd@0	2411 <DD>
wolffd@0	2412 gdImagePng outputs the specified image to the specified
wolffd@0	2413 file in PNG format. The file must be open for writing. Under MSDOS
wolffd@0	2414 and all versions of Windows, it is important to use "wb" as opposed
wolffd@0	2415 to simply "w" as the mode when opening the file, and under Unix there
wolffd@0	2416 is no penalty for doing so. gdImagePng does <em>not</em>
wolffd@0	2417 close the file; your code must do so.
wolffd@0	2418 <PRE>
wolffd@0	2419 ... inside a function ...
wolffd@0	2420 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	2421 int black, white;
wolffd@0	2422 FILE *out;
wolffd@0	2423 /* Create the image */
wolffd@0	2424 im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
wolffd@0	2425 /* Allocate background */
wolffd@0	2426 white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
wolffd@0	2427 /* Allocate drawing color */
wolffd@0	2428 black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
wolffd@0	2429 /* Draw rectangle */
wolffd@0	2430 <A HREF="#gdImageRectangle">gdImageRectangle</A>(im, 0, 0, 99, 99, black);
wolffd@0	2431 /* Open output file in binary mode */
wolffd@0	2432 out = fopen("rect.png", "wb");
wolffd@0	2433 /* Write PNG */
wolffd@0	2434 gdImagePng(im, out);
wolffd@0	2435 /* Close file */
wolffd@0	2436 fclose(out);
wolffd@0	2437 /* Destroy image */
wolffd@0	2438 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	2439 </PRE>
wolffd@0	2440 <DT><A NAME="gdImagePngEx">
wolffd@0	2441 void gdImagePngEx(gdImagePtr im, FILE *out, int level)</A>
wolffd@0	2442 <br>
wolffd@0	2443 <A NAME="gdImagePngCtxEx">
wolffd@0	2444 void gdImagePngCtxEx(gdImagePtr im, gdIOCtx *out, int level)</A>
wolffd@0	2445
wolffd@0	2446 <STRONG>(FUNCTION)</STRONG>
wolffd@0	2447 <DD>
wolffd@0	2448 Like <a href="#gdImagePng">gdImagePng</a>, gdImagePngEx outputs the
wolffd@0	2449 specified image to the specified file in PNG format. In addition,
wolffd@0	2450 gdImagePngEx allows the level of compression to be specified. A compression
wolffd@0	2451 level of 0 means "no compression." A compression level of 1 means
wolffd@0	2452 "compressed, but as quickly as possible." A compression level of 9
wolffd@0	2453 means "compressed as much as possible to produce the smallest possible
wolffd@0	2454 file." A compression level of -1 will use the default compression level
wolffd@0	2455 at the time zlib was compiled on your system.
wolffd@0	2456 <p>
wolffd@0	2457 For more information, see <a href="#gdImagePng">gdImagePng</a>.
wolffd@0	2458 <DT><A NAME="gdImagePngPtr">
wolffd@0	2459 void* gdImagePngPtr(gdImagePtr im, int *size)</A>
wolffd@0	2460 <STRONG>(FUNCTION)</STRONG>
wolffd@0	2461 <DD>Identical to gdImagePng except that it returns a pointer to a memory
wolffd@0	2462 area with the PNG data. This memory must be freed by the caller when it is
wolffd@0	2463 no longer needed. <strong>The caller must invoke gdFree(), not free(),
wolffd@0	2464 unless the caller is absolutely certain that the same implementations of
wolffd@0	2465 malloc, free, etc. are used both at library build time and at application
wolffd@0	2466 build time.</strong> The 'size' parameter receives the total size of the block
wolffd@0	2467 of memory.
wolffd@0	2468 <DT><A NAME="gdImagePngPtrEx">
wolffd@0	2469 void* gdImagePngPtrEx(gdImagePtr im, int *size, int level)</A>
wolffd@0	2470 <STRONG>(FUNCTION)</STRONG>
wolffd@0	2471 <DD>
wolffd@0	2472 Like <a href="#gdImagePngPtr">gdImagePngPtr</a>, gdImagePngPtrEx returns a
wolffd@0	2473 pointer to a PNG image in allocated memory.
wolffd@0	2474 In addition, gdImagePngPtrEx allows the level of compression to be
wolffd@0	2475 specified. A compression level of 0 means "no compression." A compression level of 1 means
wolffd@0	2476 "compressed, but as quickly as possible." A compression level of 9
wolffd@0	2477 means "compressed as much as possible to produce the smallest possible
wolffd@0	2478 file." A compression level of -1 will use the default compression level
wolffd@0	2479 at the time zlib was compiled on your system.
wolffd@0	2480 <p>
wolffd@0	2481 For more information, see <a href="#gdImagePngPtr">gdImagePngPtr</a>.
wolffd@0	2482 <DT><A NAME="gdImagePngToSink">gdImagePngToSink(gdImagePtr im, gdSinkPtr out)</A>
wolffd@0	2483 <strong>(FUNCTION)</strong>
wolffd@0	2484 <dd>
wolffd@0	2485 gdImagePngToSink is called to write a PNG to
wolffd@0	2486 a data "sink" (destination) other than a file. Usage is very similar to
wolffd@0	2487 the <a href="#gdImagePng">gdImagePng</a> function,
wolffd@0	2488 except that the programmer provides a custom data sink.
wolffd@0	2489 <p>
wolffd@0	2490 The programmer must write an output function which accepts
wolffd@0	2491 a context pointer, a buffer, and a number of bytes to be
wolffd@0	2492 written as arguments. This function must write the number of
wolffd@0	2493 bytes requested and return that number, unless an error
wolffd@0	2494 has occurred, in which case the function should return
wolffd@0	2495 <code>-1</code>. The programmer then creates a
wolffd@0	2496 <a href="#gdSink">gdSink</a> structure and sets
wolffd@0	2497 the <code>sink</code> pointer to the output function and
wolffd@0	2498 the context pointer to any value which is useful to the
wolffd@0	2499 programmer.
wolffd@0	2500 <p>
wolffd@0	2501 The example below
wolffd@0	2502 implements <a href="#gdImagePng">gdImagePng</a>
wolffd@0	2503 by creating a custom data source and invoking gdImagePngFromSink.
wolffd@0	2504 <pre>
wolffd@0	2505 static int stdioSink(void context, char buffer, int len)
wolffd@0	2506 {
wolffd@0	2507 return fwrite(buffer, 1, len, (FILE *) context);
wolffd@0	2508 }
wolffd@0	2509
wolffd@0	2510 void gdImagePng(gdImagePtr im, FILE *out)
wolffd@0	2511 {
wolffd@0	2512 gdSink mySink;
wolffd@0	2513 mySink.context = (void *) out;
wolffd@0	2514 mySink.sink = stdioSink;
wolffd@0	2515 gdImagePngToSink(im, &mySink);
wolffd@0	2516 }
wolffd@0	2517 </pre>
wolffd@0	2518 <DT><A NAME="gdImageWBMP">
wolffd@0	2519 void gdImageWBMP(gdImagePtr im, int fg, FILE *out)</A>
wolffd@0	2520 <BR><A NAME="gdImageWBMPCtx">gdImageWBMPCtx(<a href=#gdioctx>gdIOCtx</a> *out)</A>
wolffd@0	2521 <strong>(FUNCTION)</strong><STRONG>(FUNCTION)</STRONG>
wolffd@0	2522 <DD>
wolffd@0	2523 gdImageWBMP outputs the specified image to the specified
wolffd@0	2524 file in WBMP format. The file must be open for writing. Under MSDOS
wolffd@0	2525 and all versions of Windows, it is important to use "wb" as opposed
wolffd@0	2526 to simply "w" as the mode when opening the file, and under Unix there
wolffd@0	2527 is no penalty for doing so. gdImageWBMP does <em>not</em>
wolffd@0	2528 close the file; your code must do so.
wolffd@0	2529 <p>
wolffd@0	2530 <strong>WBMP file support is black and white only. The color index
wolffd@0	2531 specified by the fg argument is the "foreground," and only pixels
wolffd@0	2532 of this color will be set in the WBMP file.</strong> All other pixels
wolffd@0	2533 will be considered "background."
wolffd@0	2534 <PRE>
wolffd@0	2535 ... inside a function ...
wolffd@0	2536 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	2537 int black, white;
wolffd@0	2538 FILE *out;
wolffd@0	2539 /* Create the image */
wolffd@0	2540 im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
wolffd@0	2541 /* Allocate background */
wolffd@0	2542 white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
wolffd@0	2543 /* Allocate drawing color */
wolffd@0	2544 black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
wolffd@0	2545 /* Draw rectangle */
wolffd@0	2546 <A HREF="#gdImageRectangle">gdImageRectangle</A>(im, 0, 0, 99, 99, black);
wolffd@0	2547 /* Open output file in binary mode */
wolffd@0	2548 out = fopen("rect.wbmp", "wb");
wolffd@0	2549 /* Write WBMP, with black as foreground */
wolffd@0	2550 gdImageWBMP(im, black, out);
wolffd@0	2551 /* Close file */
wolffd@0	2552 fclose(out);
wolffd@0	2553 /* Destroy image */
wolffd@0	2554 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	2555 </PRE>
wolffd@0	2556 <DT><A NAME="gdImageWBMPPtr">
wolffd@0	2557 void* gdImageWBMPPtr(gdImagePtr im, int *size)</A>
wolffd@0	2558 <STRONG>(FUNCTION)</STRONG>
wolffd@0	2559 <DD>Identical to gdImageWBMP except that it returns a pointer to a memory
wolffd@0	2560 area with the WBMP data. This memory must be freed by the caller when it is
wolffd@0	2561 no longer needed. <strong>The caller must invoke gdFree(), not free(),
wolffd@0	2562 unless the caller is absolutely certain that the same implementations of
wolffd@0	2563 malloc, free, etc. are used both at library build time and at application
wolffd@0	2564 build time.</strong> The 'size' parameter receives the total size of the block
wolffd@0	2565 of memory.
wolffd@0	2566 <DT><A NAME="gdImageGd">
wolffd@0	2567 void gdImageGd(gdImagePtr im, FILE *out)</A>
wolffd@0	2568 <STRONG>(FUNCTION)</STRONG>
wolffd@0	2569 <DD>
wolffd@0	2570 gdImageGd outputs the specified image to the specified
wolffd@0	2571 file in the <A HREF="#gdformat">gd image format</A>. The file must
wolffd@0	2572 be open for writing. Under MSDOS and all versions of Windows, it is
wolffd@0	2573 important to use "wb" as
wolffd@0	2574 opposed to simply "w" as the mode when opening the file, and under
wolffd@0	2575 Unix there is no penalty for doing so. gdImagePng does <em>not</em>
wolffd@0	2576 close the file; your code must do so.
wolffd@0	2577 <P>
wolffd@0	2578 The gd image format is intended for fast reads and writes of
wolffd@0	2579 images your program will need frequently to build other
wolffd@0	2580 images. It is <em>not</em> a compressed format, and is not intended
wolffd@0	2581 for general use.
wolffd@0	2582 <PRE>
wolffd@0	2583 ... inside a function ...
wolffd@0	2584 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	2585 int black, white;
wolffd@0	2586 FILE *out;
wolffd@0	2587 /* Create the image */
wolffd@0	2588 im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
wolffd@0	2589 /* Allocate background */
wolffd@0	2590 white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
wolffd@0	2591 /* Allocate drawing color */
wolffd@0	2592 black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
wolffd@0	2593 /* Draw rectangle */
wolffd@0	2594 <A HREF="#gdImageRectangle">gdImageRectangle</A>(im, 0, 0, 99, 99, black);
wolffd@0	2595 /* Open output file in binary mode */
wolffd@0	2596 out = fopen("rect.gd", "wb");
wolffd@0	2597 /* Write gd format file */
wolffd@0	2598 gdImageGd(im, out);
wolffd@0	2599 /* Close file */
wolffd@0	2600 fclose(out);
wolffd@0	2601 /* Destroy image */
wolffd@0	2602 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	2603 </PRE>
wolffd@0	2604
wolffd@0	2605 <DT><A NAME="gdImageGdPtr">
wolffd@0	2606 void* gdImageGdPtr(gdImagePtr im, int *size)</A>
wolffd@0	2607 <STRONG>(FUNCTION)</STRONG>
wolffd@0	2608 <DD>Identical to gdImageGd except that it returns a pointer to a memory
wolffd@0	2609 area with the GD data. This memory must be freed by the caller when it is
wolffd@0	2610 no longer needed. <strong>The caller must invoke gdFree(), not free(),
wolffd@0	2611 unless the caller is absolutely certain that the same implementations of
wolffd@0	2612 malloc, free, etc. are used both at library build time and at application
wolffd@0	2613 build time.</strong> The 'size' parameter receives the total size of the block
wolffd@0	2614 of memory.
wolffd@0	2615
wolffd@0	2616 <DT><A NAME="gdImageGd2">
wolffd@0	2617 void gdImageGd2(gdImagePtr im, FILE *out, int chunkSize, int fmt)</A>
wolffd@0	2618 <br>
wolffd@0	2619 <A NAME="gdImageGd2Ctx">
wolffd@0	2620 void gdImageGd2Ctx(gdImagePtr im, gdIOCtx *out, int chunkSize, int fmt)</A>
wolffd@0	2621 <STRONG>(FUNCTION)</STRONG>
wolffd@0	2622 <DD>
wolffd@0	2623 gdImageGd2 outputs the specified image to the specified
wolffd@0	2624 file in the <A HREF="#gd2format">gd2 image format</A>. The file must
wolffd@0	2625 be open for writing. Under MSDOS and all versions of Windows, it is
wolffd@0	2626 important to use "wb" as
wolffd@0	2627 opposed to simply "w" as the mode when opening the file, and under
wolffd@0	2628 Unix there is no penalty for doing so. gdImageGd2 does <em>not</em>
wolffd@0	2629 close the file; your code must do so.
wolffd@0	2630 <P>
wolffd@0	2631 The gd2 image format is intended for fast reads and writes of
wolffd@0	2632 parts of images.
wolffd@0	2633 It is a compressed format, and well suited to retrieving smll sections of
wolffd@0	2634 much larger images.
wolffd@0	2635
wolffd@0	2636 The third and fourth parameters are the 'chunk size' and format resposectively.
wolffd@0	2637 <p>
wolffd@0	2638 The file is stored as a series of compressed subimages, and the
wolffd@0	2639 <strong>Chunk Size</strong> determines the sub-image size - a value of
wolffd@0	2640 zero causes the GD library to use the default.
wolffd@0	2641 <p>
wolffd@0	2642 It is also possible to store GD2 files in an uncompressed format, in which case the
wolffd@0	2643 fourth parameter should be GD2_FMT_RAW.
wolffd@0	2644
wolffd@0	2645 <PRE>
wolffd@0	2646 ... inside a function ...
wolffd@0	2647 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	2648 int black, white;
wolffd@0	2649 FILE *out;
wolffd@0	2650 /* Create the image */
wolffd@0	2651 im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
wolffd@0	2652 /* Allocate background */
wolffd@0	2653 white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
wolffd@0	2654 /* Allocate drawing color */
wolffd@0	2655 black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
wolffd@0	2656 /* Draw rectangle */
wolffd@0	2657 <A HREF="#gdImageRectangle">gdImageRectangle</A>(im, 0, 0, 99, 99, black);
wolffd@0	2658 /* Open output file in binary mode */
wolffd@0	2659 out = fopen("rect.gd", "wb");
wolffd@0	2660 /* Write gd2 format file */
wolffd@0	2661 gdImageGd2(im, out, 0, GD2_FMT_COMPRESSED);
wolffd@0	2662 /* Close file */
wolffd@0	2663 fclose(out);
wolffd@0	2664 /* Destroy image */
wolffd@0	2665 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	2666 </PRE>
wolffd@0	2667
wolffd@0	2668 <DT><A NAME="gdImageGd2Ptr">
wolffd@0	2669 void* gdImageGd2Ptr(gdImagePtr im, int chunkSize, int fmt, int *size)</A>
wolffd@0	2670 <STRONG>(FUNCTION)</STRONG>
wolffd@0	2671 <DD>Identical to gdImageGd2 except that it returns a pointer to a memory
wolffd@0	2672 area with the GD2 data. This memory must be freed by the caller when it is
wolffd@0	2673 no longer needed. <strong>The caller must invoke gdFree(), not free(),
wolffd@0	2674 unless the caller is absolutely certain that the same implementations of
wolffd@0	2675 malloc, free, etc. are used both at library build time and at application
wolffd@0	2676 build time.</strong> The 'size' parameter receives the total size of the block
wolffd@0	2677 of memory.
wolffd@0	2678 <DT><A NAME="gdImageTrueColorToPalette">
wolffd@0	2679 void gdImageTrueColorToPalette(gdImagePtr im, int ditherFlag, int colorsWanted)</A>
wolffd@0	2680 <br>
wolffd@0	2681 <A NAME="gdImageCreatePaletteFromTrueColor">
wolffd@0	2682 gdImagePtr gdImageCreatePaletteFromTrueColor(gdImagePtr im, int ditherFlag, int colorsWanted)</A>
wolffd@0	2683
wolffd@0	2684 <STRONG>(FUNCTION)</STRONG>
wolffd@0	2685 <DD>
wolffd@0	2686 <blockquote>
wolffd@0	2687 gdImageCreatePaletteFromTrueColor returns a <b>new</b>
wolffd@0	2688 image. gdImageTrueColorToPalette permanently converts the
wolffd@0	2689 <b>existing</b> image. The two functions are otherwise identical.
wolffd@0	2690 </blockquote>
wolffd@0	2691 <p>
wolffd@0	2692 The function converts a truecolor image to a palette-based image,
wolffd@0	2693 using a high-quality two-pass quantization routine.
wolffd@0	2694 If ditherFlag is set, the image will be
wolffd@0	2695 dithered to approximate colors better, at the expense
wolffd@0	2696 of some obvious "speckling." colorsWanted can be
wolffd@0	2697 anything up to 256. If the original source image
wolffd@0	2698 includes photographic information or anything that
wolffd@0	2699 came out of a JPEG, 256 is strongly recommended.
wolffd@0	2700 100% transparency of a single transparent color in the
wolffd@0	2701 original truecolor image will be preserved. There is no other
wolffd@0	2702 support for preservation of alpha channel or transparency in
wolffd@0	2703 the destination image.
wolffd@0	2704 <p>
wolffd@0	2705 For best results, don't use this function -- write real
wolffd@0	2706 truecolor PNGs and JPEGs. The disk space gain of
wolffd@0	2707 conversion to palette is not great (for small images
wolffd@0	2708 it can be negative) and the quality loss is ugly. However,
wolffd@0	2709 the version of this function included in version 2.0.12 and later does
wolffd@0	2710 do a better job than the version included prior to 2.0.12.
wolffd@0	2711 </DL>
wolffd@0	2712 <H3><A NAME="drawing">Drawing Functions</A></H3>
wolffd@0	2713 <DL>
wolffd@0	2714 <DT><A NAME="gdImageSetPixel">void gdImageSetPixel(gdImagePtr im, int x, int y, int color)</A> <STRONG>(FUNCTION)</STRONG>
wolffd@0	2715 <DD>gdImageSetPixel sets a pixel to a particular color index. Always use
wolffd@0	2716 this function or one of the other drawing functions to access pixels;
wolffd@0	2717 do not access the pixels of the <A HREF="#gdImage">gdImage</A> structure
wolffd@0	2718 directly.
wolffd@0	2719 <PRE>
wolffd@0	2720 ... inside a function ...
wolffd@0	2721 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	2722 int black;
wolffd@0	2723 int white;
wolffd@0	2724 im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
wolffd@0	2725 /* Background color (first allocated) */
wolffd@0	2726 black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
wolffd@0	2727 /* Allocate the color white (red, green and blue all maximum). */
wolffd@0	2728 white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
wolffd@0	2729 /* Set a pixel near the center. */
wolffd@0	2730 gdImageSetPixel(im, 50, 50, white);
wolffd@0	2731 /* ... Do something with the image, such as
wolffd@0	2732 saving it to a file... */
wolffd@0	2733 /* Destroy it */
wolffd@0	2734 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	2735 </PRE>
wolffd@0	2736 <DT><A NAME="gdImageLine">void gdImageLine(gdImagePtr im, int x1, int y1, int x2, int y2, int color)</A>
wolffd@0	2737 <STRONG>(FUNCTION)</STRONG>
wolffd@0	2738 <DD>
wolffd@0	2739 gdImageLine is used to draw a line between two endpoints (x1,y1 and x2, y2).
wolffd@0	2740 The line is drawn using the color index specified. Note that the color
wolffd@0	2741 index can be an actual color returned by <A HREF="#gdImageColorAllocate">
wolffd@0	2742 gdImageColorAllocate</A> or one of <A HREF="#gdStyled">gdStyled</A>,
wolffd@0	2743 <A HREF="#gdBrushed">gdBrushed</A> or <A HREF="#gdStyledBrushed">
wolffd@0	2744 gdStyledBrushed</A>.
wolffd@0	2745 <PRE>
wolffd@0	2746 ... inside a function ...
wolffd@0	2747 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	2748 int black;
wolffd@0	2749 int white;
wolffd@0	2750 im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
wolffd@0	2751 /* Background color (first allocated) */
wolffd@0	2752 black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
wolffd@0	2753 /* Allocate the color white (red, green
wolffd@0	2754 and blue all maximum). */
wolffd@0	2755 white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
wolffd@0	2756 /* Draw a line from the upper left corner to the
wolffd@0	2757 lower right corner. */
wolffd@0	2758 gdImageLine(im, 0, 0, 99, 99, white);
wolffd@0	2759 /* ... Do something with the image, such as
wolffd@0	2760 saving it to a file... */
wolffd@0	2761 /* Destroy it */
wolffd@0	2762 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	2763 </PRE>
wolffd@0	2764 <DT><A NAME="gdImageDashedLine">void gdImageDashedLine(gdImagePtr im, int x1, int y1, int x2, int y2, int color)</A>
wolffd@0	2765 <STRONG>(FUNCTION)</STRONG>
wolffd@0	2766 <DD>
wolffd@0	2767 gdImageDashedLine is provided <strong>solely for backwards compatibility
wolffd@0	2768 </strong> with gd 1.0. New programs should draw dashed lines using
wolffd@0	2769 the normal <A HREF="#gdImageLine">gdImageLine</A> function and the
wolffd@0	2770 new <A HREF="#gdImageSetStyle">gdImageSetStyle</A> function.
wolffd@0	2771 <P>
wolffd@0	2772 gdImageDashedLine is used to draw a dashed line between two endpoints
wolffd@0	2773 (x1,y1 and x2, y2).
wolffd@0	2774 The line is drawn using the color index specified. The portions of the line
wolffd@0	2775 that are not drawn are left transparent so the background is visible.
wolffd@0	2776 <PRE>
wolffd@0	2777 ... inside a function ...
wolffd@0	2778 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	2779 int black;
wolffd@0	2780 int white;
wolffd@0	2781 im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
wolffd@0	2782 /* Background color (first allocated) */
wolffd@0	2783 black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
wolffd@0	2784 /* Allocate the color white (red, green and blue
wolffd@0	2785 all maximum). */
wolffd@0	2786 white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
wolffd@0	2787 /* Draw a dashed line from the upper left corner
wolffd@0	2788 to the lower right corner. */
wolffd@0	2789 gdImageDashedLine(im, 0, 0, 99, 99);
wolffd@0	2790 /* ... Do something with the image, such as
wolffd@0	2791 saving it to a file... */
wolffd@0	2792 /* Destroy it */
wolffd@0	2793 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	2794 </PRE>
wolffd@0	2795 <DT><A NAME="gdImagePolygon">void gdImagePolygon(gdImagePtr im, gdPointPtr points, int pointsTotal, int color)</A>
wolffd@0	2796 <STRONG>(FUNCTION)</STRONG>
wolffd@0	2797 <DD>
wolffd@0	2798 gdImagePolygon is used to draw a polygon with the verticies
wolffd@0	2799 (at least 3) specified, using the color index specified.
wolffd@0	2800 See also <A HREF="#gdImageFilledPolygon">gdImageFilledPolygon</A>.
wolffd@0	2801 <PRE>
wolffd@0	2802 ... inside a function ...
wolffd@0	2803 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	2804 int black;
wolffd@0	2805 int white;
wolffd@0	2806 /* Points of polygon */
wolffd@0	2807 <A HREF="#gdPoint">gdPoint</A> points[3];
wolffd@0	2808 im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
wolffd@0	2809 /* Background color (first allocated) */
wolffd@0	2810 black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
wolffd@0	2811 /* Allocate the color white (red, green and
wolffd@0	2812 blue all maximum). */
wolffd@0	2813 white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
wolffd@0	2814 /* Draw a triangle. */
wolffd@0	2815 points[0].x = 50;
wolffd@0	2816 points[0].y = 0;
wolffd@0	2817 points[1].x = 99;
wolffd@0	2818 points[1].y = 99;
wolffd@0	2819 points[2].x = 0;
wolffd@0	2820 points[2].y = 99;
wolffd@0	2821 gdImagePolygon(im, points, 3, white);
wolffd@0	2822 /* ... Do something with the image, such as
wolffd@0	2823 saving it to a file... */
wolffd@0	2824 /* Destroy it */
wolffd@0	2825 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	2826 </PRE>
wolffd@0	2827 <DT><A NAME="gdImageOpenPolygon">void gdImageOpenPolygon(gdImagePtr im, gdPointPtr points, int pointsTotal, int color)</A>
wolffd@0	2828 <STRONG>(FUNCTION)</STRONG>
wolffd@0	2829 <DD>
wolffd@0	2830 gdImageOpenPolygon is used to draw a sequence of lines with the verticies
wolffd@0	2831 (at least 3) specified, using the color index specified. Unlike
wolffd@0	2832 <A HREF="#gdImagePolygon">gdImagePolygon</A>, the enpoints of the line
wolffd@0	2833 sequence are not connected to a closed polygon.
wolffd@0	2834 <DT><A NAME="gdImageRectangle">void gdImageRectangle(gdImagePtr im, int x1, int y1, int x2, int y2, int color)</A>
wolffd@0	2835 <STRONG>(FUNCTION)</STRONG>
wolffd@0	2836 <DD>
wolffd@0	2837 gdImageRectangle is used to draw a rectangle with the two corners
wolffd@0	2838 (upper left first, then lower right) specified, using the
wolffd@0	2839 color index specified.
wolffd@0	2840 <PRE>
wolffd@0	2841 ... inside a function ...
wolffd@0	2842 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	2843 int black;
wolffd@0	2844 int white;
wolffd@0	2845 im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
wolffd@0	2846 /* Background color (first allocated) */
wolffd@0	2847 black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
wolffd@0	2848 /* Allocate the color white (red, green and blue all maximum). */
wolffd@0	2849 white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
wolffd@0	2850 /* Draw a rectangle occupying the central area. */
wolffd@0	2851 gdImageRectangle(im, 25, 25, 74, 74, white);
wolffd@0	2852 /* ... Do something with the image, such as
wolffd@0	2853 saving it to a file... */
wolffd@0	2854 /* Destroy it */
wolffd@0	2855 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	2856 </PRE>
wolffd@0	2857 <DT><A NAME="gdImageFilledPolygon">void gdImageFilledPolygon(gdImagePtr im, gdPointPtr points, int pointsTotal, int color)</A>
wolffd@0	2858 <STRONG>(FUNCTION)</STRONG>
wolffd@0	2859 <DD>
wolffd@0	2860 gdImageFilledPolygon is used to fill a polygon with the verticies
wolffd@0	2861 (at least 3) specified, using the color index specified.
wolffd@0	2862 See also <A HREF="#gdImageFilledPolygon">gdImagePolygon</A>.
wolffd@0	2863 <PRE>
wolffd@0	2864 ... inside a function ...
wolffd@0	2865 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	2866 int black;
wolffd@0	2867 int white;
wolffd@0	2868 int red;
wolffd@0	2869 /* Points of polygon */
wolffd@0	2870 <A HREF="#gdPoint">gdPoint</A> points[3];
wolffd@0	2871 im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
wolffd@0	2872 /* Background color (first allocated) */
wolffd@0	2873 black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
wolffd@0	2874 /* Allocate the color white (red, green and blue all maximum). */
wolffd@0	2875 white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
wolffd@0	2876 /* Allocate the color red. */
wolffd@0	2877 red = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 0, 0);
wolffd@0	2878 /* Draw a triangle. */
wolffd@0	2879 points[0].x = 50;
wolffd@0	2880 points[0].y = 0;
wolffd@0	2881 points[1].x = 99;
wolffd@0	2882 points[1].y = 99;
wolffd@0	2883 points[2].x = 0;
wolffd@0	2884 points[2].y = 99;
wolffd@0	2885 /* Paint it in white */
wolffd@0	2886 gdImageFilledPolygon(im, points, 3, white);
wolffd@0	2887 /* Outline it in red; must be done second */
wolffd@0	2888 <A HREF="#gdImagePolygon">gdImagePolygon</A>(im, points, 3, red);
wolffd@0	2889 /* ... Do something with the image, such as
wolffd@0	2890 saving it to a file... */
wolffd@0	2891 /* Destroy it */
wolffd@0	2892 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	2893 </PRE>
wolffd@0	2894 <DT><A NAME="gdImageFilledRectangle">void gdImageFilledRectangle(gdImagePtr im, int x1, int y1, int x2, int y2, int color)</A>
wolffd@0	2895 <STRONG>(FUNCTION)</STRONG>
wolffd@0	2896 <DD>
wolffd@0	2897 gdImageFilledRectangle is used to draw a solid rectangle with the two corners
wolffd@0	2898 (upper left first, then lower right) specified, using the
wolffd@0	2899 color index specified.
wolffd@0	2900 <PRE>
wolffd@0	2901 ... inside a function ...
wolffd@0	2902 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	2903 int black;
wolffd@0	2904 int white;
wolffd@0	2905 im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
wolffd@0	2906 /* Background color (first allocated) */
wolffd@0	2907 black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
wolffd@0	2908 /* Allocate the color white (red, green and blue all maximum). */
wolffd@0	2909 white = <A HREF="#gdImageColorAllocate">int gdImageColorAllocate</A>(im, 255, 255, 255);
wolffd@0	2910 /* Draw a filled rectangle occupying the central area. */
wolffd@0	2911 gdImageFilledRectangle(im, 25, 25, 74, 74, white);
wolffd@0	2912 /* ... Do something with the image, such as
wolffd@0	2913 saving it to a file... */
wolffd@0	2914 /* Destroy it */
wolffd@0	2915 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	2916 </PRE>
wolffd@0	2917 <DT><A NAME="gdImageArc">void gdImageArc(gdImagePtr im, int cx, int cy, int w, int h, int s, int e, int color)</A>
wolffd@0	2918 <STRONG> (FUNCTION)</STRONG>
wolffd@0	2919 <DD>
wolffd@0	2920 gdImageArc is used to draw a partial ellipse centered at the given point,
wolffd@0	2921 with the specified width and height in pixels. The arc begins at
wolffd@0	2922 the position in degrees specified by <code>s</code> and ends at
wolffd@0	2923 the position specified by <code>e</code>. The arc is drawn in
wolffd@0	2924 the color specified by the last argument. A circle can be drawn
wolffd@0	2925 by beginning from 0 degrees and ending at 360 degrees, with
wolffd@0	2926 width and height being equal. e must be greater than s. Values greater
wolffd@0	2927 than 360 are interpreted modulo 360.
wolffd@0	2928 <PRE>
wolffd@0	2929 ... inside a function ...
wolffd@0	2930 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	2931 int black;
wolffd@0	2932 int white;
wolffd@0	2933 im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 50);
wolffd@0	2934 /* Background color (first allocated) */
wolffd@0	2935 black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
wolffd@0	2936 /* Allocate the color white (red, green and blue all maximum). */
wolffd@0	2937 white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
wolffd@0	2938 /* Inscribe an ellipse in the image. */
wolffd@0	2939 gdImageArc(im, 50, 25, 98, 48, 0, 360, white);
wolffd@0	2940 /* ... Do something with the image, such as
wolffd@0	2941 saving it to a file... */
wolffd@0	2942 /* Destroy it */
wolffd@0	2943 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	2944 </PRE>
wolffd@0	2945 <DT><A NAME="gdImageFilledArc">void gdImageFilledArc(gdImagePtr im, int cx, int cy, int w, int h, int s, int e, int color, int style)</A>
wolffd@0	2946 <STRONG> (FUNCTION)</STRONG>
wolffd@0	2947 <DD>
wolffd@0	2948 gdImageFilledArc is used to draw a partial ellipse centered at the given point,
wolffd@0	2949 with the specified width and height in pixels. The arc begins at
wolffd@0	2950 the position in degrees specified by <code>s</code> and ends at
wolffd@0	2951 the position specified by <code>e</code>. The arc is filled in
wolffd@0	2952 the color specified by the second to last argument. A circle can be drawn
wolffd@0	2953 by beginning from 0 degrees and ending at 360 degrees, with
wolffd@0	2954 width and height being equal. e must be greater than s. Values greater
wolffd@0	2955 than 360 are interpreted modulo 360. The last argument is a bitwise
wolffd@0	2956 OR of the following possibilities:
wolffd@0	2957 <ul>
wolffd@0	2958 <li>gdArc
wolffd@0	2959 <li>gdChord
wolffd@0	2960 <li>gdPie (synonym for gdChord)
wolffd@0	2961 <li>gdNoFill
wolffd@0	2962 <li>gdEdged
wolffd@0	2963 </ul>
wolffd@0	2964 gdArc and gdChord are mutually exclusive;
wolffd@0	2965 gdChord just connects the starting and ending
wolffd@0	2966 angles with a straight line, while gdArc produces
wolffd@0	2967 a rounded edge. gdPie is a synonym for gdArc.
wolffd@0	2968 gdNoFill indicates that the arc or chord should be
wolffd@0	2969 outlined, not filled. gdEdged, used together with
wolffd@0	2970 gdNoFill, indicates that the beginning and ending
wolffd@0	2971 angles should be connected to the center; this is
wolffd@0	2972 a good way to outline (rather than fill) a
wolffd@0	2973 'pie slice'.
wolffd@0	2974
wolffd@0	2975 <PRE>
wolffd@0	2976 ... inside a function ...
wolffd@0	2977 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	2978 int black;
wolffd@0	2979 int white;
wolffd@0	2980 im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 50);
wolffd@0	2981 /* Background color (first allocated) */
wolffd@0	2982 black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
wolffd@0	2983 /* Allocate the color white (red, green and blue all maximum). */
wolffd@0	2984 white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
wolffd@0	2985 /* Inscribe a filled pie slice in the image. */
wolffd@0	2986 gdImageFilledArc(im, 50, 25, 98, 48, 0, 45, white, gdArc);
wolffd@0	2987 /* ... Do something with the image, such as
wolffd@0	2988 saving it to a file... */
wolffd@0	2989 /* Destroy it */
wolffd@0	2990 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	2991 </PRE>
wolffd@0	2992 <DT><A NAME="gdImageFilledEllipse">void gdImageFilledEllipse(gdImagePtr im, int cx, int cy, int w, int h, int color)</A>
wolffd@0	2993 <STRONG> (FUNCTION)</STRONG>
wolffd@0	2994 <DD>
wolffd@0	2995 gdImageFilledEllipse is used to draw an ellipse centered at the given point,
wolffd@0	2996 with the specified width and height in pixels. The ellipse is filled in
wolffd@0	2997 the color specified by the last argument.
wolffd@0	2998 <PRE>
wolffd@0	2999 ... inside a function ...
wolffd@0	3000 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	3001 int black;
wolffd@0	3002 int white;
wolffd@0	3003 im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 50);
wolffd@0	3004 /* Background color (first allocated) */
wolffd@0	3005 black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
wolffd@0	3006 /* Allocate the color white (red, green and blue all maximum). */
wolffd@0	3007 white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
wolffd@0	3008 /* Inscribe a filled ellipse in the image. */
wolffd@0	3009 gdImageFilledEllipse(im, 50, 25, 98, 48, white);
wolffd@0	3010 /* ... Do something with the image, such as
wolffd@0	3011 saving it to a file... */
wolffd@0	3012 /* Destroy it */
wolffd@0	3013 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	3014 </PRE>
wolffd@0	3015 <DT><A NAME="gdImageFillToBorder">void gdImageFillToBorder(gdImagePtr im, int x, int y, int border, int color)
wolffd@0	3016 <STRONG> (FUNCTION)</STRONG>
wolffd@0	3017 <DD>
wolffd@0	3018 gdImageFillToBorder floods a portion of the image with the specified
wolffd@0	3019 <code>color</code>, beginning at the specified point and stopping at
wolffd@0	3020 the specified <code>border</code> color. For a way of flooding an
wolffd@0	3021 area defined by the color of the starting point, see
wolffd@0	3022 <A HREF="#gdImageFill">gdImageFill</A>.
wolffd@0	3023 <P>
wolffd@0	3024 The border color <em>cannot</em> be a special color
wolffd@0	3025 such as <A HREF="#gdTiled">gdTiled</A>; it must be a proper
wolffd@0	3026 solid color. The fill color can be, however.
wolffd@0	3027 <P>
wolffd@0	3028 Note that gdImageFillToBorder is recursive. It is not the most
wolffd@0	3029 naive implementation possible, and the implementation is
wolffd@0	3030 expected to improve, but there will always be degenerate
wolffd@0	3031 cases in which the stack can become very deep. This can be
wolffd@0	3032 a problem in MSDOS and MS Windows 3.1 environments. (Of course,
wolffd@0	3033 in a Unix or Windows 95/98/NT environment with a proper stack, this is
wolffd@0	3034 not a problem at all.)
wolffd@0	3035 <PRE>
wolffd@0	3036 ... inside a function ...
wolffd@0	3037 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	3038 int black;
wolffd@0	3039 int white;
wolffd@0	3040 int red;
wolffd@0	3041 im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 50);
wolffd@0	3042 /* Background color (first allocated) */
wolffd@0	3043 black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
wolffd@0	3044 /* Allocate the color white (red, green and blue all maximum). */
wolffd@0	3045 white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
wolffd@0	3046 /* Allocate the color red. */
wolffd@0	3047 red = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 0, 0);
wolffd@0	3048 /* Inscribe an ellipse in the image. */
wolffd@0	3049 gdImageArc(im, 50, 25, 98, 48, 0, 360, white);
wolffd@0	3050 /* Flood-fill the ellipse. Fill color is red, border color is
wolffd@0	3051 white (ellipse). */
wolffd@0	3052 gdImageFillToBorder(im, 50, 50, white, red);
wolffd@0	3053 /* ... Do something with the image, such as
wolffd@0	3054 saving it to a file... */
wolffd@0	3055 /* Destroy it */
wolffd@0	3056 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	3057 </PRE>
wolffd@0	3058 <DT><A NAME="gdImageFill">void gdImageFill(gdImagePtr im, int x, int y, int color)
wolffd@0	3059 <STRONG> (FUNCTION)</STRONG>
wolffd@0	3060 <DD>
wolffd@0	3061 gdImageFill floods a portion of the image with the specified
wolffd@0	3062 <code>color</code>, beginning at the specified point and flooding the
wolffd@0	3063 surrounding region of the same color as the starting point.
wolffd@0	3064 For a way of flooding a region defined by a specific border
wolffd@0	3065 color rather than by its interior color, see
wolffd@0	3066 <A HREF="#gdImageFillToBorder">gdImageFillToBorder</A>.
wolffd@0	3067 <P>
wolffd@0	3068 The fill color can be <A HREF="#gdTiled">gdTiled</A>, resulting
wolffd@0	3069 in a tile fill using another image as the tile. However,
wolffd@0	3070 the tile image cannot be transparent. If the image you wish
wolffd@0	3071 to fill with has a transparent color index, call
wolffd@0	3072 <A HREF="#gdImageTransparent">gdImageTransparent</A> on the
wolffd@0	3073 tile image and set the transparent color index to -1
wolffd@0	3074 to turn off its transparency.
wolffd@0	3075 <P>
wolffd@0	3076 Note that gdImageFill is recursive. It is not the most
wolffd@0	3077 naive implementation possible, and the implementation is
wolffd@0	3078 expected to improve, but there will always be degenerate
wolffd@0	3079 cases in which the stack can become very deep. This can be
wolffd@0	3080 a problem in MSDOS and MS Windows environments. (Of course,
wolffd@0	3081 in a Unix or Windows 95/98/NT environment with a proper stack, this is
wolffd@0	3082 not a problem at all.)
wolffd@0	3083 <PRE>
wolffd@0	3084 ... inside a function ...
wolffd@0	3085 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	3086 int black;
wolffd@0	3087 int white;
wolffd@0	3088 int red;
wolffd@0	3089 im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 50);
wolffd@0	3090 /* Background color (first allocated) */
wolffd@0	3091 black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
wolffd@0	3092 /* Allocate the color white (red, green and blue all maximum). */
wolffd@0	3093 white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
wolffd@0	3094 /* Allocate the color red. */
wolffd@0	3095 red = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 0, 0);
wolffd@0	3096 /* Inscribe an ellipse in the image. */
wolffd@0	3097 gdImageArc(im, 50, 25, 98, 48, 0, 360, white);
wolffd@0	3098 /* Flood-fill the ellipse. Fill color is red, and will replace the
wolffd@0	3099 black interior of the ellipse. */
wolffd@0	3100 gdImageFill(im, 50, 50, red);
wolffd@0	3101 /* ... Do something with the image, such as
wolffd@0	3102 saving it to a file... */
wolffd@0	3103 /* Destroy it */
wolffd@0	3104 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	3105 </PRE>
wolffd@0	3106 <DT><A NAME="gdImageSetAntiAliased">void gdImageSetAntiAliased(gdImagePtr im, int c)</A>
wolffd@0	3107 <STRONG>(FUNCTION)</STRONG>
wolffd@0	3108 <DD>
wolffd@0	3109 "Antialiasing" is a process by which jagged edges associated with line
wolffd@0	3110 drawing can be reduced by blending the foreground color with an appropriate
wolffd@0	3111 percentage of the background, depending on how much of the pixel in question
wolffd@0	3112 is actually within the boundaries of the line being drawn.
wolffd@0	3113 All line-drawing functions,
wolffd@0	3114 such as <A HREF="#gdImageLine">gdImageLine</A>,
wolffd@0	3115 <A HREF="#gdImageOpenPolygon">gdImageOpenPolygon</A> and
wolffd@0	3116 <A HREF="#gdImagePolygon">gdImagePolygon</A>, will draw antialiased lines
wolffd@0	3117 if the special "color" <A HREF="#gdAntiAliased">
wolffd@0	3118 gdAntiAliased</A> is used when calling them.
wolffd@0	3119 <P>
wolffd@0	3120 gdImageSetAntiAliased is used to specify the actual foreground color
wolffd@0	3121 to be used when drawing antialiased lines. You may set any color to
wolffd@0	3122 be the foreground, however as of version 2.0.12 an alpha channel
wolffd@0	3123 component is not supported.
wolffd@0	3124 <p>
wolffd@0	3125 Antialiased lines can be drawn on both truecolor and palette-based
wolffd@0	3126 images. However, attempts to draw antialiased lines on
wolffd@0	3127 highly complex palette-based backgrounds may not give satisfactory
wolffd@0	3128 results, due to the limited number of colors available in the
wolffd@0	3129 palette. Antialiased line-drawing on simple backgrounds should
wolffd@0	3130 work well with palette-based images; otherwise create or fetch
wolffd@0	3131 a truecolor image instead.
wolffd@0	3132 <P>
wolffd@0	3133 You need not take any special action when you are finished
wolffd@0	3134 with antialised line drawing.
wolffd@0	3135 <PRE>
wolffd@0	3136 ... inside a function ...
wolffd@0	3137 <A HREF="#gdImagePtr">gdImagePtr</A> im, brush;
wolffd@0	3138 int black;
wolffd@0	3139 int blue;
wolffd@0	3140 im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
wolffd@0	3141 /* Background color (first allocated) */
wolffd@0	3142 black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
wolffd@0	3143 blue = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 255);
wolffd@0	3144 gdImageSetAntiAliased(im, blue);
wolffd@0	3145 /* Draw a smooth line from the upper left corner to the
wolffd@0	3146 lower right corner. */
wolffd@0	3147 <A HREF="#gdImageLine">gdImageLine</A>(im, 0, 0, 99, 99, <A HREF="#gdBrushed">gdAntiAliased</A>);
wolffd@0	3148 /* ... Do something with the image, such as
wolffd@0	3149 saving it to a file... */
wolffd@0	3150 /* Destroy it */
wolffd@0	3151 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	3152 </PRE>
wolffd@0	3153 See also <a href="#gdAntiAliased">gdAntiAliased</a> and
wolffd@0	3154 <a href="#gdSetAntiAliasedDontBlend">gdSetAntiAliasedDontBlend</a>.
wolffd@0	3155 <DT><A NAME="gdImageSetAntiAliasedDontBlend">void gdImageSetAntiAliasedDontBlend(gdImagePtr im, int c)</A>
wolffd@0	3156 <STRONG>(FUNCTION)</STRONG>
wolffd@0	3157 <DD>
wolffd@0	3158 Normally, when drawing lines with the special
wolffd@0	3159 <a href="#gdAntiAliased">gdAntiAliased</a> "color," blending with the
wolffd@0	3160 background to reduce jagged edges is the desired behavior. However, when
wolffd@0	3161 it is desired that lines not be blended with one particular color when
wolffd@0	3162 it is encountered in the background, the
wolffd@0	3163 gdImageSetAntiAliasedDontBlend function can be used to indicate the
wolffd@0	3164 special color that the foreground should stand out more clearly against.
wolffd@0	3165 <PRE>
wolffd@0	3166 ... inside a function ...
wolffd@0	3167 <A HREF="#gdImagePtr">gdImagePtr</A> im, brush;
wolffd@0	3168 int black;
wolffd@0	3169 int blue;
wolffd@0	3170 int white;
wolffd@0	3171 im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
wolffd@0	3172 /* Background color (first allocated) */
wolffd@0	3173 black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
wolffd@0	3174 blue = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 255);
wolffd@0	3175 white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
wolffd@0	3176
wolffd@0	3177 gdImageSetAntiAliased(im, blue);
wolffd@0	3178 /* The portion of the line that crosses this white rectangle will
wolffd@0	3179 not be blended smoothly */
wolffd@0	3180 gdImageSetAntiAliasedDontBlend(im, white);
wolffd@0	3181 gdImageFilledRectangle(im, 25, 25, 75, 75, white);
wolffd@0	3182 /* Draw a smooth line from the upper left corner
wolffd@0	3183 to the lower right corner. */
wolffd@0	3184 <A HREF="#gdImageLine">gdImageLine</A>(im, 0, 0, 99, 99, <A HREF="#gdBrushed">gdAntiAliased</A>);
wolffd@0	3185 /* ... Do something with the image, such as
wolffd@0	3186 saving it to a file... */
wolffd@0	3187 /* Destroy it */
wolffd@0	3188 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	3189 </PRE>
wolffd@0	3190 See also <a href="#gdAntiAliased">gdAntiAliased</a> and
wolffd@0	3191 <a href="#gdSetAntiAliased">gdSetAntiAliased</a>.
wolffd@0	3192 <DT><A NAME="gdImageSetBrush">void gdImageSetBrush(gdImagePtr im, gdImagePtr brush)</A>
wolffd@0	3193 <STRONG>(FUNCTION)</STRONG>
wolffd@0	3194 <DD>
wolffd@0	3195 A "brush" is an image used to draw wide, shaped strokes in another image. Just
wolffd@0	3196 as a paintbrush is not a single point, a brush image need not be
wolffd@0	3197 a single pixel. <em>Any</em> gd image can be used as a brush, and by
wolffd@0	3198 setting the transparent color index of the brush image with
wolffd@0	3199 <A HREF="#gdImageColorTransparent">gdImageColorTransparent</A>,
wolffd@0	3200 a brush of any shape can be created. All line-drawing functions,
wolffd@0	3201 such as <A HREF="#gdImageLine">gdImageLine</A>,
wolffd@0	3202 <A HREF="#gdImageOpenPolygon">gdImageOpenPolygon</A> and
wolffd@0	3203 <A HREF="#gdImagePolygon">gdImagePolygon</A>, will use the
wolffd@0	3204 current brush if the special "color" <A HREF="#gdBrushed">
wolffd@0	3205 gdBrushed</A> or <A HREF="#gdStyledBrushed">gdStyledBrushed</A>
wolffd@0	3206 is used when calling them.
wolffd@0	3207 <P>
wolffd@0	3208 gdImageSetBrush is used to specify the brush to be used in a
wolffd@0	3209 particular image. You can set any image to be the brush.
wolffd@0	3210 If the brush image does not have the same color map as the
wolffd@0	3211 first image, any colors missing from the first image
wolffd@0	3212 will be allocated. If not enough colors can be allocated,
wolffd@0	3213 the closest colors already available will be used. This
wolffd@0	3214 allows arbitrary PNGs to be used as brush images. It also
wolffd@0	3215 means, however, that you should not set a brush unless you
wolffd@0	3216 will actually use it; if you set a rapid succession of
wolffd@0	3217 different brush images, you can quickly fill your color map,
wolffd@0	3218 and the results will not be optimal.
wolffd@0	3219 <P>
wolffd@0	3220 You need not take any special action when you are finished
wolffd@0	3221 with a brush. As for any other image, if you will not
wolffd@0	3222 be using the brush image for any further purpose,
wolffd@0	3223 you should call <A HREF="#gdImageDestroy">gdImageDestroy</A>.
wolffd@0	3224 You must not use the color <A HREF="#gdBrushed">gdBrushed</A>
wolffd@0	3225 if the current brush has been destroyed; you can of
wolffd@0	3226 course set a new brush to replace it.
wolffd@0	3227 <PRE>
wolffd@0	3228 ... inside a function ...
wolffd@0	3229 <A HREF="#gdImagePtr">gdImagePtr</A> im, brush;
wolffd@0	3230 FILE *in;
wolffd@0	3231 int black;
wolffd@0	3232 im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
wolffd@0	3233 /* Open the brush PNG. For best results, portions of the
wolffd@0	3234 brush that should be transparent (ie, not part of the
wolffd@0	3235 brush shape) should have the transparent color index. */
wolffd@0	3236 in = fopen("star.png", "rb");
wolffd@0	3237 brush = <A HREF="#gdImageCreateFromPng">gdImageCreateFromPng</A>(in);
wolffd@0	3238 /* Background color (first allocated) */
wolffd@0	3239 black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
wolffd@0	3240 gdImageSetBrush(im, brush);
wolffd@0	3241 /* Draw a line from the upper left corner to the lower right corner
wolffd@0	3242 using the brush. */
wolffd@0	3243 <A HREF="#gdImageLine">gdImageLine</A>(im, 0, 0, 99, 99, <A HREF="#gdBrushed">gdBrushed</A>);
wolffd@0	3244 /* ... Do something with the image, such as
wolffd@0	3245 saving it to a file... */
wolffd@0	3246 /* Destroy it */
wolffd@0	3247 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	3248 /* Destroy the brush image */
wolffd@0	3249 <A HREF="#gdImageDestroy">gdImageDestroy</A>(brush);
wolffd@0	3250 </PRE>
wolffd@0	3251 <DT><A NAME="gdImageSetTile">void gdImageSetTile(gdImagePtr im, gdImagePtr tile)</A>
wolffd@0	3252 <STRONG>(FUNCTION)</STRONG>
wolffd@0	3253 <DD>
wolffd@0	3254 A "tile" is an image used to fill an area with a repeated pattern.
wolffd@0	3255 <em>Any</em> gd image can be used as a tile, and by
wolffd@0	3256 setting the transparent color index of the tile image with
wolffd@0	3257 <A HREF="#gdImageColorTransparent">gdImageColorTransparent</A>,
wolffd@0	3258 a tile that allows certain parts of the underlying area to shine
wolffd@0	3259 through can be created. All region-filling functions,
wolffd@0	3260 such as <A HREF="#gdImageFill">gdImageFill</A> and
wolffd@0	3261 <A HREF="#gdImageFilledPolygon">gdImageFilledPolygon</A>, will use the
wolffd@0	3262 current tile if the special "color" <A HREF="#gdTiled">
wolffd@0	3263 gdTiled</A> is used when calling them.
wolffd@0	3264 <P>
wolffd@0	3265 gdImageSetTile is used to specify the tile to be used in a
wolffd@0	3266 particular image. You can set any image to be the tile.
wolffd@0	3267 If the tile image does not have the same color map as the
wolffd@0	3268 first image, any colors missing from the first image
wolffd@0	3269 will be allocated. If not enough colors can be allocated,
wolffd@0	3270 the closest colors already available will be used. This
wolffd@0	3271 allows arbitrary PNGs to be used as tile images. It also
wolffd@0	3272 means, however, that you should not set a tile unless you
wolffd@0	3273 will actually use it; if you set a rapid succession of
wolffd@0	3274 different tile images, you can quickly fill your color map,
wolffd@0	3275 and the results will not be optimal.
wolffd@0	3276 <P>
wolffd@0	3277 You need not take any special action when you are finished
wolffd@0	3278 with a tile. As for any other image, if you will not
wolffd@0	3279 be using the tile image for any further purpose,
wolffd@0	3280 you should call <A HREF="#gdImageDestroy">gdImageDestroy</A>.
wolffd@0	3281 You must not use the color <A HREF="#gdBrushed">gdTiled</A>
wolffd@0	3282 if the current tile has been destroyed; you can of
wolffd@0	3283 course set a new tile to replace it.
wolffd@0	3284 <PRE>
wolffd@0	3285 ... inside a function ...
wolffd@0	3286 <A HREF="#gdImagePtr">gdImagePtr</A> im, tile;
wolffd@0	3287 FILE *in;
wolffd@0	3288 int black;
wolffd@0	3289 im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
wolffd@0	3290 /* Open the tile PNG. For best results, portions of the
wolffd@0	3291 tile that should be transparent (ie, allowing the
wolffd@0	3292 background to shine through) should have the transparent
wolffd@0	3293 color index. */
wolffd@0	3294 in = fopen("star.png", "rb");
wolffd@0	3295 tile = <A HREF="#gdImageCreateFromPng">gdImageCreateFromPng</A>(in);
wolffd@0	3296 /* Background color (first allocated) */
wolffd@0	3297 black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
wolffd@0	3298 gdImageSetTile(im, tile);
wolffd@0	3299 /* Fill an area using the tile. */
wolffd@0	3300 <A HREF="#gdImageFilledRectangle">gdImageFilledRectangle</A>(im, 25, 25, 75, 75, <A HREF="#gdTiled">gdTiled</A>);
wolffd@0	3301 /* ... Do something with the image, such as
wolffd@0	3302 saving it to a file... */
wolffd@0	3303 /* Destroy it */
wolffd@0	3304 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	3305 /* Destroy the tile image */
wolffd@0	3306 <A HREF="#gdImageDestroy">gdImageDestroy</A>(tile);
wolffd@0	3307 </PRE>
wolffd@0	3308 <DT><A NAME="gdImageSetStyle">void gdImageSetStyle(gdImagePtr im, int *style, int styleLength)</A>
wolffd@0	3309 <STRONG>(FUNCTION)</STRONG>
wolffd@0	3310 <DD>
wolffd@0	3311 It is often desirable to draw dashed lines, dotted lines, and other
wolffd@0	3312 variations on a broken line. gdImageSetStyle can be used to set
wolffd@0	3313 any desired series of colors, including a special color that
wolffd@0	3314 leaves the background intact, to be repeated during the drawing
wolffd@0	3315 of a line.
wolffd@0	3316 <P>
wolffd@0	3317 To use gdImageSetStyle, create an array of integers and assign
wolffd@0	3318 them the desired series of color values to be repeated.
wolffd@0	3319 You can assign the special color value <A HREF="#gdTransparent">
wolffd@0	3320 gdTransparent</A> to indicate that the existing color should
wolffd@0	3321 be left unchanged for that particular pixel (allowing a dashed
wolffd@0	3322 line to be attractively drawn over an existing image).
wolffd@0	3323 <P>
wolffd@0	3324 Then, to draw a line using the style, use the normal
wolffd@0	3325 <A HREF="#gdImageLine">gdImageLine</A> function with the
wolffd@0	3326 special color value <A HREF="#gdStyled">gdStyled</A>.
wolffd@0	3327 <P>
wolffd@0	3328 As of <A HREF="#whatsnew1.1.1">version 1.1.1</A>, the style
wolffd@0	3329 array is copied when you set the style, so you need not
wolffd@0	3330 be concerned with keeping the array around indefinitely.
wolffd@0	3331 This should not break existing code that assumes styles
wolffd@0	3332 are not copied.
wolffd@0	3333 <P>
wolffd@0	3334 You can also combine styles and brushes to draw the brush
wolffd@0	3335 image at intervals instead of in a continuous stroke.
wolffd@0	3336 When creating a style for use with a brush, the
wolffd@0	3337 style values are interpreted differently: zero (0) indicates
wolffd@0	3338 pixels at which the brush should not be drawn, while one (1)
wolffd@0	3339 indicates pixels at which the brush should be drawn.
wolffd@0	3340 To draw a styled, brushed line, you must use the
wolffd@0	3341 special color value <A HREF="#gdStyledBrushed">
wolffd@0	3342 gdStyledBrushed</A>. For an example of this feature
wolffd@0	3343 in use, see gddemo.c (provided in the distribution).
wolffd@0	3344 <PRE>
wolffd@0	3345 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	3346 int styleDotted[2], styleDashed[6];
wolffd@0	3347 FILE *in;
wolffd@0	3348 int black;
wolffd@0	3349 int red;
wolffd@0	3350 im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
wolffd@0	3351 /* Background color (first allocated) */
wolffd@0	3352 black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
wolffd@0	3353 red = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 0, 0);
wolffd@0	3354 /* Set up dotted style. Leave every other pixel alone. */
wolffd@0	3355 styleDotted[0] = red;
wolffd@0	3356 styleDotted[1] = gdTransparent;
wolffd@0	3357 /* Set up dashed style. Three on, three off. */
wolffd@0	3358 styleDashed[0] = red;
wolffd@0	3359 styleDashed[1] = red;
wolffd@0	3360 styleDashed[2] = red;
wolffd@0	3361 styleDashed[3] = gdTransparent;
wolffd@0	3362 styleDashed[4] = gdTransparent;
wolffd@0	3363 styleDashed[5] = gdTransparent;
wolffd@0	3364 /* Set dotted style. Note that we have to specify how many pixels are
wolffd@0	3365 in the style! */
wolffd@0	3366 gdImageSetStyle(im, styleDotted, 2);
wolffd@0	3367 /* Draw a line from the upper left corner to the lower right corner. */
wolffd@0	3368 <A HREF="#gdImageLine">gdImageLine</A>(im, 0, 0, 99, 99, <A HREF="#gdStyled">gdStyled</A>);
wolffd@0	3369 /* Now the dashed line. */
wolffd@0	3370 gdImageSetStyle(im, styleDashed, 6);
wolffd@0	3371 <A HREF="#gdImageLine">gdImageLine</A>(im, 0, 99, 0, 99, <A HREF="#gdStyled">gdStyled</A>);
wolffd@0	3372
wolffd@0	3373 /* ... Do something with the image, such as
wolffd@0	3374 saving it to a file ... */
wolffd@0	3375
wolffd@0	3376 /* Destroy it */
wolffd@0	3377 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	3378 </PRE>
wolffd@0	3379 <DT><A NAME="gdImageSetThickness">void gdImageSetThickness(gdImagePtr im, int thickness)</A> <STRONG>(FUNCTION)</STRONG>
wolffd@0	3380 <DD>gdImageSetThickness determines the width of lines drawn by the
wolffd@0	3381 <a href="#gdImageLine">gdImageLine</a>, <a href="#gdImagePolygon">gdImagePolygon</a>, <a href="#gdImageOpenPolygon">gdImageOpenPolygon</a>
wolffd@0	3382 and related functions, in pixels.
wolffd@0	3383 <PRE>
wolffd@0	3384 ... inside a function ...
wolffd@0	3385 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	3386 int black;
wolffd@0	3387 int white;
wolffd@0	3388 im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
wolffd@0	3389 /* Background color (first allocated) */
wolffd@0	3390 black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
wolffd@0	3391 /* Allocate the color white (red, green and blue all maximum). */
wolffd@0	3392 white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
wolffd@0	3393 /* Set thickness. */
wolffd@0	3394 gdImageSetThickness(im, 4);
wolffd@0	3395 /* Draw a fat line from the upper left corner to the lower right corner. */
wolffd@0	3396 gdImageLine(im, 0, 0, 99, 99, white);
wolffd@0	3397 /* ... Do something with the image, such as
wolffd@0	3398 saving it to a file... */
wolffd@0	3399 /* Destroy it */
wolffd@0	3400 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	3401 </PRE>
wolffd@0	3402 <DT><A NAME="gdImageAlphaBlending">void gdImageAlphaBlending(gdImagePtr im, int blending)</A>
wolffd@0	3403 <STRONG>(FUNCTION)</STRONG>
wolffd@0	3404 <DD>
wolffd@0	3405 The <a href="#gdImageAlphaBlending">gdImageAlphaBlending</a>
wolffd@0	3406 function allows for two different modes of drawing on truecolor
wolffd@0	3407 images. In blending mode, which is <strong>on by default (gd 2.0.2
wolffd@0	3408 and above)</strong>, the alpha channel component of the color
wolffd@0	3409 supplied to all drawing functions, such as
wolffd@0	3410 <a href="#gdImageSetPixel">gdImageSetPixel</a>, determines how much of
wolffd@0	3411 the underlying color should be allowed to shine through. As a result,
wolffd@0	3412 gd automatically blends the existing color at that point with the
wolffd@0	3413 drawing color, and stores the result in the image. The resulting pixel
wolffd@0	3414 is opaque. In non-blending mode, the drawing color is copied literally
wolffd@0	3415 with its alpha channel information, replacing the destination pixel.
wolffd@0	3416 Blending mode is not available when drawing on palette images.
wolffd@0	3417 <PRE>
wolffd@0	3418 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	3419 int red, blue;
wolffd@0	3420 im = <A HREF="#gdImageCreate">gdImageCreateTrueColor</A>(100, 100);
wolffd@0	3421 /* Background color */
wolffd@0	3422 red = <A HREF="#gdTrueColor">gdTrueColor</A>(255, 0, 0);
wolffd@0	3423 gdImageFilledRectangle(im, 0, 0, 100, 100, red);
wolffd@0	3424 /* Drawing color. Full transparency would be an alpha channel value
wolffd@0	3425 of 127 (gd has a 7 bit alpha chnanel). 0 is opaque,
wolffd@0	3426 127 is transparent. So cut gdAlphaTransparent in half to get
wolffd@0	3427 50% blending. */
wolffd@0	3428 blue = <A HREF="#gdTrueColor">gdTrueColorAlpha</A>(0, 0, 255, gdAlphaTransparent / 2);
wolffd@0	3429 /* Draw with blending. Result will be 50% red, 50% blue: yellow
wolffd@0	3430 (emitted light, remember, not reflected light. What you learned
wolffd@0	3431 in Kindergarten is wrong here). */
wolffd@0	3432 gdImageAlphaBlending(im, 1);
wolffd@0	3433 <a href="#gdImageFilledRectangle">gdImageFilledRectangle</a>(im, 0, 0, 25, 25, blue);
wolffd@0	3434 /* Draw without blending. Result will be 50% blue, 50%
wolffd@0	3435 the background color of the image viewer or web browser
wolffd@0	3436 used; results in browsers that don't support
wolffd@0	3437 semi-transparent pixels are unpredictable! */
wolffd@0	3438 gdImageAlphaBlending(im, 0);
wolffd@0	3439 <a href="#gdImageFilledRectangle">gdImageFilledRectangle</a>(im, 75, 75, 25, 25, blue);
wolffd@0	3440 /* Write the image to disk, etc. */
wolffd@0	3441 </pre>
wolffd@0	3442 <DT><A NAME="gdImageSaveAlpha">
wolffd@0	3443 void gdImageSaveAlpha(gdImagePtr im, int saveFlag)</A>
wolffd@0	3444 <STRONG>(FUNCTION)</STRONG>
wolffd@0	3445 <DD>
wolffd@0	3446 By default, gd 2.0.2 and above do not attempt to save full alpha channel information
wolffd@0	3447 (as opposed to single-color transparency) when saving PNG images. (PNG
wolffd@0	3448 is currently the only output format supported by gd which can accommodate
wolffd@0	3449 alpa channel information.) This saves space in the output file. If you wish
wolffd@0	3450 to create an image with alpha channel information for use with tools that
wolffd@0	3451 support it, call gdImageSaveAlpha(im, 1) to turn on saving of such
wolffd@0	3452 information, and call <a href="#gdImageAlphaBlending">gdImageAlphaBlending(im, 0)</a>
wolffd@0	3453 to turn off alpha blending within the library so that alpha channel
wolffd@0	3454 information is actually stored in the image rather than being composited
wolffd@0	3455 immediately at the time that drawing functions are invoked.
wolffd@0	3456 <DT><A NAME="gdImageSetClip">
wolffd@0	3457 void gdImageSetClip(gdImagePtr im, int x1, int y1, int x2, int y2)</A>
wolffd@0	3458 <STRONG>(FUNCTION)</STRONG>
wolffd@0	3459 <DD>
wolffd@0	3460 Establishes a clipping rectangle. Once gdImageSetClip has been called,
wolffd@0	3461 all future drawing operations will remain within the specified clipping
wolffd@0	3462 area, until a new gdImageSetClip call takes place. For instance,
wolffd@0	3463 if a clipping rectangle of 25, 25, 75, 75 has been set within a
wolffd@0	3464 100x100 image, a diagonal line from 0,0 to 99,99 will appear only
wolffd@0	3465 between 25,25 and 75,75.
wolffd@0	3466 <p>
wolffd@0	3467 If gdImageSetClip is never called, the clipping area will be the
wolffd@0	3468 entire image.
wolffd@0	3469 <p>
wolffd@0	3470 The parameters passed to gdImageSetClip are checked against the dimensions
wolffd@0	3471 of the image and limited to "safe" values.
wolffd@0	3472 <PRE>
wolffd@0	3473 ... inside a function ...
wolffd@0	3474 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	3475 int black;
wolffd@0	3476 int white;
wolffd@0	3477 im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
wolffd@0	3478 /* Background color (first allocated) */
wolffd@0	3479 black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
wolffd@0	3480 /* Allocate the color white (red, green and blue all maximum). */
wolffd@0	3481 white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
wolffd@0	3482 /* Set the clipping rectangle. */
wolffd@0	3483 gdImageSetClip(im, 25, 25, 75, 75);
wolffd@0	3484 /* Draw a line from the upper left corner to the lower right corner.
wolffd@0	3485 Only the part within the clipping rectangle will appear. */
wolffd@0	3486 <a href="#gdImageLine">gdImageLine</a>(im, 0, 0, 99, 99, white);
wolffd@0	3487 /* ... Do something with the image, such as
wolffd@0	3488 saving it to a file ... */
wolffd@0	3489 /* Destroy it */
wolffd@0	3490 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	3491 </PRE>
wolffd@0	3492 See also <a href="#gdImageGetClip">gdImageGetClip</a>.
wolffd@0	3493 <DT><A NAME="gdImageGetClip">
wolffd@0	3494 void gdImageGetClip(gdImagePtr im, int x1P, int y1P, int x2P, int y2P)</A>
wolffd@0	3495 <STRONG>(FUNCTION)</STRONG>
wolffd@0	3496 <DD>
wolffd@0	3497 Fetches the boundaries of the current clipping rectangle.
wolffd@0	3498 <pre>
wolffd@0	3499 ... Inside a function ...
wolffd@0	3500 gdImagePtr im = <a href="#gdImageCreateTrueColor">gdImageCreateTrueColor</a>(100, 100);
wolffd@0	3501 int x1, y1, x2, y2;
wolffd@0	3502 gdImageSetClip(im, 25, 25, 75, 75);
wolffd@0	3503 gdImageGetClip(im, &x1, &y1, &x2, &y2);
wolffd@0	3504 printf("%d %d %d %d\n", x1, y1, x2, y2);
wolffd@0	3505 </pre>
wolffd@0	3506 The above code would print:
wolffd@0	3507 <pre>
wolffd@0	3508 25 25 75 75
wolffd@0	3509 </pre>
wolffd@0	3510 See also <a href="#gdImageSetClip">gdImageSetClip</a>.
wolffd@0	3511 </DL>
wolffd@0	3512 <H3><A NAME="query">Query Functions</A></H3>
wolffd@0	3513 <DL>
wolffd@0	3514 <DT><A NAME="gdImageBlue">
wolffd@0	3515 int gdImageAlpha(gdImagePtr im, int color)</A>
wolffd@0	3516 <STRONG>(MACRO)</STRONG>
wolffd@0	3517 <DD>
wolffd@0	3518 gdImageAlpha is a macro which returns the alpha channel component of
wolffd@0	3519 the specified color index. Alpha channel values vary between
wolffd@0	3520 0 (gdAlphaOpaque), which does not blend at all with the background,
wolffd@0	3521 through 127 (gdAlphaTransparent), which allows the background to
wolffd@0	3522 shine through 100%. Use this macro rather than accessing the
wolffd@0	3523 structure members directly.
wolffd@0	3524 int gdImageBlue(gdImagePtr im, int color)</A>
wolffd@0	3525 <STRONG>(MACRO)</STRONG>
wolffd@0	3526 <DD>
wolffd@0	3527 gdImageBlue is a macro which returns the blue component of
wolffd@0	3528 the specified color index. Use this macro rather than accessing the
wolffd@0	3529 structure members directly.
wolffd@0	3530 <DT><A NAME="gdImageGetPixel">int gdImageGetPixel(gdImagePtr im, int x, int y)</A>
wolffd@0	3531 <STRONG>(FUNCTION)</STRONG>
wolffd@0	3532 <DD>
wolffd@0	3533 gdImageGetPixel() retrieves the color index of a particular
wolffd@0	3534 pixel. Always use this function to query pixels;
wolffd@0	3535 do not access the pixels of the <A HREF="#gdImage">gdImage</A> structure
wolffd@0	3536 directly.
wolffd@0	3537 <PRE>
wolffd@0	3538 ... inside a function ...
wolffd@0	3539 FILE *in;
wolffd@0	3540 gdImagePtr im;
wolffd@0	3541 int c;
wolffd@0	3542 in = fopen("mypng.png", "rb");
wolffd@0	3543 im = <A HREF="#gdImageCreateFromPng">gdImageCreateFromPng</A>(in);
wolffd@0	3544 fclose(in);
wolffd@0	3545 c = gdImageGetPixel(im, gdImageSX(im) / 2, gdImageSY(im) / 2);
wolffd@0	3546 printf("The value of the center pixel is %d; RGB values are %d,%d,%d\n",
wolffd@0	3547 c, im->red[c], im->green[c], im->blue[c]);
wolffd@0	3548 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	3549 </PRE>
wolffd@0	3550 <DT><A NAME="gdImageBoundsSafe">
wolffd@0	3551 int gdImageBoundsSafe(gdImagePtr im, int x, int y)</A>
wolffd@0	3552 <STRONG>(FUNCTION)</STRONG>
wolffd@0	3553 <DD>
wolffd@0	3554 gdImageBoundsSafe returns true (1) if the specified point is within the
wolffd@0	3555 current clipping rectangle, false (0) if not. The clipping rectangle is
wolffd@0	3556 set by <a href="#gdImageSetClip">gdImageSetClip</a> and defaults
wolffd@0	3557 to the entire image. This function is intended primarily for
wolffd@0	3558 use by those who wish to add functions to gd. All of the gd drawing
wolffd@0	3559 functions already clip safely using this function or its macro
wolffd@0	3560 equivalent in gd.c, gdImageBoundsSafeMacro.
wolffd@0	3561 <PRE>
wolffd@0	3562 ... inside a function ...
wolffd@0	3563 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	3564 int black;
wolffd@0	3565 int white;
wolffd@0	3566 im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
wolffd@0	3567 if (gdImageBoundsSafe(im, 50, 50)) {
wolffd@0	3568 printf("50, 50 is within the image bounds\n");
wolffd@0	3569 } else {
wolffd@0	3570 printf("50, 50 is outside the image bounds\n");
wolffd@0	3571 }
wolffd@0	3572 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	3573 </PRE>
wolffd@0	3574 <DT><A NAME="gdImageGreen">
wolffd@0	3575 int gdImageGreen(gdImagePtr im, int color)</A>
wolffd@0	3576 <STRONG>(MACRO)</STRONG>
wolffd@0	3577 <DD>
wolffd@0	3578 gdImageGreen is a macro which returns the green component of
wolffd@0	3579 the specified color index. Use this macro rather than accessing the
wolffd@0	3580 structure members directly.
wolffd@0	3581 <DT><A NAME="gdImageRed">
wolffd@0	3582 int gdImageRed(gdImagePtr im, int color)</A>
wolffd@0	3583 <STRONG>(MACRO)</STRONG>
wolffd@0	3584 <DD>
wolffd@0	3585 gdImageRed is a macro which returns the red component of
wolffd@0	3586 the specified color index. Use this macro rather than accessing the
wolffd@0	3587 structure members directly.
wolffd@0	3588 <DT><A NAME="gdImageSX">
wolffd@0	3589 int gdImageSX(gdImagePtr im)</A>
wolffd@0	3590 <STRONG>(MACRO)</STRONG>
wolffd@0	3591 <DD>
wolffd@0	3592 gdImageSX is a macro which returns the width of the image
wolffd@0	3593 in pixels. Use this macro rather than accessing the
wolffd@0	3594 structure members directly.
wolffd@0	3595 <DT><A NAME="gdImageSY">
wolffd@0	3596 int gdImageSY(gdImagePtr im)</A>
wolffd@0	3597 <STRONG>(MACRO)</STRONG>
wolffd@0	3598 <DD>
wolffd@0	3599 gdImageSY is a macro which returns the height of the image
wolffd@0	3600 in pixels. Use this macro rather than accessing the
wolffd@0	3601 structure members directly.
wolffd@0	3602 </DL>
wolffd@0	3603 <H3><A NAME="fonts">Fonts and text-handling functions</A></H3>
wolffd@0	3604 <DL>
wolffd@0	3605 <DT><A NAME="gdFontGetSmall">
wolffd@0	3606 gdFontPtr gdFontGetSmall(void)</a>
wolffd@0	3607 <STRONG>(FUNCTION)</STRONG>
wolffd@0	3608 <DD>
wolffd@0	3609 Returns a font pointer for the "small" gd font. Your code must
wolffd@0	3610 include the header file <code>gdfonts.h</code> before
wolffd@0	3611 calling this function. Under Windows, due to the nature of DLLs,
wolffd@0	3612 the use of this function is strongly recommended rather than attempting
wolffd@0	3613 to use the <code>gdFontSmall</code> pointer directly. (You may
wolffd@0	3614 safely assign the result to a local <code>gdFontPtr</code> variable
wolffd@0	3615 in your own code.)
wolffd@0	3616 <p>
wolffd@0	3617 See <a href="#gdImageString">gdImageString</a> for more information
wolffd@0	3618 and examples, or <a href="#gdImageStringFT">gdImageStringFT</a> for a
wolffd@0	3619 freetype-based alternative that supports truetype fonts.
wolffd@0	3620 <DT><A NAME="gdFontGetLarge">
wolffd@0	3621 gdFontPtr gdFontGetLarge(void)</a>
wolffd@0	3622 <STRONG>(FUNCTION)</STRONG>
wolffd@0	3623 <DD>
wolffd@0	3624 Returns a font pointer for the "large" gd font. Your code must
wolffd@0	3625 include the header file <code>gdfontl.h</code> before
wolffd@0	3626 calling this function. Under Windows, due to the nature of DLLs,
wolffd@0	3627 the use of this function is strongly recommended rather than attempting
wolffd@0	3628 to use the <code>gdFontLarge</code> pointer directly. (You may
wolffd@0	3629 safely assign the result to a local <code>gdFontPtr</code> variable
wolffd@0	3630 in your own code.)
wolffd@0	3631 <p>
wolffd@0	3632 See <a href="#gdImageString">gdImageString</a> for more information
wolffd@0	3633 and examples, or <a href="#gdImageStringFT">gdImageStringFT</a> for a
wolffd@0	3634 freetype-based alternative that supports truetype fonts.
wolffd@0	3635 <DT><A NAME="gdFontGetMediumBold">
wolffd@0	3636 gdFontPtr gdFontGetMediumBold(void)</a>
wolffd@0	3637 <STRONG>(FUNCTION)</STRONG>
wolffd@0	3638 <DD>
wolffd@0	3639 Returns a font pointer for the "medium bold" gd font. Your code must
wolffd@0	3640 include the header file <code>gdfontmb.h</code> before
wolffd@0	3641 calling this function. Under Windows, due to the nature of DLLs,
wolffd@0	3642 the use of this function is strongly recommended rather than attempting
wolffd@0	3643 to use the <code>gdFontMediumBold</code> pointer directly. (You may
wolffd@0	3644 safely assign the result to a local <code>gdFontPtr</code> variable
wolffd@0	3645 in your own code.)
wolffd@0	3646 <p>
wolffd@0	3647 See <a href="#gdImageString">gdImageString</a> for more information
wolffd@0	3648 and examples, or <a href="#gdImageStringFT">gdImageStringFT</a> for a
wolffd@0	3649 freetype-based alternative that supports truetype fonts.
wolffd@0	3650 <DT><A NAME="gdFontGetGiant">
wolffd@0	3651 gdFontPtr gdFontGetGiant(void)</a>
wolffd@0	3652 <STRONG>(FUNCTION)</STRONG>
wolffd@0	3653 <DD>
wolffd@0	3654 Returns a font pointer for the "giant" gd font. Your code must
wolffd@0	3655 include the header file <code>gdfontg.h</code> before
wolffd@0	3656 calling this function. Under Windows, due to the nature of DLLs,
wolffd@0	3657 the use of this function is strongly recommended rather than attempting
wolffd@0	3658 to use the <code>gdFontGiant</code> pointer directly. (You may
wolffd@0	3659 safely assign the result to a local <code>gdFontPtr</code> variable
wolffd@0	3660 in your own code.)
wolffd@0	3661 <p>
wolffd@0	3662 See <a href="#gdImageString">gdImageString</a> for more information
wolffd@0	3663 and examples, or <a href="#gdImageStringFT">gdImageStringFT</a> for a
wolffd@0	3664 freetype-based alternative that supports truetype fonts.
wolffd@0	3665 <DT><A NAME="gdFontGetTiny">
wolffd@0	3666 gdFontPtr gdFontGetTiny(void)</a>
wolffd@0	3667 <STRONG>(FUNCTION)</STRONG>
wolffd@0	3668 <DD>
wolffd@0	3669 Returns a font pointer for the "tiny" gd font. Your code must
wolffd@0	3670 include the header file <code>gdfontt.h</code> before
wolffd@0	3671 calling this function. Under Windows, due to the nature of DLLs,
wolffd@0	3672 the use of this function is strongly recommended rather than attempting
wolffd@0	3673 to use the <code>gdFontTiny</code> pointer directly. (You may
wolffd@0	3674 safely assign the result to a local <code>gdFontPtr</code> variable
wolffd@0	3675 in your own code.)
wolffd@0	3676 <p>
wolffd@0	3677 See <a href="#gdImageString">gdImageString</a> for more information
wolffd@0	3678 and examples, or <a href="#gdImageStringFT">gdImageStringFT</a> for a
wolffd@0	3679 freetype-based alternative that supports truetype fonts.
wolffd@0	3680 <DT><A NAME="gdImageChar">
wolffd@0	3681 void gdImageChar(gdImagePtr im, gdFontPtr font, int x, int y,
wolffd@0	3682 int c, int color)</A>
wolffd@0	3683 <STRONG>(FUNCTION)</STRONG>
wolffd@0	3684 <DD>
wolffd@0	3685 gdImageChar is used to draw single characters on the image.
wolffd@0	3686 (To draw multiple characters, use <A HREF="#gdImageString">
wolffd@0	3687 gdImageString</A> or <A HREF="#gdImageString16">
wolffd@0	3688 gdImageString16</A>.
wolffd@0	3689 See also <A HREF="#gdImageStringFT">gdImageStringFT</A> for a high quality
wolffd@0	3690 solution.)
wolffd@0	3691 The second argument is a pointer to a font definition structure; five fonts are
wolffd@0	3692 provided with gd, gdFontTiny, gdFontSmall, gdFontMediumBold,
wolffd@0	3693 gdFontLarge, and gdFontGiant.
wolffd@0	3694 <p>
wolffd@0	3695 You must include the files "gdfontt.h", "gdfonts.h", "gdfontmb.h",
wolffd@0	3696 "gdfontl.h" and "gdfontg.h" respectively
wolffd@0	3697 and (if you are not using a library-based approach) link with the
wolffd@0	3698 corresponding .c files to use the provided fonts.
wolffd@0	3699 <p>
wolffd@0	3700 <blockquote>
wolffd@0	3701 <b>Windows DLL users:</b> although you can use
wolffd@0	3702 these DLL-exported pointers directly, you cannot easily assign them to other
wolffd@0	3703 pointers. This will cause hard-to-debug problems. To avoid such troubles, you
wolffd@0	3704 should call the functions gdFontGetTiny(), gdFontGetSmall(),
wolffd@0	3705 gdFontGetMediumBold(), gdFontGetLarge(), and gdFontGetGiant() in order to
wolffd@0	3706 obtain pointers to the fonts under Windows.
wolffd@0	3707 </blockquote>
wolffd@0	3708 <p>
wolffd@0	3709 The character specified by the fifth
wolffd@0	3710 argument is drawn from left to right in the specified
wolffd@0	3711 color. (See <A HREF="#gdImageCharUp">gdImageCharUp</A> for a way
wolffd@0	3712 of drawing vertical text.) Pixels not
wolffd@0	3713 set by a particular character retain their previous color.
wolffd@0	3714 <PRE>
wolffd@0	3715 #include "gd.h"
wolffd@0	3716 #include "gdfontl.h"
wolffd@0	3717 ... inside a function ...
wolffd@0	3718 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	3719 int black;
wolffd@0	3720 int white;
wolffd@0	3721 im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
wolffd@0	3722 /* Background color (first allocated) */
wolffd@0	3723 black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
wolffd@0	3724 /* Allocate the color white (red, green and blue all maximum). */
wolffd@0	3725 white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
wolffd@0	3726 /* Draw a character. */
wolffd@0	3727 gdImageChar(im, gdFontGetLarge(), 0, 0, 'Q', white);
wolffd@0	3728 /* ... Do something with the image, such as
wolffd@0	3729 saving it to a file... */
wolffd@0	3730 /* Destroy it */
wolffd@0	3731 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	3732 </PRE>
wolffd@0	3733 <DT><A NAME="gdImageCharUp">
wolffd@0	3734 void gdImageCharUp(gdImagePtr im, gdFontPtr font, int x, int y,
wolffd@0	3735 int c, int color)</A>
wolffd@0	3736 <STRONG>(FUNCTION)</STRONG>
wolffd@0	3737 <DD>
wolffd@0	3738 gdImageCharUp is used to draw single characters on the image,
wolffd@0	3739 rotated 90 degrees.
wolffd@0	3740 (To draw multiple characters, use <A HREF="#gdImageStringUp">
wolffd@0	3741 gdImageStringUp</A> or <A HREF="#gdImageStringUp16">
wolffd@0	3742 gdImageStringUp16</A>.) The second argument is a
wolffd@0	3743 pointer to a font definition structure; five fonts are
wolffd@0	3744 provided with gd, gdFontTiny, gdFontSmall, gdFontMediumBold,
wolffd@0	3745 gdFontLarge, and gdFontGiant. You must
wolffd@0	3746 include the files "gdfontt.h", "gdfonts.h", "gdfontmb.h",
wolffd@0	3747 "gdfontl.h" and "gdfontg.h" respectively
wolffd@0	3748 and (if you are not using a library-based approach) link with the
wolffd@0	3749 corresponding .c files to use the provided fonts.
wolffd@0	3750 <p>
wolffd@0	3751 <blockquote>
wolffd@0	3752 <b>Windows DLL users:</b> although you can use
wolffd@0	3753 these DLL-exported pointers directly, you cannot easily assign them to other
wolffd@0	3754 pointers. This will cause hard-to-debug problems. To avoid such troubles, you
wolffd@0	3755 should call the functions gdFontGetTiny(), gdFontGetSmall(),
wolffd@0	3756 gdFontGetMediumBold(), gdFontGetLarge(), and gdFontGetGiant() in order to
wolffd@0	3757 obtain pointers to the fonts under Windows.
wolffd@0	3758 </blockquote>
wolffd@0	3759 <p>
wolffd@0	3760 The character specified by
wolffd@0	3761 the fifth argument is drawn
wolffd@0	3762 from bottom to top, rotated at a 90-degree angle, in the specified
wolffd@0	3763 color. (See <A HREF="#gdImageChar">gdImageChar</A> for a way
wolffd@0	3764 of drawing horizontal text.) Pixels not
wolffd@0	3765 set by a particular character retain their previous color.
wolffd@0	3766 <PRE>
wolffd@0	3767 #include "gd.h"
wolffd@0	3768 #include "gdfontl.h"
wolffd@0	3769 ... inside a function ...
wolffd@0	3770 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	3771 int black;
wolffd@0	3772 int white;
wolffd@0	3773 im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
wolffd@0	3774 /* Background color (first allocated) */
wolffd@0	3775 black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
wolffd@0	3776 /* Allocate the color white (red, green and blue all maximum). */
wolffd@0	3777 white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
wolffd@0	3778 /* Draw a character upwards so it rests against the top of the image. */
wolffd@0	3779 gdImageCharUp(im, gdFontGetLarge(),
wolffd@0	3780 0, gdFontGetLarge()->h, 'Q', white);
wolffd@0	3781 /* ... Do something with the image, such as
wolffd@0	3782 saving it to a file... */
wolffd@0	3783 /* Destroy it */
wolffd@0	3784 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	3785 </PRE>
wolffd@0	3786 <DT><A NAME="gdImageString">
wolffd@0	3787 void gdImageString(gdImagePtr im, gdFontPtr font, int x, int y,
wolffd@0	3788 unsigned char *s, int color)</A>
wolffd@0	3789 <STRONG>(FUNCTION)</STRONG>
wolffd@0	3790 <DD>
wolffd@0	3791 gdImageString is used to draw multiple characters on the image.
wolffd@0	3792 (To draw single characters, use <A HREF="#gdImageChar">
wolffd@0	3793 gdImageChar</A>.) The second argument is a
wolffd@0	3794 pointer to a font definition structure; five fonts are
wolffd@0	3795 provided with gd, gdFontTiny, gdFontSmall, gdFontMediumBold,
wolffd@0	3796 gdFontLarge, and gdFontGiant. You must
wolffd@0	3797 include the files "gdfontt.h", "gdfonts.h", "gdfontmb.h",
wolffd@0	3798 "gdfontl.h" and "gdfontg.h" respectively
wolffd@0	3799 and (if you are not using a library-based approach) link with the
wolffd@0	3800 corresponding .c files to use the provided fonts.
wolffd@0	3801 <p>
wolffd@0	3802 <blockquote>
wolffd@0	3803 <b>Windows DLL users:</b> although you can use
wolffd@0	3804 these DLL-exported pointers directly, you cannot easily assign them to other
wolffd@0	3805 pointers. This will cause hard-to-debug problems. To avoid such troubles, you
wolffd@0	3806 should call the functions gdFontGetTiny(), gdFontGetSmall(),
wolffd@0	3807 gdFontGetMediumBold(), gdFontGetLarge(), and gdFontGetGiant() in order to
wolffd@0	3808 obtain pointers to the fonts under Windows.
wolffd@0	3809 </blockquote>
wolffd@0	3810 The null-terminated C string specified
wolffd@0	3811 by the fifth argument is drawn from left to right in the specified
wolffd@0	3812 color. (See <A HREF="#gdImageStringUp">gdImageStringUp</A> for a way
wolffd@0	3813 of drawing vertical text.
wolffd@0	3814 See also <A HREF="#gdImageStringFT">gdImageStringFT</A> for a high
wolffd@0	3815 quality solution.)
wolffd@0	3816 Pixels not set by a particular character retain their previous color.
wolffd@0	3817 <PRE>
wolffd@0	3818 #include "gd.h"
wolffd@0	3819 #include "gdfontl.h"
wolffd@0	3820 #include <string.h>
wolffd@0	3821 ... inside a function ...
wolffd@0	3822 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	3823 int black;
wolffd@0	3824 int white;
wolffd@0	3825 /* String to draw. */
wolffd@0	3826 char *s = "Hello.";
wolffd@0	3827 im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
wolffd@0	3828 /* Background color (first allocated) */
wolffd@0	3829 black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
wolffd@0	3830 /* Allocate the color white (red, green and blue all maximum). */
wolffd@0	3831 white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
wolffd@0	3832 /* Draw a centered string. */
wolffd@0	3833 gdImageString(im, gdFontGetLarge(),
wolffd@0	3834 im->sx / 2 - (strlen(s) * gdFontGetLarge()->w / 2),
wolffd@0	3835 im->sy / 2 - gdFontGetLarge()->h / 2,
wolffd@0	3836 s, white);
wolffd@0	3837 /* ... Do something with the image, such as
wolffd@0	3838 saving it to a file... */
wolffd@0	3839 /* Destroy it */
wolffd@0	3840 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	3841 </PRE>
wolffd@0	3842 <DT><A NAME="gdImageString16">
wolffd@0	3843 void gdImageString16(gdImagePtr im, gdFontPtr font, int x, int y,
wolffd@0	3844 unsigned short *s, int color)</A>
wolffd@0	3845 <STRONG>(FUNCTION)</STRONG>
wolffd@0	3846 <DD>
wolffd@0	3847 gdImageString16 is used to draw multiple 16-bit characters on the image.
wolffd@0	3848 (To draw single characters, use <A HREF="#gdImageChar">
wolffd@0	3849 gdImageChar16</A>.) The second argument is a
wolffd@0	3850 pointer to a font definition structure; no 16-bit fonts are
wolffd@0	3851 provided with gd as standard equipment and there does not seem to be
wolffd@0	3852 much momentum to create them although the bdftogd script can do so. The
wolffd@0	3853 preferred solution is <a href="#gdImageStringFT">gdImageStringFT</a>, which
wolffd@0	3854 uses freetype to provide truetype font support.
wolffd@0	3855 <p>
wolffd@0	3856 <blockquote>
wolffd@0	3857 <b>Windows DLL users:</b> although you can use
wolffd@0	3858 these DLL-exported pointers directly, you cannot easily assign them to other
wolffd@0	3859 pointers. This will cause hard-to-debug problems. To avoid such troubles, you
wolffd@0	3860 should call the functions gdFontGetTiny(), gdFontGetSmall(),
wolffd@0	3861 gdFontGetMediumBold(), gdFontGetLarge(), and gdFontGetGiant() in order to
wolffd@0	3862 obtain pointers to the fonts under Windows.
wolffd@0	3863 </blockquote>
wolffd@0	3864 The null-terminated string of characters represented as 16-bit unsigned
wolffd@0	3865 short integers specified by the fifth argument is drawn from left to right
wolffd@0	3866 in the specified
wolffd@0	3867 color. (See <A HREF="#gdImageStringUp16">gdImageStringUp16</A> for a way
wolffd@0	3868 of drawing vertical text.) Pixels not
wolffd@0	3869 set by a particular character retain their previous color.
wolffd@0	3870 <p>
wolffd@0	3871 This function was added in gd1.3 to provide a means of rendering
wolffd@0	3872 fonts with more than 256 characters for those who have them. A
wolffd@0	3873 more frequently used routine is <a href="#gdImageString">gdImageString</a>.
wolffd@0	3874 <DT><A NAME="gdImageStringUp">
wolffd@0	3875 void gdImageStringUp(gdImagePtr im, gdFontPtr font, int x, int y,
wolffd@0	3876 unsigned char *s, int color)</A>
wolffd@0	3877 <STRONG>(FUNCTION)</STRONG>
wolffd@0	3878 <DD>
wolffd@0	3879 gdImageStringUp is used to draw multiple characters on the image,
wolffd@0	3880 rotated 90 degrees.
wolffd@0	3881 (To draw single characters, use <A HREF="#gdImageCharUp">
wolffd@0	3882 gdImageCharUp</A>.) The second argument is a
wolffd@0	3883 pointer to a font definition structure; five fonts are
wolffd@0	3884 provided with gd, gdFontTiny, gdFontSmall, gdFontMediumBold,
wolffd@0	3885 gdFontLarge, and gdFontGiant. You must
wolffd@0	3886 include the files "gdfontt.h", "gdfonts.h", "gdfontmb.h",
wolffd@0	3887 "gdfontl.h" and "gdfontg.h" respectively
wolffd@0	3888 and (if you are not using a library-based approach) link with the
wolffd@0	3889 corresponding .c files to use the provided fonts.
wolffd@0	3890 <blockquote>
wolffd@0	3891 <b>Windows DLL users:</b> although you can use
wolffd@0	3892 these DLL-exported pointers directly, you cannot easily assign them to other
wolffd@0	3893 pointers. This will cause hard-to-debug problems. To avoid such troubles, you
wolffd@0	3894 should call the functions gdFontGetTiny(), gdFontGetSmall(),
wolffd@0	3895 gdFontGetMediumBold(), gdFontGetLarge(), and gdFontGetGiant() in order to
wolffd@0	3896 obtain pointers to the fonts under Windows.
wolffd@0	3897 </blockquote>
wolffd@0	3898
wolffd@0	3899 The null-terminated C string specified
wolffd@0	3900 by the fifth argument is drawn from bottom to top (rotated
wolffd@0	3901 90 degrees) in the specified color. (See
wolffd@0	3902 <A HREF="#gdImageString">gdImageString</A> for a way
wolffd@0	3903 of drawing horizontal text.) Pixels not
wolffd@0	3904 set by a particular character retain their previous color.
wolffd@0	3905 <PRE>
wolffd@0	3906 #include "gd.h"
wolffd@0	3907 #include "gdfontl.h"
wolffd@0	3908 #include <string.h>
wolffd@0	3909 ... inside a function ...
wolffd@0	3910 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	3911 int black;
wolffd@0	3912 int white;
wolffd@0	3913 /* String to draw. */
wolffd@0	3914 char *s = "Hello.";
wolffd@0	3915 im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
wolffd@0	3916 /* Background color (first allocated) */
wolffd@0	3917 black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
wolffd@0	3918 /* Allocate the color white (red, green and blue all maximum). */
wolffd@0	3919 white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
wolffd@0	3920 /* Draw a centered string going upwards. Axes are reversed,
wolffd@0	3921 and Y axis is decreasing as the string is drawn. */
wolffd@0	3922 gdImageStringUp(im, gdFontGetLarge(),
wolffd@0	3923 im->w / 2 - gdFontGetLarge()->h / 2,
wolffd@0	3924 im->h / 2 + (strlen(s) * gdFontGetLarge()->w / 2),
wolffd@0	3925 s, white);
wolffd@0	3926 /* ... Do something with the image, such as
wolffd@0	3927 saving it to a file... */
wolffd@0	3928 /* Destroy it */
wolffd@0	3929 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	3930 </PRE>
wolffd@0	3931 <DT><A NAME="gdImageStringUp16">
wolffd@0	3932 void gdImageStringUp16(gdImagePtr im, gdFontPtr font, int x, int y,
wolffd@0	3933 unsigned short *s, int color)</A>
wolffd@0	3934 <STRONG>(FUNCTION)</STRONG>
wolffd@0	3935 <DD>
wolffd@0	3936 gdImageString is used to draw multiple 16-bit characters vertically on
wolffd@0	3937 the image. (To draw single characters, use <A HREF="#gdImageChar">
wolffd@0	3938 gdImageChar</A>.) The second argument is a
wolffd@0	3939 pointer to a font definition structure; five fonts are
wolffd@0	3940 provided with gd, gdFontTiny, gdFontSmall, gdFontMediumBold,
wolffd@0	3941 gdFontLarge, and gdFontGiant. You must
wolffd@0	3942 include the files "gdfontt.h", "gdfonts.h", "gdfontmb.h",
wolffd@0	3943 "gdfontl.h" and "gdfontg.h" respectively
wolffd@0	3944 and (if you are not using a library-based approach) link with the
wolffd@0	3945 corresponding .c files to use the provided fonts.
wolffd@0	3946 <blockquote>
wolffd@0	3947 <b>Windows DLL users:</b> although you can use
wolffd@0	3948 these DLL-exported pointers directly, you cannot easily assign them to other
wolffd@0	3949 pointers. This will cause hard-to-debug problems. To avoid such troubles, you
wolffd@0	3950 should call the functions gdFontGetTiny(), gdFontGetSmall(),
wolffd@0	3951 gdFontGetMediumBold(), gdFontGetLarge(), and gdFontGetGiant() in order to
wolffd@0	3952 obtain pointers to the fonts under Windows.
wolffd@0	3953 </blockquote>
wolffd@0	3954 The null-terminated string of characters represented as 16-bit unsigned
wolffd@0	3955 short integers specified by the fifth argument is drawn from bottom to top
wolffd@0	3956 in the specified color.
wolffd@0	3957 (See <A HREF="#gdImageStringUp16">gdImageStringUp16</A> for a way
wolffd@0	3958 of drawing horizontal text.) Pixels not
wolffd@0	3959 set by a particular character retain their previous color.
wolffd@0	3960 <p>
wolffd@0	3961 This function was added in gd1.3 to provide a means of rendering
wolffd@0	3962 fonts with more than 256 characters for those who have them. A
wolffd@0	3963 more frequently used routine is <a href="#gdImageStringUp">gdImageStringUp</a>.
wolffd@0	3964 <DT><A NAME="gdFTUseFontConfig">int gdFTUseFontConfig(int flag)</a>
wolffd@0	3965 <STRONG>(FUNCTION)</STRONG>
wolffd@0	3966 <DD>
wolffd@0	3967 GD 2.0.29 introduced the ability to use
wolffd@0	3968 <a href="http://freedesktop.org/software/fontconfig">fontconfig patterns</a>
wolffd@0	3969 rather than font file names as parameters to
wolffd@0	3970 <a href="#gdImageStringFT">gdImageStringFT</a>,
wolffd@0	3971 <a href="#gdImageStringFTEx">gdImageStringFTEx</a> and
wolffd@0	3972 <a href="#gdImageStringFTEx">gdImageStringFTCircle</a>.
wolffd@0	3973 For backwards compatibility reasons, the fontlist parameter to those
wolffd@0	3974 functions is still expected to be a full or partial font file path name
wolffd@0	3975 or list thereof by default. However, as a convenience, a single call
wolffd@0	3976 to gdFTUseFontConfig with a nonzero parameter configures gd to expect
wolffd@0	3977 the fontlist parameter to be a fontconfig pattern. Regardless of whether
wolffd@0	3978 the flag argument is nonzero, this function returns true when the
wolffd@0	3979 fontconfig library is available and false when it is not. When fontconfig
wolffd@0	3980 is not available, the fontlist parameter always behaves as in previous
wolffd@0	3981 versions of GD.
wolffd@0	3982 <pre>
wolffd@0	3983 #include "gd.h"
wolffd@0	3984 #include <string.h>
wolffd@0	3985 ... inside a function ...
wolffd@0	3986 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	3987 int black;
wolffd@0	3988 int white;
wolffd@0	3989 int brect[8];
wolffd@0	3990 int x, y;
wolffd@0	3991 char *err;
wolffd@0	3992
wolffd@0	3993 char s = "Hello."; / String to draw. */
wolffd@0	3994 double sz = 40.;
wolffd@0	3995 char fc = "times:bold:italic"; / fontconfig pattern */
wolffd@0	3996
wolffd@0	3997 /* Signal that all freetype font calls in this program will receive
wolffd@0	3998 fontconfig patterns rather than filenames of font files */
wolffd@0	3999 gdUseFontConfig(1);
wolffd@0	4000
wolffd@0	4001 /* obtain brect so that we can size the image */
wolffd@0	4002 err = <A HREF="#gdImageStringFT">gdImageStringFT</A>(NULL,&brect[0],0,fc,sz,0.,0,0,s);
wolffd@0	4003 if (err) {fprintf(stderr,err); return 1;}
wolffd@0	4004
wolffd@0	4005 /* create an image big enough for the string plus a little whitespace */
wolffd@0	4006 x = brect[2]-brect[6] + 6;
wolffd@0	4007 y = brect[3]-brect[7] + 6;
wolffd@0	4008 im = <A HREF="#gdImageCreate">gdImageCreate</A>(x,y);
wolffd@0	4009
wolffd@0	4010 /* Background color (first allocated) */
wolffd@0	4011 white = <A HREF="#gdImageColorResolve">gdImageColorResolve</A>(im, 255, 255, 255);
wolffd@0	4012 black = <A HREF="#gdImageColorResolve">gdImageColorResolve</A>(im, 0, 0, 0);
wolffd@0	4013
wolffd@0	4014 /* render the string, offset origin to center string*/
wolffd@0	4015 /* note that we use top-left coordinate for adjustment
wolffd@0	4016 * since gd origin is in top-left with y increasing downwards. */
wolffd@0	4017 x = 3 - brect[6];
wolffd@0	4018 y = 3 - brect[7];
wolffd@0	4019 err = <A HREF="#gdImageStringFT">gdImageStringFT</A>(im,&brect[0],black,fc,sz,0.0,x,y,s);
wolffd@0	4020 if (err) {fprintf(stderr,err); return 1;}
wolffd@0	4021 </pre>
wolffd@0	4022 <DT><A NAME="gdImageStringFT">
wolffd@0	4023 char gdImageStringFT(gdImagePtr im, int brect,
wolffd@0	4024 int fg, char *fontname, double ptsize, double angle,
wolffd@0	4025 int x, int y, char *string)</A>
wolffd@0	4026 <STRONG>(FUNCTION)</STRONG>
wolffd@0	4027 <DD>
wolffd@0	4028 <strong>RECOMMENDED. New in 1.8.4.</strong> gdImageStringFT draws text using the
wolffd@0	4029 FreeType 2.x library.
wolffd@0	4030 <p>
wolffd@0	4031 gdImageStringFT draws a string of anti-aliased characters on the image using
wolffd@0	4032 the <A HREF=http://www.freetype.org/>FreeType</A>
wolffd@0	4033 library to render user-supplied TrueType fonts. <strong>We do not provide
wolffd@0	4034 TrueType fonts (.ttf and .ttc files). Obtaining them is entirely up to
wolffd@0	4035 you.</strong> The string is anti-aliased, meaning that there should be
wolffd@0	4036 fewer "jaggies" visible. The fontname is the full pathname to a TrueType
wolffd@0	4037 font file, or a font face name if the GDFONTPATH environment variable
wolffd@0	4038 or the compiled-in DEFAULT_FONTPATH macro of gdft.c have been set intelligently. In the absence of a full path, the font face name may be presented with or without extension (2.0.26).
wolffd@0	4039 <p>
wolffd@0	4040 The null-terminated <b>string</b> argument is considered to be encoded via the UTF_8
wolffd@0	4041 standard; also, HTML entities are supported, including decimal,
wolffd@0	4042 hexadecimal, and named entities (2.0.26). Those who are passing
wolffd@0	4043 ordinary ASCII strings may have difficulty with the &
wolffd@0	4044 character unless encoded correctly as & but should have no
wolffd@0	4045 other difficulties.
wolffd@0	4046 <p>
wolffd@0	4047 The string may be arbitrarily scaled (ptsize) and rotated (angle in radians).
wolffd@0	4048 The direction of rotation is counter-clockwise, with 0 radians (0 degrees)
wolffd@0	4049 at 3 o'clock and PI/2 radians (90 degrees) at 12 o'clock.
wolffd@0	4050
wolffd@0	4051 <p>
wolffd@0	4052 The user-supplied int brect[8] array is filled on return from gdImageStringFT
wolffd@0	4053 with the 8 elements representing the 4 corner coordinates of the
wolffd@0	4054 bounding rectangle (the smallest rectangle that completely surrounds the
wolffd@0	4055 rendered string and does not intersect any pixel of the rendered string).
wolffd@0	4056
wolffd@0	4057 <TABLE BORDER="1">
wolffd@0	4058 <TR><TD ALIGN="LEFT" VALIGN="TOP">0</TD><TD ALIGN="LEFT" VALIGN="TOP">
wolffd@0	4059 lower left corner, X position</TD></TR>
wolffd@0	4060 <TR><TD ALIGN="LEFT" VALIGN="TOP">1</TD><TD ALIGN="LEFT" VALIGN="TOP">
wolffd@0	4061 lower left corner, Y position</TD></TR>
wolffd@0	4062 <TR><TD ALIGN="LEFT" VALIGN="TOP">2</TD><TD ALIGN="LEFT" VALIGN="TOP">
wolffd@0	4063 lower right corner, X position</TD></TR>
wolffd@0	4064 <TR><TD ALIGN="LEFT" VALIGN="TOP">3</TD><TD ALIGN="LEFT" VALIGN="TOP">
wolffd@0	4065 lower right corner, Y position</TD></TR>
wolffd@0	4066 <TR><TD ALIGN="LEFT" VALIGN="TOP">4</TD><TD ALIGN="LEFT" VALIGN="TOP">
wolffd@0	4067 upper right corner, X position</TD></TR>
wolffd@0	4068 <TR><TD ALIGN="LEFT" VALIGN="TOP">5</TD><TD ALIGN="LEFT" VALIGN="TOP">
wolffd@0	4069 upper right corner, Y position</TD></TR>
wolffd@0	4070 <TR><TD ALIGN="LEFT" VALIGN="TOP">6</TD><TD ALIGN="LEFT" VALIGN="TOP">
wolffd@0	4071 upper left corner, X position</TD></TR>
wolffd@0	4072 <TR><TD ALIGN="LEFT" VALIGN="TOP">7</TD><TD ALIGN="LEFT" VALIGN="TOP">
wolffd@0	4073 upper left corner, Y position</TD></TR>
wolffd@0	4074 </TABLE>
wolffd@0	4075 <p>
wolffd@0	4076 The points are relative to the text regardless of the angle, so "upper left"
wolffd@0	4077 means in the top left-hand corner seeing the text horizontally.
wolffd@0	4078 <p>
wolffd@0	4079 Use a NULL gdImagePtr to get the bounding rectangle without rendering.
wolffd@0	4080 This is a relatively cheap operation if followed by a rendering of the same
wolffd@0	4081 string, because of the caching of the partial rendering during bounding
wolffd@0	4082 rectangle calculation.
wolffd@0	4083 <p>
wolffd@0	4084 The string is rendered in the color indicated by the gf color index.
wolffd@0	4085 <strong>Use the negative of the desired color index to
wolffd@0	4086 disable anti-aliasing.</strong>
wolffd@0	4087 <p>
wolffd@0	4088 The string may contain UTF-8 sequences like: "&#192;"
wolffd@0	4089 <p>
wolffd@0	4090 gdImageStringFT will return a null char* on success, or an error
wolffd@0	4091 string on failure.
wolffd@0	4092 <PRE>
wolffd@0	4093 #include "gd.h"
wolffd@0	4094 #include <string.h>
wolffd@0	4095 ... inside a function ...
wolffd@0	4096 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	4097 int black;
wolffd@0	4098 int white;
wolffd@0	4099 int brect[8];
wolffd@0	4100 int x, y;
wolffd@0	4101 char *err;
wolffd@0	4102
wolffd@0	4103 char s = "Hello."; / String to draw. */
wolffd@0	4104 double sz = 40.;
wolffd@0	4105 char f = "/usr/local/share/ttf/Times.ttf"; / User supplied font */
wolffd@0	4106
wolffd@0	4107 /* obtain brect so that we can size the image */
wolffd@0	4108 err = <A HREF="#gdImageStringFT">gdImageStringFT</A>(NULL,&brect[0],0,f,sz,0.,0,0,s);
wolffd@0	4109 if (err) {fprintf(stderr,err); return 1;}
wolffd@0	4110
wolffd@0	4111 /* create an image big enough for the string plus a little whitespace */
wolffd@0	4112 x = brect[2]-brect[6] + 6;
wolffd@0	4113 y = brect[3]-brect[7] + 6;
wolffd@0	4114 im = <A HREF="#gdImageCreate">gdImageCreate</A>(x,y);
wolffd@0	4115
wolffd@0	4116 /* Background color (first allocated) */
wolffd@0	4117 white = <A HREF="#gdImageColorResolve">gdImageColorResolve</A>(im, 255, 255, 255);
wolffd@0	4118 black = <A HREF="#gdImageColorResolve">gdImageColorResolve</A>(im, 0, 0, 0);
wolffd@0	4119
wolffd@0	4120 /* render the string, offset origin to center string*/
wolffd@0	4121 /* note that we use top-left coordinate for adjustment
wolffd@0	4122 * since gd origin is in top-left with y increasing downwards. */
wolffd@0	4123 x = 3 - brect[6];
wolffd@0	4124 y = 3 - brect[7];
wolffd@0	4125 err = <A HREF="#gdImageStringFT">gdImageStringFT</A>(im,&brect[0],black,f,sz,0.0,x,y,s);
wolffd@0	4126 if (err) {fprintf(stderr,err); return 1;}
wolffd@0	4127
wolffd@0	4128 /* Write img to stdout */
wolffd@0	4129 <A HREF="#gdImagePng">gdImagePng</A>(im, stdout);
wolffd@0	4130
wolffd@0	4131 /* Destroy it */
wolffd@0	4132 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	4133 </PRE>
wolffd@0	4134 See also <a href="#gdImageStringFTEx">gdImageStringFTEx</a>.
wolffd@0	4135 <DT><A NAME="gdImageStringFTEx">
wolffd@0	4136 char gdImageStringFTEx(gdImagePtr im, int brect,
wolffd@0	4137 int fg, char *fontname, double ptsize, double angle,
wolffd@0	4138 int x, int y, char *string, gdFTStringExtraPtr strex)</A>
wolffd@0	4139 <STRONG>(FUNCTION)</STRONG>
wolffd@0	4140 <DD>
wolffd@0	4141 <strong>New in 2.0.5,</strong> also found in common third-party versions
wolffd@0	4142 of gd. gdImageStringFTEx extends the capabilities of
wolffd@0	4143 <a href="#gdImageStringFT">gdImageStringFT</a> by providing a
wolffd@0	4144 way to pass additional parameters.
wolffd@0	4145 <p>
wolffd@0	4146 If the <code>strex</code> parameter is not null, it must point to a
wolffd@0	4147 <code>gdFTStringExtra</code> structure. As of gd 2.0.5, this structure
wolffd@0	4148 is defined as follows:
wolffd@0	4149 <pre>
wolffd@0	4150 typedef struct {
wolffd@0	4151 /* logical OR of gdFTEX_ values */
wolffd@0	4152 int flags;
wolffd@0	4153 /* fine tune line spacing for '\n' */
wolffd@0	4154 double linespacing;
wolffd@0	4155 /* Preferred character mapping */
wolffd@0	4156 int charmap;
wolffd@0	4157 /* Rendering resolution */
wolffd@0	4158 int hdpi;
wolffd@0	4159 int vdpi;
wolffd@0	4160 char *xshow;
wolffd@0	4161 char *fontpath;
wolffd@0	4162 } gdFTStringExtra, *gdFTStringExtraPtr;
wolffd@0	4163 </pre>
wolffd@0	4164 To output multiline text with a specific line spacing,
wolffd@0	4165 include <code>gdFTEX_LINESPACE</code> in the setting of
wolffd@0	4166 <code>flags</code>:
wolffd@0	4167 <pre>
wolffd@0	4168 flags \|= gdFTEX_LINESPACE;
wolffd@0	4169 </pre>
wolffd@0	4170 And also set <code>linespacing</code> to the desired spacing, expressed as a
wolffd@0	4171 multiple of the font height. Thus a line spacing of 1.0 is the
wolffd@0	4172 minimum to guarantee that lines of text do not collide.
wolffd@0	4173 <p>
wolffd@0	4174 If <code>gdFTEX_LINESPACE</code> is not present, or
wolffd@0	4175 <code>strex</code> is null, or <a href="#gdImageStringFT">gdImageStringFT</a>
wolffd@0	4176 is called, <code>linespacing</code> defaults to 1.05.
wolffd@0	4177 <p>
wolffd@0	4178 To specify a preference for Unicode, Shift_JIS Big5 character encoding,
wolffd@0	4179 set or To output multiline text with a specific line spacing,
wolffd@0	4180 include <code>gdFTEX_CHARMAP</code> in the setting of
wolffd@0	4181 <code>flags</code>:
wolffd@0	4182 <pre>
wolffd@0	4183 flags \|= gdFTEX_CHARMAP;
wolffd@0	4184 </pre>
wolffd@0	4185 And set <code>charmap</code> to the desired value, which can be
wolffd@0	4186 any of gdFTEX_Unicode, gdFTEX_Shift_JIS, gdFTEX_Big5, or gdFTEX_Adobe_Custom.
wolffd@0	4187 If you do not specify a preference, Unicode will be tried first. If the preferred
wolffd@0	4188 character mapping is not found in the font, other character mappings
wolffd@0	4189 are attempted.
wolffd@0	4190 <p>
wolffd@0	4191 GD operates on the assumption that the output image will be
wolffd@0	4192 rendered to a computer screen. By default, gd passes a
wolffd@0	4193 resolution of 96 dpi to the freetype text rendering engine.
wolffd@0	4194 This influences the "hinting" decisions made by the renderer. To
wolffd@0	4195 specify a different resolution, set hdpi and vdpi accordingly
wolffd@0	4196 (in dots per inch) and add <code>gdFTEX_RESOLUTION</code> to <code>flags</code>:
wolffd@0	4197 <pre>
wolffd@0	4198 flags \| gdFTEX_RESOLUTION;
wolffd@0	4199 </pre>
wolffd@0	4200 GD 2.0.29 and later will normally attempt to apply kerning tables, if
wolffd@0	4201 fontconfig is available, to adjust the relative positions of consecutive
wolffd@0	4202 characters more ideally for that pair of characters. This can be turn off by
wolffd@0	4203 specifying the gdFTEX_DISABLE_KERNING flag:
wolffd@0	4204 <pre>
wolffd@0	4205 flags \| gdFTEX_DISABLE_KERNING;
wolffd@0	4206 </pre>
wolffd@0	4207 GD 2.0.29 and later can return a vector of individual character
wolffd@0	4208 position advances, occasionally useful in applications that must know
wolffd@0	4209 exactly where each character begins. This is returned in the xshow
wolffd@0	4210 element of the gdFTStringExtra structure if the gdFTEX_XSHOW
wolffd@0	4211 flag is set:
wolffd@0	4212 <pre>
wolffd@0	4213 flags \| gdFTEX_XSHOW;
wolffd@0	4214 </pre>
wolffd@0	4215 <b>The caller is responsible for calling gdFree() on the xshow
wolffd@0	4216 element after the call</b> if gdFTEX_XSHOW is set.
wolffd@0	4217 <p>
wolffd@0	4218 GD 2.0.29 and later can also return the path to the actual font file
wolffd@0	4219 used if the gdFTEX_RETURNFONTPATHNAME flag is set. This is useful because
wolffd@0	4220 GD 2.0.29 and above are capable of
wolffd@0	4221 selecting a font automatically based on a fontconfig font pattern
wolffd@0	4222 when fontconfig is available. This information is returned in the
wolffd@0	4223 fontpath element of the gdFTStringExtra structure.
wolffd@0	4224 <pre>
wolffd@0	4225 flags \| gdFTEX_RETURNFONTPATHNAME;
wolffd@0	4226 </pre>
wolffd@0	4227 <b>The caller is responsible for calling gdFree() on the fontpath
wolffd@0	4228 element after the call</b> if gdFTEX_RETURNFONTPATHNAME is set.
wolffd@0	4229 <p>
wolffd@0	4230 GD 2.0.29 and later can use fontconfig to resolve
wolffd@0	4231 font names, including fontconfig patterns, if the gdFTEX_FONTCONFIG
wolffd@0	4232 flag is set. As a convenience, this behavior can be made the default
wolffd@0	4233 by calling <a href="#gdFTUseFontConfig">gdFTUseFontConfig</a> with
wolffd@0	4234 a nonzero value. In that situation it is not necessary to set the
wolffd@0	4235 gdFTEX_FONTCONFIG flag on every call; however explicit font path names
wolffd@0	4236 can still be used if the gdFTEX_FONTPATHNAME flag is set:
wolffd@0	4237 <pre>
wolffd@0	4238 flags \| gdFTEX_FONTPATHNAME;
wolffd@0	4239 </pre>
wolffd@0	4240 <p>
wolffd@0	4241 Unless <a href="#gdFTUseFontConfig">gdFTUseFontConfig</a> has been
wolffd@0	4242 called with a nonzero value, GD 2.0.29 and later will still expect
wolffd@0	4243 the fontlist argument to the freetype text output functions to be
wolffd@0	4244 a font file name or list thereof as in previous versions. If you do
wolffd@0	4245 not wish to make fontconfig the default, it is
wolffd@0	4246 still possible to force the use of fontconfig for a single call to
wolffd@0	4247 the freetype text output functions by setting the gdFTEX_FONTCONFIG
wolffd@0	4248 flag:
wolffd@0	4249 <pre>
wolffd@0	4250 flags \| gdFTEX_FONTCONFIG;
wolffd@0	4251 </pre>
wolffd@0	4252 GD 2.0.29 and above can use fontconfig to resolve
wolffd@0	4253 font names, including fontconfig patterns, if the gdFTEX_FONTCONFIG
wolffd@0	4254 flag is set. As a convenience, this behavior can be made the default
wolffd@0	4255 by calling <a href="#gdFTUseFontConfig">gdFTUseFontConfig</a> with
wolffd@0	4256 a nonzero value. In that situation it is not necessary to set the
wolffd@0	4257 gdFTEX_FONTCONFIG flag on every call; however explicit font path names
wolffd@0	4258 can still be used if the gdFTEX_FONTPATHNAME flag is set:
wolffd@0	4259 <pre>
wolffd@0	4260 flags \| gdFTEX_FONTPATHNAME;
wolffd@0	4261 </pre>
wolffd@0	4262 For more information, see <a href="#gdImageStringFT">gdImageStringFT</a>.
wolffd@0	4263 <DT><A NAME="gdImageStringFTCircle">
wolffd@0	4264 char *gdImageStringFTCircle(gdImagePtr im,
wolffd@0	4265 int cx,
wolffd@0	4266 int cy,
wolffd@0	4267 double radius,
wolffd@0	4268 double textRadius,
wolffd@0	4269 double fillPortion,
wolffd@0	4270 char *font,
wolffd@0	4271 double points,
wolffd@0	4272 char *top,
wolffd@0	4273 char *bottom,
wolffd@0	4274 int fgcolor)</A>
wolffd@0	4275 <STRONG>(FUNCTION)</STRONG>
wolffd@0	4276 <DD>
wolffd@0	4277 Draws the text strings specified by <code>top</code> and <code>bottom</code>
wolffd@0	4278 on <code>im</code>, curved along the edge of a circle of radius
wolffd@0	4279 <code>radius</code>, with its center at <code>cx</code> and <code>cy</code>.
wolffd@0	4280 <code>top</code> is written clockwise
wolffd@0	4281 along the top; <code>bottom</code> is written counterclockwise
wolffd@0	4282 along the bottom. <code>textRadius</code> determines the "height"
wolffd@0	4283 of each character; if <code>textRadius</code> is 1/2 of
wolffd@0	4284 <code>radius</code>,
wolffd@0	4285 characters extend halfway from the edge to the center.
wolffd@0	4286 <code>fillPortion</code> varies from 0 to 1.0, with useful values
wolffd@0	4287 from about 0.4 to 0.9, and determines how much of the
wolffd@0	4288 180 degrees of arc assigned to each section of text
wolffd@0	4289 is actually occupied by text; 0.9 looks better than
wolffd@0	4290 1.0 which is rather crowded. <code>font</code> is a freetype
wolffd@0	4291 font; see gdImageStringFT. <code>points</code> is passed to the
wolffd@0	4292 freetype engine and has an effect on hinting; although
wolffd@0	4293 the size of the text is determined by <code>radius</code>,
wolffd@0	4294 <code>textRadius</code>, and <code>fillPortion</code>, you should
wolffd@0	4295 pass a point size that
wolffd@0	4296 "hints" appropriately -- if you know the text will be
wolffd@0	4297 large, pass a large point size such as 24.0 to get the
wolffd@0	4298 best results. <code>fgcolor</code> can be any color, and may have
wolffd@0	4299 an alpha component, do blending, etc.
wolffd@0	4300 <p>
wolffd@0	4301 Returns 0 on success, or an error string otherwise.
wolffd@0	4302 <pre>
wolffd@0	4303 #include <stdio.h>
wolffd@0	4304 #include <gd.h>
wolffd@0	4305
wolffd@0	4306 int main (int argc, char *argv[])
wolffd@0	4307 {
wolffd@0	4308 FILE *in;
wolffd@0	4309 FILE *out;
wolffd@0	4310 gdImagePtr im;
wolffd@0	4311 int radius;
wolffd@0	4312 /* Create an image of text on a circle, with an
wolffd@0	4313 alpha channel so that we can copy it onto a
wolffd@0	4314 background */
wolffd@0	4315 in = fopen("mypicture.jpg", "rb");
wolffd@0	4316 if (!in) {
wolffd@0	4317 im = gdImageCreateTrueColor(300, 300);
wolffd@0	4318 } else {
wolffd@0	4319 im = gdImageCreateFromJpeg(in);
wolffd@0	4320 fclose(in);
wolffd@0	4321 }
wolffd@0	4322 if (gdImageSX(im) < gdImageSY(im)) {
wolffd@0	4323 radius = gdImageSX(im) / 2;
wolffd@0	4324 } else {
wolffd@0	4325 radius = gdImageSY(im) / 2;
wolffd@0	4326 }
wolffd@0	4327 gdStringFTCircle(
wolffd@0	4328 im,
wolffd@0	4329 gdImageSX(im) / 2,
wolffd@0	4330 gdImageSY(im) / 2,
wolffd@0	4331 radius,
wolffd@0	4332 radius / 2,
wolffd@0	4333 0.8,
wolffd@0	4334 "arial",
wolffd@0	4335 24,
wolffd@0	4336 "top text",
wolffd@0	4337 "bottom text",
wolffd@0	4338 gdTrueColorAlpha(240, 240, 255, 32));
wolffd@0	4339 out = fopen("gdfx.png", "wb");
wolffd@0	4340 if (!out) {
wolffd@0	4341 fprintf(stderr, "Can't create gdfx.png\n");
wolffd@0	4342 return 1;
wolffd@0	4343 }
wolffd@0	4344 gdImagePng(im, out);
wolffd@0	4345 fclose(out);
wolffd@0	4346 gdImageDestroy(im);
wolffd@0	4347 return 0;
wolffd@0	4348 }
wolffd@0	4349 </pre>
wolffd@0	4350
wolffd@0	4351 <p>
wolffd@0	4352 For more information, see <a href="#gdImageStringFTEx">gdImageStringFTEx</a>
wolffd@0	4353 and <a href="#gdImageSquareToCircle">gdImageSquareToCircle</a>.
wolffd@0	4354 <DT><A NAME="gdImageStringTTF">
wolffd@0	4355 char gdImageStringTTF(gdImagePtr im, int brect,
wolffd@0	4356 int fg, char *fontname, double ptsize, double angle,
wolffd@0	4357 int x, int y, char *string)</A>
wolffd@0	4358 <STRONG>(FUNCTION)</STRONG>
wolffd@0	4359 <DD>
wolffd@0	4360 <strong>DEPRECATED.</strong> This function simply invokes
wolffd@0	4361 <a href="#gdImageStringFT">gdImageStringFT</a> for backwards
wolffd@0	4362 compatibility with old code that was written with FreeType 1.x.
wolffd@0	4363 <DT><A NAME="gdFontCacheSetup">
wolffd@0	4364 int gdFontCacheSetup(void)</A>
wolffd@0	4365 <STRONG>(FUNCTION)</STRONG>
wolffd@0	4366 <DD>
wolffd@0	4367 This function initializes the font cache for freetype text output
wolffd@0	4368 functions such as <a href="#gdImageStringFTEx">gdImageStringFTEx</a>.
wolffd@0	4369 If this function is not called by the programmer, it is invoked
wolffd@0	4370 automatically on the first truetype text output call, which is
wolffd@0	4371 perfectly safe <b>unless</b> the application is multithreaded.
wolffd@0	4372 Multithreaded applications should directly invoke this function before
wolffd@0	4373 allowing any thread to use freetype text output. Returns 0 on success,
wolffd@0	4374 nonzero if the freetype library fails to initialize.
wolffd@0	4375 <DT><A NAME="gdFontCacheShutdown">
wolffd@0	4376 void gdFontCacheShutdown(void)</A>
wolffd@0	4377 <STRONG>(FUNCTION)</STRONG>
wolffd@0	4378 <DD>
wolffd@0	4379 This function releases the memory used by the freetype font cache
wolffd@0	4380 and the text output mutex. Applications that use gd for their
wolffd@0	4381 entire lifetime, then exit, need not call this function.
wolffd@0	4382 </DL>
wolffd@0	4383 <H3><A NAME="colors">Color-handling functions</A></H3>
wolffd@0	4384 <DL>
wolffd@0	4385 <DT><A NAME="gdImageColorAllocate">
wolffd@0	4386 int gdImageColorAllocate(gdImagePtr im, int r, int g, int b)</A>
wolffd@0	4387 <STRONG>(FUNCTION)</STRONG>
wolffd@0	4388 <DD>
wolffd@0	4389 gdImageColorAllocate finds the first available color index in
wolffd@0	4390 the image specified, sets its RGB values to those requested
wolffd@0	4391 (255 is the maximum for each),
wolffd@0	4392 and returns the index of the new color table entry, or an RGBA
wolffd@0	4393 value in the case of a truecolor image; in either case you can
wolffd@0	4394 then use the returned value as a parameter to drawing functions. When
wolffd@0	4395 creating a new palette-based image, the first time you invoke this function,
wolffd@0	4396 you are setting the background color for that image.
wolffd@0	4397 <P>
wolffd@0	4398 In the event that all <A HREF="#gdMaxColors">gdMaxColors</A> colors
wolffd@0	4399 (256) have already been allocated, gdImageColorAllocate will
wolffd@0	4400 return -1 to indicate failure. (This is not uncommon when
wolffd@0	4401 working with existing PNG files that already use 256 colors.)
wolffd@0	4402 Note that gdImageColorAllocate
wolffd@0	4403 does not check for existing colors that match your request;
wolffd@0	4404 see <A HREF="#gdImageColorExact">gdImageColorExact</A>,
wolffd@0	4405 <A HREF="#gdImageColorClosest">gdImageColorClosest</A> and
wolffd@0	4406 <A HREF="#gdImageColorClosestHWB">gdImageColorClosestHWB</A>
wolffd@0	4407 for ways to locate existing colors that approximate the
wolffd@0	4408 color desired in situations where a new color is not available.
wolffd@0	4409 Also see <A HREF="#gdImageColorResolve">gdImageColorResolve</A>,
wolffd@0	4410 new in gd-1.6.2.
wolffd@0	4411 <PRE>
wolffd@0	4412 ... inside a function ...
wolffd@0	4413 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	4414 int black;
wolffd@0	4415 int red;
wolffd@0	4416 im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
wolffd@0	4417 /* Background color (first allocated) */
wolffd@0	4418 black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
wolffd@0	4419 /* Allocate the color red. */
wolffd@0	4420 red = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 0, 0);
wolffd@0	4421 /* Draw a dashed line from the upper left corner
wolffd@0	4422 to the lower right corner. */
wolffd@0	4423 gdImageDashedLine(im, 0, 0, 99, 99, red);
wolffd@0	4424 /* ... Do something with the image, such as saving
wolffd@0	4425 it to a file... */
wolffd@0	4426 /* Destroy it */
wolffd@0	4427 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	4428 </PRE>
wolffd@0	4429 <DT><A NAME="gdImageColorAllocateAlpha">
wolffd@0	4430 int gdImageColorAllocateAlpha(gdImagePtr im, int r, int g, int b, int a)</A>
wolffd@0	4431 <STRONG>(FUNCTION)</STRONG>
wolffd@0	4432 <DD>
wolffd@0	4433 gdImageColorAllocateAlpha finds the first available color index in
wolffd@0	4434 the image specified, sets its RGBA values to those requested
wolffd@0	4435 (255 is the maximum for red, green and blue, and 127 represents
wolffd@0	4436 full transparency for alpha),
wolffd@0	4437 and returns the index of the new color table entry, or an RGBA
wolffd@0	4438 value in the case of a truecolor image; in either case you can
wolffd@0	4439 then use the returned value as a parameter to drawing functions. When
wolffd@0	4440 creating a new palette-based image, the first time you invoke this function,
wolffd@0	4441 you are setting the background color for that image.
wolffd@0	4442 <P>
wolffd@0	4443 In the event that all <A HREF="#gdMaxColors">gdMaxColors</A> colors
wolffd@0	4444 (256) have already been allocated, gdImageColorAllocate will
wolffd@0	4445 return -1 to indicate failure. (This is not uncommon when
wolffd@0	4446 working with existing palette-based PNG files that already use 256 colors.)
wolffd@0	4447 Note that gdImageColorAllocateAlpha
wolffd@0	4448 does not check for existing colors that match your request;
wolffd@0	4449 see <A HREF="#gdImageColorExactAlpha">gdImageColorExactAlpha</A> and
wolffd@0	4450 <A HREF="#gdImageColorClosestAlpha">gdImageColorClosestAlpha</A>
wolffd@0	4451 for ways to locate existing colors that approximate the
wolffd@0	4452 color desired in situations where a new color is not available.
wolffd@0	4453 Also see <A HREF="#gdImageColorResolveAlpha">gdImageColorResolveAlpha</A>.
wolffd@0	4454 <PRE>
wolffd@0	4455 ... inside a function ...
wolffd@0	4456 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	4457 int black;
wolffd@0	4458 int red;
wolffd@0	4459 im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
wolffd@0	4460 /* Background color (first allocated) */
wolffd@0	4461 black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
wolffd@0	4462 /* Allocate the color red, 50% transparent. */
wolffd@0	4463 red = <A HREF="#gdImageColorAllocateAlpha">gdImageColorAllocateAlpha</A>(im, 255, 0, 0, 64);
wolffd@0	4464 /* Draw a dashed line from the upper left corner to the lower right corner. */
wolffd@0	4465 gdImageDashedLine(im, 0, 0, 99, 99, red);
wolffd@0	4466 /* ... Do something with the image, such as
wolffd@0	4467 saving it to a file... */
wolffd@0	4468 /* Destroy it */
wolffd@0	4469 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	4470 </PRE>
wolffd@0	4471 <DT><A NAME="gdImageColorClosest">
wolffd@0	4472 int gdImageColorClosest(gdImagePtr im, int r, int g, int b)</A>
wolffd@0	4473 <STRONG>(FUNCTION)</STRONG>
wolffd@0	4474 <DD>
wolffd@0	4475 gdImageColorClosest searches the colors which have been
wolffd@0	4476 defined thus far in the image specified and returns the
wolffd@0	4477 index of the color with RGB values closest to those of the
wolffd@0	4478 request. (Closeness is determined by Euclidian distance,
wolffd@0	4479 which is used to determine the distance in three-dimensional color
wolffd@0	4480 space between colors.)
wolffd@0	4481 <P>
wolffd@0	4482 If no colors have yet been allocated in the image,
wolffd@0	4483 gdImageColorClosest returns -1.
wolffd@0	4484 <p>
wolffd@0	4485 When applied to a truecolor image, this function always
wolffd@0	4486 succeeds in returning the desired color.
wolffd@0	4487 <P>
wolffd@0	4488 This function is most useful as a backup method for choosing
wolffd@0	4489 a drawing color when an image already contains
wolffd@0	4490 <A HREF="#gdMaxColors">gdMaxColors</A> (256) colors and
wolffd@0	4491 no more can be allocated. (This is not uncommon when
wolffd@0	4492 working with existing PNG files that already use many colors.)
wolffd@0	4493 See <A HREF="#gdImageColorExact">gdImageColorExact</A>
wolffd@0	4494 for a method of locating exact matches only.
wolffd@0	4495 <PRE>
wolffd@0	4496 ... inside a function ...
wolffd@0	4497 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	4498 FILE *in;
wolffd@0	4499 int red;
wolffd@0	4500 /* Let's suppose that photo.png is a scanned photograph with
wolffd@0	4501 many colors. */
wolffd@0	4502 in = fopen("photo.png", "rb");
wolffd@0	4503 im = <A HREF="#gdImageCreateFromPng">gdImageCreateFromPng</A>(in);
wolffd@0	4504 fclose(in);
wolffd@0	4505 /* Try to allocate red directly */
wolffd@0	4506 red = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 0, 0);
wolffd@0	4507 /* If we fail to allocate red... */
wolffd@0	4508 if (red == (-1)) {
wolffd@0	4509 /* Find the <em>closest</em> color instead. */
wolffd@0	4510 red = gdImageColorClosest(im, 255, 0, 0);
wolffd@0	4511 }
wolffd@0	4512 /* Draw a dashed line from the upper left corner to the lower right corner */
wolffd@0	4513 gdImageDashedLine(im, 0, 0, 99, 99, red);
wolffd@0	4514 /* ... Do something with the image, such as
wolffd@0	4515 saving it to a file... */
wolffd@0	4516 /* Destroy it */
wolffd@0	4517 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	4518 </PRE>
wolffd@0	4519 <DT><A NAME="gdImageColorClosestAlpha">
wolffd@0	4520 int gdImageColorClosestAlpha(gdImagePtr im, int r, int g, int b, int a)</A>
wolffd@0	4521 <STRONG>(FUNCTION)</STRONG>
wolffd@0	4522 <DD>
wolffd@0	4523 gdImageColorClosest searches the colors which have been
wolffd@0	4524 defined thus far in the image specified and returns the
wolffd@0	4525 index of the color with RGBA values closest to those of the
wolffd@0	4526 request. (Closeness is determined by Euclidian distance,
wolffd@0	4527 which is used to determine the distance in four-dimensional color/alpha
wolffd@0	4528 space between colors.)
wolffd@0	4529 <P>
wolffd@0	4530 If no colors have yet been allocated in the image,
wolffd@0	4531 gdImageColorClosestAlpha returns -1.
wolffd@0	4532 <p>
wolffd@0	4533 When applied to a truecolor image, this function always
wolffd@0	4534 succeeds in returning the desired color.
wolffd@0	4535 <P>
wolffd@0	4536 This function is most useful as a backup method for choosing
wolffd@0	4537 a drawing color when a palette-based image already contains
wolffd@0	4538 <A HREF="#gdMaxColors">gdMaxColors</A> (256) colors and
wolffd@0	4539 no more can be allocated. (This is not uncommon when
wolffd@0	4540 working with existing palette-based PNG files that already use many colors.)
wolffd@0	4541 See <A HREF="#gdImageColorExactAlpha">gdImageColorExactAlpha</A>
wolffd@0	4542 for a method of locating exact matches only.
wolffd@0	4543 <PRE>
wolffd@0	4544 ... inside a function ...
wolffd@0	4545 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	4546 FILE *in;
wolffd@0	4547 int red;
wolffd@0	4548 /* Let's suppose that photo.png is a scanned photograph with
wolffd@0	4549 many colors. */
wolffd@0	4550 in = fopen("photo.png", "rb");
wolffd@0	4551 im = <A HREF="#gdImageCreateFromPng">gdImageCreateFromPng</A>(in);
wolffd@0	4552 fclose(in);
wolffd@0	4553 /* Try to allocate red, 50% transparent, directly */
wolffd@0	4554 red = <A HREF="#gdImageColorAllocateAlpha">gdImageColorAllocateAlpha</A>(im, 255, 0, 0, 64);
wolffd@0	4555 /* If we fail to allocate red... */
wolffd@0	4556 if (red == (-1)) {
wolffd@0	4557 /* Find the <em>closest</em> color instead. */
wolffd@0	4558 red = gdImageColorClosestAlpha(im, 255, 0, 0, 64);
wolffd@0	4559 }
wolffd@0	4560 /* Draw a dashed line from the upper left corner to the lower right corner */
wolffd@0	4561 gdImageDashedLine(im, 0, 0, 99, 99, red);
wolffd@0	4562 /* ... Do something with the image, such as
wolffd@0	4563 saving it to a file... */
wolffd@0	4564 /* Destroy it */
wolffd@0	4565 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	4566 </PRE>
wolffd@0	4567 <DT><A NAME="gdImageColorClosestHWB">
wolffd@0	4568 int gdImageColorClosestHWB(gdImagePtr im, int r, int g, int b)</A>
wolffd@0	4569 <STRONG>(FUNCTION)</STRONG>
wolffd@0	4570 <DD>
wolffd@0	4571 gdImageColorClosestHWB searches the colors which have been
wolffd@0	4572 defined thus far in the image specified and returns the
wolffd@0	4573 index of the color with hue, whiteness and blackness closest to the
wolffd@0	4574 requested color. This scheme is typically superior to the
wolffd@0	4575 Euclidian distance scheme used by
wolffd@0	4576 <a href="#gdImageColorClosest">gdImageColorClosest</a>.
wolffd@0	4577 <P>
wolffd@0	4578 If no colors have yet been allocated in the image,
wolffd@0	4579 gdImageColorClosestHWB returns -1.
wolffd@0	4580 <p>
wolffd@0	4581 When applied to a truecolor image, this function always
wolffd@0	4582 succeeds in returning the desired color.
wolffd@0	4583 <P>
wolffd@0	4584 This function is most useful as a backup method for choosing
wolffd@0	4585 a drawing color when an image already contains
wolffd@0	4586 <A HREF="#gdMaxColors">gdMaxColors</A> (256) colors and
wolffd@0	4587 no more can be allocated. (This is not uncommon when
wolffd@0	4588 working with existing PNG files that already use many colors.)
wolffd@0	4589 See <A HREF="#gdImageColorExact">gdImageColorExact</A>
wolffd@0	4590 for a method of locating exact matches only.
wolffd@0	4591 <PRE>
wolffd@0	4592 ... inside a function ...
wolffd@0	4593 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	4594 FILE *in;
wolffd@0	4595 int red;
wolffd@0	4596 /* Let's suppose that photo.png is a scanned photograph with
wolffd@0	4597 many colors. */
wolffd@0	4598 in = fopen("photo.png", "rb");
wolffd@0	4599 im = <A HREF="#gdImageCreateFromPng">gdImageCreateFromPng</A>(in);
wolffd@0	4600 fclose(in);
wolffd@0	4601 /* Try to allocate red directly */
wolffd@0	4602 red = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 0, 0);
wolffd@0	4603 /* If we fail to allocate red... */
wolffd@0	4604 if (red == (-1)) {
wolffd@0	4605 /* Find the <em>closest</em> color instead. */
wolffd@0	4606 red = gdImageColorClosestHWB(im, 255, 0, 0);
wolffd@0	4607 }
wolffd@0	4608 /* Draw a dashed line from the upper left corner to the lower right corner */
wolffd@0	4609 gdImageDashedLine(im, 0, 0, 99, 99, red);
wolffd@0	4610 /* ... Do something with the image, such as
wolffd@0	4611 saving it to a file... */
wolffd@0	4612 /* Destroy it */
wolffd@0	4613 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	4614 </PRE>
wolffd@0	4615 <DT><A NAME="gdImageColorExact">
wolffd@0	4616 int gdImageColorExact(gdImagePtr im, int r, int g, int b)</A>
wolffd@0	4617 <STRONG>(FUNCTION)</STRONG>
wolffd@0	4618 <DD>
wolffd@0	4619 gdImageColorExact searches the colors which have been
wolffd@0	4620 defined thus far in the image specified and returns the
wolffd@0	4621 index of the first color with RGB values which exactly
wolffd@0	4622 match those of the request. If no allocated color matches the
wolffd@0	4623 request precisely, gdImageColorExact returns -1.
wolffd@0	4624 See <A HREF="#gdImageColorClosest">gdImageColorClosest</A>
wolffd@0	4625 for a way to find the color closest to the color requested.
wolffd@0	4626 <p>
wolffd@0	4627 When applied to a truecolor image, this function always
wolffd@0	4628 succeeds in returning the desired color.
wolffd@0	4629 <PRE>
wolffd@0	4630 ... inside a function ...
wolffd@0	4631 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	4632 int red;
wolffd@0	4633 in = fopen("photo.png", "rb");
wolffd@0	4634 im = <A HREF="#gdImageCreateFromPng">gdImageCreateFromPng</A>(in);
wolffd@0	4635 fclose(in);
wolffd@0	4636 /* The image may already contain red; if it does, we'll save a slot
wolffd@0	4637 in the color table by using that color. */
wolffd@0	4638 /* Try to allocate red directly */
wolffd@0	4639 red = gdImageColorExact(im, 255, 0, 0);
wolffd@0	4640 /* If red isn't already present... */
wolffd@0	4641 if (red == (-1)) {
wolffd@0	4642 /* Second best: try to allocate it directly. */
wolffd@0	4643 red = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 0, 0);
wolffd@0	4644 /* Out of colors, so find the <em>closest</em> color instead. */
wolffd@0	4645 red = gdImageColorClosest(im, 255, 0, 0);
wolffd@0	4646 }
wolffd@0	4647 /* Draw a dashed line from the upper left corner to the lower right corner */
wolffd@0	4648 gdImageDashedLine(im, 0, 0, 99, 99, red);
wolffd@0	4649 /* ... Do something with the image, such as
wolffd@0	4650 saving it to a file... */
wolffd@0	4651 /* Destroy it */
wolffd@0	4652 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	4653 </PRE>
wolffd@0	4654 <DT><A NAME="gdImageColorResolve">
wolffd@0	4655 int gdImageColorResolve(gdImagePtr im, int r, int g, int b)</A>
wolffd@0	4656 <STRONG>(FUNCTION)</STRONG>
wolffd@0	4657 <DD>
wolffd@0	4658 gdImageColorResolve searches the colors which have been
wolffd@0	4659 defined thus far in the image specified and returns the
wolffd@0	4660 index of the first color with RGB values which exactly
wolffd@0	4661 match those of the request. If no allocated color matches the
wolffd@0	4662 request precisely, then gdImageColorResolve tries to allocate the
wolffd@0	4663 exact color. If there is no space left in the color table then
wolffd@0	4664 gdImageColorResolve returns the closest color (as in gdImageColorClosest).
wolffd@0	4665 This function always returns an index of a color.
wolffd@0	4666 <p>
wolffd@0	4667 When applied to a truecolor image, this function always
wolffd@0	4668 succeeds in returning the desired color.
wolffd@0	4669 <PRE>
wolffd@0	4670 ... inside a function ...
wolffd@0	4671 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	4672 int red;
wolffd@0	4673 in = fopen("photo.png", "rb");
wolffd@0	4674 im = <A HREF="#gdImageCreateFromPng">gdImageCreateFromPng</A>(in);
wolffd@0	4675 fclose(in);
wolffd@0	4676 /* The image may already contain red; if it does, we'll save a slot
wolffd@0	4677 in the color table by using that color. */
wolffd@0	4678 /* Get index of red, or color closest to red */
wolffd@0	4679 red = gdImageColorResolve(im, 255, 0, 0);
wolffd@0	4680 /* Draw a dashed line from the upper left corner to the lower right corner */
wolffd@0	4681 gdImageDashedLine(im, 0, 0, 99, 99, red);
wolffd@0	4682 /* ... Do something with the image, such as
wolffd@0	4683 saving it to a file... */
wolffd@0	4684 /* Destroy it */
wolffd@0	4685 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	4686 </PRE>
wolffd@0	4687 <DT><A NAME="gdImageColorResolveAlpha">
wolffd@0	4688 int gdImageColorResolveAlpha(gdImagePtr im, int r, int g, int b, int a)</A>
wolffd@0	4689 <STRONG>(FUNCTION)</STRONG>
wolffd@0	4690 <DD>
wolffd@0	4691 gdImageColorResolveAlpha searches the colors which have been
wolffd@0	4692 defined thus far in the image specified and returns the
wolffd@0	4693 index of the first color with RGBA values which exactly
wolffd@0	4694 match those of the request. If no allocated color matches the
wolffd@0	4695 request precisely, then gdImageColorResolveAlpha tries to allocate the
wolffd@0	4696 exact color. If there is no space left in the color table then
wolffd@0	4697 gdImageColorResolveAlpha returns the closest color (as in gdImageColorClosestAlpha).
wolffd@0	4698 This function always returns an index of a color.
wolffd@0	4699 <p>
wolffd@0	4700 When applied to a truecolor image, this function always
wolffd@0	4701 succeeds in returning the desired color.
wolffd@0	4702 <PRE>
wolffd@0	4703 ... inside a function ...
wolffd@0	4704 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	4705 int red;
wolffd@0	4706 in = fopen("photo.png", "rb");
wolffd@0	4707 im = <A HREF="#gdImageCreateFromPng">gdImageCreateFromPng</A>(in);
wolffd@0	4708 fclose(in);
wolffd@0	4709 /* The image may already contain red; if it does,
wolffd@0	4710 we'll save a slot in the color table by using that color. */
wolffd@0	4711 /* Get index of red, 50% transparent, or the next best thing */
wolffd@0	4712 red = gdImageColorResolveAlpha(im, 255, 0, 0, 64);
wolffd@0	4713 /* Draw a dashed line from the upper left corner to the lower right corner */
wolffd@0	4714 gdImageDashedLine(im, 0, 0, 99, 99, red);
wolffd@0	4715 /* ... Do something with the image, such as saving
wolffd@0	4716 it to a file... */
wolffd@0	4717 /* Destroy it */
wolffd@0	4718 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	4719 </PRE>
wolffd@0	4720 <DT><A NAME="gdImageColorsTotal">
wolffd@0	4721 int gdImageColorsTotal(gdImagePtr im)</A>
wolffd@0	4722 <STRONG>(MACRO)</STRONG>
wolffd@0	4723 <DD>
wolffd@0	4724 gdImageColorsTotal is a macro which returns the number of
wolffd@0	4725 colors currently allocated in a palette image. For truecolor
wolffd@0	4726 images, the result of this call is undefined and should not
wolffd@0	4727 be used.
wolffd@0	4728 <DT><A NAME="gdImageRed">
wolffd@0	4729 int gdImageRed(gdImagePtr im, int c)</A>
wolffd@0	4730 <STRONG>(MACRO)</STRONG>
wolffd@0	4731 <DD>
wolffd@0	4732 gdImageRed is a macro which returns the red portion
wolffd@0	4733 of the specified color in the image. This macro works
wolffd@0	4734 for both palette and truecolor images.
wolffd@0	4735 <DT><A NAME="gdImageGreen">
wolffd@0	4736 int gdImageGreen(gdImagePtr im, int c)</A>
wolffd@0	4737 <STRONG>(MACRO)</STRONG>
wolffd@0	4738 <DD>
wolffd@0	4739 gdImageGreen is a macro which returns the green portion
wolffd@0	4740 of the specified color in the image. This macro works
wolffd@0	4741 for both palette and truecolor images.
wolffd@0	4742 <DT><A NAME="gdImageBlue">
wolffd@0	4743 int gdImageBlue(gdImagePtr im, int c)</A>
wolffd@0	4744 <STRONG>(MACRO)</STRONG>
wolffd@0	4745 <DD>
wolffd@0	4746 gdImageBlue is a macro which returns the blue portion
wolffd@0	4747 of the specified color in the image. This macro works
wolffd@0	4748 for both palette and truecolor images.
wolffd@0	4749 <DT><A NAME="gdImageGetInterlaced">
wolffd@0	4750 int gdImageGetInterlaced(gdImagePtr im)</A>
wolffd@0	4751 <STRONG>(MACRO)</STRONG>
wolffd@0	4752 <DD>
wolffd@0	4753 gdImageGetInterlaced is a macro which returns true (1)
wolffd@0	4754 if the image is interlaced, false (0) if not.
wolffd@0	4755 Use this macro to obtain this information; do not
wolffd@0	4756 access the structure directly.
wolffd@0	4757 See <A HREF="#gdImageInterlace">gdImageInterlace</A> for
wolffd@0	4758 a means of interlacing images.
wolffd@0	4759 <DT><A NAME="gdImageGetTransparent">
wolffd@0	4760 int gdImageGetTransparent(gdImagePtr im)</A>
wolffd@0	4761 <STRONG>(MACRO)</STRONG>
wolffd@0	4762 <DD>
wolffd@0	4763 gdImageGetTransparent is a macro which returns the
wolffd@0	4764 current transparent color index in the image.
wolffd@0	4765 If there is no transparent color, gdImageGetTransparent
wolffd@0	4766 returns -1. Use this macro to obtain this information; do not
wolffd@0	4767 access the structure directly.
wolffd@0	4768 <DT><A NAME="gdImageColorDeallocate">
wolffd@0	4769 void gdImageColorDeallocate(gdImagePtr im, int color)</A>
wolffd@0	4770 <STRONG>(FUNCTION)</STRONG>
wolffd@0	4771 <DD>
wolffd@0	4772 gdImageColorDeallocate marks the specified color as being
wolffd@0	4773 available for reuse. It does not attempt to determine whether
wolffd@0	4774 the color index is still in use in the image. After a call
wolffd@0	4775 to this function, the next call to
wolffd@0	4776 <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>
wolffd@0	4777 for the same image will set new RGB values for that
wolffd@0	4778 color index, changing the color of any pixels which
wolffd@0	4779 have that index as a result. If multiple calls to
wolffd@0	4780 gdImageColorDeallocate are made consecutively, the lowest-numbered
wolffd@0	4781 index among them will be reused by the next
wolffd@0	4782 <A HREF="#gdImageColorAllocate"> gdImageColorAllocate</A> call.
wolffd@0	4783 <PRE>
wolffd@0	4784 ... inside a function ...
wolffd@0	4785 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	4786 int red, blue;
wolffd@0	4787 in = fopen("photo.png", "rb");
wolffd@0	4788 im = <A HREF="#gdImageCreateFromPng">gdImageCreateFromPng</A>(in);
wolffd@0	4789 fclose(in);
wolffd@0	4790 /* Look for red in the color table. */
wolffd@0	4791 red = gdImageColorExact(im, 255, 0, 0);
wolffd@0	4792 /* If red is present... */
wolffd@0	4793 if (red != (-1)) {
wolffd@0	4794 /* Deallocate it. */
wolffd@0	4795 gdImageColorDeallocate(im, red);
wolffd@0	4796 /* Allocate blue, reusing slot in table.
wolffd@0	4797 Existing red pixels will change color. */
wolffd@0	4798 blue = gdImageColorAllocate(im, 0, 0, 255);
wolffd@0	4799 }
wolffd@0	4800 /* ... Do something with the image, such as
wolffd@0	4801 saving it to a file... */
wolffd@0	4802 /* Destroy it */
wolffd@0	4803 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	4804 </PRE>
wolffd@0	4805 <DT><A NAME="gdImageColorTransparent">
wolffd@0	4806 void gdImageColorTransparent(gdImagePtr im, int color)</A>
wolffd@0	4807 <STRONG>(FUNCTION)</STRONG>
wolffd@0	4808 <DD>
wolffd@0	4809 gdImageColorTransparent sets the transparent color index
wolffd@0	4810 for the specified image to the specified index. To indicate
wolffd@0	4811 that there should be <em>no</em> transparent color, invoke
wolffd@0	4812 gdImageColorTransparent with a color index of -1. Note that
wolffd@0	4813 JPEG images do not support transparency, so this setting has no effect
wolffd@0	4814 when writing JPEG images.
wolffd@0	4815 <P>
wolffd@0	4816 The color index used should be an index
wolffd@0	4817 allocated by <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>,
wolffd@0	4818 whether explicitly invoked by your code or implicitly
wolffd@0	4819 invoked by loading an image.
wolffd@0	4820 In order to ensure that your image has a reasonable appearance
wolffd@0	4821 when viewed by users who do not have transparent background
wolffd@0	4822 capabilities (or when you are writing a JPEG-format file, which does
wolffd@0	4823 not support transparency), be sure to give reasonable RGB values to the
wolffd@0	4824 color you allocate for use as a transparent color,
wolffd@0	4825 <em>even though it will be transparent on systems
wolffd@0	4826 that support PNG transparency</em>.
wolffd@0	4827 <PRE>
wolffd@0	4828 ... inside a function ...
wolffd@0	4829 <A HREF="#gdImagePtr">gdImagePtr</A> im;
wolffd@0	4830 int black;
wolffd@0	4831 FILE in, out;
wolffd@0	4832 in = fopen("photo.png", "rb");
wolffd@0	4833 im = <A HREF="#gdImageCreateFromPng">gdImageCreateFromPng</A>(in);
wolffd@0	4834 fclose(in);
wolffd@0	4835 /* Look for black in the color table and make it transparent. */
wolffd@0	4836 black = <A HREF="#gdImageColorExact">gdImageColorExact</A>(im, 0, 0, 0);
wolffd@0	4837 /* If black is present... */
wolffd@0	4838 if (black != (-1)) {
wolffd@0	4839 /* Make it transparent */
wolffd@0	4840 gdImageColorTransparent(im, black);
wolffd@0	4841 }
wolffd@0	4842 /* Save the newly-transparent image back to the file */
wolffd@0	4843 out = fopen("photo.png", "wb");
wolffd@0	4844 <A HREF="#gdImagePng">gdImagePng</A>(im, out);
wolffd@0	4845 fclose(out);
wolffd@0	4846 /* Destroy it */
wolffd@0	4847 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	4848 </PRE>
wolffd@0	4849 <DT><A NAME="gdImageTrueColor">
wolffd@0	4850 void gdImageTrueColor(int red, int green, int blue)</A>
wolffd@0	4851 <STRONG>(MACRO)</STRONG>
wolffd@0	4852 <DD>
wolffd@0	4853 gdImageTrueColor returns an RGBA color value for use when
wolffd@0	4854 drawing on a truecolor image. Red, green, and blue are all
wolffd@0	4855 in the range between 0 (off) and 255 (maximum). This macro should
wolffd@0	4856 not be used with palette-based images. If you need to write
wolffd@0	4857 code which is compatible with both palette-based and
wolffd@0	4858 truecolor images, use <a href="#gdImageColorResolve">gdImageColorResolve</a>.
wolffd@0	4859 <DT><A NAME="gdTrueColorAlpha">
wolffd@0	4860 void gdTrueColorAlpha(int red, int green, int blue, int alpha)</A>
wolffd@0	4861 <STRONG>(MACRO)</STRONG>
wolffd@0	4862 <DD>
wolffd@0	4863 gdTrueColorAlpha returns an RGBA color value for use when
wolffd@0	4864 drawing on a truecolor image with alpha channel transparency. Red,
wolffd@0	4865 green, and blue are all
wolffd@0	4866 in the range between 0 (off) and 255 (maximum). Alpha is in the
wolffd@0	4867 range between 0 (opaque) and 127 (fully transparent). This macro should
wolffd@0	4868 not be used with palette-based images. If you need to write
wolffd@0	4869 code which is compatible with both palette-based and
wolffd@0	4870 truecolor images, use <a href="#gdImageColorResolveAlpha">gdImageColorResolveAlpha</a>.</DL>
wolffd@0	4871 <H3><A NAME="copying">Copying and resizing functions</A></H3>
wolffd@0	4872 <DL>
wolffd@0	4873
wolffd@0	4874 <DT><A NAME="gdImageCopy">void gdImageCopy(gdImagePtr dst, gdImagePtr src, int dstX, int dstY, int srcX, int srcY, int w, int h)
wolffd@0	4875 <STRONG> (FUNCTION)</STRONG>
wolffd@0	4876 <DD>
wolffd@0	4877 gdImageCopy is used to copy a rectangular portion of one image to
wolffd@0	4878 another image. (For a way of stretching or shrinking the image
wolffd@0	4879 in the process, see <A HREF="#gdImageCopyResized">
wolffd@0	4880 gdImageCopyResized</A>.)
wolffd@0	4881 <P>
wolffd@0	4882 The <code>dst</code> argument is the destination image to which the
wolffd@0	4883 region will be copied. The <code>src</code> argument is the source
wolffd@0	4884 image from which the region is copied. The <code>dstX</code>
wolffd@0	4885 and <code>dstY</code> arguments specify the point in the destination
wolffd@0	4886 image to which the region will be copied. The <code>srcX</code>
wolffd@0	4887 and <code>srcY</code> arguments specify the upper left corner
wolffd@0	4888 of the region in the source image. The <code>w</code>
wolffd@0	4889 and <code>h</code> arguments specify the width and height
wolffd@0	4890 of the region.
wolffd@0	4891 <P>
wolffd@0	4892 When you copy a region from one location in an image to another
wolffd@0	4893 location in the same image, gdImageCopy will perform as expected
wolffd@0	4894 unless the regions overlap, in which case the result is
wolffd@0	4895 unpredictable.
wolffd@0	4896 <P>
wolffd@0	4897 <strong>Important note on copying between images:</strong> since
wolffd@0	4898 different images do
wolffd@0	4899 not necessarily have the same color tables, pixels are not simply set to the
wolffd@0	4900 same color index values to copy them. gdImageCopy will attempt
wolffd@0	4901 to find an identical RGB value in the destination image for
wolffd@0	4902 each pixel in the copied portion of the source image by
wolffd@0	4903 invoking <A HREF="#gdImageColorExact">gdImageColorExact</A>. If
wolffd@0	4904 such a value is not found, gdImageCopy will attempt to
wolffd@0	4905 allocate colors as needed using <A HREF="#gdImageColorAllocate">
wolffd@0	4906 gdImageColorAllocate</A>. If both of these methods fail,
wolffd@0	4907 gdImageCopy will invoke <A HREF="#gdImageColorClosest">
wolffd@0	4908 gdImageColorClosest</A> to find the color in the destination
wolffd@0	4909 image which most closely approximates the color of the
wolffd@0	4910 pixel being copied.
wolffd@0	4911 <PRE>
wolffd@0	4912 ... Inside a function ...
wolffd@0	4913 <A HREF="#gdImagePtr">gdImagePtr</A> im_in;
wolffd@0	4914 <A HREF="#gdImagePtr">gdImagePtr</A> im_out;
wolffd@0	4915 int x, y;
wolffd@0	4916 FILE *in;
wolffd@0	4917 FILE *out;
wolffd@0	4918 /* Load a small png to tile the larger one with */
wolffd@0	4919 in = fopen("small.png", "rb");
wolffd@0	4920 im_in = <A HREF="#gdImageCreateFromPng">gdImageCreateFromPng</A>(in);
wolffd@0	4921 fclose(in);
wolffd@0	4922 /* Make the output image four times as large on both axes */
wolffd@0	4923 im_out = <A HREF="#gdImageCreate">gdImageCreate</A>(im_in->sx * 4, im_in->sy * 4);
wolffd@0	4924 /* Now tile the larger image using the smaller one */
wolffd@0	4925 for (y = 0; (y < 4); y++) {
wolffd@0	4926 for (x = 0; (x < 4); x++) {
wolffd@0	4927 gdImageCopy(im_out, im_in,
wolffd@0	4928 x * im_in->sx, y * im_in->sy,
wolffd@0	4929 0, 0,
wolffd@0	4930 im_in->sx, im_in->sy);
wolffd@0	4931 }
wolffd@0	4932 }
wolffd@0	4933 out = fopen("tiled.png", "wb");
wolffd@0	4934 <A HREF="#gdImagePng">gdImagePng</A>(im_out, out);
wolffd@0	4935 fclose(out);
wolffd@0	4936 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im_in);
wolffd@0	4937 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im_out);
wolffd@0	4938 </PRE>
wolffd@0	4939 <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)
wolffd@0	4940 <STRONG> (FUNCTION)</STRONG>
wolffd@0	4941 <DD>
wolffd@0	4942 gdImageCopyResized is used to copy a rectangular portion of one image to
wolffd@0	4943 another image. The X and Y dimensions of the original region and the
wolffd@0	4944 destination region can vary, resulting in stretching or shrinking of
wolffd@0	4945 the region as appropriate. (For a simpler version of this function
wolffd@0	4946 which does not deal with resizing, see <A HREF="#gdImageCopy">
wolffd@0	4947 gdImageCopy</A>.)
wolffd@0	4948 <P>
wolffd@0	4949 The <code>dst</code> argument is the destination image to which the
wolffd@0	4950 region will be copied. The <code>src</code> argument is the source
wolffd@0	4951 image from which the region is copied. The <code>dstX</code>
wolffd@0	4952 and <code>dstY</code> arguments specify the point in the destination
wolffd@0	4953 image to which the region will be copied. The <code>srcX</code>
wolffd@0	4954 and <code>srcY</code> arguments specify the upper left corner
wolffd@0	4955 of the region in the source image. The <code>dstW</code>
wolffd@0	4956 and <code>dstH</code> arguments specify the width and height
wolffd@0	4957 of the destination region. The <code>srcW</code>
wolffd@0	4958 and <code>srcH</code> arguments specify the width and height
wolffd@0	4959 of the source region and can differ from the destination size,
wolffd@0	4960 allowing a region to be scaled during the copying process.
wolffd@0	4961 <P>
wolffd@0	4962 When you copy a region from one location in an image to another
wolffd@0	4963 location in the same image, gdImageCopy will perform as expected
wolffd@0	4964 unless the regions overlap, in which case the result is
wolffd@0	4965 unpredictable. If this presents a problem, create a scratch image
wolffd@0	4966 in which to keep intermediate results.
wolffd@0	4967 <P>
wolffd@0	4968 <strong>Important note on copying between images:</strong> since images
wolffd@0	4969 do not necessarily have the same color tables, pixels are not simply set
wolffd@0	4970 to the same color index values to copy them. gdImageCopy will attempt
wolffd@0	4971 to find an identical RGB value in the destination image for
wolffd@0	4972 each pixel in the copied portion of the source image by
wolffd@0	4973 invoking <A HREF="#gdImageColorExact">gdImageColorExact</A>. If
wolffd@0	4974 such a value is not found, gdImageCopy will attempt to
wolffd@0	4975 allocate colors as needed using <A HREF="#gdImageColorAllocate">
wolffd@0	4976 gdImageColorAllocate</A>. If both of these methods fail,
wolffd@0	4977 gdImageCopy will invoke <A HREF="#gdImageColorClosest">
wolffd@0	4978 gdImageColorClosest</A> to find the color in the destination
wolffd@0	4979 image which most closely approximates the color of the
wolffd@0	4980 pixel being copied.
wolffd@0	4981 <PRE>
wolffd@0	4982 ... Inside a function ...
wolffd@0	4983 <A HREF="#gdImagePtr">gdImagePtr</A> im_in;
wolffd@0	4984 <A HREF="#gdImagePtr">gdImagePtr</A> im_out;
wolffd@0	4985 int x, y;
wolffd@0	4986 FILE *in;
wolffd@0	4987 FILE *out;
wolffd@0	4988 /* Load a small png to expand in the larger one */
wolffd@0	4989 in = fopen("small.png", "rb");
wolffd@0	4990 im_in = <A HREF="#gdImageCreateFromPng">gdImageCreateFromPng</A>(in);
wolffd@0	4991 fclose(in);
wolffd@0	4992 /* Make the output image four times as large on both axes */
wolffd@0	4993 im_out = <A HREF="#gdImageCreate">gdImageCreate</A>(im_in->sx * 4, im_in->sy * 4);
wolffd@0	4994 /* Now copy the smaller image, but four times larger */
wolffd@0	4995 gdImageCopyResized(im_out, im_in, 0, 0, 0, 0,
wolffd@0	4996 im_out->sx, im_out->sy,
wolffd@0	4997 im_in->sx, im_in->sy);
wolffd@0	4998 out = fopen("large.png", "wb");
wolffd@0	4999 <A HREF="#gdImagePng">gdImagePng</A>(im_out, out);
wolffd@0	5000 fclose(out);
wolffd@0	5001 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im_in);
wolffd@0	5002 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im_out);
wolffd@0	5003 </PRE>
wolffd@0	5004 <DT><A NAME="gdImageCopyResampled">void gdImageCopyResampled(gdImagePtr dst, gdImagePtr src, int dstX, int dstY, int srcX, int srcY, int destW, int destH, int srcW, int srcH)
wolffd@0	5005 <STRONG> (FUNCTION)</STRONG>
wolffd@0	5006 <DD>
wolffd@0	5007 gdImageCopyResampled is used to copy a rectangular portion of one image to
wolffd@0	5008 another image, smoothly interpolating pixel values so that, in particular,
wolffd@0	5009 reducing the size of an image still retains a great deal of clarity. The
wolffd@0	5010 X and Y dimensions of the original region and the
wolffd@0	5011 destination region can vary, resulting in stretching or shrinking of
wolffd@0	5012 the region as appropriate. (For a simpler version of this function
wolffd@0	5013 which does not deal with resizing, see <A HREF="#gdImageCopy">
wolffd@0	5014 gdImageCopy</A>. For a version which does not interpolate pixel values,
wolffd@0	5015 see <A HREF="#gdImageCopyResized">gdImageCopyResized</A>.
wolffd@0	5016 <p>
wolffd@0	5017 Pixel values are only interpolated if the destination image is a
wolffd@0	5018 truecolor image. Otherwise,
wolffd@0	5019 <a href="#gdImageCopyResized">gdImageCopyResized</a> is
wolffd@0	5020 automatically invoked.
wolffd@0	5021 <P>
wolffd@0	5022 The <code>dst</code> argument is the destination image to which the
wolffd@0	5023 region will be copied. The <code>src</code> argument is the source
wolffd@0	5024 image from which the region is copied. The <code>dstX</code>
wolffd@0	5025 and <code>dstY</code> arguments specify the point in the destination
wolffd@0	5026 image to which the region will be copied. The <code>srcX</code>
wolffd@0	5027 and <code>srcY</code> arguments specify the upper left corner
wolffd@0	5028 of the region in the source image. The <code>dstW</code>
wolffd@0	5029 and <code>dstH</code> arguments specify the width and height
wolffd@0	5030 of the destination region. The <code>srcW</code>
wolffd@0	5031 and <code>srcH</code> arguments specify the width and height
wolffd@0	5032 of the source region and can differ from the destination size,
wolffd@0	5033 allowing a region to be scaled during the copying process.
wolffd@0	5034 <P>
wolffd@0	5035 When you copy a region from one location in an image to another
wolffd@0	5036 location in the same image, gdImageCopy will perform as expected
wolffd@0	5037 unless the regions overlap, in which case the result is
wolffd@0	5038 unpredictable. If this presents a problem, create a scratch image
wolffd@0	5039 in which to keep intermediate results.
wolffd@0	5040 <P>
wolffd@0	5041 <strong>Important note on copying between images:</strong> since images
wolffd@0	5042 do not necessarily have the same color tables, pixels are not simply set
wolffd@0	5043 to the same color index values to copy them. If the destination image
wolffd@0	5044 is a palette image, gd will use the
wolffd@0	5045 <a href="#gdImageColorResolve">gdImageColorResolve</a> function to
wolffd@0	5046 determine the best color available.
wolffd@0	5047 <PRE>
wolffd@0	5048 ... Inside a function ...
wolffd@0	5049 <A HREF="#gdImagePtr">gdImagePtr</A> im_in;
wolffd@0	5050 <A HREF="#gdImagePtr">gdImagePtr</A> im_out;
wolffd@0	5051 int x, y;
wolffd@0	5052 FILE *in;
wolffd@0	5053 FILE *out;
wolffd@0	5054 /* Load a large png to shrink in the smaller one */
wolffd@0	5055 in = fopen("large.png", "rb");
wolffd@0	5056 im_in = <A HREF="#gdImageCreateFromPng">gdImageCreateFromPng</A>(in);
wolffd@0	5057 fclose(in);
wolffd@0	5058 /* Make the output image four times as small on both axes. Use
wolffd@0	5059 a true color image so that we can interpolate colors. */
wolffd@0	5060 im_out = <A HREF="#gdImageCreate">gdImageCreateTrueColor</A>(im_in->sx / 4, im_in->sy / 4);
wolffd@0	5061 /* Now copy the large image, but four times smaller */
wolffd@0	5062 gdImageCopyResampled(im_out, im_in, 0, 0, 0, 0,
wolffd@0	5063 im_out->sx, im_out->sy,
wolffd@0	5064 im_in->sx, im_in->sy);
wolffd@0	5065 out = fopen("large.png", "wb");
wolffd@0	5066 <A HREF="#gdImagePng">gdImagePng</A>(im_out, out);
wolffd@0	5067 fclose(out);
wolffd@0	5068 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im_in);
wolffd@0	5069 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im_out);
wolffd@0	5070 </PRE>
wolffd@0	5071 <DT><A NAME="gdImageCopyRotated">void gdImageCopyRotated(gdImagePtr dst, gdImagePtr src, double dstX, double dstY, int srcX, int srcY, int srcW, int srcH, int angle)
wolffd@0	5072 <STRONG> (FUNCTION)</STRONG>
wolffd@0	5073 <DD>
wolffd@0	5074 gdImageCopyRotated is used to copy a rectangular portion of one image to
wolffd@0	5075 another image, or to another region of the same image. <strong>The srcX and
wolffd@0	5076 srcY coordinates specify the upper left corner of the source area; however,
wolffd@0	5077 the dstX and dstY coordinates specify the CENTER of the destination area.
wolffd@0	5078 </strong> This important distinction is made because the rotated rectangle may
wolffd@0	5079 may or may not be parallel to the X and Y axes. The destination coordinates
wolffd@0	5080 may be floating point, as the center of the desired destination area may lie
wolffd@0	5081 at the center of a pixel (0.5 pixels) rather than its upper left corner.
wolffd@0	5082 The angle specified is an integer number of degrees, between 0 and 360,
wolffd@0	5083 with 0 degrees causing no change, and counterclockwise rotation as
wolffd@0	5084 the angle increases.
wolffd@0	5085 <P>
wolffd@0	5086 When you copy a region from one location in an image to another
wolffd@0	5087 location in the same image, gdImageCopyRotated will perform as expected
wolffd@0	5088 unless the regions overlap, in which case the result is
wolffd@0	5089 unpredictable. If this presents a problem, create a scratch image
wolffd@0	5090 in which to keep intermediate results.
wolffd@0	5091 <P>
wolffd@0	5092 <strong>Important note on copying between images:</strong> since
wolffd@0	5093 palette-based images do not necessarily have the same color tables, pixels
wolffd@0	5094 are not simply set to the same color index values to copy them.
wolffd@0	5095 If the destination image is not a truecolor image,
wolffd@0	5096 <a href="#gdImageColorResolveAlpha">gdImageColorResolveAlpha</a> is
wolffd@0	5097 used to choose the destination pixel.
wolffd@0	5098 <PRE>
wolffd@0	5099 ... Inside a function ...
wolffd@0	5100 <A HREF="#gdImagePtr">gdImagePtr</A> im_in;
wolffd@0	5101 <A HREF="#gdImagePtr">gdImagePtr</A> im_out;
wolffd@0	5102 int x, y;
wolffd@0	5103 int a;
wolffd@0	5104 FILE *in;
wolffd@0	5105 FILE *out;
wolffd@0	5106 /* Load a small png to rotate in the larger one */
wolffd@0	5107 in = fopen("small.png", "rb");
wolffd@0	5108 im_in = <A HREF="#gdImageCreateFromPng">gdImageCreateFromPng</A>(in);
wolffd@0	5109 fclose(in);
wolffd@0	5110 /* Make the output image four times as large on both axes */
wolffd@0	5111 im_out = <A HREF="#gdImageCreate">gdImageCreate</A>(im_in->sx * 4, im_in->sy * 4);
wolffd@0	5112 /* Now rotate the smaller image */
wolffd@0	5113 for (a = 0; (a < 360); a += 45) {
wolffd@0	5114 double x = cos(a * .0174532925) * gdImageSX(im_out) / 2;
wolffd@0	5115 double y = -sin(a * .0174532925) * gdImageSY(im_out) / 2;
wolffd@0	5116 gdImageCopyRotated(im_out, im_in,
wolffd@0	5117 gdImageSX(im_out) / 2 + x,
wolffd@0	5118 gdImageSY(im_out) / 2 + y,
wolffd@0	5119 0, 0,
wolffd@0	5120 gdImageSX(im_in),
wolffd@0	5121 gdImageSY(im_in),
wolffd@0	5122 a);
wolffd@0	5123 }
wolffd@0	5124 out = fopen("large.png", "wb");
wolffd@0	5125 <A HREF="#gdImagePng">gdImagePng</A>(im_out, out);
wolffd@0	5126 fclose(out);
wolffd@0	5127 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im_in);
wolffd@0	5128 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im_out);
wolffd@0	5129 </PRE>
wolffd@0	5130
wolffd@0	5131 <DT><A NAME="gdImageCopyMerge">void gdImageCopyMerge(gdImagePtr dst, gdImagePtr src, int dstX, int dstY, int srcX, int srcY, int w, int h, int pct)
wolffd@0	5132 <STRONG> (FUNCTION)</STRONG>
wolffd@0	5133 <DD>
wolffd@0	5134 gdImageCopyMerge is almost identical to <a href=#gdImageCopy>gdImageCopy</a>, except that
wolffd@0	5135 it 'merges' the two images by an amount specified in the last parameter. If the last
wolffd@0	5136 parameter is 100, then it will function identically to gdImageCopy - the source image replaces
wolffd@0	5137 the pixels in the destination.
wolffd@0	5138 <p>
wolffd@0	5139 If, however, the <strong>pct</strong> parameter is less than 100, then the two images are merged.
wolffd@0	5140 With pct = 0, no action is taken.
wolffd@0	5141 <p>This feature is most useful to 'highlight' sections of an image by merging a solid color with
wolffd@0	5142 pct = 50:
wolffd@0	5143 <PRE>
wolffd@0	5144 ... Inside a function ...
wolffd@0	5145 gdImageCopyMerge(im_out, im_in, 100, 200, 0, 0, 30, 50, 50);
wolffd@0	5146 </PRE>
wolffd@0	5147
wolffd@0	5148 <DT><A NAME="gdImageCopyMergeGray">void gdImageCopyMergeGray(gdImagePtr dst, gdImagePtr src, int dstX, int dstY, int srcX, int srcY, int
wolffd@0	5149 w, int h, int pct)
wolffd@0	5150 <STRONG> (FUNCTION)</STRONG>
wolffd@0	5151 <DD>
wolffd@0	5152 gdImageCopyMergeGray is almost identical to <a href=#gdImageCopyMerge>gdImageCopyMerge</a>,
wolffd@0	5153 except that when merging images it preserves the hue of the source by converting the destination
wolffd@0	5154 pixels to grey scale before the copy operation.
wolffd@0	5155 <PRE>
wolffd@0	5156 ... Inside a function ...
wolffd@0	5157 gdImageCopyMergeGray(im_out, im_in, 100, 200, 0, 0, 30, 50, 50);
wolffd@0	5158 </PRE>
wolffd@0	5159
wolffd@0	5160 <DT><A NAME="gdImagePaletteCopy">void gdImagePaletteCopy(gdImagePtr dst, gdImagePtr src)
wolffd@0	5161 <STRONG> (FUNCTION)</STRONG>
wolffd@0	5162 <DD>
wolffd@0	5163 Copies a palette from one image to another, attempting to match the colors in the target image
wolffd@0	5164 to the colors
wolffd@0	5165 in the source palette.
wolffd@0	5166 <DT><A NAME="gdImageSquareToCircle">void gdImageSquareToCircle(gdImagePtr im, int radius)</a>
wolffd@0	5167 <STRONG> (FUNCTION)</STRONG>
wolffd@0	5168 <DD>
wolffd@0	5169 <b>im MUST be square, but can have any size.</b> Returns a new image
wolffd@0	5170 of width and height radius * 2, in which the X axis of
wolffd@0	5171 the original has been remapped to theta (angle) and the Y axis
wolffd@0	5172 of the original has been remapped to rho (distance from center).
wolffd@0	5173 This is known as a "polar coordinate transform."
wolffd@0	5174 See also <a href="#gdImageStringFTCircle">gdImageStringFTCircle</a>, which
wolffd@0	5175 uses this function internally.
wolffd@0	5176 <DT><A NAME="gdImageSharpen">void gdImageSharpen(gdImagePtr im, int pct)</a>
wolffd@0	5177 <STRONG> (FUNCTION)</STRONG>
wolffd@0	5178 <DD>
wolffd@0	5179 Sharpens the specified image. pct is a sharpening percentage, and
wolffd@0	5180 can be greater than 100. Silently does nothing to non-truecolor images.
wolffd@0	5181 Silently does nothing for pct<0. Transparency/alpha channel are not
wolffd@0	5182 altered.
wolffd@0	5183 </DL>
wolffd@0	5184 <H3><A NAME="misc">Miscellaneous Functions</A></H3>
wolffd@0	5185 <DL>
wolffd@0	5186
wolffd@0	5187 <DT><A NAME="gdImageCompare">int gdImageCompare(gdImagePtr im1, gdImagePtr im2)
wolffd@0	5188 <STRONG> (FUNCTION)</STRONG>
wolffd@0	5189 <DD>
wolffd@0	5190 gdImageCompare returns a bitmap indicating if the two images are different. The members of the
wolffd@0	5191 bitmap are defined in gd.h, but the most important is GD_CMP_IMAGE, which indicated that the images
wolffd@0	5192 will actually appear different when displayed. Other, less important, differences relate to pallette
wolffd@0	5193 entries. Any difference in the transparent colour is assumed to make images display differently,
wolffd@0	5194 even if the transparent colour is not used.
wolffd@0	5195 <PRE>
wolffd@0	5196 ... Inside a function ...
wolffd@0	5197 cmpMask = gdImageCompare(im1, im2);
wolffd@0	5198 </PRE>
wolffd@0	5199
wolffd@0	5200 <DT><A NAME="gdImageInterlace">gdImageInterlace(gdImagePtr im, int interlace)</A> <strong>(FUNCTION)</strong>
wolffd@0	5201 <DD>
wolffd@0	5202 gdImageInterlace is used to determine whether an image should be stored
wolffd@0	5203 in a linear fashion, in which lines will appear on the display from
wolffd@0	5204 first to last, or in an interlaced fashion, in which the image
wolffd@0	5205 will "fade in" over several passes. By default, images are not
wolffd@0	5206 interlaced. (When writing JPEG images, interlacing implies generating
wolffd@0	5207 progressive JPEG files, which are represented as a series of scans of
wolffd@0	5208 increasing quality. Noninterlaced gd images result in regular
wolffd@0	5209 [sequential] JPEG data streams.)
wolffd@0	5210 <P>
wolffd@0	5211 A nonzero value for the interlace argument turns on interlace;
wolffd@0	5212 a zero value turns it off. Note that interlace has no effect
wolffd@0	5213 on other functions, and has no meaning unless you save the
wolffd@0	5214 image in PNG or JPEG format; the gd and xbm formats do not support
wolffd@0	5215 interlace.
wolffd@0	5216 <P>
wolffd@0	5217 When a PNG is loaded with
wolffd@0	5218 <A HREF="#gdImageCreateFromPng">gdImageCreateFromPng</A> or a JPEG is
wolffd@0	5219 loaded with
wolffd@0	5220 <A HREF="#gdImageCreateFromJpeg">gdImageCreateFromJpeg</A>, interlace
wolffd@0	5221 will be set according to the setting in the PNG or JPEG file.
wolffd@0	5222 <P>
wolffd@0	5223 Note that many PNG and JPEG viewers and web browsers do <em>not</em>
wolffd@0	5224 support interlace or the incremental display of progressive
wolffd@0	5225 JPEGs. However, the interlaced PNG or progressive JPEG should still
wolffd@0	5226 display; it will simply appear all at once, just as other images do.
wolffd@0	5227 <PRE>
wolffd@0	5228 gdImagePtr im;
wolffd@0	5229 FILE *out;
wolffd@0	5230 /* ... Create or load the image... */
wolffd@0	5231
wolffd@0	5232 /* Now turn on interlace */
wolffd@0	5233 gdImageInterlace(im, 1);
wolffd@0	5234 /* And open an output file */
wolffd@0	5235 out = fopen("test.png", "wb");
wolffd@0	5236 /* And save the image -- could also use <A HREF="#gdImageJpeg">gdImageJpeg</A> */
wolffd@0	5237 <A HREF="#gdImagePng">gdImagePng</A>(im, out);
wolffd@0	5238 fclose(out);
wolffd@0	5239 <A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
wolffd@0	5240 </PRE>
wolffd@0	5241 <DT><A NAME="gdFree">gdFree(void *ptr)</A> <strong>(FUNCTION)</strong>
wolffd@0	5242 <DD>
wolffd@0	5243 gdFree provides a reliable way to free memory allocated by functions
wolffd@0	5244 such as <a href="#gdImagePngPtr">gdImagePngPtr</a> which return
wolffd@0	5245 blocks of memory. Use of this function guarantees that the
wolffd@0	5246 version of <code>free()</code> that is ultimately called will
wolffd@0	5247 be intended for use with the version of <code>malloc()</code> that
wolffd@0	5248 originally allocated the block.
wolffd@0	5249 </DL>
wolffd@0	5250 <H3><A NAME="constants">Constants</A></H3>
wolffd@0	5251 <DL>
wolffd@0	5252 <DT><A NAME="gdAntiAliased">gdAntiAliased</A> <strong>(CONSTANT)</strong>
wolffd@0	5253 <DD>
wolffd@0	5254 Used in place of a color when invoking a line-drawing
wolffd@0	5255 function such as <A HREF="#gdImageLine">gdImageLine</A>
wolffd@0	5256 or <A HREF="#gdImageRectangle">gdImageRectangle</A>.
wolffd@0	5257 When gdAntiAliased is used as the color, the foreground color
wolffd@0	5258 set with <a href="#gdImageSetAntiAliased">gdImageSetAntiAliased</a>
wolffd@0	5259 is used, with antialiasing mechanisms to minimize any
wolffd@0	5260 "jagged" appearance.
wolffd@0	5261 For more information, see
wolffd@0	5262 <a href="#gdImageSetAntiAliased">gdImageSetAntiAliased</a>.
wolffd@0	5263 <DT><A NAME="gdBrushed">gdBrushed</A> <strong>(CONSTANT)</strong>
wolffd@0	5264 <DD>
wolffd@0	5265 Used in place of a color when invoking a line-drawing
wolffd@0	5266 function such as <A HREF="#gdImageLine">gdImageLine</A>
wolffd@0	5267 or <A HREF="#gdImageRectangle">gdImageRectangle</A>.
wolffd@0	5268 When gdBrushed is used as the color, the brush
wolffd@0	5269 image set with <A HREF="#gdImageSetBrush">gdImageSetBrush</A>
wolffd@0	5270 is drawn in place of each pixel of the line (the brush is
wolffd@0	5271 usually larger than one pixel, creating the effect
wolffd@0	5272 of a wide paintbrush). See also
wolffd@0	5273 <A HREF="#gdStyledBrushed">gdStyledBrushed</A> for a way
wolffd@0	5274 to draw broken lines with a series of distinct copies of an image.
wolffd@0	5275 <DT><A NAME="gdMaxColors"><code>gdMaxColors</code><strong>(CONSTANT)</strong>
wolffd@0	5276 <DD>
wolffd@0	5277 The constant 256. This is the maximum number of colors in a palette-based
wolffd@0	5278 PNG file according to the PNG standard, and is also the maximum number of
wolffd@0	5279 colors in a palette-based gd image. This of course does not apply to
wolffd@0	5280 truecolor images.
wolffd@0	5281 <DT><A NAME="gdStyled">gdStyled</A> <strong>(CONSTANT)</strong>
wolffd@0	5282 <DD>
wolffd@0	5283 Used in place of a color when invoking a line-drawing
wolffd@0	5284 function such as <A HREF="#gdImageLine">gdImageLine</A>
wolffd@0	5285 or <A HREF="#gdImageRectangle">gdImageRectangle</A>.
wolffd@0	5286 When gdStyled is used as the color, the colors of the pixels are
wolffd@0	5287 drawn successively from the style that has been
wolffd@0	5288 set with <A HREF="#gdImageSetStyle">gdImageSetStyle</A>.
wolffd@0	5289 If the color of a pixel is equal to
wolffd@0	5290 <A HREF="#gdTransparent">gdTransparent</A>, that pixel
wolffd@0	5291 is not altered. (This mechanism is completely unrelated
wolffd@0	5292 to the "transparent color" of the image itself; see
wolffd@0	5293 <A HREF="#gdImageColorTransparent">gdImageColorTransparent</A>
wolffd@0	5294 gdImageColorTransparent for that mechanism.) See also
wolffd@0	5295 <A NAME="#gdStyledBrushed"> gdStyledBrushed</A>.
wolffd@0	5296 <DT><A NAME="gdStyledBrushed">gdStyledBrushed</A> <strong>(CONSTANT)</strong>
wolffd@0	5297 <DD>
wolffd@0	5298 Used in place of a color when invoking a line-drawing
wolffd@0	5299 function such as <A HREF="#gdImageLine">gdImageLine</A>
wolffd@0	5300 or <A HREF="#gdImageRectangle">gdImageRectangle</A>.
wolffd@0	5301 When gdStyledBrushed is used as the color, the brush
wolffd@0	5302 image set with <A HREF="#gdImageSetBrush">gdImageSetBrush</A>
wolffd@0	5303 is drawn at each pixel of the line, providing that the
wolffd@0	5304 style set with <A HREF="#gdImageSetStyle">gdImageSetStyle</A>
wolffd@0	5305 contains a nonzero value (OR gdTransparent, which
wolffd@0	5306 does not equal zero but is supported for consistency)
wolffd@0	5307 for the current pixel. (Pixels are drawn successively from the style as the
wolffd@0	5308 line is drawn, returning to the beginning when the
wolffd@0	5309 available pixels in the style are exhausted.) Note that
wolffd@0	5310 this differs from the behavior of <A HREF="#gdStyled">gdStyled</A>,
wolffd@0	5311 in which the values in the style are used as actual
wolffd@0	5312 pixel colors, except for gdTransparent.
wolffd@0	5313 <DT><A NAME="gdDashSize">gdDashSize</A> <strong>(CONSTANT)</strong>
wolffd@0	5314 <DD>
wolffd@0	5315 The length of a dash in a dashed line. Defined to be 4 for
wolffd@0	5316 backwards compatibility with programs that use
wolffd@0	5317 <A NAME="gdImageDashedLine">gdImageDashedLine</A>. New
wolffd@0	5318 programs should use <A NAME="gdImageSetStyle">
wolffd@0	5319 gdImageSetStyle</A> and call the standard
wolffd@0	5320 <A NAME="gdImageLine">gdImageLine</A> function
wolffd@0	5321 with the special "color" <A NAME="gdStyled">
wolffd@0	5322 gdStyled</A> or <A NAME="gdStyledBrushed">gdStyledBrushed</A>.
wolffd@0	5323 <DT><A NAME="gdTiled">gdTiled</A> <strong>(CONSTANT)</strong>
wolffd@0	5324 <DD>
wolffd@0	5325 Used in place of a normal color in <A HREF="#gdImageFilledRectangle">
wolffd@0	5326 gdImageFilledRectangle</A>, <A HREF="#gdImageFilledPolygon">
wolffd@0	5327 gdImageFilledPolygon</A>,
wolffd@0	5328 <A HREF="#gdImageFill">gdImageFill</A>, and <A HREF="#gdImageFillToBorder">
wolffd@0	5329 gdImageFillToBorder</A>. gdTiled selects a pixel from the
wolffd@0	5330 tile image set with <A HREF="#gdImageSetTile">gdImageSetTile</A>
wolffd@0	5331 in such a way as to ensure that the filled area will be
wolffd@0	5332 tiled with copies of the tile image. See the discussions of
wolffd@0	5333 <A HREF="#gdImageFill">gdImageFill</A> and
wolffd@0	5334 <A HREF="#gdImageFillToBorder">gdImageFillToBorder</A> for special
wolffd@0	5335 restrictions regarding those functions.
wolffd@0	5336 <DT><A NAME="gdTransparent">gdTransparent</A> <strong>(CONSTANT)</strong>
wolffd@0	5337 <DD>
wolffd@0	5338 Used in place of a normal color in a style to be set with
wolffd@0	5339 <A HREF="#gdImageSetStyle">gdImageSetStyle</A>.
wolffd@0	5340 gdTransparent is <strong>not</strong> the transparent
wolffd@0	5341 color index of the image; for that functionality please
wolffd@0	5342 see <A HREF="#gdImageColorTransparent">gdImageColorTransparent</A>.
wolffd@0	5343 </DL>
wolffd@0	5344
wolffd@0	5345 <A NAME="gdformat"><H3>About the additional .gd image file format</H3></A>
wolffd@0	5346 In addition to reading and writing the PNG and JPEG formats and reading the
wolffd@0	5347 X Bitmap format, gd has the capability to read and write its
wolffd@0	5348 own ".gd" format. This format is <em>not</em> intended for
wolffd@0	5349 general purpose use and should never be used to distribute
wolffd@0	5350 images. It is not a compressed format. Its purpose is solely to
wolffd@0	5351 allow very fast loading of images your program needs often in
wolffd@0	5352 order to build other images for output. If you are experiencing
wolffd@0	5353 performance problems when loading large, fixed PNG images your
wolffd@0	5354 program needs to produce its output images, you may wish
wolffd@0	5355 to examine the functions <A HREF="#gdImageCreateFromGd">
wolffd@0	5356 gdImageCreateFromGd</A> and <A HREF="#gdImageGd">gdImageGd</A>,
wolffd@0	5357 which read and write .gd format images.
wolffd@0	5358
wolffd@0	5359 <P>
wolffd@0	5360 The program "pngtogd.c" is provided as a simple way of converting
wolffd@0	5361 .png files to .gd format. I emphasize again that you will not
wolffd@0	5362 need to use this format unless you have a need for high-speed loading
wolffd@0	5363 of a few frequently-used images in your program.
wolffd@0	5364
wolffd@0	5365 <A NAME="gd2format"><H3>About the .gd2 image file format</H3></A>
wolffd@0	5366 In addition to reading and writing the PNG format and reading the
wolffd@0	5367 X Bitmap format, gd has the capability to read and write its
wolffd@0	5368 own ".gd2" format. This format is <em>not</em> intended for
wolffd@0	5369 general purpose use and should never be used to distribute
wolffd@0	5370 images. It is a compressed format allowing pseudo-random access
wolffd@0	5371 to large image files. Its purpose is solely to
wolffd@0	5372 allow very fast loading of <strong>parts</strong> of images
wolffd@0	5373 If you are experiencing
wolffd@0	5374 performance problems when loading large, fixed PNG or JPEG images your
wolffd@0	5375 program needs to produce its output images, you may wish
wolffd@0	5376 to examine the functions <A HREF="#gdImageCreateFromGd2">
wolffd@0	5377 gdImageCreateFromGd2</A>, <A HREF="#gdImageCreateFromGd2Part">
wolffd@0	5378 gdImageCreateFromGd2Part</A> and <A HREF="#gdImageGd2">gdImageGd2</A>,
wolffd@0	5379 which read and write .gd2 format images.
wolffd@0	5380
wolffd@0	5381 <P>
wolffd@0	5382 The program "pngtogd2.c" is provided as a simple way of converting
wolffd@0	5383 .png files to .gd2 format.
wolffd@0	5384
wolffd@0	5385 <A NAME="gdioctx"><H3>About the gdIOCtx structure</H3></A>
wolffd@0	5386 Version 1.5 of GD added a new style of I/O based on an IOCtx
wolffd@0	5387 structure (the most up-to-date version can be found in gd_io.h):
wolffd@0	5388 <PRE>
wolffd@0	5389 typedef struct gdIOCtx {
wolffd@0	5390 int (getC)(struct gdIOCtx);
wolffd@0	5391 int (getBuf)(struct gdIOCtx, void*, int);
wolffd@0	5392
wolffd@0	5393 void (putC)(struct gdIOCtx, int);
wolffd@0	5394 int (putBuf)(struct gdIOCtx, const void*, int);
wolffd@0	5395
wolffd@0	5396 int (seek)(struct gdIOCtx, const int); /* Returns 1 on SUCCESS */
wolffd@0	5397 long (tell)(struct gdIOCtx);
wolffd@0	5398
wolffd@0	5399 void (free)(struct gdIOCtx);
wolffd@0	5400
wolffd@0	5401 } gdIOCtx;
wolffd@0	5402 </PRE>
wolffd@0	5403
wolffd@0	5404 Most functions that accepted files in previous versions now also have a
wolffd@0	5405 counterpart that accepts an I/O context. These functions have a 'Ctx'
wolffd@0	5406 suffix.
wolffd@0	5407 <p>
wolffd@0	5408 The <xxx>Ctx routines use the function pointers in the I/O context pointed to
wolffd@0	5409 by gdIOCtx to perform all I/O. Examples of how to implement an I/O context
wolffd@0	5410 can be found in io_file.c (which provides a wrapper for file routines), and
wolffd@0	5411 io_dp.c (which implements in-memory storage).
wolffd@0	5412 <p>
wolffd@0	5413 It is not necessary to implement all functions in an I/O context if you know
wolffd@0	5414 that it will only be used in limited cirsumstances. At the time of writing
wolffd@0	5415 (Version 1.6.1, July 1999), the known requirements are:
wolffd@0	5416 <p>
wolffd@0	5417 <Table>
wolffd@0	5418 <TR><TD>All</TD><td width=20> </td><TD>Must have 'free',</td></tr>
wolffd@0	5419 <TR><TD>Anything that reads from the context</TD><td></td><TD>Must have 'getC' and 'getBuf',</td></tr>
wolffd@0	5420 <TR><TD>Anything that writes to the context</TD><td></td><TD>Must have 'putC' and 'putBuf'.</td></tr>
wolffd@0	5421 <TR><TD>If gdCreateFromGd2Part is called</td><td></td><TD>Must also have 'seek' and 'tell'. Note: seek must return 1 on SUCCESS and 0 on FAILURE.</td></tr>
wolffd@0	5422 <TR><TD>If gdImageGd2 is called</td><td></td><TD>Must also have 'seek' and 'tell'.</td></tr>
wolffd@0	5423 </Table>
wolffd@0	5424
wolffd@0	5425
wolffd@0	5426
wolffd@0	5427 <A NAME="informing"><H3>Please tell us you're using gd!</H3>
wolffd@0	5428 When you contact us and let us know you are using gd,
wolffd@0	5429 you help us justify the time spent in maintaining and improving
wolffd@0	5430 it. So please let us know. If the results are publicly
wolffd@0	5431 visible on the web, a URL is a wonderful thing to receive, but
wolffd@0	5432 if it's not a publicly visible project, a simple note is just
wolffd@0	5433 as welcome.
wolffd@0	5434
wolffd@0	5435 <A NAME="support"><H3>How do I get support?</H3></A>
wolffd@0	5436 <h4>Free Support</h4>
wolffd@0	5437
wolffd@0	5438 Anyone can mail questions about the gd library using the
wolffd@0	5439 <a href="http://www.libgd.org/Wiki/Support">LibGD support</a>. However,
wolffd@0	5440 we receive a very large volume of email on many subjects, and while we do
wolffd@0	5441 our best to respond to all queries this can take some time. Sometimes
wolffd@0	5442 the response must take the form of an eventual new release or
wolffd@0	5443 an addition to a FAQ or other document, as opposed to an detailed individual response.
wolffd@0	5444
wolffd@0	5445 <h4>Hourly Support</h4>
wolffd@0	5446 Those requiring support in detail may arrange for direct support
wolffd@0	5447 from the maintaines, at the rate of $50/hr, billed
wolffd@0	5448 directly by credit card. Purchase orders are also accepted from
wolffd@0	5449 Fortune 500 corporations and institutions in good standing.
wolffd@0	5450 To make arrangements, contact <A HREF="http://www.libgd.org/Contact">Pierre-A. Joye</A>. To avoid delay
wolffd@0	5451 and/or confusion, be sure to specifically mention that you wish to purchase gd support at the
wolffd@0	5452 hourly rate above.
wolffd@0	5453
wolffd@0	5454 <A NAME="issues"><H3>How do I report issues, bugs or features request?</H3></A>
wolffd@0	5455 Bugs, feature requests or other issues can be reported using the
wolffd@0	5456 <A HREF="http://bugs.libgd.org">libGD.org issues tracker.</A> as well as using
wolffd@0	5457 one of our support channels: <a href="http://www.libgd.org/Wiki/Support">LibGD support</a>
wolffd@0	5458
wolffd@0	5459 <H3><A NAME="index">Alphabetical quick index</A></H3>
wolffd@0	5460 <A HREF="#gdAntiAliased">gdAntiAliased</A> \|
wolffd@0	5461 <A HREF="#gdBrushed">gdBrushed</A> \|
wolffd@0	5462 <A HREF="#gdDashSize">gdDashSize</A> \|
wolffd@0	5463 <A HREF="#gdFont">gdFont</A> \|
wolffd@0	5464 <A HREF="#gdFontGetHuge">gdFontGetHuge</A> \|
wolffd@0	5465 <A HREF="#gdFontGetLarge">gdFontGetLarge</A> \|
wolffd@0	5466 <A HREF="#gdFontGetMediumBold">gdFontGetMediumBold</A> \|
wolffd@0	5467 <A HREF="#gdFontGetSmall">gdFontGetSmall</A> \|
wolffd@0	5468 <A HREF="#gdFontGetTiny">gdFontGetTiny</A> \|
wolffd@0	5469 <A HREF="#gdFontCacheSetup">gdFontCacheSetup</A> \|
wolffd@0	5470 <A HREF="#gdFontCacheShutdown">gdFontCacheShutdown</A> \|
wolffd@0	5471 <A HREF="#gdFontPtr">gdFontPtr</A> \|
wolffd@0	5472 <A HREF="#gdFree">gdFree</A> \|
wolffd@0	5473 <A HREF="#gdImage">gdImage</A> \|
wolffd@0	5474 <A HREF="#gdImageAlphaBlending">gdImageAlphaBlending</A> \|
wolffd@0	5475 <A HREF="#gdImageArc">gdImageArc</A> \|
wolffd@0	5476 <A HREF="#gdImageBlue">gdImageBlue</A> \|
wolffd@0	5477 <A HREF="#gdImageBoundsSafe">gdImageBoundsSafe</A> \|
wolffd@0	5478 <A HREF="#gdImageChar">gdImageChar</A> \|
wolffd@0	5479 <A HREF="#gdImageCharUp">gdImageCharUp</A> \|
wolffd@0	5480 <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A> \|
wolffd@0	5481 <A HREF="#gdImageColorAllocateAlpha">gdImageColorAllocateAlpha</A> \|
wolffd@0	5482 <A HREF="#gdImageColorClosest">gdImageColorClosest</A> \|
wolffd@0	5483 <A HREF="#gdImageColorClosestAlpha">gdImageColorClosestAlpha</A> \|
wolffd@0	5484 <A HREF="#gdImageColorClosestHWB">gdImageColorClosestHWB</A> \|
wolffd@0	5485 <A HREF="#gdImageColorDeallocate">gdImageColorDeallocate</A> \|
wolffd@0	5486 <A HREF="#gdImageColorExact">gdImageColorExact</A> \|
wolffd@0	5487 <A HREF="#gdImageColorExactAlpha">gdImageColorExactAlpha</A> \|
wolffd@0	5488 <A HREF="#gdImageColorResolve">gdImageColorResolve</A> \|
wolffd@0	5489 <A HREF="#gdImageColorResolveAlpha">gdImageColorResolveAlpha</A> \|
wolffd@0	5490 <A HREF="#gdImageColorTransparent">gdImageColorTransparent</A> \|
wolffd@0	5491 <A HREF="#gdImageCopy">gdImageCopy</A> \|
wolffd@0	5492 <A HREF="#gdImageCopyMerge">gdImageCopyMerge</A> \|
wolffd@0	5493 <A HREF="#gdImageCopyMergeGray">gdImageMergeGray</A> \|
wolffd@0	5494 <A HREF="#gdImageCopyResized">gdImageCopyResized</A> \|
wolffd@0	5495 <A HREF="#gdImageCopyResampled">gdImageCopyResampled</A> \|
wolffd@0	5496 <A HREF="#gdImageCopyRotated">gdImageCopyRotated</A> \|
wolffd@0	5497 <A HREF="#gdImageCreate">gdImageCreate</A> \|
wolffd@0	5498 <A HREF="#gdImageCreate">gdImageCreatePalette</A> \|
wolffd@0	5499 <A HREF="#gdImageCreate">gdImageCreateTrueColor</A> \|
wolffd@0	5500 <A HREF="#gdImageCreateFromGd">gdImageCreateFromGd</A> \|
wolffd@0	5501 <A HREF="#gdImageCreateFromGdCtx">gdImageCreateFromGdCtx</A> \|
wolffd@0	5502 <A HREF="#gdImageCreateFromGdPtr">gdImageCreateFromGdPtr</A> \|
wolffd@0	5503 <A HREF="#gdImageCreateFromGd2">gdImageCreateFromGd2</A> \|
wolffd@0	5504 <A HREF="#gdImageCreateFromGd2Ctx">gdImageCreateFromGd2Ctx</A> \|
wolffd@0	5505 <A HREF="#gdImageCreateFromGd2Ptr">gdImageCreateFromGd2Ptr</A> \|
wolffd@0	5506 <A HREF="#gdImageCreateFromGd2Part">gdImageCreateFromGd2Part</A> \|
wolffd@0	5507 <A HREF="#gdImageCreateFromGd2PartCtx">gdImageCreateFromGd2PartCtx</A> \|
wolffd@0	5508 <A HREF="#gdImageCreateFromGd2PartPtr">gdImageCreateFromGd2PartPtr</A> \|
wolffd@0	5509 <A HREF="#gdImageCreateFromJpeg">gdImageCreateFromJpeg</A> \|
wolffd@0	5510 <A HREF="#gdImageCreateFromJpegCtx">gdImageCreateFromJpegCtx</A> \|
wolffd@0	5511 <A HREF="#gdImageCreateFromJpegPtr">gdImageCreateFromJpegPtr</A> \|
wolffd@0	5512 <A HREF="#gdImageCreateFromPng">gdImageCreateFromPng</A> \|
wolffd@0	5513 <A HREF="#gdImageCreateFromPngCtx">gdImageCreateFromPngCtx</A> \|
wolffd@0	5514 <A HREF="#gdImageCreateFromPngPtr">gdImageCreateFromPngPtr</A> \|
wolffd@0	5515 <A HREF="#gdImageCreateFromPngSource">gdImageCreateFromPngSource</A> \|
wolffd@0	5516 <A HREF="#gdImageCreateFromWBMP">gdImageCreateFromWBMP</A> \|
wolffd@0	5517 <A HREF="#gdImageCreateFromWBMPCtx">gdImageCreateFromWBMPCtx</A> \|
wolffd@0	5518 <A HREF="#gdImageCreateFromWBMPPtr">gdImageCreateFromWBMPPtr</A> \|
wolffd@0	5519 <A HREF="#gdImageCreateFromXbm">gdImageCreateFromXbm</A> \|
wolffd@0	5520 <A HREF="#gdImageCreateFromXpm">gdImageCreateFromXpm</A> \|
wolffd@0	5521 <A HREF="#gdImageDashedLine">gdImageDashedLine</A> \|
wolffd@0	5522 <A HREF="#gdImageDestroy">gdImageDestroy</A> \|
wolffd@0	5523 <A HREF="#gdImageFill">gdImageFill</A> \|
wolffd@0	5524 <A HREF="#gdImageFilledArc">gdImageFilledArc</A> \|
wolffd@0	5525 <A HREF="#gdImageFilledEllipse">gdImageFilledEllipse</A> \|
wolffd@0	5526 <A HREF="#gdImageFillToBorder">gdImageFillToBorder</A> \|
wolffd@0	5527 <A HREF="#gdImageFilledRectangle">gdImageFilledRectangle</A> \|
wolffd@0	5528 <A HREF="#gdImageGd">gdImageGd</A> \|
wolffd@0	5529 <A HREF="#gdImageGd2">gdImageGd2</A> \|
wolffd@0	5530 <A HREF="#gdImageGetInterlaced">gdImageGetInterlaced</A> \|
wolffd@0	5531 <A HREF="#gdImageGetPixel">gdImageGetPixel</A> \|
wolffd@0	5532 <A HREF="#gdImageGetTransparent">gdImageGetTransparent</A> \|
wolffd@0	5533 <A HREF="#gdImageGifAnimAdd">gdImageGifAnimAdd</A> \|
wolffd@0	5534 <A HREF="#gdImageGifAnimAddCtx">gdImageGifAnimAddCtx</A> \|
wolffd@0	5535 <A HREF="#gdImageGifAnimAddPtr">gdImageGifAnimAddPtr</A> \|
wolffd@0	5536 <A HREF="#gdImageGifAnimBegin">gdImageGifAnimBegin</A> \|
wolffd@0	5537 <A HREF="#gdImageGifAnimBeginCtx">gdImageGifAnimBeginCtx</A> \|
wolffd@0	5538 <A HREF="#gdImageGifAnimBeginPtr">gdImageGifAnimBeginPtr</A> \|
wolffd@0	5539 <A HREF="#gdImageGifAnimEnd">gdImageGifAnimEnd</A> \|
wolffd@0	5540 <A HREF="#gdImageGifAnimEndCtx">gdImageGifAnimEndCtx</A> \|
wolffd@0	5541 <A HREF="#gdImageGifAnimEndPtr">gdImageGifAnimEndPtr</A> \|
wolffd@0	5542 <A HREF="#gdImageGreen">gdImageGreen</A> \|
wolffd@0	5543 <A HREF="#gdImageInterlace">gdImageInterlace</A> \|
wolffd@0	5544 <A HREF="#gdImageJpeg">gdImageJpeg</A> \|
wolffd@0	5545 <A HREF="#gdImageJpegCtx">gdImageJpegCtx</A> \|
wolffd@0	5546 <A HREF="#gdImageLine">gdImageLine</A> \|
wolffd@0	5547 <A HREF="#gdImageFilledPolygon">gdImageFilledPolygon</A> \|
wolffd@0	5548 <A HREF="#gdImageOpenPolygon">gdImageOpenPolygon</A> \|
wolffd@0	5549 <A HREF="#gdImagePaletteCopy">gdImagePaletteCopy</A> \|
wolffd@0	5550 <A HREF="#gdImagePng">gdImagePng</A> \|
wolffd@0	5551 <A HREF="#gdImagePngEx">gdImagePngEx</A> \|
wolffd@0	5552 <A HREF="#gdImagePngCtx">gdImagePngCtx</A> \|
wolffd@0	5553 <A HREF="#gdImagePngCtxEx">gdImagePngCtxEx</A> \|
wolffd@0	5554 <A HREF="#gdImagePngPtr">gdImagePngPtr</A> \|
wolffd@0	5555 <A HREF="#gdImagePngPtrEx">gdImagePngPtrEx</A> \|
wolffd@0	5556 <A HREF="#gdImagePngToSink">gdImagePngToSink</A> \|
wolffd@0	5557 <A HREF="#gdImagePolygon">gdImagePolygon</A> \|
wolffd@0	5558 <A HREF="#gdImagePtr">gdImagePtr</A> \|
wolffd@0	5559 <A HREF="#gdImageWBMP">gdImageWBMP</A> \|
wolffd@0	5560 <A HREF="#gdImageWBMPCtx">gdImageWBMPCtx</A> \|
wolffd@0	5561 <A HREF="#gdImageRectangle">gdImageRectangle</A> \|
wolffd@0	5562 <A HREF="#gdImageRed">gdImageRed</A> \|
wolffd@0	5563 <A HREF="#gdImageSaveAlpha">gdImageSaveAlpha</A> \|
wolffd@0	5564 <A HREF="#gdImageSetAntiAliased">gdImageSetAntiAliased</A> \|
wolffd@0	5565 <A HREF="#gdImageSetAntiAliasedDontBlend">gdImageSetAntiAliasedDontBlend</A> \|
wolffd@0	5566 <A HREF="#gdImageSetBrush">gdImageSetBrush</A> \|
wolffd@0	5567 <A HREF="#gdImageSetPixel">gdImageSetPixel</A> \|
wolffd@0	5568 <A HREF="#gdImageSetStyle">gdImageSetStyle</A> \|
wolffd@0	5569 <A HREF="#gdImageSetThickness">gdImageSetThickness</A> \|
wolffd@0	5570 <A HREF="#gdImageSetTile">gdImageSetTile</A> \|
wolffd@0	5571 <A HREF="#gdImageSharpen">gdImageSharpen</A> \|
wolffd@0	5572 <A HREF="#gdImageSquareToCircle">gdImageSquareToCircle</A> \|
wolffd@0	5573 <A HREF="#gdImageString">gdImageString</A> \|
wolffd@0	5574 <A HREF="#gdImageString16">gdImageString16</A> \|
wolffd@0	5575 <A HREF="#gdImageStringFT">gdImageStringFT</A> \|
wolffd@0	5576 <A HREF="#gdImageStringFTCircle">gdImageStringFTCircle</A> \|
wolffd@0	5577 <A HREF="#gdImageStringFTEx">gdImageStringFTEx</A> \|
wolffd@0	5578 <A HREF="#gdImageStringTTF">gdImageStringTTF</A> \|
wolffd@0	5579 <A HREF="#gdImageStringUp">gdImageStringUp</A> \|
wolffd@0	5580 <A HREF="#gdImageStringUp">gdImageStringUp16</A> \|
wolffd@0	5581 <A HREF="#gdImageToPalette">gdImageToPalette</A> \|
wolffd@0	5582 <A HREF="#gdImageWBMP">gdImageWBMP</A> \|
wolffd@0	5583 <A HREF="#gdMaxColors">gdMaxColors</A> \|
wolffd@0	5584 <A HREF="#gdPoint">gdPoint</A> \|
wolffd@0	5585 <A HREF="#gdStyled">gdStyled</A> \|
wolffd@0	5586 <A HREF="#gdStyledBrushed">gdStyledBrushed</A> \|
wolffd@0	5587 <A HREF="#gdTiled">gdTiled</A> \|
wolffd@0	5588 <A HREF="#gdTransparent">gdTransparent</A>
wolffd@0	5589 <P>
wolffd@0	5590 <em><A HREF="http://www.libgd.org/">
wolffd@0	5591 www.libgd.org</A></em>
wolffd@0	5592 </body>
wolffd@0	5593

Mercurial > hg > camir-aes2014

annotate toolboxes/graph_visualisation/share/graphviz/doc/html/gd.html @ 0:e9a9cd732c1e tip