libpng/libpng-1.2.38rc02.txt

libpng.txt - A description on how to use and modify libpng

 libpng version 1.2.38rc02 - June 29, 2009
 Updated and distributed by Glenn Randers-Pehrson
 <glennrp at users.sourceforge.net>
 Copyright (c) 1998-2009 Glenn Randers-Pehrson
 For conditions of distribution and use, see copyright
 notice in png.h.

 Based on:

 libpng versions 0.97, January 1998, through 1.2.38rc02 - June 29, 2009
 Updated and distributed by Glenn Randers-Pehrson
 Copyright (c) 1998-2009 Glenn Randers-Pehrson

 libpng 1.0 beta 6  version 0.96 May 28, 1997
 Updated and distributed by Andreas Dilger
 Copyright (c) 1996, 1997 Andreas Dilger

 libpng 1.0 beta 2 - version 0.88  January 26, 1996
 For conditions of distribution and use, see copyright
 notice in png.h. Copyright (c) 1995, 1996 Guy Eric
 Schalnat, Group 42, Inc.

 Updated/rewritten per request in the libpng FAQ
 Copyright (c) 1995, 1996 Frank J. T. Wojcik
 December 18, 1995 & January 20, 1996

I. Introduction

This file describes how to use and modify the PNG reference library
(known as libpng) for your own use.  There are five sections to this
file: introduction, structures, reading, writing, and modification and
configuration notes for various special platforms.  In addition to this
file, example.c is a good starting point for using the library, as
it is heavily commented and should include everything most people
will need.  We assume that libpng is already installed; see the
INSTALL file for instructions on how to install libpng.

For examples of libpng usage, see the files "example.c", "pngtest.c",
and the files in the "contrib" directory, all of which are included in the
libpng distribution.

Libpng was written as a companion to the PNG specification, as a way
of reducing the amount of time and effort it takes to support the PNG
file format in application programs.

The PNG specification (second edition), November 2003, is available as
a W3C Recommendation and as an ISO Standard (ISO/IEC 15948:2003 (E)) at
<http://www.w3.org/TR/2003/REC-PNG-20031110/
The W3C and ISO documents have identical technical content.

The PNG-1.2 specification is available at
<http://www.libpng.org/pub/png/documents/>.  It is technically equivalent
to the PNG specification (second edition) but has some additional material.

The PNG-1.0 specification is available
as RFC 2083 <http://www.libpng.org/pub/png/documents/> and as a
W3C Recommendation <http://www.w3.org/TR/REC.png.html>.

Some additional chunks are described in the special-purpose public chunks
documents at <http://www.libpng.org/pub/png/documents/>.

Other information
about PNG, and the latest version of libpng, can be found at the PNG home
page, <http://www.libpng.org/pub/png/>.

Most users will not have to modify the library significantly; advanced
users may want to modify it more.  All attempts were made to make it as
complete as possible, while keeping the code easy to understand.
Currently, this library only supports C.  Support for other languages
is being considered.

Libpng has been designed to handle multiple sessions at one time,
to be easily modifiable, to be portable to the vast majority of
machines (ANSI, K&R, 16-, 32-, and 64-bit) available, and to be easy
to use.  The ultimate goal of libpng is to promote the acceptance of
the PNG file format in whatever way possible.  While there is still
work to be done (see the TODO file), libpng should cover the
majority of the needs of its users.

Libpng uses zlib for its compression and decompression of PNG files.
Further information about zlib, and the latest version of zlib, can
be found at the zlib home page, <http://www.info-zip.org/pub/infozip/zlib/>.
The zlib compression utility is a general purpose utility that is
useful for more than PNG files, and can be used without libpng.
See the documentation delivered with zlib for more details.
You can usually find the source files for the zlib utility wherever you
find the libpng source files.

Libpng is thread safe, provided the threads are using different
instances of the structures.  Each thread should have its own
png_struct and png_info instances, and thus its own image.
Libpng does not protect itself against two threads using the
same instance of a structure.

II. Structures

There are two main structures that are important to libpng, png_struct
and png_info.  The first, png_struct, is an internal structure that
will not, for the most part, be used by a user except as the first
variable passed to every libpng function call.

The png_info structure is designed to provide information about the
PNG file.  At one time, the fields of png_info were intended to be
directly accessible to the user.  However, this tended to cause problems
with applications using dynamically loaded libraries, and as a result
a set of interface functions for png_info (the png_get_*() and png_set_*()
functions) was developed.  The fields of png_info are still available for
older applications, but it is suggested that applications use the new
interfaces if at all possible.

Applications that do make direct access to the members of png_struct (except
for png_ptr->jmpbuf) must be recompiled whenever the library is updated,
and applications that make direct access to the members of png_info must
be recompiled if they were compiled or loaded with libpng version 1.0.6,
in which the members were in a different order.  In version 1.0.7, the
members of the png_info structure reverted to the old order, as they were
in versions 0.97c through 1.0.5.  Starting with version 2.0.0, both
structures are going to be hidden, and the contents of the structures will
only be accessible through the png_get/png_set functions.

The png.h header file is an invaluable reference for programming with libpng.
And while I'm on the topic, make sure you include the libpng header file:

#include <png.h>

III. Reading

We'll now walk you through the possible functions to call when reading
in a PNG file sequentially, briefly explaining the syntax and purpose
of each one.  See example.c and png.h for more detail.  While
progressive reading is covered in the next section, you will still
need some of the functions discussed in this section to read a PNG
file.

Setup

You will want to do the I/O initialization(*) before you get into libpng,
so if it doesn't work, you don't have much to undo.  Of course, you
will also want to insure that you are, in fact, dealing with a PNG
file.  Libpng provides a simple check to see if a file is a PNG file.
To use it, pass in the first 1 to 8 bytes of the file to the function
png_sig_cmp(), and it will return 0 (false) if the bytes match the
corresponding bytes of the PNG signature, or nonzero (true) otherwise.
Of course, the more bytes you pass in, the greater the accuracy of the
prediction.

If you are intending to keep the file pointer open for use in libpng,
you must ensure you don't read more than 8 bytes from the beginning
of the file, and you also have to make a call to png_set_sig_bytes_read()
with the number of bytes you read from the beginning.  Libpng will
then only check the bytes (if any) that your program didn't read.

