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