Page Hits
Site Hits
Since
|
GD for Euphoria Manual
gd 2.0.33
A Graphics Library for Fast Image Creation
UPGRADING UNIX USERS: READ THIS FIRST!
Modern version of gd install by default to /usr/local/lib
and /usr/local/include. If you already have an older
version of gd in /usr/lib and /usr/include, you may wish to
use:
./configure --prefix=/usr
To ensure that your new installation overwrites the old.
GIF support has been restored in gd 2.0.28 and
above. The well-known patents on LZW compression
held by Unisys have expired in all countries. British
Telecom and IBM may hold related patents but have never
chosen to require royalties for GIF applications, to the
best of my knowledge. I am not a lawyer and cannot give
legal advice regarding this issue. PNG remains a superior
format especially if lossless truecolour images are
needed.
gd 2.0.33 requires that the following
libraries also be installed, in order to produce the
related image formats. The pre-compiled Win32 DLL already
contains the necessary libraries. You may skip libraries
associated with formats you do not use:
libpng (see the libpng home page), if
you want PNG
zlib (see the info-zip home
page), if you want PNG
jpeg-6b or later, if desired (see the Independent JPEG Group home
page), if you want JPEG
If you want to use the TrueType font support, you must
also install the FreeType 2.x library,
including the header files. See the Freetype Home Page, or
SourceForge.
No, I cannot explain why that site is down on a particular
day, and no, I can't send you a copy.
If you want to use the Xpm colour bitmap loading
support, you must also have the X Window System and the Xpm
library installed (Xpm is often included in modern X
distributions). Most of the time you won't need Xpm.
Please note that libpng 1.2.5, zlib 1.2.1, jpeg-6b and
FreeType 2.1.9 are pre-compiled into the Windows DLL. If
you wish to have a smaller DLL, or do not need some of
these components, please contact me. I will
compile a DLL to meet your requirements.
Table of Contents
Up to the
Boutell.Com, Inc. Home Page
In order to resolve any possible confusion regarding the
authorship of gd, the following copyright statement covers
all of the authors who have required such a statement.
If you are aware of any oversights in this copyright
notice, please contact Thomas Boutell who will
be pleased to correct them.
COPYRIGHT STATEMENT FOLLOWS THIS LINE
Portions copyright 1994, 1995, 1996, 1997, 1998, 1999,
2000, 2001, 2002, 2003, 2004 by Cold Spring Harbor
Laboratory. Funded under Grant P41-RR02188 by the National
Institutes of Health.
Portions copyright 1996, 1997, 1998, 1999, 2000, 2001,
2002, 2003, 2004 by Boutell.Com, Inc.
Portions relating to GD2 format copyright 1999, 2000,
2001, 2002, 2003, 2004 Philip Warner.
Portions relating to PNG copyright 1999, 2000, 2001,
2002, 2003, 2004 Greg Roelofs.
Portions relating to gdttf.c copyright 1999, 2000, 2001,
2002, 2003, 2004 John Ellson (ellson@graphviz.org).
Portions relating to gdft.c copyright 2001, 2002, 2003,
2004 John Ellson (ellson@graphviz.org).
Portions relating to JPEG and to colour quantization
copyright 2000, 2001, 2002, Doug Becker and copyright (C)
1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003,
2004, Thomas G. Lane. This software is based in part on the
work of the Independent JPEG Group. See the file
README-JPEG.TXT for more information.
Portions relating to GIF compression copyright 1989 by
Jef Poskanzer and David Rowley, with modifications for
thread safety by Thomas Boutell.
Portions relating to GIF decompression copyright 1990,
1991, 1993 by David Koblas, with modifications for thread
safety by Thomas Boutell.
Portions relating to WBMP copyright 2000, 2001, 2002,
2003, 2004 Maurice Szmurlo and Johan Van den Brande.
Portions relating to GIF animations copyright 2004
Jaakko Hyvätti (jaakko.hyvatti@iki.fi)
Permission has been granted to copy, distribute
and modify gd in any context without fee, including a
commercial application, provided that this notice is
present in user-accessible supporting
documentation.
This does not affect your ownership of the derived work
itself, and the intent is to assure proper credit for the
authors of gd, not to interfere with your productive use of
gd. If you have questions, ask. "Derived works" includes
all programs that utilize the library. Credit must be given
in user-accessible documentation.
This software is provided "AS IS." The
copyright holders disclaim all warranties, either express
or implied, including but not limited to implied warranties
of merchantability and fitness for a particular purpose,
with respect to this code and accompanying
documentation.
Although their code does not appear in gd 2.0.4, the
authors wish to thank David Koblas, David Rowley, and
Hutchison Avenue Software Corporation for their prior
contributions.
Although their code does not appear in the current
release, the authors also wish to thank Hutchison Avenue
Software Corporation for their prior contributions.
END OF COPYRIGHT STATEMENT
gd is a graphics library. It allows your code to quickly
draw images complete with lines, arcs, text, multiple
colours, cut and paste from other images, and flood fills,
and write out the result as a PNG or JPEG file. This is
particularly useful in World Wide Web applications, where PNG
and JPEG are two of the formats accepted for inline images by
most browsers.
gd is not a paint program. If you are looking for a paint
program, you are looking in the wrong place. If you are not a
programmer, you are looking in the wrong place, unless you
are installing a required library in order to run an
application.
gd does not provide for every possible desirable graphics
operation. It is not necessary or desirable for gd to become
a kitchen-sink graphics package, but version 2.0 does include
most frequently requested features, including both truecolour
and palette images, resampling (smooth resizing of truecolour
images) and so forth.
Not all of these tools
are necessarily up to date and fully compatible with 2.0.33.
PHPA variant of gd 2.x is included in PHP 4.3.0. It
is also possible to patch PHP 4.2.3 for use with gd 2.0.33;
see the gd home page
for a link to that information. It would be a Good Idea to
merge all of the things that are better in mainstream gd and
all of the things that are better in PHP gd at some point in
the near future.
Perlgd can also be used from Perl, courtesy of
Lincoln Stein's GD.pm library,
which uses gd as the basis for a set of Perl 5.x classes.
Highly recommended.
OCamlgd can be used from OCaml, thanks to Matt Gushee's GD4O
project.
Tclgd can be used from Tcl with John Ellson's
Gdtclft
dynamically loaded extension package.
PascalPascal enthusiasts should look into the
freepascal project,
a free Pascal compiler that includes gd support.
REXXA gd
interface for the REXX language is available.
Any LanguageThe "fly" interpreter performs gd
operations specified in a text file. You can output the
desired commands to a simple text file from whatever
scripting language you prefer to use, then invoke the
interpreter.
Version 2.0.33 restores compatibility with older releases
of Freetype 2.x in addition to the latest release. Thanks to
John Ellson and the graphviz project.
Version 2.0.32 restores correct detection of Unicode
character sets for freetype fonts, which repairs a bug that
prevented umlauts from displaying properly. Thanks to John
Ellson and the graphviz project. Also, version 2.0.32 builds
all test programs smoothly in the absence of libpng.
A minor type naming conflict prevented bgd.dll from
compiling, and it was left out of the distribution as a
result. This has been corrected.
2.0.29 did not compile correctly when freetype was not
available. This has been corrected. Thanks to Alessandro
Ranellucci.
- A 32-bit multiplication overflow vulnerability reported
on the Bugtraq mailing list has been corrected, along with
a number of similar issues. These bugs come into play only
when attempting to deal with images with extremely
large dimensions. The relevant functions now fail
gracefully when such extreme parameters are specified. The
code in question is also correct for systems with larger
bit depths. Thanks to Phil Knirsch, Alan Cox and
infamous41md. Since exploits are theoretically possible,
upgrading is recommended.
- Support for the fontconfig library, when available.
When fontconfig is available and gdFTUseFontConfig(1) has
been invoked or the gdFTEX_FONTCONFIG flag has been set for
a particular call, fontconfig patterns can be used to fetch
the best available font. For instance, "arial:bold:italic"
does the right thing (or as close as the available fonts
permit). Also, standard PostScript font names can be mapped
to an appropriate font by gdImageStringFTEx and relatives.
When fontconfig is available gdlib-config
--features will list the GD_FONTCONFIG feature. For
more information about fontconfig, see the fontconfig
pages.
The actual resolved font filename can be returned in
the gdFTStringExtra structure as the fontpath element if
the gdFTEX_RETURNFONTPATHNAME flag is set. Also, a vector
of character position advances can be retrieved if
gdFTEX_XSHOW is set in the flags element. .afm files
(font metrics) are now used to adjust size calculations
when available. When fontconfig is not available, gd
falls back to its usual behavior and requires a specific
font file name. One can still fetch fonts by filename
when gdFTUseFontConfig(1) is in effect, by setting the
gdFTEX_FONTPATHNAME flag in the flag element of the
gdFTStringExtra structure. Thanks to Dag Lem and John
Ellson.
- Additional freetype fixes: fixed width fonts are now
the right size, horizontal advance calculations now better
match the PostScript equivalent, and various compiler
warning fixes. Also, a fix to the encoding table selection
in the was made, addressing a problem with latin1 font
encodings. Thanks to Dag Lem and John Ellson.
- Improved tolerance when reading JPEG files containing
some garbage as well as valid image data.
- Easier compilation on Windows: no errno.h in
gd_gd2.c.
- Support for creating optimized GIF animations has been
added by Jaakko Hyvätti. See gdImageGifAnimAdd, gdImageGifAnimAddCtx, gdImageGifAnimAddPtr, gdImageGifAnimBegin, gdImageGifAnimBeginCtx,
gdImageGifAnimBeginPtr,
gdImageGifAnimEnd,
gdImageGifAnimEndCtx,
and gdImageGifAnimEndPtr.
- gdImageOpenPolygon
has been added to allow consecutive line segments to be
drawn without connecting the end points to form a closed
polygon. Thanks to Jaakko Hyvätti.
- Better alpha channel blending when the destination
color contains an alpha channel. Also, quicker handling of
the most common cases. Thanks to Frank Warmerdam.
- In gd 2.0.26, there was potential for out of bounds
fills, and therefore crashes, in the horizontalLine
function used by gdImageFilledPolygon. Fixed by John
Ellson.
- The order of the points returned in the bounding
rectangle by gdImageStringFT was incorrect in version
2.0.26. This has been corrected in version 2.0.27. Thanks
to Riccardo Cohen for pointing this out, and to John Ellson
for verifying and fixing it.
The following enhancements and fixes:
Drastically faster, less memory-intensive antialiased
drawing, thanks to Pierre-Alain Joye. This code was imported
from the PHP "fork" of gd. The API for antialiased drawing
has not changed, however the implementation has been
completely replaced. Antialiased line drawing does not
support widths other than 1, however this did not work
properly with the other implementation of antialiasing
either. Support has been included for the "non-blending
colour" option introduced by the previous implementation of
antialiased drawing.
gdlib-config, which has been installed by
make install for some time now, has gained a
--features option. This option produces a
space-separated list of optional features with which the gd
library was compiled. Typical usage looks like this:
% gdlib-config --features
GD_XPM GD_JPEG GD_FREETYPE GD_PNG GD_GIF
Other configure scripts can conveniently define preprocessor
symbols based on this list in order to conditionally compile code. For
instance, if GD_PNG is not reported by --features, then gdImagePng is not
included in the library.
Thanks to Lars Hecking and Lincoln Stein for their advice
on implementing this feature. Any blame for the actual
implementation is entirely due to me (TBB).
Fixes to the behavior of the bounding rectangle returned
by gdImageStringFT and relatives when the string is rotated.
See fontwheeltest.c. Thanks to John Ellson.
Previously, gdImageStringFT and friends accepted either a
full path to a font file, or the name of a font with no
extension, in which case the GDFONTPATH environment variable
and then the compiled-in DEFAULT_FONTPATH was searched. In
addition, a font filename with an extension but no full path
can now be automatically searched for in the same fashion.
Thanks to John Ellson.
Fixes to freetype antialiased text against a transparent
background. See testtr.c. Thanks to John Ellson.
Support for named entities like & and hex-coded
entities such as 水 in text strings passed to
gdImageStringFT and relatives, adding to the previous support
for decimal-coded entities like Å. These were
extracted from entities.html (from the W3C) via the script
entities.tcl, which is included for the curious and those
with other entities they need support for. Thanks to John
Ellson.
Optimization: gdImageSetPixel no longer calls
gdImageAlphaBlend when either the source or the destination
pixel is 100% transparent. Thanks to John Ellson.
Optimization: gdImageLine is potentially faster now in the
most common cases. Thanks to John Ellson.
Documentation of the entities feature of
gdImageStringFT.
autoconf/configure fixes. Thanks to many who pointed out
an oversight in handling libpng flags.
Owing to an oversight while making changes to better
accommodate the use of gd as a DLL, the extern
qualifier was dropped from the declarations of font pointers
in 2.0.24. This has been corrected. Thanks to Richard
("OpenMacNews").
Windows DLL now uses __stdcall calling convention.
Existing applications will require a recompile, using the new
version of gd.h, in order to use this version of the DLL.
However, Visual BASIC and other non-C programmers will now be
able to use the DLL, which is an enormous benefit and
justifies the one-time inconvenience to existing DLL
users.
The elaborate #ifdef test for older versions of Freetype
without FT_ENCODING_MS_SYMBOL was needed in a second place
also. Thanks to David R. Morrison.
An off-by-one error in gdImageToPalette caused
transparency to be applied to the wrong pixels. Thanks to
"Super Pikeman."
Output dpi specification option added to the
gdFTStringExtra structure, thanks to Mark
Shackelford. See gdImageStringFTEx.
- Win32 DLL users: working with pointers exported by DLLs
is difficult and causes unexpected results. gd 2.0.22
exports new functions for retrieving the basic gd fonts:
gdFontGetTiny(), gdFontGetSmall(), gdFontGetMediumBold(), gdFontGetLarge(), and gdFontGetGiant(). You may safely
assign the return values from these functions to a local
gdFontPtr. Direct use of
gdFontLarge, etc. is strongly deprecated for
users of bgd.dll; use these new functions
instead.
- Basic support for loading CMYK-colourspace JPEG images.
They are of course converted to RGB which is a lossy
process, however the results do look quite good and are
certainly fine for thumbnails and web previews of DTP
work.
- "make" no longer fails on
circletexttest
if PNG support is missing.
- Small performance improvements to gdImageCopyResampled;
larger improvements are forthcoming.
- You can now use standard I/O for input and output of
your images. This could be useful for CGI
programs.
- Version 2.0.21 adds a
gdImageCreateFrom*Ptr family of functions
which make it convenient to load an image in any
GD-supported format directly from memory.
- The new
gdNewDynamicCtxEx function was
added to support the easy implementation of the above
functions and to correct a design problem which made life
unpleasant for those passing in memory not originally
allocated by gd to the gdNewDynamicCtx
function by provoding a way to specify that gd should never
free or reallocate a particular block of memory. The
gdNewDynamicCtx function and its relatives,
although still exported for ABI compatibility, are now
deprecated except for internal use, in favor of
gdImageCreateFromPngPtr
and its relatives.
- Version 2.0.21 includes a new patch from Ethan A.
Merritt to correct a bug in the conditional compilation of
support for symbol fonts in gdft.c. Symbol fonts should now
work correctly. Thanks to Mr. Merritt.
- Version 2.0.20 restores the
gdFreeFontCache function, an undocumented
function added in an earlier release which now simply calls
gdFontCacheShutdown for backwards
compatibility. This repairs build problems when compiling
PHP against the latest gd.
- Documentation improvements.
- Version 2.0.20 restores the
gdFreeFontCache function, an undocumented
function added in an earlier release which now simply calls
gdFontCacheShutdown for backwards
compatibility. This repairs build problems when compiling
PHP against the latest gd.
- Version 2.0.19 restored
extern
declarations for the gd font pointers inadvertently removed
in 2.0.18.
- A Win32 binary distribution of "bgd.dll," built with
mingw32 and tested with win32 versions of the demo programs
as console applications, is now available.
- Semicolon rather than space used as the default
separator of alternative font file paths in gdImageStringFT, for better
compatibility with Windows and other environments where
spaces are common in paths.
- The circletexttest demo no longer fails to compile when
JPEG support happens to be absent.
- Minor compilation and packaging problems with 2.0.16
were corrected. If 2.0.16 compiled without errors for you,
then you don't need to upgrade to 2.0.17.
- Thread safety for freetype text output. Background: all
gd functions were already thread safe, as long as only one
thread manipulates each image -- except for gdImageStringFT
and gdImageStringFTEx. This is because of a shared freetype
font cache. Sharing the cache between images is worthwhile,
so "configure" now detects pthreads and uses it to wrap
freetype text output in a critical section if available.
There is also critical section support under WIN32. Those
who wish to be strictly thread-safe should call the new
function gdFontCacheSetup
before allowing any thread to use freetype text calls.
Otherwise this function is automatically invoked on the
first use of freetype, with a very small but real chance of
a race condition.
- gdImageSquareToCircle performs
a "polar coordinate transform," returning a new image in
which the X axis of the original has been remapped to theta
(angle) and the Y axis of the original has been remapped to
rho (distance from center).
- gdImageStringFTCircle wraps
text in a circle around a specified center point. This
function takes advantage of gdImageSquareToCircle. The
result is very smooth, although it takes some time to
compute. Thanks to Steve Bassi for sponsoring this
work.
- gdImageSharpen,
contributed by Paul Troughton. Thank you.
- Christophe Thomas corrected gdft.c to include freetype
header files in the way that is now mandatory in freetype
2.1.6 and above.
- Gustavo Scotti fixed a memory leak in gdft.c.
- Clipping rectangle respected in freetype text output.
Thanks to Matt McNabb.
- Paul den Dulk found a degenerate case that crashes
gdImageToPalette. Fixed.
- Optimization by Ilia Chipitsine to avoid wasting time
with offscreen scanlines during polygon rasterization.
- Optimized PNG saving by Phong Tran. Speeds up saves a
little bit.
- Bug in gdImageCopyResized fixed by Mao
Morimoto.
- gd.c in 2.0.14 contained an instance of declaring
variables after the first line of executable code appears.
This is of course not allowed by ANSI C, although many
compilers accept it. My apologies. Thanks to Jeff Vendetti
for reporting this quickly.
- 2.0.13 was available for mere minutes due to a typo in
the new bounds-checking code for antialiased line drawing.
Fixed.
- Not all platforms -- notably msys/mingw -- have an
ssize_t type. We now call an int an int in gd_jpeg.c, with
good results. (Note: ssize_t is signed, unlike size_t, and
it needs to be here.)
- The
main() function of one of the test
programs was accidentally included in the gd shared
library, causing problems on some platforms. This has been
corrected. Thanks to many people who pointed this out.
- The antialiased drawing functions now have proper
bounds checking. Thanks to Arne Jorgensen.
- A void function returned a value in gd_png.c, causing
warnings and, on some platforms, compilation errors but no
reported runtime problems. Thanks to Kevin Smith, among
others.
- Autohinting was being forced ON for freetype text
output. This is apparently meant only for testing freetype
and does not look as good as the default behavior
(FT_LOAD_DEFAULT). Thanks to Bob Ostermann.
- penf.x is properly reset when newlines are encountered
in freetype text output. Thanks to Christopher J.
Grayce.
- Small but numerous code cleanups by Dr. Martin
Zinser.gdImageSetClip and
gdImageGetClip have been
added. All drawing routines now stay within the specified
clipping rectangle. Note that the gdImageBoundsSafe function now
returns true only if the specified location is within the
clipping rectangle. Of course, the default clipping area is
the entire image. The behavior of existing gd applications
does not change.
- Support for fast drawing of antialiased lines and
polygons, by Bright Fulton and Frank Faubert. To learn more
about this feature, read about the gdImageSetAntiAliased
function, which is used to set the foreground colour for
antialiasing, as well as the gdAntiAliased constant, which is
passed to line- and polygon-drawing functions in place of a
colour. This code does not currently support an alpha
channel component in the specified foreground colour, or in
the existing background image, but does perform
alpha blending against an opaque background. Also see the
gdImageSetAntiAliasedDontBlend
function, which allows the specification of a special
background colour that should never be blended with the
foreground.
- Fixes to colour mapping in gdImageCopyMergeGray. Thanks to
Philip Warner.
- gdImageStringFTEx now
supports explicit specification of the desired character
mapping. This is useful when a font offers more than one of
Unicode, Shift_JIS, and Big5.
- The PNG compression level can now be specified when
writing PNG images. See the new gdImagePngEx, gdImagePngEx, gdImagePngCtxEx, and gdImagePngPtrEx functions.
- The annotate utility builds without error in the
absence of freetype, although of course it is not useful
without freetype.
- Thorben Kundinger fixed a bug relating to the use of
palette-based images as brushes when drawing on truecolour
images.
- Michael Schwartz corrected a problem with his code for
drawing thick lines.
- Prior to 2.0.12, any alpha channel component in the
destination image was ignored when drawing with
alpha blending in effect (see gdImageAlphaBlending). 2.0.12
correctly preserves an appropriate proportion of the alpha
component of the destination, just as it preserves an
appropriate proportion of the red, green and blue
components, depending on the opacity of the foreground.
Thanks to Frank Warmerdam for pointing out the issue.
- Memory leaks on failed attempts to load fonts in
gdImageStringFTEx were
corrected. Thanks to Frank Faubert.
- The impact of kerning is now correctly included in the
calculation of the bounding box returned by the freetype
text routines. This issue was pointed out by several
individuals.
- Colour problems with the
gd2 file format
routines were fixed by Steven Brown. These problems were
due to the incorrect use of a signed integer.
- Version 2.0.12 supports the
gd file format
correctly for truecolour images. Truecolour gd
files created with earlier releases in the 2.0 series must
be written again. The gd file format is used
to quickly load an entire uncompressed image, typically an
existing background to which additional material will be
added; it is not a general purpose file format. More
advanced capabilities are also available via the
gd2 format. Thanks to Andreas Pfaller for
reporting the problem.
- Signed vs. unsigned problem caused misbehavior when
attempting to load a bad JPEG image. Thanks to Geert
Jansen.
- Existing truecolour PNG images with simple
single-colour transparency are now loaded properly, thanks
to Slaven Rezic.
- The gdImageTrueColourToPalette
function no longer attempts to preserve an alpha channel in
the original. My attempt to do so resulted in significantly
inferior output even if no alpha channel was present in the
original. Thanks to Barend Gehrels for submitting a new
adaptation of Tom Lane's jquant2.c which does a very
high-quality job of palette conversion. Thanks also to
Steven Brown, who submitted patches allowing a single 100%
transparent colour in the original truecolour image to be
preserved. In practice, more complex alpha channels in
palettes are ill-supported and difficult to allocate
skillfully.
- Support for the "gd2" file format, which allows fast
loading of all or only part of an existing image, has been
properly debugged for use with truecolour images. (Palette
images already worked properly, except for a bug when
loading from a regular file with gdImageCreateFromGd2Part,
which has also been fixed.) .gd2 files can be either
compressed or uncompressed, and they allow useful tricks
such as fast loading of a 500x500 pixel region of a
6000x3000 pixel image, without uncompressing all
of the image. .gd2 is NOT a general purpose file format and
should only be used where quick loading of a background
image or subset of a larger image is required. For more
information, see gdImageGd2,
gdImageCreateFromGd2,
and gdImageCreateFromGd2Part.
- The gd2topng utility has been extended to support
extraction of only part of an image from a .gd2 file. This
is both a demonstration and a practical tool.
- Additional
configure improvements by Lars
Hecking.
- gdImageLine now clips to the edges of the image before
drawing lines, which greatly improves performance when many
lines extend outside or are entirely outside the actual
image. Thanks to Nick Atty for this code.
- gdImageBoundsSafe is replaced with a macro when called
internally; this improves the performance of
gdImageSetPixel and gdImageGetPixel a little bit, and
therefore everything else as well. Thanks to Nicky Atty for
the idea.
- Transparent indexes are handled properly with
non-truecolour source images in gdImageCopy. Thanks to
Frank Warmerdam.
- floor() replaced with a cast to long in
gdImageCopyResampled, for a roughly 35% performance boost.
Thanks to John Buckman.
- gdft.c builds correctly on WIN32 without patches.
- Much faster gdImageCreateFromJpeg routines, thanks to
Christian Aberger for more efficient pointer
arithmetic.
- gdtestft correctly builds without PNG tests if PNG
support is not present. Thanks to Gabriele Verzeletti.
- Version 2.0.9 contains a fix to gdImageCopyResized
which allows correct results when copying a palette-based
image with a single transparent index into a truecolour
image. Thanks to Thorben Kundinger.
- More
configure fixes from Lars Hecking.
Thanks, Lars.
- Version 2.0.8 contains additional fixes to the
'configure' script, allowing a clean out-of-the-box build
on more systems.
- Version 2.0.8 adds the new gdImageCopyRotated function,
which can rotate any rectangular image region by an
arbitrary number of degrees.
Version 2.0.7 corrects a problem which caused 'configure'
to complain that the directory NONE was not found, in various
places, causing the configuration process to stop. There are
no code changes.
- Fixed a compilation problem with gdft.c. A declaration
appeared after executable code, and gcc let it slide by, so
it made it out the door. My apologies!
- As penance, I have seen to it that the entire library
now compiles cleanly with the
-Wall,
-ansi and -pedantic options
enabled.
The following contributions from John
Ellson:
- Various test programs now compile in the absence of PNG
support
- gdIOCtx correctly calls gdFree rather than free
- Various cleanups to pass -Wall without warnings
- Support for Adobe-style Type 1 fonts (.pfa and .pfb
files) via freetype
- gdImageColourResolve and gdImageColourResolveAlpha will
not attempt to resolve a colour request to the transparent
colour index (for palette-based images)
- Improved font search path support
- Antialiased freetype text on palette images works
properly when more than one image is created in a single
program lifetime with different colour indexes
- Better threshold for two-colour "mono" images
- Memory leak fixes
- Text rotation fix
- More extensive default font path
- fontwheeltest and fontsizetest test programs for
freetype
And the following additional fixes:
configure now correctly detects and
provides support for the Xpm library and its dependencies
(Len Makin)
- The
configure script has been extensively
modified to work properly in tests with both Solaris and
Linux. Other platforms should also work based on feedback
received and integrated to date.
- The
--prefix option to
configure works properly.
- The
annotate utility has been added. This
is a very handy tool for adding freetype text to existing
JPEGs. After make install, type annotate
-h for more information. Thanks to Joel
Dubiner.
- A "configure" script has been added. After wrestling
with GNU autoconf for a while, I got tired of trying to
make it detect libraries but accept their absence
gracefully, and so on. Instead, I wrote a short Perl script
which does the job and builds a reasonable Makefile. Those
who find it doesn't detect their system's needs properly
are welcome to contribute patches or the necessary
commands.
- Antialiased freetype text output now works properly in
both truecolour and non-truecolour contexts! Hurrah! On a
truecolour image it is possible, for instance, to draw
antialiased text on an arbitrarily complex background with
50% alpha blending (transparency), and get the expected
pretty results. Thanks to Joel Dubiner for his support of
this work.
- By default, alpha blending is now done within
the library. Also, by default, alpha channel is
not saved with PNG images. This means that programmers who
try loading a JPEG, scribbling some pretty antialiased text
on it, and saving the JPEG again will now get the results
they expected. It also means that, by default, users will
not run afoul of the fact that many web browsers don't
properly support full PNG alpha channel.
- Various submitted bug fixes have been
incorporated.
- Various other submitted changes have not been
incorporated. Sorry. The interval between 2.0.1 and 2.0.2
was simply too long, and changes accumulated which were not
mutually compatible. I'll do better in the future,
especially with bug fixes.
- Workaround for a bug in gcc, apparently found in gcc
2.7.2 and up. I reproduced and fixed it while using gcc
2.9.5.2. The bug occurred only when the -g option was in
use. This problem caused gcc to spew internal error
messages unrelated to the correctness of the code in
gd_gd2.c. Howard Jones was first to report it.
- gdImageFilledEllipse documented
and altered; no longer requires a superfluous style
argument. Thanks to Francis James Franklin.
- The Makefile now offers the correct syntax for
optionally creating a static library. Thanks to Jean-Lous
Regez, among others.
- A nested comment, an attempt to return the value of a
void function, and a potentially significant error in
gdImageCopyResampled were fixed thanks to Joseph
Shirley.
- A bug preventing proper truecolour text rendering was
fixed, thanks to Jason Gallagher.
- gdImageStringFT
(FreeType) should now work better against a transparent or
semitransparent background, and should act in a manner
consistent with the most recent gdImageAlphaBlending setting.
Antialiasing is now done via the alpha channel mechanism if
the image is a truecolour image.
- Bugs in the output of gdImageArc and gdImageFilledArc
were reported by Bruce Verderaime. A simple and correct but
inefficient implementation has been substituted until fixes
are contributed for the faster code, which is in
gd_arc_f_buggy.c along with the test program that
reproduces the bug(s).
- gdImageFilledArc now
offers additional style options, which can be combined to
produce various effects.
- Masahito Yamaga (ma@yama-ga.com) sent a patch to
improve support for Japanese output via gdImageStringFT. He also added a new
readme.jpn file.
- Zillions of documentation fixes.
- Support for truecolour images! Version
2.0 can load truecolour PNGs with no loss of colour
information, and almost no loss of alpha channel
information. Version 2.0 can also load truecolour 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
truecolour image from scratch, call the new gdImageCreateTrueColour
function. The gdImageCreate
function is still available to create palette images, and
may also be referred to as gdImageCreatePalette.
- Support for alpha channels! In
addition to 24 bits of colour information for each pixel
(eight bits of red, green, and blue respectively), version
2.0 supports 7 bits of "alpha channel" information. This is
used to determine exactly how transparent the pixel should
be. There is also support for a full 7 bits of transparency
for each individual palette index in a palette-based image.
Please note that, as of this writing, only Macintosh
Internet Explorer 5.x and Mozilla/Netscape 6.x display
partial transparency properly.
- The new gdImageAlphaBlending function
allows for two different modes of drawing. In blending
mode, the alpha channel component of the colour supplied to
all drawing functions, such as gdImageSetPixel, determines how much
of the underlying colour should be allowed to shine
through. The resulting image is not transparent. In
non-blending mode, drawing colour is copied literally with
the alpha channel information, resulting in a transparent
image. Blending mode is not available when drawing on
palette images.
- The gdImageCopyResampled function
provides "smooth" copying from a large image to a smaller
one, using a weighted average of the pixels of the source
area rather than selecting one representative pixel. This
function is identical to gdImageCopyResized when the
destination image is a palette image.
- The gdImageTrueColourToPalette
function converts a truecolour 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 colours as well as possible. This
does not work as well as might be hoped. It is usually best
to simply produce a truecolour output image instead, which
guarantees the highest output quality.
- A very high degree of backwards compatibility with
existing gd 1.x code has been maintained, at both the
source code and binary level. Code which directly
accesses the
pixels array will fail only if it
encounters an existing truecolour image, which may
happen if the code attempts to open and modify an existing
JPEG or truecolour PNG. Such code should be modified to
check the trueColour flag of the
gdImage structure, and refer to the
tpixels array instead when it is set.
- gd is now compiled and installed as a shared library.
However, gd still does not use autoconf, because I (TBB)
have very limited patience with autoconf. These days, most
Unix systems provide a fairly POSIX-standard environment,
and the provided Makefile is likely to work well if users
read it and follow the instructions at the top.
- Support for line thickness was added by Michael
Schwartz. My apologies to him for sitting on his patches
for so long. See the new gdImageSetThickness function,
which affects all standard gd functions that draw lines and
curves. In addition, Michael added a convenient gdImageEllipse function.
- The new gdImageFilledArc function provides
a straightforward way to draw filled arcs. Also, gdImageFilledEllipse is a
convenient way to fill an ellipse without specifying
starting and ending angles. Thanks go out to F J
Franklin.
- To put an end to the confusion, TrueType 1.x support
has been removed in favor of TrueType 2.x support. The old
gdImageStringTTF function simply invokes
gdImageStringFT.
- The specialized .gd and .gd2 file formats have been
upgraded to support truecolour. 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.
You will also want a PNG viewer, if you do not already
have one for your system, since you will need a good way to
check the results of your work. Netscape 4.04 and higher, and
Microsoft Internet Explorer 4.0 or higher, both support PNG.
Not every PNG-compatible viewer supports alpha
channel transparency, which is why gd 2.0.2 and
above do alpha blending in the library by default; it is
possible to turn on the saving of alpha channel information
to the file instead.
In order to build gd, you must first unpack the archive
you have downloaded. If you are not familiar with
tar and gunzip (Unix) or
ZIP (Windows), please consult with an
experienced user of your system. Sorry, we cannot answer
questions about basic Internet skills.
Unpacking the archive will produce a directory called
"gd-2.0.33".
Run gddemo to see some of the capabilities of gd. Run
gdtestft to play with the freetype support, if you have built
gd with it and have access to truetype fonts.
gddemo should execute without incident, creating the file
demoout.png. (Note there is also a file named demoin.png,
which is provided in the package as part of the
demonstration.)
Display demoout.png in your PNG viewer. The image should
be 128x128 pixels and should contain an image of the space
shuttle with quite a lot of graphical elements drawn on top
of it.
(If you are missing the demoin.png file, the other items
should appear anyway.)
Look at demoin.png to see the original space shuttle image
which was scaled and copied into the output image.
gd lets you create PNG or JPEG images on the
fly. To use gd in your program, include the file gd.e
If you want to use the provided simple fonts, use
gdFontTiny, gdFontSmall, gdFontMediumBold, gdFontLarge and/or
gdFontGiant.h. For more impressive results, install FreeType
2.x and use the gdImageStringFT function.
Here is a short example program. (For a more
advanced example, see gddemo.c, included in the distribution.
gddemo.c is NOT the same program; it demonstrates additional
features!)
-- Bring in gd library functions
include gd.e
-- Declare the image
gdImagePtr im
-- Declare colour indexes
atom black, white
-- Allocate the image: 64 pixels across by 64 pixels tall
im = gdImageCreate(64, 64)
-- Allocate the colour black (red, green and blue all minimum).
-- Since this is the first colour in a new image, it will
-- be the background colour.
black = gdImageColourAllocate(im, 0, 0, 0)
-- Allocate the colour white (red, green and blue all maximum).
white = gdImageColourAllocate(im, 255, 255, 255)
-- Draw a line from the upper left to the lower right,
-- using white colour index.
gdImageLine(im, 0, 0, 63, 63, white)
-- Output the image to the disk file in PNG format.
gdImagePng(im, "test.png")
-- Output the same image in JPEG format, using the default
-- JPEG quality setting.
gdImageJpeg(im, "test.jpg", -1)
-- Destroy the image in memory.
gdImageDestroy(im)
When executed, this program creates an image, allocates two colours (the
first colour allocated becomes the background colour), draws a diagonal line
(note that 0, 0 is the upper left corner), writes the image to PNG and JPEG
files, and destroys the image.
The above example program should give you an idea of how
the package works. gd provides many additional functions,
which are listed in the following reference chapters,
complete with code snippets demonstrating each. There is also
an alphabetical index.
Webpng 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.
webpng.exw is provided in the distribution. Type "exwc
webpng" with no arguments to see the available options.
gdImage(TYPE)-
NOTE: You should not have to
worry about this structure. Define variables to the
gdImagePtr type below.
The data structure in which gd stores images. gdImageCreate, gdImageCreateTrueColour
and the various image file-loading functions return a
pointer to this type, and the other functions expect to
receive a pointer to this type as their first argument.
It is reasonably safe to examine any of the members of
this structure. It is also reasonably safe to modify
individual pixels within the pixels or
tpixels arrays. If the
trueColour flag is set, the
tpixels array is valid; otherwise the
pixels array is valid.
The coloursTotal, red,
green,blue,alpha
and open arrays manage the palette. They are
valid only when the trueColour flag is not
set. The transparent value contains the
palette index of the first transparent colour as
read-only information for backwards compatibility; gd 2.0
stores this information in the alpha array
so that variable transparency can be supported for each
palette entry. However, for truecolour images,
transparent represents a single RGB colour
which is always 100% transparent, and
this feature is generally supported by browsers which do
not support full alpha channels.
typedef struct {
/* Palette-based image pixels */
unsigned char ** pixels;
int sx;
int sy;
/* These are valid in palette images only. See also
'alpha', which appears later in the structure to
preserve binary backwards compatibility */
int coloursTotal;
int red[gdMaxColours];
int green[gdMaxColours];
int blue[gdMaxColours];
int open[gdMaxColours];
/* For backwards compatibility, this is set to the
first palette entry with 100% transparency,
and is also set and reset by the
gdImageColourTransparent 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 brushColourMap[gdMaxColours];
int tileColourMap[gdMaxColours];
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[gdMaxColours];
/* Truecolour flag and pixels. New 2.0 fields appear here at the
end to minimize breakage of existing object code. */
int trueColour;
int ** tpixels;
/* Should alpha channel be copied, or applied, each time a
pixel is drawn? This applies to truecolour 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 truecolour image,
then quantize down to 8 bits. */
int alphaBlendingFlag;
/* Should the alpha channel of the image be saved? This affects
PNG at the moment; other future formats may also
have that capability. JPEG doesn't. */
int saveAlphaFlag;
} gdImage
The order of the structure members may appear
confusing, but was chosen deliberately to increase
backwards compatibility with existing gd 1.x-based binary
code that references particular structure members.
- gdImagePtr
(TYPE)
- A pointer to an image structure. gdImageCreate returns this type, and
the other functions expect it as the first argument.
- gdIOCtx
(TYPE)
-
NOTE: All functions take only
gdIOCtxPtrs (see below) as parameters. Please read about
the gdIOCtx below.
Most of the gd functions that read and write files, such
as gdImagePng and gdImageCreateFromJpeg, also have
variants that accept a gdIOCtx structure; see gdImagePngCtxand gdImageCreateFromJpegCtx. Those who
wish to provide their own custom routines to read and
write images can populate a gdIOCtx structure with
functions of their own devising to to read and write
data. For image reading, the only mandatory functions are
getC and getBuf, which must return the number of
characters actually read, or a negative value on error or
EOF. These functions must read the number of characters
requested unless at the end of the file. For image
writing, the only mandatory functions are putC and
putBuf, which return the number of characters written;
these functions must write the number of characters
requested except in the event of an error. The seek and
tell functions are only required in conjunction with the
gd2 file format, which supports quick
loading of partial images. The gd_free function will not
be invoked when calling the standard Ctx functions; it is
an implementation convenience when adding new data types
to gd. For examples, see gd_png.c, gd_gd2.c, gd_jpeg.c,
etc., all of which rely on gdIOCtx to implement the
standard image read and write functions.
typedef struct gdIOCtx
{
int (*getC) (struct gdIOCtx *);
int (*getBuf) (struct gdIOCtx *, void *, int wanted);
void (*putC) (struct gdIOCtx *, int);
int (*putBuf) (struct gdIOCtx *, const void *, int wanted);
/* seek must return 1 on SUCCESS, 0 on FAILURE. Unlike fseek */
int (*seek) (struct gdIOCtx *, const int);
long (*tell) (struct gdIOCtx *);
void (*gd_free) (struct gdIOCtx *);
} gdIOCtx
- gdFont
(TYPE)
-
NOTE: Functions will take both
gdFont structures and pointers to them.
A font structure. Used to declare the characteristics of
a font. Please see the files gdfontl.e 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.
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
- gdFontPtr
(TYPE)
- A pointer to a font structure. Text-output functions
expect these as their second argument, following the
gdImagePtr argument. Two such
pointers are declared in the provided include files
gdfonts.e and gdfontl.e.
- gdPoint
(TYPE)
-
Represents a point in the coordinate space of the image;
used by gdImagePolygon,
gdImageOpenPolygon and
gdImageFilledPolygon.
typedef struct {
int x, y;
} gdPoint, *gdPointPtr;
- gdPointPtr
(TYPE)
- A pointer to a gdPoint
structure; passed as an argument to gdImagePolygon, gdImageOpenPolygon and gdImageFilledPolygon.
-
(TYPE)
- A structure used to pass additional parameters to the
gdImageStringFTEx
function. See gdImageStringFTEx for the
structure definition.
-
(TYPE)
- A pointer to a structure used to pass additional
parameters to the gdImageStringFTEx function. See
gdImageStringFTEx for the
structure definition.
- gdSource
(TYPE)
-
typedef struct {
int (*source) (void *context, char *buffer, int len);
void *context;
} gdSource, *gdSourcePtr
Represents a source from which a PNG can be read. Programmers who do not
wish to read PNGs from a file can provide their own alternate input mechanism,
using the gdImageCreateFromPngSource
function. See the documentation of that function for an example of the proper
use of this type.
- gdSink
(TYPE)
-
typedef struct {
int (*sink) (void *context, char *buffer, int len);
void *context;
} gdSink, *gdSinkPtr
Represents a "sink" (destination) to which a PNG can be written.
Programmers who do not wish to write PNGs to a file can provide their own
alternate output mechanism, using the
gdImagePngToSink function. See the documentation of
that function for an example of the proper use of this
type.
- gdImageCreate(integer sx, integer sy)
(FUNCTION)
-
gdImageCreate is called to create palette-based images,
with no more than 256 colours. Invoke gdImageCreate with
the x and y dimensions of the desired image.
gdImageCreate returns a gdImagePtr to the new image, or NULL if
unable to allocate the image. The image must eventually
be destroyed using gdImageDestroy().
-- ... inside a function ...
gdImagePtr im
im = gdImageCreate(64, 64)
-- ... Use the image ...
gdImageDestroy(im)
- gdImageCreateTrueColour(integer
sx, integer sy) (FUNCTION)
-
gdImageCreateTrueColour is called to create truecolour
images, with an essentially unlimited number of colours.
Invoke gdImageCreateTrueColour with the x and y
dimensions of the desired image. gdImageCreateTrueColour
returns a gdImagePtr to the new
image, or NULL if unable to allocate the image. The image
must eventually be destroyed using gdImageDestroy().
Truecolour images are always filled with black at
creation time. There is no concept of a "background"
colour index.
-- ... inside a function ...
gdImagePtr im
im = gdImageCreateTrueColour(64, 64)
-- ... Use the image ...
gdImageDestroy(im)
- gdImageCreateFromJpeg(sequence
in) (FUNCTION)
gdImageCreateFromJpegPtr(integer
size, object data) (FUNCTION)
gdImageCreateFromJpegCtx(gdIOCtxPtr
in) (FUNCTION)
-
gdImageCreateFromJpeg is called to load truecolour images
from JPEG format files. Invoke gdImageCreateFromJpeg with
the name of a file containing the desired image.
gdImageCreateFromJpeg returns a gdImagePtr to the new truecolour image,
or NULL if unable to load the image (most often because
the file is corrupt or does not contain a JPEG image).
You can inspect the sx and sy members of the image to
determine its size. The image must eventually be
destroyed using gdImageDestroy(). The
returned image is always a truecolour image.
If you already have the image file in memory, pass the
size of the file and a pointer to the file's data to
gdImageCreateFromJpegPtr, which is otherwise identical to
gdImageCreateFromJpeg.
gdImagePtr im
-- ... inside a function ...
sequence in
in = "myjpeg.jpg"
im = gdImageCreateFromJpeg(in)
-- ... Use the image ...
gdImageDestroy(im)
- gdImageCreateFromPng(sequence
in) (FUNCTION)
gdImageCreateFromPngPtr(integer
size, object data) (FUNCTION)
gdImageCreateFromPngCtx(
gdIOCtxPtr in)
(FUNCTION)
-
gdImageCreateFromPng is called to load images from PNG
format files. Invoke gdImageCreateFromPng with the name
of a file containing the desired image.
gdImageCreateFromPng returns a gdImagePtr to the new image, or NULL if
unable to load the image (most often because the file is
corrupt or does not contain a PNG image). You can inspect
the sx and sy members of the image to determine its size.
The image must eventually be destroyed using gdImageDestroy().
If the PNG image being loaded is a truecolour image,
the resulting gdImagePtr will refer to a truecolour
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
colour 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.
If you already have the image file in memory, pass the
size of the file and a pointer to the file's data to
gdImageCreateFromPngPtr, which is otherwise identical to
gdImageCreateFromPng.
gdImagePtr im
-- ... inside a function ...
sequence in
in = "mypng.png"
im = gdImageCreateFromPng(in)
-- ... Use the image ...
gdImageDestroy(im)
- gdImageCreateFromPngSource(gdSourcePtr
in) (FUNCTION)
-
b>Deprecated in favour of gdImageCreateFromPngCtx.
Should not be used in new applications.
gdImageCreateFromPngSource is called to load a PNG
from a data source other than a file. Usage is very
similar to the gdImageCreateFromPng
function, except that the programmer provides a custom
data source.
The programmer must write an input function which
accepts a context pointer, a buffer, and a number of
bytes to be read as arguments. This function must read
the number of bytes requested, unless the end of the file
has been reached, in which case the function should
return zero, or an error has occurred, in which case the
function should return -1. The programmer
then creates a gdSource structure
and sets the source pointer to the input
function and the context pointer to any value which is
useful to the programmer.
The example below implements gdImageCreateFromPng by
creating a custom data source and invoking
gdImageCreateFromPngSource.
function readWrapper(atom context, atom buffer, integer len)
poke(buffer, get_bytes(context, len)
--Hope it went well....
return len
end function
function gdImageCreateFromPng(integer fn)
gdSource s
s = {call_back(routine_id("freadWrapper")), fn}
return gdImageCreateFromPngSource(s)
end function
- gdImageCreateFromGif(sequence
in) (FUNCTION)
gdImageCreateFromGifPtr(integer
size, object data) (FUNCTION)
gdImageCreateFromGifCtx(
gdIOCtx *in)
(FUNCTION)
-
gdImageCreateFromGif is called to load images from GIF
format files. Invoke gdImageCreateFromGif with the name
of a file containing the desired image.
gdImageCreateFromGif returns a gdImagePtr to the new image, or NULL if
unable to load the image (most often because the file is
corrupt or does not contain a GIF image). You can inspect
the sx and sy members of the image to determine its size.
The image must eventually be destroyed using gdImageDestroy().
If you already have the image file in memory, pass the
size of the file and a pointer to the file's data to
gdImageCreateFromGifPtr, which is otherwise identical to
gdImageCreateFromGif.
gdImagePtr im
--... inside a function ...
sequence in
in = "mygif.gif"
im = gdImageCreateFromGif(in)
-- ... Use the image ...
gdImageDestroy(im)
- gdImageCreateFromGd(sequence in)
(FUNCTION)
gdImageCreateFromGdPtr(integer
size, object data) (FUNCTION)
gdImageCreateFromGdCtx(
gdIOCtxPtr in)
(FUNCTION)
-
gdImageCreateFromGd is called to load images from gd
format files. Invoke gdImageCreateFromGd with the name of
a file containing the desired image in the gd file format, which is specific to gd
and intended for very fast loading. (It is not
intended for compression; for compression, use PNG or
JPEG.)
If you already have the image file in memory, pass the
size of the file and a pointer to the file's data to
gdImageCreateFromGdPtr, which is otherwise identical to
gdImageCreateFromGd.
gdImageCreateFromGd returns a gdImagePtr to the new image, or NULL if
unable to load the image (most often because the file is
corrupt or does not contain a gd format image). You can
inspect the sx and sy members of the image to determine
its size. The image must eventually be destroyed using
gdImageDestroy().
-- ... inside a function ...
gdImagePtr im
sequence in
in = "mygd.gd"
im = gdImageCreateFromGd(in)
-- ... Use the image ...
gdImageDestroy(im)
- gdImageCreateFromGd2(sequence
in) (FUNCTION)
gdImageCreateFromGd2Ptr(integer
size, object data) gdImageCreateFromGd2Ctx(
gdIOCtxPtr in)
(FUNCTION)
-
gdImageCreateFromGd2 is called to load images from gd2
format files. Invoke gdImageCreateFromGd2 with the name
of a file containing the desired image in the gd2 file format, 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.)
If you already have the image file in memory, pass the
size of the file and a pointer to the file's data to
gdImageCreateFromGd2Ptr, which is otherwise identical to
gdImageCreateFromGd2.
gdImageCreateFromGd returns a gdImagePtr to the new image, or NULL if
unable to load the image (most often because the file is
corrupt or does not contain a gd format image).You can
inspect the sx and sy members of the image to determine
its size. The image must eventually be destroyed using
gdImageDestroy().
-- ... inside a function ...
gdImagePtr im
sequence in
in = "mygd.gd2"
im = gdImageCreateFromGd2(in)
-- ... Use the image ...
gdImageDestroy(im)
- gdImageCreateFromGd2Part(sequence
in, integer srcX, integer srcY, integer w, integer h)
(FUNCTION)
gdImageCreateFromGd2PartPtr(integer
size, atom data, integer srcX, integer srcY, integer w,
integer h) (FUNCTION)
gdImageCreateFromGd2PartCtx(
gdIOCtxPtr in, integer srcX, integer
srcY, integer w, integer h) (FUNCTION)
-
gdImageCreateFromGd2Part is called to load parts of
images from gd2 format files.
Invoked in the same way as gdImageCreateFromGd2, but
with extra parameters indicating the source (x, y) and
width/height of the desired image.
gdImageCreateFromGd2Part returns a gdImagePtr to the new image, or NULL if
unable to load the image. The image must eventually be
destroyed using gdImageDestroy().
If you already have the image file in memory, you may
use gdImageCreateFromGd2PartPtr. Pass the size of the
image file, in bytes, as the first argument and the
pointer to the image file data as the second
argument.
- gdImageCreateFromWBMP(sequence
in) (FUNCTION)
gdImageCreateFromWBMPPtr(integer
size, atom data) (FUNCTION)
gdImageCreateFromWBMPCtx(
gdIOCtxPtr in)
(FUNCTION)
-
gdImageCreateFromWBMP is called to load images from WBMP
format files. Invoke gdImageCreateFromWBMP with the name
of a file containing the desired image.
gdImageCreateFromWBMP returns a gdImagePtr to the new image, or NULL if
unable to load the image (most often because the file is
corrupt or does not contain a WBMP image). You can
inspect the sx and sy members of the image to determine
its size. The image must eventually be destroyed using
gdImageDestroy().
If you already have the image file in memory, pass the
size of the file and a pointer to the file's data to
gdImageCreateFromWBMPPtr, which is otherwise identical to
gdImageCreateFromWBMP.
gdImagePtr im
-- ... inside a function ...
im = gdImageCreateFromWBMP("mywbmp.wbmp")
-- ... Use the image ...
gdImageDestroy(im)
- gdImageCreateFromXbm(sequence
in) (FUNCTION)
-
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 gdImagePtr 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).
You can inspect the sx and sy members of the image to
determine its size. The image must eventually be
destroyed using gdImageDestroy().
-- ... inside a function ...
gdImagePtr im
sequence in
in = "myxbm.xbm"
im = gdImageCreateFromXbm(in)
-- ... Use the image ...
gdImageDestroy(im)
- gdImageCreateFromXpm(sequence
filename) (FUNCTION)
-
gdImageCreateFromXbm is called to load images from XPM X
Window System colour 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.
gdImageCreateFromXpm returns a gdImagePtr to the new image, or NULL if
unable to load the image (most often because the file is
corrupt or does not contain 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 gdImageDestroy().
-- ... inside a function ...
gdImagePtr im
sequence in
in = "myxpm.xpm"
im = gdImageCreateFromXpm(in)
-- ... Use the image ...
gdImageDestroy(im)
- gdImageDestroy(gdImagePtr im)
(FUNCTION)
-
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
gdImagePtr variable.
-- ... inside a function ...
gdImagePtr im
im = gdImageCreate(10, 10)
-- ... Use the image ...
-- Now destroy it
gdImageDestroy(im)
- gdImageJpeg(gdImagePtr im, sequence out,
integer quality) (FUNCTION)
gdImageJpegCtx(gdImagePtr im, gdIOCtxPtr
out, integer quality)
(FUNCTION)
-
gdImageJpeg outputs the specified image to the specified
file in JPEG format.
If quality is negative, the default IJG JPEG quality
value (which should yield a good general quality / size
tradeoff for most situations) is used. Otherwise, for
practical purposes, quality should be a value in the
range 0-95, higher quality values usually implying both
higher quality and larger image sizes.
If you have set image interlacing using gdImageInterlace, this function
will interpret that to mean you wish to output a
progressive JPEG. Some programs (e.g., Web browsers) can
display progressive JPEGs incrementally; this can be
useful when browsing over a relatively slow
communications link, for example. Progressive JPEGs can
also be slightly smaller than sequential
(non-progressive) JPEGs.
-- ... inside a function ...
gdImagePtr im
atom black, white
sequence out
-- Create the image
im = gdImageCreate(100, 100)
-- Allocate background
white = gdImageColourAllocate(im, 255, 255, 255)
-- Allocate drawing colour
black = gdImageColourAllocate(im, 0, 0, 0)
-- Draw rectangle
gdImageRectangle(im, 0, 0, 99, 99, black)
-- Write JPEG using default quality
gdImageJpeg(im, out, -1)
-- Destroy image
gdImageDestroy(im)
- sequence
gdImageJpegPtr(gdImagePtr im, integer quality)
(FUNCTION)
- Identical to gdImageJpeg except that it returns the
JPEG data.
- gdImageGif(gdImagePtr im, sequence out)
(FUNCTION)
gdImageGifCtx(gdImagePtr im, gdIOCtxPtr
out) (FUNCTION)
-
gdImageGif outputs the specified image to the specified
file in GIF format.
GIF does not support true colour; GIF images can
contain a maximum of 256 colours. If the image to be
written is a truecolour image, such as those created with
gdImageCreateTrueColor or
loaded from a JPEG or a truecolour PNG image file, a
palette-based temporary image will automatically be
created internally using the gdImageCreatePaletteFromTrueColor
function. The original image pixels are not modified.
This conversion produces high quality palettes but does
require some CPU time. If you are regularly converting
truecolour to palette in this way, you should consider
creating your image as a palette-based image in the first
place.
-- ... inside a function ...
gdImagePtr im
integer black, white
sequence out
-- Create the image
im = gdImageCreate(100, 100)
-- Allocate background
white = gdImageColorAllocate(im, 255, 255, 255)
-- Allocate drawing colour
black = gdImageColorAllocate(im, 0, 0, 0)
-- Draw rectangle
gdImageRectangle(im, 0, 0, 99, 99, black)
out = "rect.gif"
-- Write GIF
gdImageGif(im, out)
-- Destroy image
gdImageDestroy(im)
- sequence
gdImageGifPtr(gdImagePtr
im)(FUNCTION)
- Identical to gdImageGif except that it returns a
sequence with the GIF data.
- gdImageGifAnimBegin(gdImagePtr im,
sequence out, integer globalCM, integer loops)
gdImageGifAnimBeginCtx(gdImagePtr
im, gdIOCtxPtr out, integer globalCM, integer loops)
(FUNCTION)
-
This function must be called as the first function when
creating a GIF animation. It writes the correct GIF file
headers to selected file output, and prepares for frames
to be added for the animation. The image argument is not
used to produce an image frame to the file, it is only
used to establish the GIF animation frame size,
interlacing options and the color palette.
gdImageGifAnimAdd is used to add the first and subsequent
frames to the animation, and the animation must be
terminated by writing a semicolon character (;) to it or
by using gdImageGifAnimEnd to do that.
The globalCM flag indicates if a global color map (or
palette) is used in the GIF89A header. A nonzero value
specifies that a global color map should be used to
reduce the size of the animation. Of course, if the color
maps of individual frames differ greatly, a global color
map may not be a good idea. globalCM=1 means write global
color map, globalCM=0 means do not, and globalCM=-1 means
to do the default, which currently is to use a global
color map.
If loops is 0 or greater, the Netscape 2.0 extension
for animation loop count is written. 0 means infinite
loop count. -1 means that the extension is not added
which results in no looping. -1 is the default.
- sequence
gdImageGifAnimBeginPtr(gdImagePtr im, integer globalCM,
integer loops) (FUNCTION)
- Identical to gdImageGifAnimBegin except that it returns
a sequence with the GIF data.
- gdImageGifAnimAdd(gdImagePtr im,
sequence out, integer localCM, integer leftOfs, integer
topOfs, integer delay, integer disposal, gdImagePtr
previm)
gdImageGifAnimAddCtx(gdImagePtr im,
gdIOCtxPtr out, integer localCM, integer leftOfs, integer
topOfs, integer delay, integer disposal, gdImagePtr
previm) (FUNCTION)
-
This function writes GIF animation frames to GIF
animation, which was initialized with gdImageGifAnimBegin. With
leftOfs and topOfs you can place this frame in different
offset than (0,0) inside the image screen as defined in
gdImageGifAnimBegin. Delay between the previous frame and
this frame is in 1/100s units. disposal is usually
gdDisposalNone, meaning that the pixels
changed by this frame should remain on the display when
the next frame begins to render, but can also be
gdDisposalUnknown (not recommended),
gdDisposalRestoreBackground (restores the
first allocated color of the global palette), or
gdDisposalRestorePrevious (restores the
appearance of the affected area before the frame was
rendered). Only gdDisposalNone is a sensible
choice for the first frame. If previm is
passed, the built-in GIF optimizer will always use
gdDisposalNone regardless of the Disposal
parameter.
Setting the localCM flag to 1 adds a local palette for
this image to the animation. Otherwise the global palette
is assumed and the user must make sure the palettes
match. Use gdImagePaletteCopy to do
that.
Automatic optimization is activated by giving the
|
