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 x, 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 type - the type of color object to return, either C<'8bit'> for
 600 Imager::Color objects or C<'float'> for Imager::Color::Float objects.
 601 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 Possible errors conditions include:
 613
 614 =over
 615
 616 =item * the image supplied is empty
 617
 618 =item * a reference to an empty array was supplied for C<x> or C<y>
 619
 620 =item * C<x> or C<y> wasn't supplied
 621
 622 =item * C<type> isn't a valid value.
 623
 624 =back
 625
 626 For any of these errors getpixel() returns an empty list.
 627
 628 =item string()
 629
 630   my $font = Imager::Font->new(file=>"foo.ttf");
 631   $img->string(x => 50, y => 70,
 632                string => "Hello, World!",
 633                font => $font,
 634                size => 30,
 635                aa => 1,
 636                color => 'white');
 637
 638 Draws text on the image.
 639
 640 Parameters:
 641
 642 =over
 643
 644 =item *
 645
 646 C<x>, C<y> - the point to draw the text from.  If C<align> is 0 this
 647 is the top left of the string.  If C<align> is 1 (the default) then
 648 this is the left of the string on the baseline.  Required.
 649
 650 =item *
 651
 652 C<string> - the text to draw.  Required unless you supply the C<text>
 653 parameter.
 654
 655 =item *
 656
 657 C<font> - an L<Imager::Font> object representing the font to draw the
 658 text with.  Required.
 659
 660 =item *
 661
 662 C<aa> - if non-zero the output will be anti-aliased.  Default: the value
 663 set in Imager::Font->new() or 0 if not set.
 664
 665 =item *
 666
 667 C<align> - if non-zero the point supplied in (x,y) will be on the
 668 base-line, if zero then (x,y) will be at the top-left of the string.
 669
 670 i.e. if drawing the string C<"yA"> and align is 0 the point (x,y) will
 671 aligned with the top of the A.  If align is 1 (the default) it will be
 672 aligned with the baseline of the font, typically bottom of the A,
 673 depending on the font used.
 674
 675 Default: the value set in Imager::Font->new, or 1 if not set.
 676
 677 =item *
 678
 679 C<channel> - if present, the text will be written to the specified
 680 channel of the image and the color parameter will be ignore.
 681
 682 =item *
 683
 684 C<color> - the color to draw the text in.  Default: the color supplied to
 685 Imager::Font->new, or red if none.
 686
 687 =item *
 688
 689 C<size> - the point size to draw the text at.  Default: the size
 690 supplied to Imager::Font->new, or 15.
 691
 692 =item *
 693
 694 C<sizew> - the width scaling to draw the text at.  Default: the value
 695 of C<size>.
 696
 697 =item *
 698
 699 C<utf8> - for drivers that support it, treat the string as UTF-8
 700 encoded.  For versions of perl that support Unicode (5.6 and later),
 701 this will be enabled automatically if the C<string> parameter is
 702 already a UTF-8 string. See L<Imager::Font/"UTF-8"> for more
 703 information.
 704
 705 =item *
 706
 707 C<vlayout> - for drivers that support it, draw the text vertically.
 708 Note: I haven't found a font that has the appropriate metrics yet.
 709
 710 =item *
 711
 712 C<text> - alias for the C<string> parameter.
 713
 714 =back
 715
 716 On error, string() returns false and you can use $img->errstr to get
 717 the reason for the error.
 718
 719 =item align_string()
 720
 721 Draws text aligned around a point on the image.
 722
 723   # "Hello" centered at 100, 100 in the image.
 724   my ($left, $top, $right, $bottom) =
 725     $img->align_string(string=>"Hello",
 726                        x=>100, y=>100,
 727                        halign=>'center', valign=>'center',
 728                        font=>$font);
 729
 730 Parameters:
 731
 732 =over
 733
 734 =item *
 735
 736 C<x>, C<y> - the point to draw the text from.  If C<align> is 0 this
 737 is the top left of the string.  If C<align> is 1 (the default) then
 738 this is the left of the string on the baseline.  Required.
 739
 740 =item *
 741
 742 C<string> - the text to draw.  Required unless you supply the C<text>
 743 parameter.
 744
 745 =item *
 746
 747 C<font> - an L<Imager::Font> object representing the font to draw the
 748 text with.  Required.
 749
 750 =item *
 751
 752 C<aa> - if non-zero the output will be anti-aliased
 753
 754 =item *
 755
 756 C<valign> - vertical alignment of the text against (x,y)
 757
 758 =over
 759
 760 =item *
 761
 762 C<top> - Point is at the top of the text.
 763
 764 =item *
 765
 766 C<bottom> - Point is at the bottom of the text.
 767
 768 =item *
 769
 770 C<baseline> - Point is on the baseline of the text.  This is the default.
 771
 772 =item *
 773
 774 C<center> - Point is vertically centered within the text.
 775
 776 =back
 777
 778 =item *
 779
 780 C<halign> - horizontal alignment of the text against (x,y)
 781
 782 =over
 783
 784 =item *
 785
 786 C<left> - The point is at the left of the text.  This is the default.
 787
 788 =item *
 789
 790 C<start> - The point is at the start point of the text.
 791
 792 =item *
 793
 794 C<center> - The point is horizontally centered within the text.
 795
 796 =item *
 797
 798 C<right> - The point is at the right end of the text.
 799
 800 =item *
 801
 802 C<end> - The point is at the end point of the text.
 803
 804 =back
 805
 806 =item *
 807
 808 C<channel> - if present, the text will be written to the specified
 809 channel of the image and the color parameter will be ignore.
 810
 811 =item *
 812
 813 C<color> - the color to draw the text in.  Default: the color supplied to
 814 Imager::Font->new, or red if none.
 815
 816 =item *
 817
 818 C<size> - the point size to draw the text at.  Default: the size supplied
 819 to Imager::Font->new, or 15.
 820
 821 =item *
 822
 823 C<sizew> - the width scaling to draw the text at.  Default: the value of
 824 C<size>.
 825
 826 =item *
 827
 828 C<utf8> - for drivers that support it, treat the string as UTF-8
 829 encoded.  For versions of perl that support Unicode (5.6 and later),
 830 this will be enabled automatically if the C<string> parameter is
 831 already a UTF-8 string. See L<Imager::Font/"UTF-8"> for more
 832 information.
 833
 834 =item *
 835
 836 C<vlayout> - for drivers that support it, draw the text vertically.
 837 Note: I haven't found a font that has the appropriate metrics yet.
 838
 839 =item *
 840
 841 C<text> - alias for the C<string> parameter.
 842
 843 =back
 844
 845 On success returns a list of bounds of the drawn text, in the order
 846 left, top, right, bottom.
 847
 848 On error, align_string() returns an empty list and you can use
 849 C<< $img->errstr >> to get the reason for the error.
 850
 851 =item setscanline()
 852
 853 Set all or part of a horizontal line of pixels to an image.  This
 854 method is most useful in conjunction with L</getscanline()>.
 855
 856 The parameters you can pass are:
 857
 858 =over
 859
 860 =item *
 861
 862 C<y> - vertical position of the scan line.  This parameter is required.
 863
 864 =item *
 865
 866 C<x> - position to start on the scan line.  Default: 0
 867
 868 =item *
 869
 870 C<pixels> - either a reference to an array containing Imager::Color
 871 objects, an reference to an array containing Imager::Color::Float
 872 objects or a scalar containing packed color data.
 873
 874 If C<type> is C<index> then this can either be a reference to an array
 875 of palette color indexes or a scalar containing packed indexes.
 876
 877 See L</"Packed Color Data"> for information on the format of packed
 878 color data.
 879
 880 =item *
 881
 882 C<type> - the type of pixel data supplied.  If you supply an array
 883 reference of object then this is determined automatically.  If you
 884 supply packed color data this defaults to C<'8bit'>, if your data is
 885 packed floating point color data then set this to C<'float'>.
 886
 887 You can use C<float> or C<8bit> samples with any image.
 888
 889 If this is 'index' then pixels should be either an array of palette
 890 color indexes or a packed string of color indexes.
 891
 892 =back
 893
 894 Returns the number of pixels set.
 895
 896 Each of the following sets 5 pixels from (5, 10) through (9, 10) to
 897 blue, red, blue, red, blue:
 898
 899   my $red_color = Imager::Color->new(255, 0, 0);
 900   my $blue_color = Imager::Color->new(0, 0, 255);
 901
 902   $image->setscanline(y=>10, x=>5, pixels=>
 903                       [ ($blue_color, $red_color) x 2, $blue_color ]);
 904
 905   # use floating point color instead, for 16-bit plus images
 906   my $red_colorf = Imager::Color::Float->new(1.0, 0, 0);
 907   my $blue_colorf = Imager::Color::Float->new(0, 0, 1.0);
 908
 909   $image->setscanline(y=>10, x=>5, pixels=>
 910                       [ ($blue_colorf, $red_colorf) x 2, $blue_colorf ]);
 911
 912   # packed 8-bit data
 913   $image->setscanline(y=>10, x=>5, pixels=>
 914                       pack("C*", ((0, 0, 255, 255), (255, 0, 0, 255)) x 2,
 915                             (0, 0, 255, 255)));
 916
 917   # packed floating point samples
 918   $image->setscanline(y=>10, x=>5, type=>'float', pixels=>
 919                       pack("d*", ((0, 0, 1.0, 1.0), (1.0, 0, 0, 1.0)) x 2,
 920                             (0, 0, 1.0, 1.0)));
 921
 922
 923 Copy even rows from one image to another:
 924
 925   for (my $y = 0; $y < $im2->getheight; $y+=2) {
 926     $im1->setscanline(y=>$y,
 927                       pixels=>scalar($im2->getscanline(y=>$y)));
 928   }
 929
 930
 931 Set the blue channel to 0 for all pixels in an image.  This could be
 932 done with convert too:
 933
 934   for my $y (0..$im->getheight-1) {
 935     my $row = $im->getscanline(y=>$y);
 936     $row =~ s/(..).(.)/$1\0$2/gs;
 937     $im->setscanline(y=>$y, pixels=>$row);
 938   }
 939
 940 =item getscanline()
 941
 942 Read all or part of a horizontal line of pixels from an image.  This
 943 method is most useful in conjunction with L</setscanline()>.
 944
 945 The parameters you can pass are:
 946
 947 =over
 948
 949 =item *
 950
 951 C<y> - vertical position of the scan line.  This parameter is required.
 952
 953 =item *
 954
 955 C<x> - position to start on the scan line.  Default: 0
 956
 957 =item *
 958
 959 C<width> - number of pixels to read.  Default: $img->getwidth - x
 960
 961 =item *
 962
 963 C<type> - the type of pixel data to return.  Default: C<8bit>.
 964
 965 Permitted values are C<8bit> and C<float> and C<index>.
 966
 967 =back
 968
 969 In list context this method will return a list of Imager::Color
 970 objects when I<type> is C<8bit>, or a list of Imager::Color::Float
 971 objects when I<type> if C<float>, or a list of integers when I<type>
 972 is C<index>.
 973
 974 In scalar context this returns a packed 8-bit pixels when I<type> is
 975 C<8bit>, or a list of packed floating point pixels when I<type> is
 976 C<float>, or packed palette color indexes when I<type> is C<index>.
 977
 978 The values of samples for which the image does not have channels is
 979 undefined.  For example, for a single channel image the values of
 980 channels 1 through 3 are undefined.
 981
 982 Check image for a given color:
 983
 984   my $found;
 985   YLOOP: for my $y (0..$img->getheight-1) {
 986     my @colors = $img->getscanline(y=>$y);
 987     for my $color (@colors) {
 988       my ($red, $green, $blue, $alpha) = $color->rgba;
 989       if ($red == $test_red && $green == $test_green && $blue == $test_blue
 990           && $alpha == $test_alpha) {
 991         ++$found;
 992         last YLOOP;
 993       }
 994     }
 995   }
 996
 997 Or do it using packed data:
 998
 999   my $found;
