lstein/Perl-GD

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
g.  support for TrueType font rendering, via libfreetype.
h.  support for spline curves, via GD::Polyline
i.  support for symbolic font names, such as "helvetica:italic"
j.  support for symbolic color names, such as "green", via GD::Simple
k.  produces output in png, gif, jpeg, xbm and other formats supported by libgd
l.  produces output in svg format via GD::SVG.

For full information on usage, see the accompanying man and html
documentation. Also check the FAQ at the bottom of this document.

INSTALLATION:

1. Windows users can find a binary PPM package in the repositories at
these sites:

        http://trouchelle.com/perl/ppmrepview.pl
        http://www.bribes.org/perl/ppmdir.html

These packages are not always updated to the most recent version, but
GD is pretty stable and you usually won't miss the bleeding edge
version.

For Unix/darwin users and those who have a developer's kit installed
on Windows (e.g. cygwin):

2.  Make sure you have downloaded and installed the following packages:

	a. Perl 5.6.0 or higher:
		http://www.perl.com/

	b. The gd graphics library:
		http://libgd.org

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

	d. The zlib compression library:
		http://www.gzip.org/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.

3. On darwin, you can use these package managers to resolve dependencies and
build libgd:

        i.  MacPorts http://www.macports.org/
	ii. Homebrew http://mxcl.github.io/homebrew/

If this module fails to compile and link, you are probably using an
older version of libgd.  Symptoms of this problem include errors about
functions not being recognized in the gd.h header file, and undefined
symbols from the linker.  If you are having this type of error, please
REMOVE all versions of libgd, gd.h from your system and reinstall
libgd 2.0.28 or higher.  Do not contact Lincoln for help until you
have done this.

Use GD 1.41 for libgd versions 1.8.4 and lower.

3.  Unpack the tar file:

	zcat GD-2.XX.tar.gz | tar xvf -

    (Where "XX" is the most recent revision number.)  This will create
    the directory GD-2.XX.

4.  To compile GD.pm:

	a.  cd GD-2.XX
	b.  perl Makefile.PL
	c.  make
        d.  make test
	f.  sudo make install

    This will create GD.pm and install it 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 look for the program gdlib-config or gdlib.pc
    that newer versions of libgd install for you.  If this program is not present, the
    Makefile.PL script 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.  Before you install GD, you will 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 PNG
    files to standard output.  To view the files, pipe their
    output to "display" or "xv" in this way:

	a.  cd GD-2.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

IF YOU RUN INTO PROBLEMS

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 GD::SIMPLE LIBRARY

GD::Simple is a simplified API for GD. It supports turtle graphics, a
unified interface for drawing text, and symbolic color names (like
"green").  Run "perldoc GD::Simple" for information on using it.

The GD::SVG LIBRARY

GD::SVG, which is available separately on CPAN, provides a subset of
GD method calls. For this subset, you can create images in SVG
(scalable vector graphics) format.

THE QUICKDRAW LIBRARY

This is no longer supported.

FREQUENTLY ASKED QUESTIONS

1. I get a warning about prerequisite Math::Trig not being found

   The version of Math::Trig that comes with Perl version 5.6.0 and
   lower has a bug in it that causes it not to be found even when it
   is installed.  Try running perl -MMath::Trig -e0 from the command
   line.  If you get no errors, go ahead and install GD. If you get an
   error, install Math::Trig from CPAN.

2. Why do I get errors about functions not being found when building this module?

   You need libgd (the C library that does all the work) version 2.0.28 or
   higher.  Older versions will give you errors during GD
   installation. Get the latest version from http://libgd.org and install it.
   Sometimes just installing the new version of libgd is not enough: you must
   remove the old library first. Find the gd.h include file and all libgd files
   and remove them from your system.

3. Why do I get errors about symbols being undefined when building this module?

   See (1).

