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