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.  For non antialiasing operation all coordinates are
  77 rounded towards the nearest integer.  For antialiased operations floating
  78 point coordinates are used.
  79
  80 Drawing is assumed to take place in a coordinate system of infinite
  81 resolution.  This is the typical convention and really only matters when
  82 it is necessary to check for off-by-one cases.  Typically it's usefull to
  83 think of C<(10, 20)> as C<(10.00, 20.00)> and consider the consiquences.
  84
  85 =head2 Color Parameters
  86
  87 X<color parameters>The C<color> parameter for any of the drawing
  88 methods can be an L<Imager::Color> object, a simple scalar that
  89 Imager::Color can understand, a hashref of parameters that
  90 Imager::Color->new understands, or an arrayref of red, green, blue
  91 values, for example:
  92
  93   $image->box(..., color=>'red');
  94   $image->line(..., color=>'#FF0000');
  95   $image->flood_fill(..., color=>[ 255, 0, 255 ]);
  96
  97 =head2 Fill Parameters
  98
  99 X<fill parameters>All filled primitives, i.e. C<arc()>, C<box()>,
 100 C<circle()>, C<polygon()> and the C<flood_fill()> method can take a
 101 C<fill> parameter instead of a C<color> parameter which can either be
 102 an Imager::Fill object, or a reference to a hash containing the
 103 parameters used to create the fill, for example:
 104
 105   $image->box(..., fill=>{ hatch => 'check1x1' });
 106   my $fillimage = Imager->new;
 107   $fillimage->read(file=>$somefile) or die;
 108   $image->flood_fill(..., fill=>{ image=>$fillimage });
 109
 110 Currently you can create opaque or transparent plain color fills,
 111 hatched fills, image based fills and fountain fills.  See
 112 L<Imager::Fill> for more information.
 113
 114 =head2 List of primitives
 115
 116 =over
 117
 118 =item line
 119
 120   $img->line(color=>$green, x1=>10, x2=>100,
 121                             y1=>20, y2=>50, aa=>1, endp=>1 );
 122
 123 X<line method>Draws a line from (x1,y1) to (x2,y2).  The endpoint
 124 (x2,y2) is drawn by default.  If endp of 0 is specified then the
 125 endpoint will not be drawn.  If C<aa> is set then the line will be
 126 drawn antialiased.  The I<antialias> parameter is still available for
 127 backwards compatibility.
 128
 129 Parameters:
 130
 131 =over
 132
 133 =item *
 134
 135 x1, y1 - starting point of the line.  Required.
 136
 137 =item *
 138
 139 x2, y2 - end point of the line. Required.
 140
 141 =item *
 142
 143 color - the color of the line.  See L<"Color Parameters">.  Default:
 144 black.
 145
 146 =item *
 147
 148 endp - if zero the end point of the line is not drawn.  Default: 1 -
 149 the end point is drawn.  This is useful to set to 0 when drawning a
 150 series of connected lines.
 151
 152 =item *
 153
 154 aa - if true the line is drawn anti-aliased.  Default: 0.
 155
 156 =back
 157
 158 =item polyline
 159
 160   $img->polyline(points=>[[$x0,$y0],[$x1,$y1],[$x2,$y2]],color=>$red);
 161   $img->polyline(x=>[$x0,$x1,$x2], y=>[$y0,$y1,$y2], aa=>1);
 162
 163 X<polyline method>Polyline is used to draw multilple lines between a
 164 series of points.  The point set can either be specified as an
 165 arrayref to an array of array references (where each such array
 166 represents a point).  The other way is to specify two array
 167 references.
 168
 169 The I<antialias> parameter is still available for backwards compatibility.
 170
 171 =over
 172
 173 =item *
 174
 175 points - a reference to an array of references to arrays containing
 176 the co-ordinates of the points in the line, for example:
 177
 178   my @points = ( [ 0, 0 ], [ 100, 0 ], [ 100, 100 ], [ 0, 100 ] );
 179   $img->polyline(points => \@points);
 180
 181 =item *
 182
 183 x, y - each is an array of x or y ordinates.  This is an alternative
 184 to supplying the C<points> parameter.
 185
 186   # same as the above points example
 187   my @x = ( 0, 100, 100, 0 );
 188   my @y = ( 0, 0, 100, 100 );
 189   $img->polyline(x => \@x, y => \@y);
 190
 191 =item *
 192
 193 color - the color of the line.  See L<"Color Parameters">.  Default:
 194 black.
 195
 196 =item *
 197
 198 aa - if true the line is drawn anti-aliased.  Default: 0.  Can also be
 199 supplied as C<antialias> for backward compatibility.
 200
 201 =back
 202
 203 =item box
 204
 205   $blue = Imager::Color->new( 0, 0, 255 );
 206   $img->box(color => $blue, xmin=>10, ymin=>30, xmax=>200, ymax=>300,
 207             filled=>1);
 208
 209 X<box method>If any of the edges of the box are ommited it will snap
 210 to the outer edge of the image in that direction.  If C<filled> is
 211 ommited the box is drawn as an outline.  Instead of a color it is
 212 possible to use a C<fill> pattern:
 213
 214   $fill = Imager::Fill->new(hatch=>'stipple');
 215   $img->box(fill=>$fill);  # fill entire image with a given fill pattern
 216
 217   $img->box(xmin=>10, ymin=>30, xmax=>150, ymax=>60,
 218             fill => { hatch=>'cross2' });
 219
 220 Also if a color is omitted a color with (255,255,255,255) is used
 221 instead.  [NOTE: This may change to use C<$img-E<gt>fgcolor()> in the future].
 222
 223 Box does not support fractional coordinates yet.
 224
 225 Parameters:
 226
 227 =over
 228
 229 =item *
 230
 231 xmin - left side of the box.  Default: 0 (left edge of the image)
 232
 233 =item *
 234
 235 ymin - top side of the box.  Default: 0 (top edge of the image)
 236
 237 =item *
 238
 239 xmax - right side of the box.  Default: $img->getwidth-1. (right edge
 240 of the image)
 241
 242 =item *
 243
 244 ymax - bottom side of the box.  Default: $img->getheight-1. (bottom
 245 edge of the image)
 246
 247 Note: xmax and ymax are I<inclusive> - the number of pixels drawn for
 248 a filled box is (xmax-xmin+1) * (ymax-ymin+1).
 249
 250 =item *
 251
 252 box - a reference to an array of (left, top, right, bottom)
 253 co-ordinates.  This is an alternative to supplying xmin, ymin, xmax,
 254 ymax and overrides their values.
 255
 256 =item *
 257
 258 color - the color of the line.  See L<"Color Parameters">.  Default:
 259 white.  This is ignored if the filled parameter
 260
 261 =item *
 262
 263 filled - if non-zero the box is filled with I<color> instead of
 264 outlined.  Default: an outline is drawn.
 265
 266 =item *
 267
 268 fill - the fill for the box.  If this is supplied then the box will be
 269 filled.  See L<"Fill Parameters">.
 270
 271 =back
 272
 273 =item arc
 274
 275   $img->arc(color=>$red, r=>20, x=>200, y=>100, d1=>10, d2=>20 );
 276
 277 This creates a filled red arc with a 'center' at (200, 100) and spans
 278 10 degrees and the slice has a radius of 20. [NOTE: arc has a BUG in
 279 it right now for large differences in angles.]
 280 It's also possible to supply a C<fill> parameter.
 281
 282 Parameters:
 283
 284 =over
 285
 286 =item *
 287
 288 x, y - center of the filled arc.  Default: center of the image.
 289
 290 =item *
 291
 292 r - radius of the arc.  Default: 1/3 of min(image height, image width).
 293
 294 =item *
 295
 296 d1 - starting angle of the arc, in degrees.  Default: 0
 297
 298 =item *
 299
 300 d2 - ending angle of the arc, in degrees.  Default: 361.
 301
 302 =item *
 303
 304 color - the color of the filled arc.  See L<"Color Parameters">.
 305 Default: white.  Overridden by C<fill>.
 306
 307 =item *
 308
 309 fill - the fill for the filled arc.  See L<"Fill Parameters">
 310
 311 =item *
 312
 313 aa - if true the filled arc is drawn anti-aliased.  Default: false.
 314
 315 Anti-aliased arc() is experimental for now, I'm not entirely happy
 316 with the results in some cases.
 317
 318 =back
 319
 320   # arc going through angle zero:
 321   $img->arc(d1=>320, d2=>40, x=>100, y=>100, r=>50, color=>'blue');
 322
 323   # complex fill arc
 324   $img->arc(d1=>135, d2=>45, x=>100, y=>150, r=>50,
 325             fill=>{ solid=>'red', combine=>'diff' });
 326
 327 =item circle
 328
 329   $img->circle(color=>$green, r=>50, x=>200, y=>100, aa=>1, filled=>1);
 330
 331 This creates an antialiased green circle with its center at (200, 100)
 332 and has a radius of 50.  It's also possible to supply a C<fill> parameter
 333 instead of a color parameter.
 334
 335   $img->circle(r => 50, x=> 150, y => 150, fill=>{ hatch => 'stipple' });
 336
 337 The circle is always filled but that might change, so always pass a
 338 filled=>1 parameter if you want it to be filled.
 339
 340 =over
 341
 342 =item *
 343
 344 x, y - center of the filled circle.  Default: center of the image.
 345
 346 =item *
 347
 348 r - radius of the circle.  Default: 1/3 of min(image height, image width).
 349
 350 =item *
 351
 352 color - the color of the filled circle.  See L<"Color Parameters">.
 353 Default: white.  Overridden by C<fill>.
 354
 355 =item *
 356
 357 fill - the fill for the filled circle.  See L<"Fill Parameters">
 358
 359 =item *
 360
 361 aa - if true the filled circle is drawn anti-aliased.  Default: false.
 362
 363 =back
 364
 365 =item polygon
 366
 367   $img->polygon(points=>[[$x0,$y0],[$x1,$y1],[$x2,$y2]],color=>$red);
 368   $img->polygon(x=>[$x0,$x1,$x2], y=>[$y0,$y1,$y2], fill=>$fill);
 369
 370 Polygon is used to draw a filled polygon.  Currently the polygon is
 371 always drawn antialiased, although that will change in the future.
 372 Like other antialiased drawing functions its coordinates can be
 373 specified with floating point values.  As with other filled shapes
 374 it's possible to use a C<fill> instead of a color.
 375
 376 =over
 377
 378 =item *
 379
 380 points - a reference to an array of references to arrays containing
 381 the co-ordinates of the points in the line, for example:
 382
 383   my @points = ( [ 0, 0 ], [ 100, 0 ], [ 100, 100 ], [ 0, 100 ] );
 384   $img->polygon(points => \@points);
 385
 386 =item *
 387
 388 x, y - each is an array of x or y ordinates.  This is an alternative
 389 to supplying the C<points> parameter.
 390
 391   # same as the above points example
 392   my @x = ( 0, 100, 100, 0 );
 393   my @y = ( 0, 0, 100, 100 );
 394   $img->polygon(x => \@x, y => \@y);
 395
 396 =item *
 397
 398 color - the color of the filled polygon.  See L<"Color Parameters">.
 399 Default: black.  Overridden by C<fill>.
 400
 401 =item *
 402
 403 fill - the fill for the filled circle.  See L<"Fill Parameters">
 404
 405 =back
 406
 407 =item flood_fill
 408
 409 You can fill a region that all has the same color using the
 410 flood_fill() method, for example:
 411
 412   $img->flood_fill(x=>50, y=>50, color=>$color);
 413
 414 will fill all regions the same color connected to the point (50, 50).
 415
 416 You can also fill with a complex fill:
 417
 418   $img->flood_fill(x=>50, y=>50, fill=>{ hatch=>'cross1x1' });
 419
 420 Parameters:
 421
 422 =over
 423
 424 =item *
 425
 426 x, y - the start point of the fill.
 427
 428 =item *
 429
 430 color - the color of the filled area.  See L<"Color Parameters">.
 431 Default: white.  Overridden by C<fill>.
 432
 433 =item *
 434
 435 fill - the fill for the filled area.  See L<"Fill Parameters">
 436
 437 =back
 438
 439 =item setpixel
 440
 441   $img->setpixel(x=>50, y=>70, color=>$color);
 442   $img->setpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40], color=>$color);
 443
 444 setpixel() is used to set one or more individual pixels.
 445
 446 Parameters:
 447
 448 =over
 449
 450 =item *
 451
 452 x, y - either integers giving the co-ordinates of the pixel to set or
 453 array references containing a set of pixels to be set.
 454
 455 =item *
 456
 457 color - the color of the pixels drawn.  See L<"Color Parameters">.
 458 Default: white.
 459
 460 =back
 461
 462 =item getpixel
 463
 464   my $color = $img->getpixel(x=>50, y=>70);
 465   my @colors = $img->getpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40]);
 466   my $colors_ref = $img->getpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40]);
 467
 468 getpixel() is used to retrieve one or more individual pixels.
 469
 470 For either method you can supply a single set of co-ordinates as
 471 scalar x and y parameters, or set each to an arrayref of ordinates.
 472
 473 When called with arrays, getpixel() will return a list of colors in
 474 list context, and an arrayref in scalar context.
 475
 476 To receive floating point colors from getpixel, set the C<type>
 477 parameter to 'float'.
 478
 479 Parameters:
 480
 481 =over
 482
 483 =item *
 484
 485 x, y - either integers giving the co-ordinates of the pixel to set or
 486 array references containing a set of pixels to be set.
 487
 488 =item *
 489
 490 type - the type of color object to return, either C<'8bit'> for
 491 Imager::Color objects or C<'float'> for Imager::Color::Float objects.
 492 Default: C<'8bit'>.
 493
 494 =back
 495
 496 =item string
 497
 498   my $font = Imager::Font->new(file=>"foo.ttf");
 499   $img->string(x => 50, y => 70,
 500                string => "Hello, World!",
 501                font => $font,
 502                size => 30,
 503                aa => 1,
 504                color => 'white');
 505
 506 Draws text on the image.
 507
 508 Parameters:
 509
 510 =over
 511
 512 =item *
 513
 514 x, y - the point to draw the text from.  If C<align> is 0 this is the
 515 top left of the string.  If C<align> is 1 (the default) then this is
 516 the left of the string on the baseline.  Required.
 517
 518 =item *
 519
 520 string - the text to draw.  Required unless you supply the C<text>
 521 parameter.
 522
 523 =item *
 524
 525 font - an L<Imager::Font> object representing the font to draw the
 526 text with.  Required.
 527
 528 =item *
 529
 530 aa - if non-zero the output will be anti-aliased.  Default: the value
 531 set in Imager::Font->new() or 0 if not set.
 532
 533 =item *
 534
 535 align - if non-zero the point supplied in (x,y) will be on the
 536 base-line, if zero then (x,y) will be at the top-left of the string.
 537
 538 ie. if drawing the string "yA" and align is 0 the point (x,y) will
 539 aligned with the top of the A.  If align is 1 (the default) it will be
 540 aligned with the baseline of the font, typically bottom of the A,
 541 depending on the font used.
 542
 543 Default: the value set in Imager::Font->new, or 1 if not set.
 544
 545 =item *
 546
 547 channel - if present, the text will be written to the specified
 548 channel of the image and the color parameter will be ignore.
 549
 550 =item *
 551
 552 color - the color to draw the text in.  Default: the color supplied to
 553 Imager::Font->new, or red if none.
 554
 555 =item *
 556
 557 size - the point size to draw the text at.  Default: the size supplied
 558 to Imager::Font->new, or 15.
 559
 560 =item *
 561
 562 sizew - the width scaling to draw the text at.  Default: the value of
 563 C<size>.
 564
 565 =item *
 566
 567 utf8 - for drivers that support it, treat the string as UTF8 encoded.
 568 For versions of perl that support Unicode (5.6 and later), this will
 569 be enabled automatically if the C<string> parameter is already a UTF8
 570 string. See L<Imager::Font/"UTF8"> for more information.
 571
 572 =item *
 573
 574 vlayout - for drivers that support it, draw the text vertically.
 575 Note: I haven't found a font that has the appropriate metrics yet.
 576
 577 =item *
 578
 579 text - alias for the C<string> parameter.
 580
 581 =back
 582
 583 On error, string() returns false and you can use $img->errstr to get
 584 the reason for the error.
 585
 586 =item align_string
 587
 588 Draws text aligned around a point on the image.
 589
 590   # "Hello" centered at 100, 100 in the image.
 591   my ($left, $top, $right, $bottom) =
 592     $img->align_string(string=>"Hello",
 593                        x=>100, y=>100,
 594                        halign=>'center', valign=>'center',
 595                        font=>$font);
 596
 597 Parameters:
 598
 599 =over
 600
 601 =item *
 602
 603 x, y - the point to draw the text from.  If C<align> is 0 this is the
 604 top left of the string.  If C<align> is 1 (the default) then this is
 605 the left of the string on the baseline.  Required.
 606
 607 =item *
 608
 609 string - the text to draw.  Required unless you supply the C<text> parameter.
 610
 611 =item *
 612
 613 font - an L<Imager::Font> object representing the font to draw the
 614 text with.  Required.
 615
 616 =item *
 617
 618 aa - if non-zero the output will be anti-aliased
 619
 620 =item *
 621
 622 valign - vertical alignment of the text against (x,y)
 623
 624 =over
 625
 626 =item *
 627
 628 top - Point is at the top of the text.
 629
 630 =item *
 631
 632 bottom - Point is at the bottom of the text.
 633
 634 =item *
 635
 636 baseline - Point is on the baseline of the text.  This is the default.
 637
 638 =item *
 639
 640 center - Point is vertically centered within the text.
 641
 642 =back
 643
 644 =item *
 645
 646 halign - horizontal alignment of the text against (x,y)
 647
 648 =over
 649
 650 =item *
 651
 652 left - The point is at the left of the text.  This is the default.
 653
 654 =item *
 655
 656 start - The point is at the start point of the text.
 657
 658 =item *
 659
 660 center - The point is horizontally centered within the text.
 661
 662 =item *
 663
 664 right - The point is at the right end of the text.
 665
 666 =item *
 667
 668 end - The point is at the end point of the text.
 669
 670 =back
 671
 672 =item *
 673
 674 channel - if present, the text will be written to the specified
 675 channel of the image and the color parameter will be ignore.
 676
 677 =item *
 678
 679 color - the color to draw the text in.  Default: the color supplied to
 680 Imager::Font->new, or red if none.
 681
 682 =item *
 683
 684 size - the point size to draw the text at.  Default: the size supplied
 685 to Imager::Font->new, or 15.
 686
 687 =item *
 688
 689 sizew - the width scaling to draw the text at.  Default: the value of
 690 C<size>.
 691
 692 =item *
 693
 694 utf8 - for drivers that support it, treat the string as UTF8 encoded.
 695 For versions of perl that support Unicode (5.6 and later), this will
 696 be enabled automatically if the C<string> parameter is already a UTF8
 697 string. See L<Imager::Font/"UTF8"> for more information.
 698
 699 =item *
 700
 701 vlayout - for drivers that support it, draw the text vertically.
 702 Note: I haven't found a font that has the appropriate metrics yet.
 703
 704 =item *
 705
 706 text - alias for the C<string> parameter.
 707
 708 =back
 709
 710 On success returns a list of bounds of the drawn text, in the order
 711 left, top, right, bottom.
 712
 713 On error, align_string() returns an empty list and you can use
 714 $img->errstr to get the reason for the error.
 715
 716 =item setscanline
 717
 718 Set all or part of a horizontal line of pixels to an image.  This
 719 method is most useful in conjuction with L</getscanline>.
 720
 721 The parameters you can pass are:
 722
 723 =over
 724
 725 =item *
 726
 727 y - vertical position of the scanline.  This parameter is required.
 728
 729 =item *
 730
 731 x - position to start on the scanline.  Default: 0
 732
 733 =item *
 734
 735 pixels - either a reference to an array containing Imager::Color
 736 objects, an reference to an array containing Imager::Color::Float
 737 objects or a scalar containing packed color data.
 738
 739 See L</"Packed Color Data"> for information on the format of packed
 740 color data.
 741
 742 =item *
 743
 744 type - the type of pixel data supplied.  If you supply an array
 745 reference of object then this is determined automatically.  If you
 746 supply packed color data this defaults to '8bit', if your data is
 747 packed floating point color data then set this to 'float'.
 748
 749 You can use float or 8bit samples with any image.
 750
 751 =back
 752
 753 Returns the number of pixels set.
 754
 755 Each of the following sets 5 pixels from (5, 10) through (9, 10) to
 756 blue, red, blue, red, blue:
 757
 758   my $red_color = Imager::Color->new(255, 0, 0);
 759   my $blue_color = Imager::Color->new(0, 0, 255);
 760
 761   $image->setscanline(y=>10, x=>5, pixels=>
 762                       [ ($blue_color, $red_color) x 2, $blue_color ]);
 763
 764   # use floating point color instead, for 16-bit plus images
 765   my $red_colorf = Imager::Color::Float->new(1.0, 0, 0);
 766   my $blue_colorf = Imager::Color::Float->new(0, 0, 1.0);
 767
 768   $image->setscanline(y=>10, x=>5, pixels=>
 769                       [ ($blue_colorf, $red_colorf) x 2, $blue_colorf ]);
 770
 771   # packed 8-bit data
 772   $image->setscanline(y=>10, x=>5, pixels=>
 773                       pack("C*", ((0, 0, 255, 255), (255, 0, 0, 255)) x 2,
 774                             (0, 0, 255, 255)));
 775
 776   # packed floating point samples
 777   $image->setscanline(y=>10, x=>5, type=>'float', pixels=>
 778                       pack("d*", ((0, 0, 1.0, 1.0), (1.0, 0, 0, 1.0)) x 2,
 779                             (0, 0, 1.0, 1.0)));
 780
 781
 782 Copy even rows from one image to another:
 783
 784   for (my $y = 0; $y < $im2->getheight; $y+=2) {
 785     $im1->setscanline(y=>$y,
 786                       pixels=>scalar($im2->getscanline(y=>$y)));
 787   }
 788
 789
 790 Set the blue channel to 0 for all pixels in an image.  This could be
 791 done with convert too:
 792
 793   for my $y (0..$im->getheight-1) {
 794     my $row = $im->getscanline(y=>$y);
 795     $row =~ s/(..).(.)/$1\0$2/gs;
 796     $im->setscanline(y=>$y, pixels=>$row);
 797   }
 798
 799 =item getscanline
 800
 801 Read all or part of a horizonatal line of pixels from an image.  This
 802 method is most useful in conjunction with L</setscanline>.
 803
 804 The parameters you can pass are:
 805
 806 =over
 807
 808 =item *
 809
 810 y - vertical position of the scanline.  This parameter is required.
 811
 812 =item *
 813
 814 x - position to start on the scanline.  Default: 0
 815
 816 =item *
 817
 818 width - number of pixels to read.  Default: $img->getwidth - x
 819
 820 =item *
 821
 822 type - the type of pixel data to return.  Default: C<8bit>.
 823
 824 Permited values are C<8bit> and C<float>.
 825
 826 =back
 827
 828 In list context this method will return a list of Imager::Color
 829 objects when I<type> is C<8bit>, or a list of Imager::Color::Float
 830 objects when I<type> if C<float>.
 831
 832 In scalar context this returns a packed 8-bit pixels when I<type> is
 833 C<8bit>, or a list of packed floating point pixels when I<type> is
 834 C<float>.
 835
 836 The values of samples for which the image does not have channels is
 837 undefined.  For example, for a single channel image the values of
 838 channels 1 through 3 are undefined.
 839
 840 Check image for a given color:
 841
 842   my $found;
 843   YLOOP: for my $y (0..$img->getheight-1) {
 844     my @colors = $img->getscanline(y=>$y);
 845     for my $color (@colors) {
 846       my ($red, $green, $blue, $alpha) = $color->rgba;
 847       if ($red == $test_red && $green == $test_green && $blue == $test_blue
 848           && $alpha == $test_alpha) {
 849         ++$found;
 850         last YLOOP;
 851       }
 852     }
 853   }
 854
 855 Or do it using packed data:
 856
 857   my $found;
 858   my $test_packed = pack("CCCC", $test_red, $test_green, $test_blue,
 859                          $test_alpha);
 860   YLOOP: for my $y (0..$img->getheight-1) {
 861     my $colors = $img->getscanline(y=>$y);
 862     while (length $colors) {
 863       if (substr($colors, 0, 4, '') eq $test_packed) {
 864         ++$found;
 865         last YLOOP;
 866       }
 867     }
 868   }
 869
 870 Some of the examples for L</setscanline> for more examples.
 871
 872 =item getsamples
 873
 874 Read specified channels from all or part of a horizontal line of
 875 pixels from an image.
 876
 877 The parameters you can pass are:
 878
 879 =over
 880
 881 =item *
 882
 883 y - vertical position of the scanline.  This parameter is required.
 884
 885 =item *
 886
 887 x - position to start on the scanline.  Default: 0
 888
 889 =item *
 890
 891 width - number of pixels to read.  Default: $img->getwidth - x
 892
 893 =item *
 894
 895 type - the type of sample data to return.  Default: C<8bit>.
 896
 897 Permited values are C<8bit> and C<float>.
 898
 899 =item *
 900
 901 channels - a reference to an array of channels to return, where 0 is
 902 the first channel.  Default: C< [ 0 .. $self->getchannels()-1 ] >
 903
 904 =back
 905
 906 In list context this will return a list of integers between 0 and 255
 907 inclusive when I<type> is C<8bit>, or a list of floating point numbers
 908 between 0.0 and 1.0 inclusive when I<type> is C<float>.
 909
 910 In scalar context this will return a string of packed bytes, as with
 911 C< pack("C*", ...) > when I<type> is C<8bit> or a string of packed
 912 doubles as with C< pack("d*", ...) > when I<type> is C<float>.
 913
 914 Example: Check if any pixels in an image have a non-zero alpha
 915 channel:
 916
 917   my $has_coverage;
 918   for my $y (0 .. $img->getheight()-1) {
 919     my $alpha = $img->getsamples(y=>$y, channels=>[0]);
 920     if ($alpha =~ /[^\0]/) {
 921       ++$has_coverage;
 922       last;
 923     }
 924   }
 925
 926 Example: Convert a 2 channel grey image into a 4 channel RGBA image:
 927
 928   # this could be done with convert() instead
 929   my $out = Imager->new(xsize => $src->getwidth(),
 930                         ysize => $src->getheight(),
 931                         channels => 4);
 932   for my $y ( 0 .. $src->getheight()-1 ) {
 933     my $data = $src->getsamples(y=>$y, channels=>[ 0, 0, 0, 1 ]);
 934     $out->setscanline(y=>$y, pixels=>$data);
 935   }
 936
 937 =back
 938
 939 =head1 Packed Color Data
 940
 941 The getscanline() and setscanline() functions can work with pixels
 942 packed into scalars.  This is useful to remove the cost of creating
 943 color objects, but should only be used when performance is an issue.
 944
 945 Packed data can either be 1 byte per sample or 1 double per sample.
 946
 947 Each pixel returned by getscanline() or supplied to setscanline()
 948 contains 4 samples, even if the image has fewer then 4 channels.  The
 949 values of the extra samples as returned by getscanline() is not
 950 specified.  The extra samples passed to setscanline() are ignored.
 951
 952 To produce packed 1 byte/sample pixels, use the pack C<C> template:
 953
 954   my $packed_8bit_pixel = pack("CCCC", $red, $blue, $green, $alpha);
 955
 956 To produce packed double/sample pixels, use the pack C<d> template:
 957
 958   my $packed_float_pixel = pack("dddd", $red, $blue, $green, $alpha);
 959
 960 =head1 BUGS
 961
 962 box, arc, do not support antialiasing yet.  Arc, is only filled as of
 963 yet.  Default color is not unified yet.
 964
 965 =head1 AUTHOR
 966
 967 Tony Cook <tony@imager.perl.org>, Arnar M. Hrafnkelsson.
 968
 969 =head1 SEE ALSO
 970
 971 L<Imager>(3), L<Imager::Cookbook>(3)
 972
 973 =head1 REVISION
 974
 975 $Revision$
 976
 977 =cut