(*): If you are not using the standard I/O functions, you will need
to replace them with custom functions.  See the discussion under
Customizing libpng.


    FILE *fp = fopen(file_name, "rb");
    if (!fp)
    {
        return (ERROR);
    }
    fread(header, 1, number, fp);
    is_png = !png_sig_cmp(header, 0, number);
    if (!is_png)
    {
        return (NOT_PNG);
    }


Next, png_struct and png_info need to be allocated and initialized.  In
order to ensure that the size of these structures is correct even with a
dynamically linked libpng, there are functions to initialize and
allocate the structures.  We also pass the library version, optional
pointers to error handling functions, and a pointer to a data struct for
use by the error functions, if necessary (the pointer and functions can
be NULL if the default error handlers are to be used).  See the section
on Changes to Libpng below regarding the old initialization functions.
The structure allocation functions quietly return NULL if they fail to
create the structure, so your application should check for that.

    png_structp png_ptr = png_create_read_struct
       (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
        user_error_fn, user_warning_fn);
    if (!png_ptr)
        return (ERROR);

    png_infop info_ptr = png_create_info_struct(png_ptr);
    if (!info_ptr)
    {
        png_destroy_read_struct(&png_ptr,
           (png_infopp)NULL, (png_infopp)NULL);
        return (ERROR);
    }

    png_infop end_info = png_create_info_struct(png_ptr);
    if (!end_info)
    {
        png_destroy_read_struct(&png_ptr, &info_ptr,
          (png_infopp)NULL);
        return (ERROR);
    }

If you want to use your own memory allocation routines,
define PNG_USER_MEM_SUPPORTED and use
png_create_read_struct_2() instead of png_create_read_struct():

    png_structp png_ptr = png_create_read_struct_2
       (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
        user_error_fn, user_warning_fn, (png_voidp)
        user_mem_ptr, user_malloc_fn, user_free_fn);

The error handling routines passed to png_create_read_struct()
and the memory alloc/free routines passed to png_create_struct_2()
are only necessary if you are not using the libpng supplied error
handling and memory alloc/free functions.

When libpng encounters an error, it expects to longjmp back
to your routine.  Therefore, you will need to call setjmp and pass
your png_jmpbuf(png_ptr).  If you read the file from different
routines, you will need to update the jmpbuf field every time you enter
a new routine that will call a png_*() function.

See your documentation of setjmp/longjmp for your compiler for more
information on setjmp/longjmp.  See the discussion on libpng error
handling in the Customizing Libpng section below for more information
on the libpng error handling.  If an error occurs, and libpng longjmp's
back to your setjmp, you will want to call png_destroy_read_struct() to
free any memory.

    if (setjmp(png_jmpbuf(png_ptr)))
    {
        png_destroy_read_struct(&png_ptr, &info_ptr,
           &end_info);
        fclose(fp);
        return (ERROR);
    }

If you would rather avoid the complexity of setjmp/longjmp issues,
you can compile libpng with PNG_SETJMP_NOT_SUPPORTED, in which case
errors will result in a call to PNG_ABORT() which defaults to abort().

Now you need to set up the input code.  The default for libpng is to
use the C function fread().  If you use this, you will need to pass a
valid FILE * in the function png_init_io().  Be sure that the file is
opened in binary mode.  If you wish to handle reading data in another
way, you need not call the png_init_io() function, but you must then
implement the libpng I/O methods discussed in the Customizing Libpng
section below.

    png_init_io(png_ptr, fp);

If you had previously opened the file and read any of the signature from
the beginning in order to see if this was a PNG file, you need to let
libpng know that there are some bytes missing from the start of the file.

    png_set_sig_bytes(png_ptr, number);

Setting up callback code

You can set up a callback function to handle any unknown chunks in the
input stream. You must supply the function

    read_chunk_callback(png_ptr ptr,
         png_unknown_chunkp chunk);
    {
       /* The unknown chunk structure contains your
          chunk data, along with similar data for any other
          unknown chunks: */

           png_byte name[5];
           png_byte *data;
           png_size_t size;

       /* Note that libpng has already taken care of
          the CRC handling */

       /* put your code here.  Search for your chunk in the
          unknown chunk structure, process it, and return one
          of the following: */

       return (-n); /* chunk had an error */
       return (0); /* did not recognize */
       return (n); /* success */
    }

(You can give your function another name that you like instead of
"read_chunk_callback")

To inform libpng about your function, use

    png_set_read_user_chunk_fn(png_ptr, user_chunk_ptr,
        read_chunk_callback);

This names not only the callback function, but also a user pointer that
you can retrieve with

    png_get_user_chunk_ptr(png_ptr);

If you call the png_set_read_user_chunk_fn() function, then all unknown
chunks will be saved when read, in case your callback function will need
one or more of them.  This behavior can be changed with the
png_set_keep_unknown_chunks() function, described below.

At this point, you can set up a callback function that will be
called after each row has been read, which you can use to control
a progress meter or the like.  It's demonstrated in pngtest.c.
You must supply a function

    void read_row_callback(png_ptr ptr, png_uint_32 row,
       int pass);
    {
      /* put your code here */
    }

(You can give it another name that you like instead of "read_row_callback")

To inform libpng about your function, use

    png_set_read_status_fn(png_ptr, read_row_callback);

Unknown-chunk handling

Now you get to set the way the library processes unknown chunks in the
input PNG stream. Both known and unknown chunks will be read.  Normal
behavior is that known chunks will be parsed into information in
various info_ptr members while unknown chunks will be discarded. This
behavior can be wasteful if your application will never use some known
chunk types. To change this, you can call:

    png_set_keep_unknown_chunks(png_ptr, keep,
        chunk_list, num_chunks);
    keep       - 0: default unknown chunk handling
                 1: ignore; do not keep
                 2: keep only if safe-to-copy
                 3: keep even if unsafe-to-copy
               You can use these definitions:
                 PNG_HANDLE_CHUNK_AS_DEFAULT   0
                 PNG_HANDLE_CHUNK_NEVER        1
                 PNG_HANDLE_CHUNK_IF_SAFE      2
                 PNG_HANDLE_CHUNK_ALWAYS       3
    chunk_list - list of chunks affected (a byte string,
                 five bytes per chunk, NULL or '\0' if
                 num_chunks is 0)
    num_chunks - number of chunks affected; if 0, all
                 unknown chunks are affected.  If nonzero,
                 only the chunks in the list are affected

