gd 2.0.36

A graphics library for fast image creation

Follow this link to the latest version of this document.

UPGRADING UNIX USERS: READ THIS FIRST! Modern versions of gd install by default to /usr/local/lib and /usr/local/include. If you already have an older version of gd in /usr/lib and /usr/include, you may wish to use:

./configure --prefix=/usr

To ensure that your new installation overwrites the old.

GIF support has been restored in gd 2.0.28 and above. The well-known patents on LZW compression held by Unisys have expired in all countries. British Telecom and IBM may hold related patents but have never chosen to require royalties for GIF applications, to the best of my knowledge. I am not a lawyer and cannot give legal advice regarding this issue. PNG remains a superior format especially if lossless truecolor images are needed.

When building from soruce, gd 2.0.36 requires that the following libraries also be installed, in order to produce the related image formats. The win32 binary release (bgd) already contains the appropriate libraries. You may skip libraries associated with formats you do not use:

libpng (see the libpng home page), if you want PNG

zlib (see the info-zip home page), if you want PNG

jpeg-6b or later, if desired (see the Independent JPEG Group home page), if you want JPEG

If you want to use the TrueType font support, you must also install the FreeType 2.x library, including the header files. See the Freetype Home Page, or SourceForge. No, I cannot explain why that site is down on a particular day, and no, I can't send you a copy.

If you want to use the Xpm color bitmap loading support, you must also have the X Window System and the Xpm library installed (Xpm is often included in modern X distributions). Most of the time you won't need Xpm.

Please read the documentation and install the required libraries. Do not send email asking why png.h is not found. Do not send email asking why libgd.so is not found, either. See the requirements section for more information. Thank you!

Table of Contents

• Credits and license terms
• What's new in version "XYZ" of GD?
• What is gd?
• What if I want to use another programming language?
• What else do I need to use gd?
• How do I get gd?
• How do I build gd?
• gd basics: using gd in your program
• webpng: a useful example
• Function and type reference by category
• About the additional .gd image file format
• Please tell us you're using gd!
• How do I get support?
• How do I report issues, bugs or features request?
• Alphabetical quick index

Up to the LibGD Homepage

Credits and license terms

In order to resolve any possible confusion regarding the authorship of gd, the following copyright statement covers all of the authors who have required such a statement. If you are aware of any oversights in this copyright notice, please contact Pierre-A. Joye who will be pleased to correct them.

COPYRIGHT STATEMENT FOLLOWS THIS LINE

Portions copyright 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004 by Cold Spring Harbor Laboratory. Funded under Grant P41-RR02188 by the National Institutes of Health.

Portions copyright 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004 by Boutell.Com, Inc.

Portions relating to GD2 format copyright 1999, 2000, 2001, 2002, 2003, 2004 Philip Warner.

Portions relating to PNG copyright 1999, 2000, 2001, 2002, 2003, 2004 Greg Roelofs.

Portions relating to gdttf.c copyright 1999, 2000, 2001, 2002, 2003, 2004 John Ellson (ellson@graphviz.org).

Portions relating to gdft.c copyright 2001, 2002, 2003, 2004 John Ellson (ellson@graphviz.org).

Portions copyright 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Pierre-Alain Joye (pierre@libgd.org).

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 in part on the work of the Independent JPEG Group. See the file README-JPEG.TXT for more information.

Portions relating to GIF compression copyright 1989 by Jef Poskanzer and David Rowley, with modifications for thread safety by Thomas Boutell.

Portions relating to GIF decompression copyright 1990, 1991, 1993 by David Koblas, with modifications for thread safety by Thomas Boutell.

Portions relating to WBMP copyright 2000, 2001, 2002, 2003, 2004 Maurice Szmurlo and Johan Van den Brande.

Portions relating to GIF animations copyright 2004 Jaakko Hyvätti (jaakko.hyvatti@iki.fi)

Permission has been granted to copy, distribute and modify gd in any context without fee, including a commercial application, provided that this notice is present in user-accessible supporting documentation.

This does not affect your ownership of the derived work itself, and the intent is to assure proper credit for the authors of gd, not to interfere with your productive use of gd. If you have questions, ask. "Derived works" includes all programs that utilize the library. Credit must be given in user-accessible documentation.

This software is provided "AS IS." The copyright holders disclaim all warranties, either express or implied, including but not limited to implied warranties of merchantability and fitness for a particular purpose, with respect to this code and accompanying documentation.

Although their code does not appear in the current release, the authors also wish to thank Hutchison Avenue Software Corporation for their prior contributions.

END OF COPYRIGHT STATEMENT

What is gd?

gd is a graphics library. It allows your code to quickly draw images complete with lines, arcs, text, multiple colors, cut and paste from other images, and flood fills, and write out the result as a PNG or JPEG file. This is particularly useful in World Wide Web applications, where PNG and JPEG are two of the formats accepted for inline images by most browsers.

gd is not a paint program. If you are looking for a paint program, you are looking in the wrong place. If you are not a programmer, you are looking in the wrong place, unless you are installing a required library in order to run an application.

gd does not provide for every possible desirable graphics operation. It is not necessary or desirable for gd to become a kitchen-sink graphics package, but version 2.0 does include most frequently requested features, including both truecolor and palette images, resampling (smooth resizing of truecolor images) and so forth.

What if I want to use another programming language?

PHP

Perl

OCaml

Tcl

Pascal

REXX

Any Language

• fly, by Martin Gleeson

Please see the NEWS file, the releases announcements and the ChangeLog for the changes in the releases after 2.0.34.

What's new in version 2.0.34?

From 2.0.34 and later, please check the ISSUES and ChangeLog as well as the releases announcements.

What's new in version 2.0.33?

Version 2.0.33 restores compatibility with older releases of Freetype 2.x in addition to the latest release. Thanks to John Ellson and the graphviz project.

What's new in version 2.0.32?

Version 2.0.32 restores correct detection of Unicode character sets for freetype fonts, which repairs a bug that prevented umlauts from displaying properly. Thanks to John Ellson and the graphviz project. Also, version 2.0.32 builds all test programs smoothly in the absence of libpng.

What's new in version 2.0.31?

A minor type naming conflict prevented bgd.dll from compiling, and it was left out of the distribution as a result. This has been corrected.

What's new in version 2.0.30?

2.0.29 did not compile correctly when freetype was not available. This has been corrected. Thanks to Alessandro Ranellucci.

What's new in version 2.0.29?

• A 32-bit multiplication overflow vulnerability reported on the Bugtraq mailing list has been corrected, along with a number of similar issues. These bugs come into play only when attempting to deal with images with extremely large dimensions. The relevant functions now fail gracefully when such extreme parameters are specified. The code in question is also correct for systems with larger bit depths. Thanks to Phil Knirsch, Alan Cox and infamous41md. Since exploits are theoretically possible, upgrading is recommended.
• Support for the fontconfig library, when available. When fontconfig is available and gdFTUseFontConfig(1) has been invoked or the gdFTEX_FONTCONFIG flag has been set for a particular call, fontconfig patterns can be used to fetch the best available font. For instance, "arial:bold:italic" does the right thing (or as close as the available fonts permit). Also, standard PostScript font names can be mapped to an appropriate font by gdImageStringFTEx and relatives. When fontconfig is available gdlib-config --features will list the GD_FONTCONFIG feature. For more information about fontconfig, see the fontconfig pages.

  The actual resolved font filename can be returned in the gdFTStringExtra structure as the fontpath element if the gdFTEX_RETURNFONTPATHNAME flag is set. Also, a vector of character position advances can be retrieved if gdFTEX_XSHOW is set in the flags element. .afm files (font metrics) are now used to adjust size calculations when available. When fontconfig is not available, gd falls back to its usual behavior and requires a specific font file name. One can still fetch fonts by filename when gdFTUseFontConfig(1) is in effect, by setting the gdFTEX_FONTPATHNAME flag in the flag element of the gdFTStringExtra structure. Thanks to Dag Lem and John Ellson.

• Additional freetype fixes: fixed width fonts are now the right size, horizontal advance calculations now better match the PostScript equivalent, and various compiler warning fixes. Also, a fix to the encoding table selection in the was made, addressing a problem with latin1 font encodings. Thanks to Dag Lem and John Ellson.
• Improved tolerance when reading JPEG files containing some garbage as well as valid image data.
• Easier compilation on Windows: no errno.h in gd_gd2.c.
• Support for creating optimized GIF animations has been added by Jaakko Hyvätti. See gdImageGifAnimAdd, gdImageGifAnimAddCtx, gdImageGifAnimAddPtr, gdImageGifAnimBegin, gdImageGifAnimBeginCtx, gdImageGifAnimBeginPtr, gdImageGifAnimEnd, gdImageGifAnimEndCtx, and gdImageGifAnimEndPtr.
• gdImageOpenPolygon has been added to allow consecutive line segments to be drawn without connecting the end points to form a closed polygon. Thanks to Jaakko Hyvätti.
• Better alpha channel blending when the destination color contains an alpha channel. Also, quicker handling of the most common cases. Thanks to Frank Warmerdam.

What's new in version 2.0.28?

• GIF support has been restored. See gdImageGif, gdImageGifCtx, gdImageGifPtr, gdImageCreateFromGif, gdImageCreateFromGifCtx, and gdImageCreateFromGifPtr. These functions are now thread-safe, similar to the PNG and JPEG manipulation functions.
• The new gdImageCreatePaletteFromTrueColor function is identical to gdImageTrueColorToPalette, except that it returns a new image rather than permanently modifying the original.

What's new in version 2.0.27?

• In gd 2.0.26, there was potential for out of bounds fills, and therefore crashes, in the horizontalLine function used by gdImageFilledPolygon. Fixed by John Ellson.
• The order of the points returned in the bounding rectangle by gdImageStringFT was incorrect in version 2.0.26. This has been corrected in version 2.0.27. Thanks to Riccardo Cohen for pointing this out, and to John Ellson for verifying and fixing it.

What's new in version 2.0.26?

The following enhancements and fixes:

• Drastically faster, less memory-intensive antialiased drawing, thanks to Pierre-Alain Joye. This code was imported from the PHP "fork" of gd. The API for antialiased drawing has not changed, however the implementation has been completely replaced. Antialiased line drawing does not support widths other than 1, however this did not work properly with the other implementation of antialiasing either. Support has been included for the "non-blending color" option introduced by the previous implementation of antialiased drawing.
• gdlib-config, which has been installed by make install for some time now, has gained a --features option. This option produces a space-separated list of optional features with which the gd library was compiled. Typical usage looks like this:

  % gdlib-config --features
  GD_XPM GD_JPEG GD_FREETYPE GD_PNG GD_GIF
  

  Other configure scripts can conveniently define preprocessor symbols based on this list in order to conditionally compile code. For instance, if GD_PNG is not reported by --features, then gdImagePng is not included in the library.

  Thanks to Lars Hecking and Lincoln Stein for their advice on implementing this feature. Any blame for the actual implementation is entirely due to me (TBB).

• Fixes to the behavior of the bounding rectangle returned by gdImageStringFT and relatives when the string is rotated. See fontwheeltest.c. Thanks to John Ellson.
• Previously, gdImageStringFT and friends accepted either a full path to a font file, or the name of a font with no extension, in which case the GDFONTPATH environment variable and then the compiled-in DEFAULT_FONTPATH was searched. In addition, a font filename with an extension but no full path can now be automatically searched for in the same fashion. Thanks to John Ellson.
• Fixes to freetype antialiased text against a transparent background. See testtr.c. Thanks to John Ellson.
• Support for named entities like & and hex-coded entities such as 水 in text strings passed to gdImageStringFT and relatives, adding to the previous support for decimal-coded entities like Å. These were extracted from entities.html (from the W3C) via the script entities.tcl, which is included for the curious and those with other entities they need support for. Thanks to John Ellson.
• Optimization: gdImageSetPixel no longer calls gdImageAlphaBlend when either the source or the destination pixel is 100% transparent. Thanks to John Ellson.
• Optimization: gdImageLine is potentially faster now in the most common cases. Thanks to John Ellson.
• Documentation of the entities feature of gdImageStringFT.
• autoconf/configure fixes. Thanks to many who pointed out an oversight in handling libpng flags.

What's new in version 2.0.25?

Owing to an oversight while making changes to better accommodate the use of gd as a DLL, the extern qualifier was dropped from the declarations of font pointers in 2.0.24. This has been corrected. Thanks to Richard ("OpenMacNews").

What's new in version 2.0.24?

Windows DLL now uses __stdcall calling convention. Existing applications will require a recompile, using the new version of gd.h, in order to use this version of the DLL. However, Visual BASIC and other non-C programmers will now be able to use the DLL, which is an enormous benefit and justifies the one-time inconvenience to existing DLL users.

The elaborate #ifdef test for older versions of Freetype without FT_ENCODING_MS_SYMBOL was needed in a second place also. Thanks to David R. Morrison.

An off-by-one error in gdImageToPalette caused transparency to be applied to the wrong pixels. Thanks to "Super Pikeman."

What's new in version 2.0.23?

Output dpi specification option added to the gdFTStringExtra structure, thanks to Mark Shackelford. See gdImageStringFTEx.

What's new in version 2.0.22?

• Win32 DLL users: working with pointers exported by DLLs is difficult and causes unexpected results. gd 2.0.22 exports new functions for retrieving the basic gd fonts: gdFontGetTiny(), gdFontGetSmall(), gdFontGetMediumBold(), gdFontGetLarge(), and gdFontGetHuge(). You may safely assign the return values from these functions to a local gdFontPtr. Direct use of gdFontLarge, etc. is strongly deprecated for users of bgd.dll; use these new functions instead.
• Basic support for loading CMYK-colorspace JPEG images. They are of course converted to RGB which is a lossy process, however the results do look quite good and are certainly fine for thumbnails and web previews of DTP work.
• "make" no longer fails on circletexttest if PNG support is missing.
• Small performance improvements to gdImageCopyResampled; larger improvements are forthcoming.

What's new in version 2.0.21?

• Version 2.0.21 adds a gdImageCreateFrom*Ptr family of functions which make it convenient to load an image in any GD-supported format directly from memory.
• The new gdNewDynamicCtxEx function was added to support the easy implementation of the above functions and to correct a design problem which made life unpleasant for those passing in memory not originally allocated by gd to the gdNewDynamicCtx function by provoding a way to specify that gd should never free or reallocate a particular block of memory. The gdNewDynamicCtx function and its relatives, although still exported for ABI compatibility, are now deprecated except for internal use, in favor of gdImageCreateFromPngPtr and its relatives.
• Version 2.0.21 includes a new patch from Ethan A. Merritt to correct a bug in the conditional compilation of support for symbol fonts in gdft.c. Symbol fonts should now work correctly. Thanks to Mr. Merritt.
• Version 2.0.20 restores the gdFreeFontCache function, an undocumented function added in an earlier release which now simply calls gdFontCacheShutdown for backwards compatibility. This repairs build problems when compiling PHP against the latest gd.
• Documentation improvements.

What's new in version 2.0.20?

• Version 2.0.20 restores the gdFreeFontCache function, an undocumented function added in an earlier release which now simply calls gdFontCacheShutdown for backwards compatibility. This repairs build problems when compiling PHP against the latest gd.

What's new in version 2.0.19?

• Version 2.0.19 restored extern declarations for the gd font pointers inadvertently removed in 2.0.18.

What's new in version 2.0.18?

• A Win32 binary distribution of "bgd.dll," built with mingw32 and tested with win32 versions of the demo programs as console applications, is now available.
• Semicolon rather than space used as the default separator of alternative font file paths in gdImageStringFT, for better compatibility with Windows and other environments where spaces are common in paths.
• The circletexttest demo no longer fails to compile when JPEG support happens to be absent.

What's new in version 2.0.17?

Minor compilation and packaging problems with 2.0.16 were corrected. If 2.0.16 compiled without errors for you, then you don't need to upgrade to 2.0.17.

What's new in version 2.0.16?

• Thread safety for freetype text output. Background: all gd functions were already thread safe, as long as only one thread manipulates each image -- except for gdImageStringFT and gdImageStringFTEx. This is because of a shared freetype font cache. Sharing the cache between images is worthwhile, so "configure" now detects pthreads and uses it to wrap freetype text output in a critical section if available. There is also critical section support under WIN32. Those who wish to be strictly thread-safe should call the new function gdFontCacheSetup before allowing any thread to use freetype text calls. Otherwise this function is automatically invoked on the first use of freetype, with a very small but real chance of a race condition.
• gdImageSquareToCircle performs a "polar coordinate transform," returning a new image in which the X axis of the original has been remapped to theta (angle) and the Y axis of the original has been remapped to rho (distance from center).
• gdImageStringFTCircle wraps text in a circle around a specified center point. This function takes advantage of gdImageSquareToCircle. The result is very smooth, although it takes some time to compute. Thanks to Steve Bassi for sponsoring this work.
• gdImageSharpen, contributed by Paul Troughton. Thank you.
• Christophe Thomas corrected gdft.c to include freetype header files in the way that is now mandatory in freetype 2.1.6 and above.
• Gustavo Scotti fixed a memory leak in gdft.c.
• Clipping rectangle respected in freetype text output. Thanks to Matt McNabb.
• Paul den Dulk found a degenerate case that crashes gdImageToPalette. Fixed.
• Optimization by Ilia Chipitsine to avoid wasting time with offscreen scanlines during polygon rasterization.
• Optimized PNG saving by Phong Tran. Speeds up saves a little bit.
• Bug in gdImageCopyResized fixed by Mao Morimoto.

What's new in version 2.0.15?

• gd.c in 2.0.14 contained an instance of declaring variables after the first line of executable code appears. This is of course not allowed by ANSI C, although many compilers accept it. My apologies. Thanks to Jeff Vendetti for reporting this quickly.

What's new in version 2.0.14?

• 2.0.13 was available for mere minutes due to a typo in the new bounds-checking code for antialiased line drawing. Fixed.
• Not all platforms -- notably msys/mingw -- have an ssize_t type. We now call an int an int in gd_jpeg.c, with good results. (Note: ssize_t is signed, unlike size_t, and it needs to be here.)

What's new in version 2.0.13?

• The main() function of one of the test programs was accidentally included in the gd shared library, causing problems on some platforms. This has been corrected. Thanks to many people who pointed this out.
• The antialiased drawing functions now have proper bounds checking. Thanks to Arne Jorgensen.
• A void function returned a value in gd_png.c, causing warnings and, on some platforms, compilation errors but no reported runtime problems. Thanks to Kevin Smith, among others.
• Autohinting was being forced ON for freetype text output. This is apparently meant only for testing freetype and does not look as good as the default behavior (FT_LOAD_DEFAULT). Thanks to Bob Ostermann.
• penf.x is properly reset when newlines are encountered in freetype text output. Thanks to Christopher J. Grayce.

What's new in version 2.0.12?

