| 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 |
|