1Image::PNG::Libpng(3) User Contributed Perl DocumentationImage::PNG::Libpng(3)
2
3
4

NAME

6       Image::PNG::Libpng - Perl interface to the C library "libpng".
7

SYNOPSIS

9       Libpng-like interface:
10
11           use Image::PNG::Libpng ':all';
12           my $png = create_read_struct ();
13           open my $file, '<:raw', 'nice.png' or die $!;
14           $png->init_io ($file);
15           $png->read_png ();
16           close $file;
17           # Get all valid chunks
18           my $valid = $png->get_valid ();
19           my @valid_chunks = sort grep {$valid->{$_}} keys %$valid;
20           print "Valid chunks are ", join (", ", @valid_chunks), "\n";
21           # Print image information
22           my $header = $png->get_IHDR ();
23           for my $k (keys %$header) {
24               print "$k: $header->{$k}\n";
25           }
26
27       (This example is included as examples/synopsis.pl
28       <https://fastapi.metacpan.org/source/BKB/Image-PNG-
29       Libpng-0.57/examples/synopsis.pl> in the distribution.)
30
31       Simple interface:
32
33           use Image::PNG::Libpng ':all';
34           my $png = read_png_file ('../t/tantei-san.png');
35           # Get all valid chunks
36           my $valid = $png->get_valid ();
37           my @valid_chunks = sort grep {$valid->{$_}} keys %$valid;
38           print "Valid chunks are ", join (", ", @valid_chunks), "\n";
39           # Print image information
40           my $header = $png->get_IHDR ();
41           for my $k (keys %$header) {
42               if ($k eq 'color_type') {
43                   print "$k: " . color_type_name ($header->{$k}) . "\n";
44               }
45               else {
46                   print "$k: $header->{$k}\n";
47               }
48           }
49           my $wpng = $png->copy_png ();
50           $wpng->write_png_file ('new.png');
51
52       (This example is included as examples/synopsis-easy.pl
53       <https://fastapi.metacpan.org/source/BKB/Image-PNG-
54       Libpng-0.57/examples/synopsis-easy.pl> in the distribution.)
55

VERSION

57       This document describes Image::PNG::Libpng version 0.57, corresponding
58       to git commit unknown <https://github.com/benkasminbullock/image-png-
59       libpng/commit/unknown> at unknown.
60
61       Unless otherwise qualified, comments in this document on the libpng
62       source code and documentation refer to libpng version 1.6.37. Libpng is
63       not bundled with this distribution, so your installed version may vary.
64

DESCRIPTION

66       Image::PNG::Libpng is a Perl library for accessing the contents of PNG
67       (Portable Network Graphics) images. Image::PNG::Libpng enables Perl to
68       use the "libpng" library to read and write files in PNG format.
69       Image::PNG::Libpng does not contain the libpng library. The libpng
70       library must be installed on your computer prior to installing
71       Image::PNG::Libpng.
72
73       Image::PNG::Libpng consists of Perl subroutines which mirror the C
74       functions in libpng, plus helper subroutines to make it easier to read
75       and write PNG data in Perl.
76
77       For those familiar with libpng, the section "Differences from libpng"
78       explains the differences with libpng.
79

FUNCTIONS

81       The functions in the module are gathered into the following categories:
82       "Simple input and output", which describes some convenience functions,
83       "Libpng-style input and output", which describes functions which
84       closely mirror libpng, "The image header", which describes functions
85       for reading and writing the meta-information about PNG images, "Image
86       data", which describes functions for accessing the image data itself,
87       "Text chunks", "Private chunks", "Library version functions",
88       "Compression and filtering", "Other chunks", "Libpng transformations",
89       "Other libpng functions", functions from libpng which don't fit
90       elsewhere, and "Other functions", which are functions specific to this
91       module.
92

Simple input and output

94       These convenience functions combine common operations. They are not
95       part of the original libpng API.
96
97   copy_png
98           my $outpng = $png->copy_png ();
99
100       Copy a PNG from a read to a write structure. This function bridges two
101       kinds of object, "read a png" objects created by "create_read_struct"
102       and "write a png" objects created by "create_write_struct". This
103       function copies all the valid chunks from a read structure to a write
104       structure.
105
106       The following example demonstrates copying a PNG.
107
108           use utf8;
109           use FindBin '$Bin';
110           use Image::PNG::Libpng qw(read_png_file write_png_file) ;
111           my $pngin = read_png_file ("$Bin/../t/tantei-san.png");
112           my $pngout = $pngin->copy_png ();
113           $pngout->set_text ([{key => 'Name', text => 'Shunsaku Kudo'}]);
114           # $pngout->write_png_file ('copy.png');
115
116       (This example is included as examples/copy-png.pl
117       <https://fastapi.metacpan.org/source/BKB/Image-PNG-
118       Libpng-0.57/examples/copy-png.pl> in the distribution.)
119
120   create_reader
121            my $png = create_reader ('file.png');
122            $png->read_png ();
123
124       This combines "create_read_struct", "open", and "init_io" on the
125       specified file name but does not read the file in. This is for the case
126       that the user wants to apply some kind of transformation.
127
128       Setting the background
129
130       In the following example, the user sets the background with
131       "set_background" to replace the alpha channel.
132
133           use utf8;
134           use FindBin '$Bin';
135           use Image::PNG::Libpng ':all';
136           use Image::PNG::Const ':all';
137           my $file = "$Bin/luv.png";
138           my %color = (red => 0xC0, green => 0xFF, blue => 0xFF);
139           my $png = create_reader ($file);
140           $png->set_background (\%color, PNG_BACKGROUND_GAMMA_SCREEN, 0);
141           $png->read_png ();
142           my $wpng = copy_png ($png);
143           $wpng->write_png_file ("$Bin/set-background.png");
144
145       (This example is included as examples/set-background.pl
146       <https://fastapi.metacpan.org/source/BKB/Image-PNG-
147       Libpng-0.57/examples/set-background.pl> in the distribution.)
148
149       examples/luv.png <https://fastapi.metacpan.org/source/BKB/Image-PNG-
150       Libpng-0.57/examples/luv.png> is included in the distribution.
151
152       examples/set-background.png
153       <https://fastapi.metacpan.org/source/BKB/Image-PNG-
154       Libpng-0.57/examples/set-background.png> is included in the
155       distribution.
156
157       This function was added to the module in version 0.53.
158
159   create_writer
160            my $png = create_writer ('file.png');
161            $png->set_IHDR (\%ihdr);
162            $png->set_rows (\@rows);
163            $png->write_png ();
164
165       This combines "create_write_struct", "open", and "init_io" on the
166       specified file name but does not read the file in. This is for the case
167       that the user wants to apply some kind of transformation before
168       writing.
169
170       This function was added to the module in version 0.53.
171
172   read_from_scalar
173            my $png = read_from_scalar ($string);
174
175       This creates an image structure $png from the contents of a Perl scalar
176       variable $string containing PNG image data, for example data read from
177       a file, or data obtained from a web page. The first argument, $png, is
178       a PNG structure created with "create_read_struct". It reads in all the
179       data from the structure on being called.
180
181       This is useful when image data is stored in a Perl scalar. For example
182
183           use Image::PNG::Libpng 'read_from_scalar';
184           use LWP::Simple;
185           use JSON::Create;
186           my $image_data = get 'http://libpng.org/pub/png/img_png/libpng-88x31.png';
187           # Now $image_data contains the PNG file
188           my $png = read_from_scalar ($image_data);
189           # Now $png contains the PNG information from the image.
190           # Get the header.
191           my $header = $png->get_IHDR ();
192           my $jc = JSON::Create->new (indent => 1, sort => 1);
193           print $jc->run ($header);
194
195       (This example is included as examples/get-www-png.pl
196       <https://fastapi.metacpan.org/source/BKB/Image-PNG-
197       Libpng-0.57/examples/get-www-png.pl> in the distribution.)
198
199       The output looks like this:
200
201           {
202                   "bit_depth":4,
203                   "color_type":3,
204                   "height":31,
205                   "interlace_method":0,
206                   "width":88
207           }
208
209       See also "Input/output manipulation functions".
210
211   read_png_file
212            my $png = read_png_file ('q.png');
213
214       Open q.png and read its contents into $png.
215
216       This combines "create_read_struct", "open", "init_io", and "read_png".
217       The return value is the same as that of "create_read_struct" with the
218       entire PNG image already read in.
219
220       The optional argument to "read_png" can be specified using an optional
221       "transforms" argument:
222
223           my $png = read_png_file ('file.png', transforms => PNG_TRANSFORM_EXPAND);
224
225       "croak" in Carp is used to signal errors opening or closing the file.
226
227   set_transforms
228           $png->set_transforms (PNG_TRANSFORM_BGR);
229
230       Set transforms for reading and writing. This is the same as the
231       optional argument to "read_png" or "write_png". If both this and the
232       optional argument are given, the optional argument overrides what is
233       set here.
234
235   write_png_file
236           $png->write_png_file ('nice.png');
237
238       This combines open, "init_io", and "write_png" to write an entire PNG
239       image out to the file name specified by the argument. $png must be the
240       object created by "create_write_struct", so "read_png_file" followed by
241       a call to this does not work. See "copy_png" if you need to do that
242       kind of operation.
243
244       The optional argument to "write_png" can be specified using
245       "set_transforms".
246
247       "croak" in Carp is used to signal errors opening or closing the file.
248
249   write_to_scalar
250           my $image_data = $png->write_to_scalar ();
251
252       This writes the PNG image data in $png into a Perl scalar. The first
253       argument, $png, is a writeable PNG structure created with
254       "create_write_struct". The return value of the subroutine is the Perl
255       scalar containing the image data.
256
257       So, for example,
258
259           # This CGI script prints a PNG in a random colour.
260
261           use Image::PNG::Libpng ':all';
262           use Image::PNG::Const ':all';
263           my $png = create_write_struct ();
264           my $size = 100;
265           $png->set_IHDR ({height => $size, width => $size, bit_depth => 8,
266                            color_type => PNG_COLOR_TYPE_RGB});
267           my $bytes = pack "CCC", randcol (), randcol (), randcol ();
268           my @rows = ($bytes x $size) x $size;
269           $png->set_rows (\@rows);
270           my $img = $png->write_to_scalar ();
271           binmode STDOUT;
272           print "Content-Type:image/png\r\n\r\n$img";
273           exit;
274           sub randcol
275           {
276               return int (rand () * 0x100);
277           }
278
279       (This example is included as examples/png-cgi.pl
280       <https://fastapi.metacpan.org/source/BKB/Image-PNG-
281       Libpng-0.57/examples/png-cgi.pl> in the distribution.)
282
283       See also "Input/output manipulation functions".
284
285       The optional argument to "write_png" can be specified using
286       "set_transforms".
287

Libpng-style input and output

