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