1GD(3)                 User Contributed Perl Documentation                GD(3)
2
3
4

NAME

6       GD.pm - Interface to Gd Graphics Library
7

SYNOPSIS

9           use GD;
10
11           # create a new image
12           $im = new GD::Image(100,100);
13
14           # allocate some colors
15           $white = $im->colorAllocate(255,255,255);
16           $black = $im->colorAllocate(0,0,0);
17           $red = $im->colorAllocate(255,0,0);
18           $blue = $im->colorAllocate(0,0,255);
19
20           # make the background transparent and interlaced
21           $im->transparent($white);
22           $im->interlaced('true');
23
24           # Put a black frame around the picture
25           $im->rectangle(0,0,99,99,$black);
26
27           # Draw a blue oval
28           $im->arc(50,50,95,75,0,360,$blue);
29
30           # And fill it with red
31           $im->fill(50,50,$red);
32
33           # make sure we are writing to a binary stream
34           binmode STDOUT;
35
36           # Convert the image to PNG and print it on standard output
37           print $im->png;
38

DESCRIPTION

40       GD.pm is a Perl interface to Thomas Boutell's gd graphics library
41       (version 2.01 or higher; see below). GD allows you to create color
42       drawings using a large number of graphics primitives, and emit the
43       drawings as PNG files.
44
45       GD defines the following four classes:
46
47       "GD::Image"
48            An image class, which holds the image data and accepts graphic
49            primitive method calls.
50
51       "GD::Font"
52            A font class, which holds static font information and used for
53            text rendering.
54
55       "GD::Polygon"
56            A simple polygon object, used for storing lists of vertices prior
57            to rendering a polygon into an image.
58
59       "GD::Simple"
60            A "simple" class that simplifies the GD::Image API and then adds a
61            set of object-oriented drawing methods using turtle graphics,
62            simplified font handling, ability to work in polar coordinates,
63            HSV color spaces, and human-readable color names like "lightblue".
64            Please see GD::Simple for a description of these methods.
65
66       A Simple Example:
67
68               #!/usr/bin/perl
69
70               use GD;
71
72               # create a new image
73               $im = new GD::Image(100,100);
74
75               # allocate some colors
76               $white = $im->colorAllocate(255,255,255);
77               $black = $im->colorAllocate(0,0,0);
78               $red = $im->colorAllocate(255,0,0);
79               $blue = $im->colorAllocate(0,0,255);
80
81               # make the background transparent and interlaced
82               $im->transparent($white);
83               $im->interlaced('true');
84
85               # Put a black frame around the picture
86               $im->rectangle(0,0,99,99,$black);
87
88               # Draw a blue oval
89               $im->arc(50,50,95,75,0,360,$blue);
90
91               # And fill it with red
92               $im->fill(50,50,$red);
93
94               # make sure we are writing to a binary stream
95               binmode STDOUT;
96
97               # Convert the image to PNG and print it on standard output
98               print $im->png;
99
100       Notes:
101
102       1. To create a new, empty image, send a new() message to GD::Image,
103       passing it the width and height of the image you want to create.  An
104       image object will be returned.  Other class methods allow you to
105       initialize an image from a preexisting JPG, PNG, GD, GD2 or XBM file.
106       2. Next you will ordinarily add colors to the image's color table.
107       colors are added using a colorAllocate() method call.  The three
108       parameters in each call are the red, green and blue (rgb) triples for
109       the desired color.  The method returns the index of that color in the
110       image's color table.  You should store these indexes for later use.
111       3. Now you can do some drawing!  The various graphics primitives are
112       described below.  In this example, we do some text drawing, create an
113       oval, and create and draw a polygon.
114       4. Polygons are created with a new() message to GD::Polygon.  You can
115       add points to the returned polygon one at a time using the addPt()
116       method. The polygon can then be passed to an image for rendering.
117       5. When you're done drawing, you can convert the image into PNG format
118       by sending it a png() message.  It will return a (potentially large)
119       scalar value containing the binary data for the image.  Ordinarily you
120       will print it out at this point or write it to a file.  To ensure
121       portability to platforms that differentiate between text and binary
122       files, be sure to call "binmode()" on the file you are writing the
123       image to.
124

Object Constructors: Creating Images

126       The following class methods allow you to create new GD::Image objects.
127
128       $image = GD::Image->new([$width,$height],[$truecolor])
129       $image = GD::Image->new(*FILEHANDLE)
130       $image = GD::Image->new($filename)
131       $image = GD::Image->new($data)
132           The new() method is the main constructor for the GD::Image class.
133           Called with two integer arguments, it creates a new blank image of
134           the specified width and height. For example:
135
136                   $myImage = new GD::Image(100,100) || die;
137
138           This will create an image that is 100 x 100 pixels wide.  If you
139           don't specify the dimensions, a default of 64 x 64 will be chosen.
140
141           The optional third argument, $truecolor, tells new() to create a
142           truecolor GD::Image object.  Truecolor images have 24 bits of color
143           data (eight bits each in the red, green and blue channels
144           respectively), allowing for precise photograph-quality color usage.
145           If not specified, the image will use an 8-bit palette for
146           compatibility with older versions of libgd.
147
148           Alternatively, you may create a GD::Image object based on an
149           existing image by providing an open filehandle, a filename, or the
150           image data itself.  The image formats automatically recognized and
151           accepted are: PNG, JPEG, XPM and GD2.  Other formats, including
152           WBMP, and GD version 1, cannot be recognized automatically at this
153           time.
154
155           If something goes wrong (e.g. insufficient memory), this call will
156           return undef.
157
158       $image = GD::Image->trueColor([0,1])
159           For backwards compatibility with scripts previous versions of GD,
160           new images created from scratch (width, height) are palette based
161           by default.  To change this default to create true color images
162           use:
163
164                   GD::Image->trueColor(1);
165
166           before creating new images.  To switch back to palette based by
167           default, use:
168
169                   GD::Image->trueColor(0);
170
171       $image = GD::Image->newPalette([$width,$height])
172       $image = GD::Image->newTrueColor([$width,$height])
173           The newPalette() and newTrueColor() methods can be used to
174           explicitly create an palette based or true color image regardless
175           of the current setting of trueColor().
176
177       $image = GD::Image->newFromPng($file, [$truecolor])
178       $image = GD::Image->newFromPngData($data, [$truecolor])
179           The newFromPng() method will create an image from a PNG file read
180           in through the provided filehandle or file path.  The filehandle
181           must previously have been opened on a valid PNG file or pipe.  If
182           successful, this call will return an initialized image which you
183           can then manipulate as you please.  If it fails, which usually
184           happens if the thing at the other end of the filehandle is not a
185           valid PNG file, the call returns undef.  Notice that the call
186           doesn't automatically close the filehandle for you.  But it does
187           call "binmode(FILEHANDLE)" for you, on platforms where this
188           matters.
189
190           You may use any of the following as the argument:
191
192             1) a simple filehandle, such as STDIN
193             2) a filehandle glob, such as *PNG
194             3) a reference to a glob, such as \*PNG
195             4) an IO::Handle object
196             5) the pathname of a file
197
198           In the latter case, newFromPng() will attempt to open the file for
199           you and read the PNG information from it.
200
201             Example1:
202
203             open (PNG,"barnswallow.png") || die;
204             $myImage = newFromPng GD::Image(\*PNG) || die;
205             close PNG;
206
207             Example2:
208             $myImage = newFromPng GD::Image('barnswallow.png');
209
210           To get information about the size and color usage of the
211           information, you can call the image query methods described below.
212           Images created by reading PNG images will be truecolor if the image
213           file itself is truecolor. To force the image to be palette-based,
214           pass a value of 0 in the optional $truecolor argument.
215
216           The newFromPngData() method will create a new GD::Image initialized
217           with the PNG format data contained in $data.
218
219       $image = GD::Image->newFromJpeg($file, [$truecolor])
220       $image = GD::Image->newFromJpegData($data, [$truecolor])
221           These methods will create an image from a JPEG file.  They work
222           just like newFromPng() and newFromPngData(), and will accept the
223           same filehandle and pathname arguments.
224
225           Images created by reading JPEG images will always be truecolor.  To
226           force the image to be palette-based, pass a value of 0 in the
227           optional $truecolor argument.
228
229       $image = GD::Image->newFromGif($file, [$truecolor])
230       $image = GD::Image->newFromGifData($data)
231           These methods will create an image from a GIF file.  They work just
232           like newFromPng() and newFromPngData(), and will accept the same
233           filehandle and pathname arguments.
234
235           Images created from GIFs are always 8-bit palette images. To
236           convert to truecolor, you must create a truecolor image and then
237           perform a copy.
238
239       $image = GD::Image->newFromXbm($file, [$truecolor])
240           This works in exactly the same way as "newFromPng", but reads the
241           contents of an X Bitmap (black & white) file:
242
243                   open (XBM,"coredump.xbm") || die;
244                   $myImage = newFromXbm GD::Image(\*XBM) || die;
245                   close XBM;
246
247           There is no newFromXbmData() function, because there is no
248           corresponding function in the gd library.
249
250       $image = GD::Image->newFromWBMP($file, [$truecolor])
251           This works in exactly the same way as "newFromPng", but reads the
252           contents of an Windows BMP Bitmap file:
253
254                   open (BMP,"coredump.bmp") || die;
255                   $myImage = newFromWBMP GD::Image(\*BMP) || die;
256                   close BMP;
257
258           There is no newFromWBMPData() function, because there is no
259           corresponding function in the gd library.
260
261       $image = GD::Image->newFromGd($file)
262       $image = GD::Image->newFromGdData($data)
263           These methods initialize a GD::Image from a Gd file, filehandle, or
264           data.  Gd is Tom Boutell's disk-based storage format, intended for
265           the rare case when you need to read and write the image to disk
266           quickly.  It's not intended for regular use, because, unlike PNG or
267           JPEG, no image compression is performed and these files can become
268           BIG.
269
270                   $myImage = newFromGd GD::Image("godzilla.gd") || die;
271                   close GDF;
272
273       $image = GD::Image->newFromGd2($file)
274       $image = GD::Image->newFromGd2Data($data)
275           This works in exactly the same way as "newFromGd()" and
276           newFromGdData, but use the new compressed GD2 image format.
277
278       $image = GD::Image->newFromGd2Part($file,srcX,srcY,width,height)
279           This class method allows you to read in just a portion of a GD2
280           image file.  In addition to a filehandle, it accepts the top-left
281           corner and dimensions (width,height) of the region of the image to
282           read.  For example:
283
284                   open (GDF,"godzilla.gd2") || die;
285                   $myImage = GD::Image->newFromGd2Part(\*GDF,10,20,100,100) || die;
286                   close GDF;
287
288           This reads a 100x100 square portion of the image starting from
289           position (10,20).
290
291       $image = GD::Image->newFromXpm($filename)
292           This creates a new GD::Image object starting from a filename.  This
293           is unlike the other newFrom() functions because it does not take a
294           filehandle.  This difference comes from an inconsistency in the
295           underlying gd library.
296
297                   $myImage = newFromXpm GD::Image('earth.xpm') || die;
298
299           This function is only available if libgd was compiled with XPM
300           support.
301
302           NOTE: The libgd library is unable to read certain XPM files,
303           returning an all-black image instead.
304
305       $bool = GD::supportsFileType($filename, $is_writing)
306           This returns a TRUE or FALSE value, if libgd supports reading or
307           when the 2nd argument is 1, if libgd supports writing the given
308           filetype, depending on the filename extension. Only with libgd
309           versions >= gd-2.1.1.
310
311           Assuming LibGD is compiled with support for these image types, the
312           following extensions are supported:
313
314               .gif
315               .gd, .gd2
316               .wbmp
317               .bmp
318               .xbm
319               .tga
320               .png
321               .jpg, .jpeg
322               .tiff, .tif
323               .webp
324               .xpm
325
326           Filenames are parsed case-insensitively.
327

