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.36 requires that the following libraries also be installed, in order to produce the related image formats. The win32 binary release (bgd) already contains the appropriate libraries. You may skip libraries associated with formats you do not use:
libpng (see the libpng home page), if you want PNG
zlib (see the info-zip home page), if you want PNG
jpeg-6b or later, if desired (see the Independent JPEG Group home page), if you want JPEG
If you want to use the TrueType font support, you must also install the FreeType 2.x library, including the header files. See the Freetype Home Page, or SourceForge. No, I cannot explain why that site is down on a particular day, and no, I can't send you a copy.
If you want to use the Xpm color bitmap loading support, you must also have the X Window System and the Xpm library installed (Xpm is often included in modern X distributions). Most of the time you won't need Xpm.
Please read the documentation and install the required libraries. Do not send email asking why
png.his not found. Do not send email asking whylibgd.sois not found, either. See the requirements section for more information. Thank you!
In order to resolve any possible confusion regarding the authorship of gd, the following copyright statement covers all of the authors who have required such a statement. If you are aware of any oversights in this copyright notice, please contact Pierre-A. Joye who will be pleased to correct them.
COPYRIGHT STATEMENT FOLLOWS THIS LINE
Portions copyright 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004 by Cold Spring Harbor Laboratory. Funded under Grant P41-RR02188 by the National Institutes of Health.Portions copyright 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004 by Boutell.Com, Inc.
Portions relating to GD2 format copyright 1999, 2000, 2001, 2002, 2003, 2004 Philip Warner.
Portions relating to PNG copyright 1999, 2000, 2001, 2002, 2003, 2004 Greg Roelofs.
Portions relating to gdttf.c copyright 1999, 2000, 2001, 2002, 2003, 2004 John Ellson (ellson@graphviz.org).
Portions relating to gdft.c copyright 2001, 2002, 2003, 2004 John Ellson (ellson@graphviz.org).
Portions copyright 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Pierre-Alain Joye (pierre@libgd.org).
Portions relating to JPEG and to color quantization copyright 2000, 2001, 2002, 2003, 2004, Doug Becker and copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004 Thomas G. Lane. This software is based in part on the work of the Independent JPEG Group. See the file README-JPEG.TXT for more information.
Portions relating to GIF compression copyright 1989 by Jef Poskanzer and David Rowley, with modifications for thread safety by Thomas Boutell.
Portions relating to GIF decompression copyright 1990, 1991, 1993 by David Koblas, with modifications for thread safety by Thomas Boutell.
Portions relating to WBMP copyright 2000, 2001, 2002, 2003, 2004 Maurice Szmurlo and Johan Van den Brande.
Portions relating to GIF animations copyright 2004 Jaakko Hyvätti (jaakko.hyvatti@iki.fi)
Permission has been granted to copy, distribute and modify gd in any context without fee, including a commercial application, provided that this notice is present in user-accessible supporting documentation.
This does not affect your ownership of the derived work itself, and the intent is to assure proper credit for the authors of gd, not to interfere with your productive use of gd. If you have questions, ask. "Derived works" includes all programs that utilize the library. Credit must be given in user-accessible documentation.
This software is provided "AS IS." The copyright holders disclaim all warranties, either express or implied, including but not limited to implied warranties of merchantability and fitness for a particular purpose, with respect to this code and accompanying documentation.
Although their code does not appear in the current release, the authors also wish to thank Hutchison Avenue Software Corporation for their prior contributions.
END OF COPYRIGHT STATEMENT
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.
Please see the NEWS file, the releases announcements and the ChangeLog for
the changes in the releases after 2.0.34.
From 2.0.34 and later, please check the ISSUES and ChangeLog as well as
the releases announcements.
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.
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.
The following enhancements and fixes:
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).
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
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.
Version 2.0.7 corrects a problem which caused 'configure' to complain
that the directory NONE was not found, in various places, causing
the configuration process to stop. There are no code changes.
What's new in version 2.0.34?
What's new in version 2.0.33?
What's new in version 2.0.32?
What's new in version 2.0.31?
What's new in version 2.0.30?
What's new in version 2.0.29?
What's new in version 2.0.28?
What's new in version 2.0.27?
What's new in version 2.0.26?
gdlib-config, which has been installed by
make install for some time now, has gained
a --features option. This option produces a space-separated
list of optional features with which the gd library was compiled.
Typical usage looks like this:
% gdlib-config --features
GD_XPM GD_JPEG GD_FREETYPE GD_PNG GD_GIF
Other configure scripts can conveniently define
preprocessor symbols based on this list in order to conditionally
compile code. For instance, if
GD_PNG is not reported by --features, then gdImagePng is not
included in the library.
What's new in version 2.0.25?
What's new in version 2.0.24?
What's new in version 2.0.23?
gdFTStringExtra structure, thanks to
Mark Shackelford. See gdImageStringFTEx.
What's new in version 2.0.22?
gdFontPtr.
Direct use of gdFontLarge, etc. is strongly deprecated
for users of bgd.dll; use these new functions instead.
circletexttest if
PNG support is missing.
What's new in version 2.0.21?
gdImageCreateFrom*Ptr family
of functions which make it convenient to load an image in any
GD-supported format directly from memory.
gdNewDynamicCtxEx function was added to
support the easy implementation of the above functions and to
correct a design problem which made life unpleasant for those passing
in memory not originally allocated by gd to the
gdNewDynamicCtx function by provoding a way to specify
that gd should never free or reallocate a particular block of memory.
The gdNewDynamicCtx function and its relatives, although
still exported for ABI compatibility, are now deprecated except
for internal use, in favor of gdImageCreateFromPngPtr
and its relatives.
gdFreeFontCache function,
an undocumented function added in an earlier release which now simply
calls gdFontCacheShutdown for backwards compatibility.
This repairs build problems when compiling PHP against the latest gd.
What's new in version 2.0.20?
gdFreeFontCache function,
an undocumented function added in an earlier release which now simply
calls gdFontCacheShutdown for backwards compatibility.
This repairs build problems when compiling PHP against the latest gd.
What's new in version 2.0.19?
extern declarations for the
gd font pointers inadvertently removed in 2.0.18.
What's new in version 2.0.18?
What's new in version 2.0.17?
What's new in version 2.0.16?
What's new in version 2.0.15?
What's new in version 2.0.14?
What's new in version 2.0.13?
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.
What's new in version 2.0.12?
gd2 file format routines
were fixed by Steven Brown. These problems were due to the
incorrect use of a signed integer.
gd file format correctly
for truecolor images. Truecolor gd files created with
earlier releases in the 2.0 series must be written again. The gd
file format is used to quickly load an entire uncompressed image, typically
an existing background to which additional material will be added; it is not a
general purpose file format. More advanced capabilities are also available
via the gd2 format. Thanks to Andreas Pfaller for reporting
the problem.
What's new in version 2.0.11?
configure improvements by Lars Hecking.
What's new in version 2.0.10?
What's new in version 2.0.9?
configure fixes from Lars Hecking. Thanks, Lars.
What's new in version 2.0.8?
What's new in version 2.0.7?
What's new in version 2.0.6?
-Wall, -ansi
and -pedantic options enabled.
What's new in version 2.0.5?
configure time using this syntax:
./configure --prefix=/usr
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.
What's new in version 2.0.4?
The following contributions from John Ellson:
And the following additional fixes:
configure now correctly detects and provides
support for the Xpm library and its dependencies (Len Makin)
What's new in version 2.0.3?
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.
What's new in version 2.0.2?
What's new in version 2.0.1?
readme.jpn file.
What's new in version 2.0?
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.
What's new in version 1.8.4?
What's new in version 1.8.3?
#include <gd.h> corrected to #include "gd.h" in gd_wbmp.c
What's new in version 1.8.2?
What's new in version 1.8.1?
What's new in version 1.8?
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/.
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.
gdtestttf.c. Thanks to Masahito Yamaga.
autoconf and configure have been removed, in favor of a
carefully designed Makefile which produces and properly installs
the library and the binaries. System-dependent variables are
at the top of the Makefile for easy modification. I'm sorry,
folks, but autoconf generated many, many confused email
messages from people who didn't have things where autoconf
expected to find them. I am not an autoconf/automake wizard, and
gd is a simple, very compact library which does not need to
be a shared library. I did make many improvements
over the old gd 1.3 Makefile, which were directly inspired by the
autoconf version found in the 1.6 series (thanks to John Ellson).
-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.
if ((color=gdImageColorExact(im,R,G,B)) < 0)
if ((color=gdImageColorAllocate(im,R,G,B)) < 0)
color=gdImageColorClosest(im,R,G,B);
Also in this release the build process has been converted to GNU autoconf/automake/libtool conventions so that both (or either) static and shared libraries can be built.
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.
pixels array will require
changes.
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.
Win32 DLL users: if you are using MSVC, use the provided batch file
makemsvcimport.bat to make a bgd.lib import library
corresponding to the provided bgd.dll. Copy bgd.dll to your
application directory, or to your Windows sytem directory. In the
settings of your MSVC project, you MUST choose the
"multithreaded DLL" library option under "code generation."
mingw32 and cygwin users can simply link with the provided libbgd.a
stub library in order to use the DLL.
Building gd From the Source
In order to build gd, you must first unpack the archive you have
downloaded. If you are not familiar with tar and
gunzip (Unix) or ZIP (Windows), please
consult with an experienced user of your system. Sorry, we cannot
answer questions about basic Internet skills.
Unpacking the archive will produce a directory called "gd-2.0.33".
cd to the 2.0.33 directory and type:
./configure
NOTE: BY DEFAULT, THE LIBRARY IS INSTALLED IN/usr/local/liband the include files are installed in/usr/local/include. IF YOU ARE UPGRADING, you may wish to use:./configure --prefix=/usrRather than just./configure, before typingmakeandmake install.
If all goes well, this will create a Makefile. If all does not go well --
for instance, if neither the the JPEG nor the PNG and ZLIB libraries
are found -- you will need to install those libraries, then come back
and run configure again.
If necessary, make changes to the resulting Makefile. Then, type "make". If there are no errors, follow this with "make install". Because gd 2.0 and above installs as a shared library, it is necessary to install the library properly before running gd-based programs.
If you get errors, type ./configure --help for more
information about the available options. In the unlikely event
that the GNU autoconf-produced configure script does not work well
for you, you may wish to try configure.pl, a
simple Perl script with similar but less complete capabilities.
If all else fails, try renaming makefile.sample
to Makefile. However, ./configure is
almost always your best bet.
For Windows
Use the DLL version! See the paragraph at the beginning of this sectino. If you really want to compile it yourself for some strange reason, read on.Create a project using your favorite programming environment. Copy all of the gd files to the project directory. Add
gd.cto 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 freemingw32orcygwintools, which may prove to be compatible with the providedconfigurescript.
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.
-lgd -lpng -lz -ljpeg -lfreetype -lmAssuming that all of these libraries are available.
If you want to use the provided simple fonts, include gdfontt.h, gdfonts.h, gdfontmb.h, gdfontl.h and/or gdfontg.h. For more impressive results, install FreeType 2.x and use the gdImageStringFT function. If you are not using the provided Makefile and/or a library-based approach, be sure to include the source modules as well in your project. (They may be too large for 16-bit memory models, that is, 16-bit DOS and Windows.)
Here is a short example program. (For a more advanced example, see gddemo.c, included in the distribution. gddemo.c is NOT the same program; it demonstrates additional features!)
/* Bring in gd library functions */
#include "gd.h"
/* Bring in standard I/O so we can output the PNG to a file */
#include <stdio.h>
int main() {
/* Declare the image */
gdImagePtr im;
/* Declare output files */
FILE *pngout, *jpegout;
/* Declare color indexes */
int black;
int white;
/* Allocate the image: 64 pixels across by 64 pixels tall */
im = gdImageCreate(64, 64);
/* Allocate the color black (red, green and blue all minimum).
Since this is the first color in a new image, it will
be the background color. */
black = gdImageColorAllocate(im, 0, 0, 0);
/* Allocate the color white (red, green and blue all maximum). */
white = gdImageColorAllocate(im, 255, 255, 255);
/* Draw a line from the upper left to the lower right,
using white color index. */
gdImageLine(im, 0, 0, 63, 63, white);
/* Open a file for writing. "wb" means "write binary", important
under MSDOS, harmless under Unix. */
pngout = fopen("test.png", "wb");
/* Do the same for a JPEG-format file. */
jpegout = fopen("test.jpg", "wb");
/* Output the image to the disk file in PNG format. */
gdImagePng(im, pngout);
/* Output the same image in JPEG format, using the default
JPEG quality setting. */
gdImageJpeg(im, jpegout, -1);
/* Close the files. */
fclose(pngout);
fclose(jpegout);
/* Destroy the image in memory. */
gdImageDestroy(im);
}
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.
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.
gdImage(TYPE)
pixels
or tpixels arrays. If the trueColor flag
is set, the tpixels array is valid; otherwise the
pixels array is valid.
The colorsTotal, red, green,
blue, alpha and open arrays
manage the palette. They are valid only when the trueColor
flag is not set.
The transparent value contains the palette index of the first
transparent color as read-only information for backwards compatibility;
gd 2.0 stores this information in the alpha array so that
variable transparency can be supported for each palette entry. However,
for truecolor images, transparent represents a single
RGB color which is always 100% transparent, and this
feature is generally supported by browsers which do not support
full alpha channels.
typedef struct {
/* Palette-based image pixels */
unsigned char ** pixels;
int sx;
int sy;
/* These are valid in palette images only. See also
/* 'alpha', which appears later in the structure to
preserve binary backwards compatibility */
int colorsTotal;
int red[gdMaxColors];
int green[gdMaxColors];
int blue[gdMaxColors];
int open[gdMaxColors];
/* For backwards compatibility, this is set to the
first palette entry with 100% transparency,
and is also set and reset by the
gdImageColorTransparent function. Newer
applications can allocate palette entries
with any desired level of transparency; however,
bear in mind that many viewers, notably
many web browsers, fail to implement
full alpha channel for PNG and provide
support for full opacity or transparency only. */
int transparent;
int *polyInts;
int polyAllocated;
struct gdImageStruct *brush;
struct gdImageStruct *tile;
int brushColorMap[gdMaxColors];
int tileColorMap[gdMaxColors];
int styleLength;
int stylePos;
int *style;
int interlace;
/* New in 2.0: alpha channel for palettes. Note that only
Macintosh Internet Explorer and (possibly) Netscape 6
really support multiple levels of transparency in
palettes, to my knowledge, as of 2/15/01. Most
common browsers will display 100% opaque and
100% transparent correctly, and do something
unpredictable and/or undesirable for levels
in between. TBB */
int alpha[gdMaxColors];
/* Truecolor flag and pixels. New 2.0 fields appear here at the
end to minimize breakage of existing object code. */
int trueColor;
int ** tpixels;
/* Should alpha channel be copied, or applied, each time a
pixel is drawn? This applies to truecolor images only.
No attempt is made to alpha-blend in palette images,
even if semitransparent palette entries exist.
To do that, build your image as a truecolor image,
then quantize down to 8 bits. */
int alphaBlendingFlag;
/* Should the alpha channel of the image be saved? This affects
PNG at the moment; other future formats may also
have that capability. JPEG doesn't. */
int saveAlphaFlag;
} gdImage;
The order of the structure members may appear confusing, but was chosen deliberately to increase backwards compatibility with existing gd 1.x-based binary code that references particular structure members.
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.
... inside a function ... gdImagePtr im; im = gdImageCreate(64, 64); /* ... Use the image ... */ gdImageDestroy(im);
Truecolor images are always filled with black at creation time. There is no concept of a "background" color index.
... inside a function ... gdImagePtr im; im = gdImageCreateTrueColor(64, 64); /* ... Use the image ... */ gdImageDestroy(im);
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.
gdImagePtr im;
... inside a function ...
FILE *in;
in = fopen("myjpeg.jpg", "rb");
im = gdImageCreateFromJpeg(in);
fclose(in);
/* ... Use the image ... */
gdImageDestroy(im);
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.
gdImagePtr im;
... inside a function ...
FILE *in;
in = fopen("mypng.png", "rb");
im = gdImageCreateFromPng(in);
fclose(in);
/* ... Use the image ... */
gdImageDestroy(im);
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
-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.
The example below implements gdImageCreateFromPng by creating a custom data source and invoking gdImageCreateFromPngSource.
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;
}
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.
gdImagePtr im;
... inside a function ...
FILE *in;
in = fopen("mygif.gif", "rb");
im = gdImageCreateFromGif(in);
fclose(in);
/* ... Use the image ... */
gdImageDestroy(im);
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().
... inside a function ...
gdImagePtr im;
FILE *in;
in = fopen("mygd.gd", "rb");
im = gdImageCreateFromGd(in);
fclose(in);
/* ... Use the image ... */
gdImageDestroy(im);
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().
... inside a function ...
gdImagePtr im;
FILE *in;
in = fopen("mygd.gd2", "rb");
im = gdImageCreateFromGd2(in);
fclose(in);
/* ... Use the image ... */
gdImageDestroy(im);
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.
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);
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.
... 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);
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.
... 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);
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.
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.
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.
... 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);
... 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);
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
-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.
The example below implements gdImagePng by creating a custom data source and invoking gdImagePngFromSink.
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);
}
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."
... 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);
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.
... 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);
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.
... 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);
gdImageCreatePaletteFromTrueColor returns a new image. gdImageTrueColorToPalette permanently converts the existing image. The two functions are otherwise identical.
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.
... 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);
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.
... 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:
... 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.
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.)
... 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.
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.)
... 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);
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.
... 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.
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.
... 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);
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.
... 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);
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).
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. */
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.
... 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 75See also gdImageSetClip.
... 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);
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.)
See gdImageString for more information and examples, or gdImageStringFT for a freetype-based alternative that supports truetype fonts.
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.)
See gdImageString for more information and examples, or gdImageStringFT for a freetype-based alternative that supports truetype fonts.
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.)
See gdImageString for more information and examples, or gdImageStringFT for a freetype-based alternative that supports truetype fonts.
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.)
See gdImageString for more information and examples, or gdImageStringFT for a freetype-based alternative that supports truetype fonts.
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.)
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.
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 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.
#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.
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.
#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.
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.
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.
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.
#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;}
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).
| 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 |
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.
#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.
If the 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.
If gdFTEX_LINESPACE is not present, or
strex is null, or gdImageStringFT
is called, linespacing defaults to 1.05.
To specify a preference for Unicode, Shift_JIS Big5 character encoding,
set or To output multiline text with a specific line spacing,
include 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, gdFTEX_Big5, or gdFTEX_Adobe_Custom.
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.
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 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.
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.
flags | gdFTEX_RETURNFONTPATHNAME;The caller is responsible for calling gdFree() on the fontpath element after the call if gdFTEX_RETURNFONTPATHNAME is set.
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:
flags | gdFTEX_FONTPATHNAME;
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:
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.
Returns 0 on success, or an error string otherwise.
#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;
}
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.
... 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);
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.
... 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);
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.
... 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);
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.
... 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);
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.
... 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);
When applied to a truecolor image, this function always succeeds in returning the desired color.
... 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);
When applied to a truecolor image, this function always succeeds in returning the desired color.
... 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);
When applied to a truecolor image, this function always succeeds in returning the desired color.
... 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);
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.
... 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);
The 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.
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.
... 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);
The 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.
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.
... 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);
Pixel values are only interpolated if the destination image is a truecolor image. Otherwise, gdImageCopyResized is automatically invoked.
The 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.
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.
... 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);
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.
... 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);
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:
... 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);
... Inside a function ... cmpMask = gdImageCompare(im1, im2);
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.
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.
gdMaxColors(CONSTANT)
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.
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.
The <xxx>Ctx routines use the function pointers in the I/O context pointed to by gdIOCtx to perform all I/O. Examples of how to implement an I/O context can be found in io_file.c (which provides a wrapper for file routines), and io_dp.c (which implements in-memory storage).
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:
| 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'. |