=pod

[%- libpng = "=head3 Correspondence to libpng" -%]
[%- noinfo = "No info structure" -%]
[%- xnoinfo = BLOCK -%]
L</[% noinfo %]>
[%- END -%]
[%-  noinfoxref = BLOCK -%]
It does not take a second "info" argument. [% noinfo -%]
[%- END -%]
[% transform_list = BLOCK %]
=over
[% FOR transform IN transforms %]
=item [% transform.name %]

[% transform.text %]
[% END %]
=back
[% END %]
[% libpngdoc = "The libpng documentation" %]
[% pngspec = "The PNG specification" %]
[% MACRO spec(subsection) BLOCK -%]
L<http://www.w3.org/TR/PNG/#[%- subsection -%]>
[%- END %]
[%- wfirstpng = BLOCK -%]
The first argument, C<$png>, is a writeable PNG structure created with 
L</create_write_struct>.
[%- END -%]
[%- rfirstpng = BLOCK -%]
The first argument, C<$png>, is a PNG structure created with 
L</create_read_struct>.
[%- END -%]
[%- MACRO cor BLOCK -%]
[% libpng %]

This function corresponds to C<png_[% fn %]>
[%- END %]
[% source_link = "http://cpansearch.perl.org/src/" _ config.author_pause _ "/" _ config.base_hyphen _ "-" _ config.version _ "/" %]
[% perl_libpng_c = "L<in the file C<perl-libpng.c> in the top directory of the distribution|" _ source_link  _ "perl-libpng.c>" %]
[% unused_title = "Unused arguments omitted" %]
[% unused = "See L<" _ unused_title _ ">." %]

=head1 NAME

[% config.base %]::Libpng - Perl interface to the C library "libpng".

[% INCLUDE "warning" %]

=head1 SYNOPSIS

     use [% config.base %]::Libpng;
     my $png = [% config.base %]::Libpng::create_read_struct ();
     open my $file, '<:raw', 'nice.png';
     [% config.base %]::Libpng::init_io ($png, $file);
     [% config.base %]::Libpng::read_png ($png);
     close $file;
     [% config.base %]::Libpng::destroy_read_struct ($png);

[% config.base %]::Libpng enables Perl to use the "libpng" library for
reading and writing files in the PNG (Portable Network Graphics)
format.

[% config.base %]::Libpng consists of Perl subroutines which mirror
the C functions in libpng, plus helper subroutines to make it easier
to read and write PNG data in Perl. 

For an easy way to access PNG files, try the companion module L<[%
config.base %]>, which offers a simplified interface to the functions
in this module.

For those who are familiar with libpng, to know what the differences
between this module and libpng are, please go to the section
L</Differences from libpng>.

=head1 FUNCTIONS

=head2 create_read_struct

     my $png = create_read_struct ();

Create a structure for reading a PNG.

[% cor(fn="create_read_struct") %] plus C<create_info_struct> (see [%
xnoinfo %]) with the error and warning handler variables set up to use
Perl's error reporting.

=head2 create_write_struct

     my $png = create_write_struct ();

Create a structure for writing a PNG.

[% cor(fn="create_write_struct") %] plus C<create_info_struct> (see [%
xnoinfo %])  with the error and warning handler variables set up to use
Perl's error reporting.

=head2 destroy_read_struct

     destroy_read_struct ($png);

This frees the memory associated with C<$png>. 

[% cor(fn="destroy_read_struct") %], without the
info and end_info arguments. See [% xnoinfo %].

=head2 destroy_write_struct

     destroy_write_struct ($png);

This frees the memory associated with C<$png>.

[% cor(fn="destroy_write_struct") %].

=head1 Input and output

=head2 init_io

     open my $file, "<", 'nice.png';
     init_io ($png, $file);

Set the file which C<$png> reads or writes to C<$file>. C<$file> must
be an already-opened Perl file handle. If C<$png> was created with
L<create_write_struct>, C<$file> must be opened for writing. If
C<$png> was created with L<create_read_struct>, C<$file> must be open
for reading.

Since PNG files are binary files, it's safest to specify the "raw"
pragma or use "binmode" with the file in order to override any default
text file encoding which Perl might be using:

     open my $file, ">:raw", 'output.png';

or

     open my $file, ">", 'output.png';
     binmode $file;