• Small but numerous code cleanups by Dr. Martin Zinser.
• gdImageSetClip and gdImageGetClip have been added. All drawing routines now stay within the specified clipping rectangle. Note that the gdImageBoundsSafe function now returns true only if the specified location is within the clipping rectangle. Of course, the default clipping area is the entire image. The behavior of existing gd applications does not change.
• Support for fast drawing of antialiased lines and polygons, by Bright Fulton and Frank Faubert. To learn more about this feature, read about the gdImageSetAntiAliased function, which is used to set the foreground color for antialiasing, as well as the gdAntiAliased constant, which is passed to line- and polygon-drawing functions in place of a color. This code does not currently support an alpha channel component in the specified foreground color, or in the existing background image, but does perform alpha blending against an opaque background. Also see the gdImageSetAntiAliasedDontBlend function, which allows the specification of a special background color that should never be blended with the foreground.
• Fixes to color mapping in gdImageCopyMergeGray. Thanks to Philip Warner.
• gdImageStringFTEx now supports explicit specification of the desired character mapping. This is useful when a font offers more than one of Unicode, Shift_JIS, and Big5.
• The PNG compression level can now be specified when writing PNG images. See the new gdImagePngEx, gdImagePngEx, gdImagePngCtxEx, and gdImagePngPtrEx functions.
• The annotate utility builds without error in the absence of freetype, although of course it is not useful without freetype.
• Thorben Kundinger fixed a bug relating to the use of palette-based images as brushes when drawing on truecolor images.
• Michael Schwartz corrected a problem with his code for drawing thick lines.
• Prior to 2.0.12, any alpha channel component in the destination image was ignored when drawing with alpha blending in effect (see gdImageAlphaBlending). 2.0.12 correctly preserves an appropriate proportion of the alpha component of the destination, just as it preserves an appropriate proportion of the red, green and blue components, depending on the opacity of the foreground. Thanks to Frank Warmerdam for pointing out the issue.
• Memory leaks on failed attempts to load fonts in gdImageStringFTEx were corrected. Thanks to Frank Faubert.
• The impact of kerning is now correctly included in the calculation of the bounding box returned by the freetype text routines. This issue was pointed out by several individuals.
• Color problems with the gd2 file format routines were fixed by Steven Brown. These problems were due to the incorrect use of a signed integer.
• Version 2.0.12 supports the gd file format correctly for truecolor images. Truecolor gd files created with earlier releases in the 2.0 series must be written again. The gd file format is used to quickly load an entire uncompressed image, typically an existing background to which additional material will be added; it is not a general purpose file format. More advanced capabilities are also available via the gd2 format. Thanks to Andreas Pfaller for reporting the problem.
• Signed vs. unsigned problem caused misbehavior when attempting to load a bad JPEG image. Thanks to Geert Jansen.
• Existing truecolor PNG images with simple single-color transparency are now loaded properly, thanks to Slaven Rezic.
• The gdImageTrueColorToPalette function no longer attempts to preserve an alpha channel in the original. My attempt to do so resulted in significantly inferior output even if no alpha channel was present in the original. Thanks to Barend Gehrels for submitting a new adaptation of Tom Lane's jquant2.c which does a very high-quality job of palette conversion. Thanks also to Steven Brown, who submitted patches allowing a single 100% transparent color in the original truecolor image to be preserved. In practice, more complex alpha channels in palettes are ill-supported and difficult to allocate skillfully.

What's new in version 2.0.11?

• Support for the "gd2" file format, which allows fast loading of all or only part of an existing image, has been properly debugged for use with truecolor images. (Palette images already worked properly, except for a bug when loading from a regular file with gdImageCreateFromGd2Part, which has also been fixed.) .gd2 files can be either compressed or uncompressed, and they allow useful tricks such as fast loading of a 500x500 pixel region of a 6000x3000 pixel image, without uncompressing all of the image. .gd2 is NOT a general purpose file format and should only be used where quick loading of a background image or subset of a larger image is required. For more information, see gdImageGd2, gdImageCreateFromGd2, and gdImageCreateFromGd2Part.
• The gd2topng utility has been extended to support extraction of only part of an image from a .gd2 file. This is both a demonstration and a practical tool.
• Additional configure improvements by Lars Hecking.

What's new in version 2.0.10?

• gdImageLine now clips to the edges of the image before drawing lines, which greatly improves performance when many lines extend outside or are entirely outside the actual image. Thanks to Nick Atty for this code.
• gdImageBoundsSafe is replaced with a macro when called internally; this improves the performance of gdImageSetPixel and gdImageGetPixel a little bit, and therefore everything else as well. Thanks to Nicky Atty for the idea.
• Transparent indexes are handled properly with non-truecolor source images in gdImageCopy. Thanks to Frank Warmerdam.
• floor() replaced with a cast to long in gdImageCopyResampled, for a roughly 35% performance boost. Thanks to John Buckman.
• gdft.c builds correctly on WIN32 without patches.
• Much faster gdImageCreateFromJpeg routines, thanks to Christian Aberger for more efficient pointer arithmetic.
• gdtestft correctly builds without PNG tests if PNG support is not present. Thanks to Gabriele Verzeletti.

What's new in version 2.0.9?

• Version 2.0.9 contains a fix to gdImageCopyResized which allows correct results when copying a palette-based image with a single transparent index into a truecolor image. Thanks to Thorben Kundinger.
• More configure fixes from Lars Hecking. Thanks, Lars.

What's new in version 2.0.8?

• Version 2.0.8 contains additional fixes to the 'configure' script, allowing a clean out-of-the-box build on more systems.
• Version 2.0.8 adds the new gdImageCopyRotated function, which can rotate any rectangular image region by an arbitrary number of degrees.

What's new in version 2.0.7?

Version 2.0.7 corrects a problem which caused 'configure' to complain that the directory NONE was not found, in various places, causing the configuration process to stop. There are no code changes.

What's new in version 2.0.6?

• Fixed a compilation problem with gdft.c. A declaration appeared after executable code, and gcc let it slide by, so it made it out the door. My apologies!
• As penance, I have seen to it that the entire library now compiles cleanly with the -Wall, -ansi and -pedantic options enabled.

What's new in version 2.0.5?

• libgd 2.0.5 INSTALLS IN /usr/local/lib BY DEFAULT. IF YOU WANT IT TO INSTALL IN /usr/lib, YOU MUST SPECIFY THIS at configure time using this syntax:

  ./configure --prefix=/usr

• gd now uses GNU autoconf. This means that the provided configure script should be compatible with all standard GNU configure options and will figure out the correct settings for a much wider range of operating systems. Many, many thanks to Lars Hecking for taking care of this.
• The gdImageStringFTEx function is now included, thanks to Wez Furlong. My apologies to Wez for the unreasonable amount of time this patch has sat in my queue.
• Additional fixes from Wez Furlong.
• Arithmetic cleanup by Doug Claar.
• Corrections to loading and saving of alpha channel information in PNG files, by Andrew Hull.
• gdImageTrueColorToPalette does not contain unneeded test code.
• gdImageCopyResized works properly again when copying from a non-truecolor source.

What's new in version 2.0.4?

• Various test programs now compile in the absence of PNG support
• gdIOCtx correctly calls gdFree rather than free
• Various cleanups to pass -Wall without warnings
• Support for Adobe-style Type 1 fonts (.pfa and .pfb files) via freetype
• gdImageColorResolve and gdImageColorResolveAlpha will not attempt to resolve a color request to the transparent color index (for palette-based images)
• Improved font search path support
• Antialiased freetype text on palette images works properly when more than one image is created in a single program lifetime with different color indexes
• Better threshold for two-color "mono" images
• Memory leak fixes
• Text rotation fix
• More extensive default font path
• fontwheeltest and fontsizetest test programs for freetype

• configure now correctly detects and provides support for the Xpm library and its dependencies (Len Makin)

What's new in version 2.0.3?

• The configure script has been extensively modified to work properly in tests with both Solaris and Linux. Other platforms should also work based on feedback received and integrated to date.
• The --prefix option to configure works properly.
• The annotate utility has been added. This is a very handy tool for adding freetype text to existing JPEGs. After make install, type annotate -h for more information. Thanks to Joel Dubiner.

What's new in version 2.0.2?

• A "configure" script has been added. After wrestling with GNU autoconf for a while, I got tired of trying to make it detect libraries but accept their absence gracefully, and so on. Instead, I wrote a short Perl script which does the job and builds a reasonable Makefile. Those who find it doesn't detect their system's needs properly are welcome to contribute patches or the necessary commands.
• Antialiased freetype text output now works properly in both truecolor and non-truecolor contexts! Hurrah! On a truecolor image it is possible, for instance, to draw antialiased text on an arbitrarily complex background with 50% alpha blending (transparency), and get the expected pretty results. Thanks to Joel Dubiner for his support of this work.
• By default, alpha blending is now done within the library. Also, by default, alpha channel is not saved with PNG images. This means that programmers who try loading a JPEG, scribbling some pretty antialiased text on it, and saving the JPEG again will now get the results they expected. It also means that, by default, users will not run afoul of the fact that many web browsers don't properly support full PNG alpha channel.
• Various submitted bug fixes have been incorporated.
• Various other submitted changes have not been incorporated. Sorry. The interval between 2.0.1 and 2.0.2 was simply too long, and changes accumulated which were not mutually compatible. I'll do better in the future, especially with bug fixes.

What's new in version 2.0.1?

• Workaround for a bug in gcc, apparently found in gcc 2.7.2 and up. I reproduced and fixed it while using gcc 2.9.5.2. The bug occurred only when the -g option was in use. This problem caused gcc to spew internal error messages unrelated to the correctness of the code in gd_gd2.c. Howard Jones was first to report it.
• gdImageFilledEllipse documented and altered; no longer requires a superfluous style argument. Thanks to Francis James Franklin.
• The Makefile now offers the correct syntax for optionally creating a static library. Thanks to Jean-Lous Regez, among others.
• A nested comment, an attempt to return the value of a void function, and a potentially significant error in gdImageCopyResampled were fixed thanks to Joseph Shirley.
• A bug preventing proper truecolor text rendering was fixed, thanks to Jason Gallagher.
• gdImageStringFT (FreeType) should now work better against a transparent or semitransparent background, and should act in a manner consistent with the most recent gdImageAlphaBlending setting. Antialiasing is now done via the alpha channel mechanism if the image is a truecolor image.
• Bugs in the output of gdImageArc and gdImageFilledArc were reported by Bruce Verderaime. A simple and correct but inefficient implementation has been substituted until fixes are contributed for the faster code, which is in gd_arc_f_buggy.c along with the test program that reproduces the bug(s).
• gdImageFilledArc now offers additional style options, which can be combined to produce various effects.
• Masahito Yamaga (ma@yama-ga.com) sent a patch to improve support for Japanese output via gdImageStringFT. He also added a new readme.jpn file.
• Zillions of documentation fixes.

What's new in version 2.0?

• Support for truecolor images! Version 2.0 can load truecolor PNGs with no loss of color information, and almost no loss of alpha channel information. Version 2.0 can also load truecolor JPEGs with as little loss as possible; however, bear in mind that JPEG is a lossy format, so repeated load/save cycles always reduce image quality. This is not a bug. To create a truecolor image from scratch, call the new gdImageCreateTrueColor function. The gdImageCreate function is still available to create palette images, and may also be referred to as gdImageCreatePalette.
• Support for alpha channels! In addition to 24 bits of color information for each pixel (eight bits of red, green, and blue respectively), version 2.0 supports 7 bits of "alpha channel" information. This is used to determine exactly how transparent the pixel should be. There is also support for a full 7 bits of transparency for each individual palette index in a palette-based image. Please note that, as of this writing, only Macintosh Internet Explorer 5.x and Mozilla/Netscape 6.x display partial transparency properly.
• The new gdImageAlphaBlending function allows for two different modes of drawing. In blending mode, the alpha channel component of the color supplied to all drawing functions, such as gdImageSetPixel, determines how much of the underlying color should be allowed to shine through. The resulting image is not transparent. In non-blending mode, drawing color is copied literally with the alpha channel information, resulting in a transparent image. Blending mode is not available when drawing on palette images.
• The gdImageCopyResampled function provides "smooth" copying from a large image to a smaller one, using a weighted average of the pixels of the source area rather than selecting one representative pixel. This function is identical to gdImageCopyResized when the destination image is a palette image.
• The gdImageTrueColorToPalette function converts a truecolor image to a palette image. The code for this function was originally drawn from the Independent JPEG Group library code, which is excellent. The code has been modified to preserve as much alpha channel information as possible in the resulting palette, in addition to preserving colors as well as possible. This does not work as well as might be hoped. It is usually best to simply produce a truecolor output image instead, which guarantees the highest output quality.
• A very high degree of backwards compatibility with existing gd 1.x code has been maintained, at both the source code and binary level. Code which directly accesses the pixels array will fail only if it encounters an existing truecolor image, which may happen if the code attempts to open and modify an existing JPEG or truecolor PNG. Such code should be modified to check the trueColor flag of the gdImage structure, and refer to the tpixels array instead when it is set.
• gd is now compiled and installed as a shared library. However, gd still does not use autoconf, because I (TBB) have very limited patience with autoconf. These days, most Unix systems provide a fairly POSIX-standard environment, and the provided Makefile is likely to work well if users read it and follow the instructions at the top.
• Support for line thickness was added by Michael Schwartz. My apologies to him for sitting on his patches for so long. See the new gdImageSetThickness function, which affects all standard gd functions that draw lines and curves. In addition, Michael added a convenient gdImageEllipse function.
• The new gdImageFilledArc function provides a straightforward way to draw filled arcs. Also, gdImageFilledEllipse is a convenient way to fill an ellipse without specifying starting and ending angles. Thanks go out to F J Franklin.
• To put an end to the confusion, TrueType 1.x support has been removed in favor of TrueType 2.x support. The old gdImageStringTTF function simply invokes gdImageStringFT.
• The specialized .gd and .gd2 file formats have been upgraded to support truecolor. New images written by the versions of these functions found in 2.0 will be rejected, with varying degrees of grace, by older versions of gd. THIS AFFECTS THE .GD and .GD2 FORMATS ONLY. IF YOU ARE CONFUSED BY THIS PARAGRAPH, IT PROBABLY DOESN'T APPLY TO ANYTHING YOU WILL EVER ENCOUNTER. Since these file formats are absolutely, positively *not* designed for distributing images, just for preprocessing them, this should not be a big problem. gd 2.0 should read old .gd and .gd2 files correctly.

What's new in version 1.8.4?

• Add support for FreeType2 (John Ellson ellson@graphviz.org)
• Add support for finding in fonts in a builtin DEFAULT_FONTPATH, or in a path from the GDFONTPATH environment variable.
• remove some unused symbols to reduce compiler warnings
• bugfix in size comparisons in gdImageCompare
• REXX now mentioned
• All memory allocation functions are now wrapped within the library; gdFree is exported and recommended for freeing memory returned by the gdImage(Something)Ptr family of functions.

What's new in version 1.8.3?

• WBMP output memory leak fixed
• #include <gd.h> corrected to #include "gd.h" in gd_wbmp.c
• Documented the fact that the source and output images shouldn't match in the WBMP test except for black and white source images

What's new in version 1.8.2?

• WBMP support debugged and improved by Johann Van den Brande
• WBMP tests added to gdtest.c by Thomas Boutell
• Use of platform-dependent 'install' command removed by Thomas Boutell
• Comments added to Makefile warning users to juggle the order of the libraries if the linker complains; is there any portable way to do this automatically, short of using autoconf?
• Documentation of gdImageCreateFromXpm corrected
• Updated links to fast-moving, always dodging libpng and zlib web sites

What's new in version 1.8.1?

• Optional components no longer built by default (following the documentation)
• JPEG code no longer requires inappropriate header files
• Win32 patches from Joe Gregorio
• 16-bit font support for bdftogd, from Honza Pazdziora

What's new in version 1.8?

• Support for JPEG output, courtesy of Doug Becker
• A link to Michael Bradbery's Pascal wrapper
• Support for WBMP output, courtesy of Maurice Szmurlo
• gdImageColorClosestHWB function based on hue, whiteness, blackness, superior to the regular gdImageColorClosest function, courtesy of Philip Warner
• License clarification: yes, you can modify gd

Additional JPEG Information

What's new in version 1.7.3?

What's new in version 1.7.2?

Documentation fixes. Thanks to Dohn Arms.

Makefile fixes to permit linking with all libraries required on platforms with order- dependent linkers.

What's new in version 1.7.1?

What's new in version 1.7?

• Japanese language support for the TrueType functions. Thanks to Masahito Yamaga.
• autoconf and configure have been removed, in favor of a carefully designed Makefile which produces and properly installs the library and the binaries. System-dependent variables are at the top of the Makefile for easy modification. I'm sorry, folks, but autoconf generated many, many confused email messages from people who didn't have things where autoconf expected to find them. I am not an autoconf/automake wizard, and gd is a simple, very compact library which does not need to be a shared library. I did make many improvements over the old gd 1.3 Makefile, which were directly inspired by the autoconf version found in the 1.6 series (thanks to John Ellson).
• Completely ANSI C compliant, according to the -pedantic-errors flag of gcc. Several pieces of not-quite-ANSI-C code were causing problems for those with non-gcc compilers.
• gdttf.c patched to allow the use of Windows symbol fonts, when present (thanks to Joseph Peppin).
• extern "C" wrappers added to gd.h and the font header files for the convenience of C++ programmers. bdftogd was also modified to automatically insert these wrappers into future font header files. Thanks to John Lindal.
• Compiles correctly on platforms that don't define SEEK_SET. Thanks to Robert Bonomi.
• Loads Xpm images via the gdImageCreateFromXpm function, if the Xpm library is available. Thanks to Caolan McNamara.

What's new in version 1.6.3?

What's new in version 1.6.2?

• gdImageStringTTF - scalable, rotatable, anti-aliased, TrueType strings using the FreeType library, but only if libttf is found by configure. We do not provide TrueType fonts. Obtaining them is entirely up to you.
• gdImageColorResolve - an efficient alternative for the common code fragment:

  
        if ((color=gdImageColorExact(im,R,G,B)) < 0)
            if ((color=gdImageColorAllocate(im,R,G,B)) < 0)
                color=gdImageColorClosest(im,R,G,B);
  

Also in this release the build process has been converted to GNU autoconf/automake/libtool conventions so that both (or either) static and shared libraries can be built.

What's new in version 1.6.1?

Unlike gd 1.6, users should have no trouble linking with gd 1.6.1 if they follow the instructions and install all of the pieces. However, If you get undefined symbol errors, be sure to check for older versions of libpng in your library directories!

What's new in version 1.6?

Support for 8-bit palette PNG images has been added. Support for GIF has been removed. This step was taken to completely avoid the legal controversy regarding the LZW compression algorithm used in GIF. Unisys holds a patent which is relevant to LZW compression. PNG is a superior image format in any case. Now that PNG is supported by both Microsoft Internet Explorer and Netscape (in their recent releases), we highly recommend that GD users upgrade in order to get well-compressed images in a format which is legally unemcumbered.

What's new in version 1.5?

New GD2 format

An improvement over the GD format, the GD2 format uses the zlib compression library to compress the image in chunks. This results in file sizes comparable to GIFs, with the ability to access parts of large images without having to read the entire image into memory.

This format also supports version numbers and rudimentary validity checks, so it should be more 'supportable' than the previous GD format.

Re-arranged source files

gd.c has been broken into constituant parts: io, gif, gd, gd2 and graphics functions are now in separate files.

Extended I/O capabilities.

The source/sink feature has been extended to support GD2 file formats (which require seek/tell functions; seek must return 1 for success, 0 for failure), and to allow more general non-file I/O.

Better support for Lincoln Stein's Perl Module

The new gdImage*Ptr function returns the chosen format stored in a block of memory. This can be directly used by the GD perl module.

Added functions

