X-Git-Url: http://git.imager.perl.org/imager.git/blobdiff_plain/bac4fcee03b3ae21face1a0281dfe5851e2e010d..bd4f550c29eb95bf841523fe3ed143a77a79674c:/lib/Imager/Draw.pod diff --git a/lib/Imager/Draw.pod b/lib/Imager/Draw.pod index 60afb624..925facc1 100644 --- a/lib/Imager/Draw.pod +++ b/lib/Imager/Draw.pod @@ -12,7 +12,7 @@ Imager::Draw - Draw primitives to images $fill = Imager::Fill->new(hatch=>'stipple'); $img->line(color=>$blue, x1=>10, x2=>100, - y1=>20, y2=>50, aa=>1 ); + y1=>20, y2=>50, aa=>1, endp=>1 ); $img->polyline(points=>[[$x0,$y0], [$x1,$y1], [$x2,$y2]], color=>$blue); @@ -22,10 +22,10 @@ Imager::Draw - Draw primitives to images xmax=>200, ymax=>300, filled=>1); $img->box(fill=>$fill); - $img->arc(color=>$blue, r=20, x=>200, y=>100, + $img->arc(color=>$blue, r=>20, x=>200, y=>100, d1=>10, d2=>20 ); - $img->circle(color=>$blue, r=50, x=>200, y=>100); + $img->circle(color=>$blue, r=>50, x=>200, y=>100); $img->polygon(points=>[[$x0,$y0], [$x1,$y1], [$x2,$y2]], color=>$blue); @@ -34,13 +34,48 @@ Imager::Draw - Draw primitives to images $img->flood_fill(x=>50, y=>50, color=>$color); + $img->setpixel(x=>50, y=>70, color=>$color); + + $img->setpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40], color=>$color); + + my $color = $img->getpixel(x=>50, y=>70); + + my @colors = $img->getpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40]); + + # drawing text + my $font = Imager::Font->new(...) or die; + $img->string(x => 50, y => 70, + font => $font, + string => "Hello, World!", + color => 'red', + size => 30, + aa => 1); + + # bottom right-hand corner of the image + $img->align_string(x => $img->getwidth() - 1, + y => $img->getheight() - 1, + halign => 'right', + valign => 'bottom', + string => 'Imager', + font => $font, + size => 12); + + # low-level functions + my @colors = $img->getscanline(y=>50, x=>10, width=>20); + + $img->setscanline(y=>60, x=>20, pixels=>\@colors); + + my @samples = $img->getsamples(y=>50, x=>10, width=>20, + channels=>[ 2, 0 ]); + =head1 DESCRIPTION It is possible to draw with graphics primitives onto images. Such primitives include boxes, arcs, circles, polygons and lines. The coordinate system in Imager has the origin C<(0,0)> in the upper left -corner of an image. For non antialiasing operation all coordinates are -rounded towards the nearest integer. For antialiased operations floating +corner of an image with co-ordinates increasing to the right and +bottom. For non antialiasing operation all coordinates are rounded +towards the nearest integer. For antialiased operations floating point coordinates are used. Drawing is assumed to take place in a coordinate system of infinite @@ -48,16 +83,30 @@ resolution. This is the typical convention and really only matters when it is necessary to check for off-by-one cases. Typically it's usefull to think of C<(10, 20)> as C<(10.00, 20.00)> and consider the consiquences. -The C parameter for any of the drawing methods can be an -L object, a simple scalar that Imager::Color can -understand, a hashref of parameters that Imager::Color->new -understands, or an arrayref of red, green, blue values. +=head2 Color Parameters + +XThe C parameter for any of the drawing +methods can be an L object, a simple scalar that +Imager::Color can understand, a hashref of parameters that +Imager::Color->new understands, or an arrayref of red, green, blue +values, for example: + + $image->box(..., color=>'red'); + $image->line(..., color=>'#FF0000'); + $image->flood_fill(..., color=>[ 255, 0, 255 ]); -All filled primitives, i.e. C, C, C, -C and the C method can take a C -parameter instead of a C parameter which can either be an -Imager::Fill object, or a reference to a hash containing the -parameters used to create the fill. +=head2 Fill Parameters + +XAll filled primitives, i.e. C, C, +C, C and the C method can take a +C parameter instead of a C parameter which can either be +an Imager::Fill object, or a reference to a hash containing the +parameters used to create the fill, for example: + + $image->box(..., fill=>{ hatch => 'check1x1' }); + my $fillimage = Imager->new; + $fillimage->read(file=>$somefile) or die; + $image->flood_fill(..., fill=>{ image=>$fillimage }); Currently you can create opaque or transparent plain color fills, hatched fills, image based fills and fountain fills. See @@ -70,33 +119,98 @@ L for more information. =item line $img->line(color=>$green, x1=>10, x2=>100, - y1=>20, y2=>50, aa=>1 ); + y1=>20, y2=>50, aa=>1, endp=>1 ); -That draws an antialiased line from (10,100) to (20,50). -The I parameter is still available for backwards compatibility. +XDraws a line from (x1,y1) to (x2,y2). The endpoint +(x2,y2) is drawn by default. If endp of 0 is specified then the +endpoint will not be drawn. If C is set then the line will be +drawn antialiased. The I parameter is still available for +backwards compatibility. + +Parameters: + +=over + +=item * + +x1, y1 - starting point of the line. Required. + +=item * + +x2, y2 - end point of the line. Required. + +=item * + +color - the color of the line. See L<"Color Parameters">. Default: +black. + +=item * + +endp - if zero the end point of the line is not drawn. Default: 1 - +the end point is drawn. This is useful to set to 0 when drawning a +series of connected lines. + +=item * + +aa - if true the line is drawn anti-aliased. Default: 0. + +=back =item polyline $img->polyline(points=>[[$x0,$y0],[$x1,$y1],[$x2,$y2]],color=>$red); $img->polyline(x=>[$x0,$x1,$x2], y=>[$y0,$y1,$y2], aa=>1); -Polyline is used to draw multilple lines between a series of points. -The point set can either be specified as an arrayref to an array of -array references (where each such array represents a point). The -other way is to specify two array references. +XPolyline is used to draw multilple lines between a +series of points. The point set can either be specified as an +arrayref to an array of array references (where each such array +represents a point). The other way is to specify two array +references. The I parameter is still available for backwards compatibility. +=over + +=item * + +points - a reference to an array of references to arrays containing +the co-ordinates of the points in the line, for example: + + my @points = ( [ 0, 0 ], [ 100, 0 ], [ 100, 100 ], [ 0, 100 ] ); + $img->polyline(points => \@points); + +=item * + +x, y - each is an array of x or y ordinates. This is an alternative +to supplying the C parameter. + + # same as the above points example + my @x = ( 0, 100, 100, 0 ); + my @y = ( 0, 0, 100, 100 ); + $img->polyline(x => \@x, y => \@y); + +=item * + +color - the color of the line. See L<"Color Parameters">. Default: +black. + +=item * + +aa - if true the line is drawn anti-aliased. Default: 0. Can also be +supplied as C for backward compatibility. + +=back =item box $blue = Imager::Color->new( 0, 0, 255 ); - $img->box(color => $blue, xmin=>10, ymin=>30, xmax=>200, ymax=>300, filled=>1); + $img->box(color => $blue, xmin=>10, ymin=>30, xmax=>200, ymax=>300, + filled=>1); -If any of the edges of the box are ommited it will snap to the outer -edge of the image in that direction. If C is ommited the box -is drawn as an outline. Instead of a color it is possible to use a C -pattern: +XIf any of the edges of the box are ommited it will snap +to the outer edge of the image in that direction. If C is +ommited the box is drawn as an outline. Instead of a color it is +possible to use a C pattern: $fill = Imager::Fill->new(hatch=>'stipple'); $img->box(fill=>$fill); # fill entire image with a given fill pattern @@ -105,33 +219,149 @@ pattern: fill => { hatch=>'cross2' }); Also if a color is omitted a color with (255,255,255,255) is used -instead. [NOTE: This may change to use C<$img->fgcolor()> in the future]. +instead. [NOTE: This may change to use C<$img-Efgcolor()> in the future]. Box does not support fractional coordinates yet. +Parameters: +=over + +=item * + +xmin - left side of the box. Default: 0 (left edge of the image) + +=item * + +ymin - top side of the box. Default: 0 (top edge of the image) + +=item * + +xmax - right side of the box. Default: $img->getwidth-1. (right edge +of the image) + +=item * + +ymax - bottom side of the box. Default: $img->getheight-1. (bottom +edge of the image) + +Note: xmax and ymax are I - the number of pixels drawn for +a filled box is (xmax-xmin+1) * (ymax-ymin+1). + +=item * + +box - a reference to an array of (left, top, right, bottom) +co-ordinates. This is an alternative to supplying xmin, ymin, xmax, +ymax and overrides their values. + +=item * + +color - the color of the line. See L<"Color Parameters">. Default: +white. This is ignored if the filled parameter + +=item * + +filled - if non-zero the box is filled with I instead of +outlined. Default: an outline is drawn. + +=item * + +fill - the fill for the box. If this is supplied then the box will be +filled. See L<"Fill Parameters">. + +=back =item arc - $img->arc(color=>$red, r=20, x=>200, y=>100, d1=>10, d2=>20 ); + $img->arc(color=>$red, r=>20, x=>200, y=>100, d1=>10, d2=>20 ); This creates a filled red arc with a 'center' at (200, 100) and spans 10 degrees and the slice has a radius of 20. [NOTE: arc has a BUG in it right now for large differences in angles.] It's also possible to supply a C parameter. +Parameters: + +=over + +=item * + +x, y - center of the filled arc. Default: center of the image. + +=item * + +r - radius of the arc. Default: 1/3 of min(image height, image width). + +=item * + +d1 - starting angle of the arc, in degrees. Default: 0 + +=item * + +d2 - ending angle of the arc, in degrees. Default: 361. + +=item * + +color - the color of the filled arc. See L<"Color Parameters">. +Default: white. Overridden by C. + +=item * + +fill - the fill for the filled arc. See L<"Fill Parameters"> + +=item * + +aa - if true the filled arc is drawn anti-aliased. Default: false. + +Anti-aliased arc() is experimental for now, I'm not entirely happy +with the results in some cases. + +=back + + # arc going through angle zero: + $img->arc(d1=>320, d2=>40, x=>100, y=>100, r=>50, color=>'blue'); + + # complex fill arc + $img->arc(d1=>135, d2=>45, x=>100, y=>150, r=>50, + fill=>{ solid=>'red', combine=>'diff' }); =item circle - $img->circle(color=>$green, r=50, x=>200, y=>100, aa=>1); + $img->circle(color=>$green, r=>50, x=>200, y=>100, aa=>1, filled=>1); This creates an antialiased green circle with its center at (200, 100) and has a radius of 50. It's also possible to supply a C parameter instead of a color parameter. + $img->circle(r => 50, x=> 150, y => 150, fill=>{ hatch => 'stipple' }); + The circle is always filled but that might change, so always pass a filled=>1 parameter if you want it to be filled. +=over + +=item * + +x, y - center of the filled circle. Default: center of the image. + +=item * + +r - radius of the circle. Default: 1/3 of min(image height, image width). + +=item * + +color - the color of the filled circle. See L<"Color Parameters">. +Default: white. Overridden by C. + +=item * + +fill - the fill for the filled circle. See L<"Fill Parameters"> + +=item * + +aa - if true the filled circle is drawn anti-aliased. Default: false. + +=back =item polygon @@ -144,19 +374,634 @@ Like other antialiased drawing functions its coordinates can be specified with floating point values. As with other filled shapes it's possible to use a C instead of a color. -=item flood fill +=over + +=item * + +points - a reference to an array of references to arrays containing +the co-ordinates of the points in the line, for example: + + my @points = ( [ 0, 0 ], [ 100, 0 ], [ 100, 100 ], [ 0, 100 ] ); + $img->polygon(points => \@points); + +=item * + +x, y - each is an array of x or y ordinates. This is an alternative +to supplying the C parameter. + + # same as the above points example + my @x = ( 0, 100, 100, 0 ); + my @y = ( 0, 0, 100, 100 ); + $img->polygon(x => \@x, y => \@y); + +=item * -You can fill a region that all has the same color using the -flood_fill() method, for example: +color - the color of the filled polygon. See L<"Color Parameters">. +Default: black. Overridden by C. + +=item * + +fill - the fill for the filled circle. See L<"Fill Parameters"> + +=back + +=item flood_fill + +XYou can fill a region that all has the same color using +the flood_fill() method, for example: $img->flood_fill(x=>50, y=>50, color=>$color); will fill all regions the same color connected to the point (50, 50). +Alternatively you can fill a region limited by a given border color: + + # stop at the red border + $im->flood_fill(x=>50, y=>50, color=>$color, border=>"red"); + +You can also fill with a complex fill: + + $img->flood_fill(x=>50, y=>50, fill=>{ hatch=>'cross1x1' }); + +Parameters: + +=over + +=item * + +x, y - the start point of the fill. + +=item * + +color - the color of the filled area. See L<"Color Parameters">. +Default: white. Overridden by C. + +=item * + +fill - the fill for the filled area. See L<"Fill Parameters"> + +=item * + +border - the border color of the region to be filled. If this +parameter is supplied flood_fill() will stop when it finds this color. +If this is not supplied then a normal fill is done. C can be +supplied as a L<"Color Parameter">. + +=back + +=item setpixel + + $img->setpixel(x=>50, y=>70, color=>$color); + $img->setpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40], color=>$color); + +setpixel() is used to set one or more individual pixels. + +Parameters: + +=over + +=item * + +x, y - either integers giving the co-ordinates of the pixel to set or +array references containing a set of pixels to be set. + +=item * + +color - the color of the pixels drawn. See L<"Color Parameters">. +Default: white. + +=back + +=item getpixel + + my $color = $img->getpixel(x=>50, y=>70); + my @colors = $img->getpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40]); + my $colors_ref = $img->getpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40]); + +getpixel() is used to retrieve one or more individual pixels. + +For either method you can supply a single set of co-ordinates as +scalar x and y parameters, or set each to an arrayref of ordinates. + +When called with arrays, getpixel() will return a list of colors in +list context, and an arrayref in scalar context. + +To receive floating point colors from getpixel, set the C +parameter to 'float'. + +Parameters: + +=over + +=item * + +x, y - either integers giving the co-ordinates of the pixel to set or +array references containing a set of pixels to be set. + +=item * + +type - the type of color object to return, either C<'8bit'> for +Imager::Color objects or C<'float'> for Imager::Color::Float objects. +Default: C<'8bit'>. + +=back + +=item string + + my $font = Imager::Font->new(file=>"foo.ttf"); + $img->string(x => 50, y => 70, + string => "Hello, World!", + font => $font, + size => 30, + aa => 1, + color => 'white'); + +Draws text on the image. + +Parameters: + +=over + +=item * + +x, y - the point to draw the text from. If C is 0 this is the +top left of the string. If C is 1 (the default) then this is +the left of the string on the baseline. Required. + +=item * + +string - the text to draw. Required unless you supply the C +parameter. + +=item * + +font - an L object representing the font to draw the +text with. Required. + +=item * + +aa - if non-zero the output will be anti-aliased. Default: the value +set in Imager::Font->new() or 0 if not set. + +=item * + +align - if non-zero the point supplied in (x,y) will be on the +base-line, if zero then (x,y) will be at the top-left of the string. + +ie. if drawing the string "yA" and align is 0 the point (x,y) will +aligned with the top of the A. If align is 1 (the default) it will be +aligned with the baseline of the font, typically bottom of the A, +depending on the font used. + +Default: the value set in Imager::Font->new, or 1 if not set. + +=item * + +channel - if present, the text will be written to the specified +channel of the image and the color parameter will be ignore. + +=item * + +color - the color to draw the text in. Default: the color supplied to +Imager::Font->new, or red if none. + +=item * + +size - the point size to draw the text at. Default: the size supplied +to Imager::Font->new, or 15. + +=item * + +sizew - the width scaling to draw the text at. Default: the value of +C. + +=item * + +utf8 - for drivers that support it, treat the string as UTF8 encoded. +For versions of perl that support Unicode (5.6 and later), this will +be enabled automatically if the C parameter is already a UTF8 +string. See L for more information. + +=item * + +vlayout - for drivers that support it, draw the text vertically. +Note: I haven't found a font that has the appropriate metrics yet. + +=item * + +text - alias for the C parameter. + +=back + +On error, string() returns false and you can use $img->errstr to get +the reason for the error. + +=item align_string + +Draws text aligned around a point on the image. + + # "Hello" centered at 100, 100 in the image. + my ($left, $top, $right, $bottom) = + $img->align_string(string=>"Hello", + x=>100, y=>100, + halign=>'center', valign=>'center', + font=>$font); + +Parameters: + +=over + +=item * + +x, y - the point to draw the text from. If C is 0 this is the +top left of the string. If C is 1 (the default) then this is +the left of the string on the baseline. Required. + +=item * + +string - the text to draw. Required unless you supply the C parameter. + +=item * + +font - an L object representing the font to draw the +text with. Required. + +=item * + +aa - if non-zero the output will be anti-aliased + +=item * + +valign - vertical alignment of the text against (x,y) + +=over + +=item * + +top - Point is at the top of the text. + +=item * + +bottom - Point is at the bottom of the text. + +=item * + +baseline - Point is on the baseline of the text. This is the default. + +=item * + +center - Point is vertically centered within the text. + +=back + +=item * + +halign - horizontal alignment of the text against (x,y) + +=over + +=item * + +left - The point is at the left of the text. This is the default. + +=item * + +start - The point is at the start point of the text. + +=item * + +center - The point is horizontally centered within the text. + +=item * + +right - The point is at the right end of the text. + +=item * + +end - The point is at the end point of the text. + +=back + +=item * + +channel - if present, the text will be written to the specified +channel of the image and the color parameter will be ignore. + +=item * + +color - the color to draw the text in. Default: the color supplied to +Imager::Font->new, or red if none. + +=item * + +size - the point size to draw the text at. Default: the size supplied +to Imager::Font->new, or 15. + +=item * + +sizew - the width scaling to draw the text at. Default: the value of +C. + +=item * + +utf8 - for drivers that support it, treat the string as UTF8 encoded. +For versions of perl that support Unicode (5.6 and later), this will +be enabled automatically if the C parameter is already a UTF8 +string. See L for more information. + +=item * + +vlayout - for drivers that support it, draw the text vertically. +Note: I haven't found a font that has the appropriate metrics yet. + +=item * + +text - alias for the C parameter. + +=back + +On success returns a list of bounds of the drawn text, in the order +left, top, right, bottom. + +On error, align_string() returns an empty list and you can use +$img->errstr to get the reason for the error. + +=item setscanline + +Set all or part of a horizontal line of pixels to an image. This +method is most useful in conjuction with L. + +The parameters you can pass are: + +=over + +=item * + +y - vertical position of the scanline. This parameter is required. + +=item * + +x - position to start on the scanline. Default: 0 + +=item * + +pixels - either a reference to an array containing Imager::Color +objects, an reference to an array containing Imager::Color::Float +objects or a scalar containing packed color data. + +If C is C then this can either be a reference to an array +of palette color indexes or a scalar containing packed indexes. + +See L for information on the format of packed +color data. + +=item * + +type - the type of pixel data supplied. If you supply an array +reference of object then this is determined automatically. If you +supply packed color data this defaults to '8bit', if your data is +packed floating point color data then set this to 'float'. + +You can use float or 8bit samples with any image. + +If this is 'index' then pixels should be either an array of palette +color indexes or a packed string of color indexes. + +=back + +Returns the number of pixels set. + +Each of the following sets 5 pixels from (5, 10) through (9, 10) to +blue, red, blue, red, blue: + + my $red_color = Imager::Color->new(255, 0, 0); + my $blue_color = Imager::Color->new(0, 0, 255); + + $image->setscanline(y=>10, x=>5, pixels=> + [ ($blue_color, $red_color) x 2, $blue_color ]); + + # use floating point color instead, for 16-bit plus images + my $red_colorf = Imager::Color::Float->new(1.0, 0, 0); + my $blue_colorf = Imager::Color::Float->new(0, 0, 1.0); + + $image->setscanline(y=>10, x=>5, pixels=> + [ ($blue_colorf, $red_colorf) x 2, $blue_colorf ]); + + # packed 8-bit data + $image->setscanline(y=>10, x=>5, pixels=> + pack("C*", ((0, 0, 255, 255), (255, 0, 0, 255)) x 2, + (0, 0, 255, 255))); + + # packed floating point samples + $image->setscanline(y=>10, x=>5, type=>'float', pixels=> + pack("d*", ((0, 0, 1.0, 1.0), (1.0, 0, 0, 1.0)) x 2, + (0, 0, 1.0, 1.0))); + + +Copy even rows from one image to another: + + for (my $y = 0; $y < $im2->getheight; $y+=2) { + $im1->setscanline(y=>$y, + pixels=>scalar($im2->getscanline(y=>$y))); + } + + +Set the blue channel to 0 for all pixels in an image. This could be +done with convert too: + + for my $y (0..$im->getheight-1) { + my $row = $im->getscanline(y=>$y); + $row =~ s/(..).(.)/$1\0$2/gs; + $im->setscanline(y=>$y, pixels=>$row); + } + +=item getscanline + +Read all or part of a horizonatal line of pixels from an image. This +method is most useful in conjunction with L. + +The parameters you can pass are: + +=over + +=item * + +y - vertical position of the scanline. This parameter is required. + +=item * + +x - position to start on the scanline. Default: 0 + +=item * + +width - number of pixels to read. Default: $img->getwidth - x + +=item * + +type - the type of pixel data to return. Default: C<8bit>. + +Permited values are C<8bit> and C and C. + +=back + +In list context this method will return a list of Imager::Color +objects when I is C<8bit>, or a list of Imager::Color::Float +objects when I if C, or a list of integers when I +is C. + +In scalar context this returns a packed 8-bit pixels when I is +C<8bit>, or a list of packed floating point pixels when I is +C, or packed palette color indexes when I is C. + +The values of samples for which the image does not have channels is +undefined. For example, for a single channel image the values of +channels 1 through 3 are undefined. + +Check image for a given color: + + my $found; + YLOOP: for my $y (0..$img->getheight-1) { + my @colors = $img->getscanline(y=>$y); + for my $color (@colors) { + my ($red, $green, $blue, $alpha) = $color->rgba; + if ($red == $test_red && $green == $test_green && $blue == $test_blue + && $alpha == $test_alpha) { + ++$found; + last YLOOP; + } + } + } + +Or do it using packed data: + + my $found; + my $test_packed = pack("CCCC", $test_red, $test_green, $test_blue, + $test_alpha); + YLOOP: for my $y (0..$img->getheight-1) { + my $colors = $img->getscanline(y=>$y); + while (length $colors) { + if (substr($colors, 0, 4, '') eq $test_packed) { + ++$found; + last YLOOP; + } + } + } + +Some of the examples for L for more examples. + +=item getsamples + +Read specified channels from all or part of a horizontal line of +pixels from an image. + +The parameters you can pass are: + +=over + +=item * + +y - vertical position of the scanline. This parameter is required. + +=item * + +x - position to start on the scanline. Default: 0 + +=item * + +width - number of pixels to read. Default: $img->getwidth - x + +=item * + +type - the type of sample data to return. Default: C<8bit>. + +Permited values are C<8bit> and C. + +=item * + +channels - a reference to an array of channels to return, where 0 is +the first channel. Default: C< [ 0 .. $self->getchannels()-1 ] > + +=back + +In list context this will return a list of integers between 0 and 255 +inclusive when I is C<8bit>, or a list of floating point numbers +between 0.0 and 1.0 inclusive when I is C. + +In scalar context this will return a string of packed bytes, as with +C< pack("C*", ...) > when I is C<8bit> or a string of packed +doubles as with C< pack("d*", ...) > when I is C. + +Example: Check if any pixels in an image have a non-zero alpha +channel: + + my $has_coverage; + for my $y (0 .. $img->getheight()-1) { + my $alpha = $img->getsamples(y=>$y, channels=>[0]); + if ($alpha =~ /[^\0]/) { + ++$has_coverage; + last; + } + } + +Example: Convert a 2 channel grey image into a 4 channel RGBA image: + + # this could be done with convert() instead + my $out = Imager->new(xsize => $src->getwidth(), + ysize => $src->getheight(), + channels => 4); + for my $y ( 0 .. $src->getheight()-1 ) { + my $data = $src->getsamples(y=>$y, channels=>[ 0, 0, 0, 1 ]); + $out->setscanline(y=>$y, pixels=>$data); + } + +=back + +=head1 Packed Color Data + +The getscanline() and setscanline() functions can work with pixels +packed into scalars. This is useful to remove the cost of creating +color objects, but should only be used when performance is an issue. + +Packed data can either be 1 byte per sample or 1 double per sample. + +Each pixel returned by getscanline() or supplied to setscanline() +contains 4 samples, even if the image has fewer then 4 channels. The +values of the extra samples as returned by getscanline() is not +specified. The extra samples passed to setscanline() are ignored. + +To produce packed 1 byte/sample pixels, use the pack C template: + + my $packed_8bit_pixel = pack("CCCC", $red, $blue, $green, $alpha); + +To produce packed double/sample pixels, use the pack C template: + + my $packed_float_pixel = pack("dddd", $red, $blue, $green, $alpha); + +If you use a I parameter of C then the values are palette +color indexes, not sample values: + + my $im = Imager->new(xsize => 100, ysize => 100, type => 'paletted'); + my $black_index = $im->addcolors(colors => [ 'black' ]); + my $red_index = $im->addcolors(colors => [ 'red' ]); + # 2 pixels + my $packed_index_data = pack("C*", $black_index, $red_index); + $im->setscanline(y => $y, pixels => $packed_index_data, type => 'index'); =head1 BUGS box, arc, do not support antialiasing yet. Arc, is only filled as of yet. Default color is not unified yet. -=back +=head1 AUTHOR + +Tony Cook , Arnar M. Hrafnkelsson. + +=head1 SEE ALSO + +L(3), L(3) + +=head1 REVISION + +$Revision$ + +=cut