[% cor(fn="init_io") %], with a Perl
file handle substituting for the C C<FILE *>.

=head2 read_from_scalar

     my $png = create_read_struct ();
     read_from_scalar ($png, $string);

This subroutine sets the image data of C<$png> to be the contents of a
Perl scalar variable C<$string>. [% rfirstpng %] It reads in all the
data from the structure on being called.

This is useful when image data is stored in a Perl scalar. For example

     use LWP::Simple;
     my $image_data = get 'http://www.example.com/example.png';
     # Now $image_data contains the PNG file
     my $png = create_read_struct ();
     read_from_scalar ($png, $image_data);
     # Now $png contains the PNG information from the image.

[% libpng %]

This uses C<png_set_read_fn> to set the reading function of C<$png> to
a routine which reads data from Perl scalars. It then uses
C<png_read_png> to read all the data.

The C function which does this is called C<perl_png_scalar_read>, 
[% perl_libpng_c %].

See also L</Input/output manipulation functions>.

=head2 write_to_scalar

    my $image_data = write_to_scalar ($png);

This writes the PNG image data in C<$png> into a Perl scalar. So, for
example,

    my $img = write_to_scalar ($png);
    open my $output, ">:raw", "test-write-scalar.png";
    print $output $img;
    close $output;

creates a PNG file called C<test-write-scalar.png> from the PNG data
in C<$png>.

[% wfirstpng %] The return value of the subroutine is the Perl scalar
containing the image data.

[% libpng %]

This subroutine doesn't correspond directly to anything in libpng. It
uses C<png_set_write_fn> to set the writing function of C<$png> to be
its own function, which writes data to the Perl scalar.

The C function which does this is called C<perl_png_scalar_write>, 
[% perl_libpng_c %].

See also L</Input/output manipulation functions>.

=head2 read_png

     read_png ($png);

Read the entire PNG file. You can provide a second argument containing
transformations to apply to the image:

     use [% config.base %]::Const qw/PNG_TRANSFORM_STRIP_ALPHA/;
     read_png ($png, PNG_TRANSFORM_STRIP_ALPHA);

In the absence of any third argument, the default value of
C<PNG_TRANSFORM_IDENTITY> is applied. The possible transformations
which can be applied are

[%- transform_list -%]

[% cor(fn="read_png") %] with a default value for the third
argument. The fourth, unused, argument to C<png_read_png> does not
need to be supplied. [% unused %]

[% noinfoxref %]

=head2 write_png

    write_png ($png);

This writes the PNG to the file stream. Before using this, open a file
for writing and set it up with L</init_io>. For example,

    open my $output, ">:raw", 'out.png';
    init_io ($png, $output);
    write_png ($png);
    close $output;

There is an optional second argument consisting of transformations to
apply to the PNG image before writing it:

    use [% config.base %]::Const qw/PNG_TRANSFORM_STRIP_ALPHA/;
    write_png ($png, PNG_TRANSFORM_STRIP_ALPHA);

The transformations which can be applied are as follows:

[% transform_list %]

(NOTE: this list might be wrong, it is just copied from the linux lib
pages & the linux lib pages have different transformations for the
read and write png functions.)

[% cor(fn="write_png") %].

=head1 The image header

See [% spec("11IHDR") %] for information on the PNG standards for
the image header.


=head2 sig_cmp

    if (sig_cmp ($should_be_png)) {
        print "Your data does not have a PNG signature.\n";
    }

This subroutine looks at C<$should_be_png> and checks whether its
first bytes correspond to a valid PNG signature. It returns a true
value if they do not. It can also take two further arguments
consisting of a byte offset and a number of bytes to check
respectively:

    sig_cmp ($should_be_png, 0, 8);

If these arguments are not supplied, the byte offset is assumed
to be zero, and the number of bytes to check is assumed to be eight.

[% cor(fn="sig_cmp") %], with default arguments of
0 and 8 if second and third arguments are not supplied.

=head2 get_valid

    my $valid = get_valid ($png);
    if ($valid->{oFFs}) {
        print "The PNG has valid screen offsets.\n";
    }

This function returns a hash with a key for each possible chunk which
may or may not be valid. The chunks which you can test for are

=over
[% FOR chunk IN chunks %]
=item [% chunk.name %]
[% END %]
=back

