=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>, C<readcb>, C<writecb>, C<seekcb>, C<closecb> - Imager
to supply the read callback, and when writing C<callback> or
C<writecb> to supply the write callback.
-Some file formats, currently only C<TIFF>, also require a C<seekcb>
-parameter to change position in the file. If no C<seekcb> parameter
-is provided a default will be provided that fails.
+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.
+file is complete. If no C<closecb> is supplied the default will
+succeed silently.
# contrived
my $data;
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.
Imager(3)
+=head1 AUTHOR
+
+Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson
+
=cut
projects / imager.git / blobdiff