Unknown chunks declared in this way will be saved as raw data onto a
list of png_unknown_chunk structures.  If a chunk that is normally
known to libpng is named in the list, it will be handled as unknown,
according to the "keep" directive.  If a chunk is named in successive
instances of png_set_keep_unknown_chunks(), the final instance will
take precedence.  The IHDR and IEND chunks should not be named in
chunk_list; if they are, libpng will process them normally anyway.

Here is an example of the usage of png_set_keep_unknown_chunks(),
where the private "vpAg" chunk will later be processed by a user chunk
callback function:

    png_byte vpAg[5]={118, 112,  65, 103, (png_byte) '\0'};

    #if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED)
      png_byte unused_chunks[]=
      {
        104,  73,  83,  84, (png_byte) '\0',   /* hIST */
        105,  84,  88, 116, (png_byte) '\0',   /* iTXt */
        112,  67,  65,  76, (png_byte) '\0',   /* pCAL */
        115,  67,  65,  76, (png_byte) '\0',   /* sCAL */
        115,  80,  76,  84, (png_byte) '\0',   /* sPLT */
        116,  73,  77,  69, (png_byte) '\0',   /* tIME */
      };
    #endif

    ...

    #if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED)
      /* ignore all unknown chunks: */
      png_set_keep_unknown_chunks(read_ptr, 1, NULL, 0);
      /* except for vpAg: */
      png_set_keep_unknown_chunks(read_ptr, 2, vpAg, 1);
      /* also ignore unused known chunks: */
      png_set_keep_unknown_chunks(read_ptr, 1, unused_chunks,
         (int)sizeof(unused_chunks)/5);
    #endif

User limits

The PNG specification allows the width and height of an image to be as
large as 2^31-1 (0x7fffffff), or about 2.147 billion rows and columns.
Since very few applications really need to process such large images,
we have imposed an arbitrary 1-million limit on rows and columns.
Larger images will be rejected immediately with a png_error() call. If
you wish to override this limit, you can use

   png_set_user_limits(png_ptr, width_max, height_max);

to set your own limits, or use width_max = height_max = 0x7fffffffL
to allow all valid dimensions (libpng may reject some very large images
anyway because of potential buffer overflow conditions).

You should put this statement after you create the PNG structure and
before calling png_read_info(), png_read_png(), or png_process_data().
If you need to retrieve the limits that are being applied, use

   width_max = png_get_user_width_max(png_ptr);
   height_max = png_get_user_height_max(png_ptr);

The high-level read interface

At this point there are two ways to proceed; through the high-level
read interface, or through a sequence of low-level read operations.
You can use the high-level interface if (a) you are willing to read
the entire image into memory, and (b) the input transformations
you want to do are limited to the following set:

    PNG_TRANSFORM_IDENTITY      No transformation
    PNG_TRANSFORM_STRIP_16      Strip 16-bit samples to
                                8 bits
    PNG_TRANSFORM_STRIP_ALPHA   Discard the alpha channel
    PNG_TRANSFORM_PACKING       Expand 1, 2 and 4-bit
                                samples to bytes
    PNG_TRANSFORM_PACKSWAP      Change order of packed
                                pixels to LSB first
    PNG_TRANSFORM_EXPAND        Perform set_expand()
    PNG_TRANSFORM_INVERT_MONO   Invert monochrome images
    PNG_TRANSFORM_SHIFT         Normalize pixels to the
                                sBIT depth
    PNG_TRANSFORM_BGR           Flip RGB to BGR, RGBA
                                to BGRA
    PNG_TRANSFORM_SWAP_ALPHA    Flip RGBA to ARGB or GA
                                to AG
    PNG_TRANSFORM_INVERT_ALPHA  Change alpha from opacity
                                to transparency
    PNG_TRANSFORM_SWAP_ENDIAN   Byte-swap 16-bit samples

(This excludes setting a background color, doing gamma transformation,
dithering, and setting filler.)  If this is the case, simply do this:

    png_read_png(png_ptr, info_ptr, png_transforms, NULL)

where png_transforms is an integer containing the bitwise OR of
some set of transformation flags.  This call is equivalent to png_read_info(),
followed the set of transformations indicated by the transform mask,
then png_read_image(), and finally png_read_end().

(The final parameter of this call is not yet used.  Someday it might point
to transformation parameters required by some future input transform.)

You must use png_transforms and not call any png_set_transform() functions
when you use png_read_png().

After you have called png_read_png(), you can retrieve the image data
with

   row_pointers = png_get_rows(png_ptr, info_ptr);

where row_pointers is an array of pointers to the pixel data for each row:

   png_bytep row_pointers[height];

If you know your image size and pixel size ahead of time, you can allocate
row_pointers prior to calling png_read_png() with

   if (height > PNG_UINT_32_MAX/png_sizeof(png_byte))
      png_error (png_ptr,
         "Image is too tall to process in memory");
   if (width > PNG_UINT_32_MAX/pixel_size)
      png_error (png_ptr,
         "Image is too wide to process in memory");
   row_pointers = png_malloc(png_ptr,
      height*png_sizeof(png_bytep));
   for (int i=0; i<height, i++)
      row_pointers[i]=NULL;  /* security precaution */
   for (int i=0; i<height, i++)
      row_pointers[i]=png_malloc(png_ptr,
         width*pixel_size);
   png_set_rows(png_ptr, info_ptr, &row_pointers);

Alternatively you could allocate your image in one big block and define
row_pointers[i] to point into the proper places in your block.

If you use png_set_rows(), the application is responsible for freeing
row_pointers (and row_pointers[i], if they were separately allocated).

If you don't allocate row_pointers ahead of time, png_read_png() will
do it, and it'll be free'ed when you call png_destroy_*().

The low-level read interface

If you are going the low-level route, you are now ready to read all
the file information up to the actual image data.  You do this with a
call to png_read_info().

    png_read_info(png_ptr, info_ptr);