[% rfirstpng %]

[% cor(fn = "get_valid") %], with the difference being that the
return value is a hash containing a key for each possible chunk.

=head2 get_IHDR

    my $IHDR = get_IHDR ($png);

Read the IHDR information from the PNG file. The return value is a
reference to a hash.

The hash reference contains the following fields:

=over

[% FOR field IN ihdr_fields -%]
[%- IF ! field.unused %]
=item [% field.name %]

[%- IF field.text %]
[% field.text %]
[%- END -%]
[%- IF field.retvalues -%]
This can take the values [% field.retvalues.join (", ") %].
[%- END %]
[%- END %]

[%- END %]

=back

So, for example, to get the width and height of an image,

    my $ihdr = get_IHDR ($png);
    printf "Your image is %d x %d\n", $ihdr->{width}, $ihdr->{height};

[% cor(fn="get_IHDR") %], with a single Perl hash reference
used instead of the several pointers to integers used in libpng.

=head2 set_IHDR

    my $ihdr = { width => 10, height => 10, bit_depth => 8,
                 color_type => PNG_COLOR_TYPE_RGB };
    set_IHDR ($png, $ihdr);

Set the IHDR chunk (the image header) of the PNG image. 

[% wfirstpng %] The second argument is a hash with the following values:

=over

[% FOR field IN ihdr_fields -%]
[%- IF ! field.unused %]
=item [% field.name %]

[%- IF field.text %]
[% field.text %]
[%- END -%]
[%- IF field.retvalues -%]
This can have the values [% field.retvalues.join (", ") %].
[%- END %]
[%- END %]

[%- END %]

=back

Other fields in the hash are ignored.

[% cor(fn="set_IHDR") %], with a single Perl hash reference
used instead of the seven integers. The variables
[% FOR field IN ihdr_fields -%]
[%- IF field.unused -%]
C<[%- field.name %]>, [% END -%]
[%- END %]
in C<png_set_IHDR> can only take one possible value, so the routine
ignores them. [% unused %]

=head2 get_color_type

    my $color_type;
    [% config.base %]::Libpng::get_color_type ($png, \$color_type);

This returns an integer value. If you want to get a name for the
colour type, use L</color_type_name>.

[% cor(fn="get_color_type") %].

=head1 PNG timestamps

See [% spec("11timestampinfo") %] for information on the PNG standards for
time stamp information.

=head2 get_tIME

    my $time = [% config.base %]::Libpng::get_tIME ($png);
    if ($time && $time->{year} < 2005) {
        warn "Your PNG is now getting old. Don't forget to oil it to prevent rust.";
    }

This subroutine gets the modification time value of the PNG image and
puts it into fields labelled "year", "month", "day", "hour", "minute"
and "second" of the hash reference given as the third argument. If
there is no modification time it returns an undefined value.

[% cor(fn="get_tIME") %], with a Perl hash reference
substituted for the C struct C<png_timep> used in libpng.

=head2 set_tIME

    # Set the time to "now"
    set_tIME ($png);
    # Set the time
    set_tIME ($png, {year => 1999, month => 12});

Set the modification time of the PNG to the hash value given by the
second argument. If the second argument is omitted, the time is set to
the current time. If any of year, month, day, hour, minute or second
is omitted, these are set to zero.

[% cor(fn="set_tIME") %], with a Perl hash reference
substituted for the C struct C<png_timep> used in libpng.

=head1 Text chunks

See [% spec("11textinfo") %] for information on the PNG standards for
text information.

=head2 get_text

    my $text_chunks = [% config.base %]::Libpng::get_text ($png);

This subroutine gets all the text chunks in the PNG image and returns
them as an array reference. Each element of the array represents one
text chunk. The element representing one chunk is a hash reference
with the text fields such as "key", "lang_key", "compression" taken
from the PNG's information.

The text data is uncompressed by libpng. If it is international text,
[% config.base %]::Libpng automatically puts it into Perl's internal
Unicode encoding (UTF-8). 

Note that PNG international text is required to be in the UTF-8
encoding, and non-international text is required to contain whitespace
and printable ASCII characters only. See L</[% pngspec %]> for more on
the requirements of a PNG text section.

[% cor(fn="get_text") %], with a Perl array of hash
references substituted for the C array of structs used in libpng.

