view release on metacpan or  search on metacpan

src/Source/LibPNG/libpng-manual.txt  view on Meta::CPAN

your png_jmpbuf(png_ptr).  If you read the file from different
routines, you will need to update the longjmp buffer 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);
    }

Pass (png_infopp)NULL instead of &end_info if you didn't create
an end_info structure.

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

You can #define PNG_ABORT() to a function that does something
more useful than abort(), as long as your function does not
return.

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

You can change the zlib compression buffer size to be used while
reading compressed data with

    png_set_compression_buffer_size(png_ptr, buffer_size);

where the default size is 8192 bytes.  Note that the buffer size
is changed immediately and the buffer is reallocated immediately,
instead of setting a flag to be acted upon later.

If you want CRC errors to be handled in a different manner than
the default, use

    png_set_crc_action(png_ptr, crit_action, ancil_action);

The values for png_set_crc_action() say how libpng is to handle CRC errors in
ancillary and critical chunks, and whether to use the data contained
therein.  Note that it is impossible to "discard" data in a critical
chunk.

Choices for (int) crit_action are
   PNG_CRC_DEFAULT      0  error/quit
   PNG_CRC_ERROR_QUIT   1  error/quit
   PNG_CRC_WARN_USE     3  warn/use data
   PNG_CRC_QUIET_USE    4  quiet/use data
   PNG_CRC_NO_CHANGE    5  use the current value

Choices for (int) ancil_action are
   PNG_CRC_DEFAULT      0  error/quit
   PNG_CRC_ERROR_QUIT   1  error/quit
   PNG_CRC_WARN_DISCARD 2  warn/discard data
   PNG_CRC_WARN_USE     3  warn/use data
   PNG_CRC_QUIET_USE    4  quiet/use data
   PNG_CRC_NO_CHANGE    5  use the current value

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_structp png_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);