=head1 DESCRIPTION
You can read and write a variety of images formats, assuming you have
-the appropriate libraries, and images can be read or written to/from
-files, file handles, file descriptors, scalars, or through callbacks.
+the L<appropriate libraries|Imager::Install/EXTERNAL LIBRARIES>, and
+images can be read or written to/from files, file handles, file
+descriptors, scalars, or through callbacks.
To see which image formats Imager is compiled to support the following
code snippet is sufficient:
=over
-=item read
+=item read()
Reading writing to and from files is simple, use the C<read()>
method to read an image:
$img->read(file => $filename)
or die "Cannot read $filename: ", $img->errstr;
-The read() method accepts the C<allow_partial> parameter. If this is
-non-zero then read() can return true on an incomplete image and set
+The read() method accepts the C<allow_incomplete> parameter. If this
+is non-zero then read() can return true on an incomplete image and set
the C<i_incomplete> tag.
From Imager 0.68 you can supply most read() parameters to the new()
my $img = Imager->new(file => $filename)
or die "Cannot read $filename: ", Imager->errstr;
-=item write
+=item write()
and the C<write()> method to write an image:
$img->write(file=>$filename, type=>$type)
or die "Cannot write $filename: ", $img->errstr;
-=item read_multi
+=item read_multi()
If you're reading from a format that supports multiple images per
file, use the C<read_multi()> method:
As with the read() method, Imager will normally detect the C<type>
automatically.
-=item write_multi
+=item write_multi()
and if you want to write multiple images to a single file use the
C<write_multi()> method:
=item *
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 C<giflib> 4 or
-higher, and you may need to patch C<giflib> to use this option for
-writing.
+file data, or a reference to such a scalar. When writing, C<data> is
+a reference to the scalar to save the image file data to.
my $data;
$image->write(data => \$data, type => 'tiff')
my @images = Imager->read_multi(data => $data)
or die Imager->errstr;
+ # from Imager 0.99
+ my @images = Imager->read_multi(data => \$data)
+ or die Imager->errstr;
+
=item *
-C<callback> - Imager will make calls back to your supplied coderefs to
-read, write and seek from/to/through the image file.
+C<callback>, C<readcb>, C<writecb>, C<seekcb>, C<closecb> - Imager
+will make calls back to your supplied coderefs to read, write and seek
+from/to/through the image file. See L</"I/O Callbacks"> below for details.
-When reading from a file you can use either C<callback> or C<readcb>
-to supply the read callback, and when writing C<callback> or
-C<writecb> to supply the write callback.
+=item *
-When writing you can also supply the C<maxbuffer> option to set the
-maximum amount of data that will be buffered before your write
-callback is called. Note: the amount of data supplied to your
-callback can be smaller or larger than this size.
+C<io> - an L<Imager::IO> object.
-The read callback is called with 2 parameters, the minimum amount of
-data required, and the maximum amount that Imager will store in it's C
-level buffer. You may want to return the minimum if you have a slow
-data source, or the maximum if you have a fast source and want to
-prevent many calls to your perl callback. The read data should be
-returned as a scalar.
+=back
-Your write callback takes exactly one parameter, a scalar containing
-the data to be written. Return true for success.
+X<buffering>X<unbuffered>By default Imager will use buffered I/O when
+reading or writing an image. You can disabled buffering for output by
+supplying a C<< buffered => 0 >> parameter to C<write()> or
+C<write_multi()>.
-The seek callback takes 2 parameters, a I<POSITION>, and a I<WHENCE>,
-defined in the same way as perl's seek function.
+=head2 I/O Callbacks
-You can also supply a C<closecb> which is called with no parameters
-when there is no more data to be written. This could be used to flush
-buffered data.
+When reading from a file you can use either C<callback> or C<readcb>
+to supply the read callback, and when writing C<callback> or
+C<writecb> to supply the write callback.
+
+Whether reading or writing a C<TIFF> image, C<seekcb> and C<readcb>
+are required.
+
+If a file handler attempts to use C<readcb>, C<writecb> or C<seekcb>
+and you haven't supplied one, the call will fail, failing the image
+read or write, returning an error message indicating that the callback
+is missing:
+
+ # attempting to read a TIFF image without a seekcb
+ open my $fh, "<", $filename or die;
+ my $rcb = sub {
+ my $val;
+ read($fh, $val, $_[0]) or return "";
+ return $val;
+ };
+ my $im = Imager->new(callback => $rcb)
+ or die Imager->errstr
+ # dies with (wrapped here):
+ # Error opening file: (Iolayer): Failed to read directory at offset 0:
+ # (Iolayer): Seek error accessing TIFF directory: seek callback called
+ # but no seekcb supplied
+
+You can also provide a C<closecb> parameter called when writing the
+file is complete. If no C<closecb> is supplied the default will
+succeed silently.
# contrived
my $data;
Imager->write_multi({ callback => \&mywrite, type => 'gif'}, @images)
or die Imager->errstr;
-Note that for reading you'll almost always need to provide a
-C<seekcb>.
+=head3 C<readcb>
+
+The read callback is called with 2 parameters:
+
+=over
+
+=item *
+
+C<size> - the minimum amount of data required.
+
+=item *
+
+C<maxsize> - previously this was the maximum amount of data returnable
+- currently it's always the same as C<size>
=back
+Your read callback should return the data as a scalar:
+
+=over
+
+=item *
+
+on success, a string containing the bytes read.
+
+=item *
+
+on end of file, an empty string
+
+=item *
+
+on error, C<undef>.
+
+=back
+
+If your return value contains more data than C<size> Imager will
+panic.
+
+Your return value must not contain any characters over C<\xFF> or
+Imager will panic.
+
+=head3 C<writecb>
+
+Your write callback takes exactly one parameter, a scalar containing
+the data to be written.
+
+Return true for success.
+
+=head3 C<seekcb>
+
+The seek callback takes 2 parameters, a I<POSITION>, and a I<WHENCE>,
+defined in the same way as perl's seek function.
+
+Previously you always needed a C<seekcb> callback if you called
+Imager's L</read()> or L</read_multi()> without a C<type> parameter,
+but this is no longer necessary unless the file handler requires
+seeking, such as for TIFF files.
+
+Returns the new position in the file, or -1 on failure.
+
+=head3 C<closecb>
+
+You can also supply a C<closecb> which is called with no parameters
+when there is no more data to be written. This could be used to flush
+buffered data.
+
+Return true on success.
+
=head2 Guessing types
+X<FORMATGUESS>
When writing to a file, if you don't supply a C<type> parameter Imager
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.
+done when write() or write_multi() is called with a C<file> parameter,
+or if read() or read_multi() can't determine the type from the file's
+header.
The default function value of C<$Imager::FORMATGUESS> is
C<\&Imager::def_guess_type>.
=over
=item def_guess_type()
+X<methods, 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.
You can pass any or all of the limits above, any limits you do not
pass are left as they were.
-Any limit of zero is treated as unlimited.
+Any limit of zero for width or height is treated as unlimited.
+
+A limit of zero for bytes is treated as one gigabyte, but higher bytes
+limits can be set explicitly.
By default, the width and height limits are zero, or unlimited. The
default memory size limit is one gigabyte.
-You can reset all limits to unlimited with the reset parameter:
+You can reset all limits to their defaults with the reset parameter:
# no limits
Imager->set_file_limits(reset=>1);
my ($max_width, $max_height, $max_bytes) =
Imager->get_file_limits();
+=item check_file_limits()
+X<class methods, check_file_limits()>X<check_file_limits()>
+
+Intended for use by file handlers to check that the size of a file is
+within the limits set by C<set_file_limits()>.
+
+Parameters:
+
+=over
+
+=item *
+
+C<width>, C<height> - the width and height of the image in pixels.
+Must be a positive integer. Required.
+
+=item *
+
+C<channels> - the number of channels in the image, including the alpha
+channel if any. Must be a positive integer between 1 and 4
+inclusive. Default: 3.
+
+=item *
+
+C<sample_size> - the number of bytes stored per sample. Must be a
+positive integer or C<"float">. Note that this should be the sample
+size of the Imager image you will be creating, not the sample size in
+the source, eg. if the source has 32-bit samples this should be
+C<"float"> since Imager doesn't have 32-bit/sample images.
+
+=back
+
=back
=head1 TYPE SPECIFIC INFORMATION
=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
-background set by the C<i_background> parameter (or tag).
+You can supply a C<jpegquality> parameter ranging from 0 (worst
+quality) to 100 (best quality) when writing a JPEG file, which
+defaults to 75.
$img->write(file=>'foo.jpg', jpegquality=>90) or die $img->errstr;
+If you write an image with an alpha channel to a JPEG file then it
+will be composed against the background set by the C<i_background>
+parameter (or tag), or black if not supplied.
+
Imager will read a gray scale JPEG as a 1 channel image and a color
JPEG as a 3 channel image.
JPEG supports the spatial resolution tags C<i_xres>, C<i_yres> and
C<i_aspect_only>.
+You can also set the following tags when writing to an image, they are
+not set in the image when reading:
+
+=over
+
+C<jpeg_optimize> - set to a non-zero integer to compute optimal
+Huffman coding tables for the image. This will increase memory usage
+and processing time (about 12% in my simple tests) but can
+significantly reduce file size without a loss of quality.
+
+=back
+
=for stopwords EXIF
If an C<APP1> block containing EXIF information is found, then any of the
If you read an image with multiple alpha channels, then only the first
alpha channel will be read.
+When reading a C<TIFF> image with callbacks, the C<seekcb> callback
+parameter is also required.
+
+When writing a C<TIFF> image with callbacks, the C<seekcb> and
+C<readcb> parameters are also required.
+
+C<TIFF> is a random access file format, it cannot be read from or
+written to unseekable streams such as pipes or sockets.
+
=head2 BMP (Windows Bitmap)
Imager can write 24-bit RGB, and 8, 4 and 1-bit per pixel paletted
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 C<datachannels> and
-C<storechannels> options to control the number of channels in your input
+junk in the fourth channel, you can use the C<raw_datachannels> and
+C<raw_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:
- $img->read(file=>'foo.raw', xsize=>100, ysize=>100, datachannels=>4,
- storechannels=>3)
+ $img->read(file=>'foo.raw', xsize => 100, ysize => 100,
+ raw_datachannels => 4, raw_storechannels => 3,
+ raw_interleave => 0)
or die "Cannot read raw image\n";
+In general, if you supply C<raw_storechannels> you should also supply
+C<raw_datachannels>
+
Read parameters:
=over
=item *
-raw_interleave - controls the ordering of samples within the image.
+C<raw_interleave> - controls the ordering of samples within the image.
Default: 1. Alternatively and historically spelled C<interleave>.
Possible values:
=item *
-raw_storechannels - the number of channels to store in the image.
+C<raw_storechannels> - the number of channels to store in the image.
Range: 1 to 4. Default: 3. Alternatively and historically spelled
C<storechannels>.
=item *
-raw_datachannels - the number of channels to read from the file.
+C<raw_datachannels> - the number of channels to read from the file.
Range: 1 or more. Default: 3. Alternatively and historically spelled
C<datachannels>.
=head2 PNG
-There are no PNG specific tags.
+=head3 PNG Image modes
+
+PNG files can be read and written in the following modes:
+
+=over
+
+=item *
+
+bi-level - written as a 1-bit per sample gray scale image
+
+=item *
+
+paletted - Imager gray scale paletted images are written as RGB
+paletted images. PNG palettes can include alpha values for each entry
+and this is honored as an Imager four channel paletted image.
+
+=item *
+
+8 and 16-bit per sample gray scale, optionally with an alpha channel.
+
+=item *
+
+8 and 16-bit per sample RGB, optionally with an alpha channel.
+
+=back
+
+Unlike GIF, there is no automatic conversion to a paletted image,
+since PNG supports direct color.
+
+=head3 PNG Text tags
+
+Text tags are retrieved from and written to PNG C<tEXT> or C<zTXT>
+chunks. The following standard tags from the PNG specification are
+directly supported:
+
+=over
+
+=item *
+
+C<i_comment>X<tags,i_comment> - keyword of "Comment".
+
+=item *
+
+C<png_author>X<tags,PNG,png_author> - keyword "Author".
+
+=item *
+
+C<png_copyright>X<tags,PNG,png_copyright> - keyword "Copyright".
+
+=item *
+
+C<png_creation_time>X<tags,PNG,png_creation_time> - keyword "Creation Time".
+
+=item *
+
+C<png_description>X<tags,PNG,png_description> - keyword "Description".
+
+=item *
+
+C<png_disclaimer>X<tags,PNG,png_disclaimer> - keyword "Disclaimer".
+
+=item *
+
+C<png_software>X<tags,PNG,png_software> - keyword "Software".
+
+=item *
+
+C<png_title>X<tags,PNG,png_title> - keyword "Title".
+
+=item *
+
+C<png_warning>X<tags,PNG,png_warning> - keyword "Warning".
+
+=back
+
+Each of these tags has a corresponding C<< I<base-tag-name>_compressed
+>> tag, eg. C<png_comment_compressed>. When reading, if the PNG chunk
+is compressed this tag will be set to 1, but is otherwise unset. When
+writing, Imager will honor the compression tag if set and non-zero,
+otherwise the chunk text will be compressed if the value is longer
+than 1000 characters, as recommended by the C<libpng> documentation.
+
+PNG C<tEXT> or C<zTXT> chunks outside of those above are read into or
+written from Imager tags named like:
+
+=over
+
+=item *
+
+C<< png_textI<N>_key >> - the key for the text chunk. This can be 1
+to 79 characters, may not contain any leading, trailing or consecutive
+spaces, and may contain only Latin-1 characters from 32-126, 161-255.
+
+=item *
+
+C<< png_textI<N>_text >> - the text for the text chunk. This may not
+contain any C<NUL> characters.
+
+=item *
+
+C<< png_textI<N>_compressed >> - whether or not the text chunk is
+compressed. This behaves similarly to the C<<
+I<base-tag-name>_compressed >> tags described above.
+
+=back
+
+Where I<N> starts from 0. When writing both the C<..._key> and
+C<..._text> tags must be present or the write will fail. If the key
+or text do not satisfy the requirements above the write will fail.
+
+=head3 Other PNG metadata tags
+
+=over
+
+=item *
+
+X<tags, png_interlace>C<png_interlace>, C<png_interlace_name> - only
+set when reading, C<png_interlace> is set to the type of interlacing
+used by the file, 0 for one, 1 for Adam7. C<png_interlace_name> is
+set to a keyword describing the interlacing, either C<none> or
+C<adam7>.
+
+=item *
+
+X<tags, png_srgb_intent>C<png_srgb_intent> - the sRGB rendering intent
+for the image. an integer from 0 to 3, per the PNG specification. If
+this chunk is found in the PNG file the C<gAMA> and C<cHRM> are
+ignored and the C<png_gamma> and C<png_chroma_...> tags are not set.
+Similarly when writing if C<png_srgb_intent> is set the C<gAMA> and
+C<cHRM> chunks are not written.
+
+=item *
+
+X<tags, png_gamma>C<png_gamma> - the gamma of the image. This value is
+not currently used by Imager when processing the image, but this may
+change in the future.
+
+=item *
+
+X<tags, png_chroma_...>C<png_chroma_white_x>, C<png_chroma_white_y>,
+C<png_chroma_red_x>, C<png_chroma_red_y>, C<png_chroma_green_x>,
+C<png_chroma_green_y>, C<png_chroma_blue_x>, C<png_chroma_blue_y> -
+the primary chromaticities of the image, defining the color model.
+This is currently not used by Imager when processing the image, but
+this may change in the future.
+
+=item *
+
+C<i_xres>, C<i_yres>, C<i_aspect_only> - processed per
+I<Imager::ImageTypes/CommonTags>.
+
+=item *
+
+X<tags, png_bits>C<png_bits> - the number of bits per sample in the
+representation. Ignored when writing.
+
+=item *
+
+X<tags, png_time>C<png_time> - the creation time of the file formatted
+as C<< I<year>-I<month>-I<day>TI<hour>:I<minute>:I<second> >>. This
+is stored as time data structure in the file, not a string. If you
+set C<png_time> and it cannot be parsed as above, writing the PNG file
+will fail.
+
+=item *
+
+C<i_background> - set from the C<sBKG> when reading an image file.
+
+=back
+
+X<compression>X<png_compression_level>You can control the level of
+F<zlib> compression used when writing with the
+C<png_compression_level> parameter. This can be an integer between 0
+(uncompressed) and 9 (best compression).
+
+=for stopwords
+CRC
+
+X<png_ignore_benign_errors>If you're using F<libpng> 1.6 or later, or
+an earlier release configured with C<PNG_BENIGN_ERRORS_SUPPORTED>, you
+can choose to ignore file format errors the authors of F<libpng>
+consider I<benign>, this includes at least CRC errors and palette
+index overflows. Do this by supplying a true value for the
+C<png_ignore_benign_errors> parameter to the read() method:
+
+ $im->read(file => "foo.png", png_ignore_benign_errors => 1)
+ or die $im->errstr;
=head2 ICO (Microsoft Windows Icon) and CUR (Microsoft Windows Cursor)
=item *
-ico_masked - if true, the default, then the icon/cursors mask is
-applied as an alpha channel to the image. This may result in a
-paletted image being returned as a direct color image. Default: 1
+C<ico_masked> - if true, the default, then the icon/cursors mask is
+applied as an alpha channel to the image, unless that image already
+has an alpha channel. This may result in a paletted image being
+returned as a direct color image. Default: 1
# retrieve the image as stored, without using the mask as an alpha
# channel
This was introduced in Imager 0.60. Previously reading ICO images
acted as if C<ico_masked =E<gt> 0>.
+=item *
+
+C<ico_alpha_masked> - if true, then the icon/cursor mask is applied as
+an alpha channel to images that already have an alpha mask. Note that
+this will only make pixels transparent, not opaque. Default: 0.
+
+Note: If you get different results between C<ico_alpha_masked> being
+set to 0 and 1, your mask may break when used with the Win32 API.
+
=back
C<cur_bits> is set when reading a cursor.
=back
+=item add_type_extensions($type, $ext, ...)
+
+This class method can be used to add extensions to the map used by
+C<def_guess_type> when working out the file type a filename extension.
+
+ Imager->add_type_extension(mytype => "mytype", "mytypish");
+ ...
+ $im->write(file => "foo.mytypish") # use the mytype handler
+
=back
If you name the reader module C<Imager::File::>I<your-format-name>
Imager(3)
+=head1 AUTHOR
+
+Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson
+
=cut
projects / imager.git / blobdiff