289       There are two different "new"-like functions, depending on whether you
290       want to read or write a PNG, "create_read_struct" and
291       "create_write_struct". These are based on the libpng API. Input uses
292       "open" plus "init_io" followed by "read_png" or "write_png".
293
294   Examples
295       A self-pixellating program
296
297       This example demonstrates writing a monochrome PNG by creating a write
298       structure with "create_write_struct", opening a filehandle to write it,
299       associating the filehandle with the PNG structure with "init_io", then
300       using the functions "write_info", "write_image", and then "write_end"
301       to actually write the PNG data to the file.
302
303           use utf8;
304           use FindBin '$Bin';
305           use Image::PNG::Libpng ':all';
306           use Image::PNG::Const ':all';
307           my $outfile = "$Bin/mono.png";
308           my ($height, $width, $rows) = pixelate (__FILE__, 5);
309           my $png = create_write_struct ();
310           open my $out, ">:raw", $outfile or die $!;
311           $png->init_io ($out);
312           $png->set_IHDR ({height => $height, width => $width, bit_depth => 1,
313                            color_type => PNG_COLOR_TYPE_GRAY});
314           $png->set_text ([{key => 'silly', text => 'finely-tuned breakfast cereal',}]);
315           $png->set_tIME ({year => 1999});
316           $png->write_info ();
317           $png->set_invert_mono ();
318           # PNG puts the leftmost pixel in the high-order part of the byte.
319           $png->set_packswap ();
320           $png->write_image ($rows);
321           $png->write_end ();
322           close $out or die $!;
323           exit;
324
325           sub pixelate
326           {
327               my ($file, $box) = @_;
328               open my $in, "<", $file or die "Can't open '$file': $!";
329               my $width = 0;
330               my @lines;
331               while (<$in>) {
332                   chomp;
333                   s/\t/        /g;
334                   push @lines, $_;
335                   if (length ($_) > $width) {
336                       $width = length ($_);
337                   }
338               }
339               close $in or die $!;
340               $width *= $box;
341               my $height = scalar (@lines) * $box;
342               my $zero = pack "C", 0;
343               my $bwidth = int(($width+7)/8);
344               my @rows = ($zero x $bwidth) x $height;
345               for my $r (0..$height-1) {
346                   my $y = int ($r/$box);
347                   my $line = $lines[$y];
348                   for my $x (0..length ($line) - 1) {
349                       if (substr ($line, $x, 1) ne ' ') {
350                           for my $c (0..$box - 1) {
351                               my $offset = $x*$box + $c;
352                               my $byte = int ($offset / 8);
353                               my $bit = $offset % 8;
354                               my $octet = ord (substr ($rows[$r], $byte, 1));
355                               substr ($rows[$r], $byte, 1) = chr ($octet | 1<<$bit);
356                           }
357                       }
358                   }
359               }
360               return ($height, $width, \@rows);
361           }
362
363       (This example is included as examples/libpng-write.pl
364       <https://fastapi.metacpan.org/source/BKB/Image-PNG-
365       Libpng-0.57/examples/libpng-write.pl> in the distribution.)
366
367       examples/mono.png <https://fastapi.metacpan.org/source/BKB/Image-PNG-
368       Libpng-0.57/examples/mono.png> is included in the distribution.
369
370   create_read_struct
371            my $png = create_read_struct ();
372
373       Create a structure for reading a PNG. The return value can be used as
374       an object with the other functions as methods. It can be copied to a
375       write structure with "copy_png".
376
377       This function corresponds to "png_create_read_struct" in libpng plus
378       "create_info_struct" (see "No info structure") with the error and
379       warning handler variables set up to use Perl's error reporting.
380
381   create_write_struct
382            my $png = create_write_struct ();
383
384       Create a structure for writing a PNG. This can be used as an object
385       with the other functions as methods.
386
387       This function corresponds to "png_create_write_struct" in libpng plus
388       "create_info_struct" (see "No info structure")  with the error and
389       warning handler variables set up to use Perl's error reporting.
390
391   init_io
392            open my $file, "<", 'nice.png';
393            $png->init_io ($file);
394
395       Set the file which $png reads or writes to $file. $file must be an
396       already-opened Perl file handle. If $png was created with
397       "create_write_struct", $file must be opened for writing. If $png was
398       created with "create_read_struct", $file must be open for reading.
399
400       Since PNG files are binary files, it is safest to specify the "raw"
401       pragma or use "binmode" with the file to override any default text file
402       encoding which Perl might be using:
403
404            open my $file, ">:raw", 'output.png';
405
406       or
407
408            open my $file, ">", 'output.png';
409            binmode $file;
410
411       This function corresponds to "png_init_io" in libpng, with a Perl file
412       handle substituting for the C "FILE *".
413
414       On some versions of Perl, "init_io" may crash in some circumstances
415       with an error like "segmentation fault", if you use code like
416
417           my $png = create_read_struct ();
418           open my $file, "<:raw", "some.png";
419           $png->init_io ($file);
420
421       and you do not check whether the call to "open" was successful, and
422       some.png does not exist. The crash occurs within Perl's conversion of
423       $file into a C "FILE *" pointer, before this module's code runs. This
424       bug was fixed in Perls after version 5.24.1. To avoid trouble, please
425       check the return value of "open".
426
427   read_end
428            $png->read_end ();
429
430       Read the part of the PNG file after the image data.
431
432       This function corresponds to "png_read_end" in libpng.
433
434   read_image
435            my $rows = $png->read_image ();
436
437       Read the image data of the PNG file.
438
439       This function corresponds to "png_read_image" in libpng.
440
441   read_info
442           $png->read_info ();
443
444       Read the part of the PNG file before the image data.
445
446       This function corresponds to "png_read_info" in libpng.
447
448   read_png
449            $png->read_png ();
450
451       Read the entire PNG file into memory.
452
453       You can provide an argument containing transformations to apply to the
454       image:
455
456            use Image::PNG::Const qw/PNG_TRANSFORM_STRIP_ALPHA/;
457            $png->read_png (PNG_TRANSFORM_STRIP_ALPHA);
458
459       If the argument is omitted, the default value of
460       "PNG_TRANSFORM_IDENTITY" (the "do nothing" value) is applied. The
461       possible transformations which can be applied are
462
463       PNG_TRANSFORM_BGR
464           Flip RGB to BGR, RGBA to BGRA. See also "set_bgr".
465
466       PNG_TRANSFORM_EXPAND
467           Perform set_expand(). See also "set_expand".
468
469       PNG_TRANSFORM_EXPAND_16
470           Expand samples to 16 bits. See also "set_expand_16".
471
472       PNG_TRANSFORM_GRAY_TO_RGB
473           Expand grayscale samples to RGB (or GA to RGBA). See also
474           "set_gray_to_rgb".
475
476       PNG_TRANSFORM_IDENTITY
477           No transformation.
478
479       PNG_TRANSFORM_INVERT_ALPHA
480           Change alpha from opacity to transparency. See also
481           "set_invert_alpha".
482
483       PNG_TRANSFORM_INVERT_MONO
484           Invert monochrome images. See also "set_invert_mono".
485
486       PNG_TRANSFORM_PACKING
487           Expand 1, 2 and 4-bit samples to bytes. See also "set_packing".
488
489       PNG_TRANSFORM_PACKSWAP
490           Change order of packed pixels to LSB first. See also
491           "set_packswap".
492
493       PNG_TRANSFORM_SCALE_16
494           Strip 16-bit samples to 8-bit accurately. See also "set_scale_16".
495
496       PNG_TRANSFORM_SHIFT
497           Normalize pixels to the sBIT depth.
498
499       PNG_TRANSFORM_STRIP_16
500           Chop 16-bit samples to 8-bit less accurately. See also
501           "set_strip_16".
502
503       PNG_TRANSFORM_STRIP_ALPHA
504           Discard the alpha channel.
505
506       PNG_TRANSFORM_SWAP_ALPHA
507           Flip RGBA to ARGB or GA to AG. See also "set_swap_alpha".
508
509       PNG_TRANSFORM_SWAP_ENDIAN
510           Byte-swap 16-bit samples. See also "set_swap".
511
512       This function corresponds to "png_read_png" in libpng with a default
513       value for the third argument. The fourth, unused, argument to
514       "png_read_png" does not need to be supplied. See "Unused arguments
515       omitted".
516
517       It does not take a second "info" argument. See "No info structure".
518
519   read_update_info
520           $png->read_update_info ();
521
522       ⛐ðŸĪŠâš  Inside Image::PNG::Libpng, the libpng function
523       "png_read_update_info" is called before reading image data.  According
524       to "The libpng documentation", this function may only be called once
525       for any particular info structure. So although the above Perl interface
526       exists in the module, it is strongly recommended to not use this unless
527       you know exactly what you are doing, since it will usually cause an
528       error when the image data is read.
529
530       This function corresponds to "png_read_update_info" in libpng
531
532   write_end
533           $png->write_end ();
534
535       Write the final part of the PNG file.
536
537       This function corresponds to "png_write_end" in libpng.
538
539   write_image
540           $png->write_image ($rows);
541
542       Write the image of the PNG file. $rows is an array reference as per
543       "set_rows".
544
545       This function corresponds to "png_write_image" in libpng.
546
547   write_info
548           $png->write_info ();
549
550       Write the first part of the PNG file.
551
552       This function corresponds to "png_write_info" in libpng.
553
554   write_png
555           $png->write_png ();
556
557       This writes the PNG to the file stream which was associated with it
558       using "init_io". For example,
559
560           open my $output, ">:raw", 'out.png';
561           $png->init_io ($output);
562           $png->write_png ();
563           close $output;
564
565       An optional argument consists of transformations to apply to the PNG
566       image before writing it:
567
568           use Image::PNG::Const qw/PNG_TRANSFORM_STRIP_ALPHA/;
569           $png->write_png (PNG_TRANSFORM_STRIP_ALPHA);
570
571       The transformations which can be applied are as follows:
572
573       PNG_TRANSFORM_BGR
574           Flip RGB to BGR, RGBA to BGRA. See also "set_bgr".
575
576       PNG_TRANSFORM_INVERT_ALPHA
577           Change alpha from opacity to transparency. See also
578           "set_invert_alpha".
579
580       PNG_TRANSFORM_INVERT_MONO
581           Invert monochrome images. See also "set_invert_mono".
582
583       PNG_TRANSFORM_PACKING
584           Expand 1, 2 and 4-bit samples to bytes. See also "set_packing".
585
586       PNG_TRANSFORM_PACKSWAP
587           Change order of packed pixels to LSB first. See also
588           "set_packswap".
589
590       PNG_TRANSFORM_SHIFT
591           Normalize pixels to the sBIT depth.
592
593       PNG_TRANSFORM_STRIP_FILLER_AFTER
594           Strip out trailing filler bytes.
595
596       PNG_TRANSFORM_STRIP_FILLER_BEFORE
597           Strip out leading filler bytes.
598
599       PNG_TRANSFORM_SWAP_ALPHA
600           Flip RGBA to ARGB or GA to AG. See also "set_swap_alpha".
601
602       PNG_TRANSFORM_SWAP_ENDIAN
603           Byte-swap 16-bit samples. See also "set_swap".
604
605       This function corresponds to "png_write_png" in libpng.
606

The image header

608       These functions handle the header part of PNG image data. See this
609       subsection <http://www.w3.org/TR/PNG/#11IHDR> of "The PNG
610       specification" for information on the PNG standards for the image
611       header.
612
613   color_type_name
614           $name = color_type_name ($color_type);
615
616       This is a convenience function which returns a string corresponding to
617       the numerical color type in $color_type. The name is in upper case,
618       with words separated by underscores, as in "RGB_ALPHA".
619
620           use Image::PNG::Libpng ':all';
621           my $png = read_png_file ('tantei-san.png');
622           my $name = color_type_name ($png->get_IHDR->{color_type});
623           print "Your PNG has colour type $name.\n";
624
625       (This example is included as examples/color-type-name.pl
626       <https://fastapi.metacpan.org/source/BKB/Image-PNG-
627       Libpng-0.57/examples/color-type-name.pl> in the distribution.)
628
629       This function does not correspond to anything in libpng. The names of
630       the color types are taken from those defined in the libpng header file,
631       "png.h".
632
633   get_bit_depth
634           my $bit_depth = $png->get_bit_depth ();
635
636       Get the bit depth, the number of bits for one channel of one pixel.
637
638       This function corresponds to "png_get_bit_depth" in libpng
639
640   get_channels
641           my $channels = $png->get_channels ();
642
643       Get the number of channels, from one to four. The channels are the
644       components of pixels, for example the red channel or the alpha
645       (transparency) channel. The return value is 1 for color type
646       "PNG_COLOR_TYPE_GRAY" and "PNG_COLOR_TYPE_PALETTE", 2 for
647       "PNG_COLOR_TYPE_GRAY_ALPHA", 3 for "PNG_COLOR_TYPE_RGB" and 4 for
648       "PNG_COLOR_TYPE_RGB_ALPHA" or "PNG_COLOR_TYPE_RGB" with a filler byte.
649       Note that the number of channels does not necessarily correspond to the
650       number of bytes, since the bit depth can also be 1, 2, 4, 8, or 16,
651       depending on the color type. See also the convenience function
652       "color_type_channels".
653
654       This function corresponds to "png_get_channels" in libpng
655
656   get_color_type
657           my $color_type = $png->get_color_type ();
658
659       This returns an integer value. If you want to get a name for the color
660       type, use "color_type_name".
661
662       This function corresponds to "png_get_color_type" in libpng.
663
664   get_IHDR
665           my $IHDR = $png->get_IHDR ();
666
667       Read the IHDR information from the PNG file. The return value is a hash
668       reference containing the following key/value pairs:
669
670       width
671           The width of the image in pixels.
672
673       height
674           The height of the image in pixels.
675
676       bit_depth
677           The bit depth of the image (the number of bits used for each color
678           in a pixel).  This can take the values 1, 2, 4, 8, 16.
679
680       color_type
681           The color type.  This can take the values PNG_COLOR_TYPE_GRAY,
682           PNG_COLOR_TYPE_GRAY_ALPHA, PNG_COLOR_TYPE_PALETTE,
683           PNG_COLOR_TYPE_RGB, PNG_COLOR_TYPE_RGB_ALPHA.
684
685       interlace_method
686           The method of interlacing.  This can take the values
687           PNG_INTERLACE_NONE, PNG_INTERLACE_ADAM7.
688
689       So, for example, to get the width and height of an image,
690
691           my $ihdr = $png->get_IHDR ();
692           printf "Your image is %d x %d\n", $ihdr->{width}, $ihdr->{height};
693
694       This function corresponds to "png_get_IHDR" in libpng, with a single
695       Perl hash reference used instead of the several pointers to integers
696       used in libpng.
697
698       It does not return the fields "filter_type" and "compression_type",
699       since these are always 0. See "Unused arguments omitted".
700
701   get_image_height
702           my $height = $png->get_image_height ();
703
704       Get the image's height from the header.
705
706       This function corresponds to "png_get_image_height" in libpng
707
708   get_image_width
709           my $width = $png->get_image_width ();
710
711       Get the image's width from the header.
712
713       This function corresponds to "png_get_image_width" in libpng
714
715   get_interlace_type
716           my $interlace_type = $png->get_interlace_type ();
717
718       Get the interlace type. This is either PNG_INTERLACE_NONE or
719       PNG_INTERLACE_ADAM7.
720
721       This function corresponds to "png_get_interlace_type" in libpng
722
723   get_valid
724           my $valid = $png->get_valid ();
725           if ($valid->{oFFs}) {
726               print "The PNG has valid screen offsets.\n";
727           }
728
729       This function returns a hash with a key for each possible chunk which
730       may or may not be valid. The chunks which you can test for are "bKGD",
731       "cHRM", "eXIf", "gAMA", "hIST", "hIST", "iCCP", IDAT, IHDR, "iTXt",
732       "oFFs", "pCAL", "pHYs", "PLTE", "sBIT", "sCAL", "sPLT", "sRGB", "tEXt",
733       "tIME", "tRNS", and "zTXt".
734
735       Whereas "libpng_supports" tells you whether the installed libpng on
736       your system supports various chunks, this tells you whether the chunks
737       are present in a particular PNG image file.
738
739       The first argument, $png, is a PNG structure created with
740       "create_read_struct".
741
742       This function corresponds to "png_get_valid" in libpng, with the
743       difference being that the return value is a hash containing a key for
744       each possible chunk.
745
746   height
747           my $height = $png->height ();
748
749       Alias for "get_image_height". This is not exported, it's intended for
750       use with the object only.
751
752   set_IHDR
753           my $ihdr = {width => 10, height => 10, bit_depth => 8,
754                       color_type => PNG_COLOR_TYPE_RGB};
755           $png->set_IHDR ($ihdr);
756
757       Set the IHDR chunk (the image header) of the PNG image.
758
759       The first argument, $png, is a writeable PNG structure created with
760       "create_write_struct". The second argument is a hash with the following
761       values:
762
763       width
764           The width of the image in pixels.
765            This cannot be zero, negative, or omitted.
766
767       height
768           The height of the image in pixels.
769            This cannot be zero, negative, or omitted.
770
771       bit_depth
772           The bit depth of the image (the number of bits used for each color
773           in a pixel).
774            This cannot be omitted. This can have the values 1, 2, 4, 8, 16.
775
776       color_type
777           The color type.
778            This cannot be omitted. This can have the values
779           PNG_COLOR_TYPE_GRAY, PNG_COLOR_TYPE_GRAY_ALPHA,
780           PNG_COLOR_TYPE_PALETTE, PNG_COLOR_TYPE_RGB,
781           PNG_COLOR_TYPE_RGB_ALPHA.
782
783       interlace_method
784           The method of interlacing.
785            If this is omitted, it's set to PNG_INTERLACE_NONE. This can have
786           the values PNG_INTERLACE_NONE, PNG_INTERLACE_ADAM7.
787
788       Other fields in the hash are ignored.
789
790       This function corresponds to "png_set_IHDR" in libpng, with a single
791       Perl hash reference used instead of the seven integers.
792
793       The values "compression_method", "filter_method", may be supplied by
794       the user but are ignored since they may only take the value 0. See
795       "Unused arguments omitted".
796
797   sig_cmp
798           if (sig_cmp ($should_be_png)) {
799               print "Your data does not have a PNG signature.\n";
800           }
801
802       This subroutine looks at $should_be_png and checks whether its first
803       bytes correspond to a valid PNG signature. It returns a true value if
804       they do not.
805
806       It can also take two further arguments consisting of a byte offset and
807       a number of bytes to check respectively:
808
809           sig_cmp ($should_be_png, 0, 8);
810
811       If these arguments are not supplied, the byte offset is assumed to be
812       zero, and the number of bytes to check is assumed to be eight.
813
814       This function corresponds to "png_sig_cmp" in libpng, with default
815       arguments of 0 and 8 if second and third arguments are not supplied.
816
817   width
818           my $width = $png->width ();
819
820       Alias for "get_image_width". This is not exported, it's intended for
821       use with the object only.
822

Image data

824       These functions deal with accessing the image data itself.
825
826   get_rowbytes
827           my $bytes_in_a_row = $png->get_rowbytes ();
828
829       This returns the number of bytes needed to hold a transformed row of an
830       image.
831
832       This function corresponds to "png_get_rowbytes" in libpng.
833
834   get_rows
835           my $rows = $png->get_rows ();
836           my $pixel = substr ($rows->[10], 20, 1);
837
838       This returns the rows of the PNG image, after uncompressing and
839       unfiltering, as binary data. The return value, $rows in the example, is
840       an array reference with a number of rows equal to the height of the PNG
841       image. Each element of the array reference is a string containing the
842       binary data making up a row of the image. The values of individual
843       pixels can be extracted from using a function such as "substr" or
844       "unpack". This binary data is likely to contain bytes equal to zero.
845
846       "get_rowbytes" gives the number of bytes in each row.
847
848       Each row is a Perl string. Perl terminates each row of data with an
849       extra zero byte at the end.
850
851       This function corresponds to "png_get_rows" in libpng.
852
853   set_rows
854           $png->set_rows (\@rows);
855
856       Set the rows of data to be written in to the PNG to @rows. @rows needs
857       to contain at least the same number of rows of data as the height of
858       the PNG image set with "set_IHDR", and the length of each entry needs
859       to be at least the width of the image multiplied by the number of bytes
860       required for each pixel.
861
862       This function was changed to copy the data in version 0.46.
863
864       This function corresponds to "png_set_rows" in libpng.
865

Text chunks