This will process all chunks up to but not including the image data.

Querying the info structure

Functions are used to get the information from the info_ptr once it
has been read.  Note that these fields may not be completely filled
in until png_read_end() has read the chunk data following the image.

    png_get_IHDR(png_ptr, info_ptr, &width, &height,
       &bit_depth, &color_type, &interlace_type,
       &compression_type, &filter_method);

    width          - holds the width of the image
                     in pixels (up to 2^31).
    height         - holds the height of the image
                     in pixels (up to 2^31).
    bit_depth      - holds the bit depth of one of the
                     image channels.  (valid values are
                     1, 2, 4, 8, 16 and depend also on
                     the color_type.  See also
                     significant bits (sBIT) below).
    color_type     - describes which color/alpha channels
                         are present.
                     PNG_COLOR_TYPE_GRAY
                        (bit depths 1, 2, 4, 8, 16)
                     PNG_COLOR_TYPE_GRAY_ALPHA
                        (bit depths 8, 16)
                     PNG_COLOR_TYPE_PALETTE
                        (bit depths 1, 2, 4, 8)
                     PNG_COLOR_TYPE_RGB
                        (bit_depths 8, 16)
                     PNG_COLOR_TYPE_RGB_ALPHA
                        (bit_depths 8, 16)

                     PNG_COLOR_MASK_PALETTE
                     PNG_COLOR_MASK_COLOR
                     PNG_COLOR_MASK_ALPHA

    filter_method  - (must be PNG_FILTER_TYPE_BASE
                     for PNG 1.0, and can also be
                     PNG_INTRAPIXEL_DIFFERENCING if
                     the PNG datastream is embedded in
                     a MNG-1.0 datastream)
    compression_type - (must be PNG_COMPRESSION_TYPE_BASE
                     for PNG 1.0)
    interlace_type - (PNG_INTERLACE_NONE or
                     PNG_INTERLACE_ADAM7)
    Any or all of interlace_type, compression_type, of
    filter_method can be NULL if you are
    not interested in their values.

    channels = png_get_channels(png_ptr, info_ptr);
    channels       - number of channels of info for the
                     color type (valid values are 1 (GRAY,
                     PALETTE), 2 (GRAY_ALPHA), 3 (RGB),
                     4 (RGB_ALPHA or RGB + filler byte))
    rowbytes = png_get_rowbytes(png_ptr, info_ptr);
    rowbytes       - number of bytes needed to hold a row

    signature = png_get_signature(png_ptr, info_ptr);
    signature      - holds the signature read from the
                     file (if any).  The data is kept in
                     the same offset it would be if the
                     whole signature were read (i.e. if an
                     application had already read in 4
                     bytes of signature before starting
                     libpng, the remaining 4 bytes would
                     be in signature[4] through signature[7]
                     (see png_set_sig_bytes())).


    width            = png_get_image_width(png_ptr,
                         info_ptr);
    height           = png_get_image_height(png_ptr,
                         info_ptr);
    bit_depth        = png_get_bit_depth(png_ptr,
                         info_ptr);
    color_type       = png_get_color_type(png_ptr,
                         info_ptr);
    filter_method    = png_get_filter_type(png_ptr,
                         info_ptr);
    compression_type = png_get_compression_type(png_ptr,
                         info_ptr);
    interlace_type   = png_get_interlace_type(png_ptr,
                         info_ptr);


