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.

===> NOTE: This version of GD REQUIRES libgd 1.8.3 or higher.  If you
===> have an older version of libgd installed you must remove libgd.a,
===> libgd.so (if present) and gd.h.  Then install the new version of
===> libgd from www.boutell.com (see below).  This particularly
===> applies to users of Linux systems.

===> This version of GD no longer supports GIF output because of
===> threats from the legal department at Unisys.  Source code
===> that calls $image->gif will have to be changed to call either
===> $image->jpg or $image->png to output in JPEG or PNG formats.
===> The last version of GD that supported GIF output was version 
===> 1.19.

COPYRIGHT INFO

The GD.pm interface is copyright 1995-2000, 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.

THE LATEST VERSION IS 1.31

INSTALLATION:

Read these instructions all the way through before you start!

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.8.4 or higher:
		http://www.boutell.com/gd/

	c. The PNG graphics library:
		http://www.libpng.org/pub/png

	d. The zlib compression library:
		http://www.cdrom.com/pub/infozip/zlib/

	(OPTIONAL)

	e. The FreeType font rendering library for TrueType fonts:
		http://www.freetype.org/

        f. The JPEG library, version 6b or later:
                ftp://ftp.uu.net/graphics/jpeg/

        g. The XPM library, a standard part of modern X Windows 
	   distributions.  If you don't have a modern
           version of X, don't try to get XPM working.

NOTE: libgd version 2.01 (currently beta) crashes in the gdFilledRect()
function when using the gdTiled color.  Don't use it with GD.

2. OPTIONAL -- patch the libgd distribution

Some users have had trouble getting GD to link correctly.  Part of the
problem is that Perl's Makefile.PL system prefers dynamically-linked
shared libraries, but libgd builds a static library file by default.
The file C<patch_gd.pl>, included with this distribution, will patch
libgd version 1.8.4 to make it possible to compile it as a shared
library.

This file is a perl script which runs GNU patch and then makes a few
other adjustments.  To use it, copy it into the top level of a
B<virgin> copy of the gd-1.8.4 directory.  Then run it like this:

  % perl patch_gd.pl

This will patch the libgd distribution so that it works with the GNU
autoconfiguration system.  Read the README and INSTALL files that were
created by the script and follow the directions.

The patch requires a recent version of GNU patch (download sites
listed at http://www.gnu.org/order/ftp.html).  Solaris systems do
*not* have a suitable version of patch.  You must install GNU patch
yourself.

It is possible that this patch will work with later version of libgd,
but this is not guaranteed. 

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

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

	a.  cd GD-1.XX
	b.  perl Makefile.PL
            Please choose the features that match how libgd was built:
            Build JPEG support? [y] 
            Build FreeType support? [y] 
            Build XPM support? [y] 
	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.

    During step (b), Makefile.PL will ask you whether to build support for
    JPEG, FreeType and/or XPM image formats.  Please answer "y" (the default) 
    if libgd was built with the feature, and "n" if it was not.  Failure
    to answer correctly will lead to link errors.

    If, during step (b) you see notes about missing libraries, then this
    module will probably not link correctly, even though the warning may say
    "probably harmless".    

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

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

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

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

9.  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.  Other problems may be fixed by compiling libgd as a
shared library, as described in step (2) of the installation
instructions.

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.  I don't own any Win32 systems,
   and cannot provide you with help in compiling GD from scratch on such 
   systems.

4. GD won't compile on system XX.

   Because libgd relies on multiple external libraries, GD does as well.  
   Unfortunately, different systems place their libraries in different
   places and sometimes are picky about the order in which libraries 
   are linked.  If you are having problems with compiling GD, first make
   sure that you have removed all vestiges of old libgd installations,
   including both library and header files (e.g. gd.h).  If that doesn't
   help matters, examine the following lines in Makefile.PL:

   my @INC     = qw(-I/usr/local/include -I/usr/local/include/gd); 
   my @LIBPATH = qw(-L/usr/lib/X11 -L/usr/X11R6/lib -L/usr/X11/lib -L/usr/local/lib );
   my @LIBS    = qw(-lgd -lpng -lz);

   Try adjusting the pathnames in @INC and @LIBPATH, and/or the
   link order in @LIBS.  In a few cases, people who haven't had any
   luck at all have been able to get GD to compile by first reinstalling
   Perl from scratch.  Perhaps this reflects a situation in which Perl
   was initially built with one set of system libraries, and then the
   libraries were updated (or Perl was moved to a different machine).

   If you get this error:

   /arch/auto/GD/GD.so: undefined symbol: SetCPerlObj at ....

   You may have a version of Perl that was compiled with one C compiler
   and then moved to another system with a slightly different version of
   the compiler.  The only solution I know of is to compile Perl completely 
   from scratch on the target system.

   If you get frustrated with not being able to compile libgd, GD, or one
   of the many external libraries needed by this module, just go to CPAN
   and get GD version 1.19.  It only produces GIFs, but it uses a self-
   contained version of libgd and requires no external libraries at all.

5. When I try to load an XPM file, all I get is blackness!

   The libgd createFromXpm() function works with some XPM files, and
   not with others.  The problem is buried deep in the libXpm library
   somewhere.

BUG REPORTS

Feel free to contact me via e-mail, subject to the caveats below.
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.

Also do NOT contact me for issues involving the images looking
distorted, having the wrong color tables, or other such low-level
issues.  These problems should be referred to Tom Boutell because they
pertain to the underlying libgd library.

WHAT'S NEW IN 1.30
	- now you can create GD::Image objects directly from image DATA
	- reformatted documentation

WHAT'S NEW IN 1.29
	- internal release

WHAT'S NEW IN 1.28
	- fixed a bad regression test

WHAT'S NEW IN 1.27
	- updated for compatibility with libgd 1.8.3
	- WBMP support
	- turned Makefile.PL into a multiple-choice quiz
	- turned libgd patchfile into a perl script

WHAT'S NEW IN 1.26
	- updated for compatibility with libgd 1.8.1
	- JPEG support
	- the newFromXXX() functions now accept pathnames
	- patchfile for building libgd as a shared library

WHAT'S NEW IN 1.25
	- improvements to the Makefile to help with compilation

WHAT'S NEW IN 1.24
	- added more help in compiling and installing to docs

WHAT'S NEW IN 1.23
	- added some more libraries to link in, might help unresolved symbol problems
	- if Tom Boutell would provide support for linking libgd dynamically,
	 none of these unresolved symbol problems would be occurring!!!!!

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.

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