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=/usrTo 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.33 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 whylibgd.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?
- Alphabetical quick index
Up to the Boutell.Com, Inc. Home Page
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 Thomas Boutell 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 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?
Not all of these tools are necessarily up to date and fully compatible
with 2.0.33.
PHP
A variant of gd 2.x is included in PHP 4.3.0. It is also possible to patch PHP 4.2.3 for use with gd 2.0.33; see the gd home page for a link to that information. It would be a Good Idea to merge all of the things that are better in mainstream gd and all of the things that are better in PHP gd at some point in the near future.Perl
gd can also be used from Perl, courtesy of Lincoln Stein's GD.pm library, which uses gd as the basis for a set of Perl 5.x classes. Highly recommended.OCaml
gd can be used from OCaml, thanks to Matt Gushee's GD4O project.Tcl
gd can be used from Tcl with John Ellson's Gdtclft dynamically loaded extension package.Pascal
Pascal enthusiasts should look into the freepascal project, a free Pascal compiler that includes gd support.REXX
A gd interface for the REXX language is available.Any Language
The "fly" interpreter performs gd operations specified in a text file. You can output the desired commands to a simple text file from whatever scripting language you prefer to use, then invoke the interpreter.
- fly, by Martin Gleeson
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.
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.
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.
2.0.29 did not compile correctly when freetype was not available. This has been corrected. Thanks to Alessandro Ranellucci.
- 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.
- 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.
- 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.
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 bymake 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
Otherconfigure
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.
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").
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."
Output dpi specification option added to the
gdFTStringExtra
structure, thanks to
Mark Shackelford. See gdImageStringFTEx.
- 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 ofgdFontLarge
, etc. is strongly deprecated for users ofbgd.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.
- 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 thegdNewDynamicCtx
function by provoding a way to specify that gd should never free or reallocate a particular block of memory. ThegdNewDynamicCtx
function and its relatives, although still exported for ABI compatibility, are now deprecated except for internal use, in favor ofgdImageCreateFromPngPtr
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 callsgdFontCacheShutdown
for backwards compatibility. This repairs build problems when compiling PHP against the latest gd. - Documentation improvements.
- Version 2.0.20 restores the
gdFreeFontCache
function, an undocumented function added in an earlier release which now simply callsgdFontCacheShutdown
for backwards compatibility. This repairs build problems when compiling PHP against the latest gd.
- Version 2.0.19 restored
extern
declarations for the gd font pointers inadvertently removed in 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.
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.
- 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.
- 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.
- 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.)
- 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.
- 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. Truecolorgd
files created with earlier releases in the 2.0 series must be written again. Thegd
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 thegd2
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.
- 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.
- 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.
- 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.
- 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.
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.
- 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.
- 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?
The following contributions from John Ellson:
- 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 toconfigure
works properly. - The
annotate
utility has been added. This is a very handy tool for adding freetype text to existing JPEGs. Aftermake install
, typeannotate -h
for more information. Thanks to Joel Dubiner.
- 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.
- 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.
- 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 thetrueColor
flag of thegdImage
structure, and refer to thetpixels
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.
- 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.
- 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
- 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 websites
- 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
- 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
Support for reading and writing JPEG-format images is courtesy of Doug Becker and the Independent JPEG Group / Thomas G. Lane. You can get the latest version of the IJG JPEG software from ftp://ftp.uu.net/graphics/jpeg/ (e.g., the jpegsrc.v6b.tar.gz file). You must use version 6b or later of the IJG JPEG software. You might also consult the JPEG FAQ at http://www.faqs.org/faqs/jpeg-faq/.What's new in version 1.7.3?
Another attempt at Makefile fixes to permit
linking with all libraries required on platforms with order-
dependent linkers. Perhaps it will work this time.
What's new in version 1.7.2?
An uninitialized-pointer bug in gdtestttf.c
was corrected.
This bug caused crashes at the end of each call to gdImageStringTTF on
some platforms. Thanks to Wolfgang Haefelinger.
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?
A minor buglet in the Makefile was corrected, as well as an inaccurate
error message in gdtestttf.c
. Thanks to Masahito Yamaga.
What's new in version 1.7?
Version 1.7 contains the following changes:
- Japanese language support for the TrueType functions. Thanks to Masahito Yamaga.
autoconf
andconfigure
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 togd.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?
Version 1.6.3 corrects a memory leak in gd_png.c. This leak caused
a significant amount of memory to be allocated and not freed when
writing a PNG image.
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.
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!
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.
This format also supports version numbers and rudimentary validity
checks, so it should be more 'supportable' than the previous GD format.
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 website.
libpng is available for a variety of platforms from
the PNG website.
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.
In order to build gd, you must first unpack the archive you have
downloaded. If you are not familiar with
Unpacking the archive will produce a directory called "gd-2.0.33".
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
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
Create a project using your favorite programming environment.
Copy all of the gd files to the project directory. Add
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.
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!)
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.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.
The
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.
Truecolor images are always filled with black at creation time.
There is no concept of a "background" color index.
If you already have the
image file in memory, pass the size of the file and a pointer to the
file's data to gdImageCreateFromJpegPtr, which is otherwise identical
to gdImageCreateFromJpeg.
If you already have the
image file in memory, pass the size of the file and a pointer to the
file's data to gdImageCreateFromPngPtr, which is otherwise identical
to gdImageCreateFromPng.
If the PNG image being loaded is a truecolor image, the resulting
gdImagePtr will refer to a truecolor image. If the PNG image
being loaded is a palette or grayscale image, the resulting
gdImagePtr will refer to a palette image. gd retains only 8 bits
of resolution for each of the red, green and blue channels, and
only 7 bits of resolution for the alpha channel. The former
restriction affects only a handful of very rare 48-bit color
and 16-bit grayscale PNG images. The second restriction affects
all semitransparent PNG images, but the difference is essentially
invisible to the eye. 7 bits of alpha channel resolution is,
in practice, quite a lot.
gdImageCreateFromPngSource is called to load a PNG from
a data source other than a file. Usage is very similar to
the gdImageCreateFromPng function,
except that the programmer provides a custom data source.
The programmer must write an input function which accepts
a context pointer, a buffer, and a number of bytes to be
read as arguments. This function must read the number of
bytes requested, unless the end of the file has been reached,
in which case the function should return zero, or an error
has occurred, in which case the function should return
The example below
implements gdImageCreateFromPng
by creating a custom data source and invoking gdImageCreateFromPngSource.
If you already have the
image file in memory, pass the size of the file and a pointer to the
file's data to gdImageCreateFromGifPtr, which is otherwise identical
to gdImageCreateFromGif.
If you already have the
image file in memory, pass the size of the file and a pointer to the
file's data to gdImageCreateFromGdPtr, which is otherwise identical
to gdImageCreateFromGd.
gdImageCreateFromGd
returns a gdImagePtr to the new image, or NULL
if unable to load the image (most often because the file is corrupt or
does not contain a gd format image). gdImageCreateFromGd does not
close the file. You can inspect the sx and sy members of the
image to determine its size. The image must eventually be destroyed
using gdImageDestroy().
If you already have the
image file in memory, pass the size of the file and a pointer to the
file's data to gdImageCreateFromGd2Ptr, which is otherwise identical
to gdImageCreateFromGd2.
gdImageCreateFromGd2
returns a gdImagePtr to the new image, or NULL
if unable to load the image (most often because the file is corrupt or
does not contain a gd format image). gdImageCreateFromGd2 does not
close the file. You can inspect the sx and sy members of the
image to determine its size. The image must eventually be destroyed
using gdImageDestroy().
If you already have the image file in memory, you may use
gdImageCreateFromGd2PartPtr. Pass the size of the image file,
in bytes, as the first argument and the pointer to the image file data
as the second argument.
If you already have the
image file in memory, pass the size of the file and a pointer to the
file's data to gdImageCreateFromWBMPPtr, which is otherwise identical
to gdImageCreateFromWBMP.
If quality is negative, the default IJG JPEG quality value (which
should yield a good general quality / size tradeoff for most
situations) is used. Otherwise, for practical purposes, quality
should be a value in the range 0-95, higher quality values usually
implying both higher quality and larger image sizes.
If you have set image interlacing using
gdImageInterlace, this function will
interpret that to mean you wish to output a progressive JPEG. Some
programs (e.g., Web browsers) can display progressive JPEGs
incrementally; this can be useful when browsing over a relatively slow
communications link, for example. Progressive JPEGs can also be
slightly smaller than sequential (non-progressive) JPEGs.
GIF does not support true color; GIF images can contain a maximum
of 256 colors. If the image to be written is a
truecolor image, such as those created with
gdImageCreateTrueColor or loaded
from a JPEG or a truecolor PNG image file, a palette-based
temporary image will automatically be created internally using the
gdImageCreatePaletteFromTrueColor function. The original image pixels are not modified. This conversion
produces high quality palettes but does require some CPU time. If you are
regularly converting truecolor to palette in this way, you should consider
creating your image as a palette-based image in the first place.
The GlobalCM flag indicates if a global color map (or palette) is used
in the GIF89A header. A nonzero value specifies that a global color
map should be used to reduce the size of the animation.
Of course, if the color maps of
individual frames differ greatly, a global color map may not be a good idea.
GlobalCM=1 means write global color map, GlobalCM=0 means do not, and
GlobalCM=-1 means to do the default, which currently is to use a global
color map.
If Loops is 0 or greater, the Netscape 2.0 extension for animation
loop count is written. 0 means infinite loop count. -1 means that
the extension is not added which results in no looping. -1 is the
default.
Setting the LocalCM flag to 1 adds a local palette for this image to the
animation. Otherwise the global palette is assumed and the user must make
sure the palettes match. Use gdImagePaletteCopy to do that.
Automatic optimization is activated by giving the previous image as a
parameter. This function then compares the images and only writes the changed
pixels to the new frame in animation. The Disposal parameter for
optimized animations must be set to 1, also for the first frame.
LeftOfs and TopOfs parameters are ignored for optimized frames. To
achieve good optimization, it is usually best to use a single global
color map. To allow gdImageGifAnimAdd to compress unchanged pixels via
the use of a transparent color, the image must include a transparent color.
For more information, see gdImagePng.
For more information, see gdImagePngPtr.
The programmer must write an output function which accepts
a context pointer, a buffer, and a number of bytes to be
written as arguments. This function must write the number of
bytes requested and return that number, unless an error
has occurred, in which case the function should return
The example below
implements gdImagePng
by creating a custom data source and invoking gdImagePngFromSink.
WBMP file support is black and white only. The color index
specified by the fg argument is the "foreground," and only pixels
of this color will be set in the WBMP file. All other pixels
will be considered "background."
The gd image format is intended for fast reads and writes of
images your program will need frequently to build other
images. It is not a compressed format, and is not intended
for general use.
The gd2 image format is intended for fast reads and writes of
parts of images.
It is a compressed format, and well suited to retrieving smll sections of
much larger images.
The third and fourth parameters are the 'chunk size' and format resposectively.
The file is stored as a series of compressed subimages, and the
Chunk Size determines the sub-image size - a value of
zero causes the GD library to use the default.
It is also possible to store GD2 files in an uncompressed format, in which case the
fourth parameter should be GD2_FMT_RAW.
The function converts a truecolor image to a palette-based image,
using a high-quality two-pass quantization routine.
If ditherFlag is set, the image will be
dithered to approximate colors better, at the expense
of some obvious "speckling." colorsWanted can be
anything up to 256. If the original source image
includes photographic information or anything that
came out of a JPEG, 256 is strongly recommended.
100% transparency of a single transparent color in the
original truecolor image will be preserved. There is no other
support for preservation of alpha channel or transparency in
the destination image.
For best results, don't use this function -- write real
truecolor PNGs and JPEGs. The disk space gain of
conversion to palette is not great (for small images
it can be negative) and the quality loss is ugly. However,
the version of this function included in version 2.0.12 and later does
do a better job than the version included prior to 2.0.12.
gdImageDashedLine is used to draw a dashed line between two endpoints
(x1,y1 and x2, y2).
The line is drawn using the color index specified. The portions of the line
that are not drawn are left transparent so the background is visible.
The border color cannot be a special color
such as gdTiled; it must be a proper
solid color. The fill color can be, however.
Note that gdImageFillToBorder is recursive. It is not the most
naive implementation possible, and the implementation is
expected to improve, but there will always be degenerate
cases in which the stack can become very deep. This can be
a problem in MSDOS and MS Windows 3.1 environments. (Of course,
in a Unix or Windows 95/98/NT environment with a proper stack, this is
not a problem at all.)
The fill color can be gdTiled, resulting
in a tile fill using another image as the tile. However,
the tile image cannot be transparent. If the image you wish
to fill with has a transparent color index, call
gdImageTransparent on the
tile image and set the transparent color index to -1
to turn off its transparency.
Note that gdImageFill is recursive. It is not the most
naive implementation possible, and the implementation is
expected to improve, but there will always be degenerate
cases in which the stack can become very deep. This can be
a problem in MSDOS and MS Windows environments. (Of course,
in a Unix or Windows 95/98/NT environment with a proper stack, this is
not a problem at all.)
gdImageSetAntiAliased is used to specify the actual foreground color
to be used when drawing antialiased lines. You may set any color to
be the foreground, however as of version 2.0.12 an alpha channel
component is not supported.
Antialiased lines can be drawn on both truecolor and palette-based
images. However, attempts to draw antialiased lines on
highly complex palette-based backgrounds may not give satisfactory
results, due to the limited number of colors available in the
palette. Antialiased line-drawing on simple backgrounds should
work well with palette-based images; otherwise create or fetch
a truecolor image instead.
You need not take any special action when you are finished
with antialised line drawing.
gdImageSetBrush is used to specify the brush to be used in a
particular image. You can set any image to be the brush.
If the brush image does not have the same color map as the
first image, any colors missing from the first image
will be allocated. If not enough colors can be allocated,
the closest colors already available will be used. This
allows arbitrary PNGs to be used as brush images. It also
means, however, that you should not set a brush unless you
will actually use it; if you set a rapid succession of
different brush images, you can quickly fill your color map,
and the results will not be optimal.
You need not take any special action when you are finished
with a brush. As for any other image, if you will not
be using the brush image for any further purpose,
you should call gdImageDestroy.
You must not use the color gdBrushed
if the current brush has been destroyed; you can of
course set a new brush to replace it.
gdImageSetTile is used to specify the tile to be used in a
particular image. You can set any image to be the tile.
If the tile image does not have the same color map as the
first image, any colors missing from the first image
will be allocated. If not enough colors can be allocated,
the closest colors already available will be used. This
allows arbitrary PNGs to be used as tile images. It also
means, however, that you should not set a tile unless you
will actually use it; if you set a rapid succession of
different tile images, you can quickly fill your color map,
and the results will not be optimal.
You need not take any special action when you are finished
with a tile. As for any other image, if you will not
be using the tile image for any further purpose,
you should call gdImageDestroy.
You must not use the color gdTiled
if the current tile has been destroyed; you can of
course set a new tile to replace it.
To use gdImageSetStyle, create an array of integers and assign
them the desired series of color values to be repeated.
You can assign the special color value
gdTransparent to indicate that the existing color should
be left unchanged for that particular pixel (allowing a dashed
line to be attractively drawn over an existing image).
Then, to draw a line using the style, use the normal
gdImageLine function with the
special color value gdStyled.
As of version 1.1.1, the style
array is copied when you set the style, so you need not
be concerned with keeping the array around indefinitely.
This should not break existing code that assumes styles
are not copied.
You can also combine styles and brushes to draw the brush
image at intervals instead of in a continuous stroke.
When creating a style for use with a brush, the
style values are interpreted differently: zero (0) indicates
pixels at which the brush should not be drawn, while one (1)
indicates pixels at which the brush should be drawn.
To draw a styled, brushed line, you must use the
special color value
gdStyledBrushed. For an example of this feature
in use, see gddemo.c (provided in the distribution).
If gdImageSetClip is never called, the clipping area will be the
entire image.
The parameters passed to gdImageSetClip are checked against the dimensions
of the image and limited to "safe" values.
See gdImageString for more information
and examples, or gdImageStringFT for a
freetype-based alternative that supports truetype fonts.
See gdImageString for more information
and examples, or gdImageStringFT for a
freetype-based alternative that supports truetype fonts.
See gdImageString for more information
and examples, or gdImageStringFT for a
freetype-based alternative that supports truetype fonts.
See gdImageString for more information
and examples, or gdImageStringFT for a
freetype-based alternative that supports truetype fonts.
See gdImageString for more information
and examples, or gdImageStringFT for a
freetype-based alternative that supports truetype fonts.
You must include the files "gdfontt.h", "gdfonts.h", "gdfontmb.h",
"gdfontl.h" and "gdfontg.h" respectively
and (if you are not using a library-based approach) link with the
corresponding .c files to use the provided fonts.
The character specified by the fifth
argument is drawn from left to right in the specified
color. (See gdImageCharUp for a way
of drawing vertical text.) Pixels not
set by a particular character retain their previous color.
The character specified by
the fifth argument is drawn
from bottom to top, rotated at a 90-degree angle, in the specified
color. (See gdImageChar for a way
of drawing horizontal text.) Pixels not
set by a particular character retain their previous color.
This function was added in gd1.3 to provide a means of rendering
fonts with more than 256 characters for those who have them. A
more frequently used routine is gdImageString.
This function was added in gd1.3 to provide a means of rendering
fonts with more than 256 characters for those who have them. A
more frequently used routine is gdImageStringUp.
gdImageStringFT draws a string of anti-aliased characters on the image using
the FreeType
library to render user-supplied TrueType fonts. We do not provide
TrueType fonts (.ttf and .ttc files). Obtaining them is entirely up to
you. The string is anti-aliased, meaning that there should be
fewer "jaggies" visible. The fontname is the full pathname to a TrueType
font file, or a font face name if the GDFONTPATH environment variable
or the compiled-in DEFAULT_FONTPATH macro of gdft.c have been set intelligently. In the absence of a full path, the font face name may be presented with or without extension (2.0.26).
The null-terminated string argument is considered to be encoded via the UTF_8
standard; also, HTML entities are supported, including decimal,
hexadecimal, and named entities (2.0.26). Those who are passing
ordinary ASCII strings may have difficulty with the &
character unless encoded correctly as & but should have no
other difficulties.
The string may be arbitrarily scaled (ptsize) and rotated (angle in radians).
The direction of rotation is counter-clockwise, with 0 radians (0 degrees)
at 3 o'clock and PI/2 radians (90 degrees) at 12 o'clock.
The user-supplied int brect[8] array is filled on return from gdImageStringFT
with the 8 elements representing the 4 corner coordinates of the
bounding rectangle (the smallest rectangle that completely surrounds the
rendered string and does not intersect any pixel of the rendered string).
The points are relative to the text regardless of the angle, so "upper left"
means in the top left-hand corner seeing the text horizontally.
Use a NULL gdImagePtr to get the bounding rectangle without rendering.
This is a relatively cheap operation if followed by a rendering of the same
string, because of the caching of the partial rendering during bounding
rectangle calculation.
The string is rendered in the color indicated by the gf color index.
Use the negative of the desired color index to
disable anti-aliasing.
The string may contain UTF-8 sequences like: "À"
gdImageStringFT will return a null char* on success, or an error
string on failure.
If the
If
To specify a preference for Unicode, Shift_JIS Big5 character encoding,
set or To output multiline text with a specific line spacing,
include
GD operates on the assumption that the output image will be
rendered to a computer screen. By default, gd passes a
resolution of 96 dpi to the freetype text rendering engine.
This influences the "hinting" decisions made by the renderer. To
specify a different resolution, set hdpi and vdpi accordingly
(in dots per inch) and add
GD 2.0.29 and later can also return the path to the actual font file
used if the gdFTEX_RETURNFONTPATHNAME flag is set. This is useful because
GD 2.0.29 and above are capable of
selecting a font automatically based on a fontconfig font pattern
when fontconfig is available. This information is returned in the
fontpath element of the gdFTStringExtra structure.
GD 2.0.29 and later can use fontconfig to resolve
font names, including fontconfig patterns, if the gdFTEX_FONTCONFIG
flag is set. As a convenience, this behavior can be made the default
by calling gdFTUseFontConfig with
a nonzero value. In that situation it is not necessary to set the
gdFTEX_FONTCONFIG flag on every call; however explicit font path names
can still be used if the gdFTEX_FONTPATHNAME flag is set:
Unless gdFTUseFontConfig has been
called with a nonzero value, GD 2.0.29 and later will still expect
the fontlist argument to the freetype text output functions to be
a font file name or list thereof as in previous versions. If you do
not wish to make fontconfig the default, it is
still possible to force the use of fontconfig for a single call to
the freetype text output functions by setting the gdFTEX_FONTCONFIG
flag:
Returns 0 on success, or an error string otherwise.
For more information, see gdImageStringFTEx
and gdImageSquareToCircle.
In the event that all gdMaxColors colors
(256) have already been allocated, gdImageColorAllocate will
return -1 to indicate failure. (This is not uncommon when
working with existing PNG files that already use 256 colors.)
Note that gdImageColorAllocate
does not check for existing colors that match your request;
see gdImageColorExact,
gdImageColorClosest and
gdImageColorClosestHWB
for ways to locate existing colors that approximate the
color desired in situations where a new color is not available.
Also see gdImageColorResolve,
new in gd-1.6.2.
In the event that all gdMaxColors colors
(256) have already been allocated, gdImageColorAllocate will
return -1 to indicate failure. (This is not uncommon when
working with existing palette-based PNG files that already use 256 colors.)
Note that gdImageColorAllocateAlpha
does not check for existing colors that match your request;
see gdImageColorExactAlpha and
gdImageColorClosestAlpha
for ways to locate existing colors that approximate the
color desired in situations where a new color is not available.
Also see gdImageColorResolveAlpha.
If no colors have yet been allocated in the image,
gdImageColorClosest returns -1.
When applied to a truecolor image, this function always
succeeds in returning the desired color.
This function is most useful as a backup method for choosing
a drawing color when an image already contains
gdMaxColors (256) colors and
no more can be allocated. (This is not uncommon when
working with existing PNG files that already use many colors.)
See gdImageColorExact
for a method of locating exact matches only.
If no colors have yet been allocated in the image,
gdImageColorClosestAlpha returns -1.
When applied to a truecolor image, this function always
succeeds in returning the desired color.
This function is most useful as a backup method for choosing
a drawing color when a palette-based image already contains
gdMaxColors (256) colors and
no more can be allocated. (This is not uncommon when
working with existing palette-based PNG files that already use many colors.)
See gdImageColorExactAlpha
for a method of locating exact matches only.
If no colors have yet been allocated in the image,
gdImageColorClosestHWB returns -1.
When applied to a truecolor image, this function always
succeeds in returning the desired color.
This function is most useful as a backup method for choosing
a drawing color when an image already contains
gdMaxColors (256) colors and
no more can be allocated. (This is not uncommon when
working with existing PNG files that already use many colors.)
See gdImageColorExact
for a method of locating exact matches only.
When applied to a truecolor image, this function always
succeeds in returning the desired color.
When applied to a truecolor image, this function always
succeeds in returning the desired color.
When applied to a truecolor image, this function always
succeeds in returning the desired color.
The color index used should be an index
allocated by gdImageColorAllocate,
whether explicitly invoked by your code or implicitly
invoked by loading an image.
In order to ensure that your image has a reasonable appearance
when viewed by users who do not have transparent background
capabilities (or when you are writing a JPEG-format file, which does
not support transparency), be sure to give reasonable RGB values to the
color you allocate for use as a transparent color,
even though it will be transparent on systems
that support PNG transparency.
The
When you copy a region from one location in an image to another
location in the same image, gdImageCopy will perform as expected
unless the regions overlap, in which case the result is
unpredictable.
Important note on copying between images: since
different images do
not necessarily have the same color tables, pixels are not simply set to the
same color index values to copy them. gdImageCopy will attempt
to find an identical RGB value in the destination image for
each pixel in the copied portion of the source image by
invoking gdImageColorExact. If
such a value is not found, gdImageCopy will attempt to
allocate colors as needed using
gdImageColorAllocate. If both of these methods fail,
gdImageCopy will invoke
gdImageColorClosest to find the color in the destination
image which most closely approximates the color of the
pixel being copied.
The
When you copy a region from one location in an image to another
location in the same image, gdImageCopy will perform as expected
unless the regions overlap, in which case the result is
unpredictable. If this presents a problem, create a scratch image
in which to keep intermediate results.
Important note on copying between images: since images
do not necessarily have the same color tables, pixels are not simply set
to the same color index values to copy them. gdImageCopy will attempt
to find an identical RGB value in the destination image for
each pixel in the copied portion of the source image by
invoking gdImageColorExact. If
such a value is not found, gdImageCopy will attempt to
allocate colors as needed using
gdImageColorAllocate. If both of these methods fail,
gdImageCopy will invoke
gdImageColorClosest to find the color in the destination
image which most closely approximates the color of the
pixel being copied.
Pixel values are only interpolated if the destination image is a
truecolor image. Otherwise,
gdImageCopyResized is
automatically invoked.
The
When you copy a region from one location in an image to another
location in the same image, gdImageCopy will perform as expected
unless the regions overlap, in which case the result is
unpredictable. If this presents a problem, create a scratch image
in which to keep intermediate results.
Important note on copying between images: since images
do not necessarily have the same color tables, pixels are not simply set
to the same color index values to copy them. If the destination image
is a palette image, gd will use the
gdImageColorResolve function to
determine the best color available.
When you copy a region from one location in an image to another
location in the same image, gdImageCopyRotated will perform as expected
unless the regions overlap, in which case the result is
unpredictable. If this presents a problem, create a scratch image
in which to keep intermediate results.
Important note on copying between images: since
palette-based images do not necessarily have the same color tables, pixels
are not simply set to the same color index values to copy them.
If the destination image is not a truecolor image,
gdImageColorResolveAlpha is
used to choose the destination pixel.
If, however, the pct parameter is less than 100, then the two images are merged.
With pct = 0, no action is taken.
This feature is most useful to 'highlight' sections of an image by merging a solid color with
pct = 50:
A nonzero value for the interlace argument turns on interlace;
a zero value turns it off. Note that interlace has no effect
on other functions, and has no meaning unless you save the
image in PNG or JPEG format; the gd and xbm formats do not support
interlace.
When a PNG is loaded with
gdImageCreateFromPng or a JPEG is
loaded with
gdImageCreateFromJpeg, interlace
will be set according to the setting in the PNG or JPEG file.
Note that many PNG and JPEG viewers and web browsers do not
support interlace or the incremental display of progressive
JPEGs. However, the interlaced PNG or progressive JPEG should still
display; it will simply appear all at once, just as other images do.
The program "pngtogd.c" is provided as a simple way of converting
.png files to .gd format. I emphasize again that you will not
need to use this format unless you have a need for high-speed loading
of a few frequently-used images in your program.
The program "pngtogd2.c" is provided as a simple way of converting
.png files to .gd2 format.
The
It is not necessary to implement all functions in an I/O context if you know
that it will only be used in limited cirsumstances. At the time of writing
(Version 1.6.1, July 1999), the known requirements are:
What's new in version 1.6.2?
Version 1.6.2 from John Ellson
if ((color=gdImageColorExact(im,R,G,B)) < 0)
if ((color=gdImageColorAllocate(im,R,G,B)) < 0)
color=gdImageColorClosest(im,R,G,B);
What's new in version 1.6.1?
Version 1.6.1 incorporates superior PNG reading and writing code
from Greg Roelofs, with minor modifications by Tom Boutell.
Specifically, I altered his code to read non-palette images
(converting them to palette images badly, by dithering them),
and to tolerate palette images with types of transparency that
gd doesn't actually support (it just ignores the advanced
transparency features). Any bugs in this area are therefore my
fault, not Greg's.
What's new in version 1.6?
Version 1.6 features the following changes:
What's new in version 1.5?
Version 1.5 featured the following changes:
NOTE: In fairness to Thomas Boutell, any bug/problems with any of the above features should
probably be reported to Philip Warner.
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?
Version 1.4 features the following changes:
What's new in version 1.3?
Version 1.3 features the following changes:
pixels
array will require
changes.
What else do I need to use gd?
Binaries (DLL for Windows programmers):
Source Code:
Win32 DLL users: if you are using MSVC, use the provided batch file
Building gd From the Source
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.
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.
For Unix
cd
to the 2.0.33 directory and type:
./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
.
configure
again.
./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.
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.
gd basics: using gd in your program
gd lets you create PNG or JPEG images on the fly. To use gd in your
program, include the file gd.h, and link with the gd
library and the other required libraries; the syntax for
most Unix flavors is:
-lgd -lpng -lz -ljpeg -lfreetype -lm
Assuming that all of these libraries are available.
/* 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);
}
When executed, this program creates an image, allocates
two colors (the first color allocated becomes the background
color), draws a diagonal line (note that 0, 0 is the upper
left corner), writes the image to PNG and JPEG files, and
destroys the image.
Webpng: a more powerful gd example
Webpng is a simple utility program to manipulate PNGs from the
command line. It is written for Unix and similar command-line
systems, but should be easily adapted for other environments.
Webpng allows you to set transparency and interlacing and
output interesting information about the PNG in question.
Function and type reference
Types
gdImage
(TYPE)
pixels
or tpixels
arrays. If the trueColor
flag
is set, the tpixels
array is valid; otherwise the
pixels
array is valid.
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;
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_gd2.c, gd_jpeg.c, etc., all of which rely
on gdIOCtx to implement the standard image read and write functions.
typedef struct gdIOCtx
{
int (*getC) (struct gdIOCtx *);
int (*getBuf) (struct gdIOCtx *, void *, int wanted);
void (*putC) (struct gdIOCtx *, int);
int (*putBuf) (struct gdIOCtx *, const void *, int wanted);
/* seek must return 1 on SUCCESS, 0 on FAILURE. Unlike fseek! */
int (*seek) (struct gdIOCtx *, const int);
long (*tell) (struct gdIOCtx *);
void (*gd_free) (struct gdIOCtx *);
} gdIOCtx;
typedef struct {
/* # of characters in font */
int nchars;
/* First character is numbered... (usually 32 = space) */
int offset;
/* Character width and height */
int w;
int h;
/* Font data; array of characters, one row after another.
Easily included in code, also easily loaded from
data files. */
char *data;
} gdFont;
typedef struct {
int x, y;
} gdPoint, *gdPointPtr;
typedef struct {
int (*source) (void *context, char *buffer, int len);
void *context;
} gdSource, *gdSourcePtr;
Represents a source from which a PNG can be read.
Programmers who do not wish to read PNGs from a file can provide
their own alternate input mechanism, using the
gdImageCreateFromPngSource function.
See the documentation of that function for an example of the
proper use of this type.
typedef struct {
int (*sink) (void *context, char *buffer, int len);
void *context;
} gdSink, *gdSinkPtr;
Represents a "sink" (destination) to which a PNG can be written.
Programmers who do not wish to write PNGs to a file can provide
their own alternate output mechanism, using the
gdImagePngToSink function.
See the documentation of that function for an example of the
proper use of this type.
Image creation, destruction, loading and saving
... inside a function ...
gdImagePtr im;
im = gdImageCreate(64, 64);
/* ... Use the image ... */
gdImageDestroy(im);
... inside a function ...
gdImagePtr im;
im = gdImageCreateTrueColor(64, 64);
/* ... Use the image ... */
gdImageDestroy(im);
gdImageCreateFromJpegPtr(int size, void *data)
(FUNCTION)
gdImageCreateFromJpegCtx(gdIOCtx *in)
(FUNCTION)
gdImagePtr im;
... inside a function ...
FILE *in;
in = fopen("myjpeg.jpg", "rb");
im = gdImageCreateFromJpeg(in);
fclose(in);
/* ... Use the image ... */
gdImageDestroy(im);
gdImageCreateFromPngPtr(int size, void *data)
(FUNCTION)
gdImageCreateFromPngCtx(gdIOCtx *in)
(FUNCTION)
gdImagePtr im;
... inside a function ...
FILE *in;
in = fopen("mypng.png", "rb");
im = gdImageCreateFromPng(in);
fclose(in);
/* ... Use the image ... */
gdImageDestroy(im);
-1
. The programmer then creates a
gdSource structure and sets
the source
pointer to the input function and
the context pointer to any value which is useful to the
programmer.
static int freadWrapper(void *context, char *buf, int len);
gdImagePtr gdImageCreateFromPng(FILE *in)
{
gdSource s;
s.source = freadWrapper;
s.context = in;
return gdImageCreateFromPngSource(&s);
}
static int freadWrapper(void *context, char *buf, int len)
{
int got = fread(buf, 1, len, (FILE *) context);
return got;
}
gdImageCreateFromGifPtr(int size, void *data)
(FUNCTION)
gdImageCreateFromGifCtx(gdIOCtx *in)
(FUNCTION)
gdImagePtr im;
... inside a function ...
FILE *in;
in = fopen("mygif.gif", "rb");
im = gdImageCreateFromGif(in);
fclose(in);
/* ... Use the image ... */
gdImageDestroy(im);
gdImageCreateFromGdCtx(gdIOCtx *in)
(FUNCTION)
... inside a function ...
gdImagePtr im;
FILE *in;
in = fopen("mygd.gd", "rb");
im = gdImageCreateFromGd(in);
fclose(in);
/* ... Use the image ... */
gdImageDestroy(im);
gdImageCreateFromGd2Ptr(int size, void *data)
(FUNCTION)
gdImageCreateFromGd2Ctx(gdIOCtx *in)
(FUNCTION)
... inside a function ...
gdImagePtr im;
FILE *in;
in = fopen("mygd.gd2", "rb");
im = gdImageCreateFromGd2(in);
fclose(in);
/* ... Use the image ... */
gdImageDestroy(im);
gdImageCreateFromGd2PartPtr(int size, void *data, int srcX, int srcY, int w, int h)
(FUNCTION)
gdImageCreateFromGd2PartCtx(gdIOCtx *in)
(FUNCTION)
gdImageCreateFromWBMPPtr(int size, void *data)
(FUNCTION)
gdImageCreateFromWBMPCtx(gdIOCtx *in)
(FUNCTION)
gdImagePtr im;
... inside a function ...
FILE *in;
in = fopen("mywbmp.wbmp", "rb");
im = gdImageCreateFromWBMP(in);
fclose(in);
/* ... Use the image ... */
gdImageDestroy(im);
... inside a function ...
gdImagePtr im;
FILE *in;
in = fopen("myxbm.xbm", "rb");
im = gdImageCreateFromXbm(in);
fclose(in);
/* ... Use the image ... */
gdImageDestroy(im);
... inside a function ...
gdImagePtr im;
FILE *in;
in = fopen("myxpm.xpm", "rb");
im = gdImageCreateFromXpm(in);
fclose(in);
/* ... Use the image ... */
gdImageDestroy(im);
... inside a function ...
gdImagePtr im;
im = gdImageCreate(10, 10);
/* ... Use the image ... */
/* Now destroy it */
gdImageDestroy(im);
void gdImageJpegCtx(gdImagePtr im, gdIOCtx *out, int quality)
(FUNCTION)
... inside a function ...
gdImagePtr im;
int black, white;
FILE *out;
/* Create the image */
im = gdImageCreate(100, 100);
/* Allocate background */
white = gdImageColorAllocate(im, 255, 255, 255);
/* Allocate drawing color */
black = gdImageColorAllocate(im, 0, 0, 0);
/* Draw rectangle */
gdImageRectangle(im, 0, 0, 99, 99, black);
/* Open output file in binary mode */
out = fopen("rect.jpg", "wb");
/* Write JPEG using default quality */
gdImageJpeg(im, out, -1);
/* Close file */
fclose(out);
/* Destroy image */
gdImageDestroy(im);
void gdImageGifCtx(gdImagePtr im, gdIOCtx *out)
(FUNCTION)
... inside a function ...
gdImagePtr im;
int black, white;
FILE *out;
/* Create the image */
im = gdImageCreate(100, 100);
/* Allocate background */
white = gdImageColorAllocate(im, 255, 255, 255);
/* Allocate drawing color */
black = gdImageColorAllocate(im, 0, 0, 0);
/* Draw rectangle */
gdImageRectangle(im, 0, 0, 99, 99, black);
/* Open output file in binary mode */
out = fopen("rect.gif", "wb");
/* Write GIF */
gdImageGif(im, out);
/* Close file */
fclose(out);
/* Destroy image */
gdImageDestroy(im);
void gdImageGifAnimBeginCtx(gdImagePtr im, gdIOCtx *out, int GlobalCM, int Loops)
(FUNCTION)
void gdImageGifAnimAddCtx(gdImagePtr im, gdIOCtx *out, int LocalCM, int LeftOfs, int TopOfs, int Delay, int Disposal, gdImagePtr previm)
(FUNCTION)
gdDisposalNone
, meaning that the pixels changed by this
frame should remain on the display when the next frame begins to render, but
can also be gdDisposalUnknown
(not recommended),
gdDisposalRestoreBackground
(restores the first
allocated color of the global palette), or
gdDisposalRestorePrevious
(restores the appearance of the
affected area before the frame was rendered). Only
gdDisposalNone
is a sensible choice for the first frame.
If previm
is
passed, the built-in GIF optimizer will always use gdDisposalNone
regardless of the Disposal parameter.
... inside a function ...
gdImagePtr im, im2, im3;
int black, white, trans;
FILE *out;
/* Create the image */
im = gdImageCreate(100, 100);
/* Allocate background */
white = gdImageColorAllocate(im, 255, 255, 255);
/* Allocate drawing color */
black = gdImageColorAllocate(im, 0, 0, 0);
/* Allocate transparent color for animation compression */
trans = gdImageColorAllocate(im, 1, 1, 1);
/* Draw rectangle */
gdImageRectangle(im, 0, 0, 10, 10, black);
/* Open output file in binary mode */
out = fopen("anim.gif", "wb");
/* Write GIF header. Use global color map. Loop a few times */
gdImageGifAnimBegin(im, out, 1, 3);
/* Write the first frame. No local color map. Delay = 1s */
gdImageGifAnimAdd(im, out, 0, 0, 0, 100, 1, NULL);
/* construct the second frame */
im2 = gdImageCreate(100, 100);
/* Allocate background to make it white */
(void)gdImageColorAllocate(im2, 255, 255, 255);
/* Make sure the palette is identical */
gdImagePaletteCopy (im2, im);
/* Draw something */
gdImageRectangle(im2, 0, 0, 15, 15, black);
/* Allow animation compression with transparent pixels */
gdImageColorTransparent (im2, trans);
/* Add the second frame */
gdImageGifAnimAdd(im2, out, 0, 0, 0, 100, 1, im);
/* construct the second frame */
im3 = gdImageCreate(100, 100);
/* Allocate background to make it white */
(void)gdImageColorAllocate(im3, 255, 255, 255);
/* Make sure the palette is identical */
gdImagePaletteCopy (im3, im);
/* Draw something */
gdImageRectangle(im3, 0, 0, 15, 20, black);
/* Allow animation compression with transparent pixels */
gdImageColorTransparent (im3, trans);
/* Add the third frame, compressing against the second one */
gdImageGifAnimAdd(im3, out, 0, 0, 0, 100, 1, im2);
/* Write the end marker */
/* gdImageGifAnimEnd(out); is the same as the following: */
putc (';', out);
/* Close file */
fclose(out);
/* Destroy images */
gdImageDestroy(im);
gdImageDestroy(im2);
gdImageDestroy(im3);
void gdImageGifAnimEndCtx(gdIOCtx *out)
(FUNCTION)
void gdImagePngCtx(gdImagePtr im, gdIOCtx *out)
(FUNCTION)
... inside a function ...
gdImagePtr im;
int black, white;
FILE *out;
/* Create the image */
im = gdImageCreate(100, 100);
/* Allocate background */
white = gdImageColorAllocate(im, 255, 255, 255);
/* Allocate drawing color */
black = gdImageColorAllocate(im, 0, 0, 0);
/* Draw rectangle */
gdImageRectangle(im, 0, 0, 99, 99, black);
/* Open output file in binary mode */
out = fopen("rect.png", "wb");
/* Write PNG */
gdImagePng(im, out);
/* Close file */
fclose(out);
/* Destroy image */
gdImageDestroy(im);
void gdImagePngCtxEx(gdImagePtr im, gdIOCtx *out, int level)
(FUNCTION)
-1
. The programmer then creates a
gdSink structure and sets
the sink
pointer to the output function and
the context pointer to any value which is useful to the
programmer.
static int stdioSink(void *context, char *buffer, int len)
{
return fwrite(buffer, 1, len, (FILE *) context);
}
void gdImagePng(gdImagePtr im, FILE *out)
{
gdSink mySink;
mySink.context = (void *) out;
mySink.sink = stdioSink;
gdImagePngToSink(im, &mySink);
}
gdImageWBMPCtx(gdIOCtx *out)
(FUNCTION)(FUNCTION)
... inside a function ...
gdImagePtr im;
int black, white;
FILE *out;
/* Create the image */
im = gdImageCreate(100, 100);
/* Allocate background */
white = gdImageColorAllocate(im, 255, 255, 255);
/* Allocate drawing color */
black = gdImageColorAllocate(im, 0, 0, 0);
/* Draw rectangle */
gdImageRectangle(im, 0, 0, 99, 99, black);
/* Open output file in binary mode */
out = fopen("rect.wbmp", "wb");
/* Write WBMP, with black as foreground */
gdImageWBMP(im, black, out);
/* Close file */
fclose(out);
/* Destroy image */
gdImageDestroy(im);
... inside a function ...
gdImagePtr im;
int black, white;
FILE *out;
/* Create the image */
im = gdImageCreate(100, 100);
/* Allocate background */
white = gdImageColorAllocate(im, 255, 255, 255);
/* Allocate drawing color */
black = gdImageColorAllocate(im, 0, 0, 0);
/* Draw rectangle */
gdImageRectangle(im, 0, 0, 99, 99, black);
/* Open output file in binary mode */
out = fopen("rect.gd", "wb");
/* Write gd format file */
gdImageGd(im, out);
/* Close file */
fclose(out);
/* Destroy image */
gdImageDestroy(im);
void gdImageGd2Ctx(gdImagePtr im, gdIOCtx *out, int chunkSize, int fmt)
(FUNCTION)
... inside a function ...
gdImagePtr im;
int black, white;
FILE *out;
/* Create the image */
im = gdImageCreate(100, 100);
/* Allocate background */
white = gdImageColorAllocate(im, 255, 255, 255);
/* Allocate drawing color */
black = gdImageColorAllocate(im, 0, 0, 0);
/* Draw rectangle */
gdImageRectangle(im, 0, 0, 99, 99, black);
/* Open output file in binary mode */
out = fopen("rect.gd", "wb");
/* Write gd2 format file */
gdImageGd2(im, out, 0, GD2_FMT_COMPRESSED);
/* Close file */
fclose(out);
/* Destroy image */
gdImageDestroy(im);
gdImagePtr gdImageCreatePaletteFromTrueColor(gdImagePtr im, int ditherFlag, int colorsWanted)
(FUNCTION)
gdImageCreatePaletteFromTrueColor returns a new
image. gdImageTrueColorToPalette permanently converts the
existing image. The two functions are otherwise identical.
Drawing Functions
... inside a function ...
gdImagePtr im;
int black;
int white;
im = gdImageCreate(100, 100);
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0);
/* Allocate the color white (red, green and blue all maximum). */
white = gdImageColorAllocate(im, 255, 255, 255);
/* Set a pixel near the center. */
gdImageSetPixel(im, 50, 50, white);
/* ... Do something with the image, such as
saving it to a file... */
/* Destroy it */
gdImageDestroy(im);
... inside a function ...
gdImagePtr im;
int black;
int white;
im = gdImageCreate(100, 100);
/* Background color (first allocated) */
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 corner to the
lower right corner. */
gdImageLine(im, 0, 0, 99, 99, white);
/* ... Do something with the image, such as
saving it to a file... */
/* Destroy it */
gdImageDestroy(im);
... inside a function ...
gdImagePtr im;
int black;
int white;
im = gdImageCreate(100, 100);
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0);
/* Allocate the color white (red, green and blue
all maximum). */
white = gdImageColorAllocate(im, 255, 255, 255);
/* Draw a dashed line from the upper left corner
to the lower right corner. */
gdImageDashedLine(im, 0, 0, 99, 99);
/* ... Do something with the image, such as
saving it to a file... */
/* Destroy it */
gdImageDestroy(im);
... inside a function ...
gdImagePtr im;
int black;
int white;
/* Points of polygon */
gdPoint points[3];
im = gdImageCreate(100, 100);
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0);
/* Allocate the color white (red, green and
blue all maximum). */
white = gdImageColorAllocate(im, 255, 255, 255);
/* Draw a triangle. */
points[0].x = 50;
points[0].y = 0;
points[1].x = 99;
points[1].y = 99;
points[2].x = 0;
points[2].y = 99;
gdImagePolygon(im, points, 3, white);
/* ... Do something with the image, such as
saving it to a file... */
/* Destroy it */
gdImageDestroy(im);
... inside a function ...
gdImagePtr im;
int black;
int white;
im = gdImageCreate(100, 100);
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0);
/* Allocate the color white (red, green and blue all maximum). */
white = gdImageColorAllocate(im, 255, 255, 255);
/* Draw a rectangle occupying the central area. */
gdImageRectangle(im, 25, 25, 74, 74, white);
/* ... Do something with the image, such as
saving it to a file... */
/* Destroy it */
gdImageDestroy(im);
... inside a function ...
gdImagePtr im;
int black;
int white;
int red;
/* Points of polygon */
gdPoint points[3];
im = gdImageCreate(100, 100);
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0);
/* Allocate the color white (red, green and blue all maximum). */
white = gdImageColorAllocate(im, 255, 255, 255);
/* Allocate the color red. */
red = gdImageColorAllocate(im, 255, 0, 0);
/* Draw a triangle. */
points[0].x = 50;
points[0].y = 0;
points[1].x = 99;
points[1].y = 99;
points[2].x = 0;
points[2].y = 99;
/* Paint it in white */
gdImageFilledPolygon(im, points, 3, white);
/* Outline it in red; must be done second */
gdImagePolygon(im, points, 3, red);
/* ... Do something with the image, such as
saving it to a file... */
/* Destroy it */
gdImageDestroy(im);
... inside a function ...
gdImagePtr im;
int black;
int white;
im = gdImageCreate(100, 100);
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0);
/* Allocate the color white (red, green and blue all maximum). */
white = int gdImageColorAllocate(im, 255, 255, 255);
/* Draw a filled rectangle occupying the central area. */
gdImageFilledRectangle(im, 25, 25, 74, 74, white);
/* ... Do something with the image, such as
saving it to a file... */
/* Destroy it */
gdImageDestroy(im);
s
and ends at
the position specified by e
. The arc is drawn in
the color specified by the last argument. A circle can be drawn
by beginning from 0 degrees and ending at 360 degrees, with
width and height being equal. e must be greater than s. Values greater
than 360 are interpreted modulo 360.
... inside a function ...
gdImagePtr im;
int black;
int white;
im = gdImageCreate(100, 50);
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0);
/* Allocate the color white (red, green and blue all maximum). */
white = gdImageColorAllocate(im, 255, 255, 255);
/* Inscribe an ellipse in the image. */
gdImageArc(im, 50, 25, 98, 48, 0, 360, white);
/* ... Do something with the image, such as
saving it to a file... */
/* Destroy it */
gdImageDestroy(im);
s
and ends at
the position specified by e
. The arc is filled in
the color specified by the second to last argument. A circle can be drawn
by beginning from 0 degrees and ending at 360 degrees, with
width and height being equal. e must be greater than s. Values greater
than 360 are interpreted modulo 360. The last argument is a bitwise
OR of the following possibilities:
gdArc and gdChord are mutually exclusive;
gdChord just connects the starting and ending
angles with a straight line, while gdArc produces
a rounded edge. gdPie is a synonym for gdArc.
gdNoFill indicates that the arc or chord should be
outlined, not filled. gdEdged, used together with
gdNoFill, indicates that the beginning and ending
angles should be connected to the center; this is
a good way to outline (rather than fill) a
'pie slice'.
... inside a function ...
gdImagePtr im;
int black;
int white;
im = gdImageCreate(100, 50);
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0);
/* Allocate the color white (red, green and blue all maximum). */
white = gdImageColorAllocate(im, 255, 255, 255);
/* Inscribe a filled pie slice in the image. */
gdImageFilledArc(im, 50, 25, 98, 48, 0, 45, white, gdArc);
/* ... Do something with the image, such as
saving it to a file... */
/* Destroy it */
gdImageDestroy(im);
... inside a function ...
gdImagePtr im;
int black;
int white;
im = gdImageCreate(100, 50);
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0);
/* Allocate the color white (red, green and blue all maximum). */
white = gdImageColorAllocate(im, 255, 255, 255);
/* Inscribe a filled ellipse in the image. */
gdImageFilledEllipse(im, 50, 25, 98, 48, white);
/* ... Do something with the image, such as
saving it to a file... */
/* Destroy it */
gdImageDestroy(im);
color
, beginning at the specified point and stopping at
the specified border
color. For a way of flooding an
area defined by the color of the starting point, see
gdImageFill.
... inside a function ...
gdImagePtr im;
int black;
int white;
int red;
im = gdImageCreate(100, 50);
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0);
/* Allocate the color white (red, green and blue all maximum). */
white = gdImageColorAllocate(im, 255, 255, 255);
/* Allocate the color red. */
red = gdImageColorAllocate(im, 255, 0, 0);
/* Inscribe an ellipse in the image. */
gdImageArc(im, 50, 25, 98, 48, 0, 360, white);
/* Flood-fill the ellipse. Fill color is red, border color is
white (ellipse). */
gdImageFillToBorder(im, 50, 50, white, red);
/* ... Do something with the image, such as
saving it to a file... */
/* Destroy it */
gdImageDestroy(im);
color
, beginning at the specified point and flooding the
surrounding region of the same color as the starting point.
For a way of flooding a region defined by a specific border
color rather than by its interior color, see
gdImageFillToBorder.
... inside a function ...
gdImagePtr im;
int black;
int white;
int red;
im = gdImageCreate(100, 50);
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0);
/* Allocate the color white (red, green and blue all maximum). */
white = gdImageColorAllocate(im, 255, 255, 255);
/* Allocate the color red. */
red = gdImageColorAllocate(im, 255, 0, 0);
/* Inscribe an ellipse in the image. */
gdImageArc(im, 50, 25, 98, 48, 0, 360, white);
/* Flood-fill the ellipse. Fill color is red, and will replace the
black interior of the ellipse. */
gdImageFill(im, 50, 50, red);
/* ... Do something with the image, such as
saving it to a file... */
/* Destroy it */
gdImageDestroy(im);
... inside a function ...
gdImagePtr im, brush;
int black;
int blue;
im = gdImageCreate(100, 100);
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0);
blue = gdImageColorAllocate(im, 0, 0, 255);
gdImageSetAntiAliased(im, blue);
/* Draw a smooth line from the upper left corner to the
lower right corner. */
gdImageLine(im, 0, 0, 99, 99, gdAntiAliased);
/* ... Do something with the image, such as
saving it to a file... */
/* Destroy it */
gdImageDestroy(im);
See also gdAntiAliased and
gdSetAntiAliasedDontBlend.
... inside a function ...
gdImagePtr im, brush;
int black;
int blue;
int white;
im = gdImageCreate(100, 100);
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0);
blue = gdImageColorAllocate(im, 0, 0, 255);
white = gdImageColorAllocate(im, 255, 255, 255);
gdImageSetAntiAliased(im, blue);
/* The portion of the line that crosses this white rectangle will
not be blended smoothly */
gdImageSetAntiAliasedDontBlend(im, white);
gdImageFilledRectangle(im, 25, 25, 75, 75, white);
/* Draw a smooth line from the upper left corner
to the lower right corner. */
gdImageLine(im, 0, 0, 99, 99, gdAntiAliased);
/* ... Do something with the image, such as
saving it to a file... */
/* Destroy it */
gdImageDestroy(im);
See also gdAntiAliased and
gdSetAntiAliased.
... inside a function ...
gdImagePtr im, brush;
FILE *in;
int black;
im = gdImageCreate(100, 100);
/* Open the brush PNG. For best results, portions of the
brush that should be transparent (ie, not part of the
brush shape) should have the transparent color index. */
in = fopen("star.png", "rb");
brush = gdImageCreateFromPng(in);
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0);
gdImageSetBrush(im, brush);
/* Draw a line from the upper left corner to the lower right corner
using the brush. */
gdImageLine(im, 0, 0, 99, 99, gdBrushed);
/* ... Do something with the image, such as
saving it to a file... */
/* Destroy it */
gdImageDestroy(im);
/* Destroy the brush image */
gdImageDestroy(brush);
... inside a function ...
gdImagePtr im, tile;
FILE *in;
int black;
im = gdImageCreate(100, 100);
/* Open the tile PNG. For best results, portions of the
tile that should be transparent (ie, allowing the
background to shine through) should have the transparent
color index. */
in = fopen("star.png", "rb");
tile = gdImageCreateFromPng(in);
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0);
gdImageSetTile(im, tile);
/* Fill an area using the tile. */
gdImageFilledRectangle(im, 25, 25, 75, 75, gdTiled);
/* ... Do something with the image, such as
saving it to a file... */
/* Destroy it */
gdImageDestroy(im);
/* Destroy the tile image */
gdImageDestroy(tile);
gdImagePtr im;
int styleDotted[2], styleDashed[6];
FILE *in;
int black;
int red;
im = gdImageCreate(100, 100);
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0);
red = gdImageColorAllocate(im, 255, 0, 0);
/* Set up dotted style. Leave every other pixel alone. */
styleDotted[0] = red;
styleDotted[1] = gdTransparent;
/* Set up dashed style. Three on, three off. */
styleDashed[0] = red;
styleDashed[1] = red;
styleDashed[2] = red;
styleDashed[3] = gdTransparent;
styleDashed[4] = gdTransparent;
styleDashed[5] = gdTransparent;
/* Set dotted style. Note that we have to specify how many pixels are
in the style! */
gdImageSetStyle(im, styleDotted, 2);
/* Draw a line from the upper left corner to the lower right corner. */
gdImageLine(im, 0, 0, 99, 99, gdStyled);
/* Now the dashed line. */
gdImageSetStyle(im, styleDashed, 6);
gdImageLine(im, 0, 99, 0, 99, gdStyled);
/* ... Do something with the image, such as
saving it to a file ... */
/* Destroy it */
gdImageDestroy(im);
... inside a function ...
gdImagePtr im;
int black;
int white;
im = gdImageCreate(100, 100);
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0);
/* Allocate the color white (red, green and blue all maximum). */
white = gdImageColorAllocate(im, 255, 255, 255);
/* Set thickness. */
gdImageSetThickness(im, 4);
/* Draw a fat line from the upper left corner to the lower right corner. */
gdImageLine(im, 0, 0, 99, 99, white);
/* ... Do something with the image, such as
saving it to a file... */
/* Destroy it */
gdImageDestroy(im);
gdImagePtr im;
int red, blue;
im = gdImageCreateTrueColor(100, 100);
/* Background color */
red = gdTrueColor(255, 0, 0);
gdImageFilledRectangle(im, 0, 0, 100, 100, red);
/* Drawing color. Full transparency would be an alpha channel value
of 127 (gd has a 7 bit alpha chnanel). 0 is opaque,
127 is transparent. So cut gdAlphaTransparent in half to get
50% blending. */
blue = gdTrueColorAlpha(0, 0, 255, gdAlphaTransparent / 2);
/* Draw with blending. Result will be 50% red, 50% blue: yellow
(emitted light, remember, not reflected light. What you learned
in Kindergarten is wrong here). */
gdImageAlphaBlending(im, 1);
gdImageFilledRectangle(im, 0, 0, 25, 25, blue);
/* Draw without blending. Result will be 50% blue, 50%
the background color of the image viewer or web browser
used; results in browsers that don't support
semi-transparent pixels are unpredictable! */
gdImageAlphaBlending(im, 0);
gdImageFilledRectangle(im, 75, 75, 25, 25, blue);
/* Write the image to disk, etc. */
... inside a function ...
gdImagePtr im;
int black;
int white;
im = gdImageCreate(100, 100);
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0);
/* Allocate the color white (red, green and blue all maximum). */
white = gdImageColorAllocate(im, 255, 255, 255);
/* Set the clipping rectangle. */
gdImageSetClip(im, 25, 25, 75, 75);
/* Draw a line from the upper left corner to the lower right corner.
Only the part within the clipping rectangle will appear. */
gdImageLine(im, 0, 0, 99, 99, white);
/* ... Do something with the image, such as
saving it to a file ... */
/* Destroy it */
gdImageDestroy(im);
See also gdImageGetClip.
... Inside a function ...
gdImagePtr im = gdImageCreateTrueColor(100, 100);
int x1, y1, x2, y2;
gdImageSetClip(im, 25, 25, 75, 75);
gdImageGetClip(im, &x1, &y1, &x2, &y2);
printf("%d %d %d %d\n", x1, y1, x2, y2);
The above code would print:
25 25 75 75
See also gdImageSetClip.
Query Functions
... inside a function ...
FILE *in;
gdImagePtr im;
int c;
in = fopen("mypng.png", "rb");
im = gdImageCreateFromPng(in);
fclose(in);
c = gdImageGetPixel(im, gdImageSX(im) / 2, gdImageSY(im) / 2);
printf("The value of the center pixel is %d; RGB values are %d,%d,%d\n",
c, im->red[c], im->green[c], im->blue[c]);
gdImageDestroy(im);
... inside a function ...
gdImagePtr im;
int black;
int white;
im = gdImageCreate(100, 100);
if (gdImageBoundsSafe(im, 50, 50)) {
printf("50, 50 is within the image bounds\n");
} else {
printf("50, 50 is outside the image bounds\n");
}
gdImageDestroy(im);
Fonts and text-handling functions
gdfonts.h
before
calling this function. Under Windows, due to the nature of DLLs,
the use of this function is strongly recommended rather than attempting
to use the gdFontSmall
pointer directly. (You may
safely assign the result to a local gdFontPtr
variable
in your own code.)
gdfontl.h
before
calling this function. Under Windows, due to the nature of DLLs,
the use of this function is strongly recommended rather than attempting
to use the gdFontLarge
pointer directly. (You may
safely assign the result to a local gdFontPtr
variable
in your own code.)
gdfontmb.h
before
calling this function. Under Windows, due to the nature of DLLs,
the use of this function is strongly recommended rather than attempting
to use the gdFontMediumBold
pointer directly. (You may
safely assign the result to a local gdFontPtr
variable
in your own code.)
gdfontg.h
before
calling this function. Under Windows, due to the nature of DLLs,
the use of this function is strongly recommended rather than attempting
to use the gdFontGiant
pointer directly. (You may
safely assign the result to a local gdFontPtr
variable
in your own code.)
gdfontt.h
before
calling this function. Under Windows, due to the nature of DLLs,
the use of this function is strongly recommended rather than attempting
to use the gdFontTiny
pointer directly. (You may
safely assign the result to a local gdFontPtr
variable
in your own code.)
Windows DLL users: although you can use
these DLL-exported pointers directly, you cannot easily assign them to other
pointers. This will cause hard-to-debug problems. To avoid such troubles, you
should call the functions gdFontGetTiny(), gdFontGetSmall(),
gdFontGetMediumBold(), gdFontGetLarge(), and gdFontGetGiant() in order to
obtain pointers to the fonts under Windows.
#include "gd.h"
#include "gdfontl.h"
... inside a function ...
gdImagePtr im;
int black;
int white;
im = gdImageCreate(100, 100);
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0);
/* Allocate the color white (red, green and blue all maximum). */
white = gdImageColorAllocate(im, 255, 255, 255);
/* Draw a character. */
gdImageChar(im, gdFontGetLarge(), 0, 0, 'Q', white);
/* ... Do something with the image, such as
saving it to a file... */
/* Destroy it */
gdImageDestroy(im);
Windows DLL users: although you can use
these DLL-exported pointers directly, you cannot easily assign them to other
pointers. This will cause hard-to-debug problems. To avoid such troubles, you
should call the functions gdFontGetTiny(), gdFontGetSmall(),
gdFontGetMediumBold(), gdFontGetLarge(), and gdFontGetGiant() in order to
obtain pointers to the fonts under Windows.
#include "gd.h"
#include "gdfontl.h"
... inside a function ...
gdImagePtr im;
int black;
int white;
im = gdImageCreate(100, 100);
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0);
/* Allocate the color white (red, green and blue all maximum). */
white = gdImageColorAllocate(im, 255, 255, 255);
/* Draw a character upwards so it rests against the top of the image. */
gdImageCharUp(im, gdFontGetLarge(),
0, gdFontGetLarge()->h, 'Q', white);
/* ... Do something with the image, such as
saving it to a file... */
/* Destroy it */
gdImageDestroy(im);
Windows DLL users: although you can use
these DLL-exported pointers directly, you cannot easily assign them to other
pointers. This will cause hard-to-debug problems. To avoid such troubles, you
should call the functions gdFontGetTiny(), gdFontGetSmall(),
gdFontGetMediumBold(), gdFontGetLarge(), and gdFontGetGiant() in order to
obtain pointers to the fonts under Windows.
The null-terminated C string specified
by the fifth argument is drawn from left to right in the specified
color. (See gdImageStringUp for a way
of drawing vertical text.
See also gdImageStringFT for a high
quality solution.)
Pixels not set by a particular character retain their previous color.
#include "gd.h"
#include "gdfontl.h"
#include <string.h>
... inside a function ...
gdImagePtr im;
int black;
int white;
/* String to draw. */
char *s = "Hello.";
im = gdImageCreate(100, 100);
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0);
/* Allocate the color white (red, green and blue all maximum). */
white = gdImageColorAllocate(im, 255, 255, 255);
/* Draw a centered string. */
gdImageString(im, gdFontGetLarge(),
im->sx / 2 - (strlen(s) * gdFontGetLarge()->w / 2),
im->sy / 2 - gdFontGetLarge()->h / 2,
s, white);
/* ... Do something with the image, such as
saving it to a file... */
/* Destroy it */
gdImageDestroy(im);
Windows DLL users: although you can use
these DLL-exported pointers directly, you cannot easily assign them to other
pointers. This will cause hard-to-debug problems. To avoid such troubles, you
should call the functions gdFontGetTiny(), gdFontGetSmall(),
gdFontGetMediumBold(), gdFontGetLarge(), and gdFontGetGiant() in order to
obtain pointers to the fonts under Windows.
The null-terminated string of characters represented as 16-bit unsigned
short integers specified by the fifth argument is drawn from left to right
in the specified
color. (See gdImageStringUp16 for a way
of drawing vertical text.) Pixels not
set by a particular character retain their previous color.
Windows DLL users: although you can use
these DLL-exported pointers directly, you cannot easily assign them to other
pointers. This will cause hard-to-debug problems. To avoid such troubles, you
should call the functions gdFontGetTiny(), gdFontGetSmall(),
gdFontGetMediumBold(), gdFontGetLarge(), and gdFontGetGiant() in order to
obtain pointers to the fonts under Windows.
The null-terminated C string specified
by the fifth argument is drawn from bottom to top (rotated
90 degrees) in the specified color. (See
gdImageString for a way
of drawing horizontal text.) Pixels not
set by a particular character retain their previous color.
#include "gd.h"
#include "gdfontl.h"
#include <string.h>
... inside a function ...
gdImagePtr im;
int black;
int white;
/* String to draw. */
char *s = "Hello.";
im = gdImageCreate(100, 100);
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0);
/* Allocate the color white (red, green and blue all maximum). */
white = gdImageColorAllocate(im, 255, 255, 255);
/* Draw a centered string going upwards. Axes are reversed,
and Y axis is decreasing as the string is drawn. */
gdImageStringUp(im, gdFontGetLarge(),
im->w / 2 - gdFontGetLarge()->h / 2,
im->h / 2 + (strlen(s) * gdFontGetLarge()->w / 2),
s, white);
/* ... Do something with the image, such as
saving it to a file... */
/* Destroy it */
gdImageDestroy(im);
Windows DLL users: although you can use
these DLL-exported pointers directly, you cannot easily assign them to other
pointers. This will cause hard-to-debug problems. To avoid such troubles, you
should call the functions gdFontGetTiny(), gdFontGetSmall(),
gdFontGetMediumBold(), gdFontGetLarge(), and gdFontGetGiant() in order to
obtain pointers to the fonts under Windows.
The null-terminated string of characters represented as 16-bit unsigned
short integers specified by the fifth argument is drawn from bottom to top
in the specified color.
(See gdImageStringUp16 for a way
of drawing horizontal text.) Pixels not
set by a particular character retain their previous color.
#include "gd.h"
#include <string.h>
... inside a function ...
gdImagePtr im;
int black;
int white;
int brect[8];
int x, y;
char *err;
char *s = "Hello."; /* String to draw. */
double sz = 40.;
char *fc = "times:bold:italic"; /* fontconfig pattern */
/* Signal that all freetype font calls in this program will receive
fontconfig patterns rather than filenames of font files */
gdUseFontConfig(1);
/* obtain brect so that we can size the image */
err = gdImageStringFT(NULL,&brect[0],0,fc,sz,0.,0,0,s);
if (err) {fprintf(stderr,err); return 1;}
/* create an image big enough for the string plus a little whitespace */
x = brect[2]-brect[6] + 6;
y = brect[3]-brect[7] + 6;
im = gdImageCreate(x,y);
/* Background color (first allocated) */
white = gdImageColorResolve(im, 255, 255, 255);
black = gdImageColorResolve(im, 0, 0, 0);
/* render the string, offset origin to center string*/
/* note that we use top-left coordinate for adjustment
* since gd origin is in top-left with y increasing downwards. */
x = 3 - brect[6];
y = 3 - brect[7];
err = gdImageStringFT(im,&brect[0],black,fc,sz,0.0,x,y,s);
if (err) {fprintf(stderr,err); return 1;}
0
lower left corner, X position 1
lower left corner, Y position 2
lower right corner, X position 3
lower right corner, Y position 4
upper right corner, X position 5
upper right corner, Y position 6
upper left corner, X position 7
upper left corner, Y position
#include "gd.h"
#include <string.h>
... inside a function ...
gdImagePtr im;
int black;
int white;
int brect[8];
int x, y;
char *err;
char *s = "Hello."; /* String to draw. */
double sz = 40.;
char *f = "/usr/local/share/ttf/Times.ttf"; /* User supplied font */
/* obtain brect so that we can size the image */
err = gdImageStringFT(NULL,&brect[0],0,f,sz,0.,0,0,s);
if (err) {fprintf(stderr,err); return 1;}
/* create an image big enough for the string plus a little whitespace */
x = brect[2]-brect[6] + 6;
y = brect[3]-brect[7] + 6;
im = gdImageCreate(x,y);
/* Background color (first allocated) */
white = gdImageColorResolve(im, 255, 255, 255);
black = gdImageColorResolve(im, 0, 0, 0);
/* render the string, offset origin to center string*/
/* note that we use top-left coordinate for adjustment
* since gd origin is in top-left with y increasing downwards. */
x = 3 - brect[6];
y = 3 - brect[7];
err = gdImageStringFT(im,&brect[0],black,f,sz,0.0,x,y,s);
if (err) {fprintf(stderr,err); return 1;}
/* Write img to stdout */
gdImagePng(im, stdout);
/* Destroy it */
gdImageDestroy(im);
See also gdImageStringFTEx.
strex
parameter is not null, it must point to a
gdFTStringExtra
structure. As of gd 2.0.5, this structure
is defined as follows:
typedef struct {
/* logical OR of gdFTEX_ values */
int flags;
/* fine tune line spacing for '\n' */
double linespacing;
/* Preferred character mapping */
int charmap;
/* Rendering resolution */
int hdpi;
int vdpi;
char *xshow;
char *fontpath;
} gdFTStringExtra, *gdFTStringExtraPtr;
To output multiline text with a specific line spacing,
include gdFTEX_LINESPACE
in the setting of
flags
:
flags |= gdFTEX_LINESPACE;
And also set linespacing
to the desired spacing, expressed as a
multiple of the font height. Thus a line spacing of 1.0 is the
minimum to guarantee that lines of text do not collide.
gdFTEX_LINESPACE
is not present, or
strex
is null, or gdImageStringFT
is called, linespacing
defaults to 1.05.
gdFTEX_CHARMAP
in the setting of
flags
:
flags |= gdFTEX_CHARMAP;
And set charmap
to the desired value, which can be
any of gdFTEX_Unicode, gdFTEX_Shift_JIS, or gdFTEX_Big5. If you do not
specify a preference, Unicode will be tried first. If the preferred
character mapping is not found in the font, other character mappings
are attempted.
gdFTEX_RESOLUTION
to flags
:
flags | gdFTEX_RESOLUTION;
GD 2.0.29 and later will normally attempt to apply kerning tables, if
fontconfig is available, to adjust the relative positions of consecutive
characters more ideally for that pair of characters. This can be turn off by
specifying the gdFTEX_DISABLE_KERNING flag:
flags | gdFTEX_DISABLE_KERNING;
GD 2.0.29 and later can return a vector of individual character
position advances, occasionally useful in applications that must know
exactly where each character begins. This is returned in the xshow
element of the gdFTStringExtra structure if the gdFTEX_XSHOW
flag is set:
flags | gdFTEX_XSHOW;
The caller is responsible for calling gdFree() on the xshow
element after the call if gdFTEX_XSHOW is set.
flags | gdFTEX_RETURNFONTPATHNAME;
The caller is responsible for calling gdFree() on the fontpath
element after the call if gdFTEX_RETURNFONTPATHNAME is set.
flags | gdFTEX_FONTPATHNAME;
flags | gdFTEX_FONTCONFIG;
GD 2.0.29 and above can use fontconfig to resolve
font names, including fontconfig patterns, if the gdFTEX_FONTCONFIG
flag is set. As a convenience, this behavior can be made the default
by calling gdFTUseFontConfig with
a nonzero value. In that situation it is not necessary to set the
gdFTEX_FONTCONFIG flag on every call; however explicit font path names
can still be used if the gdFTEX_FONTPATHNAME flag is set:
flags | gdFTEX_FONTPATHNAME;
For more information, see gdImageStringFT.
top
and bottom
on im
, curved along the edge of a circle of radius
radius
, with its center at cx
and cy
.
top
is written clockwise
along the top; bottom
is written counterclockwise
along the bottom. textRadius
determines the "height"
of each character; if textRadius
is 1/2 of
radius
,
characters extend halfway from the edge to the center.
fillPortion
varies from 0 to 1.0, with useful values
from about 0.4 to 0.9, and determines how much of the
180 degrees of arc assigned to each section of text
is actually occupied by text; 0.9 looks better than
1.0 which is rather crowded. font
is a freetype
font; see gdImageStringFT. points
is passed to the
freetype engine and has an effect on hinting; although
the size of the text is determined by radius
,
textRadius
, and fillPortion
, you should
pass a point size that
"hints" appropriately -- if you know the text will be
large, pass a large point size such as 24.0 to get the
best results. fgcolor
can be any color, and may have
an alpha component, do blending, etc.
#include <stdio.h>
#include <gd.h>
int main (int argc, char *argv[])
{
FILE *in;
FILE *out;
gdImagePtr im;
int radius;
/* Create an image of text on a circle, with an
alpha channel so that we can copy it onto a
background */
in = fopen("mypicture.jpg", "rb");
if (!in) {
im = gdImageCreateTrueColor(300, 300);
} else {
im = gdImageCreateFromJpeg(in);
fclose(in);
}
if (gdImageSX(im) < gdImageSY(im)) {
radius = gdImageSX(im) / 2;
} else {
radius = gdImageSY(im) / 2;
}
gdStringFTCircle(
im,
gdImageSX(im) / 2,
gdImageSY(im) / 2,
radius,
radius / 2,
0.8,
"arial",
24,
"top text",
"bottom text",
gdTrueColorAlpha(240, 240, 255, 32));
out = fopen("gdfx.png", "wb");
if (!out) {
fprintf(stderr, "Can't create gdfx.png\n");
return 1;
}
gdImagePng(im, out);
fclose(out);
gdImageDestroy(im);
return 0;
}
Color-handling functions
... inside a function ...
gdImagePtr im;
int black;
int red;
im = gdImageCreate(100, 100);
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0);
/* Allocate the color red. */
red = gdImageColorAllocate(im, 255, 0, 0);
/* Draw a dashed line from the upper left corner
to the lower right corner. */
gdImageDashedLine(im, 0, 0, 99, 99, red);
/* ... Do something with the image, such as saving
it to a file... */
/* Destroy it */
gdImageDestroy(im);
... inside a function ...
gdImagePtr im;
int black;
int red;
im = gdImageCreate(100, 100);
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0);
/* Allocate the color red, 50% transparent. */
red = gdImageColorAllocateAlpha(im, 255, 0, 0, 64);
/* Draw a dashed line from the upper left corner to the lower right corner. */
gdImageDashedLine(im, 0, 0, 99, 99, red);
/* ... Do something with the image, such as
saving it to a file... */
/* Destroy it */
gdImageDestroy(im);
... inside a function ...
gdImagePtr im;
FILE *in;
int red;
/* Let's suppose that photo.png is a scanned photograph with
many colors. */
in = fopen("photo.png", "rb");
im = gdImageCreateFromPng(in);
fclose(in);
/* Try to allocate red directly */
red = gdImageColorAllocate(im, 255, 0, 0);
/* If we fail to allocate red... */
if (red == (-1)) {
/* Find the closest color instead. */
red = gdImageColorClosest(im, 255, 0, 0);
}
/* Draw a dashed line from the upper left corner to the lower right corner */
gdImageDashedLine(im, 0, 0, 99, 99, red);
/* ... Do something with the image, such as
saving it to a file... */
/* Destroy it */
gdImageDestroy(im);
... inside a function ...
gdImagePtr im;
FILE *in;
int red;
/* Let's suppose that photo.png is a scanned photograph with
many colors. */
in = fopen("photo.png", "rb");
im = gdImageCreateFromPng(in);
fclose(in);
/* Try to allocate red, 50% transparent, directly */
red = gdImageColorAllocateAlpha(im, 255, 0, 0, 64);
/* If we fail to allocate red... */
if (red == (-1)) {
/* Find the closest color instead. */
red = gdImageColorClosestAlpha(im, 255, 0, 0, 64);
}
/* Draw a dashed line from the upper left corner to the lower right corner */
gdImageDashedLine(im, 0, 0, 99, 99, red);
/* ... Do something with the image, such as
saving it to a file... */
/* Destroy it */
gdImageDestroy(im);
... inside a function ...
gdImagePtr im;
FILE *in;
int red;
/* Let's suppose that photo.png is a scanned photograph with
many colors. */
in = fopen("photo.png", "rb");
im = gdImageCreateFromPng(in);
fclose(in);
/* Try to allocate red directly */
red = gdImageColorAllocate(im, 255, 0, 0);
/* If we fail to allocate red... */
if (red == (-1)) {
/* Find the closest color instead. */
red = gdImageColorClosestHWB(im, 255, 0, 0);
}
/* Draw a dashed line from the upper left corner to the lower right corner */
gdImageDashedLine(im, 0, 0, 99, 99, red);
/* ... Do something with the image, such as
saving it to a file... */
/* Destroy it */
gdImageDestroy(im);
... inside a function ...
gdImagePtr im;
int red;
in = fopen("photo.png", "rb");
im = gdImageCreateFromPng(in);
fclose(in);
/* The image may already contain red; if it does, we'll save a slot
in the color table by using that color. */
/* Try to allocate red directly */
red = gdImageColorExact(im, 255, 0, 0);
/* If red isn't already present... */
if (red == (-1)) {
/* Second best: try to allocate it directly. */
red = gdImageColorAllocate(im, 255, 0, 0);
/* Out of colors, so find the closest color instead. */
red = gdImageColorClosest(im, 255, 0, 0);
}
/* Draw a dashed line from the upper left corner to the lower right corner */
gdImageDashedLine(im, 0, 0, 99, 99, red);
/* ... Do something with the image, such as
saving it to a file... */
/* Destroy it */
gdImageDestroy(im);
... inside a function ...
gdImagePtr im;
int red;
in = fopen("photo.png", "rb");
im = gdImageCreateFromPng(in);
fclose(in);
/* The image may already contain red; if it does, we'll save a slot
in the color table by using that color. */
/* Get index of red, or color closest to red */
red = gdImageColorResolve(im, 255, 0, 0);
/* Draw a dashed line from the upper left corner to the lower right corner */
gdImageDashedLine(im, 0, 0, 99, 99, red);
/* ... Do something with the image, such as
saving it to a file... */
/* Destroy it */
gdImageDestroy(im);
... inside a function ...
gdImagePtr im;
int red;
in = fopen("photo.png", "rb");
im = gdImageCreateFromPng(in);
fclose(in);
/* The image may already contain red; if it does,
we'll save a slot in the color table by using that color. */
/* Get index of red, 50% transparent, or the next best thing */
red = gdImageColorResolveAlpha(im, 255, 0, 0, 64);
/* Draw a dashed line from the upper left corner to the lower right corner */
gdImageDashedLine(im, 0, 0, 99, 99, red);
/* ... Do something with the image, such as saving
it to a file... */
/* Destroy it */
gdImageDestroy(im);
... inside a function ...
gdImagePtr im;
int red, blue;
in = fopen("photo.png", "rb");
im = gdImageCreateFromPng(in);
fclose(in);
/* Look for red in the color table. */
red = gdImageColorExact(im, 255, 0, 0);
/* If red is present... */
if (red != (-1)) {
/* Deallocate it. */
gdImageColorDeallocate(im, red);
/* Allocate blue, reusing slot in table.
Existing red pixels will change color. */
blue = gdImageColorAllocate(im, 0, 0, 255);
}
/* ... Do something with the image, such as
saving it to a file... */
/* Destroy it */
gdImageDestroy(im);
... inside a function ...
gdImagePtr im;
int black;
FILE *in, *out;
in = fopen("photo.png", "rb");
im = gdImageCreateFromPng(in);
fclose(in);
/* Look for black in the color table and make it transparent. */
black = gdImageColorExact(im, 0, 0, 0);
/* If black is present... */
if (black != (-1)) {
/* Make it transparent */
gdImageColorTransparent(im, black);
}
/* Save the newly-transparent image back to the file */
out = fopen("photo.png", "wb");
gdImagePng(im, out);
fclose(out);
/* Destroy it */
gdImageDestroy(im);
Copying and resizing functions
dst
argument is the destination image to which the
region will be copied. The src
argument is the source
image from which the region is copied. The dstX
and dstY
arguments specify the point in the destination
image to which the region will be copied. The srcX
and srcY
arguments specify the upper left corner
of the region in the source image. The w
and h
arguments specify the width and height
of the region.
... Inside a function ...
gdImagePtr im_in;
gdImagePtr im_out;
int x, y;
FILE *in;
FILE *out;
/* Load a small png to tile the larger one with */
in = fopen("small.png", "rb");
im_in = gdImageCreateFromPng(in);
fclose(in);
/* Make the output image four times as large on both axes */
im_out = gdImageCreate(im_in->sx * 4, im_in->sy * 4);
/* Now tile the larger image using the smaller one */
for (y = 0; (y < 4); y++) {
for (x = 0; (x < 4); x++) {
gdImageCopy(im_out, im_in,
x * im_in->sx, y * im_in->sy,
0, 0,
im_in->sx, im_in->sy);
}
}
out = fopen("tiled.png", "wb");
gdImagePng(im_out, out);
fclose(out);
gdImageDestroy(im_in);
gdImageDestroy(im_out);
dst
argument is the destination image to which the
region will be copied. The src
argument is the source
image from which the region is copied. The dstX
and dstY
arguments specify the point in the destination
image to which the region will be copied. The srcX
and srcY
arguments specify the upper left corner
of the region in the source image. The dstW
and dstH
arguments specify the width and height
of the destination region. The srcW
and srcH
arguments specify the width and height
of the source region and can differ from the destination size,
allowing a region to be scaled during the copying process.
... Inside a function ...
gdImagePtr im_in;
gdImagePtr im_out;
int x, y;
FILE *in;
FILE *out;
/* Load a small png to expand in the larger one */
in = fopen("small.png", "rb");
im_in = gdImageCreateFromPng(in);
fclose(in);
/* Make the output image four times as large on both axes */
im_out = gdImageCreate(im_in->sx * 4, im_in->sy * 4);
/* Now copy the smaller image, but four times larger */
gdImageCopyResized(im_out, im_in, 0, 0, 0, 0,
im_out->sx, im_out->sy,
im_in->sx, im_in->sy);
out = fopen("large.png", "wb");
gdImagePng(im_out, out);
fclose(out);
gdImageDestroy(im_in);
gdImageDestroy(im_out);
dst
argument is the destination image to which the
region will be copied. The src
argument is the source
image from which the region is copied. The dstX
and dstY
arguments specify the point in the destination
image to which the region will be copied. The srcX
and srcY
arguments specify the upper left corner
of the region in the source image. The dstW
and dstH
arguments specify the width and height
of the destination region. The srcW
and srcH
arguments specify the width and height
of the source region and can differ from the destination size,
allowing a region to be scaled during the copying process.
... Inside a function ...
gdImagePtr im_in;
gdImagePtr im_out;
int x, y;
FILE *in;
FILE *out;
/* Load a large png to shrink in the smaller one */
in = fopen("large.png", "rb");
im_in = gdImageCreateFromPng(in);
fclose(in);
/* Make the output image four times as small on both axes. Use
a true color image so that we can interpolate colors. */
im_out = gdImageCreateTrueColor(im_in->sx / 4, im_in->sy / 4);
/* Now copy the large image, but four times smaller */
gdImageCopyResampled(im_out, im_in, 0, 0, 0, 0,
im_out->sx, im_out->sy,
im_in->sx, im_in->sy);
out = fopen("large.png", "wb");
gdImagePng(im_out, out);
fclose(out);
gdImageDestroy(im_in);
gdImageDestroy(im_out);
... Inside a function ...
gdImagePtr im_in;
gdImagePtr im_out;
int x, y;
int a;
FILE *in;
FILE *out;
/* Load a small png to rotate in the larger one */
in = fopen("small.png", "rb");
im_in = gdImageCreateFromPng(in);
fclose(in);
/* Make the output image four times as large on both axes */
im_out = gdImageCreate(im_in->sx * 4, im_in->sy * 4);
/* Now rotate the smaller image */
for (a = 0; (a < 360); a += 45) {
double x = cos(a * .0174532925) * gdImageSX(im_out) / 2;
double y = -sin(a * .0174532925) * gdImageSY(im_out) / 2;
gdImageCopyRotated(im_out, im_in,
gdImageSX(im_out) / 2 + x,
gdImageSY(im_out) / 2 + y,
0, 0,
gdImageSX(im_in),
gdImageSY(im_in),
a);
}
out = fopen("large.png", "wb");
gdImagePng(im_out, out);
fclose(out);
gdImageDestroy(im_in);
gdImageDestroy(im_out);
... Inside a function ...
gdImageCopyMerge(im_out, im_in, 100, 200, 0, 0, 30, 50, 50);
... Inside a function ...
gdImageCopyMergeGray(im_out, im_in, 100, 200, 0, 0, 30, 50, 50);
Miscellaneous Functions
... Inside a function ...
cmpMask = gdImageCompare(im1, im2);
gdImagePtr im;
FILE *out;
/* ... Create or load the image... */
/* Now turn on interlace */
gdImageInterlace(im, 1);
/* And open an output file */
out = fopen("test.png", "wb");
/* And save the image -- could also use gdImageJpeg */
gdImagePng(im, out);
fclose(out);
gdImageDestroy(im);
free()
that is ultimately called will
be intended for use with the version of malloc()
that
originally allocated the block.
Constants
gdMaxColors
(CONSTANT)
About the additional .gd image file format
In addition to reading and writing the PNG and JPEG formats and reading the
X Bitmap format, gd has the capability to read and write its
own ".gd" format. This format is not intended for
general purpose use and should never be used to distribute
images. It is not a compressed format. Its purpose is solely to
allow very fast loading of images your program needs often in
order to build other images for output. If you are experiencing
performance problems when loading large, fixed PNG images your
program needs to produce its output images, you may wish
to examine the functions
gdImageCreateFromGd and gdImageGd,
which read and write .gd format images.
About the .gd2 image file format
In addition to reading and writing the PNG format and reading the
X Bitmap format, gd has the capability to read and write its
own ".gd2" format. This format is not intended for
general purpose use and should never be used to distribute
images. It is a compressed format allowing pseudo-random access
to large image files. Its purpose is solely to
allow very fast loading of parts of images
If you are experiencing
performance problems when loading large, fixed PNG or JPEG images your
program needs to produce its output images, you may wish
to examine the functions
gdImageCreateFromGd2,
gdImageCreateFromGd2Part and gdImageGd2,
which read and write .gd2 format images.
About the gdIOCtx structure
Version 1.5 of GD added a new style of I/O based on an IOCtx
structure (the most up-to-date version can be found in gd_io.h):
typedef struct gdIOCtx {
int (*getC)(struct gdIOCtx*);
int (*getBuf)(struct gdIOCtx*, void*, int);
void (*putC)(struct gdIOCtx*, int);
int (*putBuf)(struct gdIOCtx*, const void*, int);
int (*seek)(struct gdIOCtx*, const int); /* Returns 1 on SUCCESS */
long (*tell)(struct gdIOCtx*);
void (*free)(struct gdIOCtx*);
} gdIOCtx;
Most functions that accepted files in previous versions now also have a
counterpart that accepts an I/O context. These functions have a 'Ctx'
suffix.
All Must have 'free', Anything that reads from the context Must have 'getC' and 'getBuf', Anything that writes to the context Must have 'putC' and 'putBuf'. If gdCreateFromGd2Part is called Must also have 'seek' and 'tell'. Note: seek must return 1 on SUCCESS and 0 on FAILURE. If gdImageGd2 is called Must also have 'seek' and 'tell'. Please tell us you're using gd!
When you contact us and let us know you are using gd,
you help us justify the time spent in maintaining and improving
it. So please let us know. If the results are publicly
visible on the web, a URL is a wonderful thing to receive, but
if it's not a publicly visible project, a simple note is just
as welcome.
How do I get support?
Free Support
Anyone can mail questions about the gd library to
Thomas Boutell. However,
I receive a very large volume of email on
many subjects, and while I do my best to respond to all queries this can
take some time. Sometimes the response must take the form of an eventual
new release or an addition to a FAQ or other document, as opposed to an
detailed individual response.
Hourly Support
Those requiring support in detail may arrange for direct support
from the author, Thomas Boutell, at the rate of $50/hr, billed
directly by credit card. Purchase orders are also accepted from
Fortune 500 corporations and institutions in good standing.
To make arrangements, contact
Boutell.Com support. To avoid delay
and/or confusion, be sure to specifically mention that you wish to
purchase gd support at the hourly rate above.
Alphabetical quick index
gdAntiAliased |
gdBrushed |
gdDashSize |
gdFont |
gdFontGetHuge |
gdFontGetLarge |
gdFontGetMediumBold |
gdFontGetSmall |
gdFontGetTiny |
gdFontCacheSetup |
gdFontCacheShutdown |
gdFontPtr |
gdFree |
gdImage |
gdImageAlphaBlending |
gdImageArc |
gdImageBlue |
gdImageBoundsSafe |
gdImageChar |
gdImageCharUp |
gdImageColorAllocate |
gdImageColorAllocateAlpha |
gdImageColorClosest |
gdImageColorClosestAlpha |
gdImageColorClosestHWB |
gdImageColorDeallocate |
gdImageColorExact |
gdImageColorExactAlpha |
gdImageColorResolve |
gdImageColorResolveAlpha |
gdImageColorTransparent |
gdImageCopy |
gdImageCopyMerge |
gdImageMergeGray |
gdImageCopyResized |
gdImageCopyResampled |
gdImageCopyRotated |
gdImageCreate |
gdImageCreatePalette |
gdImageCreateTrueColor |
gdImageCreateFromGd |
gdImageCreateFromGdCtx |
gdImageCreateFromGdPtr |
gdImageCreateFromGd2 |
gdImageCreateFromGd2Ctx |
gdImageCreateFromGd2Ptr |
gdImageCreateFromGd2Part |
gdImageCreateFromGd2PartCtx |
gdImageCreateFromGd2PartPtr |
gdImageCreateFromJpeg |
gdImageCreateFromJpegCtx |
gdImageCreateFromJpegPtr |
gdImageCreateFromPng |
gdImageCreateFromPngCtx |
gdImageCreateFromPngPtr |
gdImageCreateFromPngSource |
gdImageCreateFromWBMP |
gdImageCreateFromWBMPCtx |
gdImageCreateFromWBMPPtr |
gdImageCreateFromXbm |
gdImageCreateFromXpm |
gdImageDashedLine |
gdImageDestroy |
gdImageFill |
gdImageFilledArc |
gdImageFilledEllipse |
gdImageFillToBorder |
gdImageFilledRectangle |
gdImageGd |
gdImageGd2 |
gdImageGetInterlaced |
gdImageGetPixel |
gdImageGetTransparent |
gdImageGifAnimAdd |
gdImageGifAnimAddCtx |
gdImageGifAnimAddPtr |
gdImageGifAnimBegin |
gdImageGifAnimBeginCtx |
gdImageGifAnimBeginPtr |
gdImageGifAnimEnd |
gdImageGifAnimEndCtx |
gdImageGifAnimEndPtr |
gdImageGreen |
gdImageInterlace |
gdImageJpeg |
gdImageJpegCtx |
gdImageLine |
gdImageFilledPolygon |
gdImageOpenPolygon |
gdImagePaletteCopy |
gdImagePng |
gdImagePngEx |
gdImagePngCtx |
gdImagePngCtxEx |
gdImagePngPtr |
gdImagePngPtrEx |
gdImagePngToSink |
gdImagePolygon |
gdImagePtr |
gdImageWBMP |
gdImageWBMPCtx |
gdImageRectangle |
gdImageRed |
gdImageSaveAlpha |
gdImageSetAntiAliased |
gdImageSetAntiAliasedDontBlend |
gdImageSetBrush |
gdImageSetPixel |
gdImageSetStyle |
gdImageSetThickness |
gdImageSetTile |
gdImageSharpen |
gdImageSquareToCircle |
gdImageString |
gdImageString16 |
gdImageStringFT |
gdImageStringFTCircle |
gdImageStringFTEx |
gdImageStringTTF |
gdImageStringUp |
gdImageStringUp16 |
gdImageToPalette |
gdImageWBMP |
gdMaxColors |
gdPoint |
gdStyled |
gdStyledBrushed |
gdTiled |
gdTransparent