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