move most of README to lib/Imager/Install.pod
[imager.git] / lib / Imager / Files.pod
1 =head1 NAME
2
3 Imager::Files - working with image files
4
5 =head1 SYNOPSIS
6
7   use Imager;
8   my $img = ...;
9   $img->write(file=>$filename, type=>$type)
10     or die "Cannot write: ",$img->errstr;
11
12   # type is optional if we can guess the format from the filename
13   $img->write(file => "foo.png")
14     or die "Cannot write: ",$img->errstr;
15
16   $img = Imager->new;
17   $img->read(file=>$filename, type=>$type)
18     or die "Cannot read: ", $img->errstr;
19
20   # type is optional if we can guess the type from the file data
21   # and we normally can guess
22   $img->read(file => $filename)
23     or die "Cannot read: ", $img->errstr;
24
25   Imager->write_multi({ file=> $filename, ... }, @images)
26     or die "Cannot write: ", Imager->errstr;
27
28   my @imgs = Imager->read_multi(file=>$filename)
29     or die "Cannot read: ", Imager->errstr;
30
31   Imager->set_file_limits(width=>$max_width, height=>$max_height)
32
33   my @read_types = Imager->read_types;
34   my @write_types = Imager->write_types;
35
36   # we can write/write_multi to things other than filenames
37   my $data;
38   $img->write(data => \$data, type => $type) or die;
39
40   my $fh = ... ; # eg. IO::File
41   $img->write(fh => $fh, type => $type) or die;
42
43   $img->write(fd => fileno($fh), type => $type) or die;
44
45   # some file types need seek callbacks too
46   $img->write(callback => \&write_callback, type => $type) or die;
47
48   # and similarly for read/read_multi
49   $img->read(data => $data) or die;
50   $img->read(fh => $fh) or die;
51   $img->read(fd => fileno($fh)) or die;
52   $img->read(callback => \&read_callback) or die;
53
54   use Imager 0.68;
55   my $img = Imager->new(file => $filename)
56     or die Imager->errstr;
57
58 =head1 DESCRIPTION
59
60 You can read and write a variety of images formats, assuming you have
61 the appropriate libraries, and images can be read or written to/from
62 files, file handles, file descriptors, scalars, or through callbacks.
63
64 To see which image formats Imager is compiled to support the following
65 code snippet is sufficient:
66
67   use Imager;
68   print join " ", keys %Imager::formats;
69
70 This will include some other information identifying libraries rather
71 than file formats.  For new code you might find the L</read_types()>
72 or L</write_types()> methods useful.
73
74 =over 
75
76 =item read()
77
78 Reading writing to and from files is simple, use the C<read()>
79 method to read an image:
80
81   my $img = Imager->new;
82   $img->read(file=>$filename, type=>$type)
83     or die "Cannot read $filename: ", $img->errstr;
84
85 In most cases Imager can auto-detect the file type, so you can just
86 supply the file name:
87
88   $img->read(file => $filename)
89     or die "Cannot read $filename: ", $img->errstr;
90
91 The read() method accepts the C<allow_incomplete> parameter.  If this
92 is non-zero then read() can return true on an incomplete image and set
93 the C<i_incomplete> tag.
94
95 From Imager 0.68 you can supply most read() parameters to the new()
96 method to read the image file on creation.  If the read fails, check
97 Imager->errstr() for the cause:
98
99   use Imager 0.68;
100   my $img = Imager->new(file => $filename)
101     or die "Cannot read $filename: ", Imager->errstr;
102
103 =item write()
104
105 and the C<write()> method to write an image:
106
107   $img->write(file=>$filename, type=>$type)
108     or die "Cannot write $filename: ", $img->errstr;
109
110 =item read_multi()
111
112 If you're reading from a format that supports multiple images per
113 file, use the C<read_multi()> method:
114
115   my @imgs = Imager->read_multi(file=>$filename, type=>$type)
116     or die "Cannot read $filename: ", Imager->errstr;
117
118 As with the read() method, Imager will normally detect the C<type>
119 automatically.
120
121 =item write_multi()
122
123 and if you want to write multiple images to a single file use the
124 C<write_multi()> method:
125
126   Imager->write_multi({ file=> $filename, type=>$type }, @images)
127     or die "Cannot write $filename: ", Imager->errstr;
128
129 =item read_types()
130
131 This is a class method that returns a list of the image file types
132 that Imager can read.
133
134   my @types = Imager->read_types;
135
136 These types are the possible values for the C<type> parameter, not
137 necessarily the extension of the files you're reading.
138
139 It is possible for extra file read handlers to be loaded when
140 attempting to read a file, which may modify the list of available read
141 types.
142
143 =item write_types()
144
145 This is a class method that returns a list of the image file types
146 that Imager can write.
147
148   my @types = Imager->write_types;
149
150 Note that these are the possible values for the C<type> parameter, not
151 necessarily the extension of the files you're writing.
152
153 It is possible for extra file write handlers to be loaded when
154 attempting to write a file, which may modify the list of available
155 write types.
156
157 =back
158
159 When writing, if the C<filename> includes an extension that Imager
160 recognizes, then you don't need the C<type>, but you may want to
161 provide one anyway.  See L</Guessing types> for information on
162 controlling this recognition.
163
164 The C<type> parameter is a lowercase representation of the file type,
165 and can be any of the following:
166
167   bmp   Windows BitMaP (BMP)
168   gif   Graphics Interchange Format (GIF)
169   jpeg  JPEG/JFIF
170   png   Portable Network Graphics (PNG)
171   pnm   Portable aNyMap (PNM)
172   raw   Raw
173   sgi   SGI .rgb files
174   tga   TARGA
175   tiff  Tagged Image File Format (TIFF)
176
177 When you read an image, Imager may set some tags, possibly including
178 information about the spatial resolution, textual information, and
179 animation information.  See L<Imager::ImageTypes/Tags> for specifics.
180
181 The open() method is a historical alias for the read() method.
182
183 =head2 Input and output
184
185 When reading or writing you can specify one of a variety of sources or
186 targets:
187
188 =over
189
190 =item *
191
192 C<file> - The C<file> parameter is the name of the image file to be
193 written to or read from.  If Imager recognizes the extension of the
194 file you do not need to supply a C<type>.
195
196   # write in tiff format
197   $image->write(file => "example.tif")
198     or die $image->errstr;
199
200   $image->write(file => 'foo.tmp', type => 'tiff')
201     or die $image->errstr;
202
203   my $image = Imager->new;
204   $image->read(file => 'example.tif')
205     or die $image->errstr;
206
207 =item *
208
209 C<fh> - C<fh> is a file handle, typically either returned from
210 C<<IO::File->new()>>, or a glob from an C<open> call.  You should call
211 C<binmode> on the handle before passing it to Imager.
212
213 Imager will set the handle to autoflush to make sure any buffered data
214 is flushed , since Imager will write to the file descriptor (from
215 fileno()) rather than writing at the perl level.
216
217   $image->write(fh => \*STDOUT, type => 'gif')
218     or die $image->errstr;
219
220   # for example, a file uploaded via CGI.pm
221   $image->read(fd => $cgi->param('file')) 
222     or die $image->errstr;
223
224 =item *
225
226 C<fd> - C<fd> is a file descriptor.  You can get this by calling the
227 C<fileno()> function on a file handle, or by using one of the standard
228 file descriptor numbers.
229
230 If you get this from a perl file handle, you may need to flush any
231 buffered output, otherwise it may appear in the output stream after
232 the image.
233
234   $image->write(fd => file(STDOUT), type => 'gif')
235     or die $image->errstr;
236
237 =item *
238
239 C<data> - When reading data, C<data> is a scalar containing the image
240 file data, when writing, C<data> is a reference to the scalar to save
241 the image file data too.  For GIF images you will need C<giflib> 4 or
242 higher, and you may need to patch C<giflib> to use this option for
243 writing.
244
245   my $data;
246   $image->write(data => \$data, type => 'tiff')
247     or die $image->errstr;
248
249   my $data = $row->{someblob}; # eg. from a database
250   my @images = Imager->read_multi(data => $data)
251     or die Imager->errstr;
252
253 =item *
254
255 C<callback>, C<readcb>, C<writecb>, C<seekcb>, C<closecb> - Imager
256 will make calls back to your supplied coderefs to read, write and seek
257 from/to/through the image file.  See L</"I/O Callbacks"> below for details.
258
259 =item *
260
261 C<io> - an L<Imager::IO> object.
262
263 =back
264
265 X<buffering>X<unbuffered>By default Imager will use buffered I/O when
266 reading or writing an image.  You can disabled buffering for output by
267 supplying a C<< buffered => 0 >> parameter to C<write()> or
268 C<write_multi()>.
269
270 =head2 I/O Callbacks
271
272 When reading from a file you can use either C<callback> or C<readcb>
273 to supply the read callback, and when writing C<callback> or
274 C<writecb> to supply the write callback.
275
276 Whether reading or writing a C<TIFF> image, C<seekcb> and C<readcb>
277 are required.
278
279 If a file handler attempts to use C<readcb>, C<writecb> or C<seekcb>
280 and you haven't supplied one, the call will fail, failing the image
281 read or write, returning an error message indicating that the callback
282 is missing:
283
284   # attempting to read a TIFF image without a seekcb
285   open my $fh, "<", $filename or die;
286   my $rcb = sub {
287     my $val;
288     read($fh, $val, $_[0]) or return "";
289     return $val;
290   };
291   my $im = Imager->new(callback => $rcb)
292     or die Imager->errstr
293   # dies with (wrapped here):
294   # Error opening file: (Iolayer): Failed to read directory at offset 0:
295   # (Iolayer): Seek error accessing TIFF directory: seek callback called
296   # but no seekcb supplied
297
298 You can also provide a C<closecb> parameter called when writing the
299 file is complete.  If no C<closecb> is supplied the default will
300 succeed silently.
301
302   # contrived
303   my $data;
304   sub mywrite {
305     $data .= unpack("H*", shift);
306     1;
307   }
308   Imager->write_multi({ callback => \&mywrite, type => 'gif'}, @images)
309     or die Imager->errstr;
310
311 =head3 C<readcb>
312
313 The read callback is called with 2 parameters:
314
315 =over
316
317 =item *
318
319 C<size> - the minimum amount of data required.
320
321 =item *
322
323 C<maxsize> - previously this was the maximum amount of data returnable
324 - currently it's always the same as C<size>
325
326 =back
327
328 Your read callback should return the data as a scalar:
329
330 =over
331
332 =item *
333
334 on success, a string containing the bytes read.
335
336 =item *
337
338 on end of file, an empty string
339
340 =item *
341
342 on error, C<undef>.
343
344 =back
345
346 If your return value contains more data than C<size> Imager will
347 panic.
348
349 Your return value must not contain any characters over C<\xFF> or
350 Imager will panic.
351
352 =head3 C<writecb>
353
354 Your write callback takes exactly one parameter, a scalar containing
355 the data to be written.
356
357 Return true for success.
358
359 =head3 C<seekcb>
360
361 The seek callback takes 2 parameters, a I<POSITION>, and a I<WHENCE>,
362 defined in the same way as perl's seek function.
363
364 Previously you always needed a C<seekcb> callback if you called
365 Imager's L</read()> or L</read_multi()> without a C<type> parameter,
366 but this is no longer necessary unless the file handler requires
367 seeking, such as for TIFF files.
368
369 Returns the new position in the file, or -1 on failure.
370
371 =head3 C<closecb>
372
373 You can also supply a C<closecb> which is called with no parameters
374 when there is no more data to be written.  This could be used to flush
375 buffered data.
376
377 Return true on success.
378
379 =head2 Guessing types
380 X<FORMATGUESS>
381
382 When writing to a file, if you don't supply a C<type> parameter Imager
383 will attempt to guess it from the file name.  This is done by calling
384 the code reference stored in C<$Imager::FORMATGUESS>.  This is only
385 done when write() or write_multi() is called with a C<file> parameter,
386 or if read() or read_multi() can't determine the type from the file's
387 header.
388
389 The default function value of C<$Imager::FORMATGUESS> is
390 C<\&Imager::def_guess_type>.
391
392 =over
393
394 =item def_guess_type()
395 X<methods, def_guess_type()>
396
397 This is the default function Imager uses to derive a file type from a
398 file name.  This is a function, not a method.
399
400 Accepts a single parameter, the file name and returns the type or
401 undef.
402
403 =back
404
405 You can replace function with your own implementation if you have some
406 specialized need.  The function takes a single parameter, the name of
407 the file, and should return either a file type or under.
408
409   # I'm writing jpegs to weird filenames
410   local $Imager::FORMATGUESS = sub { 'jpeg' };
411
412 When reading a file Imager examines beginning of the file for
413 identifying information.  The current implementation attempts to
414 detect the following image types beyond those supported by Imager:
415
416 =for stopwords Photoshop
417
418 =over
419
420 C<xpm>, C<mng>, C<jng>, C<ilbm>, C<pcx>, C<fits>, C<psd> (Photoshop), C<eps>, Utah
421 C<RLE>.
422
423 =back
424
425 =head2 Limiting the sizes of images you read
426
427 =over
428
429 =item set_file_limits()
430
431 In some cases you will be receiving images from an untested source,
432 such as submissions via CGI.  To prevent such images from consuming
433 large amounts of memory, you can set limits on the dimensions of
434 images you read from files:
435
436 =over
437
438 =item *
439
440 width - limit the width in pixels of the image
441
442 =item *
443
444 height - limit the height in pixels of the image
445
446 =item *
447
448 bytes - limits the amount of storage used by the image.  This depends
449 on the width, height, channels and sample size of the image.  For
450 paletted images this is calculated as if the image was expanded to a
451 direct color image.
452
453 =back
454
455 To set the limits, call the class method set_file_limits:
456
457   Imager->set_file_limits(width=>$max_width, height=>$max_height);
458
459 You can pass any or all of the limits above, any limits you do not
460 pass are left as they were.
461
462 Any limit of zero for width or height is treated as unlimited.
463
464 A limit of zero for bytes is treated as one gigabyte, but higher bytes
465 limits can be set explicitly.
466
467 By default, the width and height limits are zero, or unlimited.  The
468 default memory size limit is one gigabyte.
469
470 You can reset all limits to their defaults with the reset parameter:
471
472   # no limits
473   Imager->set_file_limits(reset=>1);
474
475 This can be used with the other limits to reset all but the limit you
476 pass:
477
478   # only width is limited
479   Imager->set_file_limits(reset=>1, width=>100);
480
481   # only bytes is limited
482   Imager->set_file_limits(reset=>1, bytes=>10_000_000);
483
484 =item get_file_limits()
485
486 You can get the current limits with the get_file_limits() method:
487
488   my ($max_width, $max_height, $max_bytes) =
489      Imager->get_file_limits();
490
491 =item check_file_limits()
492 X<class methods, check_file_limits()>X<check_file_limits()>
493
494 Intended for use by file handlers to check that the size of a file is
495 within the limits set by C<set_file_limits()>.
496
497 Parameters:
498
499 =over
500
501 =item *
502
503 C<width>, C<height> - the width and height of the image in pixels.
504 Must be a positive integer. Required.
505
506 =item *
507
508 C<channels> - the number of channels in the image, including the alpha
509 channel if any.  Must be a positive integer between 1 and 4
510 inclusive.  Default: 3.
511
512 =item *
513
514 C<sample_size> - the number of bytes stored per sample.  Must be a
515 positive integer or C<"float">.  Note that this should be the sample
516 size of the Imager image you will be creating, not the sample size in
517 the source, eg. if the source has 32-bit samples this should be
518 C<"float"> since Imager doesn't have 32-bit/sample images.
519
520 =back
521
522 =back
523
524 =head1 TYPE SPECIFIC INFORMATION
525
526 The different image formats can write different image type, and some have
527 different options to control how the images are written.
528
529 When you call C<write()> or C<write_multi()> with an option that has
530 the same name as a tag for the image format you're writing, then the
531 value supplied to that option will be used to set the corresponding
532 tag in the image.  Depending on the image format, these values will be
533 used when writing the image.
534
535 This replaces the previous options that were used when writing GIF
536 images.  Currently if you use an obsolete option, it will be converted
537 to the equivalent tag and Imager will produced a warning.  You can
538 suppress these warnings by calling the C<Imager::init()> function with
539 the C<warn_obsolete> option set to false:
540
541   Imager::init(warn_obsolete=>0);
542
543 At some point in the future these obsolete options will no longer be
544 supported.
545
546 =for stopwords aNy PixMaps BitMap
547
548 =head2 PNM (Portable aNy Map)
549
550 Imager can write C<PGM> (Portable Gray Map) and C<PPM> (Portable
551 PixMaps) files, depending on the number of channels in the image.
552 Currently the images are written in binary formats.  Only 1 and 3
553 channel images can be written, including 1 and 3 channel paletted
554 images.
555
556   $img->write(file=>'foo.ppm') or die $img->errstr;
557
558 Imager can read both the ASCII and binary versions of each of the
559 C<PBM> (Portable BitMap), C<PGM> and C<PPM> formats.
560
561   $img->read(file=>'foo.ppm') or die $img->errstr;
562
563 PNM does not support the spatial resolution tags.
564
565 The following tags are set when reading a PNM file:
566
567 =over
568
569 =item *
570
571 X<pnm_maxval>C<pnm_maxval> - the C<maxvals> number from the PGM/PPM header.
572 Always set to 2 for a C<PBM> file.
573
574 =item *
575
576 X<pnm_type>C<pnm_type> - the type number from the C<PNM> header, 1 for ASCII
577 C<PBM> files, 2 for ASCII C<PGM> files, 3 for ASCII c<PPM> files, 4 for binary
578 C<PBM> files, 5 for binary C<PGM> files, 6 for binary C<PPM> files.
579
580 =back
581
582 The following tag is checked when writing an image with more than
583 8-bits/sample:
584
585 =over
586
587 =item *
588
589 X<pnm_write_wide_data>pnm_write_wide_data - if this is non-zero then
590 write() can write C<PGM>/C<PPM> files with 16-bits/sample.  Some
591 applications, for example GIMP 2.2, and tools can only read
592 8-bit/sample binary PNM files, so Imager will only write a 16-bit
593 image when this tag is non-zero.
594
595 =back
596
597 =head2 JPEG
598
599 =for stopwords composited
600
601 You can supply a C<jpegquality> parameter (0-100) when writing a JPEG
602 file, which defaults to 75%.  If you write an image with an alpha
603 channel to a JPEG file then it will be composited against the
604 background set by the C<i_background> parameter (or tag).
605
606   $img->write(file=>'foo.jpg', jpegquality=>90) or die $img->errstr;
607
608 Imager will read a gray scale JPEG as a 1 channel image and a color
609 JPEG as a 3 channel image.
610
611   $img->read(file=>'foo.jpg') or die $img->errstr;
612
613 The following tags are set in a JPEG image when read, and can be set
614 to control output:
615
616 =over
617
618 =item *
619
620 C<jpeg_density_unit> - The value of the density unit field in the
621 C<JFIF> header.  This is ignored on writing if the C<i_aspect_only>
622 tag is non-zero.
623
624 The C<i_xres> and C<i_yres> tags are expressed in pixels per inch no
625 matter the value of this tag, they will be converted to/from the value
626 stored in the JPEG file.
627
628 =item *
629
630 C<jpeg_density_unit_name> - This is set when reading a JPEG file to
631 the name of the unit given by C<jpeg_density_unit>.  Possible results
632 include C<inch>, C<centimeter>, C<none> (the C<i_aspect_only> tag is
633 also set reading these files).  If the value of C<jpeg_density_unit>
634 is unknown then this tag isn't set.
635
636 =item *
637
638 C<jpeg_comment> - Text comment.
639
640 =item *
641
642 C<jpeg_progressive> - Whether the JPEG file is a progressive
643 file. (Imager 0.84)
644
645 =back
646
647 JPEG supports the spatial resolution tags C<i_xres>, C<i_yres> and
648 C<i_aspect_only>.
649
650 =for stopwords EXIF
651
652 If an C<APP1> block containing EXIF information is found, then any of the
653 following tags can be set when reading a JPEG image:
654
655 =over
656
657 exif_aperture exif_artist exif_brightness exif_color_space
658 exif_contrast exif_copyright exif_custom_rendered exif_date_time
659 exif_date_time_digitized exif_date_time_original
660 exif_digital_zoom_ratio exif_exposure_bias exif_exposure_index
661 exif_exposure_mode exif_exposure_program exif_exposure_time
662 exif_f_number exif_flash exif_flash_energy exif_flashpix_version
663 exif_focal_length exif_focal_length_in_35mm_film
664 exif_focal_plane_resolution_unit exif_focal_plane_x_resolution
665 exif_focal_plane_y_resolution exif_gain_control exif_image_description
666 exif_image_unique_id exif_iso_speed_rating exif_make exif_max_aperture
667 exif_metering_mode exif_model exif_orientation exif_related_sound_file
668 exif_resolution_unit exif_saturation exif_scene_capture_type
669 exif_sensing_method exif_sharpness exif_shutter_speed exif_software
670 exif_spectral_sensitivity exif_sub_sec_time
671 exif_sub_sec_time_digitized exif_sub_sec_time_original
672 exif_subject_distance exif_subject_distance_range
673 exif_subject_location exif_tag_light_source exif_user_comment
674 exif_version exif_white_balance exif_x_resolution exif_y_resolution
675
676 =back
677
678 The following derived tags can also be set when reading a JPEG image:
679
680 =over
681
682 exif_color_space_name exif_contrast_name exif_custom_rendered_name
683 exif_exposure_mode_name exif_exposure_program_name exif_flash_name
684 exif_focal_plane_resolution_unit_name exif_gain_control_name
685 exif_light_source_name exif_metering_mode_name
686 exif_resolution_unit_name exif_saturation_name
687 exif_scene_capture_type_name exif_sensing_method_name
688 exif_sharpness_name exif_subject_distance_range_name
689 exif_white_balance_name
690
691 =back
692
693 The derived tags are for enumerated fields, when the value for the
694 base field is valid then the text that appears in the EXIF
695 specification for that value appears in the derived field.  So for
696 example if C<exf_metering_mode> is C<5> then
697 C<exif_metering_mode_name> is set to C<Pattern>.
698
699 eg.
700
701   my $image = Imager->new;
702   $image->read(file => 'exiftest.jpg')
703     or die "Cannot load image: ", $image->errstr;
704   print $image->tags(name => "exif_image_description"), "\n";
705   print $image->tags(name => "exif_exposure_mode"), "\n";
706   print $image->tags(name => "exif_exposure_mode_name"), "\n";
707
708   # for the exiftest.jpg in the Imager distribution the output would be:
709   Imager Development Notes
710   0
711   Auto exposure
712
713 Imager will not write EXIF tags to any type of image, if you need more
714 advanced EXIF handling, consider L<Image::ExifTool>.
715
716 =for stopwords IPTC
717
718 =over
719
720 =item parseiptc()
721
722 Historically, Imager saves IPTC data when reading a JPEG image, the
723 parseiptc() method returns a list of key/value pairs resulting from a
724 simple decoding of that data.
725
726 Any future IPTC data decoding is likely to go into tags.
727
728 =back
729
730 =head2 GIF
731
732 When writing one of more GIF images you can use the same
733 L<Quantization Options|Imager::ImageTypes> as you can when converting
734 an RGB image into a paletted image.
735
736 When reading a GIF all of the sub-images are combined using the screen
737 size and image positions into one big image, producing an RGB image.
738 This may change in the future to produce a paletted image where possible.
739
740 When you read a single GIF with C<$img-E<gt>read()> you can supply a
741 reference to a scalar in the C<colors> parameter, if the image is read
742 the scalar will be filled with a reference to an anonymous array of
743 L<Imager::Color> objects, representing the palette of the image.  This
744 will be the first palette found in the image.  If you want the
745 palettes for each of the images in the file, use C<read_multi()> and
746 use the C<getcolors()> method on each image.
747
748 GIF does not support the spatial resolution tags.
749
750 Imager will set the following tags in each image when reading, and can
751 use most of them when writing to GIF:
752
753 =over
754
755 =item *
756
757 gif_left - the offset of the image from the left of the "screen"
758 ("Image Left Position")
759
760 =item *
761
762 gif_top - the offset of the image from the top of the "screen" ("Image
763 Top Position")
764
765 =item *
766
767 gif_interlace - non-zero if the image was interlaced ("Interlace
768 Flag")
769
770 =item *
771
772 gif_screen_width, gif_screen_height - the size of the logical
773 screen. When writing this is used as the minimum.  If any image being
774 written would extend beyond this then the screen size is extended.
775 ("Logical Screen Width", "Logical Screen Height").
776
777 =item *
778
779 gif_local_map - Non-zero if this image had a local color map.  If set
780 for an image when writing the image is quantized separately from the
781 other images in the file.
782
783 =item *
784
785 gif_background - The index in the global color map of the logical
786 screen's background color.  This is only set if the current image uses
787 the global color map.  You can set this on write too, but for it to
788 choose the color you want, you will need to supply only paletted
789 images and set the C<gif_eliminate_unused> tag to 0.
790
791 =item *
792
793 gif_trans_index - The index of the color in the color map used for
794 transparency.  If the image has a transparency then it is returned as
795 a 4 channel image with the alpha set to zero in this palette entry.
796 This value is not used when writing. ("Transparent Color Index")
797
798 =item *
799
800 gif_trans_color - A reference to an Imager::Color object, which is the
801 color to use for the palette entry used to represent transparency in
802 the palette.  You need to set the C<transp> option (see
803 L<Imager::ImageTypes/"Quantization options">) for this value to be
804 used.
805
806 =item *
807
808 gif_delay - The delay until the next frame is displayed, in 1/100 of a
809 second.  ("Delay Time").
810
811 =item *
812
813 gif_user_input - whether or not a user input is expected before
814 continuing (view dependent) ("User Input Flag").
815
816 =item *
817
818 gif_disposal - how the next frame is displayed ("Disposal Method")
819
820 =item *
821
822 gif_loop - the number of loops from the Netscape Loop extension.  This
823 may be zero to loop forever.
824
825 =item *
826
827 gif_comment - the first block of the first GIF comment before each
828 image.
829
830 =item *
831
832 gif_eliminate_unused - If this is true, when you write a paletted
833 image any unused colors will be eliminated from its palette.  This is
834 set by default.
835
836 =item *
837
838 gif_colormap_size - the original size of the color map for the image.
839 The color map of the image may have been expanded to include out of
840 range color indexes.
841
842 =back
843
844 Where applicable, the ("name") is the name of that field from the C<GIF89>
845 standard.
846
847 The following GIF writing options are obsolete, you should set the
848 corresponding tag in the image, either by using the tags functions, or
849 by supplying the tag and value as options.
850
851 =over
852
853 =item *
854
855 gif_each_palette - Each image in the GIF file has it's own palette if
856 this is non-zero.  All but the first image has a local color table
857 (the first uses the global color table.
858
859 Use C<gif_local_map> in new code.
860
861 =item *
862
863 interlace - The images are written interlaced if this is non-zero.
864
865 Use C<gif_interlace> in new code.
866
867 =item *
868
869 gif_delays - A reference to an array containing the delays between
870 images, in 1/100 seconds.
871
872 Use C<gif_delay> in new code.
873
874 =item *
875
876 gif_positions - A reference to an array of references to arrays which
877 represent screen positions for each image.
878
879 New code should use the C<gif_left> and C<gif_top> tags.
880
881 =item *
882
883 gif_loop_count - If this is non-zero the Netscape loop extension block
884 is generated, which makes the animation of the images repeat.
885
886 This is currently unimplemented due to some limitations in C<giflib>.
887
888 =back
889
890 You can supply a C<page> parameter to the C<read()> method to read
891 some page other than the first.  The page is 0 based:
892
893   # read the second image in the file
894   $image->read(file=>"example.gif", page=>1)
895     or die "Cannot read second page: ",$image->errstr,"\n";
896
897 Before release 0.46, Imager would read multiple image GIF image files
898 into a single image, overlaying each of the images onto the virtual
899 GIF screen.
900
901 As of 0.46 the default is to read the first image from the file, as if
902 called with C<< page => 0 >>.
903
904 You can return to the previous behavior by calling read with the
905 C<gif_consolidate> parameter set to a true value:
906
907   $img->read(file=>$some_gif_file, gif_consolidate=>1);
908
909 As with the to_paletted() method, if you supply a colors parameter as
910 a reference to an array, this will be filled with Imager::Color
911 objects of the color table generated for the image file.
912
913 =head2 TIFF (Tagged Image File Format)
914
915 Imager can write images to either paletted or RGB TIFF images,
916 depending on the type of the source image.
917
918 When writing direct color images to TIFF the sample size of the
919 output file depends on the input:
920
921 =over
922
923 =item *
924
925 double/sample - written as 32-bit/sample TIFF
926
927 =item *
928
929 16-bit/sample - written as 16-bit/sample TIFF
930
931 =item *
932
933 8-bit/sample - written as 8-bit/sample TIFF
934
935 =back
936
937 For paletted images:
938
939 =over
940
941 =item *
942
943 C<< $img->is_bilevel >> is true - the image is written as bi-level
944
945 =item *
946
947 otherwise - image is written as paletted.
948
949 =back
950
951 If you are creating images for faxing you can set the I<class>
952 parameter set to C<fax>.  By default the image is written in fine
953 mode, but this can be overridden by setting the I<fax_fine> parameter
954 to zero.  Since a fax image is bi-level, Imager uses a threshold to
955 decide if a given pixel is black or white, based on a single channel.
956 For gray scale images channel 0 is used, for color images channel 1
957 (green) is used.  If you want more control over the conversion you can
958 use $img->to_paletted() to product a bi-level image.  This way you can
959 use dithering:
960
961   my $bilevel = $img->to_paletted(make_colors => 'mono',
962                                   translate => 'errdiff',
963                                   errdiff => 'stucki');
964
965 =over
966
967 =item *
968
969 C<class> - If set to 'fax' the image will be written as a bi-level fax
970 image.
971
972 =item *
973
974 C<fax_fine> - By default when C<class> is set to 'fax' the image is
975 written in fine mode, you can select normal mode by setting
976 C<fax_fine> to 0.
977
978 =back
979
980 Imager should be able to read any TIFF image you supply.  Paletted
981 TIFF images are read as paletted Imager images, since paletted TIFF
982 images have 16-bits/sample (48-bits/color) this means the bottom
983 8-bits are lost, but this shouldn't be a big deal.
984
985 TIFF supports the spatial resolution tags.  See the
986 C<tiff_resolutionunit> tag for some extra options.
987
988 As of Imager 0.62 Imager reads:
989
990 =over
991
992 =item *
993
994 8-bit/sample gray, RGB or CMYK images, including a possible alpha
995 channel as an 8-bit/sample image.
996
997 =item *
998
999 16-bit gray, RGB, or CMYK image, including a possible alpha channel as
1000 a 16-bit/sample image.
1001
1002 =item *
1003
1004 32-bit gray, RGB image, including a possible alpha channel as a
1005 double/sample image.
1006
1007 =item *
1008
1009 bi-level images as paletted images containing only black and white,
1010 which other formats will also write as bi-level.
1011
1012 =item *
1013
1014 tiled paletted images are now handled correctly
1015
1016 =item *
1017
1018 other images are read using C<tifflib>'s RGBA interface as
1019 8-bit/sample images.
1020
1021 =back
1022
1023 The following tags are set in a TIFF image when read, and can be set
1024 to control output:
1025
1026 =over
1027
1028 =item *
1029
1030 C<tiff_compression> - When reading an image this is set to the numeric
1031 value of the TIFF compression tag.
1032
1033 On writing you can set this to either a numeric compression tag value,
1034 or one of the following values:
1035
1036   Ident     Number  Description
1037   none         1    No compression
1038   packbits   32773  Macintosh RLE
1039   ccittrle     2    CCITT RLE
1040   fax3         3    CCITT Group 3 fax encoding (T.4)
1041   t4           3    As above
1042   fax4         4    CCITT Group 4 fax encoding (T.6)
1043   t6           4    As above
1044   lzw          5    LZW
1045   jpeg         7    JPEG
1046   zip          8    Deflate (GZIP) Non-standard
1047   deflate      8    As above.
1048   oldzip     32946  Deflate with an older code.
1049   ccittrlew  32771  Word aligned CCITT RLE
1050
1051 In general a compression setting will be ignored where it doesn't make
1052 sense, eg. C<jpeg> will be ignored for compression if the image is
1053 being written as bilevel.
1054
1055 =for stopwords LZW
1056
1057 Imager attempts to check that your build of C<libtiff> supports the
1058 given compression, and will fallback to C<packbits> if it isn't
1059 enabled.  eg. older distributions didn't include LZW compression, and
1060 JPEG compression is only available if C<libtiff> is configured with
1061 C<libjpeg>'s location.
1062
1063   $im->write(file => 'foo.tif', tiff_compression => 'lzw')
1064     or die $im->errstr;
1065
1066 =item *
1067
1068 C<tags, tiff_jpegquality>C<tiff_jpegquality> - If C<tiff_compression>
1069 is C<jpeg> then this can be a number from 1 to 100 giving the JPEG
1070 compression quality.  High values are better quality and larger files.
1071
1072 =item *
1073
1074 X<tags, tiff_resolutionunit>C<tiff_resolutionunit> - The value of the
1075 C<ResolutionUnit> tag.  This is ignored on writing if the
1076 i_aspect_only tag is non-zero.
1077
1078 The C<i_xres> and C<i_yres> tags are expressed in pixels per inch no
1079 matter the value of this tag, they will be converted to/from the value
1080 stored in the TIFF file.
1081
1082 =item *
1083
1084 X<tags, tiff_resolutionunit_name>C<tiff_resolutionunit_name> - This is
1085 set when reading a TIFF file to the name of the unit given by
1086 C<tiff_resolutionunit>.  Possible results include C<inch>,
1087 C<centimeter>, C<none> (the C<i_aspect_only> tag is also set reading
1088 these files) or C<unknown>.
1089
1090 =item *
1091
1092 X<tags, tiff_bitspersample>C<tiff_bitspersample> - Bits per sample
1093 from the image.  This value is not used when writing an image, it is
1094 only set on a read image.
1095
1096 =item *
1097
1098 X<tags, tiff_photometric>C<tiff_photometric> - Value of the
1099 C<PhotometricInterpretation> tag from the image.  This value is not
1100 used when writing an image, it is only set on a read image.
1101
1102 =item *
1103
1104 C<tiff_documentname>, C<tiff_imagedescription>, C<tiff_make>,
1105 C<tiff_model>, C<tiff_pagename>, C<tiff_software>, C<tiff_datetime>,
1106 C<tiff_artist>, C<tiff_hostcomputer> - Various strings describing the
1107 image.  C<tiff_datetime> must be formatted as "YYYY:MM:DD HH:MM:SS".
1108 These correspond directly to the mixed case names in the TIFF
1109 specification.  These are set in images read from a TIFF and saved
1110 when writing a TIFF image.
1111
1112 =back
1113
1114 You can supply a C<page> parameter to the C<read()> method to read
1115 some page other than the first.  The page is 0 based:
1116
1117   # read the second image in the file
1118   $image->read(file=>"example.tif", page=>1)
1119     or die "Cannot read second page: ",$image->errstr,"\n";
1120
1121 If you read an image with multiple alpha channels, then only the first
1122 alpha channel will be read.
1123
1124 When reading a C<TIFF> image with callbacks, the C<seekcb> callback
1125 parameter is also required.
1126
1127 When writing a C<TIFF> image with callbacks, the C<seekcb> and
1128 C<readcb> parameters are also required.
1129
1130 C<TIFF> is a random access file format, it cannot be read from or
1131 written to unseekable streams such as pipes or sockets.
1132
1133 =head2 BMP (Windows Bitmap)
1134
1135 Imager can write 24-bit RGB, and 8, 4 and 1-bit per pixel paletted
1136 Windows BMP files.  Currently you cannot write compressed BMP files
1137 with Imager.
1138
1139 Imager can read 24-bit RGB, and 8, 4 and 1-bit perl pixel paletted
1140 Windows BMP files.  There is some support for reading 16-bit per pixel
1141 images, but I haven't found any for testing.
1142
1143 BMP has no support for multiple image files.
1144
1145 BMP files support the spatial resolution tags, but since BMP has no
1146 support for storing only an aspect ratio, if C<i_aspect_only> is set
1147 when you write the C<i_xres> and C<i_yres> values are scaled so the
1148 smaller is 72 DPI.
1149
1150 The following tags are set when you read an image from a BMP file:
1151
1152 =over
1153
1154 =item bmp_compression
1155
1156 The type of compression, if any.  This can be any of the following
1157 values:
1158
1159 =for stopwords RLE
1160
1161 =over
1162
1163 =item BI_RGB (0)
1164
1165 Uncompressed.
1166
1167 =item BI_RLE8 (1)
1168
1169 8-bits/pixel paletted value RLE compression.
1170
1171 =item BI_RLE4 (2)
1172
1173 4-bits/pixel paletted value RLE compression.
1174
1175 =item BI_BITFIELDS (3)
1176
1177 Packed RGB values.
1178
1179 =back
1180
1181 =item bmp_compression_name
1182
1183 The bmp_compression value as a BI_* string
1184
1185 =item bmp_important_colors
1186
1187 The number of important colors as defined by the writer of the image.
1188
1189 =item bmp_used_colors
1190
1191 Number of color used from the BMP header
1192
1193 =item bmp_filesize
1194
1195 The file size from the BMP header
1196
1197 =item bmp_bit_count
1198
1199 Number of bits stored per pixel. (24, 8, 4 or 1)
1200
1201 =back
1202
1203 =for stopwords Targa
1204
1205 =head2 TGA (Targa)
1206
1207 When storing Targa images RLE compression can be activated with the
1208 C<compress> parameter, the C<idstring> parameter can be used to set the
1209 Targa comment field and the C<wierdpack> option can be used to use the
1210 15 and 16 bit Targa formats for RGB and RGBA data.  The 15 bit format
1211 has 5 of each red, green and blue.  The 16 bit format in addition
1212 allows 1 bit of alpha.  The most significant bits are used for each
1213 channel.
1214
1215 Tags:
1216
1217 =over
1218
1219 =item tga_idstring
1220
1221 =item tga_bitspp
1222
1223 =item compressed
1224
1225 =back
1226
1227 =head2 RAW
1228
1229 When reading raw images you need to supply the width and height of the
1230 image in the C<xsize> and C<ysize> options:
1231
1232   $img->read(file=>'foo.raw', xsize=>100, ysize=>100)
1233     or die "Cannot read raw image\n";
1234
1235 If your input file has more channels than you want, or (as is common),
1236 junk in the fourth channel, you can use the C<datachannels> and
1237 C<storechannels> options to control the number of channels in your input
1238 file and the resulting channels in your image.  For example, if your
1239 input image uses 32-bits per pixel with red, green, blue and junk
1240 values for each pixel you could do:
1241
1242   $img->read(file=>'foo.raw', xsize=>100, ysize=>100, datachannels=>4,
1243              storechannels=>3)
1244     or die "Cannot read raw image\n";
1245
1246 Read parameters:
1247
1248 =over
1249
1250 =item *
1251
1252 raw_interleave - controls the ordering of samples within the image.
1253 Default: 1.  Alternatively and historically spelled C<interleave>.
1254 Possible values:
1255
1256 =over
1257
1258 =item *
1259
1260 0 - samples are pixel by pixel, so all samples for the first pixel,
1261 then all samples for the second pixel and so on.  eg. for a four pixel
1262 scan line the channels would be laid out as:
1263
1264   012012012012
1265
1266 =item *
1267
1268 1 - samples are line by line, so channel 0 for the entire scan line is
1269 followed by channel 1 for the entire scan line and so on.  eg. for a
1270 four pixel scan line the channels would be laid out as:
1271
1272   000011112222
1273
1274 This is the default.
1275
1276 =back
1277
1278 Unfortunately, historically, the default C<raw_interleave> for read
1279 has been 1, while writing only supports the C<raw_interleave> = 0
1280 format.
1281
1282 For future compatibility, you should always supply the
1283 C<raw_interleave> (or C<interleave>) parameter.  As of 0.68, Imager
1284 will warn if you attempt to read a raw image without a
1285 C<raw_interleave> parameter.
1286
1287 =item *
1288
1289 raw_storechannels - the number of channels to store in the image.
1290 Range: 1 to 4.  Default: 3.  Alternatively and historically spelled
1291 C<storechannels>.
1292
1293 =item *
1294
1295 raw_datachannels - the number of channels to read from the file.
1296 Range: 1 or more.  Default: 3.  Alternatively and historically spelled
1297 C<datachannels>.
1298
1299 =back
1300
1301   $img->read(file=>'foo.raw', xsize=100, ysize=>100, raw_interleave=>1)
1302     or die "Cannot read raw image\n";
1303
1304 =head2 PNG
1305
1306 =head3 PNG Image modes
1307
1308 PNG files can be read and written in the following modes:
1309
1310 =over
1311
1312 =item *
1313
1314 bi-level - written as a 1-bit per sample gray scale image
1315
1316 =item *
1317
1318 paletted - Imager gray scale paletted images are written as RGB
1319 paletted images.  PNG palettes can include alpha values for each entry
1320 and this is honored as an Imager four channel paletted image.
1321
1322 =item *
1323
1324 8 and 16-bit per sample gray scale, optionally with an alpha channel.
1325
1326 =item *
1327
1328 8 and 16-bit per sample RGB, optionally with an alpha channel.
1329
1330 =back
1331
1332 Unlike GIF, there is no automatic conversion to a paletted image,
1333 since PNG supports direct color.
1334
1335 =head3 PNG Text tags
1336
1337 Text tags are retrieved from and written to PNG C<tEXT> or C<zTXT>
1338 chunks.  The following standard tags from the PNG specification are
1339 directly supported:
1340
1341 =over
1342
1343 =item *
1344
1345 C<i_comment>X<tags,i_comment> - keyword of "Comment".
1346
1347 =item *
1348
1349 C<png_author>X<tags,PNG,png_author> - keyword "Author".
1350
1351 =item *
1352
1353 C<png_copyright>X<tags,PNG,png_copyright> - keyword "Copyright".
1354
1355 =item *
1356
1357 C<png_creation_time>X<tags,PNG,png_creation_time> - keyword "Creation Time".
1358
1359 =item *
1360
1361 C<png_description>X<tags,PNG,png_description> - keyword "Description".
1362
1363 =item *
1364
1365 C<png_disclaimer>X<tags,PNG,png_disclaimer> - keyword "Disclaimer".
1366
1367 =item *
1368
1369 C<png_software>X<tags,PNG,png_software> - keyword "Software".
1370
1371 =item *
1372
1373 C<png_title>X<tags,PNG,png_title> - keyword "Title".
1374
1375 =item *
1376
1377 C<png_warning>X<tags,PNG,png_warning> - keyword "Warning".
1378
1379 =back
1380
1381 Each of these tags has a corresponding C<< I<base-tag-name>_compressed
1382 >> tag, eg. C<png_comment_compressed>.  When reading, if the PNG chunk
1383 is compressed this tag will be set to 1, but is otherwise unset.  When
1384 writing, Imager will honor the compression tag if set and non-zero,
1385 otherwise the chunk text will be compressed if the value is longer
1386 than 1000 characters, as recommended by the C<libpng> documentation.
1387
1388 PNG C<tEXT> or C<zTXT> chunks outside of those above are read into or
1389 written from Imager tags named like:
1390
1391 =over
1392
1393 =item *
1394
1395 C<< png_textI<N>_key >> - the key for the text chunk.  This can be 1
1396 to 79 characters, may not contain any leading, trailing or consecutive
1397 spaces, and may contain only Latin-1 characters from 32-126, 161-255.
1398
1399 =item *
1400
1401 C<< png_textI<N>_text >> - the text for the text chunk.  This may not
1402 contain any C<NUL> characters.
1403
1404 =item *
1405
1406 C<< png_textI<N>_compressed >> - whether or not the text chunk is
1407 compressed.  This behaves similarly to the C<<
1408 I<base-tag-name>_compressed >> tags described above.
1409
1410 =back
1411
1412 Where I<N> starts from 0.  When writing both the C<..._key> and
1413 C<..._text> tags must be present or the write will fail.  If the key
1414 or text do not satisfy the requirements above the write will fail.
1415
1416 =head3 Other PNG metadata tags
1417
1418 =over
1419
1420 =item *
1421
1422 X<tags, png_interlace>C<png_interlace>, C<png_interlace_name> - only
1423 set when reading, C<png_interlace> is set to the type of interlacing
1424 used by the file, 0 for one, 1 for Adam7.  C<png_interlace_name> is
1425 set to a keyword describing the interlacing, either C<none> or
1426 C<adam7>.
1427
1428 =item *
1429
1430 X<tags, png_srgb_intent>C<png_srgb_intent> - the sRGB rendering intent
1431 for the image. an integer from 0 to 3, per the PNG specification.  If
1432 this chunk is found in the PNG file the C<gAMA> and C<cHRM> are
1433 ignored and the C<png_gamme> and C<png_chroma_...> tags are not set.
1434 Similarly when writing if C<png_srgb_intent> is set the C<gAMA> and
1435 C<cHRM> chunks are not written.
1436
1437 =item *
1438
1439 X<tags, png_gamma>C<png_gamma> - the gamma of the image. This value is
1440 not currently used by Imager when processing the image, but this may
1441 change in the future.
1442
1443 =item *
1444
1445 X<tags, png_chroma_...>C<png_chroma_white_x>, C<png_chroma_white_y>,
1446 C<png_chroma_red_x>, C<png_chroma_red_y>, C<png_chroma_green_x>,
1447 C<png_chroma_green_y>, C<png_chroma_blue_x>, C<png_chroma_blue_y> -
1448 the primary chromaticities of the image, defining the color model.
1449 This is currently not used by Imager when processing the image, but
1450 this may change in the future.
1451
1452 =item *
1453
1454 C<i_xres>, C<i_yres>, C<i_aspect_only> - processed per
1455 I<Imager::ImageTypes/CommonTags>.
1456
1457 =item *
1458
1459 X<tags, png_bits>C<png_bits> - the number of bits per sample in the
1460 representation.  Ignored when writing.
1461
1462 =item *
1463
1464 X<tags, png_time>C<png_time> - the creation time of the file formatted
1465 as C<< I<year>-I<month>-I<day>TI<hour>:I<minute>:I<second> >>.  This
1466 is stored as time data structure in the file, not a string.  If you
1467 set C<png_time> and it cannot be parsed as above, writing the PNG file
1468 will fail.
1469
1470 =item *
1471
1472 C<i_background> - set from the C<sBKG> when reading an image file.
1473
1474 =back
1475
1476 =head2 ICO (Microsoft Windows Icon) and CUR (Microsoft Windows Cursor)
1477
1478 Icon and Cursor files are very similar, the only differences being a
1479 number in the header and the storage of the cursor hot spot.  I've
1480 treated them separately so that you're not messing with tags to
1481 distinguish between them.
1482
1483 The following tags are set when reading an icon image and are used
1484 when writing it:
1485
1486 =over
1487
1488 =item ico_mask
1489
1490 This is the AND mask of the icon.  When used as an icon in Windows 1
1491 bits in the mask correspond to pixels that are modified by the source
1492 image rather than simply replaced by the source image.
1493
1494 Rather than requiring a binary bitmap this is accepted in a specific format:
1495
1496 =over
1497
1498 =item *
1499
1500 first line consisting of the 0 placeholder, the 1 placeholder and a
1501 newline.
1502
1503 =item *
1504
1505 following lines which contain 0 and 1 placeholders for each scan line
1506 of the image, starting from the top of the image.
1507
1508 =back
1509
1510 When reading an image, '.' is used as the 0 placeholder and '*' as the
1511 1 placeholder.  An example:
1512
1513   .*
1514   ..........................******
1515   ..........................******
1516   ..........................******
1517   ..........................******
1518   ...........................*****
1519   ............................****
1520   ............................****
1521   .............................***
1522   .............................***
1523   .............................***
1524   .............................***
1525   ..............................**
1526   ..............................**
1527   ...............................*
1528   ...............................*
1529   ................................
1530   ................................
1531   ................................
1532   ................................
1533   ................................
1534   ................................
1535   *...............................
1536   **..............................
1537   **..............................
1538   ***.............................
1539   ***.............................
1540   ****............................
1541   ****............................
1542   *****...........................
1543   *****...........................
1544   *****...........................
1545   *****...........................
1546
1547 =back
1548
1549 The following tags are set when reading an icon:
1550
1551 =over
1552
1553 =item ico_bits
1554
1555 The number of bits per pixel used to store the image.
1556
1557 =back
1558
1559 For cursor files the following tags are set and read when reading and
1560 writing:
1561
1562 =over
1563
1564 =item cur_mask
1565
1566 This is the same as the ico_mask above.
1567
1568 =item cur_hotspotx
1569
1570 =item cur_hotspoty
1571
1572 The "hot" spot of the cursor image.  This is the spot on the cursor
1573 that you click with.  If you set these to out of range values they are
1574 clipped to the size of the image when written to the file.
1575
1576 =back
1577
1578 The following parameters can be supplied to read() or read_multi() to
1579 control reading of ICO/CUR files:
1580
1581 =over
1582
1583 =item *
1584
1585 ico_masked - if true, the default, then the icon/cursors mask is
1586 applied as an alpha channel to the image.  This may result in a
1587 paletted image being returned as a direct color image.  Default: 1
1588
1589   # retrieve the image as stored, without using the mask as an alpha
1590   # channel
1591   $img->read(file => 'foo.ico', ico_masked => 0)
1592     or die $img->errstr;
1593
1594 This was introduced in Imager 0.60.  Previously reading ICO images
1595 acted as if C<ico_masked =E<gt> 0>.
1596
1597 =back
1598
1599 C<cur_bits> is set when reading a cursor.
1600
1601 Examples:
1602
1603   my $img = Imager->new(xsize => 32, ysize => 32, channels => 4);
1604   $im->box(color => 'FF0000');
1605   $im->write(file => 'box.ico');
1606
1607   $im->settag(name => 'cur_hotspotx', value => 16);
1608   $im->settag(name => 'cur_hotspoty', value => 16);
1609   $im->write(file => 'box.cur');
1610
1611 =for stopwords BW
1612
1613 =head2 SGI (RGB, BW)
1614
1615 SGI images, often called by the extensions, RGB or BW, can be stored
1616 either uncompressed or compressed using an RLE compression.
1617
1618 By default, when saving to an extension of C<rgb>, C<bw>, C<sgi>,
1619 C<rgba> the file will be saved in SGI format.  The file extension is
1620 otherwise ignored, so saving a 3-channel image to a C<.bw> file will
1621 result in a 3-channel image on disk.
1622
1623 The following tags are set when reading a SGI image:
1624
1625 =over
1626
1627 =item *
1628
1629 i_comment - the C<IMAGENAME> field from the image.  Also written to
1630 the file when writing.
1631
1632 =item *
1633
1634 sgi_pixmin, sgi_pixmax - the C<PIXMIN> and C<PIXMAX> fields from the
1635 image.  On reading image data is expanded from this range to the full
1636 range of samples in the image.
1637
1638 =item *
1639
1640 sgi_bpc - the number of bytes per sample for the image.  Ignored when
1641 writing.
1642
1643 =item *
1644
1645 sgi_rle - whether or not the image is compressed.  If this is non-zero
1646 when writing the image will be compressed.
1647
1648 =back
1649
1650 =head1 ADDING NEW FORMATS
1651
1652 To support a new format for reading, call the register_reader() class
1653 method:
1654
1655 =over
1656
1657 =item register_reader()
1658
1659 Registers single or multiple image read functions.
1660
1661 Parameters:
1662
1663 =over
1664
1665 =item *
1666
1667 type - the identifier of the file format, if Imager's
1668 i_test_format_probe() can identify the format then this value should
1669 match i_test_format_probe()'s result.
1670
1671 This parameter is required.
1672
1673 =item *
1674
1675 single - a code ref to read a single image from a file.  This is
1676 supplied:
1677
1678 =over
1679
1680 =item *
1681
1682 the object that read() was called on,
1683
1684 =item *
1685
1686 an Imager::IO object that should be used to read the file, and
1687
1688 =item *
1689
1690 all the parameters supplied to the read() method.
1691
1692 =back
1693
1694 The single parameter is required.
1695
1696 =item *
1697
1698 multiple - a code ref which is called to read multiple images from a
1699 file. This is supplied:
1700
1701 =over
1702
1703 =item *
1704
1705 an Imager::IO object that should be used to read the file, and
1706
1707 =item *
1708
1709 all the parameters supplied to the read_multi() method.
1710
1711 =back
1712
1713 =back
1714
1715 Example:
1716
1717   # from Imager::File::ICO
1718   Imager->register_reader
1719     (
1720      type=>'ico',
1721      single => 
1722      sub { 
1723        my ($im, $io, %hsh) = @_;
1724        $im->{IMG} = i_readico_single($io, $hsh{page} || 0);
1725
1726        unless ($im->{IMG}) {
1727          $im->_set_error(Imager->_error_as_msg);
1728          return;
1729        }
1730        return $im;
1731      },
1732      multiple =>
1733      sub {
1734        my ($io, %hsh) = @_;
1735      
1736        my @imgs = i_readico_multi($io);
1737        unless (@imgs) {
1738          Imager->_set_error(Imager->_error_as_msg);
1739          return;
1740        }
1741        return map { 
1742          bless { IMG => $_, DEBUG => $Imager::DEBUG, ERRSTR => undef }, 'Imager'
1743        } @imgs;
1744      },
1745     );
1746
1747 =item register_writer()
1748
1749 Registers single or multiple image write functions.
1750
1751 Parameters:
1752
1753 =over
1754
1755 =item *
1756
1757 type - the identifier of the file format.  This is typically the
1758 extension in lowercase.
1759
1760 This parameter is required.
1761
1762 =item *
1763
1764 single - a code ref to write a single image to a file.  This is
1765 supplied:
1766
1767 =over
1768
1769 =item *
1770
1771 the object that write() was called on,
1772
1773 =item *
1774
1775 an Imager::IO object that should be used to write the file, and
1776
1777 =item *
1778
1779 all the parameters supplied to the write() method.
1780
1781 =back
1782
1783 The single parameter is required.
1784
1785 =item *
1786
1787 multiple - a code ref which is called to write multiple images to a
1788 file. This is supplied:
1789
1790 =over
1791
1792 =item *
1793
1794 the class name write_multi() was called on, this is typically
1795 C<Imager>.
1796
1797 =item *
1798
1799 an Imager::IO object that should be used to write the file, and
1800
1801 =item *
1802
1803 all the parameters supplied to the read_multi() method.
1804
1805 =back
1806
1807 =back
1808
1809 =back
1810
1811 If you name the reader module C<Imager::File::>I<your-format-name>
1812 where I<your-format-name> is a fully upper case version of the type
1813 value you would pass to read(), read_multi(), write() or write_multi()
1814 then Imager will attempt to load that module if it has no other way to
1815 read or write that format.
1816
1817 For example, if you create a module Imager::File::GIF and the user has
1818 built Imager without it's normal GIF support then an attempt to read a
1819 GIF image will attempt to load Imager::File::GIF.
1820
1821 If your module can only handle reading then you can name your module
1822 C<Imager::File::>I<your-format-name>C<Reader> and Imager will attempt
1823 to autoload it.
1824
1825 If your module can only handle writing then you can name your module 
1826 C<Imager::File::>I<your-format-name>C<Writer> and Imager will attempt
1827 to autoload it.
1828
1829 =head1 PRELOADING FILE MODULES
1830
1831 =over
1832
1833 =item preload()
1834
1835 This preloads the file support modules included with or that have been
1836 included with Imager in the past.  This is intended for use in forking
1837 servers such as mod_perl.
1838
1839 If the module is not available no error occurs.
1840
1841 Preserves $@.
1842
1843   use Imager;
1844   Imager->preload;
1845
1846 =back
1847
1848 =head1 EXAMPLES
1849
1850 =head2 Producing an image from a CGI script
1851
1852 Once you have an image the basic mechanism is:
1853
1854 =for stopwords STDOUT
1855
1856 =over
1857
1858 =item 1.
1859
1860 set STDOUT to autoflush
1861
1862 =item 2.
1863
1864 output a content-type header, and optionally a content-length header
1865
1866 =item 3.
1867
1868 put STDOUT into binmode
1869
1870 =item 4.
1871
1872 call write() with the C<fd> or C<fh> parameter.  You will need to
1873 provide the C<type> parameter since Imager can't use the extension to
1874 guess the file format you want.
1875
1876 =back
1877
1878   # write an image from a CGI script
1879   # using CGI.pm
1880   use CGI qw(:standard);
1881   $| = 1;
1882   binmode STDOUT;
1883   print header(-type=>'image/gif');
1884   $img->write(type=>'gif', fd=>fileno(STDOUT))
1885     or die $img->errstr;
1886
1887 If you want to send a content length you can send the output to a
1888 scalar to get the length:
1889
1890   my $data;
1891   $img->write(type=>'gif', data=>\$data)
1892     or die $img->errstr;
1893   binmode STDOUT;
1894   print header(-type=>'image/gif', -content_length=>length($data));
1895   print $data;
1896
1897 =head2 Writing an animated GIF
1898
1899 The basic idea is simple, just use write_multi():
1900
1901   my @imgs = ...;
1902   Imager->write_multi({ file=>$filename, type=>'gif' }, @imgs);
1903
1904 If your images are RGB images the default quantization mechanism will
1905 produce a very good result, but can take a long time to execute.  You
1906 could either use the standard web color map:
1907
1908   Imager->write_multi({ file=>$filename, 
1909                         type=>'gif',
1910                         make_colors=>'webmap' },
1911                       @imgs);
1912
1913 or use a median cut algorithm to built a fairly optimal color map:
1914
1915   Imager->write_multi({ file=>$filename,
1916                         type=>'gif',
1917                         make_colors=>'mediancut' },
1918                       @imgs);
1919
1920 By default all of the images will use the same global color map, which
1921 will produce a smaller image.  If your images have significant color
1922 differences, you may want to generate a new palette for each image:
1923
1924   Imager->write_multi({ file=>$filename,
1925                         type=>'gif',
1926                         make_colors=>'mediancut',
1927                         gif_local_map => 1 },
1928                       @imgs);
1929
1930 which will set the C<gif_local_map> tag in each image to 1.
1931 Alternatively, if you know only some images have different colors, you
1932 can set the tag just for those images:
1933
1934   $imgs[2]->settag(name=>'gif_local_map', value=>1);
1935   $imgs[4]->settag(name=>'gif_local_map', value=>1);
1936
1937 and call write_multi() without a C<gif_local_map> parameter, or supply
1938 an arrayref of values for the tag:
1939
1940   Imager->write_multi({ file=>$filename,
1941                         type=>'gif',
1942                         make_colors=>'mediancut',
1943                         gif_local_map => [ 0, 0, 1, 0, 1 ] },
1944                       @imgs);
1945
1946 Other useful parameters include C<gif_delay> to control the delay
1947 between frames and C<transp> to control transparency.
1948
1949 =head2 Reading tags after reading an image
1950
1951 This is pretty simple:
1952
1953   # print the author of a TIFF, if any
1954   my $img = Imager->new;
1955   $img->read(file=>$filename, type='tiff') or die $img->errstr;
1956   my $author = $img->tags(name=>'tiff_author');
1957   if (defined $author) {
1958     print "Author: $author\n";
1959   }
1960
1961 =head1 BUGS
1962
1963 When saving GIF images the program does NOT try to shave off extra
1964 colors if it is possible.  If you specify 128 colors and there are
1965 only 2 colors used - it will have a 128 color table anyway.
1966
1967 =head1 SEE ALSO
1968
1969 Imager(3)
1970
1971 =cut