1000   my $test_packed = pack("CCCC", $test_red, $test_green, $test_blue,
1001                          $test_alpha);
1002   YLOOP: for my $y (0..$img->getheight-1) {
1003     my $colors = $img->getscanline(y=>$y);
1004     while (length $colors) {
1005       if (substr($colors, 0, 4, '') eq $test_packed) {
1006         ++$found;
1007         last YLOOP;
1008       }
1009     }
1010   }
1011
1012 Some of the examples for L</setscanline()> for more examples.
1013
1014 =item getsamples()
1015
1016 Read specified channels from all or part of a horizontal line of
1017 pixels from an image.
1018
1019 The parameters you can pass are:
1020
1021 =over
1022
1023 =item *
1024
1025 C<y> - vertical position of the scan line.  This parameter is required.
1026
1027 =item *
1028
1029 C<x> - position to start on the scan line.  Default: 0
1030
1031 =item *
1032
1033 C<width> - number of pixels to read.  Default: C<< $img->getwidth - x >>
1034
1035 =item *
1036
1037 C<type> - the type of sample data to return.  Default: C<8bit>.
1038
1039 Permitted values are C<8bit> and C<float>.
1040
1041 As of Imager 0.61 this can be C<16bit> only for 16 bit images.
1042
1043 =item *
1044
1045 C<channels> - a reference to an array of channels to return, where 0
1046 is the first channel.  Default: C<< [ 0 .. $self->getchannels()-1 ] >>
1047
1048 =item *
1049
1050 C<target> - if an array reference is supplied in target then the samples
1051 will be stored here instead of being returned.
1052
1053 =item *
1054
1055 C<offset> - the offset within the array referenced by I<target>
1056
1057 =back
1058
1059 In list context this will return a list of integers between 0 and 255
1060 inclusive when I<type> is C<8bit>, or a list of floating point numbers
1061 between 0.0 and 1.0 inclusive when I<type> is C<float>.
1062
1063 In scalar context this will return a string of packed bytes, as with
1064 C< pack("C*", ...) > when I<type> is C<8bit> or a string of packed
1065 doubles as with C< pack("d*", ...) > when I<type> is C<float>.
1066
1067 If the I<target> option is supplied then only a count of samples is
1068 returned.
1069
1070 Example: Check if any pixels in an image have a non-zero alpha
1071 channel:
1072
1073   my $has_coverage;
1074   for my $y (0 .. $img->getheight()-1) {
1075     my $alpha = $img->getsamples(y=>$y, channels=>[0]);
1076     if ($alpha =~ /[^\0]/) {
1077       ++$has_coverage;
1078       last;
1079     }
1080   }
1081
1082 Example: Convert a 2 channel gray image into a 4 channel RGBA image:
1083
1084   # this could be done with convert() instead
1085   my $out = Imager->new(xsize => $src->getwidth(),
1086                         ysize => $src->getheight(),
1087                         channels => 4);
1088   for my $y ( 0 .. $src->getheight()-1 ) {
1089     my $data = $src->getsamples(y=>$y, channels=>[ 0, 0, 0, 1 ]);
1090     $out->setscanline(y=>$y, pixels=>$data);
1091   }
1092
1093 Retrieve 16-bit samples:
1094
1095   if ($img->bits == 16) {
1096     my @samples;
1097     $img->getsamples(x => 0, y => $y, target => \@samples, type => '16bit');
1098   }
1099
1100 =item setsamples()
1101
1102 This allows writing of samples back to some images.  Currently this is
1103 only supported for 16-bit/sample images.
1104
1105 Parameters:
1106
1107 =over
1108
1109 =item *
1110
1111 C<y> - vertical position of the scan line.  This parameter is required.
1112
1113 =item *
1114
1115 C<x> - position to start on the scan line.  Default: 0
1116
1117 =item *
1118
1119 C<width> - number of pixels to write.  Default: C<< $img->getwidth - x >>.
1120 The minimum of this and the number of pixels represented by the
1121 samples provided will be written.
1122
1123 =item *
1124
1125 C<type> - the type of sample data to write.  This parameter is required.
1126
1127 This can be C<8bit>, C<float> or for 16-bit images only, C<16bit>.
1128
1129 =item *
1130
1131 C<channels> - a reference to an array of channels to return, where 0 is
1132 the first channel.  Default: C<< [ 0 .. $self->getchannels()-1 ] >>
1133
1134 =item *
1135
1136 C<data> - for a type of C<8bit> or C<float> this can be a reference to
1137 an array of samples or a scalar containing packed samples.  If C<data>
1138 is a scalar it may only contain characters from \x00 to \xFF.
1139
1140 For a type of C<16bit> this can only be a reference to an array of
1141 samples to write.
1142
1143 Required.
1144
1145 =item *
1146
1147 C<offset> - the starting offset within the array referenced by
1148 I<data>.  If C<data> is a scalar containing packed samples this offset
1149 is in samples.
1150
1151 =back
1152
1153 Returns the number of samples written.
1154
1155   $targ->setsamples(y => $y, data => \@data);
1156
1157   $targ->setsamples(y => $y, data => \@data, offset => $src->getchannels);
1158
1159 Copy from one image to another:
1160
1161   my $targ = Imager->new(xsize => $src->getwidth,
1162         ysize => $src->getheight, channels => $src->getchannels);
1163   for my $y (0 .. $targ->getheight()-1) {
1164     my $row = $src->getsamples(y => $y)
1165       or die $src->errstr;
1166     $targ->setsamples(y => $y, data => $row)
1167       or die $targ->errstr;;
1168   }
1169
1170 Compose an image from separate source channels:
1171
1172   my @src = ...; # images to work from, up to 4
1173   my $targ = Imager->new(xsize => $src[0]->getwidth,
1174      ysize => $src[0]->getheight, channels => scalar(@src));
1175   for my $y (0 .. $targ->getheight()-1) {
1176     for my $ch (0 .. $#src) {
1177       my $row = $src[$ch]->getsamples(y => $y, channels => [ 0 ]);
1178       $targ->setsamples(y => $y, data => $row, channels => [ $ch ] );
1179     }
1180   }
1181
1182 =back
1183
1184 =head1 Packed Color Data
1185
1186 The getscanline() and setscanline() methods can work with pixels
1187 packed into scalars.  This is useful to remove the cost of creating
1188 color objects, but should only be used when performance is an issue.
1189
1190 The getsamples() and setsamples() methods can work with samples packed
1191 into scalars.
1192
1193 Packed data can either be 1 byte per sample or 1 double per sample.
1194
1195 Each pixel returned by getscanline() or supplied to setscanline()
1196 contains 4 samples, even if the image has fewer then 4 channels.  The
1197 values of the extra samples as returned by getscanline() is not
1198 specified.  The extra samples passed to setscanline() are ignored.
1199
1200 To produce packed 1 byte/sample pixels, use the pack C<C> template:
1201
1202   my $packed_8bit_pixel = pack("CCCC", $red, $blue, $green, $alpha);
1203
1204 To produce packed double/sample pixels, use the pack C<d> template:
1205
1206   my $packed_float_pixel = pack("dddd", $red, $blue, $green, $alpha);
1207
1208 If you use a I<type> parameter of C<index> then the values are palette
1209 color indexes, not sample values:
1210
1211   my $im = Imager->new(xsize => 100, ysize => 100, type => 'paletted');
1212   my $black_index = $im->addcolors(colors => [ 'black' ]);
1213   my $red_index = $im->addcolors(colors => [ 'red' ]);
1214   # 2 pixels
1215   my $packed_index_data = pack("C*", $black_index, $red_index);
1216   $im->setscanline(y => $y, pixels => $packed_index_data, type => 'index');
1217
1218 =head1 Combine Types
1219
1220 Some methods accept a C<combine> parameter, this can be any of the
1221 following:
1222
1223 =over
1224
1225 =item C<none>
1226
1227 The fill pixel replaces the target pixel.
1228
1229 =item C<normal>
1230
1231 The fill pixels alpha value is used to combine it with the target pixel.
1232
1233 =item C<multiply>
1234
1235 =item C<mult>
1236
1237 Each channel of fill and target is multiplied, and the result is
1238 combined using the alpha channel of the fill pixel.
1239
1240 =item C<dissolve>
1241
1242 If the alpha of the fill pixel is greater than a random number, the
1243 fill pixel is alpha combined with the target pixel.
1244
1245 =item C<add>
1246
1247 The channels of the fill and target are added together, clamped to the range of the samples and alpha combined with the target.
1248
1249 =item C<subtract>
1250
1251 The channels of the fill are subtracted from the target, clamped to be
1252 >= 0, and alpha combined with the target.
1253
1254 =item C<diff>
1255
1256 The channels of the fill are subtracted from the target and the
1257 absolute value taken this is alpha combined with the target.
1258
1259 =item C<lighten>
1260
1261 The higher value is taken from each channel of the fill and target
1262 pixels, which is then alpha combined with the target.
1263
1264 =item C<darken>
1265
1266 The higher value is taken from each channel of the fill and target
1267 pixels, which is then alpha combined with the target.
1268
1269 =item C<hue>
1270
1271 The combination of the saturation and value of the target is combined
1272 with the hue of the fill pixel, and is then alpha combined with the
1273 target.
1274
1275 =item C<sat>
1276
1277 The combination of the hue and value of the target is combined
1278 with the saturation of the fill pixel, and is then alpha combined with the
1279 target.
1280
1281 =item C<value>
1282
1283 The combination of the hue and value of the target is combined
1284 with the value of the fill pixel, and is then alpha combined with the
1285 target.
1286
1287 =item C<color>
1288
1289 The combination of the value of the target is combined with the hue
1290 and saturation of the fill pixel, and is then alpha combined with the
1291 target.
1292
1293 =back
1294
1295 =over
1296
1297 =item combines()
1298
1299 Returns a list of possible combine types.
1300
1301 =back
1302
1303 =head1 BUGS
1304
1305 box() does not support anti-aliasing yet.  Default color is not
1306 unified yet.
1307
1308 =head1 AUTHOR
1309
1310 Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson.
1311
1312 =head1 SEE ALSO
1313
1314 L<Imager>(3), L<Imager::Cookbook>(3)
1315
1316 =head1 REVISION
1317
1318 $Revision$
1319
1320 =cut