These are also important, but their validity depends on whether the chunk
has been read.  The png_get_valid(png_ptr, info_ptr, PNG_INFO_<chunk>) and
png_get_<chunk>(png_ptr, info_ptr, ...) functions return non-zero if the
data has been read, or zero if it is missing.  The parameters to the
png_get_<chunk> are set directly if they are simple data types, or a pointer
into the info_ptr is returned for any complex types.

    png_get_PLTE(png_ptr, info_ptr, &palette,
                     &num_palette);
    palette        - the palette for the file
                     (array of png_color)
    num_palette    - number of entries in the palette

    png_get_gAMA(png_ptr, info_ptr, &gamma);
    gamma          - the gamma the file is written
                     at (PNG_INFO_gAMA)

    png_get_sRGB(png_ptr, info_ptr, &srgb_intent);
    srgb_intent    - the rendering intent (PNG_INFO_sRGB)
                     The presence of the sRGB chunk
                     means that the pixel data is in the
                     sRGB color space.  This chunk also
                     implies specific values of gAMA and
                     cHRM.

    png_get_iCCP(png_ptr, info_ptr, &name,
       &compression_type, &profile, &proflen);
    name            - The profile name.
    compression     - The compression type; always
                      PNG_COMPRESSION_TYPE_BASE for PNG 1.0.
                      You may give NULL to this argument to
                      ignore it.
    profile         - International Color Consortium color
                      profile data. May contain NULs.
    proflen         - length of profile data in bytes.

    png_get_sBIT(png_ptr, info_ptr, &sig_bit);
    sig_bit        - the number of significant bits for
                     (PNG_INFO_sBIT) each of the gray,
                     red, green, and blue channels,
                     whichever are appropriate for the
                     given color type (png_color_16)

    png_get_tRNS(png_ptr, info_ptr, &trans, &num_trans,
                     &trans_values);
    trans          - array of transparent entries for
                     palette (PNG_INFO_tRNS)
    trans_values   - graylevel or color sample values of
                     the single transparent color for
                     non-paletted images (PNG_INFO_tRNS)
    num_trans      - number of transparent entries
                     (PNG_INFO_tRNS)

    png_get_hIST(png_ptr, info_ptr, &hist);
                     (PNG_INFO_hIST)
    hist           - histogram of palette (array of
                     png_uint_16)

    png_get_tIME(png_ptr, info_ptr, &mod_time);
    mod_time       - time image was last modified
                    (PNG_VALID_tIME)

    png_get_bKGD(png_ptr, info_ptr, &background);
    background     - background color (PNG_VALID_bKGD)
                     valid 16-bit red, green and blue
                     values, regardless of color_type

    num_comments   = png_get_text(png_ptr, info_ptr,
                     &text_ptr, &num_text);
    num_comments   - number of comments
    text_ptr       - array of png_text holding image
                     comments
    text_ptr[i].compression - type of compression used
                 on "text" PNG_TEXT_COMPRESSION_NONE
                           PNG_TEXT_COMPRESSION_zTXt
                           PNG_ITXT_COMPRESSION_NONE
                           PNG_ITXT_COMPRESSION_zTXt
    text_ptr[i].key   - keyword for comment.  Must contain
                         1-79 characters.
    text_ptr[i].text  - text comments for current
                         keyword.  Can be empty.
    text_ptr[i].text_length - length of text string,
                 after decompression, 0 for iTXt
    text_ptr[i].itxt_length - length of itxt string,
                 after decompression, 0 for tEXt/zTXt
    text_ptr[i].lang  - language of comment (empty
                         string for unknown).
    text_ptr[i].lang_key  - keyword in UTF-8
                         (empty string for unknown).
    num_text       - number of comments (same as
                     num_comments; you can put NULL here
                     to avoid the duplication)
    Note while png_set_text() will accept text, language,
    and translated keywords that can be NULL pointers, the
    structure returned by png_get_text will always contain
    regular zero-terminated C strings.  They might be
    empty strings but they will never be NULL pointers.

    num_spalettes = png_get_sPLT(png_ptr, info_ptr,
       &palette_ptr);
    palette_ptr    - array of palette structures holding
                     contents of one or more sPLT chunks
                     read.
    num_spalettes  - number of sPLT chunks read.

    png_get_oFFs(png_ptr, info_ptr, &offset_x, &offset_y,
       &unit_type);
    offset_x       - positive offset from the left edge
                     of the screen
    offset_y       - positive offset from the top edge
                     of the screen
    unit_type      - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER

    png_get_pHYs(png_ptr, info_ptr, &res_x, &res_y,
       &unit_type);
    res_x          - pixels/unit physical resolution in
                     x direction
    res_y          - pixels/unit physical resolution in
                     x direction
    unit_type      - PNG_RESOLUTION_UNKNOWN,
                     PNG_RESOLUTION_METER

    png_get_sCAL(png_ptr, info_ptr, &unit, &width,
       &height)
    unit        - physical scale units (an integer)
    width       - width of a pixel in physical scale units
    height      - height of a pixel in physical scale units
                 (width and height are doubles)

    png_get_sCAL_s(png_ptr, info_ptr, &unit, &width,
       &height)
    unit        - physical scale units (an integer)
    width       - width of a pixel in physical scale units
    height      - height of a pixel in physical scale units
                 (width and height are strings like "2.54")

    num_unknown_chunks = png_get_unknown_chunks(png_ptr,
       info_ptr, &unknowns)
    unknowns          - array of png_unknown_chunk
                        structures holding unknown chunks
    unknowns[i].name  - name of unknown chunk
    unknowns[i].data  - data of unknown chunk
    unknowns[i].size  - size of unknown chunk's data
    unknowns[i].location - position of chunk in file

    The value of "i" corresponds to the order in which the
    chunks were read from the PNG file or inserted with the
    png_set_unknown_chunks() function.

The data from the pHYs chunk can be retrieved in several convenient
forms:

    res_x = png_get_x_pixels_per_meter(png_ptr,
       info_ptr)
    res_y = png_get_y_pixels_per_meter(png_ptr,
       info_ptr)
    res_x_and_y = png_get_pixels_per_meter(png_ptr,
       info_ptr)
    res_x = png_get_x_pixels_per_inch(png_ptr,
       info_ptr)
    res_y = png_get_y_pixels_per_inch(png_ptr,
       info_ptr)
    res_x_and_y = png_get_pixels_per_inch(png_ptr,
       info_ptr)
    aspect_ratio = png_get_pixel_aspect_ratio(png_ptr,
       info_ptr)

   (Each of these returns 0 [signifying "unknown"] if
       the data is not present or if res_x is 0;
       res_x_and_y is 0 if res_x != res_y)

The data from the oFFs chunk can be retrieved in several convenient
forms:

    x_offset = png_get_x_offset_microns(png_ptr, info_ptr);
    y_offset = png_get_y_offset_microns(png_ptr, info_ptr);
    x_offset = png_get_x_offset_inches(png_ptr, info_ptr);
    y_offset = png_get_y_offset_inches(png_ptr, info_ptr);

   (Each of these returns 0 [signifying "unknown" if both
       x and y are 0] if the data is not present or if the
       chunk is present but the unit is the pixel)

For more information, see the png_info definition in png.h and the
PNG specification for chunk contents.  Be careful with trusting
rowbytes, as some of the transformations could increase the space
needed to hold a row (expand, filler, gray_to_rgb, etc.).
See png_read_update_info(), below.

