print join " ", keys %Imager::formats;
This will include some other information identifying libraries rather
-than file formats. For new code you might find the L</read_types> or
-L</write_types> methods useful.
+than file formats. For new code you might find the L</read_types()>
+or L</write_types()> methods useful.
=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:
Imager->write_multi({ file=> $filename, type=>$type }, @images)
or die "Cannot write $filename: ", Imager->errstr;
-=item read_types
+=item read_types()
This is a class method that returns a list of the image file types
that Imager can read.
attempting to read a file, which may modify the list of available read
types.
-=item write_types
+=item write_types()
This is a class method that returns a list of the image file types
that Imager can write.
=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
+=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.
=over
-=item set_file_limits
+=item set_file_limits()
In some cases you will be receiving images from an untested source,
such as submissions via CGI. To prevent such images from consuming
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, all of the limits are zero, or unlimited.
+By default, the width and height limits are zero, or unlimited. The
+default memory size limit is one gigabyte.
-You can reset all of the limited to their defaults by passing in the
-reset parameter as a true value:
+You can reset all limits to their defaults with the reset parameter:
# no limits
Imager->set_file_limits(reset=>1);
# only bytes is limited
Imager->set_file_limits(reset=>1, bytes=>10_000_000);
-=item get_file_limits
+=item get_file_limits()
You can get the current limits with the get_file_limits() method:
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
=over
-=item C<jpeg_density_unit>
+=item *
-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.
+C<jpeg_density_unit> - 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 C<jpeg_density_unit_name>
+=item *
-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 C<jpeg_density_unit> is unknown then
-this tag isn't set.
+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 C<jpeg_density_unit>
+is unknown then this tag isn't set.
+
+=item *
+
+C<jpeg_comment> - Text comment.
-=item C<jpeg_comment>
+=item *
-Text comment.
+C<jpeg_progressive> - Whether the JPEG file is a progressive
+file. (Imager 0.84)
=back
=back
-=head2 GIF (Graphics Interchange Format)
+=head2 GIF
When writing one of more GIF images you can use the same
L<Quantization Options|Imager::ImageTypes> as you can when converting
gif_trans_color - A reference to an Imager::Color object, which is the
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.
+the palette. You need to set the C<transp> option (see
+L<Imager::ImageTypes/"Quantization options">) for this value to be
+used.
=item *
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
=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_gamme> 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 *
+
+C<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>X<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
=head2 ICO (Microsoft Windows Icon) and CUR (Microsoft Windows Cursor)
=over
-=item register_reader
+=item register_reader()
Registers single or multiple image read functions.
},
);
-=item register_writer
+=item register_writer()
Registers single or multiple image write functions.
C<Imager::File::>I<your-format-name>C<Writer> and Imager will attempt
to autoload it.
+=head1 PRELOADING FILE MODULES
+
+=over
+
+=item preload()
+
+This preloads the file support modules included with or that have been
+included with Imager in the past. This is intended for use in forking
+servers such as mod_perl.
+
+If the module is not available no error occurs.
+
+Preserves $@.
+
+ use Imager;
+ Imager->preload;
+
+=back
+
=head1 EXAMPLES
=head2 Producing an image from a CGI script
projects / imager.git / blobdiff