Debian Codegraph @

lib/Image/PNG/Libpng.pod

raw
1
2
3
4
5
6
7
8
9
10
11
12 =pod
13
14 =encoding UTF-8
15
16 =head1 NAME
17
18 Image::PNG::Libpng - Perl interface to the C library "libpng".
19
20 =head1 SYNOPSIS
21
22 Libpng-like interface:
23
24
25 use Image::PNG::Libpng ':all';
26 my $png = create_read_struct ();
27 open my $file, '<:raw', 'nice.png' or die $!;
28 $png->init_io ($file);
29 $png->read_png ();
30 close $file;
31 # Get all valid chunks
32 my $valid = $png->get_valid ();
33 my @valid_chunks = sort grep {$valid->{$_}} keys %$valid;
34 print "Valid chunks are ", join (", ", @valid_chunks), "\n";
35 # Print image information
36 my $header = $png->get_IHDR ();
37 for my $k (keys %$header) {
38 print "$k: $header->{$k}\n";
39 }
40
41 (This example is included as L<F<examples/synopsis.pl>|https://fastapi.metacpan.org/source/BKB/Image-PNG-Libpng-0.60/examples/synopsis.pl>
42 in the distribution.)
43
44
45 Simple interface:
46
47
48 use Image::PNG::Libpng ':all';
49 my $png = read_png_file ('../t/tantei-san.png');
50 # Get all valid chunks
51 my $valid = $png->get_valid ();
52 my @valid_chunks = sort grep {$valid->{$_}} keys %$valid;
53 print "Valid chunks are ", join (", ", @valid_chunks), "\n";
54 # Print image information
55 my $header = $png->get_IHDR ();
56 for my $k (keys %$header) {
57 if ($k eq 'color_type') {
58 print "$k: " . color_type_name ($header->{$k}) . "\n";
59 }
60 else {
61 print "$k: $header->{$k}\n";
62 }
63 }
64 my $wpng = $png->copy_png ();
65 $wpng->write_png_file ('new.png');
66
67
68 (This example is included as L<F<examples/synopsis-easy.pl>|https://fastapi.metacpan.org/source/BKB/Image-PNG-Libpng-0.60/examples/synopsis-easy.pl>
69 in the distribution.)
70
71
72 =head1 VERSION
73
74 This document describes Image::PNG::Libpng version 0.60, corresponding to git commit L<c8b9220ff9731ddfc6ff4b0d5f7bfed775d952fe|https://github.com/benkasminbullock/image-png-libpng/commit/c8b9220ff9731ddfc6ff4b0d5f7bfed775d952fe> at Tue Mar 17 11:06:31 2026 +0900.
75
76 Unless otherwise qualified, comments in this document on the libpng
77 source code and documentation refer to libpng version 1.6.45. Libpng is not bundled with this distribution, so
78 your installed version may vary.
79
80 =head1 DESCRIPTION
81
82 Image::PNG::Libpng is a Perl library for accessing the contents of PNG
83 (Portable Network Graphics) images. Image::PNG::Libpng enables Perl to
84 use the "libpng" library to read and write files in PNG
85 format. Image::PNG::Libpng does not contain the libpng library. The
86 libpng library must be installed on your computer prior to installing
87 Image::PNG::Libpng.
88
89 Image::PNG::Libpng consists of Perl subroutines which mirror
90 the C functions in libpng, plus helper subroutines to make it easier
91 to read and write PNG data in Perl.
92
93 For those familiar with libpng, the section L</Differences
94 from libpng> explains the differences with libpng.
95
96 =head1 FUNCTIONS
97
98 The functions in the module are gathered into the following
99 categories: L</Simple input and output>, which describes some
100 convenience functions, L</Libpng-style input and output>, which
101 describes functions which closely mirror libpng, L</The image header>,
102 which describes functions for reading and writing the meta-information
103 about PNG images, L</Image data>, which describes functions for
104 accessing the image data itself, L</Text chunks>, L</Private chunks>,
105 L</Library version functions>, L</Compression and filtering>, L</Other
106 chunks>, L</Libpng transformations>, L</Other libpng functions>,
107 functions from libpng which don't fit elsewhere, and L</Other
108 functions>, which are functions specific to this module.
109
110 =head1 Simple input and output
111
112 These convenience functions combine common operations. They are not
113 part of the original libpng API.
114
115 =head2 copy_png
116
117 my $outpng = $png->copy_png ();
118
119 Copy a PNG from a read to a write structure. This function bridges two
120 kinds of object, "read a png" objects created by
121 L</create_read_struct> and "write a png" objects created by
122 L</create_write_struct>. This function copies all the valid chunks
123 from a read structure to a write structure.
124
125 The following example demonstrates copying a PNG.
126
127
128 use utf8;
129 use FindBin '$Bin';
130 use Image::PNG::Libpng qw(read_png_file write_png_file) ;
131 my $pngin = read_png_file ("$Bin/../t/tantei-san.png");
132 my $pngout = $pngin->copy_png ();
133 $pngout->set_text ([{key => 'Name', text => 'Shunsaku Kudo'}]);
134 # $pngout->write_png_file ('copy.png');
135
136 (This example is included as L<F<examples/copy-png.pl>|https://fastapi.metacpan.org/source/BKB/Image-PNG-Libpng-0.60/examples/copy-png.pl>
137 in the distribution.)
138
139
140 =head2 create_reader
141
142 my $png = create_reader ('file.png');
143 $png->read_png ();
144
145 This combines L</create_read_struct>, C<open>, and L</init_io> on the
146 specified file name but does not read the file in. This is for the
147 case that the user wants to apply some kind of transformation.
148
149 =head3 Setting the background
150
151 In the following example, the user sets the background with
152 L</set_background> to replace the alpha channel.
153
154
155 use utf8;
156 use FindBin '$Bin';
157 use Image::PNG::Libpng ':all';
158 use Image::PNG::Const ':all';
159 my $file = "$Bin/luv.png";
160 my %color = (red => 0xC0, green => 0xFF, blue => 0xFF);
161 my $png = create_reader ($file);
162 $png->set_background (\%color, PNG_BACKGROUND_GAMMA_SCREEN, 0);
163 $png->read_png ();
164 my $wpng = copy_png ($png);
165 $wpng->write_png_file ("$Bin/set-background.png");
166
167 (This example is included as L<F<examples/set-background.pl>|https://fastapi.metacpan.org/source/BKB/Image-PNG-Libpng-0.60/examples/set-background.pl>
168 in the distribution.)
169
170
171
172
173 L<examples/luv.png|https://fastapi.metacpan.org/source/BKB/Image-PNG-Libpng-0.60/examples/luv.png> is included in the distribution.
174
175 =begin html
176
177 <p>The input image has a transparent background:</p>
178
179 <!-- metacpan doesn't allow figure/figcaption tags. -->
180 <table>
181 <tr>
182 <td>
183 <img src="https://fastapi.metacpan.org/source/BKB/Image-PNG-Libpng-0.60/examples/luv.png">
184 </td>
185 </tr>
186 <tr>
187 <th>
188 <a href='https://fastapi.metacpan.org/source/BKB/Image-PNG-Libpng-0.60/examples/luv.png'>examples/luv.png</a>
189 </th>
190 </tr>
191 </table>
192
193 =end html
194
195
196
197
198 L<examples/set-background.png|https://fastapi.metacpan.org/source/BKB/Image-PNG-Libpng-0.60/examples/set-background.png> is included in the distribution.
199
200 =begin html
201
202 <p>The output image has a blue background:</p>
203
204 <!-- metacpan doesn't allow figure/figcaption tags. -->
205 <table>
206 <tr>
207 <td>
208 <img src="https://fastapi.metacpan.org/source/BKB/Image-PNG-Libpng-0.60/examples/set-background.png">
209 </td>
210 </tr>
211 <tr>
212 <th>
213 <a href='https://fastapi.metacpan.org/source/BKB/Image-PNG-Libpng-0.60/examples/set-background.png'>examples/set-background.png</a>
214 </th>
215 </tr>
216 </table>
217
218 =end html
219
220
221 This function was added to the module in version 0.53.
222
223 =head2 create_writer
224
225 my $png = create_writer ('file.png');
226 $png->set_IHDR (\%ihdr);
227 $png->set_rows (\@rows);
228 $png->write_png ();
229
230 This combines L</create_write_struct>, C<open>, and L</init_io> on the
231 specified file name but does not read the file in. This is for the
232 case that the user wants to apply some kind of transformation before
233 writing.
234
235 This function was added to the module in version 0.53.
236
237 =head2 read_from_scalar
238
239 my $png = read_from_scalar ($string);
240
241 This creates an image structure C<$png> from the contents of a Perl
242 scalar variable C<$string> containing PNG image data, for example data
243 read from a file, or data obtained from a web page. The first argument, C<$png>, is a PNG structure created with
244 L</create_read_struct>. It
245 reads in all the data from the structure on being called.
246
247 This is useful when image data is stored in a Perl scalar. For example
248
249
250 use Image::PNG::Libpng 'read_from_scalar';
251 use LWP::Simple;
252 use JSON::Create;
253 my $image_data = get 'http://libpng.org/pub/png/img_png/libpng-88x31.png';
254 # Now $image_data contains the PNG file
255 my $png = read_from_scalar ($image_data);
256 # Now $png contains the PNG information from the image.
257 # Get the header.
258 my $header = $png->get_IHDR ();
259 my $jc = JSON::Create->new (indent => 1, sort => 1);
260 print $jc->run ($header);
261
262 (This example is included as L<F<examples/get-www-png.pl>|https://fastapi.metacpan.org/source/BKB/Image-PNG-Libpng-0.60/examples/get-www-png.pl>
263 in the distribution.)
264
265
266 The output looks like this:
267
268 {
269 "bit_depth":4,
270 "color_type":3,
271 "height":31,
272 "interlace_method":0,
273 "width":88
274 }
275
276
277 See also L</Input and output manipulation functions>.
278
279 =head2 read_png_file
280
281 my $png = read_png_file ('q.png');
282
283 Open F<q.png> and read its contents into C<$png>.
284
285 This combines L</create_read_struct>, C<open>, L</init_io>, and
286 L</read_png>. The return value is the same as that of
287 L</create_read_struct> with the entire PNG image already read in.
288
289 The optional argument to L</read_png> can be specified using an
290 optional C<transforms> argument:
291
292 my $png = read_png_file ('file.png', transforms => PNG_TRANSFORM_EXPAND);
293
294 L<Carp/croak> is used to signal errors opening or closing the file.
295
296 =head2 set_transforms
297
298 $png->set_transforms (PNG_TRANSFORM_BGR);
299
300 Set transforms for reading and writing. This is the same as the
301 optional argument to L</read_png> or L</write_png>. If both this and
302 the optional argument are given, the optional argument overrides what
303 is set here.
304
305 =head2 write_png_file
306
307 $png->write_png_file ('nice.png');
308
309 This combines open, L</init_io>, and L</write_png> to write an entire
310 PNG image out to the file name specified by the argument. C<$png> must
311 be the object created by L</create_write_struct>, so L</read_png_file>
312 followed by a call to this does not work. See L</copy_png> if you need
313 to do that kind of operation.
314
315 The optional argument to L</write_png> can be specified using
316 L</set_transforms>.
317
318 L<Carp/croak> is used to signal errors opening or closing the file.
319
320 =head2 write_to_scalar
321
322 my $image_data = $png->write_to_scalar ();
323
324 This writes the PNG image data in C<$png> into a Perl scalar. The first argument, C<$png>, is a writeable PNG structure created with
325 L</create_write_struct>. The return value of the subroutine is the Perl scalar
326 containing the image data.
327
328 So, for example,
329
330
331
332 # This CGI script prints a PNG in a random colour.
333
334 use Image::PNG::Libpng ':all';
335 use Image::PNG::Const ':all';
336 my $png = create_write_struct ();
337 my $size = 100;
338 $png->set_IHDR ({height => $size, width => $size, bit_depth => 8,
339 color_type => PNG_COLOR_TYPE_RGB});
340 my $bytes = pack "CCC", randcol (), randcol (), randcol ();
341 my @rows = ($bytes x $size) x $size;
342 $png->set_rows (\@rows);
343 my $img = $png->write_to_scalar ();
344 binmode STDOUT;
345 print "Content-Type:image/png\r\n\r\n$img";
346 exit;
347 sub randcol
348 {
349 return int (rand () * 0x100);
350 }
351
352 (This example is included as L<F<examples/png-cgi.pl>|https://fastapi.metacpan.org/source/BKB/Image-PNG-Libpng-0.60/examples/png-cgi.pl>
353 in the distribution.)
354
355
356 See also L</Input and output manipulation functions>.
357
358 The optional argument to L</write_png> can be specified using
359 L</set_transforms>.
360
361 =head1 Libpng-style input and output
362
363 There are two different "new"-like functions, depending on whether you
364 want to read or write a PNG, L</create_read_struct> and
365 L</create_write_struct>. These are based on the libpng API. Input uses
366 C<open> plus L</init_io> followed by L</read_png> or L</write_png>.
367
368 =head2 Examples
369
370 =head3 A self-pixellating program
371
372 This example demonstrates writing a monochrome PNG by creating a write
373 structure with L</create_write_struct>, opening a filehandle to write
374 it, associating the filehandle with the PNG structure with
375 L</init_io>, then using the functions L</write_info>, L</write_image>,
376 and then L</write_end> to actually write the PNG data to the file.
377
378
379 use utf8;
380 use FindBin '$Bin';
381 use Image::PNG::Libpng ':all';
382 use Image::PNG::Const ':all';
383 my $outfile = "$Bin/mono.png";
384 my ($height, $width, $rows) = pixelate (__FILE__, 5);
385 my $png = create_write_struct ();
386 open my $out, ">:raw", $outfile or die $!;
387 $png->init_io ($out);
388 $png->set_IHDR ({height => $height, width => $width, bit_depth => 1,
389 color_type => PNG_COLOR_TYPE_GRAY});
390 $png->set_text ([{key => 'silly', text => 'finely-tuned breakfast cereal',}]);
391 $png->set_tIME ({year => 1999});
392 $png->write_info ();
393 $png->set_invert_mono ();
394 # PNG puts the leftmost pixel in the high-order part of the byte.
395 $png->set_packswap ();
396 $png->write_image ($rows);
397 $png->write_end ();
398 close $out or die $!;
399 exit;
400
401 sub pixelate
402 {
403 my ($file, $box) = @_;
404 open my $in, "<", $file or die "Can't open '$file': $!";
405 my $width = 0;
406 my @lines;
407 while (<$in>) {
408 chomp;
409 s/\t/ /g;
410 push @lines, $_;
411 if (length ($_) > $width) {
412 $width = length ($_);
413 }
414 }
415 close $in or die $!;
416 $width *= $box;
417 my $height = scalar (@lines) * $box;
418 my $zero = pack "C", 0;
419 my $bwidth = int(($width+7)/8);
420 my @rows = ($zero x $bwidth) x $height;
421 for my $r (0..$height-1) {
422 my $y = int ($r/$box);
423 my $line = $lines[$y];
424 for my $x (0..length ($line) - 1) {
425 if (substr ($line, $x, 1) ne ' ') {
426 for my $c (0..$box - 1) {
427 my $offset = $x*$box + $c;
428 my $byte = int ($offset / 8);
429 my $bit = $offset % 8;
430 my $octet = ord (substr ($rows[$r], $byte, 1));
431 substr ($rows[$r], $byte, 1) = chr ($octet | 1<<$bit);
432 }
433 }
434 }
435 }
436 return ($height, $width, \@rows);
437 }
438
439 (This example is included as L<F<examples/libpng-write.pl>|https://fastapi.metacpan.org/source/BKB/Image-PNG-Libpng-0.60/examples/libpng-write.pl>
440 in the distribution.)
441
442
443
444
445 L<examples/mono.png|https://fastapi.metacpan.org/source/BKB/Image-PNG-Libpng-0.60/examples/mono.png> is included in the distribution.
446
447 =begin html
448
449 <p>The output has a bit depth of 1:</p>
450
451 <!-- metacpan doesn't allow figure/figcaption tags. -->
452 <table>
453 <tr>
454 <td>
455 <img src="https://fastapi.metacpan.org/source/BKB/Image-PNG-Libpng-0.60/examples/mono.png">
456 </td>
457 </tr>
458 <tr>
459 <th>
460 <a href='https://fastapi.metacpan.org/source/BKB/Image-PNG-Libpng-0.60/examples/mono.png'>examples/mono.png</a>
461 </th>
462 </tr>
463 </table>
464
465 =end html
466
467
468 =head2 create_read_struct
469
470 my $png = create_read_struct ();
471
472 Create a structure for reading a PNG. The return value can be used as
473 an object with the other functions as methods. It can be copied to a
474 write structure with L</copy_png>.
475
476 This function corresponds to C<png_create_read_struct> in libpng plus C<create_info_struct> (see L</No info structure>) with the error and warning handler variables set up to use
477 Perl's error reporting.
478
479 =head2 create_write_struct
480
481 my $png = create_write_struct ();
482
483 Create a structure for writing a PNG. This can be used as an object
484 with the other functions as methods.
485
486 This function corresponds to C<png_create_write_struct> in libpng plus C<create_info_struct> (see L</No info structure>) with the error and warning handler variables set up to use
487 Perl's error reporting.
488
489 =head2 init_io
490
491 open my $file, "<", 'nice.png';
492 $png->init_io ($file);
493
494 Set the file which C<$png> reads or writes to C<$file>. C<$file> must
495 be an already-opened Perl file handle. If C<$png> was created with
496 L</create_write_struct>, C<$file> must be opened for writing. If
497 C<$png> was created with L</create_read_struct>, C<$file> must be open
498 for reading.
499
500 Since PNG files are binary files, it is safest to specify the "raw"
501 pragma or use "binmode" with the file to override any default text
502 file encoding which Perl might be using:
503
504 open my $file, ">:raw", 'output.png';
505
506 or
507
508 open my $file, ">", 'output.png';
509 binmode $file;
510
511 This function corresponds to C<png_init_io> in libpng, with a Perl
512 file handle substituting for the C C<FILE *>.
513
514 =head3 Caveats when using init_io
515
516 =head4 Check the return value of open
517
518 On some versions of Perl, L</init_io> may crash in some circumstances
519 with an error like "segmentation fault", if you use code like
520
521 my $png = create_read_struct ();
522 open my $file, "<:raw", "some.png";
523 $png->init_io ($file);
524
525 and you do not check whether the call to C<open> was successful, and
526 F<some.png> does not exist. The crash occurs within Perl's conversion
527 of C<$file> into a C C<FILE *> pointer, before this module's code
528 runs. This bug was fixed in Perls after version 5.24.1. To avoid
529 trouble, please check the return value of C<open>.
530
531 =head4 Cannot deal with non-file filehandles
532
533 Since C<init_io> is a Perl access to an underlying C function
534 C<png_init_io>, it requires something which can be passed to the
535 underlying C as a C<FILE *>, C's file structure. If, for example you
536 use L<IO::String> or open a scalar reference as a file handle, since
537 these actions do not create a C file structure, an error of the form
538 C<scalar's file handle is NULL> will occur.
539
540 If you have a PNG in the form of a Perl scalar, use
541 L</read_from_scalar> instead of C<init_io>, which uses a C function
542 called C<png_set_read_fn> so that the C library can access the data in
543 the Perl scalar. See also L</Input and output manipulation functions>.
544
545 =head2 read_end
546
547 $png->read_end ();
548
549 Read the part of the PNG file after the image data.
550
551 This function corresponds to C<png_read_end> in libpng.
552
553 =head2 read_image
554
555 my $rows = $png->read_image ();
556
557 Read the image data of the PNG file.
558
559 This function corresponds to C<png_read_image> in libpng.
560
561 =head2 read_info
562
563 $png->read_info ();
564
565 Read the part of the PNG file before the image data.
566
567 This function corresponds to C<png_read_info> in libpng.
568
569 =head2 read_png
570
571 $png->read_png ();
572
573 Read the entire PNG file into memory.
574
575 You can provide an argument containing transformations to apply to the
576 image:
577
578 use Image::PNG::Const qw/PNG_TRANSFORM_STRIP_ALPHA/;
579 $png->read_png (PNG_TRANSFORM_STRIP_ALPHA);
580
581 If the argument is omitted, the default value of
582 C<PNG_TRANSFORM_IDENTITY> (the "do nothing" value) is applied. The
583 possible transformations which can be applied are
584
585 =over
586
587
588 =item PNG_TRANSFORM_BGR
589
590 Flip RGB to BGR, RGBA to BGRA. See also L</set_bgr>.
591
592
593
594 =item PNG_TRANSFORM_EXPAND
595
596 Perform set_expand(). See also L</set_expand>.
597
598
599
600 =item PNG_TRANSFORM_EXPAND_16
601
602 Expand samples to 16 bits. See also L</set_expand_16>.
603
604
605
606 =item PNG_TRANSFORM_GRAY_TO_RGB
607
608 Expand grayscale samples to RGB (or GA to RGBA). See also L</set_gray_to_rgb>.
609
610
611
612 =item PNG_TRANSFORM_IDENTITY
613
614 No transformation.
615
616
617
618 =item PNG_TRANSFORM_INVERT_ALPHA
619
620 Change alpha from opacity to transparency. See also L</set_invert_alpha>.
621
622
623
624 =item PNG_TRANSFORM_INVERT_MONO
625
626 Invert monochrome images. See also L</set_invert_mono>.
627
628
629
630 =item PNG_TRANSFORM_PACKING
631
632 Expand 1, 2 and 4-bit samples to bytes. See also L</set_packing>.
633
634
635
636 =item PNG_TRANSFORM_PACKSWAP
637
638 Change order of packed pixels to LSB first. See also L</set_packswap>.
639
640
641
642 =item PNG_TRANSFORM_SCALE_16
643
644 Strip 16-bit samples to 8-bit accurately. See also L</set_scale_16>.
645
646
647
648 =item PNG_TRANSFORM_SHIFT
649
650 Normalize pixels to the sBIT depth.
651
652
653
654 =item PNG_TRANSFORM_STRIP_16
655
656 Chop 16-bit samples to 8-bit less accurately. See also L</set_strip_16>.
657
658
659
660 =item PNG_TRANSFORM_STRIP_ALPHA
661
662 Discard the alpha channel.
663
664
665
666
667
668
669
670 =item PNG_TRANSFORM_SWAP_ALPHA
671
672 Flip RGBA to ARGB or GA to AG. See also L</set_swap_alpha>.
673
674
675
676 =item PNG_TRANSFORM_SWAP_ENDIAN
677
678 Byte-swap 16-bit samples. See also L</set_swap>.
679
680
681 =back
682
683 This function corresponds to C<png_read_png> in libpng with a default value for the third
684 argument. The fourth, unused, argument to C<png_read_png> does not
685 need to be supplied. See L<Unused arguments omitted>.
686
687 It does not take a second "info" argument. See L</No info structure>.
688
689 =head2 read_update_info
690
691 $png->read_update_info ();
692
693 ⛐ðŸĪŠâš  Inside Image::PNG::Libpng, the libpng function
694 C<png_read_update_info> is called before reading image data.
695 According to L</The libpng documentation>, this function may only be called
696 once for any particular info structure. So although the above Perl
697 interface exists in the module, it is strongly recommended to not use
698 this unless you know exactly what you are doing, since it will usually
699 cause an error when the image data is read.
700
701 This function corresponds to C<png_read_update_info> in libpng
702
703 =head2 write_end
704
705 $png->write_end ();
706
707 Write the final part of the PNG file.
708
709 This function corresponds to C<png_write_end> in libpng.
710
711 =head2 write_image
712
713 $png->write_image ($rows);
714
715 Write the image of the PNG file. C<$rows> is an array reference as per
716 L</set_rows>.
717
718 This function corresponds to C<png_write_image> in libpng.
719
720 =head2 write_info
721
722 $png->write_info ();
723
724 Write the first part of the PNG file.
725
726 This function corresponds to C<png_write_info> in libpng.
727
728 =head2 write_png
729
730 $png->write_png ();
731
732 This writes the PNG to the file stream which was associated with it
733 using L</init_io>. For example,
734
735 open my $output, ">:raw", 'out.png';
736 $png->init_io ($output);
737 $png->write_png ();
738 close $output;
739
740 An optional argument consists of transformations to apply to the PNG
741 image before writing it:
742
743 use Image::PNG::Const qw/PNG_TRANSFORM_STRIP_ALPHA/;
744 $png->write_png (PNG_TRANSFORM_STRIP_ALPHA);
745
746 The transformations which can be applied are as follows:
747
748 =over
749
750
751 =item PNG_TRANSFORM_BGR
752
753 Flip RGB to BGR, RGBA to BGRA. See also L</set_bgr>.
754
755
756
757
758
759
760
761
762
763
764
765 =item PNG_TRANSFORM_INVERT_ALPHA
766
767 Change alpha from opacity to transparency. See also L</set_invert_alpha>.
768
769
770
771 =item PNG_TRANSFORM_INVERT_MONO
772
773 Invert monochrome images. See also L</set_invert_mono>.
774
775
776
777 =item PNG_TRANSFORM_PACKING
778
779 Expand 1, 2 and 4-bit samples to bytes. See also L</set_packing>.
780
781
782
783 =item PNG_TRANSFORM_PACKSWAP
784
785 Change order of packed pixels to LSB first. See also L</set_packswap>.
786
787
788
789
790
791 =item PNG_TRANSFORM_SHIFT
792
793 Normalize pixels to the sBIT depth.
794
795
796
797
798
799
800
801 =item PNG_TRANSFORM_STRIP_FILLER_AFTER
802
803 Strip out trailing filler bytes.
804
805
806
807 =item PNG_TRANSFORM_STRIP_FILLER_BEFORE
808
809 Strip out leading filler bytes.
810
811
812
813 =item PNG_TRANSFORM_SWAP_ALPHA
814
815 Flip RGBA to ARGB or GA to AG. See also L</set_swap_alpha>.
816
817
818
819 =item PNG_TRANSFORM_SWAP_ENDIAN
820
821 Byte-swap 16-bit samples. See also L</set_swap>.
822
823
824 =back
825
826 This function corresponds to C<png_write_png> in libpng.
827
828 =head1 The image header
829
830 These functions handle the header part of PNG image data. See L<this subsection|http://www.w3.org/TR/PNG/#11IHDR>
831 of L</The PNG specification> for information on the PNG standards for the image
832 header.
833
834 =head2 color_type_name
835
836 $name = color_type_name ($color_type);
837
838 This is a convenience function which returns a string corresponding to
839 the numerical color type in C<$color_type>. The name is in upper
840 case, with words separated by underscores, as in C<RGB_ALPHA>.
841
842
843 use Image::PNG::Libpng ':all';
844 my $png = read_png_file ('tantei-san.png');
845 my $name = color_type_name ($png->get_IHDR->{color_type});
846 print "Your PNG has colour type $name.\n";
847
848 (This example is included as L<F<examples/color-type-name.pl>|https://fastapi.metacpan.org/source/BKB/Image-PNG-Libpng-0.60/examples/color-type-name.pl>
849 in the distribution.)
850
851
852 This function does not correspond to anything in libpng. The names of
853 the color types are taken from those defined in the libpng header
854 file, C<png.h>.
855
856 =head2 get_bit_depth
857
858 my $bit_depth = $png->get_bit_depth ();
859
860 Get the bit depth, the number of bits for one channel of one pixel.
861
862 This function corresponds to C<png_get_bit_depth> in libpng
863
864 =head2 get_channels
865
866 my $channels = $png->get_channels ();
867
868 Get the number of channels, from one to four. The channels are the
869 components of pixels, for example the red channel or the alpha
870 (transparency) channel. The return value is 1 for color type
871 C<PNG_COLOR_TYPE_GRAY> and C<PNG_COLOR_TYPE_PALETTE>, 2 for
872 C<PNG_COLOR_TYPE_GRAY_ALPHA>, 3 for C<PNG_COLOR_TYPE_RGB> and 4 for
873 C<PNG_COLOR_TYPE_RGB_ALPHA> or C<PNG_COLOR_TYPE_RGB> with a filler
874 byte. Note that the number of channels does not necessarily correspond
875 to the number of bytes, since the bit depth can also be 1, 2, 4, 8, or
876 16, depending on the color type. See also the convenience function
877 L</color_type_channels>.
878
879 This function corresponds to C<png_get_channels> in libpng
880
881 =head2 get_color_type
882
883 my $color_type = $png->get_color_type ();
884
885 This returns an integer value. If you want to get a name for the
886 color type, use L</color_type_name>.
887
888 This function corresponds to C<png_get_color_type> in libpng.
889
890 =head2 get_IHDR
891
892 my $IHDR = $png->get_IHDR ();
893
894 Read the IHDR information from the PNG file. The return value is a
895 hash reference containing the following key/value pairs:
896
897 =over
898
899
900 =item width
901
902 The width of the image in pixels.
903
904
905 =item height
906
907 The height of the image in pixels.
908
909
910 =item bit_depth
911
912 The bit depth of the image (the number of bits used for each color in
913 a pixel).
914 This can take the values 1, 2, 4, 8, 16.
915
916 =item color_type
917
918 The color type.
919 This can take the values PNG_COLOR_TYPE_GRAY, PNG_COLOR_TYPE_GRAY_ALPHA, PNG_COLOR_TYPE_PALETTE, PNG_COLOR_TYPE_RGB, PNG_COLOR_TYPE_RGB_ALPHA.
920
921 =item interlace_method
922
923 The method of interlacing.
924 This can take the values PNG_INTERLACE_NONE, PNG_INTERLACE_ADAM7.
925
926
927
928
929 =back
930
931 So, for example, to get the width and height of an image,
932
933 my $ihdr = $png->get_IHDR ();
934 printf "Your image is %d x %d\n", $ihdr->{width}, $ihdr->{height};
935
936 This function corresponds to C<png_get_IHDR> in libpng, with a single Perl hash reference used
937 instead of the several pointers to integers used in libpng.
938
939 It does not return the fields C<filter_type> and
940 C<compression_type>, since these are always 0. See L<Unused arguments omitted>.
941
942 =head2 get_image_height
943
944 my $height = $png->get_image_height ();
945
946 Get the image's height from the header.
947
948 This function corresponds to C<png_get_image_height> in libpng
949
950 =head2 get_image_width
951
952 my $width = $png->get_image_width ();
953
954 Get the image's width from the header.
955
956 This function corresponds to C<png_get_image_width> in libpng
957
958 =head2 get_interlace_type
959
960 my $interlace_type = $png->get_interlace_type ();
961
962 Get the interlace type. This is either PNG_INTERLACE_NONE or
963 PNG_INTERLACE_ADAM7.
964
965 This function corresponds to C<png_get_interlace_type> in libpng
966
967 =head2 get_valid
968
969 my $valid = $png->get_valid ();
970 if ($valid->{oFFs}) {
971 print "The PNG has valid screen offsets.\n";
972 }
973
974 This function returns a hash with a key for each possible chunk which
975 may or may not be valid. The chunks which you can test for are
976 L</bKGD>, L</cHRM>, L</eXIf>, L</gAMA>, L</hIST>, L</hIST>, L</iCCP>, L<IDAT|/Image data>, L<IHDR|/The image header>, L</iTXt>, L</oFFs>, L</pCAL>, L</pHYs>, L</PLTE>, L</sBIT>, L</sCAL>, L</sPLT>, L</sRGB>, L</tEXt>, L</tIME>, L</tRNS>, and L</zTXt>.
977
978 Whereas L</libpng_supports> tells you whether the installed libpng on
979 your system supports various chunks, this tells you whether the chunks
980 are present in a particular PNG image file.
981
982 The first argument, C<$png>, is a PNG structure created with
983 L</create_read_struct>.
984
985 This function corresponds to C<png_get_valid> in libpng, with the difference being that the
986 return value is a hash containing a key for each possible chunk.
987
988 =head2 height
989
990 my $height = $png->height ();
991
992 Alias for L</get_image_height>. This is not exported, it's
993 intended for use with the object only.
994
995 =head2 set_IHDR
996
997 my $ihdr = {width => 10, height => 10, bit_depth => 8,
998 color_type => PNG_COLOR_TYPE_RGB};
999 $png->set_IHDR ($ihdr);
1000
1001 Set the IHDR chunk (the image header) of the PNG image.
1002
1003 The first argument, C<$png>, is a writeable PNG structure created with
1004 L</create_write_struct>. The second argument is a hash with the following values:
1005
1006 =over
1007
1008
1009 =item width
1010
1011 The width of the image in pixels.
1012 This cannot be zero, negative, or omitted.
1013
1014 =item height
1015
1016 The height of the image in pixels.
1017 This cannot be zero, negative, or omitted.
1018
1019 =item bit_depth
1020
1021 The bit depth of the image (the number of bits used for each color in
1022 a pixel).
1023 This cannot be omitted. This can have the values 1, 2, 4, 8, 16.
1024
1025 =item color_type
1026
1027 The color type.
1028 This cannot be omitted. This can have the values PNG_COLOR_TYPE_GRAY, PNG_COLOR_TYPE_GRAY_ALPHA, PNG_COLOR_TYPE_PALETTE, PNG_COLOR_TYPE_RGB, PNG_COLOR_TYPE_RGB_ALPHA.
1029
1030 =item interlace_method
1031
1032 The method of interlacing.
1033 If this is omitted, it's set to PNG_INTERLACE_NONE. This can have the values PNG_INTERLACE_NONE, PNG_INTERLACE_ADAM7.
1034
1035
1036
1037
1038 =back
1039
1040 Other fields in the hash are ignored.
1041
1042 This function corresponds to C<png_set_IHDR> in libpng, with a single Perl hash reference
1043 used instead of the seven integers.
1044
1045 The values
1046 C<compression_method>, C<filter_method>,
1047 may be supplied by the user but are ignored since they may only take
1048 the value 0. See L<Unused arguments omitted>.
1049
1050 =head2 sig_cmp
1051
1052 if (sig_cmp ($should_be_png)) {
1053 print "Your data does not have a PNG signature.\n";
1054 }
1055
1056 This subroutine looks at C<$should_be_png> and checks whether its
1057 first bytes correspond to a valid PNG signature. It returns a true
1058 value if they do not.
1059
1060 It can also take two further arguments consisting of a byte offset and
1061 a number of bytes to check respectively:
1062
1063 sig_cmp ($should_be_png, 0, 8);
1064
1065 If these arguments are not supplied, the byte offset is assumed
1066 to be zero, and the number of bytes to check is assumed to be eight.
1067
1068 This function corresponds to C<png_sig_cmp> in libpng, with default arguments of
1069 0 and 8 if second and third arguments are not supplied.
1070
1071 =head2 width
1072
1073 my $width = $png->width ();
1074
1075 Alias for L</get_image_width>. This is not exported, it's
1076 intended for use with the object only.
1077
1078 =head1 Image data
1079
1080 These functions deal with accessing the image data itself.
1081
1082 =head2 get_rowbytes
1083
1084 my $bytes_in_a_row = $png->get_rowbytes ();
1085
1086 This returns the number of bytes needed to hold a transformed row of
1087 an image.
1088
1089 This function corresponds to C<png_get_rowbytes> in libpng.
1090
1091 =head2 get_rows
1092
1093 my $rows = $png->get_rows ();
1094 my $pixel = substr ($rows->[10], 20, 1);
1095
1096 This returns the rows of the PNG image, after uncompressing and
1097 unfiltering, as binary data. The return value, C<$rows> in the
1098 example, is an array reference with a number of rows equal to the
1099 height of the PNG image. Each element of the array reference is a
1100 string containing the binary data making up a row of the image. The
1101 values of individual pixels can be extracted from using a function
1102 such as C<substr> or C<unpack>. This binary data is likely to contain
1103 bytes equal to zero.
1104
1105 L</get_rowbytes> gives the number of bytes in each row.
1106
1107 Each row is a Perl string. Perl terminates each row of data with an
1108 extra zero byte at the end.
1109
1110 This function corresponds to C<png_get_rows> in libpng.
1111
1112 =head2 set_rows
1113
1114 $png->set_rows (\@rows);
1115
1116 Set the rows of data to be written in to the PNG to C<@rows>. C<@rows>
1117 needs to contain at least the same number of rows of data as the
1118 height of the PNG image set with L</set_IHDR>, and the length of each
1119 entry needs to be at least the width of the image multiplied by the
1120 number of bytes required for each pixel.
1121
1122 This function was changed to copy the data in version 0.46.
1123
1124 This function corresponds to C<png_set_rows> in libpng.
1125
1126 =head1 Text chunks
1127
1128 See L<this subsection|http://www.w3.org/TR/PNG/#11textinfo>
1129 of L</The PNG specification> for information on the PNG standards for
1130 text information.
1131
1132 =head2 get_text
1133
1134 my $text_chunks = $png->get_text ();
1135
1136 This gets all of the text chunks in the PNG image and returns them as
1137 an array reference. Each element of the array represents one text
1138 chunk. This element is a hash reference with keys such as C<key>,
1139 C<lang_key>, or C<compression> taken from the PNG's information.
1140
1141 The text data is uncompressed by libpng. If it is international text
1142 (C<ITXT>), it is put into Perl's internal Unicode encoding if it is
1143 found to be valid UTF-8. (PNG "international text", C<ITXT> is
1144 required to be in the UTF-8 encoding, and non-international text is
1145 required to contain whitespace and printable ASCII characters
1146 only. See L</The PNG specification> for more on the requirements of a PNG text
1147 section.)
1148
1149 This function corresponds to C<png_get_text> in libpng, with a Perl array of hash references
1150 substituted for the C array of structs used by libpng. See
1151 L</set_text> for details of the keys and values which may be returned.
1152
1153 =head2 set_text
1154
1155 $png->set_text ([\%chunk1, \%chunk2]);
1156
1157 This sets the text chunks in a writeable image. The input value is an
1158 array reference containing one or more hash references. Each hash
1159 reference must have a C<key> value for the text. According to the PNG
1160 specification, this should be between one and 79 bytes in length. This
1161 module enforces that restriction, so if you supply a key longer than
1162 that, the chunk cannot be added. A hash reference may also have the
1163 following:
1164
1165 =over
1166
1167 =item C<compression>
1168
1169 The value of C<compression> controls the compression of the
1170 text. If C<compression> is not supplied, a default value of
1171 PNG_TEXT_COMPRESSION_NONE is applied. The C<compression> field can
1172 take the following values, available from L<Image::PNG::Const>:
1173
1174 =over
1175
1176 =item PNG_TEXT_COMPRESSION_NONE
1177
1178 TEXT = Printable ASCII and space characters.
1179
1180 =item PNG_TEXT_COMPRESSION_zTXt
1181
1182 TEXT = Printable ASCII and space characters.
1183
1184 =item PNG_ITXT_COMPRESSION_NONE
1185
1186 ITXT = International text, should be UTF-8.
1187
1188 =item PNG_ITXT_COMPRESSION_zTXt
1189
1190 ITXT = International text, should be UTF-8.
1191
1192 =back
1193
1194 =item C<itxt_length>
1195
1196 The string length of international text in bytes.
1197
1198 ⛐ðŸĪŠâš  This is ignored by libpng when writing text chunks. When
1199 reading text chunks, if the text is marked as international text,
1200 libpng adds the length of the string in bytes in this field rather
1201 than in L</text_length>.
1202
1203 =item C<lang>
1204
1205 This should be set to name of the language of the text, if the text
1206 chunk is iTXt. According to the PNG specification, "It is an ISO
1207 646.IRV:1991 [ISO 646] string consisting of hyphen-separated words of
1208 1-8 alphanumeric characters each (for example cn, en-uk, no-bok,
1209 x-klingon, x-KlInGoN)."
1210
1211 Support for writing C<lang> was added in version 0.49 of this
1212 module. (Prior to that undocumented support existed via a
1213 differently-named key.)
1214
1215 ⛐ðŸĪŠâš  This module does not attempt to check the supplied value,
1216 but merely passes it to libpng. libpng appears not to check the value
1217 either, nor to enforce restrictions on its length.
1218
1219 =item C<lang_key>
1220
1221 This corresponds to the "Translated keyword" of the PNG
1222 specification. Note that the user needs to supply C<key> and L</lang>
1223 as well as C<lang_key>.
1224
1225 Support for writing C<lang_key> was added in version 0.49 of this
1226 module. (Prior to that undocumented support existed via a
1227 differently-named key.)
1228
1229 =item C<text>
1230
1231 The value of "text" is added to the PNG as the text segment. This can
1232 be omitted if you just want to write a key value without any
1233 accompanying text.
1234
1235 =item C<text_length>
1236
1237 The string length in bytes. The user may set this, but it is ignored
1238 when writing PNG text chunks, instead this module uses the string
1239 length obtained from Perl. This key contains the length of the string
1240 when reading text chunks via L</get_text>, but if the text is marked
1241 as international text, L</itxt_length> is used to return its length in
1242 bytes, rather than this.
1243
1244 =back
1245
1246 Whether or not the value of C<text> is an ITXT field is decided by the
1247 value of C<compression>.
1248
1249 People who want to fiddle with the text compression applied can do so
1250 via L</set_text_compression_level> and the other functions described
1251 below that.
1252
1253 If C<set_text> is called more than once, the chunks are not overwritten but
1254 appended to the existing ones. (This behaviour is from libpng itself.)
1255
1256 Prior to version 0.50, C<set_text> would fail silently if the user
1257 added invalid chunks, for example hash references without a valid
1258 C<key>, or things which were not hash references at all. From version
1259 0.50, all invalid inputs cause fatal errors. However, unknown keys in
1260 the hash references do not cause fatal errors.
1261
1262 This function corresponds to C<png_set_text> in libpng.
1263
1264 =head3 Example
1265
1266
1267 use utf8;
1268 use Image::PNG::Const ':all';
1269 use Image::PNG::Libpng ':all';
1270 my $png = create_write_struct ();
1271 $png->set_IHDR ({width => 1, height => 1, bit_depth => 8,
1272 color_type => PNG_COLOR_TYPE_GRAY});
1273 $png->set_rows (['X']);
1274 $png->set_text ([{
1275 compression => PNG_TEXT_COMPRESSION_NONE,
1276 key => "Copyright",
1277 text => "Copyright (C) 2020 Fat Cat",
1278 }, {
1279 compression => PNG_ITXT_COMPRESSION_zTXt,
1280 key => "Copyright",
1281 lang_key => '著者æĻĐ',
1282 lang => 'ja_JP',
1283 text => 'ÂĐäŧĪ和åđīčŒ‰čŽ‰ãƒ‹ãƒĢãƒģバマゎマさん',
1284 }]);
1285 $png->write_png_file ('copyright.png');
1286
1287 (This example is included as L<F<examples/set-text.pl>|https://fastapi.metacpan.org/source/BKB/Image-PNG-Libpng-0.60/examples/set-text.pl>
1288 in the distribution.)
1289
1290
1291 =head2 text_compression_name
1292
1293 my $name = Image::PNG::Libpng::text_compression_name ($text->{compression});
1294
1295 Given a numerical text compression type, return the equivalent
1296 name. The name is in upper case. The possible return values are
1297
1298 =over
1299
1300 =item TEXT_NONE
1301
1302 =item TEXT_zTXt
1303
1304 =item ITXT_NONE
1305
1306 =item ITXT_zTXt
1307
1308 =item an empty string
1309
1310 if the compression method is unknown.
1311
1312 =back
1313
1314 The compression field is also used to store the information about
1315 whether the text is "international text" in UTF-8 or not.
1316
1317 This function does not correspond to anything in libpng. The names of
1318 the text compression types are based on those in C<png.h>, but without
1319 the word "COMPRESSION", so for example the libpng constant
1320 C<PNG_ITXT_COMPRESSION_zTXt> corresponds to a return value of
1321 C<ITXT_zTXt>.
1322
1323 =head1 Private chunks
1324
1325 See L<this subsection|http://www.w3.org/TR/PNG/#12Use-of-private-chunks>
1326 of L</The PNG specification> for information on the PNG
1327 standards for private chunks.
1328
1329 To test whether your version of libpng supports C<private chunks>, use
1330 L</libpng_supports> with argument 'L</UNKNOWN_CHUNKS>':
1331
1332 if (libpng_supports ('UNKNOWN_CHUNKS')) {
1333 # do something
1334 }
1335
1336 =head2 get_chunk_malloc_max
1337
1338 my $max = $png->get_chunk_malloc_max ();
1339
1340 This gets the maximum amount of memory that a chunk can use.
1341
1342 To test whether your version of libpng supports C<get_chunk_malloc_max>, use
1343 L</libpng_supports> with argument 'L</CHUNK_MALLOC_MAX>':
1344
1345 if (libpng_supports ('CHUNK_MALLOC_MAX')) {
1346 # do something
1347 }
1348
1349 This function corresponds to C<png_get_chunk_malloc_max> in libpng
1350
1351 =head2 set_chunk_malloc_max
1352
1353 $png->set_chunk_malloc_max ($max);
1354
1355 This sets the maximum amount of memory that a chunk can use. The
1356 default value of libpng 1.6.45 is 8 megabytes.
1357
1358 To test whether your version of libpng supports C<get_chunk_malloc_max>, use
1359 L</libpng_supports> with argument 'L</CHUNK_MALLOC_MAX>':
1360
1361 if (libpng_supports ('CHUNK_MALLOC_MAX')) {
1362 # do something
1363 }
1364
1365 This function corresponds to C<png_set_chunk_malloc_max> in libpng
1366
1367 =head2 set_keep_unknown_chunks
1368
1369 use Image::PNG::Const 'PNG_HANDLE_CHUNK_ALWAYS';
1370 $png->set_keep_unknown_chunks (PNG_HANDLE_CHUNK_ALWAYS);
1371
1372 Tell libpng not to discard unknown chunks when reading the file.
1373
1374 =head2 get_unknown_chunks
1375
1376 my $private_chunks = $png->get_unknown_chunks ();
1377 # Get some data from a private chunk
1378 my $chunk_three_data = $private_chunks->[3]->{data};
1379 # Get the size of the data
1380 print length $chunk_three_data;
1381
1382 This gets all of the private chunks from the image. The return value
1383 is an array reference containing hash references. If there are no
1384 private chunks, this returns an undefined value. There is one element
1385 of the array for each chunk member. It is necessary to call
1386 L</set_keep_unknown_chunks> with an appropriate value before reading
1387 the file, otherwise libpng discards unknown chunks when reading the
1388 file.
1389
1390 Each member hash reference has the following keys:
1391
1392 =over
1393
1394 =item name
1395
1396 The name of the unknown chunk, in the PNG chunk format (four bytes).
1397
1398
1399 =item location
1400
1401 The location of the unknown chunk.
1402
1403
1404 =item data
1405
1406 The data of the unknown chunk
1407
1408
1409 =back
1410
1411 The "size" field of the PNG structure is not stored, because the
1412 "data" member of the hash contains information on its length.
1413
1414 This function corresponds to C<png_get_unknown_chunks> in libpng
1415
1416 =head2 set_unknown_chunks
1417
1418 $png->set_unknown_chunks (name => 'dUCk', data => 'abcdefg',
1419 location => PNG_AFTER_IDAT);
1420
1421 ⛐ðŸĪŠâš  This currently does not fully function.
1422
1423 This function corresponds to C<png_set_unknown_chunks> in libpng
1424
1425 =head1 Library version functions
1426
1427 =head2 access_version_number
1428
1429 my $libpng_version_number = Image::PNG::Libpng::access_version_number ();
1430
1431 This function returns the version of the libpng library which the
1432 module is using as an integer number.
1433
1434 This function corresponds to C<png_access_version_number> in libpng.
1435
1436 =head2 get_libpng_ver
1437
1438 my $libpng_version = Image::PNG::Libpng::get_libpng_ver ();
1439
1440 This function returns the version of the libpng library which the
1441 module is using.
1442
1443 This function corresponds to C<png_get_libpng_ver> in libpng. However, it doesn't require the
1444 C<png_structp> argument of the C function. See L<Unused arguments omitted>.
1445
1446 =head1 Compression and filtering
1447
1448
1449
1450 =head2 get_compression_buffer_size
1451
1452 my $size = $png->get_compression_buffer_size ();
1453
1454 Returns the value of the compression buffer size, which may be altered
1455 with L</set_compression_buffer_size>.
1456
1457 =head2 set_compression_buffer_size
1458
1459 $png->set_compression_buffer_size (100);
1460
1461 Set the size of the buffer which zlib uses to compress or decompress
1462 the image data. It takes one argument, an integer number. This cannot
1463 be less than 6.
1464
1465 =head2 set_compression_level
1466
1467 $png->set_compression_level ($number);
1468
1469 Set the compression level used to make the PNG. A value of 0
1470 (C<Z_NO_COMPRESSION>) corresponds to no compression at all, otherwise
1471 C<$number> may take values of 1 (C<Z_BEST_SPEED>) to 9
1472 (C<Z_BEST_COMPRESSION>), with smaller values giving faster, and
1473 larger values giving better, that is with smaller output,
1474 compression. These correspond to the -1, -2, ... -9 options to the
1475 C<gzip> utility, or the compression level parameter of
1476 C<zlib>. Calling with C<-1> (C<Z_DEFAULT_COMPRESSION>)
1477 reverts to the default compression. Calling with any other number
1478 outside the range 0 to 9 results in a fatal error.
1479
1480 This function was added to the module in version 0.49.
1481
1482
1483 =head2 set_compression_mem_level
1484
1485 $png->set_compression_mem_level ($argument);
1486
1487 ⛐ðŸĪŠâš  Untested function corresponding to C<png_set_compression_mem_level>. Takes one integer argument.
1488
1489
1490 Sets the C<memLevel> parameter of C<deflateInit2> in zlib when writing
1491 PNG image data. Argument between 1 for minimum memory and 9 for
1492 maximum speed. The default is 8. See L</zlib documentation>.
1493
1494
1495 =head2 set_compression_window_bits
1496
1497 $png->set_compression_window_bits ($argument);
1498
1499 ⛐ðŸĪŠâš  Untested function corresponding to C<png_set_compression_window_bits>. Takes one integer argument.
1500
1501
1502 Sets the C<windowBits> parameter of C<deflateInit2> in zlib when
1503 writing PNG image data. Argument value must be between 8 and 15 for
1504 libpng. The default is 15. See the L</zlib documentation>.
1505
1506
1507 =head2 set_compression_strategy
1508
1509 $png->set_compression_strategy ($argument);
1510
1511 ⛐ðŸĪŠâš  Untested function corresponding to C<png_set_compression_strategy>. Takes one integer argument.
1512
1513
1514 Sets the C<strategy> parameter of C<deflateInit2> when writing PNG
1515 image data. Setting this with libpng overrides libpng's default
1516 behaviour of changing the value depending on the filter in use. For
1517 zlib, the argument is either 0 for default behaviour, or 1 to 4. See
1518 the L</zlib documentation>. libpng uses the default strategy 0
1519 (C<Z_DEFAULT_STRATEGY>) for unfiltered image data, and 1
1520 (C<Z_FILTERED>) for filtered image data.
1521
1522 =head2 set_filter
1523
1524 use Image::PNG::Const 'PNG_FILTER_NONE';
1525 $png->set_filter (PNG_FILTER_NONE);
1526
1527 This sets the filters which are allowed to be used for writing a PNG
1528 image. The possible values are
1529
1530 =over
1531
1532 =item PNG_NO_FILTERS
1533
1534 =item PNG_FILTER_NONE
1535
1536 =item PNG_FILTER_SUB
1537
1538 =item PNG_FILTER_UP
1539
1540 =item PNG_FILTER_AVG
1541
1542 =item PNG_FILTER_PAETH
1543
1544 =item PNG_ALL_FILTERS
1545
1546 =back
1547
1548 These can be combined using C<|> (logical or):
1549
1550 use Image::PNG::Const ':all';
1551 set_filter ($png, PNG_FILTER_UP | PNG_FILTER_AVG);
1552
1553 Please see L<this subsection|http://www.w3.org/TR/PNG/#9Filter-types>
1554 of L</The PNG specification> for the meanings of these
1555 filter types.
1556
1557 This function corresponds to C<png_set_filter> in libpng with the second (unused)
1558 argument omitted. See L<Unused arguments omitted>.
1559
1560
1561 =head2 set_text_compression_level
1562
1563 $png->set_text_compression_level ($argument);
1564
1565 ⛐ðŸĪŠâš  Untested function corresponding to C<png_set_text_compression_level>. Takes one integer argument.
1566
1567
1568 As L</set_compression_level> but for compressed text.
1569
1570
1571 =head2 set_text_compression_mem_level
1572
1573 $png->set_text_compression_mem_level ($argument);
1574
1575 ⛐ðŸĪŠâš  Untested function corresponding to C<png_set_text_compression_mem_level>. Takes one integer argument.
1576
1577
1578 As L</set_compression_mem_level> but for compressed text.
1579
1580
1581 =head2 set_text_compression_window_bits
1582
1583 $png->set_text_compression_window_bits ($argument);
1584
1585 ⛐ðŸĪŠâš  Untested function corresponding to C<png_set_text_compression_window_bits>. Takes one integer argument.
1586
1587
1588 As L</set_compression_window_bits> but for compressed text.
1589
1590
1591 =head2 set_text_compression_strategy
1592
1593 $png->set_text_compression_strategy ($argument);
1594
1595 ⛐ðŸĪŠâš  Untested function corresponding to C<png_set_text_compression_strategy>. Takes one integer argument.
1596
1597
1598 As L</set_compression_strategy> but for compressed text.
1599
1600 =head1 Other chunks
1601
1602 These routines deal with the other possible chunks of PNGs.
1603
1604 The getter and setter routines for all other chunks are designed so
1605 that the return value of C<get_wXYZ> is able to be used directly as
1606 the value for C<set_wXYZ>, so the values of chunks can easily be
1607 copied from one PNG to another.
1608
1609 my $values = $png1->get_wXYZ ();
1610 $png2->set_wXYZ ($values);
1611
1612 If the chunk is not present, or if the chunk is not supported by the
1613 user's version of libpng, the return value of C<get_wXYZ> is the
1614 undefined value.
1615
1616 =head2 bKGD
1617
1618 The background color of the PNG image.
1619
1620 See L<this subsection|http://www.w3.org/TR/PNG/#11bKGD>
1621 of L</The PNG specification> for information on the PNG standards for
1622 the background chunk.
1623
1624 =head3 get_bKGD
1625
1626 my $bkgd = $png->get_bKGD ();
1627
1628 Get the bKGD (background) chunk of the image.
1629
1630 The return value is a hash with the following keys, depending on the
1631 color type of the image:
1632
1633 =over
1634
1635 =item index
1636
1637 For palette color types, this is the offset into the palette.
1638
1639 =item gray
1640
1641 For grayscale color types.
1642
1643 =item red
1644
1645 =item green
1646
1647 =item blue
1648
1649 =back
1650
1651 This function corresponds to C<png_get_bKGD> in libpng with a hash function instead of a
1652 C<png_color> struct.
1653
1654 =head3 set_bKGD
1655
1656 $png->set_bKGD ($bkgd);
1657
1658 Set the bKGD (background) chunk of the image. C<$bkgd> is a hash
1659 reference. The keys of the hash reference are as described in
1660 L</get_bKGD>.
1661
1662 This function corresponds to C<png_set_bKGD> in libpng with a hash function instead of a
1663 C<png_color> struct.
1664
1665 =head2 cHRM
1666
1667 See L<this subsection|http://www.w3.org/TR/PNG/#11cHRM>
1668 of L</The PNG specification> "cHRM Primary chromaticities and white
1669 point".
1670
1671 =head3 get_cHRM
1672
1673 my $cHRM = $png->get_cHRM ();
1674
1675 Get the cHRM chunk as a hash reference.
1676
1677 The keys of the hash are white_x, white_y, red_x, red_y, green_x, green_y, blue_x, blue_y.
1678
1679 The values of the hash are floating point numbers between 0 and 1.
1680
1681 This function corresponds to C<png_get_cHRM> in libpng with a hash reference supplying the
1682 arguments. The hash's keys correspond to the names of the C<double>
1683 arguments in libpng.
1684
1685 =head3 get_cHRM_XYZ
1686
1687 my $cHRM = $png->get_cHRM_XYZ ();
1688
1689 Get the cHRM chunk as a hash reference for the XYZ color space.
1690
1691 The keys of the hash are red_x, red_y, red_z, green_x, green_y, green_z, blue_x, blue_y, blue_z.
1692
1693 The values of the hash are floating point numbers between 0 and 1.
1694
1695 This function corresponds to C<png_get_cHRM_XYZ> in libpng with a hash reference supplying the
1696 arguments. The hash's keys correspond to the names of the C<double>
1697 arguments in libpng.
1698
1699 =head3 set_cHRM
1700
1701 $png->set_cHRM (\%cHRM);
1702
1703 Set the cHRM chunk from a hash reference.
1704
1705 The keys of the hash are as for L</get_cHRM>. The values are floating
1706 point numbers between 0 and 1.
1707
1708 This function corresponds to C<png_set_cHRM> in libpng with a hash reference instead of the C<double>
1709 arguments.
1710
1711 =head3 set_cHRM_XYZ
1712
1713 $png->set_cHRM_XYZ (\%cHRM);
1714
1715 Set the cHRM chunk from a hash reference for the XYZ color space.
1716
1717 The keys of the hash are as for L</get_cHRM_XYZ>. The values are
1718 floating point numbers between 0 and 1. The C<Y> values C<red_y>,
1719 C<green_y>, and C<blue_y> should sum to 1. If you supply values
1720 outside the allowed range, libpng corrects them silently on writing
1721 rather than producing an error.
1722
1723 This function corresponds to C<png_set_cHRM_XYZ> in libpng with a hash reference instead of the C<double>
1724 arguments.
1725
1726 =head2 eXIf
1727
1728 The C<eXIf> chunk is an extension to the PNG specification. See
1729 L<http://www.simplesystems.org/png-group/proposals/eXIf/>. Support for
1730 this chunk was added in version 0.50 of this module.
1731
1732 =head3 get_eXIf
1733
1734 my $exif = $png->get_eXIf ();
1735
1736 This retrieves the C<eXIf> chunk from C<$png> but does not process the
1737 internal information.
1738
1739 =head3 set_eXIf
1740
1741 $png->set_eXIf ($exif);
1742
1743 libpng checks whether the chunk's first two bytes are either C<II> for
1744 little-endian (from Intel) or C<MM> for big-endian (from Motorola)
1745 then adds the entire chunk, including the first two bytes, to the PNG.
1746
1747 ⛐ðŸĪŠâš  As of December 2020, there appears to be a bug in libpng
1748 in which the eXIf chunk is added twice, causing a warning of the form
1749 C<libpng warning: eXIf: duplicate> on reading a PNG file back in. See
1750 L<https://github.com/glennrp/libpng/pull/351>.
1751
1752 =head2 gAMA
1753
1754 See L<this subsection|http://www.w3.org/TR/PNG/#11gAMA>
1755 of L</The PNG specification>.
1756
1757 =head3 get_gAMA
1758
1759 my $gamma = $png->get_gAMA ();
1760
1761 Get the gamma value or gAMA chunk. The return value is a
1762 floating-point number.
1763
1764 This function corresponds to C<png_get_gAMA> in libpng
1765
1766 =head3 set_gAMA
1767
1768 $png->set_gAMA (0.2);
1769
1770 Set the gamma value or gAMA chunk.
1771
1772 This function corresponds to C<png_set_gAMA> in libpng
1773
1774 =head2 hIST
1775
1776 See L<this subsection|http://www.w3.org/TR/PNG/#11hIST>
1777 of L</The PNG specification>.
1778
1779 =head3 get_hIST
1780
1781 my $hist = $png->get_hIST ();
1782
1783 If the PNG file contains a histogram, the return value is array
1784 reference, otherwise it is the undefined value. The number of entries
1785 in the array reference is the same as in the palette.
1786
1787 This function corresponds to C<png_get_hIST> in libpng
1788
1789 =head3 set_hIST
1790
1791 $png->set_hIST (\@hist);
1792
1793 Set the histogram of frequencies of the colors of a paletted (L</PLTE>)
1794 image. The entries of the histogram are 16 bit unsigned integers, so
1795 the maximum value that can be entered is 65535 = 2^16 - 1. Larger
1796 numbers and floating point numbers will cause a warning to be printed
1797 and the value to be set to zero. The histogram must have exactly the
1798 same number of entries as the palette or the call will fail with a
1799 warning. A histogram cannot be added to an image without a palette. A
1800 call to set_hIST for an image without a palette will cause a warning
1801 and return without setting the value.
1802
1803 (I'm not sure of the best form of error handling for this function so
1804 it may change in future versions to have errors for a bad histogram
1805 rather than warnings.)
1806
1807 This function corresponds to C<png_set_hIST> in libpng
1808
1809 =head2 iCCP
1810
1811 See L<this subsection|http://www.w3.org/TR/PNG/#11iCCP>
1812 of L</The PNG specification>.
1813
1814 =head3 get_iCCP
1815
1816 my $iccp = $png->get_iCCP ();
1817
1818 The return value is a hash with two keys,
1819
1820 =over
1821
1822 =item name
1823
1824 The name of the profile.
1825
1826 =item profile
1827
1828 The color profile.
1829
1830 =back
1831
1832 The C<compression_type> value, which is always 0, is not returned. See L<Unused arguments omitted>.
1833
1834 This function corresponds to C<png_get_iCCP> in libpng.
1835
1836 =head3 set_iCCP
1837
1838 $png->set_iCCP ({name => 'name', profile => 'profile'});
1839
1840 This function corresponds to C<png_set_iCCP> in libpng. For details of the arguments, see
1841 L</get_iCCP>. A C<compression_type> argument, which must always be 0
1842 anyway, is ignored. See L<Unused arguments omitted>.
1843
1844 =head2 oFFs
1845
1846 This is an extension to the PNG specification. See L<http://www.libpng.org/pub/png/spec/1.1/pngext-1.1.0-pdg.html#C.oFFs>.
1847
1848 =head3 get_oFFs
1849
1850 my $phys = $png->get_oFFs ();
1851
1852 Get oFFs chunk. Return value is a hash reference
1853
1854 This function corresponds to C<png_get_oFFs> in libpng
1855
1856 =head3 set_oFFs
1857
1858 $png->set_oFFs ({x_offset => 1, y_offset => 1, unit_type => 0});
1859
1860 Set oFFs chunk. See the specification linked above for the meanings of
1861 the parameters. If C<unit_type> is not 0 or 1, a warning is produced.
1862
1863 This function corresponds to C<png_set_oFFs> in libpng
1864
1865 =head2 pCAL
1866
1867 pCAL is an extension of the PNG specification which allows one to
1868 associate pixels in the PNG image with non-image data such as a heat
1869 map. See
1870 L<http://www.libpng.org/pub/png/spec/1.1/pngext-1.1.0-pdg.html#C.pCAL>.
1871
1872 To test whether your version of libpng supports C<the pCAL extension>, use
1873 L</libpng_supports> with argument 'L</pCAL>':
1874
1875 if (libpng_supports ('pCAL')) {
1876 # do something
1877 }
1878
1879 =head3 get_pCAL
1880
1881 my $pcal = $png->get_pCAL ();
1882
1883 The return value is a hash reference with the following keys:
1884
1885 =over
1886
1887 =item params
1888
1889 If this exists, its value is a reference to an array containing the
1890 parameter list of the pCAL chunk, which are floating point
1891 numbers. Within the PNG file chunk, these parameters are stored as
1892 strings representing floating point numbers, but you can pass in Perl
1893 floating point numbers rather than strings. The number of parameters
1894 you should set is fixed by the C<type> parameter. Refer to the PNG
1895 specification for full details.
1896
1897 =item purpose
1898
1899 The purpose string of the pCAL chunk.
1900
1901 =item type
1902
1903 The equation type as a number, from 0 to 3. See the PNG specification
1904 for the meanings. Other numbers cause an error.
1905
1906 =item units
1907
1908 The units as a string. See the PNG specification for details.
1909
1910 =item x0
1911
1912 The zero value for the equation, an integer.
1913
1914 =item x1
1915
1916 The max value for the equation, an integer.
1917
1918 =back
1919
1920 This function corresponds to C<png_get_pCAL> in libpng
1921
1922 =head3 set_pCAL
1923
1924 $png->set_pCAL (\%values);
1925
1926 See L</get_pCAL> for the parameters of C<%values>.
1927
1928 This function corresponds to C<png_set_pCAL> in libpng
1929
1930 =head2 pHYs
1931
1932 See L<this subsection|http://www.w3.org/TR/PNG/#11pHYs>
1933 of L</The PNG specification>.
1934
1935 =head3 get_pHYs
1936
1937 my $phys = $png->get_pHYs ();
1938
1939 The return value is a hash reference with the keys
1940
1941 =over
1942
1943 =item res_x
1944
1945 =item res_y
1946
1947 =item unit_type
1948
1949 Is either 0 or 1.
1950
1951 =back
1952
1953 This function corresponds to C<png_get_pHYs> in libpng
1954
1955 =head3 set_pHYs
1956
1957 $png->set_pHYs ({res_x => 1, res_y => 1, unit_type => 1});
1958
1959 This function corresponds to C<png_set_pHYs> in libpng
1960
1961 =head2 PLTE
1962
1963 See L<this subsection|http://www.w3.org/TR/PNG/#11PLTE>
1964 of L</The PNG specification> for information on the PNG standards for
1965 the palette chunk.
1966
1967 =head3 get_palette_max
1968
1969 my $pmax = $png->get_palette_max ();
1970
1971 If your libpng supports it, this will return the maximum palette index
1972 found in the image, or "-1" if the palette was not checked, or "0" if
1973 no palette was found.
1974
1975 To test whether your version of libpng supports C<get_palette_max>, use
1976 L</libpng_supports> with argument 'L</GET_PALETTE_MAX>':
1977
1978 if (libpng_supports ('GET_PALETTE_MAX')) {
1979 # do something
1980 }
1981
1982 ⛐ðŸĪŠâš  This function is implemented but so far it is not very
1983 clear to me what it does, since, for example, it returns zero for the
1984 test image F<t/tantei-san.png> which is an image with a fully-used
1985 256-color palette. I've L<asked about it on the libpng mailing
1986 list|https://sourceforge.net/p/png-mng/mailman/png-mng-implement/?viewmonth=202012&viewday=14>,
1987 but so far nobody has responded.
1988
1989 =head3 get_PLTE
1990
1991 my $colors = $png->get_PLTE ();
1992 # Get the green value of the twentieth entry in the palette.
1993 my $green = $colors->[20]->{green};
1994
1995 This function gets the palette from the PNG. The return value is an
1996 array reference containing the palette. This array contains hash
1997 references with the values "green", "blue" and "red" for the color of
1998 each pixel in the palette. If the PNG has no palette, it returns an
1999 undefined value.
2000
2001 A PNG image may or may not contain a palette. To check whether the
2002 image contains a palette, use something of the following form:
2003
2004 use Image::PNG::Const ':all';
2005 my $color_type = $png->get_color_type ();
2006 if ($color_type == PNG_COLOR_TYPE_PALETTE) {
2007 # The PNG uses a palette.
2008 }
2009
2010 A PNG image may also contain a palette even when the "color_type" does
2011 not indicate that. To check for that case, use L</get_valid>.
2012
2013 This function corresponds to C<png_get_PLTE> in libpng.
2014
2015 =head3 set_PLTE
2016
2017 $png->set_PLTE ($palette);
2018
2019 Set the palette of C<$png>. The argument is an array reference
2020 containing hash references. There is one hash reference for each
2021 palette entry. The hash references contain three fields, red, green,
2022 and blue, corresponding to the pixel value for that palette
2023 entry. Other values in the hash references are ignored. For example,
2024
2025 $png->set_PLTE ([{red => 1, green => 99, blue => 0x10},
2026 {red => 0xFF, green => 0xFF, blue => 0xFF}]);
2027
2028 creates a palette with two entries in C<$png>.
2029
2030 This function corresponds to C<png_set_PLTE> in libpng.
2031
2032 =head2 sBIT
2033
2034 See L<this subsection|http://www.w3.org/TR/PNG/#11sBIT>
2035 of L</The PNG specification>.
2036
2037 =head3 get_sBIT
2038
2039 my $sbit = $png->get_sBIT ();
2040
2041 The return value is a hash reference containing integer values for the
2042 keys C<red>, C<blue>, C<green>, C<gray> and C<alpha>, depending on the
2043 C<color_type> of C<$png>.
2044
2045 ⛐ðŸĪŠâš  Prior to version 0.50 of this module, get_sBIT wrote
2046 values of 0 for all of the keys, regardless of the C<color_type>,
2047 causing errors in some circumstances. From version 0.50, hash keys are
2048 not entered if the C<color_type> of the image makes them invalid.
2049
2050 This function corresponds to C<png_get_sBIT> in libpng
2051
2052 =head3 set_sBIT
2053
2054 $png->set_sBIT ({red => 1, blue => 2, green => 3});
2055
2056 The argument is a hash reference containing integer values for the
2057 keys C<red>, C<blue>, C<green>, C<gray>, and C<alpha>, as required by
2058 the C<color_type> of C<$png>.
2059
2060 This function corresponds to C<png_set_sBIT> in libpng
2061
2062 =head2 sCAL
2063
2064 This is an extension to the PNG specification. See
2065 L<http://www.libpng.org/pub/png/spec/1.1/pngext-1.1.0-pdg.html#C.sCAL>.
2066
2067 To test whether your version of libpng supports C<the sCAL chunk>, use
2068 L</libpng_supports> with argument 'L</sCAL>':
2069
2070 if (libpng_supports ('sCAL')) {
2071 # do something
2072 }
2073
2074 =head3 get_sCAL
2075
2076 my $scal = $png->get_sCAL ();
2077
2078 The returned hash value contains the following keys:
2079
2080 =over
2081
2082 =item unit
2083
2084 The unit type, which is either PNG_SCALE_UNKNOWN, PNG_SCALE_METER, or
2085 PNG_SCALE_RADIAN.
2086
2087 =item width
2088
2089 The width, as a string.
2090
2091 =item height
2092
2093 The height, as a string.
2094
2095 =back
2096
2097 This function corresponds to C<png_get_sCAL_s> in libpng. Note that this uses the sCAL_s function
2098 rather than the get_sCAL and the returned values are the strings
2099 themselves rather than parsed numbers.
2100
2101 =head3 set_sCAL
2102
2103 $png->set_sCAL ($scal);
2104
2105 C<$scal> is a hash reference containing the keys described in
2106 L</get_sCAL>.
2107
2108 This function corresponds to C<png_set_sCAL_s> in libpng. Note that this uses the C<set_sCAL_s>
2109 function rather than C<set_sCAL> and the input values are the strings
2110 themselves rather than numbers.
2111
2112 =head2 sPLT
2113
2114 See L<this subsection|http://www.w3.org/TR/PNG/#11sPLT>
2115 of L</The PNG specification>.
2116
2117 =head3 get_sPLT
2118
2119 ⛐ðŸĪŠâš  Provisional. See L</set_sPLT> for documentation, the
2120 return value is like the input of that.
2121
2122 =head3 set_sPLT
2123
2124 $png->set_sPLT ([{ name => 'palette', depth => 8, entries => [{red => 1, blue => 2},]}]);
2125
2126 Set suggested palettes. The input is an array reference containing
2127 hash references with the following fields:
2128
2129 =over
2130
2131 =item name
2132
2133 The name of the suggested palette.
2134
2135 =item depth
2136
2137 The depth of the suggested palette.
2138
2139 =item entries
2140
2141 The entries of the palette. This is an array reference containing hash
2142 references with keys as follows:
2143
2144 =over
2145
2146 =item red
2147
2148 =item blue
2149
2150 =item green
2151
2152 =item frequency
2153
2154 =item alpha
2155
2156 =back
2157
2158 =back
2159
2160 The field C<nentries> which is returned by L</get_sPLT> does not need
2161 to be specified, it is calculated from the length of C<entries>.
2162
2163 =head2 sRGB
2164
2165 See L<this subsection|http://www.w3.org/TR/PNG/#11sRGB>
2166 of L</The PNG specification>.
2167
2168 =head3 get_sRGB
2169
2170 my $sRGB = $png->get_sRGB ();
2171
2172 The return value is an integer number corresponding to one of the
2173 following:
2174
2175 =over
2176
2177 =item PNG_sRGB_INTENT_SATURATION
2178
2179 =item PNG_sRGB_INTENT_PERCEPTUAL
2180
2181 =item PNG_sRGB_INTENT_ABSOLUTE
2182
2183 =item PNG_sRGB_INTENT_RELATIVE
2184
2185 =back
2186
2187 This function corresponds to C<png_get_sRGB> in libpng
2188
2189 =head3 set_sRGB
2190
2191 $png->set_sRGB ($srgb);
2192
2193 C<$srgb> is one of the values described in L</get_sRGB>.
2194
2195 This function corresponds to C<png_set_sRGB> in libpng
2196
2197 =head2 tIME
2198
2199 See L<this subsection|http://www.w3.org/TR/PNG/#11timestampinfo>
2200 of L</The PNG specification> for information on the PNG standards for
2201 time stamp information.
2202
2203 =head3 get_tIME
2204
2205 my $time = $png->get_tIME ();
2206 if ($time && $time->{year} < 2005) {
2207 warn "Your PNG is now getting old. Don't forget to oil it to prevent rust.";
2208 }
2209
2210 The return value is either the undefined value, if no C<tIME> chunk
2211 exists in the PNG, or a hash reference containing fields C<year>,
2212 C<month>, C<day>, C<hour>, C<minute> and C<second>. C<month> and
2213 C<day> start from 1 rather than 0.
2214
2215 The "modification time value" of the PNG image is a chunk written into
2216 the PNG file itself, and may not have the same value as the operating
2217 system's modification time for the file. The tIME chunk is not a
2218 compulsory requirement for PNG files, and most PNG image files do not
2219 contain this chunk. PNG tIME chunks do not contain a time zone. According to L<this subsection|http://www.w3.org/TR/PNG/#11tIME>
2220 of L</The PNG specification>, "Universal Time (UTC) should be specified rather
2221 than local time."
2222
2223 This function corresponds to C<png_get_tIME> in libpng, with a Perl hash reference
2224 substituted for the C struct C<png_timep> used in libpng.
2225
2226 =head3 set_tIME
2227
2228 # Set the time to "now"
2229 $png->set_tIME ();
2230 # Set the time
2231 $png->set_tIME ({year => 1999, month => 12});
2232
2233 Set the modification time of the PNG to the values given by the
2234 argument, a hash reference containing the fields C<year>, C<month>,
2235 C<day> for the day of the month, C<hour>, C<minute>, and C<second>.
2236 The numbering for C<month> and C<day> is from 1, not 0. If any of
2237 year, hour, minute or second is omitted from the hash reference, these
2238 are set to zero. If month or day are omitted, these are set to 1. PNG tIME chunks do not contain a time zone. According to L<this subsection|http://www.w3.org/TR/PNG/#11tIME>
2239 of L</The PNG specification>, "Universal Time (UTC) should be specified rather
2240 than local time." If the entire argument is omitted or contains an invalid
2241 value, the time is set to the current time.
2242
2243 This function corresponds to C<png_set_tIME> in libpng, with a Perl hash reference
2244 substituted for the C struct C<png_timep> used in libpng.
2245
2246 =head2 tRNS
2247
2248 See L<this subsection|http://www.w3.org/TR/PNG/#11tRNS>
2249 of L</The PNG specification>.
2250
2251 =head3 get_tRNS
2252
2253 my $trns = $png->get_tRNS ();
2254
2255 Get the C<tRNS> chunk. If the image is a palette type, this is an
2256 array reference. If the image is a non-palette type, this is a hash
2257 containing values for the keys red, green, blue, and gray.
2258
2259 =head3 set_tRNS
2260
2261 $png->set_tRNS ($trns);
2262
2263 Set the C<tRNS> chunk. If the image is a palette type, C<$trns> is a
2264 reference to an array of positive or zero values between 0 and 255 of
2265 the same size as the palette. It must not contain more than 256
2266 values. If the image is not a palette type, C<$trns> is a hash
2267 reference containing values for the keys red, green, blue and gray.
2268
2269 =head1 Libpng transformations
2270
2271 =head2 set_bgr
2272
2273 $png->set_bgr ();
2274
2275 ⛐ðŸĪŠâš  Untested. Flips RGB to BGR. See the libpng manual for details.
2276
2277 To test whether your version of libpng supports C<set_bgr>, for a read
2278 object, use L</libpng_supports> with argument 'L</READ_BGR>'.
2279
2280 if (libpng_supports ('READ_BGR')) {
2281 # do something
2282 }
2283
2284 For a write object, use argument 'L</WRITE_BGR>'.
2285
2286 This function corresponds to C<png_set_bgr> in libpng
2287
2288 =head2 set_expand
2289
2290 $png->set_expand ();
2291
2292 Set transformation in C<$png> such that paletted images are expanded
2293 to RGB, grayscale images of bit-depth less than 8 are expanded to
2294 8-bit images, and tRNS chunks are expanded to alpha channels.
2295
2296 To test whether your version of libpng supports C<set_expand>, use
2297 L</libpng_supports> with argument 'L</READ_EXPAND>':
2298
2299 if (libpng_supports ('READ_EXPAND')) {
2300 # do something
2301 }
2302
2303 This function corresponds to C<png_set_expand> in libpng
2304
2305 =head2 set_expand_16
2306
2307 $png->set_expand_16 ();
2308
2309 ⛐ðŸĪŠâš  Untested.
2310
2311 To test whether your version of libpng supports C<set_expand_16>, use
2312 L</libpng_supports> with argument 'L</READ_EXPAND_16>':
2313
2314 if (libpng_supports ('READ_EXPAND_16')) {
2315 # do something
2316 }
2317
2318 This function corresponds to C<png_set_expand_16> in libpng
2319
2320 =head2 set_expand_gray_1_2_4_to_8
2321
2322 $png->set_expand_gray_1_2_4_to_8 ();
2323
2324 ⛐ðŸĪŠâš  Untested.
2325
2326 To test whether your version of libpng supports C<set_expand_gray_1_2_4_to_8>, use
2327 L</libpng_supports> with argument 'L</READ_EXPAND>':
2328
2329 if (libpng_supports ('READ_EXPAND')) {
2330 # do something
2331 }
2332
2333 This function corresponds to C<png_set_expand_gray_1_2_4_to_8> in libpng
2334
2335 =head2 set_gray_to_rgb
2336
2337 $png->set_gray_to_rgb ();
2338
2339 Convert a grayscale PNG file to RGB format on reading.
2340
2341 To test whether your version of libpng supports C<set_gray_to_rgb>, use
2342 L</libpng_supports> with argument 'L</READ_GRAY_TO_RGB>':
2343
2344 if (libpng_supports ('READ_GRAY_TO_RGB')) {
2345 # do something
2346 }
2347
2348 This function corresponds to C<png_set_gray_to_rgb> in libpng
2349
2350 =head2 set_invert_alpha
2351
2352 $png->set_invert_alpha ();
2353
2354 ⛐ðŸĪŠâš  Untested. See the libpng manual for details.
2355
2356 To test whether your version of libpng supports C<set_invert_alpha>, use
2357 L</libpng_supports> with argument 'L</READ_INVERT_ALPHA>':
2358
2359 if (libpng_supports ('READ_INVERT_ALPHA')) {
2360 # do something
2361 }
2362
2363 This function corresponds to C<png_set_invert_alpha> in libpng
2364
2365 =head2 set_invert_mono
2366
2367 $png->set_invert_mono ();
2368
2369 Invert monochrome images. See the libpng manual for details.
2370
2371 To test whether your version of libpng supports C<set_invert_mono>, use
2372 L</libpng_supports> with argument 'L</READ_INVERT>':
2373
2374 if (libpng_supports ('READ_INVERT')) {
2375 # do something
2376 }
2377
2378 This function corresponds to C<png_set_invert_mono> in libpng
2379
2380 =head2 set_packing
2381
2382 $png->set_packing ();
2383
2384 When reading a PNG, expand the image to 1 pixel per byte for
2385 bit-depths 1, 2 and 4 without changing the order of the pixels. If
2386 this is not called, the pixels of bit_depths 1, 2 and 4 are packed
2387 into bytes as small as possible, for example, 8 pixels per byte for
2388 1-bit files. See the libpng manual for details. See also L</set_packswap>.
2389
2390 To test whether your version of libpng supports C<set_packing>, for a read
2391 object, use L</libpng_supports> with argument 'L</READ_PACK>'.
2392
2393 if (libpng_supports ('READ_PACK')) {
2394 # do something
2395 }
2396
2397 For a write object, use argument 'L</WRITE_PACK>'.
2398
2399 This function corresponds to C<png_set_packing> in libpng
2400
2401 =head2 set_packswap
2402
2403 $png->set_packswap ();
2404
2405 Swaps the bits of 1, 2, or 4 bits/pixel images. The default for PNG
2406 image is to put the left pixel into the highest part of the byte, so
2407 for example if the bit depth is 1, the pixels from left to right go
2408 into a byte as values 128 for the leftmost, 64, 32, 16, 8, 4, 2, then
2409 1 for the rightmost pixel. This call reverses that behavior so that
2410 the pixels in a byte go 1 for the leftmost, 2, ..., then 128 for the
2411 rightmost. See the libpng manual for details.
2412
2413 To test whether your version of libpng supports C<set_packswap>, for a read
2414 object, use L</libpng_supports> with argument 'L</READ_PACKSWAP>'.
2415
2416 if (libpng_supports ('READ_PACKSWAP')) {
2417 # do something
2418 }
2419
2420 For a write object, use argument 'L</WRITE_PACKSWAP>'.
2421
2422 This function corresponds to C<png_set_packswap> in libpng
2423
2424 =head2 set_palette_to_rgb
2425
2426 $png->set_palette_to_rgb ();
2427
2428 ⛐ðŸĪŠâš  Untested. See the libpng manual for details.
2429
2430 To test whether your version of libpng supports C<set_palette_to_rgb>, use
2431 L</libpng_supports> with argument 'L</READ_EXPAND>':
2432
2433 if (libpng_supports ('READ_EXPAND')) {
2434 # do something
2435 }
2436
2437 This function corresponds to C<png_set_palette_to_rgb> in libpng
2438
2439 =head2 set_scale_16
2440
2441 $png->set_scale_16 ()
2442
2443 ⛐ðŸĪŠâš  Untested.
2444
2445 To test whether your version of libpng supports C<set_scale_16>, use
2446 L</libpng_supports> with argument 'L</READ_SCALE_16_TO_8>':
2447
2448 if (libpng_supports ('READ_SCALE_16_TO_8')) {
2449 # do something
2450 }
2451
2452 This function corresponds to C<png_set_scale_16> in libpng
2453
2454 =head2 set_strip_16
2455
2456 $png->set_strip_16 ();
2457
2458 Strip the pixels of a PNG stream with 16 bits per channel to 8 bits
2459 per channel.
2460
2461 To test whether your version of libpng supports C<set_strip_16>, use
2462 L</libpng_supports> with argument 'L</READ_STRIP_16_TO_8>':
2463
2464 if (libpng_supports ('READ_STRIP_16_TO_8')) {
2465 # do something
2466 }
2467
2468 This function corresponds to C<png_set_strip_16> in libpng
2469
2470 =head2 set_strip_alpha
2471
2472 $png->set_strip_alpha ();
2473
2474 Strip the alpha channel of a PNG stream.
2475
2476 To test whether your version of libpng supports C<set_strip_alpha>, use
2477 L</libpng_supports> with argument 'L</READ_STRIP_ALPHA>':
2478
2479 if (libpng_supports ('READ_STRIP_ALPHA')) {
2480 # do something
2481 }
2482
2483 This function corresponds to C<png_set_strip_alpha> in libpng
2484
2485 =head2 set_swap
2486
2487 $png->set_swap ();
2488
2489 ⛐ðŸĪŠâš  Untested. Swaps around the bytes of 16 bits/pixel
2490 images. See the libpng manual for details.
2491
2492 To test whether your version of libpng supports C<set_swap>, use
2493 L</libpng_supports> with argument 'L</READ_SWAP>':
2494
2495 if (libpng_supports ('READ_SWAP')) {
2496 # do something
2497 }
2498
2499 This function corresponds to C<png_set_swap> in libpng
2500
2501 =head2 set_swap_alpha
2502
2503 $png->set_swap_alpha ();
2504
2505 ⛐ðŸĪŠâš  Untested. See the libpng manual for details.
2506
2507 To test whether your version of libpng supports C<set_swap_alpha>, use
2508 L</libpng_supports> with argument 'L</READ_SWAP_ALPHA>':
2509
2510 if (libpng_supports ('READ_SWAP_ALPHA')) {
2511 # do something
2512 }
2513
2514 This function corresponds to C<png_set_swap_alpha> in libpng
2515
2516 =head2 set_tRNS_to_alpha
2517
2518 $png->set_tRNS_to_alpha
2519
2520 ⛐ðŸĪŠâš  Untested. See the libpng manual for details.
2521
2522 To test whether your version of libpng supports C<set_tRNS_to_alpha>, use
2523 L</libpng_supports> with argument 'L</READ_EXPAND>':
2524
2525 if (libpng_supports ('READ_EXPAND')) {
2526 # do something
2527 }
2528
2529 This function corresponds to C<png_set_tRNS_to_alpha> in libpng
2530
2531 =head1 Other libpng functions
2532
2533 =head2 get_chunk_cache_max
2534
2535 my $max = $png->get_chunk_cache_max ();
2536
2537 Get the maximum number of ancilliary chunks
2538 allowed. See also L</set_chunk_cache_max>.
2539
2540 To test whether your version of libpng supports C<get_chunk_cache_max>, use
2541 L</libpng_supports> with argument 'L</CHUNK_CACHE_MAX>':
2542
2543 if (libpng_supports ('CHUNK_CACHE_MAX')) {
2544 # do something
2545 }
2546
2547 This function corresponds to C<png_png_get_chunk_cache_max> in libpng
2548
2549 =head2 get_rgb_to_gray_status
2550
2551 my $badpixels = $png->get_rgb_to_gray_status ();
2552
2553 Returns a true value if there were some non-gray pixels in an RGB
2554 image after calling L</set_rgb_to_gray>.
2555
2556 =head3 Saving bandwidth
2557
2558 Try this one weird old C<get_rgb_to_gray_status> trick to check
2559 whether an image marked as RGB is really monochrome or not.
2560
2561
2562 use utf8;
2563 use FindBin '$Bin';
2564 use Image::PNG::Libpng ':all';
2565 use Image::PNG::Const ':all';
2566
2567 my $file = 'life.png';
2568 print "Size before: ", -s $file, "\n";
2569 my $png = create_reader ($file);
2570 $png->read_info ();
2571 $png->set_rgb_to_gray ();
2572 if ($png->get_rgb_to_gray_status ()) {
2573 print "The image contained non-gray pixels.\n";
2574 }
2575 else {
2576 print "The image was grayscale already.\n";
2577 }
2578 $png->read_image ();
2579 $png->read_end ();
2580 my $wpng = $png->copy_png ();
2581 my $ihdr = $wpng->get_IHDR ();
2582 $ihdr->{color_type} = PNG_COLOR_TYPE_GRAY;
2583 $wpng->set_IHDR ($ihdr);
2584 my $after = "life-gray.png";
2585 $wpng->write_png_file ($after);
2586 print "Size after: ", -s $after, "\n";
2587
2588 if (! png_compare ($file, $after)) {
2589 print "The two files contain exactly the same image data.\n";
2590 }
2591 else {
2592 print "The two files contain different image data.\n";
2593 }
2594
2595 (This example is included as L<F<examples/xkcd.pl>|https://fastapi.metacpan.org/source/BKB/Image-PNG-Libpng-0.60/examples/xkcd.pl>
2596 in the distribution.)
2597
2598
2599 The output looks like this:
2600
2601 Size before: 97299
2602 The image was grayscale already.
2603 Size after: 46956
2604 The two files contain exactly the same image data.
2605
2606
2607
2608
2609 L<examples/life-gray.png|https://fastapi.metacpan.org/source/BKB/Image-PNG-Libpng-0.60/examples/life-gray.png> is included in the distribution.
2610
2611 =begin html
2612
2613 <p>The resulting image looks like this:</p>
2614
2615 <!-- metacpan doesn't allow figure/figcaption tags. -->
2616 <table>
2617 <tr>
2618 <td>
2619 <img src="https://fastapi.metacpan.org/source/BKB/Image-PNG-Libpng-0.60/examples/life-gray.png">
2620 </td>
2621 </tr>
2622 <tr>
2623 <th>
2624 <a href='https://fastapi.metacpan.org/source/BKB/Image-PNG-Libpng-0.60/examples/life-gray.png'>examples/life-gray.png</a>
2625 </th>
2626 </tr>
2627 </table>
2628
2629 =end html
2630
2631
2632 Correct use of Image::PNG::Libpng could have spared as many as 50,000
2633 bytes from the indignity of being sent around the internet.
2634
2635 This also illustrates the use of L</png_compare>.
2636
2637 L<Original image, licence statement and copyright notice
2638 here|https://xkcd.com/2391/>.
2639
2640
2641
2642 =head2 get_user_height_max
2643
2644 $png->get_user_height_max ();
2645
2646 Get the maximum height allowed for a PNG file. The default is 1
2647 million pixels. These values can be changed by L</set_user_limits>.
2648
2649 This function corresponds to C<png_get_user_height_max> in libpng
2650
2651
2652
2653 =head2 get_user_width_max
2654
2655 $png->get_user_width_max ();
2656
2657 Get the maximum width allowed for a PNG file. The default is 1
2658 million pixels. These values can be changed by L</set_user_limits>.
2659
2660 This function corresponds to C<png_get_user_width_max> in libpng
2661
2662
2663
2664 =head2 permit_mng_features
2665
2666 $png->permit_mng_features ($mask);
2667
2668 ⛐ðŸĪŠâš  Untested. C<$mask> is an integer containing flags. See the libpng manual for details.
2669
2670 (MNG, 'Multiple-image Network Graphics', is an image animation format
2671 related to PNG. It has not been widely adopted.)
2672
2673 To test whether your version of libpng supports C<permit_mng_features>, use
2674 L</libpng_supports> with argument 'L</MNG_FEATURES>':
2675
2676 if (libpng_supports ('MNG_FEATURES')) {
2677 # do something
2678 }
2679
2680 This function corresponds to C<png_permit_mng_features> in libpng
2681
2682 =head2 set_add_alpha
2683
2684 $png->set_add_alpha ($filler, $filler_loc);
2685
2686 ⛐ðŸĪŠâš  Untested. Change C<$png> to add an alpha channel. This
2687 only works for grayscale or RGB images with bit depth of 8 or
2688 16. C<$filler> contains the alpha value to assign to each pixel, and
2689 C<$filler_loc> is either C<PNG_FILLER_BEFORE> or
2690 C<PNG_FILLER_AFTER>. The function of C<set_add_alpha> is
2691 L</set_filler> and a change of the color type to add an alpha
2692 channel. See the libpng manual for details.
2693
2694 To test whether your version of libpng supports C<set_add_alpha>, use
2695 L</libpng_supports> with argument 'L</READ_FILLER>':
2696
2697 if (libpng_supports ('READ_FILLER')) {
2698 # do something
2699 }
2700
2701 This function corresponds to C<png_set_add_alpha> in libpng
2702
2703 =head2 set_alpha_mode
2704
2705 $png->set_alpha_mode ($mode, $screen_gamma);
2706
2707 ⛐ðŸĪŠâš  Untested. C<$mode> is an integer, one of the
2708 C<PNG_ALPHA_*> constants. C<$screen_gamma> is a floating point
2709 number. See the libpng manual for details.
2710
2711 To test whether your version of libpng supports C<set_alpha_mode>, use
2712 L</libpng_supports> with argument 'L</READ_ALPHA_MODE>':
2713
2714 if (libpng_supports ('READ_ALPHA_MODE')) {
2715 # do something
2716 }
2717
2718 This function corresponds to C<png_set_alpha_mode> in libpng
2719
2720 =head2 set_background
2721
2722 $png->set_background (\%color, $bkgd_gamma_code, $need_expand, $gamma);
2723
2724 C<set_background> sets the background of an image with an alpha
2725 channel or simple transparency (a L</tRNS> chunk) with the color
2726 specified by C<%color>. If C<$bkgd_gamma_code> is set to
2727 C<PNG_BACKGROUND_GAMMA_SCREEN>, it indicates that the supplied
2728 background color is in the gamma space of the display, else if it is
2729 set to C<PNG_BACKGROUND_GAMMA_FILE>, the color is in the gamma space
2730 of the file. If C<$bkgd_gamma_code> is set to
2731 C<PNG_BACKGROUND_GAMMA_UNIQUE>, the value of C<$gamma> is used,
2732 otherwise C<$gamma> appears to be ignored and can be omitted. (This is
2733 not documented in the libpng manual or elsewhere. See
2734 L<https://github.com/glennrp/libpng/issues/358>.)
2735
2736 If the background color is supplied at the original bit-depth for a
2737 grayscale image that is expanded to truecolor or to a higher
2738 bit-depth, C<$need_expand> must be set to a true value, but if the
2739 background color is supplied at the expanded bit-depth,
2740 C<$need_expand> must be set to a false value. Similarly for paletted
2741 images, if C<%color> is supplied as a palette index
2742 (C<$color{index}>), C<$need_expand> must be set to a true value, but
2743 if C<%color> is an RGB triplet, C<$need_expand> must be set to a false
2744 value.
2745
2746 See L</Setting the background> for an example.
2747
2748 To test whether your version of libpng supports C<set_background>, use
2749 L</libpng_supports> with argument 'L</READ_BACKGROUND>':
2750
2751 if (libpng_supports ('READ_BACKGROUND')) {
2752 # do something
2753 }
2754
2755 =head2 set_chunk_cache_max
2756
2757 $png->set_chunk_cache_max (42);
2758
2759 Set the maximum number of ancilliary chunks allowed. The default is
2760 1000. See also L</get_chunk_cache_max>.
2761
2762 To test whether your version of libpng supports C<set_chunk_cache_max>, use
2763 L</libpng_supports> with argument 'L</CHUNK_CACHE_MAX>':
2764
2765 if (libpng_supports ('CHUNK_CACHE_MAX')) {
2766 # do something
2767 }
2768
2769 This function corresponds to C<png_png_set_chunk_cache_max> in libpng
2770
2771 =head2 set_filler
2772
2773 $png->set_filler ($filler, $flags);
2774
2775 Set transformations in C<$png> such that a filler byte C<$filler> is
2776 added when an 8-bit grayscale image or 24-bit RGB image is read, and a
2777 filler byte is deleted when an 8-bit grayscale image or 24-bit RGB
2778 image is written. C<$flags> may be C<PNG_FILLER_BEFORE> or
2779 C<PNG_FILLER_AFTER>. An error is produced if C<$png> has bit depth
2780 less than 8.
2781
2782 This does not change the color type of the image. See the related
2783 function L</set_add_alpha> if you want to add an alpha channel.
2784
2785 To test whether your version of libpng supports C<set_filler>, use
2786 L</libpng_supports> with argument 'L</READ_FILLER>':
2787
2788 if (libpng_supports ('READ_FILLER')) {
2789 # do something
2790 }
2791
2792 This function corresponds to C<png_set_filler> in libpng
2793
2794 =head2 set_gamma
2795
2796 $png->set_gamma ($screen_gamma, $output_gamma);
2797
2798 ⛐ðŸĪŠâš  Untested. C<$screen_gamma> and C<$output_gamma> should
2799 contain floating-point arguments. See the libpng manual for details.
2800
2801 To test whether your version of libpng supports C<set_gamma>, use
2802 L</libpng_supports> with argument 'L</READ_GAMMA>':
2803
2804 if (libpng_supports ('READ_GAMMA')) {
2805 # do something
2806 }
2807
2808 This function corresponds to C<png_set_gamma> in libpng
2809
2810 =head2 set_quantize
2811
2812 $png->set_quantize (\@palette, $ncolors, \@histogram, $full_quantize);
2813
2814 The C<@palette> part must be set to a palette similar to
2815 L</set_PLTE>. C<$ncolors> must be the length of C<@palette> or
2816 shorter. C<@histogram> can be an empty array or if not it needs to be
2817 an array of integers of exactly the same length as C<@palette>. The
2818 integers represent the frequency of the colors in C<@palette>. These
2819 integers can range from 0 to 65355. Larger values or negative values
2820 cause an error. The final argument, C<$full_quantize>, should be 1 for
2821 RGB images or 0 for paletted images.
2822
2823 =head3 Experiments in quantization
2824
2825 This example program experiments with two ways to quantize a PNG
2826 image, first of all using a completely random palette, and second
2827 using colors picked from the image at random:
2828
2829
2830 use utf8;
2831 use FindBin '$Bin';
2832 use Image::PNG::Libpng ':all';
2833 my $file = "wave.png";
2834 my $ncolors = 40;
2835 my $palette = randompalette ($ncolors);
2836 write_with_palette ($file, $palette, $ncolors, [], "random");
2837 my $picked = points ($file, $ncolors);
2838 my @hist = (1) x $ncolors;
2839 write_with_palette ($file, $picked, $ncolors, \@hist, "picked");
2840 exit;
2841
2842 sub write_with_palette
2843 {
2844 my ($file, $palette, $ncolors, $hist, $name) = @_;
2845 my $rpng = create_reader ($file);
2846 $rpng->set_quantize ($palette, $ncolors, $hist, 1);
2847 $rpng->read_png ();
2848 my $wpng = copy_png ($rpng);
2849 $wpng->set_PLTE ($palette);
2850 $wpng->write_png_file ("$name-$file");
2851 }
2852
2853 sub points
2854 {
2855 my ($pngfile, $ncolors) = @_;
2856 my $png = read_png_file ($pngfile);
2857 my $rows = $png->get_rows ();
2858 my $h = $png->height ();
2859 my $w = $png->width ();
2860 my $ch = $png->get_channels ();
2861 my @p;
2862 for (0..$ncolors-1) {
2863 my $x = int (rand ($w));
2864 my $y = int (rand ($h));
2865 my $row = $rows->[$y];
2866 my @pix = split ('', substr ($row, $x*$ch, $ch));
2867 push @p, {
2868 red => ord ($pix[0]),
2869 green => ord ($pix[1]),
2870 blue => ord ($pix[2]),
2871 };
2872 }
2873 return \@p;
2874 }
2875
2876 sub randompalette
2877 {
2878 my ($n) = @_;
2879 my @p;
2880 for (0..$n-1) {
2881 my %color;
2882 for my $c (qw!red green blue!) {
2883 $color{$c} = int (rand (256))
2884 }
2885 push @p, \%color;
2886 }
2887 return \@p;
2888 }
2889
2890 (This example is included as L<F<examples/q.pl>|https://fastapi.metacpan.org/source/BKB/Image-PNG-Libpng-0.60/examples/q.pl>
2891 in the distribution.)
2892
2893
2894
2895
2896 L<examples/wave.png|https://fastapi.metacpan.org/source/BKB/Image-PNG-Libpng-0.60/examples/wave.png> is included in the distribution.
2897
2898 =begin html
2899
2900 <p>The input image is this:</p>
2901
2902 <!-- metacpan doesn't allow figure/figcaption tags. -->
2903 <table>
2904 <tr>
2905 <td>
2906 <img src="https://fastapi.metacpan.org/source/BKB/Image-PNG-Libpng-0.60/examples/wave.png">
2907 </td>
2908 </tr>
2909 <tr>
2910 <th>
2911 <a href='https://fastapi.metacpan.org/source/BKB/Image-PNG-Libpng-0.60/examples/wave.png'>examples/wave.png</a>
2912 </th>
2913 </tr>
2914 </table>
2915
2916 =end html
2917
2918
2919
2920
2921 L<examples/random-wave.png|https://fastapi.metacpan.org/source/BKB/Image-PNG-Libpng-0.60/examples/random-wave.png> is included in the distribution.
2922
2923 =begin html
2924
2925 <p>Completely random colors gives this kind of output:</p>
2926
2927 <!-- metacpan doesn't allow figure/figcaption tags. -->
2928 <table>
2929 <tr>
2930 <td>
2931 <img src="https://fastapi.metacpan.org/source/BKB/Image-PNG-Libpng-0.60/examples/random-wave.png">
2932 </td>
2933 </tr>
2934 <tr>
2935 <th>
2936 <a href='https://fastapi.metacpan.org/source/BKB/Image-PNG-Libpng-0.60/examples/random-wave.png'>examples/random-wave.png</a>
2937 </th>
2938 </tr>
2939 </table>
2940
2941 =end html
2942
2943
2944
2945
2946 L<examples/picked-wave.png|https://fastapi.metacpan.org/source/BKB/Image-PNG-Libpng-0.60/examples/picked-wave.png> is included in the distribution.
2947
2948 =begin html
2949
2950 <p>Picked colors gives this kind of output:</p>
2951
2952 <!-- metacpan doesn't allow figure/figcaption tags. -->
2953 <table>
2954 <tr>
2955 <td>
2956 <img src="https://fastapi.metacpan.org/source/BKB/Image-PNG-Libpng-0.60/examples/picked-wave.png">
2957 </td>
2958 </tr>
2959 <tr>
2960 <th>
2961 <a href='https://fastapi.metacpan.org/source/BKB/Image-PNG-Libpng-0.60/examples/picked-wave.png'>examples/picked-wave.png</a>
2962 </th>
2963 </tr>
2964 </table>
2965
2966 =end html
2967
2968
2969 =head2 set_rgb_to_gray
2970
2971 $png->set_rgb_to_gray ();
2972
2973 $png->set_rgb_to_gray ($error_action, $red_weight, $green_weight);
2974
2975 Convert a PNG image from RGB (colored) to gray. See the libpng manual for details.
2976
2977 Without arguments, the libpng default values are used for
2978 C<$red_weight> and C<$green_weight>, and an error action of "none" is
2979 chosen. If the error action is set to a value of
2980 C<PNG_ERROR_ACTION_WARN> or C<PNG_ERROR_ACTION_ERROR>, pixels in the
2981 RGB image where the R, G and B values are not equal will cause a
2982 warning or error respectively. To get the default values for
2983 C<$red_weight> or C<$green_weight>, use any negative value. See the libpng manual for details.
2984
2985 If you choose C<PNG_ERROR_ACTION_NONE> you can find out whether there
2986 were non-RGB pixels in your image using L</get_rgb_to_gray_status>.
2987
2988 This function corresponds to C<png_png_set_rgb_to_gray> in libpng with C<$error_action> having a
2989 default value of C<PNG_ERROR_ACTION_NONE>, and C<$red_weight> and
2990 C<$green_weight> both set to negative values.
2991
2992 =head3 Convert a colored image to gray
2993
2994
2995 use utf8;
2996 use FindBin '$Bin';
2997 use Image::PNG::Libpng ':all';
2998 use Image::PNG::Const ':all';
2999
3000 my $png = create_reader ("$Bin/luv.png");
3001 $png->read_info ();
3002 $png->set_rgb_to_gray ();
3003 $png->read_image ();
3004 $png->read_end ();
3005 my $wpng = $png->copy_png ();
3006 my $ihdr = $wpng->get_IHDR ();
3007 $ihdr->{color_type} = PNG_COLOR_TYPE_GRAY_ALPHA;
3008 $wpng->set_IHDR ($ihdr);
3009 $wpng->write_png_file ("$Bin/grayface.png");
3010
3011 (This example is included as L<F<examples/rgb-to-gray.pl>|https://fastapi.metacpan.org/source/BKB/Image-PNG-Libpng-0.60/examples/rgb-to-gray.pl>
3012 in the distribution.)
3013
3014
3015
3016
3017 L<examples/grayface.png|https://fastapi.metacpan.org/source/BKB/Image-PNG-Libpng-0.60/examples/grayface.png> is included in the distribution.
3018
3019 =begin html
3020
3021 <p>This is the output:</p>
3022
3023 <!-- metacpan doesn't allow figure/figcaption tags. -->
3024 <table>
3025 <tr>
3026 <td>
3027 <img src="https://fastapi.metacpan.org/source/BKB/Image-PNG-Libpng-0.60/examples/grayface.png">
3028 </td>
3029 </tr>
3030 <tr>
3031 <th>
3032 <a href='https://fastapi.metacpan.org/source/BKB/Image-PNG-Libpng-0.60/examples/grayface.png'>examples/grayface.png</a>
3033 </th>
3034 </tr>
3035 </table>
3036
3037 =end html
3038
3039
3040 =head2 set_user_limits
3041
3042 $png->set_user_limits ($width, $height);
3043
3044 This enables a user to override libpng's restrictions to one million
3045 pixels in width and one million pixels in height for a PNG image.
3046
3047 This function corresponds to C<png_set_user_limits> in libpng
3048
3049 =head1 Other functions
3050
3051 This section contains other functions which don't correspond to
3052 anything in libpng itself, but which have been added to the module for
3053 utility.
3054
3055 =head2 color_type_channels
3056
3057 my $channels = color_type_channels ('PNG_COLOR_TYPE_RGB_ALPHA');
3058
3059 Returns the number of channels (the number of components of one pixel)
3060 of the specified color type.
3061
3062 =head2 copy_row_pointers
3063
3064 $png->copy_row_pointers ($row_pointers);
3065
3066 This allows XS routines to directly set the value of the row pointers
3067 for the PNG image. The memory is copied, so whatever is in the row
3068 pointers can be freed immediately after calling this. However, the
3069 image data it points to is not copied, so this needs to be valid until
3070 the PNG is written.
3071
3072 The Perl scalar C<$row_pointers> should be set up something like the
3073 following (where C<rp> is the C pointer):
3074
3075 RETVAL = newSViv (PTR2IV (rp));
3076
3077 It's extracted from the Perl scalar using
3078
3079 rp = INT2PTR (png_byte **, SvIV (row_pointers));
3080
3081 where row_pointers is the C<SV *> corresponding to C<$row_pointers> in
3082 the Perl script. See also L</set_row_pointers> which does the same
3083 thing but takes ownership of the memory.
3084
3085 =head2 get_chunk
3086
3087 my $timechunk = $png->get_chunk ('tIME');
3088
3089 Get the specified chunk. This produces a fatal error if asked for the
3090 C<IDAT> (image data) chunk, use L</get_rows> instead. Returns C<undef>
3091 if asked for an unknown chunk name.
3092
3093 This is used by L<pnginspect> to get the valid chunks. See also
3094 L</set_chunk>.
3095
3096 =head2 get_internals
3097
3098 my ($png_struct, $png_info) = get_internals ($png);
3099
3100 This function returns the C<png_structp> and C<png_infop> contained in
3101 C<$png>. The return value is a list containing the C<png_structp> as
3102 the first argument and the C<png_infop> as the second argument,
3103 wrapped up as references to objects of type
3104 C<Image::PNG::Libpng::png_struct> and C<Image::PNG::Libpng::png_info>.
3105
3106 To access the values of the pointers, use something like this:
3107
3108 void access_png_internals (png, info)
3109 SV * png;
3110 SV * info;
3111 PREINIT:
3112 png_struct * cpng;
3113 png_info * cinfo;
3114 CODE:
3115 cpng = INT2PTR (png_struct *, SvIV (png));
3116 cinfo = INT2PTR (png_info *, SvIV (info));
3117
3118 An example exists in L<Image::PNG::Cairo>.
3119
3120 =head2 get_tRNS_palette
3121
3122 $png->get_tRNS_palette ();
3123
3124 This is not a libpng-equivalent function.
3125
3126 =head2 image_data_diff
3127
3128 my $diff = image_data_diff ('a.png', 'b.png');
3129
3130 This returns the undefined value if the image data in F<a.png> is the
3131 same as the image data in F<b.png>. If the image data is different, it
3132 returns a readable text message describing the first difference found,
3133 for example the height is different, or row 0 of the image data is
3134 different, etc.
3135
3136 This function is used in testing this module. See also L</png_compare>.
3137
3138 =head2 libpng_supports
3139
3140 if (libpng_supports ('iTXt')) {
3141 print "Your libpng supports international text.\n";
3142 }
3143
3144 This function returns true or false depending on whether the version
3145 of libpng which this was compiled with supports or does not support a
3146 particular facility. For the most part, these are taken directly from
3147 the C macros of libpng.
3148
3149 The possible arguments to C<libpng_supports> are:
3150
3151 =over
3152
3153
3154 =item 16BIT
3155
3156
3157
3158
3159
3160 =item ALIGNED_MEMORY
3161
3162
3163
3164
3165
3166 =item ARM_NEON_API
3167
3168
3169
3170
3171
3172 =item BENIGN_ERRORS
3173
3174
3175
3176
3177
3178 =item BENIGN_READ_ERRORS
3179
3180
3181
3182
3183
3184 =item BENIGN_WRITE_ERRORS
3185
3186
3187
3188
3189
3190 =item bKGD
3191
3192
3193 Does the libpng support the L</bKGD> chunk?
3194
3195
3196 =item BUILD_GRAYSCALE_PALETTE
3197
3198
3199
3200
3201
3202 =item BUILTIN_BSWAP16
3203
3204
3205
3206
3207
3208 =item CHECK_FOR_INVALID_INDEX
3209
3210
3211
3212
3213
3214 =item cHRM
3215
3216
3217 Does the libpng support the L</cHRM> chunk?
3218
3219
3220 =item cHRM_XYZ
3221
3222
3223 This is local to Image::PNG::Libpng and not a part of libpng itself.
3224
3225 It was necessary to extend libpng because the conditional compilation
3226 macro for L</set_cHRM_XYZ> and L</get_cHRM_XYZ>, C<PNG_cHRM_SUPPORTED>
3227 is defined (true) for old libpngs which do not actually contain these
3228 functions.
3229
3230
3231 =item CHUNK_CACHE_MAX
3232
3233
3234 This is local to Image::PNG::Libpng and not a part of libpng itself.
3235
3236 It was necessary to extend libpng because the conditional compilation
3237 macro for L</set_chunk_cache_max> and L</get_chunk_cache_max>,
3238 C<PNG_USER_LIMITS_SUPPORTED> is defined (true) for old libpngs which
3239 do not actually contain these functions.
3240
3241
3242 =item CHUNK_MALLOC_MAX
3243
3244
3245 This is local to Image::PNG::Libpng and not a part of libpng itself.
3246
3247 The reasons for this are identical to those for L</CHUNK_CACHE_MAX>.
3248
3249
3250 =item COLORSPACE
3251
3252
3253
3254
3255
3256 =item CONSOLE_IO
3257
3258
3259
3260
3261
3262 =item CONVERT_tIME
3263
3264
3265 This is related to two deprecated functions,
3266 L</png_convert_from_time_t> and L</png_convert_from_struct_tm>.
3267
3268
3269 =item CONVERT_tIME
3270
3271
3272
3273
3274
3275 =item EASY_ACCESS
3276
3277
3278
3279
3280
3281 =item ERROR_NUMBERS
3282
3283
3284
3285
3286
3287 =item ERROR_TEXT
3288
3289
3290
3291
3292
3293 =item eXIf
3294
3295
3296 Does the libpng support the L</eXIf> chunk?
3297
3298
3299 =item FIXED_POINT
3300
3301
3302
3303
3304
3305 =item FIXED_POINT_MACRO
3306
3307
3308
3309
3310
3311 =item FLOATING_ARITHMETIC
3312
3313
3314
3315
3316
3317 =item FLOATING_POINT
3318
3319
3320
3321
3322
3323 =item FORMAT_AFIRST
3324
3325
3326
3327
3328
3329 =item FORMAT_BGR
3330
3331
3332
3333
3334
3335 =item gAMA
3336
3337
3338 Does the libpng support the L</gAMA> chunk?
3339
3340
3341 =item GAMMA
3342
3343
3344
3345
3346
3347 =item GET_PALETTE_MAX
3348
3349
3350 Does your libpng support L</get_palette_max>?
3351
3352
3353 =item HANDLE_AS_UNKNOWN
3354
3355
3356
3357
3358
3359 =item HANDLE_AS_UNKNOWN
3360
3361
3362
3363
3364
3365 =item hIST
3366
3367
3368 Does the libpng support the L</hIST> chunk?
3369
3370
3371 =item iCCP
3372
3373
3374 Does the libpng support the L</iCCP> chunk?
3375
3376
3377 =item INCH_CONVERSIONS
3378
3379
3380
3381
3382
3383 =item INFO_IMAGE
3384
3385
3386
3387
3388
3389 =item IO_STATE
3390
3391
3392
3393
3394
3395 =item iTXt
3396
3397
3398 Does the libpng support international text?
3399
3400
3401 =item MIPS_MSA_API
3402
3403
3404
3405
3406
3407 =item MNG_FEATURES
3408
3409
3410
3411
3412
3413 =item oFFs
3414
3415
3416 Does the libpng support the L</oFFs> chunk?
3417
3418
3419 =item pCAL
3420
3421
3422 Does the libpng support the L</pCAL> extension?
3423
3424
3425 =item PEDANTIC_WARNINGS
3426
3427
3428
3429
3430
3431 =item pHYs
3432
3433
3434 Does the libpng support the L</pHYs> chunk?
3435
3436
3437 =item POINTER_INDEXING
3438
3439
3440
3441
3442
3443 =item POWERPC_VSX_API
3444
3445
3446
3447
3448
3449 =item PROGRESSIVE_READ
3450
3451
3452
3453
3454
3455 =item READ
3456
3457
3458 Can libpng read PNGs?
3459
3460
3461 =item READ_16_TO_8
3462
3463
3464
3465
3466
3467 =item READ_ALPHA_MODE
3468
3469
3470 See L</set_alpha_mode>.
3471
3472
3473 =item READ_BACKGROUND
3474
3475
3476 See L</set_background>.
3477
3478
3479 =item READ_BGR
3480
3481
3482 See L</set_bgr>.
3483
3484
3485 =item READ_COMPOSITE_NODIV
3486
3487
3488
3489
3490
3491 =item READ_COMPRESSED_TEXT
3492
3493
3494
3495
3496
3497 =item READ_EXPAND
3498
3499
3500
3501
3502
3503 =item READ_EXPAND_16
3504
3505
3506
3507
3508
3509 =item READ_FILLER
3510
3511
3512
3513
3514
3515 =item READ_GAMMA
3516
3517
3518 See L</set_gamma>.
3519
3520
3521 =item READ_GRAY_TO_RGB
3522
3523
3524
3525
3526
3527 =item READ_INTERLACING
3528
3529
3530
3531
3532
3533 =item READ_INT_FUNCTIONS
3534
3535
3536
3537
3538
3539 =item READ_INVERT
3540
3541
3542
3543
3544
3545 =item READ_INVERT_ALPHA
3546
3547
3548
3549
3550
3551 =item READ_OPT_PLTE
3552
3553
3554
3555
3556
3557 =item READ_PACK
3558
3559
3560
3561
3562
3563 =item READ_PACKSWAP
3564
3565
3566
3567
3568
3569 =item READ_QUANTIZE
3570
3571
3572
3573
3574
3575 =item READ_RGB_TO_GRAY
3576
3577
3578
3579
3580
3581 =item READ_SCALE_16_TO_8
3582
3583
3584
3585
3586
3587 =item READ_SHIFT
3588
3589
3590
3591
3592
3593 =item READ_STRIP_16_TO_8
3594
3595
3596
3597
3598
3599 =item READ_STRIP_ALPHA
3600
3601
3602
3603
3604
3605 =item READ_SWAP
3606
3607
3608
3609
3610
3611 =item READ_SWAP_ALPHA
3612
3613
3614
3615
3616
3617 =item READ_tEXt
3618
3619
3620
3621
3622
3623 =item READ_TRANSFORMS
3624
3625
3626
3627
3628
3629 =item READ_USER_TRANSFORM
3630
3631
3632
3633
3634
3635 =item READ_zTXt
3636
3637
3638
3639
3640
3641 =item SAVE_INT_32
3642
3643
3644
3645
3646
3647 =item SAVE_UNKNOWN_CHUNKS
3648
3649
3650
3651
3652
3653 =item sBIT
3654
3655
3656 Does the libpng support the L</sBIT> chunk?
3657
3658
3659 =item sCAL
3660
3661
3662 Does the libpng support the L</sCAL> extension? This actually tests
3663 for the presence of the C<get_sCAL_s>/C<set_sCAL_s> functions, so its
3664 behaviour is dependent on other factors for versions 1.2 and 1.4 of
3665 libpng.
3666
3667
3668 =item SEQUENTIAL_READ
3669
3670
3671
3672
3673
3674 =item SETJMP
3675
3676
3677
3678
3679
3680 =item SET_OPTION
3681
3682
3683
3684
3685
3686 =item SET_UNKNOWN_CHUNKS
3687
3688
3689
3690
3691
3692 =item SET_USER_LIMITS
3693
3694
3695
3696
3697
3698 =item SIMPLIFIED_READ
3699
3700
3701
3702
3703
3704 =item SIMPLIFIED_READ_AFIRST
3705
3706
3707
3708
3709
3710 =item SIMPLIFIED_WRITE
3711
3712
3713
3714
3715
3716 =item SIMPLIFIED_WRITE_AFIRST
3717
3718
3719
3720
3721
3722 =item SIMPLIFIED_WRITE_BGR
3723
3724
3725
3726
3727
3728 =item SIMPLIFIED_WRITE_STDIO
3729
3730
3731
3732
3733
3734 =item sPLT
3735
3736
3737 Does the libpng support L</sPLT> chunks?
3738
3739
3740 =item sRGB
3741
3742
3743 Does the libpng support the L</sRGB> chunk?
3744
3745
3746 =item STDIO
3747
3748
3749
3750
3751
3752 =item STORE_UNKNOWN_CHUNKS
3753
3754
3755
3756
3757
3758 =item TEXT
3759
3760
3761 Does the libpng support text?
3762
3763
3764 =item tEXt
3765
3766
3767 Does the libpng support tEXt chunks?
3768
3769
3770 =item tIME
3771
3772
3773 Does the libpng support the L</tIME> chunk?
3774
3775
3776 =item TIME_RFC1123
3777
3778
3779
3780
3781
3782 =item tRNS
3783
3784
3785 Does the libpng support the L</tRNS> chunk?
3786
3787
3788 =item UNKNOWN_CHUNKS
3789
3790
3791 Does the libpng support unknown chunks (see L<Private chunks>)?
3792
3793
3794 =item USER_CHUNKS
3795
3796
3797
3798
3799
3800 =item USER_LIMITS
3801
3802
3803 Does the libpng support L</set_user_limits> and the related functions
3804 L</get_user_width_max>, and L</get_user_height_max>?
3805
3806
3807 =item USER_LIMITS
3808
3809
3810
3811
3812
3813 =item USER_MEM
3814
3815
3816
3817
3818
3819 =item USER_TRANSFORM_INFO
3820
3821
3822
3823
3824
3825 =item USER_TRANSFORM_PTR
3826
3827
3828
3829
3830
3831 =item WARNINGS
3832
3833
3834
3835
3836
3837 =item WRITE
3838
3839
3840 Can libpng write pngs?
3841
3842
3843 =item WRITE_BGR
3844
3845
3846
3847
3848
3849 =item WRITE_COMPRESSED_TEXT
3850
3851
3852
3853
3854
3855 =item WRITE_CUSTOMIZE_COMPRESSION
3856
3857
3858 Does the libpng support L</set_compression_level> and similar functions?
3859
3860 ⛐ðŸĪŠâš  It's not very clear that this returns a useful value,
3861 since L</set_compression_level> seems to be in libpngs from at least
3862 as far back as C<1.5.1>, and yet this macro was only added to libpng
3863 in version C<1.6.13>.
3864
3865
3866 =item WRITE_CUSTOMIZE_ZTXT_COMPRESSION
3867
3868
3869 Does the libpng support L</set_text_compression_level> and similar functions?
3870
3871
3872 =item WRITE_FILLER
3873
3874
3875
3876
3877
3878 =item WRITE_FILTER
3879
3880
3881
3882
3883
3884 =item WRITE_FLUSH
3885
3886
3887
3888
3889
3890 =item WRITE_FLUSH_AFTER_IEND
3891
3892
3893
3894
3895
3896 =item WRITE_INTERLACING
3897
3898
3899
3900
3901
3902 =item WRITE_INT_FUNCTIONS
3903
3904
3905
3906
3907
3908 =item WRITE_INVERT
3909
3910
3911
3912
3913
3914 =item WRITE_INVERT_ALPHA
3915
3916
3917
3918
3919
3920 =item WRITE_OPTIMIZE_CMF
3921
3922
3923
3924
3925
3926 =item WRITE_PACK
3927
3928
3929
3930
3931
3932 =item WRITE_PACKSWAP
3933
3934
3935
3936
3937
3938 =item WRITE_SHIFT
3939
3940
3941
3942
3943
3944 =item WRITE_SWAP
3945
3946
3947
3948
3949
3950 =item WRITE_SWAP_ALPHA
3951
3952
3953
3954
3955
3956 =item WRITE_TRANSFORMS
3957
3958
3959
3960
3961
3962 =item WRITE_USER_TRANSFORM
3963
3964
3965
3966
3967
3968 =item WRITE_WEIGHTED_FILTER
3969
3970
3971
3972
3973
3974 =item zTXt
3975
3976
3977 Does the libpng support C<zTXt> chunks?
3978
3979
3980 =back
3981
3982 =head2 png_compare
3983
3984 if (png_compare ('a.png', 'b.png') == 0) {
3985 print "The PNGs are the same.\n";
3986 }
3987
3988 This compares the image data in two PNGs and returns 0 if they contain
3989 exactly the same image data, or 1 if they contain different image
3990 data. For a more detailed comparison, see L</image_data_diff>. This
3991 does not compare to see if the PNG files "look like" each other, but
3992 whether each pixel contains exactly the same values. Please see
3993 L<Image::Similar> for a looser comparison of images.
3994
3995 This uses the "expand" transform of libpng to read both the images, so
3996 it is able to compare images of different color types. It compares the
3997 alpha values as well as the color pixels. See L</Saving bandwidth> for
3998 an example of comparing an RGB and a grayscale image.
3999
4000 =head2 read_struct
4001
4002 if ($png->read_struct ()) {
4003 warn "Can't write this, use copy_png to copy it";
4004 }
4005
4006 This returns a true value if C<$png> was created with
4007 L</create_read_struct> or allied functions like L</read_from_scalar>,
4008 and a false value if C<$png> was created with L</create_write_struct>
4009 or allied functions like L</copy_png>.
4010
4011 =head2 set_chunk
4012
4013 $png->set_chunk ('tIME', $timechunk);
4014
4015 Set the specified chunk. This produces a fatal error if given an
4016 C<IDAT> (image data) chunk, use L</set_rows> instead. This produces a
4017 fatal error if given an unknown chunk name.
4018
4019 The first argument is the chunk name and then the second argument is a
4020 scalar containing whatever the chunk requires, for example a hash
4021 reference for the C<tIME> chunk as described under L</set_tIME> and
4022 L</get_tIME>.
4023
4024 This is essentially a convenience function for the benefit of
4025 L</copy_png> which, together with L</get_valid>, enables the PNG
4026 chunks to be copied in a loop rather than one-by-one.
4027
4028 =head2 set_image_data
4029
4030 $png->set_image_data ($image_data);
4031
4032 Set the internal image data pointer to C<$image_data>. C<$image_data>
4033 should contain a pointer to memory stored as an C<SvIV> allocated with
4034 C<Newx> or a similar function. This transfers ownership of the memory
4035 to C<$png>, which will free it with C<Safefree> when C<$png> is
4036 destroyed. Calling this function with any value does not actually
4037 change the content of the PNG image itself.
4038
4039 =head2 set_row_pointers
4040
4041 $png->set_row_pointers ($row_pointers);
4042
4043 This sets the rows of the PNG image to C<$row_pointers> using
4044 C<png_set_rows>. C<$row_pointers> must contain a pointer to memory
4045 stored as an SvIV allocated with a Perl memory allocator like C<Newx>
4046 or a similar function. This also transfers ownership of the memory to
4047 C<$png>, which will free it with C<Safefree> when C<$png> is
4048 destroyed. See also L</copy_row_pointers>, which does the same thing
4049 except for the freeing of the memory.
4050
4051 =head2 split_alpha
4052
4053 my $split = $png->split_alpha ();
4054 my $alpha = $split->{alpha};
4055 my $color = $split->{data};
4056
4057 Split the alpha channel away from the other data. This only works for
4058 images with color types C<PNG_COLOR_TYPE_RGB_ALPHA> and
4059 C<PNG_COLOR_TYPE_GRAY_ALPHA>. This is not part of the libpng API. This
4060 function was added to this module to assist the author of
4061 L<PDF::Builder> due to problems with very slow access to PNG images
4062 using Perl.
4063
4064 To remove the alpha channel from an image, use L</set_background>. See
4065 L</Setting the background> for an example. You can also use the
4066 transform C<PNG_TRANSFORM_STRIP_ALPHA> in L</read_png_file>, or
4067 L</set_strip_alpha>, but this may leave spurious pixel values in
4068 transparent parts of the image.
4069
4070 =head1 EXPORTS
4071
4072 Nothing is exported by default, but all the functions in this module,
4073 including the object methods, can be exported on request. The export
4074 tag 'all' exports everything in the module:
4075
4076 use Image::PNG::Libpng ':all';
4077
4078 This includes all the methods, which can then be used with the C<$png>
4079 argument as the first argument.
4080
4081 =head1 Differences from libpng
4082
4083 The functions in Image::PNG::Libpng are closely based on those of
4084 libpng, with the following differences.
4085
4086 =head2 No info structure
4087
4088 This module does not use the "info" structure of libpng. Almost all
4089 libpng functions require two initial arguments, a C<png_structp> and a
4090 C<png_infop>. However, in Image::PNG::Libpng, both the "png" and the
4091 "info" are contained in the object. People who need access to the
4092 internals of an C<Image::PNG::Libpng> object (C programmers or XS
4093 programmers) can use L</get_internals> to access them.
4094
4095 This module does not support the "end info" structure of PNGs when
4096 writing, although these are handled when reading.
4097
4098 =head2 Unused arguments omitted
4099
4100 This module eliminates unevaluated arguments of libpng. For example,
4101 libpng requires the user to pass a pointer to a C<png_struct> to call
4102 the libpng version number function, (see L</get_libpng_ver>), but it
4103 actually ignores this structure. There are many similar instances of
4104 unevaluated arguments, which have all been eliminated from this
4105 module.
4106
4107 If you are interested in exactly which libpng arguments are omitted,
4108 you can find each instance L<in the file C<perl-libpng.c> in the top directory of the distribution|https://fastapi.metacpan.org/source/BKB/Image-PNG-Libpng-0.60/perl-libpng.c> in the macro
4109 C<UNUSED_ZERO_ARG>.
4110
4111 =head2 Useless functions omitted
4112
4113 The functions from libpng which don't do anything have been omitted
4114 from this module.
4115
4116 =head2 Function return values are used to return values
4117
4118 libpng is very inconsistent in its calling conventions. Some functions
4119 return results using references, and some return results using the
4120 function's return value. For example C<png_get_rows> (see
4121 L</get_rows>) uses the return value of the function to return an array
4122 of pointers, but C<png_get_PLTE> (see L</get_PLTE>) uses a pointer
4123 reference to return an array of pointers, and the return value to
4124 indicate errors.
4125
4126 Image::PNG::Libpng uses only the return value. Errors and
4127 non-existence are indicated by a return value of the undefined
4128 value.
4129
4130 Further to this, libpng's error handling is also very inconsistent.
4131 Some functions use the return value to indicate errors, and some of
4132 the functions don't indicate errors at all, but just fail
4133 silently. Even more inconsistently, some of the functions which use
4134 the return value to indicate an error use a non-zero value, and some
4135 use a zero value, to indicate an error.
4136
4137 =head2 No destructors
4138
4139 Freeing the memory allocated by L</create_read_struct> and
4140 L</create_write_struct> is automatically handled by Perl.
4141
4142 Older versions of this module (pre-0.18) had functions called
4143 C<destroy_read_struct> and C<destroy_write_struct> corresponding to
4144 the functions with similar names in libpng. From version 0.18, these
4145 functions still exist, but they no longer do anything. The memory
4146 freeing is now handled by Perl automatically.
4147
4148 =head2 Other unimplemented parts of libpng
4149
4150 =head3 Memory management functions
4151
4152 The management of memory for libpng objects is handled automatically
4153 by this module, and so it does not offer an interface to C<png_malloc>
4154 and C<png_free> or other libpng memory handling functions.
4155
4156 =head3 Error handling functions
4157
4158 This module does not offer an interface to C<png_error> and
4159 C<png_get_error_ptr> or any of the other error handling functions of
4160 libpng. It redirects the error and warning handlers to Perl's error
4161 stream.
4162
4163 =head3 Input and output manipulation functions
4164
4165 This module does not offer a direct interface to C<png_set_write_fn>
4166 and C<png_set_read_fn>. However, it is possible to use their
4167 functionality to access Perl data via L</read_from_scalar> and
4168 L</write_to_scalar>.
4169
4170 =head3 Fixed point functions
4171
4172 There is currently no support for the PNG fixed point functions in
4173 this Perl module, the functions with suffix C<_fixed>.
4174
4175 =head2 List of unsupported functions
4176
4177 The following functions from the libpng API are unsupported by this
4178 module.
4179
4180 =over
4181
4182
4183 =item png_benign_error
4184
4185
4186
4187
4188 💔 See L</Error handling functions>.
4189
4190 =item png_build_grayscale_palette
4191
4192
4193 ⛐ðŸĪŠâš  Undocumented function, but it is part of the public API.
4194 See L<https://github.com/glennrp/libpng/issues/353>.
4195
4196 This function builds an evenly-spaced grayscale palette at a specified
4197 bit depth into a user-supplied array. It is not used elsewhere in
4198 libpng.
4199
4200 =item png_chunk_benign_error
4201
4202
4203
4204
4205 💔 See L</Error handling functions>.
4206
4207 =item png_chunk_warning
4208
4209
4210
4211
4212 💔 See L</Error handling functions>.
4213
4214 =item png_convert_from_struct_tm
4215
4216 👎 Deprecated in libpng.
4217 This function related to the C<tIME> chunk is deprecated in libpng
4218 1.7.
4219
4220 =item png_convert_from_time_t
4221
4222 👎 Deprecated in libpng.
4223 This function related to the C<tIME> chunk is deprecated in libpng 1.7.
4224
4225 =item png_convert_to_rfc1123
4226
4227 👎 Deprecated in libpng.
4228 This function related to the C<tIME> chunk is deprecated in libpng 1.7.
4229
4230 =item png_convert_to_rfc1123_buffer
4231
4232
4233 👎🐊 This function was deliberately omitted from this module because it doesn't seem useful for Perl programmers.
4234
4235 This function is related to the C<tIME> chunk; it seems fairly
4236 superfluous with the many other ways to manipulate time strings
4237 already in Perl.
4238
4239 =item png_data_freer
4240
4241
4242
4243
4244 🐘 See L</Memory management functions>.
4245
4246 =item png_free
4247
4248
4249
4250
4251 🐘 See L</Memory management functions>.
4252
4253 =item png_free_data
4254
4255
4256
4257
4258 🐘 See L</Memory management functions>.
4259
4260 =item png_get_cHRM_XYZ_fixed
4261
4262
4263
4264
4265 🍓 See L</Fixed point functions>.
4266
4267 =item png_get_cHRM_fixed
4268
4269
4270
4271
4272 🍓 See L</Fixed point functions>.
4273
4274 =item png_get_compression_type
4275
4276 🙃ðŸĪĄ See L</Useless functions omitted>.
4277 Useless function which returns 0 since there is only one type of
4278 compression.
4279
4280 =item png_get_copyright
4281
4282
4283 👎🐊 This function was deliberately omitted from this module because it doesn't seem useful for Perl programmers.
4284
4285 This function gives you the copyright string for libpng.
4286
4287 =item png_get_current_pass_number
4288
4289
4290
4291
4292 =item png_get_current_row_number
4293
4294
4295
4296
4297 =item png_get_error_ptr
4298
4299
4300
4301
4302 💔 See L</Error handling functions>.
4303
4304 =item png_get_filter_type
4305
4306 🙃ðŸĪĄ See L</Useless functions omitted>.
4307 This function returns the value of the unused field C<filter_type> in
4308 the PNG header, which is always 0. See L<Unused arguments omitted>.
4309
4310 =item png_get_gAMA_fixed
4311
4312
4313
4314
4315 🍓 See L</Fixed point functions>.
4316
4317 =item png_get_header_ver
4318
4319
4320 This function was omitted from this module because it merely
4321 duplicates another function.
4322
4323 Identical to L</get_libpng_ver>.
4324
4325 =item png_get_header_version
4326
4327
4328 This function was omitted from this module because it merely
4329 duplicates another function.
4330
4331 Identical to L</get_libpng_ver>.
4332
4333 =item png_get_io_chunk_type
4334
4335
4336
4337
4338 =item png_get_io_ptr
4339
4340
4341
4342
4343 =item png_get_io_state
4344
4345
4346
4347
4348 =item png_get_mem_ptr
4349
4350
4351
4352
4353 =item png_get_pHYs_dpi
4354
4355
4356
4357
4358 =item png_get_pixel_aspect_ratio
4359
4360
4361
4362
4363 =item png_get_pixel_aspect_ratio_fixed
4364
4365
4366
4367
4368 🍓 See L</Fixed point functions>.
4369
4370 =item png_get_pixels_per_inch
4371
4372
4373
4374
4375 =item png_get_pixels_per_meter
4376
4377
4378
4379
4380 =item png_get_progressive_ptr
4381
4382
4383 Incremental reading of PNGs is not handled yet.
4384
4385 =item png_get_sCAL_fixed
4386
4387
4388
4389
4390 🍓 See L</Fixed point functions>.
4391
4392 =item png_get_signature
4393
4394
4395 👎🐊 This function was deliberately omitted from this module because it doesn't seem useful for Perl programmers.
4396
4397 Returns the PNG signature of a PNG you read in.
4398
4399 =item png_get_uint_31
4400
4401
4402 👎🐊 This function was deliberately omitted from this module because it doesn't seem useful for Perl programmers.
4403
4404 This produces an error if the unsigned integer argument is too big for
4405 a 31 bit number.
4406
4407 =item png_get_user_chunk_ptr
4408
4409
4410
4411
4412 =item png_get_user_height_max
4413
4414
4415
4416
4417 =item png_get_user_transform_ptr
4418
4419
4420
4421
4422 =item png_get_x_offset_inches
4423
4424
4425
4426
4427 =item png_get_x_offset_inches_fixed
4428
4429
4430
4431
4432 🍓 See L</Fixed point functions>.
4433
4434 =item png_get_x_offset_microns
4435
4436
4437
4438
4439 =item png_get_x_offset_pixels
4440
4441
4442 Duplicates L</get_oFFs>.
4443
4444 =item png_get_x_pixels_per_inch
4445
4446
4447
4448
4449 =item png_get_x_pixels_per_meter
4450
4451
4452 Duplicates L</get_oFFs>.
4453
4454 =item png_get_y_offset_inches
4455
4456
4457
4458
4459 =item png_get_y_offset_inches_fixed
4460
4461
4462
4463
4464 🍓 See L</Fixed point functions>.
4465
4466 =item png_get_y_offset_microns
4467
4468
4469
4470
4471 =item png_get_y_offset_pixels
4472
4473
4474 Duplicates L</get_oFFs>.
4475
4476 =item png_get_y_pixels_per_inch
4477
4478
4479
4480
4481 =item png_get_y_pixels_per_meter
4482
4483
4484 Duplicates L</get_oFFs>.
4485
4486 =item png_handle_as_unknown
4487
4488
4489
4490
4491 =item png_image_begin_read_from_file
4492
4493
4494
4495
4496 =item png_image_begin_read_from_stdio
4497
4498
4499
4500
4501 =item png_image_finish_read
4502
4503
4504
4505
4506 =item png_image_free
4507
4508
4509
4510
4511 🐘 See L</Memory management functions>.
4512
4513 =item png_image_write_to_file
4514
4515
4516
4517
4518 =item png_image_write_to_memory
4519
4520
4521
4522
4523 🐘 See L</Memory management functions>.
4524
4525 =item png_image_write_to_stdio
4526
4527
4528
4529
4530 =item png_process_data
4531
4532
4533
4534
4535 =item png_process_data_pause
4536
4537
4538
4539
4540 =item png_process_data_skip
4541
4542
4543
4544
4545 =item png_progressive_combine_row
4546
4547
4548
4549
4550 =item png_read_row
4551
4552
4553
4554
4555 =item png_read_rows
4556
4557
4558
4559
4560 =item png_reset_zstream
4561
4562 👎 Deprecated in libpng.
4563 Resets the zstream of the zlib instance used for the image data.
4564
4565 =item png_save_int_32
4566
4567
4568 👎🐊 This function was deliberately omitted from this module because it doesn't seem useful for Perl programmers.
4569
4570 Writes a 32 bit signed number into an octet buffer. Perl programmers
4571 will probably use C<pack> for this.
4572
4573 =item png_save_uint_16
4574
4575
4576 👎🐊 This function was deliberately omitted from this module because it doesn't seem useful for Perl programmers.
4577
4578 Writes a 16 bit number into an octet buffer. Perl programmers
4579 will probably use C<pack> for this.
4580
4581 =item png_save_uint_32
4582
4583
4584 👎🐊 This function was deliberately omitted from this module because it doesn't seem useful for Perl programmers.
4585
4586 Writes a 32 bit unsigned number into an octet buffer. Perl programmers
4587 will probably use C<pack> for this.
4588
4589 =item png_set_alpha_mode_fixed
4590
4591
4592
4593
4594 🍓 See L</Fixed point functions>.
4595
4596 =item png_set_background_fixed
4597
4598
4599
4600
4601 🍓 See L</Fixed point functions>.
4602
4603 =item png_set_benign_errors
4604
4605
4606
4607
4608 💔 See L</Error handling functions>.
4609
4610 =item png_set_cHRM_XYZ_fixed
4611
4612
4613
4614
4615 🍓 See L</Fixed point functions>.
4616
4617 =item png_set_cHRM_fixed
4618
4619
4620
4621
4622 🍓 See L</Fixed point functions>.
4623
4624 =item png_set_check_for_invalid_index
4625
4626
4627
4628
4629 =item png_set_compression_method
4630
4631 🙃ðŸĪĄ See L</Useless functions omitted>.
4632 This function in libpng corresponds to the unused
4633 C<method> parameter of zlib functions like C<deflateInit2>. See
4634 L</zlib documentation>. The libpng function just produces a warning if
4635 the user sets the value to anything but 8, the value of the macro
4636 C<Z_DEFLATED>, and then lets zlib produce an error.
4637
4638 =item png_set_crc_action
4639
4640
4641
4642
4643 💔 See L</Error handling functions>.
4644
4645 =item png_set_error_fn
4646
4647
4648
4649
4650 💔 See L</Error handling functions>.
4651
4652 =item png_set_filter_heuristics
4653
4654 👎 Deprecated in libpng.
4655
4656
4657 =item png_set_filter_heuristics_fixed
4658
4659
4660
4661
4662 🍓 See L</Fixed point functions>.
4663
4664 =item png_set_flush
4665
4666
4667
4668
4669 =item png_set_gAMA_fixed
4670
4671
4672
4673
4674 🍓 See L</Fixed point functions>.
4675
4676 =item png_set_gamma_fixed
4677
4678
4679
4680
4681 🍓 See L</Fixed point functions>.
4682
4683 =item png_set_interlace_handling
4684
4685
4686 Incremental writing is not handled.
4687
4688 =item png_set_invalid
4689
4690
4691
4692
4693 🐘 See L</Memory management functions>.
4694
4695 =item png_set_longjmp_fn
4696
4697
4698 ⛐ðŸĪŠâš  Undocumented function, but it is part of the public API.
4699
4700
4701 =item png_set_mem_fn
4702
4703
4704
4705
4706 🐘 See L</Memory management functions>.
4707
4708 =item png_set_option
4709
4710
4711
4712
4713 =item png_set_progressive_read_fn
4714
4715
4716
4717
4718 =item png_set_read_status_fn
4719
4720
4721
4722
4723 =item png_set_read_user_chunk_fn
4724
4725
4726
4727
4728 =item png_set_read_user_transform_fn
4729
4730
4731
4732
4733 =item png_set_sCAL_fixed
4734
4735
4736
4737
4738 🍓 See L</Fixed point functions>.
4739
4740 =item png_set_sRGB_gAMA_and_cHRM
4741
4742
4743
4744
4745 =item png_set_shift
4746
4747
4748
4749
4750 =item png_set_sig_bytes
4751
4752
4753 👎🐊 This function was deliberately omitted from this module because it doesn't seem useful for Perl programmers.
4754
4755
4756
4757 =item png_set_strip_error_numbers
4758
4759 🙃ðŸĪĄ See L</Useless functions omitted>.
4760 According to the libpng manual, "we never got around to actually
4761 numbering the error messages", so I assume this is not very useful.
4762
4763 =item png_set_text_compression_method
4764
4765 🙃ðŸĪĄ See L</Useless functions omitted>.
4766 Unsupported for the same reasons as
4767 L</png_set_compression_method>.
4768
4769 =item png_set_unknown_chunk_location
4770
4771
4772 This is related to some kind of bug in version 1.5 and previous of
4773 libpng.
4774
4775 =item png_set_user_transform_info
4776
4777
4778
4779
4780 =item png_set_write_status_fn
4781
4782
4783
4784
4785 💔 See L</Error handling functions>.
4786
4787 =item png_set_write_user_transform_fn
4788
4789
4790
4791
4792 =item png_start_read_image
4793
4794
4795
4796
4797 =item png_write_chunk
4798
4799
4800
4801
4802 =item png_write_chunk_data
4803
4804
4805
4806
4807 =item png_write_chunk_end
4808
4809
4810
4811
4812 =item png_write_chunk_start
4813
4814
4815
4816
4817 =item png_write_flush
4818
4819
4820
4821
4822 =item png_write_info_before_PLTE
4823
4824
4825
4826
4827 =item png_write_row
4828
4829
4830
4831
4832 =item png_write_rows
4833
4834
4835
4836
4837 =item png_write_sig
4838
4839
4840
4841
4842
4843 =back
4844
4845 This is an exhaustive list of unsupported libpng API functions,
4846 extracted from the libpng source code using F<util/api.pl> in this
4847 module's repository.
4848
4849 =head2 Conditional compilation and old libpng versions
4850
4851 It is possible to compile a version of the libpng library without
4852 support for various things. For example, a libpng without support for
4853 text chunks may be created by undefining the C macro
4854 C<PNG_TEXT_SUPPORTED>. This module supports the conditional
4855 compilation choices which we're aware of, but if you encounter
4856 problems using this module because of a conditionally-compiled libpng,
4857 then let us know and we'll add the necessary facility.
4858
4859 Currently we test this module against vanilla libpng versions
4860 C<1.2.59>, C<1.4.22>, C<1.5.30>, C<1.6.47>, and C<1.6.45> before
4861 releases. There doesn't seem to have been a 1.3 or a 1.1 version of
4862 libpng. See
4863 L<http://www.libpng.org/pub/png/pngnews.html|http://www.libpng.org/pub/png/pngnews.html>. Versions
4864 1.0 and earlier of libpng are not tested against.
4865
4866 The following issues with older libpng versions may affect users of
4867 this module:
4868
4869 =head3 cHRM chunk
4870
4871 The L</get_cHRM_XYZ> and L</set_cHRM_XYZ> functions for
4872 the L</cHRM> chunk are not present in pre-1.5.5 versions of libpng,
4873 but the conditional compilation macro of libpng for these newer
4874 functions is the same as for L</get_cHRM> and L</set_cHRM> functions,
4875 which are present on older versions of libpng. Because of this, this
4876 module includes its own protection macro, accessible via
4877 L</libpng_supports> as L</cHRM_XYZ>. These functions are disabled for
4878 libpng versions earlier than 1.5.5.
4879
4880 =head3 chunk_cache_max
4881
4882 The functions L</set_chunk_cache_max> and L</get_chunk_cache_max> are
4883 not protected by a libpng macro, so this module includes its own
4884 protection macro, accessible via L</libpng_supports> as
4885 L</CHUNK_CACHE_MAX>. These functions are disabled for libpng versions
4886 earlier than 1.4.0.
4887
4888 =head3 Compression level
4889
4890 Versions of libpng up to 1.5 behave erratically when
4891 L</set_compression_level> or other C<set_compression_*> functions are
4892 used to alter the compression of the image data. Testing of
4893 compression-related functions is disabled by this Perl module for
4894 pre-1.6.13 versions of libpng.
4895
4896 =head3 Compression level and zlib-ng
4897
4898 Some people have compiled libpng with a new version of zlib known as
4899 zlib-ng. This gives different values for compression than the original
4900 zlib. On versions of this module earlier than 0.58, this caused some
4901 unimportant but annoying test failures where this module was making
4902 exact size comparisons. See
4903 L<https://github.com/benkasminbullock/image-png-libpng/issues/40>. As
4904 far as we know, there is no way to detect whether zlib-ng is being
4905 used from Perl, so to support the use of zlib-ng, these tests have
4906 been switched off. The disabled tests can be restored by setting the
4907 environment variable C<ORIGINAL_ZLIB> to a true value, if you want
4908 them.
4909
4910 ORIGINAL_ZLIB=1 prove t/*.t
4911
4912 =head3 sCAL chunk
4913
4914 Support for the sCAL chunk is disabled within this module
4915 for pre-1.6 versions of libpng.
4916
4917 =head3 Text chunk handling
4918
4919 Versions of libpng up to 1.6.3 produce erratic results
4920 with C<iTXt> (international text) chunks. Testing of text-related
4921 chunks is disabled by this Perl module for pre-1.6.13 versions of
4922 libpng.
4923
4924 =head2 Not all constants are available
4925
4926 Some of the libpng constants are defined in F<pnglibconf.h> or
4927 F<pngconf.h> but L<Image::PNG::Const> only looks at F<png.h> to make
4928 its constants. Because of this, some constant values like
4929 C<PNG_Z_DEFAULT_COMPRESSION> aren't currently available in
4930 L<Image::PNG::Const>. This probably should be fixed to extract the
4931 constants from the other files in a future version.
4932
4933 =head1 STANDALONE SCRIPT
4934
4935 A standalone script, L<pnginspect>, is installed with the
4936 distribution. It prints out the contents of the chunks of the PNG file
4937 on the command line.
4938
4939 =head1 SEE ALSO
4940
4941 =head2 The PNG specification
4942
4943 L<The PNG specification|http://www.w3.org/TR/PNG/> (link to W3
4944 consortium) explains the details of the PNG format.
4945
4946
4947 =head3 PNG The Definitive Guide by Greg Roelofs
4948
4949 The book "PNG - The Definitive Guide" by Greg Roelofs, published in
4950 1999 by O'Reilly is available online at
4951 L<http://www.faqs.org/docs/png/> or L<http://www.libpng.org/pub/png/book/>.
4952
4953 =head2 The libpng documentation
4954
4955 =over
4956
4957 =item Official documentation
4958
4959 The starting point is the plain text libpng manual at
4960 L<http://libpng.org/pub/png/libpng-manual.txt> and the manual page
4961 libpng.3, which you can read using "man 3 libpng".
4962
4963 ⛐ðŸĪŠâš  The documentation which comes with libpng is rather
4964 sketchy. See L</Differences from libpng>. It doesn't contain full
4965 specifications (prototypes, return values) for all of the functions in
4966 the library. For programming in C using libpng, look at the header
4967 file F<png.h>. In some cases, you need to look at the source code of
4968 the library.
4969
4970 =item Other documentation
4971
4972 There is a collection of function definitions under the title
4973 "Interface Definitions for libpng12" at
4974 L<https://refspecs.linuxbase.org/LSB_4.0.0/LSB-Desktop-generic/LSB-Desktop-generic/libpng12man.html>
4975 as part of the "Linux Standard Base Desktop Specification". These
4976 contain extensive information on the prototypes and return values for
4977 the libpng routines, something which is often only available elsewhere
4978 by actually looking at the libpng source code. These pages are usually
4979 the first hits on search engines if you search for a function name in
4980 libpng.
4981
4982 =back
4983
4984 =head2 zlib documentation
4985
4986 See L<https://zlib.net/manual.html> for the zlib documentation.
4987
4988 =head2 Other Perl modules on CPAN
4989
4990 These other modules may also be useful.
4991
4992 =over
4993
4994 =item Alien::PNG
4995
4996 L<Alien::PNG> claims to be a way of "building, finding and using PNG
4997 binaries". It may help in installing libpng. We didn't use it as a
4998 dependency for this module because it seems not to work in batch mode,
4999 but stop and prompt the user. We're interested in hearing feedback
5000 from users whether this works or not on various platforms.
5001
5002 =item Imager
5003
5004 L<Imager>, L<Imager::Files> and C<Imager::Files::PNG> contain support
5005 for reading and writing PNGs via libpng, as well as support for
5006 reading and writing various other kinds of image files, changing the
5007 images, converting, and more.
5008
5009 =item Image::ExifTool
5010
5011 L<Image::ExifTool> is a pure Perl (doesn't require a C compiler)
5012 solution for accessing the text segments of images. It supports PNG
5013 text segments.
5014
5015 =item Image::Info
5016
5017 L<Image::Info> gets information out of images. It supports PNG and is
5018 written in pure Perl, so it doesn't require a C compiler. As well as
5019 basics such as height, width, and colour type, it can get text chunks,
5020 modification time, palette, gamma (gAMA chunk), resolution (pHYs
5021 chunk), and significant bits (sBIT chunk). At the time of writing
5022 (version 1.31) it doesn't support other chunks.
5023
5024 =item Image::PNG::Rewriter
5025
5026 L<Image::PNG::Rewriter> is a utility for unpacking and recompressing
5027 the IDAT (image data) part of a PNG image. The main purpose seems to
5028 be to recompress the image data with the module author's other module
5029 L<Compress::Deflate7>. At the time of writing, that only works with
5030 Perl versions 5.12 or later.
5031
5032 =item Image::Pngslimmer
5033
5034 L<Image::Pngslimmer> reduces the size of dynamically created PNG
5035 images. It's very, very slow at reading PNG data, but seems to work
5036 OK.
5037
5038 =item Image::PNG::Write::BW
5039
5040 L<Image::PNG::Write::BW> writes black and white PNGs from strings.
5041
5042 =item Image::Size
5043
5044 If you only need to read the sizes of images, L<Image::Size> works
5045 with PNG and other image formats.
5046
5047 =back
5048
5049
5050
5051
5052 =head1 AUTHOR
5053
5054 Ben Bullock, <[email protected]>
5055
5056 =head1 COPYRIGHT & LICENCE
5057
5058 This package and associated files are copyright (C)
5059 2011-2026
5060 Ben Bullock.
5061
5062 You can use, copy, modify and redistribute this package and associated
5063 files under the Perl Artistic Licence or the GNU General Public
5064 Licence.
5065
5066
5067
5068