gdImageCreateFromGd2Part - allows retrieval of part of an image (good for huge images, like maps),
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.
gdImageGd2, gdImageCreateFromGd2 - Support for new format
gdImageCopyMerge - Merges two images (useful to highlight part of an image)
gdImageCopyMergeGray - Similar to gdImageCopyMerge, but tries to preserve source image hue.
gdImagePngPtr, gdImageJpegPtr, gdImageWBMPPtr, gdImageGdPtr, gdImageGd2Ptr - return memory blocks for each type of image.
gdImageCreateFromPngCtx, gdImageCreateFromGdCtx, gdImageCreateFromGd2Ctx, gdImageCreateFromGd2PartCtx - Support for new I/O context.

What's new in version 1.4?

Fixed polygon fill routine (again)

Thanks to Kirsten Schulz, version 1.4 is able to fill numerous types of polygons that caused problems with previous releases, including version 1.3.

Support for alternate data sources

Programmers who wish to load a GIF from something other than a stdio FILE * stream can use the new gdImageCreateFromPngSource function.

Support for alternate data destinations

Programmers who wish to write a GIF to something other than a stdio FILE * stream can use the new gdImagePngToSink function.

More tolerant when reading GIFs

Version 1.4 does not crash when reading certain animated GIFs, although it still only reads the first frame. Version 1.4 also has overflow testing code to prevent crashes when reading damaged GIFs.

What's new in version 1.3?

Non-LZW-based GIF compression code

Version 1.3 contained GIF compression code that uses simple Run Length Encoding instead of LZW compression, while still retaining compatibility with normal LZW-based GIF decoders (your browser will still like your GIFs). LZW compression is patented by Unisys. We are currently reevaluating the approach taken by gd 1.3. The current release of gd does not support this approach. We recommend that you use the current release, and generate PNG images. Thanks to Hutchison Avenue Software Corporation for contributing the RLE GIF code.

8-bit fonts, and 8-bit font support

This improves support for European languages. Thanks are due to Honza Pazdziora <adelton@informatics.muni.cz> and also to Jan Pazdziora <adelton@fi.muni.cz>. Also see the provided bdftogd Perl script if you wish to convert fixed-width X11 fonts to gd fonts.

16-bit font support (no fonts provided)

Although no such fonts are provided in the distribution, fonts containing more than 256 characters should work if the gdImageString16 and gdImageStringUp16 routines are used.

Improvements to the "webpng" example/utility

The "webpng" utility is now a slightly more useful application. Thanks to Brian Dowling for this code.

Corrections to the color resolution field of GIF output

Thanks to Bruno Aureli.

Fixed polygon fills

A one-line patch for the infamous polygon fill bug, courtesy of Jim Mason. I believe this fix is sufficient. However, if you find a situation where polygon fills still fail to behave properly, please send code that demonstrates the problem, and a fix if you have one. Verifying the fix is important.

Row-major, not column-major

Internally, gd now represents the array of pixels as an array of rows of pixels, rather than an array of columns of pixels. This improves the performance of compression and decompression routines slightly, because horizontally adjacent pixels are now next to each other in memory. This should not affect properly written gd applications, but applications that directly manipulate the pixels array will require changes.

What else do I need to use gd?

To use gd, you will need an ANSI C compiler. All popular Windows 95 and NT C compilers are ANSI C compliant. Any full-ANSI-standard C compiler should be adequate. The cc compiler released with SunOS 4.1.3 is not an ANSI C compiler. Most Unix users who do not already have gcc should get it. gcc is free, ANSI compliant and a de facto industry standard. Ask your ISP why it is missing.

As of version 1.6, you also need the zlib compression library, and the libpng library. As of version 1.6.2, you can draw text using antialiased TrueType fonts if you also have the libttf library installed, but this is not mandatory. zlib is available for a variety of platforms from the zlib web site. libpng is available for a variety of platforms from the PNG web site.

You will also want a PNG viewer, if you do not already have one for your system, since you will need a good way to check the results of your work. Netscape 4.04 and higher, and Microsoft Internet Explorer 4.0 or higher, both support PNG. Not every PNG-compatible viewer supports alpha channel transparency, which is why gd 2.0.2 and above do alpha blending in the library by default; it is possible to turn on the saving of alpha channel information to the file instead.

How do I get gd?

Binaries (DLL for Windows programmers):

• .ZIP File of DLL, Headers, Et Cetera

Source Code:

• Gzipped Tar File (Unix)
• .ZIP File of SOURCE CODE (Windows)

How do I build gd?

Win32 DLL users: if you are using MSVC, use the provided batch file makemsvcimport.bat to make a bgd.lib import library corresponding to the provided bgd.dll. Copy bgd.dll to your application directory, or to your Windows sytem directory. In the settings of your MSVC project, you MUST choose the "multithreaded DLL" library option under "code generation." mingw32 and cygwin users can simply link with the provided libbgd.a stub library in order to use the DLL.

In order to build gd, you must first unpack the archive you have downloaded. If you are not familiar with tar and gunzip (Unix) or ZIP (Windows), please consult with an experienced user of your system. Sorry, we cannot answer questions about basic Internet skills.

Unpacking the archive will produce a directory called "gd-2.0.33".

For Unix

./configure

NOTE: BY DEFAULT, THE LIBRARY IS INSTALLED IN /usr/local/lib and the include files are installed in /usr/local/include. IF YOU ARE UPGRADING, you may wish to use:

./configure --prefix=/usr

Rather than just ./configure, before typing make and make install.

If all goes well, this will create a Makefile. If all does not go well -- for instance, if neither the the JPEG nor the PNG and ZLIB libraries are found -- you will need to install those libraries, then come back and run configure again.

If necessary, make changes to the resulting Makefile. Then, type "make". If there are no errors, follow this with "make install". Because gd 2.0 and above installs as a shared library, it is necessary to install the library properly before running gd-based programs.

If you get errors, type ./configure --help for more information about the available options. In the unlikely event that the GNU autoconf-produced configure script does not work well for you, you may wish to try configure.pl, a simple Perl script with similar but less complete capabilities. If all else fails, try renaming makefile.sample to Makefile. However, ./configure is almost always your best bet.

For Windows

Use the DLL version! See the paragraph at the beginning of this sectino. If you really want to compile it yourself for some strange reason, read on.

Create a project using your favorite programming environment. Copy all of the gd files to the project directory. Add gd.c to your project. Add other source files as appropriate. Learning the basic skills of creating projects with your chosen C environment is up to you. Alternatively, use the free mingw32 or cygwin tools, which may prove to be compatible with the provided configure script.

If you wish to test the library, type "make test" AFTER you have successfully executed "make install". This will build several test programs, including "gddemo". (Not all of these programs are expected to print completely successful messages, depending on the nature of the image formats with which some of the tests are tried; for instance, WBMP is a black and white format, so loss of color information is expected there.) Run gddemo to see some of the capabilities of gd. Run gdtestft to play with the freetype support, if you have built gd with it and have access to truetype fonts.

gddemo should execute without incident, creating the file demoout.png. (Note there is also a file named demoin.png, which is provided in the package as part of the demonstration.)

Display demoout.png in your PNG viewer. The image should be 128x128 pixels and should contain an image of the space shuttle with quite a lot of graphical elements drawn on top of it.

(If you are missing the demoin.png file, the other items should appear anyway.)

Look at demoin.png to see the original space shuttle image which was scaled and copied into the output image.

gd basics: using gd in your program

-lgd -lpng -lz -ljpeg -lfreetype -lm

If you want to use the provided simple fonts, include gdfontt.h, gdfonts.h, gdfontmb.h, gdfontl.h and/or gdfontg.h. For more impressive results, install FreeType 2.x and use the gdImageStringFT function. If you are not using the provided Makefile and/or a library-based approach, be sure to include the source modules as well in your project. (They may be too large for 16-bit memory models, that is, 16-bit DOS and Windows.)

Here is a short example program. (For a more advanced example, see gddemo.c, included in the distribution. gddemo.c is NOT the same program; it demonstrates additional features!)

/* Bring in gd library functions */
#include "gd.h"

/* Bring in standard I/O so we can output the PNG to a file */
#include <stdio.h>

int main() {
  /* Declare the image */
  gdImagePtr im;
  /* Declare output files */
  FILE *pngout, *jpegout;
  /* Declare color indexes */
  int black;
  int white;

  /* Allocate the image: 64 pixels across by 64 pixels tall */
  im = gdImageCreate(64, 64);

  /* Allocate the color black (red, green and blue all minimum).
    Since this is the first color in a new image, it will
    be the background color. */
  black = gdImageColorAllocate(im, 0, 0, 0);  

  /* Allocate the color white (red, green and blue all maximum). */
  white = gdImageColorAllocate(im, 255, 255, 255);  
  
  /* Draw a line from the upper left to the lower right,
    using white color index. */
  gdImageLine(im, 0, 0, 63, 63, white);  

  /* Open a file for writing. "wb" means "write binary", important
    under MSDOS, harmless under Unix. */
  pngout = fopen("test.png", "wb");

  /* Do the same for a JPEG-format file. */
  jpegout = fopen("test.jpg", "wb");

  /* Output the image to the disk file in PNG format. */
  gdImagePng(im, pngout);

  /* Output the same image in JPEG format, using the default
    JPEG quality setting. */
  gdImageJpeg(im, jpegout, -1);

  /* Close the files. */
  fclose(pngout);
  fclose(jpegout);

  /* Destroy the image in memory. */
  gdImageDestroy(im);
}

The above example program should give you an idea of how the package works. gd provides many additional functions, which are listed in the following reference chapters, complete with code snippets demonstrating each. There is also an alphabetical index.

Webpng: a more powerful gd example

webpng.c is provided in the distribution. Unix users can simply type "make webpng" to compile the program. Type "webpng" with no arguments to see the available options.

Function and type reference

• Types
• Image creation, destruction, loading and saving
• Drawing, styling, brushing, tiling and filling functions
• Query functions (not color-related)
• Font and text-handling functions
• Color handling functions
• Copying, resizing, rotating, deformation and filter functions
• Miscellaneous Functions
• Constants

Types

gdImage(TYPE)

The data structure in which gd stores images. gdImageCreate, gdImageCreateTrueColor and the various image file-loading functions return a pointer to this type, and the other functions expect to receive a pointer to this type as their first argument. It is reasonably safe to examine any of the members of this structure. It is also reasonably safe to modify individual pixels within the pixels or tpixels arrays. If the trueColor flag is set, the tpixels array is valid; otherwise the pixels array is valid.

The colorsTotal, red, green, blue, alpha and open arrays manage the palette. They are valid only when the trueColor flag is not set. The transparent value contains the palette index of the first transparent color as read-only information for backwards compatibility; gd 2.0 stores this information in the alpha array so that variable transparency can be supported for each palette entry. However, for truecolor images, transparent represents a single RGB color which is always 100% transparent, and this feature is generally supported by browsers which do not support full alpha channels.

typedef struct {
  /* Palette-based image pixels */
  unsigned char ** pixels;
  int sx;
  int sy;
  /* These are valid in palette images only. See also
  /* 'alpha', which appears later in the structure to
    preserve binary backwards compatibility */
  int colorsTotal;
  int red[gdMaxColors];
  int green[gdMaxColors];
  int blue[gdMaxColors]; 
  int open[gdMaxColors];
  /* For backwards compatibility, this is set to the
    first palette entry with 100% transparency,
    and is also set and reset by the 
    gdImageColorTransparent function. Newer
    applications can allocate palette entries
    with any desired level of transparency; however,
    bear in mind that many viewers, notably
    many web browsers, fail to implement
    full alpha channel for PNG and provide
    support for full opacity or transparency only. */
  int transparent;
  int *polyInts;
  int polyAllocated;
  struct gdImageStruct *brush;
  struct gdImageStruct *tile;  
  int brushColorMap[gdMaxColors];
  int tileColorMap[gdMaxColors];
  int styleLength;
  int stylePos;
  int *style;
  int interlace;
  /* New in 2.0: alpha channel for palettes. Note that only
    Macintosh Internet Explorer and (possibly) Netscape 6
    really support multiple levels of transparency in
    palettes, to my knowledge, as of 2/15/01. Most
    common browsers will display 100% opaque and
    100% transparent correctly, and do something 
    unpredictable and/or undesirable for levels
    in between. TBB */
  int alpha[gdMaxColors]; 
  /* Truecolor flag and pixels. New 2.0 fields appear here at the
    end to minimize breakage of existing object code. */
  int trueColor;
  int ** tpixels;
  /* Should alpha channel be copied, or applied, each time a
    pixel is drawn? This applies to truecolor images only.
    No attempt is made to alpha-blend in palette images,
    even if semitransparent palette entries exist. 
    To do that, build your image as a truecolor image,
    then quantize down to 8 bits. */
  int alphaBlendingFlag;
  /* Should the alpha channel of the image be saved? This affects
    PNG at the moment; other future formats may also
    have that capability. JPEG doesn't. */
  int saveAlphaFlag;
} gdImage;

The order of the structure members may appear confusing, but was chosen deliberately to increase backwards compatibility with existing gd 1.x-based binary code that references particular structure members.

gdImagePtr (TYPE)

A pointer to an image structure. gdImageCreate returns this type, and the other functions expect it as the first argument.

gdIOCtx (TYPE)

Most of the gd functions that read and write files, such as gdImagePng and , also have variants that accept a gdIOCtx structure; see gdImagePngCtx and gdImageCreateFromJpegCtx. Those who wish to provide their own custom routines to read and write images can populate a gdIOCtx structure with functions of their own devising to to read and write data. For image reading, the only mandatory functions are getC and getBuf, which must return the number of characters actually read, or a negative value on error or EOF. These functions must read the number of characters requested unless at the end of the file. For image writing, the only mandatory functions are putC and putBuf, which return the number of characters written; these functions must write the number of characters requested except in the event of an error. The seek and tell functions are only required in conjunction with the gd2 file format, which supports quick loading of partial images. The gd_free function will not be invoked when calling the standard Ctx functions; it is an implementation convenience when adding new data types to gd. For examples, see gd_png.c, gd_gd2locate ompression and decompression routines slightly, because horizontally adjacent pixels are now next to each other in memory. This should not affect properly written gd applications, but applications that directly manipulate the pixels array will require changes.

What else do I need to use gd?

To use gd, you will need an ANSI C compiler. All popular Windows 95 and NT C compilers are ANSI C compliant. Any full-ANSI-standard C compiler should be adequate. The cc compiler released with SunOS 4.1.3 is not an ANSI C compiler. Most Unix users who do not already have gcc should get it. gcc is free, ANSI compliant and a de facto industry standard. Ask your ISP why it is missing.

As of version 1.6, you also need the zlib compression library, and the libpng library. As of version 1.6.2, you can draw text using antialiased TrueType fonts if you also have the libttf library installed, but this is not mandatory. zlib is available for a variety of platforms from the zlib web site. libpng is available for a variety of platforms from the PNG web site.

You will also want a PNG viewer, if you do not already have one for your system, since you will need a good way to check the results of your work. Netscape 4.04 and higher, and Microsoft Internet Explorer 4.0 or higher, both support PNG. Not every PNG-compatible viewer supports alpha channel transparency, which is why gd 2.0.2 and above do alpha blending in the library by default; it is possible to turn on the saving of alpha channel information to the file instead.

How do I get gd?

Binaries (DLL for Windows programmers):

• .ZIP File of DLL, Headers, Et Cetera

Source Code:

• Gzipped Tar File (Unix)
• .ZIP File of SOURCE CODE (Windows)

How do I build gd?

Win32 DLL users: if you are using MSVC, use the provided batch file makemsvcimport.bat to make a bgd.lib import library corresponding to the provided bgd.dll. Copy bgd.dll to your application directory, or to your Windows sytem directory. In the settings of your MSVC project, you MUST choose the "multithreaded DLL" library option under "code generation." mingw32 and cygwin users can simply link with the provided libbgd.a stub library in order to use the DLL.

In order to build gd, you must first unpack the archive you have downloaded. If you are not familiar with tar and gunzip (Unix) or ZIP (Windows), please consult with an experienced user of your system. Sorry, we cannot answer questions about basic Internet skills.

Unpacking the archive will produce a directory called "gd-2.0.33".

For Unix

./configure

NOTE: BY DEFAULT, THE LIBRARY IS INSTALLED IN /usr/local/lib and the include files are installed in /usr/local/include. IF YOU ARE UPGRADING, you may wish to use:

./configure --prefix=/usr

Rather than just ./configure, before typing make and make install.

If all goes well, this will create a Makefile. If all does not go well -- for instance, if neither the the JPEG nor the PNG and ZLIB libraries are found -- you will need to install those libraries, then come back and run configure again.

If necessary, make changes to the resulting Makefile. Then, type "make". If there are no errors, follow this with "make install". Because gd 2.0 and above installs as a shared library, it is necessary to install the library properly before running gd-based programs.

If you get errors, type ./configure --help for more information about the available options. In the unlikely event that the GNU autoconf-produced configure script does not work well for you, you may wish to try configure.pl, a simple Perl script with similar but less complete capabilities. If all else fails, try renaming makefile.sample to Makefile. However, ./configure is almost always your best bet.

For Windows

Use the DLL version! See the paragraph at the beginning of this sectino. If you really want to compile it yourself for some strange reason, read on.

Create a project using your favorite programming environment. Copy all of the gd files to the project directory. Add gd.c to your project. Add other source files as appropriate. Learning the basic skills of creating projects with your chosen C environment is up to you. Alternatively, use the free mingw32 or cygwin tools, which may prove to be compatible with the provided configure script.

If you wish to test the library, type "make test" AFTER you have successfully executed "make install". This will build several test programs, including "gddemo". (Not all of these programs are expected to print completely successful messages, depending on the nature of the image formats with which some of the tests are tried; for instance, WBMP is a black and white format, so loss of color information is expected there.) Run gddemo to see some of the capabilities of gd. Run gdtestft to play with the freetype support, if you have built gd with it and have access to truetype fonts.

gddemo should execute without incident, creating the file demoout.png. (Note there is also a file named demoin.png, which is provided in the package as part of the demonstration.)

Display demoout.png in your PNG viewer. The image should be 128x128 pixels and should contain an image of the space shuttle with quite a lot of graphical elements drawn on top of it.

(If you are missing the demoin.png file, the other items should appear anyway.)

Look at demoin.png to see the original space shuttle image which was scaled and copied into the output image.

gd basics: using gd in your program

-lgd -lpng -lz -ljpeg -lfreetype -lm

If you want to use the provided simple fonts, include gdfontt.h, gdfonts.h, gdfontmb.h, gdfontl.h and/or gdfontg.h. For more impressive results, install FreeType 2.x and use the gdImageStringFT function. If you are not using the provided Makefile and/or a library-based approach, be sure to include the source modules as well in your project. (They may be too large for 16-bit memory models, that is, 16-bit DOS and Windows.)

Here is a short example program. (For a more advanced example, see gddemo.c, included in the distribution. gddemo.c is NOT the same program; it demonstrates additional features!)

/* Bring in gd library functions */
#include "gd.h"

/* Bring in standard I/O so we can output the PNG to a file */
#include <stdio.h>

