lib/Imager/Draw.pod

   1 =head1 NAME
   2
   3 Imager::Draw - Draw primitives to images
   4
   5 =head1 SYNOPSIS
   6
   7   use Imager;
   8   use Imager::Fill;
   9
  10   $img = ...;
  11   $blue = Imager::Color->new( 0, 0, 255 );
  12   $fill = Imager::Fill->new(hatch=>'stipple');
  13
  14   $img->line(color=>$blue, x1=>10, x2=>100,
  15                            y1=>20, y2=>50, aa=>1, endp=>1 );
  16
  17   $img->polyline(points=>[[$x0,$y0], [$x1,$y1], [$x2,$y2]],
  18                  color=>$blue);
  19   $img->polyline(x=>[$x0,$x1,$x2], y=>[$y0,$y1,$y2], aa=>1);
  20
  21   $img->box(color=> $blue, xmin=> 10, ymin=>30,
  22                            xmax=>200, ymax=>300, filled=>1);
  23   $img->box(fill=>$fill);
  24
  25   $img->arc(color=>$blue, r=>20, x=>200, y=>100,
  26             d1=>10, d2=>20 );
  27
  28   $img->circle(color=>$blue, r=>50, x=>200, y=>100);
  29
  30   $img->polygon(points=>[[$x0,$y0], [$x1,$y1], [$x2,$y2]],
  31                 color=>$blue);
  32
  33   $img->polygon(x=>[$x0,$x1,$x2], y=>[$y0,$y1,$y2]);
  34
  35   $img->flood_fill(x=>50, y=>50, color=>$color);
  36
  37   $img->setpixel(x=>50, y=>70, color=>$color);
  38
  39   $img->setpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40], color=>$color);
  40
  41   my $color = $img->getpixel(x=>50, y=>70);
  42
  43   my @colors = $img->getpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40]);
  44
  45   # drawing text
  46   my $font = Imager::Font->new(...) or die;
  47   $img->string(x => 50, y => 70,
  48                font => $font,
  49                string => "Hello, World!",
  50                color => 'red',
  51                size => 30,
  52                aa => 1);
  53
  54   # bottom right-hand corner of the image
  55   $img->align_string(x => $img->getwidth() - 1,
  56                      y => $img->getheight() - 1,
  57                      halign => 'right',
  58                      valign => 'bottom',
  59                      string => 'Imager',
  60                      font => $font,
  61                      size => 12);
  62
  63   # low-level functions
  64   my @colors = $img->getscanline(y=>50, x=>10, width=>20);
  65
  66   $img->setscanline(y=>60, x=>20, pixels=>\@colors);
  67
  68   my @samples = $img->getsamples(y=>50, x=>10, width=>20,
  69                                  channels=>[ 2, 0 ]);
  70
  71 =head1 DESCRIPTION
  72
  73 It is possible to draw with graphics primitives onto images.  Such
  74 primitives include boxes, arcs, circles, polygons and lines.  The
  75 coordinate system in Imager has the origin C<(0,0)> in the upper left
  76 corner of an image with co-ordinates increasing to the right and
  77 bottom.  For non anti-aliasing operation all coordinates are rounded
  78 towards the nearest integer.  For anti-aliased operations floating
  79 point coordinates are used.
  80
  81 Drawing is assumed to take place in a coordinate system of infinite
  82 resolution.  This is the typical convention and really only matters when
  83 it is necessary to check for off-by-one cases.  Typically it's useful to
  84 think of C<(10, 20)> as C<(10.00, 20.00)> and consider the consequences.
  85
  86 =head2 Color Parameters
  87
  88 X<color parameters>The C<color> parameter for any of the drawing
  89 methods can be an L<Imager::Color> object, a simple scalar that
  90 Imager::Color can understand, a hashref of parameters that
  91 Imager::Color->new understands, or an arrayref of red, green, blue
  92 values, for example:
  93
  94   $image->box(..., color=>'red');
  95   $image->line(..., color=>'#FF0000');
  96   $image->flood_fill(..., color=>[ 255, 0, 255 ]);
  97
  98 While supplying colors as names, array references or CSS color
  99 specifiers is convenient, for maximum performance you should supply
 100 the color as an L<Imager::Color> object:
 101
 102   my @colors = map Imager::Color->new($_), qw/red green blue/
 103   for my $i (1..1000) {
 104     $image->box(..., color => $colors[rand @colors]);
 105   }
 106
 107 =head2 Fill Parameters
 108
 109 X<fill parameters>All filled primitives, i.e. C<arc()>, C<box()>,
 110 C<circle()>, C<polygon()> and the C<flood_fill()> method can take a
 111 C<fill> parameter instead of a C<color> parameter which can either be
 112 an Imager::Fill object, or a reference to a hash containing the
 113 parameters used to create the fill, for example:
 114
 115   $image->box(..., fill=>{ hatch => 'check1x1' });
 116   my $fillimage = Imager->new;
 117   $fillimage->read(file=>$somefile) or die;
 118   $image->flood_fill(..., fill=>{ image=>$fillimage });
 119
 120 Currently you can create opaque or transparent plain color fills,
 121 hatched fills, image based fills and fountain fills.  See
 122 L<Imager::Fill> for more information.
 123
 124 =head2 List of primitives
 125
 126 =over
 127
 128 =item line()
 129
 130   $img->line(color=>$green, x1=>10, x2=>100,
 131                             y1=>20, y2=>50, aa=>1, endp=>1 );
 132
 133 X<line method>Draws a line from (x1,y1) to (x2,y2).  The endpoint
 134 (x2,y2) is drawn by default.  If C<endp> of 0 is specified then the
 135 endpoint will not be drawn.  If C<aa> is set then the line will be
 136 drawn anti-aliased.  The C<antialias> parameter is still available for
 137 backwards compatibility.
 138
 139 Parameters:
 140
 141 =over
 142
 143 =item *
 144
 145 C<x1>, C<y1> - starting point of the line.  Required.
 146
 147 =item *
 148
 149 C<x2>, C<y2> - end point of the line. Required.
 150
 151 =item *
 152
 153 C<color> - the color of the line.  See L</"Color Parameters">.  Default:
 154 black.
 155
 156 =item *
 157
 158 C<endp> - if zero the end point of the line is not drawn.  Default: 1
 159 - the end point is drawn.  This is useful to set to 0 when drawing a
 160 series of connected lines.
 161
 162 =item *
 163
 164 C<aa> - if true the line is drawn anti-aliased.  Default: 0.
 165
 166 =back
 167
 168 =item polyline()
 169
 170   $img->polyline(points=>[[$x0,$y0],[$x1,$y1],[$x2,$y2]],color=>$red);
 171   $img->polyline(x=>[$x0,$x1,$x2], y=>[$y0,$y1,$y2], aa=>1);
 172
 173 X<polyline method>C<polyline> is used to draw multiple lines between a
 174 series of points.  The point set can either be specified as an
 175 arrayref to an array of array references (where each such array
 176 represents a point).  The other way is to specify two array
 177 references.
 178
 179 The C<antialias> parameter is still available for backwards compatibility.
 180
 181 =over
 182
 183 =item *
 184
 185 points - a reference to an array of references to arrays containing
 186 the co-ordinates of the points in the line, for example:
 187
 188   my @points = ( [ 0, 0 ], [ 100, 0 ], [ 100, 100 ], [ 0, 100 ] );
 189   $img->polyline(points => \@points);
 190
 191 =item *
 192
 193 x, y - each is an array of x or y ordinates.  This is an alternative
 194 to supplying the C<points> parameter.
 195
 196   # same as the above points example
 197   my @x = ( 0, 100, 100, 0 );
 198   my @y = ( 0, 0, 100, 100 );
 199   $img->polyline(x => \@x, y => \@y);
 200
 201 =item *
 202
 203 C<color> - the color of the line.  See L</"Color Parameters">.
 204 Default: black.
 205
 206 =item *
 207
 208 C<aa> - if true the line is drawn anti-aliased.  Default: 0.  Can also
 209 be supplied as C<antialias> for backward compatibility.
 210
 211 =back
 212
 213 =item box()
 214
 215   $blue = Imager::Color->new( 0, 0, 255 );
 216   $img->box(color => $blue, xmin=>10, ymin=>30, xmax=>200, ymax=>300,
 217             filled=>1);
 218
 219 X<box method>If any of the edges of the box are omitted it will snap
 220 to the outer edge of the image in that direction.  If C<filled> is
 221 omitted the box is drawn as an outline.  Instead of a color it is
 222 possible to use a C<fill> pattern:
 223
 224   $fill = Imager::Fill->new(hatch=>'stipple');
 225   $img->box(fill=>$fill);  # fill entire image with a given fill pattern
 226
 227   $img->box(xmin=>10, ymin=>30, xmax=>150, ymax=>60,
 228             fill => { hatch=>'cross2' });
 229
 230 Also if a color is omitted a color with (255,255,255,255) is used
 231 instead.  [NOTE: This may change to use C<$img-E<gt>fgcolor()> in the future].
 232
 233 Box does not support fractional coordinates yet.
 234
 235 Parameters:
 236
 237 =over
 238
 239 =item *
 240
 241 C<xmin> - left side of the box.  Default: 0 (left edge of the image)
 242
 243 =item *
 244
 245 C<ymin> - top side of the box.  Default: 0 (top edge of the image)
 246
 247 =item *
 248
 249 C<xmax> - right side of the box.  Default: C<< $img->getwidth-1
 250 >>. (right edge of the image)
 251
 252 =item *
 253
 254 C<ymax> - bottom side of the box.  Default: C<< $img->getheight-1
 255 >>. (bottom edge of the image)
 256
 257 Note: C<xmax> and C<ymax> are I<inclusive> - the number of pixels
 258 drawn for a filled box is C<(xmax-xmin+1) * (ymax-ymin+1)>.
 259
 260 =item *
 261
 262 C<box> - a reference to an array of (left, top, right, bottom)
 263 co-ordinates.  This is an alternative to supplying C<xmin>, C<ymin>,
 264 C<xmax>, C<ymax> and overrides their values.
 265
 266 =item *
 267
 268 C<color> - the color of the line.  See L</"Color Parameters">.
 269 Default: white.  This is ignored if the filled parameter
 270
 271 =item *
 272
 273 C<filled> - if non-zero the box is filled with I<color> instead of
 274 outlined.  Default: an outline is drawn.
 275
 276 =item *
 277
 278 C<fill> - the fill for the box.  If this is supplied then the box will be
 279 filled.  See L</"Fill Parameters">.
 280
 281 =back
 282
 283 =item arc()
 284
 285   $img->arc(color=>$red, r=>20, x=>200, y=>100, d1=>10, d2=>20 );
 286
 287 This creates a filled red arc with a 'center' at (200, 100) and spans
 288 10 degrees and the slice has a radius of 20.
 289
 290 It's also possible to supply a C<fill> parameter.
 291
 292 To draw just an arc outline - just the curve, not the radius lines,
 293 set filled to 0:
 294
 295 Parameters:
 296
 297   $img->arc(color=>$red, r=>20, x=>200, y=>100, d1=>10, d2=>20, filled=>0 );
 298
 299 =over
 300
 301 =item *
 302
 303 C<x>, C<y> - center of the filled arc.  Default: center of the image.
 304
 305 =item *
 306
 307 C<r> - radius of the arc.  Default: 1/3 of min(image height, image width).
 308
 309 =item *
 310
 311 C<d1> - starting angle of the arc, in degrees.  Default: 0
 312
 313 =item *
 314
 315 C<d2> - ending angle of the arc, in degrees.  Default: 361.
 316
 317 =item *
 318
 319 C<color> - the color of the filled arc.  See L</"Color Parameters">.
 320 Default: white.  Overridden by C<fill>.
 321
 322 =item *
 323
 324 C<fill> - the fill for the filled arc.  See L</"Fill Parameters">
 325
 326 =item *
 327
 328 C<aa> - if true the filled arc is drawn anti-aliased.  Default: false.
 329
 330 Anti-aliased arc() is experimental for now, I'm not entirely happy
 331 with the results in some cases.
 332
 333 =item *
 334
 335 C<filled> - set to 0 to draw only an outline.
 336
 337 =back
 338
 339   # arc going through angle zero:
 340   $img->arc(d1=>320, d2=>40, x=>100, y=>100, r=>50, color=>'blue');
 341
 342   # complex fill arc
 343   $img->arc(d1=>135, d2=>45, x=>100, y=>150, r=>50,
 344             fill=>{ solid=>'red', combine=>'diff' });
 345
 346   # draw an anti-aliased circle outline
 347   $img->arc(x => 100, y => 150, r => 150, filled => 0,
 348             color => '#F00', aa => 1);
 349
 350   # draw an anti-aliased arc
 351   $img->arc(x => 100, y => 150, r => 90, filled => 0,
 352             color => '#0f0', aa => 1, d1 => 90, d2 => 180);
 353
 354 =item circle()
 355
 356   $img->circle(color=>$green, r=>50, x=>200, y=>100, aa=>1, filled=>1);
 357
 358 This creates an anti-aliased green circle with its center at (200, 100)
 359 and has a radius of 50.  It's also possible to supply a C<fill> parameter
 360 instead of a color parameter.
 361
 362   $img->circle(r => 50, x=> 150, y => 150, fill=>{ hatch => 'stipple' });
 363
 364 To draw a circular outline, set C<filled> to 0:
 365
 366   $img->circle(color=>$green, r=>50, x=>200, y=>100, aa=>1, filled=>0);
 367
 368 =over
 369
 370 =item *
 371
 372 C<x>, C<y> - center of the filled circle.  Default: center of the image.
 373
 374 =item *
 375
 376 C<r> - radius of the circle.  Default: 1/3 of min(image height, image width).
 377
 378 =item *
 379
 380 C<color> - the color of the filled circle.  See L</"Color Parameters">.
 381 Default: white.  Overridden by C<fill>.
 382
 383 =item *
 384
 385 C<fill> - the fill for the filled circle.  See L</"Fill Parameters">
 386
 387 =item *
 388
 389 C<aa> - if true the filled circle is drawn anti-aliased.  Default: false.
 390
 391 =item *
 392
 393 C<filled> - set to 0 to just draw an outline.
 394
 395 =back
 396
 397 =item polygon()
 398
 399   $img->polygon(points=>[[$x0,$y0],[$x1,$y1],[$x2,$y2]],color=>$red);
 400   $img->polygon(x=>[$x0,$x1,$x2], y=>[$y0,$y1,$y2], fill=>$fill);
 401
 402 Polygon is used to draw a filled polygon.  Currently the polygon is
 403 always drawn anti-aliased, although that will change in the future.
 404 Like other anti-aliased drawing functions its coordinates can be
 405 specified with floating point values.  As with other filled shapes
 406 it's possible to use a C<fill> instead of a color.
 407
 408 =over
 409
 410 =item *
 411
 412 C<points> - a reference to an array of references to arrays containing
 413 the co-ordinates of the points in the line, for example:
 414
 415   my @points = ( [ 0, 0 ], [ 100, 0 ], [ 100, 100 ], [ 0, 100 ] );
 416   $img->polygon(points => \@points);
 417
 418 =item *
 419
 420 C<x>, C<y> - each is an array of x or y ordinates.  This is an alternative
 421 to supplying the C<points> parameter.
 422
 423   # same as the above points example
 424   my @x = ( 0, 100, 100, 0 );
 425   my @y = ( 0, 0, 100, 100 );
 426   $img->polygon(x => \@x, y => \@y);
 427
 428 =item *
 429
 430 C<color> - the color of the filled polygon.  See L</"Color Parameters">.
 431 Default: black.  Overridden by C<fill>.
 432
 433 =item *
 434
 435 C<fill> - the fill for the filled circle.  See L</"Fill Parameters">
 436
 437 =back
 438
 439 =item flood_fill()
 440
 441 X<flood_fill>You can fill a region that all has the same color using
 442 the flood_fill() method, for example:
 443
 444   $img->flood_fill(x=>50, y=>50, color=>$color);
 445
 446 will fill all regions the same color connected to the point (50, 50).
 447
 448 Alternatively you can fill a region limited by a given border color:
 449
 450   # stop at the red border
 451   $im->flood_fill(x=>50, y=>50, color=>$color, border=>"red");
 452
 453 You can also fill with a complex fill:
 454
 455   $img->flood_fill(x=>50, y=>50, fill=>{ hatch=>'cross1x1' });
 456
 457 Parameters:
 458
 459 =over
 460
 461 =item *
 462
 463 C<x>, C<y> - the start point of the fill.
 464
 465 =item *
 466
 467 C<color> - the color of the filled area.  See L</"Color Parameters">.
 468 Default: white.  Overridden by C<fill>.
 469
 470 =item *
 471
 472 C<fill> - the fill for the filled area.  See L</"Fill Parameters">
 473
 474 =item *
 475
 476 C<border> - the border color of the region to be filled.  If this
 477 parameter is supplied flood_fill() will stop when it finds this color.
 478 If this is not supplied then a normal fill is done.  C<border> can be
 479 supplied as a L</"Color Parameters">.
 480
 481 =back
 482
 483 =item setpixel()
 484
 485   $img->setpixel(x=>50, y=>70, color=>$color);
 486   $img->setpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40], color=>$color);
 487
 488 setpixel() is used to set one or more individual pixels.
 489
 490 You can supply a single set of co-ordinates as scalar C<x> and C<y>
 491 parameters, or set either to an arrayref of ordinates.
 492
 493 If one array is shorter than another the final value in the shorter
 494 will be duplicated until they match in length.
 495
 496 If only one of C<x> or C<y> is an array reference then setpixel() will
 497 behave as if the non-reference value were an array reference
 498 containing only that value.
 499
 500 eg.
 501
 502   my $count = $img->setpixel(x => 1, y => [ 0 .. 3 ], color => $color);
 503
 504 behaves like:
 505
 506   my $count = $img->setpixel(x => [ 1 ], y => [ 0 .. 3 ], color => $color);
 507
 508 and since the final element in the shorter array is duplicated, this
 509 behaves like:
 510
 511   my $count = $img->setpixel(x => [ 1, 1, 1, 1 ], y => [ 0 .. 3 ],
 512                              color => $color);
 513
 514 Parameters:
 515
 516 =over
 517
 518 =item *
 519
 520 x, y - either integers giving the co-ordinates of the pixel to set or
 521 array references containing a set of pixels to be set.
 522
 523 =item *
 524
 525 color - the color of the pixels drawn.  See L</"Color Parameters">.
 526 Default: white.
 527
 528 =back
 529
 530 When called with an array reference in either C<x> or C<y>, returns
 531 the number of pixels successfully set, or false if none.
 532
 533 When called with scalars for x and y, return $img on success, false on
 534 failure.
 535
 536 Possible errors conditions include:
 537
 538 =over
 539
 540 =item * the image supplied is empty
 541
 542 =item * a reference to an empty array was supplied for C<x> or C<y>
 543
 544 =item * C<x> or C<y> wasn't supplied
 545
 546 =item * C<color> isn't a valid color, and can't be converted to a
 547 color.
 548
 549 =back
 550
 551 On any of these errors, setpixel() returns an empty list and sets
 552 errstr().
 553
 554 =item getpixel()
 555
 556   my $color = $img->getpixel(x=>50, y=>70); my @colors =
 557   $img->getpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40]); my $colors_ref =
 558   $img->getpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40]);
 559
 560 getpixel() is used to retrieve one or more individual pixels.
 561
 562 You can supply a single set of co-ordinates as scalar C<x> and C<y>
 563 parameters, or set each to an arrayref of ordinates.
 564
 565 If one array is shorter than another the final value in the shorter
 566 will be duplicated until they match in length.
 567
 568 If only one of C<x> or C<y> is an array reference then getpixel() will
 569 behave as if the non-reference value were an array reference
 570 containing only that value.
 571
 572 eg.
 573
 574   my @colors = $img->getpixel(x => 0, y => [ 0 .. 3 ]);
 575
 576 behaves like:
 577
 578   my @colors = $img->getpixel(x => [ 0 ], y => [ 0 .. 3 ]);
 579
 580 and since the final element in the shorter array is duplicated, this
 581 behaves like:
 582
 583   my @colors = $img->getpixel(x => [ 0, 0, 0, 0 ], y => [ 0 .. 3 ]);
 584
 585 To receive floating point colors from getpixel(), set the C<type>
 586 parameter to 'float'.
 587
 588 Parameters:
 589
 590 =over
 591
 592 =item *
 593
 594 C<x>, C<y> - either integers giving the co-ordinates of the pixel to set or
 595 array references containing a set of pixels to be set.
 596
 597 =item *
 598
 599 C<type> - the type of color object to return, either C<'8bit'> for
 600 L<Imager::Color> objects or C<'float'> for L<Imager::Color::Float>
 601 objects.  Default: C<'8bit'>.
 602
 603 =back
 604
 605 When called with an array reference for either or C<x> or C<y>,
 606 getpixel() will return a list of colors in list context, and an
 607 arrayref in scalar context.
 608
 609 If a supplied co-ordinate is outside the image then C<undef> is
 610 returned for the pixel.
 611
 612 Each color is returned as an L<Imager::Color> object or as an
 613 L<Imager::Color::Float> object if C<type> is set to C<"float">.
 614
 615 Possible errors conditions include:
 616
 617 =over
 618
 619 =item * the image supplied is empty
 620
 621 =item * a reference to an empty array was supplied for C<x> or C<y>
 622
 623 =item * C<x> or C<y> wasn't supplied
 624
 625 =item * C<type> isn't a valid value.
 626
 627 =back
 628
 629 For any of these errors getpixel() returns an empty list.
 630
 631 =item string()
 632
 633   my $font = Imager::Font->new(file=>"foo.ttf");
 634   $img->string(x => 50, y => 70,
 635                string => "Hello, World!",
 636                font => $font,
 637                size => 30,
 638                aa => 1,
 639                color => 'white');
 640
 641 Draws text on the image.
 642
 643 Parameters:
 644
 645 =over
 646
 647 =item *
 648
 649 C<x>, C<y> - the point to draw the text from.  If C<align> is 0 this
 650 is the top left of the string.  If C<align> is 1 (the default) then
 651 this is the left of the string on the baseline.  Required.
 652
 653 =item *
 654
 655 C<string> - the text to draw.  Required unless you supply the C<text>
 656 parameter.
 657
 658 =item *
 659
 660 C<font> - an L<Imager::Font> object representing the font to draw the
 661 text with.  Required.
 662
 663 =item *
 664
 665 C<aa> - if non-zero the output will be anti-aliased.  Default: the value
 666 set in Imager::Font->new() or 0 if not set.
 667
 668 =item *
 669
 670 C<align> - if non-zero the point supplied in (x,y) will be on the
 671 base-line, if zero then (x,y) will be at the top-left of the string.
 672
 673 i.e. if drawing the string C<"yA"> and align is 0 the point (x,y) will
 674 aligned with the top of the A.  If align is 1 (the default) it will be
 675 aligned with the baseline of the font, typically bottom of the A,
 676 depending on the font used.
 677
 678 Default: the value set in Imager::Font->new, or 1 if not set.
 679
 680 =item *
 681
 682 C<channel> - if present, the text will be written to the specified
 683 channel of the image and the color parameter will be ignore.
 684
 685 =item *
 686
 687 C<color> - the color to draw the text in.  Default: the color supplied to
 688 Imager::Font->new, or red if none.
 689
 690 =item *
 691
 692 C<size> - the point size to draw the text at.  Default: the size
 693 supplied to Imager::Font->new, or 15.
 694
 695 =item *
 696
 697 C<sizew> - the width scaling to draw the text at.  Default: the value
 698 of C<size>.
 699
 700 =item *
 701
 702 C<utf8> - for drivers that support it, treat the string as UTF-8
 703 encoded.  For versions of perl that support Unicode (5.6 and later),
 704 this will be enabled automatically if the C<string> parameter is
 705 already a UTF-8 string. See L<Imager::Font/"UTF-8"> for more
 706 information.
 707
 708 =item *
 709
 710 C<vlayout> - for drivers that support it, draw the text vertically.
 711 Note: I haven't found a font that has the appropriate metrics yet.
 712
 713 =item *
 714
 715 C<text> - alias for the C<string> parameter.
 716
 717 =back
 718
 719 On error, string() returns false and you can use $img->errstr to get
 720 the reason for the error.
 721
 722 =item align_string()
 723
 724 Draws text aligned around a point on the image.
 725
 726   # "Hello" centered at 100, 100 in the image.
 727   my ($left, $top, $right, $bottom) =
 728     $img->align_string(string=>"Hello",
 729                        x=>100, y=>100,
 730                        halign=>'center', valign=>'center',
 731                        font=>$font);
 732
 733 Parameters:
 734
 735 =over
 736
 737 =item *
 738
 739 C<x>, C<y> - the point to draw the text from.  If C<align> is 0 this
 740 is the top left of the string.  If C<align> is 1 (the default) then
 741 this is the left of the string on the baseline.  Required.
 742
 743 =item *
 744
 745 C<string> - the text to draw.  Required unless you supply the C<text>
 746 parameter.
 747
 748 =item *
 749
 750 C<font> - an L<Imager::Font> object representing the font to draw the
 751 text with.  Required.
 752
 753 =item *
 754
 755 C<aa> - if non-zero the output will be anti-aliased
 756
 757 =item *
 758
 759 C<valign> - vertical alignment of the text against (x,y)
 760
 761 =over
 762
 763 =item *
 764
 765 C<top> - Point is at the top of the text.
 766
 767 =item *
 768
 769 C<bottom> - Point is at the bottom of the text.
 770
 771 =item *
 772
 773 C<baseline> - Point is on the baseline of the text.  This is the default.
 774
 775 =item *
 776
 777 C<center> - Point is vertically centered within the text.
 778
 779 =back
 780
 781 =item *
 782
 783 C<halign> - horizontal alignment of the text against (x,y)
 784
 785 =over
 786
 787 =item *
 788
 789 C<left> - The point is at the left of the text.  This is the default.
 790
 791 =item *
 792
 793 C<start> - The point is at the start point of the text.
 794
 795 =item *
 796
 797 C<center> - The point is horizontally centered within the text.
 798
 799 =item *
 800
 801 C<right> - The point is at the right end of the text.
 802
 803 =item *
 804
 805 C<end> - The point is at the end point of the text.
 806
 807 =back
 808
 809 =item *
 810
 811 C<channel> - if present, the text will be written to the specified
 812 channel of the image and the color parameter will be ignore.
 813
 814 =item *
 815
 816 C<color> - the color to draw the text in.  Default: the color supplied to
 817 Imager::Font->new, or red if none.
 818
 819 =item *
 820
 821 C<size> - the point size to draw the text at.  Default: the size supplied
 822 to Imager::Font->new, or 15.
 823
 824 =item *
 825
 826 C<sizew> - the width scaling to draw the text at.  Default: the value of
 827 C<size>.
 828
 829 =item *
 830
 831 C<utf8> - for drivers that support it, treat the string as UTF-8
 832 encoded.  For versions of perl that support Unicode (5.6 and later),
 833 this will be enabled automatically if the C<string> parameter is
 834 already a UTF-8 string. See L<Imager::Font/"UTF-8"> for more
 835 information.
 836
 837 =item *
 838
 839 C<vlayout> - for drivers that support it, draw the text vertically.
 840 Note: I haven't found a font that has the appropriate metrics yet.
 841
 842 =item *
 843
 844 C<text> - alias for the C<string> parameter.
 845
 846 =back
 847
 848 On success returns a list of bounds of the drawn text, in the order
 849 left, top, right, bottom.
 850
 851 On error, align_string() returns an empty list and you can use
 852 C<< $img->errstr >> to get the reason for the error.
 853
 854 =item setscanline()
 855
 856 Set all or part of a horizontal line of pixels to an image.  This
 857 method is most useful in conjunction with L</getscanline()>.
 858
 859 The parameters you can pass are:
 860
 861 =over
 862
 863 =item *
 864
 865 C<y> - vertical position of the scan line.  This parameter is required.
 866
 867 =item *
 868
 869 C<x> - position to start on the scan line.  Default: 0
 870
 871 =item *
 872
 873 C<pixels> - either a reference to an array containing Imager::Color
 874 objects, an reference to an array containing Imager::Color::Float
 875 objects or a scalar containing packed color data.
 876
 877 If C<type> is C<index> then this can either be a reference to an array
 878 of palette color indexes or a scalar containing packed indexes.
 879
 880 See L</"Packed Color Data"> for information on the format of packed
 881 color data.
 882
 883 =item *
 884
 885 C<type> - the type of pixel data supplied.  If you supply an array
 886 reference then this is determined automatically.  If you supply packed
 887 color data this defaults to C<'8bit'>, if your data is packed floating
 888 point color data then you need to set this to C<'float'>.
 889
 890 You can use C<float> or C<8bit> samples with any image.
 891
 892 If this is C<index> then C<pixels> should be either an array of
 893 palette color indexes or a packed string of color indexes.
 894
 895 =back
 896
 897 Returns the number of pixels set.
 898
 899 Each of the following sets 5 pixels from (5, 10) through (9, 10) to
 900 blue, red, blue, red, blue:
 901
 902   my $red_color = Imager::Color->new(255, 0, 0);
 903   my $blue_color = Imager::Color->new(0, 0, 255);
 904
 905   $image->setscanline(y=>10, x=>5, pixels=>
 906                       [ ($blue_color, $red_color) x 2, $blue_color ]);
 907
 908   # use floating point color instead, for 16-bit plus images
 909   my $red_colorf = Imager::Color::Float->new(1.0, 0, 0);
 910   my $blue_colorf = Imager::Color::Float->new(0, 0, 1.0);
 911
 912   $image->setscanline(y=>10, x=>5, pixels=>
 913                       [ ($blue_colorf, $red_colorf) x 2, $blue_colorf ]);
 914
 915   # packed 8-bit data
 916   $image->setscanline(y=>10, x=>5, pixels=>
 917                       pack("C*", ((0, 0, 255, 255), (255, 0, 0, 255)) x 2,
 918                             (0, 0, 255, 255)));
 919
 920   # packed floating point samples
 921   $image->setscanline(y=>10, x=>5, type=>'float', pixels=>
 922                       pack("d*", ((0, 0, 1.0, 1.0), (1.0, 0, 0, 1.0)) x 2,
 923                             (0, 0, 1.0, 1.0)));
 924
 925
 926 Copy even rows from one image to another:
 927
 928   for (my $y = 0; $y < $im2->getheight; $y+=2) {
 929     $im1->setscanline(y=>$y,
 930                       pixels=>scalar($im2->getscanline(y=>$y)));
 931   }
 932
 933
 934 Set the blue channel to 0 for all pixels in an image.  This could be
 935 done with convert too:
 936
 937   for my $y (0..$im->getheight-1) {
 938     my $row = $im->getscanline(y=>$y);
 939     $row =~ s/(..).(.)/$1\0$2/gs;
 940     $im->setscanline(y=>$y, pixels=>$row);
 941   }
 942
 943 =item getscanline()
 944
 945 Read all or part of a horizontal line of pixels from an image.  This
 946 method is most useful in conjunction with L</setscanline()>.
 947
 948 The parameters you can pass are:
 949
 950 =over
 951
 952 =item *
 953
 954 C<y> - vertical position of the scan line.  This parameter is required.
 955
 956 =item *
 957
 958 C<x> - position to start on the scan line.  Default: 0
 959
 960 =item *
 961
 962 C<width> - number of pixels to read.  Default: $img->getwidth - x
 963
 964 =item *
 965
 966 C<type> - the type of pixel data to return.  Default: C<8bit>.
 967
 968 Permitted values are C<8bit> and C<float> and C<index>.
 969
 970 =back
 971
 972 In list context this method will return a list of Imager::Color
 973 objects when I<type> is C<8bit>, or a list of Imager::Color::Float
 974 objects when I<type> if C<float>, or a list of integers when I<type>
 975 is C<index>.
 976
 977 In scalar context this returns a packed 8-bit pixels when I<type> is
 978 C<8bit>, or a list of packed floating point pixels when I<type> is
 979 C<float>, or packed palette color indexes when I<type> is C<index>.
 980
 981 The values of samples for which the image does not have channels is
 982 undefined.  For example, for a single channel image the values of
 983 channels 1 through 3 are undefined.
 984
 985 Check image for a given color:
 986
 987   my $found;
 988   YLOOP: for my $y (0..$img->getheight-1) {
 989     my @colors = $img->getscanline(y=>$y);
 990     for my $color (@colors) {
 991       my ($red, $green, $blue, $alpha) = $color->rgba;
 992       if ($red == $test_red && $green == $test_green && $blue == $test_blue
 993           && $alpha == $test_alpha) {
 994         ++$found;
 995         last YLOOP;
 996       }
 997     }
 998   }
 999
