]>
Commit | Line | Data |
---|---|---|
7144e056 AMH |
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, | |
aa833c97 | 15 | y1=>20, y2=>50, aa=>1, endp=>1 ); |
7144e056 AMH |
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 | ||
9ecefd41 | 25 | $img->arc(color=>$blue, r=>20, x=>200, y=>100, |
7144e056 AMH |
26 | d1=>10, d2=>20 ); |
27 | ||
9ecefd41 | 28 | $img->circle(color=>$blue, r=>50, x=>200, y=>100); |
7144e056 AMH |
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 | ||
591b5954 TC |
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 | ||
08e6cbea TC |
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', | |
cad360aa | 58 | valign => 'bottom', |
08e6cbea TC |
59 | string => 'Imager', |
60 | font => $font, | |
61 | size => 12); | |
62 | ||
ca4d914e TC |
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 | ||
7144e056 AMH |
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 | |
7117f25c | 76 | corner of an image with co-ordinates increasing to the right and |
5715f7c3 TC |
77 | bottom. For non anti-aliasing operation all coordinates are rounded |
78 | towards the nearest integer. For anti-aliased operations floating | |
7144e056 AMH |
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 | |
7468f3fa | 83 | it is necessary to check for off-by-one cases. Typically it's useful to |
5715f7c3 | 84 | think of C<(10, 20)> as C<(10.00, 20.00)> and consider the consequences. |
7144e056 | 85 | |
08e6cbea TC |
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: | |
ed9e5812 TC |
93 | |
94 | $image->box(..., color=>'red'); | |
95 | $image->line(..., color=>'#FF0000'); | |
96 | $image->flood_fill(..., color=>[ 255, 0, 255 ]); | |
7144e056 | 97 | |
8289f78b TC |
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 | ||
08e6cbea TC |
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 | |
ed9e5812 TC |
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 }); | |
7144e056 AMH |
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 | ||
ec5d8b5c TC |
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 | ||
7144e056 AMH |
153 | =head2 List of primitives |
154 | ||
155 | =over | |
156 | ||
67d441b2 | 157 | =item line() |
7144e056 AMH |
158 | |
159 | $img->line(color=>$green, x1=>10, x2=>100, | |
aa833c97 | 160 | y1=>20, y2=>50, aa=>1, endp=>1 ); |
7144e056 | 161 | |
08e6cbea | 162 | X<line method>Draws a line from (x1,y1) to (x2,y2). The endpoint |
5715f7c3 | 163 | (x2,y2) is drawn by default. If C<endp> of 0 is specified then the |
08e6cbea | 164 | endpoint will not be drawn. If C<aa> is set then the line will be |
5715f7c3 | 165 | drawn anti-aliased. The C<antialias> parameter is still available for |
08e6cbea TC |
166 | backwards compatibility. |
167 | ||
168 | Parameters: | |
169 | ||
170 | =over | |
171 | ||
172 | =item * | |
173 | ||
5715f7c3 | 174 | C<x1>, C<y1> - starting point of the line. Required. |
08e6cbea TC |
175 | |
176 | =item * | |
177 | ||
5715f7c3 | 178 | C<x2>, C<y2> - end point of the line. Required. |
08e6cbea TC |
179 | |
180 | =item * | |
181 | ||
67d441b2 | 182 | C<color> - the color of the line. See L</"Color Parameters">. Default: |
08e6cbea TC |
183 | black. |
184 | ||
185 | =item * | |
186 | ||
5715f7c3 TC |
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 | |
08e6cbea TC |
189 | series of connected lines. |
190 | ||
191 | =item * | |
192 | ||
5715f7c3 | 193 | C<aa> - if true the line is drawn anti-aliased. Default: 0. |
08e6cbea TC |
194 | |
195 | =back | |
7144e056 | 196 | |
67d441b2 | 197 | =item polyline() |
7144e056 AMH |
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 | ||
5715f7c3 | 202 | X<polyline method>C<polyline> is used to draw multiple lines between a |
08e6cbea TC |
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. | |
7144e056 | 207 | |
5715f7c3 | 208 | The C<antialias> parameter is still available for backwards compatibility. |
7144e056 | 209 | |
08e6cbea TC |
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 | ||
67d441b2 | 232 | C<color> - the color of the line. See L</"Color Parameters">. |
5715f7c3 | 233 | Default: black. |
08e6cbea TC |
234 | |
235 | =item * | |
236 | ||
5715f7c3 TC |
237 | C<aa> - if true the line is drawn anti-aliased. Default: 0. Can also |
238 | be supplied as C<antialias> for backward compatibility. | |
08e6cbea TC |
239 | |
240 | =back | |
241 | ||
67d441b2 | 242 | =item box() |
7144e056 AMH |
243 | |
244 | $blue = Imager::Color->new( 0, 0, 255 ); | |
ed9e5812 TC |
245 | $img->box(color => $blue, xmin=>10, ymin=>30, xmax=>200, ymax=>300, |
246 | filled=>1); | |
7144e056 | 247 | |
5715f7c3 | 248 | X<box method>If any of the edges of the box are omitted it will snap |
08e6cbea | 249 | to the outer edge of the image in that direction. If C<filled> is |
5715f7c3 | 250 | omitted the box is drawn as an outline. Instead of a color it is |
08e6cbea | 251 | possible to use a C<fill> pattern: |
7144e056 AMH |
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 | |
55b287f5 | 260 | instead. [NOTE: This may change to use C<$img-E<gt>fgcolor()> in the future]. |
7144e056 AMH |
261 | |
262 | Box does not support fractional coordinates yet. | |
263 | ||
08e6cbea TC |
264 | Parameters: |
265 | ||
266 | =over | |
267 | ||
268 | =item * | |
269 | ||
5715f7c3 | 270 | C<xmin> - left side of the box. Default: 0 (left edge of the image) |
08e6cbea TC |
271 | |
272 | =item * | |
273 | ||
5715f7c3 | 274 | C<ymin> - top side of the box. Default: 0 (top edge of the image) |
08e6cbea TC |
275 | |
276 | =item * | |
277 | ||
5715f7c3 TC |
278 | C<xmax> - right side of the box. Default: C<< $img->getwidth-1 |
279 | >>. (right edge of the image) | |
08e6cbea TC |
280 | |
281 | =item * | |
282 | ||
5715f7c3 TC |
283 | C<ymax> - bottom side of the box. Default: C<< $img->getheight-1 |
284 | >>. (bottom edge of the image) | |
08e6cbea | 285 | |
5715f7c3 TC |
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)>. | |
08e6cbea TC |
288 | |
289 | =item * | |
290 | ||
5715f7c3 TC |
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. | |
08e6cbea TC |
294 | |
295 | =item * | |
296 | ||
67d441b2 | 297 | C<color> - the color of the line. See L</"Color Parameters">. |
5715f7c3 | 298 | Default: white. This is ignored if the filled parameter |
08e6cbea TC |
299 | |
300 | =item * | |
301 | ||
5715f7c3 | 302 | C<filled> - if non-zero the box is filled with I<color> instead of |
08e6cbea TC |
303 | outlined. Default: an outline is drawn. |
304 | ||
305 | =item * | |
306 | ||
5715f7c3 | 307 | C<fill> - the fill for the box. If this is supplied then the box will be |
67d441b2 | 308 | filled. See L</"Fill Parameters">. |
08e6cbea TC |
309 | |
310 | =back | |
311 | ||
67d441b2 | 312 | =item arc() |
7144e056 | 313 | |
9ecefd41 | 314 | $img->arc(color=>$red, r=>20, x=>200, y=>100, d1=>10, d2=>20 ); |
7144e056 AMH |
315 | |
316 | This creates a filled red arc with a 'center' at (200, 100) and spans | |
40068b33 TC |
317 | 10 degrees and the slice has a radius of 20. |
318 | ||
7144e056 AMH |
319 | It's also possible to supply a C<fill> parameter. |
320 | ||
40068b33 TC |
321 | To draw just an arc outline - just the curve, not the radius lines, |
322 | set filled to 0: | |
323 | ||
08e6cbea TC |
324 | Parameters: |
325 | ||
40068b33 TC |
326 | $img->arc(color=>$red, r=>20, x=>200, y=>100, d1=>10, d2=>20, filled=>0 ); |
327 | ||
08e6cbea TC |
328 | =over |
329 | ||
330 | =item * | |
331 | ||
5715f7c3 | 332 | C<x>, C<y> - center of the filled arc. Default: center of the image. |
08e6cbea TC |
333 | |
334 | =item * | |
335 | ||
5715f7c3 | 336 | C<r> - radius of the arc. Default: 1/3 of min(image height, image width). |
08e6cbea TC |
337 | |
338 | =item * | |
339 | ||
5715f7c3 | 340 | C<d1> - starting angle of the arc, in degrees. Default: 0 |
08e6cbea TC |
341 | |
342 | =item * | |
343 | ||
5715f7c3 | 344 | C<d2> - ending angle of the arc, in degrees. Default: 361. |
08e6cbea TC |
345 | |
346 | =item * | |
347 | ||
67d441b2 | 348 | C<color> - the color of the filled arc. See L</"Color Parameters">. |
08e6cbea TC |
349 | Default: white. Overridden by C<fill>. |
350 | ||
351 | =item * | |
352 | ||
67d441b2 | 353 | C<fill> - the fill for the filled arc. See L</"Fill Parameters"> |
08e6cbea TC |
354 | |
355 | =item * | |
356 | ||
5715f7c3 | 357 | C<aa> - if true the filled arc is drawn anti-aliased. Default: false. |
08e6cbea TC |
358 | |
359 | Anti-aliased arc() is experimental for now, I'm not entirely happy | |
360 | with the results in some cases. | |
361 | ||
40068b33 TC |
362 | =item * |
363 | ||
5715f7c3 | 364 | C<filled> - set to 0 to draw only an outline. |
40068b33 | 365 | |
08e6cbea TC |
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 | ||
80599c3f TC |
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 | ||
67d441b2 | 383 | =item circle() |
7144e056 | 384 | |
08e6cbea | 385 | $img->circle(color=>$green, r=>50, x=>200, y=>100, aa=>1, filled=>1); |
7144e056 | 386 | |
5715f7c3 | 387 | This creates an anti-aliased green circle with its center at (200, 100) |
7144e056 AMH |
388 | and has a radius of 50. It's also possible to supply a C<fill> parameter |
389 | instead of a color parameter. | |
390 | ||
08e6cbea TC |
391 | $img->circle(r => 50, x=> 150, y => 150, fill=>{ hatch => 'stipple' }); |
392 | ||
40068b33 TC |
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); | |
7144e056 | 396 | |
08e6cbea TC |
397 | =over |
398 | ||
399 | =item * | |
400 | ||
5715f7c3 | 401 | C<x>, C<y> - center of the filled circle. Default: center of the image. |
08e6cbea TC |
402 | |
403 | =item * | |
404 | ||
5715f7c3 | 405 | C<r> - radius of the circle. Default: 1/3 of min(image height, image width). |
08e6cbea TC |
406 | |
407 | =item * | |
408 | ||
67d441b2 | 409 | C<color> - the color of the filled circle. See L</"Color Parameters">. |
08e6cbea TC |
410 | Default: white. Overridden by C<fill>. |
411 | ||
412 | =item * | |
413 | ||
67d441b2 | 414 | C<fill> - the fill for the filled circle. See L</"Fill Parameters"> |
08e6cbea TC |
415 | |
416 | =item * | |
417 | ||
5715f7c3 | 418 | C<aa> - if true the filled circle is drawn anti-aliased. Default: false. |
08e6cbea | 419 | |
40068b33 TC |
420 | =item * |
421 | ||
5715f7c3 | 422 | C<filled> - set to 0 to just draw an outline. |
40068b33 | 423 | |
08e6cbea | 424 | =back |
7144e056 | 425 | |
5715f7c3 | 426 | =item polygon() |
7144e056 AMH |
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 | |
5715f7c3 TC |
432 | always drawn anti-aliased, although that will change in the future. |
433 | Like other anti-aliased drawing functions its coordinates can be | |
7144e056 AMH |
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 | ||
08e6cbea TC |
437 | =over |
438 | ||
439 | =item * | |
440 | ||
5715f7c3 | 441 | C<points> - a reference to an array of references to arrays containing |
08e6cbea TC |
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 | ||
5715f7c3 | 449 | C<x>, C<y> - each is an array of x or y ordinates. This is an alternative |
08e6cbea TC |
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 | ||
67d441b2 | 459 | C<color> - the color of the filled polygon. See L</"Color Parameters">. |
08e6cbea TC |
460 | Default: black. Overridden by C<fill>. |
461 | ||
462 | =item * | |
463 | ||
67d441b2 | 464 | C<fill> - the fill for the filled circle. See L</"Fill Parameters"> |
08e6cbea | 465 | |
ec5d8b5c TC |
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 | ||
08e6cbea TC |
512 | =back |
513 | ||
ec5d8b5c TC |
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 | ||
5715f7c3 | 522 | =item flood_fill() |
7144e056 | 523 | |
3efb0915 TC |
524 | X<flood_fill>You can fill a region that all has the same color using |
525 | the flood_fill() method, for example: | |
7144e056 AMH |
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 | ||
3efb0915 TC |
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 | ||
ed9e5812 TC |
536 | You can also fill with a complex fill: |
537 | ||
538 | $img->flood_fill(x=>50, y=>50, fill=>{ hatch=>'cross1x1' }); | |
539 | ||
08e6cbea TC |
540 | Parameters: |
541 | ||
542 | =over | |
543 | ||
544 | =item * | |
545 | ||
5715f7c3 | 546 | C<x>, C<y> - the start point of the fill. |
08e6cbea TC |
547 | |
548 | =item * | |
549 | ||
67d441b2 | 550 | C<color> - the color of the filled area. See L</"Color Parameters">. |
08e6cbea TC |
551 | Default: white. Overridden by C<fill>. |
552 | ||
553 | =item * | |
554 | ||
67d441b2 | 555 | C<fill> - the fill for the filled area. See L</"Fill Parameters"> |
08e6cbea | 556 | |
3efb0915 TC |
557 | =item * |
558 | ||
5715f7c3 | 559 | C<border> - the border color of the region to be filled. If this |
3efb0915 TC |
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 | |
67d441b2 | 562 | supplied as a L</"Color Parameters">. |
3efb0915 | 563 | |
08e6cbea TC |
564 | =back |
565 | ||
5715f7c3 | 566 | =item setpixel() |
591b5954 TC |
567 | |
568 | $img->setpixel(x=>50, y=>70, color=>$color); | |
569 | $img->setpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40], color=>$color); | |
08e6cbea TC |
570 | |
571 | setpixel() is used to set one or more individual pixels. | |
572 | ||
2a27eeff TC |
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 | ||
08e6cbea TC |
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 | ||
67d441b2 | 608 | color - the color of the pixels drawn. See L</"Color Parameters">. |
08e6cbea TC |
609 | Default: white. |
610 | ||
611 | =back | |
612 | ||
5daeb11a TC |
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">. | |
f2ad77de | 615 | |
5daeb11a | 616 | For other errors, setpixel() returns an empty list and sets errstr(). |
f2ad77de | 617 | |
2a27eeff TC |
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 | ||
5715f7c3 | 633 | =item getpixel() |
08e6cbea | 634 | |
2a27eeff TC |
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]); | |
591b5954 | 638 | |
08e6cbea | 639 | getpixel() is used to retrieve one or more individual pixels. |
591b5954 | 640 | |
2a27eeff TC |
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 ]); | |
591b5954 | 654 | |
2a27eeff TC |
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 ]); | |
591b5954 | 663 | |
5715f7c3 | 664 | To receive floating point colors from getpixel(), set the C<type> |
591b5954 | 665 | parameter to 'float'. |
7144e056 | 666 | |
08e6cbea TC |
667 | Parameters: |
668 | ||
669 | =over | |
670 | ||
671 | =item * | |
672 | ||
ab53641f | 673 | C<x>, C<y> - either integers giving the co-ordinates of the pixel to set or |
08e6cbea TC |
674 | array references containing a set of pixels to be set. |
675 | ||
676 | =item * | |
677 | ||
ab53641f TC |
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'>. | |
08e6cbea TC |
681 | |
682 | =back | |
683 | ||
2a27eeff TC |
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 | ||
ab53641f TC |
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 | ||
2a27eeff TC |
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 | ||
67d441b2 | 710 | =item string() |
08e6cbea TC |
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 | ||
5715f7c3 TC |
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. | |
08e6cbea TC |
731 | |
732 | =item * | |
733 | ||
5715f7c3 | 734 | C<string> - the text to draw. Required unless you supply the C<text> |
08e6cbea TC |
735 | parameter. |
736 | ||
737 | =item * | |
738 | ||
5715f7c3 | 739 | C<font> - an L<Imager::Font> object representing the font to draw the |
08e6cbea TC |
740 | text with. Required. |
741 | ||
742 | =item * | |
743 | ||
5715f7c3 | 744 | C<aa> - if non-zero the output will be anti-aliased. Default: the value |
08e6cbea TC |
745 | set in Imager::Font->new() or 0 if not set. |
746 | ||
747 | =item * | |
748 | ||
5715f7c3 | 749 | C<align> - if non-zero the point supplied in (x,y) will be on the |
08e6cbea TC |
750 | base-line, if zero then (x,y) will be at the top-left of the string. |
751 | ||
5715f7c3 | 752 | i.e. if drawing the string C<"yA"> and align is 0 the point (x,y) will |
08e6cbea TC |
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 | ||
5715f7c3 | 761 | C<channel> - if present, the text will be written to the specified |
08e6cbea TC |
762 | channel of the image and the color parameter will be ignore. |
763 | ||
764 | =item * | |
765 | ||
5715f7c3 | 766 | C<color> - the color to draw the text in. Default: the color supplied to |
08e6cbea TC |
767 | Imager::Font->new, or red if none. |
768 | ||
769 | =item * | |
770 | ||
5715f7c3 TC |
771 | C<size> - the point size to draw the text at. Default: the size |
772 | supplied to Imager::Font->new, or 15. | |
08e6cbea TC |
773 | |
774 | =item * | |
775 | ||
5715f7c3 TC |
776 | C<sizew> - the width scaling to draw the text at. Default: the value |
777 | of C<size>. | |
08e6cbea TC |
778 | |
779 | =item * | |
780 | ||
5715f7c3 TC |
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 | |
67d441b2 | 784 | already a UTF-8 string. See L<Imager::Font/"UTF-8"> for more |
5715f7c3 | 785 | information. |
08e6cbea TC |
786 | |
787 | =item * | |
788 | ||
5715f7c3 | 789 | C<vlayout> - for drivers that support it, draw the text vertically. |
08e6cbea TC |
790 | Note: I haven't found a font that has the appropriate metrics yet. |
791 | ||
792 | =item * | |
793 | ||
5715f7c3 | 794 | C<text> - alias for the C<string> parameter. |
08e6cbea TC |
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 | ||
67d441b2 | 801 | =item align_string() |
08e6cbea TC |
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 | ||
5715f7c3 TC |
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. | |
08e6cbea TC |
821 | |
822 | =item * | |
823 | ||
5715f7c3 TC |
824 | C<string> - the text to draw. Required unless you supply the C<text> |
825 | parameter. | |
08e6cbea TC |
826 | |
827 | =item * | |
828 | ||
5715f7c3 | 829 | C<font> - an L<Imager::Font> object representing the font to draw the |
08e6cbea TC |
830 | text with. Required. |
831 | ||
832 | =item * | |
833 | ||
5715f7c3 | 834 | C<aa> - if non-zero the output will be anti-aliased |
08e6cbea TC |
835 | |
836 | =item * | |
837 | ||
5715f7c3 | 838 | C<valign> - vertical alignment of the text against (x,y) |
08e6cbea TC |
839 | |
840 | =over | |
841 | ||
842 | =item * | |
843 | ||
5715f7c3 | 844 | C<top> - Point is at the top of the text. |
08e6cbea TC |
845 | |
846 | =item * | |
847 | ||
5715f7c3 | 848 | C<bottom> - Point is at the bottom of the text. |
08e6cbea TC |
849 | |
850 | =item * | |
851 | ||
5715f7c3 | 852 | C<baseline> - Point is on the baseline of the text. This is the default. |
08e6cbea TC |
853 | |
854 | =item * | |
855 | ||
5715f7c3 | 856 | C<center> - Point is vertically centered within the text. |
08e6cbea TC |
857 | |
858 | =back | |
859 | ||
860 | =item * | |
861 | ||
5715f7c3 | 862 | C<halign> - horizontal alignment of the text against (x,y) |
08e6cbea TC |
863 | |
864 | =over | |
865 | ||
866 | =item * | |
867 | ||
5715f7c3 | 868 | C<left> - The point is at the left of the text. This is the default. |
08e6cbea TC |
869 | |
870 | =item * | |
871 | ||
5715f7c3 | 872 | C<start> - The point is at the start point of the text. |
08e6cbea TC |
873 | |
874 | =item * | |
875 | ||
5715f7c3 | 876 | C<center> - The point is horizontally centered within the text. |
08e6cbea TC |
877 | |
878 | =item * | |
879 | ||
5715f7c3 | 880 | C<right> - The point is at the right end of the text. |
08e6cbea TC |
881 | |
882 | =item * | |
883 | ||
5715f7c3 | 884 | C<end> - The point is at the end point of the text. |
08e6cbea TC |
885 | |
886 | =back | |
887 | ||
888 | =item * | |
889 | ||
5715f7c3 | 890 | C<channel> - if present, the text will be written to the specified |
08e6cbea TC |
891 | channel of the image and the color parameter will be ignore. |
892 | ||
893 | =item * | |
894 | ||
5715f7c3 | 895 | C<color> - the color to draw the text in. Default: the color supplied to |
08e6cbea TC |
896 | Imager::Font->new, or red if none. |
897 | ||
898 | =item * | |
899 | ||
5715f7c3 | 900 | C<size> - the point size to draw the text at. Default: the size supplied |
08e6cbea TC |
901 | to Imager::Font->new, or 15. |
902 | ||
903 | =item * | |
904 | ||
5715f7c3 | 905 | C<sizew> - the width scaling to draw the text at. Default: the value of |
08e6cbea TC |
906 | C<size>. |
907 | ||
908 | =item * | |
909 | ||
5715f7c3 TC |
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. | |
08e6cbea TC |
915 | |
916 | =item * | |
917 | ||
5715f7c3 | 918 | C<vlayout> - for drivers that support it, draw the text vertically. |
08e6cbea TC |
919 | Note: I haven't found a font that has the appropriate metrics yet. |
920 | ||
921 | =item * | |
922 | ||
5715f7c3 | 923 | C<text> - alias for the C<string> parameter. |
08e6cbea TC |
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 | ||
5715f7c3 TC |
930 | On error, align_string() returns an empty list and you can use |
931 | C<< $img->errstr >> to get the reason for the error. | |
08e6cbea | 932 | |
5715f7c3 | 933 | =item setscanline() |
ca4d914e TC |
934 | |
935 | Set all or part of a horizontal line of pixels to an image. This | |
67d441b2 | 936 | method is most useful in conjunction with L</getscanline()>. |
ca4d914e TC |
937 | |
938 | The parameters you can pass are: | |
939 | ||
940 | =over | |
941 | ||
942 | =item * | |
943 | ||
5715f7c3 | 944 | C<y> - vertical position of the scan line. This parameter is required. |
ca4d914e TC |
945 | |
946 | =item * | |
947 | ||
5715f7c3 | 948 | C<x> - position to start on the scan line. Default: 0 |
ca4d914e TC |
949 | |
950 | =item * | |
951 | ||
5715f7c3 | 952 | C<pixels> - either a reference to an array containing Imager::Color |
ca4d914e TC |
953 | objects, an reference to an array containing Imager::Color::Float |
954 | objects or a scalar containing packed color data. | |
955 | ||
4cda4e76 TC |
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 | ||
ca4d914e TC |
959 | See L</"Packed Color Data"> for information on the format of packed |
960 | color data. | |
961 | ||
962 | =item * | |
963 | ||
5715f7c3 | 964 | C<type> - the type of pixel data supplied. If you supply an array |
78660b6c TC |
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'>. | |
ca4d914e | 968 | |
5715f7c3 | 969 | You can use C<float> or C<8bit> samples with any image. |
ca4d914e | 970 | |
78660b6c TC |
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. | |
4cda4e76 | 973 | |
ca4d914e TC |
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 | ||
5715f7c3 | 1022 | =item getscanline() |
ca4d914e | 1023 | |
51c27309 | 1024 | Read all or part of a horizontal line of pixels from an image. This |
67d441b2 | 1025 | method is most useful in conjunction with L</setscanline()>. |
ca4d914e TC |
1026 | |
1027 | The parameters you can pass are: | |
1028 | ||
1029 | =over | |
1030 | ||
1031 | =item * | |
1032 | ||
5715f7c3 | 1033 | C<y> - vertical position of the scan line. This parameter is required. |
ca4d914e TC |
1034 | |
1035 | =item * | |
1036 | ||
5715f7c3 | 1037 | C<x> - position to start on the scan line. Default: 0 |
ca4d914e TC |
1038 | |
1039 | =item * | |
1040 | ||
5715f7c3 | 1041 | C<width> - number of pixels to read. Default: $img->getwidth - x |
ca4d914e TC |
1042 | |
1043 | =item * | |
1044 | ||
5715f7c3 | 1045 | C<type> - the type of pixel data to return. Default: C<8bit>. |
ca4d914e | 1046 | |
5715f7c3 | 1047 | Permitted values are C<8bit> and C<float> and C<index>. |
ca4d914e TC |
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 | |
4cda4e76 TC |
1053 | objects when I<type> if C<float>, or a list of integers when I<type> |
1054 | is C<index>. | |
ca4d914e TC |
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 | |
4cda4e76 | 1058 | C<float>, or packed palette color indexes when I<type> is C<index>. |
ca4d914e TC |
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 | ||
67d441b2 | 1094 | Some of the examples for L</setscanline()> for more examples. |
ca4d914e | 1095 | |
5715f7c3 | 1096 | =item getsamples() |
ca4d914e TC |
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 | ||
5715f7c3 | 1107 | C<y> - vertical position of the scan line. This parameter is required. |
ca4d914e TC |
1108 | |
1109 | =item * | |
1110 | ||
5715f7c3 | 1111 | C<x> - position to start on the scan line. Default: 0 |
ca4d914e TC |
1112 | |
1113 | =item * | |
1114 | ||
5715f7c3 | 1115 | C<width> - number of pixels to read. Default: C<< $img->getwidth - x >> |
ca4d914e TC |
1116 | |
1117 | =item * | |
1118 | ||
5715f7c3 | 1119 | C<type> - the type of sample data to return. Default: C<8bit>. |
ca4d914e | 1120 | |
5715f7c3 | 1121 | Permitted values are C<8bit> and C<float>. |
ca4d914e | 1122 | |
bd8052a6 TC |
1123 | As of Imager 0.61 this can be C<16bit> only for 16 bit images. |
1124 | ||
ca4d914e TC |
1125 | =item * |
1126 | ||
5715f7c3 TC |
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 ] >> | |
ca4d914e | 1129 | |
bd8052a6 TC |
1130 | =item * |
1131 | ||
5715f7c3 | 1132 | C<target> - if an array reference is supplied in target then the samples |
bd8052a6 TC |
1133 | will be stored here instead of being returned. |
1134 | ||
1135 | =item * | |
1136 | ||
5715f7c3 | 1137 | C<offset> - the offset within the array referenced by I<target> |
bd8052a6 | 1138 | |
ca4d914e TC |
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 | ||
bd8052a6 TC |
1149 | If the I<target> option is supplied then only a count of samples is |
1150 | returned. | |
1151 | ||
ca4d914e TC |
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 | ||
5715f7c3 | 1164 | Example: Convert a 2 channel gray image into a 4 channel RGBA image: |
ca4d914e TC |
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 | ||
bd8052a6 TC |
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 | ||
5715f7c3 | 1182 | =item setsamples() |
bd8052a6 | 1183 | |
78660b6c | 1184 | This allows writing of samples to an image. |
bd8052a6 TC |
1185 | |
1186 | Parameters: | |
1187 | ||
1188 | =over | |
1189 | ||
1190 | =item * | |
1191 | ||
5715f7c3 | 1192 | C<y> - vertical position of the scan line. This parameter is required. |
bd8052a6 TC |
1193 | |
1194 | =item * | |
1195 | ||
5715f7c3 | 1196 | C<x> - position to start on the scan line. Default: 0 |
bd8052a6 TC |
1197 | |
1198 | =item * | |
1199 | ||
5715f7c3 TC |
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. | |
bd8052a6 TC |
1203 | |
1204 | =item * | |
1205 | ||
5715f7c3 | 1206 | C<type> - the type of sample data to write. This parameter is required. |
bd8052a6 | 1207 | |
0c78633e | 1208 | This can be C<8bit>, C<float> or for 16-bit images only, C<16bit>. |
bd8052a6 TC |
1209 | |
1210 | =item * | |
1211 | ||
5715f7c3 | 1212 | C<channels> - a reference to an array of channels to return, where 0 is |
de3ca2fd | 1213 | the first channel. Default: C<< [ 0 .. $self->getchannels()-1 ] >> |
bd8052a6 TC |
1214 | |
1215 | =item * | |
1216 | ||
0c78633e TC |
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. | |
bd8052a6 TC |
1225 | |
1226 | =item * | |
1227 | ||
0c78633e TC |
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. | |
bd8052a6 TC |
1231 | |
1232 | =back | |
1233 | ||
1234 | Returns the number of samples written. | |
1235 | ||
0c78633e TC |
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 | ||
ca4d914e TC |
1263 | =back |
1264 | ||
1265 | =head1 Packed Color Data | |
1266 | ||
0c78633e | 1267 | The getscanline() and setscanline() methods can work with pixels |
ca4d914e TC |
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 | ||
0c78633e TC |
1271 | The getsamples() and setsamples() methods can work with samples packed |
1272 | into scalars. | |
1273 | ||
ca4d914e TC |
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 | ||
78660b6c TC |
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 | ||
4cda4e76 TC |
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 | ||
9b1ec2b8 TC |
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 | ||
5715f7c3 | 1310 | =item C<none> |
9b1ec2b8 TC |
1311 | |
1312 | The fill pixel replaces the target pixel. | |
1313 | ||
5715f7c3 | 1314 | =item C<normal> |
9b1ec2b8 TC |
1315 | |
1316 | The fill pixels alpha value is used to combine it with the target pixel. | |
1317 | ||
5715f7c3 | 1318 | =item C<multiply> |
9b1ec2b8 | 1319 | |
5715f7c3 | 1320 | =item C<mult> |
9b1ec2b8 TC |
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 | ||
5715f7c3 | 1325 | =item C<dissolve> |
9b1ec2b8 TC |
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 | ||
5715f7c3 | 1330 | =item C<add> |
9b1ec2b8 TC |
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 | ||
5715f7c3 | 1334 | =item C<subtract> |
9b1ec2b8 TC |
1335 | |
1336 | The channels of the fill are subtracted from the target, clamped to be | |
1337 | >= 0, and alpha combined with the target. | |
1338 | ||
5715f7c3 | 1339 | =item C<diff> |
9b1ec2b8 TC |
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 | ||
5715f7c3 | 1344 | =item C<lighten> |
9b1ec2b8 TC |
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 | ||
5715f7c3 | 1349 | =item C<darken> |
9b1ec2b8 TC |
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 | ||
5715f7c3 | 1354 | =item C<hue> |
9b1ec2b8 TC |
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 | ||
5715f7c3 | 1360 | =item C<sat> |
9b1ec2b8 TC |
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 | ||
5715f7c3 | 1366 | =item C<value> |
9b1ec2b8 TC |
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 | ||
5715f7c3 | 1372 | =item C<color> |
9b1ec2b8 TC |
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 | ||
5715f7c3 | 1382 | =item combines() |
9b1ec2b8 TC |
1383 | |
1384 | Returns a list of possible combine types. | |
1385 | ||
1386 | =back | |
1387 | ||
bac4fcee AMH |
1388 | =head1 BUGS |
1389 | ||
5715f7c3 TC |
1390 | box() does not support anti-aliasing yet. Default color is not |
1391 | unified yet. | |
bac4fcee | 1392 | |
08e6cbea TC |
1393 | =head1 AUTHOR |
1394 | ||
5b480b14 | 1395 | Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson. |
08e6cbea | 1396 | |
ed9e5812 TC |
1397 | =head1 SEE ALSO |
1398 | ||
08e6cbea TC |
1399 | L<Imager>(3), L<Imager::Cookbook>(3) |
1400 | ||
1401 | =head1 REVISION | |
1402 | ||
1403 | $Revision$ | |
ed9e5812 | 1404 | |
f75c1aeb | 1405 | =cut |