int main() {
  /* Declare the image */
  gdImagePtr im;
  /* Declare output files */
  FILE *pngout, *jpegout;
  /* Declare color indexes */
  int black;
  int white;

  /* Allocate the image: 64 pixels across by 64 pixels tall */
  im = gdImageCreate(64, 64);

  /* Allocate the color black (red, green and blue all minimum).
    Since this is the first color in a new image, it will
    be the background color. */
  black = gdImageColorAllocate(im, 0, 0, 0);  

  /* Allocate the color white (red, green and blue all maximum). */
  white = gdImageColorAllocate(im, 255, 255, 255);  
  
  /* Draw a line from the upper left to the lower right,
    using white color index. */
  gdImageLine(im, 0, 0, 63, 63, white);  

  /* Open a file for writing. "wb" means "write binary", important
    under MSDOS, harmless under Unix. */
  pngout = fopen("test.png", "wb");

  /* Do the same for a JPEG-format file. */
  jpegout = fopen("test.jpg", "wb");

  /* Output the image to the disk file in PNG format. */
  gdImagePng(im, pngout);

  /* Output the same image in JPEG format, using the default
    JPEG quality setting. */
  gdImageJpeg(im, jpegout, -1);

  /* Close the files. */
  fclose(pngout);
  fclose(jpegout);

  /* Destroy the image in memory. */
  gdImageDestroy(im);
}

The above example program should give you an idea of how the package works. gd provides many additional functions, which are listed in the following reference chapters, complete with code snippets demonstrating each. There is also an alphabetical index.

Webpng: a more powerful gd example

webpng.c is provided in the distribution. Unix users can simply type "make webpng" to compile the program. Type "webpng" with no arguments to see the available options.

Function and type reference

• Types
• Image creation, destruction, loading and saving
• Drawing, styling, brushing, tiling and filling functions
• Query functions (not color-related)
• Font and text-handling functions
• Color handling functions
• Copying, resizing, rotating, deformation and filter functions
• Miscellaneous Functions
• Constants

Types

gdImage(TYPE)

The data structure in which gd stores images. gdImageCreate, gdImageCreateTrueColor and the various image file-loading functions return a pointer to this type, and the other functions expect to receive a pointer to this type as their first argument. It is reasonably safe to examine any of the members of this structure. It is also reasonably safe to modify individual pixels within the pixels or tpixels arrays. If the trueColor flag is set, the tpixels array is valid; otherwise the pixels array is valid.

The colorsTotal, red, green, blue, alpha and open arrays manage the palette. They are valid only when the trueColor flag is not set. The transparent value contains the palette index of the first transparent color as read-only information for backwards compatibility; gd 2.0 stores this information in the alpha array so that variable transparency can be supported for each palette entry. However, for truecolor images, transparent represents a single RGB color which is always 100% transparent, and this feature is generally supported by browsers which do not support full alpha channels.

typedef struct {
  /* Palette-based image pixels */
  unsigned char ** pixels;
  int sx;
  int sy;
  /* These are valid in palette images only. See also
  /* 'alpha', which appears later in the structure to
    preserve binary backwards compatibility */
  int colorsTotal;
  int red[gdMaxColors];
  int green[gdMaxColors];
  int blue[gdMaxColors]; 
  int open[gdMaxColors];
  /* For backwards compatibility, this is set to the
    first palette entry with 100% transparency,
    and is also set and reset by the 
    gdImageColorTransparent function. Newer
    applications can allocate palette entries
    with any desired level of transparency; however,
    bear in mind that many viewers, notably
    many web browsers, fail to implement
    full alpha channel for PNG and provide
    support for full opacity or transparency only. */
  int transparent;
  int *polyInts;
  int polyAllocated;
  struct gdImageStruct *brush;
  struct gdImageStruct *tile;  
  int brushColorMap[gdMaxColors];
  int tileColorMap[gdMaxColors];
  int styleLength;
  int stylePos;
  int *style;
  int interlace;
  /* New in 2.0: alpha channel for palettes. Note that only
    Macintosh Internet Explorer and (possibly) Netscape 6
    really support multiple levels of transparency in
    palettes, to my knowledge, as of 2/15/01. Most
    common browsers will display 100% opaque and
    100% transparent correctly, and do something 
    unpredictable and/or undesirable for levels
    in between. TBB */
  int alpha[gdMaxColors]; 
  /* Truecolor flag and pixels. New 2.0 fields appear here at the
    end to minimize breakage of existing object code. */
  int trueColor;
  int ** tpixels;
  /* Should alpha channel be copied, or applied, each time a
    pixel is drawn? This applies to truecolor images only.
    No attempt is made to alpha-blend in palette images,
    even if semitransparent palette entries exist. 
    To do that, build your image as a truecolor image,
    then quantize down to 8 bits. */
  int alphaBlendingFlag;
  /* Should the alpha channel of the image be saved? This affects
    PNG at the moment; other future formats may also
    have that capability. JPEG doesn't. */
  int saveAlphaFlag;
} gdImage;

The order of the structure members may appear confusing, but was chosen deliberately to increase backwards compatibility with existing gd 1.x-based binary code that references particular structure members.

gdImagePtr (TYPE)

A pointer to an image structure. gdImageCreate returns this type, and the other functions expect it as the first argument.

gdIOCtx (TYPE)

Most of the gd functions that read and write files, such as gdImagePng and , also have variants that accept a gdIOCtx structure; see gdImagePngCtx and gdImageCreateFromJpegCtx. Those who wish to provide their own custom routines to read and write images can populate a gdIOCtx structure with functions of their own devising to to read and write data. For image reading, the only mandatory functions are getC and getBuf, which must return the number of characters actually read, or a negative value on error or EOF. These functions must read the number of characters requested unless at the end of the file. For image writing, the only mandatory functions are putC and putBuf, which return the number of characters written; these functions must write the number of characters requested except in the event of an error. The seek and tell functions are only required in conjunction with the gd2 file format, which supports quick loading of partial images. The gd_free function will not be invoked when calling the standard Ctx functions; it is an implementation convenience when adding new data types to gd. For examples, see gd_png.c, gd_gd2locate ompression and decompression routines slightly, because horizontally adjacent pixels are now next to each other in memory. This should not affect properly written gd applications, but applications that directly manipulate the pixels array will require changes.

What else do I need to use gd?

To use gd, you will need an ANSI C compiler. All popular Windows 95 and NT C compilers are ANSI C compliant. Any full-ANSI-standard C compiler should be adequate. The cc compiler released with SunOS 4.1.3 is not an ANSI C compiler. Most Unix users who do not already have gcc should get it. gcc is free, ANSI compliant and a de facto industry standard. Ask your ISP why it is missing.

As of version 1.6, you also need the zlib compression library, and the libpng library. As of version 1.6.2, you can draw text using antialiased TrueType fonts if you also have the libttf library installed, but this is not mandatory. zlib is available for a variety of platforms from the zlib web site. libpng is available for a variety of platforms from the PNG web site.

You will also want a PNG viewer, if you do not already have one for your system, since you will need a good way to check the results of your work. Netscape 4.04 and higher, and Microsoft Internet Explorer 4.0 or higher, both support PNG. Not every PNG-compatible viewer supports alpha channel transparency, which is why gd 2.0.2 and above do alpha blending in the library by default; it is possible to turn on the saving of alpha channel information to the file instead.

How do I get gd?

Binaries (DLL for Windows programmers):

• .ZIP File of DLL, Headers, Et Cetera

Source Code:

• Gzipped Tar File (Unix)
• .ZIP File of SOURCE CODE (Windows)

How do I build gd?

Win32 DLL users: if you are using MSVC, use the provided batch file makemsvcimport.bat to make a bgd.lib import library corresponding to the provided bgd.dll. Copy bgd.dll to your application directory, or to your Windows sytem directory. In the settings of your MSVC project, you MUST choose the "multithreaded DLL" library option under "code generation." mingw32 and cygwin users can simply link with the provided libbgd.a stub library in order to use the DLL.

In order to build gd, you must first unpack the archive you have downloaded. If you are not familiar with tar and gunzip (Unix) or ZIP (Windows), please consult with an experienced user of your system. Sorry, we cannot answer questions about basic Internet skills.

Unpacking the archive will produce a directory called "gd-2.0.33".

For Unix

./configure

NOTE: BY DEFAULT, THE LIBRARY IS INSTALLED IN /usr/local/lib and the include files are installed in /usr/local/include. IF YOU ARE UPGRADING, you may wish to use:

./configure --prefix=/usr

Rather than just ./configure, before typing make and make install.

If all goes well, this will create a Makefile. If all does not go well -- for instance, if neither the the JPEG nor the PNG and ZLIB libraries are found -- you will need to install those libraries, then come back and run configure again.

If necessary, make changes to the resulting Makefile. Then, type "make". If there are no errors, follow this with "make install". Because gd 2.0 and above installs as a shared library, it is necessary to install the library properly before running gd-based programs.

If you get errors, type ./configure --help for more information about the available options. In the unlikely event that the GNU autoconf-produced configure script does not work well for you, you may wish to try configure.pl, a simple Perl script with similar but less complete capabilities. If all else fails, try renaming makefile.sample to Makefile. However, ./configure is almost always your best bet.

For Windows

Use the DLL version! See the paragraph at the beginning of this sectino. If you really want to compile it yourself for some strange reason, read on.

Create a project using your favorite programming environment. Copy all of the gd files to the project directory. Add gd.c to your project. Add other source files as appropriate. Learning the basic skills of creating projects with your chosen C environment is up to you. Alternatively, use the free mingw32 or cygwin tools, which may prove to be compatible with the provided configure script.

If you wish to test the library, type "make test" AFTER you have successfully executed "make install". This will build several test programs, including "gddemo". (Not all of these programs are expected to print completely successful messages, depending on the nature of the image formats with which some of the tests are tried; for instance, WBMP is a black and white format, so loss of color information is expected there.) Run gddemo to see some of the capabilities of gd. Run gdtestft to play with the freetype support, if you have built gd with it and have access to truetype fonts.

gddemo should execute without incident, creating the file demoout.png. (Note there is also a file named demoin.png, which is provided in the package as part of the demonstration.)

Display demoout.png in your PNG viewer. The image should be 128x128 pixels and should contain an image of the space shuttle with quite a lot of graphical elements drawn on top of it.

(If you are missing the demoin.png file, the other items should appear anyway.)

Look at demoin.png to see the original space shuttle image which was scaled and copied into the output image.

gd basics: using gd in your program

-lgd -lpng -lz -ljpeg -lfreetype -lm

If you want to use the provided simple fonts, include gdfontt.h, gdfonts.h, gdfontmb.h, gdfontl.h and/or gdfontg.h. For more impressive results, install FreeType 2.x and use the gdImageStringFT function. If you are not using the provided Makefile and/or a library-based approach, be sure to include the source modules as well in your project. (They may be too large for 16-bit memory models, that is, 16-bit DOS and Windows.)

Here is a short example program. (For a more advanced example, see gddemo.c, included in the distribution. gddemo.c is NOT the same program; it demonstrates additional features!)

/* Bring in gd library functions */
#include "gd.h"

/* Bring in standard I/O so we can output the PNG to a file */
#include <stdio.h>

int main() {
  /* Declare the image */
  gdImagePtr im;
  /* Declare output files */
  FILE *pngout, *jpegout;
  /* Declare color indexes */
  int black;
  int white;

  /* Allocate the image: 64 pixels across by 64 pixels tall */
  im = gdImageCreate(64, 64);

  /* Allocate the color black (red, green and blue all minimum).
    Since this is the first color in a new image, it will
    be the background color. */
  black = gdImageColorAllocate(im, 0, 0, 0);  

  /* Allocate the color white (red, green and blue all maximum). */
  white = gdImageColorAllocate(im, 255, 255, 255);  
  
  /* Draw a line from the upper left to the lower right,
    using white color index. */
  gdImageLine(im, 0, 0, 63, 63, white);  

  /* Open a file for writing. "wb" means "write binary", important
    under MSDOS, harmless under Unix. */
  pngout = fopen("test.png", "wb");

  /* Do the same for a JPEG-format file. */
  jpegout = fopen("test.jpg", "wb");

  /* Output the image to the disk file in PNG format. */
  gdImagePng(im, pngout);

  /* Output the same image in JPEG format, using the default
    JPEG quality setting. */
  gdImageJpeg(im, jpegout, -1);

  /* Close the files. */
  fclose(pngout);
  fclose(jpegout);

  /* Destroy the image in memory. */
  gdImageDestroy(im);
}

The above example program should give you an idea of how the package works. gd provides many additional functions, which are listed in the following reference chapters, complete with code snippets demonstrating each. There is also an alphabetical index.

Webpng: a more powerful gd example

webpng.c is provided in the distribution. Unix users can simply type "make webpng" to compile the program. Type "webpng" with no arguments to see the available options.

Function and type reference

• Types
• Image creation, destruction, loading and saving
• Drawing, styling, brushing, tiling and filling functions
• Query functions (not color-related)
• Font and text-handling functions
• Color handling functions
• Copying, resizing, rotating, deformation and filter functions
• Miscellaneous Functions
• Constants

Types

gdImage(TYPE)

The data structure in which gd stores images. gdImageCreate, gdImageCreateTrueColor and the various image file-loading functions return a pointer to this type, and the other functions expect to receive a pointer to this type as their first argument. It is reasonably safe to examine any of the members of this structure. It is also reasonably safe to modify individual pixels within the pixels or tpixels arrays. If the trueColor flag is set, the tpixels array is valid; otherwise the pixels array is valid.

The colorsTotal, red, green, blue, alpha and open arrays manage the palette. They are valid only when the trueColor flag is not set. The transparent value contains the palette index of the first transparent color as read-only information for backwards compatibility; gd 2.0 stores this information in the alpha array so that variable transparency can be supported for each palette entry. However, for truecolor images, transparent represents a single RGB color which is always 100% transparent, and this feature is generally supported by browsers which do not support full alpha channels.

typedef struct {
  /* Palette-based image pixels */
  unsigned char ** pixels;
  int sx;
  int sy;
  /* These are valid in palette images only. See also
  /* 'alpha', which appears later in the structure to
    preserve binary backwards compatibility */
  int colorsTotal;
  int red[gdMaxColors];
  int green[gdMaxColors];
  int blue[gdMaxColors]; 
  int open[gdMaxColors];
  /* For backwards compatibility, this is set to the
    first palette entry with 100% transparency,
    and is also set and reset by the 
    gdImageColorTransparent function. Newer
    applications can allocate palette entries
    with any desired level of transparency; however,
    bear in mind that many viewers, notably
    many web browsers, fail to implement
    full alpha channel for PNG and provide
    support for full opacity or transparency only. */
  int transparent;
  int *polyInts;
  int polyAllocated;
  struct gdImageStruct *brush;
  struct gdImageStruct *tile;  
  int brushColorMap[gdMaxColors];
  int tileColorMap[gdMaxColors];
  int styleLength;
  int stylePos;
  int *style;
  int interlace;
  /* New in 2.0: alpha channel for palettes. Note that only
    Macintosh Internet Explorer and (possibly) Netscape 6
    really support multiple levels of transparency in
    palettes, to my knowledge, as of 2/15/01. Most
    common browsers will display 100% opaque and
    100% transparent correctly, and do something 
    unpredictable and/or undesirable for levels
    in between. TBB */
  int alpha[gdMaxColors]; 
  /* Truecolor flag and pixels. New 2.0 fields appear here at the
    end to minimize breakage of existing object code. */
  int trueColor;
  int ** tpixels;
  /* Should alpha channel be copied, or applied, each time a
    pixel is drawn? This applies to truecolor images only.
    No attempt is made to alpha-blend in palette images,
    even if semitransparent palette entries exist. 
    To do that, build your image as a truecolor image,
    then quantize down to 8 bits. */
  int alphaBlendingFlag;
  /* Should the alpha channel of the image be saved? This affects
    PNG at the moment; other future formats may also
    have that capability. JPEG doesn't. */
  int saveAlphaFlag;
} gdImage;

The order of the structure members may appear confusing, but was chosen deliberately to increase backwards compatibility with existing gd 1.x-based binary code that references particular structure members.

gdImagePtr (TYPE)

A pointer to an image structure. gdImageCreate returns this type, and the other functions expect it as the first argument.

gdIOCtx (TYPE)

Most of the gd functions that read and write files, such as gdImagePng and , also have variants that accept a gdIOCtx structure; see gdImagePngCtx and gdImageCreateFromJpegCtx. Those who wish to provide their own custom routines to read and write images can populate a gdIOCtx structure with functions of their own devising to to read and write data. For image reading, the only mandatory functions are getC and getBuf, which must return the number of characters actually read, or a negative value on error or EOF. These functions must read the number of characters requested unless at the end of the file. For image writing, the only mandatory functions are putC and putBuf, which return the number of characters written; these functions must write the number of characters requested except in the event of an error. The seek and tell functions are only required in conjunction with the gd2 file format, which supports quick loading of partial images. The gd_free function will not be invoked when calling the standard Ctx functions; it is an implementation convenience when adding new data types to gd. For examples, see gd_png.c, gd_gd2locate ompression and decompression routines slightly, because horizontally adjacent pixels are now next to each other in memory. This should not affect properly written gd applications, but applications that directly manipulate the pixels array will require changes.

What else do I need to use gd?

To use gd, you will need an ANSI C compiler. All popular Windows 95 and NT C compilers are ANSI C compliant. Any full-ANSI-standard C compiler should be adequate. The cc compiler released with SunOS 4.1.3 is not an ANSI C compiler. Most Unix users who do not already have gcc should get it. gcc is free, ANSI compliant and a de facto industry standard. Ask your ISP why it is missing.

As of version 1.6, you also need the zlib compression library, and the libpng library. As of version 1.6.2, you can draw text using antialiased TrueType fonts if you also have the libttf library installed, but this is not mandatory. zlib is available for a variety of platforms from the zlib web site. libpng is available for a variety of platforms from the PNG web site.

You will also want a PNG viewer, if you do not already have one for your system, since you will need a good way to check the results of your work. Netscape 4.04 and higher, and Microsoft Internet Explorer 4.0 or higher, both support PNG. Not every PNG-compatible viewer supports alpha channel transparency, which is why gd 2.0.2 and above do alpha blending in the library by default; it is possible to turn on the saving of alpha channel information to the file instead.

How do I get gd?

Binaries (DLL for Windows programmers):

• .ZIP File of DLL, Headers, Et Cetera

Source Code:

• Gzipped Tar File (Unix)
• .ZIP File of SOURCE CODE (Windows)

How do I build gd?

Win32 DLL users: if you are using MSVC, use the provided batch file makemsvcimport.bat to make a bgd.lib import library corresponding to the provided bgd.dll. Copy bgd.dll to your application directory, or to your Windows sytem directory. In the settings of your MSVC project, you MUST choose the "multithreaded DLL" library option under "code generation." mingw32 and cygwin users can simply link with the provided libbgd.a stub library in order to use the DLL.

In order to build gd, you must first unpack the archive you have downloaded. If you are not familiar with tar and gunzip (Unix) or ZIP (Windows), please consult with an experienced user of your system. Sorry, we cannot answer questions about basic Internet skills.

Unpacking the archive will produce a directory called "gd-2.0.33".

For Unix

./configure

NOTE: BY DEFAULT, THE LIBRARY IS INSTALLED IN /usr/local/lib and the include files are installed in /usr/local/include. IF YOU ARE UPGRADING, you may wish to use:

./configure --prefix=/usr

Rather than just ./configure, before typing make and make install.

If all goes well, this will create a Makefile. If all does not go well -- for instance, if neither the the JPEG nor the PNG and ZLIB libraries are found -- you will need to install those libraries, then come back and run configure again.

If necessary, make changes to the resulting Makefile. Then, type "make". If there are no errors, follow this with "make install". Because gd 2.0 and above installs as a shared library, it is necessary to install the library properly before running gd-based programs.

