HEY! READ THIS! gd 2.0.4 creates PNG, JPEG and WBMP images, not GIF images. This is a good thing. PNG is a more compact format, and full compression is available. JPEG works best with photographic images, and is still more compatible with the major Web browsers than even PNG is. WBMP is intended for wireless devices (not regular web browsers). Old code will need modification to call gdImagePng or gdImageJpeg instead of gdImageGif. Please do not ask us to send you the old GIF version of GD. Unisys holds a patent on the LZW compression algorithm, which is used in fully compressed GIF images. The best solution is to move to legally unencumbered, well-compressed, modern image formats such as PNG and JPEG as soon as possible.gd 2.0.4 requires that the following libraries also be installed, in order to produce the related image formats:
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.his not found. Do not send email asking whylibgd.sois not found, either. See the requirements section for more information. Thank you!
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 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 by Boutell.Com, Inc.
Portions relating to GD2 format copyright 1999, 2000, 2001, 2002 Philip Warner.
Portions relating to PNG copyright 1999, 2000, 2001, 2002 Greg Roelofs.
Portions relating to gdttf.c copyright 1999, 2000, 2001, 2002 John Ellson (ellson@lucent.com).
Portions relating to gdft.c copyright 2001, 2002 John Ellson (ellson@lucent.com).
Portions relating to JPEG and to color quantization copyright 2000, 2001, 2002, Doug Becker and copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 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 WBMP copyright 2000, 2001, 2002 Maurice Szmurlo and Johan Van den Brande.
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 gd 2.0.4, the authors wish to thank David Koblas, David Rowley, and Hutchison Avenue Software Corporation for their prior contributions.
END OF COPYRIGHT STATEMENT
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.4.
What's new in version 2.0.4?
The following contributions from John Ellson:
configure now correctly detects and provides
support for the Xpm library and its dependencies (Len Makin)
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.
--prefix option to configure
works properly.
annotate utility has been added. This is a
very handy tool for adding freetype text to existing JPEGs. After
make install, type annotate -h for more
information. Thanks to Joel Dubiner.
readme.jpn file.
pixels array
will fail only if it encounters an existing truecolor image, which may
happen if the code attempts to open and modify an existing JPEG or
truecolor PNG. Such code should be modified to check the
trueColor flag of the gdImage structure, and
refer to the tpixels array instead when it is set.
#include <gd.h> corrected to #include "gd.h" in gd_wbmp.c
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:
autoconf and configure have been removed, in favor of a
carefully designed Makefile which produces and properly installs
the library and the binaries. System-dependent variables are
at the top of the Makefile for easy modification. I'm sorry,
folks, but autoconf generated many, many confused email
messages from people who didn't have things where autoconf
expected to find them. I am not an autoconf/automake wizard, and
gd is a simple, very compact library which does not need to
be a shared library. I did make many improvements
over the old gd 1.3 Makefile, which were directly inspired by the
autoconf version found in the 1.6 series (thanks to John Ellson).
-pedantic-errors
flag of gcc. Several pieces of not-quite-ANSI-C code were causing problems
for those with non-gcc compilers.
gdttf.c patched to allow the use of Windows symbol
fonts, when present (thanks to Joseph Peppin).
extern "C" wrappers added to gd.h and the
font header files for the convenience of C++ programmers.
bdftogd was also modified to automatically insert these
wrappers into future font header files. Thanks to John Lindal.
SEEK_SET.
Thanks to Robert Bonomi.
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 web site.
libpng is available for a variety of platforms from
the PNG web site.
You will also want a PNG viewer, if you do not already have
one for your system, since you will need a good way to check the
results of your work. Netscape 4.04 and higher, and Microsoft
Internet Explorer 4.0 or higher, both support PNG.
Not every PNG-compatible viewer supports alpha channel
transparency, which is why gd 2.0.2 and above do alpha
blending in the library by default; it is possible to turn on the
saving of alpha channel information to the file instead.
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.4".
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 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, edit the Makefile again or customize 'configure',
paying special attention to the INCLUDEDIRS and LIBDIRS settings.
IF YOU GET LINKER ERRORS, TRY JUGGLING THE ORDER OF THE -l DIRECTIVES
IN THE MAKEFILE. Some platforms may prefer that the libraries be listed
in the opposite order. If you find such a platform where
linking does not work properly, plese send the correct linking
commands to gd@boutell.com.
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 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.
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 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.
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.
Better yet, 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.
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.)
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).
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 FreeType's DEFAULT_FONTPATH variable have been set intelligently.
The string may be arbitrarily scaled (ptsize) and rotated (angle in radians).
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 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.
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.
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?
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.4 directory and type:
./configure
configure again.
For Windows
Create a project using your favorite programming environment.
Copy all of the gd files to the project directory. Add gd.c
to your project. Add other source files as appropriate. Learning the
basic skills of creating projects with your chosen C environment
is up to you. Alternatively, use the free mingw32
or cygwin tools, which may prove to be compatible
with the provided configure script.
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;
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);
gdImageCreateFromJpegCtx(FILE *in)
(FUNCTION)
gdImageCreateFromJpegCtx(FILE *in)
(FUNCTION)
gdImagePtr im;
... inside a function ...
FILE *in;
in = fopen("myjpeg.jpg", "rb");
im = gdImageCreateFromJpeg(in);
fclose(in);
/* ... Use the image ... */
gdImageDestroy(im);
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;
}
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);
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);
gdImageCreateFromGd2PartCtx(gdIOCtx *in)
(FUNCTION)
... 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);
... 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);
-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);
... 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);
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;
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);
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. */
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
#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, gdFontLarge, 0, 0, 'Q', white);
/* ... Do something with the image, such as saving it to a file... */
/* Destroy it */
gdImageDestroy(im);
#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, gdFontLarge,
0, gdFontLarge->h, 'Q', white);
/* ... Do something with the image, such as saving it to a file... */
/* Destroy it */
gdImageDestroy(im);
#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, gdFontLarge,
im->w / 2 - (strlen(s) * gdFontLarge->w / 2),
im->h / 2 - gdFontLarge->h / 2,
s, white);
/* ... Do something with the image, such as saving it to a file... */
/* Destroy it */
gdImageDestroy(im);
#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, gdFontLarge,
im->w / 2 - gdFontLarge->h / 2,
im->h / 2 + (strlen(s) * gdFontLarge->w / 2),
s, white);
/* ... Do something with the image, such as saving it to a file... */
/* Destroy it */
gdImageDestroy(im);
0
lower left corner, X position
lower left corner, Y position
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);
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 ...
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);
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'. 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
boutell@boutell.com. 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
support@boutell.com. 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
gdBrushed |
gdDashSize |
gdFont |
gdFontPtr |
gdFree |
gdImage |
gdImageAlphaBlending |
gdImageArc |
gdImageBlue |
gdImageBoundsSafe |
gdImageChar |
gdImageCharUp |
gdImageColorAllocate |
gdImageColorAllocateAlpha |
gdImageColorClosest |
gdImageColorClosestAlpha |
gdImageColorDeallocate |
gdImageColorExact |
gdImageColorExactAlpha |
gdImageColorResolve |
gdImageColorResolveAlpha |
gdImageColorTransparent |
gdImageCopy |
gdImageCopyMerge |
gdImageMergeGray |
gdImageCopyResized |
gdImageCopyResampled |
gdImageCreate |
gdImageCreatePalette |
gdImageCreateTrueColor |
gdImageCreateFromGd |
gdImageCreateFromGd2 |
gdImageCreateFromGd2Part |
gdImageCreateFromJpeg |
gdImageCreateFromPng |
gdImageCreateFromPngSource |
gdImageCreateFromXbm |
gdImageCreateFromXpm |
gdImageDashedLine |
gdImageDestroy |
gdImageFill |
gdImageFilledArc |
gdImageFilledEllipse |
gdImageFillToBorder |
gdImageFilledRectangle |
gdImageGd |
gdImageGd2 |
gdImageGetInterlaced |
gdImageGetPixel |
gdImageGetTransparent |
gdImageGreen |
gdImageInterlace |
gdImageJpeg |
gdImageLine |
gdImageFilledPolygon |
gdImagePaletteCopy |
gdImagePng |
gdImagePngToSink |
gdImagePolygon |
gdImagePtr |
gdImageWBMP |
gdImageRectangle |
gdImageRed |
gdImageSaveAlpha |
gdImageSetBrush |
gdImageSetPixel |
gdImageSetStyle |
gdImageSetTile |
gdImageString |
gdImageString16 |
gdImageStringFT |
gdImageStringTTF |
gdImageStringUp |
gdImageStringUp16 |
gdImageToPalette |
gdImageWBMP |
gdMaxColors |
gdPoint |
gdStyled |
gdStyledBrushed |
gdTiled |
gdTransparent