GD.pm -- A perl5 interface to Thomas Boutell's gd library. ABSTRACT: This is a autoloadable interface module for libgd, a popular library for creating and manipulating PNG files. With this library you can create PNG images on the fly or modify existing files. Features include: a. lines, polygons, rectangles and arcs, both filled and unfilled b. flood fills c. the use of arbitrary images as brushes and as tiled fill patterns d. line styling (dashed lines and the like) e. horizontal and vertical text rendering f. support for transparency and interlacing For full information on usage, see the accompanying man and html documentation. COPYRIGHT INFO The GD.pm interface is copyright 1995-1999, Lincoln D. Stein. It is covered by the Perl "Artistic License", which allows for free usage and redistribution. See the Artistic License in the Perl source package for details. Code from the gd graphics library is covered separately, under a 1994 copyright by Quest Protein Database Center, Cold Spring Harbor Labs, and by Thomas Boutell. THE LATEST VERSION IS 1.22 WHAT's NEW IN 1.22 - added support for statically linked libgd.a, which is now default for libgd 1.7.3 (grrrr) - added newFromGd2Part() and newFromXPM() methods WHAT'S NEW IN 1.21 - fix to regression test so that all tests pass when truetype support not enabled - removed GD.html from distribution WHAT'S NEW IN 1.20 - uses libgd 1.6.3, allowing it to 1. create png images 2. render TrueType Fonts - SUPPORT FOR GIF OUTPUT HAS BEEN REMOVED DUE TO UNISYS PATENT RESTRICTIONS - Fixes to compile correctly on VMS systems - Patches from ActiveState for Windows/DOS systems. - bdftogd fix from Honza Pazdziora to handle non-fixed width fonts better WHAT'S NEW IN 1.19 - Fixes to compile correctly on Win32 systems WHAT'S NEW IN 1.18 - New "Giant" font. WHAT'S NEW IN 1.17 - Patches from Gurusamy Sarathy <gsar@engin.umich.edu> that allow GD to compile correctly on Win32 systems. - Patches from Jan Pazdziora <adelton@fi.muni.cz> to handle the full ISO-Latin-2 alphabet, along with some bug fixes. WHAT'S NEW IN 1.16 - Patches from Andreas Koenig <koenig@kulturbox.de> to use FileHandle correctly (also fixes problems with mod_perl). WHAT'S NEW IN 1.15 - Patches from Ulrich Pfeifer to allow to compile correctly with FastCGI - Patches from Douglas Wegscheid to avoid multiple defined symbol problems under NetBSD - Patches from Weinfriend Koenig to fix problems in filled polygons, plus new routines for scaling, translating and rotating polygons. WHAT'S NEW IN 1.14 - Modified gd library now included in the package. - Performance improvements. - Extensive code cleanup. - Runs correctly with FastCGI. INSTALLATION: 1. Make sure you have downloaded and installed the following packages: a. Perl 5.004 or higher: http://www.perl.com/ b. The gd graphics library, version 1.6.3 or higher: http://www.boutell.com/gd/ c. The PNG graphics library: http://www.cdrom.com/pub/png/ d. The zlib compression library: http://www.cdrom.com/pub/infozip/zlib/ e. The FreeType font rendering library for TrueType fonts (optional): http://www.freetype.org/ 2. Unpack the tar file: zcat GD-1.XX.tar.gz | tar xvf - (Where "XX" is the most recent revision number.) This will create the directory GD-1.XX. 3. To compile GD.pm on a system that supports dynamic linking: a. cd GD-1.XX b. perl Makefile.PL c. make d. make test (optional) e. make html (optional) f. make install This will create GD.pm, its HTML manual page, and install GD into the system-wide Perl library directory. You'll need root privileges to do the install step. If you don't have them, see below. If during step (b) you see either of these messages: Note (probably harmless): No library found for -lttf Note (probably harmless): No library found for -lXpm this means that FreeType and/or Xpm support will not be compiled in. You may still be able to use the library, but the functions that call these routines will fail (check the $@ variable for the exact error message). If you get a link error while loading the module, then you be able to recover the situation by changing the library search path specified by the @extrasearch variable in Makefile.PL If you see notes about any other missing libraries (-lz, -lgd, -lpng) then this module will not compile and install correctly. 4. To compile GD.pm statically on systems that do not support dynamic linking: a. cd GD-1.XX b. perl Makefile.PL LINKTYPE=static c. make perl d. make -f Makefile.aperl inst_perl MAP_TARGET=gdperl This will create a new version of Perl and install it in your system binaries directory, under the name "gdperl". 5. Before you install GD, you may want to run the regression tests. You can do this after the "make" step by typing: make test If any tests fail, you might want to run them verbosely with: make test TEST_VERBOSE=1 6. There are some demos you can run in ext/GD/demos. They print PNG files to standard output. To view the files, pipe their output to "display" or "xv" in this way: a. cd GD-1.XX/demos b perl shapes.pl | display - You will need a graphics program that can read and display PNG format. I recommend Image::Magick's display program, available from ftp://ftp.wizards.dupont.com/pub/ImageMagick/ If you don't have any display programs handy, you can save to a temporary file and display with recent versions of Netscape or Internet Explorer. 7. A program named fonttest is included in this package under demos. This generates an image showing all the built-in fonts available. If you have built libgd with TrueType support, and you have a directory containing some TrueType fonts, you can create a simple font listing by running the program truetype_test, also located in demos. 8. See demos/gd_example.cgi for an example of how to use GD to create a picture dynamically with a CGI script. It's intended to be run under a Web server. To see it work, install it in your server's cgi-bin/ directory and invoke it from a browser by fetching a URL like: http://your.site/cgi-bin/gd_example.cgi INSTALLING GD IN YOUR HOME DIRECTORY IF YOU DON'T HAVE PRIVILEGES TO INSTALL GD.pm in your system's main Perl library directory, don't despair. You can install it into your home directory using the following feature of Makefile.PL: a. cd GD-1.XX b. perl Makefile.PL LIB=/home/fred/lib c. make d. make install (change /home/fred/lib as appropriate for your home directory). This will install GD.pm in /home/fred/lib. You may get some errors about not being able to install the manual pages. Either don't worry about it, or run the "perl Makefile.PL" step with the INST_MAN3DIR variable set to some directory you have write permission for. You'll now need to modify your GD-using scripts to tell Perl where to find GD. This example assumes that your home directory is at path "/home/fred"; change it as appropriate. #!/usr/local/bin/perl use lib '/home/fred/lib'; use GD; ... etc ... USING GD WITH FAST CGI FastCGI is a protocol from OpenMarket Corporation that markedly speeds up the execution of CGI scripts. To use FastCGI with Perl scripts, you need a specially-modified version of the Perl interpreter which you can obtain in binary and/or source form from: http://www.fastcgi.com/ To use GD with a FastCGI version of Perl you'll need to recompile it using the modified Perl. In this example, I assume that this version of Perl is found at '/usr/local/fcgi/bin/perl': modify as appropriate for your system. a. cd GD-1.XX b. edit Makefile.PL and uncomment the line 'DEFINE' => '-DFCGI' c. /usr/local/fcgi/bin/perl Makefile.PL d. make e. make install Note that these instructions have not been verified for a long time, and may no longer work. If you successfully use this module with FastCGI and find that the instructions are no longer valid, please send me the updated information. IF YOU RUN INTO PROBLEMS Some versions of Unix and Unix-like systems such as Linux ship with an incomplete version of the Perl distribution. If you get warnings such as "Module ExtUtils::MakeMaker not found", you may have such a system. Your only option is to obtain the full Perl distribution and reinstall it. If the make and install all seem to go well but you get errors like "Fatal error: can't load module GD.so", or "Fatal error: unknown symbol gdFontSmall" when you try to run a script that uses GD, you may have problems with dynamic linking. Check whether other dynamically-linked Perl modules such as POSIX and DB_File run correctly. If not, then you'll have to link Perl statically, as described above. If you are trying to compile and link GD on a Windows or Macintosh machine and fail, please verify that you are able to build the Perl distribution from source code. If you can't do that, then you don't have the compiler/linker/make tools required for building Perl modules. You may not even need to do this, as ActiveState and MacPerl both include precompiled versions of GD. If you have problems and can't solve it on your own, post a message to the newsgroup "comp.lang.perl.modules". There are some systems that require obscure compiler and linker options in order to compile correctly, and unfortunately I have a limited number of systems at my disposal. You're much more likely to get correct answers from the gurus on the newsgroup than from myself. THE QUICKDRAW LIBRARY Also included in this package is qd.pl, a package of Quickdraw routines. If you are familiar with the Quickdraw Macintosh library, you can create Macintosh pictures (complete with scaleable fonts, draggable objects, etc. etc.) directly in Perl. See README.QUICKDRAW and qd.pl for more information. FREQUENTLY ASKED QUESTIONS 1. What happened to GIF support? Unisys owns the patent on the LZW compression scheme, which is the basis for GIF. Recently (Summer 1999) Unisys's lawyers have begun threatening providers of GIF software, as well as Web site operators who display GIF images. To avoid legal issues, Tom Boutell and myself are forced to remove GIF support from GD. PNG is technically better than GIF, and is supported by newer Web browsers, including Netscape Navigator 4.04 and higher, and Microsoft Internet Explorer 4.0 and higher. 2. Is there a utility to convert X Windows BDF fonts into GD fonts. Yes. See the directory bdf_scripts/. However these scripts were written for earlier versions of GD which included its own mini-gd library. These scripts will have to be adapted for use with libgd, and the libgd library itself will have to be recompiled and linked! 3. Does GD run with MacPerl/Win32 Perl? Yes. The latest MacPerl and ActiveState binaries come with GD already compiled in and ready to go. 4. GD won't compile on system XX. The most frequent problem is missing or redundant symbols during the link. If you get an error about missing math symbols (usually "floor"), then uncomment the line in Makefile.PL that starts with 'LIBS'. If you get an error about multiple redundant symbols, then comment out the line. 5. When I try to load an XPM file, all I get is blackness! I can't get the libgd createFromXpm() function to work, either. There may be a bug in the library. BUG REPORTS Feel free to contact me via e-mail. Provide the version numbers of GD, Perl, make and model of your operating system, and make and model of your Web server, if appropriate. Provide a small script that demonstrates the bug. Do NOT contact me for issues involving compilation failures on Windows, VMS, or Macintosh systems. I do not have any such systems on hand, and cannot help you out. ACKNOWLEDGEMENTS: I'd like to thank Jan Pazdziora, Geoff Baysinger, and David Kilzer for their contributions to the library, as well as Thomas Boutell who wrote libgd. UPDATES: The current version of GD can be found at: http://stein.cshl.org/WWW/software/GD AUTHOR: Lincoln Stein lstein@cshl.org http://stein.cshl.org/~lstein