home *** CD-ROM | disk | FTP | other *** search
/ CLIX - Fazer Clix Custa Nix / CLIX-CD.cdr / mac / lib / GD.pm < prev    next >
Text File  |  1998-04-05  |  35KB  |  1,237 lines
  1. package GD;
  2.  
  3. # Copyright 1995 Lincoln D. Stein.  See accompanying README file for
  4. # usage information
  5.  
  6. require 5.00323;
  7. require FileHandle;
  8. require Exporter;
  9. require DynaLoader;
  10. require AutoLoader;
  11. use strict;
  12. use vars qw($VERSION @ISA @EXPORT $AUTOLOAD);
  13. $VERSION = "1.18";
  14.  
  15. @ISA = qw(Exporter DynaLoader);
  16. # Items to export into callers namespace by default. Note: do not export
  17. # names by default without a very good reason. Use EXPORT_OK instead.
  18. # Do not simply export all your public functions/methods/constants.
  19. @EXPORT = qw(
  20.     gdBrushed
  21.     gdDashSize
  22.     gdMaxColors
  23.     gdStyled
  24.     gdStyledBrushed
  25.     gdTiled
  26.     gdTransparent
  27.     gdTinyFont
  28.     gdSmallFont
  29.     gdMediumBoldFont
  30.     gdLargeFont
  31.     gdGiantFont
  32. );
  33. sub AUTOLOAD {
  34.     # This AUTOLOAD is used to 'autoload' constants from the constant()
  35.     # XS function.  If a constant is not found then control is passed
  36.     # to the AUTOLOAD in AutoLoader.
  37.  
  38.     my($constname);
  39.     ($constname = $AUTOLOAD) =~ s/.*:://;
  40.     my $val = constant($constname, @_ ? $_[0] : 0);
  41.     if ($! != 0) {
  42.     if ($! =~ /Invalid/) {
  43.         $AutoLoader::AUTOLOAD = $AUTOLOAD;
  44.         goto &AutoLoader::AUTOLOAD;
  45.     }
  46.     else {
  47.         my($pack,$file,$line) = caller;
  48.         die "Your vendor has not defined GD macro $pack\:\:$constname, used at $file line $line.\n";
  49.     }
  50.     }
  51.     eval "sub $AUTOLOAD { $val }";
  52.     goto &$AUTOLOAD;
  53. }
  54.  
  55. bootstrap GD;
  56.  
  57. # Preloaded methods go here.
  58. sub GD::gdSmallFont {
  59.     return &GD::Font::Small;
  60. }
  61.  
  62. sub GD::gdLargeFont {
  63.     return &GD::Font::Large;
  64. }
  65.  
  66. sub GD::gdMediumBoldFont {
  67.     return &GD::Font::MediumBold;
  68. }
  69.  
  70. sub GD::gdTinyFont {
  71.     return &GD::Font::Tiny;
  72. }
  73.  
  74. sub GD::gdGiantFont {
  75.     return &GD::Font::Giant;
  76. }
  77.  
  78. # This is a C callback
  79. sub GD::Image::newFromGif {
  80.     croak("Usage: newFromGif(class,filehandle)") unless @_==2;
  81.     my($class,$fh) = @_;
  82.     unless (ref $fh or ref(\$fh) eq 'GLOB') {
  83.     my($package) = caller;
  84.     no strict;
  85.     $fh = *{"$package\::$fh"};
  86.     }
  87.     binmode($fh);
  88.     $class->_newFromGif($fh);
  89. }
  90.  
  91. sub GD::Image::newFromXbm {
  92.     croak("Usage: newFromXbm(class,filehandle)") unless @_==2;
  93.     my($class,$fh) = @_;
  94.     unless (ref $fh or ref(\$fh) eq 'GLOB') {
  95.     my($package) = caller;
  96.     no strict;
  97.     $fh = *{"$package\::$fh"};
  98.     }
  99.     binmode($fh);
  100.     $class->_newFromXbm($fh);
  101. }
  102.  
  103. sub GD::Image::newFromGd {
  104.     croak("Usage: newFromGd(class,filehandle)") unless @_==2;
  105.     my($class,$fh) = @_;
  106.     unless (ref $fh or ref(\$fh) eq 'GLOB') {
  107.     my($package) = caller;
  108.     no strict;
  109.     $fh = *{"$package\::$fh"};
  110.     }
  111.     binmode($fh);
  112.     $class->_newFromGd($fh);
  113. }
  114.  
  115. ### The polygon object ###
  116. # create a new polygon
  117. sub GD::Polygon::new {
  118.     my $class = shift;
  119.     return bless { 'length'=>0,'points'=>[] },$class;
  120. }
  121.  
  122. # automatic destruction of the polygon
  123. sub GD::Polygon::DESTROY {
  124.     my $self = shift;
  125.     undef $self->{'points'};
  126. }
  127.  
  128. # add an x,y vertex to the polygon
  129. sub GD::Polygon::addPt {
  130.     my($self,$x,$y) = @_;
  131.     push(@{$self->{'points'}},[$x,$y]);
  132.     $self->{'length'}++;
  133. }
  134.  
  135. # get a vertex
  136. sub GD::Polygon::getPt {
  137.     my($self,$index) = @_;
  138.     return () unless ($index>=0) && ($index<$self->{'length'});
  139.     return @{$self->{'points'}->[$index]};
  140. }
  141.  
  142. # change the value of a vertex
  143. sub GD::Polygon::setPt {
  144.     my($self,$index,$x,$y) = @_;
  145.     unless (($index>=0) && ($index<$self->{'length'})) {
  146.     warn "Attempt to set an undefined polygon vertex";
  147.     return undef;
  148.     }
  149.     @{$self->{'points'}->[$index]} = ($x,$y);
  150.     1;
  151. }
  152.  
  153. # return the total number of vertices
  154. sub GD::Polygon::length {
  155.     my $self = shift;
  156.     return $self->{'length'};
  157. }
  158.  
  159. # return the array of vertices.
  160. # each vertex is an two-member (x,y) array
  161. sub GD::Polygon::vertices {
  162.     my $self = shift;
  163.     return @{$self->{'points'}};
  164. }
  165.  
  166. # return the bounding box of the polygon
  167. # (smallest rectangle that contains it)
  168. sub GD::Polygon::bounds {
  169.     my $self = shift;
  170.     my($top,$bottom,$left,$right) = @_;
  171.     $top =    99999999;
  172.     $bottom =-99999999;
  173.     $left =   99999999;
  174.     $right = -99999999;
  175.     my $v;
  176.     foreach $v ($self->vertices) {
  177.     $left = $v->[0] if $left > $v->[0];
  178.     $right = $v->[0] if $right < $v->[0];
  179.     $top = $v->[1] if $top > $v->[1];
  180.     $bottom = $v->[1] if $bottom < $v->[1];
  181.     }
  182.     return ($left,$top,$right,$bottom);
  183. }
  184.  
  185. # delete a vertex, returning it, just for fun
  186. sub GD::Polygon::delete {
  187.     my($self,$index) = @_;
  188.     my($vertex) = splice(@{$self->{'points'}},$index,1);
  189.     return @$vertex;
  190. }
  191.  
  192. # translate the polygon in space by deltaX and deltaY
  193. sub GD::Polygon::offset {
  194.     my($self,$dh,$dv) = @_;
  195.     my $size = $self->length;
  196.     my($i);
  197.     for ($i=0;$i<$size;$i++) {
  198.     my($x,$y)=$self->getPt($i);
  199.     $self->setPt($i,$x+$dh,$y+$dv);
  200.     }
  201. }
  202.  
  203. # map the polygon from sourceRect to destRect,
  204. # translating and resizing it if necessary
  205. sub GD::Polygon::map {
  206.     my($self,$srcL,$srcT,$srcR,$srcB,$destL,$destT,$destR,$destB) = @_;
  207.     my($factorV) = ($destB-$destT)/($srcB-$srcT);
  208.     my($factorH) = ($destR-$destL)/($srcR-$srcL);
  209.     my($vertices) = $self->length;
  210.     my($i);
  211.     for ($i=0;$i<$vertices;$i++) {
  212.     my($x,$y) = $self->getPt($i);
  213.     $x = int($destL + ($x - $srcL) * $factorH);
  214.     $y = int($destT + ($y - $srcT) * $factorV);
  215.     $self->setPt($i,$x,$y);
  216.     }
  217. }
  218.  
  219. # draws closed polygon with the specified color
  220. sub GD::Image::polygon {
  221.     my $self = shift;
  222.     my($p,$c) = @_;
  223.     $self->openPolygon($p, $c);
  224.     $self->line( @{$p->{'points'}->[0]},
  225.         @{$p->{'points'}->[$p->{'length'}-1]}, $c);
  226. }
  227.  
  228. # These routines added by Winfriend Koenig.
  229. sub GD::Polygon::toPt {
  230.     my($self, $dx, $dy) = @_;
  231.     unless ($self->length > 0) {
  232.     $self->addPt($dx,$dy);
  233.     return;
  234.     }
  235.     my ($x, $y) = $self->getPt($self->length-1);
  236.     $self->addPt($x+$dx,$y+$dy);
  237. }
  238.  
  239. sub GD::Polygon::transform($$$$$$$) {
  240.     # see PostScript Ref. page 154
  241.     my($self, $a, $b, $c, $d, $tx, $ty) = @_;
  242.     my $size = $self->length;
  243.     for (my $i=0;$i<$size;$i++) {
  244.     my($x,$y)=$self->getPt($i);
  245.     $self->setPt($i, $a*$x+$c*$y+$tx, $b*$x+$d*$y+$ty);
  246.     }
  247.     
  248. }
  249.  
  250. sub GD::Polygon::scale {
  251.     my($self, $sx, $sy) = @_;
  252.     $self->transform($sx,0,0,$sy,0,0);
  253. }
  254.  
  255.  
  256. # Autoload methods go after __END__, and are processed by the autosplit program.
  257. 1;
  258. __END__
  259.  
  260. =head1 NAME
  261.  
  262. GD.pm - Interface to Gd Graphics Library
  263.  
  264. =head1 SYNOPSIS
  265.  
  266.     use GD;
  267.         
  268.     # create a new image
  269.     $im = new GD::Image(100,100);
  270.  
  271.     # allocate some colors
  272.     $white = $im->colorAllocate(255,255,255);
  273.     $black = $im->colorAllocate(0,0,0);       
  274.     $red = $im->colorAllocate(255,0,0);      
  275.     $blue = $im->colorAllocate(0,0,255);
  276.  
  277.     # make the background transparent and interlaced
  278.     $im->transparent($white);
  279.     $im->interlaced('true');
  280.  
  281.     # Put a black frame around the picture
  282.     $im->rectangle(0,0,99,99,$black);
  283.  
  284.     # Draw a blue oval
  285.     $im->arc(50,50,95,75,0,360,$blue);
  286.  
  287.     # And fill it with red
  288.     $im->fill(50,50,$red);
  289.  
  290.     # make sure we are writing to a binary stream
  291.     binmode STDOUT;
  292.  
  293.     # Convert the image to GIF and print it on standard output
  294.     print $im->gif;
  295.  
  296. =head1 DESCRIPTION
  297.  
  298. B<GD.pm> is a port of Thomas Boutell's gd graphics library (see
  299. below).  GD allows you to create color drawings using a large number of
  300. graphics primitives, and emit the drawings as GIF files.
  301.  
  302. GD defines the following three classes:
  303.  
  304. =over 5
  305.  
  306. =item C<GD::Image>
  307.  
  308. An image class, which holds the image data and accepts graphic
  309. primitive method calls.
  310.  
  311. =item C<GD::Font>
  312.  
  313. A font class, which holds static font information and used for text
  314. rendering.
  315.  
  316. =item C<GD::Polygon>
  317.  
  318. A simple polygon object, used for storing lists of vertices prior to
  319. rendering a polygon into an image.
  320.  
  321. =back
  322.  
  323. A Simple Example:
  324.  
  325.     #!/usr/local/bin/perl
  326.  
  327.     use GD;
  328.     
  329.     # create a new image
  330.     $im = new GD::Image(100,100);
  331.  
  332.     # allocate some colors
  333.     $white = $im->colorAllocate(255,255,255);
  334.     $black = $im->colorAllocate(0,0,0);       
  335.     $red = $im->colorAllocate(255,0,0);      
  336.     $blue = $im->colorAllocate(0,0,255);
  337.  
  338.     # make the background transparent and interlaced
  339.     $im->transparent($white);
  340.     $im->interlaced('true');
  341.  
  342.     # Put a black frame around the picture
  343.     $im->rectangle(0,0,99,99,$black);
  344.  
  345.     # Draw a blue oval
  346.     $im->arc(50,50,95,75,0,360,$blue);
  347.  
  348.     # And fill it with red
  349.     $im->fill(50,50,$red);
  350.  
  351.     # make sure we are writing to a binary stream
  352.     binmode STDOUT;
  353.  
  354.     # Convert the image to GIF and print it on standard output
  355.     print $im->gif;
  356.  
  357. Notes:
  358.  
  359. =over 5
  360.  
  361. =item 1.
  362. To create a new, empty image, send a new() message to GD::Image, passing
  363. it the width and height of the image you want to create.  An image
  364. object will be returned.  Other class methods allow you to initialize
  365. an image from a preexisting GIF, GD or XBM file.
  366.  
  367. =item 2.
  368. Next you will ordinarily add colors to the image's color table.
  369. colors are added using a colorAllocate() method call.  The three
  370. parameters in each call are the red, green and blue (rgb) triples for
  371. the desired color.  The method returns the index of that color in the
  372. image's color table.  You should store these indexes for later use.
  373.  
  374. =item 3.
  375. Now you can do some drawing!  The various graphics primitives are
  376. described below.  In this example, we do some text drawing, create an
  377. oval, and create and draw a polygon.
  378.  
  379. =item 4.
  380. Polygons are created with a new() message to GD::Polygon.  You can add
  381. points to the returned polygon one at a time using the addPt() method.
  382. The polygon can then be passed to an image for rendering.
  383.  
  384. =item 5.
  385. When you're done drawing, you can convert the image into GIF format by
  386. sending it a gif() message.  It will return a (potentially large)
  387. scalar value containing the binary data for the image.  Ordinarily you
  388. will print it out at this point or write it to a file.  To ensure
  389. portability to platforms that differentiate between text and binary
  390. files, be sure to call C<binmode()> on the file you are writing
  391. the image to.
  392.  
  393. =back
  394.  
  395. =head1 Method Calls
  396.  
  397.  
  398. =head2 Creating and Saving Images
  399.  
  400. =over 5
  401.  
  402. =item C<new>
  403.  
  404. C<GD::Image::new(width,height)> I<class method>
  405.  
  406. To create a new, blank image, send a new() message to the GD::Image
  407. class.  For example:
  408.  
  409.     $myImage = new GD::Image(100,100) || die;
  410.  
  411. This will create an image that is 100 x 100 pixels wide.  If you don't
  412. specify the dimensions, a default of 64 x 64 will be chosen. If
  413. something goes wrong (e.g. insufficient memory), this call will
  414. return undef.
  415.  
  416. =item C<newFromGif>
  417.  
  418. C<GD::Image::newFromGif(FILEHANDLE)> I<class method>
  419.  
  420. This will create an image from a GIF file read in through the provided
  421. filehandle.  The filehandle must previously have been opened on a
  422. valid GIF file or pipe.  If successful, this call will return an
  423. initialized image which you can then manipulate as you please.  If it
  424. fails, which usually happens if the thing at the other end of the
  425. filehandle is not a valid GIF file, the call returns undef.  Notice
  426. that the call doesn't automatically close the filehandle for you.
  427. But it does call C<binmode(FILEHANDLE)> for you, on platforms where
  428. this matters.
  429.  
  430. To get information about the size and color usage of the information,
  431. you can call the image query methods described below.
  432.  
  433.     Example usage:
  434.  
  435.     open (GIF,"barnswallow.gif") || die;
  436.     $myImage = newFromGif GD::Image(GIF) || die;
  437.     close GIF;
  438.  
  439. =item C<newFromXbm>
  440.  
  441. C<GD::Image::newFromXbm(FILEHANDLE)> I<class method>
  442.  
  443. This works in exactly the same way as C<newFromGif>, but reads the
  444. contents of an X Bitmap file:
  445.  
  446.     open (XBM,"coredump.xbm") || die;
  447.     $myImage = newFromXbm GD::Image(XBM) || die;
  448.     close XBM;
  449.  
  450. Note that this function also calls C<binmode(FILEHANDLE)> before
  451. reading from the filehandle.
  452.  
  453. =item C<newFromGd>
  454.  
  455. C<GD::Image::newFromGd(FILEHANDLE)> I<class method>
  456.  
  457. This works in exactly the same way as C<newFromGif>, but reads the
  458. contents of a GD file.  GD is Tom Boutell's disk-based storage format,
  459. intended for the rare case when you need to read and write the image
  460. to disk quickly.  It's not intended for regular use, because, unlike
  461. GIF or JPEG, no image compression is performed and these files can
  462. become B<BIG>.
  463.  
  464.     open (GDF,"godzilla.gd") || die;
  465.     $myImage = newFromGd GD::Image(GDF) || die;
  466.     close GDF;
  467.  
  468. Note that this function also calls C<binmode(FILEHANDLE)> before
  469. reading from the supplied filehandle.
  470.  
  471. =item C<gif>
  472.  
  473. C<GD::Image::gif> I<object method>
  474.  
  475. This returns the image data in GIF format.  You can then print it,
  476. pipe it to a display program, or write it to a file.  Example:
  477.  
  478.     $gif_data = $myImage->gif;
  479.     open (DISPLAY,"| display -") || die;
  480.     binmode DISPLAY;
  481.     print DISPLAY $gif_data;
  482.     close DISPLAY;
  483.  
  484. Note the use of C<binmode()>.  This is crucial for portability to
  485. DOSish platforms.
  486.  
  487. =item C<gd>
  488.  
  489. C<GD::Image::gd> I<object method>
  490.  
  491. This returns the image data in GD format.  You can then print it,
  492. pipe it to a display program, or write it to a file.  Example:
  493.  
  494.     binmode MYOUTFILE;
  495.     print MYOUTFILE $myImage->gd;
  496.  
  497. =back
  498.  
  499. =head2 Color Control
  500.  
  501. =over 5
  502.  
  503. =item C<colorAllocate>
  504.  
  505. C<GD::Image::colorAllocate(red,green,blue)> I<object method>
  506.  
  507. This allocates a color with the specified red, green and blue
  508. components and returns its index in the color table, if specified.
  509. The first color allocated in this way becomes the image's background
  510. color.  (255,255,255) is white (all pixels on).  (0,0,0) is black (all
  511. pixels off).  (255,0,0) is fully saturated red.  (127,127,127) is 50%
  512. gray.  You can find plenty of examples in /usr/X11/lib/X11/rgb.txt.
  513.  
  514. If no colors are allocated, then this function returns -1.
  515.  
  516. Example:
  517.  
  518.     $white = $myImage->colorAllocate(0,0,0); #background color
  519.     $black = $myImage->colorAllocate(255,255,255);
  520.     $peachpuff = $myImage->colorAllocate(255,218,185);
  521.  
  522. =item C<colorDeallocate>
  523.  
  524. C<GD::Image::colorDeallocate(colorIndex)> I<object method> 
  525.  
  526. This marks the color at the specified index as being ripe for
  527. reallocation.  The next time colorAllocate is used, this entry will be
  528. replaced.  You can call this method several times to deallocate
  529. multiple colors.  There's no function result from this call.
  530.  
  531. Example:
  532.  
  533.     $myImage->colorDeallocate($peachpuff);
  534.     $peachy = $myImage->colorAllocate(255,210,185);
  535.  
  536. =item C<colorClosest>
  537.  
  538. C<GD::Image::colorClosest(red,green,blue)> I<object method>
  539.  
  540. This returns the index of the color closest in the color table to the
  541. red green and blue components specified.  If no colors have yet been
  542. allocated, then this call returns -1.
  543.  
  544. Example:
  545.  
  546.     $apricot = $myImage->colorClosest(255,200,180);
  547.  
  548. =item C<colorExact>
  549.  
  550. C<GD::Image::colorExact(red,green,blue)> I<object method>
  551.  
  552. This returns the index of a color that exactly matches the specified
  553. red green and blue components.  If such a color is not in the color
  554. table, this call returns -1.
  555.  
  556.     $rosey = $myImage->colorExact(255,100,80);
  557.     warn "Everything's coming up roses.\n" if $rosey >= 0;
  558.  
  559. =item C<colorsTotal>
  560.  
  561. C<GD::Image::colorsTotal)> I<object method>
  562.  
  563. This returns the total number of colors allocated in the object.
  564.  
  565.     $maxColors = $myImage->colorsTotal;
  566.  
  567. =item C<getPixel>
  568.  
  569. C<GD::Image::getPixel(x,y)> I<object method>
  570.  
  571. This returns the color table index underneath the specified
  572. point.  It can be combined with rgb()
  573. to obtain the rgb color underneath the pixel.
  574.  
  575. Example:
  576.  
  577.         $index = $myImage->getPixel(20,100);
  578.         ($r,$g,$b) = $myImage->rgb($index);
  579.  
  580. =item C<rgb>
  581.  
  582. C<GD::Image::rgb(colorIndex)> I<object method>
  583.  
  584. This returns a list containing the red, green and blue components of
  585. the specified color index.
  586.  
  587. Example:
  588.  
  589.     @RGB = $myImage->rgb($peachy);
  590.  
  591. =item C<transparent>
  592.  
  593. C<GD::Image::transparent(colorIndex)> I<object method>
  594.  
  595. This marks the color at the specified index as being transparent.
  596. Portions of the image drawn in this color will be invisible.  This is
  597. useful for creating paintbrushes of odd shapes, as well as for
  598. making GIF backgrounds transparent for displaying on the Web.  Only
  599. one color can be transparent at any time. To disable transparency, 
  600. specify -1 for the index.  
  601.  
  602. If you call this method without any parameters, it will return the
  603. current index of the transparent color, or -1 if none.
  604.  
  605. Example:
  606.  
  607.     open(GIF,"test.gif");
  608.     $im = newFromGif GD::Image(GIF);
  609.     $white = $im->colorClosest(255,255,255); # find white
  610.     $im->transparent($white);
  611.     binmode STDOUT;
  612.     print $im->gif;
  613.  
  614. =back
  615.  
  616. =head2 Special Colors
  617.  
  618. GD implements a number of special colors that can be used to achieve
  619. special effects.  They are constants defined in the GD::
  620. namespace, but automatically exported into your namespace when the GD
  621. module is loaded.
  622.  
  623. =over 5
  624.  
  625. =item C<setBrush>
  626.  
  627. =item C<gdBrushed>
  628.  
  629. C<GD::Image::setBrush( )> and C<GD::gdBrushed>
  630.  
  631. You can draw lines and shapes using a brush pattern.  Brushes are 
  632. just images that you can create and manipulate in the usual way. When
  633. you draw with them, their contents are used for the color and shape of
  634. the lines.
  635.  
  636. To make a brushed line, you must create or load the brush first, then
  637. assign it to the image using C<setBrush>.  You can then draw in that
  638. with that brush using the C<gdBrushed> special color.  It's often 
  639. useful to set the background of the brush to transparent so that 
  640. the non-colored parts don't overwrite other parts of your image.
  641.  
  642. Example:
  643.  
  644.     # Create a brush at an angle
  645.     $diagonal_brush = new GD::Image(5,5);
  646.     $white = $diagonal_brush->allocateColor(255,255,255);
  647.     $black = $diagonal_brush->allocateColor(0,0,0);
  648.     $diagonal_brush->transparent($white);
  649.     $diagonal_brush->line(0,4,4,0,$black); # NE diagonal
  650.  
  651.     # Set the brush
  652.     $myImage->setBrush($diagonal_brush);
  653.     
  654.     # Draw a circle using the brush
  655.     $myImage->arc(50,50,25,25,0,360,gdBrushed);
  656.  
  657. =item C<setStyle>
  658.  
  659. =item C<gdStyled>
  660.  
  661. C<GD::Image::setStyle(@colors)> and C<GD::gdStyled>
  662.  
  663. Styled lines consist of an arbitrary series of repeated colors and are
  664. useful for generating dotted and dashed lines.  To create a styled
  665. line, use C<setStyle> to specify a repeating series of colors.  It
  666. accepts an array consisting of one or more color indexes.  Then
  667. draw using the C<gdStyled> special color.  Another special color,
  668. C<gdTransparent> can be used to introduce holes in the line, as the
  669. example shows.
  670.  
  671. Example:
  672.  
  673.     # Set a style consisting of 4 pixels of yellow,
  674.     # 4 pixels of blue, and a 2 pixel gap
  675.     $myImage->setStyle($yellow,$yellow,$yellow,$yellow,
  676.                $blue,$blue,$blue,$blue,
  677.                gdTransparent,gdTransparent);
  678.     $myImage->arc(50,50,25,25,0,360,gdStyled);
  679.  
  680. To combine the C<gdStyled> and C<gdBrushed> behaviors, you can specify
  681. C<gdStyledBrushed>.  In this case, a pixel from the current brush
  682. pattern is rendered wherever the color specified in setStyle() is
  683. neither gdTransparent nor 0.
  684.  
  685. =item C<gdTiled>
  686.  
  687. Draw filled shapes and flood fills using a pattern.  The pattern is
  688. just another image.  The image will be tiled multiple times in order
  689. to fill the required space, creating wallpaper effects.  You must call
  690. C<setTile> in order to define the particular tile pattern you'll use
  691. for drawing when you specify the gdTiled color.
  692. details.
  693.  
  694. =item C<gdStyled>
  695.  
  696. The gdStyled color is used for creating dashed and dotted lines.  A
  697. styled line can contain any series of colors and is created using the
  698. C<setStyled> command.
  699.  
  700. =back
  701.  
  702. =head2 Drawing Commands
  703.  
  704. =over 5
  705.  
  706. =item C<setPixel>
  707.  
  708. C<GD::Image::setPixel(x,y,color)> I<object method> 
  709.  
  710. This sets the pixel at (x,y) to the specified color index.  No value
  711. is returned from this method.  The coordinate system starts at the
  712. upper left at (0,0) and gets larger as you go down and to the right.
  713. You can use a real color, or one of the special colors gdBrushed, 
  714. gdStyled and gdStyledBrushed can be specified.
  715.  
  716. Example:
  717.  
  718.     # This assumes $peach already allocated
  719.     $myImage->setPixel(50,50,$peach);
  720.  
  721. =item C<line>
  722.  
  723. C<GD::Image::line(x1,y1,x2,y2,color)> I<object method>
  724.  
  725. This draws a line from (x1,y1) to (x2,y2) of the specified color.  You
  726. can use a real color, or one of the special colors gdBrushed, 
  727. gdStyled and gdStyledBrushed.
  728.  
  729. Example:
  730.  
  731.     # Draw a diagonal line using the currently defind
  732.     # paintbrush pattern.
  733.     $myImage->line(0,0,150,150,gdBrushed);
  734.  
  735. =item C<dashedLine>
  736.  
  737. C<GD::Image::dashedLine(x1,y1,x2,y2,color)> I<object method>
  738.  
  739. This draws a dashed line from (x1,y1) to (x2,y2) in the specified
  740. color.  A more powerful way to generate arbitrary dashed and dotted
  741. lines is to use the setStyle() method described below and to draw with
  742. the special color gdStyled.
  743.  
  744. Example:
  745.  
  746.     $myImage->dashedLine(0,0,150,150,$blue);
  747.  
  748. =item C<rectangle>
  749.  
  750. C<GD::Image::rectangle(x1,y1,x2,y2,color)> I<object method>
  751.  
  752. This draws a rectangle with the specified color.  (x1,y1) and (x2,y2)
  753. are the upper left and lower right corners respectively.  Both real 
  754. color indexes and the special colors gdBrushed, gdStyled and 
  755. gdStyledBrushed are accepted.
  756.  
  757. Example:
  758.  
  759.     $myImage->rectangle(10,10,100,100,$rose);
  760.  
  761. =item C<filledRectangle>
  762.  
  763. C<GD::Image::filledRectangle(x1,y1,x2,y2,color)> I<object method>
  764.  
  765. This draws a rectangle filed with the specified color.  You can use a
  766. real color, or the special fill color gdTiled to fill the polygon
  767. with a pattern.
  768.  
  769. Example:
  770.  
  771.     # read in a fill pattern and set it
  772.     open(GIF,"happyface.gif") || die;
  773.     $tile = newFromGif GD::Image(GIF);
  774.     $myImage->setTile($tile); 
  775.  
  776.     # draw the rectangle, filling it with the pattern
  777.     $myImage->filledRectangle(10,10,150,200,gdTiled);
  778.  
  779. =item C<polygon>
  780.  
  781. C<GD::Image::polygon(polygon,color)> I<object method> 
  782.  
  783. This draws a polygon with the specified color.  The polygon must be
  784. created first (see below).  The polygon must have at least three
  785. vertices.  If the last vertex doesn't close the polygon, the method
  786. will close it for you.  Both real color indexes and the special 
  787. colors gdBrushed, gdStyled and gdStyledBrushed can be specified.
  788.  
  789. Example:
  790.  
  791.     $poly = new GD::Polygon;
  792.     $poly->addPt(50,0);
  793.     $poly->addPt(99,99);
  794.     $poly->addPt(0,99);
  795.     $myImage->polygon($poly,$blue);
  796.  
  797. =item C<filledPolygon>
  798.  
  799. C<GD::Image::filledPolygon(poly,color)> I<object method>
  800.  
  801. This draws a polygon filled with the specified color.  You can use a
  802. real color, or the special fill color gdTiled to fill the polygon
  803. with a pattern.
  804.  
  805. Example:
  806.  
  807.     # make a polygon
  808.     $poly = new GD::Polygon;
  809.     $poly->addPt(50,0);
  810.     $poly->addPt(99,99);
  811.     $poly->addPt(0,99);
  812.  
  813.     # draw the polygon, filling it with a color
  814.     $myImage->filledPolygon($poly,$peachpuff);
  815.  
  816. =item C<arc>
  817.  
  818. C<GD::Image::arc(cx,cy,width,height,start,end,color)> I<object method>
  819.  
  820. This draws arcs and ellipses.  (cx,cy) are the center of the arc, and
  821. (width,height) specify the width and height, respectively.  The
  822. portion of the ellipse covered by the arc are controlled by start and
  823. end, both of which are given in degrees from 0 to 360.  Zero is at the
  824. top of the ellipse, and angles increase clockwise.  To specify a
  825. complete ellipse, use 0 and 360 as the starting and ending angles.  To
  826. draw a circle, use the same value for width and height.
  827.  
  828. You can specify a normal color or one of the special colors gdBrushed,
  829. gdStyled, or gdStyledBrushed.
  830.  
  831. Example:
  832.  
  833.     # draw a semicircle centered at 100,100
  834.     $myImage->arc(100,100,50,50,0,180,$blue);
  835.  
  836. =item C<fill>
  837.  
  838. C<GD::Image::fill(x,y,color)> I<object method>
  839.  
  840. This method flood-fills regions with the specified color.  The color
  841. will spread through the image, starting at point (x,y), until it is
  842. stopped by a pixel of a different color from the starting pixel (this
  843. is similar to the "paintbucket" in many popular drawing toys).  You
  844. can specify a normal color, or the special color gdTiled, to flood-fill
  845. with patterns.
  846.  
  847. Example:
  848.  
  849.     # Draw a rectangle, and then make its interior blue
  850.     $myImage->rectangle(10,10,100,100,$black);
  851.     $myImage->fill(50,50,$blue);
  852.  
  853. =item C<GD::Image::fillToBorder(x,y,bordercolor,color)> I<object method>
  854.  
  855. Like C<fill>, this method flood-fills regions with the specified color,
  856. starting at position (x,y).
  857. However, instead of stopping when it hits a pixel of a different color
  858. than the starting pixel, flooding will only stop when it hits the
  859. color specified by bordercolor.  You must specify a normal indexed
  860. color for the bordercolor.  However, you are free to use the gdTiled
  861. color for the fill.
  862.  
  863. Example:
  864.  
  865.     # This has the same effect as the previous example
  866.     $myImage->rectangle(10,10,100,100,$black);
  867.     $myImage->fillToBorder(50,50,$black,$blue);
  868.  
  869. =back
  870.  
  871. =head2 Image Copying Commands
  872.  
  873. Two methods are provided for copying a rectangular region from one
  874. image to another.  One method copies a region without resizing it.
  875. The other allows you to stretch the region during the copy operation.
  876.  
  877. With either of these methods it is important to know that the routines
  878. will attempt to flesh out the destination image's color table to match
  879. the colors that are being copied from the source.  If the
  880. destination's color table is already full, then the routines will
  881. attempt to find the best match, with varying results.
  882.  
  883. =over 5
  884.  
  885. =item C<copy>
  886.  
  887. C<GD::Image::copy(sourceImage,dstX,dstY,srcX,srcY,width,height)> I<object method>
  888.  
  889. This is the simpler of the two copy operations, copying the specified
  890. region from the source image to the destination image (the one
  891. performing the method call).  (srcX,srcY) specify the upper left
  892. corner of a rectangle in the source image, and (width,height) give the
  893. width and height of the region to copy.  (dstX,dstY) control where in
  894. the destination image to stamp the copy.  You can use the same image
  895. for both the source and the destination, but the source and
  896. destination regions must not overlap or strange things will happen.
  897.  
  898. Example:
  899.  
  900.     $myImage = new GD::Image(100,100);
  901.     ... various drawing stuff ...
  902.     $srcImage = new GD::Image(50,50);
  903.     ... more drawing stuff ...
  904.     # copy a 25x25 pixel region from $srcImage to
  905.     # the rectangle starting at (10,10) in $myImage
  906.     $myImage->copy($srcImage,10,10,0,0,25,25);
  907.  
  908. =item C<copyResized>
  909.  
  910. C<GD::Image::copyResized(sourceImage,dstX,dstY,srcX,srcY,destW,destH,srcW,srcH)> I<object method>
  911.  
  912. This method is similar to copy() but allows you to choose different
  913. sizes for the source and destination rectangles.  The source and
  914. destination rectangle's are specified independently by (srcW,srcH) and
  915. (destW,destH) respectively.  copyResized() will stretch or shrink the
  916. image to accomodate the size requirements.
  917.  
  918. Example:
  919.  
  920.     $myImage = new GD::Image(100,100);
  921.     ... various drawing stuff ...
  922.     $srcImage = new GD::Image(50,50);
  923.     ... more drawing stuff ...
  924.     # copy a 25x25 pixel region from $srcImage to
  925.     # a larger rectangle starting at (10,10) in $myImage
  926.     $myImage->copyResized($srcImage,10,10,0,0,50,50,25,25);
  927.  
  928. =back
  929.  
  930. =head2 Character and String Drawing
  931.  
  932. Gd allows you to draw characters and strings, either in normal
  933. horizontal orientation or rotated 90 degrees.  These routines use a
  934. GD::Font object, described in more detail below.  There are four
  935. built-in fonts, available in global variables gdGiantFont, gdLargeFont,
  936. gdMediumBoldFont, gdSmallFont and gdTinyFont.  Currently there is no
  937. way of dynamically creating your own fonts.
  938.  
  939. =over 5
  940.  
  941. =item C<string>
  942.  
  943. C<GD::Image::string(font,x,y,string,color)> I<Object Method>
  944.  
  945. This method draws a string startin at position (x,y) in the specified
  946. font and color.  Your choices of fonts are gdSmallFont, gdMediumBoldFont,
  947. gdTinyFont, gdLargeFont and gdGiantFont.
  948.  
  949. Example:
  950.  
  951.     $myImage->string(gdSmallFont,2,10,"Peachy Keen",$peach);
  952.  
  953. =item C<stringUp>
  954.  
  955. C<GD::Image::stringUp(font,x,y,string,color)> I<Object Method>
  956.  
  957. Just like the previous call, but draws the text rotated
  958. counterclockwise 90 degrees.
  959.  
  960. =item C<char>
  961.  
  962. =item C<charUp>
  963.  
  964. C<GD::Image::char(font,x,y,char,color)> I<Object Method>
  965. C<GD::Image::charUp(font,x,y,char,color)> I<Object Method>
  966.  
  967. These methods draw single characters at position (x,y) in the
  968. specified font and color.  They're carry-overs from the C interface,
  969. where there is a distinction between characters and strings.  Perl is
  970. insensible to such subtle distinctions.
  971.  
  972. =back
  973.  
  974. =head2 Miscellaneous Image Methods
  975.  
  976. =over 5
  977.  
  978. =item C<interlaced>
  979.  
  980. C<GD::Image::interlaced( )> C<GD::Image::interlaced(1)> I<Object method>
  981.  
  982. This method sets or queries the image's interlaced setting.  Interlace
  983. produces a cool venetian blinds effect on certain viewers.  Provide a
  984. true parameter to set the interlace attribute.  Provide undef to
  985. disable it.  Call the method without parameters to find out the
  986. current setting.
  987.  
  988. =item c<getBounds>
  989.  
  990. C<GD::Image::getBounds( )> I<Object method>
  991.  
  992. This method will return a two-member list containing the width and
  993. height of the image.  You query but not not change the size of the
  994. image once it's created.
  995.  
  996.  
  997. =back
  998.  
  999. =head2 Polygon Methods
  1000.  
  1001. A few primitive polygon creation and manipulation methods are
  1002. provided.  They aren't part of the Gd library, but I thought they
  1003. might be handy to have around (they're borrowed from my qd.pl
  1004. Quickdraw library).
  1005.  
  1006. =over 5
  1007.  
  1008. =item c<new>
  1009.  
  1010. C<GD::Polygon::new> I<class method>
  1011.  
  1012. Create an empty polygon with no vertices.
  1013.  
  1014.     $poly = new GD::Polygon;
  1015.  
  1016. =item C<addPt>
  1017.  
  1018. C<GD::Polygon::addPt(x,y)> I<object method>
  1019.  
  1020. Add point (x,y) to the polygon.
  1021.  
  1022.     $poly->addPt(0,0);
  1023.     $poly->addPt(0,50);
  1024.     $poly->addPt(25,25);
  1025.     $myImage->fillPoly($poly,$blue);
  1026.  
  1027. =item C<getPt>
  1028.  
  1029. C<GD::Polygon::getPt(index)> I<object method>
  1030.  
  1031. Retrieve the point at the specified vertex.
  1032.  
  1033.     ($x,$y) = $poly->getPt(2);
  1034.  
  1035. =item C<setPt>
  1036.  
  1037. C<GD::Polygon::setPt(index,x,y)> I<object method>
  1038.  
  1039. Change the value of an already existing vertex.  It is an error to set
  1040. a vertex that isn't already defined.
  1041.  
  1042.     $poly->setPt(2,100,100);
  1043.  
  1044. =item C<deletePt>
  1045.  
  1046. C<GD::Polygon:deletePt(index)> I<object method>
  1047.  
  1048. Delete the specified vertex, returning its value.
  1049.  
  1050.     ($x,$y) = $poly->deletePt(1); 
  1051.  
  1052. =item C<toPt>
  1053.  
  1054. C<GD::Polygon::toPt(dx,dy)> I<object method>
  1055.  
  1056. Draw from current vertex to a new vertex, using relative 
  1057. (dx,dy) coordinates.  If this is the first point, act like
  1058. addPt().
  1059.  
  1060.     $poly->addPt(0,0);
  1061.     $poly->toPt(0,50);
  1062.     $poly->toPt(25,-25);
  1063.     $myImage->fillPoly($poly,$blue);
  1064.  
  1065.  
  1066. =item C<length>
  1067.  
  1068. C<GD::Polygon::length> I<object method>
  1069.  
  1070. Return the number of vertices in the polygon.
  1071.  
  1072.     $points = $poly->length;
  1073.  
  1074. =item C<vertices>
  1075.  
  1076. C<GD::Polygon::vertices> I<object method>
  1077.  
  1078. Return a list of all the verticies in the polygon object.  Each
  1079. membver of the list is a reference to an (x,y) array.
  1080.  
  1081.     @vertices = $poly->vertices;
  1082.     foreach $v (@vertices)
  1083.        print join(",",@$v),"\n";
  1084.     }
  1085.  
  1086. =item C<bounds>
  1087.  
  1088. C<GD::Polygon::bounds> I<object method>
  1089.  
  1090. Return the smallest rectangle that completely encloses the polygon.
  1091. The return value is an array containing the (left,top,right,bottom) of
  1092. the rectangle.
  1093.  
  1094.     ($left,$top,$right,$bottom) = $poly->bounds;
  1095.  
  1096. =item C<offset>
  1097.  
  1098. C<GD::Polygon::offset(dx,dy)> I<object method>
  1099.  
  1100. Offset all the vertices of the polygon by the specified horizontal
  1101. (dh) and vertical (dy) amounts.  Positive numbers move the polygon
  1102. down and to the right.
  1103.  
  1104.     $poly->offset(10,30);
  1105.  
  1106. =item C<map>
  1107.  
  1108. C<GD::Polygon::map(srcL,srcT,srcR,srcB,destL,dstT,dstR,dstB)> I<object method>
  1109.  
  1110. Map the polygon from a source rectangle to an equivalent position in a
  1111. destination rectangle, moving it and resizing it as necessary.  See
  1112. polys.pl for an example of how this works.  Both the source and
  1113. destination rectangles are given in (left,top,right,bottom)
  1114. coordinates.  For convenience, you can use the polygon's own bounding
  1115. box as the source rectangle.
  1116.  
  1117.     # Make the polygon really tall
  1118.     $poly->map($poly->bounds,0,0,50,200);
  1119.  
  1120. =item C<scale>
  1121.  
  1122. C<GD::Polygon::scale(sx,sy)> I<object method>
  1123.  
  1124. Scale each vertex of the polygon by the X and Y factors indicated by
  1125. sx and sy.  For example scale(2,2) will make the polygon twice as
  1126. large.  For best results, move the center of the polygon to position
  1127. (0,0) before you scale, then move it back to its previous position.
  1128.  
  1129. =item C<transform>
  1130.  
  1131. C<GD::Polygon::transform(sx,rx,sy,ry,tx,ty)> I<object method>
  1132.  
  1133. Run each vertex of the polygon through a transformation matrix, where
  1134. sx and sy are the X and Y scaling factors, rx and ry are the X and Y
  1135. rotation factors, and tx and ty are X and Y offsets.  See the Adobe
  1136. PostScript Reference, page 154 for a full explanation, or experiment.
  1137.  
  1138. =back
  1139.  
  1140. =head2 Font Utilities
  1141.  
  1142. Gd's support for fonts is minimal.  Basically you have access to a
  1143. half dozen for drawing, and not much else.  However, for future
  1144. compatibility, I've made the fonts into perl objects of type GD::Font
  1145. that you can query and, perhaps someday manipulate.
  1146.  
  1147. This distribution comes with Jan Pazdziora's bdftogd program, an
  1148. B<unsupported> utility that can help you convert BDF fonts into GD
  1149. format.
  1150.  
  1151. =over 5
  1152.  
  1153. =item C<gdSmallFont>
  1154.  
  1155. C<GD::Font::Small> I<constant>
  1156.  
  1157. This is the basic small font, "borrowed" from a well known public
  1158. domain 6x12 font.
  1159.  
  1160. =item C<gdLargeFont>
  1161.  
  1162. C<GD::Font::Large> I<constant>
  1163.  
  1164. This is the basic large font, "borrowed" from a well known public
  1165. domain 8x16 font.
  1166.  
  1167. =item C<gdMediumBoldFont>
  1168.  
  1169. C<GD::Font::MediumBold> I<constant>
  1170.  
  1171. This is a bold font intermediate in size between the small and large
  1172. fonts, borrowed from a public domain 7x13 font;
  1173.  
  1174. =item C<gdTinyFont>
  1175.  
  1176. C<GD::Font::Tiny> I<constant>
  1177.  
  1178. This is a tiny, almost unreadable font, 5x8 pixels wide.
  1179.  
  1180. =item C<gdGiantFont>
  1181.  
  1182. C<GD::Font::Giant> I<constant>
  1183.  
  1184. This is a 9x15 bold font converted by Jan Pazdziora from a sans serif
  1185. X11 font.
  1186.  
  1187. =item C<nchars>
  1188.  
  1189. C<GD::Font::nchars> I<object method>
  1190.  
  1191. This returns the number of characters in the font.
  1192.  
  1193.     print "The large font contains ",gdLargeFont->nchars," characters\n";
  1194.  
  1195. =item C<offset>
  1196.  
  1197. C<GD::Font::offset>     I<object method>
  1198.  
  1199. This returns the ASCII value of the first character in the font
  1200.  
  1201. =item C<width>
  1202.  
  1203. =item C<height>
  1204.  
  1205. C<GD::Font::width> C<GD::Font::height>  I<object methods>
  1206.  
  1207. These return the width and height of the font.
  1208.  
  1209.     ($w,$h) = (gdLargeFont->width,gdLargeFont->height);
  1210.  
  1211. =back
  1212.  
  1213. =head1 Obtaining the C-language version of gd
  1214.  
  1215. libgd, the C-language version of gd, can be obtained at URL
  1216. http://www.boutell.com/gd/gd.html.  Directions for installing and
  1217. using it can be found at that site.  Please do not contact me for help
  1218. with libgd.
  1219.  
  1220. =head1 Copyright Information
  1221.  
  1222. The GD.pm interface is copyright 1995, Lincoln D. Stein.  You are free
  1223. to use it for any purpose, commercial or noncommercial, provided that
  1224. if you redistribute the source code this statement of copyright
  1225. remains attached. The gd library is covered separately under a 1994
  1226. copyright by Quest Protein Database Center, Cold Spring Harbor Labs
  1227. and Thomas Boutell.  For usage information see the gd documentation at
  1228. URL
  1229.  
  1230.     http://www.boutell.com/gd/gd.html
  1231.  
  1232. The latest versions of GD.pm are available at
  1233.  
  1234.   http://www.genome.wi.mit.edu/ftp/pub/software/WWW/GD.html
  1235.   ftp://ftp-genome.wi.mit.edu/pub/software/WWW/GD.pm.tar.gz
  1236.  
  1237.