=head2 set_text

    set_text ($png, $text_chunks);

This sets the text chunks in an array reference C<$text_chunks>. [%
wfirstarg %]. If you call it more than once, the chunks are appended
to the existing ones rather than replacing them.

    set_text ($png, [{compression => PNG_TEXT_COMPRESSION_NONE,
                      keyword => "Copyright",
                      text => "Copyright (C) 1997 The Dukes of Hazzard",
              }]);

[% cor(fn="set_text") %].

=head1 Private chunks

=head2 set_keep_unknown_chunks

    use Image::PNG::Const 'PNG_HANDLE_CHUNK_ALWAYS';
    set_keep_unknown_chunks ($png, PNG_HANDLE_CHUNK_ALWAYS);

Tell libpng not to discard unknown chunks when reading the file.

=head2 get_unknown_chunks

    my $private_chunks = get_unknown_chunks ($png);
    # Get some data from a private chunk
    my $chunk_three_data = $private_chunks->[3]->{data};
    # Get the size of the data
    print length $chunk_three_data;

This gets all of the private chunks from the image. You need to call
L</set_keep_unknown_chunks> with an appropriate value before reading
the file, otherwise libpng discards unknown chunks when reading the
file.

The return value is an array reference containing hash references. If
there are no private chunks, this returns an undefined value. There is
one element of the array for each chunk member.

Each member hash reference has the following keys:

=over
[% FOR field IN unknown_chunk_fields %]
=item [% field.name %]

[% field.description %]
[% END %]
=back

The "size" field of the PNG structure is not stored, because the
"data" member of the hash contains information on its length.

[% cor(fn="get_unknown_chunks") %]

=head2 set_unknown_chunks

    set_unknown_chunks ($png, $private_chunks);

[% cor(fn="set_unknown_chunks") %]

=head1 Helper functions

These helper functions assist the programmer in the transition from
libpng, which uses C conventions such as upper case macros standing
for numerical constants and C structures, to Perl's string-based
conventions.

=head2 color_type_name

    my $name = [% config.base %]::Libpng::color_type_name ($color_type);

Given a numerical colour type in C<$color_type>, return the equivalent
name. The name is in upper case, with words separated by underscores,
as in C<RGB_ALPHA>.

[% libpng %]

This function does not correspond to anything in libpng. The names of
the colour types are taken from those defined in the libpng header
file, C<png.h>.

=head2 text_compression_name

    my $name = [% config.base %]::Libpng::text_compression_name ($text->{compression});

Given a numerical text compression type, return the equivalent
name. The name is in upper case. The possible return values are

=over

=item TEXT_NONE

=item TEXT_zTXt

=item ITXT_NONE

=item ITXT_zTXt

=item an empty string

if the compression method is unknown.

=back

For some reason the compression field is also used to store the
information about whether the text is "international text" in UTF-8 or
not.

[% libpng %]

This function does not correspond to anything in libpng. The names of
the text compression types are based on those in C<png.h>, but without
the word "COMPRESSION", so for example the libpng constant
C<PNG_ITXT_COMPRESSION_zTXt> corresponds to a return value of
C<ITXT_zTXt>.

=head1 Library version functions

=head2 get_libpng_ver

    my $libpng_version = [% config.base %]::Libpng::get_libpng_ver ();

This function returns the version of the libpng library which the
module is using.

[% cor(fn="get_libpng_ver") %]. However, it
doesn't require the C<png_structp> argument of the C function. See
L</About libpng>.

=head2 access_version_number

    my $libpng_version_number = [% config.base %]::Libpng::access_version_number ();

This function returns the version of the libpng library which the
module is using as an integer number.

[% cor(fn="access_version_number") %].

=head1 Palettes

See [% spec("11PLTE") %] for information on the PNG standards for
the palette chunk.

=head2 get_PLTE

     my $colours = [% config.base %]::Libpng::get_PLTE ($png);
     # Get the green value of the twentieth entry in the palette.
     my $green = $colours->[20]->{green};

This function gets the palette from the PNG. The return value is an
array reference containing the palette. This array contains hash
references with the values "green", "blue" and "red" for the colour of
each pixel in the palette. If the PNG has no palette, it returns an
undefined value.