4. The %&#&#! thing doesn't compile at all! I'm getting lots of compile errors!

   Does "make" fail with messages like these?

   GD.xs: In function 'newDynamicCtx':
   GD.xs:440: error: 'gdIOCtx' has no member named 'gd_free'
   GD.xs: In function 'gd_cloneDim':
   GD.xs:460: error: 'struct gdImageStruct' has no member named 'alpha'
   GD.xs:460: error: 'struct gdImageStruct' has no member named 'alpha'
   GD.xs:466: error: 'struct gdImageStruct' has no member named 'thick'
   GD.xs:466: error: 'struct gdImageStruct' has no member named 'thick'

   If so, then you may have an old gd.h include file located somewhere
   in your system include path. Please find it and remove it. A typical
   location is /usr/include/gd.h. The way to make sure you are removing
   the correct gd.h is to run "gdlib-config --cflags" to find out where
   the current gd.h lives:

      % gdlib-config --cflags
      -I/usr/local/include

   This tells you that /usr/local/include/gd.h is the correct gd.h. Please
   find and remove any other gd.h.

5. My scripts fail with "Can't locate object method 'png' via package "GD::Image".

   libgd can now be built with support for one or more of the PNG, GIF, XPM or 
   JPEG formats. If one or more of these formats are not supported by libgd, then
   the corresponding GD::Image methods will be unavailable.  Unfortunately, many
   older scripts assume that the png() method will always be present.  You can
   work around this issue with code like the following:

      my $image = $gd->can('png') ? $gd->png : $gd->gif;

   or if you prefer eval {}

      my $image = eval {$gd->png} || $gd->gif;

   As of libgd 2.0.33, GIF support is always compiled in, so (for the time being!)
   this is a safe fallback.
   
6. Is there a utility to convert X Windows BDF fonts into GD fonts.

   Yes.  See the utility bdf2gdfont.pl.  Run "bdf2gdfont.pl -h" to get help
   on using this.

7. Does GD run with Macintosh OS X?

   Yes.  GD compiles just fine under OSX.  However, you may need to
   remove old versions of libgd, libpng, and libz and reinstall the
   current versions before you try to install GD.

8. Does GD run with Win32 Perl?

   The latest ActiveState binaries for Win32 systems 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. Github actions and appveyor are used to test the windows builds.

9. 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.  The best thing to do is to install the latest version of
   libgd. Recent versions of libgd contain a gdlib-config utility, which
   GD will use to determine which libraries are necessary and in which
   order to link them.

   Another thing to be aware of is that some Unix distributions provide
   a faulty precompiled version of Perl which is unable to build and
   load new C-based modules (like this one).  If you are getting errors
   like this:

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

   then you may have such a faulty version of Perl.  The most reliable
   thing to do is to recompile Perl from source code, thereby ensuring
   that it is complete.

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

11. The stringFTCircle() method doesn't work!

   I know.  I think this might be a problem in libgd because I have
   never gotten it to work as a C program.  If you have any insight
   into this problem let me know.

12. Test XX fails

   The regression tests for GD involve generating images, saving
   them as PNG, JPEG or GIF files, and then comparing the files bit-for-bit
   to known "correct" files.  Sometimes one of the underlying
   C libraries such as libz, libpng or libgd is updated, causing 
   GD to generate an image that is subtly different.  These differences
   are usually insignificant, such as a reordering of colors in the
   color table, but they will call isolated tests to fail.  If you
   are seeing the great majority of GD tests pass, but one or two
   fail, then you are probably seeing the effect of a new library.
   Just go ahead and install GD and drop me a note about the problem.

BUG REPORTS

Please report bugs, feature requests and propose code changes using
the GitHub repository at https://github.com/lstein/Perl-GD. We do not
check the CPAN RT bug system with any frequency.

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.

SOURCE CODE AND UPDATES:

The current version of GD can be found in CPAN. The development
version can be found on GitHub at https://github.com/lstein/Perl-GD.

AUTHOR and LICENSE

Copyright 1995-2014 Lincoln Stein <[email protected]>
Maintainance taken over by Reini Urban 2017.

This package and its accompanying libraries is free software; you can
redistribute it and/or modify it under the terms of the GPL (either
version 1, or at your option, any later version) or the Artistic
License 2.0.  Refer to LICENSE for the full license text.
package for details.