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(points => [ [ x, y ], [ x, y ], ... ], color => color)
 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 Parameter">.
 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 Parameters:
 491
 492 =over
 493
 494 =item *
 495
 496 x, y - either integers giving the co-ordinates of the pixel to set or
 497 array references containing a set of pixels to be set.
 498
 499 =item *
 500
 501 color - the color of the pixels drawn.  See L<"Color Parameters">.
 502 Default: white.
 503
 504 =back
 505
 506 When called with array parameters, returns the number of pixels
 507 successfully set, or false if none.
 508
 509 When called with scalars for x and y, return $img on success, false on
 510 failure.
 511
 512 =item getpixel()
 513
 514   my $color = $img->getpixel(x=>50, y=>70);
 515   my @colors = $img->getpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40]);
 516   my $colors_ref = $img->getpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40]);
 517
 518 getpixel() is used to retrieve one or more individual pixels.
 519
 520 For either method you can supply a single set of co-ordinates as
 521 scalar x and y parameters, or set each to an arrayref of ordinates.
 522
 523 When called with arrays, getpixel() will return a list of colors in
 524 list context, and an arrayref in scalar context.
 525
 526 To receive floating point colors from getpixel(), set the C<type>
 527 parameter to 'float'.
 528
 529 Parameters:
 530
 531 =over
 532
 533 =item *
 534
 535 x, y - either integers giving the co-ordinates of the pixel to set or
 536 array references containing a set of pixels to be set.
 537
 538 =item *
 539
 540 type - the type of color object to return, either C<'8bit'> for
 541 Imager::Color objects or C<'float'> for Imager::Color::Float objects.
 542 Default: C<'8bit'>.
 543
 544 =back
 545
 546 =item string
 547
 548   my $font = Imager::Font->new(file=>"foo.ttf");
 549   $img->string(x => 50, y => 70,
 550                string => "Hello, World!",
 551                font => $font,
 552                size => 30,
 553                aa => 1,
 554                color => 'white');
 555
 556 Draws text on the image.
 557
 558 Parameters:
 559
 560 =over
 561
 562 =item *
 563
 564 C<x>, C<y> - the point to draw the text from.  If C<align> is 0 this
 565 is the top left of the string.  If C<align> is 1 (the default) then
 566 this is the left of the string on the baseline.  Required.
 567
 568 =item *
 569
 570 C<string> - the text to draw.  Required unless you supply the C<text>
 571 parameter.
 572
 573 =item *
 574
 575 C<font> - an L<Imager::Font> object representing the font to draw the
 576 text with.  Required.
 577
 578 =item *
 579
 580 C<aa> - if non-zero the output will be anti-aliased.  Default: the value
 581 set in Imager::Font->new() or 0 if not set.
 582
 583 =item *
 584
 585 C<align> - if non-zero the point supplied in (x,y) will be on the
 586 base-line, if zero then (x,y) will be at the top-left of the string.
 587
 588 i.e. if drawing the string C<"yA"> and align is 0 the point (x,y) will
 589 aligned with the top of the A.  If align is 1 (the default) it will be
 590 aligned with the baseline of the font, typically bottom of the A,
 591 depending on the font used.
 592
 593 Default: the value set in Imager::Font->new, or 1 if not set.
 594
 595 =item *
 596
 597 C<channel> - if present, the text will be written to the specified
 598 channel of the image and the color parameter will be ignore.
 599
 600 =item *
 601
 602 C<color> - the color to draw the text in.  Default: the color supplied to
 603 Imager::Font->new, or red if none.
 604
 605 =item *
 606
 607 C<size> - the point size to draw the text at.  Default: the size
 608 supplied to Imager::Font->new, or 15.
 609
 610 =item *
 611
 612 C<sizew> - the width scaling to draw the text at.  Default: the value
 613 of C<size>.
 614
 615 =item *
 616
 617 C<utf8> - for drivers that support it, treat the string as UTF-8
 618 encoded.  For versions of perl that support Unicode (5.6 and later),
 619 this will be enabled automatically if the C<string> parameter is
 620 already a UTF-8 string. See L<Imager::Font/"UTF8"> for more
 621 information.
 622
 623 =item *
 624
 625 C<vlayout> - for drivers that support it, draw the text vertically.
 626 Note: I haven't found a font that has the appropriate metrics yet.
 627
 628 =item *
 629
 630 C<text> - alias for the C<string> parameter.
 631
 632 =back
 633
 634 On error, string() returns false and you can use $img->errstr to get
 635 the reason for the error.
 636
 637 =item align_string
 638
 639 Draws text aligned around a point on the image.
 640
 641   # "Hello" centered at 100, 100 in the image.
 642   my ($left, $top, $right, $bottom) =
 643     $img->align_string(string=>"Hello",
 644                        x=>100, y=>100,
 645                        halign=>'center', valign=>'center',
 646                        font=>$font);
 647
 648 Parameters:
 649
 650 =over
 651
 652 =item *
 653
 654 C<x>, C<y> - the point to draw the text from.  If C<align> is 0 this
 655 is the top left of the string.  If C<align> is 1 (the default) then
 656 this is the left of the string on the baseline.  Required.
 657
 658 =item *
 659
 660 C<string> - the text to draw.  Required unless you supply the C<text>
 661 parameter.
 662
 663 =item *
 664
 665 C<font> - an L<Imager::Font> object representing the font to draw the
 666 text with.  Required.
 667
 668 =item *
 669
 670 C<aa> - if non-zero the output will be anti-aliased
 671
 672 =item *
 673
 674 C<valign> - vertical alignment of the text against (x,y)
 675
 676 =over
 677
 678 =item *
 679
 680 C<top> - Point is at the top of the text.
 681
 682 =item *
 683
 684 C<bottom> - Point is at the bottom of the text.
 685
 686 =item *
 687
 688 C<baseline> - Point is on the baseline of the text.  This is the default.
 689
 690 =item *
 691
 692 C<center> - Point is vertically centered within the text.
 693
 694 =back
 695
 696 =item *
 697
 698 C<halign> - horizontal alignment of the text against (x,y)
 699
 700 =over
 701
 702 =item *
 703
 704 C<left> - The point is at the left of the text.  This is the default.
 705
 706 =item *
 707
 708 C<start> - The point is at the start point of the text.
 709
 710 =item *
 711
 712 C<center> - The point is horizontally centered within the text.
 713
 714 =item *
 715
 716 C<right> - The point is at the right end of the text.
 717
 718 =item *
 719
 720 C<end> - The point is at the end point of the text.
 721
 722 =back
 723
 724 =item *
 725
 726 C<channel> - if present, the text will be written to the specified
 727 channel of the image and the color parameter will be ignore.
 728
 729 =item *
 730
 731 C<color> - the color to draw the text in.  Default: the color supplied to
 732 Imager::Font->new, or red if none.
 733
 734 =item *
 735
 736 C<size> - the point size to draw the text at.  Default: the size supplied
 737 to Imager::Font->new, or 15.
 738
 739 =item *
 740
 741 C<sizew> - the width scaling to draw the text at.  Default: the value of
 742 C<size>.
 743
 744 =item *
 745
 746 C<utf8> - for drivers that support it, treat the string as UTF-8
 747 encoded.  For versions of perl that support Unicode (5.6 and later),
 748 this will be enabled automatically if the C<string> parameter is
 749 already a UTF-8 string. See L<Imager::Font/"UTF-8"> for more
 750 information.
 751
 752 =item *
 753
 754 C<vlayout> - for drivers that support it, draw the text vertically.
 755 Note: I haven't found a font that has the appropriate metrics yet.
 756
 757 =item *
 758
 759 C<text> - alias for the C<string> parameter.
 760
 761 =back
 762
 763 On success returns a list of bounds of the drawn text, in the order
 764 left, top, right, bottom.
 765
 766 On error, align_string() returns an empty list and you can use
 767 C<< $img->errstr >> to get the reason for the error.
 768
 769 =item setscanline()
 770
 771 Set all or part of a horizontal line of pixels to an image.  This
 772 method is most useful in conjunction with L</getscanline>.
 773
 774 The parameters you can pass are:
 775
 776 =over
 777
 778 =item *
 779
 780 C<y> - vertical position of the scan line.  This parameter is required.
 781
 782 =item *
 783
 784 C<x> - position to start on the scan line.  Default: 0
 785
 786 =item *
 787
 788 C<pixels> - either a reference to an array containing Imager::Color
 789 objects, an reference to an array containing Imager::Color::Float
 790 objects or a scalar containing packed color data.
 791
 792 If C<type> is C<index> then this can either be a reference to an array
 793 of palette color indexes or a scalar containing packed indexes.
 794
 795 See L</"Packed Color Data"> for information on the format of packed
 796 color data.
 797
 798 =item *
 799
 800 C<type> - the type of pixel data supplied.  If you supply an array
 801 reference of object then this is determined automatically.  If you
 802 supply packed color data this defaults to C<'8bit'>, if your data is
 803 packed floating point color data then set this to C<'float'>.
 804
 805 You can use C<float> or C<8bit> samples with any image.
 806
 807 If this is 'index' then pixels should be either an array of palette
 808 color indexes or a packed string of color indexes.
 809
 810 =back
 811
 812 Returns the number of pixels set.
 813
 814 Each of the following sets 5 pixels from (5, 10) through (9, 10) to
 815 blue, red, blue, red, blue:
 816
 817   my $red_color = Imager::Color->new(255, 0, 0);
 818   my $blue_color = Imager::Color->new(0, 0, 255);
 819
 820   $image->setscanline(y=>10, x=>5, pixels=>
 821                       [ ($blue_color, $red_color) x 2, $blue_color ]);
 822
 823   # use floating point color instead, for 16-bit plus images
 824   my $red_colorf = Imager::Color::Float->new(1.0, 0, 0);
 825   my $blue_colorf = Imager::Color::Float->new(0, 0, 1.0);
 826
 827   $image->setscanline(y=>10, x=>5, pixels=>
 828                       [ ($blue_colorf, $red_colorf) x 2, $blue_colorf ]);
 829
 830   # packed 8-bit data
 831   $image->setscanline(y=>10, x=>5, pixels=>
 832                       pack("C*", ((0, 0, 255, 255), (255, 0, 0, 255)) x 2,
 833                             (0, 0, 255, 255)));
 834
 835   # packed floating point samples
 836   $image->setscanline(y=>10, x=>5, type=>'float', pixels=>
 837                       pack("d*", ((0, 0, 1.0, 1.0), (1.0, 0, 0, 1.0)) x 2,
 838                             (0, 0, 1.0, 1.0)));
 839
 840
 841 Copy even rows from one image to another:
 842
 843   for (my $y = 0; $y < $im2->getheight; $y+=2) {
 844     $im1->setscanline(y=>$y,
 845                       pixels=>scalar($im2->getscanline(y=>$y)));
 846   }
 847
 848
 849 Set the blue channel to 0 for all pixels in an image.  This could be
 850 done with convert too:
 851
 852   for my $y (0..$im->getheight-1) {
 853     my $row = $im->getscanline(y=>$y);
 854     $row =~ s/(..).(.)/$1\0$2/gs;
 855     $im->setscanline(y=>$y, pixels=>$row);
 856   }
 857
 858 =item getscanline()
 859
 860 Read all or part of a horizontal line of pixels from an image.  This
 861 method is most useful in conjunction with L</setscanline>.
 862
 863 The parameters you can pass are:
 864
 865 =over
 866
 867 =item *
 868
 869 C<y> - vertical position of the scan line.  This parameter is required.
 870
 871 =item *
 872
 873 C<x> - position to start on the scan line.  Default: 0
 874
 875 =item *
 876
 877 C<width> - number of pixels to read.  Default: $img->getwidth - x
 878
 879 =item *
 880
 881 C<type> - the type of pixel data to return.  Default: C<8bit>.
 882
 883 Permitted values are C<8bit> and C<float> and C<index>.
 884
 885 =back
 886
 887 In list context this method will return a list of Imager::Color
 888 objects when I<type> is C<8bit>, or a list of Imager::Color::Float
 889 objects when I<type> if C<float>, or a list of integers when I<type>
 890 is C<index>.
 891
 892 In scalar context this returns a packed 8-bit pixels when I<type> is
 893 C<8bit>, or a list of packed floating point pixels when I<type> is
 894 C<float>, or packed palette color indexes when I<type> is C<index>.
 895
 896 The values of samples for which the image does not have channels is
 897 undefined.  For example, for a single channel image the values of
 898 channels 1 through 3 are undefined.
 899
 900 Check image for a given color:
 901
 902   my $found;
 903   YLOOP: for my $y (0..$img->getheight-1) {
 904     my @colors = $img->getscanline(y=>$y);
 905     for my $color (@colors) {
 906       my ($red, $green, $blue, $alpha) = $color->rgba;
 907       if ($red == $test_red && $green == $test_green && $blue == $test_blue
 908           && $alpha == $test_alpha) {
 909         ++$found;
 910         last YLOOP;
 911       }
 912     }
 913   }
 914
 915 Or do it using packed data:
 916
 917   my $found;
 918   my $test_packed = pack("CCCC", $test_red, $test_green, $test_blue,
 919                          $test_alpha);
 920   YLOOP: for my $y (0..$img->getheight-1) {
 921     my $colors = $img->getscanline(y=>$y);
 922     while (length $colors) {
 923       if (substr($colors, 0, 4, '') eq $test_packed) {
 924         ++$found;
 925         last YLOOP;
 926       }
 927     }
 928   }
 929
 930 Some of the examples for L</setscanline> for more examples.
 931
 932 =item getsamples()
 933
 934 Read specified channels from all or part of a horizontal line of
 935 pixels from an image.
 936
 937 The parameters you can pass are:
 938
 939 =over
 940
 941 =item *
 942
 943 C<y> - vertical position of the scan line.  This parameter is required.
 944
 945 =item *
 946
 947 C<x> - position to start on the scan line.  Default: 0
 948
 949 =item *
 950
 951 C<width> - number of pixels to read.  Default: C<< $img->getwidth - x >>
 952
 953 =item *
 954
 955 C<type> - the type of sample data to return.  Default: C<8bit>.
 956
 957 Permitted values are C<8bit> and C<float>.
 958
 959 As of Imager 0.61 this can be C<16bit> only for 16 bit images.
 960
 961 =item *
 962
 963 C<channels> - a reference to an array of channels to return, where 0
 964 is the first channel.  Default: C<< [ 0 .. $self->getchannels()-1 ] >>
 965
 966 =item *
 967
 968 C<target> - if an array reference is supplied in target then the samples
 969 will be stored here instead of being returned.
 970
 971 =item *
 972
 973 C<offset> - the offset within the array referenced by I<target>
 974
 975 =back
 976
 977 In list context this will return a list of integers between 0 and 255
 978 inclusive when I<type> is C<8bit>, or a list of floating point numbers
 979 between 0.0 and 1.0 inclusive when I<type> is C<float>.
 980
 981 In scalar context this will return a string of packed bytes, as with
 982 C< pack("C*", ...) > when I<type> is C<8bit> or a string of packed
 983 doubles as with C< pack("d*", ...) > when I<type> is C<float>.
 984
 985 If the I<target> option is supplied then only a count of samples is
 986 returned.
 987
 988 Example: Check if any pixels in an image have a non-zero alpha
 989 channel:
 990
 991   my $has_coverage;
 992   for my $y (0 .. $img->getheight()-1) {
 993     my $alpha = $img->getsamples(y=>$y, channels=>[0]);
 994     if ($alpha =~ /[^\0]/) {
 995       ++$has_coverage;
 996       last;
 997     }
 998   }
 999