A PNG image may or may not contain a palette. To check whether the
image contains a palette, use something of the following form:

     use [% config.base %]::Const ':all';
     my $color_type = [% config.base %]::Libpng::get_color_type ($png);
     if ($color_type == PNG_COLOR_TYPE_PALETTE) {
         # The PNG uses a palette.
     }

A PNG image may also contain a palette even when the "color_type" does
not indicate that. To check for that case, use L</get_valid>.

[% cor(fn="get_PLTE") %].

=head2 set_PLTE

    set_PLTE ($png, $palette);

Set the palette of C<$png>. [% wfirstpng %] The second argument is an
array reference containing hash references. There is one hash
reference for each palette entry. The hash references contain three
fields, red, green, and blue, corresponding to the pixel value for
that palette entry. Other values in the hash references are
ignored. For example,

    set_PLTE ($png, [{red => 1, green => 99, blue => 0x10},
                     {red => 0xFF, green => 0xFF, blue => 0xFF}]);

creates a palette with two entries in C<$png>.

[% cor(fn="set_PLTE") %].

=head1 Image data

=head2 get_rows

    my $rows = [% config.base %]::Libpng::get_rows ($png);
    my $pixel = substr ($rows->[10], 20, 1);

This returns the rows of the PNG image, after uncompressing and
unfiltering, as binary data. The return value, C<$rows> in the
example, is an array reference with a number of rows equal to the
height of the PNG image. Each row consists of the actual binary data,
which you will need to cut out using a routine like L<substr> or
L<unpack> to access pixel values. This binary data is likely to
contain bytes equal to zero.

You can get the number of bytes in each row using L</get_rowbytes>.

Each row is a Perl string. Perl terminates each row of data with an
extra zero byte at the end.

[% cor(fn="get_rows") %].

=head2 set_rows

     set_rows ($png, \@rows);

Set the rows of data to be written in to the PNG to C<@rows>. C<@rows>
needs to contain at least the same number of rows of data as the
height of the PNG image, and the length of each entry needs to be at
least the width of the entry times the number of bytes required for
each pixel.

Please also note that this is a bit unreliable. 
See L</set_rows is unreliable>.
I recommend that you only use this immediately before calling L</write_png> 
in order to prevent problems occuring.

[% cor(fn="set_rows") %].

=head2 get_rowbytes

    my $bytes_in_a_row = get_rowbytes ($png);

[% cor(fn="get_rowbytes") %].

=head1 Compression and filtering

=head2 set_filter

    use Image::PNG::Const 'PNG_FILTER_NONE';
    set_filter ($png, PNG_FILTER_NONE);

This sets the filters which are allowed to be used for writing a PNG
image. The possible values are

=over
[% FOR filter IN filters %]
=item [% filter.macro %]
[% END %]
=back

These can be combined using C<|> (logical or):

    use Image::PNG::Const ':all';
    set_filter ($png, PNG_FILTER_UP | PNG_FILTER_AVG);

Please see [% spec("9Filter-types") %] for the meanings of these
filter types.

[% cor(fn="set_filter") %] with the second (unused)
argument omitted. [% unused %]

=head1 EXPORTS

Nothing is exported by default, but all the functions in this module
can be exported on request. The export tag 'all' exports everything in
the module:

    use [% config.base %]::Libpng ':all';
    # Now everything in the module has been imported

=head1 Differences from libpng

The procedures in [% config.base %]::Libpng are closely based on
those of libpng, with the following differences.

=head2 [% noinfo %]

This module, C<[% config.base %]::Libpng> does not use the "info"
structure of libpng. Almost all libpng functions require two initial
arguments, a C<png_structp> and a C<png_infop>. However, in 
[% config.base %]::Libpng, both the "png" and the "info" are contained in
the first argument to each function.

=head2 [% unused_title %]

This module eliminates all the unevaluated arguments of libpng. For
example, libpng requires the user to pass a pointer to a C<png_struct>
before calling the library to ask for its version number (see
L</get_libpng_ver>), but the library ignores the this structure
anyway, so this module does not duplicate this. There are many similar
instances of unevaluated arguments, which have all been eliminated
from this module.

If you are interested in exactly which libpng arguments are omitted,
you can find each instance [% perl_libpng_c %] in the macro
C<UNUSED_ZERO_ARG>.

=head2 Function return values are used to return values