867       See this subsection <http://www.w3.org/TR/PNG/#11textinfo> of "The PNG
868       specification" for information on the PNG standards for text
869       information.
870
871   get_text
872           my $text_chunks = $png->get_text ();
873
874       This gets all of the text chunks in the PNG image and returns them as
875       an array reference. Each element of the array represents one text
876       chunk. This element is a hash reference with keys such as "key",
877       "lang_key", or "compression" taken from the PNG's information.
878
879       The text data is uncompressed by libpng. If it is international text
880       ("ITXT"), it is put into Perl's internal Unicode encoding if it is
881       found to be valid UTF-8. (PNG "international text", "ITXT" is required
882       to be in the UTF-8 encoding, and non-international text is required to
883       contain whitespace and printable ASCII characters only. See "The PNG
884       specification" for more on the requirements of a PNG text section.)
885
886       This function corresponds to "png_get_text" in libpng, with a Perl
887       array of hash references substituted for the C array of structs used by
888       libpng. See "set_text" for details of the keys and values which may be
889       returned.
890
891   set_text
892           $png->set_text ([\%chunk1, \%chunk2]);
893
894       This sets the text chunks in a writeable image. The input value is an
895       array reference containing one or more hash references. Each hash
896       reference must have a "key" value for the text. According to the PNG
897       specification, this should be between one and 79 bytes in length. This
898       module enforces that restriction, so if you supply a key longer than
899       that, the chunk cannot be added. A hash reference may also have the
900       following:
901
902       "compression"
903           The value of "compression" controls the compression of the text. If
904           "compression" is not supplied, a default value of
905           PNG_TEXT_COMPRESSION_NONE is applied. The "compression" field can
906           take the following values, available from Image::PNG::Const:
907
908           PNG_TEXT_COMPRESSION_NONE
909               TEXT = Printable ASCII and space characters.
910
911           PNG_TEXT_COMPRESSION_zTXt
912               TEXT = Printable ASCII and space characters.
913
914           PNG_ITXT_COMPRESSION_NONE
915               ITXT = International text, should be UTF-8.
916
917           PNG_ITXT_COMPRESSION_zTXt
918               ITXT = International text, should be UTF-8.
919
920       "itxt_length"
921           The string length of international text in bytes.
922
923           ⛐ðŸĪŠâš  This is ignored by libpng when writing text chunks. When
924           reading text chunks, if the text is marked as international text,
925           libpng adds the length of the string in bytes in this field rather
926           than in "text_length".
927
928       "lang"
929           This should be set to name of the language of the text, if the text
930           chunk is iTXt. According to the PNG specification, "It is an ISO
931           646.IRV:1991 [ISO 646] string consisting of hyphen-separated words
932           of 1-8 alphanumeric characters each (for example cn, en-uk, no-bok,
933           x-klingon, x-KlInGoN)."
934
935           Support for writing "lang" was added in version 0.49 of this
936           module. (Prior to that undocumented support existed via a
937           differently-named key.)
938
939           ⛐ðŸĪŠâš  This module does not attempt to check the supplied value, but
940           merely passes it to libpng. libpng appears not to check the value
941           either, nor to enforce restrictions on its length.
942
943       "lang_key"
944           This corresponds to the "Translated keyword" of the PNG
945           specification. Note that the user needs to supply "key" and "lang"
946           as well as "lang_key".
947
948           Support for writing "lang_key" was added in version 0.49 of this
949           module.  (Prior to that undocumented support existed via a
950           differently-named key.)
951
952       "text"
953           The value of "text" is added to the PNG as the text segment. This
954           can be omitted if you just want to write a key value without any
955           accompanying text.
956
957       "text_length"
958           The string length in bytes. The user may set this, but it is
959           ignored when writing PNG text chunks, instead this module uses the
960           string length obtained from Perl. This key contains the length of
961           the string when reading text chunks via "get_text", but if the text
962           is marked as international text, "itxt_length" is used to return
963           its length in bytes, rather than this.
964
965       Whether or not the value of "text" is an ITXT field is decided by the
966       value of "compression".
967
968       People who want to fiddle with the text compression applied can do so
969       via "set_text_compression_level" and the other functions described
970       below that.
971
972       If "set_text" is called more than once, the chunks are not overwritten
973       but appended to the existing ones. (This behaviour is from libpng
974       itself.)
975
976       Prior to version 0.50, "set_text" would fail silently if the user added
977       invalid chunks, for example hash references without a valid "key", or
978       things which were not hash references at all. From version 0.50, all
979       invalid inputs cause fatal errors. However, unknown keys in the hash
980       references do not cause fatal errors.
981
982       This function corresponds to "png_set_text" in libpng.
983
984       Example
985
986           use utf8;
987           use Image::PNG::Const ':all';
988           use Image::PNG::Libpng ':all';
989           my $png = create_write_struct ();
990           $png->set_IHDR ({width => 1, height => 1, bit_depth => 8,
991                            color_type => PNG_COLOR_TYPE_GRAY});
992           $png->set_rows (['X']);
993           $png->set_text ([{
994               compression => PNG_TEXT_COMPRESSION_NONE,
995               key => "Copyright",
996               text => "Copyright (C) 2020 Fat Cat",
997           }, {
998               compression => PNG_ITXT_COMPRESSION_zTXt,
999               key => "Copyright",
1000               lang_key => '著者æĻĐ',
1001               lang => 'ja_JP',
1002               text => 'ÂĐäŧĪ和åđīčŒ‰čŽ‰ãƒ‹ãƒĢãƒģバマゎマさん',
1003           }]);
1004           $png->write_png_file ('copyright.png');
1005
1006       (This example is included as examples/set-text.pl
1007       <https://fastapi.metacpan.org/source/BKB/Image-PNG-
1008       Libpng-0.57/examples/set-text.pl> in the distribution.)
1009
1010   text_compression_name
1011           my $name = Image::PNG::Libpng::text_compression_name ($text->{compression});
1012
1013       Given a numerical text compression type, return the equivalent name.
1014       The name is in upper case. The possible return values are
1015
1016       TEXT_NONE
1017       TEXT_zTXt
1018       ITXT_NONE
1019       ITXT_zTXt
1020       an empty string
1021           if the compression method is unknown.
1022
1023       The compression field is also used to store the information about
1024       whether the text is "international text" in UTF-8 or not.
1025
1026       This function does not correspond to anything in libpng. The names of
1027       the text compression types are based on those in "png.h", but without
1028       the word "COMPRESSION", so for example the libpng constant
1029       "PNG_ITXT_COMPRESSION_zTXt" corresponds to a return value of
1030       "ITXT_zTXt".
1031

Private chunks

1033       See this subsection <http://www.w3.org/TR/PNG/#12Use-of-private-chunks>
1034       of "The PNG specification" for information on the PNG standards for
1035       private chunks.
1036
1037       To test whether your version of libpng supports "private chunks", use
1038       "libpng_supports" with argument '"UNKNOWN_CHUNKS"':
1039
1040           if (libpng_supports ('UNKNOWN_CHUNKS')) {
1041               # do something
1042           }
1043
1044   get_chunk_malloc_max
1045           my $max = $png->get_chunk_malloc_max ();
1046
1047       This gets the maximum amount of memory that a chunk can use.
1048
1049       To test whether your version of libpng supports "get_chunk_malloc_max",
1050       use "libpng_supports" with argument '"CHUNK_MALLOC_MAX"':
1051
1052           if (libpng_supports ('CHUNK_MALLOC_MAX')) {
1053               # do something
1054           }
1055
1056       This function corresponds to "png_get_chunk_malloc_max" in libpng
1057
1058   set_chunk_malloc_max
1059           $png->set_chunk_malloc_max ($max);
1060
1061       This sets the maximum amount of memory that a chunk can use. The
1062       default value of libpng 1.6.37 is 8 megabytes.
1063
1064       To test whether your version of libpng supports "get_chunk_malloc_max",
1065       use "libpng_supports" with argument '"CHUNK_MALLOC_MAX"':
1066
1067           if (libpng_supports ('CHUNK_MALLOC_MAX')) {
1068               # do something
1069           }
1070
1071       This function corresponds to "png_set_chunk_malloc_max" in libpng
1072
1073   set_keep_unknown_chunks
1074           use Image::PNG::Const 'PNG_HANDLE_CHUNK_ALWAYS';
1075           $png->set_keep_unknown_chunks (PNG_HANDLE_CHUNK_ALWAYS);
1076
1077       Tell libpng not to discard unknown chunks when reading the file.
1078
1079   get_unknown_chunks
1080           my $private_chunks = $png->get_unknown_chunks ();
1081           # Get some data from a private chunk
1082           my $chunk_three_data = $private_chunks->[3]->{data};
1083           # Get the size of the data
1084           print length $chunk_three_data;
1085
1086       This gets all of the private chunks from the image. The return value is
1087       an array reference containing hash references. If there are no private
1088       chunks, this returns an undefined value. There is one element of the
1089       array for each chunk member. It is necessary to call
1090       "set_keep_unknown_chunks" with an appropriate value before reading the
1091       file, otherwise libpng discards unknown chunks when reading the file.
1092
1093       Each member hash reference has the following keys:
1094
1095       name
1096           The name of the unknown chunk, in the PNG chunk format (four
1097           bytes).
1098
1099       location
1100           The location of the unknown chunk.
1101
1102       data
1103           The data of the unknown chunk
1104
1105       The "size" field of the PNG structure is not stored, because the "data"
1106       member of the hash contains information on its length.
1107
1108       This function corresponds to "png_get_unknown_chunks" in libpng
1109
1110   set_unknown_chunks
1111           $png->set_unknown_chunks (name => 'dUCk', data => 'abcdefg',
1112                                     location => PNG_AFTER_IDAT);
1113
1114       ⛐ðŸĪŠâš  This currently does not fully function.
1115
1116       This function corresponds to "png_set_unknown_chunks" in libpng
1117

Library version functions

1119   access_version_number
1120           my $libpng_version_number = Image::PNG::Libpng::access_version_number ();
1121
1122       This function returns the version of the libpng library which the
1123       module is using as an integer number.
1124
1125       This function corresponds to "png_access_version_number" in libpng.
1126
1127   get_libpng_ver
1128           my $libpng_version = Image::PNG::Libpng::get_libpng_ver ();
1129
1130       This function returns the version of the libpng library which the
1131       module is using.
1132
1133       This function corresponds to "png_get_libpng_ver" in libpng. However,
1134       it doesn't require the "png_structp" argument of the C function. See
1135       "Unused arguments omitted".
1136

Compression and filtering

1138   get_compression_buffer_size
1139           my $size = $png->get_compression_buffer_size ();
1140
1141       Returns the value of the compression buffer size, which may be altered
1142       with "set_compression_buffer_size".
1143
1144   set_compression_buffer_size
1145           $png->set_compression_buffer_size (100);
1146
1147       Set the size of the buffer which zlib uses to compress or decompress
1148       the image data. It takes one argument, an integer number. This cannot
1149       be less than 6.
1150
1151   set_compression_level
1152           $png->set_compression_level ($number);
1153
1154       Set the compression level used to make the PNG. A value of 0
1155       ("Z_NO_COMPRESSION") corresponds to no compression at all, otherwise
1156       $number may take values of 1 ("Z_BEST_SPEED") to 9
1157       ("Z_BEST_COMPRESSION"), with smaller values giving faster, and larger
1158       values giving better, that is with smaller output, compression. These
1159       correspond to the -1, -2, ... -9 options to the "gzip" utility, or the
1160       compression level parameter of "zlib". Calling with "-1"
1161       ("Z_DEFAULT_COMPRESSION") reverts to the default compression. Calling
1162       with any other number outside the range 0 to 9 results in a fatal
1163       error.
1164
1165       This function was added to the module in version 0.49.
1166
1167   set_compression_mem_level
1168           $png->set_compression_mem_level ($argument);
1169
1170       ⛐ðŸĪŠâš  Untested function corresponding to
1171       "png_set_compression_mem_level". Takes one integer argument.
1172
1173       Sets the "memLevel" parameter of "deflateInit2" in zlib when writing
1174       PNG image data. Argument between 1 for minimum memory and 9 for maximum
1175       speed. The default is 8. See "zlib documentation".
1176
1177   set_compression_window_bits
1178           $png->set_compression_window_bits ($argument);
1179
1180       ⛐ðŸĪŠâš  Untested function corresponding to
1181       "png_set_compression_window_bits". Takes one integer argument.
1182
1183       Sets the "windowBits" parameter of "deflateInit2" in zlib when writing
1184       PNG image data. Argument value must be between 8 and 15 for libpng. The
1185       default is 15. See the "zlib documentation".
1186
1187   set_compression_strategy
1188           $png->set_compression_strategy ($argument);
1189
1190       ⛐ðŸĪŠâš  Untested function corresponding to "png_set_compression_strategy".
1191       Takes one integer argument.
1192
1193       Sets the "strategy" parameter of "deflateInit2" when writing PNG image
1194       data. Setting this with libpng overrides libpng's default behaviour of
1195       changing the value depending on the filter in use. For zlib, the
1196       argument is either 0 for default behaviour, or 1 to 4.  See the "zlib
1197       documentation". libpng uses the default strategy 0
1198       ("Z_DEFAULT_STRATEGY") for unfiltered image data, and 1 ("Z_FILTERED")
1199       for filtered image data.
1200
1201   set_filter
1202           use Image::PNG::Const 'PNG_FILTER_NONE';
1203           $png->set_filter (PNG_FILTER_NONE);
1204
1205       This sets the filters which are allowed to be used for writing a PNG
1206       image. The possible values are
1207
1208       PNG_NO_FILTERS
1209       PNG_FILTER_NONE
1210       PNG_FILTER_SUB
1211       PNG_FILTER_UP
1212       PNG_FILTER_AVG
1213       PNG_FILTER_PAETH
1214       PNG_ALL_FILTERS
1215
1216       These can be combined using "|" (logical or):
1217
1218           use Image::PNG::Const ':all';
1219           set_filter ($png, PNG_FILTER_UP | PNG_FILTER_AVG);
1220
1221       Please see this subsection <http://www.w3.org/TR/PNG/#9Filter-types> of
1222       "The PNG specification" for the meanings of these filter types.
1223
1224       This function corresponds to "png_set_filter" in libpng with the second
1225       (unused) argument omitted. See "Unused arguments omitted".
1226
1227   set_text_compression_level
1228           $png->set_text_compression_level ($argument);
1229
1230       ⛐ðŸĪŠâš  Untested function corresponding to
1231       "png_set_text_compression_level". Takes one integer argument.
1232
1233       As "set_compression_level" but for compressed text.
1234
1235   set_text_compression_mem_level
1236           $png->set_text_compression_mem_level ($argument);
1237
1238       ⛐ðŸĪŠâš  Untested function corresponding to
1239       "png_set_text_compression_mem_level". Takes one integer argument.
1240
1241       As "set_compression_mem_level" but for compressed text.
1242
1243   set_text_compression_window_bits
1244           $png->set_text_compression_window_bits ($argument);
1245
1246       ⛐ðŸĪŠâš  Untested function corresponding to
1247       "png_set_text_compression_window_bits". Takes one integer argument.
1248
1249       As "set_compression_window_bits" but for compressed text.
1250
1251   set_text_compression_strategy
1252           $png->set_text_compression_strategy ($argument);
1253
1254       ⛐ðŸĪŠâš  Untested function corresponding to
1255       "png_set_text_compression_strategy". Takes one integer argument.
1256
1257       As "set_compression_strategy" but for compressed text.
1258

Other chunks

1260       These routines deal with the other possible chunks of PNGs.
1261
1262       The getter and setter routines for all other chunks are designed so
1263       that the return value of "get_wXYZ" is able to be used directly as the
1264       value for "set_wXYZ", so the values of chunks can easily be copied from
1265       one PNG to another.
1266
1267           my $values = $png1->get_wXYZ ();
1268           $png2->set_wXYZ ($values);
1269
1270       If the chunk is not present, or if the chunk is not supported by the
1271       user's version of libpng, the return value of "get_wXYZ" is the
1272       undefined value.
1273
1274   bKGD
1275       The background color of the PNG image.
1276
1277       See this subsection <http://www.w3.org/TR/PNG/#11bKGD> of "The PNG
1278       specification" for information on the PNG standards for the background
1279       chunk.
1280
1281       get_bKGD
1282
1283           my $bkgd = $png->get_bKGD ();
1284
1285       Get the bKGD (background) chunk of the image.
1286
1287       The return value is a hash with the following keys, depending on the
1288       color type of the image:
1289
1290       index
1291           For palette color types, this is the offset into the palette.
1292
1293       gray
1294           For grayscale color types.
1295
1296       red
1297       green
1298       blue
1299
1300       This function corresponds to "png_get_bKGD" in libpng with a hash
1301       function instead of a "png_color" struct.
1302
1303       set_bKGD
1304
1305           $png->set_bKGD ($bkgd);
1306
1307       Set the bKGD (background) chunk of the image. $bkgd is a hash
1308       reference. The keys of the hash reference are as described in
1309       "get_bKGD".
1310
1311       This function corresponds to "png_set_bKGD" in libpng with a hash
1312       function instead of a "png_color" struct.
1313
1314   cHRM
1315       See this subsection <http://www.w3.org/TR/PNG/#11cHRM> of "The PNG
1316       specification" "cHRM Primary chromaticities and white point".
1317
1318       get_cHRM
1319
1320           my $cHRM = $png->get_cHRM ();
1321
1322       Get the cHRM chunk as a hash reference.
1323
1324       The keys of the hash are white_x, white_y, red_x, red_y, green_x,
1325       green_y, blue_x, blue_y.
1326
1327       The values of the hash are floating point numbers between 0 and 1.
1328
1329       This function corresponds to "png_get_cHRM" in libpng with a hash
1330       reference supplying the arguments. The hash's keys correspond to the
1331       names of the "double" arguments in libpng.
1332
1333       get_cHRM_XYZ
1334
1335           my $cHRM = $png->get_cHRM_XYZ ();
1336
1337       Get the cHRM chunk as a hash reference for the XYZ color space.
1338
1339       The keys of the hash are red_x, red_y, red_z, green_x, green_y,
1340       green_z, blue_x, blue_y, blue_z.
1341
1342       The values of the hash are floating point numbers between 0 and 1.
1343
1344       This function corresponds to "png_get_cHRM_XYZ" in libpng with a hash
1345       reference supplying the arguments. The hash's keys correspond to the
1346       names of the "double" arguments in libpng.
1347
1348       set_cHRM
1349
1350           $png->set_cHRM (\%cHRM);
1351
1352       Set the cHRM chunk from a hash reference.
1353
1354       The keys of the hash are as for "get_cHRM". The values are floating
1355       point numbers between 0 and 1.
1356
1357       This function corresponds to "png_set_cHRM" in libpng with a hash
1358       reference instead of the "double" arguments.
1359
1360       set_cHRM_XYZ
1361
1362           $png->set_cHRM_XYZ (\%cHRM);
1363
1364       Set the cHRM chunk from a hash reference for the XYZ color space.
1365
1366       The keys of the hash are as for "get_cHRM_XYZ". The values are floating
1367       point numbers between 0 and 1. The "Y" values "red_y", "green_y", and
1368       "blue_y" should sum to 1. If you supply values outside the allowed
1369       range, libpng corrects them silently on writing rather than producing
1370       an error.
1371
1372       This function corresponds to "png_set_cHRM_XYZ" in libpng with a hash
1373       reference instead of the "double" arguments.
1374
1375   eXIf
1376       The "eXIf" chunk is an extension to the PNG specification. See
1377       <http://www.simplesystems.org/png-group/proposals/eXIf/>. Support for
1378       this chunk was added in version 0.50 of this module.
1379
1380       get_eXIf
1381
1382           my $exif = $png->get_eXIf ();
1383
1384       This retrieves the "eXIf" chunk from $png but does not process the
1385       internal information.
1386
1387       set_eXIf
1388
1389           $png->set_eXIf ($exif);
1390
1391       libpng checks whether the chunk's first two bytes are either "II" for
1392       little-endian (from Intel) or "MM" for big-endian (from Motorola) then
1393       adds the entire chunk, including the first two bytes, to the PNG.
1394
1395       ⛐ðŸĪŠâš  As of December 2020, there appears to be a bug in libpng in which
1396       the eXIf chunk is added twice, causing a warning of the form "libpng
1397       warning: eXIf: duplicate" on reading a PNG file back in. See
1398       <https://github.com/glennrp/libpng/pull/351>.
1399
1400   gAMA
1401       See this subsection <http://www.w3.org/TR/PNG/#11gAMA> of "The PNG
1402       specification".
1403
1404       get_gAMA
1405
1406           my $gamma = $png->get_gAMA ();
1407
1408       Get the gamma value or gAMA chunk. The return value is a floating-point
1409       number.
1410
1411       This function corresponds to "png_get_gAMA" in libpng
1412
1413       set_gAMA
1414
1415           $png->set_gAMA (0.2);
1416
1417       Set the gamma value or gAMA chunk.
1418
1419       This function corresponds to "png_set_gAMA" in libpng
1420
1421   hIST
1422       See this subsection <http://www.w3.org/TR/PNG/#11hIST> of "The PNG
1423       specification".
1424
1425       get_hIST
1426
1427           my $hist = $png->get_hIST ();
1428
1429       If the PNG file contains a histogram, the return value is array
1430       reference, otherwise it is the undefined value. The number of entries
1431       in the array reference is the same as in the palette.
1432
1433       This function corresponds to "png_get_hIST" in libpng
1434
1435       set_hIST
1436
1437           $png->set_hIST (\@hist);
1438
1439       Set the histogram of frequencies of the colors of a paletted ("PLTE")
1440       image. The entries of the histogram are 16 bit unsigned integers, so
1441       the maximum value that can be entered is 65535 = 2^16 - 1. Larger
1442       numbers and floating point numbers will cause a warning to be printed
1443       and the value to be set to zero. The histogram must have exactly the
1444       same number of entries as the palette or the call will fail with a
1445       warning. A histogram cannot be added to an image without a palette. A
1446       call to set_hIST for an image without a palette will cause a warning
1447       and return without setting the value.
1448
1449       (I'm not sure of the best form of error handling for this function so
1450       it may change in future versions to have errors for a bad histogram
1451       rather than warnings.)
1452
1453       This function corresponds to "png_set_hIST" in libpng
1454
1455   iCCP
1456       See this subsection <http://www.w3.org/TR/PNG/#11iCCP> of "The PNG
1457       specification".
1458
1459       get_iCCP
1460
1461           my $iccp = $png->get_iCCP ();
1462
1463       The return value is a hash with two keys,
1464
1465       name
1466           The name of the profile.
1467
1468       profile
1469           The color profile.
1470
1471       The "compression_type" value, which is always 0, is not returned. See
1472       "Unused arguments omitted".
1473
1474       This function corresponds to "png_get_iCCP" in libpng.
1475
1476       set_iCCP
1477
1478           $png->set_iCCP ({name => 'name', profile => 'profile'});
1479
1480       This function corresponds to "png_set_iCCP" in libpng. For details of
1481       the arguments, see "get_iCCP". A "compression_type" argument, which
1482       must always be 0 anyway, is ignored. See "Unused arguments omitted".
1483
1484   oFFs
1485       This is an extension to the PNG specification. See
1486       <http://www.libpng.org/pub/png/spec/1.1/pngext-1.1.0-pdg.html#C.oFFs>.
1487
1488       get_oFFs
1489
1490           my $phys = $png->get_oFFs ();
1491
1492       Get oFFs chunk. Return value is a hash reference
1493
1494       This function corresponds to "png_get_oFFs" in libpng
1495
1496       set_oFFs
1497
1498           $png->set_oFFs ({x_offset => 1, y_offset => 1, unit_type => 0});
1499
1500       Set oFFs chunk. See the specification linked above for the meanings of
1501       the parameters. If "unit_type" is not 0 or 1, a warning is produced.
1502
1503       This function corresponds to "png_set_oFFs" in libpng
1504
1505   pCAL
1506       pCAL is an extension of the PNG specification which allows one to
1507       associate pixels in the PNG image with non-image data such as a heat
1508       map. See
1509       <http://www.libpng.org/pub/png/spec/1.1/pngext-1.1.0-pdg.html#C.pCAL>.
1510
1511       To test whether your version of libpng supports "the pCAL extension",
1512       use "libpng_supports" with argument '"pCAL"':
1513
1514           if (libpng_supports ('pCAL')) {
1515               # do something
1516           }
1517
1518       get_pCAL
1519
1520           my $pcal = $png->get_pCAL ();
1521
1522       The return value is a hash reference with the following keys:
1523
1524       params
1525           If this exists, its value is a reference to an array containing the
1526           parameter list of the pCAL chunk, which are floating point numbers.
1527           Within the PNG file chunk, these parameters are stored as strings
1528           representing floating point numbers, but you can pass in Perl
1529           floating point numbers rather than strings. The number of
1530           parameters you should set is fixed by the "type" parameter. Refer
1531           to the PNG specification for full details.
1532
1533       purpose
1534           The purpose string of the pCAL chunk.
1535
1536       type
1537           The equation type as a number, from 0 to 3. See the PNG
1538           specification for the meanings. Other numbers cause an error.
1539
1540       units
1541           The units as a string. See the PNG specification for details.
1542
1543       x0  The zero value for the equation, an integer.
1544
1545       x1  The max value for the equation, an integer.
1546
1547       This function corresponds to "png_get_pCAL" in libpng
1548
1549       set_pCAL
1550
1551           $png->set_pCAL (\%values);
1552
1553       See "get_pCAL" for the parameters of %values.
1554
1555       This function corresponds to "png_set_pCAL" in libpng
1556
1557   pHYs
1558       See this subsection <http://www.w3.org/TR/PNG/#11pHYs> of "The PNG
1559       specification".
1560
1561       get_pHYs
1562
1563           my $phys = $png->get_pHYs ();
1564
1565       The return value is a hash reference with the keys
1566
1567       res_x
1568       res_y
1569       unit_type
1570           Is either 0 or 1.
1571
1572       This function corresponds to "png_get_pHYs" in libpng
1573
1574       set_pHYs
1575
1576           $png->set_pHYs ({res_x => 1, res_y => 1, unit_type => 1});
1577
1578       This function corresponds to "png_set_pHYs" in libpng
1579
1580   PLTE
1581       See this subsection <http://www.w3.org/TR/PNG/#11PLTE> of "The PNG
1582       specification" for information on the PNG standards for the palette
1583       chunk.
1584
1585       get_palette_max
1586
1587           my $pmax = $png->get_palette_max ();
1588
1589       If your libpng supports it, this will return the maximum palette index
1590       found in the image, or "-1" if the palette was not checked, or "0" if
1591       no palette was found.
1592
1593       To test whether your version of libpng supports "get_palette_max", use
1594       "libpng_supports" with argument '"GET_PALETTE_MAX"':
1595
1596           if (libpng_supports ('GET_PALETTE_MAX')) {
1597               # do something
1598           }
1599
1600       ⛐ðŸĪŠâš  This function is implemented but so far it is not very clear to me
1601       what it does, since, for example, it returns zero for the test image
1602       t/tantei-san.png which is an image with a fully-used 256-color palette.
1603       I've asked about it on the libpng mailing list
1604       <https://sourceforge.net/p/png-mng/mailman/png-mng-
1605       implement/?viewmonth=202012&viewday=14>, but so far nobody has
1606       responded.
1607
1608       get_PLTE
1609
1610            my $colors = $png->get_PLTE ();
1611            # Get the green value of the twentieth entry in the palette.
1612            my $green = $colors->[20]->{green};
1613
1614       This function gets the palette from the PNG. The return value is an
1615       array reference containing the palette. This array contains hash
1616       references with the values "green", "blue" and "red" for the color of
1617       each pixel in the palette. If the PNG has no palette, it returns an
1618       undefined value.
1619
1620       A PNG image may or may not contain a palette. To check whether the
1621       image contains a palette, use something of the following form:
1622
1623            use Image::PNG::Const ':all';
1624            my $color_type = $png->get_color_type ();
1625            if ($color_type == PNG_COLOR_TYPE_PALETTE) {
1626                # The PNG uses a palette.
1627            }
1628
1629       A PNG image may also contain a palette even when the "color_type" does
1630       not indicate that. To check for that case, use "get_valid".
1631
1632       This function corresponds to "png_get_PLTE" in libpng.
1633
1634       set_PLTE
1635
1636           $png->set_PLTE ($palette);
1637
1638       Set the palette of $png. The argument is an array reference containing
1639       hash references. There is one hash reference for each palette entry.
1640       The hash references contain three fields, red, green, and blue,
1641       corresponding to the pixel value for that palette entry. Other values
1642       in the hash references are ignored. For example,
1643
1644           $png->set_PLTE ([{red => 1, green => 99, blue => 0x10},
1645                            {red => 0xFF, green => 0xFF, blue => 0xFF}]);
1646
1647       creates a palette with two entries in $png.
1648
1649       This function corresponds to "png_set_PLTE" in libpng.
1650
1651   sBIT
1652       See this subsection <http://www.w3.org/TR/PNG/#11sBIT> of "The PNG
1653       specification".
1654
1655       get_sBIT
1656
1657           my $sbit = $png->get_sBIT ();
1658
1659       The return value is a hash reference containing integer values for the
1660       keys "red", "blue", "green", "gray" and "alpha", depending on the
1661       "color_type" of $png.
1662
1663       ⛐ðŸĪŠâš  Prior to version 0.50 of this module, get_sBIT wrote values of 0
1664       for all of the keys, regardless of the "color_type", causing errors in
1665       some circumstances. From version 0.50, hash keys are not entered if the
1666       "color_type" of the image makes them invalid.
1667
1668       This function corresponds to "png_get_sBIT" in libpng
1669
1670       set_sBIT
1671
1672           $png->set_sBIT ({red => 1, blue => 2, green => 3});
1673
1674       The argument is a hash reference containing integer values for the keys
1675       "red", "blue", "green", "gray", and "alpha", as required by the
1676       "color_type" of $png.
1677
1678       This function corresponds to "png_set_sBIT" in libpng
1679
1680   sCAL
1681       This is an extension to the PNG specification. See
1682       <http://www.libpng.org/pub/png/spec/1.1/pngext-1.1.0-pdg.html#C.sCAL>.
1683
1684       To test whether your version of libpng supports "the sCAL chunk", use
1685       "libpng_supports" with argument '"sCAL"':
1686
1687           if (libpng_supports ('sCAL')) {
1688               # do something
1689           }
1690
1691       get_sCAL
1692
1693           my $scal = $png->get_sCAL ();
1694
1695       The returned hash value contains the following keys:
1696
1697       unit
1698           The unit type, which is either PNG_SCALE_UNKNOWN, PNG_SCALE_METER,
1699           or PNG_SCALE_RADIAN.
1700
1701       width
1702           The width, as a string.
1703
1704       height
1705           The height, as a string.
1706
1707       This function corresponds to "png_get_sCAL_s" in libpng. Note that this
1708       uses the sCAL_s function rather than the get_sCAL and the returned
1709       values are the strings themselves rather than parsed numbers.
1710
1711       set_sCAL
1712
1713           $png->set_sCAL ($scal);
1714
1715       $scal is a hash reference containing the keys described in "get_sCAL".
1716
1717       This function corresponds to "png_set_sCAL_s" in libpng. Note that this
1718       uses the "set_sCAL_s" function rather than "set_sCAL" and the input
1719       values are the strings themselves rather than numbers.
1720
1721   sPLT
1722       See this subsection <http://www.w3.org/TR/PNG/#11sPLT> of "The PNG
1723       specification".
1724
1725       get_sPLT
1726
1727       ⛐ðŸĪŠâš  Provisional. See "set_sPLT" for documentation, the return value is
1728       like the input of that.
1729
1730       set_sPLT
1731
1732           $png->set_sPLT ([{ name => 'palette', depth => 8, entries => [{red => 1, blue => 2},]}]);
1733
1734       Set suggested palettes. The input is an array reference containing hash
1735       references with the following fields:
1736
1737       name
1738           The name of the suggested palette.
1739
1740       depth
1741           The depth of the suggested palette.
1742
1743       entries
1744           The entries of the palette. This is an array reference containing
1745           hash references with keys as follows:
1746
1747           red
1748           blue
1749           green
1750           frequency
1751           alpha
1752
1753       The field "nentries" which is returned by "get_sPLT" does not need to
1754       be specified, it is calculated from the length of "entries".
1755
1756   sRGB
1757       See this subsection <http://www.w3.org/TR/PNG/#11sRGB> of "The PNG
1758       specification".
1759
1760       get_sRGB
1761
1762           my $sRGB = $png->get_sRGB ();
1763
1764       The return value is an integer number corresponding to one of the
1765       following:
1766
1767       PNG_sRGB_INTENT_SATURATION
1768       PNG_sRGB_INTENT_PERCEPTUAL
1769       PNG_sRGB_INTENT_ABSOLUTE
1770       PNG_sRGB_INTENT_RELATIVE
1771
1772       This function corresponds to "png_get_sRGB" in libpng
1773
1774       set_sRGB
1775
1776           $png->set_sRGB ($srgb);
1777
1778       $srgb is one of the values described in "get_sRGB".
1779
1780       This function corresponds to "png_set_sRGB" in libpng
1781
1782   tIME
1783       See this subsection <http://www.w3.org/TR/PNG/#11timestampinfo> of "The
1784       PNG specification" for information on the PNG standards for time stamp
1785       information.
1786
1787       get_tIME
1788
1789           my $time = $png->get_tIME ();
1790           if ($time && $time->{year} < 2005) {
1791               warn "Your PNG is now getting old. Don't forget to oil it to prevent rust.";
1792           }
1793
1794       The return value is either the undefined value, if no "tIME" chunk
1795       exists in the PNG, or a hash reference containing fields "year",
1796       "month", "day", "hour", "minute" and "second". "month" and "day" start
1797       from 1 rather than 0.
1798
1799       The "modification time value" of the PNG image is a chunk written into
1800       the PNG file itself, and may not have the same value as the operating
1801       system's modification time for the file. The tIME chunk is not a
1802       compulsory requirement for PNG files, and most PNG image files do not
1803       contain this chunk. PNG tIME chunks do not contain a time zone.
1804       According to this subsection <http://www.w3.org/TR/PNG/#11tIME> of "The
1805       PNG specification", "Universal Time (UTC) should be specified rather
1806       than local time."
1807
1808       This function corresponds to "png_get_tIME" in libpng, with a Perl hash
1809       reference substituted for the C struct "png_timep" used in libpng.
1810
1811       set_tIME
1812
1813           # Set the time to "now"
1814           $png->set_tIME ();
1815           # Set the time
1816           $png->set_tIME ({year => 1999, month => 12});
1817
1818       Set the modification time of the PNG to the values given by the
1819       argument, a hash reference containing the fields "year", "month", "day"
1820       for the day of the month, "hour", "minute", and "second".  The
1821       numbering for "month" and "day" is from 1, not 0. If any of year, hour,
1822       minute or second is omitted from the hash reference, these are set to
1823       zero. If month or day are omitted, these are set to 1.  PNG tIME chunks
1824       do not contain a time zone. According to this subsection
1825       <http://www.w3.org/TR/PNG/#11tIME> of "The PNG specification",
1826       "Universal Time (UTC) should be specified rather than local time." If
1827       the entire argument is omitted or contains an invalid value, the time
1828       is set to the current time.
1829
1830       This function corresponds to "png_set_tIME" in libpng, with a Perl hash
1831       reference substituted for the C struct "png_timep" used in libpng.
1832
1833   tRNS
1834       See this subsection <http://www.w3.org/TR/PNG/#11tRNS> of "The PNG
1835       specification".
1836
1837       get_tRNS
1838
1839           my $trns = $png->get_tRNS ();
1840
1841       Get the "tRNS" chunk. If the image is a palette type, this is an array
1842       reference. If the image is a non-palette type, this is a hash
1843       containing values for the keys red, green, blue, and gray.
1844
1845       set_tRNS
1846
1847           $png->set_tRNS ($trns);
1848
1849       Set the "tRNS" chunk. If the image is a palette type, $trns is a
1850       reference to an array of positive or zero values between 0 and 255 of
1851       the same size as the palette. It must not contain more than 256 values.
1852       If the image is not a palette type, $trns is a hash reference
1853       containing values for the keys red, green, blue and gray.
1854

Libpng transformations

1856   set_bgr
1857           $png->set_bgr ();
1858
1859       ⛐ðŸĪŠâš  Untested. Flips RGB to BGR. See the libpng manual for details.
1860
1861       To test whether your version of libpng supports "set_bgr", for a read
1862       object, use "libpng_supports" with argument '"READ_BGR"'.
1863
1864           if (libpng_supports ('READ_BGR')) {
1865               # do something
1866           }
1867
1868       For a write object, use argument '"WRITE_BGR"'.
1869
1870       This function corresponds to "png_set_bgr" in libpng
1871
1872   set_expand
1873           $png->set_expand ();
1874
1875       Set transformation in $png such that paletted images are expanded to
1876       RGB, grayscale images of bit-depth less than 8 are expanded to 8-bit
1877       images, and tRNS chunks are expanded to alpha channels.
1878
1879       To test whether your version of libpng supports "set_expand", use
1880       "libpng_supports" with argument '"READ_EXPAND"':
1881
1882           if (libpng_supports ('READ_EXPAND')) {
1883               # do something
1884           }
1885
1886       This function corresponds to "png_set_expand" in libpng
1887
1888   set_expand_16
1889           $png->set_expand_16 ();
1890
1891       ⛐ðŸĪŠâš  Untested.
1892
1893       To test whether your version of libpng supports "set_expand_16", use
1894       "libpng_supports" with argument '"READ_EXPAND_16"':
1895
1896           if (libpng_supports ('READ_EXPAND_16')) {
1897               # do something
1898           }
1899
1900       This function corresponds to "png_set_expand_16" in libpng
1901
1902   set_expand_gray_1_2_4_to_8
1903           $png->set_expand_gray_1_2_4_to_8 ();
1904
1905       ⛐ðŸĪŠâš  Untested.
1906
1907       To test whether your version of libpng supports
1908       "set_expand_gray_1_2_4_to_8", use "libpng_supports" with argument
1909       '"READ_EXPAND"':
1910
1911           if (libpng_supports ('READ_EXPAND')) {
1912               # do something
1913           }
1914
1915       This function corresponds to "png_set_expand_gray_1_2_4_to_8" in libpng
1916
1917   set_gray_to_rgb
1918           $png->set_gray_to_rgb ();
1919
1920       Convert a grayscale PNG file to RGB format on reading.
1921
1922       To test whether your version of libpng supports "set_gray_to_rgb", use
1923       "libpng_supports" with argument '"READ_GRAY_TO_RGB"':
1924
1925           if (libpng_supports ('READ_GRAY_TO_RGB')) {
1926               # do something
1927           }
1928
1929       This function corresponds to "png_set_gray_to_rgb" in libpng
1930
1931   set_invert_alpha
1932           $png->set_invert_alpha ();
1933
1934       ⛐ðŸĪŠâš  Untested. See the libpng manual for details.
1935
1936       To test whether your version of libpng supports "set_invert_alpha", use
1937       "libpng_supports" with argument '"READ_INVERT_ALPHA"':
1938
1939           if (libpng_supports ('READ_INVERT_ALPHA')) {
1940               # do something
1941           }
1942
1943       This function corresponds to "png_set_invert_alpha" in libpng
1944
1945   set_invert_mono
1946           $png->set_invert_mono ();
1947
1948       Invert monochrome images. See the libpng manual for details.
1949
1950       To test whether your version of libpng supports "set_invert_mono", use
1951       "libpng_supports" with argument '"READ_INVERT"':
1952
1953           if (libpng_supports ('READ_INVERT')) {
1954               # do something
1955           }
1956
1957       This function corresponds to "png_set_invert_mono" in libpng
1958
1959   set_packing
1960           $png->set_packing ();
1961
1962       When reading a PNG, expand the image to 1 pixel per byte for bit-depths
1963       1, 2 and 4 without changing the order of the pixels. If this is not
1964       called, the pixels of bit_depths 1, 2 and 4 are packed into bytes as
1965       small as possible, for example, 8 pixels per byte for 1-bit files. See
1966       the libpng manual for details.  See also "set_packswap".
1967
1968       To test whether your version of libpng supports "set_packing", for a
1969       read object, use "libpng_supports" with argument '"READ_PACK"'.
1970
1971           if (libpng_supports ('READ_PACK')) {
1972               # do something
1973           }
1974
1975       For a write object, use argument '"WRITE_PACK"'.
1976
1977       This function corresponds to "png_set_packing" in libpng
1978
1979   set_packswap
1980           $png->set_packswap ();
1981
1982       Swaps the bits of 1, 2, or 4 bits/pixel images. The default for PNG
1983       image is to put the left pixel into the highest part of the byte, so
1984       for example if the bit depth is 1, the pixels from left to right go
1985       into a byte as values 128 for the leftmost, 64, 32, 16, 8, 4, 2, then 1
1986       for the rightmost pixel. This call reverses that behavior so that the
1987       pixels in a byte go 1 for the leftmost, 2, ..., then 128 for the
1988       rightmost. See the libpng manual for details.
1989
1990       To test whether your version of libpng supports "set_packswap", for a
1991       read object, use "libpng_supports" with argument '"READ_PACKSWAP"'.
1992
1993           if (libpng_supports ('READ_PACKSWAP')) {
1994               # do something
1995           }
1996
1997       For a write object, use argument '"WRITE_PACKSWAP"'.
1998
1999       This function corresponds to "png_set_packswap" in libpng
2000
2001   set_palette_to_rgb
2002           $png->set_palette_to_rgb ();
2003
2004       ⛐ðŸĪŠâš  Untested. See the libpng manual for details.
2005
2006       To test whether your version of libpng supports "set_palette_to_rgb",
2007       use "libpng_supports" with argument '"READ_EXPAND"':
2008
2009           if (libpng_supports ('READ_EXPAND')) {
2010               # do something
2011           }
2012
2013       This function corresponds to "png_set_palette_to_rgb" in libpng
2014
2015   set_scale_16
2016           $png->set_scale_16 ()
2017
2018       ⛐ðŸĪŠâš  Untested.
2019
2020       To test whether your version of libpng supports "set_scale_16", use
2021       "libpng_supports" with argument '"READ_SCALE_16_TO_8"':
2022
2023           if (libpng_supports ('READ_SCALE_16_TO_8')) {
2024               # do something
2025           }
2026
2027       This function corresponds to "png_set_scale_16" in libpng
2028
2029   set_strip_16
2030           $png->set_strip_16 ();
2031
2032       Strip the pixels of a PNG stream with 16 bits per channel to 8 bits per
2033       channel.
2034
2035       To test whether your version of libpng supports "set_strip_16", use
2036       "libpng_supports" with argument '"READ_STRIP_16_TO_8"':
2037
2038           if (libpng_supports ('READ_STRIP_16_TO_8')) {
2039               # do something
2040           }
2041
2042       This function corresponds to "png_set_strip_16" in libpng
2043
2044   set_strip_alpha
2045           $png->set_strip_alpha ();
2046
2047       Strip the alpha channel of a PNG stream.
2048
2049       To test whether your version of libpng supports "set_strip_alpha", use
2050       "libpng_supports" with argument '"READ_STRIP_ALPHA"':
2051
2052           if (libpng_supports ('READ_STRIP_ALPHA')) {
2053               # do something
2054           }
2055
2056       This function corresponds to "png_set_strip_alpha" in libpng
2057
2058   set_swap
2059           $png->set_swap ();
2060
2061       ⛐ðŸĪŠâš  Untested. Swaps around the bytes of 16 bits/pixel images. See the
2062       libpng manual for details.
2063
2064       To test whether your version of libpng supports "set_swap", use
2065       "libpng_supports" with argument '"READ_SWAP"':
2066
2067           if (libpng_supports ('READ_SWAP')) {
2068               # do something
2069           }
2070
2071       This function corresponds to "png_set_swap" in libpng
2072
2073   set_swap_alpha
2074           $png->set_swap_alpha ();
2075
2076       ⛐ðŸĪŠâš  Untested.  See the libpng manual for details.
2077
2078       To test whether your version of libpng supports "set_swap_alpha", use
2079       "libpng_supports" with argument '"READ_SWAP_ALPHA"':
2080
2081           if (libpng_supports ('READ_SWAP_ALPHA')) {
2082               # do something
2083           }
2084
2085       This function corresponds to "png_set_swap_alpha" in libpng
2086
2087   set_tRNS_to_alpha
2088           $png->set_tRNS_to_alpha
2089
2090       ⛐ðŸĪŠâš  Untested. See the libpng manual for details.
2091
2092       To test whether your version of libpng supports "set_tRNS_to_alpha",
2093       use "libpng_supports" with argument '"READ_EXPAND"':
2094
2095           if (libpng_supports ('READ_EXPAND')) {
2096               # do something
2097           }
2098
2099       This function corresponds to "png_set_tRNS_to_alpha" in libpng
2100

Other libpng functions

2102   get_chunk_cache_max
2103           my $max = $png->get_chunk_cache_max ();
2104
2105       Get the maximum number of ancilliary chunks allowed. See also
2106       "set_chunk_cache_max".
2107
2108       To test whether your version of libpng supports "get_chunk_cache_max",
2109       use "libpng_supports" with argument '"CHUNK_CACHE_MAX"':
2110
2111           if (libpng_supports ('CHUNK_CACHE_MAX')) {
2112               # do something
2113           }
2114
2115       This function corresponds to "png_png_get_chunk_cache_max" in libpng
2116
2117   get_rgb_to_gray_status
2118           my $badpixels = $png->get_rgb_to_gray_status ();
2119
2120       Returns a true value if there were some non-gray pixels in an RGB image
2121       after calling "set_rgb_to_gray".
2122
2123       Saving bandwidth
2124
2125       Try this one weird old "get_rgb_to_gray_status" trick to check whether
2126       an image marked as RGB is really monochrome or not.
2127
2128           use utf8;
2129           use FindBin '$Bin';
2130           use Image::PNG::Libpng ':all';
2131           use Image::PNG::Const ':all';
2132
2133           my $file = 'life.png';
2134           print "Size before: ", -s $file, "\n";
2135           my $png = create_reader ($file);
2136           $png->read_info ();
2137           $png->set_rgb_to_gray ();
2138           if ($png->get_rgb_to_gray_status ()) {
2139               print "The image contained non-gray pixels.\n";
2140           }
2141           else {
2142               print "The image was grayscale already.\n";
2143           }
2144           $png->read_image ();
2145           $png->read_end ();
2146           my $wpng = $png->copy_png ();
2147           my $ihdr = $wpng->get_IHDR ();
2148           $ihdr->{color_type}  = PNG_COLOR_TYPE_GRAY;
2149           $wpng->set_IHDR ($ihdr);
2150           my $after = "life-gray.png";
2151           $wpng->write_png_file ($after);
2152           print "Size after: ", -s $after, "\n";
2153
2154           if (! png_compare ($file, $after)) {
2155               print "The two files contain exactly the same image data.\n";
2156           }
2157           else {
2158               print "The two files contain different image data.\n";
2159           }
2160
2161       (This example is included as examples/xkcd.pl
2162       <https://fastapi.metacpan.org/source/BKB/Image-PNG-
2163       Libpng-0.57/examples/xkcd.pl> in the distribution.)
2164
2165       The output looks like this:
2166
2167           Size before: 97299
2168           The image was grayscale already.
2169           Size after: 46956
2170           The two files contain exactly the same image data.
2171
2172       examples/life-gray.png <https://fastapi.metacpan.org/source/BKB/Image-
2173       PNG-Libpng-0.57/examples/life-gray.png> is included in the
2174       distribution.
2175
2176       Correct use of Image::PNG::Libpng could have spared as many as 50,000
2177       bytes from the indignity of being sent around the internet.
2178
2179       This also illustrates the use of "png_compare".
2180
2181       Original image, licence statement and copyright notice here
2182       <https://xkcd.com/2391/>.
2183
2184   get_user_height_max
2185           $png->get_user_height_max ();
2186
2187       Get the maximum height allowed for a PNG file. The default is 1 million
2188       pixels. These values can be changed by "set_user_limits".
2189
2190       This function corresponds to "png_get_user_height_max" in libpng
2191
2192   get_user_width_max
2193           $png->get_user_width_max ();
2194
2195       Get the maximum width allowed for a PNG file. The default is 1 million
2196       pixels. These values can be changed by "set_user_limits".
2197
2198       This function corresponds to "png_get_user_width_max" in libpng
2199
2200   permit_mng_features
2201           $png->permit_mng_features ($mask);
2202
2203       ⛐ðŸĪŠâš  Untested. $mask is an integer containing flags. See the libpng
2204       manual for details.
2205
2206       (MNG, 'Multiple-image Network Graphics', is an image animation format
2207       related to PNG. It has not been widely adopted.)
2208
2209       To test whether your version of libpng supports "permit_mng_features",
2210       use "libpng_supports" with argument '"MNG_FEATURES"':
2211
2212           if (libpng_supports ('MNG_FEATURES')) {
2213               # do something
2214           }
2215
2216       This function corresponds to "png_permit_mng_features" in libpng
2217
2218   set_add_alpha
2219           $png->set_add_alpha ($filler, $filler_loc);
2220
2221       ⛐ðŸĪŠâš  Untested. Change $png to add an alpha channel. This only works for
2222       grayscale or RGB images with bit depth of 8 or 16. $filler contains the
2223       alpha value to assign to each pixel, and $filler_loc is either
2224       "PNG_FILLER_BEFORE" or "PNG_FILLER_AFTER". The function of
2225       "set_add_alpha" is "set_filler" and a change of the color type to add
2226       an alpha channel. See the libpng manual for details.
2227
2228       To test whether your version of libpng supports "set_add_alpha", use
2229       "libpng_supports" with argument '"READ_FILLER"':
2230
2231           if (libpng_supports ('READ_FILLER')) {
2232               # do something
2233           }
2234
2235       This function corresponds to "png_set_add_alpha" in libpng
2236
2237   set_alpha_mode
2238           $png->set_alpha_mode ($mode, $screen_gamma);
2239
2240       ⛐ðŸĪŠâš  Untested. $mode is an integer, one of the "PNG_ALPHA_*" constants.
2241       $screen_gamma is a floating point number. See the libpng manual for
2242       details.
2243
2244       To test whether your version of libpng supports "set_alpha_mode", use
2245       "libpng_supports" with argument '"READ_ALPHA_MODE"':
2246
2247           if (libpng_supports ('READ_ALPHA_MODE')) {
2248               # do something
2249           }
2250
2251       This function corresponds to "png_set_alpha_mode" in libpng
2252
2253   set_background
2254           $png->set_background (\%color, $bkgd_gamma_code, $need_expand, $gamma);
2255
2256       "set_background" sets the background of an image with an alpha channel
2257       or simple transparency (a "tRNS" chunk) with the color specified by
2258       %color. If $bkgd_gamma_code is set to "PNG_BACKGROUND_GAMMA_SCREEN", it
2259       indicates that the supplied background color is in the gamma space of
2260       the display, else if it is set to "PNG_BACKGROUND_GAMMA_FILE", the
2261       color is in the gamma space of the file. If $bkgd_gamma_code is set to
2262       "PNG_BACKGROUND_GAMMA_UNIQUE", the value of $gamma is used, otherwise
2263       $gamma appears to be ignored and can be omitted. (This is not
2264       documented in the libpng manual or elsewhere. See
2265       <https://github.com/glennrp/libpng/issues/358>.)
2266
2267       If the background color is supplied at the original bit-depth for a
2268       grayscale image that is expanded to truecolor or to a higher bit-depth,
2269       $need_expand must be set to a true value, but if the background color
2270       is supplied at the expanded bit-depth, $need_expand must be set to a
2271       false value. Similarly for paletted images, if %color is supplied as a
2272       palette index ($color{index}), $need_expand must be set to a true
2273       value, but if %color is an RGB triplet, $need_expand must be set to a
2274       false value.
2275
2276       See "Setting the background" for an example.
2277
2278       To test whether your version of libpng supports "set_background", use
2279       "libpng_supports" with argument '"READ_BACKGROUND"':
2280
2281           if (libpng_supports ('READ_BACKGROUND')) {
2282               # do something
2283           }
2284
2285   set_chunk_cache_max
2286           $png->set_chunk_cache_max (42);
2287
2288       Set the maximum number of ancilliary chunks allowed. The default is
2289       1000. See also "get_chunk_cache_max".
2290
2291       To test whether your version of libpng supports "set_chunk_cache_max",
2292       use "libpng_supports" with argument '"CHUNK_CACHE_MAX"':
2293
2294           if (libpng_supports ('CHUNK_CACHE_MAX')) {
2295               # do something
2296           }
2297
2298       This function corresponds to "png_png_set_chunk_cache_max" in libpng
2299
2300   set_filler
2301           $png->set_filler ($filler, $flags);
2302
2303       Set transformations in $png such that a filler byte $filler is added
2304       when an 8-bit grayscale image or 24-bit RGB image is read, and a filler
2305       byte is deleted when an 8-bit grayscale image or 24-bit RGB image is
2306       written. $flags may be "PNG_FILLER_BEFORE" or "PNG_FILLER_AFTER". An
2307       error is produced if $png has bit depth less than 8.
2308
2309       This does not change the color type of the image. See the related
2310       function "set_add_alpha" if you want to add an alpha channel.
2311
2312       To test whether your version of libpng supports "set_filler", use
2313       "libpng_supports" with argument '"READ_FILLER"':
2314
2315           if (libpng_supports ('READ_FILLER')) {
2316               # do something
2317           }
2318
2319       This function corresponds to "png_set_filler" in libpng
2320
2321   set_gamma
2322           $png->set_gamma ($screen_gamma, $output_gamma);
2323
2324       ⛐ðŸĪŠâš  Untested. $screen_gamma and $output_gamma should contain floating-
2325       point arguments.  See the libpng manual for details.
2326
2327       To test whether your version of libpng supports "set_gamma", use
2328       "libpng_supports" with argument '"READ_GAMMA"':
2329
2330           if (libpng_supports ('READ_GAMMA')) {
2331               # do something
2332           }
2333
2334       This function corresponds to "png_set_gamma" in libpng
2335
2336   set_quantize
2337           $png->set_quantize (\@palette, $ncolors, \@histogram, $full_quantize);
2338
2339       The @palette part must be set to a palette similar to "set_PLTE".
2340       $ncolors must be the length of @palette or shorter. @histogram can be
2341       an empty array or if not it needs to be an array of integers of exactly
2342       the same length as @palette. The integers represent the frequency of
2343       the colors in @palette. These integers can range from 0 to 65355.
2344       Larger values or negative values cause an error. The final argument,
2345       $full_quantize, should be 1 for RGB images or 0 for paletted images.
2346
2347       Experiments in quantization
2348
2349       This example program experiments with two ways to quantize a PNG image,
2350       first of all using a completely random palette, and second using colors
2351       picked from the image at random:
2352
2353           use utf8;
2354           use FindBin '$Bin';
2355           use Image::PNG::Libpng ':all';
2356           my $file = "wave.png";
2357           my $ncolors = 40;
2358           my $palette = randompalette ($ncolors);
2359           write_with_palette ($file, $palette, $ncolors, [], "random");
2360           my $picked = points ($file, $ncolors);
2361           my @hist = (1) x $ncolors;
2362           write_with_palette ($file, $picked, $ncolors, \@hist, "picked");
2363           exit;
2364
2365           sub write_with_palette
2366           {
2367               my ($file, $palette, $ncolors, $hist, $name) = @_;
2368               my $rpng = create_reader ($file);
2369               $rpng->set_quantize ($palette, $ncolors, $hist, 1);
2370               $rpng->read_png ();
2371               my $wpng = copy_png ($rpng);
2372               $wpng->set_PLTE ($palette);
2373               $wpng->write_png_file ("$name-$file");
2374           }
2375
2376           sub points
2377           {
2378               my ($pngfile, $ncolors) = @_;
2379               my $png = read_png_file ($pngfile);
2380               my $rows = $png->get_rows ();
2381               my $h = $png->height ();
2382               my $w = $png->width ();
2383               my $ch = $png->get_channels ();
2384               my @p;
2385               for (0..$ncolors-1) {
2386                   my $x = int (rand ($w));
2387                   my $y = int (rand ($h));
2388                   my $row = $rows->[$y];
2389                   my @pix = split ('', substr ($row, $x*$ch, $ch));
2390                   push @p, {
2391                       red => ord ($pix[0]),
2392                       green => ord ($pix[1]),
2393                       blue => ord ($pix[2]),
2394                   };
2395               }
2396               return \@p;
2397           }
2398
2399           sub randompalette
2400           {
2401               my ($n) = @_;
2402               my @p;
2403               for (0..$n-1) {
2404                   my %color;
2405                   for my $c (qw!red green blue!) {
2406                       $color{$c} = int (rand (256))
2407                   }
2408                   push @p, \%color;
2409               }
2410               return \@p;
2411           }
2412
2413       (This example is included as examples/q.pl
2414       <https://fastapi.metacpan.org/source/BKB/Image-PNG-
2415       Libpng-0.57/examples/q.pl> in the distribution.)
2416
2417       examples/wave.png <https://fastapi.metacpan.org/source/BKB/Image-PNG-
2418       Libpng-0.57/examples/wave.png> is included in the distribution.
2419
2420       examples/random-wave.png
2421       <https://fastapi.metacpan.org/source/BKB/Image-PNG-
2422       Libpng-0.57/examples/random-wave.png> is included in the distribution.
2423
2424       examples/picked-wave.png
2425       <https://fastapi.metacpan.org/source/BKB/Image-PNG-
2426       Libpng-0.57/examples/picked-wave.png> is included in the distribution.
2427
2428   set_rgb_to_gray
2429           $png->set_rgb_to_gray ();
2430
2431           $png->set_rgb_to_gray ($error_action, $red_weight, $green_weight);
2432
2433       Convert a PNG image from RGB (colored) to gray. See the libpng manual
2434       for details.
2435
2436       Without arguments, the libpng default values are used for $red_weight
2437       and $green_weight, and an error action of "none" is chosen. If the
2438       error action is set to a value of "PNG_ERROR_ACTION_WARN" or
2439       "PNG_ERROR_ACTION_ERROR", pixels in the RGB image where the R, G and B
2440       values are not equal will cause a warning or error respectively. To get
2441       the default values for $red_weight or $green_weight, use any negative
2442       value. See the libpng manual for details.
2443
2444       If you choose "PNG_ERROR_ACTION_NONE" you can find out whether there
2445       were non-RGB pixels in your image using "get_rgb_to_gray_status".
2446
2447       This function corresponds to "png_png_set_rgb_to_gray" in libpng with
2448       $error_action having a default value of "PNG_ERROR_ACTION_NONE", and
2449       $red_weight and $green_weight both set to negative values.
2450
2451       Convert a colored image to gray
2452
2453           use utf8;
2454           use FindBin '$Bin';
2455           use Image::PNG::Libpng ':all';
2456           use Image::PNG::Const ':all';
2457
2458           my $png = create_reader ("$Bin/luv.png");
2459           $png->read_info ();
2460           $png->set_rgb_to_gray ();
2461           $png->read_image ();
2462           $png->read_end ();
2463           my $wpng = $png->copy_png ();
2464           my $ihdr = $wpng->get_IHDR ();
2465           $ihdr->{color_type}  = PNG_COLOR_TYPE_GRAY_ALPHA;
2466           $wpng->set_IHDR ($ihdr);
2467           $wpng->write_png_file ("$Bin/grayface.png");
2468
2469       (This example is included as examples/rgb-to-gray.pl
2470       <https://fastapi.metacpan.org/source/BKB/Image-PNG-
2471       Libpng-0.57/examples/rgb-to-gray.pl> in the distribution.)
2472
2473       examples/grayface.png <https://fastapi.metacpan.org/source/BKB/Image-
2474       PNG-Libpng-0.57/examples/grayface.png> is included in the distribution.
2475
2476   set_user_limits
2477           $png->set_user_limits ($width, $height);
2478
2479       This enables a user to override libpng's restrictions to one million
2480       pixels in width and one million pixels in height for a PNG image.
2481
2482       This function corresponds to "png_set_user_limits" in libpng
2483

Other functions

2485       This section contains other functions which don't correspond to
2486       anything in libpng itself, but which have been added to the module for
2487       utility.
2488
2489   any2gray8
2490           my $wpng = any2gray8 ("any.png");
2491
2492       Convert any type of PNG file whatsoever into a bit-depth 8 grayscale
2493       image without an alpha channel (PNG_COLOR_TYPE_GRAY). The return value
2494       is a writing structure as made by "create_write_struct".
2495
2496       Currently the "tRNS" chunk is ignored by this.
2497
2498       By default the alpha channel is set to either the value of the "bKGD"
2499       chunk if there is one, or white if not. You can set another background
2500       using the option "bkgd":
2501
2502           my $wpng = any2gray8 ('any.png', bkgd => {red => 255, green => 0, blue => 99});
2503
2504       This will of course be ignored if any.png does not contain an alpha
2505       channel. RGB to gray conversion is done using "set_rgb_to_gray" with
2506       the default values.
2507
2508       This function is not supported for versions of libpng earlier than
2509       1.6.14.
2510
2511   color_type_channels
2512           my $channels = color_type_channels ('PNG_COLOR_TYPE_RGB_ALPHA');
2513
2514       Returns the number of channels (the number of components of one pixel)
2515       of the specified color type.
2516
2517   copy_row_pointers
2518           $png->copy_row_pointers ($row_pointers);
2519
2520       This allows XS routines to directly set the value of the row pointers
2521       for the PNG image. The memory is copied, so whatever is in the row
2522       pointers can be freed immediately after calling this. However, the
2523       image data it points to is not copied, so this needs to be valid until
2524       the PNG is written.
2525
2526       The Perl scalar $row_pointers should be set up something like the
2527       following (where "rp" is the C pointer):
2528
2529           RETVAL = newSViv (PTR2IV (rp));
2530
2531       It's extracted from the Perl scalar using
2532
2533           rp = INT2PTR (png_byte **, SvIV (row_pointers));
2534
2535       where row_pointers is the "SV *" corresponding to $row_pointers in the
2536       Perl script. See also "set_row_pointers" which does the same thing but
2537       takes ownership of the memory.
2538
2539   get_chunk
2540           my $timechunk = $png->get_chunk ('tIME');
2541
2542       Get the specified chunk. This produces a fatal error if asked for the
2543       "IDAT" (image data) chunk, use "get_rows" instead. Returns "undef" if
2544       asked for an unknown chunk name.
2545
2546       This is used by pnginspect to get the valid chunks. See also
2547       "set_chunk".
2548
2549   get_internals
2550           my ($png_struct, $png_info) = get_internals ($png);
2551
2552       This function returns the "png_structp" and "png_infop" contained in
2553       $png. The return value is a list containing the "png_structp" as the
2554       first argument and the "png_infop" as the second argument, wrapped up
2555       as references to objects of type "Image::PNG::Libpng::png_struct" and
2556       "Image::PNG::Libpng::png_info".
2557
2558       To access the values of the pointers, use something like this:
2559
2560           void access_png_internals (png, info)
2561               SV * png;
2562               SV * info;
2563           PREINIT:
2564               png_struct * cpng;
2565               png_info * cinfo;
2566           CODE:
2567               cpng = INT2PTR (png_struct *, SvIV (png));
2568               cinfo = INT2PTR (png_info *, SvIV (info));
2569
2570       An example exists in Image::PNG::Cairo.
2571
2572   get_tRNS_palette
2573           $png->get_tRNS_palette ();
2574
2575       This is not a libpng-equivalent function.
2576
2577   image_data_diff
2578           my $diff = image_data_diff ('a.png', 'b.png');
2579
2580       This returns the undefined value if the image data in a.png is the same
2581       as the image data in b.png. If the image data is different, it returns
2582       a readable text message describing the first difference found, for
2583       example the height is different, or row 0 of the image data is
2584       different, etc.
2585
2586       This function is used in testing this module. See also "png_compare".
2587
2588   libpng_supports
2589           if (libpng_supports ('iTXt')) {
2590               print "Your libpng supports international text.\n";
2591           }
2592
2593       This function returns true or false depending on whether the version of
2594       libpng which this was compiled with supports or does not support a
2595       particular facility. For the most part, these are taken directly from
2596       the C macros of libpng.
2597
2598       The possible arguments to "libpng_supports" are:
2599
2600       16BIT
2601       ALIGNED_MEMORY
2602       ARM_NEON_API
2603       BENIGN_ERRORS
2604       BENIGN_READ_ERRORS
2605       BENIGN_WRITE_ERRORS
2606       bKGD
2607           Does the libpng support the "bKGD" chunk?
2608
2609       BUILD_GRAYSCALE_PALETTE
2610       BUILTIN_BSWAP16
2611       CHECK_FOR_INVALID_INDEX
2612       cHRM
2613           Does the libpng support the "cHRM" chunk?
2614
2615       cHRM_XYZ
2616           This is local to Image::PNG::Libpng and not a part of libpng
2617           itself.
2618
2619           It was necessary to extend libpng because the conditional
2620           compilation macro for "set_cHRM_XYZ" and "get_cHRM_XYZ",
2621           "PNG_cHRM_SUPPORTED" is defined (true) for old libpngs which do not
2622           actually contain these functions.
2623
2624       CHUNK_CACHE_MAX
2625           This is local to Image::PNG::Libpng and not a part of libpng
2626           itself.
2627
2628           It was necessary to extend libpng because the conditional
2629           compilation macro for "set_chunk_cache_max" and
2630           "get_chunk_cache_max", "PNG_USER_LIMITS_SUPPORTED" is defined
2631           (true) for old libpngs which do not actually contain these
2632           functions.
2633
2634       CHUNK_MALLOC_MAX
2635           This is local to Image::PNG::Libpng and not a part of libpng
2636           itself.
2637
2638           The reasons for this are identical to those for "CHUNK_CACHE_MAX".
2639
2640       COLORSPACE
2641       CONSOLE_IO
2642       CONVERT_tIME
2643           This is related to two deprecated functions,
2644           "png_convert_from_time_t" and "png_convert_from_struct_tm".
2645
2646       CONVERT_tIME
2647       EASY_ACCESS
2648       ERROR_NUMBERS
2649       ERROR_TEXT
2650       eXIf
2651           Does the libpng support the "eXIf" chunk?
2652
2653       FIXED_POINT
2654       FIXED_POINT_MACRO
2655       FLOATING_ARITHMETIC
2656       FLOATING_POINT
2657       FORMAT_AFIRST
2658       FORMAT_BGR
2659       gAMA
2660           Does the libpng support the "gAMA" chunk?
2661
2662       GAMMA
2663       GET_PALETTE_MAX
2664           Does your libpng support "get_palette_max"?
2665
2666       HANDLE_AS_UNKNOWN
2667       HANDLE_AS_UNKNOWN
2668       hIST
2669           Does the libpng support the "hIST" chunk?
2670
2671       iCCP
2672           Does the libpng support the "iCCP" chunk?
2673
2674       INCH_CONVERSIONS
2675       INFO_IMAGE
2676       IO_STATE
2677       iTXt
2678           Does the libpng support international text?
2679
2680       MIPS_MSA_API
2681       MNG_FEATURES
2682       oFFs
2683           Does the libpng support the "oFFs" chunk?
2684
2685       pCAL
2686           Does the libpng support the "pCAL" extension?
2687
2688       PEDANTIC_WARNINGS
2689       pHYs
2690           Does the libpng support the "pHYs" chunk?
2691
2692       POINTER_INDEXING
2693       POWERPC_VSX_API
2694       PROGRESSIVE_READ
2695       READ
2696           Can libpng read PNGs?
2697
2698       READ_16_TO_8
2699       READ_ALPHA_MODE
2700           See "set_alpha_mode".
2701
2702       READ_BACKGROUND
2703           See "set_background".
2704
2705       READ_BGR
2706           See "set_bgr".
2707
2708       READ_COMPOSITE_NODIV
2709       READ_COMPRESSED_TEXT
2710       READ_EXPAND
2711       READ_EXPAND_16
2712       READ_FILLER
2713       READ_GAMMA
2714           See "set_gamma".
2715
2716       READ_GRAY_TO_RGB
2717       READ_INTERLACING
2718       READ_INT_FUNCTIONS
2719       READ_INVERT
2720       READ_INVERT_ALPHA
2721       READ_OPT_PLTE
2722       READ_PACK
2723       READ_PACKSWAP
2724       READ_QUANTIZE
2725       READ_RGB_TO_GRAY
2726       READ_SCALE_16_TO_8
2727       READ_SHIFT
2728       READ_STRIP_16_TO_8
2729       READ_STRIP_ALPHA
2730       READ_SWAP
2731       READ_SWAP_ALPHA
2732       READ_tEXt
2733       READ_TRANSFORMS
2734       READ_USER_TRANSFORM
2735       READ_zTXt
2736       SAVE_INT_32
2737       SAVE_UNKNOWN_CHUNKS
2738       sBIT
2739           Does the libpng support the "sBIT" chunk?
2740
2741       sCAL
2742           Does the libpng support the "sCAL" extension?  This actually tests
2743           for the presence of the "get_sCAL_s"/"set_sCAL_s" functions, so its
2744           behaviour is dependent on other factors for versions 1.2 and 1.4 of
2745           libpng.
2746
2747       SEQUENTIAL_READ
2748       SETJMP
2749       SET_OPTION
2750       SET_UNKNOWN_CHUNKS
2751       SET_USER_LIMITS
2752       SIMPLIFIED_READ
2753       SIMPLIFIED_READ_AFIRST
2754       SIMPLIFIED_WRITE
2755       SIMPLIFIED_WRITE_AFIRST
2756       SIMPLIFIED_WRITE_BGR
2757       SIMPLIFIED_WRITE_STDIO
2758       sPLT
2759           Does the libpng support "sPLT" chunks?
2760
2761       sRGB
2762           Does the libpng support the "sRGB" chunk?
2763
2764       STDIO
2765       STORE_UNKNOWN_CHUNKS
2766       TEXT
2767           Does the libpng support text?
2768
2769       tEXt
2770           Does the libpng support tEXt chunks?
2771
2772       tIME
2773           Does the libpng support the "tIME" chunk?
2774
2775       TIME_RFC1123
2776       tRNS
2777           Does the libpng support the "tRNS" chunk?
2778
2779       UNKNOWN_CHUNKS
2780           Does the libpng support unknown chunks (see "Private chunks")?
2781
2782       USER_CHUNKS
2783       USER_LIMITS
2784           Does the libpng support "set_user_limits" and the related functions
2785           "get_user_width_max", and "get_user_height_max"?
2786
2787       USER_LIMITS
2788       USER_MEM
2789       USER_TRANSFORM_INFO
2790       USER_TRANSFORM_PTR
2791       WARNINGS
2792       WRITE
2793           Can libpng write pngs?
2794
2795       WRITE_BGR
2796       WRITE_COMPRESSED_TEXT
2797       WRITE_CUSTOMIZE_COMPRESSION
2798           Does the libpng support "set_compression_level" and similar
2799           functions?
2800
2801           ⛐ðŸĪŠâš  It's not very clear that this returns a useful value, since
2802           "set_compression_level" seems to be in libpngs from at least as far
2803           back as 1.5.1, and yet this macro was only added to libpng in
2804           version 1.6.13.
2805
2806       WRITE_CUSTOMIZE_ZTXT_COMPRESSION
2807           Does the libpng support "set_text_compression_level" and similar
2808           functions?
2809
2810       WRITE_FILLER
2811       WRITE_FILTER
2812       WRITE_FLUSH
2813       WRITE_FLUSH_AFTER_IEND
2814       WRITE_INTERLACING
2815       WRITE_INT_FUNCTIONS
2816       WRITE_INVERT
2817       WRITE_INVERT_ALPHA
2818       WRITE_OPTIMIZE_CMF
2819       WRITE_PACK
2820       WRITE_PACKSWAP
2821       WRITE_SHIFT
2822       WRITE_SWAP
2823       WRITE_SWAP_ALPHA
2824       WRITE_TRANSFORMS
2825       WRITE_USER_TRANSFORM
2826       WRITE_WEIGHTED_FILTER
2827       zTXt
2828           Does the libpng support "zTXt" chunks?
2829
2830   png_compare
2831           if (png_compare ('a.png', 'b.png') == 0) {
2832               print "The PNGs are the same.\n";
2833           }
2834
2835       This compares the image data in two PNGs and returns 0 if they contain
2836       exactly the same image data, or 1 if they contain different image data.
2837       For a more detailed comparison, see "image_data_diff". This does not
2838       compare to see if the PNG files "look like" each other, but whether
2839       each pixel contains exactly the same values. Please see Image::Similar
2840       for a looser comparison of images.
2841
2842       This uses the "expand" transform of libpng to read both the images, so
2843       it is able to compare images of different color types. It compares the
2844       alpha values as well as the color pixels. See "Saving bandwidth" for an
2845       example of comparing an RGB and a grayscale image.
2846
2847   read_struct
2848           if ($png->read_struct ()) {
2849                warn "Can't write this, use copy_png to copy it";
2850           }
2851
2852       This returns a true value if $png was created with "create_read_struct"
2853       or allied functions like "read_from_scalar", and a false value if $png
2854       was created with "create_write_struct" or allied functions like
2855       "copy_png".
2856
2857   set_chunk
2858           $png->set_chunk ('tIME', $timechunk);
2859
2860       Set the specified chunk. This produces a fatal error if given an "IDAT"
2861       (image data) chunk, use "set_rows" instead. This produces a fatal error
2862       if given an unknown chunk name.
2863
2864       The first argument is the chunk name and then the second argument is a
2865       scalar containing whatever the chunk requires, for example a hash
2866       reference for the "tIME" chunk as described under "set_tIME" and
2867       "get_tIME".
2868
2869       This is essentially a convenience function for the benefit of
2870       "copy_png" which, together with "get_valid", enables the PNG chunks to
2871       be copied in a loop rather than one-by-one.
2872
2873   set_image_data
2874           $png->set_image_data ($image_data);
2875
2876       Set the internal image data pointer to $image_data. $image_data should
2877       contain a pointer to memory stored as an "SvIV" allocated with "Newx"
2878       or a similar function. This transfers ownership of the memory to $png,
2879       which will free it with "Safefree" when $png is destroyed. Calling this
2880       function with any value does not actually change the content of the PNG
2881       image itself.
2882
2883   set_row_pointers
2884           $png->set_row_pointers ($row_pointers);
2885
2886       This sets the rows of the PNG image to $row_pointers using
2887       "png_set_rows". $row_pointers must contain a pointer to memory stored
2888       as an SvIV allocated with a Perl memory allocator like "Newx" or a
2889       similar function. This also transfers ownership of the memory to $png,
2890       which will free it with "Safefree" when $png is destroyed. See also
2891       "copy_row_pointers", which does the same thing except for the freeing
2892       of the memory.
2893
2894   split_alpha
2895           my $split = $png->split_alpha ();
2896           my $alpha = $split->{alpha};
2897           my $color = $split->{data};
2898
2899       Split the alpha channel away from the other data. This only works for
2900       images with color types "PNG_COLOR_TYPE_RGB_ALPHA" and
2901       "PNG_COLOR_TYPE_GRAY_ALPHA". This is not part of the libpng API. This
2902       function was added to this module to assist the author of PDF::Builder
2903       due to problems with very slow access to PNG images using Perl.
2904
2905       To remove the alpha channel from an image, use "set_background". See
2906       "Setting the background" for an example. You can also use the transform
2907       "PNG_TRANSFORM_STRIP_ALPHA" in "read_png_file", or "set_strip_alpha",
2908       but this may leave spurious pixel values in transparent parts of the
2909       image.
2910

EXPORTS

2912       Nothing is exported by default, but all the functions in this module,
2913       including the object methods, can be exported on request. The export
2914       tag 'all' exports everything in the module:
2915
2916           use Image::PNG::Libpng ':all';
2917
2918       This includes all the methods, which can then be used with the $png
2919       argument as the first argument.
2920

Differences from libpng

2922       The functions in Image::PNG::Libpng are closely based on those of
2923       libpng, with the following differences.
2924
2925   No info structure
2926       This module does not use the "info" structure of libpng. Almost all
2927       libpng functions require two initial arguments, a "png_structp" and a
2928       "png_infop". However, in Image::PNG::Libpng, both the "png" and the
2929       "info" are contained in the object. People who need access to the
2930       internals of an "Image::PNG::Libpng" object (C programmers or XS
2931       programmers) can use "get_internals" to access them.
2932
2933       This module does not support the "end info" structure of PNGs when
2934       writing, although these are handled when reading.
2935
2936   Unused arguments omitted
2937       This module eliminates unevaluated arguments of libpng. For example,
2938       libpng requires the user to pass a pointer to a "png_struct" to call
2939       the libpng version number function, (see "get_libpng_ver"), but it
2940       actually ignores this structure. There are many similar instances of
2941       unevaluated arguments, which have all been eliminated from this module.
2942
2943       If you are interested in exactly which libpng arguments are omitted,
2944       you can find each instance in the file "perl-libpng.c" in the top
2945       directory of the distribution
2946       <https://fastapi.metacpan.org/source/BKB/Image-PNG-Libpng-0.57/perl-
2947       libpng.c> in the macro "UNUSED_ZERO_ARG".
2948
2949   Useless functions omitted
2950       The functions from libpng which don't do anything have been omitted
2951       from this module.
2952
2953   Function return values are used to return values
2954       libpng is very inconsistent in its calling conventions. Some functions
2955       return results using references, and some return results using the
2956       function's return value. For example "png_get_rows" (see "get_rows")
2957       uses the return value of the function to return an array of pointers,
2958       but "png_get_PLTE" (see "get_PLTE") uses a pointer reference to return
2959       an array of pointers, and the return value to indicate errors.
2960
2961       Image::PNG::Libpng uses only the return value. Errors and non-existence
2962       are indicated by a return value of the undefined value.
2963
2964       Further to this, libpng's error handling is also very inconsistent.
2965       Some functions use the return value to indicate errors, and some of the
2966       functions don't indicate errors at all, but just fail silently. Even
2967       more inconsistently, some of the functions which use the return value
2968       to indicate an error use a non-zero value, and some use a zero value,
2969       to indicate an error.
2970
2971   No destructors
2972       Freeing the memory allocated by "create_read_struct" and
2973       "create_write_struct" is automatically handled by Perl.
2974
2975       Older versions of this module (pre-0.18) had functions called
2976       "destroy_read_struct" and "destroy_write_struct" corresponding to the
2977       functions with similar names in libpng. From version 0.18, these
2978       functions still exist, but they no longer do anything. The memory
2979       freeing is now handled by Perl automatically.
2980
2981   Other unimplemented parts of libpng
2982       Memory management functions
2983           The management of memory for libpng objects is handled
2984           automatically by this module, and so it does not offer an interface
2985           to "png_malloc" and "png_free" or other libpng memory handling
2986           functions.
2987
2988       Error handling functions
2989           This module does not offer an interface to "png_error" and
2990           "png_get_error_ptr" or any of the other error handling functions of
2991           libpng. It redirects the error and warning handlers to Perl's error
2992           stream.
2993
2994       Input/output manipulation functions
2995           This module does not offer a direct interface to "png_set_write_fn"
2996           and "png_set_read_fn". However, it is possible to use their
2997           functionality to access Perl data via "read_from_scalar" and
2998           "write_to_scalar".
2999
3000       Fixed point functions
3001           There is currently no support for the PNG fixed point functions in
3002           this Perl module, the functions with suffix "_fixed".
3003
3004   List of unsupported functions
3005       The following functions from the libpng API are unsupported by this
3006       module.
3007
3008       png_benign_error
3009           💔 See "Error handling functions".
3010
3011       png_build_grayscale_palette
3012           ⛐ðŸĪŠâš  Undocumented function, but it is part of the public API.  See
3013           <https://github.com/glennrp/libpng/issues/353>.
3014
3015           This function builds an evenly-spaced grayscale palette at a
3016           specified bit depth into a user-supplied array. It is not used
3017           elsewhere in libpng.
3018
3019       png_chunk_benign_error
3020           💔 See "Error handling functions".
3021
3022       png_chunk_warning
3023           💔 See "Error handling functions".
3024
3025       png_convert_from_struct_tm
3026           👎 Deprecated in libpng.  This function related to the "tIME" chunk
3027           is deprecated in libpng 1.7.
3028
3029       png_convert_from_time_t
3030           👎 Deprecated in libpng.  This function related to the "tIME" chunk
3031           is deprecated in libpng 1.7.
3032
3033       png_convert_to_rfc1123
3034           👎 Deprecated in libpng.  This function related to the "tIME" chunk
3035           is deprecated in libpng 1.7.
3036
3037       png_convert_to_rfc1123_buffer
3038           👎🐊 This function was deliberately omitted from this module
3039           because it doesn't seem useful for Perl programmers.
3040
3041           This function is related to the "tIME" chunk; it seems fairly
3042           superfluous with the many other ways to manipulate time strings
3043           already in Perl.
3044
3045       png_data_freer
3046           🐘 See "Memory management functions".
3047
3048       png_free
3049           🐘 See "Memory management functions".
3050
3051       png_free_data
3052           🐘 See "Memory management functions".
3053
3054       png_get_cHRM_XYZ_fixed
3055           🍓 See "Fixed point functions".
3056
3057       png_get_cHRM_fixed
3058           🍓 See "Fixed point functions".
3059
3060       png_get_compression_type
3061           🙃ðŸĪĄ See "Useless functions omitted".  Useless function which
3062           returns 0 since there is only one type of compression.
3063
3064       png_get_copyright
3065           👎🐊 This function was deliberately omitted from this module
3066           because it doesn't seem useful for Perl programmers.
3067
3068           This function gives you the copyright string for libpng.
3069
3070       png_get_current_pass_number
3071       png_get_current_row_number
3072       png_get_error_ptr
3073           💔 See "Error handling functions".
3074
3075       png_get_filter_type
3076           🙃ðŸĪĄ See "Useless functions omitted".  This function returns the
3077           value of the unused field "filter_type" in the PNG header, which is
3078           always 0. See "Unused arguments omitted".
3079
3080       png_get_gAMA_fixed
3081           🍓 See "Fixed point functions".
3082
3083       png_get_header_ver
3084           This function was omitted from this module because it merely
3085           duplicates another function.
3086
3087           Identical to "get_libpng_ver".
3088
3089       png_get_header_version
3090           This function was omitted from this module because it merely
3091           duplicates another function.
3092
3093           Identical to "get_libpng_ver".
3094
3095       png_get_io_chunk_type
3096       png_get_io_ptr
3097       png_get_io_state
3098       png_get_mem_ptr
3099       png_get_pHYs_dpi
3100       png_get_pixel_aspect_ratio
3101       png_get_pixel_aspect_ratio_fixed
3102           🍓 See "Fixed point functions".
3103
3104       png_get_pixels_per_inch
3105       png_get_pixels_per_meter
3106       png_get_progressive_ptr
3107           Incremental reading of PNGs is not handled yet.
3108
3109       png_get_sCAL_fixed
3110           🍓 See "Fixed point functions".
3111
3112       png_get_signature
3113           👎🐊 This function was deliberately omitted from this module
3114           because it doesn't seem useful for Perl programmers.
3115
3116           Returns the PNG signature of a PNG you read in.
3117
3118       png_get_uint_31
3119           👎🐊 This function was deliberately omitted from this module
3120           because it doesn't seem useful for Perl programmers.
3121
3122           This produces an error if the unsigned integer argument is too big
3123           for a 31 bit number.
3124
3125       png_get_user_chunk_ptr
3126       png_get_user_height_max
3127       png_get_user_transform_ptr
3128       png_get_x_offset_inches
3129       png_get_x_offset_inches_fixed
3130           🍓 See "Fixed point functions".
3131
3132       png_get_x_offset_microns
3133       png_get_x_offset_pixels
3134           Duplicates "get_oFFs".
3135
3136       png_get_x_pixels_per_inch
3137       png_get_x_pixels_per_meter
3138           Duplicates "get_oFFs".
3139
3140       png_get_y_offset_inches
3141       png_get_y_offset_inches_fixed
3142           🍓 See "Fixed point functions".
3143
3144       png_get_y_offset_microns
3145       png_get_y_offset_pixels
3146           Duplicates "get_oFFs".
3147
3148       png_get_y_pixels_per_inch
3149       png_get_y_pixels_per_meter
3150           Duplicates "get_oFFs".
3151
3152       png_handle_as_unknown
3153       png_image_begin_read_from_file
3154       png_image_begin_read_from_stdio
3155       png_image_finish_read
3156       png_image_free
3157           🐘 See "Memory management functions".
3158
3159       png_image_write_to_file
3160       png_image_write_to_memory
3161           🐘 See "Memory management functions".
3162
3163       png_image_write_to_stdio
3164       png_process_data
3165       png_process_data_pause
3166       png_process_data_skip
3167       png_progressive_combine_row
3168       png_read_row
3169       png_read_rows
3170       png_reset_zstream
3171           👎 Deprecated in libpng.  Resets the zstream of the zlib instance
3172           used for the image data.
3173
3174       png_save_int_32
3175           👎🐊 This function was deliberately omitted from this module
3176           because it doesn't seem useful for Perl programmers.
3177
3178           Writes a 32 bit signed number into an octet buffer. Perl
3179           programmers will probably use "pack" for this.
3180
3181       png_save_uint_16
3182           👎🐊 This function was deliberately omitted from this module
3183           because it doesn't seem useful for Perl programmers.
3184
3185           Writes a 16 bit number into an octet buffer. Perl programmers will
3186           probably use "pack" for this.
3187
3188       png_save_uint_32
3189           👎🐊 This function was deliberately omitted from this module
3190           because it doesn't seem useful for Perl programmers.
3191
3192           Writes a 32 bit unsigned number into an octet buffer. Perl
3193           programmers will probably use "pack" for this.
3194
3195       png_set_alpha_mode_fixed
3196           🍓 See "Fixed point functions".
3197
3198       png_set_background_fixed
3199           🍓 See "Fixed point functions".
3200
3201       png_set_benign_errors
3202           💔 See "Error handling functions".
3203
3204       png_set_cHRM_XYZ_fixed
3205           🍓 See "Fixed point functions".
3206
3207       png_set_cHRM_fixed
3208           🍓 See "Fixed point functions".
3209
3210       png_set_check_for_invalid_index
3211       png_set_compression_method
3212           🙃ðŸĪĄ See "Useless functions omitted".  This function in libpng
3213           corresponds to the unused "method" parameter of zlib functions like
3214           "deflateInit2". See "zlib documentation". The libpng function just
3215           produces a warning if the user sets the value to anything but 8,
3216           the value of the macro "Z_DEFLATED", and then lets zlib produce an
3217           error.
3218
3219       png_set_crc_action
3220           💔 See "Error handling functions".
3221
3222       png_set_error_fn
3223           💔 See "Error handling functions".
3224
3225       png_set_filter_heuristics
3226           👎 Deprecated in libpng.
3227
3228       png_set_filter_heuristics_fixed
3229           🍓 See "Fixed point functions".
3230
3231       png_set_flush
3232       png_set_gAMA_fixed
3233           🍓 See "Fixed point functions".
3234
3235       png_set_gamma_fixed
3236           🍓 See "Fixed point functions".
3237
3238       png_set_interlace_handling
3239           Incremental writing is not handled.
3240
3241       png_set_invalid
3242           🐘 See "Memory management functions".
3243
3244       png_set_longjmp_fn
3245           ⛐ðŸĪŠâš  Undocumented function, but it is part of the public API.
3246
3247       png_set_mem_fn
3248           🐘 See "Memory management functions".
3249
3250       png_set_option
3251       png_set_progressive_read_fn
3252       png_set_read_status_fn
3253       png_set_read_user_chunk_fn
3254       png_set_read_user_transform_fn
3255       png_set_sCAL_fixed
3256           🍓 See "Fixed point functions".
3257
3258       png_set_sRGB_gAMA_and_cHRM
3259       png_set_shift
3260       png_set_sig_bytes
3261           👎🐊 This function was deliberately omitted from this module
3262           because it doesn't seem useful for Perl programmers.
3263
3264       png_set_strip_error_numbers
3265           🙃ðŸĪĄ See "Useless functions omitted".  According to the libpng
3266           manual, "we never got around to actually numbering the error
3267           messages", so I assume this is not very useful.
3268
3269       png_set_text_compression_method
3270           🙃ðŸĪĄ See "Useless functions omitted".  Unsupported for the same
3271           reasons as "png_set_compression_method".
3272
3273       png_set_unknown_chunk_location
3274           This is related to some kind of bug in version 1.5 and previous of
3275           libpng.
3276
3277       png_set_user_transform_info
3278       png_set_write_status_fn
3279           💔 See "Error handling functions".
3280
3281       png_set_write_user_transform_fn
3282       png_start_read_image
3283       png_write_chunk
3284       png_write_chunk_data
3285       png_write_chunk_end
3286       png_write_chunk_start
3287       png_write_flush
3288       png_write_info_before_PLTE
3289       png_write_row
3290       png_write_rows
3291       png_write_sig
3292
3293       This is an exhaustive list of unsupported libpng API functions,
3294       extracted from the libpng source code using util/api.pl in this
3295       module's repository.
3296
3297   Conditional compilation and old libpng versions
3298       It is possible to compile a version of the libpng library without
3299       support for various things. For example, a libpng without support for
3300       text chunks may be created by undefining the C macro
3301       "PNG_TEXT_SUPPORTED". This module supports the conditional compilation
3302       choices which we're aware of, but if you encounter problems using this
3303       module because of a conditionally-compiled libpng, then let us know and
3304       we'll add the necessary facility.
3305
3306       Currently we test this module against vanilla libpng versions 1.2.59,
3307       1.4.22, 1.5.30, and 1.6.37 before releases. There doesn't seem to have
3308       been a 1.3 or a 1.1 version of libpng. See
3309       <http://www.libpng.org/pub/png/pngnews.html>. Versions 1.0 and earlier
3310       of libpng are not tested against.
3311
3312       The following issues with older libpng versions may affect users of
3313       this module:
3314
3315       cHRM chunk
3316
3317       The "get_cHRM_XYZ" and "set_cHRM_XYZ" functions for the "cHRM" chunk
3318       are not present in pre-1.5.5 versions of libpng, but the conditional
3319       compilation macro of libpng for these newer functions is the same as
3320       for "get_cHRM" and "set_cHRM" functions, which are present on older
3321       versions of libpng. Because of this, this module includes its own
3322       protection macro, accessible via "libpng_supports" as "cHRM_XYZ".
3323       These functions are disabled for libpng versions earlier than 1.5.5.
3324
3325       chunk_cache_max
3326
3327       The functions "set_chunk_cache_max" and "get_chunk_cache_max" are not
3328       protected by a libpng macro, so this module includes its own protection
3329       macro, accessible via "libpng_supports" as "CHUNK_CACHE_MAX". These
3330       functions are disabled for libpng versions earlier than 1.4.0.
3331
3332       Compression level
3333
3334       Versions of libpng up to 1.5 behave erratically when
3335       "set_compression_level" or other "set_compression_*" functions are used
3336       to alter the compression of the image data. Testing of compression-
3337       related functions is disabled by this Perl module for pre-1.6.13
3338       versions of libpng.
3339
3340       sCAL chunk
3341
3342       Support for the sCAL chunk is disabled within this module for pre-1.6
3343       versions of libpng.
3344
3345       Text chunk handling
3346
3347       Versions of libpng up to 1.6.3 produce erratic results with "iTXt"
3348       (international text) chunks. Testing of text-related chunks is disabled
3349       by this Perl module for pre-1.6.13 versions of libpng.
3350
3351   Not all constants are available
3352       Some of the libpng constants are defined in pnglibconf.h or pngconf.h
3353       but Image::PNG::Const only looks at png.h to make its constants.
3354       Because of this, some constant values like "PNG_Z_DEFAULT_COMPRESSION"
3355       aren't currently available in Image::PNG::Const. This probably should
3356       be fixed to extract the constants from the other files in a future
3357       version.
3358

STANDALONE SCRIPT

3360       A standalone script, pnginspect, is installed with the distribution. It
3361       prints out the contents of the chunks of the PNG file on the command
3362       line.
3363

SEE ALSO

3365   The PNG specification
3366       The PNG specification <http://www.w3.org/TR/PNG/> (link to W3
3367       consortium) explains the details of the PNG format.
3368
3369       PNG The Definitive Guide by Greg Roelofs
3370
3371       The book "PNG - The Definitive Guide" by Greg Roelofs, published in
3372       1999 by O'Reilly is available online at <http://www.faqs.org/docs/png/>
3373       or <http://www.libpng.org/pub/png/book/>.
3374
3375   The libpng documentation
3376       Official documentation
3377           The starting point is the plain text libpng manual at
3378           <http://libpng.org/pub/png/libpng-manual.txt> and the manual page
3379           libpng.3, which you can read using "man 3 libpng".
3380
3381           ⛐ðŸĪŠâš  The documentation which comes with libpng is rather sketchy.
3382           See "Differences from libpng". It doesn't contain full
3383           specifications (prototypes, return values) for all of the functions
3384           in the library. For programming in C using libpng, look at the
3385           header file png.h.  In some cases, you need to look at the source
3386           code of the library.
3387
3388       Other documentation
3389           There is a collection of function definitions under the title
3390           "Interface Definitions for libpng12" at
3391           <https://refspecs.linuxbase.org/LSB_4.0.0/LSB-Desktop-generic/LSB-Desktop-generic/libpng12man.html>
3392           as part of the "Linux Standard Base Desktop Specification". These
3393           contain extensive information on the prototypes and return values
3394           for the libpng routines, something which is often only available
3395           elsewhere by actually looking at the libpng source code. These
3396           pages are usually the first hits on search engines if you search
3397           for a function name in libpng.
3398
3399   zlib documentation
3400       See <https://zlib.net/manual.html> for the zlib documentation.
3401
3402   Other Perl modules on CPAN
3403       These other modules may also be useful.
3404
3405       Alien::PNG
3406           Alien::PNG claims to be a way of "building, finding and using PNG
3407           binaries". It may help in installing libpng. We didn't use it as a
3408           dependency for this module because it seems not to work in batch
3409           mode, but stop and prompt the user. We're interested in hearing
3410           feedback from users whether this works or not on various platforms.
3411
3412       Imager
3413           Imager, Imager::Files and "Imager::Files::PNG" contain support for
3414           reading and writing PNGs via libpng, as well as support for reading
3415           and writing various other kinds of image files, changing the
3416           images, converting, and more.
3417
3418       Image::ExifTool
3419           Image::ExifTool is a pure Perl (doesn't require a C compiler)
3420           solution for accessing the text segments of images. It supports PNG
3421           text segments.
3422
3423       Image::Info
3424           Image::Info gets information out of images. It supports PNG and is
3425           written in pure Perl, so it doesn't require a C compiler. As well
3426           as basics such as height, width, and colour type, it can get text
3427           chunks, modification time, palette, gamma (gAMA chunk), resolution
3428           (pHYs chunk), and significant bits (sBIT chunk). At the time of
3429           writing (version 1.31) it doesn't support other chunks.
3430
3431       Image::PNG::Rewriter
3432           Image::PNG::Rewriter is a utility for unpacking and recompressing
3433           the IDAT (image data) part of a PNG image. The main purpose seems
3434           to be to recompress the image data with the module author's other
3435           module Compress::Deflate7. At the time of writing, that only works
3436           with Perl versions 5.12 or later.
3437
3438       Image::Pngslimmer
3439           Image::Pngslimmer reduces the size of dynamically created PNG
3440           images. It's very, very slow at reading PNG data, but seems to work
3441           OK.
3442
3443       Image::PNG::Write::BW
3444           Image::PNG::Write::BW writes black and white PNGs from strings.
3445
3446       Image::Size
3447           If you only need to read the sizes of images, Image::Size works
3448           with PNG and other image formats.
3449

AUTHOR

3451       Ben Bullock, <bkb@cpan.org>
3452
3454       This package and associated files are copyright (C) 2011-2021 Ben
3455       Bullock.
3456
3457       You can use, copy, modify and redistribute this package and associated
3458       files under the Perl Artistic Licence or the GNU General Public
3459       Licence.
3460
3461
3462
3463perl v5.34.0                      2021-07-22             Image::PNG::Libpng(3)
Impressum