If you get errors, type ./configure --help for more information about the available options. In the unlikely event that the GNU autoconf-produced configure script does not work well for you, you may wish to try configure.pl, a simple Perl script with similar but less complete capabilities. If all else fails, try renaming makefile.sample to Makefile. However, ./configure is almost always your best bet.

For Windows

Use the DLL version! See the paragraph at the beginning of this sectino. If you really want to compile it yourself for some strange reason, read on.

Create a project using your favorite programming environment. Copy all of the gd files to the project directory. Add gd.c to your project. Add other source files as appropriate. Learning the basic skills of creating projects with your chosen C environment is up to you. Alternatively, use the free mingw32 or cygwin tools, which may prove to be compatible with the provided configure script.

If you wish to test the library, type "make test" AFTER you have successfully executed "make install". This will build several test programs, including "gddemo". (Not all of these programs are expected to print completely successful messages, depending on the nature of the image formats with which some of the tests are tried; for instance, WBMP is a black and white format, so loss of color information is expected there.) Run gddemo to see some of the capabilities of gd. Run gdtestft to play with the freetype support, if you have built gd with it and have access to truetype fonts.

gddemo should execute without incident, creating the file demoout.png. (Note there is also a file named demoin.png, which is provided in the package as part of the demonstration.)

Display demoout.png in your PNG viewer. The image should be 128x128 pixels and should contain an image of the space shuttle with quite a lot of graphical elements drawn on top of it.

(If you are missing the demoin.png file, the other items should appear anyway.)

Look at demoin.png to see the original space shuttle image which was scaled and copied into the output image.

gd basics: using gd in your program

-lgd -lpng -lz -ljpeg -lfreetype -lm

If you want to use the provided simple fonts, include gdfontt.h, gdfonts.h, gdfontmb.h, gdfontl.h and/or gdfontg.h. For more impressive results, install FreeType 2.x and use the gdImageStringFT function. If you are not using the provided Makefile and/or a library-based approach, be sure to include the source modules as well in your project. (They may be too large for 16-bit memory models, that is, 16-bit DOS and Windows.)

Here is a short example program. (For a more advanced example, see gddemo.c, included in the distribution. gddemo.c is NOT the same program; it demonstrates additional features!)

/* Bring in gd library functions */
#include "gd.h"

/* Bring in standard I/O so we can output the PNG to a file */
#include <stdio.h>

int main() {
  /* Declare the image */
  gdImagePtr im;
  /* Declare output files */
  FILE *pngout, *jpegout;
  /* Declare color indexes */
  int black;
  int white;

  /* Allocate the image: 64 pixels across by 64 pixels tall */
  im = gdImageCreate(64, 64);

  /* Allocate the color black (red, green and blue all minimum).
    Since this is the first color in a new image, it will
    be the background color. */
  black = gdImageColorAllocate(im, 0, 0, 0);  

  /* Allocate the color white (red, green and blue all maximum). */
  white = gdImageColorAllocate(im, 255, 255, 255);  
  
  /* Draw a line from the upper left to the lower right,
    using white color index. */
  gdImageLine(im, 0, 0, 63, 63, white);  

  /* Open a file for writing. "wb" means "write binary", important
    under MSDOS, harmless under Unix. */
  pngout = fopen("test.png", "wb");

  /* Do the same for a JPEG-format file. */
  jpegout = fopen("test.jpg", "wb");

  /* Output the image to the disk file in PNG format. */
  gdImagePng(im, pngout);

  /* Output the same image in JPEG format, using the default
    JPEG quality setting. */
  gdImageJpeg(im, jpegout, -1);

  /* Close the files. */
  fclose(pngout);
  fclose(jpegout);

  /* Destroy the image in memory. */
  gdImageDestroy(im);
}

The above example program should give you an idea of how the package works. gd provides many additional functions, which are listed in the following reference chapters, complete with code snippets demonstrating each. There is also an alphabetical index.

Webpng: a more powerful gd example

webpng.c is provided in the distribution. Unix users can simply type "make webpng" to compile the program. Type "webpng" with no arguments to see the available options.

Function and type reference

• Types
• Image creation, destruction, loading and saving
• Drawing, styling, brushing, tiling and filling functions
• Query functions (not color-related)
• Font and text-handling functions
• Color handling functions
• Copying, resizing, rotating, deformation and filter functions
• Miscellaneous Functions
• Constants

Types

gdImage(TYPE)

The data structure in which gd stores images. gdImageCreate, gdImageCreateTrueColor and the various image file-loading functions return a pointer to this type, and the other functions expect to receive a pointer to this type as their first argument. It is reasonably safe to examine any of the members of this structure. It is also reasonably safe to modify individual pixels within the pixels or tpixels arrays. If the trueColor flag is set, the tpixels array is valid; otherwise the pixels array is valid.

The colorsTotal, red, green, blue, alpha and open arrays manage the palette. They are valid only when the trueColor flag is not set. The transparent value contains the palette index of the first transparent color as read-only information for backwards compatibility; gd 2.0 stores this information in the alpha array so that variable transparency can be supported for each palette entry. However, for truecolor images, transparent represents a single RGB color which is always 100% transparent, and this feature is generally supported by browsers which do not support full alpha channels.

typedef struct {
  /* Palette-based image pixels */
  unsigned char ** pixels;
  int sx;
  int sy;
  /* These are valid in palette images only. See also
  /* 'alpha', which appears later in the structure to
    preserve binary backwards compatibility */
  int colorsTotal;
  int red[gdMaxColors];
  int green[gdMaxColors];
  int blue[gdMaxColors]; 
  int open[gdMaxColors];
  /* For backwards compatibility, this is set to the
    first palette entry with 100% transparency,
    and is also set and reset by the 
    gdImageColorTransparent function. Newer
    applications can allocate palette entries
    with any desired level of transparency; however,
    bear in mind that many viewers, notably
    many web browsers, fail to implement
    full alpha channel for PNG and provide
    support for full opacity or transparency only. */
  int transparent;
  int *polyInts;
  int polyAllocated;
  struct gdImageStruct *brush;
  struct gdImageStruct *tile;  
  int brushColorMap[gdMaxColors];
  int tileColorMap[gdMaxColors];
  int styleLength;
  int stylePos;
  int *style;
  int interlace;
  /* New in 2.0: alpha channel for palettes. Note that only
    Macintosh Internet Explorer and (possibly) Netscape 6
    really support multiple levels of transparency in
    palettes, to my knowledge, as of 2/15/01. Most
    common browsers will display 100% opaque and
    100% transparent correctly, and do something 
    unpredictable and/or undesirable for levels
    in between. TBB */
  int alpha[gdMaxColors]; 
  /* Truecolor flag and pixels. New 2.0 fields appear here at the
    end to minimize breakage of existing object code. */
  int trueColor;
  int ** tpixels;
  /* Should alpha channel be copied, or applied, each time a
    pixel is drawn? This applies to truecolor images only.
    No attempt is made to alpha-blend in palette images,
    even if semitransparent palette entries exist. 
    To do that, build your image as a truecolor image,
    then quantize down to 8 bits. */
  int alphaBlendingFlag;
  /* Should the alpha channel of the image be saved? This affects
    PNG at the moment; other future formats may also
    have that capability. JPEG doesn't. */
  int saveAlphaFlag;
} gdImage;

The order of the structure members may appear confusing, but was chosen deliberately to increase backwards compatibility with existing gd 1.x-based binary code that references particular structure members.

gdImagePtr (TYPE)

A pointer to an image structure. gdImageCreate returns this type, and the other functions expect it as the first argument.

gdIOCtx (TYPE)

Most of the gd functions that read and write files, such as gdImagePng and , also have variants that accept a gdIOCtx structure; see gdImagePngCtx and gdImageCreateFromJpegCtx. Those who wish to provide their own custom routines to read and write images can populate a gdIOCtx structure with functions of their own devising to to read and write data. For image reading, the only mandatory functions are getC and getBuf, which must return the number of characters actually read, or a negative value on error or EOF. These functions must read the number of characters requested unless at the end of the file. For image writing, the only mandatory functions are putC and putBuf, which return the number of characters written; these functions must write the number of characters requested except in the event of an error. The seek and tell functions are only required in conjunction with the gd2 file format, which supports quick loading of partial images. The gd_free function will not be invoked when calling the standard Ctx functions; it is an implementation convenience when adding new data types to gd. For examples, see gd_png.c, gd_gd2locate ompression and decompression routines slightly, because horizontally adjacent pixels are now next to each other in memory. This should not affect properly written gd applications, but applications that directly manipulate the pixels array will require changes.

What else do I need to use gd?

To use gd, you will need an ANSI C compiler. All popular Windows 95 and NT C compilers are ANSI C compliant. Any full-ANSI-standard C compiler should be adequate. The cc compiler released with SunOS 4.1.3 is not an ANSI C compiler. Most Unix users who do not already have gcc should get it. gcc is free, ANSI compliant and a de facto industry standard. Ask your ISP why it is missing.

As of version 1.6, you also need the zlib compression library, and the libpng library. As of version 1.6.2, you can draw text using antialiased TrueType fonts if you also have the libttf library installed, but this is not mandatory. zlib is available for a variety of platforms from the zlib web site. libpng is available for a variety of platforms from the PNG web site.

You will also want a PNG viewer, if you do not already have one for your system, since you will need a good way to check the results of your work. Netscape 4.04 and higher, and Microsoft Internet Explorer 4.0 or higher, both support PNG. Not every PNG-compatible viewer supports alpha channel transparency, which is why gd 2.0.2 and above do alpha blending in the library by default; it is possible to turn on the saving of alpha channel information to the file instead.

How do I get gd?

Binaries (DLL for Windows programmers):

• .ZIP File of DLL, Headers, Et Cetera

Source Code:

• Gzipped Tar File (Unix)
• .ZIP File of SOURCE CODE (Windows)

How do I build gd?

Win32 DLL users: if you are using MSVC, use the provided batch file makemsvcimport.bat to make a bgd.lib import library corresponding to the provided bgd.dll. Copy bgd.dll to your application directory, or to your Windows sytem directory. In the settings of your MSVC project, you MUST choose the "multithreaded DLL" library option under "code generation." mingw32 and cygwin users can simply link with the provided libbgd.a stub library in order to use the DLL.

In order to build gd, you must first unpack the archive you have downloaded. If you are not familiar with tar and gunzip (Unix) or ZIP (Windows), please consult with an experienced user of your system. Sorry, we cannot answer questions about basic Internet skills.

Unpacking the archive will produce a directory called "gd-2.0.33".

For Unix

./configure

NOTE: BY DEFAULT, THE LIBRARY IS INSTALLED IN /usr/local/lib and the include files are installed in /usr/local/include. IF YOU ARE UPGRADING, you may wish to use:

./configure --prefix=/usr

Rather than just ./configure, before typing make and make install.

If all goes well, this will create a Makefile. If all does not go well -- for instance, if neither the the JPEG nor the PNG and ZLIB libraries are found -- you will need to install those libraries, then come back and run configure again.

If necessary, make changes to the resulting Makefile. Then, type "make". If there are no errors, follow this with "make install". Because gd 2.0 and above installs as a shared library, it is necessary to install the library properly before running gd-based programs.

If you get errors, type ./configure --help for more information about the available options. In the unlikely event that the GNU autoconf-produced configure script does not work well for you, you may wish to try configure.pl, a simple Perl script with similar but less complete capabilities. If all else fails, try renaming makefile.sample to Makefile. However, ./configure is almost always your best bet.

For Windows

Use the DLL version! See the paragraph at the beginning of this sectino. If you really want to compile it yourself for some strange reason, read on.

Create a project using your favorite programming environment. Copy all of the gd files to the project directory. Add gd.c to your project. Add other source files as appropriate. Learning the basic skills of creating projects with your chosen C environment is up to you. Alternatively, use the free mingw32 or cygwin tools, which may prove to be compatible with the provided configure script.

If you wish to test the library, type "make test" AFTER you have successfully executed "make install". This will build several test programs, including "gddemo". (Not all of these programs are expected to print completely successful messages, depending on the nature of the image formats with which some of the tests are tried; for instance, WBMP is a black and white format, so loss of color information is expected there.) Run gddemo to see some of the capabilities of gd. Run gdtestft to play with the freetype support, if you have built gd with it and have access to truetype fonts.

gddemo should execute without incident, creating the file demoout.png. (Note there is also a file named demoin.png, which is provided in the package as part of the demonstration.)

Display demoout.png in your PNG viewer. The image should be 128x128 pixels and should contain an image of the space shuttle with quite a lot of graphical elements drawn on top of it.

(If you are missing the demoin.png file, the other items should appear anyway.)

Look at demoin.png to see the original space shuttle image which was scaled and copied into the output image.

gd basics: using gd in your program

-lgd -lpng -lz -ljpeg -lfreetype -lm

If you want to use the provided simple fonts, include gdfontt.h, gdfonts.h, gdfontmb.h, gdfontl.h and/or gdfontg.h. For more impressive results, install FreeType 2.x and use the gdImageStringFT function. If you are not using the provided Makefile and/or a library-based approach, be sure to include the source modules as well in your project. (They may be too large for 16-bit memory models, that is, 16-bit DOS and Windows.)

Here is a short example program. (For a more advanced example, see gddemo.c, included in the distribution. gddemo.c is NOT the same program; it demonstrates additional features!)

/* Bring in gd library functions */
#include "gd.h"

/* Bring in standard I/O so we can output the PNG to a file */
#include <stdio.h>

int main() {
  /* Declare the image */
  gdImagePtr im;
  /* Declare output files */
  FILE *pngout, *jpegout;
  /* Declare color indexes */
  int black;
  int white;

  /* Allocate the image: 64 pixels across by 64 pixels tall */
  im = gdImageCreate(64, 64);

  /* Allocate the color black (red, green and blue all minimum).
    Since this is the first color in a new image, it will
    be the background color. */
  black = gdImageColorAllocate(im, 0, 0, 0);  

  /* Allocate the color white (red, green and blue all maximum). */
  white = gdImageColorAllocate(im, 255, 255, 255);  
  
  /* Draw a line from the upper left to the lower right,
    using white color index. */
  gdImageLine(im, 0, 0, 63, 63, white);  

  /* Open a file for writing. "wb" means "write binary", important
    under MSDOS, harmless under Unix. */
  pngout = fopen("test.png", "wb");

  /* Do the same for a JPEG-format file. */
  jpegout = fopen("test.jpg", "wb");

  /* Output the image to the disk file in PNG format. */
  gdImagePng(im, pngout);

  /* Output the same image in JPEG format, using the default
    JPEG quality setting. */
  gdImageJpeg(im, jpegout, -1);

  /* Close the files. */
  fclose(pngout);
  fclose(jpegout);

  /* Destroy the image in memory. */
  gdImageDestroy(im);
}

The above example program should give you an idea of how the package works. gd provides many additional functions, which are listed in the following reference chapters, complete with code snippets demonstrating each. There is also an alphabetical index.

Webpng: a more powerful gd example

webpng.c is provided in the distribution. Unix users can simply type "make webpng" to compile the program. Type "webpng" with no arguments to see the available options.

Function and type reference

• Types
• Image creation, destruction, loading and saving
• Drawing, styling, brushing, tiling and filling functions
• Query functions (not color-related)
• Font and text-handling functions
• Color handling functions
• Copying, resizing, rotating, deformation and filter functions
• Miscellaneous Functions
• Constants

Types

gdImage(TYPE)

The data structure in which gd stores images. gdImageCreate, gdImageCreateTrueColor and the various image file-loading functions return a pointer to this type, and the other functions expect to receive a pointer to this type as their first argument. It is reasonably safe to examine any of the members of this structure. It is also reasonably safe to modify individual pixels within the pixels or tpixels arrays. If the trueColor flag is set, the tpixels array is valid; otherwise the pixels array is valid.

The colorsTotal, red, green, blue, alpha and open arrays manage the palette. They are valid only when the trueColor flag is not set. The transparent value contains the palette index of the first transparent color as read-only information for backwards compatibility; gd 2.0 stores this information in the alpha array so that variable transparency can be supported for each palette entry. However, for truecolor images, transparent represents a single RGB color which is always 100% transparent, and this feature is generally supported by browsers which do not support full alpha channels.

typedef struct {
  /* Palette-based image pixels */
  unsigned char ** pixels;
  int sx;
  int sy;
  /* These are valid in palette images only. See also
  /* 'alpha', which appears later in the structure to
    preserve binary backwards compatibility */
  int colorsTotal;
  int red[gdMaxColors];
  int green[gdMaxColors];
  int blue[gdMaxColors]; 
  int open[gdMaxColors];
  /* For backwards compatibility, this is set to the
    first palette entry with 100% transparency,
    and is also set and reset by the 
    gdImageColorTransparent function. Newer
    applications can allocate palette entries
    with any desired level of transparency; however,
    bear in mind that many viewers, notably
    many web browsers, fail to implement
    full alpha channel for PNG and provide
    support for full opacity or transparency only. */
  int transparent;
  int *polyInts;
  int polyAllocated;
  struct gdImageStruct *brush;
  struct gdImageStruct *tile;  
  int brushColorMap[gdMaxColors];
  int tileColorMap[gdMaxColors];
  int styleLength;
  int stylePos;
  int *style;
  int interlace;
  /* New in 2.0: alpha channel for palettes. Note that only
    Macintosh Internet Explorer and (possibly) Netscape 6
    really support multiple levels of transparency in
    palettes, to my knowledge, as of 2/15/01. Most
    common browsers will display 100% opaque and
    100% transparent correctly, and do something 
    unpredictable and/or undesirable for levels
    in between. TBB */
  int alpha[gdMaxColors]; 
  /* Truecolor flag and pixels. New 2.0 fields appear here at the
    end to minimize breakage of existing object code. */
  int trueColor;
  int ** tpixels;
  /* Should alpha channel be copied, or applied, each time a
    pixel is drawn? This applies to truecolor images only.
    No attempt is made to alpha-blend in palette images,
    even if semitransparent palette entries exist. 
    To do that, build your image as a truecolor image,
    then quantize down to 8 bits. */
  int alphaBlendingFlag;
  /* Should the alpha channel of the image be saved? This affects
    PNG at the moment; other future formats may also
    have that capability. JPEG doesn't. */
  int saveAlphaFlag;
} gdImage;

The order of the structure members may appear confusing, but was chosen deliberately to increase backwards compatibility with existing gd 1.x-based binary code that references particular structure members.

gdImagePtr (TYPE)

A pointer to an image structure. gdImageCreate returns this type, and the other functions expect it as the first argument.

gdIOCtx (TYPE)

Most of the gd functions that read and write files, such as gdImagePng and , also have variants that accept a gdIOCtx structure; see gdImagePngCtx and gdImageCreateFromJpegCtx. Those who wish to provide their own custom routines to read and write images can populate a gdIOCtx structure with functions of their own devising to to read and write data. For image reading, the only mandatory functions are getC and getBuf, which must return the number of characters actually read, or a negative value on error or EOF. These functions must read the number of characters requested unless at the end of the file. For image writing, the only mandatory functions are putC and putBuf, which return the number of characters written; these functions must write the number of characters requested except in the event of an error. The seek and tell functions are only required in conjunction with the gd2 file format, which supports quick loading of partial images. The gd_free function will not be invoked when calling the standard Ctx functions; it is an implementation convenience when adding new data types to gd. For examples, see gd_png.c, gd_gd2locate ompression and decompression routines slightly, because horizontally adjacent pixels are now next to each other in memory. This should not affect properly written gd applications, but applications that directly manipulate the pixels array will require changes.

