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 =item getpixel
 476
 477   my $color = $img->getpixel(x=>50, y=>70);
 478   my @colors = $img->getpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40]);
 479   my $colors_ref = $img->getpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40]);
 480
 481 getpixel() is used to retrieve one or more individual pixels.
 482
 483 For either method you can supply a single set of co-ordinates as
 484 scalar x and y parameters, or set each to an arrayref of ordinates.
 485
 486 When called with arrays, getpixel() will return a list of colors in
 487 list context, and an arrayref in scalar context.
 488
 489 To receive floating point colors from getpixel, set the C<type>
 490 parameter to 'float'.
 491
 492 Parameters:
 493
 494 =over
 495
 496 =item *
 497
 498 x, y - either integers giving the co-ordinates of the pixel to set or
 499 array references containing a set of pixels to be set.
 500
 501 =item *
 502
 503 type - the type of color object to return, either C<'8bit'> for
 504 Imager::Color objects or C<'float'> for Imager::Color::Float objects.
 505 Default: C<'8bit'>.
 506
 507 =back
 508
 509 =item string
 510
 511   my $font = Imager::Font->new(file=>"foo.ttf");
 512   $img->string(x => 50, y => 70,
 513                string => "Hello, World!",
 514                font => $font,
 515                size => 30,
 516                aa => 1,
 517                color => 'white');
 518
 519 Draws text on the image.
 520
 521 Parameters:
 522
 523 =over
 524
 525 =item *
 526
 527 x, y - the point to draw the text from.  If C<align> is 0 this is the
 528 top left of the string.  If C<align> is 1 (the default) then this is
 529 the left of the string on the baseline.  Required.
 530
 531 =item *
 532
 533 string - the text to draw.  Required unless you supply the C<text>
 534 parameter.
 535
 536 =item *
 537
 538 font - an L<Imager::Font> object representing the font to draw the
 539 text with.  Required.
 540
 541 =item *
 542
 543 aa - if non-zero the output will be anti-aliased.  Default: the value
 544 set in Imager::Font->new() or 0 if not set.
 545
 546 =item *
 547
 548 align - if non-zero the point supplied in (x,y) will be on the
 549 base-line, if zero then (x,y) will be at the top-left of the string.
 550
 551 ie. if drawing the string "yA" and align is 0 the point (x,y) will
 552 aligned with the top of the A.  If align is 1 (the default) it will be
 553 aligned with the baseline of the font, typically bottom of the A,
 554 depending on the font used.
 555
 556 Default: the value set in Imager::Font->new, or 1 if not set.
 557
 558 =item *
 559
 560 channel - if present, the text will be written to the specified
 561 channel of the image and the color parameter will be ignore.
 562
 563 =item *
 564
 565 color - the color to draw the text in.  Default: the color supplied to
 566 Imager::Font->new, or red if none.
 567
 568 =item *
 569
 570 size - the point size to draw the text at.  Default: the size supplied
 571 to Imager::Font->new, or 15.
 572
 573 =item *
 574
 575 sizew - the width scaling to draw the text at.  Default: the value of
 576 C<size>.
 577
 578 =item *
 579
 580 utf8 - for drivers that support it, treat the string as UTF8 encoded.
 581 For versions of perl that support Unicode (5.6 and later), this will
 582 be enabled automatically if the C<string> parameter is already a UTF8
 583 string. See L<Imager::Font/"UTF8"> for more information.
 584
 585 =item *
 586
 587 vlayout - for drivers that support it, draw the text vertically.
 588 Note: I haven't found a font that has the appropriate metrics yet.
 589
 590 =item *
 591
 592 text - alias for the C<string> parameter.
 593
 594 =back
 595
 596 On error, string() returns false and you can use $img->errstr to get
 597 the reason for the error.
 598
 599 =item align_string
 600
 601 Draws text aligned around a point on the image.
 602
 603   # "Hello" centered at 100, 100 in the image.
 604   my ($left, $top, $right, $bottom) =
 605     $img->align_string(string=>"Hello",
 606                        x=>100, y=>100,
 607                        halign=>'center', valign=>'center',
 608                        font=>$font);
 609
 610 Parameters:
 611
 612 =over
 613
 614 =item *
 615
 616 x, y - the point to draw the text from.  If C<align> is 0 this is the
 617 top left of the string.  If C<align> is 1 (the default) then this is
 618 the left of the string on the baseline.  Required.
 619
 620 =item *
 621
 622 string - the text to draw.  Required unless you supply the C<text> parameter.
 623
 624 =item *
 625
 626 font - an L<Imager::Font> object representing the font to draw the
 627 text with.  Required.
 628
 629 =item *
 630
 631 aa - if non-zero the output will be anti-aliased
 632
 633 =item *
 634
 635 valign - vertical alignment of the text against (x,y)
 636
 637 =over
 638
 639 =item *
 640
 641 top - Point is at the top of the text.
 642
 643 =item *
 644
 645 bottom - Point is at the bottom of the text.
 646
 647 =item *
 648
 649 baseline - Point is on the baseline of the text.  This is the default.
 650
 651 =item *
 652
 653 center - Point is vertically centered within the text.
 654
 655 =back
 656
 657 =item *
 658
 659 halign - horizontal alignment of the text against (x,y)
 660
 661 =over
 662
 663 =item *
 664
 665 left - The point is at the left of the text.  This is the default.
 666
 667 =item *
 668
 669 start - The point is at the start point of the text.
 670
 671 =item *
 672
 673 center - The point is horizontally centered within the text.
 674
 675 =item *
 676
 677 right - The point is at the right end of the text.
 678
 679 =item *
 680
 681 end - The point is at the end point of the text.
 682
 683 =back
 684
 685 =item *
 686
 687 channel - if present, the text will be written to the specified
 688 channel of the image and the color parameter will be ignore.
 689
 690 =item *
 691
 692 color - the color to draw the text in.  Default: the color supplied to
 693 Imager::Font->new, or red if none.
 694
 695 =item *
 696
 697 size - the point size to draw the text at.  Default: the size supplied
 698 to Imager::Font->new, or 15.
 699
 700 =item *
 701
 702 sizew - the width scaling to draw the text at.  Default: the value of
 703 C<size>.
 704
 705 =item *
 706
 707 utf8 - for drivers that support it, treat the string as UTF8 encoded.
 708 For versions of perl that support Unicode (5.6 and later), this will
 709 be enabled automatically if the C<string> parameter is already a UTF8
 710 string. See L<Imager::Font/"UTF8"> for more information.
 711
 712 =item *
 713
 714 vlayout - for drivers that support it, draw the text vertically.
 715 Note: I haven't found a font that has the appropriate metrics yet.
 716
 717 =item *
 718
 719 text - alias for the C<string> parameter.
 720
 721 =back
 722
 723 On success returns a list of bounds of the drawn text, in the order
 724 left, top, right, bottom.
 725
 726 On error, align_string() returns an empty list and you can use
 727 $img->errstr to get the reason for the error.
 728
 729 =item setscanline
 730
 731 Set all or part of a horizontal line of pixels to an image.  This
 732 method is most useful in conjuction with L</getscanline>.
 733
 734 The parameters you can pass are:
 735
 736 =over
 737
 738 =item *
 739
 740 y - vertical position of the scanline.  This parameter is required.
 741
 742 =item *
 743
 744 x - position to start on the scanline.  Default: 0
 745
 746 =item *
 747
 748 pixels - either a reference to an array containing Imager::Color
 749 objects, an reference to an array containing Imager::Color::Float
 750 objects or a scalar containing packed color data.
 751
 752 If C<type> is C<index> then this can either be a reference to an array
 753 of palette color indexes or a scalar containing packed indexes.
 754
 755 See L</"Packed Color Data"> for information on the format of packed
 756 color data.
 757
 758 =item *
 759
 760 type - the type of pixel data supplied.  If you supply an array
 761 reference of object then this is determined automatically.  If you
 762 supply packed color data this defaults to '8bit', if your data is
 763 packed floating point color data then set this to 'float'.
 764
 765 You can use float or 8bit samples with any image.
 766
 767 If this is 'index' then pixels should be either an array of palette
 768 color indexes or a packed string of color indexes.
 769
 770 =back
 771
 772 Returns the number of pixels set.
 773
 774 Each of the following sets 5 pixels from (5, 10) through (9, 10) to
 775 blue, red, blue, red, blue:
 776
 777   my $red_color = Imager::Color->new(255, 0, 0);
 778   my $blue_color = Imager::Color->new(0, 0, 255);
 779
 780   $image->setscanline(y=>10, x=>5, pixels=>
 781                       [ ($blue_color, $red_color) x 2, $blue_color ]);
 782
 783   # use floating point color instead, for 16-bit plus images
 784   my $red_colorf = Imager::Color::Float->new(1.0, 0, 0);
 785   my $blue_colorf = Imager::Color::Float->new(0, 0, 1.0);
 786
 787   $image->setscanline(y=>10, x=>5, pixels=>
 788                       [ ($blue_colorf, $red_colorf) x 2, $blue_colorf ]);
 789
 790   # packed 8-bit data
 791   $image->setscanline(y=>10, x=>5, pixels=>
 792                       pack("C*", ((0, 0, 255, 255), (255, 0, 0, 255)) x 2,
 793                             (0, 0, 255, 255)));
 794
 795   # packed floating point samples
 796   $image->setscanline(y=>10, x=>5, type=>'float', pixels=>
 797                       pack("d*", ((0, 0, 1.0, 1.0), (1.0, 0, 0, 1.0)) x 2,
 798                             (0, 0, 1.0, 1.0)));
 799
 800
 801 Copy even rows from one image to another:
 802
 803   for (my $y = 0; $y < $im2->getheight; $y+=2) {
 804     $im1->setscanline(y=>$y,
 805                       pixels=>scalar($im2->getscanline(y=>$y)));
 806   }
 807
 808
 809 Set the blue channel to 0 for all pixels in an image.  This could be
 810 done with convert too:
 811
 812   for my $y (0..$im->getheight-1) {
 813     my $row = $im->getscanline(y=>$y);
 814     $row =~ s/(..).(.)/$1\0$2/gs;
 815     $im->setscanline(y=>$y, pixels=>$row);
 816   }
 817
 818 =item getscanline
 819
 820 Read all or part of a horizonatal line of pixels from an image.  This
 821 method is most useful in conjunction with L</setscanline>.
 822
 823 The parameters you can pass are:
 824
 825 =over
 826
 827 =item *
 828
 829 y - vertical position of the scanline.  This parameter is required.
 830
 831 =item *
 832
 833 x - position to start on the scanline.  Default: 0
 834
 835 =item *
 836
 837 width - number of pixels to read.  Default: $img->getwidth - x
 838
 839 =item *
 840
 841 type - the type of pixel data to return.  Default: C<8bit>.
 842
 843 Permited values are C<8bit> and C<float> and C<index>.
 844
 845 =back
 846
 847 In list context this method will return a list of Imager::Color
 848 objects when I<type> is C<8bit>, or a list of Imager::Color::Float
 849 objects when I<type> if C<float>, or a list of integers when I<type>
 850 is C<index>.
 851
 852 In scalar context this returns a packed 8-bit pixels when I<type> is
 853 C<8bit>, or a list of packed floating point pixels when I<type> is
 854 C<float>, or packed palette color indexes when I<type> is C<index>.
 855
 856 The values of samples for which the image does not have channels is
 857 undefined.  For example, for a single channel image the values of
 858 channels 1 through 3 are undefined.
 859
 860 Check image for a given color:
 861
 862   my $found;
 863   YLOOP: for my $y (0..$img->getheight-1) {
 864     my @colors = $img->getscanline(y=>$y);
 865     for my $color (@colors) {
 866       my ($red, $green, $blue, $alpha) = $color->rgba;
 867       if ($red == $test_red && $green == $test_green && $blue == $test_blue
 868           && $alpha == $test_alpha) {
 869         ++$found;
 870         last YLOOP;
 871       }
 872     }
 873   }
 874
 875 Or do it using packed data:
 876
 877   my $found;
 878   my $test_packed = pack("CCCC", $test_red, $test_green, $test_blue,
 879                          $test_alpha);
 880   YLOOP: for my $y (0..$img->getheight-1) {
 881     my $colors = $img->getscanline(y=>$y);
 882     while (length $colors) {
 883       if (substr($colors, 0, 4, '') eq $test_packed) {
 884         ++$found;
 885         last YLOOP;
 886       }
 887     }
 888   }
 889
 890 Some of the examples for L</setscanline> for more examples.
 891
 892 =item getsamples
 893
 894 Read specified channels from all or part of a horizontal line of
 895 pixels from an image.
 896
 897 The parameters you can pass are:
 898
 899 =over
 900
 901 =item *
 902
 903 y - vertical position of the scanline.  This parameter is required.
 904
 905 =item *
 906
 907 x - position to start on the scanline.  Default: 0
 908
 909 =item *
 910
 911 width - number of pixels to read.  Default: $img->getwidth - x
 912
 913 =item *
 914
 915 type - the type of sample data to return.  Default: C<8bit>.
 916
 917 Permited values are C<8bit> and C<float>.
 918
 919 =item *
 920
 921 channels - a reference to an array of channels to return, where 0 is
 922 the first channel.  Default: C< [ 0 .. $self->getchannels()-1 ] >
 923
 924 =back
 925
 926 In list context this will return a list of integers between 0 and 255
 927 inclusive when I<type> is C<8bit>, or a list of floating point numbers
 928 between 0.0 and 1.0 inclusive when I<type> is C<float>.
 929
 930 In scalar context this will return a string of packed bytes, as with
 931 C< pack("C*", ...) > when I<type> is C<8bit> or a string of packed
 932 doubles as with C< pack("d*", ...) > when I<type> is C<float>.
 933
 934 Example: Check if any pixels in an image have a non-zero alpha
 935 channel:
 936
 937   my $has_coverage;
 938   for my $y (0 .. $img->getheight()-1) {
 939     my $alpha = $img->getsamples(y=>$y, channels=>[0]);
 940     if ($alpha =~ /[^\0]/) {
 941       ++$has_coverage;
 942       last;
 943     }
 944   }
 945
 946 Example: Convert a 2 channel grey image into a 4 channel RGBA image:
 947
 948   # this could be done with convert() instead
 949   my $out = Imager->new(xsize => $src->getwidth(),
 950                         ysize => $src->getheight(),
 951                         channels => 4);
 952   for my $y ( 0 .. $src->getheight()-1 ) {
 953     my $data = $src->getsamples(y=>$y, channels=>[ 0, 0, 0, 1 ]);
 954     $out->setscanline(y=>$y, pixels=>$data);
 955   }
 956
 957 =back
 958
 959 =head1 Packed Color Data
 960
 961 The getscanline() and setscanline() functions can work with pixels
 962 packed into scalars.  This is useful to remove the cost of creating
 963 color objects, but should only be used when performance is an issue.
 964
 965 Packed data can either be 1 byte per sample or 1 double per sample.
 966
 967 Each pixel returned by getscanline() or supplied to setscanline()
 968 contains 4 samples, even if the image has fewer then 4 channels.  The
 969 values of the extra samples as returned by getscanline() is not
 970 specified.  The extra samples passed to setscanline() are ignored.
 971
 972 To produce packed 1 byte/sample pixels, use the pack C<C> template:
 973
 974   my $packed_8bit_pixel = pack("CCCC", $red, $blue, $green, $alpha);
 975
 976 To produce packed double/sample pixels, use the pack C<d> template:
 977
 978   my $packed_float_pixel = pack("dddd", $red, $blue, $green, $alpha);
 979
 980 If you use a I<type> parameter of C<index> then the values are palette
 981 color indexes, not sample values:
 982
 983   my $im = Imager->new(xsize => 100, ysize => 100, type => 'paletted');
 984   my $black_index = $im->addcolors(colors => [ 'black' ]);
 985   my $red_index = $im->addcolors(colors => [ 'red' ]);
 986   # 2 pixels
 987   my $packed_index_data = pack("C*", $black_index, $red_index);
 988   $im->setscanline(y => $y, pixels => $packed_index_data, type => 'index');
 989
 990 =head1 BUGS
 991
 992 box, arc, do not support antialiasing yet.  Arc, is only filled as of
 993 yet.  Default color is not unified yet.
 994
 995 =head1 AUTHOR
 996
 997 Tony Cook <tony@imager.perl.org>, Arnar M. Hrafnkelsson.
 998
 999 =head1 SEE ALSO
1000
1001 L<Imager>(3), L<Imager::Cookbook>(3)
1002
1003 =head1 REVISION
1004
1005 $Revision$
1006
1007 =cut