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.57/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.57/examples/synopsis-easy.pl> in the distribution.)
55
57 This document describes Image::PNG::Libpng version 0.57, corresponding
58 to git commit unknown <https://github.com/benkasminbullock/image-png-
59 libpng/commit/unknown> at unknown.
60 Unless otherwise qualified, comments in this document on the libpng
62 source code and documentation refer to libpng version 1.6.37. Libpng is
63 not bundled with this distribution, so your installed version may vary.
64
66 Image::PNG::Libpng is a Perl library for accessing the contents of PNG
67 (Portable Network Graphics) images. Image::PNG::Libpng enables Perl to
68 use the "libpng" library to read and write files in PNG format.
69 Image::PNG::Libpng does not contain the libpng library. The libpng
70 library must be installed on your computer prior to installing
71 Image::PNG::Libpng.
72 Image::PNG::Libpng consists of Perl subroutines which mirror the C
74 functions in libpng, plus helper subroutines to make it easier to read
75 and write PNG data in Perl.
76 For those familiar with libpng, the section "Differences from libpng"
78 explains the differences with libpng.
79
81 The functions in the module are gathered into the following categories:
82 "Simple input and output", which describes some convenience functions,
83 "Libpng-style input and output", which describes functions which
84 closely mirror libpng, "The image header", which describes functions
85 for reading and writing the meta-information about PNG images, "Image
86 data", which describes functions for accessing the image data itself,
87 "Text chunks", "Private chunks", "Library version functions",
88 "Compression and filtering", "Other chunks", "Libpng transformations",
89 "Other libpng functions", functions from libpng which don't fit
90 elsewhere, and "Other functions", which are functions specific to this
91 module.
92
94 These convenience functions combine common operations. They are not
95 part of the original libpng API.
96 copy_png
98 my $outpng = $png->copy_png ();
99 Copy a PNG from a read to a write structure. This function bridges two
101 kinds of object, "read a png" objects created by "create_read_struct"
102 and "write a png" objects created by "create_write_struct". This
103 function copies all the valid chunks from a read structure to a write
104 structure.
105 The following example demonstrates copying a PNG.
107 use utf8;
109 use FindBin '$Bin';
110 use Image::PNG::Libpng qw(read_png_file write_png_file) ;
111 my $pngin = read_png_file ("$Bin/../t/tantei-san.png");
112 my $pngout = $pngin->copy_png ();
113 $pngout->set_text ([{key => 'Name', text => 'Shunsaku Kudo'}]);
114 # $pngout->write_png_file ('copy.png');
115 (This example is included as examples/copy-png.pl
117 <https://fastapi.metacpan.org/source/BKB/Image-PNG-
118 Libpng-0.57/examples/copy-png.pl> in the distribution.)
119 create_reader
121 my $png = create_reader ('file.png');
122 $png->read_png ();
123 This combines "create_read_struct", "open", and "init_io" on the
125 specified file name but does not read the file in. This is for the case
126 that the user wants to apply some kind of transformation.
127 Setting the background
129 In the following example, the user sets the background with
131 "set_background" to replace the alpha channel.
132 use utf8;
134 use FindBin '$Bin';
135 use Image::PNG::Libpng ':all';
136 use Image::PNG::Const ':all';
137 my $file = "$Bin/luv.png";
138 my %color = (red => 0xC0, green => 0xFF, blue => 0xFF);
139 my $png = create_reader ($file);
140 $png->set_background (\%color, PNG_BACKGROUND_GAMMA_SCREEN, 0);
141 $png->read_png ();
142 my $wpng = copy_png ($png);
143 $wpng->write_png_file ("$Bin/set-background.png");
144 (This example is included as examples/set-background.pl
146 <https://fastapi.metacpan.org/source/BKB/Image-PNG-
147 Libpng-0.57/examples/set-background.pl> in the distribution.)
148 examples/luv.png <https://fastapi.metacpan.org/source/BKB/Image-PNG-
150 Libpng-0.57/examples/luv.png> is included in the distribution.
151 examples/set-background.png
153 <https://fastapi.metacpan.org/source/BKB/Image-PNG-
154 Libpng-0.57/examples/set-background.png> is included in the
155 distribution.
156 This function was added to the module in version 0.53.
158 create_writer
160 my $png = create_writer ('file.png');
161 $png->set_IHDR (\%ihdr);
162 $png->set_rows (\@rows);
163 $png->write_png ();
164 This combines "create_write_struct", "open", and "init_io" on the
166 specified file name but does not read the file in. This is for the case
167 that the user wants to apply some kind of transformation before
168 writing.
169 This function was added to the module in version 0.53.
171 read_from_scalar
173 my $png = read_from_scalar ($string);
174 This creates an image structure $png from the contents of a Perl scalar
176 variable $string containing PNG image data, for example data read from
177 a file, or data obtained from a web page. The first argument, $png, is
178 a PNG structure created with "create_read_struct". It reads in all the
179 data from the structure on being called.
180 This is useful when image data is stored in a Perl scalar. For example
182 use Image::PNG::Libpng 'read_from_scalar';
184 use LWP::Simple;
185 use JSON::Create;
186 my $image_data = get 'http://libpng.org/pub/png/img_png/libpng-88x31.png';
187 # Now $image_data contains the PNG file
188 my $png = read_from_scalar ($image_data);
189 # Now $png contains the PNG information from the image.
190 # Get the header.
191 my $header = $png->get_IHDR ();
192 my $jc = JSON::Create->new (indent => 1, sort => 1);
193 print $jc->run ($header);
194 (This example is included as examples/get-www-png.pl
196 <https://fastapi.metacpan.org/source/BKB/Image-PNG-
197 Libpng-0.57/examples/get-www-png.pl> in the distribution.)
198 The output looks like this:
200 {
202 "bit_depth":4,
203 "color_type":3,
204 "height":31,
205 "interlace_method":0,
206 "width":88
207 }
208 See also "Input/output manipulation functions".
210 read_png_file
212 my $png = read_png_file ('q.png');
213 Open q.png and read its contents into $png.
215 This combines "create_read_struct", "open", "init_io", and "read_png".
217 The return value is the same as that of "create_read_struct" with the
218 entire PNG image already read in.
219 The optional argument to "read_png" can be specified using an optional
221 "transforms" argument:
222 my $png = read_png_file ('file.png', transforms => PNG_TRANSFORM_EXPAND);
224 "croak" in Carp is used to signal errors opening or closing the file.
226 set_transforms
228 $png->set_transforms (PNG_TRANSFORM_BGR);
229 Set transforms for reading and writing. This is the same as the
231 optional argument to "read_png" or "write_png". If both this and the
232 optional argument are given, the optional argument overrides what is
233 set here.
234 write_png_file
236 $png->write_png_file ('nice.png');
237 This combines open, "init_io", and "write_png" to write an entire PNG
239 image out to the file name specified by the argument. $png must be the
240 object created by "create_write_struct", so "read_png_file" followed by
241 a call to this does not work. See "copy_png" if you need to do that
242 kind of operation.
243 The optional argument to "write_png" can be specified using
245 "set_transforms".
246 "croak" in Carp is used to signal errors opening or closing the file.
248 write_to_scalar
250 my $image_data = $png->write_to_scalar ();
251 This writes the PNG image data in $png into a Perl scalar. The first
253 argument, $png, is a writeable PNG structure created with
254 "create_write_struct". The return value of the subroutine is the Perl
255 scalar containing the image data.
256 So, for example,
258 # This CGI script prints a PNG in a random colour.
260 use Image::PNG::Libpng ':all';
262 use Image::PNG::Const ':all';
263 my $png = create_write_struct ();
264 my $size = 100;
265 $png->set_IHDR ({height => $size, width => $size, bit_depth => 8,
266 color_type => PNG_COLOR_TYPE_RGB});
267 my $bytes = pack "CCC", randcol (), randcol (), randcol ();
268 my @rows = ($bytes x $size) x $size;
269 $png->set_rows (\@rows);
270 my $img = $png->write_to_scalar ();
271 binmode STDOUT;
272 print "Content-Type:image/png\r\n\r\n$img";
273 exit;
274 sub randcol
275 {
276 return int (rand () * 0x100);
277 }
278 (This example is included as examples/png-cgi.pl
280 <https://fastapi.metacpan.org/source/BKB/Image-PNG-
281 Libpng-0.57/examples/png-cgi.pl> in the distribution.)
282 See also "Input/output manipulation functions".
284 The optional argument to "write_png" can be specified using
286 "set_transforms".
287
289 There are two different "new"-like functions, depending on whether you
290 want to read or write a PNG, "create_read_struct" and
291 "create_write_struct". These are based on the libpng API. Input uses
292 "open" plus "init_io" followed by "read_png" or "write_png".
293 Examples
295 A self-pixellating program
296 This example demonstrates writing a monochrome PNG by creating a write
298 structure with "create_write_struct", opening a filehandle to write it,
299 associating the filehandle with the PNG structure with "init_io", then
300 using the functions "write_info", "write_image", and then "write_end"
301 to actually write the PNG data to the file.
302 use utf8;
304 use FindBin '$Bin';
305 use Image::PNG::Libpng ':all';
306 use Image::PNG::Const ':all';
307 my $outfile = "$Bin/mono.png";
308 my ($height, $width, $rows) = pixelate (__FILE__, 5);
309 my $png = create_write_struct ();
310 open my $out, ">:raw", $outfile or die $!;
311 $png->init_io ($out);
312 $png->set_IHDR ({height => $height, width => $width, bit_depth => 1,
313 color_type => PNG_COLOR_TYPE_GRAY});
314 $png->set_text ([{key => 'silly', text => 'finely-tuned breakfast cereal',}]);
315 $png->set_tIME ({year => 1999});
316 $png->write_info ();
317 $png->set_invert_mono ();
318 # PNG puts the leftmost pixel in the high-order part of the byte.
319 $png->set_packswap ();
320 $png->write_image ($rows);
321 $png->write_end ();
322 close $out or die $!;
323 exit;
324 sub pixelate
326 {
327 my ($file, $box) = @_;
328 open my $in, "<", $file or die "Can't open '$file': $!";
329 my $width = 0;
330 my @lines;
331 while (<$in>) {
332 chomp;
333 s/\t/ /g;
334 push @lines, $_;
335 if (length ($_) > $width) {
336 $width = length ($_);
337 }
338 }
339 close $in or die $!;
340 $width *= $box;
341 my $height = scalar (@lines) * $box;
342 my $zero = pack "C", 0;
343 my $bwidth = int(($width+7)/8);
344 my @rows = ($zero x $bwidth) x $height;
345 for my $r (0..$height-1) {
346 my $y = int ($r/$box);
347 my $line = $lines[$y];
348 for my $x (0..length ($line) - 1) {
349 if (substr ($line, $x, 1) ne ' ') {
350 for my $c (0..$box - 1) {
351 my $offset = $x*$box + $c;
352 my $byte = int ($offset / 8);
353 my $bit = $offset % 8;
354 my $octet = ord (substr ($rows[$r], $byte, 1));
355 substr ($rows[$r], $byte, 1) = chr ($octet | 1<<$bit);
356 }
357 }
358 }
359 }
360 return ($height, $width, \@rows);
361 }
362 (This example is included as examples/libpng-write.pl
364 <https://fastapi.metacpan.org/source/BKB/Image-PNG-
365 Libpng-0.57/examples/libpng-write.pl> in the distribution.)
366 examples/mono.png <https://fastapi.metacpan.org/source/BKB/Image-PNG-
368 Libpng-0.57/examples/mono.png> is included in the distribution.
369 create_read_struct
371 my $png = create_read_struct ();
372 Create a structure for reading a PNG. The return value can be used as
374 an object with the other functions as methods. It can be copied to a
375 write structure with "copy_png".
376 This function corresponds to "png_create_read_struct" in libpng plus
378 "create_info_struct" (see "No info structure") with the error and
379 warning handler variables set up to use Perl's error reporting.
380 create_write_struct
382 my $png = create_write_struct ();
383 Create a structure for writing a PNG. This can be used as an object
385 with the other functions as methods.
386 This function corresponds to "png_create_write_struct" in libpng plus
388 "create_info_struct" (see "No info structure") with the error and
389 warning handler variables set up to use Perl's error reporting.
390 init_io
392 open my $file, "<", 'nice.png';
393 $png->init_io ($file);
394 Set the file which $png reads or writes to $file. $file must be an
396 already-opened Perl file handle. If $png was created with
397 "create_write_struct", $file must be opened for writing. If $png was
398 created with "create_read_struct", $file must be open for reading.
399 Since PNG files are binary files, it is safest to specify the "raw"
401 pragma or use "binmode" with the file to override any default text file
402 encoding which Perl might be using:
403 open my $file, ">:raw", 'output.png';
405 or
407 open my $file, ">", 'output.png';
409 binmode $file;
410 This function corresponds to "png_init_io" in libpng, with a Perl file
412 handle substituting for the C "FILE *".
413 On some versions of Perl, "init_io" may crash in some circumstances
415 with an error like "segmentation fault", if you use code like
416 my $png = create_read_struct ();
418 open my $file, "<:raw", "some.png";
419 $png->init_io ($file);
420 and you do not check whether the call to "open" was successful, and
422 some.png does not exist. The crash occurs within Perl's conversion of
423 $file into a C "FILE *" pointer, before this module's code runs. This
424 bug was fixed in Perls after version 5.24.1. To avoid trouble, please
425 check the return value of "open".
426 read_end
428 $png->read_end ();
429 Read the part of the PNG file after the image data.
431 This function corresponds to "png_read_end" in libpng.
433 read_image
435 my $rows = $png->read_image ();
436 Read the image data of the PNG file.
438 This function corresponds to "png_read_image" in libpng.
440 read_info
442 $png->read_info ();
443 Read the part of the PNG file before the image data.
445 This function corresponds to "png_read_info" in libpng.
447 read_png
449 $png->read_png ();
450 Read the entire PNG file into memory.
452 You can provide an argument containing transformations to apply to the
454 image:
455 use Image::PNG::Const qw/PNG_TRANSFORM_STRIP_ALPHA/;
457 $png->read_png (PNG_TRANSFORM_STRIP_ALPHA);
458 If the argument is omitted, the default value of
460 "PNG_TRANSFORM_IDENTITY" (the "do nothing" value) is applied. The
461 possible transformations which can be applied are
462 PNG_TRANSFORM_BGR
464 Flip RGB to BGR, RGBA to BGRA. See also "set_bgr".
465 PNG_TRANSFORM_EXPAND
467 Perform set_expand(). See also "set_expand".
468 PNG_TRANSFORM_EXPAND_16
470 Expand samples to 16 bits. See also "set_expand_16".
471 PNG_TRANSFORM_GRAY_TO_RGB
473 Expand grayscale samples to RGB (or GA to RGBA). See also
474 "set_gray_to_rgb".
475 PNG_TRANSFORM_IDENTITY
477 No transformation.
478 PNG_TRANSFORM_INVERT_ALPHA
480 Change alpha from opacity to transparency. See also
481 "set_invert_alpha".
482 PNG_TRANSFORM_INVERT_MONO
484 Invert monochrome images. See also "set_invert_mono".
485 PNG_TRANSFORM_PACKING
487 Expand 1, 2 and 4-bit samples to bytes. See also "set_packing".
488 PNG_TRANSFORM_PACKSWAP
490 Change order of packed pixels to LSB first. See also
491 "set_packswap".
492 PNG_TRANSFORM_SCALE_16
494 Strip 16-bit samples to 8-bit accurately. See also "set_scale_16".
495 PNG_TRANSFORM_SHIFT
497 Normalize pixels to the sBIT depth.
498 PNG_TRANSFORM_STRIP_16
500 Chop 16-bit samples to 8-bit less accurately. See also
501 "set_strip_16".
502 PNG_TRANSFORM_STRIP_ALPHA
504 Discard the alpha channel.
505 PNG_TRANSFORM_SWAP_ALPHA
507 Flip RGBA to ARGB or GA to AG. See also "set_swap_alpha".
508 PNG_TRANSFORM_SWAP_ENDIAN
510 Byte-swap 16-bit samples. See also "set_swap".
511 This function corresponds to "png_read_png" in libpng with a default
513 value for the third argument. The fourth, unused, argument to
514 "png_read_png" does not need to be supplied. See "Unused arguments
515 omitted".
516 It does not take a second "info" argument. See "No info structure".
518 read_update_info
520 $png->read_update_info ();
521 âðĪŠâ Inside Image::PNG::Libpng, the libpng function
523 "png_read_update_info" is called before reading image data. According
524 to "The libpng documentation", this function may only be called once
525 for any particular info structure. So although the above Perl interface
526 exists in the module, it is strongly recommended to not use this unless
527 you know exactly what you are doing, since it will usually cause an
528 error when the image data is read.
529 This function corresponds to "png_read_update_info" in libpng
531 write_end
533 $png->write_end ();
534 Write the final part of the PNG file.
536 This function corresponds to "png_write_end" in libpng.
538 write_image
540 $png->write_image ($rows);
541 Write the image of the PNG file. $rows is an array reference as per
543 "set_rows".
544 This function corresponds to "png_write_image" in libpng.
546 write_info
548 $png->write_info ();
549 Write the first part of the PNG file.
551 This function corresponds to "png_write_info" in libpng.
553 write_png
555 $png->write_png ();
556 This writes the PNG to the file stream which was associated with it
558 using "init_io". For example,
559 open my $output, ">:raw", 'out.png';
561 $png->init_io ($output);
562 $png->write_png ();
563 close $output;
564 An optional argument consists of transformations to apply to the PNG
566 image before writing it:
567 use Image::PNG::Const qw/PNG_TRANSFORM_STRIP_ALPHA/;
569 $png->write_png (PNG_TRANSFORM_STRIP_ALPHA);
570 The transformations which can be applied are as follows:
572 PNG_TRANSFORM_BGR
574 Flip RGB to BGR, RGBA to BGRA. See also "set_bgr".
575 PNG_TRANSFORM_INVERT_ALPHA
577 Change alpha from opacity to transparency. See also
578 "set_invert_alpha".
579 PNG_TRANSFORM_INVERT_MONO
581 Invert monochrome images. See also "set_invert_mono".
582 PNG_TRANSFORM_PACKING
584 Expand 1, 2 and 4-bit samples to bytes. See also "set_packing".
585 PNG_TRANSFORM_PACKSWAP
587 Change order of packed pixels to LSB first. See also
588 "set_packswap".
589 PNG_TRANSFORM_SHIFT
591 Normalize pixels to the sBIT depth.
592 PNG_TRANSFORM_STRIP_FILLER_AFTER
594 Strip out trailing filler bytes.
595 PNG_TRANSFORM_STRIP_FILLER_BEFORE
597 Strip out leading filler bytes.
598 PNG_TRANSFORM_SWAP_ALPHA
600 Flip RGBA to ARGB or GA to AG. See also "set_swap_alpha".
601 PNG_TRANSFORM_SWAP_ENDIAN
603 Byte-swap 16-bit samples. See also "set_swap".
604 This function corresponds to "png_write_png" in libpng.
606
608 These functions handle the header part of PNG image data. See this
609 subsection <http://www.w3.org/TR/PNG/#11IHDR> of "The PNG
610 specification" for information on the PNG standards for the image
611 header.
612 color_type_name
614 $name = color_type_name ($color_type);
615 This is a convenience function which returns a string corresponding to
617 the numerical color type in $color_type. The name is in upper case,
618 with words separated by underscores, as in "RGB_ALPHA".
619 use Image::PNG::Libpng ':all';
621 my $png = read_png_file ('tantei-san.png');
622 my $name = color_type_name ($png->get_IHDR->{color_type});
623 print "Your PNG has colour type $name.\n";
624 (This example is included as examples/color-type-name.pl
626 <https://fastapi.metacpan.org/source/BKB/Image-PNG-
627 Libpng-0.57/examples/color-type-name.pl> in the distribution.)
628 This function does not correspond to anything in libpng. The names of
630 the color types are taken from those defined in the libpng header file,
631 "png.h".
632 get_bit_depth
634 my $bit_depth = $png->get_bit_depth ();
635 Get the bit depth, the number of bits for one channel of one pixel.
637 This function corresponds to "png_get_bit_depth" in libpng
639 get_channels
641 my $channels = $png->get_channels ();
642 Get the number of channels, from one to four. The channels are the
644 components of pixels, for example the red channel or the alpha
645 (transparency) channel. The return value is 1 for color type
646 "PNG_COLOR_TYPE_GRAY" and "PNG_COLOR_TYPE_PALETTE", 2 for
647 "PNG_COLOR_TYPE_GRAY_ALPHA", 3 for "PNG_COLOR_TYPE_RGB" and 4 for
648 "PNG_COLOR_TYPE_RGB_ALPHA" or "PNG_COLOR_TYPE_RGB" with a filler byte.
649 Note that the number of channels does not necessarily correspond to the
650 number of bytes, since the bit depth can also be 1, 2, 4, 8, or 16,
651 depending on the color type. See also the convenience function
652 "color_type_channels".
653 This function corresponds to "png_get_channels" in libpng
655 get_color_type
657 my $color_type = $png->get_color_type ();
658 This returns an integer value. If you want to get a name for the color
660 type, use "color_type_name".
661 This function corresponds to "png_get_color_type" in libpng.
663 get_IHDR
665 my $IHDR = $png->get_IHDR ();
666 Read the IHDR information from the PNG file. The return value is a hash
668 reference containing the following key/value pairs:
669 width
671 The width of the image in pixels.
672 height
674 The height of the image in pixels.
675 bit_depth
677 The bit depth of the image (the number of bits used for each color
678 in a pixel). This can take the values 1, 2, 4, 8, 16.
679 color_type
681 The color type. This can take the values PNG_COLOR_TYPE_GRAY,
682 PNG_COLOR_TYPE_GRAY_ALPHA, PNG_COLOR_TYPE_PALETTE,
683 PNG_COLOR_TYPE_RGB, PNG_COLOR_TYPE_RGB_ALPHA.
684 interlace_method
686 The method of interlacing. This can take the values
687 PNG_INTERLACE_NONE, PNG_INTERLACE_ADAM7.
688 So, for example, to get the width and height of an image,
690 my $ihdr = $png->get_IHDR ();
692 printf "Your image is %d x %d\n", $ihdr->{width}, $ihdr->{height};
693 This function corresponds to "png_get_IHDR" in libpng, with a single
695 Perl hash reference used instead of the several pointers to integers
696 used in libpng.
697 It does not return the fields "filter_type" and "compression_type",
699 since these are always 0. See "Unused arguments omitted".
700 get_image_height
702 my $height = $png->get_image_height ();
703 Get the image's height from the header.
705 This function corresponds to "png_get_image_height" in libpng
707 get_image_width
709 my $width = $png->get_image_width ();
710 Get the image's width from the header.
712 This function corresponds to "png_get_image_width" in libpng
714 get_interlace_type
716 my $interlace_type = $png->get_interlace_type ();
717 Get the interlace type. This is either PNG_INTERLACE_NONE or
719 PNG_INTERLACE_ADAM7.
720 This function corresponds to "png_get_interlace_type" in libpng
722 get_valid
724 my $valid = $png->get_valid ();
725 if ($valid->{oFFs}) {
726 print "The PNG has valid screen offsets.\n";
727 }
728 This function returns a hash with a key for each possible chunk which
730 may or may not be valid. The chunks which you can test for are "bKGD",
731 "cHRM", "eXIf", "gAMA", "hIST", "hIST", "iCCP", IDAT, IHDR, "iTXt",
732 "oFFs", "pCAL", "pHYs", "PLTE", "sBIT", "sCAL", "sPLT", "sRGB", "tEXt",
733 "tIME", "tRNS", and "zTXt".
734 Whereas "libpng_supports" tells you whether the installed libpng on
736 your system supports various chunks, this tells you whether the chunks
737 are present in a particular PNG image file.
738 The first argument, $png, is a PNG structure created with
740 "create_read_struct".
741 This function corresponds to "png_get_valid" in libpng, with the
743 difference being that the return value is a hash containing a key for
744 each possible chunk.
745 height
747 my $height = $png->height ();
748 Alias for "get_image_height". This is not exported, it's intended for
750 use with the object only.
751 set_IHDR
753 my $ihdr = {width => 10, height => 10, bit_depth => 8,
754 color_type => PNG_COLOR_TYPE_RGB};
755 $png->set_IHDR ($ihdr);
756 Set the IHDR chunk (the image header) of the PNG image.
758 The first argument, $png, is a writeable PNG structure created with
760 "create_write_struct". The second argument is a hash with the following
761 values:
762 width
764 The width of the image in pixels.
765 This cannot be zero, negative, or omitted.
766 height
768 The height of the image in pixels.
769 This cannot be zero, negative, or omitted.
770 bit_depth
772 The bit depth of the image (the number of bits used for each color
773 in a pixel).
774 This cannot be omitted. This can have the values 1, 2, 4, 8, 16.
775 color_type
777 The color type.
778 This cannot be omitted. This can have the values
779 PNG_COLOR_TYPE_GRAY, PNG_COLOR_TYPE_GRAY_ALPHA,
780 PNG_COLOR_TYPE_PALETTE, PNG_COLOR_TYPE_RGB,
781 PNG_COLOR_TYPE_RGB_ALPHA.
782 interlace_method
784 The method of interlacing.
785 If this is omitted, it's set to PNG_INTERLACE_NONE. This can have
786 the values PNG_INTERLACE_NONE, PNG_INTERLACE_ADAM7.
787 Other fields in the hash are ignored.
789 This function corresponds to "png_set_IHDR" in libpng, with a single
791 Perl hash reference used instead of the seven integers.
792 The values "compression_method", "filter_method", may be supplied by
794 the user but are ignored since they may only take the value 0. See
795 "Unused arguments omitted".
796 sig_cmp
798 if (sig_cmp ($should_be_png)) {
799 print "Your data does not have a PNG signature.\n";
800 }
801 This subroutine looks at $should_be_png and checks whether its first
803 bytes correspond to a valid PNG signature. It returns a true value if
804 they do not.
805 It can also take two further arguments consisting of a byte offset and
807 a number of bytes to check respectively:
808 sig_cmp ($should_be_png, 0, 8);
810 If these arguments are not supplied, the byte offset is assumed to be
812 zero, and the number of bytes to check is assumed to be eight.
813 This function corresponds to "png_sig_cmp" in libpng, with default
815 arguments of 0 and 8 if second and third arguments are not supplied.
816 width
818 my $width = $png->width ();
819 Alias for "get_image_width". This is not exported, it's intended for
821 use with the object only.
822
824 These functions deal with accessing the image data itself.
825 get_rowbytes
827 my $bytes_in_a_row = $png->get_rowbytes ();
828 This returns the number of bytes needed to hold a transformed row of an
830 image.
831 This function corresponds to "png_get_rowbytes" in libpng.
833 get_rows
835 my $rows = $png->get_rows ();
836 my $pixel = substr ($rows->[10], 20, 1);
837 This returns the rows of the PNG image, after uncompressing and
839 unfiltering, as binary data. The return value, $rows in the example, is
840 an array reference with a number of rows equal to the height of the PNG
841 image. Each element of the array reference is a string containing the
842 binary data making up a row of the image. The values of individual
843 pixels can be extracted from using a function such as "substr" or
844 "unpack". This binary data is likely to contain bytes equal to zero.
845 "get_rowbytes" gives the number of bytes in each row.
847 Each row is a Perl string. Perl terminates each row of data with an
849 extra zero byte at the end.
850 This function corresponds to "png_get_rows" in libpng.
852 set_rows
854 $png->set_rows (\@rows);
855 Set the rows of data to be written in to the PNG to @rows. @rows needs
857 to contain at least the same number of rows of data as the height of
858 the PNG image set with "set_IHDR", and the length of each entry needs
859 to be at least the width of the image multiplied by the number of bytes
860 required for each pixel.
861 This function was changed to copy the data in version 0.46.
863 This function corresponds to "png_set_rows" in libpng.
865
867 See this subsection <http://www.w3.org/TR/PNG/#11textinfo> of "The PNG
868 specification" for information on the PNG standards for text
869 information.
870 get_text
872 my $text_chunks = $png->get_text ();
873 This gets all of the text chunks in the PNG image and returns them as
875 an array reference. Each element of the array represents one text
876 chunk. This element is a hash reference with keys such as "key",
877 "lang_key", or "compression" taken from the PNG's information.
878 The text data is uncompressed by libpng. If it is international text
880 ("ITXT"), it is put into Perl's internal Unicode encoding if it is
881 found to be valid UTF-8. (PNG "international text", "ITXT" is required
882 to be in the UTF-8 encoding, and non-international text is required to
883 contain whitespace and printable ASCII characters only. See "The PNG
884 specification" for more on the requirements of a PNG text section.)
885 This function corresponds to "png_get_text" in libpng, with a Perl
887 array of hash references substituted for the C array of structs used by
888 libpng. See "set_text" for details of the keys and values which may be
889 returned.
890 set_text
892 $png->set_text ([\%chunk1, \%chunk2]);
893 This sets the text chunks in a writeable image. The input value is an
895 array reference containing one or more hash references. Each hash
896 reference must have a "key" value for the text. According to the PNG
897 specification, this should be between one and 79 bytes in length. This
898 module enforces that restriction, so if you supply a key longer than
899 that, the chunk cannot be added. A hash reference may also have the
900 following:
901 "compression"
903 The value of "compression" controls the compression of the text. If
904 "compression" is not supplied, a default value of
905 PNG_TEXT_COMPRESSION_NONE is applied. The "compression" field can
906 take the following values, available from Image::PNG::Const:
907 PNG_TEXT_COMPRESSION_NONE
909 TEXT = Printable ASCII and space characters.
910 PNG_TEXT_COMPRESSION_zTXt
912 TEXT = Printable ASCII and space characters.
913 PNG_ITXT_COMPRESSION_NONE
915 ITXT = International text, should be UTF-8.
916 PNG_ITXT_COMPRESSION_zTXt
918 ITXT = International text, should be UTF-8.
919 "itxt_length"
921 The string length of international text in bytes.
922 âðĪŠâ This is ignored by libpng when writing text chunks. When
924 reading text chunks, if the text is marked as international text,
925 libpng adds the length of the string in bytes in this field rather
926 than in "text_length".
927 "lang"
929 This should be set to name of the language of the text, if the text
930 chunk is iTXt. According to the PNG specification, "It is an ISO
931 646.IRV:1991 [ISO 646] string consisting of hyphen-separated words
932 of 1-8 alphanumeric characters each (for example cn, en-uk, no-bok,
933 x-klingon, x-KlInGoN)."
934 Support for writing "lang" was added in version 0.49 of this
936 module. (Prior to that undocumented support existed via a
937 differently-named key.)
938 âðĪŠâ This module does not attempt to check the supplied value, but
940 merely passes it to libpng. libpng appears not to check the value
941 either, nor to enforce restrictions on its length.
942 "lang_key"
944 This corresponds to the "Translated keyword" of the PNG
945 specification. Note that the user needs to supply "key" and "lang"
946 as well as "lang_key".
947 Support for writing "lang_key" was added in version 0.49 of this
949 module. (Prior to that undocumented support existed via a
950 differently-named key.)
951 "text"
953 The value of "text" is added to the PNG as the text segment. This
954 can be omitted if you just want to write a key value without any
955 accompanying text.
956 "text_length"
958 The string length in bytes. The user may set this, but it is
959 ignored when writing PNG text chunks, instead this module uses the
960 string length obtained from Perl. This key contains the length of
961 the string when reading text chunks via "get_text", but if the text
962 is marked as international text, "itxt_length" is used to return
963 its length in bytes, rather than this.
964 Whether or not the value of "text" is an ITXT field is decided by the
966 value of "compression".
967 People who want to fiddle with the text compression applied can do so
969 via "set_text_compression_level" and the other functions described
970 below that.
971 If "set_text" is called more than once, the chunks are not overwritten
973 but appended to the existing ones. (This behaviour is from libpng
974 itself.)
975 Prior to version 0.50, "set_text" would fail silently if the user added
977 invalid chunks, for example hash references without a valid "key", or
978 things which were not hash references at all. From version 0.50, all
979 invalid inputs cause fatal errors. However, unknown keys in the hash
980 references do not cause fatal errors.
981 This function corresponds to "png_set_text" in libpng.
983 Example
985 use utf8;
987 use Image::PNG::Const ':all';
988 use Image::PNG::Libpng ':all';
989 my $png = create_write_struct ();
990 $png->set_IHDR ({width => 1, height => 1, bit_depth => 8,
991 color_type => PNG_COLOR_TYPE_GRAY});
992 $png->set_rows (['X']);
993 $png->set_text ([{
994 compression => PNG_TEXT_COMPRESSION_NONE,
995 key => "Copyright",
996 text => "Copyright (C) 2020 Fat Cat",
997 }, {
998 compression => PNG_ITXT_COMPRESSION_zTXt,
999 key => "Copyright",
1000 lang_key => 'čč
æĻĐ',
1001 lang => 'ja_JP',
1002 text => 'ÂĐäŧĪåïžåđīččããĢãģããžãŽãžãã',
1003 }]);
1004 $png->write_png_file ('copyright.png');
1005 (This example is included as examples/set-text.pl
1007 <https://fastapi.metacpan.org/source/BKB/Image-PNG-
1008 Libpng-0.57/examples/set-text.pl> in the distribution.)
1009 text_compression_name
1011 my $name = Image::PNG::Libpng::text_compression_name ($text->{compression});
1012 Given a numerical text compression type, return the equivalent name.
1014 The name is in upper case. The possible return values are
1015 TEXT_NONE
1017 TEXT_zTXt
1018 ITXT_NONE
1019 ITXT_zTXt
1020 an empty string
1021 if the compression method is unknown.
1022 The compression field is also used to store the information about
1024 whether the text is "international text" in UTF-8 or not.
1025 This function does not correspond to anything in libpng. The names of
1027 the text compression types are based on those in "png.h", but without
1028 the word "COMPRESSION", so for example the libpng constant
1029 "PNG_ITXT_COMPRESSION_zTXt" corresponds to a return value of
1030 "ITXT_zTXt".
1031
1033 See this subsection <http://www.w3.org/TR/PNG/#12Use-of-private-chunks>
1034 of "The PNG specification" for information on the PNG standards for
1035 private chunks.
1036 To test whether your version of libpng supports "private chunks", use
1038 "libpng_supports" with argument '"UNKNOWN_CHUNKS"':
1039 if (libpng_supports ('UNKNOWN_CHUNKS')) {
1041 # do something
1042 }
1043 get_chunk_malloc_max
1045 my $max = $png->get_chunk_malloc_max ();
1046 This gets the maximum amount of memory that a chunk can use.
1048 To test whether your version of libpng supports "get_chunk_malloc_max",
1050 use "libpng_supports" with argument '"CHUNK_MALLOC_MAX"':
1051 if (libpng_supports ('CHUNK_MALLOC_MAX')) {
1053 # do something
1054 }
1055 This function corresponds to "png_get_chunk_malloc_max" in libpng
1057 set_chunk_malloc_max
1059 $png->set_chunk_malloc_max ($max);
1060 This sets the maximum amount of memory that a chunk can use. The
1062 default value of libpng 1.6.37 is 8 megabytes.
1063 To test whether your version of libpng supports "get_chunk_malloc_max",
1065 use "libpng_supports" with argument '"CHUNK_MALLOC_MAX"':
1066 if (libpng_supports ('CHUNK_MALLOC_MAX')) {
1068 # do something
1069 }
1070 This function corresponds to "png_set_chunk_malloc_max" in libpng
1072 set_keep_unknown_chunks
1074 use Image::PNG::Const 'PNG_HANDLE_CHUNK_ALWAYS';
1075 $png->set_keep_unknown_chunks (PNG_HANDLE_CHUNK_ALWAYS);
1076 Tell libpng not to discard unknown chunks when reading the file.
1078 get_unknown_chunks
1080 my $private_chunks = $png->get_unknown_chunks ();
1081 # Get some data from a private chunk
1082 my $chunk_three_data = $private_chunks->[3]->{data};
1083 # Get the size of the data
1084 print length $chunk_three_data;
1085 This gets all of the private chunks from the image. The return value is
1087 an array reference containing hash references. If there are no private
1088 chunks, this returns an undefined value. There is one element of the
1089 array for each chunk member. It is necessary to call
1090 "set_keep_unknown_chunks" with an appropriate value before reading the
1091 file, otherwise libpng discards unknown chunks when reading the file.
1092 Each member hash reference has the following keys:
1094 name
1096 The name of the unknown chunk, in the PNG chunk format (four
1097 bytes).
1098 location
1100 The location of the unknown chunk.
1101 data
1103 The data of the unknown chunk
1104 The "size" field of the PNG structure is not stored, because the "data"
1106 member of the hash contains information on its length.
1107 This function corresponds to "png_get_unknown_chunks" in libpng
1109 set_unknown_chunks
1111 $png->set_unknown_chunks (name => 'dUCk', data => 'abcdefg',
1112 location => PNG_AFTER_IDAT);
1113 âðĪŠâ This currently does not fully function.
1115 This function corresponds to "png_set_unknown_chunks" in libpng
1117
1119 access_version_number
1120 my $libpng_version_number = Image::PNG::Libpng::access_version_number ();
1121 This function returns the version of the libpng library which the
1123 module is using as an integer number.
1124 This function corresponds to "png_access_version_number" in libpng.
1126 get_libpng_ver
1128 my $libpng_version = Image::PNG::Libpng::get_libpng_ver ();
1129 This function returns the version of the libpng library which the
1131 module is using.
1132 This function corresponds to "png_get_libpng_ver" in libpng. However,
1134 it doesn't require the "png_structp" argument of the C function. See
1135 "Unused arguments omitted".
1136
1138 get_compression_buffer_size
1139 my $size = $png->get_compression_buffer_size ();
1140 Returns the value of the compression buffer size, which may be altered
1142 with "set_compression_buffer_size".
1143 set_compression_buffer_size
1145 $png->set_compression_buffer_size (100);
1146 Set the size of the buffer which zlib uses to compress or decompress
1148 the image data. It takes one argument, an integer number. This cannot
1149 be less than 6.
1150 set_compression_level
1152 $png->set_compression_level ($number);
1153 Set the compression level used to make the PNG. A value of 0
1155 ("Z_NO_COMPRESSION") corresponds to no compression at all, otherwise
1156 $number may take values of 1 ("Z_BEST_SPEED") to 9
1157 ("Z_BEST_COMPRESSION"), with smaller values giving faster, and larger
1158 values giving better, that is with smaller output, compression. These
1159 correspond to the -1, -2, ... -9 options to the "gzip" utility, or the
1160 compression level parameter of "zlib". Calling with "-1"
1161 ("Z_DEFAULT_COMPRESSION") reverts to the default compression. Calling
1162 with any other number outside the range 0 to 9 results in a fatal
1163 error.
1164 This function was added to the module in version 0.49.
1166 set_compression_mem_level
1168 $png->set_compression_mem_level ($argument);
1169 âðĪŠâ Untested function corresponding to
1171 "png_set_compression_mem_level". Takes one integer argument.
1172 Sets the "memLevel" parameter of "deflateInit2" in zlib when writing
1174 PNG image data. Argument between 1 for minimum memory and 9 for maximum
1175 speed. The default is 8. See "zlib documentation".
1176 set_compression_window_bits
1178 $png->set_compression_window_bits ($argument);
1179 âðĪŠâ Untested function corresponding to
1181 "png_set_compression_window_bits". Takes one integer argument.
1182 Sets the "windowBits" parameter of "deflateInit2" in zlib when writing
1184 PNG image data. Argument value must be between 8 and 15 for libpng. The
1185 default is 15. See the "zlib documentation".
1186 set_compression_strategy
1188 $png->set_compression_strategy ($argument);
1189 âðĪŠâ Untested function corresponding to "png_set_compression_strategy".
1191 Takes one integer argument.
1192 Sets the "strategy" parameter of "deflateInit2" when writing PNG image
1194 data. Setting this with libpng overrides libpng's default behaviour of
1195 changing the value depending on the filter in use. For zlib, the
1196 argument is either 0 for default behaviour, or 1 to 4. See the "zlib
1197 documentation". libpng uses the default strategy 0
1198 ("Z_DEFAULT_STRATEGY") for unfiltered image data, and 1 ("Z_FILTERED")
1199 for filtered image data.
1200 set_filter
1202 use Image::PNG::Const 'PNG_FILTER_NONE';
1203 $png->set_filter (PNG_FILTER_NONE);
1204 This sets the filters which are allowed to be used for writing a PNG
1206 image. The possible values are
1207 PNG_NO_FILTERS
1209 PNG_FILTER_NONE
1210 PNG_FILTER_SUB
1211 PNG_FILTER_UP
1212 PNG_FILTER_AVG
1213 PNG_FILTER_PAETH
1214 PNG_ALL_FILTERS
1215 These can be combined using "|" (logical or):
1217 use Image::PNG::Const ':all';
1219 set_filter ($png, PNG_FILTER_UP | PNG_FILTER_AVG);
1220 Please see this subsection <http://www.w3.org/TR/PNG/#9Filter-types> of
1222 "The PNG specification" for the meanings of these filter types.
1223 This function corresponds to "png_set_filter" in libpng with the second
1225 (unused) argument omitted. See "Unused arguments omitted".
1226 set_text_compression_level
1228 $png->set_text_compression_level ($argument);
1229 âðĪŠâ Untested function corresponding to
1231 "png_set_text_compression_level". Takes one integer argument.
1232 As "set_compression_level" but for compressed text.
1234 set_text_compression_mem_level
1236 $png->set_text_compression_mem_level ($argument);
1237 âðĪŠâ Untested function corresponding to
1239 "png_set_text_compression_mem_level". Takes one integer argument.
1240 As "set_compression_mem_level" but for compressed text.
1242 set_text_compression_window_bits
1244 $png->set_text_compression_window_bits ($argument);
1245 âðĪŠâ Untested function corresponding to
1247 "png_set_text_compression_window_bits". Takes one integer argument.
1248 As "set_compression_window_bits" but for compressed text.
1250 set_text_compression_strategy
1252 $png->set_text_compression_strategy ($argument);
1253 âðĪŠâ Untested function corresponding to
1255 "png_set_text_compression_strategy". Takes one integer argument.
1256 As "set_compression_strategy" but for compressed text.
1258
1260 These routines deal with the other possible chunks of PNGs.
1261 The getter and setter routines for all other chunks are designed so
1263 that the return value of "get_wXYZ" is able to be used directly as the
1264 value for "set_wXYZ", so the values of chunks can easily be copied from
1265 one PNG to another.
1266 my $values = $png1->get_wXYZ ();
1268 $png2->set_wXYZ ($values);
1269 If the chunk is not present, or if the chunk is not supported by the
1271 user's version of libpng, the return value of "get_wXYZ" is the
1272 undefined value.
1273 bKGD
1275 The background color of the PNG image.
1276 See this subsection <http://www.w3.org/TR/PNG/#11bKGD> of "The PNG
1278 specification" for information on the PNG standards for the background
1279 chunk.
1280 get_bKGD
1282 my $bkgd = $png->get_bKGD ();
1284 Get the bKGD (background) chunk of the image.
1286 The return value is a hash with the following keys, depending on the
1288 color type of the image:
1289 index
1291 For palette color types, this is the offset into the palette.
1292 gray
1294 For grayscale color types.
1295 red
1297 green
1298 blue
1299 This function corresponds to "png_get_bKGD" in libpng with a hash
1301 function instead of a "png_color" struct.
1302 set_bKGD
1304 $png->set_bKGD ($bkgd);
1306 Set the bKGD (background) chunk of the image. $bkgd is a hash
1308 reference. The keys of the hash reference are as described in
1309 "get_bKGD".
1310 This function corresponds to "png_set_bKGD" in libpng with a hash
1312 function instead of a "png_color" struct.
1313 cHRM
1315 See this subsection <http://www.w3.org/TR/PNG/#11cHRM> of "The PNG
1316 specification" "cHRM Primary chromaticities and white point".
1317 get_cHRM
1319 my $cHRM = $png->get_cHRM ();
1321 Get the cHRM chunk as a hash reference.
1323 The keys of the hash are white_x, white_y, red_x, red_y, green_x,
1325 green_y, blue_x, blue_y.
1326 The values of the hash are floating point numbers between 0 and 1.
1328 This function corresponds to "png_get_cHRM" in libpng with a hash
1330 reference supplying the arguments. The hash's keys correspond to the
1331 names of the "double" arguments in libpng.
1332 get_cHRM_XYZ
1334 my $cHRM = $png->get_cHRM_XYZ ();
1336 Get the cHRM chunk as a hash reference for the XYZ color space.
1338 The keys of the hash are red_x, red_y, red_z, green_x, green_y,
1340 green_z, blue_x, blue_y, blue_z.
1341 The values of the hash are floating point numbers between 0 and 1.
1343 This function corresponds to "png_get_cHRM_XYZ" in libpng with a hash
1345 reference supplying the arguments. The hash's keys correspond to the
1346 names of the "double" arguments in libpng.
1347 set_cHRM
1349 $png->set_cHRM (\%cHRM);
1351 Set the cHRM chunk from a hash reference.
1353 The keys of the hash are as for "get_cHRM". The values are floating
1355 point numbers between 0 and 1.
1356 This function corresponds to "png_set_cHRM" in libpng with a hash
1358 reference instead of the "double" arguments.
1359 set_cHRM_XYZ
1361 $png->set_cHRM_XYZ (\%cHRM);
1363 Set the cHRM chunk from a hash reference for the XYZ color space.
1365 The keys of the hash are as for "get_cHRM_XYZ". The values are floating
1367 point numbers between 0 and 1. The "Y" values "red_y", "green_y", and
1368 "blue_y" should sum to 1. If you supply values outside the allowed
1369 range, libpng corrects them silently on writing rather than producing
1370 an error.
1371 This function corresponds to "png_set_cHRM_XYZ" in libpng with a hash
1373 reference instead of the "double" arguments.
1374 eXIf
1376 The "eXIf" chunk is an extension to the PNG specification. See
1377 <http://www.simplesystems.org/png-group/proposals/eXIf/>. Support for
1378 this chunk was added in version 0.50 of this module.
1379 get_eXIf
1381 my $exif = $png->get_eXIf ();
1383 This retrieves the "eXIf" chunk from $png but does not process the
1385 internal information.
1386 set_eXIf
1388 $png->set_eXIf ($exif);
1390 libpng checks whether the chunk's first two bytes are either "II" for
1392 little-endian (from Intel) or "MM" for big-endian (from Motorola) then
1393 adds the entire chunk, including the first two bytes, to the PNG.
1394 âðĪŠâ As of December 2020, there appears to be a bug in libpng in which
1396 the eXIf chunk is added twice, causing a warning of the form "libpng
1397 warning: eXIf: duplicate" on reading a PNG file back in. See
1398 <https://github.com/glennrp/libpng/pull/351>.
1399 gAMA
1401 See this subsection <http://www.w3.org/TR/PNG/#11gAMA> of "The PNG
1402 specification".
1403 get_gAMA
1405 my $gamma = $png->get_gAMA ();
1407 Get the gamma value or gAMA chunk. The return value is a floating-point
1409 number.
1410 This function corresponds to "png_get_gAMA" in libpng
1412 set_gAMA
1414 $png->set_gAMA (0.2);
1416 Set the gamma value or gAMA chunk.
1418 This function corresponds to "png_set_gAMA" in libpng
1420 hIST
1422 See this subsection <http://www.w3.org/TR/PNG/#11hIST> of "The PNG
1423 specification".
1424 get_hIST
1426 my $hist = $png->get_hIST ();
1428 If the PNG file contains a histogram, the return value is array
1430 reference, otherwise it is the undefined value. The number of entries
1431 in the array reference is the same as in the palette.
1432 This function corresponds to "png_get_hIST" in libpng
1434 set_hIST
1436 $png->set_hIST (\@hist);
1438 Set the histogram of frequencies of the colors of a paletted ("PLTE")
1440 image. The entries of the histogram are 16 bit unsigned integers, so
1441 the maximum value that can be entered is 65535 = 2^16 - 1. Larger
1442 numbers and floating point numbers will cause a warning to be printed
1443 and the value to be set to zero. The histogram must have exactly the
1444 same number of entries as the palette or the call will fail with a
1445 warning. A histogram cannot be added to an image without a palette. A
1446 call to set_hIST for an image without a palette will cause a warning
1447 and return without setting the value.
1448 (I'm not sure of the best form of error handling for this function so
1450 it may change in future versions to have errors for a bad histogram
1451 rather than warnings.)
1452 This function corresponds to "png_set_hIST" in libpng
1454 iCCP
1456 See this subsection <http://www.w3.org/TR/PNG/#11iCCP> of "The PNG
1457 specification".
1458 get_iCCP
1460 my $iccp = $png->get_iCCP ();
1462 The return value is a hash with two keys,
1464 name
1466 The name of the profile.
1467 profile
1469 The color profile.
1470 The "compression_type" value, which is always 0, is not returned. See
1472 "Unused arguments omitted".
1473 This function corresponds to "png_get_iCCP" in libpng.
1475 set_iCCP
1477 $png->set_iCCP ({name => 'name', profile => 'profile'});
1479 This function corresponds to "png_set_iCCP" in libpng. For details of
1481 the arguments, see "get_iCCP". A "compression_type" argument, which
1482 must always be 0 anyway, is ignored. See "Unused arguments omitted".
1483 oFFs
1485 This is an extension to the PNG specification. See
1486 <http://www.libpng.org/pub/png/spec/1.1/pngext-1.1.0-pdg.html#C.oFFs>.
1487 get_oFFs
1489 my $phys = $png->get_oFFs ();
1491 Get oFFs chunk. Return value is a hash reference
1493 This function corresponds to "png_get_oFFs" in libpng
1495 set_oFFs
1497 $png->set_oFFs ({x_offset => 1, y_offset => 1, unit_type => 0});
1499 Set oFFs chunk. See the specification linked above for the meanings of
1501 the parameters. If "unit_type" is not 0 or 1, a warning is produced.
1502 This function corresponds to "png_set_oFFs" in libpng
1504 pCAL
1506 pCAL is an extension of the PNG specification which allows one to
1507 associate pixels in the PNG image with non-image data such as a heat
1508 map. See
1509 <http://www.libpng.org/pub/png/spec/1.1/pngext-1.1.0-pdg.html#C.pCAL>.
1510 To test whether your version of libpng supports "the pCAL extension",
1512 use "libpng_supports" with argument '"pCAL"':
1513 if (libpng_supports ('pCAL')) {
1515 # do something
1516 }
1517 get_pCAL
1519 my $pcal = $png->get_pCAL ();
1521 The return value is a hash reference with the following keys:
1523 params
1525 If this exists, its value is a reference to an array containing the
1526 parameter list of the pCAL chunk, which are floating point numbers.
1527 Within the PNG file chunk, these parameters are stored as strings
1528 representing floating point numbers, but you can pass in Perl
1529 floating point numbers rather than strings. The number of
1530 parameters you should set is fixed by the "type" parameter. Refer
1531 to the PNG specification for full details.
1532 purpose
1534 The purpose string of the pCAL chunk.
1535 type
1537 The equation type as a number, from 0 to 3. See the PNG
1538 specification for the meanings. Other numbers cause an error.
1539 units
1541 The units as a string. See the PNG specification for details.
1542 x0 The zero value for the equation, an integer.
1544 x1 The max value for the equation, an integer.
1546 This function corresponds to "png_get_pCAL" in libpng
1548 set_pCAL
1550 $png->set_pCAL (\%values);
1552 See "get_pCAL" for the parameters of %values.
1554 This function corresponds to "png_set_pCAL" in libpng
1556 pHYs
1558 See this subsection <http://www.w3.org/TR/PNG/#11pHYs> of "The PNG
1559 specification".
1560 get_pHYs
1562 my $phys = $png->get_pHYs ();
1564 The return value is a hash reference with the keys
1566 res_x
1568 res_y
1569 unit_type
1570 Is either 0 or 1.
1571 This function corresponds to "png_get_pHYs" in libpng
1573 set_pHYs
1575 $png->set_pHYs ({res_x => 1, res_y => 1, unit_type => 1});
1577 This function corresponds to "png_set_pHYs" in libpng
1579 PLTE
1581 See this subsection <http://www.w3.org/TR/PNG/#11PLTE> of "The PNG
1582 specification" for information on the PNG standards for the palette
1583 chunk.
1584 get_palette_max
1586 my $pmax = $png->get_palette_max ();
1588 If your libpng supports it, this will return the maximum palette index
1590 found in the image, or "-1" if the palette was not checked, or "0" if
1591 no palette was found.
1592 To test whether your version of libpng supports "get_palette_max", use
1594 "libpng_supports" with argument '"GET_PALETTE_MAX"':
1595 if (libpng_supports ('GET_PALETTE_MAX')) {
1597 # do something
1598 }
1599 âðĪŠâ This function is implemented but so far it is not very clear to me
1601 what it does, since, for example, it returns zero for the test image
1602 t/tantei-san.png which is an image with a fully-used 256-color palette.
1603 I've asked about it on the libpng mailing list
1604 <https://sourceforge.net/p/png-mng/mailman/png-mng-
1605 implement/?viewmonth=202012&viewday=14>, but so far nobody has
1606 responded.
1607 get_PLTE
1609 my $colors = $png->get_PLTE ();
1611 # Get the green value of the twentieth entry in the palette.
1612 my $green = $colors->[20]->{green};
1613 This function gets the palette from the PNG. The return value is an
1615 array reference containing the palette. This array contains hash
1616 references with the values "green", "blue" and "red" for the color of
1617 each pixel in the palette. If the PNG has no palette, it returns an
1618 undefined value.
1619 A PNG image may or may not contain a palette. To check whether the
1621 image contains a palette, use something of the following form:
1622 use Image::PNG::Const ':all';
1624 my $color_type = $png->get_color_type ();
1625 if ($color_type == PNG_COLOR_TYPE_PALETTE) {
1626 # The PNG uses a palette.
1627 }
1628 A PNG image may also contain a palette even when the "color_type" does
1630 not indicate that. To check for that case, use "get_valid".
1631 This function corresponds to "png_get_PLTE" in libpng.
1633 set_PLTE
1635 $png->set_PLTE ($palette);
1637 Set the palette of $png. The argument is an array reference containing
1639 hash references. There is one hash reference for each palette entry.
1640 The hash references contain three fields, red, green, and blue,
1641 corresponding to the pixel value for that palette entry. Other values
1642 in the hash references are ignored. For example,
1643 $png->set_PLTE ([{red => 1, green => 99, blue => 0x10},
1645 {red => 0xFF, green => 0xFF, blue => 0xFF}]);
1646 creates a palette with two entries in $png.
1648 This function corresponds to "png_set_PLTE" in libpng.
1650 sBIT
1652 See this subsection <http://www.w3.org/TR/PNG/#11sBIT> of "The PNG
1653 specification".
1654 get_sBIT
1656 my $sbit = $png->get_sBIT ();
1658 The return value is a hash reference containing integer values for the
1660 keys "red", "blue", "green", "gray" and "alpha", depending on the
1661 "color_type" of $png.
1662 âðĪŠâ Prior to version 0.50 of this module, get_sBIT wrote values of 0
1664 for all of the keys, regardless of the "color_type", causing errors in
1665 some circumstances. From version 0.50, hash keys are not entered if the
1666 "color_type" of the image makes them invalid.
1667 This function corresponds to "png_get_sBIT" in libpng
1669 set_sBIT
1671 $png->set_sBIT ({red => 1, blue => 2, green => 3});
1673 The argument is a hash reference containing integer values for the keys
1675 "red", "blue", "green", "gray", and "alpha", as required by the
1676 "color_type" of $png.
1677 This function corresponds to "png_set_sBIT" in libpng
1679 sCAL
1681 This is an extension to the PNG specification. See
1682 <http://www.libpng.org/pub/png/spec/1.1/pngext-1.1.0-pdg.html#C.sCAL>.
1683 To test whether your version of libpng supports "the sCAL chunk", use
1685 "libpng_supports" with argument '"sCAL"':
1686 if (libpng_supports ('sCAL')) {
1688 # do something
1689 }
1690 get_sCAL
1692 my $scal = $png->get_sCAL ();
1694 The returned hash value contains the following keys:
1696 unit
1698 The unit type, which is either PNG_SCALE_UNKNOWN, PNG_SCALE_METER,
1699 or PNG_SCALE_RADIAN.
1700 width
1702 The width, as a string.
1703 height
1705 The height, as a string.
1706 This function corresponds to "png_get_sCAL_s" in libpng. Note that this
1708 uses the sCAL_s function rather than the get_sCAL and the returned
1709 values are the strings themselves rather than parsed numbers.
1710 set_sCAL
1712 $png->set_sCAL ($scal);
1714 $scal is a hash reference containing the keys described in "get_sCAL".
1716 This function corresponds to "png_set_sCAL_s" in libpng. Note that this
1718 uses the "set_sCAL_s" function rather than "set_sCAL" and the input
1719 values are the strings themselves rather than numbers.
1720 sPLT
1722 See this subsection <http://www.w3.org/TR/PNG/#11sPLT> of "The PNG
1723 specification".
1724 get_sPLT
1726 âðĪŠâ Provisional. See "set_sPLT" for documentation, the return value is
1728 like the input of that.
1729 set_sPLT
1731 $png->set_sPLT ([{ name => 'palette', depth => 8, entries => [{red => 1, blue => 2},]}]);
1733 Set suggested palettes. The input is an array reference containing hash
1735 references with the following fields:
1736 name
1738 The name of the suggested palette.
1739 depth
1741 The depth of the suggested palette.
1742 entries
1744 The entries of the palette. This is an array reference containing
1745 hash references with keys as follows:
1746 red
1748 blue
1749 green
1750 frequency
1751 alpha
1752 The field "nentries" which is returned by "get_sPLT" does not need to
1754 be specified, it is calculated from the length of "entries".
1755 sRGB
1757 See this subsection <http://www.w3.org/TR/PNG/#11sRGB> of "The PNG
1758 specification".
1759 get_sRGB
1761 my $sRGB = $png->get_sRGB ();
1763 The return value is an integer number corresponding to one of the
1765 following:
1766 PNG_sRGB_INTENT_SATURATION
1768 PNG_sRGB_INTENT_PERCEPTUAL
1769 PNG_sRGB_INTENT_ABSOLUTE
1770 PNG_sRGB_INTENT_RELATIVE
1771 This function corresponds to "png_get_sRGB" in libpng
1773 set_sRGB
1775 $png->set_sRGB ($srgb);
1777 $srgb is one of the values described in "get_sRGB".
1779 This function corresponds to "png_set_sRGB" in libpng
1781 tIME
1783 See this subsection <http://www.w3.org/TR/PNG/#11timestampinfo> of "The
1784 PNG specification" for information on the PNG standards for time stamp
1785 information.
1786 get_tIME
1788 my $time = $png->get_tIME ();
1790 if ($time && $time->{year} < 2005) {
1791 warn "Your PNG is now getting old. Don't forget to oil it to prevent rust.";
1792 }
1793 The return value is either the undefined value, if no "tIME" chunk
1795 exists in the PNG, or a hash reference containing fields "year",
1796 "month", "day", "hour", "minute" and "second". "month" and "day" start
1797 from 1 rather than 0.
1798 The "modification time value" of the PNG image is a chunk written into
1800 the PNG file itself, and may not have the same value as the operating
1801 system's modification time for the file. The tIME chunk is not a
1802 compulsory requirement for PNG files, and most PNG image files do not
1803 contain this chunk. PNG tIME chunks do not contain a time zone.
1804 According to this subsection <http://www.w3.org/TR/PNG/#11tIME> of "The
1805 PNG specification", "Universal Time (UTC) should be specified rather
1806 than local time."
1807 This function corresponds to "png_get_tIME" in libpng, with a Perl hash
1809 reference substituted for the C struct "png_timep" used in libpng.
1810 set_tIME
1812 # Set the time to "now"
1814 $png->set_tIME ();
1815 # Set the time
1816 $png->set_tIME ({year => 1999, month => 12});
1817 Set the modification time of the PNG to the values given by the
1819 argument, a hash reference containing the fields "year", "month", "day"
1820 for the day of the month, "hour", "minute", and "second". The
1821 numbering for "month" and "day" is from 1, not 0. If any of year, hour,
1822 minute or second is omitted from the hash reference, these are set to
1823 zero. If month or day are omitted, these are set to 1. PNG tIME chunks
1824 do not contain a time zone. According to this subsection
1825 <http://www.w3.org/TR/PNG/#11tIME> of "The PNG specification",
1826 "Universal Time (UTC) should be specified rather than local time." If
1827 the entire argument is omitted or contains an invalid value, the time
1828 is set to the current time.
1829 This function corresponds to "png_set_tIME" in libpng, with a Perl hash
1831 reference substituted for the C struct "png_timep" used in libpng.
1832 tRNS
1834 See this subsection <http://www.w3.org/TR/PNG/#11tRNS> of "The PNG
1835 specification".
1836 get_tRNS
1838 my $trns = $png->get_tRNS ();
1840 Get the "tRNS" chunk. If the image is a palette type, this is an array
1842 reference. If the image is a non-palette type, this is a hash
1843 containing values for the keys red, green, blue, and gray.
1844 set_tRNS
1846 $png->set_tRNS ($trns);
1848 Set the "tRNS" chunk. If the image is a palette type, $trns is a
1850 reference to an array of positive or zero values between 0 and 255 of
1851 the same size as the palette. It must not contain more than 256 values.
1852 If the image is not a palette type, $trns is a hash reference
1853 containing values for the keys red, green, blue and gray.
1854
1856 set_bgr
1857 $png->set_bgr ();
1858 âðĪŠâ Untested. Flips RGB to BGR. See the libpng manual for details.
1860 To test whether your version of libpng supports "set_bgr", for a read
1862 object, use "libpng_supports" with argument '"READ_BGR"'.
1863 if (libpng_supports ('READ_BGR')) {
1865 # do something
1866 }
1867 For a write object, use argument '"WRITE_BGR"'.
1869 This function corresponds to "png_set_bgr" in libpng
1871 set_expand
1873 $png->set_expand ();
1874 Set transformation in $png such that paletted images are expanded to
1876 RGB, grayscale images of bit-depth less than 8 are expanded to 8-bit
1877 images, and tRNS chunks are expanded to alpha channels.
1878 To test whether your version of libpng supports "set_expand", use
1880 "libpng_supports" with argument '"READ_EXPAND"':
1881 if (libpng_supports ('READ_EXPAND')) {
1883 # do something
1884 }
1885 This function corresponds to "png_set_expand" in libpng
1887 set_expand_16
1889 $png->set_expand_16 ();
1890 âðĪŠâ Untested.
1892 To test whether your version of libpng supports "set_expand_16", use
1894 "libpng_supports" with argument '"READ_EXPAND_16"':
1895 if (libpng_supports ('READ_EXPAND_16')) {
1897 # do something
1898 }
1899 This function corresponds to "png_set_expand_16" in libpng
1901 set_expand_gray_1_2_4_to_8
1903 $png->set_expand_gray_1_2_4_to_8 ();
1904 âðĪŠâ Untested.
1906 To test whether your version of libpng supports
1908 "set_expand_gray_1_2_4_to_8", use "libpng_supports" with argument
1909 '"READ_EXPAND"':
1910 if (libpng_supports ('READ_EXPAND')) {
1912 # do something
1913 }
1914 This function corresponds to "png_set_expand_gray_1_2_4_to_8" in libpng
1916 set_gray_to_rgb
1918 $png->set_gray_to_rgb ();
1919 Convert a grayscale PNG file to RGB format on reading.
1921 To test whether your version of libpng supports "set_gray_to_rgb", use
1923 "libpng_supports" with argument '"READ_GRAY_TO_RGB"':
1924 if (libpng_supports ('READ_GRAY_TO_RGB')) {
1926 # do something
1927 }
1928 This function corresponds to "png_set_gray_to_rgb" in libpng
1930 set_invert_alpha
1932 $png->set_invert_alpha ();
1933 âðĪŠâ Untested. See the libpng manual for details.
1935 To test whether your version of libpng supports "set_invert_alpha", use
1937 "libpng_supports" with argument '"READ_INVERT_ALPHA"':
1938 if (libpng_supports ('READ_INVERT_ALPHA')) {
1940 # do something
1941 }
1942 This function corresponds to "png_set_invert_alpha" in libpng
1944 set_invert_mono
1946 $png->set_invert_mono ();
1947 Invert monochrome images. See the libpng manual for details.
1949 To test whether your version of libpng supports "set_invert_mono", use
1951 "libpng_supports" with argument '"READ_INVERT"':
1952 if (libpng_supports ('READ_INVERT')) {
1954 # do something
1955 }
1956 This function corresponds to "png_set_invert_mono" in libpng
1958 set_packing
1960 $png->set_packing ();
1961 When reading a PNG, expand the image to 1 pixel per byte for bit-depths
1963 1, 2 and 4 without changing the order of the pixels. If this is not
1964 called, the pixels of bit_depths 1, 2 and 4 are packed into bytes as
1965 small as possible, for example, 8 pixels per byte for 1-bit files. See
1966 the libpng manual for details. See also "set_packswap".
1967 To test whether your version of libpng supports "set_packing", for a
1969 read object, use "libpng_supports" with argument '"READ_PACK"'.
1970 if (libpng_supports ('READ_PACK')) {
1972 # do something
1973 }
1974 For a write object, use argument '"WRITE_PACK"'.
1976 This function corresponds to "png_set_packing" in libpng
1978 set_packswap
1980 $png->set_packswap ();
1981 Swaps the bits of 1, 2, or 4 bits/pixel images. The default for PNG
1983 image is to put the left pixel into the highest part of the byte, so
1984 for example if the bit depth is 1, the pixels from left to right go
1985 into a byte as values 128 for the leftmost, 64, 32, 16, 8, 4, 2, then 1
1986 for the rightmost pixel. This call reverses that behavior so that the
1987 pixels in a byte go 1 for the leftmost, 2, ..., then 128 for the
1988 rightmost. See the libpng manual for details.
1989 To test whether your version of libpng supports "set_packswap", for a
1991 read object, use "libpng_supports" with argument '"READ_PACKSWAP"'.
1992 if (libpng_supports ('READ_PACKSWAP')) {
1994 # do something
1995 }
1996 For a write object, use argument '"WRITE_PACKSWAP"'.
1998 This function corresponds to "png_set_packswap" in libpng
2000 set_palette_to_rgb
2002 $png->set_palette_to_rgb ();
2003 âðĪŠâ Untested. See the libpng manual for details.
2005 To test whether your version of libpng supports "set_palette_to_rgb",
2007 use "libpng_supports" with argument '"READ_EXPAND"':
2008 if (libpng_supports ('READ_EXPAND')) {
2010 # do something
2011 }
2012 This function corresponds to "png_set_palette_to_rgb" in libpng
2014 set_scale_16
2016 $png->set_scale_16 ()
2017 âðĪŠâ Untested.
2019 To test whether your version of libpng supports "set_scale_16", use
2021 "libpng_supports" with argument '"READ_SCALE_16_TO_8"':
2022 if (libpng_supports ('READ_SCALE_16_TO_8')) {
2024 # do something
2025 }
2026 This function corresponds to "png_set_scale_16" in libpng
2028 set_strip_16
2030 $png->set_strip_16 ();
2031 Strip the pixels of a PNG stream with 16 bits per channel to 8 bits per
2033 channel.
2034 To test whether your version of libpng supports "set_strip_16", use
2036 "libpng_supports" with argument '"READ_STRIP_16_TO_8"':
2037 if (libpng_supports ('READ_STRIP_16_TO_8')) {
2039 # do something
2040 }
2041 This function corresponds to "png_set_strip_16" in libpng
2043 set_strip_alpha
2045 $png->set_strip_alpha ();
2046 Strip the alpha channel of a PNG stream.
2048 To test whether your version of libpng supports "set_strip_alpha", use
2050 "libpng_supports" with argument '"READ_STRIP_ALPHA"':
2051 if (libpng_supports ('READ_STRIP_ALPHA')) {
2053 # do something
2054 }
2055 This function corresponds to "png_set_strip_alpha" in libpng
2057 set_swap
2059 $png->set_swap ();
2060 âðĪŠâ Untested. Swaps around the bytes of 16 bits/pixel images. See the
2062 libpng manual for details.
2063 To test whether your version of libpng supports "set_swap", use
2065 "libpng_supports" with argument '"READ_SWAP"':
2066 if (libpng_supports ('READ_SWAP')) {
2068 # do something
2069 }
2070 This function corresponds to "png_set_swap" in libpng
2072 set_swap_alpha
2074 $png->set_swap_alpha ();
2075 âðĪŠâ Untested. See the libpng manual for details.
2077 To test whether your version of libpng supports "set_swap_alpha", use
2079 "libpng_supports" with argument '"READ_SWAP_ALPHA"':
2080 if (libpng_supports ('READ_SWAP_ALPHA')) {
2082 # do something
2083 }
2084 This function corresponds to "png_set_swap_alpha" in libpng
2086 set_tRNS_to_alpha
2088 $png->set_tRNS_to_alpha
2089 âðĪŠâ Untested. See the libpng manual for details.
2091 To test whether your version of libpng supports "set_tRNS_to_alpha",
2093 use "libpng_supports" with argument '"READ_EXPAND"':
2094 if (libpng_supports ('READ_EXPAND')) {
2096 # do something
2097 }
2098 This function corresponds to "png_set_tRNS_to_alpha" in libpng
2100
2102 get_chunk_cache_max
2103 my $max = $png->get_chunk_cache_max ();
2104 Get the maximum number of ancilliary chunks allowed. See also
2106 "set_chunk_cache_max".
2107 To test whether your version of libpng supports "get_chunk_cache_max",
2109 use "libpng_supports" with argument '"CHUNK_CACHE_MAX"':
2110 if (libpng_supports ('CHUNK_CACHE_MAX')) {
2112 # do something
2113 }
2114 This function corresponds to "png_png_get_chunk_cache_max" in libpng
2116 get_rgb_to_gray_status
2118 my $badpixels = $png->get_rgb_to_gray_status ();
2119 Returns a true value if there were some non-gray pixels in an RGB image
2121 after calling "set_rgb_to_gray".
2122 Saving bandwidth
2124 Try this one weird old "get_rgb_to_gray_status" trick to check whether
2126 an image marked as RGB is really monochrome or not.
2127 use utf8;
2129 use FindBin '$Bin';
2130 use Image::PNG::Libpng ':all';
2131 use Image::PNG::Const ':all';
2132 my $file = 'life.png';
2134 print "Size before: ", -s $file, "\n";
2135 my $png = create_reader ($file);
2136 $png->read_info ();
2137 $png->set_rgb_to_gray ();
2138 if ($png->get_rgb_to_gray_status ()) {
2139 print "The image contained non-gray pixels.\n";
2140 }
2141 else {
2142 print "The image was grayscale already.\n";
2143 }
2144 $png->read_image ();
2145 $png->read_end ();
2146 my $wpng = $png->copy_png ();
2147 my $ihdr = $wpng->get_IHDR ();
2148 $ihdr->{color_type} = PNG_COLOR_TYPE_GRAY;
2149 $wpng->set_IHDR ($ihdr);
2150 my $after = "life-gray.png";
2151 $wpng->write_png_file ($after);
2152 print "Size after: ", -s $after, "\n";
2153 if (! png_compare ($file, $after)) {
2155 print "The two files contain exactly the same image data.\n";
2156 }
2157 else {
2158 print "The two files contain different image data.\n";
2159 }
2160 (This example is included as examples/xkcd.pl
2162 <https://fastapi.metacpan.org/source/BKB/Image-PNG-
2163 Libpng-0.57/examples/xkcd.pl> in the distribution.)
2164 The output looks like this:
2166 Size before: 97299
2168 The image was grayscale already.
2169 Size after: 46956
2170 The two files contain exactly the same image data.
2171 examples/life-gray.png <https://fastapi.metacpan.org/source/BKB/Image-
2173 PNG-Libpng-0.57/examples/life-gray.png> is included in the
2174 distribution.
2175 Correct use of Image::PNG::Libpng could have spared as many as 50,000
2177 bytes from the indignity of being sent around the internet.
2178 This also illustrates the use of "png_compare".
2180 Original image, licence statement and copyright notice here
2182 <https://xkcd.com/2391/>.
2183 get_user_height_max
2185 $png->get_user_height_max ();
2186 Get the maximum height allowed for a PNG file. The default is 1 million
2188 pixels. These values can be changed by "set_user_limits".
2189 This function corresponds to "png_get_user_height_max" in libpng
2191 get_user_width_max
2193 $png->get_user_width_max ();
2194 Get the maximum width allowed for a PNG file. The default is 1 million
2196 pixels. These values can be changed by "set_user_limits".
2197 This function corresponds to "png_get_user_width_max" in libpng
2199 permit_mng_features
2201 $png->permit_mng_features ($mask);
2202 âðĪŠâ Untested. $mask is an integer containing flags. See the libpng
2204 manual for details.
2205 (MNG, 'Multiple-image Network Graphics', is an image animation format
2207 related to PNG. It has not been widely adopted.)
2208 To test whether your version of libpng supports "permit_mng_features",
2210 use "libpng_supports" with argument '"MNG_FEATURES"':
2211 if (libpng_supports ('MNG_FEATURES')) {
2213 # do something
2214 }
2215 This function corresponds to "png_permit_mng_features" in libpng
2217 set_add_alpha
2219 $png->set_add_alpha ($filler, $filler_loc);
2220 âðĪŠâ Untested. Change $png to add an alpha channel. This only works for
2222 grayscale or RGB images with bit depth of 8 or 16. $filler contains the
2223 alpha value to assign to each pixel, and $filler_loc is either
2224 "PNG_FILLER_BEFORE" or "PNG_FILLER_AFTER". The function of
2225 "set_add_alpha" is "set_filler" and a change of the color type to add
2226 an alpha channel. See the libpng manual for details.
2227 To test whether your version of libpng supports "set_add_alpha", use
2229 "libpng_supports" with argument '"READ_FILLER"':
2230 if (libpng_supports ('READ_FILLER')) {
2232 # do something
2233 }
2234 This function corresponds to "png_set_add_alpha" in libpng
2236 set_alpha_mode
2238 $png->set_alpha_mode ($mode, $screen_gamma);
2239 âðĪŠâ Untested. $mode is an integer, one of the "PNG_ALPHA_*" constants.
2241 $screen_gamma is a floating point number. See the libpng manual for
2242 details.
2243 To test whether your version of libpng supports "set_alpha_mode", use
2245 "libpng_supports" with argument '"READ_ALPHA_MODE"':
2246 if (libpng_supports ('READ_ALPHA_MODE')) {
2248 # do something
2249 }
2250 This function corresponds to "png_set_alpha_mode" in libpng
2252 set_background
2254 $png->set_background (\%color, $bkgd_gamma_code, $need_expand, $gamma);
2255 "set_background" sets the background of an image with an alpha channel
2257 or simple transparency (a "tRNS" chunk) with the color specified by
2258 %color. If $bkgd_gamma_code is set to "PNG_BACKGROUND_GAMMA_SCREEN", it
2259 indicates that the supplied background color is in the gamma space of
2260 the display, else if it is set to "PNG_BACKGROUND_GAMMA_FILE", the
2261 color is in the gamma space of the file. If $bkgd_gamma_code is set to
2262 "PNG_BACKGROUND_GAMMA_UNIQUE", the value of $gamma is used, otherwise
2263 $gamma appears to be ignored and can be omitted. (This is not
2264 documented in the libpng manual or elsewhere. See
2265 <https://github.com/glennrp/libpng/issues/358>.)
2266 If the background color is supplied at the original bit-depth for a
2268 grayscale image that is expanded to truecolor or to a higher bit-depth,
2269 $need_expand must be set to a true value, but if the background color
2270 is supplied at the expanded bit-depth, $need_expand must be set to a
2271 false value. Similarly for paletted images, if %color is supplied as a
2272 palette index ($color{index}), $need_expand must be set to a true
2273 value, but if %color is an RGB triplet, $need_expand must be set to a
2274 false value.
2275 See "Setting the background" for an example.
2277 To test whether your version of libpng supports "set_background", use
2279 "libpng_supports" with argument '"READ_BACKGROUND"':
2280 if (libpng_supports ('READ_BACKGROUND')) {
2282 # do something
2283 }
2284 set_chunk_cache_max
2286 $png->set_chunk_cache_max (42);
2287 Set the maximum number of ancilliary chunks allowed. The default is
2289 1000. See also "get_chunk_cache_max".
2290 To test whether your version of libpng supports "set_chunk_cache_max",
2292 use "libpng_supports" with argument '"CHUNK_CACHE_MAX"':
2293 if (libpng_supports ('CHUNK_CACHE_MAX')) {
2295 # do something
2296 }
2297 This function corresponds to "png_png_set_chunk_cache_max" in libpng
2299 set_filler
2301 $png->set_filler ($filler, $flags);
2302 Set transformations in $png such that a filler byte $filler is added
2304 when an 8-bit grayscale image or 24-bit RGB image is read, and a filler
2305 byte is deleted when an 8-bit grayscale image or 24-bit RGB image is
2306 written. $flags may be "PNG_FILLER_BEFORE" or "PNG_FILLER_AFTER". An
2307 error is produced if $png has bit depth less than 8.
2308 This does not change the color type of the image. See the related
2310 function "set_add_alpha" if you want to add an alpha channel.
2311 To test whether your version of libpng supports "set_filler", use
2313 "libpng_supports" with argument '"READ_FILLER"':
2314 if (libpng_supports ('READ_FILLER')) {
2316 # do something
2317 }
2318 This function corresponds to "png_set_filler" in libpng
2320 set_gamma
2322 $png->set_gamma ($screen_gamma, $output_gamma);
2323 âðĪŠâ Untested. $screen_gamma and $output_gamma should contain floating-
2325 point arguments. See the libpng manual for details.
2326 To test whether your version of libpng supports "set_gamma", use
2328 "libpng_supports" with argument '"READ_GAMMA"':
2329 if (libpng_supports ('READ_GAMMA')) {
2331 # do something
2332 }
2333 This function corresponds to "png_set_gamma" in libpng
2335 set_quantize
2337 $png->set_quantize (\@palette, $ncolors, \@histogram, $full_quantize);
2338 The @palette part must be set to a palette similar to "set_PLTE".
2340 $ncolors must be the length of @palette or shorter. @histogram can be
2341 an empty array or if not it needs to be an array of integers of exactly
2342 the same length as @palette. The integers represent the frequency of
2343 the colors in @palette. These integers can range from 0 to 65355.
2344 Larger values or negative values cause an error. The final argument,
2345 $full_quantize, should be 1 for RGB images or 0 for paletted images.
2346 Experiments in quantization
2348 This example program experiments with two ways to quantize a PNG image,
2350 first of all using a completely random palette, and second using colors
2351 picked from the image at random:
2352 use utf8;
2354 use FindBin '$Bin';
2355 use Image::PNG::Libpng ':all';
2356 my $file = "wave.png";
2357 my $ncolors = 40;
2358 my $palette = randompalette ($ncolors);
2359 write_with_palette ($file, $palette, $ncolors, [], "random");
2360 my $picked = points ($file, $ncolors);
2361 my @hist = (1) x $ncolors;
2362 write_with_palette ($file, $picked, $ncolors, \@hist, "picked");
2363 exit;
2364 sub write_with_palette
2366 {
2367 my ($file, $palette, $ncolors, $hist, $name) = @_;
2368 my $rpng = create_reader ($file);
2369 $rpng->set_quantize ($palette, $ncolors, $hist, 1);
2370 $rpng->read_png ();
2371 my $wpng = copy_png ($rpng);
2372 $wpng->set_PLTE ($palette);
2373 $wpng->write_png_file ("$name-$file");
2374 }
2375 sub points
2377 {
2378 my ($pngfile, $ncolors) = @_;
2379 my $png = read_png_file ($pngfile);
2380 my $rows = $png->get_rows ();
2381 my $h = $png->height ();
2382 my $w = $png->width ();
2383 my $ch = $png->get_channels ();
2384 my @p;
2385 for (0..$ncolors-1) {
2386 my $x = int (rand ($w));
2387 my $y = int (rand ($h));
2388 my $row = $rows->[$y];
2389 my @pix = split ('', substr ($row, $x*$ch, $ch));
2390 push @p, {
2391 red => ord ($pix[0]),
2392 green => ord ($pix[1]),
2393 blue => ord ($pix[2]),
2394 };
2395 }
2396 return \@p;
2397 }
2398 sub randompalette
2400 {
2401 my ($n) = @_;
2402 my @p;
2403 for (0..$n-1) {
2404 my %color;
2405 for my $c (qw!red green blue!) {
2406 $color{$c} = int (rand (256))
2407 }
2408 push @p, \%color;
2409 }
2410 return \@p;
2411 }
2412 (This example is included as examples/q.pl
2414 <https://fastapi.metacpan.org/source/BKB/Image-PNG-
2415 Libpng-0.57/examples/q.pl> in the distribution.)
2416 examples/wave.png <https://fastapi.metacpan.org/source/BKB/Image-PNG-
2418 Libpng-0.57/examples/wave.png> is included in the distribution.
2419 examples/random-wave.png
2421 <https://fastapi.metacpan.org/source/BKB/Image-PNG-
2422 Libpng-0.57/examples/random-wave.png> is included in the distribution.
2423 examples/picked-wave.png
2425 <https://fastapi.metacpan.org/source/BKB/Image-PNG-
2426 Libpng-0.57/examples/picked-wave.png> is included in the distribution.
2427 set_rgb_to_gray
2429 $png->set_rgb_to_gray ();
2430 $png->set_rgb_to_gray ($error_action, $red_weight, $green_weight);
2432 Convert a PNG image from RGB (colored) to gray. See the libpng manual
2434 for details.
2435 Without arguments, the libpng default values are used for $red_weight
2437 and $green_weight, and an error action of "none" is chosen. If the
2438 error action is set to a value of "PNG_ERROR_ACTION_WARN" or
2439 "PNG_ERROR_ACTION_ERROR", pixels in the RGB image where the R, G and B
2440 values are not equal will cause a warning or error respectively. To get
2441 the default values for $red_weight or $green_weight, use any negative
2442 value. See the libpng manual for details.
2443 If you choose "PNG_ERROR_ACTION_NONE" you can find out whether there
2445 were non-RGB pixels in your image using "get_rgb_to_gray_status".
2446 This function corresponds to "png_png_set_rgb_to_gray" in libpng with
2448 $error_action having a default value of "PNG_ERROR_ACTION_NONE", and
2449 $red_weight and $green_weight both set to negative values.
2450 Convert a colored image to gray
2452 use utf8;
2454 use FindBin '$Bin';
2455 use Image::PNG::Libpng ':all';
2456 use Image::PNG::Const ':all';
2457 my $png = create_reader ("$Bin/luv.png");
2459 $png->read_info ();
2460 $png->set_rgb_to_gray ();
2461 $png->read_image ();
2462 $png->read_end ();
2463 my $wpng = $png->copy_png ();
2464 my $ihdr = $wpng->get_IHDR ();
2465 $ihdr->{color_type} = PNG_COLOR_TYPE_GRAY_ALPHA;
2466 $wpng->set_IHDR ($ihdr);
2467 $wpng->write_png_file ("$Bin/grayface.png");
2468 (This example is included as examples/rgb-to-gray.pl
2470 <https://fastapi.metacpan.org/source/BKB/Image-PNG-
2471 Libpng-0.57/examples/rgb-to-gray.pl> in the distribution.)
2472 examples/grayface.png <https://fastapi.metacpan.org/source/BKB/Image-
2474 PNG-Libpng-0.57/examples/grayface.png> is included in the distribution.
2475 set_user_limits
2477 $png->set_user_limits ($width, $height);
2478 This enables a user to override libpng's restrictions to one million
2480 pixels in width and one million pixels in height for a PNG image.
2481 This function corresponds to "png_set_user_limits" in libpng
2483
2485 This section contains other functions which don't correspond to
2486 anything in libpng itself, but which have been added to the module for
2487 utility.
2488 any2gray8
2490 my $wpng = any2gray8 ("any.png");
2491 Convert any type of PNG file whatsoever into a bit-depth 8 grayscale
2493 image without an alpha channel (PNG_COLOR_TYPE_GRAY). The return value
2494 is a writing structure as made by "create_write_struct".
2495 Currently the "tRNS" chunk is ignored by this.
2497 By default the alpha channel is set to either the value of the "bKGD"
2499 chunk if there is one, or white if not. You can set another background
2500 using the option "bkgd":
2501 my $wpng = any2gray8 ('any.png', bkgd => {red => 255, green => 0, blue => 99});
2503 This will of course be ignored if any.png does not contain an alpha
2505 channel. RGB to gray conversion is done using "set_rgb_to_gray" with
2506 the default values.
2507 This function is not supported for versions of libpng earlier than
2509 1.6.14.
2510 color_type_channels
2512 my $channels = color_type_channels ('PNG_COLOR_TYPE_RGB_ALPHA');
2513 Returns the number of channels (the number of components of one pixel)
2515 of the specified color type.
2516 copy_row_pointers
2518 $png->copy_row_pointers ($row_pointers);
2519 This allows XS routines to directly set the value of the row pointers
2521 for the PNG image. The memory is copied, so whatever is in the row
2522 pointers can be freed immediately after calling this. However, the
2523 image data it points to is not copied, so this needs to be valid until
2524 the PNG is written.
2525 The Perl scalar $row_pointers should be set up something like the
2527 following (where "rp" is the C pointer):
2528 RETVAL = newSViv (PTR2IV (rp));
2530 It's extracted from the Perl scalar using
2532 rp = INT2PTR (png_byte **, SvIV (row_pointers));
2534 where row_pointers is the "SV *" corresponding to $row_pointers in the
2536 Perl script. See also "set_row_pointers" which does the same thing but
2537 takes ownership of the memory.
2538 get_chunk
2540 my $timechunk = $png->get_chunk ('tIME');
2541 Get the specified chunk. This produces a fatal error if asked for the
2543 "IDAT" (image data) chunk, use "get_rows" instead. Returns "undef" if
2544 asked for an unknown chunk name.
2545 This is used by pnginspect to get the valid chunks. See also
2547 "set_chunk".
2548 get_internals
2550 my ($png_struct, $png_info) = get_internals ($png);
2551 This function returns the "png_structp" and "png_infop" contained in
2553 $png. The return value is a list containing the "png_structp" as the
2554 first argument and the "png_infop" as the second argument, wrapped up
2555 as references to objects of type "Image::PNG::Libpng::png_struct" and
2556 "Image::PNG::Libpng::png_info".
2557 To access the values of the pointers, use something like this:
2559 void access_png_internals (png, info)
2561 SV * png;
2562 SV * info;
2563 PREINIT:
2564 png_struct * cpng;
2565 png_info * cinfo;
2566 CODE:
2567 cpng = INT2PTR (png_struct *, SvIV (png));
2568 cinfo = INT2PTR (png_info *, SvIV (info));
2569 An example exists in Image::PNG::Cairo.
2571 get_tRNS_palette
2573 $png->get_tRNS_palette ();
2574 This is not a libpng-equivalent function.
2576 image_data_diff
2578 my $diff = image_data_diff ('a.png', 'b.png');
2579 This returns the undefined value if the image data in a.png is the same
2581 as the image data in b.png. If the image data is different, it returns
2582 a readable text message describing the first difference found, for
2583 example the height is different, or row 0 of the image data is
2584 different, etc.
2585 This function is used in testing this module. See also "png_compare".
2587 libpng_supports
2589 if (libpng_supports ('iTXt')) {
2590 print "Your libpng supports international text.\n";
2591 }
2592 This function returns true or false depending on whether the version of
2594 libpng which this was compiled with supports or does not support a
2595 particular facility. For the most part, these are taken directly from
2596 the C macros of libpng.
2597 The possible arguments to "libpng_supports" are:
2599 16BIT
2601 ALIGNED_MEMORY
2602 ARM_NEON_API
2603 BENIGN_ERRORS
2604 BENIGN_READ_ERRORS
2605 BENIGN_WRITE_ERRORS
2606 bKGD
2607 Does the libpng support the "bKGD" chunk?
2608 BUILD_GRAYSCALE_PALETTE
2610 BUILTIN_BSWAP16
2611 CHECK_FOR_INVALID_INDEX
2612 cHRM
2613 Does the libpng support the "cHRM" chunk?
2614 cHRM_XYZ
2616 This is local to Image::PNG::Libpng and not a part of libpng
2617 itself.
2618 It was necessary to extend libpng because the conditional
2620 compilation macro for "set_cHRM_XYZ" and "get_cHRM_XYZ",
2621 "PNG_cHRM_SUPPORTED" is defined (true) for old libpngs which do not
2622 actually contain these functions.
2623 CHUNK_CACHE_MAX
2625 This is local to Image::PNG::Libpng and not a part of libpng
2626 itself.
2627 It was necessary to extend libpng because the conditional
2629 compilation macro for "set_chunk_cache_max" and
2630 "get_chunk_cache_max", "PNG_USER_LIMITS_SUPPORTED" is defined
2631 (true) for old libpngs which do not actually contain these
2632 functions.
2633 CHUNK_MALLOC_MAX
2635 This is local to Image::PNG::Libpng and not a part of libpng
2636 itself.
2637 The reasons for this are identical to those for "CHUNK_CACHE_MAX".
2639 COLORSPACE
2641 CONSOLE_IO
2642 CONVERT_tIME
2643 This is related to two deprecated functions,
2644 "png_convert_from_time_t" and "png_convert_from_struct_tm".
2645 CONVERT_tIME
2647 EASY_ACCESS
2648 ERROR_NUMBERS
2649 ERROR_TEXT
2650 eXIf
2651 Does the libpng support the "eXIf" chunk?
2652 FIXED_POINT
2654 FIXED_POINT_MACRO
2655 FLOATING_ARITHMETIC
2656 FLOATING_POINT
2657 FORMAT_AFIRST
2658 FORMAT_BGR
2659 gAMA
2660 Does the libpng support the "gAMA" chunk?
2661 GAMMA
2663 GET_PALETTE_MAX
2664 Does your libpng support "get_palette_max"?
2665 HANDLE_AS_UNKNOWN
2667 HANDLE_AS_UNKNOWN
2668 hIST
2669 Does the libpng support the "hIST" chunk?
2670 iCCP
2672 Does the libpng support the "iCCP" chunk?
2673 INCH_CONVERSIONS
2675 INFO_IMAGE
2676 IO_STATE
2677 iTXt
2678 Does the libpng support international text?
2679 MIPS_MSA_API
2681 MNG_FEATURES
2682 oFFs
2683 Does the libpng support the "oFFs" chunk?
2684 pCAL
2686 Does the libpng support the "pCAL" extension?
2687 PEDANTIC_WARNINGS
2689 pHYs
2690 Does the libpng support the "pHYs" chunk?
2691 POINTER_INDEXING
2693 POWERPC_VSX_API
2694 PROGRESSIVE_READ
2695 READ
2696 Can libpng read PNGs?
2697 READ_16_TO_8
2699 READ_ALPHA_MODE
2700 See "set_alpha_mode".
2701 READ_BACKGROUND
2703 See "set_background".
2704 READ_BGR
2706 See "set_bgr".
2707 READ_COMPOSITE_NODIV
2709 READ_COMPRESSED_TEXT
2710 READ_EXPAND
2711 READ_EXPAND_16
2712 READ_FILLER
2713 READ_GAMMA
2714 See "set_gamma".
2715 READ_GRAY_TO_RGB
2717 READ_INTERLACING
2718 READ_INT_FUNCTIONS
2719 READ_INVERT
2720 READ_INVERT_ALPHA
2721 READ_OPT_PLTE
2722 READ_PACK
2723 READ_PACKSWAP
2724 READ_QUANTIZE
2725 READ_RGB_TO_GRAY
2726 READ_SCALE_16_TO_8
2727 READ_SHIFT
2728 READ_STRIP_16_TO_8
2729 READ_STRIP_ALPHA
2730 READ_SWAP
2731 READ_SWAP_ALPHA
2732 READ_tEXt
2733 READ_TRANSFORMS
2734 READ_USER_TRANSFORM
2735 READ_zTXt
2736 SAVE_INT_32
2737 SAVE_UNKNOWN_CHUNKS
2738 sBIT
2739 Does the libpng support the "sBIT" chunk?
2740 sCAL
2742 Does the libpng support the "sCAL" extension? This actually tests
2743 for the presence of the "get_sCAL_s"/"set_sCAL_s" functions, so its
2744 behaviour is dependent on other factors for versions 1.2 and 1.4 of
2745 libpng.
2746 SEQUENTIAL_READ
2748 SETJMP
2749 SET_OPTION
2750 SET_UNKNOWN_CHUNKS
2751 SET_USER_LIMITS
2752 SIMPLIFIED_READ
2753 SIMPLIFIED_READ_AFIRST
2754 SIMPLIFIED_WRITE
2755 SIMPLIFIED_WRITE_AFIRST
2756 SIMPLIFIED_WRITE_BGR
2757 SIMPLIFIED_WRITE_STDIO
2758 sPLT
2759 Does the libpng support "sPLT" chunks?
2760 sRGB
2762 Does the libpng support the "sRGB" chunk?
2763 STDIO
2765 STORE_UNKNOWN_CHUNKS
2766 TEXT
2767 Does the libpng support text?
2768 tEXt
2770 Does the libpng support tEXt chunks?
2771 tIME
2773 Does the libpng support the "tIME" chunk?
2774 TIME_RFC1123
2776 tRNS
2777 Does the libpng support the "tRNS" chunk?
2778 UNKNOWN_CHUNKS
2780 Does the libpng support unknown chunks (see "Private chunks")?
2781 USER_CHUNKS
2783 USER_LIMITS
2784 Does the libpng support "set_user_limits" and the related functions
2785 "get_user_width_max", and "get_user_height_max"?
2786 USER_LIMITS
2788 USER_MEM
2789 USER_TRANSFORM_INFO
2790 USER_TRANSFORM_PTR
2791 WARNINGS
2792 WRITE
2793 Can libpng write pngs?
2794 WRITE_BGR
2796 WRITE_COMPRESSED_TEXT
2797 WRITE_CUSTOMIZE_COMPRESSION
2798 Does the libpng support "set_compression_level" and similar
2799 functions?
2800 âðĪŠâ It's not very clear that this returns a useful value, since
2802 "set_compression_level" seems to be in libpngs from at least as far
2803 back as 1.5.1, and yet this macro was only added to libpng in
2804 version 1.6.13.
2805 WRITE_CUSTOMIZE_ZTXT_COMPRESSION
2807 Does the libpng support "set_text_compression_level" and similar
2808 functions?
2809 WRITE_FILLER
2811 WRITE_FILTER
2812 WRITE_FLUSH
2813 WRITE_FLUSH_AFTER_IEND
2814 WRITE_INTERLACING
2815 WRITE_INT_FUNCTIONS
2816 WRITE_INVERT
2817 WRITE_INVERT_ALPHA
2818 WRITE_OPTIMIZE_CMF
2819 WRITE_PACK
2820 WRITE_PACKSWAP
2821 WRITE_SHIFT
2822 WRITE_SWAP
2823 WRITE_SWAP_ALPHA
2824 WRITE_TRANSFORMS
2825 WRITE_USER_TRANSFORM
2826 WRITE_WEIGHTED_FILTER
2827 zTXt
2828 Does the libpng support "zTXt" chunks?
2829 png_compare
2831 if (png_compare ('a.png', 'b.png') == 0) {
2832 print "The PNGs are the same.\n";
2833 }
2834 This compares the image data in two PNGs and returns 0 if they contain
2836 exactly the same image data, or 1 if they contain different image data.
2837 For a more detailed comparison, see "image_data_diff". This does not
2838 compare to see if the PNG files "look like" each other, but whether
2839 each pixel contains exactly the same values. Please see Image::Similar
2840 for a looser comparison of images.
2841 This uses the "expand" transform of libpng to read both the images, so
2843 it is able to compare images of different color types. It compares the
2844 alpha values as well as the color pixels. See "Saving bandwidth" for an
2845 example of comparing an RGB and a grayscale image.
2846 read_struct
2848 if ($png->read_struct ()) {
2849 warn "Can't write this, use copy_png to copy it";
2850 }
2851 This returns a true value if $png was created with "create_read_struct"
2853 or allied functions like "read_from_scalar", and a false value if $png
2854 was created with "create_write_struct" or allied functions like
2855 "copy_png".
2856 set_chunk
2858 $png->set_chunk ('tIME', $timechunk);
2859 Set the specified chunk. This produces a fatal error if given an "IDAT"
2861 (image data) chunk, use "set_rows" instead. This produces a fatal error
2862 if given an unknown chunk name.
2863 The first argument is the chunk name and then the second argument is a
2865 scalar containing whatever the chunk requires, for example a hash
2866 reference for the "tIME" chunk as described under "set_tIME" and
2867 "get_tIME".
2868 This is essentially a convenience function for the benefit of
2870 "copy_png" which, together with "get_valid", enables the PNG chunks to
2871 be copied in a loop rather than one-by-one.
2872 set_image_data
2874 $png->set_image_data ($image_data);
2875 Set the internal image data pointer to $image_data. $image_data should
2877 contain a pointer to memory stored as an "SvIV" allocated with "Newx"
2878 or a similar function. This transfers ownership of the memory to $png,
2879 which will free it with "Safefree" when $png is destroyed. Calling this
2880 function with any value does not actually change the content of the PNG
2881 image itself.
2882 set_row_pointers
2884 $png->set_row_pointers ($row_pointers);
2885 This sets the rows of the PNG image to $row_pointers using
2887 "png_set_rows". $row_pointers must contain a pointer to memory stored
2888 as an SvIV allocated with a Perl memory allocator like "Newx" or a
2889 similar function. This also transfers ownership of the memory to $png,
2890 which will free it with "Safefree" when $png is destroyed. See also
2891 "copy_row_pointers", which does the same thing except for the freeing
2892 of the memory.
2893 split_alpha
2895 my $split = $png->split_alpha ();
2896 my $alpha = $split->{alpha};
2897 my $color = $split->{data};
2898 Split the alpha channel away from the other data. This only works for
2900 images with color types "PNG_COLOR_TYPE_RGB_ALPHA" and
2901 "PNG_COLOR_TYPE_GRAY_ALPHA". This is not part of the libpng API. This
2902 function was added to this module to assist the author of PDF::Builder
2903 due to problems with very slow access to PNG images using Perl.
2904 To remove the alpha channel from an image, use "set_background". See
2906 "Setting the background" for an example. You can also use the transform
2907 "PNG_TRANSFORM_STRIP_ALPHA" in "read_png_file", or "set_strip_alpha",
2908 but this may leave spurious pixel values in transparent parts of the
2909 image.
2910
2912 Nothing is exported by default, but all the functions in this module,
2913 including the object methods, can be exported on request. The export
2914 tag 'all' exports everything in the module:
2915 use Image::PNG::Libpng ':all';
2917 This includes all the methods, which can then be used with the $png
2919 argument as the first argument.
2920
2922 The functions in Image::PNG::Libpng are closely based on those of
2923 libpng, with the following differences.
2924 No info structure
2926 This module does not use the "info" structure of libpng. Almost all
2927 libpng functions require two initial arguments, a "png_structp" and a
2928 "png_infop". However, in Image::PNG::Libpng, both the "png" and the
2929 "info" are contained in the object. People who need access to the
2930 internals of an "Image::PNG::Libpng" object (C programmers or XS
2931 programmers) can use "get_internals" to access them.
2932 This module does not support the "end info" structure of PNGs when
2934 writing, although these are handled when reading.
2935 Unused arguments omitted
2937 This module eliminates unevaluated arguments of libpng. For example,
2938 libpng requires the user to pass a pointer to a "png_struct" to call
2939 the libpng version number function, (see "get_libpng_ver"), but it
2940 actually ignores this structure. There are many similar instances of
2941 unevaluated arguments, which have all been eliminated from this module.
2942 If you are interested in exactly which libpng arguments are omitted,
2944 you can find each instance in the file "perl-libpng.c" in the top
2945 directory of the distribution
2946 <https://fastapi.metacpan.org/source/BKB/Image-PNG-Libpng-0.57/perl-
2947 libpng.c> in the macro "UNUSED_ZERO_ARG".
2948 Useless functions omitted
2950 The functions from libpng which don't do anything have been omitted
2951 from this module.
2952 Function return values are used to return values
2954 libpng is very inconsistent in its calling conventions. Some functions
2955 return results using references, and some return results using the
2956 function's return value. For example "png_get_rows" (see "get_rows")
2957 uses the return value of the function to return an array of pointers,
2958 but "png_get_PLTE" (see "get_PLTE") uses a pointer reference to return
2959 an array of pointers, and the return value to indicate errors.
2960 Image::PNG::Libpng uses only the return value. Errors and non-existence
2962 are indicated by a return value of the undefined value.
2963 Further to this, libpng's error handling is also very inconsistent.
2965 Some functions use the return value to indicate errors, and some of the
2966 functions don't indicate errors at all, but just fail silently. Even
2967 more inconsistently, some of the functions which use the return value
2968 to indicate an error use a non-zero value, and some use a zero value,
2969 to indicate an error.
2970 No destructors
2972 Freeing the memory allocated by "create_read_struct" and
2973 "create_write_struct" is automatically handled by Perl.
2974 Older versions of this module (pre-0.18) had functions called
2976 "destroy_read_struct" and "destroy_write_struct" corresponding to the
2977 functions with similar names in libpng. From version 0.18, these
2978 functions still exist, but they no longer do anything. The memory
2979 freeing is now handled by Perl automatically.
2980 Other unimplemented parts of libpng
2982 Memory management functions
2983 The management of memory for libpng objects is handled
2984 automatically by this module, and so it does not offer an interface
2985 to "png_malloc" and "png_free" or other libpng memory handling
2986 functions.
2987 Error handling functions
2989 This module does not offer an interface to "png_error" and
2990 "png_get_error_ptr" or any of the other error handling functions of
2991 libpng. It redirects the error and warning handlers to Perl's error
2992 stream.
2993 Input/output manipulation functions
2995 This module does not offer a direct interface to "png_set_write_fn"
2996 and "png_set_read_fn". However, it is possible to use their
2997 functionality to access Perl data via "read_from_scalar" and
2998 "write_to_scalar".
2999 Fixed point functions
3001 There is currently no support for the PNG fixed point functions in
3002 this Perl module, the functions with suffix "_fixed".
3003 List of unsupported functions
3005 The following functions from the libpng API are unsupported by this
3006 module.
3007 png_benign_error
3009 ð See "Error handling functions".
3010 png_build_grayscale_palette
3012 âðĪŠâ Undocumented function, but it is part of the public API. See
3013 <https://github.com/glennrp/libpng/issues/353>.
3014 This function builds an evenly-spaced grayscale palette at a
3016 specified bit depth into a user-supplied array. It is not used
3017 elsewhere in libpng.
3018 png_chunk_benign_error
3020 ð See "Error handling functions".
3021 png_chunk_warning
3023 ð See "Error handling functions".
3024 png_convert_from_struct_tm
3026 ð Deprecated in libpng. This function related to the "tIME" chunk
3027 is deprecated in libpng 1.7.
3028 png_convert_from_time_t
3030 ð Deprecated in libpng. This function related to the "tIME" chunk
3031 is deprecated in libpng 1.7.
3032 png_convert_to_rfc1123
3034 ð Deprecated in libpng. This function related to the "tIME" chunk
3035 is deprecated in libpng 1.7.
3036 png_convert_to_rfc1123_buffer
3038 ððŠ This function was deliberately omitted from this module
3039 because it doesn't seem useful for Perl programmers.
3040 This function is related to the "tIME" chunk; it seems fairly
3042 superfluous with the many other ways to manipulate time strings
3043 already in Perl.
3044 png_data_freer
3046 ð See "Memory management functions".
3047 png_free
3049 ð See "Memory management functions".
3050 png_free_data
3052 ð See "Memory management functions".
3053 png_get_cHRM_XYZ_fixed
3055 ð See "Fixed point functions".
3056 png_get_cHRM_fixed
3058 ð See "Fixed point functions".
3059 png_get_compression_type
3061 ððĪĄ See "Useless functions omitted". Useless function which
3062 returns 0 since there is only one type of compression.
3063 png_get_copyright
3065 ððŠ This function was deliberately omitted from this module
3066 because it doesn't seem useful for Perl programmers.
3067 This function gives you the copyright string for libpng.
3069 png_get_current_pass_number
3071 png_get_current_row_number
3072 png_get_error_ptr
3073 ð See "Error handling functions".
3074 png_get_filter_type
3076 ððĪĄ See "Useless functions omitted". This function returns the
3077 value of the unused field "filter_type" in the PNG header, which is
3078 always 0. See "Unused arguments omitted".
3079 png_get_gAMA_fixed
3081 ð See "Fixed point functions".
3082 png_get_header_ver
3084 This function was omitted from this module because it merely
3085 duplicates another function.
3086 Identical to "get_libpng_ver".
3088 png_get_header_version
3090 This function was omitted from this module because it merely
3091 duplicates another function.
3092 Identical to "get_libpng_ver".
3094 png_get_io_chunk_type
3096 png_get_io_ptr
3097 png_get_io_state
3098 png_get_mem_ptr
3099 png_get_pHYs_dpi
3100 png_get_pixel_aspect_ratio
3101 png_get_pixel_aspect_ratio_fixed
3102 ð See "Fixed point functions".
3103 png_get_pixels_per_inch
3105 png_get_pixels_per_meter
3106 png_get_progressive_ptr
3107 Incremental reading of PNGs is not handled yet.
3108 png_get_sCAL_fixed
3110 ð See "Fixed point functions".
3111 png_get_signature
3113 ððŠ This function was deliberately omitted from this module
3114 because it doesn't seem useful for Perl programmers.
3115 Returns the PNG signature of a PNG you read in.
3117 png_get_uint_31
3119 ððŠ This function was deliberately omitted from this module
3120 because it doesn't seem useful for Perl programmers.
3121 This produces an error if the unsigned integer argument is too big
3123 for a 31 bit number.
3124 png_get_user_chunk_ptr
3126 png_get_user_height_max
3127 png_get_user_transform_ptr
3128 png_get_x_offset_inches
3129 png_get_x_offset_inches_fixed
3130 ð See "Fixed point functions".
3131 png_get_x_offset_microns
3133 png_get_x_offset_pixels
3134 Duplicates "get_oFFs".
3135 png_get_x_pixels_per_inch
3137 png_get_x_pixels_per_meter
3138 Duplicates "get_oFFs".
3139 png_get_y_offset_inches
3141 png_get_y_offset_inches_fixed
3142 ð See "Fixed point functions".
3143 png_get_y_offset_microns
3145 png_get_y_offset_pixels
3146 Duplicates "get_oFFs".
3147 png_get_y_pixels_per_inch
3149 png_get_y_pixels_per_meter
3150 Duplicates "get_oFFs".
3151 png_handle_as_unknown
3153 png_image_begin_read_from_file
3154 png_image_begin_read_from_stdio
3155 png_image_finish_read
3156 png_image_free
3157 ð See "Memory management functions".
3158 png_image_write_to_file
3160 png_image_write_to_memory
3161 ð See "Memory management functions".
3162 png_image_write_to_stdio
3164 png_process_data
3165 png_process_data_pause
3166 png_process_data_skip
3167 png_progressive_combine_row
3168 png_read_row
3169 png_read_rows
3170 png_reset_zstream
3171 ð Deprecated in libpng. Resets the zstream of the zlib instance
3172 used for the image data.
3173 png_save_int_32
3175 ððŠ This function was deliberately omitted from this module
3176 because it doesn't seem useful for Perl programmers.
3177 Writes a 32 bit signed number into an octet buffer. Perl
3179 programmers will probably use "pack" for this.
3180 png_save_uint_16
3182 ððŠ This function was deliberately omitted from this module
3183 because it doesn't seem useful for Perl programmers.
3184 Writes a 16 bit number into an octet buffer. Perl programmers will
3186 probably use "pack" for this.
3187 png_save_uint_32
3189 ððŠ This function was deliberately omitted from this module
3190 because it doesn't seem useful for Perl programmers.
3191 Writes a 32 bit unsigned number into an octet buffer. Perl
3193 programmers will probably use "pack" for this.
3194 png_set_alpha_mode_fixed
3196 ð See "Fixed point functions".
3197 png_set_background_fixed
3199 ð See "Fixed point functions".
3200 png_set_benign_errors
3202 ð See "Error handling functions".
3203 png_set_cHRM_XYZ_fixed
3205 ð See "Fixed point functions".
3206 png_set_cHRM_fixed
3208 ð See "Fixed point functions".
3209 png_set_check_for_invalid_index
3211 png_set_compression_method
3212 ððĪĄ See "Useless functions omitted". This function in libpng
3213 corresponds to the unused "method" parameter of zlib functions like
3214 "deflateInit2". See "zlib documentation". The libpng function just
3215 produces a warning if the user sets the value to anything but 8,
3216 the value of the macro "Z_DEFLATED", and then lets zlib produce an
3217 error.
3218 png_set_crc_action
3220 ð See "Error handling functions".
3221 png_set_error_fn
3223 ð See "Error handling functions".
3224 png_set_filter_heuristics
3226 ð Deprecated in libpng.
3227 png_set_filter_heuristics_fixed
3229 ð See "Fixed point functions".
3230 png_set_flush
3232 png_set_gAMA_fixed
3233 ð See "Fixed point functions".
3234 png_set_gamma_fixed
3236 ð See "Fixed point functions".
3237 png_set_interlace_handling
3239 Incremental writing is not handled.
3240 png_set_invalid
3242 ð See "Memory management functions".
3243 png_set_longjmp_fn
3245 âðĪŠâ Undocumented function, but it is part of the public API.
3246 png_set_mem_fn
3248 ð See "Memory management functions".
3249 png_set_option
3251 png_set_progressive_read_fn
3252 png_set_read_status_fn
3253 png_set_read_user_chunk_fn
3254 png_set_read_user_transform_fn
3255 png_set_sCAL_fixed
3256 ð See "Fixed point functions".
3257 png_set_sRGB_gAMA_and_cHRM
3259 png_set_shift
3260 png_set_sig_bytes
3261 ððŠ This function was deliberately omitted from this module
3262 because it doesn't seem useful for Perl programmers.
3263 png_set_strip_error_numbers
3265 ððĪĄ See "Useless functions omitted". According to the libpng
3266 manual, "we never got around to actually numbering the error
3267 messages", so I assume this is not very useful.
3268 png_set_text_compression_method
3270 ððĪĄ See "Useless functions omitted". Unsupported for the same
3271 reasons as "png_set_compression_method".
3272 png_set_unknown_chunk_location
3274 This is related to some kind of bug in version 1.5 and previous of
3275 libpng.
3276 png_set_user_transform_info
3278 png_set_write_status_fn
3279 ð See "Error handling functions".
3280 png_set_write_user_transform_fn
3282 png_start_read_image
3283 png_write_chunk
3284 png_write_chunk_data
3285 png_write_chunk_end
3286 png_write_chunk_start
3287 png_write_flush
3288 png_write_info_before_PLTE
3289 png_write_row
3290 png_write_rows
3291 png_write_sig
3292 This is an exhaustive list of unsupported libpng API functions,
3294 extracted from the libpng source code using util/api.pl in this
3295 module's repository.
3296 Conditional compilation and old libpng versions
3298 It is possible to compile a version of the libpng library without
3299 support for various things. For example, a libpng without support for
3300 text chunks may be created by undefining the C macro
3301 "PNG_TEXT_SUPPORTED". This module supports the conditional compilation
3302 choices which we're aware of, but if you encounter problems using this
3303 module because of a conditionally-compiled libpng, then let us know and
3304 we'll add the necessary facility.
3305 Currently we test this module against vanilla libpng versions 1.2.59,
3307 1.4.22, 1.5.30, and 1.6.37 before releases. There doesn't seem to have
3308 been a 1.3 or a 1.1 version of libpng. See
3309 <http://www.libpng.org/pub/png/pngnews.html>. Versions 1.0 and earlier
3310 of libpng are not tested against.
3311 The following issues with older libpng versions may affect users of
3313 this module:
3314 cHRM chunk
3316 The "get_cHRM_XYZ" and "set_cHRM_XYZ" functions for the "cHRM" chunk
3318 are not present in pre-1.5.5 versions of libpng, but the conditional
3319 compilation macro of libpng for these newer functions is the same as
3320 for "get_cHRM" and "set_cHRM" functions, which are present on older
3321 versions of libpng. Because of this, this module includes its own
3322 protection macro, accessible via "libpng_supports" as "cHRM_XYZ".
3323 These functions are disabled for libpng versions earlier than 1.5.5.
3324 chunk_cache_max
3326 The functions "set_chunk_cache_max" and "get_chunk_cache_max" are not
3328 protected by a libpng macro, so this module includes its own protection
3329 macro, accessible via "libpng_supports" as "CHUNK_CACHE_MAX". These
3330 functions are disabled for libpng versions earlier than 1.4.0.
3331 Compression level
3333 Versions of libpng up to 1.5 behave erratically when
3335 "set_compression_level" or other "set_compression_*" functions are used
3336 to alter the compression of the image data. Testing of compression-
3337 related functions is disabled by this Perl module for pre-1.6.13
3338 versions of libpng.
3339 sCAL chunk
3341 Support for the sCAL chunk is disabled within this module for pre-1.6
3343 versions of libpng.
3344 Text chunk handling
3346 Versions of libpng up to 1.6.3 produce erratic results with "iTXt"
3348 (international text) chunks. Testing of text-related chunks is disabled
3349 by this Perl module for pre-1.6.13 versions of libpng.
3350 Not all constants are available
3352 Some of the libpng constants are defined in pnglibconf.h or pngconf.h
3353 but Image::PNG::Const only looks at png.h to make its constants.
3354 Because of this, some constant values like "PNG_Z_DEFAULT_COMPRESSION"
3355 aren't currently available in Image::PNG::Const. This probably should
3356 be fixed to extract the constants from the other files in a future
3357 version.
3358
3360 A standalone script, pnginspect, is installed with the distribution. It
3361 prints out the contents of the chunks of the PNG file on the command
3362 line.
3363
3365 The PNG specification
3366 The PNG specification <http://www.w3.org/TR/PNG/> (link to W3
3367 consortium) explains the details of the PNG format.
3368 PNG The Definitive Guide by Greg Roelofs
3370 The book "PNG - The Definitive Guide" by Greg Roelofs, published in
3372 1999 by O'Reilly is available online at <http://www.faqs.org/docs/png/>
3373 or <http://www.libpng.org/pub/png/book/>.
3374 The libpng documentation
3376 Official documentation
3377 The starting point is the plain text libpng manual at
3378 <http://libpng.org/pub/png/libpng-manual.txt> and the manual page
3379 libpng.3, which you can read using "man 3 libpng".
3380 âðĪŠâ The documentation which comes with libpng is rather sketchy.
3382 See "Differences from libpng". It doesn't contain full
3383 specifications (prototypes, return values) for all of the functions
3384 in the library. For programming in C using libpng, look at the
3385 header file png.h. In some cases, you need to look at the source
3386 code of the library.
3387 Other documentation
3389 There is a collection of function definitions under the title
3390 "Interface Definitions for libpng12" at
3391 <https://refspecs.linuxbase.org/LSB_4.0.0/LSB-Desktop-generic/LSB-Desktop-generic/libpng12man.html>
3392 as part of the "Linux Standard Base Desktop Specification". These
3393 contain extensive information on the prototypes and return values
3394 for the libpng routines, something which is often only available
3395 elsewhere by actually looking at the libpng source code. These
3396 pages are usually the first hits on search engines if you search
3397 for a function name in libpng.
3398 zlib documentation
3400 See <https://zlib.net/manual.html> for the zlib documentation.
3401 Other Perl modules on CPAN
3403 These other modules may also be useful.
3404 Alien::PNG
3406 Alien::PNG claims to be a way of "building, finding and using PNG
3407 binaries". It may help in installing libpng. We didn't use it as a
3408 dependency for this module because it seems not to work in batch
3409 mode, but stop and prompt the user. We're interested in hearing
3410 feedback from users whether this works or not on various platforms.
3411 Imager
3413 Imager, Imager::Files and "Imager::Files::PNG" contain support for
3414 reading and writing PNGs via libpng, as well as support for reading
3415 and writing various other kinds of image files, changing the
3416 images, converting, and more.
3417 Image::ExifTool
3419 Image::ExifTool is a pure Perl (doesn't require a C compiler)
3420 solution for accessing the text segments of images. It supports PNG
3421 text segments.
3422 Image::Info
3424 Image::Info gets information out of images. It supports PNG and is
3425 written in pure Perl, so it doesn't require a C compiler. As well
3426 as basics such as height, width, and colour type, it can get text
3427 chunks, modification time, palette, gamma (gAMA chunk), resolution
3428 (pHYs chunk), and significant bits (sBIT chunk). At the time of
3429 writing (version 1.31) it doesn't support other chunks.
3430 Image::PNG::Rewriter
3432 Image::PNG::Rewriter is a utility for unpacking and recompressing
3433 the IDAT (image data) part of a PNG image. The main purpose seems
3434 to be to recompress the image data with the module author's other
3435 module Compress::Deflate7. At the time of writing, that only works
3436 with Perl versions 5.12 or later.
3437 Image::Pngslimmer
3439 Image::Pngslimmer reduces the size of dynamically created PNG
3440 images. It's very, very slow at reading PNG data, but seems to work
3441 OK.
3442 Image::PNG::Write::BW
3444 Image::PNG::Write::BW writes black and white PNGs from strings.
3445 Image::Size
3447 If you only need to read the sizes of images, Image::Size works
3448 with PNG and other image formats.
3449
3451 Ben Bullock, <bkb@cpan.org>
3452
3454 This package and associated files are copyright (C) 2011-2021 Ben
3455 Bullock.
3456 You can use, copy, modify and redistribute this package and associated
3458 files under the Perl Artistic Licence or the GNU General Public
3459 Licence.
3460perl v5.34.0 2022-01-21 Image::PNG::Libpng(3)