What else do I need to use gd?

To use gd, you will need an ANSI C compiler. All popular Windows 95 and NT C compilers are ANSI C compliant. Any full-ANSI-standard C compiler should be adequate. The cc compiler released with SunOS 4.1.3 is not an ANSI C compiler. Most Unix users who do not already have gcc should get it. gcc is free, ANSI compliant and a de facto industry standard. Ask your ISP why it is missing.

As of version 1.6, you also need the zlib compression library, and the libpng library. As of version 1.6.2, you can draw text using antialiased TrueType fonts if you also have the libttf library installed, but this is not mandatory. zlib is available for a variety of platforms from the zlib web site. libpng is available for a variety of platforms from the PNG web site.

You will also want a PNG viewer, if you do not already have one for your system, since you will need a good way to check the results of your work. Netscape 4.04 and higher, and Microsoft Internet Explorer 4.0 or higher, both support PNG. Not every PNG-compatible viewer supports alpha channel transparency, which is why gd 2.0.2 and above do alpha blending in the library by default; it is possible to turn on the saving of alpha channel information to the file instead.

How do I get gd?

Binaries (DLL for Windows programmers):

• .ZIP File of DLL, Headers, Et Cetera

Source Code:

• Gzipped Tar File (Unix)
• .ZIP File of SOURCE CODE (Windows)

How do I build gd?

Win32 DLL users: if you are using MSVC, use the provided batch file makemsvcimport.bat to make a bgd.lib import library corresponding to the provided bgd.dll. Copy bgd.dll to your application directory, or to your Windows sytem directory. In the settings of your MSVC project, you MUST choose the "multithreaded DLL" library option under "code generation." mingw32 and cygwin users can simply link with the provided libbgd.a stub library in order to use the DLL.

In order to build gd, you must first unpack the archive you have downloaded. If you are not familiar with tar and gunzip (Unix) or ZIP (Windows), please consult with an experienced user of your system. Sorry, we cannot answer questions about basic Internet skills.

Unpacking the archive will produce a directory called "gd-2.0.33".

For Unix

./configure

NOTE: BY DEFAULT, THE LIBRARY IS INSTALLED IN /usr/local/lib and the include files are installed in /usr/local/include. IF YOU ARE UPGRADING, you may wish to use:

./configure --prefix=/usr

Rather than just ./configure, before typing make and make install.

If all goes well, this will create a Makefile. If all does not go well -- for instance, if neither the the JPEG nor the PNG and ZLIB libraries are found -- you will need to install those libraries, then come back and run configure again.

If necessary, make changes to the resulting Makefile. Then, type "make". If there are no errors, follow this with "make install". Because gd 2.0 and above installs as a shared library, it is necessary to install the library properly before running gd-based programs.

If you get errors, type ./configure --help for more information about the available options. In the unlikely event that the GNU autoconf-produced configure script does not work well for you, you may wish to try configure.pl, a simple Perl script with similar but less complete capabilities. If all else fails, try renaming makefile.sample to Makefile. However, ./configure is almost always your best bet.

For Windows

Use the DLL version! See the paragraph at the beginning of this sectino. If you really want to compile it yourself for some strange reason, read on.

Create a project using your favorite programming environment. Copy all of the gd files to the project directory. Add gd.c to your project. Add other source files as appropriate. Learning the basic skills of creating projects with your chosen C environment is up to you. Alternatively, use the free mingw32 or cygwin tools, which may prove to be compatible with the provided configure script.

If you wish to test the library, type "make test" AFTER you have successfully executed "make install". This will build several test programs, including "gddemo". (Not all of these programs are expected to print completely successful messages, depending on the nature of the image formats with which some of the tests are tried; for instance, WBMP is a black and white format, so loss of color information is expected there.) Run gddemo to see some of the capabilities of gd. Run gdtestft to play with the freetype support, if you have built gd with it and have access to truetype fonts.

gddemo should execute without incident, creating the file demoout.png. (Note there is also a file named demoin.png, which is provided in the package as part of the demonstration.)

Display demoout.png in your PNG viewer. The image should be 128x128 pixels and should contain an image of the space shuttle with quite a lot of graphical elements drawn on top of it.

(If you are missing the demoin.png file, the other items should appear anyway.)

Look at demoin.png to see the original space shuttle image which was scaled and copied into the output image.

gd basics: using gd in your program

-lgd -lpng -lz -ljpeg -lfreetype -lm

If you want to use the provided simple fonts, include gdfontt.h, gdfonts.h, gdfontmb.h, gdfontl.h and/or gdfontg.h. For more impressive results, install FreeType 2.x and use the gdImageStringFT function. If you are not using the provided Makefile and/or a library-based approach, be sure to include the source modules as well in your project. (They may be too large for 16-bit memory models, that is, 16-bit DOS and Windows.)

Here is a short example program. (For a more advanced example, see gddemo.c, included in the distribution. gddemo.c is NOT the same program; it demonstrates additional features!)

/* Bring in gd library functions */
#include "gd.h"

/* Bring in standard I/O so we can output the PNG to a file */
#include <stdio.h>

int main() {
  /* Declare the image */
  gdImagePtr im;
  /* Declare output files */
  FILE *pngout, *jpegout;
  /* Declare color indexes */
  int black;
  int white;

  /* Allocate the image: 64 pixels across by 64 pixels tall */
  im = gdImageCreate(64, 64);

  /* Allocate the color black (red, green and blue all minimum).
    Since this is the first color in a new image, it will
    be the background color. */
  black = gdImageColorAllocate(im, 0, 0, 0);  

  /* Allocate the color white (red, green and blue all maximum). */
  white = gdImageColorAllocate(im, 255, 255, 255);  
  
  /* Draw a line from the upper left to the lower right,
    using white color index. */
  gdImageLine(im, 0, 0, 63, 63, white);  

  /* Open a file for writing. "wb" means "write binary", important
    under MSDOS, harmless under Unix. */
  pngout = fopen("test.png", "wb");

  /* Do the same for a JPEG-format file. */
  jpegout = fopen("test.jpg", "wb");

  /* Output the image to the disk file in PNG format. */
  gdImagePng(im, pngout);

  /* Output the same image in JPEG format, using the default
    JPEG quality setting. */
  gdImageJpeg(im, jpegout, -1);

  /* Close the files. */
  fclose(pngout);
  fclose(jpegout);

  /* Destroy the image in memory. */
  gdImageDestroy(im);
}

The above example program should give you an idea of how the package works. gd provides many additional functions, which are listed in the following reference chapters, complete with code snippets demonstrating each. There is also an alphabetical index.

Webpng: a more powerful gd example

webpng.c is provided in the distribution. Unix users can simply type "make webpng" to compile the program. Type "webpng" with no arguments to see the available options.

Function and type reference

• Types
• Image creation, destruction, loading and saving
• Drawing, styling, brushing, tiling and filling functions
• Query functions (not color-related)
• Font and text-handling functions
• Color handling functions
• Copying, resizing, rotating, deformation and filter functions
• Miscellaneous Functions
• Constants

Types

gdImage(TYPE)

The data structure in which gd stores images. gdImageCreate, gdImageCreateTrueColor and the various image file-loading functions return a pointer to this type, and the other functions expect to receive a pointer to this type as their first argument. It is reasonably safe to examine any of the members of this structure. It is also reasonably safe to modify individual pixels within the pixels or tpixels arrays. If the trueColor flag is set, the tpixels array is valid; otherwise the pixels array is valid.

The colorsTotal, red, green, blue, alpha and open arrays manage the palette. They are valid only when the trueColor flag is not set. The transparent value contains the palette index of the first transparent color as read-only information for backwards compatibility; gd 2.0 stores this information in the alpha array so that variable transparency can be supported for each palette entry. However, for truecolor images, transparent represents a single RGB color which is always 100% transparent, and this feature is generally supported by browsers which do not support full alpha channels.

typedef struct {
  /* Palette-based image pixels */
  unsigned char ** pixels;
  int sx;
  int sy;
  /* These are valid in palette images only. See also
  /* 'alpha', which appears later in the structure to
    preserve binary backwards compatibility */
  int colorsTotal;
  int red[gdMaxColors];
  int green[gdMaxColors];
  int blue[gdMaxColors]; 
  int open[gdMaxColors];
  /* For backwards compatibility, this is set to the
    first palette entry with 100% transparency,
    and is also set and reset by the 
    gdImageColorTransparent function. Newer
    applications can allocate palette entries
    with any desired level of transparency; however,
    bear in mind that many viewers, notably
    many web browsers, fail to implement
    full alpha channel for PNG and provide
    support for full opacity or transparency only. */
  int transparent;
  int *polyInts;
  int polyAllocated;
  struct gdImageStruct *brush;
  struct gdImageStruct *tile;  
  int brushColorMap[gdMaxColors];
  int tileColorMap[gdMaxColors];
  int styleLength;
  int stylePos;
  int *style;
  int interlace;
  /* New in 2.0: alpha channel for palettes. Note that only
    Macintosh Internet Explorer and (possibly) Netscape 6
    really support multiple levels of transparency in
    palettes, to my knowledge, as of 2/15/01. Most
    common browsers will display 100% opaque and
    100% transparent correctly, and do something 
    unpredictable and/or undesirable for levels
    in between. TBB */
  int alpha[gdMaxColors]; 
  /* Truecolor flag and pixels. New 2.0 fields appear here at the
    end to minimize breakage of existing object code. */
  int trueColor;
  int ** tpixels;
  /* Should alpha channel be copied, or applied, each time a
    pixel is drawn? This applies to truecolor images only.
    No attempt is made to alpha-blend in palette images,
    even if semitransparent palette entries exist. 
    To do that, build your image as a truecolor image,
    then quantize down to 8 bits. */
  int alphaBlendingFlag;
  /* Should the alpha channel of the image be saved? This affects
    PNG at the moment; other future formats may also
    have that capability. JPEG doesn't. */
  int saveAlphaFlag;
} gdImage;

The order of the structure members may appear confusing, but was chosen deliberately to increase backwards compatibility with existing gd 1.x-based binary code that references particular structure members.

gdImagePtr (TYPE)

A pointer to an image structure. gdImageCreate returns this type, and the other functions expect it as the first argument.

gdIOCtx (TYPE)

Most of the gd functions that read and write files, such as gdImagePng and , also have variants that accept a gdIOCtx structure; see gdImagePngCtx and gdImageCreateFromJpegCtx. Those who wish to provide their own custom routines to read and write images can populate a gdIOCtx structure with functions of their own devising to to read and write data. For image reading, the only mandatory functions are getC and getBuf, which must return the number of characters actually read, or a negative value on error or EOF. These functions must read the number of characters requested unless at the end of the file. For image writing, the only mandatory functions are putC and putBuf, which return the number of characters written; these functions must write the number of characters requested except in the event of an error. The seek and tell functions are only required in conjunction with the gd2 file format, which supports quick loading of partial images. The gd_free function will not be invoked when calling the standard Ctx functions; it is an implementation convenience when adding new data types to gd. For examples, see gd_png.c, gd_gd2locate ompression and decompression routines slightly, because horizontally adjacent pixels are now next to each other in memory. This should not affect properly written gd applications, but applications that directly manipulate the pixels array will require changes.

What else do I need to use gd?

To use gd, you will need an ANSI C compiler. All popular Windows 95 and NT C compilers are ANSI C compliant. Any full-ANSI-standard C compiler should be adequate. The cc compiler released with SunOS 4.1.3 is not an ANSI C compiler. Most Unix users who do not already have gcc should get it. gcc is free, ANSI compliant and a de facto industry standard. Ask your ISP why it is missing.

As of version 1.6, you also need the zlib compression library, and the libpng library. As of version 1.6.2, you can draw text using antialiased TrueType fonts if you also have the libttf library installed, but this is not mandatory. zlib is available for a variety of platforms from the zlib web site. libpng is available for a variety of platforms from the PNG web site.

You will also want a PNG viewer, if you do not already have one for your system, since you will need a good way to check the results of your work. Netscape 4.04 and higher, and Microsoft Internet Explorer 4.0 or higher, both support PNG. Not every PNG-compatible viewer supports alpha channel transparency, which is why gd 2.0.2 and above do alpha blending in the library by default; it is possible to turn on the saving of alpha channel information to the file instead.

How do I get gd?

Binaries (DLL for Windows programmers):

• .ZIP File of DLL, Headers, Et Cetera

Source Code:

• Gzipped Tar File (Unix)
• .ZIP File of SOURCE CODE (Windows)

How do I build gd?

Win32 DLL users: if you are using MSVC, use the provided batch file makemsvcimport.bat to make a bgd.lib import library corresponding to the provided bgd.dll. Copy bgd.dll to your application directory, or to your Windows sytem directory. In the settings of your MSVC project, you MUST choose the "multithreaded DLL" library option under "code generation." mingw32 and cygwin users can simply link with the provided libbgd.a stub library in order to use the DLL.

In order to build gd, you must first unpack the archive you have downloaded. If you are not familiar with tar and gunzip (Unix) or ZIP (Windows), please consult with an experienced user of your system. Sorry, we cannot answer questions about basic Internet skills.

Unpacking the archive will produce a directory called "gd-2.0.33".

For Unix

./configure

NOTE: BY DEFAULT, THE LIBRARY IS INSTALLED IN /usr/local/lib and the include files are installed in /usr/local/include. IF YOU ARE UPGRADING, you may wish to use:

./configure --prefix=/usr

Rather than just ./configure, before typing make and make install.

If all goes well, this will create a Makefile. If all does not go well -- for instance, if neither the the JPEG nor the PNG and ZLIB libraries are found -- you will need to install those libraries, then come back and run configure again.

If necessary, make changes to the resulting Makefile. Then, type "make". If there are no errors, follow this with "make install". Because gd 2.0 and above installs as a shared library, it is necessary to install the library properly before running gd-based programs.

If you get errors, type ./configure --help for more information about the available options. In the unlikely event that the GNU autoconf-produced configure script does not work well for you, you may wish to try configure.pl, a simple Perl script with similar but less complete capabilities. If all else fails, try renaming makefile.sample to Makefile. However, ./configure is almost always your best bet.

For Windows

Use the DLL version! See the paragraph at the beginning of this sectino. If you really want to compile it yourself for some strange reason, read on.

Create a project using your favorite programming environment. Copy all of the gd files to the project directory. Add gd.c to your project. Add other source files as appropriate. Learning the basic skills of creating projects with your chosen C environment is up to you. Alternatively, use the free mingw32 or cygwin tools, which may prove to be compatible with the provided configure script.

If you wish to test the library, type "make test" AFTER you have successfully executed "make install". This will build several test programs, including "gddemo". (Not all of these programs are expected to print completely successful messages, depending on the nature of the image formats with which some of the tests are tried; for instance, WBMP is a black and white format, so loss of color information is expected there.) Run gddemo to see some of the capabilities of gd. Run gdtestft to play with the freetype support, if you have built gd with it and have access to truetype fonts.

gddemo should execute without incident, creating the file demoout.png. (Note there is also a file named demoin.png, which is provided in the package as part of the demonstration.)

Display demoout.png in your PNG viewer. The image should be 128x128 pixels and should contain an image of the space shuttle with quite a lot of graphical elements drawn on top of it.

(If you are missing the demoin.png file, the other items should appear anyway.)

Look at demoin.png to see the original space shuttle image which was scaled and copied into the output image.

gd basics: using gd in your program

-lgd -lpng -lz -ljpeg -lfreetype -lm

If you want to use the provided simple fonts, include gdfontt.h, gdfonts.h, gdfontmb.h, gdfontl.h and/or gdfontg.h. For more impressive results, install FreeType 2.x and use the gdImageStringFT function. If you are not using the provided Makefile and/or a library-based approach, be sure to include the source modules as well in your project. (They may be too large for 16-bit memory models, that is, 16-bit DOS and Windows.)

Here is a short example program. (For a more advanced example, see gddemo.c, included in the distribution. gddemo.c is NOT the same program; it demonstrates additional features!)

/* Bring in gd library functions */
#include "gd.h"

/* Bring in standard I/O so we can output the PNG to a file */
#include <stdio.h>

int main() {
  /* Declare the image */
  gdImagePtr im;
  /* Declare output files */
  FILE *pngout, *jpegout;
  /* Declare color indexes */
  int black;
  int white;

  /* Allocate the image: 64 pixels across by 64 pixels tall */
  im = gdImageCreate(64, 64);

  /* Allocate the color black (red, green and blue all minimum).
    Since this is the first color in a new image, it will
    be the background color. */
  black = gdImageColorAllocate(im, 0, 0, 0);  

  /* Allocate the color white (red, green and blue all maximum). */
  white = gdImageColorAllocate(im, 255, 255, 255);  
  
  /* Draw a line from the upper left to the lower right,
    using white color index. */
  gdImageLine(im, 0, 0, 63, 63, white);  

  /* Open a file for writing. "wb" means "write binary", important
    under MSDOS, harmless under Unix. */
  pngout = fopen("test.png", "wb");

  /* Do the same for a JPEG-format file. */
  jpegout = fopen("test.jpg", "wb");

  /* Output the image to the disk file in PNG format. */
  gdImagePng(im, pngout);

  /* Output the same image in JPEG format, using the default
    JPEG quality setting. */
  gdImageJpeg(im, jpegout, -1);

  /* Close the files. */
  fclose(pngout);
  fclose(jpegout);

  /* Destroy the image in memory. */
  gdImageDestroy(im);
}

The above example program should give you an idea of how the package works. gd provides many additional functions, which are listed in the following reference chapters, complete with code snippets demonstrating each. There is also an alphabetical index.

Webpng: a more powerful gd example

webpng.c is provided in the distribution. Unix users can simply type "make webpng" to compile the program. Type "webpng" with no arguments to see the available options.

Function and type reference

• Types
• Image creation, destruction, loading and saving
• Drawing, styling, brushing, tiling and filling functions
• Query functions (not color-related)
• Font and text-handling functions
• Color handling functions
• Copying, resizing, rotating, deformation and filter functions
• Miscellaneous Functions
• Constants

Types

gdImage(TYPE)

The data structure in which gd stores images. gdImageCreate, gdImageCreateTrueColor and the various image file-loading functions return a pointer to this type, and the other functions expect to receive a pointer to this type as their first argument. It is reasonably safe to examine any of the members of this structure. It is also reasonably safe to modify individual pixels within the pixels or tpixels arrays. If the trueColor flag is set, the tpixels array is valid; otherwise the pixels array is valid.

The colorsTotal, red, green, blue, alpha and open arrays manage the palette. They are valid only when the trueColor flag is not set. The transparent value contains the palette index of the first transparent color as read-only information for backwards compatibility; gd 2.0 stores this information in the alpha array so that variable transparency can be supported for each palette entry. However, for truecolor images, transparent represents a single RGB color which is always 100% transparent, and this feature is generally supported by browsers which do not support full alpha channels.

