3607 lines
156 KiB
HTML
3607 lines
156 KiB
HTML
<HTML>
|
|
<HEAD>
|
|
<TITLE>gd 2.0.1</TITLE>
|
|
</HEAD>
|
|
<BODY>
|
|
<!-- BANNER HERE -->
|
|
<h1>This is gd 2.0.1 BETA.</h1>
|
|
<strong>If you have problems, report them
|
|
in detail, and consider using gd 1.8.4 until gd 2.0 final is out.</strong>
|
|
<p>
|
|
The gd 2.0 documentation update is not complete, but most new features
|
|
are documented to some degree and the what's new section is reasonably
|
|
complete. Enjoy!
|
|
<H2>gd 2.0.1</H2>
|
|
<H3>A graphics library for fast image creation</H3>
|
|
<H3>Follow this link to the
|
|
<A HREF="http://www.boutell.com/gd/">latest version
|
|
of this document</A>.</H3>
|
|
<blockquote>
|
|
<strong>HEY! READ THIS!</strong>
|
|
gd 2.0.1 creates PNG, JPEG and WBMP images, not GIF images. This is a
|
|
good thing. PNG is a more compact format, and full compression is
|
|
available. JPEG works well with photographic images, and is still
|
|
more compatible with the major Web browsers than even PNG is. WBMP is
|
|
intended for wireless devices (not regular web browsers). Existing
|
|
code will need modification to call gdImagePng or gdImageJpeg instead
|
|
of gdImageGif. <strong>Please do not ask us to send you the old GIF
|
|
version of GD.</strong> Unisys holds a patent on the LZW compression
|
|
algorithm, which is used in fully compressed GIF images. The best
|
|
solution is to move to legally unencumbered, well-compressed,
|
|
modern image formats such as PNG and JPEG as soon as possible.
|
|
|
|
<p>
|
|
gd 2.0.1 <strong>requires</strong> that the following libraries
|
|
also be installed:
|
|
<p>
|
|
libpng (see the <a href="http://www.libpng.org/pub/png/">libpng home page</a>)
|
|
<p>
|
|
zlib (see the <a href="http://www.info-zip.org/pub/infozip/zlib/">info-zip home page</a>)
|
|
zlib
|
|
<p>
|
|
jpeg-6b or later, if desired (see the <a href="http://www.ijg.org/">Independent JPEG Group home page</a>)
|
|
<p>
|
|
If you want to use the TrueType font support, you must also
|
|
install the <strong>FreeType 2.x library</strong>, including
|
|
the header files. See the <a href="http://www.freetype.org/">Freetype
|
|
Home Page</a>, or <a href="http://freetype.sourceforge.net/">SourceForge</a>.
|
|
No, I cannot explain why that site is down on a particular day, and no, I
|
|
can't send you a copy.
|
|
<p>
|
|
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).
|
|
<p>
|
|
Please read the documentation and install the required libraries.
|
|
Do not send email asking why <code>png.h</code> is not found.
|
|
Do not send email asking why <code>libgd.so</code> is not found, either.
|
|
See the <a href="#required">requirements section</a> for more
|
|
information. Thank you!
|
|
</blockquote>
|
|
<H3>Table of Contents</H3>
|
|
<UL>
|
|
<LI><A HREF="#notice">Credits and license terms</A>
|
|
<LI><A HREF="#whatsnew2.0.1">What's new in version "XYZ" of GD?</A>
|
|
<LI><A HREF="#whatis">What is gd?</A>
|
|
<LI><A HREF="#gdother">What if I want to use another programming language?</A>
|
|
<LI><A HREF="#required">What else do I need to use gd?</A>
|
|
<LI><A HREF="#getgd">How do I get gd?</A>
|
|
<LI><A HREF="#buildgd">How do I build gd?</A>
|
|
<LI><A HREF="#basics">gd basics: using gd in your program</A>
|
|
<LI><A HREF="#webpng">webpng: a useful example</A>
|
|
<LI><A HREF="#reference">Function and type reference by category</A>
|
|
<LI><A HREF="#gdformat">About the additional .gd image file format</A>
|
|
<LI><A HREF="#informing"><strong>Please</strong>
|
|
tell us you're using gd!</A>
|
|
<LI><A HREF="#problems">If you have problems</A>
|
|
<LI><A HREF="#index">Alphabetical quick index</A>
|
|
</UL>
|
|
<P><A HREF="http://www.boutell.com/">
|
|
Up to the <EM>Boutell.Com, Inc. Home Page</EM></A>
|
|
<A NAME="notice"><H3>Credits and license terms</A></H3>
|
|
<P>
|
|
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. <strong>If you are aware of any oversights
|
|
in this copyright notice, please contact
|
|
<a href="mailto:boutell@boutell.com">Thomas Boutell</a> who will be
|
|
pleased to correct them.</strong>
|
|
<pre>
|
|
COPYRIGHT STATEMENT FOLLOWS THIS LINE
|
|
</pre>
|
|
<blockquote>
|
|
|
|
Portions copyright 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001 by Cold Spring
|
|
Harbor Laboratory. Funded under Grant P41-RR02188 by the National
|
|
Institutes of Health.
|
|
<P>
|
|
Portions copyright 1996, 1997, 1998, 1999, 2000, 2001 by Boutell.Com, Inc.
|
|
<p>
|
|
Portions relating to GD2 format copyright 1999, 2000 Philip Warner.
|
|
<p>
|
|
Portions relating to PNG copyright 1999, 2000 Greg Roelofs.
|
|
<p>
|
|
Portions relating to libttf copyright 1999, 2000 John Ellson (ellson@lucent.com).
|
|
<p>
|
|
Portions relating to JPEG and to color quantization copyright 2000, Doug
|
|
Becker and copyright (C) 1994-1998, 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.
|
|
<p>
|
|
Portions relating to WBMP copyright 2000 Maurice Szmurlo and Johan Van
|
|
den Brande.
|
|
<p>
|
|
<strong>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.</strong>
|
|
<p>
|
|
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.
|
|
<p>
|
|
<strong>This software is provided "AS IS."</strong>
|
|
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.
|
|
<p>
|
|
Although their code does not appear in gd 2.0.1, the authors wish to
|
|
thank David Koblas, David Rowley, and Hutchison Avenue Software
|
|
Corporation for their prior contributions.
|
|
</blockquote>
|
|
<pre>
|
|
END OF COPYRIGHT STATEMENT
|
|
</pre>
|
|
<A NAME="whatis"><H3>What is gd?</H3></A>
|
|
<P>
|
|
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.
|
|
<P>
|
|
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.
|
|
<P>
|
|
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.
|
|
<P>
|
|
<A NAME="gdother"><H3>What if I want to use another programming
|
|
language?</h3></A>
|
|
Not all of these tools are necessarily up to date and fully compatible
|
|
with 2.0.1.
|
|
<h4>Perl</h4>
|
|
gd can also be used from Perl, courtesy of
|
|
Lincoln Stein's
|
|
<a href="http://www-genome.wi.mit.edu/ftp/pub/software/WWW/GD.html">
|
|
GD.pm</a> library, which uses gd as the basis for a set of
|
|
Perl 5.x classes. Highly recommended.
|
|
<h4>Tcl</h4>
|
|
gd can be used from Tcl with John Ellson's
|
|
<a href=http://www.tcltk.com/ftp/ellson/>Gdtclft</a>
|
|
dynamically loaded extension package.
|
|
(Gdtclft2.0 or later is needed for gd-1.6 and up with PNG output.)
|
|
<h4>Pascal</h4>
|
|
Pascal enthusiasts should look into Michael Bradbury's
|
|
<a href="http://www.elj.com/dev/free-pascal/gdfp/">gdfp</a> package.
|
|
<h4>Haskell</h4>
|
|
A new gd interface is now available for
|
|
<a href="http://www.numeric-quest.com/haskell/gd/index.html">Haskell
|
|
programmers</a>.
|
|
<h4>REXX</h4>
|
|
A
|
|
<a href="http://www.lightlink.com/hessling/RexxGd/index.html">gd interface
|
|
for the REXX language</a> is available.
|
|
<h4>Any Language</h4>
|
|
There are, at the moment, at least three simple interpreters that
|
|
perform gd operations. You can output the desired commands to a simple
|
|
text file from whatever scripting language you prefer to use, then
|
|
invoke the interpreter.
|
|
<p>
|
|
|
|
<ul>
|
|
<li><a href="http://s27w007.pswfs.gov/tgd/">tgd</a>, by Bradley K. Sherman
|
|
<li><a href="http://www.unimelb.edu.au/fly/fly.html">fly</a>, by Martin Gleeson
|
|
</ul>
|
|
<P><A NAME="whatsnew2.0.1"><H3>What's new in version 2.0.1?</H3></A>
|
|
<ul>
|
|
<li>Workaround for a bug in gcc, apparently found in gcc 2.7.2 and up.
|
|
I reproduced and fixed it while using gcc 2.9.5.2. The bug occurred only
|
|
when the -g option was in use. This problem caused gcc to spew
|
|
internal error messages unrelated to the correctness of the code
|
|
in gd_gd2.c. Howard Jones was first to report it.
|
|
<li><a href="#gdImageFilledEllipse">gdImageFilledEllipse</a> documented
|
|
and altered; no longer requires a superfluous style argument. Thanks to
|
|
Francis James Franklin.
|
|
<li>The Makefile now offers the correct syntax for
|
|
optionally creating a static library. Thanks to Jean-Lous Regez,
|
|
among others.
|
|
<li>A nested comment, an attempt to return the value of a void function,
|
|
and a potentially significant error in gdImageCopyResampled were fixed
|
|
thanks to Joseph Shirley.
|
|
<li>A bug preventing proper truecolor text rendering was fixed,
|
|
thanks to Jason Gallagher.
|
|
<li><a href="#gdImageStringFT">gdImageStringFT</a> (FreeType) should
|
|
now work better against a transparent or semitransparent background,
|
|
and should act in a manner consistent with the most recent
|
|
<a href="#gdImageAlphaBlending">gdImageAlphaBlending</a> setting.
|
|
Antialiasing is now done via the alpha channel mechanism if the
|
|
image is a truecolor image.
|
|
<li>Bugs in the output of gdImageArc and gdImageFilledArc were reported
|
|
by Bruce Verderaime. A simple and correct but inefficient implementation
|
|
has been substituted until fixes are contributed for the faster code,
|
|
which is in gd_arc_f_buggy.c along with the test program that reproduces
|
|
the bug(s).
|
|
<li><a href="#gdImageFilledArc">gdImageFilledArc</a> now offers additional
|
|
style options, which can be combined to produce various effects.
|
|
<li>Masahito Yamaga (ma@yama-ga.com) sent a patch to improve
|
|
support for Japanese output via <a href="#gdImageStringFT">gdImageStringFT</a>.
|
|
He also added a new <code>readme.jpn</code> file.
|
|
<li>Zillions of documentation fixes.
|
|
</ul>
|
|
<P><A NAME="whatsnew2.0"><H3>What's new in version 2.0?</H3></A>
|
|
<ul>
|
|
<li><strong>Support for truecolor images!</strong> Version 2.0 can
|
|
load truecolor PNGs with no loss of color information, and almost
|
|
no loss of alpha channel information. Version 2.0 can also load
|
|
truecolor JPEGs with as little loss as possible; however, bear in
|
|
mind that JPEG is a lossy format, so repeated load/save cycles
|
|
always reduce image quality. This is not a bug. To create
|
|
a truecolor image from scratch, call the new
|
|
<a href="#gdImageCreateTrueColor">gdImageCreateTrueColor</a>
|
|
function. The <a href="#gdImageCreate">gdImageCreate</a> function
|
|
is still available to create palette images, and may also be
|
|
referred to as <a href="#gdImageCreatePalette">gdImageCreatePalette</a>.
|
|
<li><strong>Support for alpha channels!</strong> In addition to
|
|
24 bits of color information for each pixel (eight bits of
|
|
red, green, and blue respectively), version 2.0 supports
|
|
7 bits of "alpha channel" information. This is used to determine
|
|
exactly how transparent the pixel should be. There is also support
|
|
for a full 7 bits of transparency for each individual palette index
|
|
in a palette-based image. Please note that, as of this writing,
|
|
only Macintosh Internet Explorer 5.x and Mozilla/Netscape 6.x
|
|
display partial transparency properly.
|
|
<li>The new <a href="#gdImageAlphaBlending">gdImageAlphaBlending</a>
|
|
function allows for two different modes of drawing. In blending mode,
|
|
the alpha channel component of the color supplied to all drawing
|
|
functions, such as <a href="#gdImageSetPixel">gdImageSetPixel</a>,
|
|
determines how much of the underlying color should be allowed to
|
|
shine through. The resulting image is not transparent. In non-blending
|
|
mode, drawing color is copied literally with the alpha channel
|
|
information, resulting in a transparent image. Blending mode is
|
|
not available when drawing on palette images.
|
|
<li>The <a href="#gdImageCopyResampled">gdImageCopyResampled</a>
|
|
function provides "smooth" copying from a large image to a smaller
|
|
one, using a weighted average of the pixels of the source area rather
|
|
than selecting one representative pixel. This function is identical
|
|
to <a href="#gdImageCopyResized">gdImageCopyResized</a> when the
|
|
destination image is a palette image.
|
|
<li>The <a href="#gdImageTrueColorToPalette">gdImageTrueColorToPalette</a>
|
|
function converts a truecolor image to a palette image. The code for
|
|
this function was originally drawn from the Independent JPEG Group library
|
|
code, which is excellent. The code has been modified to preserve as much
|
|
alpha channel information as possible in the resulting palette, in addition
|
|
to preserving colors as well as possible. This does not work as well as
|
|
might be hoped. It is usually best to simply produce a truecolor
|
|
output image instead, which guarantees the highest output quality.
|
|
<li>A very high degree of backwards compatibility with existing
|
|
gd 1.x code has been maintained, at both the source code and binary
|
|
level. <strong>Code which directly accesses the <code>pixels</code> array
|
|
will fail only if it encounters an existing truecolor image</strong>, 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
|
|
<code>trueColor</code> flag of the <code>gdImage</code> structure, and
|
|
refer to the <code>tpixels</code> array instead when it is set.
|
|
<li>gd is now compiled and installed as a shared library. However,
|
|
gd still does not use autoconf, because I (TBB) have very limited
|
|
patience with autoconf. These days, most Unix systems provide a fairly
|
|
POSIX-standard environment, and the provided Makefile is likely to work well
|
|
if users read it and follow the instructions at the top.
|
|
<li>Support for line thickness was added by Michael Schwartz. My apologies
|
|
to him for sitting on his patches for so long. See the new
|
|
<a href="#gdImageSetThickness">gdImageSetThickness</a> function, which
|
|
affects all standard gd functions that draw lines and curves. In addition,
|
|
Michael added a convenient <a href="#gdImageEllipse">gdImageEllipse</a>
|
|
function.
|
|
<li>The new <a href="#gdImageFilledArc">gdImageFilledArc</a> function
|
|
provides a straightforward way to draw filled arcs. Also,
|
|
<a href="#gdImageFilledEllipse">gdImageFilledEllipse</a> is a
|
|
convenient way to fill an ellipse without specifying starting
|
|
and ending angles. Thanks go out to F J Franklin.
|
|
<li>To put an end to the confusion, TrueType 1.x support has been
|
|
removed in favor of TrueType 2.x support. The old
|
|
gdImageStringTTF function simply invokes gdImageStringFT.
|
|
<li>The specialized .gd and .gd2 file formats have been upgraded to support
|
|
truecolor. New images written by the versions of these functions
|
|
found in 2.0 will be rejected, with varying degrees of grace, by
|
|
older versions of gd. THIS AFFECTS THE .GD and .GD2 FORMATS ONLY. IF YOU
|
|
ARE CONFUSED BY THIS PARAGRAPH, IT PROBABLY DOESN'T APPLY TO ANYTHING
|
|
YOU WILL EVER ENCOUNTER. Since these file formats are absolutely,
|
|
positively *not* designed for distributing images, just for
|
|
preprocessing them, this should not be a big problem. gd 2.0 should
|
|
read old .gd and .gd2 files correctly.
|
|
</ul>
|
|
<P><A NAME="whatsnew1.8.4"><H3>What's new in version 1.8.4?</H3></A>
|
|
<ul>
|
|
<li>Add support for FreeType2 (John Ellson ellson@lucent.com)
|
|
<li>Add support for finding in fonts in a builtin DEFAULT_FONTPATH,
|
|
or in a path from the GDFONTPATH environment variable.
|
|
<li>remove some unused symbols to reduce compiler warnings
|
|
<li>bugfix in size comparisons in gdImageCompare
|
|
<li>REXX now mentioned
|
|
<li>All memory allocation functions are now wrapped within the
|
|
library; gdFree is exported and recommended for freeing memory
|
|
returned by the gdImage(Something)Ptr family of functions.
|
|
</ul>
|
|
<P><A NAME="whatsnew1.8.3"><H3>What's new in version 1.8.3?</H3></A>
|
|
<ul>
|
|
<li>WBMP output memory leak fixed
|
|
<li><code>#include <gd.h></code> corrected to <code>#include "gd.h"</code> in gd_wbmp.c
|
|
<li>Documented the fact that the source and output images shouldn't
|
|
match in the WBMP test except for black and white source images
|
|
</ul>
|
|
<P>
|
|
<A NAME="whatsnew1.8.2"><H3>What's new in version 1.8.2?</H3></A>
|
|
<ul>
|
|
<li>WBMP support debugged and improved by Johann Van den Brande
|
|
<li>WBMP tests added to gdtest.c by Thomas Boutell
|
|
<li>Use of platform-dependent 'install' command removed by Thomas Boutell
|
|
<li>Comments added to Makefile warning users to juggle the order of the
|
|
libraries if the linker complains; is there any portable way to do this
|
|
automatically, short of using autoconf?
|
|
<li>Documentation of <a href="#gdImageCreateFromXpm">gdImageCreateFromXpm</a>
|
|
corrected
|
|
<li>Updated links to fast-moving, always dodging libpng and zlib web sites
|
|
</ul>
|
|
<P><A NAME="whatsnew1.8.1"><H3>What's new in version 1.8.1?</H3></A>
|
|
<ul>
|
|
<li>Optional components no longer built by default (following the
|
|
documentation)
|
|
<li>JPEG code no longer requires inappropriate header files
|
|
<li>Win32 patches from Joe Gregorio
|
|
<li>16-bit font support for bdftogd, from Honza Pazdziora
|
|
</ul>
|
|
<P><A NAME="whatsnew1.8"><H3>What's new in version 1.8?</H3></A>
|
|
<ul>
|
|
<li>Support for JPEG output, courtesy of Doug Becker
|
|
<li>A link to Michael Bradbery's Pascal wrapper
|
|
<li>Support for WBMP output, courtesy of Maurice Szmurlo
|
|
<li>gdImageColorClosestHWB function based on hue, whiteness, blackness,
|
|
superior to the regular gdImageColorClosest function, courtesy
|
|
of Philip Warner
|
|
<li>License clarification: yes, you can modify gd
|
|
</ul>
|
|
<h4>Additional JPEG Information</h4>
|
|
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 <A
|
|
HREF="ftp://ftp.uu.net/graphics/jpeg/">ftp://ftp.uu.net/graphics/jpeg/</A>
|
|
(e.g., the <A
|
|
HREF="ftp://ftp.uu.net/graphics/jpeg/jpegsrc.v6b.tar.gz">jpegsrc.v6b.tar.gz</A>
|
|
file). You <strong>must</strong> use
|
|
version 6b or later of the IJG JPEG software. You might also consult
|
|
the <A HREF="http://www.faqs.org/faqs/jpeg-faq/">JPEG FAQ</A> at
|
|
<A HREF="http://www.faqs.org/faqs/jpeg-faq/">http://www.faqs.org/faqs/jpeg-faq/</A>.
|
|
<P><A NAME="whatsnew1.7.3"><H3>What's new in version 1.7.3?</H3></A>
|
|
Another attempt at Makefile fixes to permit
|
|
linking with all libraries required on platforms with order-
|
|
dependent linkers. Perhaps it will work this time.
|
|
<P><A NAME="whatsnew1.7.2"><H3>What's new in version 1.7.2?</H3></A>
|
|
An uninitialized-pointer bug in <code>gdtestttf.c</code> was corrected.
|
|
This bug caused crashes at the end of each call to gdImageStringTTF on
|
|
some platforms. Thanks to Wolfgang Haefelinger.
|
|
<p>
|
|
Documentation fixes. Thanks to Dohn Arms.
|
|
<p>
|
|
Makefile fixes to permit
|
|
linking with all libraries required on platforms with order-
|
|
dependent linkers.
|
|
<P><A NAME="whatsnew1.7.1"><H3>What's new in version 1.7.1?</H3></A>
|
|
A minor buglet in the Makefile was corrected, as well as an inaccurate
|
|
error message in <code>gdtestttf.c</code>. Thanks to Masahito Yamaga.
|
|
<P><A NAME="whatsnew1.7"><H3>What's new in version 1.7?</H3></A>
|
|
Version 1.7 contains the following changes:
|
|
<ul>
|
|
<li>Japanese language support for the TrueType functions.
|
|
Thanks to Masahito Yamaga.
|
|
<li><code>autoconf</code> and <code>configure</code> 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 <strong>many, many confused email
|
|
messages</strong> 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 <strong>did</strong> 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).
|
|
<li>Completely ANSI C compliant, according to the <code>-pedantic-errors</code>
|
|
flag of gcc. Several pieces of not-quite-ANSI-C code were causing problems
|
|
for those with non-gcc compilers.
|
|
<li><code>gdttf.c</code> patched to allow the use of Windows symbol
|
|
fonts, when present (thanks to Joseph Peppin).
|
|
<li><code>extern "C"</code> wrappers added to <code>gd.h</code> and the
|
|
font header files for the convenience of C++ programmers.
|
|
<code>bdftogd</code> was also modified to automatically insert these
|
|
wrappers into future font header files. Thanks to John Lindal.
|
|
<li>Compiles correctly on platforms that don't define <code>SEEK_SET</code>.
|
|
Thanks to Robert Bonomi.
|
|
<li>Loads Xpm images via the
|
|
<a href="#gdImageCreateFromXpm"><code>gdImageCreateFromXpm</code></a>
|
|
function, if the Xpm library is available. Thanks to Caolan McNamara.
|
|
</ul>
|
|
<P><A NAME="whatsnew1.6.3"><H3>What's new in version 1.6.3?</H3></A>
|
|
Version 1.6.3 corrects a memory leak in gd_png.c. This leak caused
|
|
a significant amount of memory to be allocated and not freed when
|
|
writing a PNG image.
|
|
<P><A NAME="whatsnew1.6.2"><H3>What's new in version 1.6.2?</H3></A>
|
|
Version 1.6.2 from John Ellson <ellson@lucent.com> adds two new functions:
|
|
<ul>
|
|
<li>gdImageStringTTF - scalable, rotatable, anti-aliased, TrueType strings using
|
|
the FreeType library, but only if libttf is found by configure.
|
|
<strong>We do not provide TrueType fonts. Obtaining them
|
|
is entirely up to you.</strong>
|
|
<li>gdImageColorResolve - an efficient alternative for the
|
|
common code fragment:
|
|
<pre>
|
|
|
|
if ((color=gdImageColorExact(im,R,G,B)) < 0)
|
|
if ((color=gdImageColorAllocate(im,R,G,B)) < 0)
|
|
color=gdImageColorClosest(im,R,G,B);
|
|
</pre>
|
|
</ul>
|
|
<p>
|
|
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.
|
|
<P><A NAME="whatsnew1.6.1"><H3>What's new in version 1.6.1?</H3></A>
|
|
Version 1.6.1 incorporates superior PNG reading and writing code
|
|
from Greg Roelofs, with minor modifications by Tom Boutell.
|
|
Specifically, I altered his code to read non-palette images
|
|
(converting them to palette images badly, by dithering them),
|
|
and to tolerate palette images with types of transparency that
|
|
gd doesn't actually support (it just ignores the advanced
|
|
transparency features). Any bugs in this area are therefore my
|
|
fault, not Greg's.
|
|
<p>
|
|
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, <strong>If you get undefined symbol errors,
|
|
be sure to check for older versions of libpng in your
|
|
library directories!</strong>
|
|
<P><A NAME="whatsnew1.6"><H3>What's new in version 1.6?</H3></A>
|
|
Version 1.6 features the following changes:
|
|
<p>
|
|
<strong>Support for 8-bit palette PNG images has been added.
|
|
Support for GIF has been removed.</strong> 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.
|
|
|
|
<P><A NAME="whatsnew1.5"><H3>What's new in version 1.5?</H3></A>
|
|
|
|
Version 1.5 featured the following changes:
|
|
|
|
<dl>
|
|
<dt><b>New GD2 format</b>
|
|
<dd> An improvement over the GD format, the GD2 format uses the zlib
|
|
compression library to compress the image in chunks. This results
|
|
in file sizes comparable to GIFs, with the ability to access parts
|
|
of large images without having to read the entire image into memory.
|
|
<p>
|
|
This format also supports version numbers and rudimentary validity
|
|
checks, so it should be more 'supportable' than the previous GD format.
|
|
<p>
|
|
<dt><b>Re-arranged source files</b>
|
|
<dd> gd.c has been broken into constituant parts: io, gif, gd, gd2 and
|
|
graphics functions are now in separate files.
|
|
<p>
|
|
<dt><b>Extended I/O capabilities.</b>
|
|
<dd> The source/sink feature has been extended to support GD2 file formats (which
|
|
require seek/tell functions), and to allow more general non-file I/O.
|
|
<p>
|
|
<dt><b>Better support for Lincoln Stein's Perl Module</b>
|
|
<dd> The new gdImage*Ptr function returns the chosen format stored in a block of memory.
|
|
This can be directly used by the GD perl module.
|
|
<p>
|
|
<dt><b>Added functions</b>
|
|
<dd>gdImageCreateFromGd2Part - allows retrieval of part of an image (good for huge images, like maps),
|
|
<br>gdImagePaletteCopy - Copies a palette from one image to another, doing it's best to match the colors in the target image to the colors in the source palette.
|
|
<br>gdImageGd2, gdImageCreateFromGd2 - Support for new format
|
|
<br>gdImageCopyMerge - Merges two images (useful to highlight part of an image)
|
|
<br>gdImageCopyMergeGray - Similar to gdImageCopyMerge, but tries to preserve source image hue.
|
|
<br>gdImagePngPtr, gdImageJpegPtr, gdImageWBMPPtr, gdImageGdPtr, gdImageGd2Ptr - return memory blocks for each type of image.
|
|
<br>gdImageCreateFromPngCtx, gdImageCreateFromGdCtx, gdImageCreateFromGd2Ctx, gdImageCreateFromGd2PartCtx - Support for new I/O context.
|
|
|
|
</dl>
|
|
|
|
<b>NOTE:</b> In fairness to Thomas Boutell, any bug/problems with any of the above features should
|
|
probably be reported to <a href=mailto:pjw@rhyme.com.au>Philip Warner</a>.
|
|
|
|
<P><A NAME="whatsnew1.4"><H3>What's new in version 1.4?</H3></A>
|
|
|
|
Version 1.4 features the following changes:
|
|
<dl>
|
|
<dt>Fixed polygon fill routine (again)
|
|
<dd>Thanks to Kirsten Schulz, version 1.4 is able to fill
|
|
numerous types of polygons that caused problems with
|
|
previous releases, including version 1.3.
|
|
<dt>Support for alternate data sources
|
|
<dd>Programmers who wish to load a GIF from something other
|
|
than a stdio FILE * stream can use the new
|
|
<a href="#gdImageCreateFromPngSource">gdImageCreateFromPngSource</a> function.
|
|
<dt>Support for alternate data destinations
|
|
<dd>Programmers who wish to write a GIF to something other
|
|
than a stdio FILE * stream can use the new
|
|
<a href="#gdImagePngToSink">gdImagePngToSink</a> function.
|
|
<dt>More tolerant when reading GIFs
|
|
<dd>
|
|
Version 1.4 does not crash when reading certain animated GIFs,
|
|
although it still only reads the first frame. Version 1.4 also has
|
|
overflow testing code to prevent crashes when reading
|
|
damaged GIFs.
|
|
</dl>
|
|
<P><A NAME="whatsnew1.3"><H3>What's new in version 1.3?</H3></A>
|
|
Version 1.3 features the following changes:
|
|
<dl>
|
|
<dt>Non-LZW-based GIF compression code
|
|
<dd>
|
|
Version 1.3 contained GIF compression code that uses simple Run Length
|
|
Encoding instead of LZW compression, while still retaining compatibility
|
|
with normal LZW-based GIF decoders (your browser will still like your GIFs).
|
|
<strong>LZW compression is patented by Unisys. We are currently reevaluating
|
|
the approach taken by gd 1.3. The current release of gd does not support
|
|
this approach. We recommend that you use the current release, and generate
|
|
PNG images.</strong> Thanks to
|
|
Hutchison Avenue Software Corporation for contributing
|
|
the RLE GIF code.
|
|
<dt>8-bit fonts, and 8-bit font support
|
|
<dd>This improves support for European languages. Thanks are due
|
|
to Honza Pazdziora <adelton@informatics.muni.cz> and also to
|
|
Jan Pazdziora <adelton@fi.muni.cz>. Also see the provided bdftogd
|
|
Perl script if you wish to convert fixed-width X11 fonts
|
|
to gd fonts.
|
|
<dt>16-bit font support (no fonts provided)
|
|
<dd>Although no such fonts are provided in the distribution,
|
|
fonts containing more than 256 characters should work if the
|
|
gdImageString16 and gdImageStringUp16 routines are used.
|
|
<dt>Improvements to the "webpng" example/utility
|
|
<dd>The "webpng" utility is now a slightly more useful application. Thanks to
|
|
Brian Dowling for this code.
|
|
<dt>Corrections to the color resolution field of GIF output
|
|
<dd>Thanks to Bruno Aureli.
|
|
<dt>Fixed polygon fills
|
|
<dd>A one-line patch for the infamous polygon fill bug, courtesy
|
|
of Jim Mason. I believe this fix is sufficient. However, if you
|
|
find a situation where polygon fills still fail to behave properly,
|
|
please send code that demonstrates the problem, <em>and</em> a fix if
|
|
you have one. Verifying the fix is important.
|
|
<dt>Row-major, not column-major
|
|
<dd>Internally, gd now represents the array of pixels as
|
|
an array of rows of pixels, rather than an array of columns
|
|
of pixels. This improves the performance of compression and
|
|
decompression routines slightly, because horizontally adjacent
|
|
pixels are now next to each other in memory. <strong>This should
|
|
not affect properly written gd applications, but applications that
|
|
directly manipulate the <code>pixels</code> array will require
|
|
changes.</strong>
|
|
</dl>
|
|
<A NAME="required"><H3>What else do I need to use gd?</H3></A>
|
|
<P>
|
|
To use gd, you will need an ANSI C compiler. <strong>All popular
|
|
Windows 95 and NT C compilers are ANSI C compliant.</strong> Any
|
|
full-ANSI-standard C compiler should be adequate. <strong>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.</strong>
|
|
<P>
|
|
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
|
|
<a href="http://www.freesoftware.com/pub/infozip/index.html">the zlib web site</a>.
|
|
libpng is available for a variety of platforms from
|
|
<a href="http://www.cdrom.com/pub/png/">the PNG web site</a>.
|
|
|
|
<P>
|
|
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.
|
|
For some purposes you might be happier with a package like
|
|
Lview Pro for Windows or xv for X. There are PNG viewers available
|
|
for every graphics-capable modern operating system, so consult
|
|
newsgroups relevant to your particular system.
|
|
<P>
|
|
<A NAME="getgd"><H3>How do I get gd?</H3></A>
|
|
<h4>By HTTP</h4>
|
|
<ul>
|
|
<li><a href="http://www.boutell.com/gd/http/gd-2.0.1.tar.gz">Gzipped Tar File (Unix)</a>
|
|
<li><a href="http://www.boutell.com/gd/http/gd-2.0.1.zip">.ZIP File (Windows)</a>
|
|
</ul>
|
|
<h4>By FTP</h4>
|
|
<ul>
|
|
<li><a href="ftp://ftp.boutell.com/pub/boutell/gd/gd-2.0.1.tar.gz">Gzipped Tar File (Unix)</a>
|
|
<li><a href="ftp://ftp.boutell.com/pub/boutell/gd/gd-2.0.1.zip">.ZIP File (Windows)</a>
|
|
</ul>
|
|
<P>
|
|
<A NAME="buildgd"><H3>How do I build gd?</H3></A>
|
|
<P>
|
|
In order to build gd, you must first unpack the archive you have
|
|
downloaded. If you are not familiar with <code>tar</code> and
|
|
<code>gunzip</code> (Unix) or <code>ZIP</code> (Windows), please
|
|
consult with an experienced user of your system. Sorry, we cannot
|
|
answer questions about basic Internet skills.
|
|
<p>
|
|
Unpacking the archive will produce a directory called "gd-2.0.1".
|
|
<p>
|
|
<h4>For Unix</h4>
|
|
<code>cd</code> to the 2.0.1 directory. Edit the Makefile with
|
|
your preferred text editor and make any necessary changes to the
|
|
settings at the top, especially if you want Xpm or TrueType support.
|
|
Next, type "make install". Because gd 2.0 and above installs
|
|
as a shared library, it is necessary to install the library properly
|
|
before running gd-based programs.
|
|
<p>
|
|
If you get errors, edit the Makefile again, paying special attention
|
|
to the INCLUDEDIRS and LIBDIRS settings.
|
|
<p>
|
|
IF YOU GET LINKER ERRORS, TRY JUGGLING THE ORDER OF THE -l DIRECTIVES
|
|
IN THE MAKEFILE. Some platforms may prefer that the libraries be listed
|
|
in the opposite order.
|
|
<h4>For Windows, Mac, Et Cetera</h4>
|
|
Create a project using your favorite programming environment.
|
|
Copy all of the gd files to the project directory. Add <code>gd.c</code>
|
|
to your project. Add other source files as appropriate. Learning the
|
|
basic skills of creating projects with your chosen C environment
|
|
is up to you.
|
|
<P>
|
|
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". Run gddemo to see some of
|
|
the capabilities of gd.
|
|
<P>
|
|
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.)
|
|
<P>
|
|
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.
|
|
<P>
|
|
(If you are missing the demoin.png file, the other items
|
|
should appear anyway.)
|
|
<P>
|
|
Look at demoin.png to see the original space shuttle
|
|
image which was scaled and copied into the output image.
|
|
<P>
|
|
<A NAME="basics"><H3>gd basics: using gd in your program</H3></A>
|
|
gd lets you create PNG or JPEG images on the fly. To use gd in your
|
|
program, include the file gd.h, and link with the libgd.a
|
|
library produced by "make libgd.a", under Unix. Under other
|
|
operating systems you will add gd.c to your own project.
|
|
<P>
|
|
If you want to use the provided 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 new
|
|
<a href="#gdImageStringFT">gdImageStringFT</a>
|
|
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.)
|
|
<P>
|
|
Here is a short example program. <strong>(For a more advanced example,
|
|
see gddemo.c, included in the distribution. gddemo.c is NOT the same program;
|
|
it demonstrates additional features!)</strong>
|
|
<P>
|
|
<PRE>
|
|
/* 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 */
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> 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 = <A HREF="#gdImageCreate">gdImageCreate</A>(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 = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
|
|
|
|
/* Allocate the color white (red, green and blue all maximum). */
|
|
white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
|
|
|
|
/* Draw a line from the upper left to the lower right,
|
|
using white color index. */
|
|
<A HREF="#gdImageLine">gdImageLine</A>(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. */
|
|
<A HREF="#gdImagePng">gdImagePng</A>(im, pngout);
|
|
|
|
/* Output the same image in JPEG format, using the default
|
|
JPEG quality setting. */
|
|
<A HREF="#gdImageJpeg">gdImageJpeg</A>(im, jpegout, -1);
|
|
|
|
/* Close the files. */
|
|
fclose(pngout);
|
|
fclose(jpegout);
|
|
|
|
/* Destroy the image in memory. */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
}
|
|
</PRE>
|
|
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.
|
|
<P>
|
|
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
|
|
<A HREF="#index">alphabetical index</A>.
|
|
<H3><A NAME="webpng">Webpng: a more powerful gd example</A></H3>
|
|
Webpng is a simple utility program to manipulate PNGs from the
|
|
command line. It is written for Unix and similar command-line
|
|
systems, but should be easily adapted for other environments.
|
|
Webpng allows you to set transparency and interlacing and
|
|
output interesting information about the PNG in question.
|
|
<P>
|
|
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.
|
|
<H2><A NAME="reference">Function and type reference</A></H2>
|
|
<UL>
|
|
<LI><A HREF="#types">Types</A></LI>
|
|
<LI><A HREF="#creating">Image creation, destruction, loading and saving</A></LI>
|
|
<LI><A HREF="#drawing">Drawing, styling, brushing, tiling and
|
|
filling functions</A></LI>
|
|
<LI><A HREF="#query">Query functions (not color-related)</A></LI>
|
|
<LI><A HREF="#fonts">Font and text-handling functions</A></LI>
|
|
<LI><A HREF="#colors">Color handling functions</A></LI>
|
|
<LI><A HREF="#copying">Copying and resizing functions</A></LI>
|
|
<LI><A HREF="#misc">Miscellaneous Functions</A></LI>
|
|
<LI><A HREF="#constants">Constants</A></LI>
|
|
</UL>
|
|
<H3><A NAME="types">Types</A></H3>
|
|
<DL>
|
|
<DT><A NAME="gdImage"><code>gdImage</code><strong>(TYPE)</strong></A>
|
|
<DD>
|
|
The data structure in which gd stores images. <A HREF="#gdImageCreate">
|
|
gdImageCreate</A>, <a href="#gdImageCreateTrueColor">gdImageCreateTrueColor</a>
|
|
and the various image file-loading functions return
|
|
a pointer to this type, and the other functions expect to receive
|
|
a pointer to this type as their first argument. It is reasonably safe to
|
|
examine any of the members of this structure. It is also reasonably
|
|
safe to modify individual pixels within the <code>pixels</code>
|
|
or <code>tpixels</code> arrays. If the <code>trueColor</code> flag
|
|
is set, the <code>tpixels</code> array is valid; otherwise the
|
|
<code>pixels</code> array is valid.
|
|
<p>
|
|
The <code>colorsTotal</code>, <code>red</code>, <code>green</code>,
|
|
<code>blue</code>, <code>alpha</code> and <code>open</code> arrays
|
|
manage the palette. They are valid only when the <code>trueColor</code>
|
|
flag is not set.
|
|
The <code>transparent</code> 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 <code>alpha</code> array so that
|
|
variable transparency can be supported for each palette entry. However,
|
|
for truecolor images, <code>transparent</code> represents a single
|
|
RGB color which is <strong>always 100% transparent</strong>, and this
|
|
feature is generally supported by browsers which do not support
|
|
full alpha channels.
|
|
<PRE>
|
|
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;
|
|
</PRE>
|
|
<p>
|
|
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.
|
|
<DT><A NAME="gdImagePtr">gdImagePtr</A> <strong>(TYPE)</strong>
|
|
<DD>
|
|
A pointer to an image structure. <A HREF="#gdImageCreate">gdImageCreate</A>
|
|
returns this type, and the other functions expect it as the first
|
|
argument.
|
|
<DT><A NAME="gdFont">gdFont</A> <strong>(TYPE)</strong>
|
|
<DD>
|
|
A font structure. Used to declare the characteristics of a font.
|
|
Plese see the files gdfontl.c and gdfontl.h for an example of the
|
|
proper declaration of this structure. You can provide your
|
|
own font data by providing such a structure and the associated
|
|
pixel array. You can determine the width and height of a single
|
|
character in a font by examining the w and h members of the
|
|
structure. If you will not be creating your own fonts, you will
|
|
not need to concern yourself with the rest of the components of this
|
|
structure.
|
|
<PRE>
|
|
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;
|
|
</PRE>
|
|
<DT><A NAME="gdFontPtr">gdFontPtr</A> <strong>(TYPE)</strong>
|
|
<DD>
|
|
A pointer to a font structure. Text-output functions expect these
|
|
as their second argument, following the <A HREF="#gdImagePtr">
|
|
gdImagePtr</A> argument. Two such pointers are declared in the
|
|
provided include files gdfonts.h and gdfontl.h.
|
|
<DT><A NAME="gdPoint">gdPoint</A> <strong>(TYPE)</strong>
|
|
<DD>
|
|
Represents a point in the coordinate space of the image; used
|
|
by <A HREF="#gdImagePolygon">gdImagePolygon</A> and
|
|
<A HREF="#gdImageFilledPolygon">gdImageFilledPolygon</A>.
|
|
<PRE>
|
|
typedef struct {
|
|
int x, y;
|
|
} gdPoint, *gdPointPtr;
|
|
</PRE>
|
|
<DT><A NAME="gdPointPtr">gdPointPtr</A> <strong>(TYPE)</strong>
|
|
<DD>
|
|
A pointer to a <A HREF="#gdPoint">gdPoint</A> structure; passed
|
|
as an argument to <A HREF="#gdImagePolygon">gdImagePolygon</A>
|
|
and <A HREF="#gdImageFilledPolygon">gdImageFilledPolygon</A>.
|
|
</DL>
|
|
<DT><A NAME="gdSource">gdSource</A> <strong>(TYPE)</strong>
|
|
<DD>
|
|
<pre>
|
|
typedef struct {
|
|
int (*source) (void *context, char *buffer, int len);
|
|
void *context;
|
|
} gdSource, *gdSourcePtr;
|
|
</pre>
|
|
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
|
|
<a href="#gdImageCreateFromPngSource">gdImageCreateFromPngSource</a> function.
|
|
See the documentation of that function for an example of the
|
|
proper use of this type.
|
|
<DT><A NAME="gdSink">gdSink</A> <strong>(TYPE)</strong>
|
|
<DD>
|
|
<PRE>
|
|
typedef struct {
|
|
int (*sink) (void *context, char *buffer, int len);
|
|
void *context;
|
|
} gdSink, *gdSinkPtr;
|
|
</PRE>
|
|
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
|
|
<a href="#gdImagePngToSink">gdImagePngToSink</a> function.
|
|
See the documentation of that function for an example of the
|
|
proper use of this type.
|
|
<H3><A NAME="creating">Image creation, destruction, loading and saving</A></H3>
|
|
<DL>
|
|
<DT><A NAME="gdImageCreate">gdImageCreate(sx, sy)</A>
|
|
<strong>(FUNCTION)</strong>
|
|
<DD>
|
|
gdImageCreate is called to create palette-based images, with no
|
|
more than 256 colors. Invoke gdImageCreate
|
|
with the x and y dimensions of the desired image. gdImageCreate
|
|
returns a <A HREF="#gdImagePtr">gdImagePtr</A> to the new image, or
|
|
NULL if unable to
|
|
allocate the image. The image must eventually be destroyed
|
|
using <A HREF="#gdImageDestroy">gdImageDestroy()</A>.
|
|
<PRE>
|
|
... inside a function ...
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im;
|
|
im = gdImageCreate(64, 64);
|
|
/* ... Use the image ... */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
</PRE>
|
|
<DT><A NAME="gdImageCreateTrueColor">gdImageCreateTrueColor(sx, sy)</A>
|
|
<strong>(FUNCTION)</strong>
|
|
<DD>
|
|
gdImageCreateTrueColor is called to create truecolor images, with
|
|
an essentially unlimited number of colors. Invoke gdImageCreateTrueColor
|
|
with the x and y dimensions of the desired image. gdImageCreateTrueColor
|
|
returns a <A HREF="#gdImagePtr">gdImagePtr</A> to the new image, or
|
|
NULL if unable to
|
|
allocate the image. The image must eventually be destroyed
|
|
using <A HREF="#gdImageDestroy">gdImageDestroy()</A>.
|
|
<p>
|
|
Truecolor images are always filled with black at creation time.
|
|
<PRE>
|
|
... inside a function ...
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im;
|
|
im = gdImageCreateTrueColor(64, 64);
|
|
/* ... Use the image ... */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
</PRE>
|
|
<DT><A NAME="gdImageCreateFromJpeg">gdImageCreateFromJpeg(FILE *in)</A>
|
|
<strong>(FUNCTION)</strong>
|
|
<br>
|
|
<A NAME="gdImageCreateFromJpegCtx">gdImageCreateFromJpegCtx(FILE *in)</A>
|
|
<strong>(FUNCTION)</strong>
|
|
<p><DT><A NAME="gdImageCreateFromJpeg">gdImageCreateFromJpeg(FILE *in)</A>
|
|
<strong>(FUNCTION)</strong>
|
|
<br>
|
|
<A NAME="gdImageCreateFromJpegCtx">gdImageCreateFromJpegCtx(FILE *in)</A>
|
|
<strong>(FUNCTION)</strong>
|
|
<p>
|
|
<DD>
|
|
gdImageCreateFromJpeg is called to load images from JPEG format files.
|
|
Invoke gdImageCreateFromJpeg with an already opened pointer to a file
|
|
containing the desired image.
|
|
gdImageCreateFromJpeg
|
|
returns a <A HREF="#gdImagePtr">gdImagePtr</A> to the new
|
|
truecolor image, or NULL
|
|
if unable to load the image (most often because the file is corrupt or
|
|
does not contain a JPEG image). gdImageCreateFromJpeg does <em>not</em>
|
|
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 <A HREF="#gdImageDestroy">gdImageDestroy()</A>. <strong>The
|
|
returned image is always a truecolor image.</strong>
|
|
<PRE>
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im;
|
|
... inside a function ...
|
|
FILE *in;
|
|
in = fopen("myjpeg.jpg", "rb");
|
|
im = gdImageCreateFromJpeg(in);
|
|
fclose(in);
|
|
/* ... Use the image ... */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
</PRE>
|
|
<DT><A NAME="gdImageCreateFromPng">gdImageCreateFromPng(FILE *in)</A>
|
|
<strong>(FUNCTION)</strong>
|
|
<BR><A NAME="gdImageCreateFromPngCtx">gdImageCreateFromPngCtx(<a href=#gdioctx>gdIOCtx</a> *in)</A>
|
|
<strong>(FUNCTION)</strong>
|
|
<p>
|
|
<DD>
|
|
gdImageCreateFromPng is called to load images from PNG format files.
|
|
Invoke gdImageCreateFromPng with an already opened pointer to a file
|
|
containing the desired image.
|
|
gdImageCreateFromPng
|
|
returns a <A HREF="#gdImagePtr">gdImagePtr</A> to the new image, or NULL
|
|
if unable to load the image (most often because the file is corrupt or
|
|
does not contain a PNG image). gdImageCreateFromPng does <em>not</em>
|
|
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 <A HREF="#gdImageDestroy">gdImageDestroy()</A>.
|
|
<p>
|
|
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.
|
|
<PRE>
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im;
|
|
... inside a function ...
|
|
FILE *in;
|
|
in = fopen("mypng.png", "rb");
|
|
im = gdImageCreateFromPng(in);
|
|
fclose(in);
|
|
/* ... Use the image ... */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
</PRE>
|
|
<DT><A NAME="gdImageCreateFromPngSource">gdImageCreateFromPngSource(gdSourcePtr in)</A>
|
|
<strong>(FUNCTION)</strong>
|
|
<dd>
|
|
gdImageCreateFromPngSource is called to load a PNG from
|
|
a data source other than a file. Usage is very similar to
|
|
the <a href="#gdImageCreateFromPng">gdImageCreateFromPng</a> function,
|
|
except that the programmer provides a custom data source.
|
|
<p>
|
|
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
|
|
<code>-1</code>. The programmer then creates a
|
|
<a href="#gdSource">gdSource</a> structure and sets
|
|
the <code>source</code> pointer to the input function and
|
|
the context pointer to any value which is useful to the
|
|
programmer.
|
|
<p>
|
|
The example below
|
|
implements <a href="#gdImageCreateFromPng">gdImageCreateFromPng</a>
|
|
by creating a custom data source and invoking gdImageCreateFromPngSource.
|
|
<pre>
|
|
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;
|
|
}
|
|
</pre>
|
|
<DT><A NAME="gdImageCreateFromGd">gdImageCreateFromGd(FILE *in)</A>
|
|
<strong>(FUNCTION)</strong>
|
|
<BR><A NAME="gdImageCreateFromGdCtx">gdImageCreateFromGdCtx(<a href=#gdioctx>gdIOCtx</a> *in)</A>
|
|
<strong>(FUNCTION)</strong>
|
|
<p>
|
|
<DD>
|
|
gdImageCreateFromGd is called to load images from gd format files.
|
|
Invoke gdImageCreateFromGd
|
|
with an already opened pointer to a file containing the desired image
|
|
in the <A HREF="#gdformat">gd file format</A>, which is specific to
|
|
gd and intended for very fast loading. (It is <em>not</em> intended for
|
|
compression; for compression, use PNG or JPEG.)
|
|
gdImageCreateFromGd
|
|
returns a <A HREF="#gdImagePtr">gdImagePtr</A> 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 <em>not</em>
|
|
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 <A HREF="#gdImageDestroy">gdImageDestroy()</A>.
|
|
<PRE>
|
|
... inside a function ...
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im;
|
|
FILE *in;
|
|
in = fopen("mygd.gd", "rb");
|
|
im = gdImageCreateFromGd(in);
|
|
fclose(in);
|
|
/* ... Use the image ... */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
</PRE>
|
|
|
|
<DT><A NAME="gdImageCreateFromGd2">gdImageCreateFromGd2(FILE *in)</A>
|
|
<strong>(FUNCTION)</strong>
|
|
<BR><A NAME="gdImageCreateFromGd2Ctx">gdImageCreateFromGd2Ctx(<a href=#gdioctx>gdIOCtx</a> *in)</A>
|
|
<strong>(FUNCTION)</strong>
|
|
<p>
|
|
|
|
<DD>
|
|
gdImageCreateFromGd2 is called to load images from gd2 format files.
|
|
Invoke gdImageCreateFromGd2
|
|
with an already opened pointer to a file containing the desired image
|
|
in the <A HREF="#gdformat">gd2 file format</A>, which is specific to
|
|
gd2 and intended for fast loading of parts of large images.
|
|
(It is a compressed format, but generally not as good as maximum
|
|
compression of the entire image would be.)
|
|
gdImageCreateFromGd
|
|
returns a <A HREF="#gdImagePtr">gdImagePtr</A> 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 <em>not</em>
|
|
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 <A HREF="#gdImageDestroy">gdImageDestroy()</A>.
|
|
<PRE>
|
|
... inside a function ...
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im;
|
|
FILE *in;
|
|
in = fopen("mygd.gd2", "rb");
|
|
im = gdImageCreateFromGd2(in);
|
|
fclose(in);
|
|
/* ... Use the image ... */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
</PRE>
|
|
|
|
<DT><A NAME="gdImageCreateFromGd2Part">gdImageCreateFromGd2Part(FILE *in, int srcX, int srcY, int w, int h)</A>
|
|
<strong>(FUNCTION)</strong>
|
|
<BR><A NAME="gdImageCreateFromGd2PartCtx">gdImageCreateFromGd2PartCtx(<a href=#gdioctx>gdIOCtx</a> *in)</A>
|
|
<strong>(FUNCTION)</strong>
|
|
<p>
|
|
|
|
<DD>
|
|
gdImageCreateFromGd2Part is called to load parts of images from <A HREF="#gdformat">gd2 format files</a>.
|
|
Invoked in the same way as <a href=#gdImageCreateFromGd2>gdImageCreateFromGd2</a>,
|
|
but with extra parameters
|
|
indicating the source (x, y) and width/height of the desired image.
|
|
gdImageCreateFromGd2Part returns a <A HREF="#gdImagePtr">gdImagePtr</A> to the
|
|
new image, or NULL if unable to load the image.
|
|
The image must eventually be destroyed using <A HREF="#gdImageDestroy">gdImageDestroy()</A>.
|
|
<p>
|
|
<DT><A NAME="gdImageCreateFromXbm">gdImageCreateFromXbm(FILE *in)</A>
|
|
<strong>(FUNCTION)</strong>
|
|
<DD>
|
|
gdImageCreateFromXbm is called to load images from X bitmap format
|
|
files. Invoke gdImageCreateFromXbm
|
|
with an already opened pointer to a file containing the desired image.
|
|
gdImageCreateFromXbm
|
|
returns a <A HREF="#gdImagePtr">gdImagePtr</A> to the new image, or NULL
|
|
if unable to load the image (most often because the file is corrupt or
|
|
does not contain an X bitmap format image). gdImageCreateFromXbm does
|
|
<em>not</em> 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 <A HREF="#gdImageDestroy">gdImageDestroy()</A>.
|
|
<PRE>
|
|
... inside a function ...
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im;
|
|
FILE *in;
|
|
in = fopen("myxbm.xbm", "rb");
|
|
im = gdImageCreateFromXbm(in);
|
|
fclose(in);
|
|
/* ... Use the image ... */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
</PRE>
|
|
<DT><A NAME="gdImageCreateFromXpm">gdImageCreateFromXpm(char *filename)</A>
|
|
<strong>(FUNCTION)</strong>
|
|
<DD>
|
|
gdImageCreateFromXbm is called to load images from XPM X Window System
|
|
color bitmap format files. This function is available only if HAVE_XPM
|
|
is selected in the Makefile and the Xpm library is linked with the
|
|
application. Unlike most gd file functions, the Xpm functions require
|
|
filenames, not file pointers.
|
|
gdImageCreateFromXpm
|
|
returns a <A HREF="#gdImagePtr">gdImagePtr</A> to the new image, or NULL
|
|
if unable to load the image (most often because the file is corrupt or
|
|
does not contain an XPM bitmap format image). You can inspect the sx and sy members of the
|
|
image to determine its size. The image must eventually be destroyed
|
|
using <A HREF="#gdImageDestroy">gdImageDestroy()</A>.
|
|
<PRE>
|
|
... inside a function ...
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im;
|
|
FILE *in;
|
|
in = fopen("myxpm.xpm", "rb");
|
|
im = gdImageCreateFromXpm(in);
|
|
fclose(in);
|
|
/* ... Use the image ... */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
</PRE>
|
|
<DT><A NAME="gdImageDestroy">gdImageDestroy(gdImagePtr im)</A> <STRONG>(FUNCTION)</STRONG>
|
|
<DD>gdImageDestroy is used to free the memory associated with
|
|
an image. It is important to invoke gdImageDestroy before
|
|
exiting your program or assigning a new image to
|
|
a <A HREF="#gdImagePtr">gdImagePtr</A> variable.
|
|
<PRE>
|
|
... inside a function ...
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im;
|
|
im = <A HREF="#gdImageCreate">gdImageCreate</A>(10, 10);
|
|
/* ... Use the image ... */
|
|
/* Now destroy it */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
</PRE>
|
|
<DT><A NAME="gdImageJpeg">
|
|
void gdImageJpeg(gdImagePtr im, FILE *out, int quality)</A>
|
|
<STRONG>(FUNCTION)</STRONG><BR>
|
|
void gdImageJpegCtx(gdImagePtr im, gdIOCtx *out, int quality)</A>
|
|
<STRONG>(FUNCTION)</STRONG><BR>
|
|
<DD>
|
|
gdImageJpeg outputs the specified image to the specified
|
|
file in JPEG format. The file must be open for writing. Under MSDOS
|
|
and all versions of Windows, it is important to use "wb" as opposed
|
|
to simply "w" as the mode when opening the file, and under Unix there
|
|
is no penalty for doing so. gdImageJpeg does <em>not</em>
|
|
close the file; your code must do so.
|
|
<P>
|
|
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.
|
|
<P>
|
|
If you have set image interlacing using
|
|
<A HREF="#gdImageInterlace">gdImageInterlace</A>, 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.
|
|
<PRE>
|
|
... inside a function ...
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im;
|
|
int black, white;
|
|
FILE *out;
|
|
/* Create the image */
|
|
im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
|
|
/* Allocate background */
|
|
white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
|
|
/* Allocate drawing color */
|
|
black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
|
|
/* Draw rectangle */
|
|
<A HREF="#gdImageRectangle">gdImageRectangle</A>(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 */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
</PRE>
|
|
<DT><A NAME="gdImageJpegPtr">
|
|
void* gdImageJpegPtr(gdImagePtr im, int *size)</A>
|
|
<STRONG>(FUNCTION)</STRONG>
|
|
<DD>Identical to gdImageJpeg except that it returns a pointer to a memory
|
|
area with the JPEG data. This memory must be freed by the caller when it is
|
|
no longer needed. <strong>The caller must invoke gdFree(), not free(),
|
|
unless the caller is absolutely certain that the same implementations of
|
|
malloc, free, etc. are used both at library build time and at application
|
|
build time.</strong> The 'size' parameter receives the total size of the block
|
|
of memory.
|
|
<DT><A NAME="gdImagePng">
|
|
void gdImagePng(gdImagePtr im, FILE *out)</A>
|
|
<STRONG>(FUNCTION)</STRONG>
|
|
<DD>
|
|
gdImagePng outputs the specified image to the specified
|
|
file in PNG format. The file must be open for writing. Under MSDOS
|
|
and all versions of Windows, it is important to use "wb" as opposed
|
|
to simply "w" as the mode when opening the file, and under Unix there
|
|
is no penalty for doing so. gdImagePng does <em>not</em>
|
|
close the file; your code must do so.
|
|
<PRE>
|
|
... inside a function ...
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im;
|
|
int black, white;
|
|
FILE *out;
|
|
/* Create the image */
|
|
im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
|
|
/* Allocate background */
|
|
white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
|
|
/* Allocate drawing color */
|
|
black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
|
|
/* Draw rectangle */
|
|
<A HREF="#gdImageRectangle">gdImageRectangle</A>(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 */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
</PRE>
|
|
|
|
<DT><A NAME="gdImagePngPtr">
|
|
void* gdImagePngPtr(gdImagePtr im, int *size)</A>
|
|
<STRONG>(FUNCTION)</STRONG>
|
|
<DD>Identical to gdImagePng except that it returns a pointer to a memory
|
|
area with the PNG data. This memory must be freed by the caller when it is
|
|
no longer needed. <strong>The caller must invoke gdFree(), not free(),
|
|
unless the caller is absolutely certain that the same implementations of
|
|
malloc, free, etc. are used both at library build time and at application
|
|
build time.</strong> The 'size' parameter receives the total size of the block
|
|
of memory.
|
|
|
|
<DT><A NAME="gdImagePngToSink">gdImagePngToSink(gdImagePtr im, gdSinkPtr out)</A>
|
|
<strong>(FUNCTION)</strong>
|
|
<dd>
|
|
gdImagePngToSink is called to write a PNG to
|
|
a data "sink" (destination) other than a file. Usage is very similar to
|
|
the <a href="#gdImagePng">gdImagePng</a> function,
|
|
except that the programmer provides a custom data sink.
|
|
<p>
|
|
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
|
|
<code>-1</code>. The programmer then creates a
|
|
<a href="#gdSink">gdSink</a> structure and sets
|
|
the <code>sink</code> pointer to the output function and
|
|
the context pointer to any value which is useful to the
|
|
programmer.
|
|
<p>
|
|
The example below
|
|
implements <a href="#gdImagePng">gdImagePng</a>
|
|
by creating a custom data source and invoking gdImagePngFromSink.
|
|
<pre>
|
|
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);
|
|
}
|
|
</pre>
|
|
<DT><A NAME="gdImageWBMP">
|
|
void gdImageWBMP(gdImagePtr im, int fg, FILE *out)</A>
|
|
<BR><A NAME="gdImageWBMPCtx">gdImageWBMPCtx(<a href=#gdioctx>gdIOCtx</a> *out)</A>
|
|
<strong>(FUNCTION)</strong><STRONG>(FUNCTION)</STRONG>
|
|
<DD>
|
|
gdImageWBMP outputs the specified image to the specified
|
|
file in WBMP format. The file must be open for writing. Under MSDOS
|
|
and all versions of Windows, it is important to use "wb" as opposed
|
|
to simply "w" as the mode when opening the file, and under Unix there
|
|
is no penalty for doing so. gdImageWBMP does <em>not</em>
|
|
close the file; your code must do so.
|
|
<p>
|
|
<strong>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.</strong> All other pixels
|
|
will be considered "background."
|
|
<PRE>
|
|
... inside a function ...
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im;
|
|
int black, white;
|
|
FILE *out;
|
|
/* Create the image */
|
|
im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
|
|
/* Allocate background */
|
|
white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
|
|
/* Allocate drawing color */
|
|
black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
|
|
/* Draw rectangle */
|
|
<A HREF="#gdImageRectangle">gdImageRectangle</A>(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 */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
</PRE>
|
|
<DT><A NAME="gdImageWBMPPtr">
|
|
void* gdImageWBMPPtr(gdImagePtr im, int *size)</A>
|
|
<STRONG>(FUNCTION)</STRONG>
|
|
<DD>Identical to gdImageWBMP except that it returns a pointer to a memory
|
|
area with the WBMP data. This memory must be freed by the caller when it is
|
|
no longer needed. <strong>The caller must invoke gdFree(), not free(),
|
|
unless the caller is absolutely certain that the same implementations of
|
|
malloc, free, etc. are used both at library build time and at application
|
|
build time.</strong> The 'size' parameter receives the total size of the block
|
|
of memory.
|
|
<DT><A NAME="gdImageGd">
|
|
void gdImageGd(gdImagePtr im, FILE *out)</A>
|
|
<STRONG>(FUNCTION)</STRONG>
|
|
<DD>
|
|
gdImageGd outputs the specified image to the specified
|
|
file in the <A HREF="#gdformat">gd image format</A>. The file must
|
|
be open for writing. Under MSDOS and all versions of Windows, it is
|
|
important to use "wb" as
|
|
opposed to simply "w" as the mode when opening the file, and under
|
|
Unix there is no penalty for doing so. gdImagePng does <em>not</em>
|
|
close the file; your code must do so.
|
|
<P>
|
|
The gd image format is intended for fast reads and writes of
|
|
images your program will need frequently to build other
|
|
images. It is <em>not</em> a compressed format, and is not intended
|
|
for general use.
|
|
<PRE>
|
|
... inside a function ...
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im;
|
|
int black, white;
|
|
FILE *out;
|
|
/* Create the image */
|
|
im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
|
|
/* Allocate background */
|
|
white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
|
|
/* Allocate drawing color */
|
|
black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
|
|
/* Draw rectangle */
|
|
<A HREF="#gdImageRectangle">gdImageRectangle</A>(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 */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
</PRE>
|
|
|
|
<DT><A NAME="gdImageGdPtr">
|
|
void* gdImageGdPtr(gdImagePtr im, int *size)</A>
|
|
<STRONG>(FUNCTION)</STRONG>
|
|
<DD>Identical to gdImageGd except that it returns a pointer to a memory
|
|
area with the GD data. This memory must be freed by the caller when it is
|
|
no longer needed. <strong>The caller must invoke gdFree(), not free(),
|
|
unless the caller is absolutely certain that the same implementations of
|
|
malloc, free, etc. are used both at library build time and at application
|
|
build time.</strong> The 'size' parameter receives the total size of the block
|
|
of memory.
|
|
|
|
<DT><A NAME="gdImageGd2">
|
|
void gdImageGd2(gdImagePtr im, FILE *out, int chunkSize, int fmt)</A>
|
|
<STRONG>(FUNCTION)</STRONG>
|
|
<DD>
|
|
gdImageGd2 outputs the specified image to the specified
|
|
file in the <A HREF="#gd2format">gd2 image format</A>. The file must
|
|
be open for writing. Under MSDOS and all versions of Windows, it is
|
|
important to use "wb" as
|
|
opposed to simply "w" as the mode when opening the file, and under
|
|
Unix there is no penalty for doing so. gdImageGd2 does <em>not</em>
|
|
close the file; your code must do so.
|
|
<P>
|
|
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.
|
|
<p>
|
|
The file is stored as a series of compressed subimages, and the
|
|
<strong>Chunk Size</strong> determines the sub-image size - a value of
|
|
zero causes the GD library to use the default.
|
|
<p>
|
|
It is also possible to store GD2 files in an uncompressed format, in which case the
|
|
fourth parameter should be GD2_FMT_RAW.
|
|
|
|
<PRE>
|
|
... inside a function ...
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im;
|
|
int black, white;
|
|
FILE *out;
|
|
/* Create the image */
|
|
im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
|
|
/* Allocate background */
|
|
white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
|
|
/* Allocate drawing color */
|
|
black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
|
|
/* Draw rectangle */
|
|
<A HREF="#gdImageRectangle">gdImageRectangle</A>(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 */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
</PRE>
|
|
|
|
<DT><A NAME="gdImageGd2Ptr">
|
|
void* gdImageGd2Ptr(gdImagePtr im, int chunkSize, int fmt, int *size)</A>
|
|
<STRONG>(FUNCTION)</STRONG>
|
|
<DD>Identical to gdImageGd2 except that it returns a pointer to a memory
|
|
area with the GD2 data. This memory must be freed by the caller when it is
|
|
no longer needed. <strong>The caller must invoke gdFree(), not free(),
|
|
unless the caller is absolutely certain that the same implementations of
|
|
malloc, free, etc. are used both at library build time and at application
|
|
build time.</strong> The 'size' parameter receives the total size of the block
|
|
of memory.
|
|
|
|
</DL>
|
|
<H3><A NAME="drawing">Drawing Functions</A></H3>
|
|
<DL>
|
|
<DT><A NAME="gdImageSetPixel">void gdImageSetPixel(gdImagePtr im, int x, int y, int color)</A> <STRONG>(FUNCTION)</STRONG>
|
|
<DD>gdImageSetPixel sets a pixel to a particular color index. Always use
|
|
this function or one of the other drawing functions to access pixels;
|
|
do not access the pixels of the <A HREF="#gdImage">gdImage</A> structure
|
|
directly.
|
|
<PRE>
|
|
... inside a function ...
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im;
|
|
int black;
|
|
int white;
|
|
im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
|
|
/* Background color (first allocated) */
|
|
black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
|
|
/* Allocate the color white (red, green and blue all maximum). */
|
|
white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(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 */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
</PRE>
|
|
<DT><A NAME="gdImageLine">void gdImageLine(gdImagePtr im, int x1, int y1, int x2, int y2, int color)</A>
|
|
<STRONG>(FUNCTION)</STRONG>
|
|
<DD>
|
|
gdImageLine is used to draw a line between two endpoints (x1,y1 and x2, y2).
|
|
The line is drawn using the color index specified. Note that the color
|
|
index can be an actual color returned by <A HREF="#gdImageColorAllocate">
|
|
gdImageColorAllocate</A> or one of <A HREF="#gdStyled">gdStyled</A>,
|
|
<A HREF="#gdBrushed">gdBrushed</A> or <A HREF="#gdStyledBrushed">
|
|
gdStyledBrushed</A>.
|
|
<PRE>
|
|
... inside a function ...
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im;
|
|
int black;
|
|
int white;
|
|
im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
|
|
/* Background color (first allocated) */
|
|
black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
|
|
/* Allocate the color white (red, green and blue all maximum). */
|
|
white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(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 */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
</PRE>
|
|
<DT><A NAME="gdImageDashedLine">void gdImageDashedLine(gdImagePtr im, int x1, int y1, int x2, int y2, int color)</A>
|
|
<STRONG>(FUNCTION)</STRONG>
|
|
<DD>
|
|
gdImageDashedLine is provided <strong>solely for backwards compatibility
|
|
</strong> with gd 1.0. New programs should draw dashed lines using
|
|
the normal <A HREF="#gdImageLine">gdImageLine</A> function and the
|
|
new <A HREF="#gdImageSetStyle">gdImageSetStyle</A> function.
|
|
<P>
|
|
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.
|
|
<PRE>
|
|
... inside a function ...
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im;
|
|
int black;
|
|
int white;
|
|
im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
|
|
/* Background color (first allocated) */
|
|
black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
|
|
/* Allocate the color white (red, green and blue all maximum). */
|
|
white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(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 */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
</PRE>
|
|
<DT><A NAME="gdImagePolygon">void gdImagePolygon(gdImagePtr im, gdPointPtr points, int pointsTotal, int color)</A>
|
|
<STRONG>(FUNCTION)</STRONG>
|
|
<DD>
|
|
gdImagePolygon is used to draw a polygon with the verticies
|
|
(at least 3) specified, using the color index specified.
|
|
See also <A HREF="#gdImageFilledPolygon">gdImageFilledPolygon</A>.
|
|
<PRE>
|
|
... inside a function ...
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im;
|
|
int black;
|
|
int white;
|
|
/* Points of polygon */
|
|
<A HREF="#gdPoint">gdPoint</A> points[3];
|
|
im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
|
|
/* Background color (first allocated) */
|
|
black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
|
|
/* Allocate the color white (red, green and blue all maximum). */
|
|
white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(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 */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
</PRE>
|
|
<DT><A NAME="gdImageRectangle">void gdImageRectangle(gdImagePtr im, int x1, int y1, int x2, int y2, int color)</A>
|
|
<STRONG>(FUNCTION)</STRONG>
|
|
<DD>
|
|
gdImageRectangle is used to draw a rectangle with the two corners
|
|
(upper left first, then lower right) specified, using the
|
|
color index specified.
|
|
<PRE>
|
|
... inside a function ...
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im;
|
|
int black;
|
|
int white;
|
|
im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
|
|
/* Background color (first allocated) */
|
|
black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
|
|
/* Allocate the color white (red, green and blue all maximum). */
|
|
white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(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 */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
</PRE>
|
|
<DT><A NAME="gdImageFilledPolygon">void gdImageFilledPolygon(gdImagePtr im, gdPointPtr points, int pointsTotal, int color)</A>
|
|
<STRONG>(FUNCTION)</STRONG>
|
|
<DD>
|
|
gdImageFilledPolygon is used to fill a polygon with the verticies
|
|
(at least 3) specified, using the color index specified.
|
|
See also <A HREF="#gdImageFilledPolygon">gdImagePolygon</A>.
|
|
<PRE>
|
|
... inside a function ...
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im;
|
|
int black;
|
|
int white;
|
|
int red;
|
|
/* Points of polygon */
|
|
<A HREF="#gdPoint">gdPoint</A> points[3];
|
|
im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
|
|
/* Background color (first allocated) */
|
|
black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
|
|
/* Allocate the color white (red, green and blue all maximum). */
|
|
white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
|
|
/* Allocate the color red. */
|
|
red = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(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 */
|
|
<A HREF="#gdImagePolygon">gdImagePolygon</A>(im, points, 3, red);
|
|
/* ... Do something with the image, such as saving it to a file... */
|
|
/* Destroy it */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
</PRE>
|
|
<DT><A NAME="gdImageFilledRectangle">void gdImageFilledRectangle(gdImagePtr im, int x1, int y1, int x2, int y2, int color)</A>
|
|
<STRONG>(FUNCTION)</STRONG>
|
|
<DD>
|
|
gdImageFilledRectangle is used to draw a solid rectangle with the two corners
|
|
(upper left first, then lower right) specified, using the
|
|
color index specified.
|
|
<PRE>
|
|
... inside a function ...
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im;
|
|
int black;
|
|
int white;
|
|
im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
|
|
/* Background color (first allocated) */
|
|
black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
|
|
/* Allocate the color white (red, green and blue all maximum). */
|
|
white = <A HREF="#gdImageColorAllocate">int gdImageColorAllocate</A>(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 */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
</PRE>
|
|
<DT><A NAME="gdImageArc">void gdImageArc(gdImagePtr im, int cx, int cy, int w, int h, int s, int e, int color)</A>
|
|
<STRONG> (FUNCTION)</STRONG>
|
|
<DD>
|
|
gdImageArc is used to draw a partial ellipse centered at the given point,
|
|
with the specified width and height in pixels. The arc begins at
|
|
the position in degrees specified by <code>s</code> and ends at
|
|
the position specified by <code>e</code>. 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.
|
|
<PRE>
|
|
... inside a function ...
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im;
|
|
int black;
|
|
int white;
|
|
im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 50);
|
|
/* Background color (first allocated) */
|
|
black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
|
|
/* Allocate the color white (red, green and blue all maximum). */
|
|
white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(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 */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
</PRE>
|
|
<DT><A NAME="gdImageFilledArc">void gdImageFilledArc(gdImagePtr im, int cx, int cy, int w, int h, int s, int e, int color, int style)</A>
|
|
<STRONG> (FUNCTION)</STRONG>
|
|
<DD>
|
|
gdImageFilledArc is used to draw a partial ellipse centered at the given point,
|
|
with the specified width and height in pixels. The arc begins at
|
|
the position in degrees specified by <code>s</code> and ends at
|
|
the position specified by <code>e</code>. 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:
|
|
<ul>
|
|
<li>gdArc
|
|
<li>gdChord
|
|
<li>gdPie (synonym for gdChord)
|
|
<li>gdNoFill
|
|
<li>gdEdged
|
|
</ul>
|
|
gdArc and gdChord are mutually exclusive;
|
|
gdChord just connects the starting and ending
|
|
angles with a straight line, while gdArc produces
|
|
a rounded edge. gdPie is a synonym for gdArc.
|
|
gdNoFill indicates that the arc or chord should be
|
|
outlined, not filled. gdEdged, used together with
|
|
gdNoFill, indicates that the beginning and ending
|
|
angles should be connected to the center; this is
|
|
a good way to outline (rather than fill) a
|
|
'pie slice'.
|
|
|
|
<PRE>
|
|
... inside a function ...
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im;
|
|
int black;
|
|
int white;
|
|
im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 50);
|
|
/* Background color (first allocated) */
|
|
black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
|
|
/* Allocate the color white (red, green and blue all maximum). */
|
|
white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(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 */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
</PRE>
|
|
<DT><A NAME="gdImageFilledEllipse">void gdImageFilledEllipse(gdImagePtr im, int cx, int cy, int w, int h, int s, int e, int color)</A>
|
|
<STRONG> (FUNCTION)</STRONG>
|
|
<DD>
|
|
gdImageFilledEllipse is used to draw an ellipse centered at the given point,
|
|
with the specified width and height in pixels. The ellipse is filled 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.
|
|
<PRE>
|
|
... inside a function ...
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im;
|
|
int black;
|
|
int white;
|
|
im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 50);
|
|
/* Background color (first allocated) */
|
|
black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
|
|
/* Allocate the color white (red, green and blue all maximum). */
|
|
white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(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 */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
</PRE>
|
|
<DT><A NAME="gdImageFillToBorder">void gdImageFillToBorder(gdImagePtr im, int x, int y, int border, int color)
|
|
<STRONG> (FUNCTION)</STRONG>
|
|
<DD>
|
|
gdImageFillToBorder floods a portion of the image with the specified
|
|
<code>color</code>, beginning at the specified point and stopping at
|
|
the specified <code>border</code> color. For a way of flooding an
|
|
area defined by the color of the starting point, see
|
|
<A HREF="#gdImageFill">gdImageFill</A>.
|
|
<P>
|
|
The border color <em>cannot</em> be a special color
|
|
such as <A HREF="#gdTiled">gdTiled</A>; it must be a proper
|
|
solid color. The fill color can be, however.
|
|
<P>
|
|
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.)
|
|
<PRE>
|
|
... inside a function ...
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im;
|
|
int black;
|
|
int white;
|
|
int red;
|
|
im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 50);
|
|
/* Background color (first allocated) */
|
|
black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
|
|
/* Allocate the color white (red, green and blue all maximum). */
|
|
white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
|
|
/* Allocate the color red. */
|
|
red = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(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 */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
</PRE>
|
|
<DT><A NAME="gdImageFill">void gdImageFill(gdImagePtr im, int x, int y, int color)
|
|
<STRONG> (FUNCTION)</STRONG>
|
|
<DD>
|
|
gdImageFill floods a portion of the image with the specified
|
|
<code>color</code>, 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
|
|
<A HREF="#gdImageFillToBorder">gdImageFillToBorder</A>.
|
|
<P>
|
|
The fill color can be <A HREF="#gdTiled">gdTiled</A>, 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
|
|
<A HREF="#gdImageTransparent">gdImageTransparent</A> on the
|
|
tile image and set the transparent color index to -1
|
|
to turn off its transparency.
|
|
<P>
|
|
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.)
|
|
<PRE>
|
|
... inside a function ...
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im;
|
|
int black;
|
|
int white;
|
|
int red;
|
|
im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 50);
|
|
/* Background color (first allocated) */
|
|
black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
|
|
/* Allocate the color white (red, green and blue all maximum). */
|
|
white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
|
|
/* Allocate the color red. */
|
|
red = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(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 */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
</PRE>
|
|
<DT><A NAME="gdImageSetBrush">void gdImageSetBrush(gdImagePtr im, gdImagePtr brush)</A>
|
|
<STRONG>(FUNCTION)</STRONG>
|
|
<DD>
|
|
A "brush" is an image used to draw wide, shaped strokes in another image. Just
|
|
as a paintbrush is not a single point, a brush image need not be
|
|
a single pixel. <em>Any</em> gd image can be used as a brush, and by
|
|
setting the transparent color index of the brush image with
|
|
<A HREF="#gdImageColorTransparent">gdImageColorTransparent</A>,
|
|
a brush of any shape can be created. All line-drawing functions,
|
|
such as <A HREF="#gdImageLine">gdImageLine</A> and
|
|
<A HREF="#gdImagePolygon">gdImagePolygon</A>, will use the
|
|
current brush if the special "color" <A HREF="#gdBrushed">
|
|
gdBrushed</A> or <A HREF="#gdStyledBrushed">gdStyledBrushed</A>
|
|
is used when calling them.
|
|
<P>
|
|
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.
|
|
<P>
|
|
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 <A HREF="#gdImageDestroy">gdImageDestroy</A>.
|
|
You must not use the color <A HREF="#gdBrushed">gdBrushed</A>
|
|
if the current brush has been destroyed; you can of
|
|
course set a new brush to replace it.
|
|
<PRE>
|
|
... inside a function ...
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im, brush;
|
|
FILE *in;
|
|
int black;
|
|
im = <A HREF="#gdImageCreate">gdImageCreate</A>(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 = <A HREF="#gdImageCreateFromPng">gdImageCreateFromPng</A>(in);
|
|
/* Background color (first allocated) */
|
|
black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
|
|
gdImageSetBrush(im, brush);
|
|
/* Draw a line from the upper left corner to the lower right corner
|
|
using the brush. */
|
|
<A HREF="#gdImageLine">gdImageLine</A>(im, 0, 0, 99, 99, <A HREF="#gdBrushed">gdBrushed</A>);
|
|
/* ... Do something with the image, such as saving it to a file... */
|
|
/* Destroy it */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
/* Destroy the brush image */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(brush);
|
|
</PRE>
|
|
<DT><A NAME="gdImageSetTile">void gdImageSetTile(gdImagePtr im, gdImagePtr tile)</A>
|
|
<STRONG>(FUNCTION)</STRONG>
|
|
<DD>
|
|
A "tile" is an image used to fill an area with a repeated pattern.
|
|
<em>Any</em> gd image can be used as a tile, and by
|
|
setting the transparent color index of the tile image with
|
|
<A HREF="#gdImageColorTransparent">gdImageColorTransparent</A>,
|
|
a tile that allows certain parts of the underlying area to shine
|
|
through can be created. All region-filling functions,
|
|
such as <A HREF="#gdImageFill">gdImageFill</A> and
|
|
<A HREF="#gdImageFilledPolygon">gdImageFilledPolygon</A>, will use the
|
|
current tile if the special "color" <A HREF="#gdTiled">
|
|
gdTiled</A> is used when calling them.
|
|
<P>
|
|
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.
|
|
<P>
|
|
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 <A HREF="#gdImageDestroy">gdImageDestroy</A>.
|
|
You must not use the color <A HREF="#gdBrushed">gdTiled</A>
|
|
if the current tile has been destroyed; you can of
|
|
course set a new tile to replace it.
|
|
<PRE>
|
|
... inside a function ...
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im, tile;
|
|
FILE *in;
|
|
int black;
|
|
im = <A HREF="#gdImageCreate">gdImageCreate</A>(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 = <A HREF="#gdImageCreateFromPng">gdImageCreateFromPng</A>(in);
|
|
/* Background color (first allocated) */
|
|
black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
|
|
gdImageSetTile(im, tile);
|
|
/* Fill an area using the tile. */
|
|
<A HREF="#gdImageFilledRectangle">gdImageFilledRectangle</A>(im, 25, 25, 75, 75, <A HREF="#gdTiled">gdTiled</A>);
|
|
/* ... Do something with the image, such as saving it to a file... */
|
|
/* Destroy it */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
/* Destroy the tile image */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(tile);
|
|
</PRE>
|
|
<DT><A NAME="gdImageSetStyle">void gdImageSetStyle(gdImagePtr im, int *style, int styleLength)</A>
|
|
<STRONG>(FUNCTION)</STRONG>
|
|
<DD>
|
|
It is often desirable to draw dashed lines, dotted lines, and other
|
|
variations on a broken line. gdImageSetStyle can be used to set
|
|
any desired series of colors, including a special color that
|
|
leaves the background intact, to be repeated during the drawing
|
|
of a line.
|
|
<P>
|
|
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 <A HREF="#gdTransparent">
|
|
gdTransparent</A> 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).
|
|
<P>
|
|
Then, to draw a line using the style, use the normal
|
|
<A HREF="#gdImageLine">gdImageLine</A> function with the
|
|
special color value <A HREF="#gdStyled">gdStyled</A>.
|
|
<P>
|
|
As of <A HREF="#whatsnew1.1.1">version 1.1.1</A>, 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.
|
|
<P>
|
|
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 <A HREF="#gdStyledBrushed">
|
|
gdStyledBrushed</A>. For an example of this feature
|
|
in use, see gddemo.c (provided in the distribution).
|
|
<PRE>
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im;
|
|
int styleDotted[2], styleDashed[6];
|
|
FILE *in;
|
|
int black;
|
|
int red;
|
|
im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
|
|
/* Background color (first allocated) */
|
|
black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
|
|
red = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(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. */
|
|
<A HREF="#gdImageLine">gdImageLine</A>(im, 0, 0, 99, 99, <A HREF="#gdStyled">gdStyled</A>);
|
|
/* Now the dashed line. */
|
|
gdImageSetStyle(im, styleDashed, 6);
|
|
<A HREF="#gdImageLine">gdImageLine</A>(im, 0, 99, 0, 99, <A HREF="#gdStyled">gdStyled</A>);
|
|
|
|
/* ... Do something with the image, such as saving it to a file ... */
|
|
|
|
/* Destroy it */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
</PRE>
|
|
<DT><A NAME="gdImageAlphaBlending">void gdImageAlphaBlending(gdImagePtr im, int blending)</A>
|
|
<STRONG>(FUNCTION)</STRONG>
|
|
<DD>
|
|
The <a href="#gdImageAlphaBlending">gdImageAlphaBlending</a>
|
|
function allows for two different modes of drawing on truecolor
|
|
images. In blending mode, the alpha channel component of the color
|
|
supplied to all drawing functions, such as
|
|
<a href="#gdImageSetPixel">gdImageSetPixel</a>, determines how much of
|
|
the underlying color should be allowed to shine through. As a result,
|
|
gd automatically blends the existing color at that point with the
|
|
drawing color, and stores the result in the image. The resulting pixel
|
|
is opaque. In non-blending mode, the drawing color is copied literally
|
|
with its alpha channel information, replacing the destination pixel.
|
|
Blending mode is not available when drawing on palette images.
|
|
<PRE>
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im;
|
|
int red, blue;
|
|
im = <A HREF="#gdImageCreate">gdImageCreateTrueColor</A>(100, 100);
|
|
/* Background color */
|
|
red = <A HREF="#gdTrueColor">gdTrueColor</A>(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 = <A HREF="#gdTrueColor">gdTrueColorAlpha</A>(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);
|
|
<a href="#gdImageFilledRectangle">gdImageFilledRectangle</a>(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);
|
|
<a href="#gdImageFilledRectangle">gdImageFilledRectangle</a>(im, 75, 75, 25, 25, blue);
|
|
/* Write the image to disk, etc. */
|
|
</pre>
|
|
</DL>
|
|
<H3><A NAME="query">Query Functions</A></H3>
|
|
<DL>
|
|
<DT><A NAME="gdImageBlue">
|
|
int gdImageAlpha(gdImagePtr im, int color)</A>
|
|
<STRONG>(MACRO)</STRONG>
|
|
<DD>
|
|
gdImageAlpha is a macro which returns the alpha channel component of
|
|
the specified color index. Alpha channel values vary between
|
|
0 (gdAlphaOpaque), which does not blend at all with the background,
|
|
through 127 (gdAlphaTransparent), which allows the background to
|
|
shine through 100%. Use this macro rather than accessing the
|
|
structure members directly.
|
|
int gdImageBlue(gdImagePtr im, int color)</A>
|
|
<STRONG>(MACRO)</STRONG>
|
|
<DD>
|
|
gdImageBlue is a macro which returns the blue component of
|
|
the specified color index. Use this macro rather than accessing the
|
|
structure members directly.
|
|
<DT><A NAME="gdImageGetPixel">int gdImageGetPixel(gdImagePtr im, int x, int y)</A>
|
|
<STRONG>(FUNCTION)</STRONG>
|
|
<DD>
|
|
gdImageGetPixel() retrieves the color index of a particular
|
|
pixel. Always use this function to query pixels;
|
|
do not access the pixels of the <A HREF="#gdImage">gdImage</A> structure
|
|
directly.
|
|
<PRE>
|
|
... inside a function ...
|
|
FILE *in;
|
|
gdImagePtr im;
|
|
int c;
|
|
in = fopen("mypng.png", "rb");
|
|
im = <A HREF="#gdImageCreateFromPng">gdImageCreateFromPng</A>(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]);
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
</PRE>
|
|
<DT><A NAME="gdImageBoundsSafe">
|
|
int gdImageBoundsSafe(gdImagePtr im, int x, int y)</A>
|
|
<STRONG>(FUNCTION)</STRONG>
|
|
<DD>
|
|
gdImageBoundsSafe returns true (1) if the specified point is within the bounds
|
|
of the image, false (0) if not. This function is intended primarily for
|
|
use by those who wish to add functions to gd. All of the gd drawing
|
|
functions already clip safely to the edges of the image.
|
|
<PRE>
|
|
... inside a function ...
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im;
|
|
int black;
|
|
int white;
|
|
im = <A HREF="#gdImageCreate">gdImageCreate</A>(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");
|
|
}
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
</PRE>
|
|
<DT><A NAME="gdImageGreen">
|
|
int gdImageGreen(gdImagePtr im, int color)</A>
|
|
<STRONG>(MACRO)</STRONG>
|
|
<DD>
|
|
gdImageGreen is a macro which returns the green component of
|
|
the specified color index. Use this macro rather than accessing the
|
|
structure members directly.
|
|
<DT><A NAME="gdImageRed">
|
|
int gdImageRed(gdImagePtr im, int color)</A>
|
|
<STRONG>(MACRO)</STRONG>
|
|
<DD>
|
|
gdImageRed is a macro which returns the red component of
|
|
the specified color index. Use this macro rather than accessing the
|
|
structure members directly.
|
|
<DT><A NAME="gdImageSX">
|
|
int gdImageSX(gdImagePtr im)</A>
|
|
<STRONG>(MACRO)</STRONG>
|
|
<DD>
|
|
gdImageSX is a macro which returns the width of the image
|
|
in pixels. Use this macro rather than accessing the
|
|
structure members directly.
|
|
<DT><A NAME="gdImageSY">
|
|
int gdImageSY(gdImagePtr im)</A>
|
|
<STRONG>(MACRO)</STRONG>
|
|
<DD>
|
|
gdImageSY is a macro which returns the height of the image
|
|
in pixels. Use this macro rather than accessing the
|
|
structure members directly.
|
|
</DL>
|
|
<H3><A NAME="fonts">Fonts and text-handling functions</A></H3>
|
|
<DL>
|
|
<DT><A NAME="gdImageChar">
|
|
void gdImageChar(gdImagePtr im, gdFontPtr font, int x, int y,
|
|
int c, int color)</A>
|
|
<STRONG>(FUNCTION)</STRONG>
|
|
<DD>
|
|
gdImageChar is used to draw single characters on the image.
|
|
(To draw multiple characters, use <A HREF="#gdImageString">
|
|
gdImageString</A> or <A HREF="#gdImageString16">
|
|
gdImageString16</A>.
|
|
See also <A HREF="#gdImageStringFT">gdImageStringFT</A> for a high quality
|
|
solution.)
|
|
The second argument is a pointer to a font definition structure; five fonts are
|
|
provided with gd, gdFontTiny, gdFontSmall, gdFontMediumBold,
|
|
gdFontLarge, and gdFontGiant. You must
|
|
include the files "gdfontt.h", "gdfonts.h", "gdfontmb.h",
|
|
"gdfontl.h" and "gdfontg.h" respectively
|
|
and (if you are not using a library-based approach) link with the
|
|
corresponding .c files to use the provided fonts.
|
|
The character specified by the fifth
|
|
argument is drawn from left to right in the specified
|
|
color. (See <A HREF="#gdImageCharUp">gdImageCharUp</A> for a way
|
|
of drawing vertical text.) Pixels not
|
|
set by a particular character retain their previous color.
|
|
<PRE>
|
|
#include "gd.h"
|
|
#include "gdfontl.h"
|
|
... inside a function ...
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im;
|
|
int black;
|
|
int white;
|
|
im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
|
|
/* Background color (first allocated) */
|
|
black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
|
|
/* Allocate the color white (red, green and blue all maximum). */
|
|
white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
|
|
/* Draw a character. */
|
|
gdImageChar(im, gdFontLarge, 0, 0, 'Q', white);
|
|
/* ... Do something with the image, such as saving it to a file... */
|
|
/* Destroy it */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
</PRE>
|
|
<DT><A NAME="gdImageCharUp">
|
|
void gdImageCharUp(gdImagePtr im, gdFontPtr font, int x, int y,
|
|
int c, int color)</A>
|
|
<STRONG>(FUNCTION)</STRONG>
|
|
<DD>
|
|
gdImageCharUp is used to draw single characters on the image,
|
|
rotated 90 degrees.
|
|
(To draw multiple characters, use <A HREF="#gdImageStringUp">
|
|
gdImageStringUp</A> or <A HREF="#gdImageStringUp16">
|
|
gdImageStringUp16</A>.) The second argument is a
|
|
pointer to a font definition structure; five fonts are
|
|
provided with gd, gdFontTiny, gdFontSmall, gdFontMediumBold,
|
|
gdFontLarge, and gdFontGiant. You must
|
|
include the files "gdfontt.h", "gdfonts.h", "gdfontmb.h",
|
|
"gdfontl.h" and "gdfontg.h" respectively
|
|
and (if you are not using a library-based approach) link with the
|
|
corresponding .c files to use the provided fonts. The character specified by
|
|
the fifth argument is drawn
|
|
from bottom to top, rotated at a 90-degree angle, in the specified
|
|
color. (See <A HREF="#gdImageChar">gdImageChar</A> for a way
|
|
of drawing horizontal text.) Pixels not
|
|
set by a particular character retain their previous color.
|
|
<PRE>
|
|
#include "gd.h"
|
|
#include "gdfontl.h"
|
|
... inside a function ...
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im;
|
|
int black;
|
|
int white;
|
|
im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
|
|
/* Background color (first allocated) */
|
|
black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
|
|
/* Allocate the color white (red, green and blue all maximum). */
|
|
white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
|
|
/* Draw a character upwards so it rests against the top of the image. */
|
|
gdImageCharUp(im, gdFontLarge,
|
|
0, gdFontLarge->h, 'Q', white);
|
|
/* ... Do something with the image, such as saving it to a file... */
|
|
/* Destroy it */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
</PRE>
|
|
<DT><A NAME="gdImageString">
|
|
void gdImageString(gdImagePtr im, gdFontPtr font, int x, int y,
|
|
unsigned char *s, int color)</A>
|
|
<STRONG>(FUNCTION)</STRONG>
|
|
<DD>
|
|
gdImageString is used to draw multiple characters on the image.
|
|
(To draw single characters, use <A HREF="#gdImageChar">
|
|
gdImageChar</A>.) The second argument is a
|
|
pointer to a font definition structure; five fonts are
|
|
provided with gd, gdFontTiny, gdFontSmall, gdFontMediumBold,
|
|
gdFontLarge, and gdFontGiant. You must
|
|
include the files "gdfontt.h", "gdfonts.h", "gdfontmb.h",
|
|
"gdfontl.h" and "gdfontg.h" respectively
|
|
and (if you are not using a library-based approach) link with the
|
|
corresponding .c files to use the provided fonts.
|
|
The null-terminated C string specified
|
|
by the fifth argument is drawn from left to right in the specified
|
|
color. (See <A HREF="#gdImageStringUp">gdImageStringUp</A> for a way
|
|
of drawing vertical text.
|
|
See also <A HREF="#gdImageStringFT">gdImageStringFT</A> for a high
|
|
quality solution.)
|
|
Pixels not set by a particular character retain their previous color.
|
|
<PRE>
|
|
#include "gd.h"
|
|
#include "gdfontl.h"
|
|
#include <string.h>
|
|
... inside a function ...
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im;
|
|
int black;
|
|
int white;
|
|
/* String to draw. */
|
|
char *s = "Hello.";
|
|
im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
|
|
/* Background color (first allocated) */
|
|
black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
|
|
/* Allocate the color white (red, green and blue all maximum). */
|
|
white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
|
|
/* Draw a centered string. */
|
|
gdImageString(im, gdFontLarge,
|
|
im->w / 2 - (strlen(s) * gdFontLarge->w / 2),
|
|
im->h / 2 - gdFontLarge->h / 2,
|
|
s, white);
|
|
/* ... Do something with the image, such as saving it to a file... */
|
|
/* Destroy it */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
</PRE>
|
|
<DT><A NAME="gdImageString16">
|
|
void gdImageString16(gdImagePtr im, gdFontPtr font, int x, int y,
|
|
unsigned short *s, int color)</A>
|
|
<STRONG>(FUNCTION)</STRONG>
|
|
<DD>
|
|
gdImageString is used to draw multiple 16-bit characters on the image.
|
|
(To draw single characters, use <A HREF="#gdImageChar">
|
|
gdImageChar</A>.) The second argument is a
|
|
pointer to a font definition structure; five fonts are
|
|
provided with gd, gdFontTiny, gdFontSmall, gdFontMediumBold,
|
|
gdFontLarge, and gdFontGiant. You must
|
|
include the files "gdfontt.h", "gdfonts.h", "gdfontmb.h",
|
|
"gdfontl.h" and "gdfontg.h" respectively
|
|
and (if you are not using a library-based approach) link with the
|
|
corresponding .c files to use the provided fonts.
|
|
The 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 <A HREF="#gdImageStringUp16">gdImageStringUp16</A> for a way
|
|
of drawing vertical text.) Pixels not
|
|
set by a particular character retain their previous color.
|
|
<p>
|
|
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 <a href="#gdImageString">gdImageString</a>.
|
|
<DT><A NAME="gdImageStringUp">
|
|
void gdImageStringUp(gdImagePtr im, gdFontPtr font, int x, int y,
|
|
unsigned char *s, int color)</A>
|
|
<STRONG>(FUNCTION)</STRONG>
|
|
<DD>
|
|
gdImageStringUp is used to draw multiple characters on the image,
|
|
rotated 90 degrees.
|
|
(To draw single characters, use <A HREF="#gdImageCharUp">
|
|
gdImageCharUp</A>.) The second argument is a
|
|
pointer to a font definition structure; five fonts are
|
|
provided with gd, gdFontTiny, gdFontSmall, gdFontMediumBold,
|
|
gdFontLarge, and gdFontGiant. You must
|
|
include the files "gdfontt.h", "gdfonts.h", "gdfontmb.h",
|
|
"gdfontl.h" and "gdfontg.h" respectively
|
|
and (if you are not using a library-based approach) link with the
|
|
corresponding .c files to use the provided fonts.The null-terminated C string specified
|
|
by the fifth argument is drawn from bottom to top (rotated
|
|
90 degrees) in the specified color. (See
|
|
<A HREF="#gdImageString">gdImageString</A> for a way
|
|
of drawing horizontal text.) Pixels not
|
|
set by a particular character retain their previous color.
|
|
<PRE>
|
|
#include "gd.h"
|
|
#include "gdfontl.h"
|
|
#include <string.h>
|
|
... inside a function ...
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im;
|
|
int black;
|
|
int white;
|
|
/* String to draw. */
|
|
char *s = "Hello.";
|
|
im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
|
|
/* Background color (first allocated) */
|
|
black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
|
|
/* Allocate the color white (red, green and blue all maximum). */
|
|
white = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 255, 255);
|
|
/* Draw a centered string going upwards. Axes are reversed,
|
|
and Y axis is decreasing as the string is drawn. */
|
|
gdImageStringUp(im, gdFontLarge,
|
|
im->w / 2 - gdFontLarge->h / 2,
|
|
im->h / 2 + (strlen(s) * gdFontLarge->w / 2),
|
|
s, white);
|
|
/* ... Do something with the image, such as saving it to a file... */
|
|
/* Destroy it */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
</PRE>
|
|
<DT><A NAME="gdImageStringUp16">
|
|
void gdImageStringUp16(gdImagePtr im, gdFontPtr font, int x, int y,
|
|
unsigned short *s, int color)</A>
|
|
<STRONG>(FUNCTION)</STRONG>
|
|
<DD>
|
|
gdImageString is used to draw multiple 16-bit characters vertically on
|
|
the image. (To draw single characters, use <A HREF="#gdImageChar">
|
|
gdImageChar</A>.) The second argument is a
|
|
pointer to a font definition structure; five fonts are
|
|
provided with gd, gdFontTiny, gdFontSmall, gdFontMediumBold,
|
|
gdFontLarge, and gdFontGiant. You must
|
|
include the files "gdfontt.h", "gdfonts.h", "gdfontmb.h",
|
|
"gdfontl.h" and "gdfontg.h" respectively
|
|
and (if you are not using a library-based approach) link with the
|
|
corresponding .c files to use the provided fonts.
|
|
The 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 <A HREF="#gdImageStringUp16">gdImageStringUp16</A> for a way
|
|
of drawing horizontal text.) Pixels not
|
|
set by a particular character retain their previous color.
|
|
<p>
|
|
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 <a href="#gdImageStringUp">gdImageStringUp</a>.
|
|
<DT><A NAME="gdImageStringFT">
|
|
char *gdImageStringFT(gdImagePtr im, int *brect,
|
|
int fg, char *fontname, double ptsize, double angle,
|
|
int x, int y, char *string)</A>
|
|
<STRONG>(FUNCTION)</STRONG>
|
|
<DD>
|
|
<strong>RECOMMENDED. New in 1.8.4.</strong> gdImageStringFT draws text using the
|
|
FreeType 2.x library.
|
|
<p>
|
|
gdImageStringFT draws a string of anti-aliased characters on the image using
|
|
the <A HREF=http://www.freetype.org/>FreeType</A>
|
|
library to render user-supplied TrueType fonts. <strong>We do not provide
|
|
TrueType fonts (.ttf and .ttc files). Obtaining them is entirely up to
|
|
you.</strong> The string is anti-aliased, meaning that there should be
|
|
fewer "jaggies" visible. The fontname is the full pathname to a TrueType
|
|
font file, or a font face name if the GDFONTPATH environment variable
|
|
or FreeType's DEFAULT_FONTPATH variable have been set intelligently.
|
|
The string may be arbitrarily scaled (ptsize) and rotated (angle in radians).
|
|
<p>
|
|
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.
|
|
<TABLE BORDER="1">
|
|
<TR><TD ALIGN="LEFT" VALIGN="TOP" >0</TD><TD ALIGN="LEFT" VALIGN="TOP">
|
|
lower left corner, X position</TD></TR>
|
|
<TR><TD ALIGN="LEFT" VALIGN="TOP >1</TD><TD ALIGN="LEFT" VALIGN="TOP">
|
|
lower left corner, Y position</TD></TR>
|
|
<TR><TD ALIGN="LEFT" VALIGN="TOP >2</TD><TD ALIGN="LEFT" VALIGN="TOP">
|
|
lower right corner, X position</TD></TR>
|
|
<TR><TD ALIGN="LEFT" VALIGN="TOP">3</TD><TD ALIGN="LEFT" VALIGN="TOP">
|
|
lower right corner, Y position</TD></TR>
|
|
<TR><TD ALIGN="LEFT" VALIGN="TOP">4</TD><TD ALIGN="LEFT" VALIGN="TOP">
|
|
upper right corner, X position</TD></TR>
|
|
<TR><TD ALIGN="LEFT" VALIGN="TOP">5</TD><TD ALIGN="LEFT" VALIGN="TOP">
|
|
upper right corner, Y position</TD></TR>
|
|
<TR><TD ALIGN="LEFT" VALIGN="TOP">6</TD><TD ALIGN="LEFT" VALIGN="TOP">
|
|
upper left corner, X position</TD></TR>
|
|
<TR><TD ALIGN="LEFT" VALIGN="TOP">7</TD><TD ALIGN="LEFT" VALIGN="TOP">
|
|
upper left corner, Y position</TD></TR>
|
|
</TABLE>
|
|
<p>
|
|
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.
|
|
<p>
|
|
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.
|
|
<p>
|
|
The string is rendered in the color indicated by the gf color index.
|
|
<strong>Use the negative of the desired color index to
|
|
disable anti-aliasing.</strong>
|
|
<p>
|
|
The string may contain UTF-8 sequences like: "&#192;"
|
|
<p>
|
|
gdImageStringFT will return a null char* on success, or an error
|
|
string on failure.
|
|
<PRE>
|
|
#include "gd.h"
|
|
#include <string.h>
|
|
... inside a function ...
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> 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 = <A HREF="#gdImageStringFT">gdImageStringFT</A>(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 = <A HREF="#gdImageCreate">gdImageCreate</A>(x,y);
|
|
|
|
/* Background color (first allocated) */
|
|
white = <A HREF="#gdImageColorResolve">gdImageColorResolve</A>(im, 255, 255, 255);
|
|
black = <A HREF="#gdImageColorResolve">gdImageColorResolve</A>(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 = <A HREF="#gdImageStringFT">gdImageStringFT</A>(im,&brect[0],black,f,sz,0.0,x,y,s);
|
|
if (err) {fprintf(stderr,err); return 1;}
|
|
|
|
/* Write img to stdout */
|
|
<A HREF="#gdImagePng">gdImagePng</A>(im, stdout);
|
|
|
|
/* Destroy it */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
</PRE>
|
|
<DT><A NAME="gdImageStringTTF">
|
|
char *gdImageStringTTF(gdImagePtr im, int *brect,
|
|
int fg, char *fontname, double ptsize, double angle,
|
|
int x, int y, char *string)</A>
|
|
<STRONG>(FUNCTION)</STRONG>
|
|
<DD>
|
|
<strong>DEPRECATED.</strong> THis function simply invokes
|
|
<a href="#gdImageStringFT">gdImageStringFT</a> for backwards
|
|
compatibility with old code that was written with FreeType 1.x.
|
|
/DL>
|
|
<H3><A NAME="colors">Color-handling functions</A></H3>
|
|
<DL>
|
|
<DT><A NAME="gdImageColorAllocate">
|
|
int gdImageColorAllocate(gdImagePtr im, int r, int g, int b)</A>
|
|
<STRONG>(FUNCTION)</STRONG>
|
|
<DD>
|
|
gdImageColorAllocate finds the first available color index in
|
|
the image specified, sets its RGB values to those requested
|
|
(255 is the maximum for each),
|
|
and returns the index of the new color table entry, or an RGBA
|
|
value in the case of a truecolor image; in either case you can
|
|
then use the returned value as a parameter to drawing functions. When
|
|
creating a new palette-based image, the first time you invoke this function,
|
|
you are setting the background color for that image.
|
|
<P>
|
|
In the event that all <A HREF="#gdMaxColors">gdMaxColors</A> 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 <A HREF="#gdImageColorExact">gdImageColorExact</A>,
|
|
<A HREF="#gdImageColorClosest">gdImageColorClosest</A> and
|
|
<A HREF="#gdImageColorClosestHWB">gdImageColorClosestHWB</A>
|
|
for ways to locate existing colors that approximate the
|
|
color desired in situations where a new color is not available.
|
|
Also see <A HREF="#gdImageColorResolve">gdImageColorResolve</A>,
|
|
new in gd-1.6.2.
|
|
<PRE>
|
|
... inside a function ...
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im;
|
|
int black;
|
|
int red;
|
|
im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
|
|
/* Background color (first allocated) */
|
|
black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
|
|
/* Allocate the color red. */
|
|
red = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(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 */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
</PRE>
|
|
<DT><A NAME="gdImageColorAllocateAlpha">
|
|
int gdImageColorAllocateAlpha(gdImagePtr im, int r, int g, int b, int a)</A>
|
|
<STRONG>(FUNCTION)</STRONG>
|
|
<DD>
|
|
gdImageColorAllocateAlpha finds the first available color index in
|
|
the image specified, sets its RGBA values to those requested
|
|
(255 is the maximum for red, green and blue, and 127 represents
|
|
full transparency for alpha),
|
|
and returns the index of the new color table entry, or an RGBA
|
|
value in the case of a truecolor image; in either case you can
|
|
then use the returned value as a parameter to drawing functions. When
|
|
creating a new palette-based image, the first time you invoke this function,
|
|
you are setting the background color for that image.
|
|
<P>
|
|
In the event that all <A HREF="#gdMaxColors">gdMaxColors</A> 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 <A HREF="#gdImageColorExactAlpha">gdImageColorExactAlpha</A> and
|
|
<A HREF="#gdImageColorClosestAlpha">gdImageColorClosestAlpha</A>
|
|
for ways to locate existing colors that approximate the
|
|
color desired in situations where a new color is not available.
|
|
Also see <A HREF="#gdImageColorResolveAlpha">gdImageColorResolveAlpha</A>.
|
|
<PRE>
|
|
... inside a function ...
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im;
|
|
int black;
|
|
int red;
|
|
im = <A HREF="#gdImageCreate">gdImageCreate</A>(100, 100);
|
|
/* Background color (first allocated) */
|
|
black = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 0, 0, 0);
|
|
/* Allocate the color red, 50% transparent. */
|
|
red = <A HREF="#gdImageColorAllocateAlpha">gdImageColorAllocateAlpha</A>(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 */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
</PRE>
|
|
<DT><A NAME="gdImageColorClosest">
|
|
int gdImageColorClosest(gdImagePtr im, int r, int g, int b)</A>
|
|
<STRONG>(FUNCTION)</STRONG>
|
|
<DD>
|
|
gdImageColorClosest searches the colors which have been
|
|
defined thus far in the image specified and returns the
|
|
index of the color with RGB values closest to those of the
|
|
request. (Closeness is determined by Euclidian distance,
|
|
which is used to determine the distance in three-dimensional color
|
|
space between colors.)
|
|
<P>
|
|
If no colors have yet been allocated in the image,
|
|
gdImageColorClosest returns -1.
|
|
<p>
|
|
When applied to a truecolor image, this function always
|
|
succeeds in returning the desired color.
|
|
<P>
|
|
This function is most useful as a backup method for choosing
|
|
a drawing color when an image already contains
|
|
<A HREF="#gdMaxColors">gdMaxColors</A> (256) colors and
|
|
no more can be allocated. (This is not uncommon when
|
|
working with existing PNG files that already use many colors.)
|
|
See <A HREF="#gdImageColorExact">gdImageColorExact</A>
|
|
for a method of locating exact matches only.
|
|
<PRE>
|
|
... inside a function ...
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im;
|
|
FILE *in;
|
|
int red;
|
|
/* Let's suppose that photo.png is a scanned photograph with
|
|
many colors. */
|
|
in = fopen("photo.png", "rb");
|
|
im = <A HREF="#gdImageCreateFromPng">gdImageCreateFromPng</A>(in);
|
|
fclose(in);
|
|
/* Try to allocate red directly */
|
|
red = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 0, 0);
|
|
/* If we fail to allocate red... */
|
|
if (red == (-1)) {
|
|
/* Find the <em>closest</em> 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 */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
</PRE>
|
|
<DT><A NAME="gdImageColorClosestAlpha">
|
|
int gdImageColorClosestAlpha(gdImagePtr im, int r, int g, int b, int a)</A>
|
|
<STRONG>(FUNCTION)</STRONG>
|
|
<DD>
|
|
gdImageColorClosest searches the colors which have been
|
|
defined thus far in the image specified and returns the
|
|
index of the color with RGBA values closest to those of the
|
|
request. (Closeness is determined by Euclidian distance,
|
|
which is used to determine the distance in four-dimensional color/alpha
|
|
space between colors.)
|
|
<P>
|
|
If no colors have yet been allocated in the image,
|
|
gdImageColorClosestAlpha returns -1.
|
|
<p>
|
|
When applied to a truecolor image, this function always
|
|
succeeds in returning the desired color.
|
|
<P>
|
|
This function is most useful as a backup method for choosing
|
|
a drawing color when a palette-based image already contains
|
|
<A HREF="#gdMaxColors">gdMaxColors</A> (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 <A HREF="#gdImageColorExactAlpha">gdImageColorExactAlpha</A>
|
|
for a method of locating exact matches only.
|
|
<PRE>
|
|
... inside a function ...
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im;
|
|
FILE *in;
|
|
int red;
|
|
/* Let's suppose that photo.png is a scanned photograph with
|
|
many colors. */
|
|
in = fopen("photo.png", "rb");
|
|
im = <A HREF="#gdImageCreateFromPng">gdImageCreateFromPng</A>(in);
|
|
fclose(in);
|
|
/* Try to allocate red, 50% transparent, directly */
|
|
red = <A HREF="#gdImageColorAllocateAlpha">gdImageColorAllocateAlpha</A>(im, 255, 0, 0, 64);
|
|
/* If we fail to allocate red... */
|
|
if (red == (-1)) {
|
|
/* Find the <em>closest</em> 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 */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
</PRE>
|
|
<DT><A NAME="gdImageColorClosestHWB">
|
|
int gdImageColorClosestHWB(gdImagePtr im, int r, int g, int b)</A>
|
|
<STRONG>(FUNCTION)</STRONG>
|
|
<DD>
|
|
gdImageColorClosestHWB searches the colors which have been
|
|
defined thus far in the image specified and returns the
|
|
index of the color with hue, whiteness and blackness closest to the
|
|
requested color. This scheme is typically superior to the
|
|
Euclidian distance scheme used by
|
|
<a href="#gdImageColorClosest">gdImageColorClosest</a>.
|
|
<P>
|
|
If no colors have yet been allocated in the image,
|
|
gdImageColorClosestHWB returns -1.
|
|
<p>
|
|
When applied to a truecolor image, this function always
|
|
succeeds in returning the desired color.
|
|
<P>
|
|
This function is most useful as a backup method for choosing
|
|
a drawing color when an image already contains
|
|
<A HREF="#gdMaxColors">gdMaxColors</A> (256) colors and
|
|
no more can be allocated. (This is not uncommon when
|
|
working with existing PNG files that already use many colors.)
|
|
See <A HREF="#gdImageColorExact">gdImageColorExact</A>
|
|
for a method of locating exact matches only.
|
|
<PRE>
|
|
... inside a function ...
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im;
|
|
FILE *in;
|
|
int red;
|
|
/* Let's suppose that photo.png is a scanned photograph with
|
|
many colors. */
|
|
in = fopen("photo.png", "rb");
|
|
im = <A HREF="#gdImageCreateFromPng">gdImageCreateFromPng</A>(in);
|
|
fclose(in);
|
|
/* Try to allocate red directly */
|
|
red = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 0, 0);
|
|
/* If we fail to allocate red... */
|
|
if (red == (-1)) {
|
|
/* Find the <em>closest</em> 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 */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
</PRE>
|
|
<DT><A NAME="gdImageColorExact">
|
|
int gdImageColorExact(gdImagePtr im, int r, int g, int b)</A>
|
|
<STRONG>(FUNCTION)</STRONG>
|
|
<DD>
|
|
gdImageColorExact searches the colors which have been
|
|
defined thus far in the image specified and returns the
|
|
index of the first color with RGB values which exactly
|
|
match those of the request. If no allocated color matches the
|
|
request precisely, gdImageColorExact returns -1.
|
|
See <A HREF="#gdImageColorClosest">gdImageColorClosest</A>
|
|
for a way to find the color closest to the color requested.
|
|
<p>
|
|
When applied to a truecolor image, this function always
|
|
succeeds in returning the desired color.
|
|
<PRE>
|
|
... inside a function ...
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im;
|
|
int red;
|
|
in = fopen("photo.png", "rb");
|
|
im = <A HREF="#gdImageCreateFromPng">gdImageCreateFromPng</A>(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 = <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>(im, 255, 0, 0);
|
|
/* Out of colors, so find the <em>closest</em> 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 */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
</PRE>
|
|
<DT><A NAME="gdImageColorResolve">
|
|
int gdImageColorResolve(gdImagePtr im, int r, int g, int b)</A>
|
|
<STRONG>(FUNCTION)</STRONG>
|
|
<DD>
|
|
gdImageColorResolve searches the colors which have been
|
|
defined thus far in the image specified and returns the
|
|
index of the first color with RGB values which exactly
|
|
match those of the request. If no allocated color matches the
|
|
request precisely, then gdImageColorResolve tries to allocate the
|
|
exact color. If there is no space left in the color table then
|
|
gdImageColorResolve returns the closest color (as in gdImageColorClosest).
|
|
This function always returns an index of a color.
|
|
<p>
|
|
When applied to a truecolor image, this function always
|
|
succeeds in returning the desired color.
|
|
<PRE>
|
|
... inside a function ...
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im;
|
|
int red;
|
|
in = fopen("photo.png", "rb");
|
|
im = <A HREF="#gdImageCreateFromPng">gdImageCreateFromPng</A>(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 */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
</PRE>
|
|
<DT><A NAME="gdImageColorResolveAlpha">
|
|
int gdImageColorResolveAlpha(gdImagePtr im, int r, int g, int b, int a)</A>
|
|
<STRONG>(FUNCTION)</STRONG>
|
|
<DD>
|
|
gdImageColorResolveAlpha searches the colors which have been
|
|
defined thus far in the image specified and returns the
|
|
index of the first color with RGBA values which exactly
|
|
match those of the request. If no allocated color matches the
|
|
request precisely, then gdImageColorResolveAlpha tries to allocate the
|
|
exact color. If there is no space left in the color table then
|
|
gdImageColorResolveAlpha returns the closest color (as in gdImageColorClosestAlpha).
|
|
This function always returns an index of a color.
|
|
<p>
|
|
When applied to a truecolor image, this function always
|
|
succeeds in returning the desired color.
|
|
<PRE>
|
|
... inside a function ...
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im;
|
|
int red;
|
|
in = fopen("photo.png", "rb");
|
|
im = <A HREF="#gdImageCreateFromPng">gdImageCreateFromPng</A>(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 */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
</PRE>
|
|
<DT><A NAME="gdImageColorsTotal">
|
|
int gdImageColorsTotal(gdImagePtr im)</A>
|
|
<STRONG>(MACRO)</STRONG>
|
|
<DD>
|
|
gdImageColorsTotal is a macro which returns the number of
|
|
colors currently allocated in a palette image. For truecolor
|
|
images, the result of this call is undefined and should not
|
|
be used.
|
|
<DT><A NAME="gdImageColorRed">
|
|
int gdImageColorRed(gdImagePtr im, int c)</A>
|
|
<STRONG>(MACRO)</STRONG>
|
|
<DD>
|
|
gdImageColorRed is a macro which returns the red portion
|
|
of the specified color in the image. This macro works
|
|
for both palette and truecolor images.
|
|
<DT><A NAME="gdImageColorGreen">
|
|
int gdImageColorGreen(gdImagePtr im, int c)</A>
|
|
<STRONG>(MACRO)</STRONG>
|
|
<DD>
|
|
gdImageColorGreen is a macro which returns the green portion
|
|
of the specified color in the image. This macro works
|
|
for both palette and truecolor images.
|
|
<DT><A NAME="gdImageColorBlue">
|
|
int gdImageColorBlue(gdImagePtr im, int c)</A>
|
|
<STRONG>(MACRO)</STRONG>
|
|
<DD>
|
|
gdImageColorBlue is a macro which returns the green portion
|
|
of the specified color in the image. This macro works
|
|
for both palette and truecolor images.
|
|
<DT><A NAME="gdImageGetInterlaced">
|
|
int gdImageGetInterlaced(gdImagePtr im)</A>
|
|
<STRONG>(MACRO)</STRONG>
|
|
<DD>
|
|
gdImageGetInterlaced is a macro which returns true (1)
|
|
if the image is interlaced, false (0) if not.
|
|
Use this macro to obtain this information; do not
|
|
access the structure directly.
|
|
See <A HREF="#gdImageInterlace">gdImageInterlace</A> for
|
|
a means of interlacing images.
|
|
<DT><A NAME="gdImageGetTransparent">
|
|
int gdImageGetTransparent(gdImagePtr im)</A>
|
|
<STRONG>(MACRO)</STRONG>
|
|
<DD>
|
|
gdImageGetTransparent is a macro which returns the
|
|
current transparent color index in the image.
|
|
If there is no transparent color, gdImageGetTransparent
|
|
returns -1. Use this macro to obtain this information; do not
|
|
access the structure directly.
|
|
<DT><A NAME="gdImageColorDeallocate">
|
|
void gdImageColorDeallocate(gdImagePtr im, int color)</A>
|
|
<STRONG>(FUNCTION)</STRONG>
|
|
<DD>
|
|
gdImageColorDeallocate marks the specified color as being
|
|
available for reuse. It does not attempt to determine whether
|
|
the color index is still in use in the image. After a call
|
|
to this function, the next call to
|
|
<A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>
|
|
for the same image will set new RGB values for that
|
|
color index, changing the color of any pixels which
|
|
have that index as a result. If multiple calls to
|
|
gdImageColorDeallocate are made consecutively, the lowest-numbered
|
|
index among them will be reused by the next
|
|
<A HREF="#gdImageColorAllocate"> gdImageColorAllocate</A> call.
|
|
<PRE>
|
|
... inside a function ...
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im;
|
|
int red, blue;
|
|
in = fopen("photo.png", "rb");
|
|
im = <A HREF="#gdImageCreateFromPng">gdImageCreateFromPng</A>(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 */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
</PRE>
|
|
<DT><A NAME="gdImageColorTransparent">
|
|
void gdImageColorTransparent(gdImagePtr im, int color)</A>
|
|
<STRONG>(FUNCTION)</STRONG>
|
|
<DD>
|
|
gdImageColorTransparent sets the transparent color index
|
|
for the specified image to the specified index. To indicate
|
|
that there should be <em>no</em> transparent color, invoke
|
|
gdImageColorTransparent with a color index of -1. Note that
|
|
JPEG images do not support transparency, so this setting has no effect
|
|
when writing JPEG images.
|
|
<P>
|
|
The color index used should be an index
|
|
allocated by <A HREF="#gdImageColorAllocate">gdImageColorAllocate</A>,
|
|
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,
|
|
<em>even though it will be transparent on systems
|
|
that support PNG transparency</em>.
|
|
<PRE>
|
|
... inside a function ...
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im;
|
|
int black;
|
|
FILE *in, *out;
|
|
in = fopen("photo.png", "rb");
|
|
im = <A HREF="#gdImageCreateFromPng">gdImageCreateFromPng</A>(in);
|
|
fclose(in);
|
|
/* Look for black in the color table and make it transparent. */
|
|
black = <A HREF="#gdImageColorExact">gdImageColorExact</A>(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");
|
|
<A HREF="#gdImagePng">gdImagePng</A>(im, out);
|
|
fclose(out);
|
|
/* Destroy it */
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
</PRE>
|
|
<DT><A NAME="gdImageTrueColor">
|
|
void gdImageTrueColor(int red, int green, int blue)</A>
|
|
<STRONG>(MACRO)</STRONG>
|
|
<DD>
|
|
gdImageTrueColor returns an RGBA color value for use when
|
|
drawing on a truecolor image. Red, green, and blue are all
|
|
in the range between 0 (off) and 255 (maximum). This macro should
|
|
not be used with palette-based images. If you need to write
|
|
code which is compatible with both palette-based and
|
|
truecolor images, use <a href="#gdImageColorResolve">gdImageColorResolve</a>.
|
|
<DT><A NAME="gdImageTrueColorAlpha">
|
|
void gdImageTrueColorAlpha(int red, int green, int blue, int alpha)</A>
|
|
<STRONG>(MACRO)</STRONG>
|
|
<DD>
|
|
gdImageTrueColorAlpha returns an RGBA color value for use when
|
|
drawing on a truecolor image with alpha channel transparency. Red,
|
|
green, and blue are all
|
|
in the range between 0 (off) and 255 (maximum). Alpha is in the
|
|
range between 0 (opaque) and 127 (fully transparent). This macro should
|
|
not be used with palette-based images. If you need to write
|
|
code which is compatible with both palette-based and
|
|
truecolor images, use <a href="#gdImageColorResolveAlpha">gdImageColorResolveAlpha</a>.</DL>
|
|
<H3><A NAME="copying">Copying and resizing functions</A></H3>
|
|
<DL>
|
|
|
|
<DT><A NAME="gdImageCopy">void gdImageCopy(gdImagePtr dst, gdImagePtr src, int dstX, int dstY, int srcX, int srcY, int w, int h)
|
|
<STRONG> (FUNCTION)</STRONG>
|
|
<DD>
|
|
gdImageCopy is used to copy a rectangular portion of one image to
|
|
another image. (For a way of stretching or shrinking the image
|
|
in the process, see <A HREF="#gdImageCopyResized">
|
|
gdImageCopyResized</A>.)
|
|
<P>
|
|
The <code>dst</code> argument is the destination image to which the
|
|
region will be copied. The <code>src</code> argument is the source
|
|
image from which the region is copied. The <code>dstX</code>
|
|
and <code>dstY</code> arguments specify the point in the destination
|
|
image to which the region will be copied. The <code>srcX</code>
|
|
and <code>srcY</code> arguments specify the upper left corner
|
|
of the region in the source image. The <code>w</code>
|
|
and <code>h</code> arguments specify the width and height
|
|
of the region.
|
|
<P>
|
|
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.
|
|
<P>
|
|
<strong>Important note on copying between images:</strong> 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 <A HREF="#gdImageColorExact">gdImageColorExact</A>. If
|
|
such a value is not found, gdImageCopy will attempt to
|
|
allocate colors as needed using <A HREF="#gdImageColorAllocate">
|
|
gdImageColorAllocate</A>. If both of these methods fail,
|
|
gdImageCopy will invoke <A HREF="#gdImageColorClosest">
|
|
gdImageColorClosest</A> to find the color in the destination
|
|
image which most closely approximates the color of the
|
|
pixel being copied.
|
|
<PRE>
|
|
... Inside a function ...
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im_in;
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> 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 = <A HREF="#gdImageCreateFromPng">gdImageCreateFromPng</A>(in);
|
|
fclose(in);
|
|
/* Make the output image four times as large on both axes */
|
|
im_out = <A HREF="#gdImageCreate">gdImageCreate</A>(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");
|
|
<A HREF="#gdImagePng">gdImagePng</A>(im_out, out);
|
|
fclose(out);
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im_in);
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im_out);
|
|
</PRE>
|
|
<DT><A NAME="gdImageCopyResized">void gdImageCopyResized(gdImagePtr dst, gdImagePtr src, int dstX, int dstY, int srcX, int srcY, int destW, int destH, int srcW, int srcH)
|
|
<STRONG> (FUNCTION)</STRONG>
|
|
<DD>
|
|
gdImageCopyResized is used to copy a rectangular portion of one image to
|
|
another image. The X and Y dimensions of the original region and the
|
|
destination region can vary, resulting in stretching or shrinking of
|
|
the region as appropriate. (For a simpler version of this function
|
|
which does not deal with resizing, see <A HREF="#gdImageCopy">
|
|
gdImageCopy</A>.)
|
|
<P>
|
|
The <code>dst</code> argument is the destination image to which the
|
|
region will be copied. The <code>src</code> argument is the source
|
|
image from which the region is copied. The <code>dstX</code>
|
|
and <code>dstY</code> arguments specify the point in the destination
|
|
image to which the region will be copied. The <code>srcX</code>
|
|
and <code>srcY</code> arguments specify the upper left corner
|
|
of the region in the source image. The <code>dstW</code>
|
|
and <code>dstH</code> arguments specify the width and height
|
|
of the destination region. The <code>srcW</code>
|
|
and <code>srcH</code> 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.
|
|
<P>
|
|
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.
|
|
<P>
|
|
<strong>Important note on copying between images:</strong> 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 <A HREF="#gdImageColorExact">gdImageColorExact</A>. If
|
|
such a value is not found, gdImageCopy will attempt to
|
|
allocate colors as needed using <A HREF="#gdImageColorAllocate">
|
|
gdImageColorAllocate</A>. If both of these methods fail,
|
|
gdImageCopy will invoke <A HREF="#gdImageColorClosest">
|
|
gdImageColorClosest</A> to find the color in the destination
|
|
image which most closely approximates the color of the
|
|
pixel being copied.
|
|
<PRE>
|
|
... Inside a function ...
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im_in;
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> 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 = <A HREF="#gdImageCreateFromPng">gdImageCreateFromPng</A>(in);
|
|
fclose(in);
|
|
/* Make the output image four times as large on both axes */
|
|
im_out = <A HREF="#gdImageCreate">gdImageCreate</A>(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");
|
|
<A HREF="#gdImagePng">gdImagePng</A>(im_out, out);
|
|
fclose(out);
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im_in);
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im_out);
|
|
</PRE>
|
|
<DT><A NAME="gdImageCopyResampled">void gdImageCopyResampled(gdImagePtr dst, gdImagePtr src, int dstX, int dstY, int srcX, int srcY, int destW, int destH, int srcW, int srcH)
|
|
<STRONG> (FUNCTION)</STRONG>
|
|
<DD>
|
|
gdImageCopyResampled is used to copy a rectangular portion of one image to
|
|
another image, smoothly interpolating pixel values so that, in particular,
|
|
reducing the size of an image still retains a great deal of clarity. The
|
|
X and Y dimensions of the original region and the
|
|
destination region can vary, resulting in stretching or shrinking of
|
|
the region as appropriate. (For a simpler version of this function
|
|
which does not deal with resizing, see <A HREF="#gdImageCopy">
|
|
gdImageCopy</A>. For a version which does not interpolate pixel values,
|
|
see <A HREF="#gdImageCopyResized">gdImageCopyResized</A>.
|
|
<p>
|
|
Pixel values are only interpolated if the destination image is a
|
|
truecolor image. Otherwise,
|
|
<a href="#gdImageCopyResized">gdImageCopyResized</a> is
|
|
automatically invoked.
|
|
<P>
|
|
The <code>dst</code> argument is the destination image to which the
|
|
region will be copied. The <code>src</code> argument is the source
|
|
image from which the region is copied. The <code>dstX</code>
|
|
and <code>dstY</code> arguments specify the point in the destination
|
|
image to which the region will be copied. The <code>srcX</code>
|
|
and <code>srcY</code> arguments specify the upper left corner
|
|
of the region in the source image. The <code>dstW</code>
|
|
and <code>dstH</code> arguments specify the width and height
|
|
of the destination region. The <code>srcW</code>
|
|
and <code>srcH</code> 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.
|
|
<P>
|
|
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.
|
|
<P>
|
|
<strong>Important note on copying between images:</strong> 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
|
|
<a href="#gdImageColorResolve">gdImageColorResolve</a> function to
|
|
determine the best color available.
|
|
<PRE>
|
|
... Inside a function ...
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> im_in;
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> 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 = <A HREF="#gdImageCreateFromPng">gdImageCreateFromPng</A>(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 = <A HREF="#gdImageCreate">gdImageCreateTrueColor</A>(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");
|
|
<A HREF="#gdImagePng">gdImagePng</A>(im_out, out);
|
|
fclose(out);
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im_in);
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im_out);
|
|
</PRE>
|
|
|
|
<DT><A NAME="gdImageCopyMerge">void gdImageCopyMerge(gdImagePtr dst, gdImagePtr src, int dstX, int dstY, int srcX, int srcY, int w, int h, int pct)
|
|
<STRONG> (FUNCTION)</STRONG>
|
|
<DD>
|
|
gdImageCopyMerge is almost identical to <a href=#gdImageCopy>gdImageCopy</a>, except that
|
|
it 'merges' the two images by an amount specified in the last parameter. If the last
|
|
parameter is 100, then it will function identically to gdImageCopy - the source image replaces
|
|
the pixels in the destination.
|
|
<p>
|
|
If, however, the <strong>pct</strong> parameter is less than 100, then the two images are merged.
|
|
With pct = 0, no action is taken.
|
|
<p>This feature is most useful to 'highlight' sections of an image by merging a solid color with
|
|
pct = 50:
|
|
<PRE>
|
|
... Inside a function ...
|
|
gdImageCopyMerge(im_out, im_in, 100, 200, 0, 0, 30, 50, 50);
|
|
</PRE>
|
|
|
|
<DT><A NAME="gdImageCopyMergeGray">void gdImageCopyMergeGray(gdImagePtr dst, gdImagePtr src, int dstX, int dstY, int srcX, int srcY, int
|
|
w, int h, int pct)
|
|
<STRONG> (FUNCTION)</STRONG>
|
|
<DD>
|
|
gdImageCopyMergeGray is almost identical to <a href=#gdImageCopyMerge>gdImageCopyMerge</a>,
|
|
except that when merging images it preserves the hue of the source by converting the destination
|
|
pixels to grey scale before the copy operation.
|
|
<PRE>
|
|
... Inside a function ...
|
|
gdImageCopyMergeGray(im_out, im_in, 100, 200, 0, 0, 30, 50, 50);
|
|
</PRE>
|
|
|
|
<DT><A NAME="gdImagePaletteCopy">void gdImagePaletteCopy(gdImagePtr dst, gdImagePtr src)
|
|
<STRONG> (FUNCTION)</STRONG>
|
|
<DD>
|
|
Copies a palette from one image to another, attempting to match the colors in the target image
|
|
to the colors
|
|
in the source palette.
|
|
</DL>
|
|
<H3><A NAME="misc">Miscellaneous Functions</A></H3>
|
|
<DL>
|
|
|
|
<DT><A NAME="gdImageCompare">int gdImageCompare(gdImagePtr im1, gdImagePtr im2)
|
|
<STRONG> (FUNCTION)</STRONG>
|
|
<DD>
|
|
gdImageCompare returns a bitmap indicating if the two images are different. The members of the
|
|
bitmap are defined in gd.h, but the most important is GD_CMP_IMAGE, which indicated that the images
|
|
will actually appear different when displayed. Other, less important, differences relate to pallette
|
|
entries. Any difference in the transparent colour is assumed to make images display differently,
|
|
even if the transparent colour is not used.
|
|
<PRE>
|
|
... Inside a function ...
|
|
cmpMask = gdImageCompare(im1, im2);
|
|
</PRE>
|
|
|
|
<DT><A NAME="gdImageInterlace">gdImageInterlace(gdImagePtr im, int interlace)</A> <strong>(FUNCTION)</strong>
|
|
<DD>
|
|
gdImageInterlace is used to determine whether an image should be stored
|
|
in a linear fashion, in which lines will appear on the display from
|
|
first to last, or in an interlaced fashion, in which the image
|
|
will "fade in" over several passes. By default, images are not
|
|
interlaced. (When writing JPEG images, interlacing implies generating
|
|
progressive JPEG files, which are represented as a series of scans of
|
|
increasing quality. Noninterlaced gd images result in regular
|
|
[sequential] JPEG data streams.)
|
|
<P>
|
|
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.
|
|
<P>
|
|
When a PNG is loaded with
|
|
<A HREF="#gdImageCreateFromPng">gdImageCreateFromPng</A> or a JPEG is
|
|
loaded with
|
|
<A HREF="#gdImageCreateFromJpeg">gdImageCreateFromJpeg</A>, interlace
|
|
will be set according to the setting in the PNG or JPEG file.
|
|
<P>
|
|
Note that many PNG and JPEG viewers and web browsers do <em>not</em>
|
|
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.
|
|
<PRE>
|
|
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 <A HREF="#gdImageJpeg">gdImageJpeg</A> */
|
|
<A HREF="#gdImagePng">gdImagePng</A>(im, out);
|
|
fclose(out);
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A>(im);
|
|
</PRE>
|
|
<DT><A NAME="gdFree">gdFree(void *ptr)</A> <strong>(FUNCTION)</strong>
|
|
<DD>
|
|
gdFree provides a reliable way to free memory allocated by functions
|
|
such as <a href="#gdImagePngPtr">gdImagePngPtr</a> which return
|
|
blocks of memory. Use of this function guarantees that the
|
|
version of <code>free()</code> that is ultimately called will
|
|
be intended for use with the version of <code>malloc()</code> that
|
|
originally allocated the block.
|
|
</DL>
|
|
<H3><A NAME="constants">Constants</A></H3>
|
|
<DL>
|
|
<DT><A NAME="gdBrushed">gdBrushed</A> <strong>(CONSTANT)</strong>
|
|
<DD>
|
|
Used in place of a color when invoking a line-drawing
|
|
function such as <A HREF="#gdImageLine">gdImageLine</A>
|
|
or <A HREF="#gdImageRectangle">gdImageRectangle</A>.
|
|
When gdBrushed is used as the color, the brush
|
|
image set with <A HREF="#gdImageSetBrush">gdImageSetBrush</A>
|
|
is drawn in place of each pixel of the line (the brush is
|
|
usually larger than one pixel, creating the effect
|
|
of a wide paintbrush). See also
|
|
<A HREF="#gdStyledBrushed">gdStyledBrushed</A> for a way
|
|
to draw broken lines with a series of distinct copies of an image.
|
|
<DT><A NAME="gdMaxColors"><code>gdMaxColors</code><strong>(CONSTANT)</strong>
|
|
<DD>
|
|
The constant 256. This is the maximum number of colors in a PNG file
|
|
according to the PNG standard, and is also the maximum number of
|
|
colors in a gd image.
|
|
<DT><A NAME="gdStyled">gdStyled</A> <strong>(CONSTANT)</strong>
|
|
<DD>
|
|
Used in place of a color when invoking a line-drawing
|
|
function such as <A HREF="#gdImageLine">gdImageLine</A>
|
|
or <A HREF="#gdImageRectangle">gdImageRectangle</A>.
|
|
When gdStyled is used as the color, the colors of the pixels are
|
|
drawn successively from the style that has been
|
|
set with <A HREF="#gdImageSetStyle">gdImageSetStyle</A>.
|
|
If the color of a pixel is equal to
|
|
<A HREF="#gdTransparent">gdTransparent</A>, that pixel
|
|
is not altered. (This mechanism is completely unrelated
|
|
to the "transparent color" of the image itself; see
|
|
<A HREF="#gdImageColorTransparent">gdImageColorTransparent</A>
|
|
gdImageColorTransparent for that mechanism.) See also
|
|
<A NAME="#gdStyledBrushed"> gdStyledBrushed</A>.
|
|
<DT><A NAME="gdStyledBrushed">gdStyledBrushed</A> <strong>(CONSTANT)</strong>
|
|
<DD>
|
|
Used in place of a color when invoking a line-drawing
|
|
function such as <A HREF="#gdImageLine">gdImageLine</A>
|
|
or <A HREF="#gdImageRectangle">gdImageRectangle</A>.
|
|
When gdStyledBrushed is used as the color, the brush
|
|
image set with <A HREF="#gdImageSetBrush">gdImageSetBrush</A>
|
|
is drawn at each pixel of the line, providing that the
|
|
style set with <A HREF="#gdImageSetStyle">gdImageSetStyle</A>
|
|
contains a nonzero value (OR gdTransparent, which
|
|
does not equal zero but is supported for consistency)
|
|
for the current pixel. (Pixels are drawn successively from the style as the
|
|
line is drawn, returning to the beginning when the
|
|
available pixels in the style are exhausted.) Note that
|
|
this differs from the behavior of <A HREF="#gdStyled">gdStyled</A>,
|
|
in which the values in the style are used as actual
|
|
pixel colors, except for gdTransparent.
|
|
<DT><A NAME="gdDashSize">gdDashSize</A> <strong>(CONSTANT)</strong>
|
|
<DD>
|
|
The length of a dash in a dashed line. Defined to be 4 for
|
|
backwards compatibility with programs that use
|
|
<A NAME="gdImageDashedLine">gdImageDashedLine</A>. New
|
|
programs should use <A NAME="gdImageSetStyle">
|
|
gdImageSetStyle</A> and call the standard
|
|
<A NAME="gdImageLine">gdImageLine</A> function
|
|
with the special "color" <A NAME="gdStyled">
|
|
gdStyled</A> or <A NAME="gdStyledBrushed">gdStyledBrushed</A>.
|
|
<DT><A NAME="gdTiled">gdTiled</A> <strong>(CONSTANT)</strong>
|
|
<DD>
|
|
Used in place of a normal color in <A HREF="#gdImageFilledRectangle">
|
|
gdImageFilledRectangle</A>, <A HREF="#gdImageFilledPolygon">
|
|
gdImageFilledPolygon</A>,
|
|
<A HREF="#gdImageFill">gdImageFill</A>, and <A HREF="#gdImageFillToBorder">
|
|
gdImageFillToBorder</A>. gdTiled selects a pixel from the
|
|
tile image set with <A HREF="#gdImageSetTile">gdImageSetTile</A>
|
|
in such a way as to ensure that the filled area will be
|
|
tiled with copies of the tile image. See the discussions of
|
|
<A HREF="#gdImageFill">gdImageFill</A> and
|
|
<A HREF="#gdImageFillToBorder">gdImageFillToBorder</A> for special
|
|
restrictions regarding those functions.
|
|
<DT><A NAME="gdTransparent">gdTransparent</A> <strong>(CONSTANT)</strong>
|
|
<DD>
|
|
Used in place of a normal color in a style to be set with
|
|
<A HREF="#gdImageSetStyle">gdImageSetStyle</A>.
|
|
gdTransparent is <strong>not</strong> the transparent
|
|
color index of the image; for that functionality please
|
|
see <A HREF="#gdImageColorTransparent">gdImageColorTransparent</A>.
|
|
</DL>
|
|
|
|
<A NAME="gdformat"><H3>About the additional .gd image file format</H3></A>
|
|
In addition to reading and writing the PNG and JPEG formats and reading the
|
|
X Bitmap format, gd has the capability to read and write its
|
|
own ".gd" format. This format is <em>not</em> intended for
|
|
general purpose use and should never be used to distribute
|
|
images. It is not a compressed format. Its purpose is solely to
|
|
allow very fast loading of images your program needs often in
|
|
order to build other images for output. If you are experiencing
|
|
performance problems when loading large, fixed PNG images your
|
|
program needs to produce its output images, you may wish
|
|
to examine the functions <A HREF="#gdImageCreateFromGd">
|
|
gdImageCreateFromGd</A> and <A HREF="#gdImageGd">gdImageGd</A>,
|
|
which read and write .gd format images.
|
|
|
|
<P>
|
|
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.
|
|
|
|
<A NAME="gd2format"><H3>About the .gd2 image file format</H3></A>
|
|
In addition to reading and writing the PNG format and reading the
|
|
X Bitmap format, gd has the capability to read and write its
|
|
own ".gd2" format. This format is <em>not</em> intended for
|
|
general purpose use and should never be used to distribute
|
|
images. It is a compressed format allowing pseudo-random access
|
|
to large image files. Its purpose is solely to
|
|
allow very fast loading of <strong>parts</strong> of images
|
|
If you are experiencing
|
|
performance problems when loading large, fixed PNG or JPEG images your
|
|
program needs to produce its output images, you may wish
|
|
to examine the functions <A HREF="#gdImageCreateFromGd2">
|
|
gdImageCreateFromGd2</A>, <A HREF="#gdImageCreateFromGd2Part">
|
|
gdImageCreateFromGd2Part</A> and <A HREF="#gdImageGd2">gdImageGd2</A>,
|
|
which read and write .gd2 format images.
|
|
|
|
<P>
|
|
The program "pngtogd2.c" is provided as a simple way of converting
|
|
.png files to .gd2 format.
|
|
|
|
<A NAME="gdioctx"><H3>About the gdIOCtx structure</H3></A>
|
|
Version 1.5 of GD added a new style of I/O based on an IOCtx
|
|
structure (the most up-to-date version can be found in gd_io.h):
|
|
<PRE>
|
|
typedef struct gdIOCtx {
|
|
int (*getC)(struct gdIOCtx*);
|
|
int (*getBuf)(struct gdIOCtx*, void*, int);
|
|
|
|
void (*putC)(struct gdIOCtx*, int);
|
|
int (*putBuf)(struct gdIOCtx*, const void*, int);
|
|
|
|
int (*seek)(struct gdIOCtx*, const int);
|
|
long (*tell)(struct gdIOCtx*);
|
|
|
|
void (*free)(struct gdIOCtx*);
|
|
|
|
} gdIOCtx;
|
|
</PRE>
|
|
|
|
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.
|
|
<p>
|
|
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).
|
|
<p>
|
|
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:
|
|
<p>
|
|
<Table>
|
|
<TR><TD>All</TD><td width=20> </td><TD>Must have 'free',</td></tr>
|
|
<TR><TD>Anything that reads from the context</TD><td></td><TD>Must have 'getC' and 'getBuf',</td></tr>
|
|
<TR><TD>Anything that writes to the context</TD><td></td><TD>Must have 'putC' and 'putBuf'.</td></tr>
|
|
<TR><TD>If gdCreateFromGd2Part is called</td><td></td><TD>Must also have 'seek' and 'tell'.</td></tr>
|
|
<TR><TD>If gdImageGd2 is called</td><td></td><TD>Must also have 'seek' and 'tell'.</td></tr>
|
|
</Table>
|
|
|
|
|
|
|
|
<A NAME="informing"><H3>Please tell us you're using gd!</H3>
|
|
When you contact us and let us know you are using gd,
|
|
you help us justify the time spent in maintaining and improving
|
|
it. So please let us know. If the results are publicly
|
|
visible on the web, a URL is a wonderful thing to receive, but
|
|
if it's not a publicly visible project, a simple note is just
|
|
as welcome.
|
|
|
|
<A NAME="problems"><H3>If you have problems</H3></A>
|
|
If you have any difficulties with gd, feel free to contact
|
|
the author, <A HREF="http://www.boutell.com/boutell/">Thomas Boutell</A>.
|
|
Problems relating to the gd2 format should be addressed to
|
|
<a href=mailto:pjw@thyme.com.au>Philip Warner</a>.
|
|
<p><strong>
|
|
Be sure to read this manual carefully first.
|
|
</strong>
|
|
|
|
<H3><A NAME="index">Alphabetical quick index</A></H3>
|
|
<A HREF="#gdBrushed">gdBrushed</A> |
|
|
<A HREF="#gdDashSize">gdDashSize</A> |
|
|
<A HREF="#gdFont">gdFont</A> |
|
|
<A HREF="#gdFontPtr">gdFontPtr</A> |
|
|
<A HREF="#gdFree">gdFree</A> |
|
|
<A HREF="#gdImage">gdImage</A> |
|
|
<A HREF="#gdImageAlphaBlending">gdImageAlphaBlending</A> |
|
|
<A HREF="#gdImageArc">gdImageArc</A> |
|
|
<A HREF="#gdImageBlue">gdImageBlue</A> |
|
|
<A HREF="#gdImageBoundsSafe">gdImageBoundsSafe</A> |
|
|
<A HREF="#gdImageChar">gdImageChar</A> |
|
|
<A HREF="#gdImageCharUp">gdImageCharUp</A> |
|
|
<A HREF="#gdImageColorAllocate">gdImageColorAllocate</A> |
|
|
<A HREF="#gdImageColorAllocateAlpha">gdImageColorAllocateAlpha</A> |
|
|
<A HREF="#gdImageColorClosest">gdImageColorClosest</A> |
|
|
<A HREF="#gdImageColorClosestAlpha">gdImageColorClosestAlpha</A> |
|
|
<A HREF="#gdImageColorDeallocate">gdImageColorDeallocate</A> |
|
|
<A HREF="#gdImageColorExact">gdImageColorExact</A> |
|
|
<A HREF="#gdImageColorExactAlpha">gdImageColorExactAlpha</A> |
|
|
<A HREF="#gdImageColorResolve">gdImageColorResolve</A> |
|
|
<A HREF="#gdImageColorResolveAlpha">gdImageColorResolveAlpha</A> |
|
|
<A HREF="#gdImageColorTransparent">gdImageColorTransparent</A> |
|
|
<A HREF="#gdImageCopy">gdImageCopy</A> |
|
|
<A HREF="#gdImageCopyMerge">gdImageCopyMerge</A> |
|
|
<A HREF="#gdImageCopyMergeGray">gdImageMergeGray</A> |
|
|
<A HREF="#gdImageCopyResized">gdImageCopyResized</A> |
|
|
<A HREF="#gdImageCopyResampled">gdImageCopyResampled</A> |
|
|
<A HREF="#gdImageCreate">gdImageCreate</A> |
|
|
<A HREF="#gdImageCreate">gdImageCreatePalette</A> |
|
|
<A HREF="#gdImageCreate">gdImageCreateTrueColor</A> |
|
|
<A HREF="#gdImageCreateFromGd">gdImageCreateFromGd</A> |
|
|
<A HREF="#gdImageCreateFromGd2">gdImageCreateFromGd2</A> |
|
|
<A HREF="#gdImageCreateFromGd2Part">gdImageCreateFromGd2Part</A> |
|
|
<A HREF="#gdImageCreateFromJpeg">gdImageCreateFromJpeg</A> |
|
|
<A HREF="#gdImageCreateFromPng">gdImageCreateFromPng</A> |
|
|
<A HREF="#gdImageCreateFromPngSource">gdImageCreateFromPngSource</A> |
|
|
<A HREF="#gdImageCreateFromXbm">gdImageCreateFromXbm</A> |
|
|
<A HREF="#gdImageCreateFromXpm">gdImageCreateFromXpm</A> |
|
|
<A HREF="#gdImageDashedLine">gdImageDashedLine</A> |
|
|
<A HREF="#gdImageDestroy">gdImageDestroy</A> |
|
|
<A HREF="#gdImageFill">gdImageFill</A> |
|
|
<A HREF="#gdImageFilledArc">gdImageFilledArc</A> |
|
|
<A HREF="#gdImageFilledEllipse">gdImageFilledEllipse</A> |
|
|
<A HREF="#gdImageFillToBorder">gdImageFillToBorder</A> |
|
|
<A HREF="#gdImageFilledRectangle">gdImageFilledRectangle</A> |
|
|
<A HREF="#gdImageGd">gdImageGd</A> |
|
|
<A HREF="#gdImageGd">gdImageGd2</A> |
|
|
<A HREF="#gdImageGetInterlaced">gdImageGetInterlaced</A> |
|
|
<A HREF="#gdImageGetPixel">gdImageGetPixel</A> |
|
|
<A HREF="#gdImageGetTransparent">gdImageGetTransparent</A> |
|
|
<A HREF="#gdImageGreen">gdImageGreen</A> |
|
|
<A HREF="#gdImageInterlace">gdImageInterlace</A> |
|
|
<A HREF="#gdImageJpeg">gdImageJpeg</A> |
|
|
<A HREF="#gdImageLine">gdImageLine</A> |
|
|
<A HREF="#gdImageFilledPolygon">gdImageFilledPolygon</A> |
|
|
<A HREF="#gdImagePaletteCopy">gdImagePaletteCopy</A> |
|
|
<A HREF="#gdImagePng">gdImagePng</A> |
|
|
<A HREF="#gdImagePngToSink">gdImagePngToSink</A> |
|
|
<A HREF="#gdImagePolygon">gdImagePolygon</A> |
|
|
<A HREF="#gdImagePtr">gdImagePtr</A> |
|
|
<A HREF="#gdImageWBMP">gdImageWBMP</A> |
|
|
<A HREF="#gdImageRectangle">gdImageRectangle</A> |
|
|
<A HREF="#gdImageRed">gdImageRed</A> |
|
|
<A HREF="#gdImageSetBrush">gdImageSetBrush</A> |
|
|
<A HREF="#gdImageSetPixel">gdImageSetPixel</A> |
|
|
<A HREF="#gdImageSetStyle">gdImageSetStyle</A> |
|
|
<A HREF="#gdImageSetTile">gdImageSetTile</A> |
|
|
<A HREF="#gdImageString">gdImageString</A> |
|
|
<A HREF="#gdImageString16">gdImageString16</A> |
|
|
<A HREF="#gdImageStringFT">gdImageStringFT</A> |
|
|
<A HREF="#gdImageStringTTF">gdImageStringTTF</A> |
|
|
<A HREF="#gdImageStringUp">gdImageStringUp</A> |
|
|
<A HREF="#gdImageStringUp">gdImageStringUp16</A> |
|
|
<A HREF="#gdImageWBMP">gdImageWBMP</A> |
|
|
<A HREF="#gdMaxColors">gdMaxColors</A> |
|
|
<A HREF="#gdPoint">gdPoint</A> |
|
|
<A HREF="#gdStyled">gdStyled</A> |
|
|
<A HREF="#gdStyledBrushed">gdStyledBrushed</A> |
|
|
<A HREF="#gdTiled">gdTiled</A> |
|
|
<A HREF="#gdTransparent">gdTransparent</A>
|
|
<P>
|
|
<em><A HREF="http://www.boutell.com/">
|
|
Boutell.Com, Inc.</A></em>
|
|
</BODY>
|
|
</HTML>
|