lib/Imager/Draw.pod

   1 =head1 NAME
   2
   3 Imager::Draw - Draw primitives to images
   4
   5 =head1 SYNOPSIS
   6
   7   use Imager;
   8   use Imager::Fill;
   9
  10   $img = ...;
  11   $blue = Imager::Color->new( 0, 0, 255 );
  12   $fill = Imager::Fill->new(hatch=>'stipple');
  13
  14   $img->line(color=>$blue, x1=>10, x2=>100,
  15                            y1=>20, y2=>50, aa=>1, endp=>1 );
  16
  17   $img->polyline(points=>[[$x0,$y0], [$x1,$y1], [$x2,$y2]],
  18                  color=>$blue);
  19   $img->polyline(x=>[$x0,$x1,$x2], y=>[$y0,$y1,$y2], aa=>1);
  20
  21   $img->box(color=> $blue, xmin=> 10, ymin=>30,
  22                            xmax=>200, ymax=>300, filled=>1);
  23   $img->box(fill=>$fill);
  24
  25   $img->arc(color=>$blue, r=>20, x=>200, y=>100,
  26             d1=>10, d2=>20 );
  27
  28   $img->circle(color=>$blue, r=>50, x=>200, y=>100);
  29
  30   $img->polygon(points=>[[$x0,$y0], [$x1,$y1], [$x2,$y2]],
  31                 color=>$blue);
  32
  33   $img->polygon(x=>[$x0,$x1,$x2], y=>[$y0,$y1,$y2]);
  34
  35   $img->flood_fill(x=>50, y=>50, color=>$color);
  36
  37   $img->setpixel(x=>50, y=>70, color=>$color);
  38
  39   $img->setpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40], color=>$color);
  40
  41   my $color = $img->getpixel(x=>50, y=>70);
  42
  43   my @colors = $img->getpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40]);
  44
  45   # drawing text
  46   my $font = Imager::Font->new(...) or die;
  47   $img->string(x => 50, y => 70,
  48                font => $font,
  49                string => "Hello, World!",
  50                color => 'red',
  51                size => 30,
  52                aa => 1);
  53
  54   # bottom right-hand corner of the image
  55   $img->align_string(x => $img->getwidth() - 1,
  56                      y => $img->getheight() - 1,
  57                      halign => 'right',
  58                      valign => 'bottom',
  59                      string => 'Imager',
  60                      font => $font,
  61                      size => 12);
  62
  63   # low-level functions
  64   my @colors = $img->getscanline(y=>50, x=>10, width=>20);
  65
  66   $img->setscanline(y=>60, x=>20, pixels=>\@colors);
  67
  68   my @samples = $img->getsamples(y=>50, x=>10, width=>20,
  69                                  channels=>[ 2, 0 ]);
  70
  71 =head1 DESCRIPTION
  72
  73 It is possible to draw with graphics primitives onto images.  Such
  74 primitives include boxes, arcs, circles, polygons and lines.  The
  75 coordinate system in Imager has the origin C<(0,0)> in the upper left
  76 corner of an image with co-ordinates increasing to the right and
  77 bottom.  For non anti-aliasing operation all coordinates are rounded
  78 towards the nearest integer.  For anti-aliased operations floating
  79 point coordinates are used.
  80
  81 Drawing is assumed to take place in a coordinate system of infinite
  82 resolution.  This is the typical convention and really only matters when
  83 it is necessary to check for off-by-one cases.  Typically it's useful to
  84 think of C<(10, 20)> as C<(10.00, 20.00)> and consider the consequences.
  85
  86 =head2 Color Parameters
  87
  88 X<color parameters>The C<color> parameter for any of the drawing
  89 methods can be an L<Imager::Color> object, a simple scalar that
  90 Imager::Color can understand, a hashref of parameters that
  91 Imager::Color->new understands, or an arrayref of red, green, blue
  92 values, for example:
  93
  94   $image->box(..., color=>'red');
  95   $image->line(..., color=>'#FF0000');
  96   $image->flood_fill(..., color=>[ 255, 0, 255 ]);
  97
  98 While supplying colors as names, array references or CSS color
  99 specifiers is convenient, for maximum performance you should supply
 100 the color as an L<Imager::Color> object:
 101
 102   my @colors = map Imager::Color->new($_), qw/red green blue/
 103   for my $i (1..1000) {
 104     $image->box(..., color => $colors[rand @colors]);
 105   }
 106
 107 =head2 Fill Parameters
 108
 109 X<fill parameters>All filled primitives, i.e. C<arc()>, C<box()>,
 110 C<circle()>, C<polygon()> and the C<flood_fill()> method can take a
 111 C<fill> parameter instead of a C<color> parameter which can either be
 112 an Imager::Fill object, or a reference to a hash containing the
 113 parameters used to create the fill, for example:
 114
 115   $image->box(..., fill=>{ hatch => 'check1x1' });
 116   my $fillimage = Imager->new;
 117   $fillimage->read(file=>$somefile) or die;
 118   $image->flood_fill(..., fill=>{ image=>$fillimage });
 119
 120 Currently you can create opaque or transparent plain color fills,
 121 hatched fills, image based fills and fountain fills.  See
 122 L<Imager::Fill> for more information.
 123
 124 =head2 Polygon Fill Modes
 125
 126 When filling a polygon that overlaps itself, or when filling several
 127 polygons with polypolygon() that overlap each other, you can supply a
 128 C<mode> parameter that controls how the overlap is resolved.  This can
 129 have one of two possible values:
 130
 131 =over
 132
 133 =item *
 134
 135 C<evenodd> - if areas overlap an odd number of times, they are filled,
 136 and are otherwise unfilled.  This is the default and the historical
 137 Imager polygon fill mode.
 138
 139 =item *
 140
 141 C<nonzero> - areas that have an unbalanced clockwise and
 142 anti-clockwise boundary are filled.  This is the same as
 143 C<WindingRule> for X and C<WINDING> for Win32 GDI.
 144
 145 =back
 146
 147 C<nonzero> allows polygons to overlap, either with itself, or with
 148 another polygon in the same polypolygon() call, without producing
 149 unfilled area in the overlap, and also allows areas to be cut out of
 150 the area by specifying the points making up a cut-out in the opposite
 151 order.
 152
 153 =head2 List of primitives
 154
 155 =over
 156
 157 =item line()
 158
 159   $img->line(color=>$green, x1=>10, x2=>100,
 160                             y1=>20, y2=>50, aa=>1, endp=>1 );
 161
 162 X<line method>Draws a line from (x1,y1) to (x2,y2).  The endpoint
 163 (x2,y2) is drawn by default.  If C<endp> of 0 is specified then the
 164 endpoint will not be drawn.  If C<aa> is set then the line will be
 165 drawn anti-aliased.  The C<antialias> parameter is still available for
 166 backwards compatibility.
 167
 168 Parameters:
 169
 170 =over
 171
 172 =item *
 173
 174 C<x1>, C<y1> - starting point of the line.  Required.
 175
 176 =item *
 177
 178 C<x2>, C<y2> - end point of the line. Required.
 179
 180 =item *
 181
 182 C<color> - the color of the line.  See L</"Color Parameters">.  Default:
 183 black.
 184
 185 =item *
 186
 187 C<endp> - if zero the end point of the line is not drawn.  Default: 1
 188 - the end point is drawn.  This is useful to set to 0 when drawing a
 189 series of connected lines.
 190
 191 =item *
 192
 193 C<aa> - if true the line is drawn anti-aliased.  Default: 0.
 194
 195 =back
 196
 197 =item polyline()
 198
 199   $img->polyline(points=>[[$x0,$y0],[$x1,$y1],[$x2,$y2]],color=>$red);
 200   $img->polyline(x=>[$x0,$x1,$x2], y=>[$y0,$y1,$y2], aa=>1);
 201
 202 X<polyline method>C<polyline> is used to draw multiple lines between a
 203 series of points.  The point set can either be specified as an
 204 arrayref to an array of array references (where each such array
 205 represents a point).  The other way is to specify two array
 206 references.
 207
 208 The C<antialias> parameter is still available for backwards compatibility.
 209
 210 =over
 211
 212 =item *
 213
 214 points - a reference to an array of references to arrays containing
 215 the co-ordinates of the points in the line, for example:
 216
 217   my @points = ( [ 0, 0 ], [ 100, 0 ], [ 100, 100 ], [ 0, 100 ] );
 218   $img->polyline(points => \@points);
 219
 220 =item *
 221
 222 x, y - each is an array of x or y ordinates.  This is an alternative
 223 to supplying the C<points> parameter.
 224
 225   # same as the above points example
 226   my @x = ( 0, 100, 100, 0 );
 227   my @y = ( 0, 0, 100, 100 );
 228   $img->polyline(x => \@x, y => \@y);
 229
 230 =item *
 231
 232 C<color> - the color of the line.  See L</"Color Parameters">.
 233 Default: black.
 234
 235 =item *
 236
 237 C<aa> - if true the line is drawn anti-aliased.  Default: 0.  Can also
 238 be supplied as C<antialias> for backward compatibility.
 239
 240 =back
 241
 242 =item box()
 243
 244   $blue = Imager::Color->new( 0, 0, 255 );
 245   $img->box(color => $blue, xmin=>10, ymin=>30, xmax=>200, ymax=>300,
 246             filled=>1);
 247
 248 X<box method>If any of the edges of the box are omitted it will snap
 249 to the outer edge of the image in that direction.  If C<filled> is
 250 omitted the box is drawn as an outline.  Instead of a color it is
 251 possible to use a C<fill> pattern:
 252
 253   $fill = Imager::Fill->new(hatch=>'stipple');
 254   $img->box(fill=>$fill);  # fill entire image with a given fill pattern
 255
 256   $img->box(xmin=>10, ymin=>30, xmax=>150, ymax=>60,
 257             fill => { hatch=>'cross2' });
 258
 259 Also if a color is omitted a color with (255,255,255,255) is used
 260 instead.  [NOTE: This may change to use C<$img-E<gt>fgcolor()> in the future].
 261
 262 Box does not support fractional coordinates yet.
 263
 264 Parameters:
 265
 266 =over
 267
 268 =item *
 269
 270 C<xmin> - left side of the box.  Default: 0 (left edge of the image)
 271
 272 =item *
 273
 274 C<ymin> - top side of the box.  Default: 0 (top edge of the image)
 275
 276 =item *
 277
 278 C<xmax> - right side of the box.  Default: C<< $img->getwidth-1
 279 >>. (right edge of the image)
 280
 281 =item *
 282
 283 C<ymax> - bottom side of the box.  Default: C<< $img->getheight-1
 284 >>. (bottom edge of the image)
 285
 286 Note: C<xmax> and C<ymax> are I<inclusive> - the number of pixels
 287 drawn for a filled box is C<(xmax-xmin+1) * (ymax-ymin+1)>.
 288
 289 =item *
 290
 291 C<box> - a reference to an array of (left, top, right, bottom)
 292 co-ordinates.  This is an alternative to supplying C<xmin>, C<ymin>,
 293 C<xmax>, C<ymax> and overrides their values.
 294
 295 =item *
 296
 297 C<color> - the color of the line.  See L</"Color Parameters">.
 298 Default: white.  This is ignored if the filled parameter
 299
 300 =item *
 301
 302 C<filled> - if non-zero the box is filled with I<color> instead of
 303 outlined.  Default: an outline is drawn.
 304
 305 =item *
 306
 307 C<fill> - the fill for the box.  If this is supplied then the box will be
 308 filled.  See L</"Fill Parameters">.
 309
 310 =back
 311
 312 =item arc()
 313
 314   $img->arc(color=>$red, r=>20, x=>200, y=>100, d1=>10, d2=>20 );
 315
 316 This creates a filled red arc with a 'center' at (200, 100) and spans
 317 10 degrees and the slice has a radius of 20.
 318
 319 It's also possible to supply a C<fill> parameter.
 320
 321 To draw just an arc outline - just the curve, not the radius lines,
 322 set filled to 0:
 323
 324 Parameters:
 325
 326   $img->arc(color=>$red, r=>20, x=>200, y=>100, d1=>10, d2=>20, filled=>0 );
 327
 328 =over
 329
 330 =item *
 331
 332 C<x>, C<y> - center of the filled arc.  Default: center of the image.
 333
 334 =item *
 335
 336 C<r> - radius of the arc.  Default: 1/3 of min(image height, image width).
 337
 338 =item *
 339
 340 C<d1> - starting angle of the arc, in degrees.  Default: 0
 341
 342 =item *
 343
 344 C<d2> - ending angle of the arc, in degrees.  Default: 361.
 345
 346 =item *
 347
 348 C<color> - the color of the filled arc.  See L</"Color Parameters">.
 349 Default: white.  Overridden by C<fill>.
 350
 351 =item *
 352
 353 C<fill> - the fill for the filled arc.  See L</"Fill Parameters">
 354
 355 =item *
 356
 357 C<aa> - if true the filled arc is drawn anti-aliased.  Default: false.
 358
 359 Anti-aliased arc() is experimental for now, I'm not entirely happy
 360 with the results in some cases.
 361
 362 =item *
 363
 364 C<filled> - set to 0 to draw only an outline.
 365
 366 =back
 367
 368   # arc going through angle zero:
 369   $img->arc(d1=>320, d2=>40, x=>100, y=>100, r=>50, color=>'blue');
 370
 371   # complex fill arc
 372   $img->arc(d1=>135, d2=>45, x=>100, y=>150, r=>50,
 373             fill=>{ solid=>'red', combine=>'diff' });
 374
 375   # draw an anti-aliased circle outline
 376   $img->arc(x => 100, y => 150, r => 150, filled => 0,
 377             color => '#F00', aa => 1);
 378
 379   # draw an anti-aliased arc
 380   $img->arc(x => 100, y => 150, r => 90, filled => 0,
 381             color => '#0f0', aa => 1, d1 => 90, d2 => 180);
 382
 383 =item circle()
 384
 385   $img->circle(color=>$green, r=>50, x=>200, y=>100, aa=>1, filled=>1);
 386
 387 This creates an anti-aliased green circle with its center at (200, 100)
 388 and has a radius of 50.  It's also possible to supply a C<fill> parameter
 389 instead of a color parameter.
 390
 391   $img->circle(r => 50, x=> 150, y => 150, fill=>{ hatch => 'stipple' });
 392
 393 To draw a circular outline, set C<filled> to 0:
 394
 395   $img->circle(color=>$green, r=>50, x=>200, y=>100, aa=>1, filled=>0);
 396
 397 =over
 398
 399 =item *
 400
 401 C<x>, C<y> - center of the filled circle.  Default: center of the image.
 402
 403 =item *
 404
 405 C<r> - radius of the circle.  Default: 1/3 of min(image height, image width).
 406
 407 =item *
 408
 409 C<color> - the color of the filled circle.  See L</"Color Parameters">.
 410 Default: white.  Overridden by C<fill>.
 411
 412 =item *
 413
 414 C<fill> - the fill for the filled circle.  See L</"Fill Parameters">
 415
 416 =item *
 417
 418 C<aa> - if true the filled circle is drawn anti-aliased.  Default: false.
 419
 420 =item *
 421
 422 C<filled> - set to 0 to just draw an outline.
 423
 424 =back
 425
 426 =item polygon()
 427
 428   $img->polygon(points=>[[$x0,$y0],[$x1,$y1],[$x2,$y2]],color=>$red);
 429   $img->polygon(x=>[$x0,$x1,$x2], y=>[$y0,$y1,$y2], fill=>$fill);
 430
 431 Polygon is used to draw a filled polygon.  Currently the polygon is
 432 always drawn anti-aliased, although that will change in the future.
 433 Like other anti-aliased drawing functions its coordinates can be
 434 specified with floating point values.  As with other filled shapes
 435 it's possible to use a C<fill> instead of a color.
 436
 437 =over
 438
 439 =item *
 440
 441 C<points> - a reference to an array of references to arrays containing
 442 the co-ordinates of the points in the line, for example:
 443
 444   my @points = ( [ 0, 0 ], [ 100, 0 ], [ 100, 100 ], [ 0, 100 ] );
 445   $img->polygon(points => \@points);
 446
 447 =item *
 448
 449 C<x>, C<y> - each is an array of x or y ordinates.  This is an alternative
 450 to supplying the C<points> parameter.
 451
 452   # same as the above points example
 453   my @x = ( 0, 100, 100, 0 );
 454   my @y = ( 0, 0, 100, 100 );
 455   $img->polygon(x => \@x, y => \@y);
 456
 457 =item *
 458
 459 C<color> - the color of the filled polygon.  See L</"Color Parameters">.
 460 Default: black.  Overridden by C<fill>.
 461
 462 =item *
 463
 464 C<fill> - the fill for the filled circle.  See L</"Fill Parameters">
 465
 466 =item *
 467
 468 C<mode> - fill mode for the polygon.  See L</"Polygon Fill Modes">
 469
 470 =back
 471
 472 Note: the points specified are as offsets from the top-left of the
 473 image, I<not> as pixel locations.  This means that:
 474
 475   $img->polygon(points => [ [ 0, 0 ], [ 1, 0 ], [ 1, 1 ], [ 0, 1 ] ]);
 476
 477 fills only a single pixel at C<(0, 0)>, not four.
 478
 479 =item polypolygon()
 480 X<polypolygon() method>X<methods, polypolygon>
 481
 482   $img->polypolygon(points => $points, color => $color);
 483
 484 Draw multiple polygons, either filled or unfilled.
 485
 486 =over
 487
 488 =item *
 489
 490 C<points> - is an array reference containing polygon definitions, each
 491 polygon definition is a reference to an array containing two arrays,
 492 one each for the C<x> and C<y> co-ordinates.
 493
 494 =item *
 495
 496 C<filled> - if true, fill the polygons with the color defined by
 497 C<color>.
 498
 499 =item *
 500
 501 C<color> - the color to draw the polygons with if C<fill> is not
 502 supplied.
 503
 504 =item *
 505
 506 C<fill> - fill the polygons with this fill if supplied.
 507
 508 =item *
 509
 510 C<mode> - fill mode for the polygon.  See L</"Polygon Fill Modes">
 511
 512 =back
 513
 514 Note: the points specified are as offsets from the top-left of the
 515 image, I<not> as pixel locations.  This means that:
 516
 517   $img->polypolygon(points => [ [ [ 0, 1, 1, 0 ], [ 0, 0, 1, 1 ] ] ],
 518                     filled => 1);
 519
 520 fills only a single pixel at C<(0, 0)>, not four.
 521
 522 =item flood_fill()
 523
 524 X<flood_fill>You can fill a region that all has the same color using
 525 the flood_fill() method, for example:
 526
 527   $img->flood_fill(x=>50, y=>50, color=>$color);
 528
 529 will fill all regions the same color connected to the point (50, 50).
 530
 531 Alternatively you can fill a region limited by a given border color:
 532
 533   # stop at the red border
 534   $im->flood_fill(x=>50, y=>50, color=>$color, border=>"red");
 535
 536 You can also fill with a complex fill:
 537
 538   $img->flood_fill(x=>50, y=>50, fill=>{ hatch=>'cross1x1' });
 539
 540 Parameters:
 541
 542 =over
 543
 544 =item *
 545
 546 C<x>, C<y> - the start point of the fill.
 547
 548 =item *
 549
 550 C<color> - the color of the filled area.  See L</"Color Parameters">.
 551 Default: white.  Overridden by C<fill>.
 552
 553 =item *
 554
 555 C<fill> - the fill for the filled area.  See L</"Fill Parameters">
 556
 557 =item *
 558
 559 C<border> - the border color of the region to be filled.  If this
 560 parameter is supplied flood_fill() will stop when it finds this color.
 561 If this is not supplied then a normal fill is done.  C<border> can be
 562 supplied as a L</"Color Parameters">.
 563
 564 =back
 565
 566 =item setpixel()
 567
 568   $img->setpixel(x=>50, y=>70, color=>$color);
 569   $img->setpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40], color=>$color);
 570
 571 setpixel() is used to set one or more individual pixels.
 572
 573 You can supply a single set of co-ordinates as scalar C<x> and C<y>
 574 parameters, or set either to an arrayref of ordinates.
 575
 576 If one array is shorter than another the final value in the shorter
 577 will be duplicated until they match in length.
 578
 579 If only one of C<x> or C<y> is an array reference then setpixel() will
 580 behave as if the non-reference value were an array reference
 581 containing only that value.
 582
 583 eg.
 584
 585   my $count = $img->setpixel(x => 1, y => [ 0 .. 3 ], color => $color);
 586
 587 behaves like:
 588
 589   my $count = $img->setpixel(x => [ 1 ], y => [ 0 .. 3 ], color => $color);
 590
 591 and since the final element in the shorter array is duplicated, this
 592 behaves like:
 593
 594   my $count = $img->setpixel(x => [ 1, 1, 1, 1 ], y => [ 0 .. 3 ],
 595                              color => $color);
 596
 597 Parameters:
 598
 599 =over
 600
 601 =item *
 602
 603 x, y - either integers giving the co-ordinates of the pixel to set or
 604 array references containing a set of pixels to be set.
 605
 606 =item *
 607
 608 color - the color of the pixels drawn.  See L</"Color Parameters">.
 609 Default: white.
 610
 611 =back
 612
 613 Returns the number of pixels drawn, if no pixels were drawn, but none
 614 of the errors below occur, returns C<"0 but true">.
 615
 616 For other errors, setpixel() returns an empty list and sets errstr().
 617
 618 Possible errors conditions include:
 619
 620 =over
 621
 622 =item * the image supplied is empty
 623
 624 =item * a reference to an empty array was supplied for C<x> or C<y>
 625
 626 =item * C<x> or C<y> wasn't supplied
 627
 628 =item * C<color> isn't a valid color, and can't be converted to a
 629 color.
 630
 631 =back
 632
 633 =item getpixel()
 634
 635   my $color = $img->getpixel(x=>50, y=>70); my @colors =
 636   $img->getpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40]); my $colors_ref =
 637   $img->getpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40]);
 638
 639 getpixel() is used to retrieve one or more individual pixels.
 640
 641 You can supply a single set of co-ordinates as scalar C<x> and C<y>
 642 parameters, or set each to an arrayref of ordinates.
 643
 644 If one array is shorter than another the final value in the shorter
 645 will be duplicated until they match in length.
 646
 647 If only one of C<x> or C<y> is an array reference then getpixel() will
 648 behave as if the non-reference value were an array reference
 649 containing only that value.
 650
 651 eg.
 652
 653   my @colors = $img->getpixel(x => 0, y => [ 0 .. 3 ]);
 654
 655 behaves like:
 656
 657   my @colors = $img->getpixel(x => [ 0 ], y => [ 0 .. 3 ]);
 658
 659 and since the final element in the shorter array is duplicated, this
 660 behaves like:
 661
 662   my @colors = $img->getpixel(x => [ 0, 0, 0, 0 ], y => [ 0 .. 3 ]);
 663
 664 To receive floating point colors from getpixel(), set the C<type>
 665 parameter to 'float'.
 666
 667 Parameters:
 668
 669 =over
 670
 671 =item *
 672
 673 C<x>, C<y> - either integers giving the co-ordinates of the pixel to set or
 674 array references containing a set of pixels to be set.
 675
 676 =item *
 677
 678 C<type> - the type of color object to return, either C<'8bit'> for
 679 L<Imager::Color> objects or C<'float'> for L<Imager::Color::Float>
 680 objects.  Default: C<'8bit'>.
 681
 682 =back
 683
 684 When called with an array reference for either or C<x> or C<y>,
 685 getpixel() will return a list of colors in list context, and an
 686 arrayref in scalar context.
 687
 688 If a supplied co-ordinate is outside the image then C<undef> is
 689 returned for the pixel.
 690
 691 Each color is returned as an L<Imager::Color> object or as an
 692 L<Imager::Color::Float> object if C<type> is set to C<"float">.
 693
 694 Possible errors conditions include:
 695
 696 =over
 697
 698 =item * the image supplied is empty
 699
 700 =item * a reference to an empty array was supplied for C<x> or C<y>
 701
 702 =item * C<x> or C<y> wasn't supplied
 703
 704 =item * C<type> isn't a valid value.
 705
 706 =back
 707
 708 For any of these errors getpixel() returns an empty list.
 709
 710 =item string()
 711
 712   my $font = Imager::Font->new(file=>"foo.ttf");
 713   $img->string(x => 50, y => 70,
 714                string => "Hello, World!",
 715                font => $font,
 716                size => 30,
 717                aa => 1,
 718                color => 'white');
 719
 720 Draws text on the image.
 721
 722 Parameters:
 723
 724 =over
 725
 726 =item *
 727
 728 C<x>, C<y> - the point to draw the text from.  If C<align> is 0 this
 729 is the top left of the string.  If C<align> is 1 (the default) then
 730 this is the left of the string on the baseline.  Required.
 731
 732 =item *
 733
 734 C<string> - the text to draw.  Required unless you supply the C<text>
 735 parameter.
 736
 737 =item *
 738
 739 C<font> - an L<Imager::Font> object representing the font to draw the
 740 text with.  Required.
 741
 742 =item *
 743
 744 C<aa> - if non-zero the output will be anti-aliased.  Default: the value
 745 set in Imager::Font->new() or 0 if not set.
 746
 747 =item *
 748
 749 C<align> - if non-zero the point supplied in (x,y) will be on the
 750 base-line, if zero then (x,y) will be at the top-left of the string.
 751
 752 i.e. if drawing the string C<"yA"> and align is 0 the point (x,y) will
 753 aligned with the top of the A.  If align is 1 (the default) it will be
 754 aligned with the baseline of the font, typically bottom of the A,
 755 depending on the font used.
 756
 757 Default: the value set in Imager::Font->new, or 1 if not set.
 758
 759 =item *
 760
 761 C<channel> - if present, the text will be written to the specified
 762 channel of the image and the color parameter will be ignore.
 763
 764 =item *
 765
 766 C<color> - the color to draw the text in.  Default: the color supplied to
 767 Imager::Font->new, or red if none.
 768
 769 =item *
 770
 771 C<size> - the point size to draw the text at.  Default: the size
 772 supplied to Imager::Font->new, or 15.
 773
 774 =item *
 775
 776 C<sizew> - the width scaling to draw the text at.  Default: the value
 777 of C<size>.
 778
 779 =item *
 780
 781 C<utf8> - for drivers that support it, treat the string as UTF-8
 782 encoded.  For versions of perl that support Unicode (5.6 and later),
 783 this will be enabled automatically if the C<string> parameter is
 784 already a UTF-8 string. See L<Imager::Font/"UTF-8"> for more
 785 information.
 786
 787 =item *
 788
 789 C<vlayout> - for drivers that support it, draw the text vertically.
 790 Note: I haven't found a font that has the appropriate metrics yet.
 791
 792 =item *
 793
 794 C<text> - alias for the C<string> parameter.
 795
 796 =back
 797
 798 On error, string() returns false and you can use $img->errstr to get
 799 the reason for the error.
 800
 801 =item align_string()
 802
 803 Draws text aligned around a point on the image.
 804
 805   # "Hello" centered at 100, 100 in the image.
 806   my ($left, $top, $right, $bottom) =
 807     $img->align_string(string=>"Hello",
 808                        x=>100, y=>100,
 809                        halign=>'center', valign=>'center',
 810                        font=>$font);
 811
 812 Parameters:
 813
 814 =over
 815
 816 =item *
 817
 818 C<x>, C<y> - the point to draw the text from.  If C<align> is 0 this
 819 is the top left of the string.  If C<align> is 1 (the default) then
 820 this is the left of the string on the baseline.  Required.
 821
 822 =item *
 823
 824 C<string> - the text to draw.  Required unless you supply the C<text>
 825 parameter.
 826
 827 =item *
 828
 829 C<font> - an L<Imager::Font> object representing the font to draw the
 830 text with.  Required.
 831
 832 =item *
 833
 834 C<aa> - if non-zero the output will be anti-aliased
 835
 836 =item *
 837
 838 C<valign> - vertical alignment of the text against (x,y)
 839
 840 =over
 841
 842 =item *
 843
 844 C<top> - Point is at the top of the text.
 845
 846 =item *
 847
 848 C<bottom> - Point is at the bottom of the text.
 849
 850 =item *
 851
 852 C<baseline> - Point is on the baseline of the text.  This is the default.
 853
 854 =item *
 855
 856 C<center> - Point is vertically centered within the text.
 857
 858 =back
 859
 860 =item *
 861
 862 C<halign> - horizontal alignment of the text against (x,y)
 863
 864 =over
 865
 866 =item *
 867
 868 C<left> - The point is at the left of the text.  This is the default.
 869
 870 =item *
 871
 872 C<start> - The point is at the start point of the text.
 873
 874 =item *
 875
 876 C<center> - The point is horizontally centered within the text.
 877
 878 =item *
 879
 880 C<right> - The point is at the right end of the text.
 881
 882 =item *
 883
 884 C<end> - The point is at the end point of the text.
 885
 886 =back
 887
 888 =item *
 889
 890 C<channel> - if present, the text will be written to the specified
 891 channel of the image and the color parameter will be ignore.
 892
 893 =item *
 894
 895 C<color> - the color to draw the text in.  Default: the color supplied to
 896 Imager::Font->new, or red if none.
 897
 898 =item *
 899
 900 C<size> - the point size to draw the text at.  Default: the size supplied
 901 to Imager::Font->new, or 15.
 902
 903 =item *
 904
 905 C<sizew> - the width scaling to draw the text at.  Default: the value of
 906 C<size>.
 907
 908 =item *
 909
 910 C<utf8> - for drivers that support it, treat the string as UTF-8
 911 encoded.  For versions of perl that support Unicode (5.6 and later),
 912 this will be enabled automatically if the C<string> parameter is
 913 already a UTF-8 string. See L<Imager::Font/"UTF-8"> for more
 914 information.
 915
 916 =item *
 917
 918 C<vlayout> - for drivers that support it, draw the text vertically.
 919 Note: I haven't found a font that has the appropriate metrics yet.
 920
 921 =item *
 922
 923 C<text> - alias for the C<string> parameter.
 924
 925 =back
 926
 927 On success returns a list of bounds of the drawn text, in the order
 928 left, top, right, bottom.
 929
 930 On error, align_string() returns an empty list and you can use
 931 C<< $img->errstr >> to get the reason for the error.
 932
 933 =item setscanline()
 934
 935 Set all or part of a horizontal line of pixels to an image.  This
 936 method is most useful in conjunction with L</getscanline()>.
 937
 938 The parameters you can pass are:
 939
 940 =over
 941
 942 =item *
 943
 944 C<y> - vertical position of the scan line.  This parameter is required.
 945
 946 =item *
 947
 948 C<x> - position to start on the scan line.  Default: 0
 949
 950 =item *
 951
 952 C<pixels> - either a reference to an array containing Imager::Color
 953 objects, an reference to an array containing Imager::Color::Float
 954 objects or a scalar containing packed color data.
 955
 956 If C<type> is C<index> then this can either be a reference to an array
 957 of palette color indexes or a scalar containing packed indexes.
 958
 959 See L</"Packed Color Data"> for information on the format of packed
 960 color data.
 961
 962 =item *
 963
 964 C<type> - the type of pixel data supplied.  If you supply an array
 965 reference then this is determined automatically.  If you supply packed
 966 color data this defaults to C<'8bit'>, if your data is packed floating
 967 point color data then you need to set this to C<'float'>.
 968
 969 You can use C<float> or C<8bit> samples with any image.
 970
 971 If this is C<index> then C<pixels> should be either an array of
 972 palette color indexes or a packed string of color indexes.
 973
 974 =back
 975
 976 Returns the number of pixels set.
 977
 978 Each of the following sets 5 pixels from (5, 10) through (9, 10) to
 979 blue, red, blue, red, blue:
 980
 981   my $red_color = Imager::Color->new(255, 0, 0);
 982   my $blue_color = Imager::Color->new(0, 0, 255);
 983
 984   $image->setscanline(y=>10, x=>5, pixels=>
 985                       [ ($blue_color, $red_color) x 2, $blue_color ]);
 986
 987   # use floating point color instead, for 16-bit plus images
 988   my $red_colorf = Imager::Color::Float->new(1.0, 0, 0);
 989   my $blue_colorf = Imager::Color::Float->new(0, 0, 1.0);
 990
 991   $image->setscanline(y=>10, x=>5, pixels=>
 992                       [ ($blue_colorf, $red_colorf) x 2, $blue_colorf ]);
 993
 994   # packed 8-bit data
 995   $image->setscanline(y=>10, x=>5, pixels=>
 996                       pack("C*", ((0, 0, 255, 255), (255, 0, 0, 255)) x 2,
 997                             (0, 0, 255, 255)));
 998
 999   # packed floating point samples