typedef struct {
  /* Palette-based image pixels */
  unsigned char ** pixels;
  int sx;
  int sy;
  /* These are valid in palette images only. See also
  /* 'alpha', which appears later in the structure to
    preserve binary backwards compatibility */
  int colorsTotal;
  int red[gdMaxColors];
  int green[gdMaxColors];
  int blue[gdMaxColors]; 
  int open[gdMaxColors];
  /* For backwards compatibility, this is set to the
    first palette entry with 100% transparency,
    and is also set and reset by the 
    gdImageColorTransparent function. Newer
    applications can allocate palette entries
    with any desired level of transparency; however,
    bear in mind that many viewers, notably
    many web browsers, fail to implement
    full alpha channel for PNG and provide
    support for full opacity or transparency only. */
  int transparent;
  int *polyInts;
  int polyAllocated;
  struct gdImageStruct *brush;
  struct gdImageStruct *tile;  
  int brushColorMap[gdMaxColors];
  int tileColorMap[gdMaxColors];
  int styleLength;
  int stylePos;
  int *style;
  int interlace;
  /* New in 2.0: alpha channel for palettes. Note that only
    Macintosh Internet Explorer and (possibly) Netscape 6
    really support multiple levels of transparency in
    palettes, to my knowledge, as of 2/15/01. Most
    common browsers will display 100% opaque and
    100% transparent correctly, and do something 
    unpredictable and/or undesirable for levels
    in between. TBB */
  int alpha[gdMaxColors]; 
  /* Truecolor flag and pixels. New 2.0 fields appear here at the
    end to minimize breakage of existing object code. */
  int trueColor;
  int ** tpixels;
  /* Should alpha channel be copied, or applied, each time a
    pixel is drawn? This applies to truecolor images only.
    No attempt is made to alpha-blend in palette images,
    even if semitransparent palette entries exist. 
    To do that, build your image as a truecolor image,
    then quantize down to 8 bits. */
  int alphaBlendingFlag;
  /* Should the alpha channel of the image be saved? This affects
    PNG at the moment; other future formats may also
    have that capability. JPEG doesn't. */
  int saveAlphaFlag;
} gdImage;

The order of the structure members may appear confusing, but was chosen deliberately to increase backwards compatibility with existing gd 1.x-based binary code that references particular structure members.

gdImagePtr (TYPE)

A pointer to an image structure. gdImageCreate returns this type, and the other functions expect it as the first argument.

gdIOCtx (TYPE)

Most of the gd functions that read and write files, such as gdImagePng and , also have variants that accept a gdIOCtx structure; see gdImagePngCtx and gdImageCreateFromJpegCtx. Those who wish to provide their own custom routines to read and write images can populate a gdIOCtx structure with functions of their own devising to to read and write data. For image reading, the only mandatory functions are getC and getBuf, which must return the number of characters actually read, or a negative value on error or EOF. These functions must read the number of characters requested unless at the end of the file. For image writing, the only mandatory functions are putC and putBuf, which return the number of characters written; these functions must write the number of characters requested except in the event of an error. The seek and tell functions are only required in conjunction with the gd2 file format, which supports quick loading of partial images. The gd_free function will not be invoked when calling the standard Ctx functions; it is an implementation convenience when adding new data types to gd. For examples, see gd_png.c, gd_gd2locate ompression and decompression routines slightly, because horizontally adjacent pixels are now next to each other in memory. This should not affect properly written gd applications, but applications that directly manipulate the pixels array will require changes.

What else do I need to use gd?

To use gd, you will need an ANSI C compiler. All popular Windows 95 and NT C compilers are ANSI C compliant. Any full-ANSI-standard C compiler should be adequate. The cc compiler released with SunOS 4.1.3 is not an ANSI C compiler. Most Unix users who do not already have gcc should get it. gcc is free, ANSI compliant and a de facto industry standard. Ask your ISP why it is missing.

As of version 1.6, you also need the zlib compression library, and the libpng library. As of version 1.6.2, you can draw text using antialiased TrueType fonts if you also have the libttf library installed, but this is not mandatory. zlib is available for a variety of platforms from the zlib web site. libpng is available for a variety of platforms from the PNG web site.

You will also want a PNG viewer, if you do not already have one for your system, since you will need a good way to check the results of your work. Netscape 4.04 and higher, and Microsoft Internet Explorer 4.0 or higher, both support PNG. Not every PNG-compatible viewer supports alpha channel transparency, which is why gd 2.0.2 and above do alpha blending in the library by default; it is possible to turn on the saving of alpha channel information to the file instead.

How do I get gd?

Binaries (DLL for Windows programmers):

• .ZIP File of DLL, Headers, Et Cetera

Source Code:

• Gzipped Tar File (Unix)
• .ZIP File of SOURCE CODE (Windows)

How do I build gd?

Win32 DLL users: if you are using MSVC, use the provided batch file makemsvcimport.bat to make a bgd.lib import library corresponding to the provided bgd.dll. Copy bgd.dll to your application directory, or to your Windows sytem directory. In the settings of your MSVC project, you MUST choose the "multithreaded DLL" library option under "code generation." mingw32 and cygwin users can simply link with the provided libbgd.a stub library in order to use the DLL.

In order to build gd, you must first unpack the archive you have downloaded. If you are not familiar with tar and gunzip (Unix) or ZIP (Windows), please consult with an experienced user of your system. Sorry, we cannot answer questions about basic Internet skills.

Unpacking the archive will produce a directory called "gd-2.0.33".

For Unix

./configure

NOTE: BY DEFAULT, THE LIBRARY IS INSTALLED IN /usr/local/lib and the include files are installed in /usr/local/include. IF YOU ARE UPGRADING, you may wish to use:

./configure --prefix=/usr

Rather than just ./configure, before typing make and make install.

If all goes well, this will create a Makefile. If all does not go well -- for instance, if neither the the JPEG nor the PNG and ZLIB libraries are found -- you will need to install those libraries, then come back and run configure again.

If necessary, make changes to the resulting Makefile. Then, type "make". If there are no errors, follow this with "make install". Because gd 2.0 and above installs as a shared library, it is necessary to install the library properly before running gd-based programs.

If you get errors, type ./configure --help for more information about the available options. In the unlikely event that the GNU autoconf-produced configure script does not work well for you, you may wish to try configure.pl, a simple Perl script with similar but less complete capabilities. If all else fails, try renaming makefile.sample to Makefile. However, ./configure is almost always your best bet.

For Windows

Use the DLL version! See the paragraph at the beginning of this sectino. If you really want to compile it yourself for some strange reason, read on.

Create a project using your favorite programming environment. Copy all of the gd files to the project directory. Add gd.c to your project. Add other source files as appropriate. Learning the basic skills of creating projects with your chosen C environment is up to you. Alternatively, use the free mingw32 or cygwin tools, which may prove to be compatible with the provided configure script.

If you wish to test the library, type "make test" AFTER you have successfully executed "make install". This will build several test programs, including "gddemo". (Not all of these programs are expected to print completely successful messages, depending on the nature of the image formats with which some of the tests are tried; for instance, WBMP is a black and white format, so loss of color information is expected there.) Run gddemo to see some of the capabilities of gd. Run gdtestft to play with the freetype support, if you have built gd with it and have access to truetype fonts.

gddemo should execute without incident, creating the file demoout.png. (Note there is also a file named demoin.png, which is provided in the package as part of the demonstration.)

Display demoout.png in your PNG viewer. The image should be 128x128 pixels and should contain an image of the space shuttle with quite a lot of graphical elements drawn on top of it.

(If you are missing the demoin.png file, the other items should appear anyway.)

Look at demoin.png to see the original space shuttle image which was scaled and copied into the output image.

gd basics: using gd in your program

-lgd -lpng -lz -ljpeg -lfreetype -lm

If you want to use the provided simple fonts, include gdfontt.h, gdfonts.h, gdfontmb.h, gdfontl.h and/or gdfontg.h. For more impressive results, install FreeType 2.x and use the gdImageStringFT function. If you are not using the provided Makefile and/or a library-based approach, be sure to include the source modules as well in your project. (They may be too large for 16-bit memory models, that is, 16-bit DOS and Windows.)

Here is a short example program. (For a more advanced example, see gddemo.c, included in the distribution. gddemo.c is NOT the same program; it demonstrates additional features!)

/* Bring in gd library functions */
#include "gd.h"

/* Bring in standard I/O so we can output the PNG to a file */
#include <stdio.h>

int main() {
  /* Declare the image */
  gdImagePtr im;
  /* Declare output files */
  FILE *pngout, *jpegout;
  /* Declare color indexes */
  int black;
  int white;

  /* Allocate the image: 64 pixels across by 64 pixels tall */
  im = gdImageCreate(64, 64);

  /* Allocate the color black (red, green and blue all minimum).
    Since this is the first color in a new image, it will
    be the background color. */
  black = gdImageColorAllocate(im, 0, 0, 0);  

  /* Allocate the color white (red, green and blue all maximum). */
  white = gdImageColorAllocate(im, 255, 255, 255);  
  
  /* Draw a line from the upper left to the lower right,
    using white color index. */
  gdImageLine(im, 0, 0, 63, 63, white);  

  /* Open a file for writing. "wb" means "write binary", important
    under MSDOS, harmless under Unix. */
  pngout = fopen("test.png", "wb");

  /* Do the same for a JPEG-format file. */
  jpegout = fopen("test.jpg", "wb");

  /* Output the image to the disk file in PNG format. */
  gdImagePng(im, pngout);

  /* Output the same image in JPEG format, using the default
    JPEG quality setting. */
  gdImageJpeg(im, jpegout, -1);

  /* Close the files. */
  fclose(pngout);
  fclose(jpegout);

  /* Destroy the image in memory. */
  gdImageDestroy(im);
}

The above example program should give you an idea of how the package works. gd provides many additional functions, which are listed in the following reference chapters, complete with code snippets demonstrating each. There is also an alphabetical index.

Webpng: a more powerful gd example

webpng.c is provided in the distribution. Unix users can simply type "make webpng" to compile the program. Type "webpng" with no arguments to see the available options.

Function and type reference

• Types
• Image creation, destruction, loading and saving
• Drawing, styling, brushing, tiling and filling functions
• Query functions (not color-related)
• Font and text-handling functions
• Color handling functions
• Copying, resizing, rotating, deformation and filter functions
• Miscellaneous Functions
• Constants

Types

gdImage(TYPE)

The data structure in which gd stores images. gdImageCreate, gdImageCreateTrueColor and the various image file-loading functions return a pointer to this type, and the other functions expect to receive a pointer to this type as their first argument. It is reasonably safe to examine any of the members of this structure. It is also reasonably safe to modify individual pixels within the pixels or tpixels arrays. If the trueColor flag is set, the tpixels array is valid; otherwise the pixels array is valid.

The colorsTotal, red, green, blue, alpha and open arrays manage the palette. They are valid only when the trueColor flag is not set. The transparent value contains the palette index of the first transparent color as read-only information for backwards compatibility; gd 2.0 stores this information in the alpha array so that variable transparency can be supported for each palette entry. However, for truecolor images, transparent represents a single RGB color which is always 100% transparent, and this feature is generally supported by browsers which do not support full alpha channels.

typedef struct {
  /* Palette-based image pixels */
  unsigned char ** pixels;
  int sx;
  int sy;
  /* These are valid in palette images only. See also
  /* 'alpha', which appears later in the structure to
    preserve binary backwards compatibility */
  int colorsTotal;
  int red[gdMaxColors];
  int green[gdMaxColors];
  int blue[gdMaxColors]; 
  int open[gdMaxColors];
  /* For backwards compatibility, this is set to the
    first palette entry with 100% transparency,
    and is also set and reset by the 
    gdImageColorTransparent function. Newer
    applications can allocate palette entries
    with any desired level of transparency; however,
    bear in mind that many viewers, notably
    many web browsers, fail to implement
    full alpha channel for PNG and provide
    support for full opacity or transparency only. */
  int transparent;
  int *polyInts;
  int polyAllocated;
  struct gdImageStruct *brush;
  struct gdImageStruct *tile;  
  int brushColorMap[gdMaxColors];
  int tileColorMap[gdMaxColors];
  int styleLength;
  int stylePos;
  int *style;
  int interlace;
  /* New in 2.0: alpha channel for palettes. Note that only
    Macintosh Internet Explorer and (possibly) Netscape 6
    really support multiple levels of transparency in
    palettes, to my knowledge, as of 2/15/01. Most
    common browsers will display 100% opaque and
    100% transparent correctly, and do something 
    unpredictable and/or undesirable for levels
    in between. TBB */
  int alpha[gdMaxColors]; 
  /* Truecolor flag and pixels. New 2.0 fields appear here at the
    end to minimize breakage of existing object code. */
  int trueColor;
  int ** tpixels;
  /* Should alpha channel be copied, or applied, each time a
    pixel is drawn? This applies to truecolor images only.
    No attempt is made to alpha-blend in palette images,
    even if semitransparent palette entries exist. 
    To do that, build your image as a truecolor image,
    then quantize down to 8 bits. */
  int alphaBlendingFlag;
  /* Should the alpha channel of the image be saved? This affects
    PNG at the moment; other future formats may also
    have that capability. JPEG doesn't. */
  int saveAlphaFlag;
} gdImage;

The order of the structure members may appear confusing, but was chosen deliberately to increase backwards compatibility with existing gd 1.x-based binary code that references particular structure members.

gdImagePtr (TYPE)

A pointer to an image structure. gdImageCreate returns this type, and the other functions expect it as the first argument.

gdIOCtx (TYPE)

Most of the gd functions that read and write files, such as gdImagePng and , also have variants that accept a gdIOCtx structure; see gdImagePngCtx and gdImageCreateFromJpegCtx. Those who wish to provide their own custom routines to read and write images can populate a gdIOCtx structure with functions of their own devising to to read and write data. For image reading, the only mandatory functions are getC and getBuf, which must return the number of characters actually read, or a negative value on error or EOF. These functions must read the number of characters requested unless at the end of the file. For image writing, the only mandatory functions are putC and putBuf, which return the number of characters written; these functions must write the number of characters requested except in the event of an error. The seek and tell functions are only required in conjunction with the gd2 file format, which supports quick loading of partial images. The gd_free function will not be invoked when calling the standard Ctx functions; it is an implementation convenience when adding new data types to gd. For examples, see gd_png.c, gd_gd2locate ompression and decompression routines slightly, because horizontally adjacent pixels are now next to each other in memory. This should not affect properly written gd applications, but applications that directly manipulate the pixels array will require changes.

What else do I need to use gd?

To use gd, you will need an ANSI C compiler. All popular Windows 95 and NT C compilers are ANSI C compliant. Any full-ANSI-standard C compiler should be adequate. The cc compiler released with SunOS 4.1.3 is not an ANSI C compiler. Most Unix users who do not already have gcc should get it. gcc is free, ANSI compliant and a de facto industry standard. Ask your ISP why it is missing.

As of version 1.6, you also need the zlib compression library, and the libpng library. As of version 1.6.2, you can draw text using antialiased TrueType fonts if you also have the libttf library installed, but this is not mandatory. zlib is available for a variety of platforms from the zlib web site. libpng is available for a variety of platforms from the PNG web site.

You will also want a PNG viewer, if you do not already have one for your system, since you will need a good way to check the results of your work. Netscape 4.04 and higher, and Microsoft Internet Explorer 4.0 or higher, both support PNG. Not every PNG-compatible viewer supports alpha channel transparency, which is why gd 2.0.2 and above do alpha blending in the library by default; it is possible to turn on the saving of alpha channel information to the file instead.

How do I get gd?

Binaries (DLL for Windows programmers):

• .ZIP File of DLL, Headers, Et Cetera

Source Code:

• Gzipped Tar File (Unix)
• .ZIP File of SOURCE CODE (Windows)

How do I build gd?

Win32 DLL users: if you are using MSVC, use the provided batch file makemsvcimport.bat to make a bgd.lib import library corresponding to the provided bgd.dll. Copy bgd.dll to your application directory, or to your Windows sytem directory. In the settings of your MSVC project, you MUST choose the "multithreaded DLL" library option under "code generation." mingw32 and cygwin users can simply link with the provided libbgd.a stub library in order to use the DLL.

In order to build gd, you must first unpack the archive you have downloaded. If you are not familiar with tar and gunzip (Unix) or ZIP (Windows), please consult with an experienced user of your system. Sorry, we cannot answer questions about basic Internet skills.

Unpacking the archive will produce a directory called "gd-2.0.33".

For Unix

./configure

NOTE: BY DEFAULT, THE LIBRARY IS INSTALLED IN /usr/local/lib and the include files are installed in /usr/local/include. IF YOU ARE UPGRADING, you may wish to use:

./configure --prefix=/usr

Rather than just ./configure, before typing make and make install.

If all goes well, this will create a Makefile. If all does not go well -- for instance, if neither the the JPEG nor the PNG and ZLIB libraries are found -- you will need to install those libraries, then come back and run configure again.

If necessary, make changes to the resulting Makefile. Then, type "make". If there are no errors, follow this with "make install". Because gd 2.0 and above installs as a shared library, it is necessary to install the library properly before running gd-based programs.

If you get errors, type ./configure --help for more information about the available options. In the unlikely event that the GNU autoconf-produced configure script does not work well for you, you may wish to try configure.pl, a simple Perl script with similar but less complete capabilities. If all else fails, try renaming makefile.sample to Makefile. However, ./configure is almost always your best bet.

For Windows

Use the DLL version! See the paragraph at the beginning of this sectino. If you really want to compile it yourself for some strange reason, read on.

Create a project using your favorite programming environment. Copy all of the gd files to the project directory. Add gd.c to your project. Add other source files as appropriate. Learning the basic skills of creating projects with your chosen C environment is up to you. Alternatively, use the free mingw32 or cygwin tools, which may prove to be compatible with the provided configure script.

If you wish to test the library, type "make test" AFTER you have successfully executed "make install". This will build several test programs, including "gddemo". (Not all of these programs are expected to print completely successful messages, depending on the nature of the image formats with which some of the tests are tried; for instance, WBMP is a black and white format, so loss of color information is expected there.) Run gddemo to see some of the capabilities of gd. Run gdtestft to play with the freetype support, if you have built gd with it and have access to truetype fonts.

gddemo should execute without incident, creating the file demoout.png. (Note there is also a file named demoin.png, which is provided in the package as part of the demonstration.)

Display demoout.png in your PNG viewer. The image should be 128x128 pixels and should contain an image of the space shuttle with quite a lot of graphical elements drawn on top of it.

(If you are missing the demoin.png file, the other items should appear anyway.)

Look at demoin.png to see the original space shuttle image which was scaled and copied into the output image.

gd basics: using gd in your program

-lgd -lpng -lz -ljpeg -lfreetype -lm

If you want to use the provided simple fonts, include gdfontt.h, gdfonts.h, gdfontmb.h, gdfontl.h and/or gdfontg.h. For more impressive results, install FreeType 2.x and use the gdImageStringFT function. If you are not using the provided Makefile and/or a library-based approach, be sure to include the source modules as well in your project. (They may be too large for 16-bit memory models, that is, 16-bit DOS and Windows.)

Here is a short example program. (For a more advanced example, see gddemo.c, included in the distribution. gddemo.c is NOT the same program; it demonstrates additional features!)

/* Bring in gd library functions */
#include "gd.h"

/* Bring in standard I/O so we can output the PNG to a file */
#include <stdio.h>