A quick word about text_ptr and num_text.  PNG stores comments in
keyword/text pairs, one pair per chunk, with no limit on the number
of text chunks, and a 2^31 byte limit on their size.  While there are
suggested keywords, there is no requirement to restrict the use to these
strings.  It is strongly suggested that keywords and text be sensible
to humans (that's the point), so don't use abbreviations.  Non-printing
symbols are not allowed.  See the PNG specification for more details.
There is also no requirement to have text after the keyword.

Keywords should be limited to 79 Latin-1 characters without leading or
trailing spaces, but non-consecutive spaces are allowed within the
keyword.  It is possible to have the same keyword any number of times.
The text_ptr is an array of png_text structures, each holding a
pointer to a language string, a pointer to a keyword and a pointer to
a text string.  The text string, language code, and translated
keyword may be empty or NULL pointers.  The keyword/text
pairs are put into the array in the order that they are received.
However, some or all of the text chunks may be after the image, so, to
make sure you have read all the text chunks, don't mess with these
until after you read the stuff after the image.  This will be
mentioned again below in the discussion that goes with png_read_end().

Input transformations

After you've read the header information, you can set up the library
to handle any special transformations of the image data.  The various
ways to transform the data will be described in the order that they
should occur.  This is important, as some of these change the color
type and/or bit depth of the data, and some others only work on
certain color types and bit depths.  Even though each transformation
checks to see if it has data that it can do something with, you should
make sure to only enable a transformation if it will be valid for the
data.  For example, don't swap red and blue on grayscale data.

The colors used for the background and transparency values should be
supplied in the same format/depth as the current image data.  They
are stored in the same format/depth as the image data in a bKGD or tRNS
chunk, so this is what libpng expects for this data.  The colors are
transformed to keep in sync with the image data when an application
calls the png_read_update_info() routine (see below).

Data will be decoded into the supplied row buffers packed into bytes
unless the library has been told to transform it into another format.
For example, 4 bit/pixel paletted or grayscale data will be returned
2 pixels/byte with the leftmost pixel in the high-order bits of the
byte, unless png_set_packing() is called.  8-bit RGB data will be stored
in RGB RGB RGB format unless png_set_filler() or png_set_add_alpha()
is called to insert filler bytes, either before or after each RGB triplet.
16-bit RGB data will be returned RRGGBB RRGGBB, with the most significant
byte of the color value first, unless png_set_strip_16() is called to
transform it to regular RGB RGB triplets, or png_set_filler() or
png_set_add alpha() is called to insert filler bytes, either before or
after each RRGGBB triplet.  Similarly, 8-bit or 16-bit grayscale data can
be modified with
png_set_filler(), png_set_add_alpha(), or png_set_strip_16().

The following code transforms grayscale images of less than 8 to 8 bits,
changes paletted images to RGB, and adds a full alpha channel if there is
transparency information in a tRNS chunk.  This is most useful on
grayscale images with bit depths of 2 or 4 or if there is a multiple-image
viewing application that wishes to treat all images in the same way.

    if (color_type == PNG_COLOR_TYPE_PALETTE)
        png_set_palette_to_rgb(png_ptr);

    if (color_type == PNG_COLOR_TYPE_GRAY &&
        bit_depth < 8) png_set_expand_gray_1_2_4_to_8(png_ptr);

    if (png_get_valid(png_ptr, info_ptr,
        PNG_INFO_tRNS)) png_set_tRNS_to_alpha(png_ptr);

These three functions are actually aliases for png_set_expand(), added
in libpng version 1.0.4, with the function names expanded to improve code
readability.  In some future version they may actually do different
things.

As of libpng version 1.2.9, png_set_expand_gray_1_2_4_to_8() was
added.  It expands the sample depth without changing tRNS to alpha.

PNG can have files with 16 bits per channel.  If you only can handle
8 bits per channel, this will strip the pixels down to 8 bit.

    if (bit_depth == 16)
        png_set_strip_16(png_ptr);

If, for some reason, you don't need the alpha channel on an image,
and you want to remove it rather than combining it with the background
(but the image author certainly had in mind that you *would* combine
it with the background, so that's what you should probably do):

    if (color_type & PNG_COLOR_MASK_ALPHA)
        png_set_strip_alpha(png_ptr);

In PNG files, the alpha channel in an image
is the level of opacity.  If you need the alpha channel in an image to
be the level of transparency instead of opacity, you can invert the
alpha channel (or the tRNS chunk data) after it's read, so that 0 is
fully opaque and 255 (in 8-bit or paletted images) or 65535 (in 16-bit
images) is fully transparent, with

    png_set_invert_alpha(png_ptr);

PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as
they can, resulting in, for example, 8 pixels per byte for 1 bit
files.  This code expands to 1 pixel per byte without changing the
values of the pixels:

    if (bit_depth < 8)
        png_set_packing(png_ptr);

PNG files have possible bit depths of 1, 2, 4, 8, and 16.  All pixels
stored in a PNG image have been "scaled" or "shifted" up to the next
higher possible bit depth (e.g. from 5 bits/sample in the range [0,31] to
8 bits/sample in the range [0, 255]).  However, it is also possible to
convert the PNG pixel data back to the original bit depth of the image.
This call reduces the pixels back down to the original bit depth:

    png_color_8p sig_bit;

    if (png_get_sBIT(png_ptr, info_ptr, &sig_bit))
        png_set_shift(png_ptr, sig_bit);

PNG files store 3-color pixels in red, green, blue order.  This code
changes the storage of the pixels to blue, green, red:

    if (color_type == PNG_COLOR_TYPE_RGB ||
        color_type == PNG_COLOR_TYPE_RGB_ALPHA)
        png_set_bgr(png_ptr);

PNG files store RGB pixels packed into 3 or 6 bytes. This code expands them
into 4 or 8 bytes for windowing systems that need them in this format:

    if (color_type == PNG_COLOR_TYPE_RGB)
        png_set_filler(png_ptr, filler, PNG_FILLER_BEFORE);

where "filler" is the 8 or 16-bit number to fill with, and the location is
either PNG_FILLER_BEFORE or PNG_FILLER_AFTER, depending upon whether
you want the filler before the RGB or after.  This transformation
does not affect images that already have full alpha channels.  To add an
opaque alpha channel, use filler=0xff or 0xffff and PNG_FILLER_AFTER which
will generate RGBA pixels.

Note that png_set_filler() does not change the color type.  If you want
to do that, you can add a true alpha channel with

    if (color_type == PNG_COLOR_TYPE_RGB ||
           color_type == PNG_COLOR_TYPE_GRAY)
    png_set_add_alpha(png_ptr, filler, PNG_FILLER_AFTER);

where "filler" contains the alpha value to assign to each pixel.
This function was added in libpng-1.2.7.

If you are reading an image with an alpha channel, and you need the
data as ARGB instead of the normal PNG format RGBA:

    if (color_type == PNG_COLOR_TYPE_RGB_ALPHA)
        png_set_swap_alpha(png_ptr);

For some uses, you may want a grayscale image to be represented as
RGB.  This code will do that conversion:

    if (color_type == PNG_COLOR_TYPE_GRAY ||
        color_type == PNG_COLOR_TYPE_GRAY_ALPHA)
          png_set_gray_to_rgb(png_ptr);

Conversely, you can convert an RGB or RGBA image to grayscale or grayscale
with alpha.

    if (color_type == PNG_COLOR_TYPE_RGB ||
        color_type == PNG_COLOR_TYPE_RGB_ALPHA)
          png_set_rgb_to_gray_fixed(png_ptr, error_action,
             int red_weight, int green_weight);

    error_action = 1: silently do the conversion
    error_action = 2: issue a warning if the original
                      image has any pixel where
                      red != green or red != blue
    error_action = 3: issue an error and abort the
                      conversion if the original
                      image has any pixel where
                      red != green or red != blue

    red_weight:       weight of red component times 100000
    green_weight:     weight of green component times 100000
                      If either weight is negative, default
                      weights (21268, 71514) are used.

If you have set error_action = 1 or 2, you can
later check whether the image really was gray, after processing
the image rows, with the png_get_rgb_to_gray_status(png_ptr) function.
It will return a png_byte that is zero if the image was gray or
1 if there were any non-gray pixels.  bKGD and sBIT data
will be silently converted to grayscale, using the green channel
data, regardless of the error_action setting.

With red_weight+green_weight<=100000,
the normalized graylevel is computed:

    int rw = red_weight * 65536;
    int gw = green_weight * 65536;
    int bw = 65536 - (rw + gw);
    gray = (rw*red + gw*green + bw*blue)/65536;

The default values approximate those recommended in the Charles
Poynton's Color FAQ, <http://www.inforamp.net/~poynton/>
Copyright (c) 1998-01-04 Charles Poynton <poynton at inforamp.net>

    Y = 0.212671 * R + 0.715160 * G + 0.072169 * B

Libpng approximates this with

    Y = 0.21268 * R    + 0.7151 * G    + 0.07217 * B

which can be expressed with integers as

    Y = (6969 * R + 23434 * G + 2365 * B)/32768

The calculation is done in a linear colorspace, if the image gamma
is known.

If you have a grayscale and you are using png_set_expand_depth(),
png_set_expand(), or png_set_gray_to_rgb to change to truecolor or to
a higher bit-depth, you must either supply the background color as a gray
value at the original file bit-depth (need_expand = 1) or else supply the
background color as an RGB triplet at the final, expanded bit depth
(need_expand = 0).  Similarly, if you are reading a paletted image, you
must either supply the background color as a palette index (need_expand = 1)
or as an RGB triplet that may or may not be in the palette (need_expand = 0).

    png_color_16 my_background;
    png_color_16p image_background;

    if (png_get_bKGD(png_ptr, info_ptr, &image_background))
        png_set_background(png_ptr, image_background,
          PNG_BACKGROUND_GAMMA_FILE, 1, 1.0);
    else
        png_set_background(png_ptr, &my_background,
          PNG_BACKGROUND_GAMMA_SCREEN, 0, 1.0);

The png_set_background() function tells libpng to composite images
with alpha or simple transparency against the supplied background
color.  If the PNG file contains a bKGD chunk (PNG_INFO_bKGD valid),
you may use this color, or supply another color more suitable for
the current display (e.g., the background color from a web page).  You
need to tell libpng whether the color is in the gamma space of the
display (PNG_BACKGROUND_GAMMA_SCREEN for colors you supply), the file
(PNG_BACKGROUND_GAMMA_FILE for colors from the bKGD chunk), or one
that is neither of these gammas (PNG_BACKGROUND_GAMMA_UNIQUE - I don't
know why anyone would use this, but it's here).

To properly display PNG images on any kind of system, the application needs
to know what the display gamma is.  Ideally, the user will know this, and
the application will allow them to set it.  One method of allowing the user
to set the display gamma separately for each system is to check for a
SCREEN_GAMMA or DISPLAY_GAMMA environment variable, which will hopefully be
correctly set.

Note that display_gamma is the overall gamma correction required to produce
pleasing results, which depends on the lighting conditions in the surrounding
environment.  In a dim or brightly lit room, no compensation other than
the physical gamma exponent of the monitor is needed, while in a dark room
a slightly smaller exponent is better.

   double gamma, screen_gamma;

   if (/* We have a user-defined screen
       gamma value */)
   {
      screen_gamma = user_defined_screen_gamma;
   }
   /* One way that applications can share the same
      screen gamma value */
   else if ((gamma_str = getenv("SCREEN_GAMMA"))
      != NULL)
   {
      screen_gamma = (double)atof(gamma_str);
   }
   /* If we don't have another value */
   else
   {
      screen_gamma = 2.2; /* A good guess for a
           PC monitor in a bright office or a dim room */
      screen_gamma = 2.0; /* A good guess for a
           PC monitor in a dark room */
      screen_gamma = 1.7 or 1.0;  /* A good
           guess for Mac systems */
   }

The png_set_gamma() function handles gamma transformations of the data.
Pass both the file gamma and the current screen_gamma.  If the file does
not have a gamma value, you can pass one anyway if you have an idea what
it is (usually 0.45455 is a good guess for GIF images on PCs).  Note
that file gammas are inverted from screen gammas.  See the discussions
on gamma in the PNG specification for an excellent description of what
gamma is, and why all applications should support it.  It is strongly
recommended that PNG viewers support gamma correction.

   if (png_get_gAMA(png_ptr, info_ptr, &gamma))
      png_set_gamma(png_ptr, screen_gamma, gamma);
   else
      png_set_gamma(png_ptr, screen_gamma, 0.45455);

If you need to reduce an RGB file to a paletted file, or if a paletted
file has more entries then will fit on your screen, png_set_dither()
will do that.  Note that this is a simple match dither that merely
finds the closest color available.  This should work fairly well with
optimized palettes, and fairly badly with linear color cubes.  If you
pass a palette that is larger then maximum_colors, the file will
reduce the number of colors in the palette so it will fit into
maximum_colors.  If there is a histogram, it will use it to make
more intelligent choices when reducing the palette.  If there is no
histogram, it may not do as good a job.

   if (color_type & PNG_COLOR_MASK_COLOR)
   {
      if (png_get_valid(png_ptr, info_ptr,
         PNG_INFO_PLTE))
      {
         png_uint_16p histogram = NULL;

         png_get_hIST(png_ptr, info_ptr,
            &histogram);
         png_set_dither(png_ptr, palette, num_palette,
            max_screen_colors, histogram, 1);
      }
      else
      {
         png_color std_color_cube[MAX_SCREEN_COLORS] =
            { ... colors ... };

         png_set_dither(png_ptr, std_color_cube,
            MAX_SCREEN_COLORS, MAX_SCREEN_COLORS,
            NULL,0);
      }
   }

PNG files describe monochrome as black being zero and white being one.
The following code will reverse this (make black be one and white be
zero):

   if (bit_depth == 1 && color_type == PNG_COLOR_TYPE_GRAY)
      png_set_invert_mono(png_ptr);

This function can also be used to invert grayscale and gray-alpha images:

   if (color_type == PNG_COLOR_TYPE_GRAY ||
        color_type == PNG_COLOR_TYPE_GRAY_ALPHA)
      png_set_invert_mono(png_ptr);

PNG files store 16 bit pixels in network byte order (big-endian,
ie. most significant bits first).  This code changes the storage to the
other way (little-endian, i.e. least significant bits first, the
way PCs store them):

    if (bit_depth == 16)
        png_set_swap(png_ptr);

If you are using packed-pixel images (1, 2, or 4 bits/pixel), and you
need to change the order the pixels are packed into bytes, you can use:

    if (bit_depth < 8)
       png_set_packswap(png_ptr);

Finally, you can write your own transformation function if none of
the existing ones meets your needs.  This is done by setting a callback
with

    png_set_read_user_transform_fn(png_ptr,
       read_transform_fn);

You must supply the function

    void read_transform_fn(png_ptr ptr, row_info_ptr
       row_info, png_bytep data)

See pngtest.c for a working example.  Your function will be called
after all of the other transformations have been processed.

You can also set up a pointer to a user structure for use by your
callback function, and you can inform libpng that your transform
function will change the number of channels or bit depth with the
function

    png_set_user_transform_info(png_ptr, user_ptr,
       user_depth, user_channels);

The user's application, not libpng, is responsible for allocating and
freeing any memory required for the user structure.

You can retrieve the pointer via the function
png_get_user_transform_ptr().  For example:

    voidp read_user_transform_ptr =
       png_get_user_transform_ptr(png_ptr);

The last thing to handle is interlacing; this is covered in detail below,
but you must call the function here if you want libpng to handle expansion
of the interlaced image.

    number_of_passes = png_set_interlace_handling(png_ptr);

After setting the transformations, libpng can update your png_info
structure to reflect any transformations you've requested with this
call.  This is most useful to update the info structure's rowbytes
field so you can use it to allocate your image memory.  This function
will also update your palette with the correct screen_gamma and
background if these have been given with the calls above.

    png_read_update_info(png_ptr, info_ptr);

After you call png_read_update_info(), you can allocate any
memory you need to hold the image.  The row data is simply
raw byte data for all forms of images.  As the actual allocation
varies among applications, no example will be given.  If you
are allocating one large chunk, you will need to build an
array of pointers to each row, as it will be needed for some
of the functions below.

Reading image data

After you've allocated memory, you can read the image data.
The simplest way to do this is in one function call.  If you are
allocating enough memory to hold the whole image, you can just
call png_read_image() and libpng will read in all the image data
and put it in the memory area supplied.  You will need to pass in
an array of pointers to each row.

This function automatically handles interlacing, so you don't need
to call png_set_interlace_handling() or call this function multiple
times, or any of that other stuff necessary with png_read_rows().

   png_read_image(png_ptr, row_pointers);

where row_pointers is:

   png_bytep row_pointers[height];

You can point to void or char or whatever you use for pixels.

If you don't want to read in the whole image at once, you can
use png_read_rows() instead.  If there is no interlacing (check
interlace_type == PNG_INTERLACE_NONE), this is simple:

    png_read_rows(png_ptr, row_pointers, NULL,
       number_of_rows);

where row_pointers is the same as in the png_read_image() call.

If you are doing this just one row at a time, you can do this with
a single row_pointer instead of an array of row_pointers:

    png_bytep row_pointer = row;
    png_read_row(png_ptr, row_pointer, NULL);

If the file is interlaced (interlace_type != 0 in the IHDR chunk), things
get somewhat harder.  The only current (PNG Specification version 1.2)
interlacing type for PNG is (interlace_type == PNG_INTERLACE_ADAM7)
is a somewhat complicated 2D interlace scheme, known as Adam7, that
breaks down an image into seven smaller images of varying size, based
on an 8x8 grid.

libpng can fill out those images or it can give them to you "as is".
If you want them filled out, there are two ways to do that.  The one
mentioned in the PNG specification is to expand each pixel to cover
those pixels that have not been read yet (the "rectangle" method).
This results in a blocky image for the first pass, which gradually
smooths out as more pixels are read.  The other method is the "sparkle"
method, where pixels are drawn only in their final locations, with the
rest of the image remaining whatever colors they were initialized to
before the start of the read.  The first method usually looks better,
but tends to be slower, as there are more pixels to put in the rows.

If you don't want libpng to handle the interlacing details, just call
png_read_rows() seven times to read in all seven images.  Each of the
images is a valid image by itself, or they can all be combined on an
8x8 grid to form a single image (although if you intend to combine them
you would be far better off using the libpng interlace handling).

The first pass will return an image 1/8 as wide as the entire image
(every 8th column starting in column 0) and 1/8 as high as the original
(every 8th row starting in row 0), the second will be 1/8 as wide
(starting in column 4) and 1/8 as high (also starting in row 0).  The
third pass will be 1/4 as wide (every 4th pixel starting in column 0) and
1/8 as high (every 8th row starting in row 4), and the fourth pass will
be 1/4 as wide and 1/4 as high (every 4th column starting in column 2,
and every 4th row starting in row 0).  The fifth pass will return an
image 1/2 as wide, and 1/4 as high (starting at column 0 and row 2),
while the sixth pass will be 1/2 as wide and 1/2 as high as the original
(starting in column 1 and row 0).  The seventh and final pass will be as
wide as the original, and 1/2 as high, containing all of the odd
numbered scanlines.  Phew!

If you want libpng to expand the images, call this before calling
png_start_read_image() or png_read_update_info():

    if (interlace_type == PNG_INTERLACE_ADAM7)
        number_of_passes
           = png_set_interlace_handling(png_ptr);

This will return the number of passes needed.  Currently, this
is seven, but may change if another interlace type is added.
This function can be called even if the file is not interlaced,
where it will return one pass.

If you are not going to display the image after each pass, but are
going to wait until the entire image is read in, use the sparkle