1000   $image->setscanline(y=>10, x=>5, type=>'float', pixels=>
1001                       pack("d*", ((0, 0, 1.0, 1.0), (1.0, 0, 0, 1.0)) x 2,
1002                             (0, 0, 1.0, 1.0)));
1003
1004
1005 Copy even rows from one image to another:
1006
1007   for (my $y = 0; $y < $im2->getheight; $y+=2) {
1008     $im1->setscanline(y=>$y,
1009                       pixels=>scalar($im2->getscanline(y=>$y)));
1010   }
1011
1012
1013 Set the blue channel to 0 for all pixels in an image.  This could be
1014 done with convert too:
1015
1016   for my $y (0..$im->getheight-1) {
1017     my $row = $im->getscanline(y=>$y);
1018     $row =~ s/(..).(.)/$1\0$2/gs;
1019     $im->setscanline(y=>$y, pixels=>$row);
1020   }
1021
1022 =item getscanline()
1023
1024 Read all or part of a horizontal line of pixels from an image.  This
1025 method is most useful in conjunction with L</setscanline()>.
1026
1027 The parameters you can pass are:
1028
1029 =over
1030
1031 =item *
1032
1033 C<y> - vertical position of the scan line.  This parameter is required.
1034
1035 =item *
1036
1037 C<x> - position to start on the scan line.  Default: 0
1038
1039 =item *
1040
1041 C<width> - number of pixels to read.  Default: $img->getwidth - x
1042
1043 =item *
1044
1045 C<type> - the type of pixel data to return.  Default: C<8bit>.
1046
1047 Permitted values are C<8bit> and C<float> and C<index>.
1048
1049 =back
1050
1051 In list context this method will return a list of Imager::Color
1052 objects when I<type> is C<8bit>, or a list of Imager::Color::Float
1053 objects when I<type> if C<float>, or a list of integers when I<type>
1054 is C<index>.
1055
1056 In scalar context this returns a packed 8-bit pixels when I<type> is
1057 C<8bit>, or a list of packed floating point pixels when I<type> is
1058 C<float>, or packed palette color indexes when I<type> is C<index>.
1059
1060 The values of samples for which the image does not have channels is
1061 undefined.  For example, for a single channel image the values of
1062 channels 1 through 3 are undefined.
1063
1064 Check image for a given color:
1065
1066   my $found;
1067   YLOOP: for my $y (0..$img->getheight-1) {
1068     my @colors = $img->getscanline(y=>$y);
1069     for my $color (@colors) {
1070       my ($red, $green, $blue, $alpha) = $color->rgba;
1071       if ($red == $test_red && $green == $test_green && $blue == $test_blue
1072           && $alpha == $test_alpha) {
1073         ++$found;
1074         last YLOOP;
1075       }
1076     }
1077   }
1078
1079 Or do it using packed data:
1080
1081   my $found;
1082   my $test_packed = pack("CCCC", $test_red, $test_green, $test_blue,
1083                          $test_alpha);
1084   YLOOP: for my $y (0..$img->getheight-1) {
1085     my $colors = $img->getscanline(y=>$y);
1086     while (length $colors) {
1087       if (substr($colors, 0, 4, '') eq $test_packed) {
1088         ++$found;
1089         last YLOOP;
1090       }
1091     }
1092   }
1093
1094 Some of the examples for L</setscanline()> for more examples.
1095
1096 =item getsamples()
1097
1098 Read specified channels from all or part of a horizontal line of
1099 pixels from an image.
1100
1101 The parameters you can pass are:
1102
1103 =over
1104
1105 =item *
1106
1107 C<y> - vertical position of the scan line.  This parameter is required.
1108
1109 =item *
1110
1111 C<x> - position to start on the scan line.  Default: 0
1112
1113 =item *
1114
1115 C<width> - number of pixels to read.  Default: C<< $img->getwidth - x >>
1116
1117 =item *
1118
1119 C<type> - the type of sample data to return.  Default: C<8bit>.
1120
1121 Permitted values are C<8bit> and C<float>.
1122
1123 As of Imager 0.61 this can be C<16bit> only for 16 bit images.
1124
1125 =item *
1126
1127 C<channels> - a reference to an array of channels to return, where 0
1128 is the first channel.  Default: C<< [ 0 .. $self->getchannels()-1 ] >>
1129
1130 =item *
1131
1132 C<target> - if an array reference is supplied in target then the samples
1133 will be stored here instead of being returned.
1134
1135 =item *
1136
1137 C<offset> - the offset within the array referenced by I<target>
1138
1139 =back
1140
1141 In list context this will return a list of integers between 0 and 255
1142 inclusive when I<type> is C<8bit>, or a list of floating point numbers
1143 between 0.0 and 1.0 inclusive when I<type> is C<float>.
1144
1145 In scalar context this will return a string of packed bytes, as with
1146 C< pack("C*", ...) > when I<type> is C<8bit> or a string of packed
1147 doubles as with C< pack("d*", ...) > when I<type> is C<float>.
1148
1149 If the I<target> option is supplied then only a count of samples is
1150 returned.
1151
1152 Example: Check if any pixels in an image have a non-zero alpha
1153 channel:
1154
1155   my $has_coverage;
1156   for my $y (0 .. $img->getheight()-1) {
1157     my $alpha = $img->getsamples(y=>$y, channels=>[0]);
1158     if ($alpha =~ /[^\0]/) {
1159       ++$has_coverage;
1160       last;
1161     }
1162   }
1163
1164 Example: Convert a 2 channel gray image into a 4 channel RGBA image:
1165
1166   # this could be done with convert() instead
1167   my $out = Imager->new(xsize => $src->getwidth(),
1168                         ysize => $src->getheight(),
1169                         channels => 4);
1170   for my $y ( 0 .. $src->getheight()-1 ) {
1171     my $data = $src->getsamples(y=>$y, channels=>[ 0, 0, 0, 1 ]);
1172     $out->setscanline(y=>$y, pixels=>$data);
1173   }
1174
1175 Retrieve 16-bit samples:
1176
1177   if ($img->bits == 16) {
1178     my @samples;
1179     $img->getsamples(x => 0, y => $y, target => \@samples, type => '16bit');
1180   }
1181
1182 =item setsamples()
1183
1184 This allows writing of samples to an image.
1185
1186 Parameters:
1187
1188 =over
1189
1190 =item *
1191
1192 C<y> - vertical position of the scan line.  This parameter is required.
1193
1194 =item *
1195
1196 C<x> - position to start on the scan line.  Default: 0
1197
1198 =item *
1199
1200 C<width> - number of pixels to write.  Default: C<< $img->getwidth - x >>.
1201 The minimum of this and the number of pixels represented by the
1202 samples provided will be written.
1203
1204 =item *
1205
1206 C<type> - the type of sample data to write.  This parameter is required.
1207
1208 This can be C<8bit>, C<float> or for 16-bit images only, C<16bit>.
1209
1210 =item *
1211
1212 C<channels> - a reference to an array of channels to return, where 0 is
1213 the first channel.  Default: C<< [ 0 .. $self->getchannels()-1 ] >>
1214
1215 =item *
1216
1217 C<data> - for a type of C<8bit> or C<float> this can be a reference to
1218 an array of samples or a scalar containing packed samples.  If C<data>
1219 is a scalar it may only contain characters from \x00 to \xFF.
1220
1221 For a type of C<16bit> this can only be a reference to an array of
1222 samples to write.
1223
1224 Required.
1225
1226 =item *
1227
1228 C<offset> - the starting offset within the array referenced by
1229 I<data>.  If C<data> is a scalar containing packed samples this offset
1230 is in samples.
1231
1232 =back
1233
1234 Returns the number of samples written.
1235
1236   $targ->setsamples(y => $y, data => \@data);
1237
1238   $targ->setsamples(y => $y, data => \@data, offset => $src->getchannels);
1239
1240 Copy from one image to another:
1241
1242   my $targ = Imager->new(xsize => $src->getwidth,
1243         ysize => $src->getheight, channels => $src->getchannels);
1244   for my $y (0 .. $targ->getheight()-1) {
1245     my $row = $src->getsamples(y => $y)
1246       or die $src->errstr;
1247     $targ->setsamples(y => $y, data => $row)
1248       or die $targ->errstr;;
1249   }
1250
1251 Compose an image from separate source channels:
1252
1253   my @src = ...; # images to work from, up to 4
1254   my $targ = Imager->new(xsize => $src[0]->getwidth,
1255      ysize => $src[0]->getheight, channels => scalar(@src));
1256   for my $y (0 .. $targ->getheight()-1) {
1257     for my $ch (0 .. $#src) {
1258       my $row = $src[$ch]->getsamples(y => $y, channels => [ 0 ]);
1259       $targ->setsamples(y => $y, data => $row, channels => [ $ch ] );
1260     }
1261   }
1262
1263 =back
1264
1265 =head1 Packed Color Data
1266
1267 The getscanline() and setscanline() methods can work with pixels
1268 packed into scalars.  This is useful to remove the cost of creating
1269 color objects, but should only be used when performance is an issue.
1270
1271 The getsamples() and setsamples() methods can work with samples packed
1272 into scalars.
1273
1274 Packed data can either be 1 byte per sample or 1 double per sample.
1275
1276 Each pixel returned by getscanline() or supplied to setscanline()
1277 contains 4 samples, even if the image has fewer then 4 channels.  The
1278 values of the extra samples as returned by getscanline() is not
1279 specified.  The extra samples passed to setscanline() are ignored.
1280
1281 To produce packed 1 byte/sample pixels, use the pack C<C> template:
1282
1283   my $packed_8bit_pixel = pack("CCCC", $red, $blue, $green, $alpha);
1284
1285 To produce packed double/sample pixels, use the pack C<d> template:
1286
1287   my $packed_float_pixel = pack("dddd", $red, $blue, $green, $alpha);
1288
1289 Note that double/sample data is always stored using the C C<double>
1290 type, never C<long double>, even if C<perl> is built with
1291 C<-Duselongdouble>.
1292
1293 If you use a I<type> parameter of C<index> then the values are palette
1294 color indexes, not sample values:
1295
1296   my $im = Imager->new(xsize => 100, ysize => 100, type => 'paletted');
1297   my $black_index = $im->addcolors(colors => [ 'black' ]);
1298   my $red_index = $im->addcolors(colors => [ 'red' ]);
1299   # 2 pixels
1300   my $packed_index_data = pack("C*", $black_index, $red_index);
1301   $im->setscanline(y => $y, pixels => $packed_index_data, type => 'index');
1302
1303 =head1 Combine Types
1304
1305 Some methods accept a C<combine> parameter, this can be any of the
1306 following:
1307
1308 =over
1309
1310 =item C<none>
1311
1312 The fill pixel replaces the target pixel.
1313
1314 =item C<normal>
1315
1316 The fill pixels alpha value is used to combine it with the target pixel.
1317
1318 =item C<multiply>
1319
1320 =item C<mult>
1321
1322 Each channel of fill and target is multiplied, and the result is
1323 combined using the alpha channel of the fill pixel.
1324
1325 =item C<dissolve>
1326
1327 If the alpha of the fill pixel is greater than a random number, the
1328 fill pixel is alpha combined with the target pixel.
1329
1330 =item C<add>
1331
1332 The channels of the fill and target are added together, clamped to the range of the samples and alpha combined with the target.
1333
1334 =item C<subtract>
1335
1336 The channels of the fill are subtracted from the target, clamped to be
1337 >= 0, and alpha combined with the target.
1338
1339 =item C<diff>
1340
1341 The channels of the fill are subtracted from the target and the
1342 absolute value taken this is alpha combined with the target.
1343
1344 =item C<lighten>
1345
1346 The higher value is taken from each channel of the fill and target
1347 pixels, which is then alpha combined with the target.
1348
1349 =item C<darken>
1350
1351 The higher value is taken from each channel of the fill and target
1352 pixels, which is then alpha combined with the target.
1353
1354 =item C<hue>
1355
1356 The combination of the saturation and value of the target is combined
1357 with the hue of the fill pixel, and is then alpha combined with the
1358 target.
1359
1360 =item C<sat>
1361
1362 The combination of the hue and value of the target is combined
1363 with the saturation of the fill pixel, and is then alpha combined with the
1364 target.
1365
1366 =item C<value>
1367
1368 The combination of the hue and value of the target is combined
1369 with the value of the fill pixel, and is then alpha combined with the
1370 target.
1371
1372 =item C<color>
1373
1374 The combination of the value of the target is combined with the hue
1375 and saturation of the fill pixel, and is then alpha combined with the
1376 target.
1377
1378 =back
1379
1380 =over
1381
1382 =item combines()
1383
1384 Returns a list of possible combine types.
1385
1386 =back
1387
1388 =head1 BUGS
1389
1390 box() does not support anti-aliasing yet.  Default color is not
1391 unified yet.
1392
1393 =head1 AUTHOR
1394
1395 Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson.
1396
1397 =head1 SEE ALSO
1398
1399 L<Imager>(3), L<Imager::Cookbook>(3)
1400
1401 =head1 REVISION
1402
1403 $Revision$
1404
1405 =cut