GD::Image Methods

329       Once a GD::Image object is created, you can draw with it, copy it, and
330       merge two images.  When you are finished manipulating the object, you
331       can convert it into a standard image file format to output or save to a
332       file.
333
334   Image Data Output Methods
335       The following methods convert the internal drawing format into standard
336       output file formats.
337
338       $pngdata = $image->png([$compression_level])
339           This returns the image data in PNG format.  You can then print it,
340           pipe it to a display program, or write it to a file.  Example:
341
342                   $png_data = $myImage->png;
343                   open (DISPLAY,"| display -") || die;
344                   binmode DISPLAY;
345                   print DISPLAY $png_data;
346                   close DISPLAY;
347
348           Note the use of "binmode()".  This is crucial for portability to
349           DOSish platforms.
350
351           The optional $compression_level argument controls the amount of
352           compression to apply to the output PNG image.  Values range from
353           0-9, where 0 means no compression (largest files, highest quality)
354           and 9 means maximum compression (smallest files, worst quality).  A
355           compression level of -1 uses the default compression level selected
356           when zlib was compiled on your system, and is the same as calling
357           png() with no argument.  Be careful not to confuse this argument
358           with the jpeg() quality argument, which ranges from 0-100 and has
359           the opposite meaning from compression (higher numbers give higher
360           quality).
361
362       $gifdata = $image->gifanimbegin([$GlobalCM [, $Loops]])
363           For libgd version 2.0.33 and higher, this call begins an animated
364           GIF by returning the data that comprises animated gif image file
365           header.  After you call this method, call gifanimadd() one or more
366           times to add the frames of the image. Then call gifanimend(). Each
367           frame must be the same width and height.
368
369           A typical sequence will look like this:
370
371             my $gifdata = $image->gifanimbegin;
372             $gifdata   .= $image->gifanimadd;    # first frame
373             for (1..100) {
374                # make a frame of right size
375                my $frame  = GD::Image->new($image->getBounds);
376                add_frame_data($frame);              # add the data for this frame
377                $gifdata   .= $frame->gifanimadd;     # add frame
378             }
379             $gifdata   .= $image->gifanimend;   # finish the animated GIF
380             print $gifdata;                     # write animated gif to STDOUT
381
382           If you do not wish to store the data in memory, you can print it to
383           stdout or a file.
384
385           The image that you call gifanimbegin on is used to set the image
386           size, color resolution and color map.  If argument $GlobalCM is 1,
387           the image color map becomes the GIF89a global color map.  If $Loops
388           is given and >= 0, the NETSCAPE2.0 application extension is
389           created, with looping count.  Looping count 0 means forever.
390
391       $gifdata = $image->gifanimadd([$LocalCM [, $LeftOfs [, $TopOfs [,
392       $Delay [, $Disposal [, $previm]]]]]])
393           Returns the data that comprises one animated gif image frame.  You
394           can then print it, pipe it to a display program, or write it to a
395           file.  With $LeftOfs and $TopOfs you can place this frame in
396           different offset than (0,0) inside the image screen.  Delay between
397           the previous frame and this frame is in 1/100s units.  Disposal is
398           usually and by default 1.  Compression is activated by giving the
399           previous image as a parameter.  This function then compares the
400           images and only writes the changed pixels to the new frame in
401           animation.  The Disposal parameter for optimized animations must be
402           set to 1, also for the first frame.  $LeftOfs and $TopOfs
403           parameters are ignored for optimized frames.
404
405       $gifdata = $image->gifanimend()
406           Returns the data for end segment of animated gif file.  It always
407           returns string ';'.  This string must be printed to an animated gif
408           file after all image frames to properly terminate it according to
409           GIF file syntax.  Image object is not used at all in this method.
410
411       $jpegdata = $image->jpeg([$quality])
412           This returns the image data in JPEG format.  You can then print it,
413           pipe it to a display program, or write it to a file.  You may pass
414           an optional quality score to jpeg() in order to control the JPEG
415           quality.  This should be an integer between 0 and 100.  Higher
416           quality scores give larger files and better image quality.  If you
417           don't specify the quality, jpeg() will choose a good default.
418
419       $gifdata = $image->gif().
420           This returns the image data in GIF format.  You can then print it,
421           pipe it to a display program, or write it to a file.
422
423       $gddata = $image->gd
424           This returns the image data in GD format.  You can then print it,
425           pipe it to a display program, or write it to a file.  Example:
426
427                   binmode MYOUTFILE;
428                   print MYOUTFILE $myImage->gd;
429
430       $gd2data = $image->gd2
431           Same as gd(), except that it returns the data in compressed GD2
432           format.
433
434       $wbmpdata = $image->wbmp([$foreground])
435           This returns the image data in WBMP format, which is a black-and-
436           white image format.  Provide the index of the color to become the
437           foreground color.  All other pixels will be considered background.
438
439       $success = $image->_file($filename)
440           Writes an image to a file in the format indicated by the filename,
441           with libgd versions >= gd-2.1.1.
442
443           File type is determined by the extension of the file name.  See
444           "supportsFiletype" for an overview of the parsing.
445
446           For file types that require extra arguments, "_file" attempts to
447           use sane defaults:
448
449             C<gdImageGd2> chunk size = 0, compression is enabled.
450             C<gdImageJpeg>        quality = -1 (i.e. the reasonable default)
451             C<gdImageWBMP>        foreground is the darkest available color
452
453           Everything else is called with the two-argument function and so
454           will use the default values.
455
456           "_file" and the underlying libgd "gdImageFile" has some rudimentary
457           error detection and will return FALSE (0) if a detectable error
458           occurred.  However, the image loaders do not normally return their
459           error status so a result of TRUE (1) does **not** mean the file was
460           saved successfully.
461
462   Color Control
463       These methods allow you to control and manipulate the GD::Image color
464       table for palette, non-truecolor images.
465
466       $index = $image->colorAllocate(red,green,blue)
467           This allocates a color with the specified red, green and blue
468           components and returns its index in the color table, if specified.
469           The first color allocated in this way becomes the image's
470           background color.  (255,255,255) is white (all pixels on).  (0,0,0)
471           is black (all pixels off).  (255,0,0) is fully saturated red.
472           (127,127,127) is 50% gray.  You can find plenty of examples in
473           /usr/X11/lib/X11/rgb.txt.
474
475           If no colors are allocated, then this function returns -1.
476
477           Example:
478
479                   $black = $myImage->colorAllocate(0,0,0); #background color
480                   $white = $myImage->colorAllocate(255,255,255);
481                   $peachpuff = $myImage->colorAllocate(255,218,185);
482
483       $index = $image->colorAllocateAlpha(reg,green,blue,alpha)
484           This allocates a color with the specified red, green, and blue
485           components, plus the specified alpha channel.  The alpha value may
486           range from 0 (opaque) to 127 (transparent).  The "alphaBlending"
487           function changes the way this alpha channel affects the resulting
488           image.
489
490       $image->colorDeallocate(colorIndex)
491           This marks the color at the specified index as being ripe for
492           reallocation.  The next time colorAllocate is used, this entry will
493           be replaced.  You can call this method several times to deallocate
494           multiple colors.  There's no function result from this call.
495
496           Example:
497
498                   $myImage->colorDeallocate($peachpuff);
499                   $peachy = $myImage->colorAllocate(255,210,185);
500
501       $index = $image->colorClosest(red,green,blue)
502           This returns the index of the color closest in the color table to
503           the red green and blue components specified.  If no colors have yet
504           been allocated, then this call returns -1.
505
506           Example:
507
508                   $apricot = $myImage->colorClosest(255,200,180);
509
510       $index = $image->colorClosestAlpha(red,green,blue,alpha)
511           This returns the index of the color closest in the color table to
512           the red green blue and alpha components specified.  If no colors
513           have yet been allocated, then this call returns -1.
514
515           Example:
516
517                   $apricot = $myImage->colorClosestAlpha(255,200,180,0);
518
519       $index = $image->colorClosestHWB(red,green,blue)
520           This also attempts to return the color closest in the color table
521           to the red green and blue components specified. It uses a
522           Hue/White/Black color representation to make the selected color
523           more likely to match human perceptions of similar colors.
524
525           If no colors have yet been allocated, then this call returns -1.
526
527           Example:
528
529                   $mostred = $myImage->colorClosestHWB(255,0,0);
530
531       $index = $image->colorExact(red,green,blue)
532           This returns the index of a color that exactly matches the
533           specified red green and blue components.  If such a color is not in
534           the color table, this call returns -1.
535
536                   $rosey = $myImage->colorExact(255,100,80);
537                   warn "Everything's coming up roses.\n" if $rosey >= 0;
538
539       $index = $image->colorExactAlpha(red,green,blue,alpha)
540           This returns the index of a color that exactly matches the
541           specified red green blue and alpha components.  If such a color is
542           not in the color table, this call returns -1.
543
544                   $rosey = $myImage->colorExactAlpha(255,100,80,0);
545                   warn "Everything's coming up roses.\n" if $rosey >= 0;
546
547       $index = $image->colorResolve(red,green,blue)
548           This returns the index of a color that exactly matches the
549           specified red green and blue components.  If such a color is not in
550           the color table and there is room, then this method allocates the
551           color in the color table and returns its index.
552
553                   $rosey = $myImage->colorResolve(255,100,80);
554                   warn "Everything's coming up roses.\n" if $rosey >= 0;
555
556       $index = $image->colorResolveAlpha(red,green,blue,alpha)
557           This returns the index of a color that exactly matches the
558           specified red green blue and alpha components.  If such a color is
559           not in the color table and there is room, then this method
560           allocates the color in the color table and returns its index.
561
562                   $rosey = $myImage->colorResolveAlpha(255,100,80,0);
563                   warn "Everything's coming up roses.\n" if $rosey >= 0;
564
565       $colorsTotal = $image->colorsTotal object method
566           This returns the total number of colors allocated in the object.
567
568                   $maxColors = $myImage->colorsTotal;
569
570           In the case of a TrueColor image, this call will return undef.
571
572       $index = $image->getPixel(x,y) object method
573           This returns the color table index underneath the specified point.
574           It can be combined with rgb() to obtain the rgb color underneath
575           the pixel.
576
577           Example:
578
579                   $index = $myImage->getPixel(20,100);
580                   ($r,$g,$b) = $myImage->rgb($index);
581
582       ($red,$green,$blue) = $image->rgb($index)
583           This returns a list containing the red, green and blue components
584           of the specified color index.
585
586           Example:
587
588                   @RGB = $myImage->rgb($peachy);
589
590       ($alpha) = $image->alpha($index)
591           This returns an item containing the alpha component of the
592           specified color index.
593
594           Example:
595
596                   @RGB = $myImage->rgb($peachy);
597
598       $image->transparent($colorIndex)
599           This marks the color at the specified index as being transparent.
600           Portions of the image drawn in this color will be invisible.  This
601           is useful for creating paintbrushes of odd shapes, as well as for
602           making PNG backgrounds transparent for displaying on the Web.  Only
603           one color can be transparent at any time. To disable transparency,
604           specify -1 for the index.
605
606           If you call this method without any parameters, it will return the
607           current index of the transparent color, or -1 if none.
608
609           Example:
610
611                   open(PNG,"test.png");
612                   $im = newFromPng GD::Image(PNG);
613                   $white = $im->colorClosest(255,255,255); # find white
614                   $im->transparent($white);
615                   binmode STDOUT;
616                   print $im->png;
617
618   Special Colors
619       GD implements a number of special colors that can be used to achieve
620       special effects.  They are constants defined in the GD:: namespace, but
621       automatically exported into your namespace when the GD module is
622       loaded.
623
624       $image->setBrush($image)
625           You can draw lines and shapes using a brush pattern.  Brushes are
626           just palette, not TrueColor, images that you can create and
627           manipulate in the usual way. When you draw with them, their
628           contents are used for the color and shape of the lines.
629
630           To make a brushed line, you must create or load the brush first,
631           then assign it to the image using setBrush().  You can then draw in
632           that with that brush using the gdBrushed special color.  It's often
633           useful to set the background of the brush to transparent so that
634           the non-colored parts don't overwrite other parts of your image.
635
636           Example:
637
638                   # Create a brush at an angle
639                   $diagonal_brush = new GD::Image(5,5);
640                   $white = $diagonal_brush->colorAllocate(255,255,255);
641                   $black = $diagonal_brush->colorAllocate(0,0,0);
642                   $diagonal_brush->transparent($white);
643                   $diagonal_brush->line(0,4,4,0,$black); # NE diagonal
644
645                   # Set the brush
646                   $myImage->setBrush($diagonal_brush);
647
648                   # Draw a circle using the brush
649                   $myImage->arc(50,50,25,25,0,360,gdBrushed);
650
651       $image->setThickness($thickness)
652           Lines drawn with line(), rectangle(), arc(), and so forth are 1
653           pixel thick by default.  Call setThickness() to change the line
654           drawing width.
655
656       $image->setStyle(@colors)
657           Styled lines consist of an arbitrary series of repeated colors and
658           are useful for generating dotted and dashed lines.  To create a
659           styled line, use setStyle() to specify a repeating series of
660           colors.  It accepts an array consisting of one or more color
661           indexes.  Then draw using the gdStyled special color.  Another
662           special color, gdTransparent can be used to introduce holes in the
663           line, as the example shows.
664
665           Example:
666
667                   # Set a style consisting of 4 pixels of yellow,
668                   # 4 pixels of blue, and a 2 pixel gap
669                   $myImage->setStyle($yellow,$yellow,$yellow,$yellow,
670                                      $blue,$blue,$blue,$blue,
671                                      gdTransparent,gdTransparent);
672                   $myImage->arc(50,50,25,25,0,360,gdStyled);
673
674           To combine the "gdStyled" and "gdBrushed" behaviors, you can
675           specify "gdStyledBrushed".  In this case, a pixel from the current
676           brush pattern is rendered wherever the color specified in
677           setStyle() is neither gdTransparent nor 0.
678
679       gdTiled
680           Draw filled shapes and flood fills using a pattern.  The pattern is
681           just another image.  The image will be tiled multiple times in
682           order to fill the required space, creating wallpaper effects.  You
683           must call "setTile" in order to define the particular tile pattern
684           you'll use for drawing when you specify the gdTiled color.
685           details.
686
687       gdStyled
688           The gdStyled color is used for creating dashed and dotted lines.  A
689           styled line can contain any series of colors and is created using
690           the setStyled() command.
691
692       gdAntiAliased
693           The "gdAntiAliased" color is used for drawing lines with
694           antialiasing turned on.  Antialiasing will blend the jagged edges
695           of lines with the background, creating a smoother look.  The actual
696           color drawn is set with setAntiAliased().
697
698       $image->setAntiAliased($color)
699           "Antialiasing" is a process by which jagged edges associated with
700           line drawing can be reduced by blending the foreground color with
701           an appropriate percentage of the background, depending on how much
702           of the pixel in question is actually within the boundaries of the
703           line being drawn. All line-drawing methods, such as line() and
704           polygon, will draw antialiased lines if the special "color"
705           gdAntiAliased is used when calling them.
706
707           setAntiAliased() is used to specify the actual foreground color to
708           be used when drawing antialiased lines. You may set any color to be
709           the foreground, however as of libgd version 2.0.12 an alpha channel
710           component is not supported.
711
712           Antialiased lines can be drawn on both truecolor and palette-based
713           images. However, attempts to draw antialiased lines on highly
714           complex palette-based backgrounds may not give satisfactory
715           results, due to the limited number of colors available in the
716           palette. Antialiased line-drawing on simple backgrounds should work
717           well with palette-based images; otherwise create or fetch a
718           truecolor image instead. When using palette-based images, be sure
719           to allocate a broad spectrum of colors in order to have sufficient
720           colors for the antialiasing to use.
721
722       $image->setAntiAliasedDontBlend($color,[$flag])
723           Normally, when drawing lines with the special gdAntiAliased
724           "color," blending with the background to reduce jagged edges is the
725           desired behavior. However, when it is desired that lines not be
726           blended with one particular color when it is encountered in the
727           background, the setAntiAliasedDontBlend() method can be used to
728           indicate the special color that the foreground should stand out
729           more clearly against.
730
731           Once turned on, you can turn this feature off by calling
732           setAntiAliasedDontBlend() with a second argument of 0:
733
734             $image->setAntiAliasedDontBlend($color,0);
735
736   Drawing Commands
737       These methods allow you to draw lines, rectangles, and ellipses, as
738       well as to perform various special operations like flood-fill.
739
740       $image->setPixel($x,$y,$color)
741           This sets the pixel at (x,y) to the specified color index.  No
742           value is returned from this method.  The coordinate system starts
743           at the upper left at (0,0) and gets larger as you go down and to
744           the right.  You can use a real color, or one of the special colors
745           gdBrushed, gdStyled and gdStyledBrushed can be specified.
746
747           Example:
748
749                   # This assumes $peach already allocated
750                   $myImage->setPixel(50,50,$peach);
751
752       $image->line($x1,$y1,$x2,$y2,$color)
753           This draws a line from (x1,y1) to (x2,y2) of the specified color.
754           You can use a real color, or one of the special colors gdBrushed,
755           gdStyled and gdStyledBrushed.
756
757           Example:
758
759                   # Draw a diagonal line using the currently defined
760                   # paintbrush pattern.
761                   $myImage->line(0,0,150,150,gdBrushed);
762
763       $image->dashedLine($x1,$y1,$x2,$y2,$color)
764           DEPRECATED: The libgd library provides this method solely for
765           backward compatibility with libgd version 1.0, and there have been
766           reports that it no longer works as expected. Please use the
767           setStyle() and gdStyled methods as described below.
768
769           This draws a dashed line from (x1,y1) to (x2,y2) in the specified
770           color.  A more powerful way to generate arbitrary dashed and dotted
771           lines is to use the setStyle() method described below and to draw
772           with the special color gdStyled.
773
774           Example:
775
776                   $myImage->dashedLine(0,0,150,150,$blue);
777
778       $image->rectangle($x1,$y1,$x2,$y2,$color)
779           This draws a rectangle with the specified color.  (x1,y1) and
780           (x2,y2) are the upper left and lower right corners respectively.
781           Both real color indexes and the special colors gdBrushed, gdStyled
782           and gdStyledBrushed are accepted.
783
784           Example:
785
786                   $myImage->rectangle(10,10,100,100,$rose);
787
788       $image->filledRectangle($x1,$y1,$x2,$y2,$color) =item
789       $image->setTile($otherimage)
790           This draws a rectangle filled with the specified color.  You can
791           use a real color, or the special fill color gdTiled to fill the
792           polygon with a pattern.
793
794           Example:
795
796                   # read in a fill pattern and set it
797                   $tile = newFromPng GD::Image('happyface.png');
798                   $myImage->setTile($tile);
799
800                   # draw the rectangle, filling it with the pattern
801                   $myImage->filledRectangle(10,10,150,200,gdTiled);
802
803       $image->openPolygon($polygon,$color)
804           This draws a polygon with the specified color.  The polygon must be
805           created first (see below).  The polygon must have at least three
806           vertices.  If the last vertex doesn't close the polygon, the method
807           will close it for you.  Both real color indexes and the special
808           colors gdBrushed, gdStyled and gdStyledBrushed can be specified.
809
810           Example:
811
812                   $poly = new GD::Polygon;
813                   $poly->addPt(50,0);
814                   $poly->addPt(99,99);
815                   $poly->addPt(0,99);
816                   $myImage->openPolygon($poly,$blue);
817
818       $image->unclosedPolygon($polygon,$color)
819           This draws a sequence of connected lines with the specified color,
820           without connecting the first and last point to a closed polygon.
821           The polygon must be created first (see below).  The polygon must
822           have at least three vertices.  Both real color indexes and the
823           special colors gdBrushed, gdStyled and gdStyledBrushed can be
824           specified.
825
826           You need libgd 2.0.33 or higher to use this feature.
827
828           Example:
829
830                   $poly = new GD::Polygon;
831                   $poly->addPt(50,0);
832                   $poly->addPt(99,99);
833                   $poly->addPt(0,99);
834                   $myImage->unclosedPolygon($poly,$blue);
835
836       $image->filledPolygon($poly,$color)
837           This draws a polygon filled with the specified color.  You can use
838           a real color, or the special fill color gdTiled to fill the polygon
839           with a pattern.
840
841           Example:
842
843                   # make a polygon
844                   $poly = new GD::Polygon;
845                   $poly->addPt(50,0);
846                   $poly->addPt(99,99);
847                   $poly->addPt(0,99);
848
849                   # draw the polygon, filling it with a color
850                   $myImage->filledPolygon($poly,$peachpuff);
851
852       $image->ellipse($cx,$cy,$width,$height,$color)
853       $image->filledEllipse($cx,$cy,$width,$height,$color)
854           These methods() draw ellipses. ($cx,$cy) is the center of the arc,
855           and ($width,$height) specify the ellipse width and height,
856           respectively.  filledEllipse() is like Ellipse() except that the
857           former produces filled versions of the ellipse.
858
859       $image->arc($cx,$cy,$width,$height,$start,$end,$color)
860           This draws arcs and ellipses.  (cx,cy) are the center of the arc,
861           and (width,height) specify the width and height, respectively.  The
862           portion of the ellipse covered by the arc are controlled by start
863           and end, both of which are given in degrees from 0 to 360.  Zero is
864           at the right end of the ellipse, and angles increase clockwise.  To
865           specify a complete ellipse, use 0 and 360 as the starting and
866           ending angles.  To draw a circle, use the same value for width and
867           height.
868
869           You can specify a normal color or one of the special colors
870           gdBrushed, gdStyled, or gdStyledBrushed.
871
872           Example:
873
874                   # draw a semicircle centered at 100,100
875                   $myImage->arc(100,100,50,50,0,180,$blue);
876
877       $image->filledArc($cx,$cy,$width,$height,$start,$end,$color
878       [,$arc_style])
879           This method is like arc() except that it colors in the pie wedge
880           with the selected color.  $arc_style is optional.  If present it is
881           a bitwise OR of the following constants:
882
883             gdArc           connect start & end points of arc with a rounded edge
884             gdChord         connect start & end points of arc with a straight line
885             gdPie           synonym for gdChord
886             gdNoFill        outline the arc or chord
887             gdEdged         connect beginning and ending of the arc to the center
888
889           gdArc and gdChord are mutually exclusive.  gdChord just connects
890           the starting and ending angles with a straight line, while gdArc
891           produces a rounded edge. gdPie is a synonym for gdArc. gdNoFill
892           indicates that the arc or chord should be outlined, not filled.
893           gdEdged, used together with gdNoFill, indicates that the beginning
894           and ending angles should be connected to the center; this is a good
895           way to outline (rather than fill) a "pie slice."
896
897           Example:
898
899             $image->filledArc(100,100,50,50,0,90,$blue,gdEdged|gdNoFill);
900
901       $image->fill($x,$y,$color)
902           This method flood-fills regions with the specified color.  The
903           color will spread through the image, starting at point (x,y), until
904           it is stopped by a pixel of a different color from the starting
905           pixel (this is similar to the "paintbucket" in many popular drawing
906           toys).  You can specify a normal color, or the special color
907           gdTiled, to flood-fill with patterns.
908
909           Example:
910
911                   # Draw a rectangle, and then make its interior blue
912                   $myImage->rectangle(10,10,100,100,$black);
913                   $myImage->fill(50,50,$blue);
914
915       $image->fillToBorder($x,$y,$bordercolor,$color)
916           Like "fill", this method flood-fills regions with the specified
917           color, starting at position (x,y).  However, instead of stopping
918           when it hits a pixel of a different color than the starting pixel,
919           flooding will only stop when it hits the color specified by
920           bordercolor.  You must specify a normal indexed color for the
921           bordercolor.  However, you are free to use the gdTiled color for
922           the fill.
923
924           Example:
925
926                   # This has the same effect as the previous example
927                   $myImage->rectangle(10,10,100,100,$black);
928                   $myImage->fillToBorder(50,50,$black,$blue);
929
930   Image Copying Commands
931       Two methods are provided for copying a rectangular region from one
932       image to another.  One method copies a region without resizing it.  The
933       other allows you to stretch the region during the copy operation.
934
935       With either of these methods it is important to know that the routines
936       will attempt to flesh out the destination image's color table to match
937       the colors that are being copied from the source.  If the destination's
938       color table is already full, then the routines will attempt to find the
939       best match, with varying results.
940
941       $image->copy($sourceImage,$dstX,$dstY,$srcX,$srcY,$width,$height)
942           This is the simplest of the several copy operations, copying the
943           specified region from the source image to the destination image
944           (the one performing the method call).  (srcX,srcY) specify the
945           upper left corner of a rectangle in the source image, and
946           (width,height) give the width and height of the region to copy.
947           (dstX,dstY) control where in the destination image to stamp the
948           copy.  You can use the same image for both the source and the
949           destination, but the source and destination regions must not
950           overlap or strange things will happen.
951
952           Example:
953
954                   $myImage = new GD::Image(100,100);
955                   ... various drawing stuff ...
956                   $srcImage = new GD::Image(50,50);
957                   ... more drawing stuff ...
958                   # copy a 25x25 pixel region from $srcImage to
959                   # the rectangle starting at (10,10) in $myImage
960                   $myImage->copy($srcImage,10,10,0,0,25,25);
961
962       $image->clone()
963           Make a copy of the image and return it as a new object.  The new
964           image will look identical.  However, it may differ in the size of
965           the color palette and other nonessential details.
966
967           Example:
968
969                   $myImage = new GD::Image(100,100);
970                   ... various drawing stuff ...
971                   $copy = $myImage->clone;
972
973       $image->copyMerge($sourceImage,$dstX,$dstY,
974                               $srcX,$srcY,$width,$height,$percent)
975
976           This copies the indicated rectangle from the source image to the
977           destination image, merging the colors to the extent specified by
978           percent (an integer between 0 and 100).  Specifying 100% has the
979           same effect as copy() -- replacing the destination pixels with the
980           source image.  This is most useful for highlighting an area by
981           merging in a solid rectangle.
982
983           Example:
984
985                   $myImage = new GD::Image(100,100);
986                   ... various drawing stuff ...
987                   $redImage = new GD::Image(50,50);
988                   ... more drawing stuff ...
989                   # copy a 25x25 pixel region from $srcImage to
990                   # the rectangle starting at (10,10) in $myImage, merging 50%
991                   $myImage->copyMerge($srcImage,10,10,0,0,25,25,50);
992
993       $image->copyMergeGray($sourceImage,$dstX,$dstY,
994                               $srcX,$srcY,$width,$height,$percent)
995
996           This is identical to copyMerge() except that it preserves the hue
997           of the source by converting all the pixels of the destination
998           rectangle to grayscale before merging.
999
1000       $image->copyResized($sourceImage,$dstX,$dstY,
1001                               $srcX,$srcY,$destW,$destH,$srcW,$srcH)
1002
1003           This method is similar to copy() but allows you to choose different
1004           sizes for the source and destination rectangles.  The source and
1005           destination rectangle's are specified independently by (srcW,srcH)
1006           and (destW,destH) respectively.  copyResized() will stretch or
1007           shrink the image to accommodate the size requirements.
1008
1009           Example:
1010
1011                   $myImage = new GD::Image(100,100);
1012                   ... various drawing stuff ...
1013                   $srcImage = new GD::Image(50,50);
1014                   ... more drawing stuff ...
1015                   # copy a 25x25 pixel region from $srcImage to
1016                   # a larger rectangle starting at (10,10) in $myImage
1017                   $myImage->copyResized($srcImage,10,10,0,0,50,50,25,25);
1018
1019       $image->copyResampled($sourceImage,$dstX,$dstY,
1020                               $srcX,$srcY,$destW,$destH,$srcW,$srcH)
1021
1022           This method is similar to copyResized() but provides "smooth"
1023           copying from a large image to a smaller one, using a weighted
1024           average of the pixels of the source area rather than selecting one
1025           representative pixel. This method is identical to copyResized()
1026           when the destination image is a palette image.
1027
1028       $image->copyRotated($sourceImage,$dstX,$dstY,
1029                               $srcX,$srcY,$width,$height,$angle)
1030
1031           Like copyResized() but the $angle argument specifies an arbitrary
1032           amount to rotate the image clockwise (in degrees).  In addition,
1033           $dstX and $dstY species the center of the destination image, and
1034           not the top left corner.
1035
1036       $image->trueColorToPalette([$dither], [$colors])
1037           This method converts a truecolor image to a palette image. The code
1038           for this function was originally drawn from the Independent JPEG
1039           Group library code, which is excellent. The code has been modified
1040           to preserve as much alpha channel information as possible in the
1041           resulting palette, in addition to preserving colors as well as
1042           possible. This does not work as well as might be hoped. It is
1043           usually best to simply produce a truecolor output image instead,
1044           which guarantees the highest output quality.  Both the dithering
1045           (0/1, default=0) and maximum number of colors used (<=256, default
1046           = gdMaxColors) can be specified.
1047
1048       $image = $sourceImage->createPaletteFromTrueColor([$dither], [$colors])
1049           Creates a new palette image from a truecolor image. Same as above,
1050           but returns a new image.
1051
1052           Don't use these function -- write real truecolor PNGs and JPEGs.
1053           The disk space gain of conversion to palette is not great (for
1054           small images it can be negative) and the quality loss is ugly.
1055
1056       $error = $image->colorMatch($otherimage)
1057           Bring the palette colors in $otherimage to be closer to truecolor
1058           $image.  A negative return value is a failure.
1059
1060             -1 image must be True Color
1061             -2 otherimage must be indexed
1062             -3 the images are meant to be the same dimensions
1063             -4 At least 1 color in otherimage must be allocated
1064
1065           This method is only available with libgd >= 2.1.0
1066
1067       $image = $sourceImage->neuQuant($maxcolor=256,$samplefactor=5)
1068           Creates a new palette image from a truecolor image.
1069
1070           samplefactor   The quantization precision between 1 (highest
1071           quality) and 10 (fastest).
1072           maxcolor  The number of desired palette entries.
1073
1074           This is the same as createPaletteFromTrueColor with the
1075           quantization method GD_QUANT_NEUQUANT. This does not support
1076           dithering.  This method is only available with libgd >= 2.1.0
1077
1078   Image Transformation Commands
1079       Gd provides these simple image transformations, non-interpolated.
1080
1081       $image = $sourceImage->copyRotate90()
1082       $image = $sourceImage->copyRotate180()
1083       $image = $sourceImage->copyRotate270()
1084       $image = $sourceImage->copyFlipHorizontal()
1085       $image = $sourceImage->copyFlipVertical()
1086       $image = $sourceImage->copyTranspose()
1087       $image = $sourceImage->copyReverseTranspose()
1088           These methods can be used to rotate, flip, or transpose an image.
1089           The result of the method is a copy of the image.
1090
1091       $image->rotate180()
1092       $image->flipHorizontal()
1093       $image->flipVertical()
1094           These methods are similar to the copy* versions, but instead modify
1095           the image in place.
1096
1097   Image Interpolation Methods
1098       Since libgd 2.1.0 there are better transformation methods, with these
1099       interpolation methods:
1100
1101         GD_BELL                - Bell
1102         GD_BESSEL              - Bessel
1103         GD_BILINEAR_FIXED      - fixed point bilinear
1104         GD_BICUBIC             - Bicubic
1105         GD_BICUBIC_FIXED       - fixed point bicubic integer
1106         GD_BLACKMAN            - Blackman
1107         GD_BOX                 - Box
1108         GD_BSPLINE             - BSpline
1109         GD_CATMULLROM          - Catmullrom
1110         GD_GAUSSIAN            - Gaussian
1111         GD_GENERALIZED_CUBIC   - Generalized cubic
1112         GD_HERMITE             - Hermite
1113         GD_HAMMING             - Hamming
1114         GD_HANNING             - Hannig
1115         GD_MITCHELL            - Mitchell
1116         GD_NEAREST_NEIGHBOUR   - Nearest neighbour interpolation
1117         GD_POWER               - Power
1118         GD_QUADRATIC           - Quadratic
1119         GD_SINC                - Sinc
1120         GD_TRIANGLE            - Triangle
1121         GD_WEIGHTED4           - 4 pixels weighted bilinear interpolation
1122         GD_LINEAR              - bilinear interpolation
1123
1124       $image->interpolationMethod( [$method] )
1125           Gets or sets the interpolation methods for all subsequent
1126           interpolations.  See above for the valid values.  Only available
1127           since libgd 2.2.0
1128
1129       $image->copyScaleInterpolated( width, height )
1130           Returns a copy, using interpolation.
1131
1132       $image->copyRotateInterpolated( angle, bgcolor )
1133           Returns a copy, using interpolation.
1134
1135   Image Filter Commands
1136       Gd also provides some common image filters, they modify the image in
1137       place and return TRUE if modified or FALSE if not.  Most of them need
1138       libgd >= 2.1.0, with older versions those functions are undefined.
1139
1140       $ok = $image->scatter($sub, $plus)
1141           if $sub and $plus are 0, nothing is changed, TRUE is returned.  if
1142           $sub >= $plus, nothing is changed, FALSE is returned.  else random
1143           pixels are changed.
1144
1145       $ok = $image->scatterColor($sub, $plus, @colors)
1146           Similar to scatter, but using the given array of colors, i.e.
1147           palette indices.
1148
1149       $ok = $image->pixelate($blocksize, $mode)
1150           if $blocksize <= 0, nothing is changed, FALSE is returned.  if
1151           $blocksize == 1, nothing is changed, TRUE is returned.  else the
1152           following modes are observed:
1153             GD_PIXELATE_UPPERLEFT
1154             GD_PIXELATE_AVERAGE
1155
1156       $ok = $image->negate()
1157       $ok = $image->grayscale()
1158       $ok = $image->brightness($add)
1159           $add: -255..255
1160
1161       $ok = $image->contrast($contrast)
1162           $contrast: a double value. The contrast adjustment value. Negative
1163           values increase, positive values decrease the contrast. The larger
1164           the absolute value, the stronger the effect.
1165
1166       $ok = $image->color($red,$green,$blue,$alpha)
1167           Change channel values of an image.
1168
1169             $red   - The value to add to the red channel of all pixels.
1170             $green - The value to add to the green channel of all pixels.
1171             $blue  - The value to add to the blue channel of all pixels.
1172             $alpha - The value to add to the alpha channel of all pixels.
1173
1174       $ok = $image->selectiveBlur()
1175       $ok = $image->edgeDetectQuick()
1176       $ok = $image->gaussianBlur()
1177       $ok = $image->emboss()
1178       $ok = $image->meanRemoval()
1179       $ok = $image->smooth($weight)
1180       $image = $sourceImage->copyGaussianBlurred($radius, $sigma)
1181           $radius: int, the blur radius (*not* diameter--range is 2*radius +
1182           1) a radius, not a diameter so a radius of 2 (for example) will
1183           blur across a region 5 pixels across (2 to the center, 1 for the
1184           center itself and another 2 to the other edge).
1185
1186           $sigma: the sigma value or a value <= 0.0 to use the computed
1187           default.  represents the "fatness" of the curve (lower == fatter).
1188
1189           The result is always truecolor.
1190
1191   Character and String Drawing
1192       GD allows you to draw characters and strings, either in normal
1193       horizontal orientation or rotated 90 degrees.  These routines use a
1194       GD::Font object, described in more detail below.  There are four built-
1195       in monospaced fonts, available in the global variables gdGiantFont,
1196       gdLargeFont, gdMediumBoldFont, gdSmallFont and gdTinyFont.
1197
1198       In addition, you can use the load() method to load GD-formatted bitmap
1199       font files at runtime. You can create these bitmap files from X11 BDF-
1200       format files using the bdf2gd.pl script, which should have been
1201       installed with GD (see the bdf_scripts directory if it wasn't).  The
1202       format happens to be identical to the old-style MSDOS bitmap ".fnt"
1203       files, so you can use one of those directly if you happen to have one.
1204
1205       For writing proportional scalable fonts, GD offers the stringFT()
1206       method, which allows you to load and render any TrueType font on your
1207       system.
1208
1209       $image->string($font,$x,$y,$string,$color)
1210           This method draws a string starting at position (x,y) in the
1211           specified font and color.  Your choices of fonts are gdSmallFont,
1212           gdMediumBoldFont, gdTinyFont, gdLargeFont and gdGiantFont.
1213
1214           Example:
1215
1216                   $myImage->string(gdSmallFont,2,10,"Peachy Keen",$peach);
1217
1218       $image->stringUp($font,$x,$y,$string,$color)
1219           Just like the previous call, but draws the text rotated
1220           counterclockwise 90 degrees.
1221
1222       $image->char($font,$x,$y,$char,$color)
1223       $image->charUp($font,$x,$y,$char,$color)
1224           These methods draw single characters at position (x,y) in the
1225           specified font and color.  They're carry-overs from the C
1226           interface, where there is a distinction between characters and
1227           strings.  Perl is insensible to such subtle distinctions.
1228
1229       $font = GD::Font->load($fontfilepath)
1230           This method dynamically loads a font file, returning a font that
1231           you can use in subsequent calls to drawing methods.  For example:
1232
1233              my $courier = GD::Font->load('./courierR12.fnt') or die "Can't load font";
1234              $image->string($courier,2,10,"Peachy Keen",$peach);
1235
1236           Font files must be in GD binary format, as described above.
1237
1238       @bounds =
1239       $image->stringFT($fgcolor,$fontname,$ptsize,$angle,$x,$y,$string)
1240       @bounds =
1241       GD::Image->stringFT($fgcolor,$fontname,$ptsize,$angle,$x,$y,$string)
1242       @bounds =
1243       $image->stringFT($fgcolor,$fontname,$ptsize,$angle,$x,$y,$string,\%options)
1244           This method uses TrueType to draw a scaled, antialiased string
1245           using the TrueType vector font of your choice.  It requires that
1246           libgd to have been compiled with TrueType support, and for the
1247           appropriate TrueType font to be installed on your system.
1248
1249           The arguments are as follows:
1250
1251             fgcolor    Color index to draw the string in
1252             fontname   A path to the TrueType (.ttf) font file or a font pattern.
1253             ptsize     The desired point size (may be fractional)
1254             angle      The rotation angle, in radians (positive values rotate counter clockwise)
1255             x,y        X and Y coordinates to start drawing the string
1256             string     The string itself
1257
1258           If successful, the method returns an eight-element list giving the
1259           boundaries of the rendered string:
1260
1261            @bounds[0,1]  Lower left corner (x,y)
1262            @bounds[2,3]  Lower right corner (x,y)
1263            @bounds[4,5]  Upper right corner (x,y)
1264            @bounds[6,7]  Upper left corner (x,y)
1265
1266           In case of an error (such as the font not being available, or FT
1267           support not being available), the method returns an empty list and
1268           sets $@ to the error message.
1269
1270           The fontname argument is the name of the font, which can be a full
1271           pathname to a .ttf file, or if not the paths in $ENV{GDFONTPATH}
1272           will be searched or if empty the libgd compiled DEFAULT_FONTPATH.
1273           The TrueType extensions .ttf, .pfa, .pfb or .dfont can be omitted.
1274
1275           The string may contain UTF-8 sequences like: "&#192;"
1276
1277           You may also call this method from the GD::Image class name, in
1278           which case it doesn't do any actual drawing, but returns the
1279           bounding box using an inexpensive operation.  You can use this to
1280           perform layout operations prior to drawing.
1281
1282           Using a negative color index will disable antialiasing, as
1283           described in the libgd manual page at
1284           <http://www.boutell.com/gd/manual2.0.9.html#gdImageStringFT>.
1285
1286           An optional 8th argument allows you to pass a hashref of options to
1287           stringFT().  Several hashkeys are recognized: linespacing, charmap,
1288           resolution, and kerning.
1289
1290           The value of linespacing is supposed to be a multiple of the
1291           character height, so setting linespacing to 2.0 will result in
1292           double-spaced lines of text.  However the current version of libgd
1293           (2.0.12) does not do this.  Instead the linespacing seems to be
1294           double what is provided in this argument.  So use a spacing of 0.5
1295           to get separation of exactly one line of text.  In practice, a
1296           spacing of 0.6 seems to give nice results.  Another thing to watch
1297           out for is that successive lines of text should be separated by the
1298           "\r\n" characters, not just "\n".
1299
1300           The value of charmap is one of "Unicode", "Shift_JIS" and "Big5".
1301           The interaction between Perl, Unicode and libgd is not clear to me,
1302           and you should experiment a bit if you want to use this feature.
1303
1304           The value of resolution is the vertical and horizontal resolution,
1305           in DPI, in the format "hdpi,vdpi".  If present, the resolution will
1306           be passed to the Freetype rendering engine as a hint to improve the
1307           appearance of the rendered font.
1308
1309           The value of kerning is a flag.  Set it to false to turn off the
1310           default kerning of text.
1311
1312           Example:
1313
1314            $gd->stringFT($black,'/c/windows/Fonts/pala.ttf',40,0,20,90,
1315                         "hi there\r\nbye now",
1316                         {linespacing=>0.6,
1317                          charmap  => 'Unicode',
1318                         });
1319
1320           If GD was compiled with fontconfig support, and the fontconfig
1321           library is available on your system, then you can use a font name
1322           pattern instead of a path.  Patterns are described in fontconfig
1323           and will look something like this "Times:italic".  For backward
1324           compatibility, this feature is disabled by default.  You must
1325           enable it by calling useFontConfig(1) prior to the stringFT() call.
1326
1327              $image->useFontConfig(1);
1328
1329           For backward compatibility with older versions of the FreeType
1330           library, the alias stringTTF() is also recognized.
1331
1332       $hasfontconfig = $image->useFontConfig($flag)
1333           Call useFontConfig() with a value of 1 in order to enable support
1334           for fontconfig font patterns (see stringFT).  Regardless of the
1335           value of $flag, this method will return a true value if the
1336           fontconfig library is present, or false otherwise.
1337
1338           This method can also be called as a class method of GD::Image;
1339
1340       $result =
1341       $image->stringFTCircle($cx,$cy,$radius,$textRadius,$fillPortion,$font,$points,$top,$bottom,$fgcolor)
1342           This draws text in a circle. Currently (libgd 2.0.33) this function
1343           does not work for me, but the interface is provided for
1344           completeness.  The call signature is somewhat complex.  Here is an
1345           excerpt from the libgd manual page:
1346
1347           Draws the text strings specified by top and bottom on the image,
1348           curved along the edge of a circle of radius radius, with its center
1349           at cx and cy. top is written clockwise along the top; bottom is
1350           written counterclockwise along the bottom. textRadius determines
1351           the "height" of each character; if textRadius is 1/2 of radius,
1352           characters extend halfway from the edge to the center. fillPortion
1353           varies from 0 to 1.0, with useful values from about 0.4 to 0.9, and
1354           determines how much of the 180 degrees of arc assigned to each
1355           section of text is actually occupied by text; 0.9 looks better than
1356           1.0 which is rather crowded. font is a freetype font; see
1357           gdImageStringFT. points is passed to the freetype engine and has an
1358           effect on hinting; although the size of the text is determined by
1359           radius, textRadius, and fillPortion, you should pass a point size
1360           that "hints" appropriately -- if you know the text will be large,
1361           pass a large point size such as 24.0 to get the best results.
1362           fgcolor can be any color, and may have an alpha component, do
1363           blending, etc.
1364
1365           Returns a true value on success.
1366
1367   Alpha channels
1368       The alpha channel methods allow you to control the way drawings are
1369       processed according to the alpha channel. When true color is turned on,
1370       colors are encoded as four bytes, in which the last three bytes are the
1371       RGB color values, and the first byte is the alpha channel.  Therefore
1372       the hexadecimal representation of a non transparent RGB color will be:
1373       C=0x00(rr)(bb)(bb)
1374
1375       When alpha blending is turned on, you can use the first byte of the
1376       color to control the transparency, meaning that a rectangle painted
1377       with color 0x00(rr)(bb)(bb) will be opaque, and another one painted
1378       with 0x7f(rr)(gg)(bb) will be transparent. The Alpha value must be >= 0
1379       and <= 0x7f.
1380
1381       $image->alphaBlending($integer)
1382           The alphaBlending() method allows for two different modes of
1383           drawing on truecolor images. In blending mode, which is on by
1384           default (libgd 2.0.2 and above), the alpha channel component of the
1385           color supplied to all drawing functions, such as "setPixel",
1386           determines how much of the underlying color should be allowed to
1387           shine through. As a result, GD automatically blends the existing
1388           color at that point with the drawing color, and stores the result
1389           in the image. The resulting pixel is opaque. In non-blending mode,
1390           the drawing color is copied literally with its alpha channel
1391           information, replacing the destination pixel. Blending mode is not
1392           available when drawing on palette images.
1393
1394           Pass a value of 1 for blending mode, and 0 for non-blending mode.
1395
1396       $image->saveAlpha($saveAlpha)
1397           By default, GD (libgd 2.0.2 and above) does not attempt to save
1398           full alpha channel information (as opposed to single-color
1399           transparency) when saving PNG images. (PNG is currently the only
1400           output format supported by gd which can accommodate alpha channel
1401           information.) This saves space in the output file. If you wish to
1402           create an image with alpha channel information for use with tools
1403           that support it, call saveAlpha(1) to turn on saving of such
1404           information, and call alphaBlending(0) to turn off alpha blending
1405           within the library so that alpha channel information is actually
1406           stored in the image rather than being composited immediately at the
1407           time that drawing functions are invoked.
1408
1409   Miscellaneous Image Methods
1410       These are various utility methods that are useful in some
1411       circumstances.
1412
1413       $image->interlaced([$flag])
1414           This method sets or queries the image's interlaced setting.
1415           Interlace produces a cool venetian blinds effect on certain
1416           viewers.  Provide a true parameter to set the interlace attribute.
1417           Provide undef to disable it.  Call the method without parameters to
1418           find out the current setting.
1419
1420       ($width,$height) = $image->getBounds()
1421           This method will return a two-member list containing the width and
1422           height of the image.  You query but not change the size of the
1423           image once it's created.
1424
1425       $width = $image->width
1426       $height = $image->height
1427           Return the width and height of the image, respectively.
1428
1429       $is_truecolor = $image->isTrueColor()
1430           This method will return a Boolean representing whether the image is
1431           true color or not.
1432
1433       $flag = $image1->compare($image2)
1434           Compare two images and return a bitmap describing the differences
1435           found, if any.  The return value must be logically AND'ed with one
1436           or more constants in order to determine the differences.  The
1437           following constants are available:
1438
1439             GD_CMP_IMAGE             The two images look different
1440             GD_CMP_NUM_COLORS        The two images have different numbers of colors
1441             GD_CMP_COLOR             The two images' palettes differ
1442             GD_CMP_SIZE_X            The two images differ in the horizontal dimension
1443             GD_CMP_SIZE_Y            The two images differ in the vertical dimension
1444             GD_CMP_TRANSPARENT       The two images have different transparency
1445             GD_CMP_BACKGROUND        The two images have different background colors
1446             GD_CMP_INTERLACE         The two images differ in their interlace
1447             GD_CMP_TRUECOLOR         The two images are not both true color
1448
1449           The most important of these is GD_CMP_IMAGE, which will tell you
1450           whether the two images will look different, ignoring differences in
1451           the order of colors in the color palette and other invisible
1452           changes.  The constants are not imported by default, but must be
1453           imported individually or by importing the :cmp tag.  Example:
1454
1455             use GD qw(:DEFAULT :cmp);
1456             # get $image1 from somewhere
1457             # get $image2 from somewhere
1458             if ($image1->compare($image2) & GD_CMP_IMAGE) {
1459                warn "images differ!";
1460             }
1461
1462       $image->clip($x1,$y1,$x2,$y2)
1463       ($x1,$y1,$x2,$y2) = $image->clip
1464           Set or get the clipping rectangle.  When the clipping rectangle is
1465           set, all drawing will be clipped to occur within this rectangle.
1466           The clipping rectangle is initially set to be equal to the
1467           boundaries of the whole image. Change it by calling clip() with the
1468           coordinates of the new clipping rectangle.  Calling clip() without
1469           any arguments will return the current clipping rectangle.
1470
1471       $flag = $image->boundsSafe($x,$y)
1472           The boundsSafe() method will return true if the point indicated by
1473           ($x,$y) is within the clipping rectangle, or false if it is not.
1474           If the clipping rectangle has not been set, then it will return
1475           true if the point lies within the image boundaries.
1476
1477   Grouping Methods
1478       GD does not support grouping of objects, but GD::SVG does. In that
1479       subclass, the following methods declare new groups of graphical
1480       objects:
1481
1482       $image->startGroup([$id,\%style])
1483       $image->endGroup()
1484       $group = $image->newGroup
1485           See GD::SVG for information.
1486

Polygons

1488       A few primitive polygon creation and manipulation methods are provided.
1489       They aren't part of the Gd library, but I thought they might be handy
1490       to have around (they're borrowed from my qd.pl Quickdraw library).
1491       Also see GD::Polyline.
1492
1493       $poly = GD::Polygon->new
1494          Create an empty polygon with no vertices.
1495
1496                  $poly = new GD::Polygon;
1497
1498       $poly->addPt($x,$y)
1499          Add point (x,y) to the polygon.
1500
1501                  $poly->addPt(0,0);
1502                  $poly->addPt(0,50);
1503                  $poly->addPt(25,25);
1504                  $myImage->fillPoly($poly,$blue);
1505
1506       ($x,$y) = $poly->getPt($index)
1507          Retrieve the point at the specified vertex.
1508
1509                  ($x,$y) = $poly->getPt(2);
1510
1511       $poly->setPt($index,$x,$y)
1512          Change the value of an already existing vertex.  It is an error to
1513          set a vertex that isn't already defined.
1514
1515                  $poly->setPt(2,100,100);
1516
1517       ($x,$y) = $poly->deletePt($index)
1518          Delete the specified vertex, returning its value.
1519
1520                  ($x,$y) = $poly->deletePt(1);
1521
1522       $poly->clear()
1523          Delete all vertices, restoring the polygon to its initial empty
1524          state.
1525
1526       $poly->toPt($dx,$dy)
1527          Draw from current vertex to a new vertex, using relative (dx,dy)
1528          coordinates.  If this is the first point, act like addPt().
1529
1530                  $poly->addPt(0,0);
1531                  $poly->toPt(0,50);
1532                  $poly->toPt(25,-25);
1533                  $myImage->fillPoly($poly,$blue);
1534
1535       $vertex_count = $poly->length
1536          Return the number of vertices in the polygon.
1537
1538                  $points = $poly->length;
1539
1540       @vertices = $poly->vertices
1541          Return a list of all the vertices in the polygon object.  Each
1542          member of the list is a reference to an (x,y) array.
1543
1544                  @vertices = $poly->vertices;
1545                  foreach $v (@vertices)
1546                     print join(",",@$v),"\n";
1547                  }
1548
1549       @rect = $poly->bounds
1550          Return the smallest rectangle that completely encloses the polygon.
1551          The return value is an array containing the (left,top,right,bottom)
1552          of the rectangle.
1553
1554                  ($left,$top,$right,$bottom) = $poly->bounds;
1555
1556       $poly->offset($dx,$dy)
1557          Offset all the vertices of the polygon by the specified horizontal
1558          (dh) and vertical (dy) amounts.  Positive numbers move the polygon
1559          down and to the right.
1560
1561                  $poly->offset(10,30);
1562
1563       $poly->map($srcL,$srcT,$srcR,$srcB,$destL,$dstT,$dstR,$dstB)
1564          Map the polygon from a source rectangle to an equivalent position in
1565          a destination rectangle, moving it and resizing it as necessary.
1566          See polys.pl for an example of how this works.  Both the source and
1567          destination rectangles are given in (left,top,right,bottom)
1568          coordinates.  For convenience, you can use the polygon's own
1569          bounding box as the source rectangle.
1570
1571                  # Make the polygon really tall
1572                  $poly->map($poly->bounds,0,0,50,200);
1573
1574       $poly->scale($sx,$sy)
1575          Scale each vertex of the polygon by the X and Y factors indicated by
1576          sx and sy.  For example scale(2,2) will make the polygon twice as
1577          large.  For best results, move the center of the polygon to position
1578          (0,0) before you scale, then move it back to its previous position.
1579
1580       $poly->transform($sx,$rx,$sy,$ry,$tx,$ty)
1581          Run each vertex of the polygon through a transformation matrix,
1582          where sx and sy are the X and Y scaling factors, rx and ry are the X
1583          and Y rotation factors, and tx and ty are X and Y offsets.  See the
1584          Adobe PostScript Reference, page 154 for a full explanation, or
1585          experiment.
1586
1587   GD::Polyline
1588       Please see GD::Polyline for information on creating open polygons and
1589       splines.
1590

Font Utilities

1592       The libgd library (used by the Perl GD library) has built-in support
1593       for about half a dozen fonts, which were converted from public-domain X
1594       Windows fonts.  For more fonts, compile libgd with TrueType support and
1595       use the stringFT() call.
1596
1597       If you wish to add more built-in fonts, the directory bdf_scripts
1598       contains two contributed utilities that may help you convert X-Windows
1599       BDF-format fonts into the format that libgd uses internally.  However
1600       these scripts were written for earlier versions of GD which included
1601       its own mini-gd library.  These scripts will have to be adapted for use
1602       with libgd, and the libgd library itself will have to be recompiled and
1603       linked!  Please do not contact me for help with these scripts: they are
1604       unsupported.
1605
1606       Each of these fonts is available both as an imported global (e.g.
1607       gdSmallFont) and as a package method (e.g. GD::Font->Small).
1608
1609       gdSmallFont
1610       GD::Font->Small
1611            This is the basic small font, "borrowed" from a well known public
1612            domain 6x12 font.
1613
1614       gdLargeFont
1615       GD::Font->Large
1616            This is the basic large font, "borrowed" from a well known public
1617            domain 8x16 font.
1618
1619       gdMediumBoldFont
1620       GD::Font->MediumBold
1621            This is a bold font intermediate in size between the small and
1622            large fonts, borrowed from a public domain 7x13 font;
1623
1624       gdTinyFont
1625       GD::Font->Tiny
1626            This is a tiny, almost unreadable font, 5x8 pixels wide.
1627
1628       gdGiantFont
1629       GD::Font->Giant
1630            This is a 9x15 bold font converted by Jan Pazdziora from a sans
1631            serif X11 font.
1632
1633       $font->nchars
1634            This returns the number of characters in the font.
1635
1636                    print "The large font contains ",gdLargeFont->nchars," characters\n";
1637
1638       $font->offset
1639            This returns the ASCII value of the first character in the font
1640
1641       $width = $font->width
1642       $height = $font->height
1643       "height"
1644            These return the width and height of the font.
1645
1646              ($w,$h) = (gdLargeFont->width,gdLargeFont->height);
1647

Helper Functions

1649       GD::LIBGD_VERSION
1650           Returns a number of the libgd VERSION, like 2.0204, 2.0033 or 2.01.
1651
1652       GD::VERSION_STRING
1653           Returns the string of the libgd VERSION, like "2.2.4".
1654
1655       GD::constant
1656

Obtaining the C-language version of gd

1658       libgd, the C-language version of gd, can be obtained at URL
1659       http://libgd.org/  Directions for installing and using it can be found
1660       at that site.  Please do not contact me for help with libgd.
1661

AUTHOR

1663       The GD.pm interface is copyright 1995-2010, Lincoln D. Stein. This
1664       package and its accompanying libraries is free software; you can
1665       redistribute it and/or modify it under the terms of the GPL (either
1666       version 1, or at your option, any later version) or the Artistic
1667       License 2.0.  Refer to LICENSE for the full license text.  package for
1668       details.
1669
1670       The latest versions of GD.pm are available at
1671
1672         https://github.com/lstein/Perl-GD
1673

SEE ALSO

1675       GD::Polyline, GD::SVG, GD::Simple, Image::Magick
1676
1677
1678
1679perl v5.32.0                      2020-09-24                             GD(3)
Impressum