1000 Or do it using packed data:
1001
1002   my $found;
1003   my $test_packed = pack("CCCC", $test_red, $test_green, $test_blue,
1004                          $test_alpha);
1005   YLOOP: for my $y (0..$img->getheight-1) {
1006     my $colors = $img->getscanline(y=>$y);
1007     while (length $colors) {
1008       if (substr($colors, 0, 4, '') eq $test_packed) {
1009         ++$found;
1010         last YLOOP;
1011       }
1012     }
1013   }
1014
1015 Some of the examples for L</setscanline()> for more examples.
1016
1017 =item getsamples()
1018
1019 Read specified channels from all or part of a horizontal line of
1020 pixels from an image.
1021
1022 The parameters you can pass are:
1023
1024 =over
1025
1026 =item *
1027
1028 C<y> - vertical position of the scan line.  This parameter is required.
1029
1030 =item *
1031
1032 C<x> - position to start on the scan line.  Default: 0
1033
1034 =item *
1035
1036 C<width> - number of pixels to read.  Default: C<< $img->getwidth - x >>
1037
1038 =item *
1039
1040 C<type> - the type of sample data to return.  Default: C<8bit>.
1041
1042 Permitted values are C<8bit> and C<float>.
1043
1044 As of Imager 0.61 this can be C<16bit> only for 16 bit images.
1045
1046 =item *
1047
1048 C<channels> - a reference to an array of channels to return, where 0
1049 is the first channel.  Default: C<< [ 0 .. $self->getchannels()-1 ] >>
1050
1051 =item *
1052
1053 C<target> - if an array reference is supplied in target then the samples
1054 will be stored here instead of being returned.
1055
1056 =item *
1057
1058 C<offset> - the offset within the array referenced by I<target>
1059
1060 =back
1061
1062 In list context this will return a list of integers between 0 and 255
1063 inclusive when I<type> is C<8bit>, or a list of floating point numbers
1064 between 0.0 and 1.0 inclusive when I<type> is C<float>.
1065
1066 In scalar context this will return a string of packed bytes, as with
1067 C< pack("C*", ...) > when I<type> is C<8bit> or a string of packed
1068 doubles as with C< pack("d*", ...) > when I<type> is C<float>.
1069
1070 If the I<target> option is supplied then only a count of samples is
1071 returned.
1072
1073 Example: Check if any pixels in an image have a non-zero alpha
1074 channel:
1075
1076   my $has_coverage;
1077   for my $y (0 .. $img->getheight()-1) {
1078     my $alpha = $img->getsamples(y=>$y, channels=>[0]);
1079     if ($alpha =~ /[^\0]/) {
1080       ++$has_coverage;
1081       last;
1082     }
1083   }
1084
1085 Example: Convert a 2 channel gray image into a 4 channel RGBA image:
1086
1087   # this could be done with convert() instead
1088   my $out = Imager->new(xsize => $src->getwidth(),
1089                         ysize => $src->getheight(),
1090                         channels => 4);
1091   for my $y ( 0 .. $src->getheight()-1 ) {
1092     my $data = $src->getsamples(y=>$y, channels=>[ 0, 0, 0, 1 ]);
1093     $out->setscanline(y=>$y, pixels=>$data);
1094   }
1095
1096 Retrieve 16-bit samples:
1097
1098   if ($img->bits == 16) {
1099     my @samples;
1100     $img->getsamples(x => 0, y => $y, target => \@samples, type => '16bit');
1101   }
1102
1103 =item setsamples()
1104
1105 This allows writing of samples to an image.
1106
1107 Parameters:
1108
1109 =over
1110
1111 =item *
1112
1113 C<y> - vertical position of the scan line.  This parameter is required.
1114
1115 =item *
1116
1117 C<x> - position to start on the scan line.  Default: 0
1118
1119 =item *
1120
1121 C<width> - number of pixels to write.  Default: C<< $img->getwidth - x >>.
1122 The minimum of this and the number of pixels represented by the
1123 samples provided will be written.
1124
1125 =item *
1126
1127 C<type> - the type of sample data to write.  This parameter is required.
1128
1129 This can be C<8bit>, C<float> or for 16-bit images only, C<16bit>.
1130
1131 =item *
1132
1133 C<channels> - a reference to an array of channels to return, where 0 is
1134 the first channel.  Default: C<< [ 0 .. $self->getchannels()-1 ] >>
1135
1136 =item *
1137
1138 C<data> - for a type of C<8bit> or C<float> this can be a reference to
1139 an array of samples or a scalar containing packed samples.  If C<data>
1140 is a scalar it may only contain characters from \x00 to \xFF.
1141
1142 For a type of C<16bit> this can only be a reference to an array of
1143 samples to write.
1144
1145 Required.
1146
1147 =item *
1148
1149 C<offset> - the starting offset within the array referenced by
1150 I<data>.  If C<data> is a scalar containing packed samples this offset
1151 is in samples.
1152
1153 =back
1154
1155 Returns the number of samples written.
1156
1157   $targ->setsamples(y => $y, data => \@data);
1158
1159   $targ->setsamples(y => $y, data => \@data, offset => $src->getchannels);
1160
1161 Copy from one image to another:
1162
1163   my $targ = Imager->new(xsize => $src->getwidth,
1164         ysize => $src->getheight, channels => $src->getchannels);
1165   for my $y (0 .. $targ->getheight()-1) {
1166     my $row = $src->getsamples(y => $y)
1167       or die $src->errstr;
1168     $targ->setsamples(y => $y, data => $row)
1169       or die $targ->errstr;;
1170   }
1171
1172 Compose an image from separate source channels:
1173
1174   my @src = ...; # images to work from, up to 4
1175   my $targ = Imager->new(xsize => $src[0]->getwidth,
1176      ysize => $src[0]->getheight, channels => scalar(@src));
1177   for my $y (0 .. $targ->getheight()-1) {
1178     for my $ch (0 .. $#src) {
1179       my $row = $src[$ch]->getsamples(y => $y, channels => [ 0 ]);
1180       $targ->setsamples(y => $y, data => $row, channels => [ $ch ] );
1181     }
1182   }
1183
1184 =back
1185
1186 =head1 Packed Color Data
1187
1188 The getscanline() and setscanline() methods can work with pixels
1189 packed into scalars.  This is useful to remove the cost of creating
1190 color objects, but should only be used when performance is an issue.
1191
1192 The getsamples() and setsamples() methods can work with samples packed
1193 into scalars.
1194
1195 Packed data can either be 1 byte per sample or 1 double per sample.
1196
1197 Each pixel returned by getscanline() or supplied to setscanline()
1198 contains 4 samples, even if the image has fewer then 4 channels.  The
1199 values of the extra samples as returned by getscanline() is not
1200 specified.  The extra samples passed to setscanline() are ignored.
1201
1202 To produce packed 1 byte/sample pixels, use the pack C<C> template:
1203
1204   my $packed_8bit_pixel = pack("CCCC", $red, $blue, $green, $alpha);
1205
1206 To produce packed double/sample pixels, use the pack C<d> template:
1207
1208   my $packed_float_pixel = pack("dddd", $red, $blue, $green, $alpha);
1209
1210 Note that double/sample data is always stored using the C C<double>
1211 type, never C<long double>, even if C<perl> is built with
1212 C<-Duselongdouble>.
1213
1214 If you use a I<type> parameter of C<index> then the values are palette
1215 color indexes, not sample values:
1216
1217   my $im = Imager->new(xsize => 100, ysize => 100, type => 'paletted');
1218   my $black_index = $im->addcolors(colors => [ 'black' ]);
1219   my $red_index = $im->addcolors(colors => [ 'red' ]);
1220   # 2 pixels
1221   my $packed_index_data = pack("C*", $black_index, $red_index);
1222   $im->setscanline(y => $y, pixels => $packed_index_data, type => 'index');
1223
1224 =head1 Combine Types
1225
1226 Some methods accept a C<combine> parameter, this can be any of the
1227 following:
1228
1229 =over
1230
1231 =item C<none>
1232
1233 The fill pixel replaces the target pixel.
1234
1235 =item C<normal>
1236
1237 The fill pixels alpha value is used to combine it with the target pixel.
1238
1239 =item C<multiply>
1240
1241 =item C<mult>
1242
1243 Each channel of fill and target is multiplied, and the result is
1244 combined using the alpha channel of the fill pixel.
1245
1246 =item C<dissolve>
1247
1248 If the alpha of the fill pixel is greater than a random number, the
1249 fill pixel is alpha combined with the target pixel.
1250
1251 =item C<add>
1252
1253 The channels of the fill and target are added together, clamped to the range of the samples and alpha combined with the target.
1254
1255 =item C<subtract>
1256
1257 The channels of the fill are subtracted from the target, clamped to be
1258 >= 0, and alpha combined with the target.
1259
1260 =item C<diff>
1261
1262 The channels of the fill are subtracted from the target and the
1263 absolute value taken this is alpha combined with the target.
1264
1265 =item C<lighten>
1266
1267 The higher value is taken from each channel of the fill and target
1268 pixels, which is then alpha combined with the target.
1269
1270 =item C<darken>
1271
1272 The higher value is taken from each channel of the fill and target
1273 pixels, which is then alpha combined with the target.
1274
1275 =item C<hue>
1276
1277 The combination of the saturation and value of the target is combined
1278 with the hue of the fill pixel, and is then alpha combined with the
1279 target.
1280
1281 =item C<sat>
1282
1283 The combination of the hue and value of the target is combined
1284 with the saturation of the fill pixel, and is then alpha combined with the
1285 target.
1286
1287 =item C<value>
1288
1289 The combination of the hue and value of the target is combined
1290 with the value of the fill pixel, and is then alpha combined with the
1291 target.
1292
1293 =item C<color>
1294
1295 The combination of the value of the target is combined with the hue
1296 and saturation of the fill pixel, and is then alpha combined with the
1297 target.
1298
1299 =back
1300
1301 =over
1302
1303 =item combines()
1304
1305 Returns a list of possible combine types.
1306
1307 =back
1308
1309 =head1 BUGS
1310
1311 box() does not support anti-aliasing yet.  Default color is not
1312 unified yet.
1313
1314 =head1 AUTHOR
1315
1316 Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson.
1317
1318 =head1 SEE ALSO
1319
1320 L<Imager>(3), L<Imager::Cookbook>(3)
1321
1322 =head1 REVISION
1323
1324 $Revision$
1325
1326 =cut