1Image::PNG::Libpng(3) User Contributed Perl DocumentationImage::PNG::Libpng(3)
2
6 Image::PNG::Libpng - Perl interface to the C library "libpng".
7
9 Libpng-like interface:
10 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 (This example is included as examples/synopsis.pl
28 <https://fastapi.metacpan.org/source/BKB/Image-PNG-
29 Libpng-0.56/examples/synopsis.pl> in the distribution.)
30 Simple interface:
32 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 (This example is included as examples/synopsis-easy.pl
53 <https://fastapi.metacpan.org/source/BKB/Image-PNG-
54 Libpng-0.56/examples/synopsis-easy.pl> in the distribution.)
55
57 This document describes Image::PNG::Libpng version 0.56, corresponding
58 to git commit 2ca3f20707e31fd38b2a3c3c658efb3f18eb12df
59 <https://github.com/benkasminbullock/image-png-
60 libpng/commit/2ca3f20707e31fd38b2a3c3c658efb3f18eb12df> at Wed Dec 23
61 07:44:31 2020 +0900.
62 Unless otherwise qualified, comments in this document on the libpng
64 source code and documentation refer to libpng version 1.6.37. Libpng is
65 not bundled with this distribution, so your installed version may vary.
66
68 Image::PNG::Libpng is a Perl library for accessing the contents of PNG
69 (Portable Network Graphics) images. Image::PNG::Libpng enables Perl to
70 use the "libpng" library to read and write files in PNG format.
71 Image::PNG::Libpng does not contain the libpng library. The libpng
72 library must be installed on your computer prior to installing
73 Image::PNG::Libpng.
74 Image::PNG::Libpng consists of Perl subroutines which mirror the C
76 functions in libpng, plus helper subroutines to make it easier to read
77 and write PNG data in Perl.
78 For those familiar with libpng, the section "Differences from libpng"
80 explains the differences with libpng.
81
83 The functions in the module are gathered into the following categories:
84 "Simple input and output", which describes some convenience functions,
85 "Libpng-style input and output", which describes functions which
86 closely mirror libpng, "The image header", which describes functions
87 for reading and writing the meta-information about PNG images, "Image
88 data", which describes functions for accessing the image data itself,
89 "Text chunks", "Private chunks", "Library version functions",
90 "Compression and filtering", "Other chunks", "Libpng transformations",
91 "Other libpng functions", functions from libpng which don't fit
92 elsewhere, and "Other functions", which are functions specific to this
93 module.
94
96 These convenience functions combine common operations. They are not
97 part of the original libpng API.
98 copy_png
100 my $outpng = $png->copy_png ();
101 Copy a PNG from a read to a write structure. This function bridges two
103 kinds of object, "read a png" objects created by "create_read_struct"
104 and "write a png" objects created by "create_write_struct". This
105 function copies all the valid chunks from a read structure to a write
106 structure.
107 The following example demonstrates copying a PNG.
109 use utf8;
111 use FindBin '$Bin';
112 use Image::PNG::Libpng qw(read_png_file write_png_file) ;
113 my $pngin = read_png_file ("$Bin/../t/tantei-san.png");
114 my $pngout = $pngin->copy_png ();
115 $pngout->set_text ([{key => 'Name', text => 'Shunsaku Kudo'}]);
116 # $pngout->write_png_file ('copy.png');
117 (This example is included as examples/copy-png.pl
119 <https://fastapi.metacpan.org/source/BKB/Image-PNG-
120 Libpng-0.56/examples/copy-png.pl> in the distribution.)
121 create_reader
123 my $png = create_reader ('file.png');
124 $png->read_png ();
125 This combines "create_read_struct", "open", and "init_io" on the
127 specified file name but does not read the file in. This is for the case
128 that the user wants to apply some kind of transformation.
129 Setting the background
131 In the following example, the user sets the background with
133 "set_background" to replace the alpha channel.
134 use utf8;
136 use FindBin '$Bin';
137 use Image::PNG::Libpng ':all';
138 use Image::PNG::Const ':all';
139 my $file = "$Bin/luv.png";
140 my %color = (red => 0xC0, green => 0xFF, blue => 0xFF);
141 my $png = create_reader ($file);
142 $png->set_background (\%color, PNG_BACKGROUND_GAMMA_SCREEN, 0);
143 $png->read_png ();
144 my $wpng = copy_png ($png);
145 $wpng->write_png_file ("$Bin/set-background.png");
146 (This example is included as examples/set-background.pl
148 <https://fastapi.metacpan.org/source/BKB/Image-PNG-
149 Libpng-0.56/examples/set-background.pl> in the distribution.)
150 examples/luv.png <https://fastapi.metacpan.org/source/BKB/Image-PNG-
152 Libpng-0.56/examples/luv.png> is included in the distribution.
153 examples/set-background.png
155 <https://fastapi.metacpan.org/source/BKB/Image-PNG-
156 Libpng-0.56/examples/set-background.png> is included in the
157 distribution.
158 This function was added to the module in version 0.53.
160 create_writer
162 my $png = create_writer ('file.png');
163 $png->set_IHDR (\%ihdr);
164 $png->set_rows (\@rows);
165 $png->write_png ();
166 This combines "create_write_struct", "open", and "init_io" on the
168 specified file name but does not read the file in. This is for the case
169 that the user wants to apply some kind of transformation before
170 writing.
171 This function was added to the module in version 0.53.
173 read_from_scalar
175 my $png = read_from_scalar ($string);
176 This creates an image structure $png from the contents of a Perl scalar
178 variable $string containing PNG image data, for example data read from
179 a file, or data obtained from a web page. The first argument, $png, is
180 a PNG structure created with "create_read_struct". It reads in all the
181 data from the structure on being called.
182 This is useful when image data is stored in a Perl scalar. For example
184 use Image::PNG::Libpng 'read_from_scalar';
186 use LWP::Simple;
187 use JSON::Create;
188 my $image_data = get 'http://libpng.org/pub/png/img_png/libpng-88x31.png';
189 # Now $image_data contains the PNG file
190 my $png = read_from_scalar ($image_data);
191 # Now $png contains the PNG information from the image.
192 # Get the header.
193 my $header = $png->get_IHDR ();
194 my $jc = JSON::Create->new ();
195 $jc->indent (1);
196 print $jc->run ($header);
197 (This example is included as examples/get-www-png.pl
199 <https://fastapi.metacpan.org/source/BKB/Image-PNG-
200 Libpng-0.56/examples/get-www-png.pl> in the distribution.)
201 The output looks like this:
203 {
205 "width":88,
206 "bit_depth":4,
207 "interlace_method":0,
208 "color_type":3,
209 "height":31
210 }
211 See also "Input/output manipulation functions".
213 read_png_file
215 my $png = read_png_file ('q.png');
216 Open q.png and read its contents into $png.
218 This combines "create_read_struct", "open", "init_io", and "read_png".
220 The return value is the same as that of "create_read_struct" with the
221 entire PNG image already read in.
222 The optional argument to "read_png" can be specified using an optional
224 "transforms" argument:
225 my $png = read_png_file ('file.png', transforms => PNG_TRANSFORM_EXPAND);
227 "croak" in Carp is used to signal errors opening or closing the file.
229 set_transforms
231 $png->set_transforms (PNG_TRANSFORM_BGR);
232 Set transforms for reading and writing. This is the same as the
234 optional argument to "read_png" or "write_png". If both this and the
235 optional argument are given, the optional argument overrides what is
236 set here.
237 write_png_file
239 $png->write_png_file ('nice.png');
240 This combines open, "init_io", and "write_png" to write an entire PNG
242 image out to the file name specified by the argument. $png must be the
243 object created by "create_write_struct", so "read_png_file" followed by
244 a call to this does not work. See "copy_png" if you need to do that
245 kind of operation.
246 The optional argument to "write_png" can be specified using
248 "set_transforms".
249 "croak" in Carp is used to signal errors opening or closing the file.
251 write_to_scalar
253 my $image_data = $png->write_to_scalar ();
254 This writes the PNG image data in $png into a Perl scalar. The first
256 argument, $png, is a writeable PNG structure created with
257 "create_write_struct". The return value of the subroutine is the Perl
258 scalar containing the image data.
259 So, for example,
261 # This CGI script prints a PNG in a random colour.
263 use Image::PNG::Libpng ':all';
265 use Image::PNG::Const ':all';
266 my $png = create_write_struct ();
267 my $size = 100;
268 $png->set_IHDR ({height => $size, width => $size, bit_depth => 8,
269 color_type => PNG_COLOR_TYPE_RGB});
270 my $bytes = pack "CCC", randcol (), randcol (), randcol ();
271 my @rows = ($bytes x $size) x $size;
272 $png->set_rows (\@rows);
273 my $img = $png->write_to_scalar ();
274 binmode STDOUT;
275 print "Content-Type:image/png\r\n\r\n$img";
276 exit;
277 sub randcol
278 {
279 return int (rand () * 0x100);
280 }
281 (This example is included as examples/png-cgi.pl
283 <https://fastapi.metacpan.org/source/BKB/Image-PNG-
284 Libpng-0.56/examples/png-cgi.pl> in the distribution.)
285 See also "Input/output manipulation functions".
287 The optional argument to "write_png" can be specified using
289 "set_transforms".
290
292 There are two different "new"-like functions, depending on whether you
293 want to read or write a PNG, "create_read_struct" and
294 "create_write_struct". These are based on the libpng API. Input uses
295 "open" plus "init_io" followed by "read_png" or "write_png".
296 Examples
298 A self-pixellating program
299 This example demonstrates writing a monochrome PNG by creating a write
301 structure with "create_write_struct", opening a filehandle to write it,
302 associating the filehandle with the PNG structure with "init_io", then
303 using the functions "write_info", "write_image", and then "write_end"
304 to actually write the PNG data to the file.
305 use utf8;
307 use FindBin '$Bin';
308 use Image::PNG::Libpng ':all';
309 use Image::PNG::Const ':all';
310 my $outfile = "$Bin/mono.png";
311 my ($height, $width, $rows) = pixelate (__FILE__, 5);
312 my $png = create_write_struct ();
313 open my $out, ">:raw", $outfile or die $!;
314 $png->init_io ($out);
315 $png->set_IHDR ({height => $height, width => $width, bit_depth => 1,
316 color_type => PNG_COLOR_TYPE_GRAY});
317 $png->set_text ([{key => 'silly', text => 'finely-tuned breakfast cereal',}]);
318 $png->set_tIME ({year => 1999});
319 $png->write_info ();
320 $png->set_invert_mono ();
321 # PNG puts the leftmost pixel in the high-order part of the byte.
322 $png->set_packswap ();
323 $png->write_image ($rows);
324 $png->write_end ();
325 close $out or die $!;
326 exit;
327 sub pixelate
329 {
330 my ($file, $box) = @_;
331 open my $in, "<", $file or die "Can't open '$file': $!";
332 my $width = 0;
333 my @lines;
334 while (<$in>) {
335 chomp;
336 s/\t/ /g;
337 push @lines, $_;
338 if (length ($_) > $width) {
339 $width = length ($_);
340 }
341 }
342 close $in or die $!;
343 $width *= $box;
344 my $height = scalar (@lines) * $box;
345 my $zero = pack "C", 0;
346 my $bwidth = int(($width+7)/8);
347 my @rows = ($zero x $bwidth) x $height;
348 for my $r (0..$height-1) {
349 my $y = int ($r/$box);
350 my $line = $lines[$y];
351 for my $x (0..length ($line) - 1) {
352 if (substr ($line, $x, 1) ne ' ') {
353 for my $c (0..$box - 1) {
354 my $offset = $x*$box + $c;
355 my $byte = int ($offset / 8);
356 my $bit = $offset % 8;
357 my $octet = ord (substr ($rows[$r], $byte, 1));
358 substr ($rows[$r], $byte, 1) = chr ($octet | 1<<$bit);
359 }
360 }
361 }
362 }
363 return ($height, $width, \@rows);
364 }
365 (This example is included as examples/libpng-write.pl
367 <https://fastapi.metacpan.org/source/BKB/Image-PNG-
368 Libpng-0.56/examples/libpng-write.pl> in the distribution.)
369 examples/mono.png <https://fastapi.metacpan.org/source/BKB/Image-PNG-
371 Libpng-0.56/examples/mono.png> is included in the distribution.
372 create_read_struct
374 my $png = create_read_struct ();
375 Create a structure for reading a PNG. The return value can be used as
377 an object with the other functions as methods. It can be copied to a
378 write structure with "copy_png".
379 This function corresponds to "png_create_read_struct" in libpng plus
381 "create_info_struct" (see "No info structure") with the error and
382 warning handler variables set up to use Perl's error reporting.
383 create_write_struct
385 my $png = create_write_struct ();
386 Create a structure for writing a PNG. This can be used as an object
388 with the other functions as methods.
389 This function corresponds to "png_create_write_struct" in libpng plus
391 "create_info_struct" (see "No info structure") with the error and
392 warning handler variables set up to use Perl's error reporting.
393 init_io
395 open my $file, "<", 'nice.png';
396 $png->init_io ($file);
397 Set the file which $png reads or writes to $file. $file must be an
399 already-opened Perl file handle. If $png was created with
400 "create_write_struct", $file must be opened for writing. If $png was
401 created with "create_read_struct", $file must be open for reading.
402 Since PNG files are binary files, it is safest to specify the "raw"
404 pragma or use "binmode" with the file to override any default text file
405 encoding which Perl might be using:
406 open my $file, ">:raw", 'output.png';
408 or
410 open my $file, ">", 'output.png';
412 binmode $file;
413 This function corresponds to "png_init_io" in libpng, with a Perl file
415 handle substituting for the C "FILE *".
416 On some versions of Perl, "init_io" may crash in some circumstances
418 with an error like "segmentation fault", if you use code like
419 my $png = create_read_struct ();
421 open my $file, "<:raw", "some.png";
422 $png->init_io ($file);
423 and you do not check whether the call to "open" was successful, and
425 some.png does not exist. The crash occurs within Perl's conversion of
426 $file into a C "FILE *" pointer, before this module's code runs. This
427 bug was fixed in Perls after version 5.24.1. To avoid trouble, please
428 check the return value of "open".
429 read_end
431 $png->read_end ();
432 Read the part of the PNG file after the image data.
434 This function corresponds to "png_read_end" in libpng.
436 read_image
438 my $rows = $png->read_image ();
439 Read the image data of the PNG file.
441 This function corresponds to "png_read_image" in libpng.
443 read_info
445 $png->read_info ();
446 Read the part of the PNG file before the image data.
448 This function corresponds to "png_read_info" in libpng.
450 read_png
452 $png->read_png ();
453 Read the entire PNG file into memory.
455 You can provide an argument containing transformations to apply to the
457 image:
458 use Image::PNG::Const qw/PNG_TRANSFORM_STRIP_ALPHA/;
460 $png->read_png (PNG_TRANSFORM_STRIP_ALPHA);
461 If the argument is omitted, the default value of
463 "PNG_TRANSFORM_IDENTITY" (the "do nothing" value) is applied. The
464 possible transformations which can be applied are
465 PNG_TRANSFORM_BGR
467 Flip RGB to BGR, RGBA to BGRA. See also "set_bgr".
468 PNG_TRANSFORM_EXPAND
470 Perform set_expand(). See also "set_expand".
471 PNG_TRANSFORM_EXPAND_16
473 Expand samples to 16 bits. See also "set_expand_16".
474 PNG_TRANSFORM_GRAY_TO_RGB
476 Expand grayscale samples to RGB (or GA to RGBA). See also
477 "set_gray_to_rgb".
478 PNG_TRANSFORM_IDENTITY
480 No transformation.
481 PNG_TRANSFORM_INVERT_ALPHA
483 Change alpha from opacity to transparency. See also
484 "set_invert_alpha".
485 PNG_TRANSFORM_INVERT_MONO
487 Invert monochrome images. See also "set_invert_mono".
488 PNG_TRANSFORM_PACKING
490 Expand 1, 2 and 4-bit samples to bytes. See also "set_packing".
491 PNG_TRANSFORM_PACKSWAP
493 Change order of packed pixels to LSB first. See also
494 "set_packswap".
495 PNG_TRANSFORM_SCALE_16
497 Strip 16-bit samples to 8-bit accurately. See also "set_scale_16".
498 PNG_TRANSFORM_SHIFT
500 Normalize pixels to the sBIT depth.
501 PNG_TRANSFORM_STRIP_16
503 Chop 16-bit samples to 8-bit less accurately. See also
504 "set_strip_16".
505 PNG_TRANSFORM_STRIP_ALPHA
507 Discard the alpha channel.
508 PNG_TRANSFORM_SWAP_ALPHA
510 Flip RGBA to ARGB or GA to AG. See also "set_swap_alpha".
511 PNG_TRANSFORM_SWAP_ENDIAN
513 Byte-swap 16-bit samples. See also "set_swap".
514 This function corresponds to "png_read_png" in libpng with a default
516 value for the third argument. The fourth, unused, argument to
517 "png_read_png" does not need to be supplied. See "Unused arguments
518 omitted".
519 It does not take a second "info" argument. See "No info structure".
521 read_update_info
523 $png->read_update_info ();
524 âðĪŠâ Inside Image::PNG::Libpng, the libpng function
526 "png_read_update_info" is called before reading image data. According
527 to "The libpng documentation", this function may only be called once
528 for any particular info structure. So although the above Perl interface
529 exists in the module, it is strongly recommended to not use this unless
530 you know exactly what you are doing, since it will usually cause an
531 error when the image data is read.
532 This function corresponds to "png_read_update_info" in libpng
534 write_end
536 $png->write_end ();
537 Write the final part of the PNG file.
539 This function corresponds to "png_write_end" in libpng.
541 write_image
543 $png->write_image ($rows);
544 Write the image of the PNG file. $rows is an array reference as per
546 "set_rows".
547 This function corresponds to "png_write_image" in libpng.
549 write_info
551 $png->write_info ();
552 Write the first part of the PNG file.
554 This function corresponds to "png_write_info" in libpng.
556 write_png
558 $png->write_png ();
559 This writes the PNG to the file stream which was associated with it
561 using "init_io". For example,
562 open my $output, ">:raw", 'out.png';
564 $png->init_io ($output);
565 $png->write_png ();
566 close $output;
567 An optional argument consists of transformations to apply to the PNG
569 image before writing it:
570 use Image::PNG::Const qw/PNG_TRANSFORM_STRIP_ALPHA/;
572 $png->write_png (PNG_TRANSFORM_STRIP_ALPHA);
573 The transformations which can be applied are as follows:
575 PNG_TRANSFORM_BGR
577 Flip RGB to BGR, RGBA to BGRA. See also "set_bgr".
578 PNG_TRANSFORM_INVERT_ALPHA
580 Change alpha from opacity to transparency. See also
581 "set_invert_alpha".
582 PNG_TRANSFORM_INVERT_MONO
584 Invert monochrome images. See also "set_invert_mono".
585 PNG_TRANSFORM_PACKING
587 Expand 1, 2 and 4-bit samples to bytes. See also "set_packing".
588 PNG_TRANSFORM_PACKSWAP
590 Change order of packed pixels to LSB first. See also
591 "set_packswap".
592 PNG_TRANSFORM_SHIFT
594 Normalize pixels to the sBIT depth.
595 PNG_TRANSFORM_STRIP_FILLER_AFTER
597 Strip out trailing filler bytes.
598 PNG_TRANSFORM_STRIP_FILLER_BEFORE
600 Strip out leading filler bytes.
601 PNG_TRANSFORM_SWAP_ALPHA
603 Flip RGBA to ARGB or GA to AG. See also "set_swap_alpha".
604 PNG_TRANSFORM_SWAP_ENDIAN
606 Byte-swap 16-bit samples. See also "set_swap".
607 This function corresponds to "png_write_png" in libpng.
609
611 These functions handle the header part of PNG image data. See this
612 subsection <http://www.w3.org/TR/PNG/#11IHDR> of "The PNG
613 specification" for information on the PNG standards for the image
614 header.
615 color_type_name
617 $name = color_type_name ($color_type);
618 This is a convenience function which returns a string corresponding to
620 the numerical color type in $color_type. The name is in upper case,
621 with words separated by underscores, as in "RGB_ALPHA".
622 use Image::PNG::Libpng ':all';
624 my $png = read_png_file ('tantei-san.png');
625 my $name = color_type_name ($png->get_IHDR->{color_type});
626 print "Your PNG has colour type $name.\n";
627 (This example is included as examples/color-type-name.pl
629 <https://fastapi.metacpan.org/source/BKB/Image-PNG-
630 Libpng-0.56/examples/color-type-name.pl> in the distribution.)
631 This function does not correspond to anything in libpng. The names of
633 the color types are taken from those defined in the libpng header file,
634 "png.h".
635 get_bit_depth
637 my $bit_depth = $png->get_bit_depth ();
638 Get the bit depth, the number of bits for one channel of one pixel.
640 This function corresponds to "png_get_bit_depth" in libpng
642 get_channels
644 my $channels = $png->get_channels ();
645 Get the number of channels, from one to four. The channels are the
647 components of pixels, for example the red channel or the alpha
648 (transparency) channel. The return value is 1 for color type
649 "PNG_COLOR_TYPE_GRAY" and "PNG_COLOR_TYPE_PALETTE", 2 for
650 "PNG_COLOR_TYPE_GRAY_ALPHA", 3 for "PNG_COLOR_TYPE_RGB" and 4 for
651 "PNG_COLOR_TYPE_RGB_ALPHA" or "PNG_COLOR_TYPE_RGB" with a filler byte.
652 Note that the number of channels does not necessarily correspond to the
653 number of bytes, since the bit depth can also be 1, 2, 4, 8, or 16,
654 depending on the color type. See also the convenience function
655 "color_type_channels".
656 This function corresponds to "png_get_channels" in libpng
658 get_color_type
660 my $color_type = $png->get_color_type ();
661 This returns an integer value. If you want to get a name for the color
663 type, use "color_type_name".
664 This function corresponds to "png_get_color_type" in libpng.
666 get_IHDR
668 my $IHDR = $png->get_IHDR ();
669 Read the IHDR information from the PNG file. The return value is a hash
671 reference containing the following key/value pairs:
672 width
674 The width of the image in pixels.
675 height
677 The height of the image in pixels.
678 bit_depth
680 The bit depth of the image (the number of bits used for each color
681 in a pixel). This can take the values 1, 2, 4, 8, 16.
682 color_type
684 The color type. This can take the values PNG_COLOR_TYPE_GRAY,
685 PNG_COLOR_TYPE_GRAY_ALPHA, PNG_COLOR_TYPE_PALETTE,
686 PNG_COLOR_TYPE_RGB, PNG_COLOR_TYPE_RGB_ALPHA.
687 interlace_method
689 The method of interlacing. This can take the values
690 PNG_INTERLACE_NONE, PNG_INTERLACE_ADAM7.
691 So, for example, to get the width and height of an image,
693 my $ihdr = $png->get_IHDR ();
695 printf "Your image is %d x %d\n", $ihdr->{width}, $ihdr->{height};
696 This function corresponds to "png_get_IHDR" in libpng, with a single
698 Perl hash reference used instead of the several pointers to integers
699 used in libpng.
700 It does not return the fields "filter_type" and "compression_type",
702 since these are always 0. See "Unused arguments omitted".
703 get_image_height
705 my $height = $png->get_image_height ();
706 Get the image's height from the header.
708 This function corresponds to "png_get_image_height" in libpng
710 get_image_width
712 my $width = $png->get_image_width ();
713 Get the image's width from the header.
715 This function corresponds to "png_get_image_width" in libpng
717 get_interlace_type
719 my $interlace_type = $png->get_interlace_type ();
720 Get the interlace type. This is either PNG_INTERLACE_NONE or
722 PNG_INTERLACE_ADAM7.
723 This function corresponds to "png_get_interlace_type" in libpng
725 get_valid
727 my $valid = $png->get_valid ();
728 if ($valid->{oFFs}) {
729 print "The PNG has valid screen offsets.\n";
730 }
731 This function returns a hash with a key for each possible chunk which
733 may or may not be valid. The chunks which you can test for are "bKGD",
734 "cHRM", "eXIf", "gAMA", "hIST", "hIST", "iCCP", IDAT, IHDR, "iTXt",
735 "oFFs", "pCAL", "pHYs", "PLTE", "sBIT", "sCAL", "sPLT", "sRGB", "tEXt",
736 "tIME", "tRNS", and "zTXt".
737 Whereas "libpng_supports" tells you whether the installed libpng on
739 your system supports various chunks, this tells you whether the chunks
740 are present in a particular PNG image file.
741 The first argument, $png, is a PNG structure created with
743 "create_read_struct".
744 This function corresponds to "png_get_valid" in libpng, with the
746 difference being that the return value is a hash containing a key for
747 each possible chunk.
748 height
750 my $height = $png->height ();
751 Alias for "get_image_height". This is not exported, it's intended for
753 use with the object only.
754 set_IHDR
756 my $ihdr = {width => 10, height => 10, bit_depth => 8,
757 color_type => PNG_COLOR_TYPE_RGB};
758 $png->set_IHDR ($ihdr);
759 Set the IHDR chunk (the image header) of the PNG image.
761 The first argument, $png, is a writeable PNG structure created with
763 "create_write_struct". The second argument is a hash with the following
764 values:
765 width
767 The width of the image in pixels.
768 This cannot be zero, negative, or omitted.
769 height
771 The height of the image in pixels.
772 This cannot be zero, negative, or omitted.
773 bit_depth
775 The bit depth of the image (the number of bits used for each color
776 in a pixel).
777 This cannot be omitted. This can have the values 1, 2, 4, 8, 16.
778 color_type
780 The color type.
781 This cannot be omitted. This can have the values
782 PNG_COLOR_TYPE_GRAY, PNG_COLOR_TYPE_GRAY_ALPHA,
783 PNG_COLOR_TYPE_PALETTE, PNG_COLOR_TYPE_RGB,
784 PNG_COLOR_TYPE_RGB_ALPHA.
785 interlace_method
787 The method of interlacing.
788 If this is omitted, it's set to PNG_INTERLACE_NONE. This can have
789 the values PNG_INTERLACE_NONE, PNG_INTERLACE_ADAM7.
790 Other fields in the hash are ignored.
792 This function corresponds to "png_set_IHDR" in libpng, with a single
794 Perl hash reference used instead of the seven integers.
795 The values "compression_method", "filter_method", may be supplied by
797 the user but are ignored since they may only take the value 0. See
798 "Unused arguments omitted".
799 sig_cmp
801 if (sig_cmp ($should_be_png)) {
802 print "Your data does not have a PNG signature.\n";
803 }
804 This subroutine looks at $should_be_png and checks whether its first
806 bytes correspond to a valid PNG signature. It returns a true value if
807 they do not.
808 It can also take two further arguments consisting of a byte offset and
810 a number of bytes to check respectively:
811 sig_cmp ($should_be_png, 0, 8);
813 If these arguments are not supplied, the byte offset is assumed to be
815 zero, and the number of bytes to check is assumed to be eight.
816 This function corresponds to "png_sig_cmp" in libpng, with default
818 arguments of 0 and 8 if second and third arguments are not supplied.
819 width
821 my $width = $png->width ();
822 Alias for "get_image_width". This is not exported, it's intended for
824 use with the object only.
825
827 These functions deal with accessing the image data itself.
828 get_rowbytes
830 my $bytes_in_a_row = $png->get_rowbytes ();
831 This returns the number of bytes needed to hold a transformed row of an
833 image.
834 This function corresponds to "png_get_rowbytes" in libpng.
836 get_rows
838 my $rows = $png->get_rows ();
839 my $pixel = substr ($rows->[10], 20, 1);
840 This returns the rows of the PNG image, after uncompressing and
842 unfiltering, as binary data. The return value, $rows in the example, is
843 an array reference with a number of rows equal to the height of the PNG
844 image. Each element of the array reference is a string containing the
845 binary data making up a row of the image. The values of individual
846 pixels can be extracted from using a function such as "substr" or
847 "unpack". This binary data is likely to contain bytes equal to zero.
848 "get_rowbytes" gives the number of bytes in each row.
850 Each row is a Perl string. Perl terminates each row of data with an
852 extra zero byte at the end.
853 This function corresponds to "png_get_rows" in libpng.
855 set_rows
857 $png->set_rows (\@rows);
858 Set the rows of data to be written in to the PNG to @rows. @rows needs
860 to contain at least the same number of rows of data as the height of
861 the PNG image set with "set_IHDR", and the length of each entry needs
862 to be at least the width of the image multiplied by the number of bytes
863 required for each pixel.
864 This function was changed to copy the data in version 0.46.
866 This function corresponds to "png_set_rows" in libpng.
868
870 See this subsection <http://www.w3.org/TR/PNG/#11textinfo> of "The PNG
871 specification" for information on the PNG standards for text
872 information.
873 get_text
875 my $text_chunks = $png->get_text ();
876 This gets all of the text chunks in the PNG image and returns them as
878 an array reference. Each element of the array represents one text
879 chunk. This element is a hash reference with keys such as "key",
880 "lang_key", or "compression" taken from the PNG's information.
881 The text data is uncompressed by libpng. If it is international text
883 ("ITXT"), it is put into Perl's internal Unicode encoding if it is
884 found to be valid UTF-8. (PNG "international text", "ITXT" is required
885 to be in the UTF-8 encoding, and non-international text is required to
886 contain whitespace and printable ASCII characters only. See "The PNG
887 specification" for more on the requirements of a PNG text section.)
888 This function corresponds to "png_get_text" in libpng, with a Perl
890 array of hash references substituted for the C array of structs used by
891 libpng. See "set_text" for details of the keys and values which may be
892 returned.
893 set_text
895 $png->set_text ([\%chunk1, \%chunk2]);
896 This sets the text chunks in a writeable image. The input value is an
898 array reference containing one or more hash references. Each hash
899 reference must have a "key" value for the text. According to the PNG
900 specification, this should be between one and 79 bytes in length. This
901 module enforces that restriction, so if you supply a key longer than
902 that, the chunk cannot be added. A hash reference may also have the
903 following:
904 "compression"
906 The value of "compression" controls the compression of the text. If
907 "compression" is not supplied, a default value of
908 PNG_TEXT_COMPRESSION_NONE is applied. The "compression" field can
909 take the following values, available from Image::PNG::Const:
910 PNG_TEXT_COMPRESSION_NONE
912 TEXT = Printable ASCII and space characters.
913 PNG_TEXT_COMPRESSION_zTXt
915 TEXT = Printable ASCII and space characters.
916 PNG_ITXT_COMPRESSION_NONE
918 ITXT = International text, should be UTF-8.
919 PNG_ITXT_COMPRESSION_zTXt
921 ITXT = International text, should be UTF-8.
922 "itxt_length"
924 The string length of international text in bytes.
925 âðĪŠâ This is ignored by libpng when writing text chunks. When
927 reading text chunks, if the text is marked as international text,
928 libpng adds the length of the string in bytes in this field rather
929 than in "text_length".
930 "lang"
932 This should be set to name of the language of the text, if the text
933 chunk is iTXt. According to the PNG specification, "It is an ISO
934 646.IRV:1991 [ISO 646] string consisting of hyphen-separated words
935 of 1-8 alphanumeric characters each (for example cn, en-uk, no-bok,
936 x-klingon, x-KlInGoN)."
937 Support for writing "lang" was added in version 0.49 of this
939 module. (Prior to that undocumented support existed via a
940 differently-named key.)
941 âðĪŠâ This module does not attempt to check the supplied value, but
943 merely passes it to libpng. libpng appears not to check the value
944 either, nor to enforce restrictions on its length.
945 "lang_key"
947 This corresponds to the "Translated keyword" of the PNG
948 specification. Note that the user needs to supply "key" and "lang"
949 as well as "lang_key".
950 Support for writing "lang_key" was added in version 0.49 of this
952 module. (Prior to that undocumented support existed via a
953 differently-named key.)
954 "text"
956 The value of "text" is added to the PNG as the text segment. This
957 can be omitted if you just want to write a key value without any
958 accompanying text.
959 "text_length"
961 The string length in bytes. The user may set this, but it is
962 ignored when writing PNG text chunks, instead this module uses the
963 string length obtained from Perl. This key contains the length of
964 the string when reading text chunks via "get_text", but if the text
965 is marked as international text, "itxt_length" is used to return
966 its length in bytes, rather than this.
967 Whether or not the value of "text" is an ITXT field is decided by the
969 value of "compression".
970 People who want to fiddle with the text compression applied can do so
972 via "set_text_compression_level" and the other functions described
973 below that.
974 If "set_text" is called more than once, the chunks are not overwritten
976 but appended to the existing ones. (This behaviour is from libpng
977 itself.)
978 Prior to version 0.50, "set_text" would fail silently if the user added
980 invalid chunks, for example hash references without a valid "key", or
981 things which were not hash references at all. From version 0.50, all
982 invalid inputs cause fatal errors. However, unknown keys in the hash
983 references do not cause fatal errors.
984 This function corresponds to "png_set_text" in libpng.
986 Example
988 use utf8;
990 use Image::PNG::Const ':all';
991 use Image::PNG::Libpng ':all';
992 my $png = create_write_struct ();
993 $png->set_IHDR ({width => 1, height => 1, bit_depth => 8,
994 color_type => PNG_COLOR_TYPE_GRAY});
995 $png->set_rows (['X']);
996 $png->set_text ([{
997 compression => PNG_TEXT_COMPRESSION_NONE,
998 key => "Copyright",
999 text => "Copyright (C) 2020 Fat Cat",
1000 }, {
1001 compression => PNG_ITXT_COMPRESSION_zTXt,
1002 key => "Copyright",
1003 lang_key => 'čč
æĻĐ',
1004 lang => 'ja_JP',
1005 text => 'ÂĐäŧĪåïžåđīččããĢãģããžãŽãžãã',
1006 }]);
1007 $png->write_png_file ('copyright.png');
1008 (This example is included as examples/set-text.pl
1010 <https://fastapi.metacpan.org/source/BKB/Image-PNG-
1011 Libpng-0.56/examples/set-text.pl> in the distribution.)
1012 text_compression_name
1014 my $name = Image::PNG::Libpng::text_compression_name ($text->{compression});
1015 Given a numerical text compression type, return the equivalent name.
1017 The name is in upper case. The possible return values are
1018 TEXT_NONE
1020 TEXT_zTXt
1021 ITXT_NONE
1022 ITXT_zTXt
1023 an empty string
1024 if the compression method is unknown.
1025 The compression field is also used to store the information about
1027 whether the text is "international text" in UTF-8 or not.
1028 This function does not correspond to anything in libpng. The names of
1030 the text compression types are based on those in "png.h", but without
1031 the word "COMPRESSION", so for example the libpng constant
1032 "PNG_ITXT_COMPRESSION_zTXt" corresponds to a return value of
1033 "ITXT_zTXt".
1034
1036 See this subsection <http://www.w3.org/TR/PNG/#12Use-of-private-chunks>
1037 of "The PNG specification" for information on the PNG standards for
1038 private chunks.
1039 To test whether your version of libpng supports "private chunks", use
1041 "libpng_supports" with argument '"UNKNOWN_CHUNKS"':
1042 if (libpng_supports ('UNKNOWN_CHUNKS')) {
1044 # do something
1045 }
1046 get_chunk_malloc_max
1048 my $max = $png->get_chunk_malloc_max ();
1049 This gets the maximum amount of memory that a chunk can use.
1051 To test whether your version of libpng supports "get_chunk_malloc_max",
1053 use "libpng_supports" with argument '"CHUNK_MALLOC_MAX"':
1054 if (libpng_supports ('CHUNK_MALLOC_MAX')) {
1056 # do something
1057 }
1058 This function corresponds to "png_get_chunk_malloc_max" in libpng
1060 set_chunk_malloc_max
1062 $png->set_chunk_malloc_max ($max);
1063 This sets the maximum amount of memory that a chunk can use. The
1065 default value of libpng 1.6.37 is 8 megabytes.
1066 To test whether your version of libpng supports "get_chunk_malloc_max",
1068 use "libpng_supports" with argument '"CHUNK_MALLOC_MAX"':
1069 if (libpng_supports ('CHUNK_MALLOC_MAX')) {
1071 # do something
1072 }
1073 This function corresponds to "png_set_chunk_malloc_max" in libpng
1075 set_keep_unknown_chunks
1077 use Image::PNG::Const 'PNG_HANDLE_CHUNK_ALWAYS';
1078 $png->set_keep_unknown_chunks (PNG_HANDLE_CHUNK_ALWAYS);
1079 Tell libpng not to discard unknown chunks when reading the file.
1081 get_unknown_chunks
1083 my $private_chunks = $png->get_unknown_chunks ();
1084 # Get some data from a private chunk
1085 my $chunk_three_data = $private_chunks->[3]->{data};
1086 # Get the size of the data
1087 print length $chunk_three_data;
1088 This gets all of the private chunks from the image. The return value is
1090 an array reference containing hash references. If there are no private
1091 chunks, this returns an undefined value. There is one element of the
1092 array for each chunk member. It is necessary to call
1093 "set_keep_unknown_chunks" with an appropriate value before reading the
1094 file, otherwise libpng discards unknown chunks when reading the file.
1095 Each member hash reference has the following keys:
1097 name
1099 The name of the unknown chunk, in the PNG chunk format (four
1100 bytes).
1101 location
1103 The location of the unknown chunk.
1104 data
1106 The data of the unknown chunk
1107 The "size" field of the PNG structure is not stored, because the "data"
1109 member of the hash contains information on its length.
1110 This function corresponds to "png_get_unknown_chunks" in libpng
1112 set_unknown_chunks
1114 $png->set_unknown_chunks (name => 'dUCk', data => 'abcdefg',
1115 location => PNG_AFTER_IDAT);
1116 âðĪŠâ This currently does not fully function.
1118 This function corresponds to "png_set_unknown_chunks" in libpng
1120
1122 access_version_number
1123 my $libpng_version_number = Image::PNG::Libpng::access_version_number ();
1124 This function returns the version of the libpng library which the
1126 module is using as an integer number.
1127 This function corresponds to "png_access_version_number" in libpng.
1129 get_libpng_ver
1131 my $libpng_version = Image::PNG::Libpng::get_libpng_ver ();
1132 This function returns the version of the libpng library which the
1134 module is using.
1135 This function corresponds to "png_get_libpng_ver" in libpng. However,
1137 it doesn't require the "png_structp" argument of the C function. See
1138 "Unused arguments omitted".
1139
1141 get_compression_buffer_size
1142 my $size = $png->get_compression_buffer_size ();
1143 Returns the value of the compression buffer size, which may be altered
1145 with "set_compression_buffer_size".
1146 set_compression_buffer_size
1148 $png->set_compression_buffer_size (100);
1149 Set the size of the buffer which zlib uses to compress or decompress
1151 the image data. It takes one argument, an integer number. This cannot
1152 be less than 6.
1153 set_compression_level
1155 $png->set_compression_level ($number);
1156 Set the compression level used to make the PNG. A value of 0
1158 ("Z_NO_COMPRESSION") corresponds to no compression at all, otherwise
1159 $number may take values of 1 ("Z_BEST_SPEED") to 9
1160 ("Z_BEST_COMPRESSION"), with smaller values giving faster, and larger
1161 values giving better, that is with smaller output, compression. These
1162 correspond to the -1, -2, ... -9 options to the "gzip" utility, or the
1163 compression level parameter of "zlib". Calling with "-1"
1164 ("Z_DEFAULT_COMPRESSION") reverts to the default compression. Calling
1165 with any other number outside the range 0 to 9 results in a fatal
1166 error.
1167 This function was added to the module in version 0.49.
1169 set_compression_mem_level
1171 $png->set_compression_mem_level ($argument);
1172 âðĪŠâ Untested function corresponding to
1174 "png_set_compression_mem_level". Takes one integer argument.
1175 Sets the "memLevel" parameter of "deflateInit2" in zlib when writing
1177 PNG image data. Argument between 1 for minimum memory and 9 for maximum
1178 speed. The default is 8. See "zlib documentation".
1179 set_compression_window_bits
1181 $png->set_compression_window_bits ($argument);
1182 âðĪŠâ Untested function corresponding to
1184 "png_set_compression_window_bits". Takes one integer argument.
1185 Sets the "windowBits" parameter of "deflateInit2" in zlib when writing
1187 PNG image data. Argument value must be between 8 and 15 for libpng. The
1188 default is 15. See the "zlib documentation".
1189 set_compression_strategy
1191 $png->set_compression_strategy ($argument);
1192 âðĪŠâ Untested function corresponding to "png_set_compression_strategy".
1194 Takes one integer argument.
1195 Sets the "strategy" parameter of "deflateInit2" when writing PNG image
1197 data. Setting this with libpng overrides libpng's default behaviour of
1198 changing the value depending on the filter in use. For zlib, the
1199 argument is either 0 for default behaviour, or 1 to 4. See the "zlib
1200 documentation". libpng uses the default strategy 0
1201 ("Z_DEFAULT_STRATEGY") for unfiltered image data, and 1 ("Z_FILTERED")
1202 for filtered image data.
1203 set_filter
1205 use Image::PNG::Const 'PNG_FILTER_NONE';
1206 $png->set_filter (PNG_FILTER_NONE);
1207 This sets the filters which are allowed to be used for writing a PNG
1209 image. The possible values are
1210 PNG_NO_FILTERS
1212 PNG_FILTER_NONE
1213 PNG_FILTER_SUB
1214 PNG_FILTER_UP
1215 PNG_FILTER_AVG
1216 PNG_FILTER_PAETH
1217 PNG_ALL_FILTERS
1218 These can be combined using "|" (logical or):
1220 use Image::PNG::Const ':all';
1222 set_filter ($png, PNG_FILTER_UP | PNG_FILTER_AVG);
1223 Please see this subsection <http://www.w3.org/TR/PNG/#9Filter-types> of
1225 "The PNG specification" for the meanings of these filter types.
1226 This function corresponds to "png_set_filter" in libpng with the second
1228 (unused) argument omitted. See "Unused arguments omitted".
1229 set_text_compression_level
1231 $png->set_text_compression_level ($argument);
1232 âðĪŠâ Untested function corresponding to
1234 "png_set_text_compression_level". Takes one integer argument.
1235 As "set_compression_level" but for compressed text.
1237 set_text_compression_mem_level
1239 $png->set_text_compression_mem_level ($argument);
1240 âðĪŠâ Untested function corresponding to
1242 "png_set_text_compression_mem_level". Takes one integer argument.
1243 As "set_compression_mem_level" but for compressed text.
1245 set_text_compression_window_bits
1247 $png->set_text_compression_window_bits ($argument);
1248 âðĪŠâ Untested function corresponding to
1250 "png_set_text_compression_window_bits". Takes one integer argument.
1251 As "set_compression_window_bits" but for compressed text.
1253 set_text_compression_strategy
1255 $png->set_text_compression_strategy ($argument);
1256 âðĪŠâ Untested function corresponding to
1258 "png_set_text_compression_strategy". Takes one integer argument.
1259 As "set_compression_strategy" but for compressed text.
1261
1263 These routines deal with the other possible chunks of PNGs.
1264 The getter and setter routines for all other chunks are designed so
1266 that the return value of "get_wXYZ" is able to be used directly as the
1267 value for "set_wXYZ", so the values of chunks can easily be copied from
1268 one PNG to another.
1269 my $values = $png1->get_wXYZ ();
1271 $png2->set_wXYZ ($values);
1272 If the chunk is not present, or if the chunk is not supported by the
1274 user's version of libpng, the return value of "get_wXYZ" is the
1275 undefined value.
1276 bKGD
1278 The background color of the PNG image.
1279 See this subsection <http://www.w3.org/TR/PNG/#11bKGD> of "The PNG
1281 specification" for information on the PNG standards for the background
1282 chunk.
1283 get_bKGD
1285 my $bkgd = $png->get_bKGD ();
1287 Get the bKGD (background) chunk of the image.
1289 The return value is a hash with the following keys, depending on the
1291 color type of the image:
1292 index
1294 For palette color types, this is the offset into the palette.
1295 gray
1297 For grayscale color types.
1298 red
1300 green
1301 blue
1302 This function corresponds to "png_get_bKGD" in libpng with a hash
1304 function instead of a "png_color" struct.
1305 set_bKGD
1307 $png->set_bKGD ($bkgd);
1309 Set the bKGD (background) chunk of the image. $bkgd is a hash
1311 reference. The keys of the hash reference are as described in
1312 "get_bKGD".
1313 This function corresponds to "png_set_bKGD" in libpng with a hash
1315 function instead of a "png_color" struct.
1316 cHRM
1318 See this subsection <http://www.w3.org/TR/PNG/#11cHRM> of "The PNG
1319 specification" "cHRM Primary chromaticities and white point".
1320 get_cHRM
1322 my $cHRM = $png->get_cHRM ();
1324 Get the cHRM chunk as a hash reference.
1326 The keys of the hash are white_x, white_y, red_x, red_y, green_x,
1328 green_y, blue_x, blue_y.
1329 The values of the hash are floating point numbers between 0 and 1.
1331 This function corresponds to "png_get_cHRM" in libpng with a hash
1333 reference supplying the arguments. The hash's keys correspond to the
1334 names of the "double" arguments in libpng.
1335 get_cHRM_XYZ
1337 my $cHRM = $png->get_cHRM_XYZ ();
1339 Get the cHRM chunk as a hash reference for the XYZ color space.
1341 The keys of the hash are red_x, red_y, red_z, green_x, green_y,
1343 green_z, blue_x, blue_y, blue_z.
1344 The values of the hash are floating point numbers between 0 and 1.
1346 This function corresponds to "png_get_cHRM_XYZ" in libpng with a hash
1348 reference supplying the arguments. The hash's keys correspond to the
1349 names of the "double" arguments in libpng.
1350 set_cHRM
1352 $png->set_cHRM (\%cHRM);
1354 Set the cHRM chunk from a hash reference.
1356 The keys of the hash are as for "get_cHRM". The values are floating
1358 point numbers between 0 and 1.
1359 This function corresponds to "png_set_cHRM" in libpng with a hash
1361 reference instead of the "double" arguments.
1362 set_cHRM_XYZ
1364 $png->set_cHRM_XYZ (\%cHRM);
1366 Set the cHRM chunk from a hash reference for the XYZ color space.
1368 The keys of the hash are as for "get_cHRM_XYZ". The values are floating
1370 point numbers between 0 and 1. The "Y" values "red_y", "green_y", and
1371 "blue_y" should sum to 1. If you supply values outside the allowed
1372 range, libpng corrects them silently on writing rather than producing
1373 an error.
1374 This function corresponds to "png_set_cHRM_XYZ" in libpng with a hash
1376 reference instead of the "double" arguments.
1377 eXIf
1379 The "eXIf" chunk is an extension to the PNG specification. See
1380 <http://www.simplesystems.org/png-group/proposals/eXIf/>. Support for
1381 this chunk was added in version 0.50 of this module.
1382 get_eXIf
1384 my $exif = $png->get_eXIf ();
1386 This retrieves the "eXIf" chunk from $png but does not process the
1388 internal information.
1389 set_eXIf
1391 $png->set_eXIf ($exif);
1393 libpng checks whether the chunk's first two bytes are either "II" for
1395 little-endian (from Intel) or "MM" for big-endian (from Motorola) then
1396 adds the entire chunk, including the first two bytes, to the PNG.
1397 âðĪŠâ As of December 2020, there appears to be a bug in libpng in which
1399 the eXIf chunk is added twice, causing a warning of the form "libpng
1400 warning: eXIf: duplicate" on reading a PNG file back in. See
1401 <https://github.com/glennrp/libpng/pull/351>.
1402 gAMA
1404 See this subsection <http://www.w3.org/TR/PNG/#11gAMA> of "The PNG
1405 specification".
1406 get_gAMA
1408 my $gamma = $png->get_gAMA ();
1410 Get the gamma value or gAMA chunk. The return value is a floating-point
1412 number.
1413 This function corresponds to "png_get_gAMA" in libpng
1415 set_gAMA
1417 $png->set_gAMA (0.2);
1419 Set the gamma value or gAMA chunk.
1421 This function corresponds to "png_set_gAMA" in libpng
1423 hIST
1425 See this subsection <http://www.w3.org/TR/PNG/#11hIST> of "The PNG
1426 specification".
1427 get_hIST
1429 my $hist = $png->get_hIST ();
1431 If the PNG file contains a histogram, the return value is array
1433 reference, otherwise it is the undefined value. The number of entries
1434 in the array reference is the same as in the palette.
1435 This function corresponds to "png_get_hIST" in libpng
1437 set_hIST
1439 $png->set_hIST (\@hist);
1441 Set the histogram of frequencies of the colors of a paletted ("PLTE")
1443 image. The entries of the histogram are 16 bit unsigned integers, so
1444 the maximum value that can be entered is 65535 = 2^16 - 1. Larger
1445 numbers and floating point numbers will cause a warning to be printed
1446 and the value to be set to zero. The histogram must have exactly the
1447 same number of entries as the palette or the call will fail with a
1448 warning. A histogram cannot be added to an image without a palette. A
1449 call to set_hIST for an image without a palette will cause a warning
1450 and return without setting the value.
1451 (I'm not sure of the best form of error handling for this function so
1453 it may change in future versions to have errors for a bad histogram
1454 rather than warnings.)
1455 This function corresponds to "png_set_hIST" in libpng
1457 iCCP
1459 See this subsection <http://www.w3.org/TR/PNG/#11iCCP> of "The PNG
1460 specification".
1461 get_iCCP
1463 my $iccp = $png->get_iCCP ();
1465 The return value is a hash with two keys,
1467 name
1469 The name of the profile.
1470 profile
1472 The color profile.
1473 The "compression_type" value, which is always 0, is not returned. See
1475 "Unused arguments omitted".
1476 This function corresponds to "png_get_iCCP" in libpng.
1478 set_iCCP
1480 $png->set_iCCP ({name => 'name', profile => 'profile'});
1482 This function corresponds to "png_set_iCCP" in libpng. For details of
1484 the arguments, see "get_iCCP". A "compression_type" argument, which
1485 must always be 0 anyway, is ignored. See "Unused arguments omitted".
1486 oFFs
1488 This is an extension to the PNG specification. See
1489 <http://www.libpng.org/pub/png/spec/1.1/pngext-1.1.0-pdg.html#C.oFFs>.
1490 get_oFFs
1492 my $phys = $png->get_oFFs ();
1494 Get oFFs chunk. Return value is a hash reference
1496 This function corresponds to "png_get_oFFs" in libpng
1498 set_oFFs
1500 $png->set_oFFs ({x_offset => 1, y_offset => 1, unit_type => 0});
1502 Set oFFs chunk. See the specification linked above for the meanings of
1504 the parameters. If "unit_type" is not 0 or 1, a warning is produced.
1505 This function corresponds to "png_set_oFFs" in libpng
1507 pCAL
1509 pCAL is an extension of the PNG specification which allows one to
1510 associate pixels in the PNG image with non-image data such as a heat
1511 map. See
1512 <http://www.libpng.org/pub/png/spec/1.1/pngext-1.1.0-pdg.html#C.pCAL>.
1513 To test whether your version of libpng supports "the pCAL extension",
1515 use "libpng_supports" with argument '"pCAL"':
1516 if (libpng_supports ('pCAL')) {
1518 # do something
1519 }
1520 get_pCAL
1522 my $pcal = $png->get_pCAL ();
1524 The return value is a hash reference with the following keys:
1526 params
1528 If this exists, its value is a reference to an array containing the
1529 parameter list of the pCAL chunk, which are floating point numbers.
1530 Within the PNG file chunk, these parameters are stored as strings
1531 representing floating point numbers, but you can pass in Perl
1532 floating point numbers rather than strings. The number of
1533 parameters you should set is fixed by the "type" parameter. Refer
1534 to the PNG specification for full details.
1535 purpose
1537 The purpose string of the pCAL chunk.
1538 type
1540 The equation type as a number, from 0 to 3. See the PNG
1541 specification for the meanings. Other numbers cause an error.
1542 units
1544 The units as a string. See the PNG specification for details.
1545 x0 The zero value for the equation, an integer.
1547 x1 The max value for the equation, an integer.
1549 This function corresponds to "png_get_pCAL" in libpng
1551 set_pCAL
1553 $png->set_pCAL (\%values);
1555 See "get_pCAL" for the parameters of %values.
1557 This function corresponds to "png_set_pCAL" in libpng
1559 pHYs
1561 See this subsection <http://www.w3.org/TR/PNG/#11pHYs> of "The PNG
1562 specification".
1563 get_pHYs
1565 my $phys = $png->get_pHYs ();
1567 The return value is a hash reference with the keys
1569 res_x
1571 res_y
1572 unit_type
1573 Is either 0 or 1.
1574 This function corresponds to "png_get_pHYs" in libpng
1576 set_pHYs
1578 $png->set_pHYs ({res_x => 1, res_y => 1, unit_type => 1});
1580 This function corresponds to "png_set_pHYs" in libpng
1582 PLTE
1584 See this subsection <http://www.w3.org/TR/PNG/#11PLTE> of "The PNG
1585 specification" for information on the PNG standards for the palette
1586 chunk.
1587 get_palette_max
1589 my $pmax = $png->get_palette_max ();
1591 If your libpng supports it, this will return the maximum palette index
1593 found in the image, or "-1" if the palette was not checked, or "0" if
1594 no palette was found.
1595 To test whether your version of libpng supports "get_palette_max", use
1597 "libpng_supports" with argument '"GET_PALETTE_MAX"':
1598 if (libpng_supports ('GET_PALETTE_MAX')) {
1600 # do something
1601 }
1602 âðĪŠâ This function is implemented but so far it is not very clear to me
1604 what it does, since, for example, it returns zero for the test image
1605 t/tantei-san.png which is an image with a fully-used 256-color palette.
1606 I've asked about it on the libpng mailing list
1607 <https://sourceforge.net/p/png-mng/mailman/png-mng-
1608 implement/?viewmonth=202012&viewday=14>, but so far nobody has
1609 responded.
1610 get_PLTE
1612 my $colors = $png->get_PLTE ();
1614 # Get the green value of the twentieth entry in the palette.
1615 my $green = $colors->[20]->{green};
1616 This function gets the palette from the PNG. The return value is an
1618 array reference containing the palette. This array contains hash
1619 references with the values "green", "blue" and "red" for the color of
1620 each pixel in the palette. If the PNG has no palette, it returns an
1621 undefined value.
1622 A PNG image may or may not contain a palette. To check whether the
1624 image contains a palette, use something of the following form:
1625 use Image::PNG::Const ':all';
1627 my $color_type = $png->get_color_type ();
1628 if ($color_type == PNG_COLOR_TYPE_PALETTE) {
1629 # The PNG uses a palette.
1630 }
1631 A PNG image may also contain a palette even when the "color_type" does
1633 not indicate that. To check for that case, use "get_valid".
1634 This function corresponds to "png_get_PLTE" in libpng.
1636 set_PLTE
1638 $png->set_PLTE ($palette);
1640 Set the palette of $png. The argument is an array reference containing
1642 hash references. There is one hash reference for each palette entry.
1643 The hash references contain three fields, red, green, and blue,
1644 corresponding to the pixel value for that palette entry. Other values
1645 in the hash references are ignored. For example,
1646 $png->set_PLTE ([{red => 1, green => 99, blue => 0x10},
1648 {red => 0xFF, green => 0xFF, blue => 0xFF}]);
1649 creates a palette with two entries in $png.
1651 This function corresponds to "png_set_PLTE" in libpng.
1653 sBIT
1655 See this subsection <http://www.w3.org/TR/PNG/#11sBIT> of "The PNG
1656 specification".
1657 get_sBIT
1659 my $sbit = $png->get_sBIT ();
1661 The return value is a hash reference containing integer values for the
1663 keys "red", "blue", "green", "gray" and "alpha", depending on the
1664 "color_type" of $png.
1665 âðĪŠâ Prior to version 0.50 of this module, get_sBIT wrote values of 0
1667 for all of the keys, regardless of the "color_type", causing errors in
1668 some circumstances. From version 0.50, hash keys are not entered if the
1669 "color_type" of the image makes them invalid.
1670 This function corresponds to "png_get_sBIT" in libpng
1672 set_sBIT
1674 $png->set_sBIT ({red => 1, blue => 2, green => 3});
1676 The argument is a hash reference containing integer values for the keys
1678 "red", "blue", "green", "gray", and "alpha", as required by the
1679 "color_type" of $png.
1680 This function corresponds to "png_set_sBIT" in libpng
1682 sCAL
1684 This is an extension to the PNG specification. See
1685 <http://www.libpng.org/pub/png/spec/1.1/pngext-1.1.0-pdg.html#C.sCAL>.
1686 To test whether your version of libpng supports "the sCAL chunk", use
1688 "libpng_supports" with argument '"sCAL"':
1689 if (libpng_supports ('sCAL')) {
1691 # do something
1692 }
1693 get_sCAL
1695 my $scal = $png->get_sCAL ();
1697 The returned hash value contains the following keys:
1699 unit
1701 The unit type, which is either PNG_SCALE_UNKNOWN, PNG_SCALE_METER,
1702 or PNG_SCALE_RADIAN.
1703 width
1705 The width, as a string.
1706 height
1708 The height, as a string.
1709 This function corresponds to "png_get_sCAL_s" in libpng. Note that this
1711 uses the sCAL_s function rather than the get_sCAL and the returned
1712 values are the strings themselves rather than parsed numbers.
1713 set_sCAL
1715 $png->set_sCAL ($scal);
1717 $scal is a hash reference containing the keys described in "get_sCAL".
1719 This function corresponds to "png_set_sCAL_s" in libpng. Note that this
1721 uses the "set_sCAL_s" function rather than "set_sCAL" and the input
1722 values are the strings themselves rather than numbers.
1723 sPLT
1725 See this subsection <http://www.w3.org/TR/PNG/#11sPLT> of "The PNG
1726 specification".
1727 get_sPLT
1729 âðĪŠâ Provisional. See "set_sPLT" for documentation, the return value is
1731 like the input of that.
1732 set_sPLT
1734 $png->set_sPLT ([{ name => 'palette', depth => 8, entries => [{red => 1, blue => 2},]}]);
1736 Set suggested palettes. The input is an array reference containing hash
1738 references with the following fields:
1739 name
1741 The name of the suggested palette.
1742 depth
1744 The depth of the suggested palette.
1745 entries
1747 The entries of the palette. This is an array reference containing
1748 hash references with keys as follows:
1749 red
1751 blue
1752 green
1753 frequency
1754 alpha
1755 The field "nentries" which is returned by "get_sPLT" does not need to
1757 be specified, it is calculated from the length of "entries".
1758 sRGB
1760 See this subsection <http://www.w3.org/TR/PNG/#11sRGB> of "The PNG
1761 specification".
1762 get_sRGB
1764 my $sRGB = $png->get_sRGB ();
1766 The return value is an integer number corresponding to one of the
1768 following:
1769 PNG_sRGB_INTENT_SATURATION
1771 PNG_sRGB_INTENT_PERCEPTUAL
1772 PNG_sRGB_INTENT_ABSOLUTE
1773 PNG_sRGB_INTENT_RELATIVE
1774 This function corresponds to "png_get_sRGB" in libpng
1776 set_sRGB
1778 $png->set_sRGB ($srgb);
1780 $srgb is one of the values described in "get_sRGB".
1782 This function corresponds to "png_set_sRGB" in libpng
1784 tIME
1786 See this subsection <http://www.w3.org/TR/PNG/#11timestampinfo> of "The
1787 PNG specification" for information on the PNG standards for time stamp
1788 information.
1789 get_tIME
1791 my $time = $png->get_tIME ();
1793 if ($time && $time->{year} < 2005) {
1794 warn "Your PNG is now getting old. Don't forget to oil it to prevent rust.";
1795 }
1796 The return value is either the undefined value, if no "tIME" chunk
1798 exists in the PNG, or a hash reference containing fields "year",
1799 "month", "day", "hour", "minute" and "second". "month" and "day" start
1800 from 1 rather than 0.
1801 The "modification time value" of the PNG image is a chunk written into
1803 the PNG file itself, and may not have the same value as the operating
1804 system's modification time for the file. The tIME chunk is not a
1805 compulsory requirement for PNG files, and most PNG image files do not
1806 contain this chunk. PNG tIME chunks do not contain a time zone.
1807 According to this subsection <http://www.w3.org/TR/PNG/#11tIME> of "The
1808 PNG specification", "Universal Time (UTC) should be specified rather
1809 than local time."
1810 This function corresponds to "png_get_tIME" in libpng, with a Perl hash
1812 reference substituted for the C struct "png_timep" used in libpng.
1813 set_tIME
1815 # Set the time to "now"
1817 $png->set_tIME ();
1818 # Set the time
1819 $png->set_tIME ({year => 1999, month => 12});
1820 Set the modification time of the PNG to the values given by the
1822 argument, a hash reference containing the fields "year", "month", "day"
1823 for the day of the month, "hour", "minute", and "second". The
1824 numbering for "month" and "day" is from 1, not 0. If any of year, hour,
1825 minute or second is omitted from the hash reference, these are set to
1826 zero. If month or day are omitted, these are set to 1. PNG tIME chunks
1827 do not contain a time zone. According to this subsection
1828 <http://www.w3.org/TR/PNG/#11tIME> of "The PNG specification",
1829 "Universal Time (UTC) should be specified rather than local time." If
1830 the entire argument is omitted or contains an invalid value, the time
1831 is set to the current time.
1832 This function corresponds to "png_set_tIME" in libpng, with a Perl hash
1834 reference substituted for the C struct "png_timep" used in libpng.
1835 tRNS
1837 See this subsection <http://www.w3.org/TR/PNG/#11tRNS> of "The PNG
1838 specification".
1839 get_tRNS
1841 my $trns = $png->get_tRNS ();
1843 Get the "tRNS" chunk. If the image is a palette type, this is an array
1845 reference. If the image is a non-palette type, this is a hash
1846 containing values for the keys red, green, blue, and gray.
1847 set_tRNS
1849 $png->set_tRNS ($trns);
1851 Set the "tRNS" chunk. If the image is a palette type, $trns is a
1853 reference to an array of positive or zero values between 0 and 255 of
1854 the same size as the palette. It must not contain more than 256 values.
1855 If the image is not a palette type, $trns is a hash reference
1856 containing values for the keys red, green, blue and gray.
1857
1859 set_bgr
1860 $png->set_bgr ();
1861 âðĪŠâ Untested. Flips RGB to BGR. See the libpng manual for details.
1863 To test whether your version of libpng supports "set_bgr", for a read
1865 object, use "libpng_supports" with argument '"READ_BGR"'.
1866 if (libpng_supports ('READ_BGR')) {
1868 # do something
1869 }
1870 For a write object, use argument '"WRITE_BGR"'.
1872 This function corresponds to "png_set_bgr" in libpng
1874 set_expand
1876 $png->set_expand ();
1877 Set transformation in $png such that paletted images are expanded to
1879 RGB, grayscale images of bit-depth less than 8 are expanded to 8-bit
1880 images, and tRNS chunks are expanded to alpha channels.
1881 To test whether your version of libpng supports "set_expand", use
1883 "libpng_supports" with argument '"READ_EXPAND"':
1884 if (libpng_supports ('READ_EXPAND')) {
1886 # do something
1887 }
1888 This function corresponds to "png_set_expand" in libpng
1890 set_expand_16
1892 $png->set_expand_16 ();
1893 âðĪŠâ Untested.
1895 To test whether your version of libpng supports "set_expand_16", use
1897 "libpng_supports" with argument '"READ_EXPAND_16"':
1898 if (libpng_supports ('READ_EXPAND_16')) {
1900 # do something
1901 }
1902 This function corresponds to "png_set_expand_16" in libpng
1904 set_expand_gray_1_2_4_to_8
1906 $png->set_expand_gray_1_2_4_to_8 ();
1907 âðĪŠâ Untested.
1909 To test whether your version of libpng supports
1911 "set_expand_gray_1_2_4_to_8", use "libpng_supports" with argument
1912 '"READ_EXPAND"':
1913 if (libpng_supports ('READ_EXPAND')) {
1915 # do something
1916 }
1917 This function corresponds to "png_set_expand_gray_1_2_4_to_8" in libpng
1919 set_gray_to_rgb
1921 $png->set_gray_to_rgb ();
1922 Convert a grayscale PNG file to RGB format on reading.
1924 To test whether your version of libpng supports "set_gray_to_rgb", use
1926 "libpng_supports" with argument '"READ_GRAY_TO_RGB"':
1927 if (libpng_supports ('READ_GRAY_TO_RGB')) {
1929 # do something
1930 }
1931 This function corresponds to "png_set_gray_to_rgb" in libpng
1933 set_invert_alpha
1935 $png->set_invert_alpha ();
1936 âðĪŠâ Untested. See the libpng manual for details.
1938 To test whether your version of libpng supports "set_invert_alpha", use
1940 "libpng_supports" with argument '"READ_INVERT_ALPHA"':
1941 if (libpng_supports ('READ_INVERT_ALPHA')) {
1943 # do something
1944 }
1945 This function corresponds to "png_set_invert_alpha" in libpng
1947 set_invert_mono
1949 $png->set_invert_mono ();
1950 Invert monochrome images. See the libpng manual for details.
1952 To test whether your version of libpng supports "set_invert_mono", use
1954 "libpng_supports" with argument '"READ_INVERT"':
1955 if (libpng_supports ('READ_INVERT')) {
1957 # do something
1958 }
1959 This function corresponds to "png_set_invert_mono" in libpng
1961 set_packing
1963 $png->set_packing ();
1964 When reading a PNG, expand the image to 1 pixel per byte for bit-depths
1966 1, 2 and 4 without changing the order of the pixels. If this is not
1967 called, the pixels of bit_depths 1, 2 and 4 are packed into bytes as
1968 small as possible, for example, 8 pixels per byte for 1-bit files. See
1969 the libpng manual for details. See also "set_packswap".
1970 To test whether your version of libpng supports "set_packing", for a
1972 read object, use "libpng_supports" with argument '"READ_PACK"'.
1973 if (libpng_supports ('READ_PACK')) {
1975 # do something
1976 }
1977 For a write object, use argument '"WRITE_PACK"'.
1979 This function corresponds to "png_set_packing" in libpng
1981 set_packswap
1983 $png->set_packswap ();
1984 Swaps the bits of 1, 2, or 4 bits/pixel images. The default for PNG
1986 image is to put the left pixel into the highest part of the byte, so
1987 for example if the bit depth is 1, the pixels from left to right go
1988 into a byte as values 128 for the leftmost, 64, 32, 16, 8, 4, 2, then 1
1989 for the rightmost pixel. This call reverses that behavior so that the
1990 pixels in a byte go 1 for the leftmost, 2, ..., then 128 for the
1991 rightmost. See the libpng manual for details.
1992 To test whether your version of libpng supports "set_packswap", for a
1994 read object, use "libpng_supports" with argument '"READ_PACKSWAP"'.
1995 if (libpng_supports ('READ_PACKSWAP')) {
1997 # do something
1998 }
1999 For a write object, use argument '"WRITE_PACKSWAP"'.
2001 This function corresponds to "png_set_packswap" in libpng
2003 set_palette_to_rgb
2005 $png->set_palette_to_rgb ();
2006 âðĪŠâ Untested. See the libpng manual for details.
2008 To test whether your version of libpng supports "set_palette_to_rgb",
2010 use "libpng_supports" with argument '"READ_EXPAND"':
2011 if (libpng_supports ('READ_EXPAND')) {
2013 # do something
2014 }
2015 This function corresponds to "png_set_palette_to_rgb" in libpng
2017 set_scale_16
2019 $png->set_scale_16 ()
2020 âðĪŠâ Untested.
2022 To test whether your version of libpng supports "set_scale_16", use
2024 "libpng_supports" with argument '"READ_SCALE_16_TO_8"':
2025 if (libpng_supports ('READ_SCALE_16_TO_8')) {
2027 # do something
2028 }
2029 This function corresponds to "png_set_scale_16" in libpng
2031 set_strip_16
2033 $png->set_strip_16 ();
2034 Strip the pixels of a PNG stream with 16 bits per channel to 8 bits per
2036 channel.
2037 To test whether your version of libpng supports "set_strip_16", use
2039 "libpng_supports" with argument '"READ_STRIP_16_TO_8"':
2040 if (libpng_supports ('READ_STRIP_16_TO_8')) {
2042 # do something
2043 }
2044 This function corresponds to "png_set_strip_16" in libpng
2046 set_strip_alpha
2048 $png->set_strip_alpha ();
2049 Strip the alpha channel of a PNG stream.
2051 To test whether your version of libpng supports "set_strip_alpha", use
2053 "libpng_supports" with argument '"READ_STRIP_ALPHA"':
2054 if (libpng_supports ('READ_STRIP_ALPHA')) {
2056 # do something
2057 }
2058 This function corresponds to "png_set_strip_alpha" in libpng
2060 set_swap
2062 $png->set_swap ();
2063 âðĪŠâ Untested. Swaps around the bytes of 16 bits/pixel images. See the
2065 libpng manual for details.
2066 To test whether your version of libpng supports "set_swap", use
2068 "libpng_supports" with argument '"READ_SWAP"':
2069 if (libpng_supports ('READ_SWAP')) {
2071 # do something
2072 }
2073 This function corresponds to "png_set_swap" in libpng
2075 set_swap_alpha
2077 $png->set_swap_alpha ();
2078 âðĪŠâ Untested. See the libpng manual for details.
2080 To test whether your version of libpng supports "set_swap_alpha", use
2082 "libpng_supports" with argument '"READ_SWAP_ALPHA"':
2083 if (libpng_supports ('READ_SWAP_ALPHA')) {
2085 # do something
2086 }
2087 This function corresponds to "png_set_swap_alpha" in libpng
2089 set_tRNS_to_alpha
2091 $png->set_tRNS_to_alpha
2092 âðĪŠâ Untested. See the libpng manual for details.
2094 To test whether your version of libpng supports "set_tRNS_to_alpha",
2096 use "libpng_supports" with argument '"READ_EXPAND"':
2097 if (libpng_supports ('READ_EXPAND')) {
2099 # do something
2100 }
2101 This function corresponds to "png_set_tRNS_to_alpha" in libpng
2103
2105 get_chunk_cache_max
2106 my $max = $png->get_chunk_cache_max ();
2107 Get the maximum number of ancilliary chunks allowed. See also
2109 "set_chunk_cache_max".
2110 To test whether your version of libpng supports "get_chunk_cache_max",
2112 use "libpng_supports" with argument '"CHUNK_CACHE_MAX"':
2113 if (libpng_supports ('CHUNK_CACHE_MAX')) {
2115 # do something
2116 }
2117 This function corresponds to "png_png_get_chunk_cache_max" in libpng
2119 get_rgb_to_gray_status
2121 my $badpixels = $png->get_rgb_to_gray_status ();
2122 Returns a true value if there were some non-gray pixels in an RGB image
2124 after calling "set_rgb_to_gray".
2125 Saving bandwidth
2127 Try this one weird old "get_rgb_to_gray_status" trick to check whether
2129 an image marked as RGB is really monochrome or not.
2130 use utf8;
2132 use FindBin '$Bin';
2133 use Image::PNG::Libpng ':all';
2134 use Image::PNG::Const ':all';
2135 my $file = 'life.png';
2137 print "Size before: ", -s $file, "\n";
2138 my $png = create_reader ($file);
2139 $png->read_info ();
2140 $png->set_rgb_to_gray ();
2141 if ($png->get_rgb_to_gray_status ()) {
2142 print "The image contained non-gray pixels.\n";
2143 }
2144 else {
2145 print "The image was grayscale already.\n";
2146 }
2147 $png->read_image ();
2148 $png->read_end ();
2149 my $wpng = $png->copy_png ();
2150 my $ihdr = $wpng->get_IHDR ();
2151 $ihdr->{color_type} = PNG_COLOR_TYPE_GRAY;
2152 $wpng->set_IHDR ($ihdr);
2153 my $after = "life-gray.png";
2154 $wpng->write_png_file ($after);
2155 print "Size after: ", -s $after, "\n";
2156 if (! png_compare ($file, $after)) {
2158 print "The two files contain exactly the same image data.\n";
2159 }
2160 else {
2161 print "The two files contain different image data.\n";
2162 }
2163 (This example is included as examples/xkcd.pl
2165 <https://fastapi.metacpan.org/source/BKB/Image-PNG-
2166 Libpng-0.56/examples/xkcd.pl> in the distribution.)
2167 The output looks like this:
2169 Size before: 97299
2171 The image was grayscale already.
2172 Size after: 46956
2173 The two files contain exactly the same image data.
2174 examples/life-gray.png <https://fastapi.metacpan.org/source/BKB/Image-
2176 PNG-Libpng-0.56/examples/life-gray.png> is included in the
2177 distribution.
2178 Correct use of Image::PNG::Libpng could have spared as many as 50,000
2180 bytes from the indignity of being sent around the internet.
2181 This also illustrates the use of "png_compare".
2183 Original image, licence statement and copyright notice here
2185 <https://xkcd.com/2391/>.
2186 get_user_height_max
2188 $png->get_user_height_max ();
2189 Get the maximum height allowed for a PNG file. The default is 1 million
2191 pixels. These values can be changed by "set_user_limits".
2192 This function corresponds to "png_get_user_height_max" in libpng
2194 get_user_width_max
2196 $png->get_user_width_max ();
2197 Get the maximum width allowed for a PNG file. The default is 1 million
2199 pixels. These values can be changed by "set_user_limits".
2200 This function corresponds to "png_get_user_width_max" in libpng
2202 permit_mng_features
2204 $png->permit_mng_features ($mask);
2205 âðĪŠâ Untested. $mask is an integer containing flags. See the libpng
2207 manual for details.
2208 (MNG, 'Multiple-image Network Graphics', is an image animation format
2210 related to PNG. It has not been widely adopted.)
2211 To test whether your version of libpng supports "permit_mng_features",
2213 use "libpng_supports" with argument '"MNG_FEATURES"':
2214 if (libpng_supports ('MNG_FEATURES')) {
2216 # do something
2217 }
2218 This function corresponds to "png_permit_mng_features" in libpng
2220 set_add_alpha
2222 $png->set_add_alpha ($filler, $filler_loc);
2223 âðĪŠâ Untested. Change $png to add an alpha channel. This only works for
2225 grayscale or RGB images with bit depth of 8 or 16. $filler contains the
2226 alpha value to assign to each pixel, and $filler_loc is either
2227 "PNG_FILLER_BEFORE" or "PNG_FILLER_AFTER". The function of
2228 "set_add_alpha" is "set_filler" and a change of the color type to add
2229 an alpha channel. See the libpng manual for details.
2230 To test whether your version of libpng supports "set_add_alpha", use
2232 "libpng_supports" with argument '"READ_FILLER"':
2233 if (libpng_supports ('READ_FILLER')) {
2235 # do something
2236 }
2237 This function corresponds to "png_set_add_alpha" in libpng
2239 set_alpha_mode
2241 $png->set_alpha_mode ($mode, $screen_gamma);
2242 âðĪŠâ Untested. $mode is an integer, one of the "PNG_ALPHA_*" constants.
2244 $screen_gamma is a floating point number. See the libpng manual for
2245 details.
2246 To test whether your version of libpng supports "set_alpha_mode", use
2248 "libpng_supports" with argument '"READ_ALPHA_MODE"':
2249 if (libpng_supports ('READ_ALPHA_MODE')) {
2251 # do something
2252 }
2253 This function corresponds to "png_set_alpha_mode" in libpng
2255 set_background
2257 $png->set_background (\%color, $bkgd_gamma_code, $need_expand, $gamma);
2258 "set_background" sets the background of an image with an alpha channel
2260 or simple transparency (a "tRNS" chunk) with the color specified by
2261 %color. If $bkgd_gamma_code is set to "PNG_BACKGROUND_GAMMA_SCREEN", it
2262 indicates that the supplied background color is in the gamma space of
2263 the display, else if it is set to "PNG_BACKGROUND_GAMMA_FILE", the
2264 color is in the gamma space of the file. If $bkgd_gamma_code is set to
2265 "PNG_BACKGROUND_GAMMA_UNIQUE", the value of $gamma is used, otherwise
2266 $gamma appears to be ignored and can be omitted. (This is not
2267 documented in the libpng manual or elsewhere. See
2268 <https://github.com/glennrp/libpng/issues/358>.)
2269 If the background color is supplied at the original bit-depth for a
2271 grayscale image that is expanded to truecolor or to a higher bit-depth,
2272 $need_expand must be set to a true value, but if the background color
2273 is supplied at the expanded bit-depth, $need_expand must be set to a
2274 false value. Similarly for paletted images, if %color is supplied as a
2275 palette index ($color{index}), $need_expand must be set to a true
2276 value, but if %color is an RGB triplet, $need_expand must be set to a
2277 false value.
2278 See "Setting the background" for an example.
2280 To test whether your version of libpng supports "set_background", use
2282 "libpng_supports" with argument '"READ_BACKGROUND"':
2283 if (libpng_supports ('READ_BACKGROUND')) {
2285 # do something
2286 }
2287 set_chunk_cache_max
2289 $png->set_chunk_cache_max (42);
2290 Set the maximum number of ancilliary chunks allowed. The default is
2292 1000. See also "get_chunk_cache_max".
2293 To test whether your version of libpng supports "set_chunk_cache_max",
2295 use "libpng_supports" with argument '"CHUNK_CACHE_MAX"':
2296 if (libpng_supports ('CHUNK_CACHE_MAX')) {
2298 # do something
2299 }
2300 This function corresponds to "png_png_set_chunk_cache_max" in libpng
2302 set_filler
2304 $png->set_filler ($filler, $flags);
2305 Set transformations in $png such that a filler byte $filler is added
2307 when an 8-bit grayscale image or 24-bit RGB image is read, and a filler
2308 byte is deleted when an 8-bit grayscale image or 24-bit RGB image is
2309 written. $flags may be "PNG_FILLER_BEFORE" or "PNG_FILLER_AFTER". An
2310 error is produced if $png has bit depth less than 8.
2311 This does not change the color type of the image. See the related
2313 function "set_add_alpha" if you want to add an alpha channel.
2314 To test whether your version of libpng supports "set_filler", use
2316 "libpng_supports" with argument '"READ_FILLER"':
2317 if (libpng_supports ('READ_FILLER')) {
2319 # do something
2320 }
2321 This function corresponds to "png_set_filler" in libpng
2323 set_gamma
2325 $png->set_gamma ($screen_gamma, $output_gamma);
2326 âðĪŠâ Untested. $screen_gamma and $output_gamma should contain floating-
2328 point arguments. See the libpng manual for details.
2329 To test whether your version of libpng supports "set_gamma", use
2331 "libpng_supports" with argument '"READ_GAMMA"':
2332 if (libpng_supports ('READ_GAMMA')) {
2334 # do something
2335 }
2336 This function corresponds to "png_set_gamma" in libpng
2338 set_quantize
2340 $png->set_quantize (\@palette, $ncolors, \@histogram, $full_quantize);
2341 The @palette part must be set to a palette similar to "set_PLTE".
2343 $ncolors must be the length of @palette or shorter. @histogram can be
2344 an empty array or if not it needs to be an array of integers of exactly
2345 the same length as @palette. The integers represent the frequency of
2346 the colors in @palette. These integers can range from 0 to 65355.
2347 Larger values or negative values cause an error. The final argument,
2348 $full_quantize, should be 1 for RGB images or 0 for paletted images.
2349 Experiments in quantization
2351 This example program experiments with two ways to quantize a PNG image,
2353 first of all using a completely random palette, and second using colors
2354 picked from the image at random:
2355 use utf8;
2357 use FindBin '$Bin';
2358 use Image::PNG::Libpng ':all';
2359 my $file = "wave.png";
2360 my $ncolors = 40;
2361 my $palette = randompalette ($ncolors);
2362 write_with_palette ($file, $palette, $ncolors, [], "random");
2363 my $picked = points ($file, $ncolors);
2364 my @hist = (1) x $ncolors;
2365 write_with_palette ($file, $picked, $ncolors, \@hist, "picked");
2366 exit;
2367 sub write_with_palette
2369 {
2370 my ($file, $palette, $ncolors, $hist, $name) = @_;
2371 my $rpng = create_reader ($file);
2372 $rpng->set_quantize ($palette, $ncolors, $hist, 1);
2373 $rpng->read_png ();
2374 my $wpng = copy_png ($rpng);
2375 $wpng->set_PLTE ($palette);
2376 $wpng->write_png_file ("$name-$file");
2377 }
2378 sub points
2380 {
2381 my ($pngfile, $ncolors) = @_;
2382 my $png = read_png_file ($pngfile);
2383 my $rows = $png->get_rows ();
2384 my $h = $png->height ();
2385 my $w = $png->width ();
2386 my $ch = $png->get_channels ();
2387 my @p;
2388 for (0..$ncolors-1) {
2389 my $x = int (rand ($w));
2390 my $y = int (rand ($h));
2391 my $row = $rows->[$y];
2392 my @pix = split ('', substr ($row, $x*$ch, $ch));
2393 push @p, {
2394 red => ord ($pix[0]),
2395 green => ord ($pix[1]),
2396 blue => ord ($pix[2]),
2397 };
2398 }
2399 return \@p;
2400 }
2401 sub randompalette
2403 {
2404 my ($n) = @_;
2405 my @p;
2406 for (0..$n-1) {
2407 my %color;
2408 for my $c (qw!red green blue!) {
2409 $color{$c} = int (rand (256))
2410 }
2411 push @p, \%color;
2412 }
2413 return \@p;
2414 }
2415 (This example is included as examples/q.pl
2417 <https://fastapi.metacpan.org/source/BKB/Image-PNG-
2418 Libpng-0.56/examples/q.pl> in the distribution.)
2419 examples/wave.png <https://fastapi.metacpan.org/source/BKB/Image-PNG-
2421 Libpng-0.56/examples/wave.png> is included in the distribution.
2422 examples/random-wave.png
2424 <https://fastapi.metacpan.org/source/BKB/Image-PNG-
2425 Libpng-0.56/examples/random-wave.png> is included in the distribution.
2426 examples/picked-wave.png
2428 <https://fastapi.metacpan.org/source/BKB/Image-PNG-
2429 Libpng-0.56/examples/picked-wave.png> is included in the distribution.
2430 set_rgb_to_gray
2432 $png->set_rgb_to_gray ();
2433 $png->set_rgb_to_gray ($error_action, $red_weight, $green_weight);
2435 Convert a PNG image from RGB (colored) to gray. See the libpng manual
2437 for details.
2438 Without arguments, the libpng default values are used for $red_weight
2440 and $green_weight, and an error action of "none" is chosen. If the
2441 error action is set to a value of "PNG_ERROR_ACTION_WARN" or
2442 "PNG_ERROR_ACTION_ERROR", pixels in the RGB image where the R, G and B
2443 values are not equal will cause a warning or error respectively. To get
2444 the default values for $red_weight or $green_weight, use any negative
2445 value. See the libpng manual for details.
2446 If you choose "PNG_ERROR_ACTION_NONE" you can find out whether there
2448 were non-RGB pixels in your image using "get_rgb_to_gray_status".
2449 This function corresponds to "png_png_set_rgb_to_gray" in libpng with
2451 $error_action having a default value of "PNG_ERROR_ACTION_NONE", and
2452 $red_weight and $green_weight both set to negative values.
2453 Convert a colored image to gray
2455 use utf8;
2457 use FindBin '$Bin';
2458 use Image::PNG::Libpng ':all';
2459 use Image::PNG::Const ':all';
2460 my $png = create_reader ("$Bin/luv.png");
2462 $png->read_info ();
2463 $png->set_rgb_to_gray ();
2464 $png->read_image ();
2465 $png->read_end ();
2466 my $wpng = $png->copy_png ();
2467 my $ihdr = $wpng->get_IHDR ();
2468 $ihdr->{color_type} = PNG_COLOR_TYPE_GRAY_ALPHA;
2469 $wpng->set_IHDR ($ihdr);
2470 $wpng->write_png_file ("$Bin/grayface.png");
2471 (This example is included as examples/rgb-to-gray.pl
2473 <https://fastapi.metacpan.org/source/BKB/Image-PNG-
2474 Libpng-0.56/examples/rgb-to-gray.pl> in the distribution.)
2475 examples/grayface.png <https://fastapi.metacpan.org/source/BKB/Image-
2477 PNG-Libpng-0.56/examples/grayface.png> is included in the distribution.
2478 set_user_limits
2480 $png->set_user_limits ($width, $height);
2481 This enables a user to override libpng's restrictions to one million
2483 pixels in width and one million pixels in height for a PNG image.
2484 This function corresponds to "png_set_user_limits" in libpng
2486
2488 This section contains other functions which don't correspond to
2489 anything in libpng itself, but which have been added to the module for
2490 utility.
2491 any2gray8
2493 my $wpng = any2gray8 ("any.png");
2494 Convert any type of PNG file whatsoever into a bit-depth 8 grayscale
2496 image without an alpha channel (PNG_COLOR_TYPE_GRAY). The return value
2497 is a writing structure as made by "create_write_struct".
2498 Currently the "tRNS" chunk is ignored by this.
2500 By default the alpha channel is set to either the value of the "bKGD"
2502 chunk if there is one, or white if not. You can set another background
2503 using the option "bkgd":
2504 my $wpng = any2gray8 ('any.png', bkgd => {red => 255, green => 0, blue => 99});
2506 This will of course be ignored if any.png does not contain an alpha
2508 channel. RGB to gray conversion is done using "set_rgb_to_gray" with
2509 the default values.
2510 This function is not supported for versions of libpng earlier than
2512 1.6.14.
2513 color_type_channels
2515 my $channels = color_type_channels ('PNG_COLOR_TYPE_RGB_ALPHA');
2516 Returns the number of channels (the number of components of one pixel)
2518 of the specified color type.
2519 copy_row_pointers
2521 $png->copy_row_pointers ($row_pointers);
2522 This allows XS routines to directly set the value of the row pointers
2524 for the PNG image. The memory is copied, so whatever is in the row
2525 pointers can be freed immediately after calling this. However, the
2526 image data it points to is not copied, so this needs to be valid until
2527 the PNG is written.
2528 The Perl scalar $row_pointers should be set up something like the
2530 following (where "rp" is the C pointer):
2531 RETVAL = newSViv (PTR2IV (rp));
2533 It's extracted from the Perl scalar using
2535 rp = INT2PTR (png_byte **, SvIV (row_pointers));
2537 where row_pointers is the "SV *" corresponding to $row_pointers in the
2539 Perl script. See also "set_row_pointers" which does the same thing but
2540 takes ownership of the memory.
2541 get_chunk
2543 my $timechunk = $png->get_chunk ('tIME');
2544 Get the specified chunk. This produces a fatal error if asked for the
2546 "IDAT" (image data) chunk, use "get_rows" instead. Returns "undef" if
2547 asked for an unknown chunk name.
2548 This is used by pnginspect to get the valid chunks. See also
2550 "set_chunk".
2551 get_internals
2553 my ($png_struct, $png_info) = get_internals ($png);
2554 This function returns the "png_structp" and "png_infop" contained in
2556 $png. The return value is a list containing the "png_structp" as the
2557 first argument and the "png_infop" as the second argument, wrapped up
2558 as references to objects of type "Image::PNG::Libpng::png_struct" and
2559 "Image::PNG::Libpng::png_info".
2560 To access the values of the pointers, use something like this:
2562 void access_png_internals (png, info)
2564 SV * png;
2565 SV * info;
2566 PREINIT:
2567 png_struct * cpng;
2568 png_info * cinfo;
2569 CODE:
2570 cpng = INT2PTR (png_struct *, SvIV (png));
2571 cinfo = INT2PTR (png_info *, SvIV (info));
2572 An example exists in Image::PNG::Cairo.
2574 get_tRNS_palette
2576 $png->get_tRNS_palette ();
2577 This is not a libpng-equivalent function.
2579 image_data_diff
2581 my $diff = image_data_diff ('a.png', 'b.png');
2582 This returns the undefined value if the image data in a.png is the same
2584 as the image data in b.png. If the image data is different, it returns
2585 a readable text message describing the first difference found, for
2586 example the height is different, or row 0 of the image data is
2587 different, etc.
2588 This function is used in testing this module. See also "png_compare".
2590 libpng_supports
2592 if (libpng_supports ('iTXt')) {
2593 print "Your libpng supports international text.\n";
2594 }
2595 This function returns true or false depending on whether the version of
2597 libpng which this was compiled with supports or does not support a
2598 particular facility. For the most part, these are taken directly from
2599 the C macros of libpng.
2600 The possible arguments to "libpng_supports" are:
2602 16BIT
2604 ALIGNED_MEMORY
2605 ARM_NEON_API
2606 BENIGN_ERRORS
2607 BENIGN_READ_ERRORS
2608 BENIGN_WRITE_ERRORS
2609 bKGD
2610 Does the libpng support the "bKGD" chunk?
2611 BUILD_GRAYSCALE_PALETTE
2613 BUILTIN_BSWAP16
2614 CHECK_FOR_INVALID_INDEX
2615 cHRM
2616 Does the libpng support the "cHRM" chunk?
2617 cHRM_XYZ
2619 This is local to Image::PNG::Libpng and not a part of libpng
2620 itself.
2621 It was necessary to extend libpng because the conditional
2623 compilation macro for "set_cHRM_XYZ" and "get_cHRM_XYZ",
2624 "PNG_cHRM_SUPPORTED" is defined (true) for old libpngs which do not
2625 actually contain these functions.
2626 CHUNK_CACHE_MAX
2628 This is local to Image::PNG::Libpng and not a part of libpng
2629 itself.
2630 It was necessary to extend libpng because the conditional
2632 compilation macro for "set_chunk_cache_max" and
2633 "get_chunk_cache_max", "PNG_USER_LIMITS_SUPPORTED" is defined
2634 (true) for old libpngs which do not actually contain these
2635 functions.
2636 CHUNK_MALLOC_MAX
2638 This is local to Image::PNG::Libpng and not a part of libpng
2639 itself.
2640 The reasons for this are identical to those for "CHUNK_CACHE_MAX".
2642 COLORSPACE
2644 CONSOLE_IO
2645 CONVERT_tIME
2646 This is related to two deprecated functions,
2647 "png_convert_from_time_t" and "png_convert_from_struct_tm".
2648 CONVERT_tIME
2650 EASY_ACCESS
2651 ERROR_NUMBERS
2652 ERROR_TEXT
2653 eXIf
2654 Does the libpng support the "eXIf" chunk?
2655 FIXED_POINT
2657 FIXED_POINT_MACRO
2658 FLOATING_ARITHMETIC
2659 FLOATING_POINT
2660 FORMAT_AFIRST
2661 FORMAT_BGR
2662 gAMA
2663 Does the libpng support the "gAMA" chunk?
2664 GAMMA
2666 GET_PALETTE_MAX
2667 Does your libpng support "get_palette_max"?
2668 HANDLE_AS_UNKNOWN
2670 HANDLE_AS_UNKNOWN
2671 hIST
2672 Does the libpng support the "hIST" chunk?
2673 iCCP
2675 Does the libpng support the "iCCP" chunk?
2676 INCH_CONVERSIONS
2678 INFO_IMAGE
2679 IO_STATE
2680 iTXt
2681 Does the libpng support international text?
2682 MIPS_MSA_API
2684 MNG_FEATURES
2685 oFFs
2686 Does the libpng support the "oFFs" chunk?
2687 pCAL
2689 Does the libpng support the "pCAL" extension?
2690 PEDANTIC_WARNINGS
2692 pHYs
2693 Does the libpng support the "pHYs" chunk?
2694 POINTER_INDEXING
2696 POWERPC_VSX_API
2697 PROGRESSIVE_READ
2698 READ
2699 Can libpng read PNGs?
2700 READ_16_TO_8
2702 READ_ALPHA_MODE
2703 See "set_alpha_mode".
2704 READ_BACKGROUND
2706 See "set_background".
2707 READ_BGR
2709 See "set_bgr".
2710 READ_COMPOSITE_NODIV
2712 READ_COMPRESSED_TEXT
2713 READ_EXPAND
2714 READ_EXPAND_16
2715 READ_FILLER
2716 READ_GAMMA
2717 See "set_gamma".
2718 READ_GRAY_TO_RGB
2720 READ_INTERLACING
2721 READ_INT_FUNCTIONS
2722 READ_INVERT
2723 READ_INVERT_ALPHA
2724 READ_OPT_PLTE
2725 READ_PACK
2726 READ_PACKSWAP
2727 READ_QUANTIZE
2728 READ_RGB_TO_GRAY
2729 READ_SCALE_16_TO_8
2730 READ_SHIFT
2731 READ_STRIP_16_TO_8
2732 READ_STRIP_ALPHA
2733 READ_SWAP
2734 READ_SWAP_ALPHA
2735 READ_tEXt
2736 READ_TRANSFORMS
2737 READ_USER_TRANSFORM
2738 READ_zTXt
2739 SAVE_INT_32
2740 SAVE_UNKNOWN_CHUNKS
2741 sBIT
2742 Does the libpng support the "sBIT" chunk?
2743 sCAL
2745 Does the libpng support the "sCAL" extension? This actually tests
2746 for the presence of the "get_sCAL_s"/"set_sCAL_s" functions, so its
2747 behaviour is dependent on other factors for versions 1.2 and 1.4 of
2748 libpng.
2749 SEQUENTIAL_READ
2751 SETJMP
2752 SET_OPTION
2753 SET_UNKNOWN_CHUNKS
2754 SET_USER_LIMITS
2755 SIMPLIFIED_READ
2756 SIMPLIFIED_READ_AFIRST
2757 SIMPLIFIED_WRITE
2758 SIMPLIFIED_WRITE_AFIRST
2759 SIMPLIFIED_WRITE_BGR
2760 SIMPLIFIED_WRITE_STDIO
2761 sPLT
2762 Does the libpng support "sPLT" chunks?
2763 sRGB
2765 Does the libpng support the "sRGB" chunk?
2766 STDIO
2768 STORE_UNKNOWN_CHUNKS
2769 TEXT
2770 Does the libpng support text?
2771 tEXt
2773 Does the libpng support tEXt chunks?
2774 tIME
2776 Does the libpng support the "tIME" chunk?
2777 TIME_RFC1123
2779 tRNS
2780 Does the libpng support the "tRNS" chunk?
2781 UNKNOWN_CHUNKS
2783 Does the libpng support unknown chunks (see "Private chunks")?
2784 USER_CHUNKS
2786 USER_LIMITS
2787 Does the libpng support "set_user_limits" and the related functions
2788 "get_user_width_max", and "get_user_height_max"?
2789 USER_LIMITS
2791 USER_MEM
2792 USER_TRANSFORM_INFO
2793 USER_TRANSFORM_PTR
2794 WARNINGS
2795 WRITE
2796 Can libpng write pngs?
2797 WRITE_BGR
2799 WRITE_COMPRESSED_TEXT
2800 WRITE_CUSTOMIZE_COMPRESSION
2801 Does the libpng support "set_compression_level" and similar
2802 functions?
2803 âðĪŠâ It's not very clear that this returns a useful value, since
2805 "set_compression_level" seems to be in libpngs from at least as far
2806 back as 1.5.1, and yet this macro was only added to libpng in
2807 version 1.6.13.
2808 WRITE_CUSTOMIZE_ZTXT_COMPRESSION
2810 Does the libpng support "set_text_compression_level" and similar
2811 functions?
2812 WRITE_FILLER
2814 WRITE_FILTER
2815 WRITE_FLUSH
2816 WRITE_FLUSH_AFTER_IEND
2817 WRITE_INTERLACING
2818 WRITE_INT_FUNCTIONS
2819 WRITE_INVERT
2820 WRITE_INVERT_ALPHA
2821 WRITE_OPTIMIZE_CMF
2822 WRITE_PACK
2823 WRITE_PACKSWAP
2824 WRITE_SHIFT
2825 WRITE_SWAP
2826 WRITE_SWAP_ALPHA
2827 WRITE_TRANSFORMS
2828 WRITE_USER_TRANSFORM
2829 WRITE_WEIGHTED_FILTER
2830 zTXt
2831 Does the libpng support "zTXt" chunks?
2832 png_compare
2834 if (png_compare ('a.png', 'b.png') == 0) {
2835 print "The PNGs are the same.\n";
2836 }
2837 This compares the image data in two PNGs and returns 0 if they contain
2839 exactly the same image data, or 1 if they contain different image data.
2840 For a more detailed comparison, see "image_data_diff". This does not
2841 compare to see if the PNG files "look like" each other, but whether
2842 each pixel contains exactly the same values. Please see Image::Similar
2843 for a looser comparison of images.
2844 This uses the "expand" transform of libpng to read both the images, so
2846 it is able to compare images of different color types. It compares the
2847 alpha values as well as the color pixels. See "Saving bandwidth" for an
2848 example of comparing an RGB and a grayscale image.
2849 read_struct
2851 if ($png->read_struct ()) {
2852 warn "Can't write this, use copy_png to copy it";
2853 }
2854 This returns a true value if $png was created with "create_read_struct"
2856 or allied functions like "read_from_scalar", and a false value if $png
2857 was created with "create_write_struct" or allied functions like
2858 "copy_png".
2859 set_chunk
2861 $png->set_chunk ('tIME', $timechunk);
2862 Set the specified chunk. This produces a fatal error if given an "IDAT"
2864 (image data) chunk, use "set_rows" instead. This produces a fatal error
2865 if given an unknown chunk name.
2866 The first argument is the chunk name and then the second argument is a
2868 scalar containing whatever the chunk requires, for example a hash
2869 reference for the "tIME" chunk as described under "set_tIME" and
2870 "get_tIME".
2871 This is essentially a convenience function for the benefit of
2873 "copy_png" which, together with "get_valid", enables the PNG chunks to
2874 be copied in a loop rather than one-by-one.
2875 set_image_data
2877 $png->set_image_data ($image_data);
2878 Set the internal image data pointer to $image_data. $image_data should
2880 contain a pointer to memory stored as an "SvIV" allocated with "Newx"
2881 or a similar function. This transfers ownership of the memory to $png,
2882 which will free it with "Safefree" when $png is destroyed. Calling this
2883 function with any value does not actually change the content of the PNG
2884 image itself.
2885 set_row_pointers
2887 $png->set_row_pointers ($row_pointers);
2888 This sets the rows of the PNG image to $row_pointers using
2890 "png_set_rows". $row_pointers must contain a pointer to memory stored
2891 as an SvIV allocated with a Perl memory allocator like "Newx" or a
2892 similar function. This also transfers ownership of the memory to $png,
2893 which will free it with "Safefree" when $png is destroyed. See also
2894 "copy_row_pointers", which does the same thing except for the freeing
2895 of the memory.
2896 split_alpha
2898 my $split = $png->split_alpha ();
2899 my $alpha = $split->{alpha};
2900 my $color = $split->{data};
2901 Split the alpha channel away from the other data. This only works for
2903 images with color types "PNG_COLOR_TYPE_RGB_ALPHA" and
2904 "PNG_COLOR_TYPE_GRAY_ALPHA". This is not part of the libpng API. This
2905 function was added to this module to assist the author of PDF::Builder
2906 due to problems with very slow access to PNG images using Perl.
2907 To remove the alpha channel from an image, use "set_background". See
2909 "Setting the background" for an example. You can also use the transform
2910 "PNG_TRANSFORM_STRIP_ALPHA" in "read_png_file", or "set_strip_alpha",
2911 but this may leave spurious pixel values in transparent parts of the
2912 image.
2913
2915 Nothing is exported by default, but all the functions in this module,
2916 including the object methods, can be exported on request. The export
2917 tag 'all' exports everything in the module:
2918 use Image::PNG::Libpng ':all';
2920 This includes all the methods, which can then be used with the $png
2922 argument as the first argument.
2923
2925 The functions in Image::PNG::Libpng are closely based on those of
2926 libpng, with the following differences.
2927 No info structure
2929 This module does not use the "info" structure of libpng. Almost all
2930 libpng functions require two initial arguments, a "png_structp" and a
2931 "png_infop". However, in Image::PNG::Libpng, both the "png" and the
2932 "info" are contained in the object. People who need access to the
2933 internals of an "Image::PNG::Libpng" object (C programmers or XS
2934 programmers) can use "get_internals" to access them.
2935 This module does not support the "end info" structure of PNGs when
2937 writing, although these are handled when reading.
2938 Unused arguments omitted
2940 This module eliminates unevaluated arguments of libpng. For example,
2941 libpng requires the user to pass a pointer to a "png_struct" to call
2942 the libpng version number function, (see "get_libpng_ver"), but it
2943 actually ignores this structure. There are many similar instances of
2944 unevaluated arguments, which have all been eliminated from this module.
2945 If you are interested in exactly which libpng arguments are omitted,
2947 you can find each instance in the file "perl-libpng.c" in the top
2948 directory of the distribution
2949 <https://fastapi.metacpan.org/source/BKB/Image-PNG-Libpng-0.56/perl-
2950 libpng.c> in the macro "UNUSED_ZERO_ARG".
2951 Useless functions omitted
2953 The functions from libpng which don't do anything have been omitted
2954 from this module.
2955 Function return values are used to return values
2957 libpng is very inconsistent in its calling conventions. Some functions
2958 return results using references, and some return results using the
2959 function's return value. For example "png_get_rows" (see "get_rows")
2960 uses the return value of the function to return an array of pointers,
2961 but "png_get_PLTE" (see "get_PLTE") uses a pointer reference to return
2962 an array of pointers, and the return value to indicate errors.
2963 Image::PNG::Libpng uses only the return value. Errors and non-existence
2965 are indicated by a return value of the undefined value.
2966 Further to this, libpng's error handling is also very inconsistent.
2968 Some functions use the return value to indicate errors, and some of the
2969 functions don't indicate errors at all, but just fail silently. Even
2970 more inconsistently, some of the functions which use the return value
2971 to indicate an error use a non-zero value, and some use a zero value,
2972 to indicate an error.
2973 No destructors
2975 Freeing the memory allocated by "create_read_struct" and
2976 "create_write_struct" is automatically handled by Perl.
2977 Older versions of this module (pre-0.18) had functions called
2979 "destroy_read_struct" and "destroy_write_struct" corresponding to the
2980 functions with similar names in libpng. From version 0.18, these
2981 functions still exist, but they no longer do anything. The memory
2982 freeing is now handled by Perl automatically.
2983 Other unimplemented parts of libpng
2985 Memory management functions
2986 The management of memory for libpng objects is handled
2987 automatically by this module, and so it does not offer an interface
2988 to "png_malloc" and "png_free" or other libpng memory handling
2989 functions.
2990 Error handling functions
2992 This module does not offer an interface to "png_error" and
2993 "png_get_error_ptr" or any of the other error handling functions of
2994 libpng. It redirects the error and warning handlers to Perl's error
2995 stream.
2996 Input/output manipulation functions
2998 This module does not offer a direct interface to "png_set_write_fn"
2999 and "png_set_read_fn". However, it is possible to use their
3000 functionality to access Perl data via "read_from_scalar" and
3001 "write_to_scalar".
3002 Fixed point functions
3004 There is currently no support for the PNG fixed point functions in
3005 this Perl module, the functions with suffix "_fixed".
3006 List of unsupported functions
3008 The following functions from the libpng API are unsupported by this
3009 module.
3010 png_benign_error
3012 ð See "Error handling functions".
3013 png_build_grayscale_palette
3015 âðĪŠâ Undocumented function, but it is part of the public API. See
3016 <https://github.com/glennrp/libpng/issues/353>.
3017 This function builds an evenly-spaced grayscale palette at a
3019 specified bit depth into a user-supplied array. It is not used
3020 elsewhere in libpng.
3021 png_chunk_benign_error
3023 ð See "Error handling functions".
3024 png_chunk_warning
3026 ð See "Error handling functions".
3027 png_convert_from_struct_tm
3029 ð Deprecated in libpng. This function related to the "tIME" chunk
3030 is deprecated in libpng 1.7.
3031 png_convert_from_time_t
3033 ð Deprecated in libpng. This function related to the "tIME" chunk
3034 is deprecated in libpng 1.7.
3035 png_convert_to_rfc1123
3037 ð Deprecated in libpng. This function related to the "tIME" chunk
3038 is deprecated in libpng 1.7.
3039 png_convert_to_rfc1123_buffer
3041 ððŠ This function was deliberately omitted from this module
3042 because it doesn't seem useful for Perl programmers.
3043 This function is related to the "tIME" chunk; it seems fairly
3045 superfluous with the many other ways to manipulate time strings
3046 already in Perl.
3047 png_data_freer
3049 ð See "Memory management functions".
3050 png_free
3052 ð See "Memory management functions".
3053 png_free_data
3055 ð See "Memory management functions".
3056 png_get_cHRM_XYZ_fixed
3058 ð See "Fixed point functions".
3059 png_get_cHRM_fixed
3061 ð See "Fixed point functions".
3062 png_get_compression_type
3064 ððĪĄ See "Useless functions omitted". Useless function which
3065 returns 0 since there is only one type of compression.
3066 png_get_copyright
3068 ððŠ This function was deliberately omitted from this module
3069 because it doesn't seem useful for Perl programmers.
3070 This function gives you the copyright string for libpng.
3072 png_get_current_pass_number
3074 png_get_current_row_number
3075 png_get_error_ptr
3076 ð See "Error handling functions".
3077 png_get_filter_type
3079 ððĪĄ See "Useless functions omitted". This function returns the
3080 value of the unused field "filter_type" in the PNG header, which is
3081 always 0. See "Unused arguments omitted".
3082 png_get_gAMA_fixed
3084 ð See "Fixed point functions".
3085 png_get_header_ver
3087 This function was omitted from this module because it merely
3088 duplicates another function.
3089 Identical to "get_libpng_ver".
3091 png_get_header_version
3093 This function was omitted from this module because it merely
3094 duplicates another function.
3095 Identical to "get_libpng_ver".
3097 png_get_io_chunk_type
3099 png_get_io_ptr
3100 png_get_io_state
3101 png_get_mem_ptr
3102 png_get_pHYs_dpi
3103 png_get_pixel_aspect_ratio
3104 png_get_pixel_aspect_ratio_fixed
3105 ð See "Fixed point functions".
3106 png_get_pixels_per_inch
3108 png_get_pixels_per_meter
3109 png_get_progressive_ptr
3110 Incremental reading of PNGs is not handled yet.
3111 png_get_sCAL_fixed
3113 ð See "Fixed point functions".
3114 png_get_signature
3116 ððŠ This function was deliberately omitted from this module
3117 because it doesn't seem useful for Perl programmers.
3118 Returns the PNG signature of a PNG you read in.
3120 png_get_uint_31
3122 ððŠ This function was deliberately omitted from this module
3123 because it doesn't seem useful for Perl programmers.
3124 This produces an error if the unsigned integer argument is too big
3126 for a 31 bit number.
3127 png_get_user_chunk_ptr
3129 png_get_user_height_max
3130 png_get_user_transform_ptr
3131 png_get_x_offset_inches
3132 png_get_x_offset_inches_fixed
3133 ð See "Fixed point functions".
3134 png_get_x_offset_microns
3136 png_get_x_offset_pixels
3137 Duplicates "get_oFFs".
3138 png_get_x_pixels_per_inch
3140 png_get_x_pixels_per_meter
3141 Duplicates "get_oFFs".
3142 png_get_y_offset_inches
3144 png_get_y_offset_inches_fixed
3145 ð See "Fixed point functions".
3146 png_get_y_offset_microns
3148 png_get_y_offset_pixels
3149 Duplicates "get_oFFs".
3150 png_get_y_pixels_per_inch
3152 png_get_y_pixels_per_meter
3153 Duplicates "get_oFFs".
3154 png_handle_as_unknown
3156 png_image_begin_read_from_file
3157 png_image_begin_read_from_stdio
3158 png_image_finish_read
3159 png_image_free
3160 ð See "Memory management functions".
3161 png_image_write_to_file
3163 png_image_write_to_memory
3164 ð See "Memory management functions".
3165 png_image_write_to_stdio
3167 png_process_data
3168 png_process_data_pause
3169 png_process_data_skip
3170 png_progressive_combine_row
3171 png_read_row
3172 png_read_rows
3173 png_reset_zstream
3174 ð Deprecated in libpng. Resets the zstream of the zlib instance
3175 used for the image data.
3176 png_save_int_32
3178 ððŠ This function was deliberately omitted from this module
3179 because it doesn't seem useful for Perl programmers.
3180 Writes a 32 bit signed number into an octet buffer. Perl
3182 programmers will probably use "pack" for this.
3183 png_save_uint_16
3185 ððŠ This function was deliberately omitted from this module
3186 because it doesn't seem useful for Perl programmers.
3187 Writes a 16 bit number into an octet buffer. Perl programmers will
3189 probably use "pack" for this.
3190 png_save_uint_32
3192 ððŠ This function was deliberately omitted from this module
3193 because it doesn't seem useful for Perl programmers.
3194 Writes a 32 bit unsigned number into an octet buffer. Perl
3196 programmers will probably use "pack" for this.
3197 png_set_alpha_mode_fixed
3199 ð See "Fixed point functions".
3200 png_set_background_fixed
3202 ð See "Fixed point functions".
3203 png_set_benign_errors
3205 ð See "Error handling functions".
3206 png_set_cHRM_XYZ_fixed
3208 ð See "Fixed point functions".
3209 png_set_cHRM_fixed
3211 ð See "Fixed point functions".
3212 png_set_check_for_invalid_index
3214 png_set_compression_method
3215 ððĪĄ See "Useless functions omitted". This function in libpng
3216 corresponds to the unused "method" parameter of zlib functions like
3217 "deflateInit2". See "zlib documentation". The libpng function just
3218 produces a warning if the user sets the value to anything but 8,
3219 the value of the macro "Z_DEFLATED", and then lets zlib produce an
3220 error.
3221 png_set_crc_action
3223 ð See "Error handling functions".
3224 png_set_error_fn
3226 ð See "Error handling functions".
3227 png_set_filter_heuristics
3229 ð Deprecated in libpng.
3230 png_set_filter_heuristics_fixed
3232 ð See "Fixed point functions".
3233 png_set_flush
3235 png_set_gAMA_fixed
3236 ð See "Fixed point functions".
3237 png_set_gamma_fixed
3239 ð See "Fixed point functions".
3240 png_set_interlace_handling
3242 Incremental writing is not handled.
3243 png_set_invalid
3245 ð See "Memory management functions".
3246 png_set_longjmp_fn
3248 âðĪŠâ Undocumented function, but it is part of the public API.
3249 png_set_mem_fn
3251 ð See "Memory management functions".
3252 png_set_option
3254 png_set_progressive_read_fn
3255 png_set_read_status_fn
3256 png_set_read_user_chunk_fn
3257 png_set_read_user_transform_fn
3258 png_set_sCAL_fixed
3259 ð See "Fixed point functions".
3260 png_set_sRGB_gAMA_and_cHRM
3262 png_set_shift
3263 png_set_sig_bytes
3264 ððŠ This function was deliberately omitted from this module
3265 because it doesn't seem useful for Perl programmers.
3266 png_set_strip_error_numbers
3268 ððĪĄ See "Useless functions omitted". According to the libpng
3269 manual, "we never got around to actually numbering the error
3270 messages", so I assume this is not very useful.
3271 png_set_text_compression_method
3273 ððĪĄ See "Useless functions omitted". Unsupported for the same
3274 reasons as "png_set_compression_method".
3275 png_set_unknown_chunk_location
3277 This is related to some kind of bug in version 1.5 and previous of
3278 libpng.
3279 png_set_user_transform_info
3281 png_set_write_status_fn
3282 ð See "Error handling functions".
3283 png_set_write_user_transform_fn
3285 png_start_read_image
3286 png_write_chunk
3287 png_write_chunk_data
3288 png_write_chunk_end
3289 png_write_chunk_start
3290 png_write_flush
3291 png_write_info_before_PLTE
3292 png_write_row
3293 png_write_rows
3294 png_write_sig
3295 This is an exhaustive list of unsupported libpng API functions,
3297 extracted from the libpng source code using util/api.pl in this
3298 module's repository.
3299 Conditional compilation and old libpng versions
3301 It is possible to compile a version of the libpng library without
3302 support for various things. For example, a libpng without support for
3303 text chunks may be created by undefining the C macro
3304 "PNG_TEXT_SUPPORTED". This module supports the conditional compilation
3305 choices which we're aware of, but if you encounter problems using this
3306 module because of a conditionally-compiled libpng, then let us know and
3307 we'll add the necessary facility.
3308 Currently we test this module against vanilla libpng versions 1.2.59,
3310 1.4.22, 1.5.30, and 1.6.37 before releases. There doesn't seem to have
3311 been a 1.3 or a 1.1 version of libpng. See
3312 <http://www.libpng.org/pub/png/pngnews.html>. Versions 1.0 and earlier
3313 of libpng are not tested against.
3314 The following issues with older libpng versions may affect users of
3316 this module:
3317 cHRM chunk
3319 The "get_cHRM_XYZ" and "set_cHRM_XYZ" functions for the "cHRM" chunk
3321 are not present in pre-1.5.5 versions of libpng, but the conditional
3322 compilation macro of libpng for these newer functions is the same as
3323 for "get_cHRM" and "set_cHRM" functions, which are present on older
3324 versions of libpng. Because of this, this module includes its own
3325 protection macro, accessible via "libpng_supports" as "cHRM_XYZ".
3326 These functions are disabled for libpng versions earlier than 1.5.5.
3327 chunk_cache_max
3329 The functions "set_chunk_cache_max" and "get_chunk_cache_max" are not
3331 protected by a libpng macro, so this module includes its own protection
3332 macro, accessible via "libpng_supports" as "CHUNK_CACHE_MAX". These
3333 functions are disabled for libpng versions earlier than 1.4.0.
3334 Compression level
3336 Versions of libpng up to 1.5 behave erratically when
3338 "set_compression_level" or other "set_compression_*" functions are used
3339 to alter the compression of the image data. Testing of compression-
3340 related functions is disabled by this Perl module for pre-1.6.13
3341 versions of libpng.
3342 sCAL chunk
3344 Support for the sCAL chunk is disabled within this module for pre-1.6
3346 versions of libpng.
3347 Text chunk handling
3349 Versions of libpng up to 1.6.3 produce erratic results with "iTXt"
3351 (international text) chunks. Testing of text-related chunks is disabled
3352 by this Perl module for pre-1.6.13 versions of libpng.
3353 Not all constants are available
3355 Some of the libpng constants are defined in pnglibconf.h or pngconf.h
3356 but Image::PNG::Const only looks at png.h to make its constants.
3357 Because of this, some constant values like "PNG_Z_DEFAULT_COMPRESSION"
3358 aren't currently available in Image::PNG::Const. This probably should
3359 be fixed to extract the constants from the other files in a future
3360 version.
3361
3363 A standalone script, pnginspect, is installed with the distribution. It
3364 prints out the contents of the chunks of the PNG file on the command
3365 line.
3366
3368 The PNG specification
3369 The PNG specification <http://www.w3.org/TR/PNG/> (link to W3
3370 consortium) explains the details of the PNG format.
3371 PNG The Definitive Guide by Greg Roelofs
3373 The book "PNG - The Definitive Guide" by Greg Roelofs, published in
3375 1999 by O'Reilly is available online at <http://www.faqs.org/docs/png/>
3376 or <http://www.libpng.org/pub/png/book/>.
3377 The libpng documentation
3379 Official documentation
3380 The starting point is the plain text libpng manual at
3381 <http://libpng.org/pub/png/libpng-manual.txt> and the manual page
3382 libpng.3, which you can read using "man 3 libpng".
3383 âðĪŠâ The documentation which comes with libpng is rather sketchy.
3385 See "Differences from libpng". It doesn't contain full
3386 specifications (prototypes, return values) for all of the functions
3387 in the library. For programming in C using libpng, look at the
3388 header file png.h. In some cases, you need to look at the source
3389 code of the library.
3390 Other documentation
3392 There is a collection of function definitions under the title
3393 "Interface Definitions for libpng12" at
3394 <https://refspecs.linuxbase.org/LSB_4.0.0/LSB-Desktop-generic/LSB-Desktop-generic/libpng12man.html>
3395 as part of the "Linux Standard Base Desktop Specification". These
3396 contain extensive information on the prototypes and return values
3397 for the libpng routines, something which is often only available
3398 elsewhere by actually looking at the libpng source code. These
3399 pages are usually the first hits on search engines if you search
3400 for a function name in libpng.
3401 zlib documentation
3403 See <https://zlib.net/manual.html> for the zlib documentation.
3404 Other Perl modules on CPAN
3406 These other modules may also be useful.
3407 Alien::PNG
3409 Alien::PNG claims to be a way of "building, finding and using PNG
3410 binaries". It may help in installing libpng. We didn't use it as a
3411 dependency for this module because it seems not to work in batch
3412 mode, but stop and prompt the user. We're interested in hearing
3413 feedback from users whether this works or not on various platforms.
3414 Imager
3416 Imager, Imager::Files and "Imager::Files::PNG" contain support for
3417 reading and writing PNGs via libpng, as well as support for reading
3418 and writing various other kinds of image files, changing the
3419 images, converting, and more.
3420 Image::ExifTool
3422 Image::ExifTool is a pure Perl (doesn't require a C compiler)
3423 solution for accessing the text segments of images. It supports PNG
3424 text segments.
3425 Image::Info
3427 Image::Info gets information out of images. It supports PNG and is
3428 written in pure Perl, so it doesn't require a C compiler. As well
3429 as basics such as height, width, and colour type, it can get text
3430 chunks, modification time, palette, gamma (gAMA chunk), resolution
3431 (pHYs chunk), and significant bits (sBIT chunk). At the time of
3432 writing (version 1.31) it doesn't support other chunks.
3433 Image::PNG::Rewriter
3435 Image::PNG::Rewriter is a utility for unpacking and recompressing
3436 the IDAT (image data) part of a PNG image. The main purpose seems
3437 to be to recompress the image data with the module author's other
3438 module Compress::Deflate7. At the time of writing, that only works
3439 with Perl versions 5.12 or later.
3440 Image::Pngslimmer
3442 Image::Pngslimmer reduces the size of dynamically created PNG
3443 images. It's very, very slow at reading PNG data, but seems to work
3444 OK.
3445 Image::PNG::Write::BW
3447 Image::PNG::Write::BW writes black and white PNGs from strings.
3448 Image::Size
3450 If you only need to read the sizes of images, Image::Size works
3451 with PNG and other image formats.
3452
3454 Ben Bullock, <bkb@cpan.org>
3455
3457 This package and associated files are copyright (C) 2011-2020 Ben
3458 Bullock.
3459 You can use, copy, modify and redistribute this package and associated
3461 files under the Perl Artistic Licence or the GNU General Public
3462 Licence.
3463perl v5.32.1 2021-01-27 Image::PNG::Libpng(3)
