diff options
Diffstat (limited to 'Master/tlpkg/tlperl0/lib/GD.pm')
| -rwxr-xr-x | Master/tlpkg/tlperl0/lib/GD.pm | 1784 |
1 files changed, 1784 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl0/lib/GD.pm b/Master/tlpkg/tlperl0/lib/GD.pm new file mode 100755 index 00000000000..7d5f4206736 --- /dev/null +++ b/Master/tlpkg/tlperl0/lib/GD.pm @@ -0,0 +1,1784 @@ +package GD; + +# Copyright 1995 Lincoln D. Stein. See accompanying README file for +# usage information + +use strict; +require 5.004; +require FileHandle; +require Exporter; +require DynaLoader; +require AutoLoader; +use Carp 'croak','carp'; + +use GD::Image; +use GD::Polygon; + +use vars qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS $AUTOLOAD); + +$VERSION = '2.44'; + +@ISA = qw(Exporter DynaLoader); +# Items to export into callers namespace by default. Note: do not export +# names by default without a very good reason. Use EXPORT_OK instead. +# Do not simply export all your public functions/methods/constants. +@EXPORT = qw( + gdBrushed + gdDashSize + gdMaxColors + gdStyled + gdStyledBrushed + gdTiled + gdTransparent + gdAntiAliased + gdArc + gdChord + gdPie + gdNoFill + gdEdged + gdTinyFont + gdSmallFont + gdMediumBoldFont + gdLargeFont + gdGiantFont + gdAlphaMax + gdAlphaOpaque + gdAlphaTransparent +); + +@EXPORT_OK = qw ( + GD_CMP_IMAGE + GD_CMP_NUM_COLORS + GD_CMP_COLOR + GD_CMP_SIZE_X + GD_CMP_SIZE_Y + GD_CMP_TRANSPARENT + GD_CMP_BACKGROUND + GD_CMP_INTERLACE + GD_CMP_TRUECOLOR +); + +%EXPORT_TAGS = ('cmp' => [qw(GD_CMP_IMAGE + GD_CMP_NUM_COLORS + GD_CMP_COLOR + GD_CMP_SIZE_X + GD_CMP_SIZE_Y + GD_CMP_TRANSPARENT + GD_CMP_BACKGROUND + GD_CMP_INTERLACE + GD_CMP_TRUECOLOR + ) + ] + ); + +# documentation error +*GD::Polygon::delete = \&GD::Polygon::deletePt; + +sub AUTOLOAD { + # This AUTOLOAD is used to 'autoload' constants from the constant() + # XS function. If a constant is not found then control is passed + # to the AUTOLOAD in AutoLoader. + + my($constname); + ($constname = $AUTOLOAD) =~ s/.*:://; + my $val = constant($constname); + if ($! != 0) { + if ($! =~ /Invalid/) { + $AutoLoader::AUTOLOAD = $AUTOLOAD; + goto &AutoLoader::AUTOLOAD; + } + else { + my($pack,$file,$line) = caller; + die "Your vendor has not defined GD macro $pack\:\:$constname, used at $file line $line.\n"; + } + } + eval "sub $AUTOLOAD { $val }"; + goto &$AUTOLOAD; +} + +bootstrap GD; + + +# Preloaded methods go here. +sub GD::gdSmallFont { + return GD::Font->Small; +} + +sub GD::gdLargeFont { + return GD::Font->Large; +} + +sub GD::gdMediumBoldFont { + return GD::Font->MediumBold; +} + +sub GD::gdTinyFont { + return GD::Font->Tiny; +} + +sub GD::gdGiantFont { + return GD::Font->Giant; +} + +sub GD::Image::startGroup { } # does nothing - used by GD::SVG +sub GD::Image::endGroup { } # does nothing - used by GD::SVG +sub GD::Image::newGroup { + my $self = shift; + GD::Group->new($self,$self->startGroup); +} + +=head1 NAME + +GD.pm - Interface to Gd Graphics Library + +=head1 SYNOPSIS + + use GD; + + # create a new image + $im = new GD::Image(100,100); + + # allocate some colors + $white = $im->colorAllocate(255,255,255); + $black = $im->colorAllocate(0,0,0); + $red = $im->colorAllocate(255,0,0); + $blue = $im->colorAllocate(0,0,255); + + # make the background transparent and interlaced + $im->transparent($white); + $im->interlaced('true'); + + # Put a black frame around the picture + $im->rectangle(0,0,99,99,$black); + + # Draw a blue oval + $im->arc(50,50,95,75,0,360,$blue); + + # And fill it with red + $im->fill(50,50,$red); + + # make sure we are writing to a binary stream + binmode STDOUT; + + # Convert the image to PNG and print it on standard output + print $im->png; + +=head1 DESCRIPTION + +B<GD.pm> is a Perl interface to Thomas Boutell's gd graphics library +(version 2.01 or higher; see below). GD allows you to create color +drawings using a large number of graphics primitives, and emit the +drawings as PNG files. + +GD defines the following four classes: + +=over 5 + + +=item C<GD::Image> + +An image class, which holds the image data and accepts graphic +primitive method calls. + +=item C<GD::Font> + +A font class, which holds static font information and used for text +rendering. + +=item C<GD::Polygon> + +A simple polygon object, used for storing lists of vertices prior to +rendering a polygon into an image. + +=item C<GD::Simple> + +A "simple" class that simplifies the GD::Image API and then adds a set +of object-oriented drawing methods using turtle graphics, simplified +font handling, ability to work in polar coordinates, HSV color spaces, +and human-readable color names like "lightblue". Please see +L<GD::Simple> for a description of these methods. + +=back + +A Simple Example: + + #!/usr/local/bin/perl + + use GD; + + # create a new image + $im = new GD::Image(100,100); + + # allocate some colors + $white = $im->colorAllocate(255,255,255); + $black = $im->colorAllocate(0,0,0); + $red = $im->colorAllocate(255,0,0); + $blue = $im->colorAllocate(0,0,255); + + # make the background transparent and interlaced + $im->transparent($white); + $im->interlaced('true'); + + # Put a black frame around the picture + $im->rectangle(0,0,99,99,$black); + + # Draw a blue oval + $im->arc(50,50,95,75,0,360,$blue); + + # And fill it with red + $im->fill(50,50,$red); + + # make sure we are writing to a binary stream + binmode STDOUT; + + # Convert the image to PNG and print it on standard output + print $im->png; + +Notes: + +=over 5 + +=item 1. +To create a new, empty image, send a new() message to GD::Image, passing +it the width and height of the image you want to create. An image +object will be returned. Other class methods allow you to initialize +an image from a preexisting JPG, PNG, GD, GD2 or XBM file. + +=item 2. +Next you will ordinarily add colors to the image's color table. +colors are added using a colorAllocate() method call. The three +parameters in each call are the red, green and blue (rgb) triples for +the desired color. The method returns the index of that color in the +image's color table. You should store these indexes for later use. + +=item 3. +Now you can do some drawing! The various graphics primitives are +described below. In this example, we do some text drawing, create an +oval, and create and draw a polygon. + +=item 4. +Polygons are created with a new() message to GD::Polygon. You can add +points to the returned polygon one at a time using the addPt() method. +The polygon can then be passed to an image for rendering. + +=item 5. +When you're done drawing, you can convert the image into PNG format by +sending it a png() message. It will return a (potentially large) +scalar value containing the binary data for the image. Ordinarily you +will print it out at this point or write it to a file. To ensure +portability to platforms that differentiate between text and binary +files, be sure to call C<binmode()> on the file you are writing +the image to. + +=back + +=head1 Object Constructors: Creating Images + +The following class methods allow you to create new GD::Image objects. + +=over 4 + +=item B<$image = GD::Image-E<gt>new([$width,$height],[$truecolor])> + +=item B<$image = GD::Image-E<gt>new(*FILEHANDLE)> + +=item B<$image = GD::Image-E<gt>new($filename)> + +=item B<$image = GD::Image-E<gt>new($data)> + +The new() method is the main constructor for the GD::Image class. +Called with two integer arguments, it creates a new blank image of the +specified width and height. For example: + + $myImage = new GD::Image(100,100) || die; + +This will create an image that is 100 x 100 pixels wide. If you don't +specify the dimensions, a default of 64 x 64 will be chosen. + +The optional third argument, $truecolor, tells new() to create a +truecolor GD::Image object. Truecolor images have 24 bits of color +data (eight bits each in the red, green and blue channels +respectively), allowing for precise photograph-quality color usage. +If not specified, the image will use an 8-bit palette for +compatibility with older versions of libgd. + +Alternatively, you may create a GD::Image object based on an existing +image by providing an open filehandle, a filename, or the image data +itself. The image formats automatically recognized and accepted are: +PNG, JPEG, XPM and GD2. Other formats, including WBMP, and GD +version 1, cannot be recognized automatically at this time. + +If something goes wrong (e.g. insufficient memory), this call will +return undef. + +=item B<$image = GD::Image-E<gt>trueColor([0,1])> + +For backwards compatibility with scripts previous versions of GD, +new images created from scratch (width, height) are palette based +by default. To change this default to create true color images use: + + GD::Image->trueColor(1); + +somewhere before creating new images. To switch back to palette +based by default, use: + + GD::Image->trueColor(0); + +=item B<$image = GD::Image-E<gt>newPalette([$width,$height])> + +=item B<$image = GD::Image-E<gt>newTrueColor([$width,$height])> + +The newPalette() and newTrueColor() methods can be used to explicitly +create an palette based or true color image regardless of the +current setting of trueColor(). + +=item B<$image = GD::Image-E<gt>newFromPng($file, [$truecolor])> + +=item B<$image = GD::Image-E<gt>newFromPngData($data, [$truecolor])> + +The newFromPng() method will create an image from a PNG file read in +through the provided filehandle or file path. The filehandle must +previously have been opened on a valid PNG file or pipe. If +successful, this call will return an initialized image which you can +then manipulate as you please. If it fails, which usually happens if +the thing at the other end of the filehandle is not a valid PNG file, +the call returns undef. Notice that the call doesn't automatically +close the filehandle for you. But it does call C<binmode(FILEHANDLE)> +for you, on platforms where this matters. + +You may use any of the following as the argument: + + 1) a simple filehandle, such as STDIN + 2) a filehandle glob, such as *PNG + 3) a reference to a glob, such as \*PNG + 4) an IO::Handle object + 5) the pathname of a file + +In the latter case, newFromPng() will attempt to open the file for you +and read the PNG information from it. + + Example1: + + open (PNG,"barnswallow.png") || die; + $myImage = newFromPng GD::Image(\*PNG) || die; + close PNG; + + Example2: + $myImage = newFromPng GD::Image('barnswallow.png'); + +To get information about the size and color usage of the information, +you can call the image query methods described below. Images created +by reading PNG images will be truecolor if the image file itself is +truecolor. To force the image to be palette-based, pass a value of 0 +in the optional $truecolor argument. + +The newFromPngData() method will create a new GD::Image initialized +with the PNG format B<data> contained in C<$data>. + +=item B<$image = GD::Image-E<gt>newFromJpeg($file, [$truecolor])> + +=item B<$image = GD::Image-E<gt>newFromJpegData($data, [$truecolor])> + +These methods will create an image from a JPEG file. They work just +like newFromPng() and newFromPngData(), and will accept the same +filehandle and pathname arguments. + +Images created by reading JPEG images will always be truecolor. To +force the image to be palette-based, pass a value of 0 in the optional +$truecolor argument. + +=item B<$image = GD::Image-E<gt>newFromGif($file)> + +=item B<$image = GD::Image-E<gt>newFromGifData($data)> + +These methods will create an image from a GIF file. They work just +like newFromPng() and newFromPngData(), and will accept the same +filehandle and pathname arguments. + +Images created from GIFs are always 8-bit palette images. To convert +to truecolor, you must create a truecolor image and then perform a +copy. + +=item B<$image = GD::Image-E<gt>newFromXbm($file)> + +This works in exactly the same way as C<newFromPng>, but reads the +contents of an X Bitmap (black & white) file: + + open (XBM,"coredump.xbm") || die; + $myImage = newFromXbm GD::Image(\*XBM) || die; + close XBM; + +There is no newFromXbmData() function, because there is no +corresponding function in the gd library. + +=item B<$image = GD::Image-E<gt>newFromGd($file)> + +=item B<$image = GD::Image-E<gt>newFromGdData($data)> + +These methods initialize a GD::Image from a Gd file, filehandle, or +data. Gd is Tom Boutell's disk-based storage format, intended for the +rare case when you need to read and write the image to disk quickly. +It's not intended for regular use, because, unlike PNG or JPEG, no +image compression is performed and these files can become B<BIG>. + + $myImage = newFromGd GD::Image("godzilla.gd") || die; + close GDF; + +=item B<$image = GD::Image-E<gt>newFromGd2($file)> + +=item B<$image = GD::Image-E<gt>newFromGd2Data($data)> + +This works in exactly the same way as C<newFromGd()> and +newFromGdData, but use the new compressed GD2 image format. + +=item B<$image = GD::Image-E<gt>newFromGd2Part($file,srcX,srcY,width,height)> + +This class method allows you to read in just a portion of a GD2 image +file. In addition to a filehandle, it accepts the top-left corner and +dimensions (width,height) of the region of the image to read. For +example: + + open (GDF,"godzilla.gd2") || die; + $myImage = GD::Image->newFromGd2Part(\*GDF,10,20,100,100) || die; + close GDF; + +This reads a 100x100 square portion of the image starting from +position (10,20). + +=item B<$image = GD::Image-E<gt>newFromXpm($filename)> + +This creates a new GD::Image object starting from a B<filename>. This +is unlike the other newFrom() functions because it does not take a +filehandle. This difference comes from an inconsistency in the +underlying gd library. + + $myImage = newFromXpm GD::Image('earth.xpm') || die; + +This function is only available if libgd was compiled with XPM +support. + +NOTE: The libgd library is unable to read certain XPM files, returning +an all-black image instead. + +=head1 GD::Image Methods + +Once a GD::Image object is created, you can draw with it, copy it, and +merge two images. When you are finished manipulating the object, you +can convert it into a standard image file format to output or save to +a file. + +=head2 Image Data Output Methods + +The following methods convert the internal drawing format into +standard output file formats. + +=item B<$pngdata = $image-E<gt>png([$compression_level])> + +This returns the image data in PNG format. You can then print it, +pipe it to a display program, or write it to a file. Example: + + $png_data = $myImage->png; + open (DISPLAY,"| display -") || die; + binmode DISPLAY; + print DISPLAY $png_data; + close DISPLAY; + +Note the use of C<binmode()>. This is crucial for portability to +DOSish platforms. + +The optional $compression_level argument controls the amount of +compression to apply to the output PNG image. Values range from 0-9, +where 0 means no compression (largest files, highest quality) and 9 +means maximum compression (smallest files, worst quality). A +compression level of -1 uses the default compression level selected +when zlib was compiled on your system, and is the same as calling +png() with no argument. Be careful not to confuse this argument with +the jpeg() quality argument, which ranges from 0-100 and has the +opposite meaning from compression (higher numbers give higher +quality). + +=item B<$gifdata = $image-E<gt>gifanimbegin([$GlobalCM [, $Loops]])> + +For libgd version 2.0.33 and higher, this call begins an animated GIF +by returning the data that comprises animated gif image file header. +After you call this method, call gifanimadd() one or more times to add +the frames of the image. Then call gifanimend(). Each frame must be +the same width and height. + +A typical sequence will look like this: + + my $gifdata = $image->gifanimbegin; + $gifdata .= $image->gifanimadd; # first frame + for (1..100) { + # make a frame of right size + my $frame = GD::Image->new($image->getBounds); + add_frame_data($frame); # add the data for this frame + $gifdata .= $frame->gifanimadd; # add frame + } + $gifdata .= $image->gifanimend; # finish the animated GIF + print $gifdata; # write animated gif to STDOUT + +If you do not wish to store the data in memory, you can print it to +stdout or a file. + +The image that you call gifanimbegin on is used to set the image size, +color resolution and color map. If argument $GlobalCM is 1, the image +color map becomes the GIF89a global color map. If $Loops is given and +>= 0, the NETSCAPE2.0 application extension is created, with looping +count. Looping count 0 means forever. + +=item B<$gifdata = $image-E<gt>gifanimadd([$LocalCM [, $LeftOfs [, $TopOfs [, $Delay [, $Disposal [, $previm]]]]]])> + +Returns the data that comprises one animated gif image frame. You can +then print it, pipe it to a display program, or write it to a file. +With $LeftOfs and $TopOfs you can place this frame in different offset +than (0,0) inside the image screen. Delay between the previous frame +and this frame is in 1/100s units. Disposal is usually and by default +1. Compression is activated by giving the previous image as a +parameter. This function then compares the images and only writes the +changed pixels to the new frame in animation. The Disposal parameter +for optimized animations must be set to 1, also for the first frame. +$LeftOfs and $TopOfs parameters are ignored for optimized frames. + +=item B<$gifdata = $image-E<gt>gifanimend()> + +Returns the data for end segment of animated gif file. It always +returns string ';'. This string must be printed to an animated gif +file after all image frames to properly terminate it according to GIF +file syntax. Image object is not used at all in this method. + +=item B<$jpegdata = $image-E<gt>jpeg([$quality])> + +This returns the image data in JPEG format. You can then print it, +pipe it to a display program, or write it to a file. You may pass an +optional quality score to jpeg() in order to control the JPEG quality. +This should be an integer between 0 and 100. Higher quality scores +give larger files and better image quality. If you don't specify the +quality, jpeg() will choose a good default. + +=item B<$gifdata = $image-E<gt>gif()>. + +This returns the image data in GIF format. You can then print it, +pipe it to a display program, or write it to a file. + +=item B<$gddata = $image-E<gt>gd> + +This returns the image data in GD format. You can then print it, +pipe it to a display program, or write it to a file. Example: + + binmode MYOUTFILE; + print MYOUTFILE $myImage->gd; + +=item B<$gd2data = $image-E<gt>gd2> + +Same as gd(), except that it returns the data in compressed GD2 +format. + +=item B<$wbmpdata = $image-E<gt>wbmp([$foreground])> + +This returns the image data in WBMP format, which is a black-and-white +image format. Provide the index of the color to become the foreground +color. All other pixels will be considered background. + +=back + +=head2 Color Control + +These methods allow you to control and manipulate the GD::Image color +table. + +=over 4 + +=item B<$index = $image-E<gt>colorAllocate(red,green,blue)> + +This allocates a color with the specified red, green and blue +components and returns its index in the color table, if specified. +The first color allocated in this way becomes the image's background +color. (255,255,255) is white (all pixels on). (0,0,0) is black (all +pixels off). (255,0,0) is fully saturated red. (127,127,127) is 50% +gray. You can find plenty of examples in /usr/X11/lib/X11/rgb.txt. + +If no colors are allocated, then this function returns -1. + +Example: + + $white = $myImage->colorAllocate(0,0,0); #background color + $black = $myImage->colorAllocate(255,255,255); + $peachpuff = $myImage->colorAllocate(255,218,185); + +=item B<$index = $image-E<gt>colorAllocateAlpha(reg,green,blue,alpha)> + +This allocates a color with the specified red, green, and blue components, +plus the specified alpha channel. The alpha value may range from 0 (opaque) +to 127 (transparent). The C<alphaBlending> function changes the way this +alpha channel affects the resulting image. + +=item B<$image-E<gt>colorDeallocate(colorIndex)> + +This marks the color at the specified index as being ripe for +reallocation. The next time colorAllocate is used, this entry will be +replaced. You can call this method several times to deallocate +multiple colors. There's no function result from this call. + +Example: + + $myImage->colorDeallocate($peachpuff); + $peachy = $myImage->colorAllocate(255,210,185); + +=item B<$index = $image-E<gt>colorClosest(red,green,blue)> + +This returns the index of the color closest in the color table to the +red green and blue components specified. If no colors have yet been +allocated, then this call returns -1. + +Example: + + $apricot = $myImage->colorClosest(255,200,180); + +=item B<$index = $image-E<gt>colorClosestHWB(red,green,blue)> + +This also attempts to return the color closest in the color table to the +red green and blue components specified. It uses a Hue/White/Black +color representation to make the selected color more likely to match +human perceptions of similar colors. + +If no colors have yet been +allocated, then this call returns -1. + +Example: + + $mostred = $myImage->colorClosestHWB(255,0,0); + +=item B<$index = $image-E<gt>colorExact(red,green,blue)> + +This returns the index of a color that exactly matches the specified +red green and blue components. If such a color is not in the color +table, this call returns -1. + + $rosey = $myImage->colorExact(255,100,80); + warn "Everything's coming up roses.\n" if $rosey >= 0; + +=item B<$index = $image-E<gt>colorResolve(red,green,blue)> + +This returns the index of a color that exactly matches the specified +red green and blue components. If such a color is not in the color +table and there is room, then this method allocates the color in the +color table and returns its index. + + $rosey = $myImage->colorResolve(255,100,80); + warn "Everything's coming up roses.\n" if $rosey >= 0; + +=item B<$colorsTotal = $image-E<gt>colorsTotal> I<object method> + +This returns the total number of colors allocated in the object. + + $maxColors = $myImage->colorsTotal; + +In the case of a TrueColor image, this call will return undef. + +=item B<$index = $image-E<gt>getPixel(x,y)> I<object method> + +This returns the color table index underneath the specified +point. It can be combined with rgb() +to obtain the rgb color underneath the pixel. + +Example: + + $index = $myImage->getPixel(20,100); + ($r,$g,$b) = $myImage->rgb($index); + +=item B<($red,$green,$blue) = $image-E<gt>rgb($index)> + +This returns a list containing the red, green and blue components of +the specified color index. + +Example: + + @RGB = $myImage->rgb($peachy); + +=item B<$image-E<gt>transparent($colorIndex)> + +This marks the color at the specified index as being transparent. +Portions of the image drawn in this color will be invisible. This is +useful for creating paintbrushes of odd shapes, as well as for +making PNG backgrounds transparent for displaying on the Web. Only +one color can be transparent at any time. To disable transparency, +specify -1 for the index. + +If you call this method without any parameters, it will return the +current index of the transparent color, or -1 if none. + +Example: + + open(PNG,"test.png"); + $im = newFromPng GD::Image(PNG); + $white = $im->colorClosest(255,255,255); # find white + $im->transparent($white); + binmode STDOUT; + print $im->png; + +=back + +=head2 Special Colors + +GD implements a number of special colors that can be used to achieve +special effects. They are constants defined in the GD:: +namespace, but automatically exported into your namespace when the GD +module is loaded. + +=over 4 + +=item B<$image-E<gt>setBrush($image)> + +You can draw lines and shapes using a brush pattern. Brushes are just +images that you can create and manipulate in the usual way. When you +draw with them, their contents are used for the color and shape of the +lines. + +To make a brushed line, you must create or load the brush first, then +assign it to the image using setBrush(). You can then draw in that +with that brush using the B<gdBrushed> special color. It's often +useful to set the background of the brush to transparent so that the +non-colored parts don't overwrite other parts of your image. + +Example: + + # Create a brush at an angle + $diagonal_brush = new GD::Image(5,5); + $white = $diagonal_brush->colorAllocate(255,255,255); + $black = $diagonal_brush->colorAllocate(0,0,0); + $diagonal_brush->transparent($white); + $diagonal_brush->line(0,4,4,0,$black); # NE diagonal + + # Set the brush + $myImage->setBrush($diagonal_brush); + + # Draw a circle using the brush + $myImage->arc(50,50,25,25,0,360,gdBrushed); + +=item B<$image-E<gt>setThickness($thickness)> + +Lines drawn with line(), rectangle(), arc(), and so forth are 1 pixel +thick by default. Call setThickness() to change the line drawing +width. + +=item B<$image-E<gt>setStyle(@colors)> + +Styled lines consist of an arbitrary series of repeated colors and are +useful for generating dotted and dashed lines. To create a styled +line, use setStyle() to specify a repeating series of colors. It +accepts an array consisting of one or more color indexes. Then draw +using the B<gdStyled> special color. Another special color, +B<gdTransparent> can be used to introduce holes in the line, as the +example shows. + +Example: + + # Set a style consisting of 4 pixels of yellow, + # 4 pixels of blue, and a 2 pixel gap + $myImage->setStyle($yellow,$yellow,$yellow,$yellow, + $blue,$blue,$blue,$blue, + gdTransparent,gdTransparent); + $myImage->arc(50,50,25,25,0,360,gdStyled); + +To combine the C<gdStyled> and C<gdBrushed> behaviors, you can specify +C<gdStyledBrushed>. In this case, a pixel from the current brush +pattern is rendered wherever the color specified in setStyle() is +neither gdTransparent nor 0. + +=item B<gdTiled> + +Draw filled shapes and flood fills using a pattern. The pattern is +just another image. The image will be tiled multiple times in order +to fill the required space, creating wallpaper effects. You must call +C<setTile> in order to define the particular tile pattern you'll use +for drawing when you specify the gdTiled color. +details. + +=item B<gdStyled> + +The gdStyled color is used for creating dashed and dotted lines. A +styled line can contain any series of colors and is created using the +setStyled() command. + +=item B<gdAntiAliased> + +The C<gdAntiAliased> color is used for drawing lines with antialiasing +turned on. Antialiasing will blend the jagged edges of lines with the +background, creating a smoother look. The actual color drawn is set +with setAntiAliased(). + +=item B<$image-E<gt>setAntiAliased($color)> + +"Antialiasing" is a process by which jagged edges associated with line +drawing can be reduced by blending the foreground color with an +appropriate percentage of the background, depending on how much of the +pixel in question is actually within the boundaries of the line being +drawn. All line-drawing methods, such as line() and polygon, will draw +antialiased lines if the special "color" B<gdAntiAliased> is used when +calling them. + +setAntiAliased() is used to specify the actual foreground color to be +used when drawing antialiased lines. You may set any color to be the +foreground, however as of libgd version 2.0.12 an alpha channel +component is not supported. + +Antialiased lines can be drawn on both truecolor and palette-based +images. However, attempts to draw antialiased lines on highly complex +palette-based backgrounds may not give satisfactory results, due to +the limited number of colors available in the palette. Antialiased +line-drawing on simple backgrounds should work well with palette-based +images; otherwise create or fetch a truecolor image instead. When +using palette-based images, be sure to allocate a broad spectrum of +colors in order to have sufficient colors for the antialiasing to use. + +=item B<$image-E<gt>setAntiAliasedDontBlend($color,[$flag])> + +Normally, when drawing lines with the special B<gdAntiAliased> +"color," blending with the background to reduce jagged edges is the +desired behavior. However, when it is desired that lines not be +blended with one particular color when it is encountered in the +background, the setAntiAliasedDontBlend() method can be used to +indicate the special color that the foreground should stand out more +clearly against. + +Once turned on, you can turn this feature off by calling +setAntiAliasedDontBlend() with a second argument of 0: + + $image->setAntiAliasedDontBlend($color,0); + +=back + +=head2 Drawing Commands + +These methods allow you to draw lines, rectangles, and ellipses, as +well as to perform various special operations like flood-fill. + +=over 4 + +=item B<$image-E<gt>setPixel($x,$y,$color)> + +This sets the pixel at (x,y) to the specified color index. No value +is returned from this method. The coordinate system starts at the +upper left at (0,0) and gets larger as you go down and to the right. +You can use a real color, or one of the special colors gdBrushed, +gdStyled and gdStyledBrushed can be specified. + +Example: + + # This assumes $peach already allocated + $myImage->setPixel(50,50,$peach); + +=item B<$image-E<gt>line($x1,$y1,$x2,$y2,$color)> + +This draws a line from (x1,y1) to (x2,y2) of the specified color. You +can use a real color, or one of the special colors gdBrushed, +gdStyled and gdStyledBrushed. + +Example: + + # Draw a diagonal line using the currently defined + # paintbrush pattern. + $myImage->line(0,0,150,150,gdBrushed); + +=item B<$image-E<gt>dashedLine($x1,$y1,$x2,$y2,$color)> + +DEPRECATED: The libgd library provides this method solely for backward +compatibility with libgd version 1.0, and there have been reports that +it no longer works as expected. Please use the setStyle() and gdStyled +methods as described below. + +This draws a dashed line from (x1,y1) to (x2,y2) in the specified +color. A more powerful way to generate arbitrary dashed and dotted +lines is to use the setStyle() method described below and to draw with +the special color gdStyled. + +Example: + + $myImage->dashedLine(0,0,150,150,$blue); + +=item B<$image-E<gt>rectangle($x1,$y1,$x2,$y2,$color)> + +This draws a rectangle with the specified color. (x1,y1) and (x2,y2) +are the upper left and lower right corners respectively. Both real +color indexes and the special colors gdBrushed, gdStyled and +gdStyledBrushed are accepted. + +Example: + + $myImage->rectangle(10,10,100,100,$rose); + +=item B<$image-E<gt>filledRectangle($x1,$y1,$x2,$y2,$color)> + +This draws a rectangle filed with the specified color. You can use a +real color, or the special fill color gdTiled to fill the polygon +with a pattern. + +Example: + + # read in a fill pattern and set it + $tile = newFromPng GD::Image('happyface.png'); + $myImage->setTile($tile); + + # draw the rectangle, filling it with the pattern + $myImage->filledRectangle(10,10,150,200,gdTiled); + +=item B<$image-E<gt>openPolygon($polygon,$color)> + +This draws a polygon with the specified color. The polygon must be +created first (see below). The polygon must have at least three +vertices. If the last vertex doesn't close the polygon, the method +will close it for you. Both real color indexes and the special +colors gdBrushed, gdStyled and gdStyledBrushed can be specified. + +Example: + + $poly = new GD::Polygon; + $poly->addPt(50,0); + $poly->addPt(99,99); + $poly->addPt(0,99); + $myImage->openPolygon($poly,$blue); + +=item B<$image-E<gt>unclosedPolygon($polygon,$color)> + +This draws a sequence of connected lines with the specified color, +without connecting the first and last point to a closed polygon. The +polygon must be created first (see below). The polygon must have at +least three vertices. Both real color indexes and the special colors +gdBrushed, gdStyled and gdStyledBrushed can be specified. + +You need libgd 2.0.33 or higher to use this feature. + +Example: + + $poly = new GD::Polygon; + $poly->addPt(50,0); + $poly->addPt(99,99); + $poly->addPt(0,99); + $myImage->unclosedPolygon($poly,$blue); + +=item B<$image-E<gt>filledPolygon($poly,$color)> + +This draws a polygon filled with the specified color. You can use a +real color, or the special fill color gdTiled to fill the polygon +with a pattern. + +Example: + + # make a polygon + $poly = new GD::Polygon; + $poly->addPt(50,0); + $poly->addPt(99,99); + $poly->addPt(0,99); + + # draw the polygon, filling it with a color + $myImage->filledPolygon($poly,$peachpuff); + +=item B<$image-E<gt>ellipse($cx,$cy,$width,$height,$color)> + +=item B<$image-E<gt>filledEllipse($cx,$cy,$width,$height,$color)> + +These methods() draw ellipses. ($cx,$cy) is the center of the arc, and +($width,$height) specify the ellipse width and height, respectively. +filledEllipse() is like Ellipse() except that the former produces +filled versions of the ellipse. + +=item B<$image-E<gt>arc($cx,$cy,$width,$height,$start,$end,$color)> + +This draws arcs and ellipses. (cx,cy) are the center of the arc, and +(width,height) specify the width and height, respectively. The +portion of the ellipse covered by the arc are controlled by start and +end, both of which are given in degrees from 0 to 360. Zero is at the +top of the ellipse, and angles increase clockwise. To specify a +complete ellipse, use 0 and 360 as the starting and ending angles. To +draw a circle, use the same value for width and height. + +You can specify a normal color or one of the special colors +B<gdBrushed>, B<gdStyled>, or B<gdStyledBrushed>. + +Example: + + # draw a semicircle centered at 100,100 + $myImage->arc(100,100,50,50,0,180,$blue); + +=item B<$image-E<gt>filledArc($cx,$cy,$width,$height,$start,$end,$color [,$arc_style])> + +This method is like arc() except that it colors in the pie wedge with +the selected color. $arc_style is optional. If present it is a +bitwise OR of the following constants: + + gdArc connect start & end points of arc with a rounded edge + gdChord connect start & end points of arc with a straight line + gdPie synonym for gdChord + gdNoFill outline the arc or chord + gdEdged connect beginning and ending of the arc to the center + +gdArc and gdChord are mutually exclusive. gdChord just connects the +starting and ending angles with a straight line, while gdArc produces +a rounded edge. gdPie is a synonym for gdArc. gdNoFill indicates that +the arc or chord should be outlined, not filled. gdEdged, used +together with gdNoFill, indicates that the beginning and ending angles +should be connected to the center; this is a good way to outline +(rather than fill) a "pie slice." + +Example: + + $image->filledArc(100,100,50,50,0,90,$blue,gdEdged|gdNoFill); + +=item B<$image-E<gt>fill($x,$y,$color)> + +This method flood-fills regions with the specified color. The color +will spread through the image, starting at point (x,y), until it is +stopped by a pixel of a different color from the starting pixel (this +is similar to the "paintbucket" in many popular drawing toys). You +can specify a normal color, or the special color gdTiled, to flood-fill +with patterns. + +Example: + + # Draw a rectangle, and then make its interior blue + $myImage->rectangle(10,10,100,100,$black); + $myImage->fill(50,50,$blue); + +=item B<$image-E<gt>fillToBorder($x,$y,$bordercolor,$color)> + +Like C<fill>, this method flood-fills regions with the specified +color, starting at position (x,y). However, instead of stopping when +it hits a pixel of a different color than the starting pixel, flooding +will only stop when it hits the color specified by bordercolor. You +must specify a normal indexed color for the bordercolor. However, you +are free to use the gdTiled color for the fill. + +Example: + + # This has the same effect as the previous example + $myImage->rectangle(10,10,100,100,$black); + $myImage->fillToBorder(50,50,$black,$blue); + +=back + + + +=head2 Image Copying Commands + +Two methods are provided for copying a rectangular region from one +image to another. One method copies a region without resizing it. +The other allows you to stretch the region during the copy operation. + +With either of these methods it is important to know that the routines +will attempt to flesh out the destination image's color table to match +the colors that are being copied from the source. If the +destination's color table is already full, then the routines will +attempt to find the best match, with varying results. + +=over 4 + +=item B<$image-E<gt>copy($sourceImage,$dstX,$dstY,> + +B< $srcX,$srcY,$width,$height)> + +This is the simplest of the several copy operations, copying the +specified region from the source image to the destination image (the +one performing the method call). (srcX,srcY) specify the upper left +corner of a rectangle in the source image, and (width,height) give the +width and height of the region to copy. (dstX,dstY) control where in +the destination image to stamp the copy. You can use the same image +for both the source and the destination, but the source and +destination regions must not overlap or strange things will happen. + +Example: + + $myImage = new GD::Image(100,100); + ... various drawing stuff ... + $srcImage = new GD::Image(50,50); + ... more drawing stuff ... + # copy a 25x25 pixel region from $srcImage to + # the rectangle starting at (10,10) in $myImage + $myImage->copy($srcImage,10,10,0,0,25,25); + +=item B<$image-E<gt>clone()> + +Make a copy of the image and return it as a new object. The new image +will look identical. However, it may differ in the size of the color +palette and other nonessential details. + +Example: + + $myImage = new GD::Image(100,100); + ... various drawing stuff ... + $copy = $myImage->clone; + +=item B<$image-E<gt>copyMerge($sourceImage,$dstX,$dstY,> + +B< $srcX,$srcY,$width,$height,$percent)> + +This copies the indicated rectangle from the source image to the +destination image, merging the colors to the extent specified by +percent (an integer between 0 and 100). Specifying 100% has the same +effect as copy() -- replacing the destination pixels with the source +image. This is most useful for highlighting an area by merging in a +solid rectangle. + +Example: + + $myImage = new GD::Image(100,100); + ... various drawing stuff ... + $redImage = new GD::Image(50,50); + ... more drawing stuff ... + # copy a 25x25 pixel region from $srcImage to + # the rectangle starting at (10,10) in $myImage, merging 50% + $myImage->copyMerge($srcImage,10,10,0,0,25,25,50); + +=item B<$image-E<gt>copyMergeGray($sourceImage,$dstX,$dstY,> + +B< $srcX,$srcY,$width,$height,$percent)> + +This is identical to copyMerge() except that it preserves the hue of +the source by converting all the pixels of the destination rectangle +to grayscale before merging. + +=item B<$image-E<gt>copyResized($sourceImage,$dstX,$dstY,> + +B< $srcX,$srcY,$destW,$destH,$srcW,$srcH)> + +This method is similar to copy() but allows you to choose different +sizes for the source and destination rectangles. The source and +destination rectangle's are specified independently by (srcW,srcH) and +(destW,destH) respectively. copyResized() will stretch or shrink the +image to accommodate the size requirements. + +Example: + + $myImage = new GD::Image(100,100); + ... various drawing stuff ... + $srcImage = new GD::Image(50,50); + ... more drawing stuff ... + # copy a 25x25 pixel region from $srcImage to + # a larger rectangle starting at (10,10) in $myImage + $myImage->copyResized($srcImage,10,10,0,0,50,50,25,25); + +=item B<$image-E<gt>copyResampled($sourceImage,$dstX,$dstY,> + +B< $srcX,$srcY,$destW,$destH,$srcW,$srcH)> + +This method is similar to copyResized() but 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 method is identical to copyResized() when the destination +image is a palette image. + +=item B<$image-E<gt>copyRotated($sourceImage,$dstX,$dstY,> + +B< $srcX,$srcY,$width,$height,$angle)> + +Like copyResized() but the $angle argument specifies an arbitrary +amount to rotate the image clockwise (in degrees). In addition, $dstX +and $dstY species the B<center> of the destination image, and not the +top left corner. + +=item B<$image-E<gt>trueColorToPalette([$dither], [$colors])> + +This method converts a truecolor 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 colors as well as possible. This does not work as well as +might be hoped. It is usually best to simply produce a truecolor +output image instead, which guarantees the highest output quality. +Both the dithering (0/1, default=0) and maximum number of colors used +(<=256, default = gdMaxColors) can be specified. + +=back + +=head2 Image Transformation Commands + +Gd also provides some common image transformations: + +=over 4 + +=item B<$image = $sourceImage-E<gt>copyRotate90()> + +=item B<$image = $sourceImage-E<gt>copyRotate180()> + +=item B<$image = $sourceImage-E<gt>copyRotate270()> + +=item B<$image = $sourceImage-E<gt>copyFlipHorizontal()> + +=item B<$image = $sourceImage-E<gt>copyFlipVertical()> + +=item B<$image = $sourceImage-E<gt>copyTranspose()> + +=item B<$image = $sourceImage-E<gt>copyReverseTranspose()> + +These methods can be used to rotate, flip, or transpose an image. +The result of the method is a copy of the image. + +=item B<$image-E<gt>rotate180()> + +=item B<$image-E<gt>flipHorizontal()> + +=item B<$image-E<gt>flipVertical()> + +These methods are similar to the copy* versions, but instead +modify the image in place. + +=back + +=head2 Character and String Drawing + +GD allows you to draw characters and strings, either in normal +horizontal orientation or rotated 90 degrees. These routines use a +GD::Font object, described in more detail below. There are four +built-in monospaced fonts, available in the global variables +B<gdGiantFont>, B<gdLargeFont>, B<gdMediumBoldFont>, B<gdSmallFont> +and B<gdTinyFont>. + +In addition, you can use the load() method to load GD-formatted bitmap +font files at runtime. You can create these bitmap files from X11 +BDF-format files using the bdf2gd.pl script, which should have been +installed with GD (see the bdf_scripts directory if it wasn't). The +format happens to be identical to the old-style MSDOS bitmap ".fnt" +files, so you can use one of those directly if you happen to have one. + +For writing proportional scaleable fonts, GD offers the stringFT() +method, which allows you to load and render any TrueType font on your +system. + +=over 4 + +=item B<$image-E<gt>string($font,$x,$y,$string,$color)> + +This method draws a string starting at position (x,y) in the specified +font and color. Your choices of fonts are gdSmallFont, gdMediumBoldFont, +gdTinyFont, gdLargeFont and gdGiantFont. + +Example: + + $myImage->string(gdSmallFont,2,10,"Peachy Keen",$peach); + +=item B<$image-E<gt>stringUp($font,$x,$y,$string,$color)> + +Just like the previous call, but draws the text rotated +counterclockwise 90 degrees. + +=item B<$image-E<gt>char($font,$x,$y,$char,$color)> + +=item B<$image-E<gt>charUp($font,$x,$y,$char,$color)> + +These methods draw single characters at position (x,y) in the +specified font and color. They're carry-overs from the C interface, +where there is a distinction between characters and strings. Perl is +insensible to such subtle distinctions. + +=item $font = B<GD::Font-E<gt>load($fontfilepath)> + +This method dynamically loads a font file, returning a font that you +can use in subsequent calls to drawing methods. For example: + + my $courier = GD::Font->load('./courierR12.fnt') or die "Can't load font"; + $image->string($courier,2,10,"Peachy Keen",$peach); + +Font files must be in GD binary format, as described above. + +=item B<@bounds = $image-E<gt>stringFT($fgcolor,$fontname,$ptsize,$angle,$x,$y,$string)> + +=item B<@bounds = GD::Image-E<gt>stringFT($fgcolor,$fontname,$ptsize,$angle,$x,$y,$string)> + +=item B<@bounds = $image-E<gt>stringFT($fgcolor,$fontname,$ptsize,$angle,$x,$y,$string,\%options)> + +This method uses TrueType to draw a scaled, antialiased string using +the TrueType vector font of your choice. It requires that libgd to +have been compiled with TrueType support, and for the appropriate +TrueType font to be installed on your system. + +The arguments are as follows: + + fgcolor Color index to draw the string in + fontname A path to the TrueType (.ttf) font file or a font pattern. + ptsize The desired point size (may be fractional) + angle The rotation angle, in radians (positive values rotate counter clockwise) + x,y X and Y coordinates to start drawing the string + string The string itself + +If successful, the method returns an eight-element list giving the +boundaries of the rendered string: + + @bounds[0,1] Lower left corner (x,y) + @bounds[2,3] Lower right corner (x,y) + @bounds[4,5] Upper right corner (x,y) + @bounds[6,7] Upper left corner (x,y) + +In case of an error (such as the font not being available, or FT +support not being available), the method returns an empty list and +sets $@ to the error message. + +The string may contain UTF-8 sequences like: "À" + +You may also call this method from the GD::Image class name, in which +case it doesn't do any actual drawing, but returns the bounding box +using an inexpensive operation. You can use this to perform layout +operations prior to drawing. + +Using a negative color index will disable antialiasing, as described +in the libgd manual page at +L<http://www.boutell.com/gd/manual2.0.9.html#gdImageStringFT>. + +An optional 8th argument allows you to pass a hashref of options to +stringFT(). Several hashkeys are recognized: B<linespacing>, +B<charmap>, B<resolution>, and B<kerning>. + +The value of B<linespacing> is supposed to be a multiple of the +character height, so setting linespacing to 2.0 will result in +double-spaced lines of text. However the current version of libgd +(2.0.12) does not do this. Instead the linespacing seems to be double +what is provided in this argument. So use a spacing of 0.5 to get +separation of exactly one line of text. In practice, a spacing of 0.6 +seems to give nice results. Another thing to watch out for is that +successive lines of text should be separated by the "\r\n" characters, +not just "\n". + +The value of B<charmap> is one of "Unicode", "Shift_JIS" and "Big5". +The interaction between Perl, Unicode and libgd is not clear to me, +and you should experiment a bit if you want to use this feature. + +The value of B<resolution> is the vertical and horizontal resolution, +in DPI, in the format "hdpi,vdpi". If present, the resolution will be +passed to the Freetype rendering engine as a hint to improve the +appearance of the rendered font. + +The value of B<kerning> is a flag. Set it to false to turn off the +default kerning of text. + +Example: + + $gd->stringFT($black,'/dosc/windows/Fonts/pala.ttf',40,0,20,90, + "hi there\r\nbye now", + {linespacing=>0.6, + charmap => 'Unicode', + }); + +If GD was compiled with fontconfig support, and the fontconfig library +is available on your system, then you can use a font name pattern +instead of a path. Patterns are described in L<fontconfig> and will +look something like this "Times:italic". For backward +compatibility, this feature is disabled by default. You must enable +it by calling useFontConfig(1) prior to the stringFT() call. + + $image->useFontConfig(1); + +For backward compatibility with older versions of the FreeType +library, the alias stringTTF() is also recognized. + +=item B<$hasfontconfig = $image-E<gt>useFontConfig($flag)> + +Call useFontConfig() with a value of 1 in order to enable support for +fontconfig font patterns (see stringFT). Regardless of the value of +$flag, this method will return a true value if the fontconfig library +is present, or false otherwise. + +=item B<$result = $image->stringFTCircle($cx,$cy,$radius,$textRadius,$fillPortion,$font,$points,$top,$bottom,$fgcolor)> + +This draws text in a circle. Currently (libgd 2.0.33) this function +does not work for me, but the interface is provided for completeness. +The call signature is somewhat complex. Here is an excerpt from the +libgd manual page: + +Draws the text strings specified by top and bottom on the image, curved along +the edge of a circle of radius radius, with its center at cx and +cy. top is written clockwise along the top; bottom is written +counterclockwise along the bottom. textRadius determines the "height" +of each character; if textRadius is 1/2 of radius, characters extend +halfway from the edge to the center. fillPortion varies from 0 to 1.0, +with useful values from about 0.4 to 0.9, and determines how much of +the 180 degrees of arc assigned to each section of text is actually +occupied by text; 0.9 looks better than 1.0 which is rather +crowded. font is a freetype font; see gdImageStringFT. points is +passed to the freetype engine and has an effect on hinting; although +the size of the text is determined by radius, textRadius, and +fillPortion, you should pass a point size that "hints" appropriately +-- if you know the text will be large, pass a large point size such as +24.0 to get the best results. fgcolor can be any color, and may have +an alpha component, do blending, etc. + +Returns a true value on success. + +=back + +=head2 Alpha channels + +The alpha channel methods allow you to control the way drawings are +processed according to the alpha channel. When true color is turned +on, colors are encoded as four bytes, in which the last three bytes +are the RGB color values, and the first byte is the alpha channel. +Therefore the hexadecimal representation of a non transparent RGB +color will be: C=0x00(rr)(bb)(bb) + +When alpha blending is turned on, you can use the first byte of the +color to control the transparency, meaning that a rectangle painted +with color 0x00(rr)(bb)(bb) will be opaque, and another one painted +with 0x7f(rr)(gg)(bb) will be transparent. The Alpha value must be >= +0 and <= 0x7f. + +=over 4 + +=item B<$image-E<gt>alphaBlending($integer)> + +The alphaBlending() method allows for two different modes of drawing +on truecolor images. In blending mode, which is on by default (libgd +2.0.2 and above), the alpha channel component of the color supplied to +all drawing functions, such as C<setPixel>, determines how much of the +underlying color should be allowed to shine through. As a result, GD +automatically blends the existing color at that point with the drawing +color, and stores the result in the image. The resulting pixel is +opaque. In non-blending mode, the drawing color is copied literally +with its alpha channel information, replacing the destination +pixel. Blending mode is not available when drawing on palette images. + +Pass a value of 1 for blending mode, and 0 for non-blending mode. + +=item B<$image-E<gt>saveAlpha($saveAlpha)> + +By default, GD (libgd 2.0.2 and above) does not attempt to save full +alpha channel information (as opposed to single-color transparency) +when saving PNG images. (PNG is currently the only output format +supported by gd which can accommodate alpha channel information.) This +saves space in the output file. If you wish to create an image with +alpha channel information for use with tools that support it, call +C<saveAlpha(1)> to turn on saving of such information, and call +C<alphaBlending(0)> to turn off alpha blending within the library so +that alpha channel information is actually stored in the image rather +than being composited immediately at the time that drawing functions +are invoked. + +=back + + +=head2 Miscellaneous Image Methods + +These are various utility methods that are useful in some +circumstances. + +=over 4 + +=item B<$image-E<gt>interlaced([$flag])> + +This method sets or queries the image's interlaced setting. Interlace +produces a cool venetian blinds effect on certain viewers. Provide a +true parameter to set the interlace attribute. Provide undef to +disable it. Call the method without parameters to find out the +current setting. + +=item B<($width,$height) = $image-E<gt>getBounds()> + +This method will return a two-member list containing the width and +height of the image. You query but not change the size of the +image once it's created. + +=item B<$width = $image-E<gt>width> + +=item B<$height = $image-E<gt>height> + +Return the width and height of the image, respectively. + +=item B<$is_truecolor = $image-E<gt>isTrueColor()> + +This method will return a Boolean representing whether the image +is true color or not. + +=item B<$flag = $image1-E<gt>compare($image2)> + +Compare two images and return a bitmap describing the differences +found, if any. The return value must be logically ANDed with one or +more constants in order to determine the differences. The following +constants are available: + + GD_CMP_IMAGE The two images look different + GD_CMP_NUM_COLORS The two images have different numbers of colors + GD_CMP_COLOR The two images' palettes differ + GD_CMP_SIZE_X The two images differ in the horizontal dimension + GD_CMP_SIZE_Y The two images differ in the vertical dimension + GD_CMP_TRANSPARENT The two images have different transparency + GD_CMP_BACKGROUND The two images have different background colors + GD_CMP_INTERLACE The two images differ in their interlace + GD_CMP_TRUECOLOR The two images are not both true color + +The most important of these is GD_CMP_IMAGE, which will tell you +whether the two images will look different, ignoring differences in the +order of colors in the color palette and other invisible changes. The +constants are not imported by default, but must be imported individually +or by importing the :cmp tag. Example: + + use GD qw(:DEFAULT :cmp); + # get $image1 from somewhere + # get $image2 from somewhere + if ($image1->compare($image2) & GD_CMP_IMAGE) { + warn "images differ!"; + } + +=item B<$image-E<gt>clip($x1,$y1,$x2,$y2)> + +=item B<($x1,$y1,$x2,$y2) = $image-E<gt>clip> + +Set or get the clipping rectangle. When the clipping rectangle is +set, all drawing will be clipped to occur within this rectangle. The +clipping rectangle is initially set to be equal to the boundaries of +the whole image. Change it by calling clip() with the coordinates of +the new clipping rectangle. Calling clip() without any arguments will +return the current clipping rectangle. + +=item B<$flag = $image-E<gt>boundsSafe($x,$y)> + +The boundsSafe() method will return true if the point indicated by +($x,$y) is within the clipping rectangle, or false if it is not. If +the clipping rectangle has not been set, then it will return true if +the point lies within the image boundaries. + +=back + +=head2 Grouping Methods + +GD does not support grouping of objects, but GD::SVG does. In that +subclass, the following methods declare new groups of graphical +objects: + +=over 4 + +=item $image->startGroup([$id,\%style]) + +=item $image->endGroup() + +=item $group = $image->newGroup + +See L<GD::SVG> for information. + +=back + +=head1 Polygons + +A few primitive polygon creation and manipulation methods are +provided. They aren't part of the Gd library, but I thought they +might be handy to have around (they're borrowed from my qd.pl +Quickdraw library). Also see L<GD::Polyline>. + +=over 3 + +=item B<$poly = GD::Polygon-E<gt>new> + +Create an empty polygon with no vertices. + + $poly = new GD::Polygon; + +=item B<$poly-E<gt>addPt($x,$y)> + +Add point (x,y) to the polygon. + + $poly->addPt(0,0); + $poly->addPt(0,50); + $poly->addPt(25,25); + $myImage->fillPoly($poly,$blue); + +=item B<($x,$y) = $poly-E<gt>getPt($index)> + +Retrieve the point at the specified vertex. + + ($x,$y) = $poly->getPt(2); + +=item B<$poly-E<gt>setPt($index,$x,$y)> + +Change the value of an already existing vertex. It is an error to set +a vertex that isn't already defined. + + $poly->setPt(2,100,100); + +=item B<($x,$y) = $poly-E<gt>deletePt($index)> + +Delete the specified vertex, returning its value. + + ($x,$y) = $poly->deletePt(1); + + +=item B<$poly-E<gt>clear()> + +Delete all vertices, restoring the polygon to its initial empty state. + +=item B<$poly-E<gt>toPt($dx,$dy)> + +Draw from current vertex to a new vertex, using relative (dx,dy) +coordinates. If this is the first point, act like addPt(). + + $poly->addPt(0,0); + $poly->toPt(0,50); + $poly->toPt(25,-25); + $myImage->fillPoly($poly,$blue); + +=item B<$vertex_count = $poly-E<gt>length> + +Return the number of vertices in the polygon. + + $points = $poly->length; + +=item B<@vertices = $poly-E<gt>vertices> + +Return a list of all the vertices in the polygon object. Each member +of the list is a reference to an (x,y) array. + + @vertices = $poly->vertices; + foreach $v (@vertices) + print join(",",@$v),"\n"; + } + +=item B<@rect = $poly-E<gt>bounds> + +Return the smallest rectangle that completely encloses the polygon. +The return value is an array containing the (left,top,right,bottom) of +the rectangle. + + ($left,$top,$right,$bottom) = $poly->bounds; + +=item B<$poly-E<gt>offset($dx,$dy)> + +Offset all the vertices of the polygon by the specified horizontal +(dh) and vertical (dy) amounts. Positive numbers move the polygon +down and to the right. + + $poly->offset(10,30); + +=item B<$poly-E<gt>map($srcL,$srcT,$srcR,$srcB,$destL,$dstT,$dstR,$dstB)> + +Map the polygon from a source rectangle to an equivalent position in a +destination rectangle, moving it and resizing it as necessary. See +polys.pl for an example of how this works. Both the source and +destination rectangles are given in (left,top,right,bottom) +coordinates. For convenience, you can use the polygon's own bounding +box as the source rectangle. + + # Make the polygon really tall + $poly->map($poly->bounds,0,0,50,200); + +=item B<$poly-E<gt>scale($sx,$sy)> + +Scale each vertex of the polygon by the X and Y factors indicated by +sx and sy. For example scale(2,2) will make the polygon twice as +large. For best results, move the center of the polygon to position +(0,0) before you scale, then move it back to its previous position. + +=item B<$poly-E<gt>transform($sx,$rx,$sy,$ry,$tx,$ty)> + +Run each vertex of the polygon through a transformation matrix, where +sx and sy are the X and Y scaling factors, rx and ry are the X and Y +rotation factors, and tx and ty are X and Y offsets. See the Adobe +PostScript Reference, page 154 for a full explanation, or experiment. + +=back + +=head2 GD::Polyline + +Please see L<GD::Polyline> for information on creating open polygons +and splines. + +=head1 Font Utilities + +The libgd library (used by the Perl GD library) has built-in support +for about half a dozen fonts, which were converted from public-domain +X Windows fonts. For more fonts, compile libgd with TrueType support +and use the stringFT() call. + +If you wish to add more built-in fonts, the directory bdf_scripts +contains two contributed utilities that may help you convert X-Windows +BDF-format fonts into the format that libgd uses internally. 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! Please do not contact me for help with these +scripts: they are unsupported. + +Each of these fonts is available both as an imported global +(e.g. B<gdSmallFont>) and as a package method +(e.g. B<GD::Font-E<gt>Small>). + +=over 5 + +=item B<gdSmallFont> + +=item B<GD::Font-E<gt>Small> + +This is the basic small font, "borrowed" from a well known public +domain 6x12 font. + +=item B<gdLargeFont> + +=item B<GD::Font-E<gt>Large> + +This is the basic large font, "borrowed" from a well known public +domain 8x16 font. + +=item B<gdMediumBoldFont> + +=item B<GD::Font-E<gt>MediumBold> + +This is a bold font intermediate in size between the small and large +fonts, borrowed from a public domain 7x13 font; + +=item B<gdTinyFont> + +=item B<GD::Font-E<gt>Tiny> + +This is a tiny, almost unreadable font, 5x8 pixels wide. + +=item B<gdGiantFont> + +=item B<GD::Font-E<gt>Giant> + +This is a 9x15 bold font converted by Jan Pazdziora from a sans serif +X11 font. + +=item B<$font-E<gt>nchars> + +This returns the number of characters in the font. + + print "The large font contains ",gdLargeFont->nchars," characters\n"; + +=item B<$font-E<gt>offset> + +This returns the ASCII value of the first character in the font + +=item B<$width = $font-E<gt>width> + +=item B<$height = $font-E<gt>height> + +=item C<height> + +These return the width and height of the font. + + ($w,$h) = (gdLargeFont->width,gdLargeFont->height); + +=back + +=head1 Obtaining the C-language version of gd + +libgd, the C-language version of gd, can be obtained at URL +http://www.boutell.com/gd/. Directions for installing and using it +can be found at that site. Please do not contact me for help with +libgd. + +=head1 AUTHOR + +The GD.pm interface is copyright 1995-2007, Lincoln D. Stein. It is +distributed under GPL and the Artistic License 2.0. + +The latest versions of GD.pm are available at + + http://stein.cshl.org/WWW/software/GD + +=head1 SEE ALSO + +L<GD::Polyline>, +L<GD::SVG>, +L<GD::Simple>, +L<Image::Magick> + +=cut + +1; + +__END__ |