1000 Example: Convert a 2 channel gray image into a 4 channel RGBA image:
1001
1002   # this could be done with convert() instead
1003   my $out = Imager->new(xsize => $src->getwidth(),
1004                         ysize => $src->getheight(),
1005                         channels => 4);
1006   for my $y ( 0 .. $src->getheight()-1 ) {
1007     my $data = $src->getsamples(y=>$y, channels=>[ 0, 0, 0, 1 ]);
1008     $out->setscanline(y=>$y, pixels=>$data);
1009   }
1010
1011 Retrieve 16-bit samples:
1012
1013   if ($img->bits == 16) {
1014     my @samples;
1015     $img->getsamples(x => 0, y => $y, target => \@samples, type => '16bit');
1016   }
1017
1018 =item setsamples()
1019
1020 This allows writing of samples back to some images.  Currently this is
1021 only supported for 16-bit/sample images.
1022
1023 Parameters:
1024
1025 =over
1026
1027 =item *
1028
1029 C<y> - vertical position of the scan line.  This parameter is required.
1030
1031 =item *
1032
1033 C<x> - position to start on the scan line.  Default: 0
1034
1035 =item *
1036
1037 C<width> - number of pixels to write.  Default: C<< $img->getwidth - x >>.
1038 The minimum of this and the number of pixels represented by the
1039 samples provided will be written.
1040
1041 =item *
1042
1043 C<type> - the type of sample data to write.  This parameter is required.
1044
1045 As of Imager 0.61 this can only be C<16bit> only for 16 bit images.
1046
1047 =item *
1048
1049 C<channels> - a reference to an array of channels to return, where 0 is
1050 the first channel.  Default: C<< [ 0 .. $self->getchannels()-1 ] >>
1051
1052 =item *
1053
1054 C<data> - a reference to an array of samples to write.  Required.
1055
1056 =item *
1057
1058 C<offset> - the starting offset within the array referenced by I<data>
1059
1060 =back
1061
1062 Returns the number of samples written.
1063
1064 =back
1065
1066 =head1 Packed Color Data
1067
1068 The getscanline() and setscanline() functions can work with pixels
1069 packed into scalars.  This is useful to remove the cost of creating
1070 color objects, but should only be used when performance is an issue.
1071
1072 Packed data can either be 1 byte per sample or 1 double per sample.
1073
1074 Each pixel returned by getscanline() or supplied to setscanline()
1075 contains 4 samples, even if the image has fewer then 4 channels.  The
1076 values of the extra samples as returned by getscanline() is not
1077 specified.  The extra samples passed to setscanline() are ignored.
1078
1079 To produce packed 1 byte/sample pixels, use the pack C<C> template:
1080
1081   my $packed_8bit_pixel = pack("CCCC", $red, $blue, $green, $alpha);
1082
1083 To produce packed double/sample pixels, use the pack C<d> template:
1084
1085   my $packed_float_pixel = pack("dddd", $red, $blue, $green, $alpha);
1086
1087 If you use a I<type> parameter of C<index> then the values are palette
1088 color indexes, not sample values:
1089
1090   my $im = Imager->new(xsize => 100, ysize => 100, type => 'paletted');
1091   my $black_index = $im->addcolors(colors => [ 'black' ]);
1092   my $red_index = $im->addcolors(colors => [ 'red' ]);
1093   # 2 pixels
1094   my $packed_index_data = pack("C*", $black_index, $red_index);
1095   $im->setscanline(y => $y, pixels => $packed_index_data, type => 'index');
1096
1097 =head1 Combine Types
1098
1099 Some methods accept a C<combine> parameter, this can be any of the
1100 following:
1101
1102 =over
1103
1104 =item C<none>
1105
1106 The fill pixel replaces the target pixel.
1107
1108 =item C<normal>
1109
1110 The fill pixels alpha value is used to combine it with the target pixel.
1111
1112 =item C<multiply>
1113
1114 =item C<mult>
1115
1116 Each channel of fill and target is multiplied, and the result is
1117 combined using the alpha channel of the fill pixel.
1118
1119 =item C<dissolve>
1120
1121 If the alpha of the fill pixel is greater than a random number, the
1122 fill pixel is alpha combined with the target pixel.
1123
1124 =item C<add>
1125
1126 The channels of the fill and target are added together, clamped to the range of the samples and alpha combined with the target.
1127
1128 =item C<subtract>
1129
1130 The channels of the fill are subtracted from the target, clamped to be
1131 >= 0, and alpha combined with the target.
1132
1133 =item C<diff>
1134
1135 The channels of the fill are subtracted from the target and the
1136 absolute value taken this is alpha combined with the target.
1137
1138 =item C<lighten>
1139
1140 The higher value is taken from each channel of the fill and target
1141 pixels, which is then alpha combined with the target.
1142
1143 =item C<darken>
1144
1145 The higher value is taken from each channel of the fill and target
1146 pixels, which is then alpha combined with the target.
1147
1148 =item C<hue>
1149
1150 The combination of the saturation and value of the target is combined
1151 with the hue of the fill pixel, and is then alpha combined with the
1152 target.
1153
1154 =item C<sat>
1155
1156 The combination of the hue and value of the target is combined
1157 with the saturation of the fill pixel, and is then alpha combined with the
1158 target.
1159
1160 =item C<value>
1161
1162 The combination of the hue and value of the target is combined
1163 with the value of the fill pixel, and is then alpha combined with the
1164 target.
1165
1166 =item C<color>
1167
1168 The combination of the value of the target is combined with the hue
1169 and saturation of the fill pixel, and is then alpha combined with the
1170 target.
1171
1172 =back
1173
1174 =over
1175
1176 =item combines()
1177
1178 Returns a list of possible combine types.
1179
1180 =back
1181
1182 =head1 BUGS
1183
1184 box() does not support anti-aliasing yet.  Default color is not
1185 unified yet.
1186
1187 =head1 AUTHOR
1188
1189 Tony Cook <tony@imager.perl.org>, Arnar M. Hrafnkelsson.
1190
1191 =head1 SEE ALSO
1192
1193 L<Imager>(3), L<Imager::Cookbook>(3)
1194
1195 =head1 REVISION
1196
1197 $Revision$
1198
1199 =cut