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 GIF files.  With this library you can
create GIF 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-1998, Lincoln D. Stein.  You are
free to use it for any purpose, commercial or noncommercial, provided
that if you redistribute the source code this statement of copyright
remains attached.  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.18

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.  You'll need perl 5.003, patchlevel 23 or higher 
    (5.004 is recommended).   Perl is available from:
     
	a. Larry Wall's FTP site:
           ftp://ftp.netlabs.com/pub/outgoing/perl5.0

	b. the CPAN archives:
	   http://www.perl.com/CPAN/

    Unlike previous versions of this package, you no longer need
    the C-language version of libgd.  This package comes with a
    version of libgd that has been slightly modified to work well
    with Perl.

    (Please do not complain to me if your build fails with an
    error about not finding perlio.h.  This file is part of more
    recent versions of Perl.  You will need a recent version of
    Perl to compile and install this package).

2.  Unpack the tar file:

	zcat GD-1.18.tar.gz | tar xvf -

    This will create the directory GD-1.18. Do NOT install this directory
    into the Perl source tree.

3.  To compile GD.pm on a system that supports dynamic linking:

	a.  cd GD-1.18
	b.  perl Makefile.PL
	c.  make
	d.  make install

    This will create GD.pm and copy it and its dynamically loadable module 
    GD.so into the Perl library tree.  You'll need root privileges to do
    the install step.  If you don't have them, see below.

4.  To compile GD.pm statically on systems that do not support dynamic
    linking (I think this includes Windows NT):

	a.  cd GD-1.18
        b.  perl Makefile.PL
        c.  make perl
        d.  make inst_perl

     This will create a new version of Perl and install it in your system
     binaries directory, OVERWRITING THE PREVIOUS VERSION OF PERL.  If you'd
     like to install Perl under a different name, such as "gdperl",
     follow this recipe:

	a.  cd GD-1.18
        b.  perl Makefile.PL MAP_TARGET=gdperl
        c.  make gdperl
        d.  make inst_perl

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

6.  There are some demos you can run in ext/GD/demos.  They print GIF
    files to standard output.  To view the files, pipe their
    output to "display" or "xv" in this way:

	a.  cd GD-1.18/demos
	b   perl shapes.pl | xv -

7.  A program named fonttest is included in this package.  This generates
    an image showing all the fonts available.

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.18
	b.  perl Makefile.PL INSTALLDIRS=site \
                             INSTALLSITELIB=/home/fred/lib \
                             INSTALLSITEARCH=/home/fred/lib/arch
	c.  make
	d.  make install
p
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/perl/lib',
	        '/home/fred/lib/perl/arch';
        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.openmarket.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.18
	b. edit Makefile.PL and uncomment the line 
               'DEFINE'	=> '-DFCGI'
        c. /usr/local/fcgi/bin/perl Makefile.PL
        d. make
        e. make install

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 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. Are there plans to include additional fonts in GD?

   Maybe some day.  Not soon.  This is Thomas Boutell's provenance.

2. Is there a utility to convert {True Type, X Windows, Postscript}
fonts into GD fonts.

   No.

3. Does GD run with MacPerl?

   Yes.  The latest MacPerl binaries come with GD already compiled in and
   ready to go.

4. Are there any Windows 95/NT binaries of GD?

   Thanks to Gurusamy Sarathy, GD-1.17 and above now compiles
   correctly on Win32 systems.  If you have a C compiler, you can compile and
   install it as a .DLL library.  (If you don't have a C compiler,
   you can get a free version of gcc at Cygnus, ftp://ftp.cygnus.com/)

   David Roth has done a port to Windows NT/95.  You can find it at:

	http://roth.net/users/rothd/HOME.HTM

   Be sure to download the .DLL library version that is correct for your
   Perl interpreter.  If there is a mismatch, you may encounter a
   "parse error" message.

   As of January 16, David Roth's site has been inaccessible for some 
   time (first it was not recognized by the DNS; now it asks for a
   user name and password).  An OLD GD binary is available on CPAN, in
   
       modules/by-module/GD/DAVEROTH/Win32_gd_v961016.zip

   I don't know if it will work.  Let me know if you have success.

   Alternately, download the "standard" port of perl 5.004 from a CPAN
   site near you.  It contains a prebuilt version of GD, statically linked
   to the binary.

5. 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.

6. How come the fonts are so limited?

   The font support comes from libgd, where the fonts are compiled into the
   binary.  In order to keep the binary size down, only a few fonts are 
   compiled in.  Some day, perhaps, a future version will come with support
   for true type fonts, postscript fonts, but don't hold your breath.

   If you want to add fonts, and have access to X11-style BDF fonts, you can
   use Jan Pazdiora's <adelton@fi.muni.cz> utility, bdftogd.  It will produce
   a font in a form that can be linked into libgd.  You will also need to hack
   the files GD.xs and GD.pm to add the appropriate name for the new font.
   If you are savvy enough to figure bdftogd out, you'll be able to figure out
   what to do.

   bdftogd is included in this distribution with Jan's kind permission.

BUG REPORTS

Feel free to contact me via e-mail.

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