In libpng, some functions return results using references, and some
return results using the function's return value. For example
C<png_get_rows> (see L</get_rows>) uses the return value of the
function to return an array of pointers, but C<png_get_PLTE> (see
L</get_PLTE>) uses a pointer reference to return an array of pointers,
and the return value to indicate errors. 

[% config.base %]::Libpng uses only the return value. Errors and
non-existence are indicated by a return value of the undefined
value. You can also choose to raise errors or print errors using the
L</raise_error> and L</print_error> options.

In libpng, some functions use the return value to indicate errors, and
some of the functions don't indicate errors but fail silently. Some of
the functions which use the return value to indicate an error use a
non-zero value to indicate an error, and some of them use a zero value
to indicate an error.

=head2 Other unimplemented parts of libpng

=head3 Memory management functions

This module does not offer an interface to C<png_malloc> and C<png_free>.

=head3 Error handling functions

This module does not offer an interface to C<png_error> and
C<png_get_error_ptr>. It redirects the error and warning handlers to
Perl's error stream.

=head3 Input/output manipulation functions

This module does not offer a direct interface to C<png_set_write_fn>
and C<png_set_read_fn>. However, it is possible to use their
functionality to access Perl data via L</read_from_scalar> and
L</write_to_scalar>.

=head3 Partial read/write functions

This module does not yet offer an interface to the partial read and
write functions of libpng. The reason is because I don't know enough
about Perl's internal structures to be able to create a memory-safe
interface to these functions. The partial read/write functions would
rely on preserving pointers to data structures within the Perl
program's data area between calls. So this module doesn't deal with
png_write_chunk, png_write_end, png_write_info, png_write_row, or
png_write_rows.

=head1 DIAGNOSTICS

The module may produce the following error or warning messages.

=over
[% FOR diagnostic IN libpng_diagnostics %]

=item [% diagnostic.message %]

(
[%- IF diagnostic.type == "error" -%]
F
[%- ELSIF diagnostic.type == "warn" -%]
W
[%- END -%]
) [% IF diagnostic.comment %]
[% diagnostic.comment %]
[% END %]

[% END %]

=back

=head1 BUGS

This section documents some known deficiencies in the module.

=head2 set_rows is unreliable

The method L</set_rows> doesn't actually copy or write any
information. All it does is set a pointer to the pointers to the rows
in the PNG data structure. The actual data is only written when you
ask to write it. So if you "set_rows" to some data, then delete or
change that data before asking to write the png with L</write_png>,
you will get a memory error.

=head2 Conditional compilation

It is possible to compile a version of the libpng library without
support for various things. For example, it's possible to have a
libpng without support for text chunks by undefining a macro
C<PNG_TEXT_SUPPORTED>. The module supports some of the conditional
compilation choices which I've found in practice, but it does not
support every possible choice. If you encounter problems using this
Perl module because of a conditionally-compiled libpng, then please
let me know and I'll consider adding that facility to the module.

=head1 SEE ALSO

=head2 [% pngspec %]

[% INCLUDE "pngspec" %]

=head2 [% libpngdoc %]

=head3 "Official" documentation

The starting point is the plain text libpng manual at
L<http://libpng.org/pub/png/libpng-manual.txt> and the manual page
libpng.3, which you can read using "man 3 libpng".

Be warned that the documentation which comes with libpng is rather
sketchy. See L</Differences from libpng>. It doesn't contain full
specifications (prototypes, return values) for all of the functions in
the library. If you are considering programming in C using libpng, you
will definitely also need to look at the header file "png.h".  In some
cases you will also need to look at the source code of the library.

=head3 Unofficial documentation

There is a collection of function definitions under the title
"Interface Definitions for libpng12" at
L<http://refspecs.freestandards.org/LSB_3.1.1/LSB-Desktop-generic/LSB-Desktop-generic/libpng12man.html>
as part of the "Linux Standard Base Desktop Specification". These
contain extensive information on the prototypes and return values for
the libpng routines, something which is often only available elsewhere
by actually looking at the libpng source code. These pages are usually
the first hits on search engines if you search for a function name in
libpng.

[% INCLUDE "other_modules" %]

[% INCLUDE "examples_doc" %]

[% INCLUDE "author" %]

=cut

# Local Variables:
# mode: perl
# End:
