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