@@ -1,5 +1,24 @@
Imager release history. Older releases can be found in Changes.old
+Imager 0.74 - 7 May 2010
+===========
+
+Bug fixes:
+
+ - read_multi() didn't handle a missing file format library correctly,
+ aborting on failing to call i_readgif_multi_wiol() or
+ i_readtiff_multi_wiol().
+
+ - fix spelling errors patched by Debian
+ http://svn.debian.org/viewsvn/pkg-perl/trunk/libimager-perl/debian/patches/spelling.patch?revision=54839&view=markup
+
+ - add an (unshipped) author test to spellcheck Imager's POD.
+
+ - update the TIFF file format documentation
+ https://rt.cpan.org/Ticket/Display.html?id=56510
+
+ - lib/Imager/IO.pod was written almost 4 years ago but never shipped.
+
Imager 0.73 - 15 Mar 2010
===========
@@ -4,7 +4,7 @@ use Imager;
use vars qw($VERSION @ISA);
BEGIN {
- $VERSION = "0.01";
+ $VERSION = "0.02";
eval {
require XSLoader;
@@ -39,7 +39,7 @@ Imager::Filter::Flines - dim alternate lines to emulate a video display
=head1 DESCRIPTION
-This is an adaption of the flines dynamically loadable filter
+This is an adaption of the C<flines> dynamically loadable filter
provided in dynfilt/ in previous releases of Imager.
This filter has no parameters.
@@ -173,7 +173,7 @@ my %defaults;
BEGIN {
require Exporter;
@ISA = qw(Exporter);
- $VERSION = '0.73';
+ $VERSION = '0.74';
eval {
require XSLoader;
XSLoader::load(Imager => $VERSION);
@@ -1985,6 +1985,12 @@ sub read_multi {
return $readers{$type}{multiple}->($IO, %opts);
}
+ unless ($formats{$type}) {
+ my $read_types = join ', ', sort Imager->read_types();
+ Imager->_set_error("format '$type' not supported - formats $read_types available for reading");
+ return;
+ }
+
if ($type eq 'gif') {
my @imgs;
@imgs = i_readgif_multi_wiol($IO);
@@ -4032,7 +4038,7 @@ C<transform()>, C<transform2()> and C<matrix_transform()>.
=item *
L<Imager::Filters> - Filters, sharpen, blur, noise, convolve etc. and
-filter plugins.
+filter plug-ins.
=item *
@@ -4085,11 +4091,11 @@ This example creates a completely black image of width 400 and height
=head1 ERROR HANDLING
In general a method will return false when it fails, if it does use
-the errstr() method to find out why:
+the C<errstr()> method to find out why:
=over
-=item errstr
+=item C<errstr>
Returns the last error message in that context.
@@ -4152,7 +4158,7 @@ image
crop() - L<Imager::Transformations/crop> - extract part of an image
def_guess_type() - L<Imager::Files/def_guess_type> - default function
-used to guess the output file format based on the output filename
+used to guess the output file format based on the output file name
deltag() - L<Imager::ImageTypes/deltag> - delete image tags
@@ -4197,10 +4203,10 @@ getpixel() - L<Imager::Draw/getpixel> - retrieve one or more pixel
colors
getsamples() - L<Imager::Draw/getsamples> - retrieve samples from a
-row or subrow of pixels.
+row or partial row of pixels.
getscanline() - L<Imager::Draw/getscanline> - retrieve colors for a
-row or subrow of pixels.
+row or partial row of pixels.
getwidth() - L<Imager::ImageTypes/getwidth> - width of the image in
pixels.
@@ -4211,8 +4217,8 @@ for a new image.
init() - L<Imager::ImageTypes/init>
is_bilevel() - L<Imager::ImageTypes/is_bilevel> - returns whether
-image write functions should write the image in their bi-level (blank
-and white, no grey levels) format
+image write functions should write the image in their bilevel (blank
+and white, no gray levels) format
line() - L<Imager::Draw/line> - draw an interval
@@ -4243,6 +4249,8 @@ NF() - L<Imager::Handy/NF>
open() - L<Imager::Files> - an alias for read()
+=for stopwords IPTC
+
parseiptc() - L<Imager::Files/parseiptc> - parse IPTC data from a JPEG
image
@@ -4401,7 +4409,7 @@ gradient fill - L<Imager::Fill/"Fountain fills">,
L<Imager::Filters/fountain>, L<Imager::Fountain>,
L<Imager::Filters/gradgen>
-grayscale, convert image to - L<Imager::Transformations/convert>
+gray scale, convert image to - L<Imager::Transformations/convert>
guassian blur - L<Imager::Filters/guassian>
@@ -4436,11 +4444,13 @@ L<Imager::Transformations/rubthrough>
pseudo-color image - L<Imager::ImageTypes/to_paletted>,
L<Imager::ImageTypes/new>
+=for stopwords posterize
+
posterize - L<Imager::Filters/postlevels>
-png files - L<Imager::Files>, L<Imager::Files/"PNG">
+PNG files - L<Imager::Files>, L<Imager::Files/"PNG">
-pnm - L<Imager::Files/"PNM (Portable aNy Map)">
+PNM - L<Imager::Files/"PNM (Portable aNy Map)">
rectangles, drawing - L<Imager::Draw/box>
@@ -4473,6 +4483,8 @@ text, measuring - L<Imager::Font/bounding_box>, L<Imager::Font::BBox>
tiles, color - L<Imager::Filters/mosaic>
+=for stopwords unsharp
+
unsharp mask - L<Imager::Filters/unsharpmask>
watermark - L<Imager::Filters/watermark>
@@ -4544,11 +4556,14 @@ at CPAN Ratings:
http://cpanratings.perl.org/dist/Imager
-This requires a Bitcard Account (http://www.bitcard.org).
+=for stopwords Bitcard
+
+This requires a Bitcard account (http://www.bitcard.org).
You can also send email to the maintainer below.
-If you send me a bug report via email, it will be copied to RT.
+If you send me a bug report via email, it will be copied to Request
+Tracker.
=head2 Patches
@@ -4565,7 +4580,7 @@ Tony Cook <tony@imager.perl.org> is the current maintainer for Imager.
Arnar M. Hrafnkelsson is the original author of Imager.
-Many others have contributed to Imager, please see the README for a
+Many others have contributed to Imager, please see the C<README> for a
complete list.
=head1 SEE ALSO
@@ -171,6 +171,7 @@ lib/Imager/Fountain.pm
lib/Imager/Handy.pod
lib/Imager/ImageTypes.pod
lib/Imager/Inline.pod Using Imager with Inline::C
+lib/Imager/IO.pod Document Imager::IO objects
lib/Imager/LargeSamples.pod Track large sample support
lib/Imager/Matrix2d.pm
lib/Imager/Preprocess.pm
@@ -4,7 +4,7 @@
# editor trash
~$
-^\#.*\#$
+(^|/)\#.*\#$
# stuff we don't distribute
^TODO$
@@ -14,22 +14,31 @@
^announce/
^bench/
^design/
+^fuzz/
^fileformatdocs/
^extraimages/
^fontfiles/.*\.sfd$
+^t/x.*\.t$
+^imcover.perl$
# might distribute one day
^tools/imager$
+
# trash left by Inline::C
^_Inline/
+# distributions built
+^Imager-\d\.\d\d(_\d\d)?\.tar\.gz$
+
# build trash
Makefile$
Makefile\.old
\bpm_to_blib$
\.o$
-^testout
+^testout/
+^SGI/testout/
+^SGI/SGI.c
^blib/
^Flines/Flines\.c$
^Imager\.c$
@@ -43,9 +52,10 @@ Makefile\.old
^imconfig\.h$
^ICO/ICO\.c$
^ICO/testout
-^rubthru\.c$
+^(rubthru|paste|render|scale|flip|conv|filters|gaussian|compose)\.c$
# trash from profiling
\.gcno$
\.gcda$
\.gcov$
+\bcover_db\b
@@ -1,6 +1,6 @@
--- #YAML:1.0
name: Imager
-version: 0.73
+version: 0.74
abstract: Perl extension for Generating 24 bit Images
author:
- Tony Cook <tony@imager.perl.org>, Arnar M. Hrafnkelsson
@@ -4,7 +4,7 @@ use Imager;
use vars qw($VERSION @ISA);
BEGIN {
- $VERSION = "0.01";
+ $VERSION = "0.02";
eval {
require XSLoader;
@@ -56,8 +56,8 @@ Imager::Filter::Mandelbrot - filter that renders the Mandelbrot set.
=head1 DESCRIPTION
-This is a expansion of the mandelbrot dynamically loadable filter
-provided in dynfilt in previous releases of Imager.
+This is a expansion of the C<mandelbrot> dynamically loadable filter
+provided in C<dynfilt> in previous releases of Imager.
Valid filter parameters are:
@@ -65,16 +65,16 @@ Valid filter parameters are:
=item *
-minx, maxx - the range of x values to render. Defaults: -2.5, 1.5.
+C<minx>, C<maxx> - the range of x values to render. Defaults: -2.5, 1.5.
=item *
-miny, maxy - the range of y values to render. Defaults: -1.5, 1.5
+C<miny>, C<maxy> - the range of y values to render. Defaults: -1.5, 1.5
=item *
-maxiter - the maximum number of iterations to perform when checking if
-the sequence tend towards infinity.
+C<maxiter> - the maximum number of iterations to perform when checking
+if the sequence tend towards infinity.
=back
@@ -346,7 +346,7 @@ arc_poly(int *count, double **xvals, double **yvals,
=category Drawing
=synopsis i_arc_aa(im, 50, 50, 35, 90, 135, &color);
-Antialias fills an arc centered at (x,y) with radius I<rad> covering
+Anti-alias fills an arc centered at (x,y) with radius I<rad> covering
the range of angles in degrees from d1 to d2, with the color.
=cut
@@ -372,7 +372,7 @@ i_arc_aa(i_img *im, double x, double y, double rad, double d1, double d2,
=category Drawing
=synopsis i_arc_aa_cfill(im, 50, 50, 35, 90, 135, fill);
-Antialias fills an arc centered at (x,y) with radius I<rad> covering
+Anti-alias fills an arc centered at (x,y) with radius I<rad> covering
the range of angles in degrees from d1 to d2, with the fill object.
=cut
@@ -478,7 +478,7 @@ i_pixel_coverage(i_mmarray *dot, int x, int y) {
=category Drawing
=synopsis i_circle_aa(im, 50, 50, 45, &color);
-Antialias fills a circle centered at (x,y) for radius I<rad> with
+Anti-alias fills a circle centered at (x,y) for radius I<rad> with
color.
=cut
@@ -1118,19 +1118,21 @@ i_box_cfill(i_img *im,int x1,int y1,int x2,int y2,i_fill_t *fill) {
}
/*
-=item i_line(im, x1, y1, x2, y2, val, endp)
+=item i_line(C<im>, C<x1>, C<y1>, C<x2>, C<y2>, C<color>, C<endp>)
=category Drawing
-Draw a line to image using bresenhams linedrawing algorithm
+=for stopwords Bresenham's
- im - image to draw to
- x1 - starting x coordinate
- y1 - starting x coordinate
- x2 - starting x coordinate
- y2 - starting x coordinate
- val - color to write to image
- endp - endpoint flag (boolean)
+Draw a line to image using Bresenham's line drawing algorithm
+
+ im - image to draw to
+ x1 - starting x coordinate
+ y1 - starting x coordinate
+ x2 - starting x coordinate
+ y2 - starting x coordinate
+ color - color to write to image
+ endp - endpoint flag (boolean)
=cut
*/
@@ -1238,13 +1240,13 @@ i_line_dda(i_img *im, int x1, int y1, int x2, int y2, i_color *val) {
}
/*
-=item i_line_aa(im, x1, x2, y1, y2, color, endp)
+=item i_line_aa(C<im>, C<x1>, C<x2>, C<y1>, C<y2>, C<color>, C<endp>)
=category Drawing
-Antialias draws a line from (x1,y1) to (x2, y2) in color.
+Anti-alias draws a line from (x1,y1) to (x2, y2) in color.
-The point (x2, y2) is drawn only if endp is set.
+The point (x2, y2) is drawn only if C<endp> is set.
=cut
*/
@@ -1687,15 +1689,15 @@ i_flood_fill_low(i_img *im,int seedx,int seedy,
}
/*
-=item i_flood_fill(im, seedx, seedy, color)
+=item i_flood_fill(C<im>, C<seedx>, C<seedy>, C<color>)
=category Drawing
=synopsis i_flood_fill(im, 50, 50, &color);
-Flood fills the 4-connected region starting from the point (seedx,
-seedy) with I<color>.
+Flood fills the 4-connected region starting from the point (C<seedx>,
+C<seedy>) with I<color>.
-Returns false if (seedx, seedy) are outside the image.
+Returns false if (C<seedx>, C<seedy>) are outside the image.
=cut
*/
@@ -1729,15 +1731,15 @@ i_flood_fill(i_img *im, int seedx, int seedy, const i_color *dcol) {
}
/*
-=item i_flood_cfill(im, seedx, seedy, fill)
+=item i_flood_cfill(C<im>, C<seedx>, C<seedy>, C<fill>)
=category Drawing
=synopsis i_flood_cfill(im, 50, 50, fill);
-Flood fills the 4-connected region starting from the point (seedx,
-seedy) with I<fill>.
+Flood fills the 4-connected region starting from the point (C<seedx>,
+C<seedy>) with C<fill>.
-Returns false if (seedx, seedy) are outside the image.
+Returns false if (C<seedx>, C<seedy>) are outside the image.
=cut
*/
@@ -1769,16 +1771,16 @@ i_flood_cfill(i_img *im, int seedx, int seedy, i_fill_t *fill) {
}
/*
-=item i_flood_fill_border(im, seedx, seedy, color, border)
+=item i_flood_fill_border(C<im>, C<seedx>, C<seedy>, C<color>, C<border>)
=category Drawing
=synopsis i_flood_fill_border(im, 50, 50, &color, &border);
-Flood fills the 4-connected region starting from the point (seedx,
-seedy) with I<color>, fill stops when the fill reaches a pixels with
-color I<border>.
+Flood fills the 4-connected region starting from the point (C<seedx>,
+C<seedy>) with C<color>, fill stops when the fill reaches a pixels
+with color C<border>.
-Returns false if (seedx, seedy) are outside the image.
+Returns false if (C<seedx>, C<seedy>) are outside the image.
=cut
*/
@@ -1809,16 +1811,16 @@ i_flood_fill_border(i_img *im, int seedx, int seedy, const i_color *dcol,
}
/*
-=item i_flood_cfill_border(im, seedx, seedy, fill, border)
+=item i_flood_cfill_border(C<im>, C<seedx>, C<seedy>, C<fill>, C<border>)
=category Drawing
=synopsis i_flood_cfill_border(im, 50, 50, fill, border);
-Flood fills the 4-connected region starting from the point (seedx,
-seedy) with I<fill>, the fill stops when it reaches pixels of color
-I<border>.
+Flood fills the 4-connected region starting from the point (C<seedx>,
+C<seedy>) with C<fill>, the fill stops when it reaches pixels of color
+C<border>.
-Returns false if (seedx, seedy) are outside the image.
+Returns false if (C<seedx>, C<seedy>) are outside the image.
=cut
*/
@@ -188,7 +188,7 @@ the mark.
Clears the error stack.
-Called by any imager function before doing any other processing.
+Called by any Imager function before doing any other processing.
=cut
*/
@@ -247,7 +247,7 @@ void i_push_error(int code, char const *msg) {
}
/*
-=item i_push_errorvf(int code, char const *fmt, va_list ap)
+=item i_push_errorvf(int C<code>, char const *C<fmt>, va_list C<ap>)
=category Error handling
@@ -277,7 +277,7 @@ void i_push_errorvf(int code, char const *fmt, va_list ap) {
=synopsis i_push_errorf(errno, "Cannot open file %s: %d", filename, errno);
=category Error handling
-A version of i_push_error() that does printf() like formating.
+A version of i_push_error() that does printf() like formatting.
Does not support perl specific format codes.
@@ -412,21 +412,23 @@ i_new_hatch_low(const i_color *fg, const i_color *bg, const i_fcolor *ffg, const
int dx, int dy);
/*
-=item i_new_fill_hatch(fg, bg, combine, hatch, cust_hatch, dx, dy)
+=item i_new_fill_hatch(C<fg>, C<bg>, C<combine>, C<hatch>, C<cust_hatch>, C<dx>, C<dy>)
=category Fills
=synopsis i_fill_t *fill = i_new_fill_hatch(&fg_color, &bg_color, combine, hatch, custom_hatch, dx, dy);
-Creates a new hatched fill with the fg color used for the 1 bits in
-the hatch and bg for the 0 bits. If combine is non-zero alpha values
-will be combined.
+Creates a new hatched fill with the C<fg> color used for the 1 bits in
+the hatch and C<bg> for the 0 bits. If C<combine> is non-zero alpha
+values will be combined.
-If cust_hatch is non-NULL it should be a pointer to 8 bytes of the
+If C<cust_hatch> is non-NULL it should be a pointer to 8 bytes of the
hash definition, with the high-bits to the left.
-If cust_hatch is NULL then one of the standard hatches is used.
+If C<cust_hatch> is NULL then one of the standard hatches is used.
-(dx, dy) are an offset into the hatch which can be used to unalign adjoining areas, or to align the origin of a hatch with the the side of a filled area.
+(C<dx>, C<dy>) are an offset into the hatch which can be used to hatch
+adjoining areas out of alignment, or to align the origin of a hatch
+with the the side of a filled area.
=cut
*/
@@ -438,21 +440,23 @@ i_new_fill_hatch(const i_color *fg, const i_color *bg, int combine, int hatch,
}
/*
-=item i_new_fill_hatchf(fg, bg, combine, hatch, cust_hatch, dx, dy)
+=item i_new_fill_hatchf(C<fg>, C<bg>, C<combine>, C<hatch>, C<cust_hatch>, C<dx>, C<dy>)
=category Fills
=synopsis i_fill_t *fill = i_new_fill_hatchf(&fg_fcolor, &bg_fcolor, combine, hatch, custom_hatch, dx, dy);
-Creates a new hatched fill with the fg color used for the 1 bits in
-the hatch and bg for the 0 bits. If combine is non-zero alpha values
-will be combined.
+Creates a new hatched fill with the C<fg> color used for the 1 bits in
+the hatch and C<bg> for the 0 bits. If C<combine> is non-zero alpha
+values will be combined.
-If cust_hatch is non-NULL it should be a pointer to 8 bytes of the
+If C<cust_hatch> is non-NULL it should be a pointer to 8 bytes of the
hash definition, with the high-bits to the left.
-If cust_hatch is NULL then one of the standard hatches is used.
+If C<cust_hatch> is NULL then one of the standard hatches is used.
-(dx, dy) are an offset into the hatch which can be used to unalign adjoining areas, or to align the origin of a hatch with the the side of a filled area.
+(C<dx>, C<dy>) are an offset into the hatch which can be used to hatch
+adjoining areas out of alignment, or to align the origin of a hatch
+with the the side of a filled area.
=cut
*/
@@ -486,7 +490,7 @@ image_fill_proto =
};
/*
-=item i_new_fill_image(im, matrix, xoff, yoff, combine)
+=item i_new_fill_image(C<im>, C<matrix>, C<xoff>, C<yoff>, C<combine>)
=category Fills
=synopsis i_fill_t *fill = i_new_fill_image(src_img, matrix, x_offset, y_offset, combine);
@@ -495,7 +499,7 @@ Create an image based fill.
matrix is an array of 9 doubles representing a transformation matrix.
-xoff and yoff are the offset into the image to start filling from.
+C<xoff> and C<yoff> are the offset into the image to start filling from.
=cut
*/
@@ -1725,7 +1725,7 @@ fount_fill_proto =
/*
-=item i_new_fill_fount(xa, ya, xb, yb, type, repeat, combine, super_sample, ssample_param, count, segs)
+=item i_new_fill_fount(C<xa>, C<ya>, C<xb>, C<yb>, C<type>, C<repeat>, C<combine>, C<super_sample>, C<ssample_param>, C<count>, C<segs>)
=category Fills
=synopsis fill = i_new_fill_fount(0, 0, 100, 100, i_ft_linear, i_ft_linear,
@@ -1469,7 +1469,7 @@ static int do_ns_loop(GifFileType *gf, i_img *img)
subblock[2] = loop_count / 256;
if (EGifPutExtensionLast(gf, APPLICATION_EXT_FUNC_CODE, 3, subblock) == GIF_ERROR) {
gif_push_error();
- i_push_error(0, "writing loop extention sub-block");
+ i_push_error(0, "writing loop extension sub-block");
return 0;
}
}
@@ -86,10 +86,10 @@ i_img_alloc(void) {
}
/*
-=item i_img_init(img)
+=item i_img_init(C<img>)
=category Image Implementation
-Imager interal initialization of images.
+Imager internal initialization of images.
Currently this does very little, in the future it may be used to
support threads, or color profiles.
@@ -479,7 +479,7 @@ i_img_exorcise(i_img *im) {
}
/*
-=item i_img_destroy(img)
+=item i_img_destroy(C<img>)
=order 90
=category Image creation/destruction
=synopsis i_img_destroy(img)
@@ -536,12 +536,12 @@ i_img_info(i_img *im,int *info) {
}
/*
-=item i_img_setmask(im, ch_mask)
+=item i_img_setmask(C<im>, C<ch_mask>)
=category Image Information
=synopsis // only channel 0 writeable
=synopsis i_img_setmask(img, 0x01);
-Set the image channel mask for I<im> to I<ch_mask>.
+Set the image channel mask for C<im> to C<ch_mask>.
The image channel mask gives some control over which channels can be
written to in the image.
@@ -553,11 +553,11 @@ i_img_setmask(i_img *im,int ch_mask) { im->ch_mask=ch_mask; }
/*
-=item i_img_getmask(im)
+=item i_img_getmask(C<im>)
=category Image Information
=synopsis int mask = i_img_getmask(img);
-Get the image channel mask for I<im>.
+Get the image channel mask for C<im>.
=cut
*/
@@ -565,11 +565,11 @@ int
i_img_getmask(i_img *im) { return im->ch_mask; }
/*
-=item i_img_getchannels(im)
+=item i_img_getchannels(C<im>)
=category Image Information
=synopsis int channels = i_img_getchannels(img);
-Get the number of channels in I<im>.
+Get the number of channels in C<im>.
=cut
*/
@@ -577,7 +577,7 @@ int
i_img_getchannels(i_img *im) { return im->channels; }
/*
-=item i_img_get_width(im)
+=item i_img_get_width(C<im>)
=category Image Information
=synopsis i_img_dim width = i_img_get_width(im);
@@ -591,7 +591,7 @@ i_img_get_width(i_img *im) {
}
/*
-=item i_img_get_height(im)
+=item i_img_get_height(C<im>)
=category Image Information
=synopsis i_img_dim height = i_img_get_height(im);
@@ -605,13 +605,13 @@ i_img_get_height(i_img *im) {
}
/*
-=item i_copyto_trans(im, src, x1, y1, x2, y2, tx, ty, trans)
+=item i_copyto_trans(C<im>, C<src>, C<x1>, C<y1>, C<x2>, C<y2>, C<tx>, C<ty>, C<trans>)
=category Image
-(x1,y1) (x2,y2) specifies the region to copy (in the source coordinates)
-(tx,ty) specifies the upper left corner for the target image.
-pass NULL in trans for non transparent i_colors.
+(C<x1>,C<y1>) (C<x2>,C<y2>) specifies the region to copy (in the
+source coordinates) (C<tx>,C<ty>) specifies the upper left corner for
+the target image. pass NULL in C<trans> for non transparent i_colors.
=cut
*/
@@ -647,11 +647,11 @@ i_copyto_trans(i_img *im,i_img *src,int x1,int y1,int x2,int y2,int tx,int ty,co
}
/*
-=item i_copy(src)
+=item i_copy(source)
=category Image
-Creates a new image that is a copy of src.
+Creates a new image that is a copy of the image C<source>.
Tags are not copied, only the image data.
@@ -916,7 +916,7 @@ i_scale_nn(i_img *im, float scx, float scy) {
}
/*
-=item i_sametype(i_img *im, int xsize, int ysize)
+=item i_sametype(C<im>, C<xsize>, C<ysize>)
=category Image creation/destruction
=synopsis i_img *img = i_sametype(src, width, height);
@@ -959,7 +959,7 @@ i_img *i_sametype(i_img *src, int xsize, int ysize) {
}
/*
-=item i_sametype_chans(i_img *im, int xsize, int ysize, int channels)
+=item i_sametype_chans(C<im>, C<xsize>, C<ysize>, C<channels>)
=category Image creation/destruction
=synopsis i_img *img = i_sametype_chans(src, width, height, channels);
@@ -40,20 +40,21 @@ i_color is a union of:
=item *
-gray - contains a single element gray_color, eg. c.gray.gray_color
+gray - contains a single element gray_color, eg. C<c.gray.gray_color>
=item *
-rgb - contains three elements r, g, b, eg. c.rgb.r
+C<rgb> - contains three elements C<r>, C<g>, C<b>, eg. C<c.rgb.r>
=item *
-rgba - contains four elements r, g, b, a, eg. c.rgba.a
+C<rgba> - contains four elements C<r>, C<g>, C<b>, C<a>, eg. C<c.rgba.a>
=item *
-cmyk - contains four elements c, m, y, k, eg. C<c.cmyk.y>. Note that
-Imager never uses CMYK colors except when reading/writing files.
+C<cmyk> - contains four elements C<c>, C<m>, C<y>, C<k>,
+eg. C<c.cmyk.y>. Note that Imager never uses CMYK colors except when
+reading/writing files.
=item *
@@ -188,57 +189,57 @@ It contains the following members:
=item *
-channels - the number of channels in the image
+C<channels> - the number of channels in the image
=item *
-xsize, ysize - the width and height of the image in pixels
+C<xsize>, C<ysize> - the width and height of the image in pixels
=item *
-bytes - the number of bytes used to store the image data. Undefined
+C<bytes> - the number of bytes used to store the image data. Undefined
where virtual is non-zero.
=item *
-ch_mask - a mask of writable channels. eg. if this is 6 then only
+C<ch_mask> - a mask of writable channels. eg. if this is 6 then only
channels 1 and 2 are writable. There may be bits set for which there
are no channels in the image.
=item *
-bits - the number of bits stored per sample. Should be one of
+C<bits> - the number of bits stored per sample. Should be one of
i_8_bits, i_16_bits, i_double_bits.
=item *
-type - either i_direct_type for direct color images, or i_palette_type
+C<type> - either i_direct_type for direct color images, or i_palette_type
for paletted images.
=item *
-virtual - if zero then this image is-self contained. If non-zero then
-this image could be an interface to some other implementation.
+C<virtual> - if zero then this image is-self contained. If non-zero
+then this image could be an interface to some other implementation.
=item *
-idata - the image data. This should not be directly accessed. A new
+C<idata> - the image data. This should not be directly accessed. A new
image implementation can use this to store its image data.
i_img_destroy() will myfree() this pointer if it's non-null.
=item *
-tags - a structure storing the image's tags. This should only be
+C<tags> - a structure storing the image's tags. This should only be
accessed via the i_tags_*() functions.
=item *
-ext_data - a pointer for use internal to an image implementation.
+C<ext_data> - a pointer for use internal to an image implementation.
This should be freed by the image's destroy handler.
=item *
-im_data - data internal to Imager. This is initialized by
+C<im_data> - data internal to Imager. This is initialized by
i_img_init().
=item *
@@ -148,11 +148,11 @@ int
}
/*
-=item i_gpix(im, x, y, color)
+=item i_gpix(im, C<x>, C<y>, C<color>)
=category Drawing
-Retrieves the I<color> of the pixel (x,y).
+Retrieves the C<color> of the pixel (x,y).
Returns 0 if the pixel was retrieved, or -1 if not.
@@ -165,11 +165,11 @@ int
}
/*
-=item i_ppixf(im, x, y, fcolor)
+=item i_ppixf(im, C<x>, C<y>, C<fcolor>)
=category Drawing
-Sets the pixel at (x,y) to the floating point color I<fcolor>.
+Sets the pixel at (C<x>,C<y>) to the floating point color C<fcolor>.
Returns 0 if the pixel was drawn, or -1 if not.
@@ -184,12 +184,12 @@ int
}
/*
-=item i_gpixf(im, x, y, fcolor)
+=item i_gpixf(im, C<x>, C<y>, C<fcolor>)
=category Drawing
Retrieves the color of the pixel (x,y) as a floating point color into
-I<fcolor>.
+C<fcolor>.
Returns 0 if the pixel was retrieved, or -1 if not.
@@ -237,12 +237,12 @@ int
}
/*
-=item i_plinf(im, l, r, fcolors)
+=item i_plinf(im, C<left>, C<right>, C<fcolors>)
=category Drawing
-Sets (r-l) pixels starting from (l,y) using (r-l) floating point
-colors from I<colors>.
+Sets (right-left) pixels starting from (left,y) using (right-left)
+floating point colors from C<fcolors>.
Returns the number of pixels set.
@@ -273,19 +273,19 @@ int
}
/*
-=item i_gsamp(im, l, r, y, samp, chans, chan_count)
+=item i_gsamp(im, left, right, y, samples, channels, channel_count)
=category Drawing
-Reads sample values from im for the horizontal line (l, y) to (r-1,y)
-for the channels specified by chans, an array of int with chan_count
-elements.
+Reads sample values from C<im> for the horizontal line (left, y) to
+(right-1,y) for the channels specified by C<channels>, an array of int
+with C<channel_count> elements.
-If chans is NULL then the first chan_count channels are retrieved for
+If channels is NULL then the first channels_count channels are retrieved for
each pixel.
-Returns the number of samples read (which should be (r-l) *
-chan_count)
+Returns the number of samples read (which should be (right-left) *
+channel_count)
=cut
*/
@@ -296,19 +296,19 @@ int
}
/*
-=item i_gsampf(im, l, r, y, samp, chans, chan_count)
+=item i_gsampf(im, left, right, y, samples, channels, channel_count)
=category Drawing
-Reads floating point sample values from im for the horizontal line (l,
-y) to (r-1,y) for the channels specified by chans, an array of int
-with chan_count elements.
+Reads floating point sample values from C<im> for the horizontal line
+(left, y) to (right-1,y) for the channels specified by C<channels>, an
+array of int with channel_count elements.
-If chans is NULL then the first chan_count channels are retrieved for
-each pixel.
+If C<channels> is NULL then the first C<channel_count> channels are
+retrieved for each pixel.
-Returns the number of samples read (which should be (r-l) *
-chan_count)
+Returns the number of samples read (which should be (C<right>-C<left>)
+* C<channel_count>)
=cut
*/
@@ -319,12 +319,12 @@ int
}
/*
-=item i_gpal(im, x, r, y, indexes)
+=item i_gpal(im, left, right, y, indexes)
=category Drawing
-Reads palette indexes for the horizontal line (x, y) to (r-1, y) into
-indexes.
+Reads palette indexes for the horizontal line (left, y) to (right-1,
+y) into C<indexes>.
Returns the number of indexes read.
@@ -338,12 +338,12 @@ int
}
/*
-=item i_ppal(im, x, r, y, indexes)
+=item i_ppal(im, left, right, y, indexes)
=category Drawing
-Writes palette indexes for the horizontal line (x, y) to (r-1, y) from
-indexes.
+Writes palette indexes for the horizontal line (left, y) to (right-1,
+y) from C<indexes>.
Returns the number of indexes written.
@@ -464,7 +464,7 @@ int
Sets I<count> colors starting from I<index> in the image's palette.
-On sucess returns true.
+On success returns true.
On failure returns false.
@@ -7,7 +7,7 @@
#define IMAGER_IMMACROS_H_
/*
-=item i_img_has_alpha(im)
+=item i_img_has_alpha(C<im>)
=category Image Information
@@ -19,7 +19,7 @@ Return true if the image has an alpha channel.
#define i_img_has_alpha(im) ((im)->channels == 2 || (im)->channels == 4)
/*
-=item i_img_color_channels(im)
+=item i_img_color_channels(C<im>)
=category Image Information
@@ -19,6 +19,8 @@ Imager::API - Imager's C API - introduction.
=head1 DESCRIPTION
+=for stopwords XS
+
The API allows you to access Imager functions at the C level from XS
and from Inline::C.
@@ -38,7 +40,7 @@ core Imager object, for example, Imager::SDL.
=item *
-write C code that hooks into Imagers existing methods, such as filter
+write C code that hooks into Imager's existing methods, such as filter
or file format handlers.
=back
@@ -86,15 +88,16 @@ font functions are not visible through Imager's API.
=head2 i_img - images
-This contains the dimensions of the image (xsize, ysize, channels),
-image metadata (ch_mask, bits, type, virtual), potentially image data
-(idata) and the a function table, with pointers to functions to
-perform various low level image operations.
+This contains the dimensions of the image (C<xsize>, C<ysize>,
+C<channels>), image metadata (C<ch_mask>, C<bits>, C<type>,
+C<virtual>), potentially image data (C<idata>) and the a function
+table, with pointers to functions to perform various low level image
+operations.
The only time you should directly write to any value in this type is
if you're implementing your own image type.
-The typemap includes typenames Imager and Imager::ImgRaw as typedefs
+The typemap includes type names Imager and Imager::ImgRaw as typedefs
for C<i_img *>.
For incoming parameters the typemap will accept either Imager or
@@ -104,7 +107,7 @@ For return values the typemap will produce a full Imager object for an
Imager return type and a raw image object for an Imager::ImgRaw return
type.
-=head2 i_color - 8-bit color
+=head2 C<i_color> - 8-bit color
Represents an 8-bit per sample color. This is a union containing
several different structs for access to components of a color:
@@ -113,32 +116,32 @@ several different structs for access to components of a color:
=item *
-gray - single member gray_color.
+C<gray> - single member C<gray_color>.
=item *
-rgb - r, g, b members.
+C<rgb> - C<r>, C<g>, C<b> members.
=item *
-rgba - r, g, b, a members.
+C<rgba> - C<r>, C<g>, C<b>, C<a> members.
=item *
-channels - array of channels.
+C<channels> - array of channels.
=back
Use Imager::Color for parameter and return value types.
-=head2 i_fcolor - floating point color
+=head2 C<i_fcolor> - floating point color
-Similar to i_color except that each component is a double instead of
+Similar to C<i_color> except that each component is a double instead of
an unsigned char.
Use Imager::Color::Float for parameter and return value types.
-=head2 i_fill_t - fill objects
+=head2 C<i_fill_t> - fill objects
Abstract type containing pointers called to perform low level fill
operations.
@@ -160,7 +163,7 @@ Load Imager:
and bootstrap your XS code - see L<XSLoader> or L<DynaLoader>.
-=head2 Foo.xs
+=head2 C<Foo.xs>
You'll need the following in your XS source:
@@ -181,7 +184,7 @@ create the variables used to hold the callback table:
=item *
-initialize the callback table in your BOOT code:
+initialize the callback table in your C<BOOT> code:
BOOT:
PERL_INITIALIZE_IMAGER_CALLBACKS;
@@ -203,10 +206,10 @@ include the Imager external API header:
=back
-=head2 Makefile.PL
+=head2 C<Makefile.PL>
If you're creating an XS module that depends on Imager's API your
-Makefile.PL will need to do the following:
+C<Makefile.PL> will need to do the following:
=over
@@ -237,8 +240,8 @@ include Imager 0.48 as a PREREQ_PM:
=item *
-Since you use Imager::ExtUtils in Makefile.PL (or Build.PL) you should
-include Imager in your configure_requires:
+Since you use Imager::ExtUtils in C<Makefile.PL> (or C<Build.PL>) you
+should include Imager in your configure_requires:
META_MERGE =>
{
@@ -104,57 +104,57 @@ It contains the following members:
=item *
-channels - the number of channels in the image
+C<channels> - the number of channels in the image
=item *
-xsize, ysize - the width and height of the image in pixels
+C<xsize>, C<ysize> - the width and height of the image in pixels
=item *
-bytes - the number of bytes used to store the image data. Undefined
+C<bytes> - the number of bytes used to store the image data. Undefined
where virtual is non-zero.
=item *
-ch_mask - a mask of writable channels. eg. if this is 6 then only
+C<ch_mask> - a mask of writable channels. eg. if this is 6 then only
channels 1 and 2 are writable. There may be bits set for which there
are no channels in the image.
=item *
-bits - the number of bits stored per sample. Should be one of
+C<bits> - the number of bits stored per sample. Should be one of
i_8_bits, i_16_bits, i_double_bits.
=item *
-type - either i_direct_type for direct color images, or i_palette_type
+C<type> - either i_direct_type for direct color images, or i_palette_type
for paletted images.
=item *
-virtual - if zero then this image is-self contained. If non-zero then
-this image could be an interface to some other implementation.
+C<virtual> - if zero then this image is-self contained. If non-zero
+then this image could be an interface to some other implementation.
=item *
-idata - the image data. This should not be directly accessed. A new
+C<idata> - the image data. This should not be directly accessed. A new
image implementation can use this to store its image data.
i_img_destroy() will myfree() this pointer if it's non-null.
=item *
-tags - a structure storing the image's tags. This should only be
+C<tags> - a structure storing the image's tags. This should only be
accessed via the i_tags_*() functions.
=item *
-ext_data - a pointer for use internal to an image implementation.
+C<ext_data> - a pointer for use internal to an image implementation.
This should be freed by the image's destroy handler.
=item *
-im_data - data internal to Imager. This is initialized by
+C<im_data> - data internal to Imager. This is initialized by
i_img_init().
=item *
@@ -203,20 +203,21 @@ i_color is a union of:
=item *
-gray - contains a single element gray_color, eg. c.gray.gray_color
+gray - contains a single element gray_color, eg. C<c.gray.gray_color>
=item *
-rgb - contains three elements r, g, b, eg. c.rgb.r
+C<rgb> - contains three elements C<r>, C<g>, C<b>, eg. C<c.rgb.r>
=item *
-rgba - contains four elements r, g, b, a, eg. c.rgba.a
+C<rgba> - contains four elements C<r>, C<g>, C<b>, C<a>, eg. C<c.rgba.a>
=item *
-cmyk - contains four elements c, m, y, k, eg. C<c.cmyk.y>. Note that
-Imager never uses CMYK colors except when reading/writing files.
+C<cmyk> - contains four elements C<c>, C<m>, C<y>, C<k>,
+eg. C<c.cmyk.y>. Note that Imager never uses CMYK colors except when
+reading/writing files.
=item *
@@ -279,7 +280,7 @@ From: File draw.c
=item i_arc_aa(im, x, y, rad, d1, d2, color)
-Antialias fills an arc centered at (x,y) with radius I<rad> covering
+Anti-alias fills an arc centered at (x,y) with radius I<rad> covering
the range of angles in degrees from d1 to d2, with the color.
@@ -289,7 +290,7 @@ From: File draw.c
=item i_arc_aa_cfill(im, x, y, rad, d1, d2, fill)
-Antialias fills an arc centered at (x,y) with radius I<rad> covering
+Anti-alias fills an arc centered at (x,y) with radius I<rad> covering
the range of angles in degrees from d1 to d2, with the fill object.
@@ -336,58 +337,58 @@ From: File draw.c
=item i_circle_aa(im, x, y, rad, color)
-Antialias fills a circle centered at (x,y) for radius I<rad> with
+Anti-alias fills a circle centered at (x,y) for radius I<rad> with
color.
=for comment
From: File draw.c
-=item i_flood_cfill(im, seedx, seedy, fill)
+=item i_flood_cfill(C<im>, C<seedx>, C<seedy>, C<fill>)
-Flood fills the 4-connected region starting from the point (seedx,
-seedy) with I<fill>.
+Flood fills the 4-connected region starting from the point (C<seedx>,
+C<seedy>) with C<fill>.
-Returns false if (seedx, seedy) are outside the image.
+Returns false if (C<seedx>, C<seedy>) are outside the image.
=for comment
From: File draw.c
-=item i_flood_cfill_border(im, seedx, seedy, fill, border)
+=item i_flood_cfill_border(C<im>, C<seedx>, C<seedy>, C<fill>, C<border>)
-Flood fills the 4-connected region starting from the point (seedx,
-seedy) with I<fill>, the fill stops when it reaches pixels of color
-I<border>.
+Flood fills the 4-connected region starting from the point (C<seedx>,
+C<seedy>) with C<fill>, the fill stops when it reaches pixels of color
+C<border>.
-Returns false if (seedx, seedy) are outside the image.
+Returns false if (C<seedx>, C<seedy>) are outside the image.
=for comment
From: File draw.c
-=item i_flood_fill(im, seedx, seedy, color)
+=item i_flood_fill(C<im>, C<seedx>, C<seedy>, C<color>)
-Flood fills the 4-connected region starting from the point (seedx,
-seedy) with I<color>.
+Flood fills the 4-connected region starting from the point (C<seedx>,
+C<seedy>) with I<color>.
-Returns false if (seedx, seedy) are outside the image.
+Returns false if (C<seedx>, C<seedy>) are outside the image.
=for comment
From: File draw.c
-=item i_flood_fill_border(im, seedx, seedy, color, border)
+=item i_flood_fill_border(C<im>, C<seedx>, C<seedy>, C<color>, C<border>)
-Flood fills the 4-connected region starting from the point (seedx,
-seedy) with I<color>, fill stops when the fill reaches a pixels with
-color I<border>.
+Flood fills the 4-connected region starting from the point (C<seedx>,
+C<seedy>) with C<color>, fill stops when the fill reaches a pixels
+with color C<border>.
-Returns false if (seedx, seedy) are outside the image.
+Returns false if (C<seedx>, C<seedy>) are outside the image.
=for comment
@@ -416,11 +417,11 @@ Returns the number of pixels retrieved.
=for comment
From: File imext.c
-=item i_gpal(im, x, r, y, indexes)
+=item i_gpal(im, left, right, y, indexes)
-Reads palette indexes for the horizontal line (x, y) to (r-1, y) into
-indexes.
+Reads palette indexes for the horizontal line (left, y) to (right-1,
+y) into C<indexes>.
Returns the number of indexes read.
@@ -430,10 +431,10 @@ Always returns 0 for direct color images.
=for comment
From: File imext.c
-=item i_gpix(im, x, y, color)
+=item i_gpix(im, C<x>, C<y>, C<color>)
-Retrieves the I<color> of the pixel (x,y).
+Retrieves the C<color> of the pixel (x,y).
Returns 0 if the pixel was retrieved, or -1 if not.
@@ -441,11 +442,11 @@ Returns 0 if the pixel was retrieved, or -1 if not.
=for comment
From: File imext.c
-=item i_gpixf(im, x, y, fcolor)
+=item i_gpixf(im, C<x>, C<y>, C<fcolor>)
Retrieves the color of the pixel (x,y) as a floating point color into
-I<fcolor>.
+C<fcolor>.
Returns 0 if the pixel was retrieved, or -1 if not.
@@ -453,63 +454,65 @@ Returns 0 if the pixel was retrieved, or -1 if not.
=for comment
From: File imext.c
-=item i_gsamp(im, l, r, y, samp, chans, chan_count)
+=item i_gsamp(im, left, right, y, samples, channels, channel_count)
-Reads sample values from im for the horizontal line (l, y) to (r-1,y)
-for the channels specified by chans, an array of int with chan_count
-elements.
+Reads sample values from C<im> for the horizontal line (left, y) to
+(right-1,y) for the channels specified by C<channels>, an array of int
+with C<channel_count> elements.
-If chans is NULL then the first chan_count channels are retrieved for
+If channels is NULL then the first channels_count channels are retrieved for
each pixel.
-Returns the number of samples read (which should be (r-l) *
-chan_count)
+Returns the number of samples read (which should be (right-left) *
+channel_count)
=for comment
From: File imext.c
-=item i_gsampf(im, l, r, y, samp, chans, chan_count)
+=item i_gsampf(im, left, right, y, samples, channels, channel_count)
-Reads floating point sample values from im for the horizontal line (l,
-y) to (r-1,y) for the channels specified by chans, an array of int
-with chan_count elements.
+Reads floating point sample values from C<im> for the horizontal line
+(left, y) to (right-1,y) for the channels specified by C<channels>, an
+array of int with channel_count elements.
-If chans is NULL then the first chan_count channels are retrieved for
-each pixel.
+If C<channels> is NULL then the first C<channel_count> channels are
+retrieved for each pixel.
-Returns the number of samples read (which should be (r-l) *
-chan_count)
+Returns the number of samples read (which should be (C<right>-C<left>)
+* C<channel_count>)
=for comment
From: File imext.c
-=item i_line(im, x1, y1, x2, y2, val, endp)
+=item i_line(C<im>, C<x1>, C<y1>, C<x2>, C<y2>, C<color>, C<endp>)
+
+=for stopwords Bresenham's
-Draw a line to image using bresenhams linedrawing algorithm
+Draw a line to image using Bresenham's line drawing algorithm
- im - image to draw to
- x1 - starting x coordinate
- y1 - starting x coordinate
- x2 - starting x coordinate
- y2 - starting x coordinate
- val - color to write to image
- endp - endpoint flag (boolean)
+ im - image to draw to
+ x1 - starting x coordinate
+ y1 - starting x coordinate
+ x2 - starting x coordinate
+ y2 - starting x coordinate
+ color - color to write to image
+ endp - endpoint flag (boolean)
=for comment
From: File draw.c
-=item i_line_aa(im, x1, x2, y1, y2, color, endp)
+=item i_line_aa(C<im>, C<x1>, C<x2>, C<y1>, C<y2>, C<color>, C<endp>)
-Antialias draws a line from (x1,y1) to (x2, y2) in color.
+Anti-alias draws a line from (x1,y1) to (x2, y2) in color.
-The point (x2, y2) is drawn only if endp is set.
+The point (x2, y2) is drawn only if C<endp> is set.
=for comment
@@ -527,11 +530,11 @@ Returns the number of pixels set.
=for comment
From: File imext.c
-=item i_plinf(im, l, r, fcolors)
+=item i_plinf(im, C<left>, C<right>, C<fcolors>)
-Sets (r-l) pixels starting from (l,y) using (r-l) floating point
-colors from I<colors>.
+Sets (right-left) pixels starting from (left,y) using (right-left)
+floating point colors from C<fcolors>.
Returns the number of pixels set.
@@ -539,11 +542,11 @@ Returns the number of pixels set.
=for comment
From: File imext.c
-=item i_ppal(im, x, r, y, indexes)
+=item i_ppal(im, left, right, y, indexes)
-Writes palette indexes for the horizontal line (x, y) to (r-1, y) from
-indexes.
+Writes palette indexes for the horizontal line (left, y) to (right-1,
+y) from C<indexes>.
Returns the number of indexes written.
@@ -567,10 +570,10 @@ color to the image.
=for comment
From: File imext.c
-=item i_ppixf(im, x, y, fcolor)
+=item i_ppixf(im, C<x>, C<y>, C<fcolor>)
-Sets the pixel at (x,y) to the floating point color I<fcolor>.
+Sets the pixel at (C<x>,C<y>) to the floating point color C<fcolor>.
Returns 0 if the pixel was drawn, or -1 if not.
@@ -592,7 +595,7 @@ From: File imext.c
Clears the error stack.
-Called by any imager function before doing any other processing.
+Called by any Imager function before doing any other processing.
=for comment
@@ -612,7 +615,7 @@ From: File error.c
=item i_push_errorf(int code, char const *fmt, ...)
-A version of i_push_error() that does printf() like formating.
+A version of i_push_error() that does printf() like formatting.
Does not support perl specific format codes.
@@ -620,7 +623,7 @@ Does not support perl specific format codes.
=for comment
From: File error.c
-=item i_push_errorvf(int code, char const *fmt, va_list ap)
+=item i_push_errorvf(int C<code>, char const *C<fmt>, va_list C<ap>)
Intended for use by higher level functions, takes a varargs pointer
@@ -687,7 +690,7 @@ From: File limits.c
=over
-=item i_new_fill_fount(xa, ya, xb, yb, type, repeat, combine, super_sample, ssample_param, count, segs)
+=item i_new_fill_fount(C<xa>, C<ya>, C<xb>, C<yb>, C<type>, C<repeat>, C<combine>, C<super_sample>, C<ssample_param>, C<count>, C<segs>)
@@ -697,50 +700,54 @@ Creates a new general fill which fills with a fountain fill.
=for comment
From: File filters.im
-=item i_new_fill_hatch(fg, bg, combine, hatch, cust_hatch, dx, dy)
+=item i_new_fill_hatch(C<fg>, C<bg>, C<combine>, C<hatch>, C<cust_hatch>, C<dx>, C<dy>)
-Creates a new hatched fill with the fg color used for the 1 bits in
-the hatch and bg for the 0 bits. If combine is non-zero alpha values
-will be combined.
+Creates a new hatched fill with the C<fg> color used for the 1 bits in
+the hatch and C<bg> for the 0 bits. If C<combine> is non-zero alpha
+values will be combined.
-If cust_hatch is non-NULL it should be a pointer to 8 bytes of the
+If C<cust_hatch> is non-NULL it should be a pointer to 8 bytes of the
hash definition, with the high-bits to the left.
-If cust_hatch is NULL then one of the standard hatches is used.
+If C<cust_hatch> is NULL then one of the standard hatches is used.
-(dx, dy) are an offset into the hatch which can be used to unalign adjoining areas, or to align the origin of a hatch with the the side of a filled area.
+(C<dx>, C<dy>) are an offset into the hatch which can be used to hatch
+adjoining areas out of alignment, or to align the origin of a hatch
+with the the side of a filled area.
=for comment
From: File fills.c
-=item i_new_fill_hatchf(fg, bg, combine, hatch, cust_hatch, dx, dy)
+=item i_new_fill_hatchf(C<fg>, C<bg>, C<combine>, C<hatch>, C<cust_hatch>, C<dx>, C<dy>)
-Creates a new hatched fill with the fg color used for the 1 bits in
-the hatch and bg for the 0 bits. If combine is non-zero alpha values
-will be combined.
+Creates a new hatched fill with the C<fg> color used for the 1 bits in
+the hatch and C<bg> for the 0 bits. If C<combine> is non-zero alpha
+values will be combined.
-If cust_hatch is non-NULL it should be a pointer to 8 bytes of the
+If C<cust_hatch> is non-NULL it should be a pointer to 8 bytes of the
hash definition, with the high-bits to the left.
-If cust_hatch is NULL then one of the standard hatches is used.
+If C<cust_hatch> is NULL then one of the standard hatches is used.
-(dx, dy) are an offset into the hatch which can be used to unalign adjoining areas, or to align the origin of a hatch with the the side of a filled area.
+(C<dx>, C<dy>) are an offset into the hatch which can be used to hatch
+adjoining areas out of alignment, or to align the origin of a hatch
+with the the side of a filled area.
=for comment
From: File fills.c
-=item i_new_fill_image(im, matrix, xoff, yoff, combine)
+=item i_new_fill_image(C<im>, C<matrix>, C<xoff>, C<yoff>, C<combine>)
Create an image based fill.
matrix is an array of 9 doubles representing a transformation matrix.
-xoff and yoff are the offset into the image to start filling from.
+C<xoff> and C<yoff> are the offset into the image to start filling from.
=for comment
@@ -783,10 +790,10 @@ From: File fills.c
=over
-=item i_copy(src)
+=item i_copy(source)
-Creates a new image that is a copy of src.
+Creates a new image that is a copy of the image C<source>.
Tags are not copied, only the image data.
@@ -796,25 +803,26 @@ Returns: i_img *
=for comment
From: File image.c
-=item i_copyto(dest, src, x1, y1, x2, y2, tx, ty)
+=item i_copyto(C<dest>, C<src>, C<x1>, C<y1>, C<x2>, C<y2>, C<tx>, C<ty>)
-Copies image data from the area (x1,y1)-[x2,y2] in the source image to
-a rectangle the same size with it's top-left corner at (tx,ty) in the
-destination image.
+Copies image data from the area (C<x1>,C<y1>)-[C<x2>,C<y2>] in the
+source image to a rectangle the same size with it's top-left corner at
+(C<tx>,C<ty>) in the destination image.
-If x1 > x2 or y1 > y2 then the corresponding co-ordinates are swapped.
+If C<x1> > C<x2> or C<y1> > C<y2> then the corresponding co-ordinates
+are swapped.
=for comment
From: File paste.im
-=item i_copyto_trans(im, src, x1, y1, x2, y2, tx, ty, trans)
+=item i_copyto_trans(C<im>, C<src>, C<x1>, C<y1>, C<x2>, C<y2>, C<tx>, C<ty>, C<trans>)
-(x1,y1) (x2,y2) specifies the region to copy (in the source coordinates)
-(tx,ty) specifies the upper left corner for the target image.
-pass NULL in trans for non transparent i_colors.
+(C<x1>,C<y1>) (C<x2>,C<y2>) specifies the region to copy (in the
+source coordinates) (C<tx>,C<ty>) specifies the upper left corner for
+the target image. pass NULL in C<trans> for non transparent i_colors.
=for comment
@@ -839,15 +847,15 @@ info is an array of 4 integers with the following values:
=for comment
From: File image.c
-=item i_rubthru(im, src, tx, ty, src_minx, src_miny, src_maxx, src_maxy )
+=item i_rubthru(C<im>, C<src>, C<tx>, C<ty>, C<src_minx>, C<src_miny>, C<src_maxx>, C<src_maxy>)
-Takes the sub image I<src[src_minx, src_maxx)[src_miny, src_maxy)> and
-overlays it at (I<tx>,I<ty>) on the image object.
+Takes the sub image C<src>[C<src_minx>, C<src_maxx>)[C<src_miny>, C<src_maxy>)> and
+overlays it at (C<tx>,C<ty>) on the image object.
-The alpha channel of each pixel in I<src> is used to control how much
-the existing colour in I<im> is replaced, if it is 255 then the colour
-is completely replaced, if it is 0 then the original colour is left
+The alpha channel of each pixel in C<src> is used to control how much
+the existing color in C<im> is replaced, if it is 255 then the color
+is completely replaced, if it is 0 then the original color is left
unmodified.
@@ -891,12 +899,12 @@ Creates a new double per sample image.
=for comment
From: File imgdouble.c
-=item i_img_pal_new(x, y, channels, maxpal)
+=item i_img_pal_new(C<x>, C<y>, C<channels>, C<maxpal>)
Creates a new paletted image of the supplied dimensions.
-I<maxpal> is the maximum palette size and should normally be 256.
+C<maxpal> is the maximum palette size and should normally be 256.
Returns a new image or NULL on failure.
@@ -904,7 +912,7 @@ Returns a new image or NULL on failure.
=for comment
From: File palimg.c
-=item i_sametype(i_img *im, int xsize, int ysize)
+=item i_sametype(C<im>, C<xsize>, C<ysize>)
Returns an image of the same type (sample size, channels, paletted/direct).
@@ -915,7 +923,7 @@ For paletted images the palette is copied from the source.
=for comment
From: File image.c
-=item i_sametype_chans(i_img *im, int xsize, int ysize, int channels)
+=item i_sametype_chans(C<im>, C<xsize>, C<ysize>, C<channels>)
Returns an image of the same type (sample size).
@@ -926,7 +934,7 @@ For paletted images the equivalent direct type is returned.
=for comment
From: File image.c
-=item i_img_destroy(img)
+=item i_img_destroy(C<img>)
Destroy an image object
@@ -970,9 +978,9 @@ object.
=for comment
From: File image.c
-=item i_img_init(img)
+=item i_img_init(C<img>)
-Imager interal initialization of images.
+Imager internal initialization of images.
Currently this does very little, in the future it may be used to
support threads, or color profiles.
@@ -988,7 +996,7 @@ From: File image.c
=over
-=item i_img_color_channels(im)
+=item i_img_color_channels(C<im>)
The number of channels holding color information.
@@ -997,7 +1005,7 @@ The number of channels holding color information.
=for comment
From: File immacros.h
-=item i_img_get_height(im)
+=item i_img_get_height(C<im>)
Returns the height in pixels of the image.
@@ -1005,7 +1013,7 @@ Returns the height in pixels of the image.
=for comment
From: File image.c
-=item i_img_get_width(im)
+=item i_img_get_width(C<im>)
Returns the width in pixels of the image.
@@ -1013,23 +1021,23 @@ Returns the width in pixels of the image.
=for comment
From: File image.c
-=item i_img_getchannels(im)
+=item i_img_getchannels(C<im>)
-Get the number of channels in I<im>.
+Get the number of channels in C<im>.
=for comment
From: File image.c
-=item i_img_getmask(im)
+=item i_img_getmask(C<im>)
-Get the image channel mask for I<im>.
+Get the image channel mask for C<im>.
=for comment
From: File image.c
-=item i_img_has_alpha(im)
+=item i_img_has_alpha(C<im>)
Return true if the image has an alpha channel.
@@ -1038,9 +1046,9 @@ Return true if the image has an alpha channel.
=for comment
From: File immacros.h
-=item i_img_setmask(im, ch_mask)
+=item i_img_setmask(C<im>, C<ch_mask>)
-Set the image channel mask for I<im> to I<ch_mask>.
+Set the image channel mask for C<im> to C<ch_mask>.
The image channel mask gives some control over which channels can be
written to in the image.
@@ -1056,24 +1064,24 @@ From: File image.c
=over
-=item i_quant_makemap(quant, imgs, count)
+=item i_quant_makemap(C<quant>, C<imgs>, C<count>)
-Analyzes the I<count> images in I<imgs> according to the rules in
-I<quant> to build a color map (optimal or not depending on
-quant->make_colors).
+Analyzes the C<count> images in C<imgs> according to the rules in
+C<quant> to build a color map (optimal or not depending on
+C<< quant->make_colors >>).
=for comment
From: File quant.c
-=item i_quant_translate(quant, img)
+=item i_quant_translate(C<quant>, C<img>)
-Quantize the image given the palette in quant.
+Quantize the image given the palette in C<quant>.
-On success returns a pointer to a memory block of img->xsize *
-img->ysize i_palidx entries.
+On success returns a pointer to a memory block of C<< img->xsize *
+img->ysize >> C<i_palidx> entries.
On failure returns NULL.
@@ -1086,13 +1094,13 @@ This function will fail if the supplied palette contains no colors.
=for comment
From: File quant.c
-=item i_quant_transparent(quant, data, img, trans_index)
+=item i_quant_transparent(C<quant>, C<data>, C<img>, C<trans_index>)
-Dither the alpha channel on I<img> into the palette indexes in
-I<data>. Pixels to be transparent are replaced with I<trans_pixel>.
+Dither the alpha channel on C<img> into the palette indexes in
+C<data>. Pixels to be transparent are replaced with C<trans_pixel>.
-The method used depends on the tr_* members of quant.
+The method used depends on the tr_* members of C<quant>.
=for comment
@@ -1217,7 +1225,7 @@ From: File imext.c
Sets I<count> colors starting from I<index> in the image's palette.
-On sucess returns true.
+On success returns true.
On failure returns false.
@@ -1282,7 +1290,7 @@ From: File tags.c
=item i_tags_find(tags, name, start, &entry)
-Searchs for a tag of the given I<name> starting from index I<start>.
+Searches for a tag of the given I<name> starting from index I<start>.
On success returns true and sets *I<entry>.
@@ -1295,7 +1303,7 @@ From: File tags.c
=item i_tags_findn(tags, code, start, &entry)
-Searchs for a tag of the given I<code> starting from index I<start>.
+Searches for a tag of the given I<code> starting from index I<start>.
On success returns true and sets *I<entry>.
@@ -1360,7 +1368,7 @@ On failure returns false.
value_size must be at least large enough for a string representation
of an integer.
-The copied value is always NUL terminated.
+The copied value is always C<NUL> terminated.
=for comment
@@ -1425,11 +1433,11 @@ storage at the precision specified by C<places>.
=for comment
From: File tags.c
-=item i_tags_setn(tags, name, idata)
+=item i_tags_setn(C<tags>, C<name>, C<idata>)
-Sets the given tag to the integer I<idata>
+Sets the given tag to the integer C<idata>
-Even on failure, if an existing tag I<name> exists, it will be
+Even on failure, if an existing tag C<name> exists, it will be
removed.
@@ -4,7 +4,7 @@ use Imager;
use strict;
use vars qw($VERSION);
-$VERSION = "1.004";
+$VERSION = "1.005";
# It's just a front end to the XS creation functions.
@@ -44,7 +44,7 @@ __END__
=head1 NAME
-Imager::Color::Float - Rough floating point sample colour handling
+Imager::Color::Float - Rough floating point sample color handling
=head1 SYNOPSIS
@@ -64,9 +64,9 @@ Imager::Color::Float - Rough floating point sample colour handling
=head1 DESCRIPTION
-This module handles creating color objects used by imager. The idea is
-that in the future this module will be able to handle colorspace calculations
-as well.
+This module handles creating color objects used by Imager. The idea
+is that in the future this module will be able to handle color space
+calculations as well.
A floating point Imager color consists of up to four components, each
in the range 0.0 to 1.0. Unfortunately the meaning of the components
@@ -102,20 +102,21 @@ This creates a color object to pass to functions that need a color argument.
This changes an already defined color. Note that this does not affect any places
where the color has been used previously.
-=item rgba
+=item rgba()
-This returns the rgba code of the color the object contains.
+This returns the red, green, blue and alpha channels of the color the
+object contains.
=item info
-Calling info merely dumps the relevant colorcode to the log.
+Calling info merely dumps the relevant color to the log.
=back
=head1 AUTHOR
Arnar M. Hrafnkelsson, addi@umich.edu
-And a great deal of help from others - see the README for a complete
+And a great deal of help from others - see the C<README> for a complete
list.
=head1 SEE ALSO
@@ -2,7 +2,7 @@ package Imager::Color::Table;
use strict;
use vars qw($VERSION);
-$VERSION = "1.002";
+$VERSION = "1.003";
my %colors;
@@ -826,7 +826,7 @@ Imager::Color::Table - built-in Imager color table
This class provides a base color table for use in resolving color names.
-The table contains the standard X11 rgb.txt colors.
+The table contains the standard X11 C<rgb.txt> colors.
This table is not included as part of Imager::Color itself since it's
moderately large.
@@ -4,7 +4,7 @@ use Imager;
use strict;
use vars qw($VERSION);
-$VERSION = "1.010";
+$VERSION = "1.011";
# It's just a front end to the XS creation functions.
@@ -397,9 +397,9 @@ Imager::Color - Color handling for Imager.
=head1 DESCRIPTION
-This module handles creating color objects used by imager. The idea is
-that in the future this module will be able to handle colorspace calculations
-as well.
+This module handles creating color objects used by Imager. The idea
+is that in the future this module will be able to handle color space
+calculations as well.
An Imager color consists of up to four components, each in the range 0
to 255. Unfortunately the meaning of the components can change
@@ -435,13 +435,14 @@ This creates a color object to pass to functions that need a color argument.
This changes an already defined color. Note that this does not affect any places
where the color has been used previously.
-=item rgba
+=item rgba()
-This returns the rgba code of the color the object contains.
+This returns the red, green, blue and alpha channels of the color the
+object contains.
=item info
-Calling info merely dumps the relevant colorcode to the log.
+Calling info merely dumps the relevant color to the log.
=item equals(other=>$other_color)
@@ -466,20 +467,20 @@ simple numeric parameters - if you supply 3 or 4 numeric arguments, you get a co
=item *
-a six hex digit web color, either 'RRGGBB' or '#RRGGBB'
+a six hex digit web color, either C<RRGGBB> or C<#RRGGBB>
=item *
-an eight hex digit web color, either 'RRGGBBAA' or '#RRGGBBAA'.
+an eight hex digit web color, either C<RRGGBBAA> or C<#RRGGBBAA>.
=item *
-a 3 hex digit web color, '#RGB' - a value of F becomes 255.
+a 3 hex digit web color, C<#RGB> - a value of F becomes 255.
=item *
-a color name, from whichever of the gimp Named_Colors file or X
-rgb.txt is found first. The same as using the name keyword.
+a color name, from whichever of the gimp C<Named_Colors> file or X
+C<rgb.txt> is found first. The same as using the C<name> keyword.
=back
@@ -499,8 +500,8 @@ The color components in the range 0 to 255.
=item *
-'hue', 'saturation' and 'value', optionally shortened to 'h', 's' and
-'v', to specify a HSV color. 0 <= hue < 360, 0 <= s <= 1 and 0 <= v
+C<hue>, C<saturation> and C<value>, optionally shortened to C<h>, C<s> and
+C<v>, to specify a HSV color. 0 <= hue < 360, 0 <= s <= 1 and 0 <= v
<= 1.
# the same as RGB(127,255,127)
@@ -509,14 +510,14 @@ The color components in the range 0 to 255.
=item *
-'web', which can specify a 6 or 3 hex digit web color, in any of the
-forms '#RRGGBB', '#RGB', 'RRGGBB' or 'RGB'.
+C<web>, which can specify a 6 or 3 hex digit web color, in any of the
+forms C<#RRGGBB>, C<#RGB>, C<RRGGBB> or C<RGB>.
my $c1 = Imager::Color->new(web=>'#FFC0C0'); # pale red
=item *
-'gray' or 'grey' which specifies a single channel, from 0 to 255.
+C<gray> or C<grey> which specifies a single channel, from 0 to 255.
# exactly the same
my $c1 = Imager::Color->new(gray=>128);
@@ -524,7 +525,7 @@ forms '#RRGGBB', '#RGB', 'RRGGBB' or 'RGB'.
=item *
-'rgb' which takes a 3 member arrayref, containing each of the red,
+C<rgb> which takes a 3 member arrayref, containing each of the red,
green and blue values.
# the same
@@ -533,7 +534,7 @@ green and blue values.
=item *
-'hsv' which takes a 3 member arrayref, containting each of hue,
+C<hsv> which takes a 3 member arrayref, containing each of hue,
saturation and value.
# the same
@@ -542,37 +543,37 @@ saturation and value.
=item *
-'gimp' which specifies a color from a GIMP palette file. You can
-specify the filename of the palette file with the 'palette' parameter,
-or let Imager::Color look in various places, typically
-"$HOME/gimp-1.x/palettes/Named_Colors" with and without the version
-number, and in /usr/share/gimp/palettes/. The palette file must have
-color names.
+C<gimp> which specifies a color from a GIMP palette file. You can
+specify the file name of the palette file with the 'palette'
+parameter, or let Imager::Color look in various places, typically
+C<$HOME/gimp-1.x/palettes/Named_Colors> with and without the version
+number, and in C</usr/share/gimp/palettes/>. The palette file must
+have color names.
my $c1 = Imager::Color->new(gimp=>'snow');
my $c1 = Imager::Color->new(gimp=>'snow', palette=>'testimg/test_gimp_pal);
=item *
-'xname' which specifies a color from an X11 rgb.txt file. You can
-specify the filename of the rgb.txt file with the 'palette' parameter,
-or let Imager::Color look in various places, typically
-'/usr/lib/X11/rgb.txt'.
+C<xname> which specifies a color from an X11 C<rgb.txt> file. You can
+specify the file name of the C<rgb.txt> file with the C<palette>
+parameter, or let Imager::Color look in various places, typically
+C</usr/lib/X11/rgb.txt>.
my $c1 = Imager::Color->new(xname=>'blue') # usually RGB(0, 0, 255)
=item *
-'builtin' which specifies a color from the built-in color table in
+C<builtin> which specifies a color from the built-in color table in
Imager::Color::Table. The colors in this module are the same as the
-default X11 rgb.txt file.
+default X11 C<rgb.txt> file.
my $c1 = Imager::Color->new(builtin=>'black') # always RGB(0, 0, 0)
=item *
-'name' which specifies a name from either a GIMP palette, an X rgb.txt
-file or the built-in color table, whichever is found first.
+C<name> which specifies a name from either a GIMP palette, an X
+C<rgb.txt> file or the built-in color table, whichever is found first.
=item *
@@ -594,7 +595,7 @@ set() method.
=head1 AUTHOR
Arnar M. Hrafnkelsson, addi@umich.edu
-And a great deal of help from others - see the README for a complete
+And a great deal of help from others - see the C<README> for a complete
list.
=head1 SEE ALSO
@@ -22,7 +22,7 @@ See L<Imager::Files>.
$image->write(file=>$filename) or die $image->errstr;
-=head2 Write an animated gif.
+=head2 Write an animated GIF
# build an array of images to use in the gif
my @images;
@@ -63,7 +63,8 @@ file, for single images:
The main issue that can occur with this is if the input file has
transparency and the output file format doesn't support that. This
-can be a problem when converting from GIFs to JPEGs for example.
+can be a problem when converting from GIF files to JPEG files for
+example.
To work around that you can compose the source image onto a background
color:
@@ -80,7 +81,7 @@ color:
# now we can write safely to jpeg or pnm
Some formats support multiple files, so if you want to convert from
-say tiff to jpeg, you'll need multiple output files:
+say TIFF to JPEG, you'll need multiple output files:
my @images = Imager->read_multi(file => 'input.tif')
or die Imager->errstr;
@@ -103,11 +104,11 @@ If you also want an alpha channel:
my $rgb_alpha = Imager->new(xsize=>$width, ysize=>$height, channels=>4);
-To make a grayscale image:
+To make a gray-scale image:
my $gray = Imager->new(xsize=>$width, ysize=>$height, channels=>1);
-and a grayscale image with an alpha channel:
+and a gray-scale image with an alpha channel:
my $gray_alpha = Imager->new(xsize=>$width, ysize=>$height, channels=>2);
@@ -301,7 +302,7 @@ Then paste the source image into the new image:
Whether you draw the border before or after pasting the original image
depends on whether you want the border to overlap the image, for
-example a semi-tranparent border drawn after pasting the source image
+example a semi-transparent border drawn after pasting the source image
could overlap the edge without hiding it.
If you want a solid border you could just fill the image before
@@ -325,8 +326,8 @@ pasting the source for simplicity:
=head2 Shearing (slanting) or Rotating text
-This requires that you have Imager installed with Freetype 2.x support
-installed, and that the font be created using the Freetype 2.x driver,
+This requires that you have Imager installed with FreeType 2.x support
+installed, and that the font be created using the FreeType 2.x driver,
for example:
my $font = Imager::Font->new(file=>$fontfile, type=>'ft2');
@@ -366,9 +367,9 @@ transformed text into.
=head2 Shearing an image
-=head2 Convert to grayscale
+=head2 Convert to gray-scale
-To convert an RGB image to a grayscale image, use the convert method:
+To convert an RGB image to a gray-scale image, use the convert method:
my $grey = $image->convert(preset => 'gray');
@@ -381,8 +382,8 @@ See: L<Imager::Transformations/"Color transformations">
=head2 Image format
When Imager reads a file it does a magic number check to determine the
-file type, so "foo.png" could actually be a GIF image, and Imager will
-read it anyway.
+file type, so C<foo.png> could actually be a GIF image, and Imager
+will read it anyway.
You can check the actual format of the image by looking at the
C<i_format> tag.
@@ -74,14 +74,14 @@ 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 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
+bottom. For non anti-aliasing operation all coordinates are rounded
+towards the nearest integer. For anti-aliased operations floating
point coordinates are used.
Drawing is assumed to take place in a coordinate system of infinite
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.
+it is necessary to check for off-by-one cases. Typically it's useful to
+think of C<(10, 20)> as C<(10.00, 20.00)> and consider the consequences.
=head2 Color Parameters
@@ -122,9 +122,9 @@ L<Imager::Fill> for more information.
y1=>20, y2=>50, aa=>1, endp=>1 );
X<line method>Draws a line from (x1,y1) to (x2,y2). The endpoint
-(x2,y2) is drawn by default. If endp of 0 is specified then the
+(x2,y2) is drawn by default. If C<endp> of 0 is specified then the
endpoint will not be drawn. If C<aa> is set then the line will be
-drawn antialiased. The I<antialias> parameter is still available for
+drawn anti-aliased. The C<antialias> parameter is still available for
backwards compatibility.
Parameters:
@@ -133,41 +133,41 @@ Parameters:
=item *
-x1, y1 - starting point of the line. Required.
+C<x1>, C<y1> - starting point of the line. Required.
=item *
-x2, y2 - end point of the line. Required.
+C<x2>, C<y2> - end point of the line. Required.
=item *
-color - the color of the line. See L<"Color Parameters">. Default:
+C<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
+C<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 drawing a
series of connected lines.
=item *
-aa - if true the line is drawn anti-aliased. Default: 0.
+C<aa> - if true the line is drawn anti-aliased. Default: 0.
=back
-=item polyline
+=item polyline(points => [ [ x, y ], [ x, y ], ... ], color => color)
$img->polyline(points=>[[$x0,$y0],[$x1,$y1],[$x2,$y2]],color=>$red);
$img->polyline(x=>[$x0,$x1,$x2], y=>[$y0,$y1,$y2], aa=>1);
-X<polyline method>Polyline is used to draw multilple lines between a
+X<polyline method>C<polyline> is used to draw multiple 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<antialias> parameter is still available for backwards compatibility.
+The C<antialias> parameter is still available for backwards compatibility.
=over
@@ -191,13 +191,13 @@ to supplying the C<points> parameter.
=item *
-color - the color of the line. See L<"Color Parameters">. Default:
-black.
+C<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<antialias> for backward compatibility.
+C<aa> - if true the line is drawn anti-aliased. Default: 0. Can also
+be supplied as C<antialias> for backward compatibility.
=back
@@ -207,9 +207,9 @@ supplied as C<antialias> for backward compatibility.
$img->box(color => $blue, xmin=>10, ymin=>30, xmax=>200, ymax=>300,
filled=>1);
-X<box method>If any of the edges of the box are ommited it will snap
+X<box method>If any of the edges of the box are omitted it will snap
to the outer edge of the image in that direction. If C<filled> is
-ommited the box is drawn as an outline. Instead of a color it is
+omitted the box is drawn as an outline. Instead of a color it is
possible to use a C<fill> pattern:
$fill = Imager::Fill->new(hatch=>'stipple');
@@ -229,44 +229,44 @@ Parameters:
=item *
-xmin - left side of the box. Default: 0 (left edge of the image)
+C<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)
+C<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)
+C<xmax> - right side of the box. Default: C<< $img->getwidth-1
+>>. (right edge of the image)
=item *
-ymax - bottom side of the box. Default: $img->getheight-1. (bottom
-edge of the image)
+C<ymax> - bottom side of the box. Default: C<< $img->getheight-1
+>>. (bottom edge of the image)
-Note: xmax and ymax are I<inclusive> - the number of pixels drawn for
-a filled box is (xmax-xmin+1) * (ymax-ymin+1).
+Note: C<xmax> and C<ymax> are I<inclusive> - the number of pixels
+drawn for a filled box is C<(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.
+C<box> - a reference to an array of (left, top, right, bottom)
+co-ordinates. This is an alternative to supplying C<xmin>, C<ymin>,
+C<xmax>, C<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
+C<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<color> instead of
+C<filled> - if non-zero the box is filled with I<color> instead of
outlined. Default: an outline is drawn.
=item *
-fill - the fill for the box. If this is supplied then the box will be
+C<fill> - the fill for the box. If this is supplied then the box will be
filled. See L<"Fill Parameters">.
=back
@@ -291,39 +291,39 @@ Parameters:
=item *
-x, y - center of the filled arc. Default: center of the image.
+C<x>, C<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).
+C<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
+C<d1> - starting angle of the arc, in degrees. Default: 0
=item *
-d2 - ending angle of the arc, in degrees. Default: 361.
+C<d2> - ending angle of the arc, in degrees. Default: 361.
=item *
-color - the color of the filled arc. See L<"Color Parameters">.
+C<color> - the color of the filled arc. See L<"Color Parameters">.
Default: white. Overridden by C<fill>.
=item *
-fill - the fill for the filled arc. See L<"Fill Parameters">
+C<fill> - the fill for the filled arc. See L<"Fill Parameters">
=item *
-aa - if true the filled arc is drawn anti-aliased. Default: false.
+C<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.
=item *
-filled - set to 0 to draw only an outline.
+C<filled> - set to 0 to draw only an outline.
=back
@@ -346,7 +346,7 @@ filled - set to 0 to draw only an outline.
$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)
+This creates an anti-aliased green circle with its center at (200, 100)
and has a radius of 50. It's also possible to supply a C<fill> parameter
instead of a color parameter.
@@ -360,39 +360,39 @@ To draw a circular outline, set C<filled> to 0:
=item *
-x, y - center of the filled circle. Default: center of the image.
+C<x>, C<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).
+C<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">.
+C<color> - the color of the filled circle. See L<"Color Parameters">.
Default: white. Overridden by C<fill>.
=item *
-fill - the fill for the filled circle. See L<"Fill Parameters">
+C<fill> - the fill for the filled circle. See L<"Fill Parameters">
=item *
-aa - if true the filled circle is drawn anti-aliased. Default: false.
+C<aa> - if true the filled circle is drawn anti-aliased. Default: false.
=item *
-filled - set to 0 to just draw an outline.
+C<filled> - set to 0 to just draw an outline.
=back
-=item polygon
+=item polygon()
$img->polygon(points=>[[$x0,$y0],[$x1,$y1],[$x2,$y2]],color=>$red);
$img->polygon(x=>[$x0,$x1,$x2], y=>[$y0,$y1,$y2], fill=>$fill);
Polygon is used to draw a filled polygon. Currently the polygon is
-always drawn antialiased, although that will change in the future.
-Like other antialiased drawing functions its coordinates can be
+always drawn anti-aliased, although that will change in the future.
+Like other anti-aliased drawing functions its coordinates can be
specified with floating point values. As with other filled shapes
it's possible to use a C<fill> instead of a color.
@@ -400,7 +400,7 @@ it's possible to use a C<fill> instead of a color.
=item *
-points - a reference to an array of references to arrays containing
+C<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 ] );
@@ -408,7 +408,7 @@ the co-ordinates of the points in the line, for example:
=item *
-x, y - each is an array of x or y ordinates. This is an alternative
+C<x>, C<y> - each is an array of x or y ordinates. This is an alternative
to supplying the C<points> parameter.
# same as the above points example
@@ -418,16 +418,16 @@ to supplying the C<points> parameter.
=item *
-color - the color of the filled polygon. See L<"Color Parameters">.
+C<color> - the color of the filled polygon. See L<"Color Parameters">.
Default: black. Overridden by C<fill>.
=item *
-fill - the fill for the filled circle. See L<"Fill Parameters">
+C<fill> - the fill for the filled circle. See L<"Fill Parameters">
=back
-=item flood_fill
+=item flood_fill()
X<flood_fill>You can fill a region that all has the same color using
the flood_fill() method, for example:
@@ -451,27 +451,27 @@ Parameters:
=item *
-x, y - the start point of the fill.
+C<x>, C<y> - the start point of the fill.
=item *
-color - the color of the filled area. See L<"Color Parameters">.
+C<color> - the color of the filled area. See L<"Color Parameters">.
Default: white. Overridden by C<fill>.
=item *
-fill - the fill for the filled area. See L<"Fill Parameters">
+C<fill> - the fill for the filled area. See L<"Fill Parameters">
=item *
-border - the border color of the region to be filled. If this
+C<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<border> can be
supplied as a L<"Color Parameter">.
=back
-=item setpixel
+=item setpixel()
$img->setpixel(x=>50, y=>70, color=>$color);
$img->setpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40], color=>$color);
@@ -500,7 +500,7 @@ successfully set, or false if none.
When called with scalars for x and y, return $img on success, false on
failure.
-=item getpixel
+=item getpixel()
my $color = $img->getpixel(x=>50, y=>70);
my @colors = $img->getpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40]);
@@ -514,7 +514,7 @@ 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<type>
+To receive floating point colors from getpixel(), set the C<type>
parameter to 'float'.
Parameters:
@@ -552,31 +552,31 @@ Parameters:
=item *
-x, y - the point to draw the text from. If C<align> is 0 this is the
-top left of the string. If C<align> is 1 (the default) then this is
-the left of the string on the baseline. Required.
+C<x>, C<y> - the point to draw the text from. If C<align> is 0 this
+is the top left of the string. If C<align> 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<text>
+C<string> - the text to draw. Required unless you supply the C<text>
parameter.
=item *
-font - an L<Imager::Font> object representing the font to draw the
+C<font> - an L<Imager::Font> object representing the font to draw the
text with. Required.
=item *
-aa - if non-zero the output will be anti-aliased. Default: the value
+C<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
+C<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
+i.e. if drawing the string C<"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.
@@ -585,39 +585,40 @@ 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
+C<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
+C<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.
+C<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<size>.
+C<sizew> - the width scaling to draw the text at. Default: the value
+of C<size>.
=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<string> parameter is already a UTF8
-string. See L<Imager::Font/"UTF8"> for more information.
+C<utf8> - for drivers that support it, treat the string as UTF-8
+encoded. For versions of perl that support Unicode (5.6 and later),
+this will be enabled automatically if the C<string> parameter is
+already a UTF-8 string. See L<Imager::Font/"UTF8"> for more
+information.
=item *
-vlayout - for drivers that support it, draw the text vertically.
+C<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<string> parameter.
+C<text> - alias for the C<string> parameter.
=back
@@ -641,123 +642,125 @@ Parameters:
=item *
-x, y - the point to draw the text from. If C<align> is 0 this is the
-top left of the string. If C<align> is 1 (the default) then this is
-the left of the string on the baseline. Required.
+C<x>, C<y> - the point to draw the text from. If C<align> is 0 this
+is the top left of the string. If C<align> 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<text> parameter.
+C<string> - the text to draw. Required unless you supply the C<text>
+parameter.
=item *
-font - an L<Imager::Font> object representing the font to draw the
+C<font> - an L<Imager::Font> object representing the font to draw the
text with. Required.
=item *
-aa - if non-zero the output will be anti-aliased
+C<aa> - if non-zero the output will be anti-aliased
=item *
-valign - vertical alignment of the text against (x,y)
+C<valign> - vertical alignment of the text against (x,y)
=over
=item *
-top - Point is at the top of the text.
+C<top> - Point is at the top of the text.
=item *
-bottom - Point is at the bottom of the text.
+C<bottom> - Point is at the bottom of the text.
=item *
-baseline - Point is on the baseline of the text. This is the default.
+C<baseline> - Point is on the baseline of the text. This is the default.
=item *
-center - Point is vertically centered within the text.
+C<center> - Point is vertically centered within the text.
=back
=item *
-halign - horizontal alignment of the text against (x,y)
+C<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.
+C<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.
+C<start> - The point is at the start point of the text.
=item *
-center - The point is horizontally centered within the text.
+C<center> - The point is horizontally centered within the text.
=item *
-right - The point is at the right end of the text.
+C<right> - The point is at the right end of the text.
=item *
-end - The point is at the end point of the text.
+C<end> - The point is at the end point of the text.
=back
=item *
-channel - if present, the text will be written to the specified
+C<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
+C<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
+C<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<sizew> - the width scaling to draw the text at. Default: the value of
C<size>.
=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<string> parameter is already a UTF8
-string. See L<Imager::Font/"UTF8"> for more information.
+C<utf8> - for drivers that support it, treat the string as UTF-8
+encoded. For versions of perl that support Unicode (5.6 and later),
+this will be enabled automatically if the C<string> parameter is
+already a UTF-8 string. See L<Imager::Font/"UTF-8"> for more
+information.
=item *
-vlayout - for drivers that support it, draw the text vertically.
+C<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<string> parameter.
+C<text> - alias for the C<string> 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.
+On error, align_string() returns an empty list and you can use
+C<< $img->errstr >> to get the reason for the error.
-=item setscanline
+=item setscanline()
Set all or part of a horizontal line of pixels to an image. This
-method is most useful in conjuction with L</getscanline>.
+method is most useful in conjunction with L</getscanline>.
The parameters you can pass are:
@@ -765,15 +768,15 @@ The parameters you can pass are:
=item *
-y - vertical position of the scanline. This parameter is required.
+C<y> - vertical position of the scan line. This parameter is required.
=item *
-x - position to start on the scanline. Default: 0
+C<x> - position to start on the scan line. Default: 0
=item *
-pixels - either a reference to an array containing Imager::Color
+C<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.
@@ -785,12 +788,12 @@ color data.
=item *
-type - the type of pixel data supplied. If you supply an array
+C<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'.
+supply packed color data this defaults to C<'8bit'>, if your data is
+packed floating point color data then set this to C<'float'>.
-You can use float or 8bit samples with any image.
+You can use C<float> or C<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.
@@ -843,7 +846,7 @@ done with convert too:
$im->setscanline(y=>$y, pixels=>$row);
}
-=item getscanline
+=item getscanline()
Read all or part of a horizontal line of pixels from an image. This
method is most useful in conjunction with L</setscanline>.
@@ -854,21 +857,21 @@ The parameters you can pass are:
=item *
-y - vertical position of the scanline. This parameter is required.
+C<y> - vertical position of the scan line. This parameter is required.
=item *
-x - position to start on the scanline. Default: 0
+C<x> - position to start on the scan line. Default: 0
=item *
-width - number of pixels to read. Default: $img->getwidth - x
+C<width> - number of pixels to read. Default: $img->getwidth - x
=item *
-type - the type of pixel data to return. Default: C<8bit>.
+C<type> - the type of pixel data to return. Default: C<8bit>.
-Permited values are C<8bit> and C<float> and C<index>.
+Permitted values are C<8bit> and C<float> and C<index>.
=back
@@ -917,7 +920,7 @@ Or do it using packed data:
Some of the examples for L</setscanline> for more examples.
-=item getsamples
+=item getsamples()
Read specified channels from all or part of a horizontal line of
pixels from an image.
@@ -928,37 +931,37 @@ The parameters you can pass are:
=item *
-y - vertical position of the scanline. This parameter is required.
+C<y> - vertical position of the scan line. This parameter is required.
=item *
-x - position to start on the scanline. Default: 0
+C<x> - position to start on the scan line. Default: 0
=item *
-width - number of pixels to read. Default: $img->getwidth - x
+C<width> - number of pixels to read. Default: C<< $img->getwidth - x >>
=item *
-type - the type of sample data to return. Default: C<8bit>.
+C<type> - the type of sample data to return. Default: C<8bit>.
-Permited values are C<8bit> and C<float>.
+Permitted values are C<8bit> and C<float>.
As of Imager 0.61 this can be C<16bit> only for 16 bit images.
=item *
-channels - a reference to an array of channels to return, where 0 is
-the first channel. Default: C<< [ 0 .. $self->getchannels()-1 ] >>
+C<channels> - a reference to an array of channels to return, where 0
+is the first channel. Default: C<< [ 0 .. $self->getchannels()-1 ] >>
=item *
-target - if an array reference is supplied in target then the samples
+C<target> - if an array reference is supplied in target then the samples
will be stored here instead of being returned.
=item *
-offset - the offset within the array referenced by I<target>
+C<offset> - the offset within the array referenced by I<target>
=back
@@ -985,7 +988,7 @@ channel:
}
}
-Example: Convert a 2 channel grey image into a 4 channel RGBA image:
+Example: Convert a 2 channel gray image into a 4 channel RGBA image:
# this could be done with convert() instead
my $out = Imager->new(xsize => $src->getwidth(),
@@ -1003,7 +1006,7 @@ Retrieve 16-bit samples:
$img->getsamples(x => 0, y => $y, target => \@samples, type => '16bit');
}
-=item setsamples
+=item setsamples()
This allows writing of samples back to some images. Currently this is
only supported for 16-bit/sample images.
@@ -1014,36 +1017,36 @@ Parameters:
=item *
-y - vertical position of the scanline. This parameter is required.
+C<y> - vertical position of the scan line. This parameter is required.
=item *
-x - position to start on the scanline. Default: 0
+C<x> - position to start on the scan line. Default: 0
=item *
-width - number of pixels to write. Default: $img->getwidth - x. The
-minimum of this and the number of pixels represented by the samples
-provided will be written.
+C<width> - number of pixels to write. Default: C<< $img->getwidth - x >>.
+The minimum of this and the number of pixels represented by the
+samples provided will be written.
=item *
-type - the type of sample data to write. This parameter is required.
+C<type> - the type of sample data to write. This parameter is required.
As of Imager 0.61 this can only be C<16bit> only for 16 bit images.
=item *
-channels - a reference to an array of channels to return, where 0 is
+C<channels> - a reference to an array of channels to return, where 0 is
the first channel. Default: C<< [ 0 .. $self->getchannels()-1 ] >>
=item *
-data - a reference to an array of samples to write. Required.
+C<data> - a reference to an array of samples to write. Required.
=item *
-offset - the starting offset within the array referenced by I<data>
+C<offset> - the starting offset within the array referenced by I<data>
=back
@@ -1089,69 +1092,69 @@ following:
=over
-=item none
+=item C<none>
The fill pixel replaces the target pixel.
-=item normal
+=item C<normal>
The fill pixels alpha value is used to combine it with the target pixel.
-=item multiply
+=item C<multiply>
-=item mult
+=item C<mult>
Each channel of fill and target is multiplied, and the result is
combined using the alpha channel of the fill pixel.
-=item dissolve
+=item C<dissolve>
If the alpha of the fill pixel is greater than a random number, the
fill pixel is alpha combined with the target pixel.
-=item add
+=item C<add>
The channels of the fill and target are added together, clamped to the range of the samples and alpha combined with the target.
-=item subtract
+=item C<subtract>
The channels of the fill are subtracted from the target, clamped to be
>= 0, and alpha combined with the target.
-=item diff
+=item C<diff>
The channels of the fill are subtracted from the target and the
absolute value taken this is alpha combined with the target.
-=item lighten
+=item C<lighten>
The higher value is taken from each channel of the fill and target
pixels, which is then alpha combined with the target.
-=item darken
+=item C<darken>
The higher value is taken from each channel of the fill and target
pixels, which is then alpha combined with the target.
-=item hue
+=item C<hue>
The combination of the saturation and value of the target is combined
with the hue of the fill pixel, and is then alpha combined with the
target.
-=item sat
+=item C<sat>
The combination of the hue and value of the target is combined
with the saturation of the fill pixel, and is then alpha combined with the
target.
-=item value
+=item C<value>
The combination of the hue and value of the target is combined
with the value of the fill pixel, and is then alpha combined with the
target.
-=item color
+=item C<color>
The combination of the value of the target is combined with the hue
and saturation of the fill pixel, and is then alpha combined with the
@@ -1161,7 +1164,7 @@ target.
=over
-=item combines
+=item combines()
Returns a list of possible combine types.
@@ -1169,8 +1172,8 @@ Returns a list of possible combine types.
=head1 BUGS
-box() does not support antialiasing yet. Arc, is only filled as of
-yet. Default color is not unified yet.
+box() does not support anti-aliasing yet. Default color is not
+unified yet.
=head1 AUTHOR
@@ -1182,6 +1185,6 @@ L<Imager>(3), L<Imager::Cookbook>(3)
=head1 REVISION
-$Revision: 1714 $
+$Revision: 1724 $
=cut
@@ -27,7 +27,7 @@ Imager::Engines - Programmable transformation operations
=head1 DESCRIPTION
-=head2 transform
+=head2 transform()
The C<transform()> function can be used to generate spatial warps and
rotations and such effects. It only operates on a single image and
@@ -40,10 +40,10 @@ code. Look in the test case t/t55trans.t for an example.
C<transform()> needs expressions (or opcodes) that determine the
source pixel for each target pixel. Source expressions are infix
expressions using any of the +, -, *, / or ** binary operators, the -
-unary operator, ( and ) for grouping and the sin() and cos()
+unary operator, ( and ) for grouping and the C<sin()> and C<cos()>
functions. The target pixel is input as the variables x and y.
-You specify the x and y expressions as xexpr and yexpr respectively.
+You specify the x and y expressions as C<xexpr> and C<yexpr> respectively.
You can also specify opcodes directly, but that's magic deep enough
that you can look at the source code.
@@ -56,12 +56,12 @@ maintained.
$new_img=$img->transform(xexpr=>'x+0.1*y+5*sin(y/10.0+1.57)',
yexpr=>'y+10*sin((x+y-0.785)/10)')
-=head2 transform2
+=head2 transform2()
Imager also supports a C<transform2()> class method which allows you
perform a more general set of operations, rather than just specifying
a spatial transformation as with the transform() method, you can also
-perform colour transformations, image synthesis and image
+perform color transformations, image synthesis and image
combinations from multiple source images.
C<transform2()> takes an reference to an options hash, and a list of
@@ -101,12 +101,12 @@ supplied a 3 channel image will be created.
=back
-The tranformation function is specified using either the expr or
-rpnexpr member of the options.
+The transformation function is specified using either the C<expr> or
+C<rpnexpr> member of the options.
=head3 Infix expressions
-You can supply infix expressions to transform 2 with the expr keyword.
+You can supply infix expressions to transform 2 with the C<expr> keyword.
$opts{expr} = 'return getp1(w-x, h-y)'
@@ -128,14 +128,14 @@ due to the compilation of the expression grammar.
=head3 Postfix expressions
You can supply postfix or reverse-polish notation expressions to
-transform2() through the rpnexpr keyword.
+transform2() through the C<rpnexpr> keyword.
-The parser for rpnexpr emulates a stack machine, so operators will
+The parser for C<rpnexpr> emulates a stack machine, so operators will
expect to see their parameters on top of the stack. A stack machine
isn't actually used during the image transformation itself.
You can store the value at the top of the stack in a variable called
-foo using !foo and retrieve that value again using @foo. The !foo
+C<foo> using C<!foo> and retrieve that value again using @foo. The !foo
notation will pop the value from the stack.
An example equivalent to the infix expression above:
@@ -149,7 +149,7 @@ on the stack, which is used as the output pixel.
transform2() has a fairly rich range of operators.
-Each entry below includes the usage with rpnexpr, formatted as:
+Each entry below includes the usage with C<rpnexpr>, formatted as:
=over
@@ -166,15 +166,17 @@ begins with "C" it is a color or pixel value.
multiplication, addition, subtraction, division, remainder and
exponentiation. Multiplication, addition and subtraction can be used
-on colour values too - though you need to be careful - adding 2 white
-values together and multiplying by 0.5 will give you grey, not white.
+on color values too - though you need to be careful - adding 2 white
+values together and multiplying by 0.5 will give you gray, not white.
Division by zero (or a small number) just results in a large number.
Modulo zero (or a small number) results in zero. % is implemented
using fmod() so you can use this to take a value mod a floating point
value.
-rpnexpr usage:
+=for stopwords N1 N2 N uminus
+
+C<rpnexpr> usage:
=over
@@ -197,7 +199,9 @@ I<N1> B<uminus> -- I<N>
Some basic trig functions. They work in radians, so you can't just
use the hue values.
-rpnexpr usage:
+=for stopwords Ny Nx atan2
+
+C<rpnexpr> usage:
=over
@@ -214,7 +218,9 @@ I<Ny> I<Nx> B<atan2> -- I<N>
Find the distance between two points. This is handy (along with
atan2()) for producing circular effects.
-rpnexpr usage:
+=for stopwords Nx1 Ny1 Nx2 Ny2
+
+C<rpnexpr> usage:
=over
@@ -227,7 +233,7 @@ I<Nx1> I<Ny1> I<Nx2> I<Ny2> B<distance> -- I<N>
Find the square root. I haven't had much use for this since adding
the distance() function.
-rpnexpr usage:
+C<rpnexpr> usage:
=over
@@ -239,7 +245,7 @@ I<N> B<sqrt> -- I<N>
Find the absolute value.
-rpnexpr usage:
+C<rpnexpr> usage:
=over
@@ -254,7 +260,9 @@ respectively. I may add a getpn() function at some point, but this
prevents static checking of the instructions against the number of
images actually passed in.
-rpnexpr usage:
+=for stopwords getp1 getp2 getp3
+
+C<rpnexpr> usage:
=over
@@ -268,11 +276,13 @@ I<Nx> I<Ny> B<getp3> -- I<C>
=item value(c), hue(c), sat(c), hsv(h,s,v), hsva(h,s,v,alpha)
-Separates a colour value into it's value (brightness), hue (colour)
+Separates a color value into it's value (brightness), hue (color)
and saturation elements. Use hsv() to put them back together (after
-suitable manipulation), or hsva() to include a tranparency value.
+suitable manipulation), or hsva() to include a transparency value.
-rpnexpr usage:
+=for stopwords Nh Ns Nv hsv hsva Nr Ng Nb rgb rgba
+
+C<rpnexpr> usage:
=over
@@ -290,11 +300,11 @@ I<Nh> I<Ns> I<Nv> I<Na> B<hsva> -- I<C>
=item red(c), green(c), blue(c), rgb(r,g,b), rgba(r,g,b,a)
-Separates a colour value into it's red, green and blue colours. Use
+Separates a color value into it's red, green and blue colors. Use
rgb(r,g,b) to put it back together, or rgba() to include a
transparency value.
-rpnexpr usage:
+C<rpnexpr> usage:
=over
@@ -312,9 +322,9 @@ I<Nr> I<Ng> I<Nb> I<Na> B<rgba> -- I<C>
=item alpha(c)
-Retrieve the alpha value from a colour.
+Retrieve the alpha value from a color.
-rpnexpr usage:
+C<rpnexpr> usage:
=over
@@ -327,7 +337,7 @@ I<C> B<alpha> -- I<N>
Convert a value to an integer. Uses a C int cast, so it may break on
large values.
-rpnexpr usage:
+C<rpnexpr> usage:
=over
@@ -339,7 +349,9 @@ I<N> B<int> -- I<N>
A simple (and inefficient) if function.
-rpnexpr usage:
+=for stopwords Ncond ifp
+
+C<rpnexpr> usage:
=over
@@ -377,7 +389,7 @@ I<N1> I<N2> B<< != >> -- I<N>
Basic logical operators.
-rpnexpr usage:
+C<rpnexpr> usage:
=over
@@ -393,7 +405,7 @@ I<N> B<not> -- I<N>
Natural logarithm and exponential.
-rpnexpr usage:
+C<rpnexpr> usage:
=over
@@ -410,7 +422,9 @@ Calculate the determinant of the 2 x 2 matrix;
a b
c d
-rpnexpr usage:
+=for stopwords Na Nv Nc Nd det
+
+C<rpnexpr> usage:
=over
@@ -426,32 +440,32 @@ transform2() defines the following constants:
=over
-=item pi
+=item C<pi>
The classical constant.
-=item w
+=item C<w>
-=item h
+=item C<h>
The width and height of the output image.
-=item cx
+=item C<cx>
-=item cy
+=item C<cy>
The center of the output image.
-=item wI<image number>
+=item C<w>I<image number>
-=item hI<image number>
+=item C<h>I<image number>
The width and height of each of the input images, C<w1> is the width
of the first input image and so on.
-=item cxI<image number>
+=item C<cx>I<image number>
-=item cyI<image number>
+=item C<cy>I<image number>
The center of each of the input images, (C<cx1>, C<cy1>) is the center
of the first input image and so on.
@@ -462,33 +476,33 @@ A few examples:
=over
-=item rpnexpr=>'x 25 % 15 * y 35 % 10 * getp1 !pat x y getp1 !pix @pix sat 0.7 gt @pat @pix ifp'
+ rpnexpr=>'x 25 % 15 * y 35 % 10 * getp1 !pat x y getp1 !pix @pix sat 0.7 gt @pat @pix ifp'
tiles a smaller version of the input image over itself where the
-colour has a saturation over 0.7.
+color has a saturation over 0.7.
-=item rpnexpr=>'x 25 % 15 * y 35 % 10 * getp1 !pat y 360 / !rat x y getp1 1 @rat - pmult @pat @rat pmult padd'
+ rpnexpr=>'x 25 % 15 * y 35 % 10 * getp1 !pat y 360 / !rat x y getp1 1 @rat - pmult @pat @rat pmult padd'
tiles the input image over itself so that at the top of the image the
full-size image is at full strength and at the bottom the tiling is
most visible.
-=item rpnexpr=>'x y getp1 !pix @pix value 0.96 gt @pix sat 0.1 lt and 128 128 255 rgb @pix ifp'
+ rpnexpr=>'x y getp1 !pix @pix value 0.96 gt @pix sat 0.1 lt and 128 128 255 rgb @pix ifp'
replace pixels that are white or almost white with a palish blue
-=item rpnexpr=>'x 35 % 10 * y 45 % 8 * getp1 !pat x y getp1 !pix @pix sat 0.2 lt @pix value 0.9 gt and @pix @pat @pix value 2 / 0.5 + pmult ifp'
+ rpnexpr=>'x 35 % 10 * y 45 % 8 * getp1 !pat x y getp1 !pix @pix sat 0.2 lt @pix value 0.9 gt and @pix @pat @pix value 2 / 0.5 + pmult ifp'
-Tiles the input image overitself where the image isn't white or almost
+Tiles the input image over it self where the image isn't white or almost
white.
-=item rpnexpr=>'x y 160 180 distance !d y 180 - x 160 - atan2 !a @d 10 / @a + 3.1416 2 * % !a2 @a2 180 * 3.1416 / 1 @a2 sin 1 + 2 / hsv'
+ rpnexpr=>'x y 160 180 distance !d y 180 - x 160 - atan2 !a @d 10 / @a + 3.1416 2 * % !a2 @a2 180 * 3.1416 / 1 @a2 sin 1 + 2 / hsv'
Produces a spiral.
-=item rpnexpr=>'x y 160 180 distance !d y 180 - x 160 - atan2 !a @d 10 / @a + 3.1416 2 * % !a2 @a 180 * 3.1416 / 1 @a2 sin 1 + 2 / hsv'
+ rpnexpr=>'x y 160 180 distance !d y 180 - x 160 - atan2 !a @d 10 / @a + 3.1416 2 * % !a2 @a 180 * 3.1416 / 1 @a2 sin 1 + 2 / hsv'
-A spiral built on top of a colour wheel.
+A spiral built on top of a color wheel.
=back
@@ -534,7 +548,8 @@ method:
0, 0, 1 ]);
By default the output image will be the same size as the input image,
-but you can supply the xsize and ysize parameters to change the size.
+but you can supply the C<xsize> and C<ysize> parameters to change the
+size.
Rather than building matrices by hand you can use the Imager::Matrix2d
module to build the matrices. This class has methods to allow you to
@@ -4,7 +4,7 @@ use Imager::Expr;
use Imager::Regops;
use vars qw($VERSION);
-$VERSION = "1.002";
+$VERSION = "1.003";
use vars qw(@ISA);
@ISA = qw(Imager::Expr);
@@ -194,7 +194,7 @@ __END__
This module is a simple Imager::Expr compiler that compiles a
low-level language that has a nearly 1-to-1 relationship to the
-internal representation used for compiled regmach code.
+internal representation used for compiled register machine code.
=head2 Syntax
@@ -214,11 +214,11 @@ C<var> I<name>:I<type>
=back
-defines variable I<name> to have I<type>, which can be any of 'n' or
-'num' for a numeric type or 'pixel', 'p' or 'c' for a pixel or color
-type.
+defines variable I<name> to have I<type>, which can be any of C<n> or
+C<num> for a numeric type or C<pixel>, C<p> or C<c> for a pixel or
+color type.
-Variable names cannot include whitespace.
+Variable names cannot include white-space.
=item operators
@@ -241,8 +241,8 @@ I<operator> I<operand>
=back
-where operator is any valid regmach operator, result is any variable
-defined with C<var>, and operands are variables, constants or
+where operator is any valid register machine operator, result is any
+variable defined with C<var>, and operands are variables, constants or
literals, or for jump operators, labels.
The set operator can be simplified to:
@@ -253,7 +253,7 @@ I<result> = I<operator>
=back
-All operators maybe preceded by a label, which is any non-whitespace
+All operators maybe preceded by a label, which is any non-white-space
text immediately followed by a colon (':').
=back
@@ -263,7 +263,7 @@ text immediately followed by a colon (':').
Note that the current optimizer may produce incorrect optimization for
your code, fortunately the optimizer will disable itself if you
include any jump operator in your code. A single jump to anywhere
-after your final ret operator can be used to disable the optimizer
+after your final C<ret> operator can be used to disable the optimizer
without slowing down your code.
There's currently no high-level code generation that can generate code
@@ -271,7 +271,7 @@ with loops or real conditions.
=head1 SEE ALSO
-Imager(3), transform.perl, regmach.c
+Imager(3), F<transform.perl>, F<regmach.c>
=head1 AUTHOR
@@ -4,7 +4,7 @@ use Imager::Regops;
use strict;
use vars qw($VERSION);
-$VERSION = "1.004";
+$VERSION = "1.005";
my %expr_types;
@@ -447,7 +447,7 @@ sub compile {
# generate the final result
my $result = $self->gencode($optree->[1]);
if ($result !~ /^p\d+$/) {
- $self->error("You must return a colour value");
+ $self->error("You must return a color value");
return;
}
push(@{$self->{genops}}, [ 'ret', $result, (0) x $MaxOperands ])
@@ -570,8 +570,10 @@ numeric registers starting from register zero.
=back
-By default you can define a 'rpnexpr' key (which emulates RPN) or
-'expr' (an infix expression). It's also possible to write other
+=for stopwords RPN
+
+By default you can define a C<rpnexpr> key (which emulates RPN) or
+C<expr> (an infix expression). It's also possible to write other
expression parsers that will use other keys. Only one expression key
should be defined.
@@ -584,6 +586,8 @@ expression object cannot be created.
Imager::Expr provides only a few simple methods meant for external use:
+=for stopwords VM
+
=over
=item Imager::Expr->type_registered($keyword)
@@ -605,7 +609,7 @@ Returns a reference to the array of numeric registers.
=item $expr->cregs()
-Returns a reference to the array of colour registers.
+Returns a reference to the array of color registers.
=item $expr->dumpops()
@@ -613,7 +617,7 @@ Returns a string with the generated VM "machine code".
=item $expr->dumpcode()
-Returns a string with the unassembled VM "machine code".
+Returns a string with the disassembled VM "machine code".
=back
@@ -660,21 +664,21 @@ Set the return value of Imager::Expr::error()
Converts marginally parsed RPN to register code.
-=item assemble
+=item assemble()
Called to convert op codes into byte code.
-=item numre
+=item numre()
Returns a regular expression that matches floating point numbers.
-=item optimize
+=item optimize()
Optimizes the assembly code, including attempting common subexpression
elimination and strength reducing division by a constant into
multiplication by a constant.
-=item register_type
+=item register_type()
Called by a new expression parser implementation to register itself,
call as:
@@ -83,7 +83,7 @@ method to read an image:
or die "Cannot read $filename: ", $img->errstr;
In most cases Imager can auto-detect the file type, so you can just
-supply the filename:
+supply the file name:
$img->read(file => $filename)
or die "Cannot read $filename: ", $img->errstr;
@@ -156,8 +156,8 @@ write types.
=back
-When writing, if the I<filename> includes an extension that Imager
-recognizes, then you don't need the I<type>, but you may want to
+When writing, if the C<filename> includes an extension that Imager
+recognizes, then you don't need the C<type>, but you may want to
provide one anyway. See L</Guessing types> for information on
controlling this recognition.
@@ -189,7 +189,7 @@ targets:
=item *
-file - The C<file> parameter is the name of the image file to be
+C<file> - The C<file> parameter is the name of the image file to be
written to or read from. If Imager recognizes the extension of the
file you do not need to supply a C<type>.
@@ -206,7 +206,7 @@ file you do not need to supply a C<type>.
=item *
-fh - C<fh> is a file handle, typically either returned from
+C<fh> - C<fh> is a file handle, typically either returned from
C<<IO::File->new()>>, or a glob from an C<open> call. You should call
C<binmode> on the handle before passing it to Imager.
@@ -223,7 +223,7 @@ fileno()) rather than writing at the perl level.
=item *
-fd - C<fd> is a file descriptor. You can get this by calling the
+C<fd> - C<fd> is a file descriptor. You can get this by calling the
C<fileno()> function on a file handle, or by using one of the standard
file descriptor numbers.
@@ -236,10 +236,10 @@ the image.
=item *
-data - When reading data, C<data> is a scalar containing the image
+C<data> - When reading data, C<data> is a scalar containing the image
file data, when writing, C<data> is a reference to the scalar to save
-the image file data too. For GIF images you will need giflib 4 or
-higher, and you may need to patch giflib to use this option for
+the image file data too. For GIF images you will need C<giflib> 4 or
+higher, and you may need to patch C<giflib> to use this option for
writing.
my $data;
@@ -252,7 +252,7 @@ writing.
=item *
-callback - Imager will make calls back to your supplied coderefs to
+C<callback> - Imager will make calls back to your supplied coderefs to
read, write and seek from/to/through the image file.
When reading from a file you can use either C<callback> or C<readcb>
@@ -298,7 +298,7 @@ C<seekcb>.
=head2 Guessing types
When writing to a file, if you don't supply a C<type> parameter Imager
-will attempt to guess it from the filename. This is done by calling
+will attempt to guess it from the file name. This is done by calling
the code reference stored in C<$Imager::FORMATGUESS>. This is only
done when write() or write_multi() is called with a C<file> parameter.
@@ -312,7 +312,7 @@ C<\&Imager::def_guess_type>.
This is the default function Imager uses to derive a file type from a
file name. This is a function, not a method.
-Accepts a single parameter, the filename and returns the type or
+Accepts a single parameter, the file name and returns the type or
undef.
=back
@@ -328,10 +328,12 @@ When reading a file Imager examines beginning of the file for
identifying information. The current implementation attempts to
detect the following image types beyond those supported by Imager:
+=for stopwords Photoshop
+
=over
-xpm, mng, jng, SGI RGB, ilbm, pcx, fits, psd (Photoshop), eps, Utah
-RLE
+C<xpm>, C<mng>, C<jng>, C<ilbm>, C<pcx>, C<fits>, C<psd> (Photoshop), C<eps>, Utah
+C<RLE>.
=back
@@ -422,17 +424,20 @@ the C<warn_obsolete> option set to false:
At some point in the future these obsolete options will no longer be
supported.
+=for stopwords aNy PixMaps BitMap
+
=head2 PNM (Portable aNy Map)
-Imager can write PGM (Portable Gray Map) and PPM (Portable PixMaps)
-files, depending on the number of channels in the image. Currently
-the images are written in binary formats. Only 1 and 3 channel images
-can be written, including 1 and 3 channel paletted images.
+Imager can write C<PGM> (Portable Gray Map) and C<PPM> (Portable
+PixMaps) files, depending on the number of channels in the image.
+Currently the images are written in binary formats. Only 1 and 3
+channel images can be written, including 1 and 3 channel paletted
+images.
$img->write(file=>'foo.ppm') or die $img->errstr;
-Imager can read both the ASCII and binary versions of each of the PBM
-(Portable BitMap), PGM and PPM formats.
+Imager can read both the ASCII and binary versions of each of the
+C<PBM> (Portable BitMap), C<PGM> and C<PPM> formats.
$img->read(file=>'foo.ppm') or die $img->errstr;
@@ -444,14 +449,14 @@ The following tags are set when reading a PNM file:
=item *
-X<pnm_maxval>pnm_maxval - the maxvals number from the PGM/PPM header.
-Always set to 2 for a PBM file.
+X<pnm_maxval>C<pnm_maxval> - the C<maxvals> number from the PGM/PPM header.
+Always set to 2 for a C<PBM> file.
=item *
-X<pnm_type>pnm_type - the type number from the PNM header, 1 for ASCII
-PBM files, 2 for ASCII PGM files, 3 for ASCII PPM files, 4 for binary
-PBM files, 5 for binary PGM files, 6 for binary PPM files.
+X<pnm_type>C<pnm_type> - the type number from the C<PNM> header, 1 for ASCII
+C<PBM> files, 2 for ASCII C<PGM> files, 3 for ASCII c<PPM> files, 4 for binary
+C<PBM> files, 5 for binary C<PGM> files, 6 for binary C<PPM> files.
=back
@@ -463,7 +468,7 @@ The following tag is checked when writing an image with more than
=item *
X<pnm_write_wide_data>pnm_write_wide_data - if this is non-zero then
-write() can write PGM/PPM files with 16-bits/sample. Some
+write() can write C<PGM>/C<PPM> files with 16-bits/sample. Some
applications, for example GIMP 2.2, and tools can only read
8-bit/sample binary PNM files, so Imager will only write a 16-bit
image when this tag is non-zero.
@@ -472,14 +477,16 @@ image when this tag is non-zero.
=head2 JPEG
+=for stopwords composited
+
You can supply a C<jpegquality> parameter (0-100) when writing a JPEG
file, which defaults to 75%. If you write an image with an alpha
-channel to a jpeg file then it will be composited against the
+channel to a JPEG file then it will be composited against the
background set by the C<i_background> parameter (or tag).
$img->write(file=>'foo.jpg', jpegquality=>90) or die $img->errstr;
-Imager will read a grayscale JPEG as a 1 channel image and a color
+Imager will read a gray scale JPEG as a 1 channel image and a color
JPEG as a 3 channel image.
$img->read(file=>'foo.jpg') or die $img->errstr;
@@ -489,24 +496,24 @@ to control output:
=over
-=item jpeg_density_unit
+=item C<jpeg_density_unit>
-The value of the density unit field in the JFIF header. This is
+The value of the density unit field in the C<JFIF> header. This is
ignored on writing if the C<i_aspect_only> tag is non-zero.
The C<i_xres> and C<i_yres> tags are expressed in pixels per inch no
matter the value of this tag, they will be converted to/from the value
stored in the JPEG file.
-=item jpeg_density_unit_name
+=item C<jpeg_density_unit_name>
This is set when reading a JPEG file to the name of the unit given by
C<jpeg_density_unit>. Possible results include C<inch>,
C<centimeter>, C<none> (the C<i_aspect_only> tag is also set reading
-these files). If the value of jpeg_density_unit is unknown then this
-tag isn't set.
+these files). If the value of C<jpeg_density_unit> is unknown then
+this tag isn't set.
-=item jpeg_comment
+=item C<jpeg_comment>
Text comment.
@@ -515,7 +522,9 @@ Text comment.
JPEG supports the spatial resolution tags C<i_xres>, C<i_yres> and
C<i_aspect_only>.
-If an APP1 block containing EXIF information is found, then any of the
+=for stopwords EXIF
+
+If an C<APP1> block containing EXIF information is found, then any of the
following tags can be set:
=over
@@ -576,9 +585,11 @@ eg.
0
Auto exposure
+=for stopwords IPTC
+
=over
-=item parseiptc
+=item parseiptc()
Historically, Imager saves IPTC data when reading a JPEG image, the
parseiptc() method returns a list of key/value pairs resulting from a
@@ -643,15 +654,15 @@ other images in the file.
=item *
-gif_background - The index in the global colormap of the logical
+gif_background - The index in the global color map of the logical
screen's background color. This is only set if the current image uses
-the global colormap. You can set this on write too, but for it to
+the global color map. You can set this on write too, but for it to
choose the color you want, you will need to supply only paletted
images and set the C<gif_eliminate_unused> tag to 0.
=item *
-gif_trans_index - The index of the color in the colormap used for
+gif_trans_index - The index of the color in the color map used for
transparency. If the image has a transparency then it is returned as
a 4 channel image with the alpha set to zero in this palette entry.
This value is not used when writing. ("Transparent Color Index")
@@ -659,8 +670,8 @@ This value is not used when writing. ("Transparent Color Index")
=item *
gif_trans_color - A reference to an Imager::Color object, which is the
-colour to use for the palette entry used to represent transparency in
-the palette. You need to set the transp option (see L<Quantization
+color to use for the palette entry used to represent transparency in
+the palette. You need to set the C<transp> option (see L<Quantization
options>) for this value to be used.
=item *
@@ -684,7 +695,7 @@ may be zero to loop forever.
=item *
-gif_comment - the first block of the first gif comment before each
+gif_comment - the first block of the first GIF comment before each
image.
=item *
@@ -701,10 +712,10 @@ range color indexes.
=back
-Where applicable, the ("name") is the name of that field from the GIF89
+Where applicable, the ("name") is the name of that field from the C<GIF89>
standard.
-The following gif writing options are obsolete, you should set the
+The following GIF writing options are obsolete, you should set the
corresponding tag in the image, either by using the tags functions, or
by supplying the tag and value as options.
@@ -712,9 +723,9 @@ by supplying the tag and value as options.
=item *
-gif_each_palette - Each image in the gif file has it's own palette if
-this is non-zero. All but the first image has a local colour table
-(the first uses the global colour table.
+gif_each_palette - Each image in the GIF file has it's own palette if
+this is non-zero. All but the first image has a local color table
+(the first uses the global color table.
Use C<gif_local_map> in new code.
@@ -743,7 +754,7 @@ New code should use the C<gif_left> and C<gif_top> tags.
gif_loop_count - If this is non-zero the Netscape loop extension block
is generated, which makes the animation of the images repeat.
-This is currently unimplemented due to some limitations in giflib.
+This is currently unimplemented due to some limitations in C<giflib>.
=back
@@ -754,14 +765,14 @@ some page other than the first. The page is 0 based:
$image->read(file=>"example.gif", page=>1)
or die "Cannot read second page: ",$image->errstr,"\n";
-Before release 0.46, Imager would read multi-image GIF image files
+Before release 0.46, Imager would read multiple image GIF image files
into a single image, overlaying each of the images onto the virtual
GIF screen.
As of 0.46 the default is to read the first image from the file, as if
called with C<< page => 0 >>.
-You can return to the previous behaviour by calling read with the
+You can return to the previous behavior by calling read with the
C<gif_consolidate> parameter set to a true value:
$img->read(file=>$some_gif_file, gif_consolidate=>1);
@@ -773,16 +784,47 @@ objects of the color table generated for the image file.
=head2 TIFF (Tagged Image File Format)
Imager can write images to either paletted or RGB TIFF images,
-depending on the type of the source image. Currently if you write a
-16-bit/sample or double/sample image it will be written as an
-8-bit/sample image. Only 1 or 3 channel images can be written.
+depending on the type of the source image.
+
+When writing direct color images to TIFF the sample size of the
+output file depends on the input:
+
+=over
+
+=item *
+
+double/sample - written as 32-bit/sample TIFF
+
+=item *
+
+16-bit/sample - written as 16-bit/sample TIFF
+
+=item *
+
+8-bit/sample - written as 8-bit/sample TIFF
+
+=back
+
+For paletted images:
+
+=over
+
+=item *
+
+C<< $img->is_bilevel >> is true - the image is written as bi-level
+
+=item *
+
+otherwise - image is written as paletted.
+
+=back
If you are creating images for faxing you can set the I<class>
parameter set to C<fax>. By default the image is written in fine
mode, but this can be overridden by setting the I<fax_fine> parameter
to zero. Since a fax image is bi-level, Imager uses a threshold to
decide if a given pixel is black or white, based on a single channel.
-For greyscale images channel 0 is used, for color images channel 1
+For gray scale images channel 0 is used, for color images channel 1
(green) is used. If you want more control over the conversion you can
use $img->to_paletted() to product a bi-level image. This way you can
use dithering:
@@ -793,22 +835,23 @@ use dithering:
=over
-=item class
+=item *
-If set to 'fax' the image will be written as a bi-level fax image.
+C<class> - If set to 'fax' the image will be written as a bi-level fax
+image.
-=item fax_fine
+=item *
-By default when I<class> is set to 'fax' the image is written in fine
-mode, you can select normal mode by setting I<fax_fine> to 0.
+C<fax_fine> - By default when C<class> is set to 'fax' the image is
+written in fine mode, you can select normal mode by setting
+C<fax_fine> to 0.
=back
Imager should be able to read any TIFF image you supply. Paletted
TIFF images are read as paletted Imager images, since paletted TIFF
images have 16-bits/sample (48-bits/color) this means the bottom
-8-bits are lost, but this shouldn't be a big deal. Currently all
-direct color images are read at 8-bits/sample.
+8-bits are lost, but this shouldn't be a big deal.
TIFF supports the spatial resolution tags. See the
C<tiff_resolutionunit> tag for some extra options.
@@ -819,12 +862,17 @@ As of Imager 0.62 Imager reads:
=item *
-16-bit grey, RGB, or CMYK image, including a possible alpha channel as
+8-bit/sample gray, RGB or CMYK images, including a possible alpha
+channel as an 8-bit/sample image.
+
+=item *
+
+16-bit gray, RGB, or CMYK image, including a possible alpha channel as
a 16-bit/sample image.
=item *
-32-bit grey, RGB image, including a possible alpha channel as a
+32-bit gray, RGB image, including a possible alpha channel as a
double/sample image.
=item *
@@ -836,6 +884,11 @@ which other formats will also write as bi-level.
tiled paletted images are now handled correctly
+=item *
+
+other images are read using C<tifflib>'s RGBA interface as
+8-bit/sample images.
+
=back
The following tags are set in a TIFF image when read, and can be set
@@ -843,10 +896,10 @@ to control output:
=over
-=item tiff_compression
+=item *
-When reading an image this is set to the numeric value of the TIFF
-compression tag.
+C<tiff_compression> - When reading an image this is set to the numeric
+value of the TIFF compression tag.
On writing you can set this to either a numeric compression tag value,
or one of the following values:
@@ -870,69 +923,62 @@ In general a compression setting will be ignored where it doesn't make
sense, eg. C<jpeg> will be ignored for compression if the image is
being written as bilevel.
-Imager attempts to check that your build of libtiff supports the given
-compression, and will fallback to C<packbits> if it isn't enabled.
-eg. older distributions didn't include LZW compression, and JPEG
-compression is only available if libtiff is configured with libjpeg's
-location.
+=for stopwords LZW
+
+Imager attempts to check that your build of C<libtiff> supports the
+given compression, and will fallback to C<packbits> if it isn't
+enabled. eg. older distributions didn't include LZW compression, and
+JPEG compression is only available if C<libtiff> is configured with
+C<libjpeg>'s location.
$im->write(file => 'foo.tif', tiff_compression => 'lzw')
or die $im->errstr;
-=item tiff_jpegquality
+=item *
-If I<tiff_compression> if C<jpeg> then this can be a number from 1 to
-100 giving the JPEG compression quality. High values are better
-quality and larger files.
+C<tags, tiff_jpegquality>C<tiff_jpegquality> - If C<tiff_compression>
+is C<jpeg> then this can be a number from 1 to 100 giving the JPEG
+compression quality. High values are better quality and larger files.
-=item tiff_resolutionunit
+=item *
-The value of the ResolutionUnit tag. This is ignored on writing if
-the i_aspect_only tag is non-zero.
+X<tags, tiff_resolutionunit>C<tiff_resolutionunit> - The value of the
+C<ResolutionUnit> tag. This is ignored on writing if the
+i_aspect_only tag is non-zero.
The C<i_xres> and C<i_yres> tags are expressed in pixels per inch no
matter the value of this tag, they will be converted to/from the value
stored in the TIFF file.
-=item tiff_resolutionunit_name
+=item *
-This is set when reading a TIFF file to the name of the unit given by
+X<tags, tiff_resolutionunit_name>C<tiff_resolutionunit_name> - This is
+set when reading a TIFF file to the name of the unit given by
C<tiff_resolutionunit>. Possible results include C<inch>,
C<centimeter>, C<none> (the C<i_aspect_only> tag is also set reading
these files) or C<unknown>.
-=item tiff_bitspersample
-
-Bits per sample from the image. This value is not used when writing
-an image, it is only set on a read image.
-
-=item tiff_photometric
-
-Value of the PhotometricInterpretation tag from the image. This value
-is not used when writing an image, it is only set on a read image.
-
-=item tiff_documentname
-
-=item tiff_imagedescription
-
-=item tiff_make
-
-=item tiff_model
-
-=item tiff_pagename
+=item *
-=item tiff_software
+X<tags, tiff_bitspersample>C<tiff_bitspersample> - Bits per sample
+from the image. This value is not used when writing an image, it is
+only set on a read image.
-=item tiff_datetime
+=item *
-=item tiff_artist
+X<tags, tiff_photometric>C<tiff_photometric> - Value of the
+C<PhotometricInterpretation> tag from the image. This value is not
+used when writing an image, it is only set on a read image.
-=item tiff_hostcomputer
+=item *
-Various strings describing the image. tiff_datetime must be formatted
-as "YYYY:MM:DD HH:MM:SS". These correspond directly to the mixed case
-names in the TIFF specification. These are set in images read from a
-TIFF and saved when writing a TIFF image.
+C<tiff_documentname>, C<tiff_imagedescription>, C<tiff_make>,
+C<tiff_model>, C<tiff_pagename>, C<tiff_software>, C<tiff_datetime>,
+C<tiff_artist>, C<tiff_hostcomputer> - Various strings describing the
+image. C<tiff_datetime> must be formatted as "YYYY:MM:DD HH:MM:SS".
+These correspond directly to the mixed case names in the TIFF
+specification. These are set in images read from a TIFF and saved
+when writing a TIFF image.
=back
@@ -943,25 +989,10 @@ some page other than the first. The page is 0 based:
$image->read(file=>"example.tif", page=>1)
or die "Cannot read second page: ",$image->errstr,"\n";
-Note: Imager uses the TIFF*RGBA* family of libtiff functions,
-unfortunately these don't support alpha channels on CMYK images. This
-will result in a full coverage alpha channel on CMYK images with an
-alpha channel, until this is implemented in libtiff (or Imager's TIFF
-implementation changes.)
-
If you read an image with multiple alpha channels, then only the first
alpha channel will be read.
-Currently Imager's TIFF support reads all direct color images as 8-bit
-RGB images, this may change in the future to reading 16-bit/sample
-images.
-
-Currently tags that control the output color type and compression are
-ignored when writing, this may change in the future. If you have
-processes that rely upon Imager always producing packbits compressed
-RGB images, you should strip any tags before writing.
-
-=head2 BMP (BitMaP)
+=head2 BMP (Windows Bitmap)
Imager can write 24-bit RGB, and 8, 4 and 1-bit per pixel paletted
Windows BMP files. Currently you cannot write compressed BMP files
@@ -971,7 +1002,7 @@ Imager can read 24-bit RGB, and 8, 4 and 1-bit perl pixel paletted
Windows BMP files. There is some support for reading 16-bit per pixel
images, but I haven't found any for testing.
-BMP has no support for multi-image files.
+BMP has no support for multiple image files.
BMP files support the spatial resolution tags, but since BMP has no
support for storing only an aspect ratio, if C<i_aspect_only> is set
@@ -987,6 +1018,8 @@ The following tags are set when you read an image from a BMP file:
The type of compression, if any. This can be any of the following
values:
+=for stopwords RLE
+
=over
=item BI_RGB (0)
@@ -1029,17 +1062,18 @@ Number of bits stored per pixel. (24, 8, 4 or 1)
=back
-=head2 TGA (TarGA)
+=for stopwords Targa
-When storing targa images rle compression can be activated with the
-'compress' parameter, the 'idstring' parameter can be used to set the
-targa comment field and the 'wierdpack' option can be used to use the
-15 and 16 bit targa formats for rgb and rgba data. The 15 bit format
+=head2 TGA (Targa)
+
+When storing Targa images RLE compression can be activated with the
+C<compress> parameter, the C<idstring> parameter can be used to set the
+Targa comment field and the C<wierdpack> option can be used to use the
+15 and 16 bit Targa formats for RGB and RGBA data. The 15 bit format
has 5 of each red, green and blue. The 16 bit format in addition
allows 1 bit of alpha. The most significant bits are used for each
channel.
-
Tags:
=over
@@ -1055,14 +1089,14 @@ Tags:
=head2 RAW
When reading raw images you need to supply the width and height of the
-image in the xsize and ysize options:
+image in the C<xsize> and C<ysize> options:
$img->read(file=>'foo.raw', xsize=>100, ysize=>100)
or die "Cannot read raw image\n";
If your input file has more channels than you want, or (as is common),
-junk in the fourth channel, you can use the datachannels and
-storechannels options to control the number of channels in your input
+junk in the fourth channel, you can use the C<datachannels> and
+C<storechannels> options to control the number of channels in your input
file and the resulting channels in your image. For example, if your
input image uses 32-bits per pixel with red, green, blue and junk
values for each pixel you could do:
@@ -1087,15 +1121,15 @@ Possible values:
0 - samples are pixel by pixel, so all samples for the first pixel,
then all samples for the second pixel and so on. eg. for a four pixel
-scanline the channels would be laid out as:
+scan line the channels would be laid out as:
012012012012
=item *
-1 - samples are line by line, so channel 0 for the entire scanline is
-followed by channel 1 for the entire scanline and so on. eg. for a
-four pixel scanline the channels would be laid out as:
+1 - samples are line by line, so channel 0 for the entire scan line is
+followed by channel 1 for the entire scan line and so on. eg. for a
+four pixel scan line the channels would be laid out as:
000011112222
@@ -1136,7 +1170,7 @@ There are no PNG specific tags.
=head2 ICO (Microsoft Windows Icon) and CUR (Microsoft Windows Cursor)
Icon and Cursor files are very similar, the only differences being a
-number in the header and the storage of the cursor hotspot. I've
+number in the header and the storage of the cursor hot spot. I've
treated them separately so that you're not messing with tags to
distinguish between them.
@@ -1162,7 +1196,7 @@ newline.
=item *
-following lines which contain 0 and 1 placeholders for each scanline
+following lines which contain 0 and 1 placeholders for each scan line
of the image, starting from the top of the image.
=back
@@ -1268,6 +1302,8 @@ Examples:
$im->settag(name => 'cur_hotspoty', value => 16);
$im->write(file => 'box.cur');
+=for stopwords BW
+
=head2 SGI (RGB, BW)
SGI images, often called by the extensions, RGB or BW, can be stored
@@ -1284,14 +1320,14 @@ The following tags are set when reading a SGI image:
=item *
-i_comment - the IMAGENAME field from the image. Also written to the
-file when writing.
+i_comment - the C<IMAGENAME> field from the image. Also written to
+the file when writing.
=item *
-sgi_pixmin, sgi_pixmax - the PIXMIN and PIXMAX fields from the image.
-On reading image data is expanded from this range to the full range of
-samples in the image.
+sgi_pixmin, sgi_pixmax - the C<PIXMIN> and C<PIXMAX> fields from the
+image. On reading image data is expanded from this range to the full
+range of samples in the image.
=item *
@@ -1490,6 +1526,8 @@ to autoload it.
Once you have an image the basic mechanism is:
+=for stopwords STDOUT
+
=over
=item 1.
@@ -1540,7 +1578,7 @@ The basic idea is simple, just use write_multi():
If your images are RGB images the default quantization mechanism will
produce a very good result, but can take a long time to execute. You
-could either use the standard webmap:
+could either use the standard web color map:
Imager->write_multi({ file=>$filename,
type=>'gif',
@@ -1554,7 +1592,7 @@ or use a median cut algorithm to built a fairly optimal color map:
make_colors=>'mediancut' },
@imgs);
-By default all of the images will use the same global colormap, which
+By default all of the images will use the same global color map, which
will produce a smaller image. If your images have significant color
differences, you may want to generate a new palette for each image:
@@ -1597,9 +1635,9 @@ This is pretty simple:
=head1 BUGS
-When saving Gif images the program does NOT try to shave of extra
+When saving GIF images the program does NOT try to shave off extra
colors if it is possible. If you specify 128 colors and there are
-only 2 colors used - it will have a 128 colortable anyway.
+only 2 colors used - it will have a 128 color table anyway.
=head1 SEE ALSO
@@ -2,7 +2,7 @@ package Imager::Fill;
use strict;
use vars qw($VERSION);
-$VERSION = "1.010";
+$VERSION = "1.011";
# this needs to be kept in sync with the array of hatches in fills.c
my @hatch_types =
@@ -270,75 +270,74 @@ Current hatch names are:
=over
-=item check1x1, check2x2, check4x4
+=item *
-checkerboards at varios sizes
+C<check1x1>, C<check2x2>, C<check4x4> - checkerboards at various sizes
-=item vline1, vline2, vline4
+=item *
-1, 2, or 4 vertical lines per cell
+C<vline1>, C<vline2>, C<vline4> - 1, 2, or 4 vertical lines per cell
-=item hline1, hline2, hline4
+=item *
-1, 2, or 4 horizontal lines per cell
+C<hline1>, C<hline2>, C<hline4> - 1, 2, or 4 horizontal lines per cell
-=item slash1, slash2
+=item *
-1 or 2 / lines per cell.
+C<slash1>, C<slash2> - 1 or 2 / lines per cell.
-=item slosh1, slosh2
+=item *
-1 or 2 \ lines per cell
+C<slosh1>, C<slosh2> - 1 or 2 \ lines per cell
-=item grid1, grid2, grid4
+=item *
-1, 2, or 4 vertical and horizontal lines per cell
+C<grid1>, C<grid2>, C<grid4> - 1, 2, or 4 vertical and horizontal
+lines per cell
-=item dots1, dots4, dots16
+=item *
-1, 4 or 16 dots per cell
+C<dots1>, C<dots4>, C<dots16> - 1, 4 or 16 dots per cell
-=item stipple, stipple2
+=item *
-see the samples
+C<stipple>, C<stipple2> - see the samples
-=item weave
+=item *
-I hope this one is obvious.
+C<weave> - I hope this one is obvious.
-=item cross1, cross2
+=item *
-2 densities of crosshatch
+C<cross1>, C<cross2> - 2 densities of crosshatch
-=item vlozenge, hlozenge
+=item *
-something like lozenge tiles
+C<vlozenge>, C<hlozenge> - something like lozenge tiles
-=item scalesdown, scalesup, scalesleft, scalesright
+=item *
-Vaguely like fish scales in each direction.
+C<scalesdown>, C<scalesup>, C<scalesleft>, C<scalesright> - Vaguely
+like fish scales in each direction.
-=item tile_L
+=item *
-L-shaped tiles
+C<tile_L> - L-shaped tiles
=back
-=item fg
-
-=item bg
-
-The fg color is rendered where bits are set in the hatch, and the bg
-where they are clear. If you use a transparent fg or bg, and set
-combine, you can overlay the hatch onto an existing image.
+=item *
-fg defaults to black, bg to white.
+C<fg>, C<bg> - The C<fg> color is rendered where bits are set in the
+hatch, and the C<bg> where they are clear. If you use a transparent
+C<fg> or C<bg>, and set combine, you can overlay the hatch onto an
+existing image.
-=item dx
+C<fg> defaults to black, C<bg> to white.
-=item dy
+=item *
-An offset into the hatch cell. Both default to zero.
+C<dx>, C<dy> - An offset into the hatch cell. Both default to zero.
=back
@@ -362,8 +361,8 @@ and is required.
matrix=>$matrix, $combine);
Fills the given image with a tiled version of the given image. The
-first non-zero value of xoff or yoff will provide an offset along the
-given axis between rows or columns of tiles respectively.
+first non-zero value of C<xoff> or C<yoff> will provide an offset
+along the given axis between rows or columns of tiles respectively.
The matrix parameter performs a co-ordinate transformation from the
co-ordinates in the target image to the fill image co-ordinates.
@@ -400,7 +399,7 @@ opacity - multiplier for the source fill opacity. Default: 0.5.
=back
-The source fill's combine mode is used.
+The source fills combine mode is used.
=head1 OTHER METHODS
@@ -422,17 +421,17 @@ I'm planning on adding the following types of fills:
=over
-=item checkerboard
+=item *
-combines 2 other fills in a checkerboard
+C<checkerboard> - combines 2 other fills in a checkerboard
-=item combine
+=item *
-combines 2 other fills using the levels of an image
+C<combine> - combines 2 other fills using the levels of an image
-=item regmach
+=item *
-uses the transform2() register machine to create fills
+C<regmach> - uses the transform2() register machine to create fills
=back
@@ -50,7 +50,7 @@ many other possible parameters, see L</Types of Filters> below.
=head2 Types of Filters
-Here is a list of the filters that are always avaliable in Imager.
+Here is a list of the filters that are always available in Imager.
This list can be obtained by running the C<filterlist.perl> script
that comes with the module source.
@@ -133,12 +133,12 @@ A reference of the filters follows:
=over
-=item autolevels
+=item C<autolevels>
scales the value of each channel so that the values in the image will
-cover the whole possible range for the channel. I<lsat> and I<usat>
+cover the whole possible range for the channel. C<lsat> and C<usat>
truncate the range by the specified fraction at the top and bottom of
-the range respectivly.
+the range respectively.
# increase contrast per channel, losing little detail
$img->filter(type=>"autolevels")
@@ -148,32 +148,32 @@ the range respectivly.
$img->filter(type=>"autolevels", lsat=>0.2, usat=>0.2)
or die $img->errstr;
-=item bumpmap
+=item C<bumpmap>
-uses the channel I<elevation> image I<bump> as a bumpmap on your
-image, with the light at (I<lightx>, I<lightty>), with a shadow length
-of I<st>.
+uses the channel C<elevation> image C<bump> as a bump map on your
+image, with the light at (C<lightx>, C<lightty>), with a shadow length
+of C<st>.
$img->filter(type=>"bumpmap", bump=>$bumpmap_img,
lightx=>10, lighty=>10, st=>5)
or die $img->errstr;
-=item bumpmap_complex
+=item C<bumpmap_complex>
-uses the channel I<channel> image I<bump> as a bumpmap on your image.
-If Lz<0 the three L parameters are considered to be the direction of
-the light. If Lz>0 the L parameters are considered to be the light
-position. I<Ia> is the ambient colour, I<Il> is the light colour,
-I<Is> is the color of specular highlights. I<cd> is the diffuse
-coefficient and I<cs> is the specular coefficient. I<n> is the
-shininess of the surface.
+uses the channel C<channel> image C<bump> as a bump map on your image.
+If C<< Lz < 0 >> the three L parameters are considered to be the
+direction of the light. If C<< Lz > 0 >> the L parameters are
+considered to be the light position. C<Ia> is the ambient color,
+C<Il> is the light color, C<Is> is the color of specular highlights.
+C<cd> is the diffuse coefficient and C<cs> is the specular
+coefficient. C<n> is the shininess of the surface.
$img->filter(type=>"bumpmap_complex", bump=>$bumpmap_img)
or die $img->errstr;
-=item contrast
+=item C<contrast>
-scales each channel by I<intensity>. Values of I<intensity> < 1.0
+scales each channel by C<intensity>. Values of C<intensity> < 1.0
will reduce the contrast.
# higher contrast
@@ -184,10 +184,10 @@ will reduce the contrast.
$img->filter(type=>"contrast", intensity=>0.8)
or die $img->errstr;
-=item conv
+=item C<conv>
performs 2 1-dimensional convolutions on the image using the values
-from I<coef>. I<coef> should be have an odd length and the sum of the
+from C<coef>. C<coef> should be have an odd length and the sum of the
coefficients must be non-zero.
# sharper
@@ -202,42 +202,44 @@ coefficients must be non-zero.
$img->filter(type=>"conv", coef=>[ -0.5, 1, -0.5 ])
or die $img->errstr;
-=item fountain
+=item C<fountain>
renders a fountain fill, similar to the gradient tool in most paint
software. The default fill is a linear fill from opaque black to
-opaque white. The points A(xa, ya) and B(xb, yb) control the way the
-fill is performed, depending on the ftype parameter:
+opaque white. The points C<A(Cxa, ya)> and C<B(xb, yb)> control the
+way the fill is performed, depending on the C<ftype> parameter:
+
+=for stopwords ramping
=over
-=item linear
+=item C<linear>
the fill ramps from A through to B.
-=item bilinear
+=item C<bilinear>
the fill ramps in both directions from A, where AB defines the length
of the gradient.
-=item radial
+=item C<radial>
A is the center of a circle, and B is a point on it's circumference.
The fill ramps from the center out to the circumference.
-=item radial_square
+=item C<radial_square>
A is the center of a square and B is the center of one of it's sides.
This can be used to rotate the square. The fill ramps out to the
edges of the square.
-=item revolution
+=item C<revolution>
-A is the centre of a circle and B is a point on it's circumference. B
+A is the center of a circle and B is a point on its circumference. B
marks the 0 and 360 point on the circle, with the fill ramping
clockwise.
-=item conical
+=item C<conical>
A is the center of a circle and B is a point on it's circumference. B
marks the 0 and point on the circle, with the fill ramping in both
@@ -245,31 +247,31 @@ directions to meet opposite.
=back
-The I<repeat> option controls how the fill is repeated for some
-I<ftype>s after it leaves the AB range:
+The C<repeat> option controls how the fill is repeated for some
+C<ftype>s after it leaves the AB range:
=over
-=item none
+=item C<none>
no repeats, points outside of each range are treated as if they were
on the extreme end of that range.
-=item sawtooth
+=item C<sawtooth>
the fill simply repeats in the positive direction
-=item triangle
+=item C<triangle>
the fill repeats in reverse and then forward and so on, in the
positive direction
-=item saw_both
+=item C<saw_both>
the fill repeats in both the positive and negative directions (only
meaningful for a linear fill).
-=item tri_both
+=item C<tri_both>
as for triangle, but in the negative direction too (only meaningful
for a linear fill).
@@ -399,17 +401,19 @@ Really. It even loads GIMP gradient files.
xb => $im->getwidth / 2,
yb => 0)
or die $radial->errstr;
+
+=for stopwords Gaussian
-=item gaussian
+=item C<gaussian>
-performs a gaussian blur of the image, using I<stddev> as the standard
+performs a Gaussian blur of the image, using C<stddev> as the standard
deviation of the curve used to combine pixels, larger values give
bigger blurs. For a definition of Gaussian Blur, see:
http://www.maths.abdn.ac.uk/~igc/tch/mx4002/notes/node99.html
-Values of C<stddev> around 0.5 provide a barely noticable blur, values
-around 5 provide a very strong blur.
+Values of C<stddev> around 0.5 provide a barely noticeable blur,
+values around 5 provide a very strong blur.
# only slightly blurred
$img->filter(type=>"gaussian", stddev=>0.5)
@@ -419,11 +423,11 @@ around 5 provide a very strong blur.
$img->filter(type=>"gaussian", stddev=>5)
or die $img->errstr;
-=item gradgen
+=item C<gradgen>
renders a gradient, with the given I<colors> at the corresponding
-points (x,y) in I<xo> and I<yo>. You can specify the way distance is
-measured for color blending by setting I<dist> to 0 for Euclidean, 1
+points (x,y) in C<xo> and C<yo>. You can specify the way distance is
+measured for color blending by setting C<dist> to 0 for Euclidean, 1
for Euclidean squared, and 2 for Manhattan distance.
$img->filter(type="gradgen",
@@ -431,7 +435,7 @@ for Euclidean squared, and 2 for Manhattan distance.
yo=>[ 10, 50, 50 ],
colors=>[ qw(red blue green) ]);
-=item hardinvert
+=item C<hardinvert>
inverts the image, black to white, white to black. All channels are
inverted, including the alpha channel if any.
@@ -439,16 +443,16 @@ inverted, including the alpha channel if any.
$img->filter(type=>"hardinvert")
or die $img->errstr;
-=item mosaic
+=item C<mosaic>
-produces averaged tiles of the given I<size>.
+produces averaged tiles of the given C<size>.
$img->filter(type=>"mosaic", size=>5)
or die $img->errstr;
-=item noise
+=item C<noise>
-adds noise of the given I<amount> to the image. If I<subtype> is
+adds noise of the given C<amount> to the image. If C<subtype> is
zero, the noise is even to each channel, otherwise noise is added to
each channel independently.
@@ -460,69 +464,78 @@ each channel independently.
$img->filter(type=>"noise", amount=>20, subtype=>1)
or die $img->errstr;
-=item radnoise
+=for stopwords Perlin
-renders radiant Perlin turbulent noise. The centre of the noise is at
-(I<xo>, I<yo>), I<ascale> controls the angular scale of the noise ,
-and I<rscale> the radial scale, higher numbers give more detail.
+=item C<radnoise>
+
+renders radiant Perlin turbulent noise. The center of the noise is at
+(C<xo>, C<yo>), C<ascale> controls the angular scale of the noise ,
+and C<rscale> the radial scale, higher numbers give more detail.
$img->filter(type=>"radnoise", xo=>50, yo=>50,
ascale=>1, rscale=>0.02)
or die $img->errstr;
-=item postlevels
+=item C<postlevels>
-alters the image to have only I<levels> distinct level in each
+alters the image to have only C<levels> distinct level in each
channel.
$img->filter(type=>"postlevels", levels=>10)
or die $img->errstr;
-=item turbnoise
+=item C<turbnoise>
-renders Perlin turbulent noise. (I<xo>, I<yo>) controls the origin of
-the noise, and I<scale> the scale of the noise, with lower numbers
+renders Perlin turbulent noise. (C<xo>, C<yo>) controls the origin of
+the noise, and C<scale> the scale of the noise, with lower numbers
giving more detail.
$img->filter(type=>"turbnoise", xo=>10, yo=>10, scale=>10)
or die $img->errstr;
-=item unsharpmask
+=for stopwords unsharp
+
+=item C<unsharpmask>
performs an unsharp mask on the image. This increases the contrast of
edges in the image.
-This is the result of subtracting a gaussian blurred version of the
-image from the original. I<stddev> controls the stddev parameter of
-the gaussian blur. Each output pixel is: in + I<scale> * (in -
-blurred).
+This is the result of subtracting a Gaussian blurred version of the
+image from the original. C<stddev> controls the C<stddev> parameter
+of the Gaussian blur. Each output pixel is:
+
+ in + scale * (in - blurred)
+
+eg.
$img->filter(type=>"unsharpmask", stddev=>1, scale=>0.5)
or die $img->errstr;
-unsharpmark has the following parameters:
+C<unsharpmark> has the following parameters:
+
+=for stopwords GIMP GIMP's
=over
=item *
-stddev - this is equivalent to the C<Radius> value in the GIMP's
-unsharpmask filter. This controls the size of the contrast increase
+C<stddev> - this is equivalent to the C<Radius> value in the GIMP's
+unsharp mask filter. This controls the size of the contrast increase
around edges, larger values will remove fine detail. You should
-probably experiement on the types of images you plan to work with.
+probably experiment on the types of images you plan to work with.
Default: 2.0.
=item *
-scale - controls the strength of the edge enhancement, equivalent to
-I<Amount> in the GIMP's unsharp mask filter. Default: 1.0.
+C<scale> - controls the strength of the edge enhancement, equivalent
+to I<Amount> in the GIMP's unsharp mask filter. Default: 1.0.
=back
-=item watermark
+=item C<watermark>
-applies I<wmark> as a watermark on the image with strength I<pixdiff>,
-with an origin at (I<tx>, I<ty>)
+applies C<wmark> as a watermark on the image with strength C<pixdiff>,
+with an origin at (C<tx>, C<ty>)
$img->filter(type=>"watermark", tx=>10, ty=>50,
wmark=>$wmark_image, pixdiff=>50)
@@ -557,20 +570,20 @@ The following parameters are needed:
=item *
-type - the type value that will be supplied to filter() to use your
+C<type> - the type value that will be supplied to filter() to use your
filter.
=item *
-defaults - a hash of defaults for the filter's parameters
+C<defaults> - a hash of defaults for the filter's parameters
=item *
-callseq - a reference to an array of required parameter names.
+C<callseq> - a reference to an array of required parameter names.
=item *
-callsub - a code reference called to execute your filter. The
+C<callsub> - a code reference called to execute your filter. The
parameters passed to filter() are supplied as a list of parameter
name, value ... which can be assigned to a hash.
@@ -585,16 +598,18 @@ See Imager::Filter::Mandelbrot for an example.
=back
-=head2 Plugins
+=for stopwords DSOs
-The plugin interface is deprecated. Please use the Imager API, see
+=head2 Plug-ins
+
+The plug in interface is deprecated. Please use the Imager API, see
L</Imager::API> and L<External Filters> for details
It is possible to add filters to the module without recompiling the
module itself. This is done by using DSOs (Dynamic shared object)
-avaliable on most systems. This way you can maintain our own filters
+available on most systems. This way you can maintain our own filters
and not have to get me to add it, or worse patch every new version of
-the Module. Modules can be loaded AND UNLOADED at runtime. This
+the Module. Modules can be loaded AND UNLOADED at run time. This
means that you can have a server/daemon thingy that can do something
like:
@@ -607,7 +622,7 @@ like:
or die "unable to load plugin\n";
Someone decides that the filter is not working as it should -
-dyntest.c modified and recompiled.
+F<dyntest.c> modified and recompiled.
load_plugin("dynfilt/dyntest.so")
or die "unable to load plugin\n";
@@ -617,9 +632,11 @@ dyntest.c modified and recompiled.
An example plugin comes with the module - Please send feedback to
addi@umich.edu if you test this.
-Note: This seems to test ok on the following systems:
-Linux, Solaris, HPUX, OpenBSD, FreeBSD, TRU64/OSF1, AIX.
-If you test this on other systems please let me know.
+=for stopwords Linux Solaris HPUX OpenBSD FreeBSD TRU64 OSF1 AIX
+
+Note: This seems to test successfully on the following systems: Linux,
+Solaris, HPUX, OpenBSD, FreeBSD, TRU64/OSF1, AIX. If you test this on
+other systems please let me know.
=over
@@ -650,7 +667,7 @@ Returns true on success. Check Imager->errstr on failure.
=over
-=item difference
+=item difference()
You can create a new image that is the difference between 2 other images.
@@ -673,14 +690,14 @@ Parameters:
=item *
-other - the other image object to compare against
+C<other> - the other image object to compare against
=item *
-mindist - the difference between corresponding samples must be greater
-than I<mindist> for the pixel to be considered different. So a value
-of zero returns all different pixels, not all pixels. Range: 0 to 255
-inclusive. Default: 0.
+C<mindist> - the difference between corresponding samples must be
+greater than C<mindist> for the pixel to be considered different. So
+a value of zero returns all different pixels, not all pixels. Range:
+0 to 255 inclusive. Default: 0.
For large sample images this is scaled down to the range 0 .. 1.
@@ -698,6 +715,6 @@ Imager, Imager::Filter::Flines, Imager::Filter::Mandelbrot
=head1 REVISION
-$Revision: 1643 $
+$Revision: 1724 $
=cut
@@ -2,7 +2,7 @@ package Imager::Font::BBox;
use strict;
use vars qw($VERSION);
-$VERSION = "1.005";
+$VERSION = "1.006";
=head1 NAME
@@ -48,7 +48,7 @@ accessible.
=item left_bearing
-Returns the horizonatal offset from the selected drawing location to
+Returns the horizontal offset from the selected drawing location to
the left edge of the first character drawn. If this is positive, the
first glyph is to the right of the drawing location.
@@ -4,7 +4,7 @@ use Imager::Color;
use vars qw(@ISA $VERSION);
@ISA = qw(Imager::Font);
-$VERSION = "1.013";
+$VERSION = "1.014";
*_first = \&Imager::Font::_first;
@@ -207,11 +207,17 @@ The following parameters:
=over
-=item utf8
+=item *
-=item vlayour
+C<utf8>
-=item sizew
+=item *
+
+C<vlayout>
+
+=item *
+
+C<sizew>
=back
@@ -3,7 +3,7 @@ use strict;
use vars qw(@ISA $VERSION);
@ISA = qw(Imager::Font);
-$VERSION = "1.010";
+$VERSION = "1.011";
*_first = \&Imager::Font::_first;
@@ -112,8 +112,8 @@ __END__
=head1 DESCRIPTION
-Imager::Font creates a Imager::Font::Truetype object when asked to create
-a font object based on a .ttf file.
+Imager::Font creates a Imager::Font::Truetype object when asked to
+create a font object based on a F<.ttf> file.
See Imager::Font to see how to use this type.
@@ -4,7 +4,7 @@ use Imager::Color;
use vars qw(@ISA $VERSION);
@ISA = qw(Imager::Font);
-$VERSION = "1.010";
+$VERSION = "1.011";
*_first = \&Imager::Font::_first;
@@ -148,7 +148,7 @@ __END__
=head1 DESCRIPTION
Imager::Font creates a Imager::Font::Type1 object when asked to create
-a font object based on a .pfb file.
+a font object based on a C<.pfb> file.
See Imager::Font to see how to use this type.
@@ -165,19 +165,21 @@ This must be called before creating any fonts.
Currently specific to Imager::Font::Type1, you can use the following
flags when drawing text or calculating a bounding box:
+=for stopwords overline strikethrough
+
=over
-=item underline
+=item *
-Draw the text with an underline.
+C<underline> - Draw the text with an underline.
-=item overline
+=item *
-Draw the text with an overline.
+C<overline> - Draw the text with an overline.
-=item strikethrough
+=item *
-Draw the text with a strikethrough.
+C<strikethrough> - Draw the text with a strikethrough.
=back
@@ -3,7 +3,7 @@ use strict;
use vars qw(@ISA $VERSION);
@ISA = qw(Imager::Font);
-$VERSION = "1.005";
+$VERSION = "1.006";
# called by Imager::Font::new()
# since Win32's HFONTs include the size information this
@@ -47,6 +47,8 @@ __END__
=head1 NAME
+=for stopwords GDI
+
Imager::Font::Win32 - uses Win32 GDI services for text output
=head1 SYNOPSIS
@@ -4,7 +4,7 @@ use Imager;
use Imager::Font;
use vars qw($VERSION);
-$VERSION = "1.002";
+$VERSION = "1.003";
*_first = \&Imager::Font::_first;
@@ -240,33 +240,32 @@ C<height>.
=over
-=item wrap_text
+=item wrap_text()
Draw word-wrapped text.
=over
-=item x
+=item *
-=item y
+C<x>, C<y> - The top-left corner of the rectangle the text is
+formatted into. Defaults to (0, 0).
-The top-left corner of the rectangle the text is formatted into.
-Defaults to (0, 0).
+=item *
-=item width
+C<width> - The width of the formatted text in pixels. Defaults to the
+horizontal gap between the top-left corner and the right edge of the
+image. If no image is supplied then this is required.
-The width of the formatted text in pixels. Defaults to the horizontal
-gap between the top-left corner and the right edge of the image. If
-no image is supplied then this is required.
+=item *
-=item height
+C<height> - The maximum height of the formatted text in pixels. Not
+required.
-The maximum height of the formated text in pixels. Not required.
+=item *
-=item savepos
-
-The amount of text consumed (as a count of characters) will be stored
-into the scalar this refers to.
+C<savepos> - The amount of text consumed (as a count of characters)
+will be stored into the scalar this refers to.
my $pagenum = 1;
my $string = "...";
@@ -284,57 +283,60 @@ into the scalar this refers to.
$img->write(file=>"page$pagenum.ppm");
}
-=item image
+=item *
-The image to render the text to. Can be supplied as C<undef> to
-simply calculate the bounding box.
+C<image> - The image to render the text to. Can be supplied as
+C<undef> to simply calculate the bounding box.
-=item font
+=item *
-The font used to render the text. Required.
+C<font> - The font used to render the text. Required.
-=item size
+=item *
-The size to render the font in. Defaults to the size stored in the
-font object. Required if it isn't stored in the font object.
+C<size> - The size to render the font in. Defaults to the size stored
+in the font object. Required if it isn't stored in the font object.
-=item string
+=item *
-The text to render. This can contain non-whitespace, blanks (ASCII
-0x20), and newlines.
+C<string> - The text to render. This can contain non-white-space,
+blanks (ASCII 0x20), and newlines.
-Newlines must match /(?:\x0A\x0D?|\x0D\x0A?)/. Whitespace other than
+Newlines must match /(?:\x0A\x0D?|\x0D\x0A?)/. White-space other than
blanks and newlines are completely ignored.
-=item justify
+=item *
+
+C<justify>
The way text is formatted within each line. Possible values include:
=over
-=item left
+=item *
-Left aligned against the left edge of the text box.
+C<left> - left aligned against the left edge of the text box.
-=item right
+=item *
-Right aligned against the right edge of the text box.
+C<right> - right aligned against the right edge of the text box.
-=item center
+=item *
-Centered horizontally in the text box.
+C<center> - centered horizontally in the text box.
-=item fill
+=item *
-All but the final line of the paragraph has spaces expanded so that
-the line fills from the left to the right edge of the text box.
+fill - all but the final line of the paragraph has spaces expanded so
+that the line fills from the left to the right edge of the text box.
=back
-=item linegap
+=item *
-Gap between lines of text in pixels. This is in addition to the size
-from $font->font_height. Can be positive or negative. Default 0.
+C<linegap> - Gap between lines of text in pixels. This is in addition
+to the size from C<< $font->font_height >>. Can be positive or
+negative. Default 0.
=back
@@ -365,7 +367,7 @@ before doing it:
=head1 BUGS
-Imager::Font can handle UTF8 encoded text itself, but this module
+Imager::Font can handle UTF-8 encoded text itself, but this module
doesn't support that (and probably won't). This could probably be
done with regex magic.
@@ -4,7 +4,7 @@ use Imager::Color;
use strict;
use vars qw($VERSION);
-$VERSION = "1.033";
+$VERSION = "1.034";
# the aim here is that we can:
# - add file based types in one place: here
@@ -371,11 +371,13 @@ Imager::Font - Font handling for Imager.
=head1 DESCRIPTION
-This module handles creating Font objects used by imager. The module
+=for stopwords TrueType FreeType
+
+This module handles creating Font objects used by Imager. The module
also handles querying fonts for sizes and such. If both T1lib and
-freetype were avaliable at the time of compilation then Imager should
-be able to work with both truetype fonts and t1 postscript fonts. To
-check if Imager is t1 or truetype capable you can use something like
+FreeType were available at the time of compilation then Imager should
+be able to work with both TrueType fonts and t1 Postscript fonts. To
+check if Imager is t1 or TrueType capable you can use something like
this:
use Imager;
@@ -396,20 +398,21 @@ This creates a font object to pass to functions that take a font argument.
size => 30,
aa => 1);
-This creates a font which is the truetype font denmark.ttf. It's
+This creates a font which is the TrueType font F<denmark.ttf>. It's
default color is $blue, default size is 30 pixels and it's rendered
-antialised by default. Imager can see which type of font a file is by
-looking at the suffix of the filename for the font. A suffix of 'ttf'
-is taken to mean a truetype font while a suffix of 'pfb' is taken to
-mean a t1 postscript font. If Imager cannot tell which type a font is
-you can tell it explicitly by using the C<type> parameter:
+anti-aliased by default. Imager can see which type of font a file is
+by looking at the suffix of the file name for the font. A suffix of
+C<ttf> is taken to mean a TrueType font while a suffix of C<pfb> is
+taken to mean a Type 1 Postscript font. If Imager cannot tell which
+type a font is you can tell it explicitly by using the C<type>
+parameter:
$t1font = Imager::Font->new(file => 'fruitcase', type => 't1');
$ttfont = Imager::Font->new(file => 'arglebarf', type => 'tt');
The C<index> parameter is used to select a single face from a font
file containing more than one face, for example, from a Macintosh font
-suitcase or a .dfont file.
+suitcase or a C<.dfont> file.
If any of the C<color>, C<size> or C<aa> parameters are omitted when
calling C<< Imager::Font->new() >> the they take the following values:
@@ -419,13 +422,13 @@ calling C<< Imager::Font->new() >> the they take the following values:
aa => 0
index => 0
-To use Win32 fonts supply the facename of the font:
+To use Win32 fonts supply the face name of the font:
$font = Imager::Font->new(face=>'Arial Bold Italic');
There isn't any access to other logical font attributes, but this
typically isn't necessary for Win32 TrueType fonts, since you can
-contruct the full name of the font as above.
+construct the full name of the font as above.
Other logical font attributes may be added if there is sufficient demand.
@@ -435,67 +438,71 @@ Parameters:
=item *
-file - name of the file to load the font from.
+C<file> - name of the file to load the font from.
=item *
-face - face name. This is used only under Win32 to create a GDI based
+=for stopwords GDI
+
+C<face> - face name. This is used only under Win32 to create a GDI based
font. This is ignored if the C<file> parameter is supplied.
=item *
-type - font driver to use. Currently the permitted values for this are:
+C<type> - font driver to use. Currently the permitted values for this are:
=over
=item *
-tt - Freetype 1.x driver. Supports TTF fonts.
+C<tt> - FreeType 1.x driver. Supports TrueType (C<.ttf>) fonts.
=item *
-t1 - T1 Lib driver. Supports Postscript Type 1 fonts. Allows for
+=for stopwords strikethrough overline
+
+C<t1> - T1 Lib driver. Supports Postscript Type 1 fonts. Allows for
synthesis of underline, strikethrough and overline.
=item *
-ft2 - Freetype 2.x driver. Supports many different font formats.
+C<ft2> - FreeType 2.x driver. Supports many different font formats.
Also supports the transform() method.
=back
=item *
-color - the default color used with this font. Default: red.
+C<color> - the default color used with this font. Default: red.
=item *
-size - the default size used with this font. Default: 15.
+C<size> - the default size used with this font. Default: 15.
=item *
-utf8 - if non-zero then text supplied to $img->string(...) and
-$font->bounding_box(...) is assumed to be UTF 8 encoded by default.
+C<utf8> - if non-zero then text supplied to $img->string(...) and
+$font->bounding_box(...) is assumed to be UTF-8 encoded by default.
=item *
-align - the default value for the $img->string(...) C<align>
+C<align> - the default value for the $img->string(...) C<align>
parameter. Default: 1.
=item *
-vlayout - the default value for the $img->string(...) C<vlayout>
+C<vlayout> - the default value for the $img->string(...) C<vlayout>
parameter. Default: 0.
=item *
-aa - the default value for the $im->string(...) C<aa> parameter.
+C<aa> - the default value for the $im->string(...) C<aa> parameter.
Default: 0.
=item *
-index - for font file containing multiple fonts this selects which
-font to use. This is useful for Macintosh DFON (.dfont) and suitcase
+C<index> - for font file containing multiple fonts this selects which
+font to use. This is useful for Macintosh C<DFON> (F<.dfont>) and suitcase
font files.
If you want to use a suitcase font you will need to tell Imager to use
@@ -581,14 +588,14 @@ the space needed for the string:
@metrics = $font->bounding_box(string=>"testing",size=>15,canon=>1);
-This returns tha same values in $metrics[0] and $metrics[1],
+This returns the same values in $metrics[0] and $metrics[1],
but:
$bbox[2] - horizontal space taken by glyphs
$bbox[3] - vertical space taken by glyphs
Returns an L<Imager::Font::BBox> object in scalar context, so you can
-avoid all those confusing indices. This has methods as named above,
+avoid all those confusing indexes. This has methods as named above,
with some extra convenience methods.
Parameters are:
@@ -597,45 +604,45 @@ Parameters are:
=item *
-string - the string to calculate the bounding box for. Required.
+C<string> - the string to calculate the bounding box for. Required.
=item *
-size - the font size to use. Default: value set in
+C<size> - the font size to use. Default: value set in
Imager::Font->new(), or 15.
=item *
-sizew - the font width to use. Default to the value of the C<size>
+C<sizew> - the font width to use. Default to the value of the C<size>
parameter.
=item *
-utf8 - For drivers that support it, treat the string as UTF8 encoded.
+C<utf8> - For drivers that support it, treat the string as UTF-8 encoded.
For versions of perl that support Unicode (5.6 and later), this will
-be enabled automatically if the 'string' parameter is already a UTF8
-string. See L<UTF8> for more information. Default: the C<utf8> value
+be enabled automatically if the 'string' parameter is already a UTF-8
+string. See L<UTF-8> for more information. Default: the C<utf8> value
passed to Imager::Font->new(...) or 0.
=item *
-x, y - offsets applied to @box[0..3] to give you a adjusted bounding
+C<x>, C<y> - offsets applied to @box[0..3] to give you a adjusted bounding
box. Ignored in scalar context.
=item *
-canon - if non-zero and the C<x>, C<y> parameters are not supplied,
+C<canon> - if non-zero and the C<x>, C<y> parameters are not supplied,
then $pos_width and $global_ascent values will returned as the width
and height of the text instead.
=back
-=item string
+=item string()
The $img->string(...) method is now documented in
L<Imager::Draw/string>
-=item align(string=>$text, size=>$size, x=>..., y=>..., valign => ..., halign=>...)
+=item align(string=>$text,size=>$size,x=>...,y=>...,valign => ...,halign=>...)
Higher level text output - outputs the text aligned as specified
around the given point (x,y).
@@ -652,60 +659,62 @@ parameters:
=over
-=item valign
+=item *
-Possible values are:
+C<valign> - Possible values are:
=over
-=item top
+=item C<top>
Point is at the top of the text.
-=item bottom
+=item C<bottom>
Point is at the bottom of the text.
-=item baseline
+=item C<baseline>
Point is on the baseline of the text (default.)
-=item center
+=item C<center>
Point is vertically centered within the text.
=back
-=item halign
+=item *
+
+C<halign>
=over
-=item left
+=item *
-The point is at the left of the text.
+C<left> - the point is at the left of the text.
-=item start
+=item *
-The point is at the start point of the text.
+C<start> - the point is at the start point of the text.
-=item center
+=item *
-The point is horizontally centered within the text.
+C<center> - the point is horizontally centered within the text.
-=item right
+=item *
-The point is at the right end of the text.
+C<right> - the point is at the right end of the text.
-=item end
+=item *
-The point is at the end point of the text.
+C<end> - the point is at the end point of the text.
=back
-=item image
+=item *
-The image to draw to. Set to C<undef> to avoid drawing but still
-calculate the bounding box.
+C<image> - The image to draw to. Set to C<undef> to avoid drawing but
+still calculate the bounding box.
=back
@@ -728,16 +737,16 @@ Possible parameters are:
=item *
-xdpi, ydpi - set the horizontal and vertical resolution in dots per
-inch.
+C<xdpi>, C<ydpi> - set the horizontal and vertical resolution in dots
+per inch.
=item *
-dpi - set both horizontal and vertical resolution to this value.
+C<dpi> - set both horizontal and vertical resolution to this value.
=back
-Returns a list containing the previous xdpi, ydpi values.
+Returns a list containing the previous C<xdpi>, C<ydpi> values.
=item transform(matrix=>$matrix)
@@ -753,7 +762,7 @@ It's possible that a driver will disable hinting if you use a
transformation, to prevent discontinuities in the transformations.
See the end of the test script t/t38ft2font.t for an example.
-Currently only the ft2 (Freetype 2.x) driver supports the transform()
+Currently only the ft2 (FreeType 2.x) driver supports the transform()
method.
See samples/slant_text.pl for a sample using this function.
@@ -768,8 +777,8 @@ Checks if the characters in $text are defined by the font.
In a list context returns a list of true or false value corresponding
to the characters in $text, true if the character is defined, false if
-not. In scalar context returns a string of NUL or non-NUL
-characters. Supports UTF8 where the font driver supports UTF8.
+not. In scalar context returns a string of C<NUL> or non-C<NUL>
+characters. Supports UTF-8 where the font driver supports UTF-8.
Not all fonts support this method (use $font->can("has_chars") to
check.)
@@ -778,16 +787,16 @@ check.)
=item *
-string - string of characters to check for. Required. Must contain
+C<string> - string of characters to check for. Required. Must contain
at least one character.
=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 'string' parameter is already a UTF8
-string. See L<UTF8> for more information. Default: the C<utf8> value
-passed to Imager::Font->new(...) or 0.
+C<utf8> - For drivers that support it, treat the string as UTF-8
+encoded. For versions of perl that support Unicode (5.6 and later),
+this will be enabled automatically if the 'string' parameter is
+already a UTF-8 string. See L<UTF-8> for more information. Default:
+the C<utf8> value passed to Imager::Font->new(...) or 0.
=back
@@ -802,18 +811,18 @@ Returns a list of glyph names for each of the characters in the
string. If the character has no name then C<undef> is returned for
the character.
-Some font files do not include glyph names, in this case Freetype 2
-will not return any names. Freetype 1 can return standard names even
+Some font files do not include glyph names, in this case FreeType 2
+will not return any names. FreeType 1 can return standard names even
if there are no glyph names in the font.
-Freetype 2 has an API function that returns true only if the font has
+FreeType 2 has an API function that returns true only if the font has
"reliable glyph names", unfortunately this always returns false for
-TTF fonts. This can avoid the check of this API by supplying
+TrueType fonts. This can avoid the check of this API by supplying
C<reliable_only> as 0. The consequences of using this on an unknown
-font may be unpredictable, since the Freetype documentation doesn't
+font may be unpredictable, since the FreeType documentation doesn't
say how those name tables are unreliable, or how FT2 handles them.
-Both Freetype 1.x and 2.x allow support for glyph names to not be
+Both FreeType 1.x and 2.x allow support for glyph names to not be
included.
=item draw
@@ -825,7 +834,7 @@ See L<Imager::Draw/string>.
=head1 MULTIPLE MASTER FONTS
-The Freetype 2 driver supports multiple master fonts:
+The FreeType 2 driver supports multiple master fonts:
=over
@@ -871,7 +880,7 @@ It's possible other drivers will support multiple master fonts in the
future, check if your selected font object supports the is_mm() method
using the can() method.
-=head1 UTF8
+=head1 UTF-8
There are 2 ways of rendering Unicode characters with Imager:
@@ -879,58 +888,58 @@ There are 2 ways of rendering Unicode characters with Imager:
=item *
-For versions of perl that support it, use perl's native UTF8 strings.
+For versions of perl that support it, use perl's native UTF-8 strings.
This is the simplest method.
=item *
-Hand build your own UTF8 encoded strings. Only recommended if your
-version of perl has no UTF8 support.
+Hand build your own UTF-8 encoded strings. Only recommended if your
+version of perl has no UTF-8 support.
=back
Imager won't construct characters for you, so if want to output
-unicode character 00C3 "LATIN CAPITAL LETTER A WITH DIAERESIS", and
+Unicode character 00C3 "LATIN CAPITAL LETTER A WITH DIAERESIS", and
your font doesn't support it, Imager will I<not> build it from 0041
"LATIN CAPITAL LETTER A" and 0308 "COMBINING DIAERESIS".
-To check if a driver supports UTF8 call the utf8 method:
+To check if a driver supports UTF-8 call the utf8() method:
=over
-=item utf8
+=item utf8()
-Return true if the font supports UTF8.
+Return true if the font supports UTF-8.
=back
-=head2 Native UTF8 Support
+=head2 Native UTF-8 Support
-If your version of perl supports UTF8 and the driver supports UTF8,
+If your version of perl supports UTF-8 and the driver supports UTF-8,
just use the $im->string() method, and it should do the right thing.
=head2 Build your own
-In this case you need to build your own UTF8 encoded characters.
+In this case you need to build your own UTF-8 encoded characters.
For example:
$x = pack("C*", 0xE2, 0x80, 0x90); # character code 0x2010 HYPHEN
-You need to be be careful with versions of perl that have UTF8
-support, since your string may end up doubly UTF8 encoded.
+You need to be be careful with versions of perl that have UTF-8
+support, since your string may end up doubly UTF-8 encoded.
For example:
$x = "A\xE2\x80\x90\x41\x{2010}";
substr($x, -1, 0) = "";
- # at this point $x is has the UTF8 flag set, but has 5 characters,
- # none, of which is the constructed UTF8 character
+ # at this point $x is has the UTF-8 flag set, but has 5 characters,
+ # none, of which is the constructed UTF-8 character
The test script t/t38ft2font.t has a small example of this after the
comment:
- # an attempt using emulation of UTF8
+ # an attempt using emulation of UTF-8
=head1 DRIVER CONTROL
@@ -959,9 +968,9 @@ You can set new priorities and save the old priorities with:
If you supply driver names that are not currently supported, they will
be ignored.
-Imager supports both T1Lib and Freetype2 for working with Type 1
+Imager supports both T1Lib and FreeType 2 for working with Type 1
fonts, but currently only T1Lib does any caching, so by default T1Lib
-is given a higher priority. Since Imager's Freetype2 support can also
+is given a higher priority. Since Imager's FreeType 2 support can also
do font transformations, you may want to give that a higher priority:
my @old = Imager::Font->priorities(qw(tt ft2 t1));
@@ -969,7 +978,7 @@ do font transformations, you may want to give that a higher priority:
=head1 AUTHOR
Arnar M. Hrafnkelsson, addi@umich.edu
-And a great deal of help from others - see the README for a complete
+And a great deal of help from others - see the F<README> for a complete
list.
=head1 BUGS
@@ -978,7 +987,7 @@ You need to modify this class to add new font types.
The $pos_width member returned by the bounding_box() method has
historically returned different values from different drivers. The
-Freetype 1.x and 2.x, and the Win32 drivers return the max of the
+FreeType 1.x and 2.x, and the Win32 drivers return the max of the
advance width and the right edge of the right-most glyph. The Type 1
driver always returns the right edge of the right-most glyph.
@@ -987,7 +996,7 @@ of the above.
=head1 REVISION
-$Revision: 1667 $
+$Revision: 1724 $
=head1 SEE ALSO
@@ -3,7 +3,7 @@ use strict;
use Imager::Color::Float;
use vars qw($VERSION);
-$VERSION = "1.006";
+$VERSION = "1.007";
=head1 NAME
@@ -127,75 +127,83 @@ Adds a new segment to the fountain fill, the possible options are:
=over
-=item start
+=item *
-The start position in the gradient where this segment
-takes effect between 0 and 1. Default: 0.
+C<start> - the start position in the gradient where this segment takes
+effect between 0 and 1. Default: 0.
-=item middle
+=item *
-The mid-point of the transition between the 2
-colors, between 0 and 1. Default: average of I<start> and I<end>.
+C<middle> - the mid-point of the transition between the 2
+colors, between 0 and 1. Default: average of C<start> and C<end>.
-=item end
+=item *
-The end of the gradient, from 0 to 1. Default: 1.
+C<end> - the end of the gradient, from 0 to 1. Default: 1.
-=item c0
+=item *
-The color of the fountain fill where the fill parameter is equal
-to I<start>. Default: opaque black.
+C<c0> - the color of the fountain fill where the fill parameter is
+equal to I<start>. Default: opaque black.
-=item c1
+=item *
-The color of the fountain fill where the fill parameter is equal to
-I<end>. Default: opaque black.
+C<c1> - the color of the fountain fill where the fill parameter is
+equal to I<end>. Default: opaque black.
-=item type
+=item *
-The type of segment, controls the way in which the fill parameter
+C<type> - the type of segment, controls the way in which the fill parameter
moves from 0 to 1. Default: linear.
This can take any of the following values:
=over
-=item linear
+=item *
-=item curved
+C<linear>
-Unimplemented so far.
+=item *
-=item sine
+C<curved> - unimplemented so far.
-=item sphereup
+=item *
-=item spheredown
+C<sine>
+
+=item *
+
+C<sphereup>
+
+=item *
+
+C<spheredown>
=back
-=item color
+=item *
-The way in which the color transitions between I<c0> and I<c1>.
+C<color> - the way in which the color transitions between C<c0> and C<c1>.
Default: direct.
This can take any of the following values:
=over
-=item direct
+=item *
-Each channel is simple scaled between c0 and c1.
+C<direct> - each channel is simple scaled between c0 and c1.
-=item hueup
+=item *
-The color is converted to a HSV value and the scaling is done such
-that the hue increases as the fill parameter increases.
+C<hueup> - the color is converted to a HSV value and the scaling is
+done such that the hue increases as the fill parameter increases.
-=item huedown
+=item *
-The color is converted to a HSV value and the scaling is done such
-that the hue decreases as the fill parameter increases.
+C<huedown> - the color is converted to a HSV value and the scaling is
+done such that the hue decreases as the fill parameter increases.
=back
@@ -253,8 +261,8 @@ sub add {
Creates a simple fountain fill object consisting of linear segments.
-The arrayrefs passed as positions and colors must have the same number
-of elements. They must have at least 2 elements each.
+The array references passed as positions and colors must have the same
+number of elements. They must have at least 2 elements each.
colors must contain Imager::Color or Imager::Color::Float objects.
@@ -393,7 +401,7 @@ through the following steps:
=item 1.
calculate the base value, which is typically a distance or an angle of
-some sort. This can be positive or occasinally negative, depending on
+some sort. This can be positive or occasionally negative, depending on
the type of fill being performed (linear, radial, etc).
=item 2.
@@ -15,27 +15,27 @@ number of functions that can shorter your code.
=over
-=item NC
+=item NC()
-=item newcolor
+=item newcolor()
-=item newcolour
+=item newcolour()
Create a new Imager::Color object, supplying any parameters to the
new() method.
my $color = NC('red');
-=item NF
+=item NF()
-=item newfont
+=item newfont()
Create a new Imager::Font object, supplying any parameters to the
new() method.
my $font = NF(file => 'foo.ttf');
-=item NCF
+=item NCF()
Create a new L<Imager::Color::Font> object, supplying any parameter to
the new() method.
@@ -0,0 +1,109 @@
+=head1 NAME
+
+Imager::IO - Imager's io_layer object.
+
+=head1 SYNOPSIS
+
+ # Imager supplies Imager::IO objects to various callbacks
+ my $IO = ...;
+
+ my $count = $IO->write($data);
+ my $count = $IO->read($buffer, $max_count);
+ my $position = $IO->seek($offset, $whence);
+ my $status = $IO->close;
+
+=head1 DESCRIPTION
+
+Imager uses an abstraction when dealing with image files to allow the
+same code to work with disk files, in memory data and callbacks.
+
+If you're writing an Imager file handler your code will be passed an
+Imager::IO object to write to or read from.
+
+=head1 METHODS
+
+=over
+
+=item write
+
+Call to write to the file. Returns the number of bytes written. The
+data provided may contain only characters \x00 to \xFF - characters
+outside this range will cause this method to croak().
+
+If you supply a UTF-8 flagged string it will be converted to a byte
+string, which may have a performance impact.
+
+Returns -1 on error, though in most cases if the result of the write
+isn't the number of bytes supplied you'll want to treat it as an error
+anyway.
+
+=item read
+
+ my $buffer;
+ my $count = $io->read($buffer, $max_bytes);
+
+Reads up to I<$max_bytes> bytes from the current position in the file
+and stores them in I<$buffer>. Returns the number of bytes read on
+success or an empty list on failure. Note that a read of zero bytes
+is B<not> a failure, this indicates end of file.
+
+=item read2
+
+ my $buffer = $io->read2($max_bytes);
+
+An alternative interface to read, that might be simpler to use in some
+cases.
+
+Returns the data read or an empty list.
+
+=item seek
+
+ my $new_position = $io->seek($offset, $whence);
+
+Seek to a new position in the file. Possible values for I<$whence> are:
+
+=over
+
+=item *
+
+C<SEEK_SET> - I<$offset> is the new position in the file.
+
+=item *
+
+C<SEEK_CUR> - I<$offset> is the offset from the current position in
+the file.
+
+=item *
+
+C<SEEK_END> - I<$offset> is the offset relative to the end of the
+file.
+
+=back
+
+Note that seeking past the end of the file may or may not result in an
+error.
+
+Returns the new position in the file, or -1 on error.
+
+=item close
+
+ my $result = $io->close;
+
+Call when you're with the file. If the IO object is connected to a
+file this won't close the file handle, but buffers may be flushed (if
+any).
+
+Returns 0 on success, -1 on failure.
+
+=back
+
+=head1 AUTHOR
+
+Tony Cook <tony@imager.perl.org>
+
+=head1 SEE ALSO
+
+Imager, Imager::Files
+
+=cut
+
@@ -98,11 +98,11 @@ stored. Imager treats these as follows:
=item *
-1 sample per color - grayscale image.
+1 sample per color - gray scale image.
=item *
-2 samples per color - grayscale image with alpha channel.
+2 samples per color - gray scale image with alpha channel.
=item *
@@ -128,7 +128,7 @@ The coordinate system in Imager has the origin in the upper left
corner, see L<Imager::Draw> for details.
The alpha channel when one is present is considered unassociated -
-ie. the color data has not been scaled by the alpha channel. Note
+ie the color data has not been scaled by the alpha channel. Note
that not all code follows this (recent) rule, but will over time.
=head2 Creating Imager Objects
@@ -217,7 +217,7 @@ Default: 256. This must be in the range 1 through 256.
=item *
-C<file>, C<fh>, C<fd>, C<callback>, C<readcb> - specify a filename,
+C<file>, C<fh>, C<fd>, C<callback>, C<readcb> - specify a file name,
filehandle, file descriptor or callback to read image data from. See
L<Imager::Files> for details. The typical use is:
@@ -251,7 +251,7 @@ To create paletted images, set the 'type' parameter to 'paletted':
$img = Imager->new(xsize=>200, ysize=>200, type=>'paletted');
-which creates an image with a maxiumum of 256 colors, which you can
+which creates an image with a maximum of 256 colors, which you can
change by supplying the C<maxcolors> parameter.
For improved color precision you can use the bits parameter to specify
@@ -284,7 +284,7 @@ parameter:
my $img = Imager->new(file => $filename)
or die Imager->errstr;
-=item img_set
+=item img_set()
img_set destroys the image data in the object and creates a new one
with the given dimensions and channels. For a way to convert image
@@ -302,30 +302,30 @@ These return basic attributes of an image object.
=over
-=item getwidth
+=item getwidth()
print "Image width: ", $img->getwidth(), "\n";
The C<getwidth()> method returns the width of the image. This value
-comes either from C<new()> with xsize,ysize parameters or from reading
-data from a file with C<read()>. If called on an image that has no
-valid data in it like C<Imager-E<gt>new()> returns, the return value
-of C<getwidth()> is undef.
+comes either from C<new()> with C<xsize>, C<ysize> parameters or from
+reading data from a file with C<read()>. If called on an image that
+has no valid data in it like C<Imager-E<gt>new()> returns, the return
+value of C<getwidth()> is undef.
-=item getheight
+=item getheight()
print "Image height: ", $img->getheight(), "\n";
Same details apply as for L<getwidth>.
-=item getchannels
+=item getchannels()
print "Image has ",$img->getchannels(), " channels\n";
To get the number of channels in an image C<getchannels()> is used.
-=item bits
+=item bits()
The bits() method retrieves the number of bits used to represent each
channel in a pixel, 8 for a normal image, 16 for 16-bit image and
@@ -338,9 +338,9 @@ channel in a pixel, 8 for a normal image, 16 for 16-bit image and
# slower but more precise
}
-=item type
+=item type()
-The type() method returns either 'direct' for truecolor images or
+The type() method returns either 'direct' for direct color images or
'paletted' for paletted images.
if ($img->type eq 'paletted') {
@@ -350,15 +350,17 @@ The type() method returns either 'direct' for truecolor images or
}
}
-=item virtual
+=item virtual()
The virtual() method returns non-zero if the image contains no actual
pixels, for example masked images.
+=for stopwords SDL
+
This may also be used for non-native Imager images in the future, for
example, for an Imager object that draws on an SDL surface.
-=item is_bilevel
+=item is_bilevel()
Tests if the image will be written as a monochrome or bi-level image
for formats that support that image organization.
@@ -403,7 +405,7 @@ image.
=over
-=item getmask
+=item getmask()
@rgbanames = qw( red green blue alpha );
my $mask = $img->getmask();
@@ -412,13 +414,15 @@ image.
print $rgbanames[$_],"\n" if $mask & 1<<$_;
}
+=for stopwords th
+
C<getmask()> is used to fetch the current channel mask. The mask
determines what channels are currently modifiable in the image. The
-channel mask is an integer value, if the i-th lsb is set the i-th
-channel is modifiable. eg. a channel mask of 0x5 means only channels
-0 and 2 are writable.
+channel mask is an integer value, if the C<i-th> least significant bit
+is set the C<i-th> channel is modifiable. eg. a channel mask of 0x5
+means only channels 0 and 2 are writable.
-=item setmask
+=item setmask()
$mask = $img->getmask();
$img->setmask(mask=>8); # modify alpha only
@@ -448,7 +452,7 @@ C<getcolors()> and C<findcolor()>:
=over
-=item addcolors
+=item addcolors()
You can add colors to a paletted image with the addcolors() method:
@@ -462,7 +466,7 @@ adding the colors would overflow the palette.
The only parameter is C<colors> which must be a reference to an array
of Imager::Color objects.
-=item setcolors
+=item setcolors()
$img->setcolors(start=>$start, colors=>\@colors);
@@ -483,7 +487,7 @@ colors - reference to an array of Imager::Color objects.
=back
-=item getcolors
+=item getcolors()
To retrieve existing colors from the palette use the getcolors() method:
@@ -494,7 +498,7 @@ To retrieve existing colors from the palette use the getcolors() method:
# get a range of colors
my @colors = $img->getcolors(start=>$index, count=>$count);
-=item findcolor
+=item findcolor()
To quickly find a color in the palette use findcolor():
@@ -512,13 +516,13 @@ color - an Imager::Color object.
=back
-=item colorcount
+=item colorcount()
Returns the number of colors in the image's palette:
my $count = $img->colorcount;
-=item maxcolors
+=item maxcolors()
Returns the maximum size of the image's palette.
@@ -530,13 +534,13 @@ Returns the maximum size of the image's palette.
=over
-=item getcolorcount
+=item getcolorcount()
Calculates the number of colors in an image.
The amount of memory used by this is proportional to the number of
colors present in the image, so to avoid using too much memory you can
-supply a maxcolors parameter to limit the memory used.
+supply a maxcolors() parameter to limit the memory used.
Note: getcolorcount() treats the image as an 8-bit per sample image.
@@ -544,7 +548,7 @@ Note: getcolorcount() treats the image as an 8-bit per sample image.
=item *
-X<maxcolors!getcolorcount>maxcolors - the maximum number of colors to
+X<maxcolors!getcolorcount>C<maxcolors> - the maximum number of colors to
return. Default: unlimited.
=back
@@ -553,7 +557,7 @@ return. Default: unlimited.
print "Less than 512 colors in image\n";
}
-=item getcolorusagehash
+=item getcolorusagehash()
Calculates a histogram of colors used by the image.
@@ -561,7 +565,7 @@ Calculates a histogram of colors used by the image.
=item *
-X<maxcolors!getcolorusagehash>maxcolors - the maximum number of colors
+X<maxcolors!getcolorusagehash>C<maxcolors> - the maximum number of colors
to return. Default: unlimited.
=back
@@ -569,14 +573,14 @@ to return. Default: unlimited.
Returns a reference to a hash where the keys are the raw color as
bytes, and the values are the counts for that color.
-The alpha channel of the image is ignored. If the image is grayscale
+The alpha channel of the image is ignored. If the image is gray scale
then the hash keys will each be a single character.
my $colors = $img->getcolorusagehash;
my $blue_count = $colors->{pack("CCC", 0, 0, 255)} || 0;
print "#0000FF used $blue_count times\n";
-=item getcolorusage
+=item getcolorusage()
Calculates color usage counts and returns just the counts.
@@ -584,8 +588,8 @@ Calculates color usage counts and returns just the counts.
=item *
-X<maxcolors!getcolorusage>maxcolors - the maximum number of colors to
-return. Default: unlimited.
+X<maxcolors!getcolorusage>C<maxcolors> - the maximum number of colors
+to return. Default: unlimited.
=back
@@ -621,7 +625,7 @@ where %opts contains the options specified under L<Quantization options>.
my $optimag = $img->to_paletted({ make_colors => 'mediancut',
translate => 'errdiff' });
-=item to_rgb8
+=item to_rgb8()
You can convert a paletted image (or any image) to an 8-bit/channel
RGB image with:
@@ -630,7 +634,7 @@ RGB image with:
No parameters.
-=item to_rgb16
+=item to_rgb16()
You can convert a paletted image (or any image) to an 16-bit/channel
RGB image with:
@@ -674,7 +678,7 @@ Parameters:
mask - the mask image. If not supplied then all pixels in the target
image are writable. On each write to the masked image, only pixels
-that have non-zero in chennel 0 of the mask image will be written to
+that have non-zero in channel 0 of the mask image will be written to
the original image. Default: none, if not supplied then no masking is
done, but the other parameters are still honored.
@@ -705,7 +709,7 @@ For example, given a base image called $img:
# now draw on $maskedimg and it will only draw on areas of $img
# where $mask is non-zero in channel 0.
-You can specifiy the region of the underlying image that is masked
+You can specify the region of the underlying image that is masked
using the left, top, right and bottom options.
If you just want a subset of the image, without masking, just specify
@@ -733,7 +737,7 @@ the code or name of the tag followed by the value of the tag.
=over
-=item tags
+=item tags()
Retrieve tags from the image.
@@ -763,7 +767,7 @@ or a given code:
my @tags = $img->tags(code=>$code);
-=item addtag
+=item addtag()
You can add tags using the addtag() method, either by name:
@@ -773,7 +777,7 @@ or by code:
my $index = $img->addtag(code=>$code, value=>$value);
-=item deltag
+=item deltag()
You can remove tags with the deltag() method, either by index:
@@ -789,7 +793,7 @@ or by code:
In each case deltag() returns the number of tags deleted.
-=item settag
+=item settag()
settag() replaces any existing tags with a new tag. This is
equivalent to calling deltag() then addtag().
@@ -811,7 +815,7 @@ some standard information.
=item *
-X<i_xres tag>X<i_yres tag>X<tags, i_xres>X<tags, i_yres>i_xres, i_yres
+X<i_xres tag>X<i_yres tag>X<tags, i_xres>X<tags, i_yres>C<i_xres>, C<i_yres>
- The spatial resolution of the image in pixels per inch. If the
image format uses a different scale, eg. pixels per meter, then this
value is converted. A floating point number stored as a string.
@@ -828,22 +832,22 @@ value is converted. A floating point number stored as a string.
=item *
-X<i_aspect_only tag>X<tags, i_aspect_only>i_aspect_only - If this is
+X<i_aspect_only tag>X<tags, i_aspect_only>C<i_aspect_only> - If this is
non-zero then the values in i_xres and i_yres are treated as a ratio
only. If the image format does not support aspect ratios then this is
-scaled so the smaller value is 72dpi.
+scaled so the smaller value is 72 DPI.
=item *
-X<i_incomplete tag>X<tags, i_incomplete>i_incomplete - If this tag is
+X<i_incomplete tag>X<tags, i_incomplete>C<i_incomplete> - If this tag is
present then the whole image could not be read. This isn't
implemented for all images yet, and may not be.
=item *
-X<i_lines_read tag>X<tags, i_lines_read>i_lines_read - If
+X<i_lines_read tag>X<tags, i_lines_read>C<i_lines_read> - If
C<i_incomplete> is set then this tag may be set to the number of
-scanlines successfully read from the file. This can be used to decide
+scan lines successfully read from the file. This can be used to decide
whether an image is worth processing.
=item *
@@ -865,240 +869,235 @@ C<color(>I<red>C<,>I<green>C<,>I<blue>C<)>, eg color(255,0,0).
=head2 Quantization options
These options can be specified when calling
-L<Imager::ImageTypes/to_paletted>, write_multi() for gif files, when
-writing a single image with the gifquant option set to 'gen', or for
-direct calls to i_writegif_gen and i_writegif_callback.
+L<Imager::ImageTypes/to_paletted>, write_multi() for GIF files, when
+writing a single image with the C<gifquant> option set to C<gen>, or for
+direct calls to i_writegif_gen() and i_writegif_callback().
=over
-=item colors
+=item *
-A arrayref of colors that are fixed. Note that some color generators
-will ignore this. If this is supplied it will be filled with the
-color table generated for the image.
+C<colors> - An arrayref of colors that are fixed. Note that some
+color generators will ignore this. If this is supplied it will be
+filled with the color table generated for the image.
-=item transp
+=item *
-The type of transparency processing to perform for images with an
-alpha channel where the output format does not have a proper alpha
-channel (eg. gif). This can be any of:
+C<transp> - The type of transparency processing to perform for images
+with an alpha channel where the output format does not have a proper
+alpha channel (eg. GIF). This can be any of:
=over
-=item none
+=item *
-No transparency processing is done. (default)
+C<none> - No transparency processing is done. (default)
-=item threshold
+=item *
-Pixels more transparent that tr_threshold are rendered as transparent.
+C<threshold> - pixels more transparent than C<tr_threshold> are
+rendered as transparent.
-=item errdiff
+=item *
-An error diffusion dither is done on the alpha channel. Note that
-this is independent of the translation performed on the colour
-channels, so some combinations may cause undesired artifacts.
+C<errdiff> - An error diffusion dither is done on the alpha channel.
+Note that this is independent of the translation performed on the
+color channels, so some combinations may cause undesired artifacts.
-=item ordered
+=item *
-The ordered dither specified by tr_orddith is performed on the alpha
-channel.
+C<ordered> - the ordered dither specified by tr_orddith is performed
+on the alpha channel.
=back
This will only be used if the image has an alpha channel, and if there
-is space in the palette for a transparency colour.
+is space in the palette for a transparency color.
-=item tr_threshold
+=item *
-The highest alpha value at which a pixel will be made transparent when
-transp is 'threshold'. (0-255, default 127)
+C<tr_threshold> - the highest alpha value at which a pixel will be
+made transparent when C<transp> is 'threshold'. (0-255, default 127)
-=item tr_errdiff
+=item *
-The type of error diffusion to perform on the alpha channel when
-transp is 'errdiff'. This can be any defined error diffusion type
-except for custom (see errdiff below).
+C<tr_errdiff> - The type of error diffusion to perform on the alpha
+channel when C<transp> is C<errdiff>. This can be any defined error
+diffusion type except for custom (see C<errdiff> below).
-=item tr_orddith
+=item *
-The type of ordered dither to perform on the alpha channel when transp
-is 'ordered'. Possible values are:
+C<tr_orddith> - The type of ordered dither to perform on the alpha
+channel when C<transp> is 'ordered'. Possible values are:
=over
-=item random
-
-A semi-random map is used. The map is the same each time.
-
-=item dot8
+=item *
-8x8 dot dither.
+C<random> - A semi-random map is used. The map is the same each time.
-=item dot4
+=item *
-4x4 dot dither
+C<dot8> - 8x8 dot dither.
-=item hline
+=item *
-horizontal line dither.
+C<dot4> - 4x4 dot dither
-=item vline
+=item *
-vertical line dither.
+C<hline> - horizontal line dither.
-=item "/line"
+=item *
-=item slashline
+C<vline> - vertical line dither.
-diagonal line dither
+=item *
-=item '\line'
+C</line>, C<slashline> - diagonal line dither
-=item backline
+=item *
-diagonal line dither
+C<\line>, C<backline> - diagonal line dither
-=item tiny
+=item *
-dot matrix dither (currently the default). This is probably the best
-for displays (like web pages).
+C<tiny> - dot matrix dither (currently the default). This is probably
+the best for displays (like web pages).
-=item custom
+=item *
-A custom dither matrix is used - see tr_map
+C<custom> - A custom dither matrix is used - see C<tr_map>.
=back
-=item tr_map
+=item *
-When tr_orddith is custom this defines an 8 x 8 matrix of integers
-representing the transparency threshold for pixels corresponding to
-each position. This should be a 64 element array where the first 8
-entries correspond to the first row of the matrix. Values should be
-betweern 0 and 255.
+C<tr_map> - When tr_orddith is custom this defines an 8 x 8 matrix of
+integers representing the transparency threshold for pixels
+corresponding to each position. This should be a 64 element array
+where the first 8 entries correspond to the first row of the matrix.
+Values should be between 0 and 255.
-=item make_colors
+=item *
-Defines how the quantization engine will build the palette(s).
-Currently this is ignored if 'translate' is 'giflib', but that may
-change. Possible values are:
+C<make_colors> - Defines how the quantization engine will build the
+palette(s). Currently this is ignored if C<translate> is C<giflib>,
+but that may change. Possible values are:
=over
=item *
-none - only colors supplied in 'colors' are used.
+C<none> - only colors supplied in 'colors' are used.
=item *
-webmap - the web color map is used (need url here.)
+C<webmap> - the web color map is used (need URL here.)
=item *
-addi - The original code for generating the color map (Addi's code) is
+C<addi> - The original code for generating the color map (Addi's code) is
used.
=item *
-mediancut - Uses a mediancut algorithm, faster than 'addi', but not as good a
-result.
+C<mediancut> - Uses a median-cut algorithm, faster than C<addi>, but not
+as good a result.
=item *
-mono, monochrome - a fixed black and white palette, suitable for
+C<mono>, C<monochrome> - a fixed black and white palette, suitable for
producing bi-level images (eg. facsimile)
=back
Other methods may be added in the future.
-=item colors
+=item *
-A arrayref containing Imager::Color objects, which represents the
-starting set of colors to use in translating the images. webmap will
-ignore this. On return the final colors used are copied back into
-this array (which is expanded if necessary.)
+C<colors> - an arrayref containing Imager::Color objects, which
+represents the starting set of colors to use in translating the
+images. C<webmap> will ignore this. On return the final colors used
+are copied back into this array (which is expanded if necessary.)
-=item max_colors
+=item *
-The maximum number of colors to use in the image.
+C<max_colors> - the maximum number of colors to use in the image.
-=item translate
+=item *
-The method used to translate the RGB values in the source image into
-the colors selected by make_colors. Note that make_colors is ignored
-whene translate is 'giflib'.
+C<translate> - The method used to translate the RGB values in the
+source image into the colors selected by make_colors. Note that
+make_colors is ignored when C<translate> is C<giflib>.
Possible values are:
=over
-=item giflib
+=item *
-The giflib native quantization function is used.
+C<giflib> - the C<giflib> native quantization function is used.
-=item closest
+=item *
-The closest color available is used.
+C<closest> - the closest color available is used.
-=item perturb
+=item *
-The pixel color is modified by perturb, and the closest color is chosen.
+C<perturb> - the pixel color is modified by C<perturb>, and the
+closest color is chosen.
-=item errdiff
+=item *
-An error diffusion dither is performed.
+C<errdiff> - an error diffusion dither is performed.
=back
-It's possible other transate values will be added.
+It's possible other C<translate> values will be added.
-=item errdiff
+=item *
+
+C<errdiff> - The type of error diffusion dither to perform. These
+values (except for custom) can also be used in tr_errdif.
-The type of error diffusion dither to perform. These values (except
-for custom) can also be used in tr_errdif.
+=for stopwords Floyd-Steinberg Jarvis Judice Ninke Stucki
=over
-=item floyd
+=item *
-Floyd-Steinberg dither
+C<floyd> - Floyd-Steinberg dither
-=item jarvis
+=item *
-Jarvis, Judice and Ninke dither
+C<jarvis> - Jarvis, Judice and Ninke dither
-=item stucki
+=item *
-Stucki dither
+C<stucki> - Stucki dither
-=item custom
+=item *
-Custom. If you use this you must also set errdiff_width,
-errdiff_height and errdiff_map.
+C<custom> - custom. If you use this you must also set C<errdiff_width>,
+C<errdiff_height> and C<errdiff_map>.
=back
-=item errdiff_width
-
-=item errdiff_height
-
-=item errdiff_orig
-
-=item errdiff_map
+=item *
-When translate is 'errdiff' and errdiff is 'custom' these define a
-custom error diffusion map. errdiff_width and errdiff_height define
-the size of the map in the arrayref in errdiff_map. errdiff_orig is
-an integer which indicates the current pixel position in the top row
-of the map.
+C<errdiff_width>, C<errdiff_height>, C<errdiff_orig>, C<errdiff_map> -
+When C<translate> is C<errdiff> and C<errdiff> is C<custom> these
+define a custom error diffusion map. C<errdiff_width> and
+C<errdiff_height> define the size of the map in the arrayref in
+C<errdiff_map>. C<errdiff_orig> is an integer which indicates the
+current pixel position in the top row of the map.
-=item perturb
+=item *
-When translate is 'perturb' this is the magnitude of the random bias
-applied to each channel of the pixel before it is looked up in the
-color table.
+C<perturb> - When translate is C<perturb> this is the magnitude of the
+random bias applied to each channel of the pixel before it is looked
+up in the color table.
=back
@@ -1109,7 +1108,7 @@ almost never need to call.
=over
-=item init
+=item init()
This is a function, not a method.
@@ -1119,23 +1118,23 @@ This function is a mess, it can take the following named parameters:
=item *
-log - name of a log file to log Imager's actions to. Not all actions
+C<log> - name of a log file to log Imager's actions to. Not all actions
are logged, but the debugging memory allocator does log allocations
here. Ignored if Imager has been built without logging support.
=item *
-loglevel - the maximum level of message to log. Default: 1.
+C<loglevel> - the maximum level of message to log. Default: 1.
=item *
-warn_obsolete - if this is non-zero then Imager will warn when you
+C<warn_obsolete> - if this is non-zero then Imager will warn when you
attempt to use obsoleted parameters or functionality. This currently
-only includes the old gif output options instead of tags.
+only includes the old GIF output options instead of tags.
=item *
-t1log - if non-zero then T1lib will be configured to produce a log
+C<t1log> - if non-zero then T1lib will be configured to produce a log
file. This will fail if there are any existing T1lib font objects.
=back
@@ -1148,7 +1147,7 @@ Example:
=head1 REVISION
-$Revision: 1626 $
+$Revision: 1724 $
=head1 AUTHORS
@@ -19,11 +19,13 @@ Imager::Inline - using Imager with Inline::C.
=head1 DESCRIPTION
+=for stopwords inline Inline Inline's
+
Imager hooks into Inline's C<with> syntax to make it easier to write
Inline::C code that works with Imager, you can call Imager functions
without having to include headers or perform initialization.
-Imager's inline C<with> support does the following:
+Imager's Inline C<with> support does the following:
=over
@@ -2,7 +2,7 @@ package Imager::Matrix2d;
use strict;
use vars qw($VERSION);
-$VERSION = "1.008";
+$VERSION = "1.009";
=head1 NAME
@@ -207,7 +207,7 @@ sub reflect {
Scales at the given ratios.
-You can also specify a center for the scaling with the cx and cy
+You can also specify a center for the scaling with the C<cx> and C<cy>
parameters.
=cut
@@ -398,7 +398,7 @@ Tony Cook <tony@develop-help.com>
=head1 BUGS
-Needs a way to invert matrixes.
+Needs a way to invert a matrix.
=head1 SEE ALSO
@@ -1,11 +1,13 @@
package Imager::Preprocess;
use strict;
require Exporter;
-use vars qw(@ISA @EXPORT);
+use vars qw(@ISA @EXPORT $VERSION);
@EXPORT = qw(preprocess);
@ISA = qw(Exporter);
+$VERSION = "1.000";
+
sub preprocess {
my $src = shift @ARGV;
@@ -167,6 +169,8 @@ __END__
=head1 NAME
+=for stopwords preprocessor
+
Imager::Preprocess - simple preprocessor for handling multiple sample sizes
=head1 SYNOPSIS
@@ -184,8 +188,8 @@ This is a simple preprocessor that aims to reduce duplication of
source code when implementing an algorithm both for 8-bit samples and
double samples in Imager.
-Imager's Makefile.PL currently scans the MANIFEST for .im files and
-adds Makefile files to convert these to .c files.
+Imager's C<Makefile.PL> currently scans the F<MANIFEST> for F<.im>
+files and adds Makefile files to convert these to F<.c> files.
The beginning of a sample-independent section of code is preceded by:
@@ -213,41 +217,41 @@ The following types and values are defined in a #code section:
=item *
-IM_GPIX(im, x, y, &col)
+IM_GPIX(C<im>, C<x>, C<y>, C<&col>)
=item *
-IM_GLIN(im, l, r, y, colors)
+IM_GLIN(C<im>, C<l>, C<r>, C<y>, C<colors>)
=item *
-IM_PPIX(im, x, y, &col)
+IM_PPIX(C<im>, C<x>, C<y>, C<&col>)
=item *
-IM_PLIN(im, x, y, colors)
+IM_PLIN(C<im>, C<x>, C<y>, C<colors>)
=item *
-IM_GSAMP(im, l, r, y, samples, chans, chan_count)
+IM_GSAMP(C<im>, C<l>, C<r>, C<y>, C<samples>, C<chans>, C<chan_count>)
These correspond to the appropriate image function, eg. IM_GPIX()
becomes i_gpix() or i_gpixf() as appropriate.
=item *
-IM_ADAPT_COLORS(dest_channes, src_channels, colors, count)
+IM_ADAPT_COLORS(C<dest_channels>, C<src_channels>, C<colors>, C<count>)
Call i_adapt_colors() or i_adapt_fcolors().
=item *
-IM_FILL_COMBINE(fill) - retrieve the combine function from a fill
+IM_FILL_COMBINE(C<fill>) - retrieve the combine function from a fill
object.
=item *
-IM_FILL_FILLER(fill) - retrieve the fill_with_* function from a fill
+IM_FILL_FILLER(C<fill>) - retrieve the fill_with_* function from a fill
object.
=item *
@@ -497,7 +497,7 @@ __END__
=head1 NAME
-Imager::Regops - generated information about the register based VM
+Imager::Regops - generated information about the register based virtual machine
=head1 SYNOPSIS
@@ -511,7 +511,7 @@ Imager::Regops - generated information about the register based VM
=head1 DESCRIPTION
-This module is generated automatically from regmach.h so we don't need to
+This module is generated automatically from F<regmach.h> so we don't need to
maintain the same information in at least one extra place.
At least that's the idea.
@@ -2,7 +2,10 @@ package Imager::Test;
use strict;
use Test::Builder;
require Exporter;
-use vars qw(@ISA @EXPORT_OK);
+use vars qw(@ISA @EXPORT_OK $VERSION);
+
+$VERSION = "1.000";
+
@ISA = qw(Exporter);
@EXPORT_OK =
qw(
@@ -604,6 +607,8 @@ No functions are exported by default.
=head1 FUNCTIONS
+=for stopwords OO
+
=over
=item is_color3($color, $red, $blue, $green, $comment)
@@ -651,8 +656,8 @@ Returns a 150x150x3 double/sample OO test image.
=item diff_text_with_nul($test_name, $text1, $text2, @options)
Creates 2 test images and writes $text1 to the first image and $text2
-to the second image with the string() method. Each call adds 3 ok/not
-ok to the output of the test script.
+to the second image with the string() method. Each call adds 3
+C<ok>/C<not ok> to the output of the test script.
Extra options that should be supplied include the font and either a
color or channel parameter.
@@ -4,7 +4,7 @@ use Imager;
use Imager::Expr::Assem;
use vars qw($VERSION);
-$VERSION = "1.004";
+$VERSION = "1.005";
my %funcs =
(
@@ -497,12 +497,12 @@ transformation.
Returns a list of input image descriptions, or the number of them,
depending on content.
-The list contains hashrefs, which current contain only one member,
-desc, a description of the use of the input image.
+The list contains hash references, which current contain only one
+member, C<desc>, a description of the use of the input image.
=item $tran->constants
-Return's a list of names of constants that can be set for the
+Returns a list of names of constants that can be set for the
transformation.
=item $tran->constants($name, $name, ...)
@@ -529,6 +529,6 @@ Needs more transformations.
=head1 SEE ALSO
-Imager(3), transform.perl
+Imager(3), F<transform.perl>
=cut
@@ -77,19 +77,19 @@ A list of the transformations that do not alter the source image follows:
=item copy
-To create a copy of an image use the C<copy()> method. This is usefull
+To create a copy of an image use the C<copy()> method. This is useful
if you want to keep an original after doing something that changes the image.
$newimg = $orig->copy();
=item scale
-X<scale>To scale an image so porportions are maintained use the
-C<$img-E<gt>scale()> method. if you give either a xpixels or ypixels
-parameter they will determine the width or height respectively. If
-both are given the one resulting in a larger image is used, unless you
-set the C<type> parameter to C<'min'>. example: C<$img> is 700 pixels
-wide and 500 pixels tall.
+X<scale>To scale an image so proportions are maintained use the
+C<$img-E<gt>scale()> method. if you give either a C<xpixels> or
+C<ypixels> parameter they will determine the width or height
+respectively. If both are given the one resulting in a larger image
+is used, unless you set the C<type> parameter to C<'min'>. example:
+C<$img> is 700 pixels wide and 500 pixels tall.
$newimg = $img->scale(xpixels=>400); # 400x285
$newimg = $img->scale(ypixels=>400); # 560x400
@@ -113,45 +113,46 @@ the original.
=item *
-xpixels, ypixels - desired size of the scaled image. The C<type>
-parameter controls whether the larger or smaller of the two possible
-sizes is chosen, or if the image is scaled non-proportionally.
+C<xpixels>, C<ypixels> - desired size of the scaled image. The
+C<type> parameter controls whether the larger or smaller of the two
+possible sizes is chosen, or if the image is scaled
+non-proportionally.
=item *
-constrain - an Image::Math::Constrain object defining the way in which
-the image size should be constrained.
+C<constrain> - an Image::Math::Constrain object defining the way in
+which the image size should be constrained.
=item *
-scalefactor - if none of xpixels, ypixels, xscalefactor, yscalefactor
-or constrain is supplied then this is used as the ratio to scale by.
-Default: 0.5.
+C<scalefactor> - if none of C<xpixels>, C<ypixels>, C<xscalefactor>,
+C<yscalefactor> or C<constrain> is supplied then this is used as the
+ratio to scale by. Default: 0.5.
=item *
-xscalefactor, yscalefactor - if both are supplied then the image is
+C<xscalefactor>, C<yscalefactor> - if both are supplied then the image is
scaled as per these parameters, whether this is proportionally or not.
New in Imager 0.54.
=item *
-type - controls whether the larger or smaller of the two possible
+C<type> - controls whether the larger or smaller of the two possible
sizes is chosen, possible values are:
=over
=item *
-min - the smaller of the 2 sizes are chosen.
+C<min> - the smaller of the 2 sizes are chosen.
=item *
-max - the larger of the 2 sizes. This is the default.
+C<max> - the larger of the 2 sizes. This is the default.
=item *
-nonprop - non-proportional scaling. New in Imager 0.54.
+C<nonprop> - non-proportional scaling. New in Imager 0.54.
=back
@@ -166,7 +167,7 @@ C<type> is only used if both C<xpixels> and C<ypixels> are supplied.
=item *
-qtype - defines the quality of scaling performed. Possible values are:
+C<qtype> - defines the quality of scaling performed. Possible values are:
=over
@@ -182,12 +183,12 @@ up this will duplicate pixels.
=item *
-C<mixing> - implements the mixing algorithm implemented by pnmscale.
-This retains more detail when scaling down than C<normal>. When
-scaling down this proportionally accumulates sample data from the
-pixels, resulting in a proportional mix of all of the pixels. When
-scaling up this will mix pixels when the sampling grid crosses a pixel
-boundary but will otherwise copy pixel values.
+C<mixing> - implements the mixing algorithm implemented by
+F<pnmscale>. This retains more detail when scaling down than
+C<normal>. When scaling down this proportionally accumulates sample
+data from the pixels, resulting in a proportional mix of all of the
+pixels. When scaling up this will mix pixels when the sampling grid
+crosses a pixel boundary but will otherwise copy pixel values.
=back
@@ -204,12 +205,12 @@ dimensions. eg.
my $scaled = $img->scaleX(pixels=>400)->scaleY(pixels=>200);
From Imager 0.54 you can scale without maintaining proportions either
-by supplying both the xscalefactor and yscalefactor arguments:
+by supplying both the C<xscalefactor> and C<yscalefactor> arguments:
my $scaled = $img->scale(xscalefactor => 0.5, yscalefactor => 0.67);
or by supplying C<xpixels> and C<ypixels> and setting C<type> to
-"nonprop":
+<nonprop>:
my $scaled = $im->scale(xpixels => 200, ypixels => 200, type => 'nonprop');
@@ -261,7 +262,7 @@ A mandatory warning is produced if scale() is called in void context.
# same as Image::Math::Constrain version
my $scaled2 = $image->scale(xpixels => 800, ypixels => 600, type => 'min');
-=item scaleX
+=item scaleX()
scaleX() will scale along the X dimension, return a new image with the
new width:
@@ -273,12 +274,12 @@ new width:
=item *
-scalefactor - the amount to scale the X axis. Ignored if C<pixels> is
+C<scalefactor> - the amount to scale the X axis. Ignored if C<pixels> is
provided. Default: 0.5.
=item *
-pixels - the new width of the image.
+C<pixels> - the new width of the image.
=back
@@ -290,7 +291,7 @@ failure.
A mandatory warning is produced if scaleX() is called in void context.
-=item scaleY
+=item scaleY()
scaleY() will scale along the Y dimension, return a new image with the
new height:
@@ -302,12 +303,12 @@ new height:
=item *
-scalefactor - the amount to scale the Y axis. Ignored if C<pixels> is
+C<scalefactor> - the amount to scale the Y axis. Ignored if C<pixels> is
provided. Default: 0.5.
=item *
-pixels - the new height of the image.
+C<pixels> - the new height of the image.
=back
@@ -319,7 +320,7 @@ failure.
A mandatory warning is produced if scaleY() is called in void context.
-=item scale_calculate
+=item scale_calculate()
Performs the same calculations that the scale() method does to
calculate the scaling factors from the parameters you pass.
@@ -333,7 +334,7 @@ Takes the following parameters over scale():
=item *
-width, height - the image width and height to base the scaling on.
+C<width>, C<height> - the image width and height to base the scaling on.
Required if scale_calculate() is called as a class method. If called
as an object method these default to the image width and height
respectively.
@@ -341,7 +342,7 @@ respectively.
=back
You might use scale_calculate() as a class method when generating an
-IMG tag, for example.
+HTML C<IMG> tag, for example.
Returns an empty list on failure.
@@ -355,7 +356,9 @@ factor, new width, new height, on success.
my ($x_scale, $y_scale, $new_width, $new_height) =
$img->scale_calculate(xpixels => 200, type => 'min');
-=item crop
+=item crop()
+
+=for stopwords resize
Another way to resize an image is to crop it. The parameters to
crop are the edges of the area that you want in the returned image,
@@ -439,7 +442,7 @@ returns false and $img->errstr is an appropriate error message.
A mandatory warning is produced if crop() is called in void context.
-=item rotate
+=item rotate()
Use the rotate() method to rotate an image. This method will return a
new, rotated image.
@@ -473,20 +476,20 @@ Parameters:
=item *
-right - rotate by an exact multiple of 90 degrees, specified in
-degreess.
+C<right> - rotate by an exact multiple of 90 degrees, specified in
+degrees.
=item *
-radians - rotate by an angle specified in radians.
+C<radians> - rotate by an angle specified in radians.
=item *
-degrees - rotate by an angle specified in degrees.
+C<degrees> - rotate by an angle specified in degrees.
=item *
-back - for C<radians> and C<degrees> this is the color used for the
+C<back> - for C<radians> and C<degrees> this is the color used for the
areas not covered by the original image. For example, the corners of
an image rotated by 45 degrees.
@@ -533,28 +536,28 @@ Parameters:
=item *
-src, img - the source image. I<src> added for compatibility with
+C<src>, C<img> - the source image. C<src> added for compatibility with
rubthrough().
=item *
-left, top - position in output of the top left of the pasted image.
+C<left>, C<top> - position in output of the top left of the pasted image.
Default: (0,0)
=item *
-src_minx, src_miny - the top left corner in the source image to start
+C<src_minx>, C<src_miny> - the top left corner in the source image to start
the paste from. Default: (0, 0)
=item *
-src_maxx, src_maxy - the bottom right in the source image of the sub
+C<src_maxx>, C<src_maxy> - the bottom right in the source image of the sub
image to paste. This position is B<non> inclusive. Default: bottom
right corner of the source image.
=item *
-width, height - if the corresponding src_maxx or src_maxy is not
+C<width>, C<height> - if the corresponding src_maxx or src_maxy is not
defined then width or height is used for the width or height of the
sub image to be pasted.
@@ -569,14 +572,14 @@ sub image to be pasted.
If the source image has an alpha channel and the target doesn't, then
the source is treated as if composed onto a black background.
-If the source image is color and the target is grayscale, the the
+If the source image is color and the target is gray scale, the the
source is treated as if run through C<< convert(preset=>'gray') >>.
-=item rubthrough
+=item rubthrough()
A more complicated way of blending images is where one image is
put 'over' the other with a certain amount of opaqueness. The
-method that does this is rubthrough.
+method that does this is rubthrough().
$img->rubthrough(src=>$overlay,
tx=>30, ty=>50,
@@ -596,17 +599,17 @@ Parameters:
=item *
-tx, ty - location in the the target image ($self) to render the top
-left corner of the source.
+C<tx>, C<ty> - location in the the target image ($self) to render the
+top left corner of the source.
=item *
-src_minx, src_miny - the top left corner in the source to transfer to
+C<src_minx>, C<src_miny> - the top left corner in the source to transfer to
the target image. Default: (0, 0).
=item *
-src_maxx, src_maxy - the bottom right in the source image of the sub
+C<src_maxx>, C<src_maxy> - the bottom right in the source image of the sub
image to overlay. This position is B<non> inclusive. Default: bottom
right corner of the source image.
@@ -625,11 +628,11 @@ right corner of the source image.
src_miny => $src->getheight() - 20);
rubthrough() returns true on success. On failure check
-$target->errstr for the reason for failure.
+C<< $target->errstr >> for the reason for failure.
-=item compose
+=item compose()
-Draws the source image over the target image, with the src alpha
+Draws the source image over the target image, with the source alpha
channel modified by the optional mask and the opacity.
$img->compose(src=>$overlay,
@@ -650,32 +653,32 @@ Parameters:
=item *
-src - the source image to draw onto the target. Required.
+C<src> - the source image to draw onto the target. Required.
=item *
-tx, ty - location in the the target image ($self) to render the top
+C<tx>, C<ty> - location in the the target image ($self) to render the top
left corner of the source. These can also be supplied as C<left> and
C<right>. Default: (0, 0).
=item *
-src_minx, src_miny - the top left corner in the source to transfer to
+C<src_minx>, C<src_miny> - the top left corner in the source to transfer to
the target image. Default: (0, 0).
=item *
-src_maxx, src_maxy - the bottom right in the source image of the sub
+C<src_maxx>, C<src_maxy> - the bottom right in the source image of the sub
image to overlay. This position is B<non> inclusive. Default: bottom
right corner of the source image.
=item *
-mask - a mask image. The first channel of this image is used to
-modify the alpha channel of the source image. This can me used to
+C<mask> - a mask image. The first channel of this image is used to
+modify the alpha channel of the source image. This can be used to
mask out portions of the source image. Where the first channel is
zero none of the source image will be used, where the first channel is
-max the full alpha of the source image will be used, as further
+maximum the full alpha of the source image will be used, as further
modified by the opacity.
=item *
@@ -743,11 +746,11 @@ The convert method can be used to:
=item *
-convert an RGB or RGBA image to grayscale.
+convert an RGB or RGBA image to gray scale.
=item *
-convert a grayscale image to RGB.
+convert a gray scale image to RGB.
=item *
@@ -763,68 +766,67 @@ The currently defined presets are:
=over
-=item gray
-
-=item grey
+=item *
-converts an RGBA image into a grayscale image with alpha channel, or
-an RGB image into a grayscale image without an alpha channel.
+C<gray>, C<grey> - converts an RGBA image into a gray scale image with
+alpha channel, or an RGB image into a gray scale image without an
+alpha channel.
This weights the RGB channels at 22.2%, 70.7% and 7.1% respectively.
-=item noalpha
-
-removes the alpha channel from a 2 or 4 channel image. An identity
-for other images.
-
-=item red
-
-=item channel0
+=item *
-extracts the first channel of the image into a single channel image
+C<noalpha> - removes the alpha channel from a 2 or 4 channel image.
+An identity for other images.
-=item green
+=item *
-=item channel1
+C<red>, C<channel0> - extracts the first channel of the image into a
+single channel image
-extracts the second channel of the image into a single channel image
+=item *
-=item blue
+C<green>, C<channel1> - extracts the second channel of the image into
+a single channel image
-=item channel2
+=item *
-extracts the third channel of the image into a single channel image
+C<blue>, C<channel2> - extracts the third channel of the image into a
+single channel image
-=item alpha
+=item *
-extracts the alpha channel of the image into a single channel image.
+C<alpha> - extracts the alpha channel of the image into a single
+channel image.
-If the image has 1 or 3 channels (assumed to be grayscale of RGB) then
+If the image has 1 or 3 channels (assumed to be gray scale or RGB) then
the resulting image will be all white.
-=item rgb
+=item *
+
+C<rgb>
-converts a grayscale image to RGB, preserving the alpha channel if any
+converts a gray scale image to RGB, preserving the alpha channel if any
-=item addalpha
+=item *
-adds an alpha channel to a grayscale or RGB image. Preserves an
-existing alpha channel for a 2 or 4 channel image.
+C<addalpha> - adds an alpha channel to a gray scale or RGB image.
+Preserves an existing alpha channel for a 2 or 4 channel image.
=back
-For example, to convert an RGB image into a greyscale image:
+For example, to convert an RGB image into a gray scale image:
$new = $img->convert(preset=>'grey'); # or gray
-or to convert a grayscale image to an RGB image:
+or to convert a gray scale image to an RGB image:
$new = $img->convert(preset=>'rgb');
The presets aren't necessary simple constants in the code, some are
generated based on the number of channels in the input image.
-If you want to perform some other colour transformation, you can use
+If you want to perform some other color transformation, you can use
the 'matrix' parameter.
For each output pixel the following matrix multiplication is done:
@@ -841,12 +843,12 @@ So if you want to swap the red and green channels on a 3 channel image:
[ 1, 0, 0 ],
[ 0, 0, 1 ] ]);
-or to convert a 3 channel image to greyscale using equal weightings:
+or to convert a 3 channel image to gray scale using equal weightings:
$new = $img->convert(matrix=>[ [ 0.333, 0.333, 0.334 ] ])
-Convert a 2 channel image (grayscale with alpha) to an RGBA image with
-the grey converted to the specified RGB color:
+Convert a 2 channel image (gray scale with alpha) to an RGBA image with
+the gray converted to the specified RGB color:
# set (RGB) scaled on the grey scale portion and copy the alpha
# channel as is
@@ -874,11 +876,11 @@ alpha channel:
=item map
You can use the map method to map the values of each channel of an
-image independently using a list of lookup tables. It's important to
+image independently using a list of look-up tables. It's important to
realize that the modification is made inplace. The function simply
returns the input image again or undef on failure.
-Each channel is mapped independently through a lookup table with 256
+Each channel is mapped independently through a look-up table with 256
entries. The elements in the table should not be less than 0 and not
greater than 255. If they are out of the 0..255 range they are
clamped to the range. If a table does not contain 256 entries it is
@@ -908,7 +910,7 @@ Since C<[]> contains fewer than 256 element the gamma channel is
unaffected.
It is also possible to simply specify an array of maps that are
-applied to the images in the rgba order. For example to apply
+applied to the images in the RGBA order. For example to apply
maps to the C<red> and C<blue> channels one would use:
$img->map(maps=>[\@redmap, [], \@bluemap]);
@@ -925,6 +927,6 @@ Tony Cook <tony@imager.perl.org>, Arnar M. Hrafnkelsson
=head1 REVISION
-$Revision: 1667 $
+$Revision: 1724 $
=cut
@@ -10,6 +10,8 @@ If you have the necessary knowledge, install the image format
libraries you want Imager image file support for, and Imager itself,
otherwise arrange to have it done.
+=for stopwords Photoshop
+
You will also want some sort of image viewer tool, whether an image
editor like Photoshop or the GIMP, or a web browser.
@@ -175,6 +177,6 @@ Tony Cook <tony@imager.perl.org>
=head1 REVISION
-$Revision: 811 $
+$Revision: 1724 $
=cut
@@ -1,6 +1,6 @@
=head1 NAME
-Imager::interface.pod - decribes the C level virtual image interface
+Imager::interface.pod - describes the C level virtual image interface
=head1 SYNOPSIS
@@ -65,12 +65,14 @@ Other possible concrete images include:
Some other possible virtual images:
+=for stopwords GIMP Photoshop
+
=over
=item *
image alpha combining, where the combining function can be specified
-(see the layer modes in graphical editors like the GIMP or photoshop.
+(see the layer modes in graphical editors like the GIMP or Photoshop.
=back
@@ -84,61 +86,64 @@ can be used to determine the structure of the image:
=over
-=item channels
+=item *
-the number of samples kept for each pixel in the image. For paletted
-images the samples are kept for each entry in the palette.
+C<channels> - the number of samples kept for each pixel in the image.
+For paletted images the samples are kept for each entry in the
+palette.
-=item xsize, ysize
+=item *
-the dimensions of the image in pixels.
+C<xsize>, C<ysize> - the dimensions of the image in pixels.
-=item bytes
+=item *
-the number of bytes of data kept for the image. Zero for virtual
-images. Does not include the space required for the palette for
-paletted images.
+C<bytes> - the number of bytes of data kept for the image. Zero for
+virtual images. Does not include the space required for the palette
+for paletted images.
-=item ch_mask
+=item *
-controls which samples will be written to for direct images.
+C<ch_mask> - controls which samples will be written to for direct
+images.
-=item bits
+=item *
-the number of bits kept for each sample. There are enum values
-i_8_bits, i_16_bits and i_double_bits (64).
+C<bits> - the number of bits kept for each sample. There are enum
+values i_8_bits, i_16_bits and i_double_bits (64).
-=item type
+=item *
-the type of image, either i_direct_type or i_palette_type. Direct
-images keep the samples for every pixel image, while i_palette_type
-images keep an index into a color table for each pixel.
+C<type> - the type of image, either i_direct_type or i_palette_type.
+Direct images keep the samples for every pixel image, while
+i_palette_type images keep an index into a color table for each pixel.
-=item virtual
+=item *
-whether the image keeps any pixel data. If this is non-zero then
-idata points to image data, otherwise it points to implementation
-defined data, though ext_data is more likely to be used for that.
+C<virtual> - whether the image keeps any pixel data. If this is
+non-zero then C<idata> points to image data, otherwise it points to
+implementation defined data, though C<ext_data> is more likely to be
+used for that.
-=item idata
+=item *
-image data. If the image is 8-bit direct, non-virtual, then this
-consists of each sample of the image stored one after another,
-otherwise it is implementation defined.
+C<idata> - image data. If the image is 8-bit direct, non-virtual,
+then this consists of each sample of the image stored one after
+another, otherwise it is implementation defined.
-=item tags
+=item *
-will be used to store meta-data for an image, eg. tags from a TIFF
-file, or animation information from a GIF file. This should be
+C<tags> - will be used to store meta-data for an image, eg. tags from
+a TIFF file, or animation information from a GIF file. This should be
initialized with a call to i_tags_new() in your image constructor if
creating a new image type.
-=item ext_data
+=item *
-for internal use of image types. This is not released by the standard
-i_img_exorcise() function. If you create a new image type and want to
-store a pointer to allocated memory here you should point i_f_destroy
-at a function that will release the data.
+C<ext_data> - for internal use of image types. This is not released
+by the standard i_img_exorcise() function. If you create a new image
+type and want to store a pointer to allocated memory here you should
+point i_f_destroy at a function that will release the data.
=back
@@ -154,53 +159,53 @@ in the range 0 to 1 inclusive.
=over
-=item i_f_ppix(im, x, y, color)
+=item i_f_ppix(im,x,y,color)
-=item i_f_ppixf(im, x, y, fcolor)
+=item i_f_ppixf(im,x,y,fcolor)
stores the specified color at pixel (x,y) in the image. If the pixel
can be stored return 0, otherwise -1. An image type may choose to
return 0 under some circumstances, eg. writing to a masked area of an
-image. The color or fcolor always contains the actual samples to be
+image. The C<color> or C<fcolor> always contains the actual samples to be
written, rather than a palette index.
-=item i_f_plin(im, l, r, y, colors)
+=item i_f_plin(im,l,r,y,colors)
-=item i_f_plinf(im, l, r, y, fcolors)
+=item i_f_plinf(im,l,r,y,fcolors)
stores (r-l) pixels at positions (l,y) ... (r-1, y) from the array
-specified by colors (or fcolors). Returns the number of pixels
-written to. If l is negative it will return 0. If r > im->xsize then
-only (im->xsize - l) will be written.
+specified by C<colors> (or C<fcolors>). Returns the number of pixels
+written to. If l is negative it will return 0. If C<< r > im->xsize
+>> then only C<< (im->xsize - l) >> will be written.
-=item i_f_gpix(im, x, y, color)
+=item i_f_gpix(im,x,y,color)
-=item i_f_gpixf(im, x, y, fcolor)
+=item i_f_gpixf(im,x,y,fcolor)
retrieves a single pixel from position (x,y). This returns the
samples rather than the index for paletted images.
-=item i_f_glin(im, l, r, y, colors)
+=item i_f_glin(im,l,r,y,colors)
-=item i_f_glinf(im, l, r, y, fcolors)
+=item i_f_glinf(im,l,r,y,fcolors)
retrieves (r-l) pixels from positions (l, y) through (r-1, y) into the
array specified by colors. Returns the number of pixels retrieved.
-If l < 0 no pixels are retrieved. If r > im->xsize then pixels (l, y)
-... (im->xsize-1, y) are retrieved. Retrieves the samples rather than
-the color indexes for paletted images.
+If l < 0 no pixels are retrieved. If C<< r > im->xsize >> then pixels
+C<< (l, y) >> ... C<< (im->xsize-1, y) >> are retrieved. Retrieves
+the samples rather than the color indexes for paletted images.
-=item i_f_gsamp(im, l, r, y, samples, chans, chan_count)
+=item i_f_gsamp(im,l,r,y,samples,chans,chan_count)
-=item i_f_gsampf(im, l, r, y, fsamples, chans, chan_count)
+=item i_f_gsampf(im,l,r,y,fsamples,chans,chan_count)
-Retrieves samples from channels specified by chans (for length
-chan_count) from pixels at positions (l,y) ... (r-1, y). If chans is
-NULL then samples from channels 0 ... chan_count-1 will be retrieved.
-Returns the number of sample retrieved (_not_ the number of channels).
-If a channel in chans is not present in the image or l < 0, returns 0.
-If r > im->xsize, then the samples from (l,y) ... (im->xsize-1, y) are
-returned.
+Retrieves samples from channels specified by C<chans> (for length
+C<chan_count>) from pixels at positions (l,y) ... (r-1, y). If
+C<chans> is NULL then samples from channels 0 ... C<chan_count-1> will
+be retrieved. Returns the number of sample retrieved (I<not> the
+number of channels). If a channel in C<chans> is not present in the
+image or l < 0, returns 0. If C<< r > im->xsize >>, then the samples
+from C<(l,y)> ... C<< (im->xsize-1, y) >> are returned.
=back
@@ -208,25 +213,25 @@ The following are for images where type == i_palette_type only.
=over
-=item i_f_gpal(im, l, r, y, vals)
+=item i_f_gpal(im,l,r,y,vals)
Retrieves color indexes from the image for pixels (l, y) ... (r-1, y)
-into vals. Returns the number of indexes retrieved.
+into C<vals>. Returns the number of indexes retrieved.
-=item i_f_ppal(im, l, r, y, vals)
+=item i_f_ppal(im,l,r,y,vals)
Stores color indexes into the image for pixels (l, y) ... (r-1, y)
-from vals. Returns the number of indexes retrieved. If indices are
+from C<vals>. Returns the number of indexes retrieved. If indexes are
outside the range of the images palette, then you may have problems
reading those pixels with i_gpix() or i_glin().
-=item i_f_addcolors(im, colors, count)
+=item i_f_addcolors(im,colors,count)
Adds the count colors to the image's palette. Returns the index of
the first color added, or -1 if there is not enough space for count
colors.
-=item i_f_getcolors(im, index, colors, count)
+=item i_f_getcolors(im,index,colors,count)
Retrieves count colors from the image's palette starting from entry
index in the palette. Returns non-zero on success.
@@ -241,13 +246,13 @@ this is not a paletted image.
Returns the maximum number of colors that can fit in the image's
palette. Returns -1 if this is not a paletted image.
-=item i_f_findcolor(im, color, entry)
+=item i_f_findcolor(im,color,entry)
Searches the image's palette for the specified color, setting *entry
to the index and returning non-zero. Returns zero if the color is not
found.
-=item i_f_setcolors_t(im, index, colors, count)
+=item i_f_setcolors_t(im,index,colors,count)
Sets count colors starting from index in the image from the array
colors. The colors to be set must already have entries in the image's
@@ -268,7 +273,7 @@ same number of channels.
Several functions have been written to simplify creating new image types.
-These tools are available by including imagei.h.
+These tools are available by including F<imagei.h>.
=head2 Floating point wrappers
@@ -318,10 +323,10 @@ If this is not the case then these functions will just crash :)
=head2 Sample macros
-Imagei.h defines several macros for converting samples between
+C<Imagei.h> defines several macros for converting samples between
different sizes.
-Each macro is of the form SampleI<size>ToI<size> where I<size> is one
+Each macro is of the form C<Sample>I<size>C<To>I<size> where I<size> is one
of 8, 16, or F (for floating-point samples).
=over
@@ -6,7 +6,7 @@ Imager::transform2().
=head1 SYNOPSIS
The register machine is a complete rewrite of the stack machine
-orginally used by Imager::transform(), written for use by
+originally used by Imager::transform(), written for use by
Imager::transform2().
=head1 DESCRIPTION
@@ -15,7 +15,7 @@ Imager::transform2().
The register machine is a fast implementation of a small instruction
set designed for evaluating an arithmetic expression to produce a
-colour for an image.
+color for an image.
The machine takes as input:
@@ -30,26 +30,26 @@ An array of instructions
An array of numeric registers. Some registers are initialized as
literals.
-=item colour registers
+=item color registers
-An array of colour registers. Currently these registers aren't
+An array of color registers. Currently these registers aren't
initialized.
=item input images
-An array of Imager i_img pointers. The getpn operators read pixels
+An array of Imager i_img pointers. The C<getpn> operators read pixels
from these images.
=back
-The instructions supplied each take up to 4 input numeric or colour
-registers with a single output numeric or colour register. The
+The instructions supplied each take up to 4 input numeric or color
+registers with a single output numeric or color register. The
machine attempts to execute instructions as safely as possible,
assuming that correct instructions have been provided, eg. the machine
protects against divide by zero, but doesn't check register numbers
for validity.
-The final instruction must be a 'ret' instruction, which returns the
+The final instruction must be a C<ret> instruction, which returns the
result ;)
=head2 Adding new instructions
@@ -60,15 +60,15 @@ To add a new instruction:
=item 1
-Add a new opcode to the enumeration in regmach.h - make sure to add
-comment after the enum name giving the input registers (rX for
-numeric, pX for colour) that the instruction takes. These must be in
+Add a new opcode to the enumeration in F<regmach.h> - make sure to add
+comment after the enum name giving the input registers (C<rX> for
+numeric, C<pX> for color) that the instruction takes. These must be in
the order that the instruction expects to take the. Put a letter (r
or p) after -> to indicate the result type.
=item 2
-Add a case to regmach.c that executes the instruction.
+Add a case to F<regmach.c> that executes the instruction.
=item 3
@@ -76,7 +76,7 @@ make
=back
-The makefile should rebuild the Regops.pm file, and your new
+The F<Makefile> should rebuild the F<Regops.pm> file, and your new
instruction will be added as a function.
If you want to add a single alternative instruction that might take
@@ -97,7 +97,7 @@ performance loss.
=head1 WARNINGS
If you feed bad 'machine code' to the register machine, you have a
-good chance of a SIGSEGV.
+good chance of a C<SIGSEGV>.
=cut
@@ -77,14 +77,14 @@ static i_img IIM_base_8bit_pal =
};
/*
-=item i_img_pal_new(x, y, channels, maxpal)
+=item i_img_pal_new(C<x>, C<y>, C<channels>, C<maxpal>)
=category Image creation/destruction
=synopsis i_img *img = i_img_pal_new(width, height, channels, max_palette_size)
Creates a new paletted image of the supplied dimensions.
-I<maxpal> is the maximum palette size and should normally be 256.
+C<maxpal> is the maximum palette size and should normally be 256.
Returns a new image or NULL on failure.
@@ -1,15 +1,16 @@
#include "imager.h"
/*
-=item i_copyto(dest, src, x1, y1, x2, y2, tx, ty)
+=item i_copyto(C<dest>, C<src>, C<x1>, C<y1>, C<x2>, C<y2>, C<tx>, C<ty>)
=category Image
-Copies image data from the area (x1,y1)-[x2,y2] in the source image to
-a rectangle the same size with it's top-left corner at (tx,ty) in the
-destination image.
+Copies image data from the area (C<x1>,C<y1>)-[C<x2>,C<y2>] in the
+source image to a rectangle the same size with it's top-left corner at
+(C<tx>,C<ty>) in the destination image.
-If x1 > x2 or y1 > y2 then the corresponding co-ordinates are swapped.
+If C<x1> > C<x2> or C<y1> > C<y2> then the corresponding co-ordinates
+are swapped.
=cut
*/
@@ -28,13 +28,13 @@ setcol(i_color *cl,unsigned char r,unsigned char g,unsigned char b,unsigned char
*/
/*
-=item i_quant_makemap(quant, imgs, count)
+=item i_quant_makemap(C<quant>, C<imgs>, C<count>)
=category Image quantization
-Analyzes the I<count> images in I<imgs> according to the rules in
-I<quant> to build a color map (optimal or not depending on
-quant->make_colors).
+Analyzes the C<count> images in C<imgs> according to the rules in
+C<quant> to build a color map (optimal or not depending on
+C<< quant->make_colors >>).
=cut
*/
@@ -88,14 +88,14 @@ static void translate_errdiff(i_quantize *, i_img *, i_palidx *);
static void translate_addi(i_quantize *, i_img *, i_palidx *);
/*
-=item i_quant_translate(quant, img)
+=item i_quant_translate(C<quant>, C<img>)
=category Image quantization
-Quantize the image given the palette in quant.
+Quantize the image given the palette in C<quant>.
-On success returns a pointer to a memory block of img->xsize *
-img->ysize i_palidx entries.
+On success returns a pointer to a memory block of C<< img->xsize *
+img->ysize >> C<i_palidx> entries.
On failure returns NULL.
@@ -1486,14 +1486,14 @@ static void transparent_errdiff(i_quantize *, i_palidx *, i_img *, i_palidx);
static void transparent_ordered(i_quantize *, i_palidx *, i_img *, i_palidx);
/*
-=item i_quant_transparent(quant, data, img, trans_index)
+=item i_quant_transparent(C<quant>, C<data>, C<img>, C<trans_index>)
=category Image quantization
-Dither the alpha channel on I<img> into the palette indexes in
-I<data>. Pixels to be transparent are replaced with I<trans_pixel>.
+Dither the alpha channel on C<img> into the palette indexes in
+C<data>. Pixels to be transparent are replaced with C<trans_pixel>.
-The method used depends on the tr_* members of quant.
+The method used depends on the tr_* members of C<quant>.
=cut
*/
@@ -81,7 +81,7 @@ __END__
=head1 NAME
-Imager::Regops - generated information about the register based VM
+Imager::Regops - generated information about the register based virtual machine
=head1 SYNOPSIS
@@ -95,7 +95,7 @@ Imager::Regops - generated information about the register based VM
=head1 DESCRIPTION
-This module is generated automatically from regmach.h so we don't need to
+This module is generated automatically from F<regmach.h> so we don't need to
maintain the same information in at least one extra place.
At least that's the idea.
@@ -153,16 +153,16 @@ rubthru_targ_alpha(i_img *im, i_img *src, int tx, int ty,
}
/*
-=item i_rubthru(im, src, tx, ty, src_minx, src_miny, src_maxx, src_maxy )
+=item i_rubthru(C<im>, C<src>, C<tx>, C<ty>, C<src_minx>, C<src_miny>, C<src_maxx>, C<src_maxy>)
=category Image
-Takes the sub image I<src[src_minx, src_maxx)[src_miny, src_maxy)> and
-overlays it at (I<tx>,I<ty>) on the image object.
+Takes the sub image C<src>[C<src_minx>, C<src_maxx>)[C<src_miny>, C<src_maxy>)> and
+overlays it at (C<tx>,C<ty>) on the image object.
-The alpha channel of each pixel in I<src> is used to control how much
-the existing colour in I<im> is replaced, if it is 255 then the colour
-is completely replaced, if it is 0 then the original colour is left
+The alpha channel of each pixel in C<src> is used to control how much
+the existing color in C<im> is replaced, if it is 255 then the color
+is completely replaced, if it is 0 then the original color is left
unmodified.
=cut
@@ -72,8 +72,8 @@ align-string.pl - demo of the Imager align_string() method
=head1 DESCRIPTION
-Create an image in output imagein I<outputfile> displaying a grid of
-the various valign and halign options for the Imager align_string
+Create an image in output C<imagein> C<outputfile> displaying a grid of
+the various C<valign> and C<halign> options for the Imager align_string()
method.
Try it with different fonts and strings to get a better understanding
@@ -89,7 +89,7 @@ Imager, Imager::Font
=head1 REVISION
-$Revision: 840 $
+$Revision: 1724 $
=cut
@@ -107,6 +107,8 @@ EXPR
=head1 NAME
+=for stopwords anaglyph anaglyph.pl
+
anaglyph.pl - create a anaglyph from the source images
=head1 SYNOPSIS
@@ -141,10 +143,12 @@ though obviously the interactive component is missing.
Tony Cook <tony@imager.perl.org>
+=for stopwords Oppenheim
+
Thanks to Dan Oppenheim, who provided the impetus for this sample.
=head1 REVISION
-$Revision: 719 $
+$Revision: 1724 $
=cut
@@ -122,8 +122,8 @@ flasher.pl - produces a slowly flashing GIF based on an input image
=head1 DESCRIPTION
-flasher.pl generates an animation from the given image to I<lowpct>%
-coverage on a blank image of color I<back>.
+flasher.pl generates an animation from the given image to C<lowpct>%
+coverage on a blank image of color C<back>.
=head1 OPTIONS
@@ -131,29 +131,27 @@ coverage on a blank image of color I<back>.
=item *
--f I<frames>, --frames I<frames> - the total number of frames. This is
- always rounded up to the next even number. Default: 20
+C<-f> I<frames>, C<--frames> I<frames> - the total number of frames.
+This is always rounded up to the next even number. Default: 20
=item *
--d I<delay>, --delay I<delay> - the delay in 1/100 second between
- frames. Default: 10.
+C<-d> I<delay>, C<--delay> I<delay> - the delay in 1/100 second between
+frames. Default: 10.
=item *
--p I<percent>, --lowpct I<percent> - the lowest coverage of the image.
- Default: 30
+C<-p> I<percent>, C<--lowpct> I<percent> - the lowest coverage of the image.
+Default: 30
=item *
--b I<color>, --back I<color> - the background color to fade to.
+C<-b> I<color>, C<--back> I<color> - the background color to fade to.
Default: #FFFFFF.
=item *
--v, --verbose - produce progress information.
-
-=item
+C<-v>, C<--verbose> - produce progress information.
=back
@@ -61,15 +61,17 @@ Imager->write_multi({ file => $out_name }, @out)
=head1 NAME
+=for stopwords gifscale.pl
+
gifscale.pl - demonstrates adjusting tags when scaling a GIF image
=head1 SYNOPSIS
-perl gifscale.pl scalefactor input.gif output.gif
+ perl gifscale.pl scalefactor input.gif output.gif
=head1 DESCRIPTION
-Scales an input multi-image GIF file. Unlike a simple scale each file
+Scales an input multiple-image GIF file. Unlike a simple scale each file
solution this:
=over
@@ -57,7 +57,7 @@ __END__
=head1 NAME
-inline_capture2image.pl - convert captured BGR data to any Imager supported format
+inline_capture2image.pl - convert captured C<BGR> data to any Imager supported format
=head1 SYNOPSIS
@@ -4,6 +4,8 @@ use Imager;
=head1 NAME
+=for stopwords Inline
+
inline_replace_color.pl - replace one color with another in an image, using Inline
=head1 SYNOPSIS
@@ -124,10 +124,12 @@ might be useful.
Tony Cook <tony@imager.perl.org>
+=for stopwords Oppenheim
+
Thanks to Dan Oppenheim, who provided the impetus for this sample.
=head1 REVISION
-$Revision: 718 $
+$Revision: 1724 $
=cut
@@ -48,6 +48,8 @@ quad_to_square.pl - transform an arbitrary quadrilateral to a square.
=head1 DESCRIPTION
+=for stopwords Fairhurst resized
+
Courtesy Richard Fairhurst:
I've been using it to rectify ("square up") a load of roughly scanned
@@ -190,6 +190,7 @@ it.
=item transformed_bounds
Returns a list of bounds:
+
(minx, miny, maxx, maxy)
These are offsets from the text's starting point in font co-ordinates
@@ -208,7 +209,7 @@ Tony Cook <tony@imager.perl.org>
=head1 REVISION
-$Revision: 1073 $
+$Revision: 1724 $
=head1 SEE ALSO
@@ -27,6 +27,8 @@ MainLoop;
=head1 NAME
+=for stopwords tk-photo.pl
+
tk-photo.pl - display an Imager image under Tk
=head1 SYNOPSIS
@@ -58,7 +60,7 @@ the C<-data> parameter.
=head1 REVISION
-$Revision: 830 $
+$Revision: 1724 $
=head1 AUTHOR
@@ -7,13 +7,29 @@ use Imager qw(:all);
i_has_format("gif")
and plan skip_all => "gif support available and this tests the lack of it";
-plan tests => 6;
+plan tests => 12;
my $im = Imager->new;
ok(!$im->read(file=>"testimg/scale.gif"), "should fail to read gif");
-cmp_ok($im->errstr, '=~', "format 'gif' not supported", "check no gif message");
+cmp_ok($im->errstr, '=~', "format 'gif' not supported",
+ "check no gif message");
+ok(!Imager->read_multi(file=>"testimg/scale.gif"),
+ "should fail to read multi gif");
+cmp_ok($im->errstr, '=~', "format 'gif' not supported",
+ "check no gif message");
+
$im = Imager->new(xsize=>2, ysize=>2);
+
ok(!$im->write(file=>"testout/nogif.gif"), "should fail to write gif");
-cmp_ok($im->errstr, '=~', "format 'gif' not supported", "check no gif message");
+ok(!-e "testout/nogif.gif", "shouldn't create the file");
+cmp_ok($im->errstr, '=~', "format 'gif' not supported",
+ "check no gif message");
+
+ok(!Imager->write_multi({file => "testout/nogif.gif"}, $im, $im),
+ "should fail to write multi gif");
+ok(!-e "testout/nogif.gif", "shouldn't create the file");
+cmp_ok($im->errstr, '=~', "format 'gif' not supported",
+ "check no gif message");
+
ok(!grep($_ eq 'gif', Imager->read_types), "check gif not in read types");
ok(!grep($_ eq 'gif', Imager->write_types), "check gif not in write types");
@@ -6,13 +6,31 @@ use Imager qw(:all);
i_has_format("tiff")
and plan skip_all => "tiff support available - this tests the lack of it";
-plan tests => 6;
+plan tests => 12;
my $im = Imager->new;
+
ok(!$im->read(file=>"testimg/comp4.tif"), "should fail to read tif");
-cmp_ok($im->errstr, '=~', "format 'tiff' not supported", "check no tiff message");
+cmp_ok($im->errstr, '=~', "format 'tiff' not supported",
+ "check no tiff message");
+
+ok(!$im->read_multi(file => "testimg/comp4.tif"),
+ "should fail to read multi tiff");
+cmp_ok($im->errstr, '=~', "format 'tiff' not supported",
+ "check no tiff message");
+
$im = Imager->new(xsize=>2, ysize=>2);
+
ok(!$im->write(file=>"testout/notiff.tif"), "should fail to write tiff");
-cmp_ok($im->errstr, '=~', "format 'tiff' not supported", "check no tiff message");
+cmp_ok($im->errstr, '=~', "format 'tiff' not supported",
+ "check no tiff message");
+ok(!-e "testout/notiff.tif", "file shouldn't be created");
+
+ok(!Imager->write_multi({file=>"testout/notiff.tif"}, $im, $im),
+ "should fail to write multi tiff");
+cmp_ok($im->errstr, '=~', "format 'tiff' not supported",
+ "check no tiff message");
+ok(!-e "testout/notiff.tif", "file shouldn't be created");
+
ok(!grep($_ eq 'tiff', Imager->read_types), "check tiff not in read types");
ok(!grep($_ eq 'tiff', Imager->write_types), "check tiff not in write types");
@@ -68,7 +68,7 @@ plan tests => 18;
my @indexed;
my @unknown_indexed;
while (<IMAGER>) {
- last if /^=\w/;
+ last if /^=\w/ && !/^=for\b/;
if (/^(\w+)\(/) {
push @indexed, $1;
@@ -182,7 +182,7 @@ void i_tags_destroy(i_img_tags *tags) {
=category Tags
-Searchs for a tag of the given I<name> starting from index I<start>.
+Searches for a tag of the given I<name> starting from index I<start>.
On success returns true and sets *I<entry>.
@@ -209,7 +209,7 @@ int i_tags_find(i_img_tags *tags, char const *name, int start, int *entry) {
=category Tags
-Searchs for a tag of the given I<code> starting from index I<start>.
+Searches for a tag of the given I<code> starting from index I<start>.
On success returns true and sets *I<entry>.
@@ -580,7 +580,7 @@ On failure returns false.
value_size must be at least large enough for a string representation
of an integer.
-The copied value is always NUL terminated.
+The copied value is always C<NUL> terminated.
=cut
*/
@@ -636,14 +636,14 @@ i_tags_set(i_img_tags *tags, char const *name, char const *data, int size) {
}
/*
-=item i_tags_setn(tags, name, idata)
+=item i_tags_setn(C<tags>, C<name>, C<idata>)
=synopsis i_tags_setn(&img->tags, "i_xres", 204);
=synopsis i_tags_setn(&img->tags, "i_yres", 196);
=category Tags
-Sets the given tag to the integer I<idata>
+Sets the given tag to the integer C<idata>
-Even on failure, if an existing tag I<name> exists, it will be
+Even on failure, if an existing tag C<name> exists, it will be
removed.
=cut