int main() {
  /* Declare the image */
  gdImagePtr im;
  /* Declare output files */
  FILE *pngout, *jpegout;
  /* Declare color indexes */
  int black;
  int white;

  /* Allocate the image: 64 pixels across by 64 pixels tall */
  im = gdImageCreate(64, 64);

  /* Allocate the color black (red, green and blue all minimum).
    Since this is the first color in a new image, it will
    be the background color. */
  black = gdImageColorAllocate(im, 0, 0, 0);  

  /* Allocate the color white (red, green and blue all maximum). */
  white = gdImageColorAllocate(im, 255, 255, 255);  
  
  /* Draw a line from the upper left to the lower right,
    using white color index. */
  gdImageLine(im, 0, 0, 63, 63, white);  

  /* Open a file for writing. "wb" means "write binary", important
    under MSDOS, harmless under Unix. */
  pngout = fopen("test.png", "wb");

  /* Do the same for a JPEG-format file. */
  jpegout = fopen("test.jpg", "wb");

  /* Output the image to the disk file in PNG format. */
  gdImagePng(im, pngout);

  /* Output the same image in JPEG format, using the default
    JPEG quality setting. */
  gdImageJpeg(im, jpegout, -1);

  /* Close the files. */
  fclose(pngout);
  fclose(jpegout);

  /* Destroy the image in memory. */
  gdImageDestroy(im);
}

The above example program should give you an idea of how the package works. gd provides many additional functions, which are listed in the following reference chapters, complete with code snippets demonstrating each. There is also an alphabetical index.

Webpng: a more powerful gd example

webpng.c is provided in the distribution. Unix users can simply type "make webpng" to compile the program. Type "webpng" with no arguments to see the available options.

Function and type reference

• Types
• Image creation, destruction, loading and saving
• Drawing, styling, brushing, tiling and filling functions
• Query functions (not color-related)
• Font and text-handling functions
• Color handling functions
• Copying, resizing, rotating, deformation and filter functions
• Miscellaneous Functions
• Constants

Types

gdImage(TYPE)

The data structure in which gd stores images. gdImageCreate, gdImageCreateTrueColor and the various image file-loading functions return a pointer to this type, and the other functions expect to receive a pointer to this type as their first argument. It is reasonably safe to examine any of the members of this structure. It is also reasonably safe to modify individual pixels within the pixels or tpixels arrays. If the trueColor flag is set, the tpixels array is valid; otherwise the pixels array is valid.

The colorsTotal, red, green, blue, alpha and open arrays manage the palette. They are valid only when the trueColor flag is not set. The transparent value contains the palette index of the first transparent color as read-only information for backwards compatibility; gd 2.0 stores this information in the alpha array so that variable transparency can be supported for each palette entry. However, for truecolor images, transparent represents a single RGB color which is always 100% transparent, and this feature is generally supported by browsers which do not support full alpha channels.

typedef struct {
  /* Palette-based image pixels */
  unsigned char ** pixels;
  int sx;
  int sy;
  /* These are valid in palette images only. See also
  /* 'alpha', which appears later in the structure to
    preserve binary backwards compatibility */
  int colorsTotal;
  int red[gdMaxColors];
  int green[gdMaxColors];
  int blue[gdMaxColors]; 
  int open[gdMaxColors];
  /* For backwards compatibility, this is set to the
    first palette entry with 100% transparency,
    and is also set and reset by the 
    gdImageColorTransparent function. Newer
    applications can allocate palette entries
    with any desired level of transparency; however,
    bear in mind that many viewers, notably
    many web browsers, fail to implement
    full alpha channel for PNG and provide
    support for full opacity or transparency only. */
  int transparent;
  int *polyInts;
  int polyAllocated;
  struct gdImageStruct *brush;
  struct gdImageStruct *tile;  
  int brushColorMap[gdMaxColors];
  int tileColorMap[gdMaxColors];
  int styleLength;
  int stylePos;
  int *style;
  int interlace;
  /* New in 2.0: alpha channel for palettes. Note that only
    Macintosh Internet Explorer and (possibly) Netscape 6
    really support multiple levels of transparency in
    palettes, to my knowledge, as of 2/15/01. Most
    common browsers will display 100% opaque and
    100% transparent correctly, and do something 
    unpredictable and/or undesirable for levels
    in between. TBB */
  int alpha[gdMaxColors]; 
  /* Truecolor flag and pixels. New 2.0 fields appear here at the
    end to minimize breakage of existing object code. */
  int trueColor;
  int ** tpixels;
  /* Should alpha channel be copied, or applied, each time a
    pixel is drawn? This applies to truecolor images only.
    No attempt is made to alpha-blend in palette images,
    even if semitransparent palette entries exist. 
    To do that, build your image as a truecolor image,
    then quantize down to 8 bits. */
  int alphaBlendingFlag;
  /* Should the alpha channel of the image be saved? This affects
    PNG at the moment; other future formats may also
    have that capability. JPEG doesn't. */
  int saveAlphaFlag;
} gdImage;

The order of the structure members may appear confusing, but was chosen deliberately to increase backwards compatibility with existing gd 1.x-based binary code that references particular structure members.

gdImagePtr (TYPE)

A pointer to an image structure. gdImageCreate returns this type, and the other functions expect it as the first argument.

gdIOCtx (TYPE)

Most of the gd functions that read and write files, such as gdImagePng and , also have variants that accept a gdIOCtx structure; see gdImagePngCtx and gdImageCreateFromJpegCtx. Those who wish to provide their own custom routines to read and write images can populate a gdIOCtx structure with functions of their own devising to to read and write data. For image reading, the only mandatory functions are getC and getBuf, which must return the number of characters actually read, or a negative value on error or EOF. These functions must read the number of characters requested unless at the end of the file. For image writing, the only mandatory functions are putC and putBuf, which return the number of characters written; these functions must write the number of characters requested except in the event of an error. The seek and tell functions are only required in conjunction with the gd2 file format, which supports quick loading of partial images. The gd_free function will not be invoked when calling the standard Ctx functions; it is an implementation convenience when adding new data types to gd. For examples, see gd_png.c, gd_gd2locate ompression and decompression routines slightly, because horizontally adjacent pixels are now next to each other in memory. This should not affect properly written gd applications, but applications that directly manipulate the pixels array will require changes.

What else do I need to use gd?

To use gd, you will need an ANSI C compiler. All popular Windows 95 and NT C compilers are ANSI C compliant. Any full-ANSI-standard C compiler should be adequate. The cc compiler released with SunOS 4.1.3 is not an ANSI C compiler. Most Unix users who do not already have gcc should get it. gcc is free, ANSI compliant and a de facto industry standard. Ask your ISP why it is missing.

As of version 1.6, you also need the zlib compression library, and the libpng library. As of version 1.6.2, you can draw text using antialiased TrueType fonts if you also have the libttf library installed, but this is not mandatory. zlib is available for a variety of platforms from the zlib web site. libpng is available for a variety of platforms from the PNG web site.

You will also want a PNG viewer, if you do not already have one for your system, since you will need a good way to check the results of your work. Netscape 4.04 and higher, and Microsoft Internet Explorer 4.0 or higher, both support PNG. Not every PNG-compatible viewer supports alpha channel transparency, which is why gd 2.0.2 and above do alpha blending in the library by default; it is possible to turn on the saving of alpha channel information to the file instead.

How do I get gd?

Binaries (DLL for Windows programmers):

• .ZIP File of DLL, Headers, Et Cetera

Source Code:

• Gzipped Tar File (Unix)
• .ZIP File of SOURCE CODE (Windows)

How do I build gd?

Win32 DLL users: if you are using MSVC, use the provided batch file makemsvcimport.bat to make a bgd.lib import library corresponding to the provided bgd.dll. Copy bgd.dll to your application directory, or to your Windows sytem directory. In the settings of your MSVC project, you MUST choose the "multithreaded DLL" library option under "code generation." mingw32 and cygwin users can simply link with the provided libbgd.a stub library in order to use the DLL.

In order to build gd, you must first unpack the archive you have downloaded. If you are not familiar with tar and gunzip (Unix) or ZIP (Windows), please consult with an experienced user of your system. Sorry, we cannot answer questions about basic Internet skills.

Unpacking the archive will produce a directory called "gd-2.0.33".

For Unix

./configure

NOTE: BY DEFAULT, THE LIBRARY IS INSTALLED IN /usr/local/lib and the include files are installed in /usr/local/include. IF YOU ARE UPGRADING, you may wish to use:

./configure --prefix=/usr

Rather than just ./configure, before typing make and make install.

If all goes well, this will create a Makefile. If all does not go well -- for instance, if neither the the JPEG nor the PNG and ZLIB libraries are found -- you will need to install those libraries, then come back and run configure again.

If necessary, make changes to the resulting Makefile. Then, type "make". If there are no errors, follow this with "make install". Because gd 2.0 and above installs as a shared library, it is necessary to install the library properly before running gd-based programs.

If you get errors, type ./configure --help for more information about the available options. In the unlikely event that the GNU autoconf-produced configure script does not work well for you, you may wish to try configure.pl, a simple Perl script with similar but less complete capabilities. If all else fails, try renaming makefile.sample to Makefile. However, ./configure is almost always your best bet.

For Windows

Use the DLL version! See the paragraph at the beginning of this sectino. If you really want to compile it yourself for some strange reason, read on.

Create a project using your favorite programming environment. Copy all of the gd files to the project directory. Add gd.c to your project. Add other source files as appropriate. Learning the basic skills of creating projects with your chosen C environment is up to you. Alternatively, use the free mingw32 or cygwin tools, which may prove to be compatible with the provided configure script.

If you wish to test the library, type "make test" AFTER you have successfully executed "make install". This will build several test programs, including "gddemo". (Not all of these programs are expected to print completely successful messages, depending on the nature of the image formats with which some of the tests are tried; for instance, WBMP is a black and white format, so loss of color information is expected there.) Run gddemo to see some of the capabilities of gd. Run gdtestft to play with the freetype support, if you have built gd with it and have access to truetype fonts.

gddemo should execute without incident, creating the file demoout.png. (Note there is also a file named demoin.png, which is provided in the package as part of the demonstration.)

Display demoout.png in your PNG viewer. The image should be 128x128 pixels and should contain an image of the space shuttle with quite a lot of graphical elements drawn on top of it.

(If you are missing the demoin.png file, the other items should appear anyway.)

Look at demoin.png to see the original space shuttle image which was scaled and copied into the output image.

gd basics: using gd in your program

-lgd -lpng -lz -ljpeg -lfreetype -lm

If you want to use the provided simple fonts, include gdfontt.h, gdfonts.h, gdfontmb.h, gdfontl.h and/or gdfontg.h. For more impressive results, install FreeType 2.x and use the gdImageStringFT function. If you are not using the provided Makefile and/or a library-based approach, be sure to include the source modules as well in your project. (They may be too large for 16-bit memory models, that is, 16-bit DOS and Windows.)

Here is a short example program. (For a more advanced example, see gddemo.c, included in the distribution. gddemo.c is NOT the same program; it demonstrates additional features!)

/* Bring in gd library functions */
#include "gd.h"

/* Bring in standard I/O so we can output the PNG to a file */
#include <stdio.h>

int main() {
  /* Declare the image */
  gdImagePtr im;
  /* Declare output files */
  FILE *pngout, *jpegout;
  /* Declare color indexes */
  int black;
  int white;

  /* Allocate the image: 64 pixels across by 64 pixels tall */
  im = gdImageCreate(64, 64);

  /* Allocate the color black (red, green and blue all minimum).
    Since this is the first color in a new image, it will
    be the background color. */
  black = gdImageColorAllocate(im, 0, 0, 0);  

  /* Allocate the color white (red, green and blue all maximum). */
  white = gdImageColorAllocate(im, 255, 255, 255);  
  
  /* Draw a line from the upper left to the lower right,
    using white color index. */
  gdImageLine(im, 0, 0, 63, 63, white);  

  /* Open a file for writing. "wb" means "write binary", important
    under MSDOS, harmless under Unix. */
  pngout = fopen("test.png", "wb");

  /* Do the same for a JPEG-format file. */
  jpegout = fopen("test.jpg", "wb");

  /* Output the image to the disk file in PNG format. */
  gdImagePng(im, pngout);

  /* Output the same image in JPEG format, using the default
    JPEG quality setting. */
  gdImageJpeg(im, jpegout, -1);

  /* Close the files. */
  fclose(pngout);
  fclose(jpegout);

  /* Destroy the image in memory. */
  gdImageDestroy(im);
}

The above example program should give you an idea of how the package works. gd provides many additional functions, which are listed in the following reference chapters, complete with code snippets demonstrating each. There is also an alphabetical index.

Webpng: a more powerful gd example

webpng.c is provided in the distribution. Unix users can simply type "make webpng" to compile the program. Type "webpng" with no arguments to see the available options.

Function and type reference

• Types
• Image creation, destruction, loading and saving
• Drawing, styling, brushing, tiling and filling functions
• Query functions (not color-related)
• Font and text-handling functions
• Color handling functions
• Copying, resizing, rotating, deformation and filter functions
• Miscellaneous Functions
• Constants

Types

gdImage(TYPE)

The data structure in which gd stores images. gdImageCreate, gdImageCreateTrueColor and the various image file-loading functions return a pointer to this type, and the other functions expect to receive a pointer to this type as their first argument. It is reasonably safe to examine any of the members of this structure. It is also reasonably safe to modify individual pixels within the pixels or tpixels arrays. If the trueColor flag is set, the tpixels array is valid; otherwise the pixels array is valid.

The colorsTotal, red, green, blue, alpha and open arrays manage the palette. They are valid only when the trueColor flag is not set. The transparent value contains the palette index of the first transparent color as read-only information for backwards compatibility; gd 2.0 stores this information in the alpha array so that variable transparency can be supported for each palette entry. However, for truecolor images, transparent represents a single RGB color which is always 100% transparent, and this feature is generally supported by browsers which do not support full alpha channels.

typedef struct {
  /* Palette-based image pixels */
  unsigned char ** pixels;
  int sx;
  int sy;
  /* These are valid in palette images only. See also
  /* 'alpha', which appears later in the structure to
    preserve binary backwards compatibility */
  int colorsTotal;
  int red[gdMaxColors];
  int green[gdMaxColors];
  int blue[gdMaxColors]; 
  int open[gdMaxColors];
  /* For backwards compatibility, this is set to the
    first palette entry with 100% transparency,
    and is also set and reset by the 
    gdImageColorTransparent function. Newer
    applications can allocate palette entries
    with any desired level of transparency; however,
    bear in mind that many viewers, notably
    many web browsers, fail to implement
    full alpha channel for PNG and provide
    support for full opacity or transparency only. */
  int transparent;
  int *polyInts;
  int polyAllocated;
  struct gdImageStruct *brush;
  struct gdImageStruct *tile;  
  int brushColorMap[gdMaxColors];
  int tileColorMap[gdMaxColors];
  int styleLength;
  int stylePos;
  int *style;
  int interlace;
  /* New in 2.0: alpha channel for palettes. Note that only
    Macintosh Internet Explorer and (possibly) Netscape 6
    really support multiple levels of transparency in
    palettes, to my knowledge, as of 2/15/01. Most
    common browsers will display 100% opaque and
    100% transparent correctly, and do something 
    unpredictable and/or undesirable for levels
    in between. TBB */
  int alpha[gdMaxColors]; 
  /* Truecolor flag and pixels. New 2.0 fields appear here at the
    end to minimize breakage of existing object code. */
  int trueColor;
  int ** tpixels;
  /* Should alpha channel be copied, or applied, each time a
    pixel is drawn? This applies to truecolor images only.
    No attempt is made to alpha-blend in palette images,
    even if semitransparent palette entries exist. 
    To do that, build your image as a truecolor image,
    then quantize down to 8 bits. */
  int alphaBlendingFlag;
  /* Should the alpha channel of the image be saved? This affects
    PNG at the moment; other future formats may also
    have that capability. JPEG doesn't. */
  int saveAlphaFlag;
} gdImage;

The order of the structure members may appear confusing, but was chosen deliberately to increase backwards compatibility with existing gd 1.x-based binary code that references particular structure members.

gdImagePtr (TYPE)

A pointer to an image structure. gdImageCreate returns this type, and the other functions expect it as the first argument.

gdIOCtx (TYPE)

Most of the gd functions that read and write files, such as gdImagePng and , also have variants that accept a gdIOCtx structure; see gdImagePngCtx and gdImageCreateFromJpegCtx. Those who wish to provide their own custom routines to read and write images can populate a gdIOCtx structure with functions of their own devising to to read and write data. For image reading, the only mandatory functions are getC and getBuf, which must return the number of characters actually read, or a negative value on error or EOF. These functions must read the number of characters requested unless at the end of the file. For image writing, the only mandatory functions are putC and putBuf, which return the number of characters written; these functions must write the number of characters requested except in the event of an error. The seek and tell functions are only required in conjunction with the gd2 file format, which supports quick loading of partial images. The gd_free function will not be invoked when calling the standard Ctx functions; it is an implementation convenience when adding new data types to gd. For examples, see gd_png.c, gd_gd2locate ompression and decompression routines slightly, because horizontally adjacent pixels are now next to each other in memory. This should not affect properly written gd applications, but applications that directly manipulate the pixels array will require changes.

What else do I need to use gd?

To use gd, you will need an ANSI C compiler. All popular Windows 95 and NT C compilers are ANSI C compliant. Any full-ANSI-standard C compiler should be adequate. The cc compiler released with SunOS 4.1.3 is not an ANSI C compiler. Most Unix users who do not already have gcc should get it. gcc is free, ANSI compliant and a de facto industry standard. Ask your ISP why it is missing.

As of version 1.6, you also need the zlib compression library, and the libpng library. As of version 1.6.2, you can draw text using antialiased TrueType fonts if you also have the libttf library installed, but this is not mandatory. zlib is available for a variety of platforms from the zlib web site. libpng is available for a variety of platforms from the PNG web site.

You will also want a PNG viewer, if you do not already have one for your system, since you will need a good way to check the results of your work. Netscape 4.04 and higher, and Microsoft Internet Explorer 4.0 or higher, both support PNG. Not every PNG-compatible viewer supports alpha channel transparency, which is why gd 2.0.2 and above do alpha blending in the library by default; it is possible to turn on the saving of alpha channel information to the file instead.

How do I get gd?

Binaries (DLL for Windows programmers):

• .ZIP File of DLL, Headers, Et Cetera

Source Code:

• Gzipped Tar File (Unix)
• .ZIP File of SOURCE CODE (Windows)

How do I build gd?

Win32 DLL users: if you are using MSVC, use the provided batch file makemsvcimport.bat to make a bgd.lib import library corresponding to the provided bgd.dll. Copy bgd.dll to your application directory, or to your Windows sytem directory. In the settings of your MSVC project, you MUST choose the "multithreaded DLL" library option under "code generation." mingw32 and cygwin users can simply link with the provided libbgd.a stub library in order to use the DLL.

In order to build gd, you must first unpack the archive you have downloaded. If you are not familiar with tar and gunzip (Unix) or ZIP (Windows), please consult with an experienced user of your system. Sorry, we cannot answer questions about basic Internet skills.

Unpacking the archive will produce a directory called "gd-2.0.33".

For Unix

./configure

NOTE: BY DEFAULT, THE LIBRARY IS INSTALLED IN /usr/local/lib and the include files are installed in /usr/local/include. IF YOU ARE UPGRADING, you may wish to use:

./configure --prefix=/usr

Rather than just ./configure, before typing make and make install.

If all goes well, this will create a Makefile. If all does not go well -- for instance, if neither the the JPEG nor the PNG and ZLIB libraries are found -- you will need to install those libraries, then come back and run configure again.

If necessary, make changes to the resulting Makefile. Then, type "make". If there are no errors, follow this with "make install". Because gd 2.0 and above installs as a shared library, it is necessary to install the library properly before running gd-based programs.

If you get errors