michael@0: libpng-manual.txt - A description on how to use and modify libpng
michael@0: 
michael@0:  libpng version 1.6.9 - February 6, 2014
michael@0:  Updated and distributed by Glenn Randers-Pehrson
michael@0:  <glennrp at users.sourceforge.net>
michael@0:  Copyright (c) 1998-2014 Glenn Randers-Pehrson
michael@0: 
michael@0:  This document is released under the libpng license.
michael@0:  For conditions of distribution and use, see the disclaimer
michael@0:  and license in png.h
michael@0: 
michael@0:  Based on:
michael@0: 
michael@0:  libpng versions 0.97, January 1998, through 1.6.9 - February 6, 2014
michael@0:  Updated and distributed by Glenn Randers-Pehrson
michael@0:  Copyright (c) 1998-2014 Glenn Randers-Pehrson
michael@0: 
michael@0:  libpng 1.0 beta 6  version 0.96 May 28, 1997
michael@0:  Updated and distributed by Andreas Dilger
michael@0:  Copyright (c) 1996, 1997 Andreas Dilger
michael@0: 
michael@0:  libpng 1.0 beta 2 - version 0.88  January 26, 1996
michael@0:  For conditions of distribution and use, see copyright
michael@0:  notice in png.h. Copyright (c) 1995, 1996 Guy Eric
michael@0:  Schalnat, Group 42, Inc.
michael@0: 
michael@0:  Updated/rewritten per request in the libpng FAQ
michael@0:  Copyright (c) 1995, 1996 Frank J. T. Wojcik
michael@0:  December 18, 1995 & January 20, 1996
michael@0: 
michael@0:  TABLE OF CONTENTS
michael@0: 
michael@0:     I. Introduction
michael@0:    II. Structures
michael@0:   III. Reading
michael@0:    IV. Writing
michael@0:     V. Simplified API
michael@0:    VI. Modifying/Customizing libpng
michael@0:   VII. MNG support
michael@0:  VIII. Changes to Libpng from version 0.88
michael@0:    IX. Changes to Libpng from version 1.0.x to 1.2.x
michael@0:     X. Changes to Libpng from version 1.0.x/1.2.x to 1.4.x
michael@0:    XI. Changes to Libpng from version 1.4.x to 1.5.x
michael@0:   XII. Changes to Libpng from version 1.5.x to 1.6.x
michael@0:  XIII. Detecting libpng
michael@0:   XIV. Source code repository
michael@0:    XV. Coding style
michael@0:   XVI. Y2K Compliance in libpng
michael@0: 
michael@0: I. Introduction
michael@0: 
michael@0: This file describes how to use and modify the PNG reference library
michael@0: (known as libpng) for your own use.  In addition to this
michael@0: file, example.c is a good starting point for using the library, as
michael@0: it is heavily commented and should include everything most people
michael@0: will need.  We assume that libpng is already installed; see the
michael@0: INSTALL file for instructions on how to install libpng.
michael@0: 
michael@0: For examples of libpng usage, see the files "example.c", "pngtest.c",
michael@0: and the files in the "contrib" directory, all of which are included in
michael@0: the libpng distribution.
michael@0: 
michael@0: Libpng was written as a companion to the PNG specification, as a way
michael@0: of reducing the amount of time and effort it takes to support the PNG
michael@0: file format in application programs.
michael@0: 
michael@0: The PNG specification (second edition), November 2003, is available as
michael@0: a W3C Recommendation and as an ISO Standard (ISO/IEC 15948:2004 (E)) at
michael@0: <http://www.w3.org/TR/2003/REC-PNG-20031110/
michael@0: The W3C and ISO documents have identical technical content.
michael@0: 
michael@0: The PNG-1.2 specification is available at
michael@0: <http://www.libpng.org/pub/png/documents/>.  It is technically equivalent
michael@0: to the PNG specification (second edition) but has some additional material.
michael@0: 
michael@0: The PNG-1.0 specification is available
michael@0: as RFC 2083 <http://www.libpng.org/pub/png/documents/> and as a
michael@0: W3C Recommendation <http://www.w3.org/TR/REC.png.html>.
michael@0: 
michael@0: Some additional chunks are described in the special-purpose public chunks
michael@0: documents at <http://www.libpng.org/pub/png/documents/>.
michael@0: 
michael@0: Other information
michael@0: about PNG, and the latest version of libpng, can be found at the PNG home
michael@0: page, <http://www.libpng.org/pub/png/>.
michael@0: 
michael@0: Most users will not have to modify the library significantly; advanced
michael@0: users may want to modify it more.  All attempts were made to make it as
michael@0: complete as possible, while keeping the code easy to understand.
michael@0: Currently, this library only supports C.  Support for other languages
michael@0: is being considered.
michael@0: 
michael@0: Libpng has been designed to handle multiple sessions at one time,
michael@0: to be easily modifiable, to be portable to the vast majority of
michael@0: machines (ANSI, K&R, 16-, 32-, and 64-bit) available, and to be easy
michael@0: to use.  The ultimate goal of libpng is to promote the acceptance of
michael@0: the PNG file format in whatever way possible.  While there is still
michael@0: work to be done (see the TODO file), libpng should cover the
michael@0: majority of the needs of its users.
michael@0: 
michael@0: Libpng uses zlib for its compression and decompression of PNG files.
michael@0: Further information about zlib, and the latest version of zlib, can
michael@0: be found at the zlib home page, <http://www.info-zip.org/pub/infozip/zlib/>.
michael@0: The zlib compression utility is a general purpose utility that is
michael@0: useful for more than PNG files, and can be used without libpng.
michael@0: See the documentation delivered with zlib for more details.
michael@0: You can usually find the source files for the zlib utility wherever you
michael@0: find the libpng source files.
michael@0: 
michael@0: Libpng is thread safe, provided the threads are using different
michael@0: instances of the structures.  Each thread should have its own
michael@0: png_struct and png_info instances, and thus its own image.
michael@0: Libpng does not protect itself against two threads using the
michael@0: same instance of a structure.
michael@0: 
michael@0: II. Structures
michael@0: 
michael@0: There are two main structures that are important to libpng, png_struct
michael@0: and png_info.  Both are internal structures that are no longer exposed
michael@0: in the libpng interface (as of libpng 1.5.0).
michael@0: 
michael@0: The png_info structure is designed to provide information about the
michael@0: PNG file.  At one time, the fields of png_info were intended to be
michael@0: directly accessible to the user.  However, this tended to cause problems
michael@0: with applications using dynamically loaded libraries, and as a result
michael@0: a set of interface functions for png_info (the png_get_*() and png_set_*()
michael@0: functions) was developed, and direct access to the png_info fields was
michael@0: deprecated..
michael@0: 
michael@0: The png_struct structure is the object used by the library to decode a
michael@0: single image.  As of 1.5.0 this structure is also not exposed.
michael@0: 
michael@0: Almost all libpng APIs require a pointer to a png_struct as the first argument.
michael@0: Many (in particular the png_set and png_get APIs) also require a pointer
michael@0: to png_info as the second argument.  Some application visible macros
michael@0: defined in png.h designed for basic data access (reading and writing
michael@0: integers in the PNG format) don't take a png_info pointer, but it's almost
michael@0: always safe to assume that a (png_struct*) has to be passed to call an API
michael@0: function.
michael@0: 
michael@0: You can have more than one png_info structure associated with an image,
michael@0: as illustrated in pngtest.c, one for information valid prior to the
michael@0: IDAT chunks and another (called "end_info" below) for things after them.
michael@0: 
michael@0: The png.h header file is an invaluable reference for programming with libpng.
michael@0: And while I'm on the topic, make sure you include the libpng header file:
michael@0: 
michael@0: #include <png.h>
michael@0: 
michael@0: and also (as of libpng-1.5.0) the zlib header file, if you need it:
michael@0: 
michael@0: #include <zlib.h>
michael@0: 
michael@0: Types
michael@0: 
michael@0: The png.h header file defines a number of integral types used by the
michael@0: APIs.  Most of these are fairly obvious; for example types corresponding
michael@0: to integers of particular sizes and types for passing color values.
michael@0: 
michael@0: One exception is how non-integral numbers are handled.  For application
michael@0: convenience most APIs that take such numbers have C (double) arguments;
michael@0: however, internally PNG, and libpng, use 32 bit signed integers and encode
michael@0: the value by multiplying by 100,000.  As of libpng 1.5.0 a convenience
michael@0: macro PNG_FP_1 is defined in png.h along with a type (png_fixed_point)
michael@0: which is simply (png_int_32).
michael@0: 
michael@0: All APIs that take (double) arguments also have a matching API that
michael@0: takes the corresponding fixed point integer arguments.  The fixed point
michael@0: API has the same name as the floating point one with "_fixed" appended.
michael@0: The actual range of values permitted in the APIs is frequently less than
michael@0: the full range of (png_fixed_point) (-21474 to +21474).  When APIs require
michael@0: a non-negative argument the type is recorded as png_uint_32 above.  Consult
michael@0: the header file and the text below for more information.
michael@0: 
michael@0: Special care must be take with sCAL chunk handling because the chunk itself
michael@0: uses non-integral values encoded as strings containing decimal floating point
michael@0: numbers.  See the comments in the header file.
michael@0: 
michael@0: Configuration
michael@0: 
michael@0: The main header file function declarations are frequently protected by C
michael@0: preprocessing directives of the form:
michael@0: 
michael@0:     #ifdef PNG_feature_SUPPORTED
michael@0:     declare-function
michael@0:     #endif
michael@0:     ...
michael@0:     #ifdef PNG_feature_SUPPORTED
michael@0:     use-function
michael@0:     #endif
michael@0: 
michael@0: The library can be built without support for these APIs, although a
michael@0: standard build will have all implemented APIs.  Application programs
michael@0: should check the feature macros before using an API for maximum
michael@0: portability.  From libpng 1.5.0 the feature macros set during the build
michael@0: of libpng are recorded in the header file "pnglibconf.h" and this file
michael@0: is always included by png.h.
michael@0: 
michael@0: If you don't need to change the library configuration from the default, skip to
michael@0: the next section ("Reading").
michael@0: 
michael@0: Notice that some of the makefiles in the 'scripts' directory and (in 1.5.0) all
michael@0: of the build project files in the 'projects' directory simply copy
michael@0: scripts/pnglibconf.h.prebuilt to pnglibconf.h.  This means that these build
michael@0: systems do not permit easy auto-configuration of the library - they only
michael@0: support the default configuration.
michael@0: 
michael@0: The easiest way to make minor changes to the libpng configuration when
michael@0: auto-configuration is supported is to add definitions to the command line
michael@0: using (typically) CPPFLAGS.  For example:
michael@0: 
michael@0: CPPFLAGS=-DPNG_NO_FLOATING_ARITHMETIC
michael@0: 
michael@0: will change the internal libpng math implementation for gamma correction and
michael@0: other arithmetic calculations to fixed point, avoiding the need for fast
michael@0: floating point support.  The result can be seen in the generated pnglibconf.h -
michael@0: make sure it contains the changed feature macro setting.
michael@0: 
michael@0: If you need to make more extensive configuration changes - more than one or two
michael@0: feature macro settings - you can either add -DPNG_USER_CONFIG to the build
michael@0: command line and put a list of feature macro settings in pngusr.h or you can set
michael@0: DFA_XTRA (a makefile variable) to a file containing the same information in the
michael@0: form of 'option' settings.
michael@0: 
michael@0: A. Changing pnglibconf.h
michael@0: 
michael@0: A variety of methods exist to build libpng.  Not all of these support
michael@0: reconfiguration of pnglibconf.h.  To reconfigure pnglibconf.h it must either be
michael@0: rebuilt from scripts/pnglibconf.dfa using awk or it must be edited by hand.
michael@0: 
michael@0: Hand editing is achieved by copying scripts/pnglibconf.h.prebuilt to
michael@0: pnglibconf.h and changing the lines defining the supported features, paying
michael@0: very close attention to the 'option' information in scripts/pnglibconf.dfa
michael@0: that describes those features and their requirements.  This is easy to get
michael@0: wrong.
michael@0: 
michael@0: B. Configuration using DFA_XTRA
michael@0: 
michael@0: Rebuilding from pnglibconf.dfa is easy if a functioning 'awk', or a later
michael@0: variant such as 'nawk' or 'gawk', is available.  The configure build will
michael@0: automatically find an appropriate awk and build pnglibconf.h.
michael@0: The scripts/pnglibconf.mak file contains a set of make rules for doing the
michael@0: same thing if configure is not used, and many of the makefiles in the scripts
michael@0: directory use this approach.
michael@0: 
michael@0: When rebuilding simply write a new file containing changed options and set
michael@0: DFA_XTRA to the name of this file.  This causes the build to append the new file
michael@0: to the end of scripts/pnglibconf.dfa.  The pngusr.dfa file should contain lines
michael@0: of the following forms:
michael@0: 
michael@0: everything = off
michael@0: 
michael@0: This turns all optional features off.  Include it at the start of pngusr.dfa to
michael@0: make it easier to build a minimal configuration.  You will need to turn at least
michael@0: some features on afterward to enable either reading or writing code, or both.
michael@0: 
michael@0: option feature on
michael@0: option feature off
michael@0: 
michael@0: Enable or disable a single feature.  This will automatically enable other
michael@0: features required by a feature that is turned on or disable other features that
michael@0: require a feature which is turned off.  Conflicting settings will cause an error
michael@0: message to be emitted by awk.
michael@0: 
michael@0: setting feature default value
michael@0: 
michael@0: Changes the default value of setting 'feature' to 'value'.  There are a small
michael@0: number of settings listed at the top of pnglibconf.h, they are documented in the
michael@0: source code.  Most of these values have performance implications for the library
michael@0: but most of them have no visible effect on the API.  Some can also be overridden
michael@0: from the API.
michael@0: 
michael@0: This method of building a customized pnglibconf.h is illustrated in
michael@0: contrib/pngminim/*.  See the "$(PNGCONF):" target in the makefile and
michael@0: pngusr.dfa in these directories.
michael@0: 
michael@0: C. Configuration using PNG_USR_CONFIG
michael@0: 
michael@0: If -DPNG_USR_CONFIG is added to the CFLAGS when pnglibconf.h is built the file
michael@0: pngusr.h will automatically be included before the options in
michael@0: scripts/pnglibconf.dfa are processed.  Your pngusr.h file should contain only
michael@0: macro definitions turning features on or off or setting settings.
michael@0: 
michael@0: Apart from the global setting "everything = off" all the options listed above
michael@0: can be set using macros in pngusr.h:
michael@0: 
michael@0: #define PNG_feature_SUPPORTED
michael@0: 
michael@0: is equivalent to:
michael@0: 
michael@0: option feature on
michael@0: 
michael@0: #define PNG_NO_feature
michael@0: 
michael@0: is equivalent to:
michael@0: 
michael@0: option feature off
michael@0: 
michael@0: #define PNG_feature value
michael@0: 
michael@0: is equivalent to:
michael@0: 
michael@0: setting feature default value
michael@0: 
michael@0: Notice that in both cases, pngusr.dfa and pngusr.h, the contents of the
michael@0: pngusr file you supply override the contents of scripts/pnglibconf.dfa
michael@0: 
michael@0: If confusing or incomprehensible behavior results it is possible to
michael@0: examine the intermediate file pnglibconf.dfn to find the full set of
michael@0: dependency information for each setting and option.  Simply locate the
michael@0: feature in the file and read the C comments that precede it.
michael@0: 
michael@0: This method is also illustrated in the contrib/pngminim/* makefiles and
michael@0: pngusr.h.
michael@0: 
michael@0: III. Reading
michael@0: 
michael@0: We'll now walk you through the possible functions to call when reading
michael@0: in a PNG file sequentially, briefly explaining the syntax and purpose
michael@0: of each one.  See example.c and png.h for more detail.  While
michael@0: progressive reading is covered in the next section, you will still
michael@0: need some of the functions discussed in this section to read a PNG
michael@0: file.
michael@0: 
michael@0: Setup
michael@0: 
michael@0: You will want to do the I/O initialization(*) before you get into libpng,
michael@0: so if it doesn't work, you don't have much to undo.  Of course, you
michael@0: will also want to insure that you are, in fact, dealing with a PNG
michael@0: file.  Libpng provides a simple check to see if a file is a PNG file.
michael@0: To use it, pass in the first 1 to 8 bytes of the file to the function
michael@0: png_sig_cmp(), and it will return 0 (false) if the bytes match the
michael@0: corresponding bytes of the PNG signature, or nonzero (true) otherwise.
michael@0: Of course, the more bytes you pass in, the greater the accuracy of the
michael@0: prediction.
michael@0: 
michael@0: If you are intending to keep the file pointer open for use in libpng,
michael@0: you must ensure you don't read more than 8 bytes from the beginning
michael@0: of the file, and you also have to make a call to png_set_sig_bytes_read()
michael@0: with the number of bytes you read from the beginning.  Libpng will
michael@0: then only check the bytes (if any) that your program didn't read.
michael@0: 
michael@0: (*): If you are not using the standard I/O functions, you will need
michael@0: to replace them with custom functions.  See the discussion under
michael@0: Customizing libpng.
michael@0: 
michael@0: 
michael@0:     FILE *fp = fopen(file_name, "rb");
michael@0:     if (!fp)
michael@0:     {
michael@0:        return (ERROR);
michael@0:     }
michael@0: 
michael@0:     fread(header, 1, number, fp);
michael@0:     is_png = !png_sig_cmp(header, 0, number);
michael@0: 
michael@0:     if (!is_png)
michael@0:     {
michael@0:        return (NOT_PNG);
michael@0:     }
michael@0: 
michael@0: 
michael@0: Next, png_struct and png_info need to be allocated and initialized.  In
michael@0: order to ensure that the size of these structures is correct even with a
michael@0: dynamically linked libpng, there are functions to initialize and
michael@0: allocate the structures.  We also pass the library version, optional
michael@0: pointers to error handling functions, and a pointer to a data struct for
michael@0: use by the error functions, if necessary (the pointer and functions can
michael@0: be NULL if the default error handlers are to be used).  See the section
michael@0: on Changes to Libpng below regarding the old initialization functions.
michael@0: The structure allocation functions quietly return NULL if they fail to
michael@0: create the structure, so your application should check for that.
michael@0: 
michael@0:     png_structp png_ptr = png_create_read_struct
michael@0:         (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
michael@0:         user_error_fn, user_warning_fn);
michael@0: 
michael@0:     if (!png_ptr)
michael@0:        return (ERROR);
michael@0: 
michael@0:     png_infop info_ptr = png_create_info_struct(png_ptr);
michael@0: 
michael@0:     if (!info_ptr)
michael@0:     {
michael@0:        png_destroy_read_struct(&png_ptr,
michael@0:            (png_infopp)NULL, (png_infopp)NULL);
michael@0:        return (ERROR);
michael@0:     }
michael@0: 
michael@0: If you want to use your own memory allocation routines,
michael@0: use a libpng that was built with PNG_USER_MEM_SUPPORTED defined, and use
michael@0: png_create_read_struct_2() instead of png_create_read_struct():
michael@0: 
michael@0:     png_structp png_ptr = png_create_read_struct_2
michael@0:         (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
michael@0:         user_error_fn, user_warning_fn, (png_voidp)
michael@0:         user_mem_ptr, user_malloc_fn, user_free_fn);
michael@0: 
michael@0: The error handling routines passed to png_create_read_struct()
michael@0: and the memory alloc/free routines passed to png_create_struct_2()
michael@0: are only necessary if you are not using the libpng supplied error
michael@0: handling and memory alloc/free functions.
michael@0: 
michael@0: When libpng encounters an error, it expects to longjmp back
michael@0: to your routine.  Therefore, you will need to call setjmp and pass
michael@0: your png_jmpbuf(png_ptr).  If you read the file from different
michael@0: routines, you will need to update the longjmp buffer every time you enter
michael@0: a new routine that will call a png_*() function.
michael@0: 
michael@0: See your documentation of setjmp/longjmp for your compiler for more
michael@0: information on setjmp/longjmp.  See the discussion on libpng error
michael@0: handling in the Customizing Libpng section below for more information
michael@0: on the libpng error handling.  If an error occurs, and libpng longjmp's
michael@0: back to your setjmp, you will want to call png_destroy_read_struct() to
michael@0: free any memory.
michael@0: 
michael@0:     if (setjmp(png_jmpbuf(png_ptr)))
michael@0:     {
michael@0:        png_destroy_read_struct(&png_ptr, &info_ptr,
michael@0:            &end_info);
michael@0:        fclose(fp);
michael@0:        return (ERROR);
michael@0:     }
michael@0: 
michael@0: Pass (png_infopp)NULL instead of &end_info if you didn't create
michael@0: an end_info structure.
michael@0: 
michael@0: If you would rather avoid the complexity of setjmp/longjmp issues,
michael@0: you can compile libpng with PNG_NO_SETJMP, in which case
michael@0: errors will result in a call to PNG_ABORT() which defaults to abort().
michael@0: 
michael@0: You can #define PNG_ABORT() to a function that does something
michael@0: more useful than abort(), as long as your function does not
michael@0: return.
michael@0: 
michael@0: Now you need to set up the input code.  The default for libpng is to
michael@0: use the C function fread().  If you use this, you will need to pass a
michael@0: valid FILE * in the function png_init_io().  Be sure that the file is
michael@0: opened in binary mode.  If you wish to handle reading data in another
michael@0: way, you need not call the png_init_io() function, but you must then
michael@0: implement the libpng I/O methods discussed in the Customizing Libpng
michael@0: section below.
michael@0: 
michael@0:     png_init_io(png_ptr, fp);
michael@0: 
michael@0: If you had previously opened the file and read any of the signature from
michael@0: the beginning in order to see if this was a PNG file, you need to let
michael@0: libpng know that there are some bytes missing from the start of the file.
michael@0: 
michael@0:     png_set_sig_bytes(png_ptr, number);
michael@0: 
michael@0: You can change the zlib compression buffer size to be used while
michael@0: reading compressed data with
michael@0: 
michael@0:     png_set_compression_buffer_size(png_ptr, buffer_size);
michael@0: 
michael@0: where the default size is 8192 bytes.  Note that the buffer size
michael@0: is changed immediately and the buffer is reallocated immediately,
michael@0: instead of setting a flag to be acted upon later.
michael@0: 
michael@0: If you want CRC errors to be handled in a different manner than
michael@0: the default, use
michael@0: 
michael@0:     png_set_crc_action(png_ptr, crit_action, ancil_action);
michael@0: 
michael@0: The values for png_set_crc_action() say how libpng is to handle CRC errors in
michael@0: ancillary and critical chunks, and whether to use the data contained
michael@0: therein.  Note that it is impossible to "discard" data in a critical
michael@0: chunk.
michael@0: 
michael@0: Choices for (int) crit_action are
michael@0:    PNG_CRC_DEFAULT      0  error/quit
michael@0:    PNG_CRC_ERROR_QUIT   1  error/quit
michael@0:    PNG_CRC_WARN_USE     3  warn/use data
michael@0:    PNG_CRC_QUIET_USE    4  quiet/use data
michael@0:    PNG_CRC_NO_CHANGE    5  use the current value
michael@0: 
michael@0: Choices for (int) ancil_action are
michael@0:    PNG_CRC_DEFAULT      0  error/quit
michael@0:    PNG_CRC_ERROR_QUIT   1  error/quit
michael@0:    PNG_CRC_WARN_DISCARD 2  warn/discard data
michael@0:    PNG_CRC_WARN_USE     3  warn/use data
michael@0:    PNG_CRC_QUIET_USE    4  quiet/use data
michael@0:    PNG_CRC_NO_CHANGE    5  use the current value
michael@0: 
michael@0: Setting up callback code
michael@0: 
michael@0: You can set up a callback function to handle any unknown chunks in the
michael@0: input stream. You must supply the function
michael@0: 
michael@0:     read_chunk_callback(png_structp png_ptr,
michael@0:          png_unknown_chunkp chunk);
michael@0:     {
michael@0:        /* The unknown chunk structure contains your
michael@0:           chunk data, along with similar data for any other
michael@0:           unknown chunks: */
michael@0: 
michael@0:            png_byte name[5];
michael@0:            png_byte *data;
michael@0:            png_size_t size;
michael@0: 
michael@0:        /* Note that libpng has already taken care of
michael@0:           the CRC handling */
michael@0: 
michael@0:        /* put your code here.  Search for your chunk in the
michael@0:           unknown chunk structure, process it, and return one
michael@0:           of the following: */
michael@0: 
michael@0:        return (-n); /* chunk had an error */
michael@0:        return (0); /* did not recognize */
michael@0:        return (n); /* success */
michael@0:     }
michael@0: 
michael@0: (You can give your function another name that you like instead of
michael@0: "read_chunk_callback")
michael@0: 
michael@0: To inform libpng about your function, use
michael@0: 
michael@0:     png_set_read_user_chunk_fn(png_ptr, user_chunk_ptr,
michael@0:         read_chunk_callback);
michael@0: 
michael@0: This names not only the callback function, but also a user pointer that
michael@0: you can retrieve with
michael@0: 
michael@0:     png_get_user_chunk_ptr(png_ptr);
michael@0: 
michael@0: If you call the png_set_read_user_chunk_fn() function, then all unknown
michael@0: chunks which the callback does not handle will be saved when read.  You can
michael@0: cause them to be discarded by returning '1' ("handled") instead of '0'.  This
michael@0: behavior will change in libpng 1.7 and the default handling set by the
michael@0: png_set_keep_unknown_chunks() function, described below, will be used when the
michael@0: callback returns 0.  If you want the existing behavior you should set the global
michael@0: default to PNG_HANDLE_CHUNK_IF_SAFE now; this is compatible with all current
michael@0: versions of libpng and with 1.7.  Libpng 1.6 issues a warning if you keep the
michael@0: default, or PNG_HANDLE_CHUNK_NEVER, and the callback returns 0.
michael@0: 
michael@0: At this point, you can set up a callback function that will be
michael@0: called after each row has been read, which you can use to control
michael@0: a progress meter or the like.  It's demonstrated in pngtest.c.
michael@0: You must supply a function
michael@0: 
michael@0:     void read_row_callback(png_structp png_ptr,
michael@0:        png_uint_32 row, int pass);
michael@0:     {
michael@0:       /* put your code here */
michael@0:     }
michael@0: 
michael@0: (You can give it another name that you like instead of "read_row_callback")
michael@0: 
michael@0: To inform libpng about your function, use
michael@0: 
michael@0:     png_set_read_status_fn(png_ptr, read_row_callback);
michael@0: 
michael@0: When this function is called the row has already been completely processed and
michael@0: the 'row' and 'pass' refer to the next row to be handled.  For the
michael@0: non-interlaced case the row that was just handled is simply one less than the
michael@0: passed in row number, and pass will always be 0.  For the interlaced case the
michael@0: same applies unless the row value is 0, in which case the row just handled was
michael@0: the last one from one of the preceding passes.  Because interlacing may skip a
michael@0: pass you cannot be sure that the preceding pass is just 'pass-1', if you really
michael@0: need to know what the last pass is record (row,pass) from the callback and use
michael@0: the last recorded value each time.
michael@0: 
michael@0: As with the user transform you can find the output row using the
michael@0: PNG_ROW_FROM_PASS_ROW macro.
michael@0: 
michael@0: Unknown-chunk handling
michael@0: 
michael@0: Now you get to set the way the library processes unknown chunks in the
michael@0: input PNG stream. Both known and unknown chunks will be read.  Normal
michael@0: behavior is that known chunks will be parsed into information in
michael@0: various info_ptr members while unknown chunks will be discarded. This
michael@0: behavior can be wasteful if your application will never use some known
michael@0: chunk types. To change this, you can call:
michael@0: 
michael@0:     png_set_keep_unknown_chunks(png_ptr, keep,
michael@0:         chunk_list, num_chunks);
michael@0: 
michael@0:     keep       - 0: default unknown chunk handling
michael@0:                  1: ignore; do not keep
michael@0:                  2: keep only if safe-to-copy
michael@0:                  3: keep even if unsafe-to-copy
michael@0: 
michael@0:                You can use these definitions:
michael@0:                  PNG_HANDLE_CHUNK_AS_DEFAULT   0
michael@0:                  PNG_HANDLE_CHUNK_NEVER        1
michael@0:                  PNG_HANDLE_CHUNK_IF_SAFE      2
michael@0:                  PNG_HANDLE_CHUNK_ALWAYS       3
michael@0: 
michael@0:     chunk_list - list of chunks affected (a byte string,
michael@0:                  five bytes per chunk, NULL or '\0' if
michael@0:                  num_chunks is positive; ignored if
michael@0:                  numchunks <= 0).
michael@0: 
michael@0:     num_chunks - number of chunks affected; if 0, all
michael@0:                  unknown chunks are affected.  If positive,
michael@0:                  only the chunks in the list are affected,
michael@0:                  and if negative all unknown chunks and
michael@0:                  all known chunks except for the IHDR,
michael@0:                  PLTE, tRNS, IDAT, and IEND chunks are
michael@0:                  affected.
michael@0: 
michael@0: Unknown chunks declared in this way will be saved as raw data onto a
michael@0: list of png_unknown_chunk structures.  If a chunk that is normally
michael@0: known to libpng is named in the list, it will be handled as unknown,
michael@0: according to the "keep" directive.  If a chunk is named in successive
michael@0: instances of png_set_keep_unknown_chunks(), the final instance will
michael@0: take precedence.  The IHDR and IEND chunks should not be named in
michael@0: chunk_list; if they are, libpng will process them normally anyway.
michael@0: If you know that your application will never make use of some particular
michael@0: chunks, use PNG_HANDLE_CHUNK_NEVER (or 1) as demonstrated below.
michael@0: 
michael@0: Here is an example of the usage of png_set_keep_unknown_chunks(),
michael@0: where the private "vpAg" chunk will later be processed by a user chunk
michael@0: callback function:
michael@0: 
michael@0:     png_byte vpAg[5]={118, 112,  65, 103, (png_byte) '\0'};
michael@0: 
michael@0:     #if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED)
michael@0:       png_byte unused_chunks[]=
michael@0:       {
michael@0:         104,  73,  83,  84, (png_byte) '\0',   /* hIST */
michael@0:         105,  84,  88, 116, (png_byte) '\0',   /* iTXt */
michael@0:         112,  67,  65,  76, (png_byte) '\0',   /* pCAL */
michael@0:         115,  67,  65,  76, (png_byte) '\0',   /* sCAL */
michael@0:         115,  80,  76,  84, (png_byte) '\0',   /* sPLT */
michael@0:         116,  73,  77,  69, (png_byte) '\0',   /* tIME */
michael@0:       };
michael@0:     #endif
michael@0: 
michael@0:     ...
michael@0: 
michael@0:     #if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED)
michael@0:       /* ignore all unknown chunks
michael@0:        * (use global setting "2" for libpng16 and earlier):
michael@0:        */
michael@0:       png_set_keep_unknown_chunks(read_ptr, 2, NULL, 0);
michael@0: 
michael@0:       /* except for vpAg: */
michael@0:       png_set_keep_unknown_chunks(read_ptr, 2, vpAg, 1);
michael@0: 
michael@0:       /* also ignore unused known chunks: */
michael@0:       png_set_keep_unknown_chunks(read_ptr, 1, unused_chunks,
michael@0:          (int)(sizeof unused_chunks)/5);
michael@0:     #endif
michael@0: 
michael@0: User limits
michael@0: 
michael@0: The PNG specification allows the width and height of an image to be as
michael@0: large as 2^31-1 (0x7fffffff), or about 2.147 billion rows and columns.
michael@0: Since very few applications really need to process such large images,
michael@0: we have imposed an arbitrary 1-million limit on rows and columns.
michael@0: Larger images will be rejected immediately with a png_error() call. If
michael@0: you wish to change this limit, you can use
michael@0: 
michael@0:    png_set_user_limits(png_ptr, width_max, height_max);
michael@0: 
michael@0: to set your own limits, or use width_max = height_max = 0x7fffffffL
michael@0: to allow all valid dimensions (libpng may reject some very large images
michael@0: anyway because of potential buffer overflow conditions).
michael@0: 
michael@0: You should put this statement after you create the PNG structure and
michael@0: before calling png_read_info(), png_read_png(), or png_process_data().
michael@0: 
michael@0: When writing a PNG datastream, put this statement before calling
michael@0: png_write_info() or png_write_png().
michael@0: 
michael@0: If you need to retrieve the limits that are being applied, use
michael@0: 
michael@0:    width_max = png_get_user_width_max(png_ptr);
michael@0:    height_max = png_get_user_height_max(png_ptr);
michael@0: 
michael@0: The PNG specification sets no limit on the number of ancillary chunks
michael@0: allowed in a PNG datastream.  You can impose a limit on the total number
michael@0: of sPLT, tEXt, iTXt, zTXt, and unknown chunks that will be stored, with
michael@0: 
michael@0:    png_set_chunk_cache_max(png_ptr, user_chunk_cache_max);
michael@0: 
michael@0: where 0x7fffffffL means unlimited.  You can retrieve this limit with
michael@0: 
michael@0:    chunk_cache_max = png_get_chunk_cache_max(png_ptr);
michael@0: 
michael@0: You can also set a limit on the amount of memory that a compressed chunk
michael@0: other than IDAT can occupy, with
michael@0: 
michael@0:    png_set_chunk_malloc_max(png_ptr, user_chunk_malloc_max);
michael@0: 
michael@0: and you can retrieve the limit with
michael@0: 
michael@0:    chunk_malloc_max = png_get_chunk_malloc_max(png_ptr);
michael@0: 
michael@0: Any chunks that would cause either of these limits to be exceeded will
michael@0: be ignored.
michael@0: 
michael@0: Information about your system
michael@0: 
michael@0: If you intend to display the PNG or to incorporate it in other image data you
michael@0: need to tell libpng information about your display or drawing surface so that
michael@0: libpng can convert the values in the image to match the display.
michael@0: 
michael@0: From libpng-1.5.4 this information can be set before reading the PNG file
michael@0: header.  In earlier versions png_set_gamma() existed but behaved incorrectly if
michael@0: called before the PNG file header had been read and png_set_alpha_mode() did not
michael@0: exist.
michael@0: 
michael@0: If you need to support versions prior to libpng-1.5.4 test the version number
michael@0: as illustrated below using "PNG_LIBPNG_VER >= 10504" and follow the procedures
michael@0: described in the appropriate manual page.
michael@0: 
michael@0: You give libpng the encoding expected by your system expressed as a 'gamma'
michael@0: value.  You can also specify a default encoding for the PNG file in
michael@0: case the required information is missing from the file.  By default libpng
michael@0: assumes that the PNG data matches your system, to keep this default call:
michael@0: 
michael@0:    png_set_gamma(png_ptr, screen_gamma, 1/screen_gamma/*file gamma*/);
michael@0: 
michael@0: or you can use the fixed point equivalent:
michael@0: 
michael@0:    png_set_gamma_fixed(png_ptr, PNG_FP_1*screen_gamma,
michael@0:       PNG_FP_1/screen_gamma);
michael@0: 
michael@0: If you don't know the gamma for your system it is probably 2.2 - a good
michael@0: approximation to the IEC standard for display systems (sRGB).  If images are
michael@0: too contrasty or washed out you got the value wrong - check your system
michael@0: documentation!
michael@0: 
michael@0: Many systems permit the system gamma to be changed via a lookup table in the
michael@0: display driver, a few systems, including older Macs, change the response by
michael@0: default.  As of 1.5.4 three special values are available to handle common
michael@0: situations:
michael@0: 
michael@0:    PNG_DEFAULT_sRGB: Indicates that the system conforms to the
michael@0:                      IEC 61966-2-1 standard.  This matches almost
michael@0:                      all systems.
michael@0:    PNG_GAMMA_MAC_18: Indicates that the system is an older
michael@0:                      (pre Mac OS 10.6) Apple Macintosh system with
michael@0:                      the default settings.
michael@0:    PNG_GAMMA_LINEAR: Just the fixed point value for 1.0 - indicates
michael@0:                      that the system expects data with no gamma
michael@0:                      encoding.
michael@0: 
michael@0: You would use the linear (unencoded) value if you need to process the pixel
michael@0: values further because this avoids the need to decode and re-encode each
michael@0: component value whenever arithmetic is performed.  A lot of graphics software
michael@0: uses linear values for this reason, often with higher precision component values
michael@0: to preserve overall accuracy.
michael@0: 
michael@0: The second thing you may need to tell libpng about is how your system handles
michael@0: alpha channel information.  Some, but not all, PNG files contain an alpha
michael@0: channel.  To display these files correctly you need to compose the data onto a
michael@0: suitable background, as described in the PNG specification.
michael@0: 
michael@0: Libpng only supports composing onto a single color (using png_set_background;
michael@0: see below).  Otherwise you must do the composition yourself and, in this case,
michael@0: you may need to call png_set_alpha_mode:
michael@0: 
michael@0:    #if PNG_LIBPNG_VER >= 10504
michael@0:       png_set_alpha_mode(png_ptr, mode, screen_gamma);
michael@0:    #else
michael@0:       png_set_gamma(png_ptr, screen_gamma, 1.0/screen_gamma);
michael@0:    #endif
michael@0: 
michael@0: The screen_gamma value is the same as the argument to png_set_gamma; however,
michael@0: how it affects the output depends on the mode.  png_set_alpha_mode() sets the
michael@0: file gamma default to 1/screen_gamma, so normally you don't need to call
michael@0: png_set_gamma.  If you need different defaults call png_set_gamma() before
michael@0: png_set_alpha_mode() - if you call it after it will override the settings made
michael@0: by png_set_alpha_mode().
michael@0: 
michael@0: The mode is as follows:
michael@0: 
michael@0:     PNG_ALPHA_PNG: The data is encoded according to the PNG specification.  Red,
michael@0: green and blue, or gray, components are gamma encoded color
michael@0: values and are not premultiplied by the alpha value.  The
michael@0: alpha value is a linear measure of the contribution of the
michael@0: pixel to the corresponding final output pixel.
michael@0: 
michael@0: You should normally use this format if you intend to perform
michael@0: color correction on the color values; most, maybe all, color
michael@0: correction software has no handling for the alpha channel and,
michael@0: anyway, the math to handle pre-multiplied component values is
michael@0: unnecessarily complex.
michael@0: 
michael@0: Before you do any arithmetic on the component values you need
michael@0: to remove the gamma encoding and multiply out the alpha
michael@0: channel.  See the PNG specification for more detail.  It is
michael@0: important to note that when an image with an alpha channel is
michael@0: scaled, linear encoded, pre-multiplied component values must
michael@0: be used!
michael@0: 
michael@0: The remaining modes assume you don't need to do any further color correction or
michael@0: that if you do, your color correction software knows all about alpha (it
michael@0: probably doesn't!)
michael@0: 
michael@0:     PNG_ALPHA_STANDARD:  The data libpng produces
michael@0: is encoded in the standard way
michael@0: assumed by most correctly written graphics software.
michael@0: The gamma encoding will be removed by libpng and the
michael@0: linear component values will be pre-multiplied by the
michael@0: alpha channel.
michael@0: 
michael@0: With this format the final image must be re-encoded to
michael@0: match the display gamma before the image is displayed.
michael@0: If your system doesn't do that, yet still seems to
michael@0: perform arithmetic on the pixels without decoding them,
michael@0: it is broken - check out the modes below.
michael@0: 
michael@0: With PNG_ALPHA_STANDARD libpng always produces linear
michael@0: component values, whatever screen_gamma you supply.  The
michael@0: screen_gamma value is, however, used as a default for
michael@0: the file gamma if the PNG file has no gamma information.
michael@0: 
michael@0: If you call png_set_gamma() after png_set_alpha_mode() you
michael@0: will override the linear encoding.  Instead the
michael@0: pre-multiplied pixel values will be gamma encoded but
michael@0: the alpha channel will still be linear.  This may
michael@0: actually match the requirements of some broken software,
michael@0: but it is unlikely.
michael@0: 
michael@0: While linear 8-bit data is often used it has
michael@0: insufficient precision for any image with a reasonable
michael@0: dynamic range.  To avoid problems, and if your software
michael@0: supports it, use png_set_expand_16() to force all
michael@0: components to 16 bits.
michael@0: 
michael@0:     PNG_ALPHA_OPTIMIZED: This mode is the same
michael@0: as PNG_ALPHA_STANDARD except that
michael@0: completely opaque pixels are gamma encoded according to
michael@0: the screen_gamma value.  Pixels with alpha less than 1.0
michael@0: will still have linear components.
michael@0: 
michael@0: Use this format if you have control over your
michael@0: compositing software and so don't do other arithmetic
michael@0: (such as scaling) on the data you get from libpng.  Your
michael@0: compositing software can simply copy opaque pixels to
michael@0: the output but still has linear values for the
michael@0: non-opaque pixels.
michael@0: 
michael@0: In normal compositing, where the alpha channel encodes
michael@0: partial pixel coverage (as opposed to broad area
michael@0: translucency), the inaccuracies of the 8-bit
michael@0: representation of non-opaque pixels are irrelevant.
michael@0: 
michael@0: You can also try this format if your software is broken;
michael@0: it might look better.
michael@0: 
michael@0:     PNG_ALPHA_BROKEN: This is PNG_ALPHA_STANDARD;
michael@0: however, all component values,
michael@0: including the alpha channel are gamma encoded.  This is
michael@0: an appropriate format to try if your software, or more
michael@0: likely hardware, is totally broken, i.e., if it performs
michael@0: linear arithmetic directly on gamma encoded values.
michael@0: 
michael@0: In most cases of broken software or hardware the bug in the final display
michael@0: manifests as a subtle halo around composited parts of the image.  You may not
michael@0: even perceive this as a halo; the composited part of the image may simply appear
michael@0: separate from the background, as though it had been cut out of paper and pasted
michael@0: on afterward.
michael@0: 
michael@0: If you don't have to deal with bugs in software or hardware, or if you can fix
michael@0: them, there are three recommended ways of using png_set_alpha_mode():
michael@0: 
michael@0:    png_set_alpha_mode(png_ptr, PNG_ALPHA_PNG,
michael@0:        screen_gamma);
michael@0: 
michael@0: You can do color correction on the result (libpng does not currently
michael@0: support color correction internally).  When you handle the alpha channel
michael@0: you need to undo the gamma encoding and multiply out the alpha.
michael@0: 
michael@0:    png_set_alpha_mode(png_ptr, PNG_ALPHA_STANDARD,
michael@0:        screen_gamma);
michael@0:    png_set_expand_16(png_ptr);
michael@0: 
michael@0: If you are using the high level interface, don't call png_set_expand_16();
michael@0: instead pass PNG_TRANSFORM_EXPAND_16 to the interface.
michael@0: 
michael@0: With this mode you can't do color correction, but you can do arithmetic,
michael@0: including composition and scaling, on the data without further processing.
michael@0: 
michael@0:    png_set_alpha_mode(png_ptr, PNG_ALPHA_OPTIMIZED,
michael@0:        screen_gamma);
michael@0: 
michael@0: You can avoid the expansion to 16-bit components with this mode, but you
michael@0: lose the ability to scale the image or perform other linear arithmetic.
michael@0: All you can do is compose the result onto a matching output.  Since this
michael@0: mode is libpng-specific you also need to write your own composition
michael@0: software.
michael@0: 
michael@0: If you don't need, or can't handle, the alpha channel you can call
michael@0: png_set_background() to remove it by compositing against a fixed color.  Don't
michael@0: call png_set_strip_alpha() to do this - it will leave spurious pixel values in
michael@0: transparent parts of this image.
michael@0: 
michael@0:    png_set_background(png_ptr, &background_color,
michael@0:        PNG_BACKGROUND_GAMMA_SCREEN, 0, 1);
michael@0: 
michael@0: The background_color is an RGB or grayscale value according to the data format
michael@0: libpng will produce for you.  Because you don't yet know the format of the PNG
michael@0: file, if you call png_set_background at this point you must arrange for the
michael@0: format produced by libpng to always have 8-bit or 16-bit components and then
michael@0: store the color as an 8-bit or 16-bit color as appropriate.  The color contains
michael@0: separate gray and RGB component values, so you can let libpng produce gray or
michael@0: RGB output according to the input format, but low bit depth grayscale images
michael@0: must always be converted to at least 8-bit format.  (Even though low bit depth
michael@0: grayscale images can't have an alpha channel they can have a transparent
michael@0: color!)
michael@0: 
michael@0: You set the transforms you need later, either as flags to the high level
michael@0: interface or libpng API calls for the low level interface.  For reference the
michael@0: settings and API calls required are:
michael@0: 
michael@0: 8-bit values:
michael@0:    PNG_TRANSFORM_SCALE_16 | PNG_EXPAND
michael@0:    png_set_expand(png_ptr); png_set_scale_16(png_ptr);
michael@0: 
michael@0:    If you must get exactly the same inaccurate results
michael@0:    produced by default in versions prior to libpng-1.5.4,
michael@0:    use PNG_TRANSFORM_STRIP_16 and png_set_strip_16(png_ptr)
michael@0:    instead.
michael@0: 
michael@0: 16-bit values:
michael@0:    PNG_TRANSFORM_EXPAND_16
michael@0:    png_set_expand_16(png_ptr);
michael@0: 
michael@0: In either case palette image data will be expanded to RGB.  If you just want
michael@0: color data you can add PNG_TRANSFORM_GRAY_TO_RGB or png_set_gray_to_rgb(png_ptr)
michael@0: to the list.
michael@0: 
michael@0: Calling png_set_background before the PNG file header is read will not work
michael@0: prior to libpng-1.5.4.  Because the failure may result in unexpected warnings or
michael@0: errors it is therefore much safer to call png_set_background after the head has
michael@0: been read.  Unfortunately this means that prior to libpng-1.5.4 it cannot be
michael@0: used with the high level interface.
michael@0: 
michael@0: The high-level read interface
michael@0: 
michael@0: At this point there are two ways to proceed; through the high-level
michael@0: read interface, or through a sequence of low-level read operations.
michael@0: You can use the high-level interface if (a) you are willing to read
michael@0: the entire image into memory, and (b) the input transformations
michael@0: you want to do are limited to the following set:
michael@0: 
michael@0:     PNG_TRANSFORM_IDENTITY      No transformation
michael@0:     PNG_TRANSFORM_SCALE_16      Strip 16-bit samples to
michael@0:                                 8-bit accurately
michael@0:     PNG_TRANSFORM_STRIP_16      Chop 16-bit samples to
michael@0:                                 8-bit less accurately
michael@0:     PNG_TRANSFORM_STRIP_ALPHA   Discard the alpha channel
michael@0:     PNG_TRANSFORM_PACKING       Expand 1, 2 and 4-bit
michael@0:                                 samples to bytes
michael@0:     PNG_TRANSFORM_PACKSWAP      Change order of packed
michael@0:                                 pixels to LSB first
michael@0:     PNG_TRANSFORM_EXPAND        Perform set_expand()
michael@0:     PNG_TRANSFORM_INVERT_MONO   Invert monochrome images
michael@0:     PNG_TRANSFORM_SHIFT         Normalize pixels to the
michael@0:                                 sBIT depth
michael@0:     PNG_TRANSFORM_BGR           Flip RGB to BGR, RGBA
michael@0:                                 to BGRA
michael@0:     PNG_TRANSFORM_SWAP_ALPHA    Flip RGBA to ARGB or GA
michael@0:                                 to AG
michael@0:     PNG_TRANSFORM_INVERT_ALPHA  Change alpha from opacity
michael@0:                                 to transparency
michael@0:     PNG_TRANSFORM_SWAP_ENDIAN   Byte-swap 16-bit samples
michael@0:     PNG_TRANSFORM_GRAY_TO_RGB   Expand grayscale samples
michael@0:                                 to RGB (or GA to RGBA)
michael@0:     PNG_TRANSFORM_EXPAND_16     Expand samples to 16 bits
michael@0: 
michael@0: (This excludes setting a background color, doing gamma transformation,
michael@0: quantizing, and setting filler.)  If this is the case, simply do this:
michael@0: 
michael@0:     png_read_png(png_ptr, info_ptr, png_transforms, NULL)
michael@0: 
michael@0: where png_transforms is an integer containing the bitwise OR of some
michael@0: set of transformation flags.  This call is equivalent to png_read_info(),
michael@0: followed the set of transformations indicated by the transform mask,
michael@0: then png_read_image(), and finally png_read_end().
michael@0: 
michael@0: (The final parameter of this call is not yet used.  Someday it might point
michael@0: to transformation parameters required by some future input transform.)
michael@0: 
michael@0: You must use png_transforms and not call any png_set_transform() functions
michael@0: when you use png_read_png().
michael@0: 
michael@0: After you have called png_read_png(), you can retrieve the image data
michael@0: with
michael@0: 
michael@0:    row_pointers = png_get_rows(png_ptr, info_ptr);
michael@0: 
michael@0: where row_pointers is an array of pointers to the pixel data for each row:
michael@0: 
michael@0:    png_bytep row_pointers[height];
michael@0: 
michael@0: If you know your image size and pixel size ahead of time, you can allocate
michael@0: row_pointers prior to calling png_read_png() with
michael@0: 
michael@0:    if (height > PNG_UINT_32_MAX/(sizeof (png_byte)))
michael@0:       png_error (png_ptr,
michael@0:           "Image is too tall to process in memory");
michael@0: 
michael@0:    if (width > PNG_UINT_32_MAX/pixel_size)
michael@0:       png_error (png_ptr,
michael@0:           "Image is too wide to process in memory");
michael@0: 
michael@0:    row_pointers = png_malloc(png_ptr,
michael@0:        height*(sizeof (png_bytep)));
michael@0: 
michael@0:    for (int i=0; i<height, i++)
michael@0:       row_pointers[i]=NULL;  /* security precaution */
michael@0: 
michael@0:    for (int i=0; i<height, i++)
michael@0:       row_pointers[i]=png_malloc(png_ptr,
michael@0:           width*pixel_size);
michael@0: 
michael@0:    png_set_rows(png_ptr, info_ptr, &row_pointers);
michael@0: 
michael@0: Alternatively you could allocate your image in one big block and define
michael@0: row_pointers[i] to point into the proper places in your block.
michael@0: 
michael@0: If you use png_set_rows(), the application is responsible for freeing
michael@0: row_pointers (and row_pointers[i], if they were separately allocated).
michael@0: 
michael@0: If you don't allocate row_pointers ahead of time, png_read_png() will
michael@0: do it, and it'll be free'ed by libpng when you call png_destroy_*().
michael@0: 
michael@0: The low-level read interface
michael@0: 
michael@0: If you are going the low-level route, you are now ready to read all
michael@0: the file information up to the actual image data.  You do this with a
michael@0: call to png_read_info().
michael@0: 
michael@0:     png_read_info(png_ptr, info_ptr);
michael@0: 
michael@0: This will process all chunks up to but not including the image data.
michael@0: 
michael@0: This also copies some of the data from the PNG file into the decode structure
michael@0: for use in later transformations.  Important information copied in is:
michael@0: 
michael@0: 1) The PNG file gamma from the gAMA chunk.  This overwrites the default value
michael@0: provided by an earlier call to png_set_gamma or png_set_alpha_mode.
michael@0: 
michael@0: 2) Prior to libpng-1.5.4 the background color from a bKGd chunk.  This
michael@0: damages the information provided by an earlier call to png_set_background
michael@0: resulting in unexpected behavior.  Libpng-1.5.4 no longer does this.
michael@0: 
michael@0: 3) The number of significant bits in each component value.  Libpng uses this to
michael@0: optimize gamma handling by reducing the internal lookup table sizes.
michael@0: 
michael@0: 4) The transparent color information from a tRNS chunk.  This can be modified by
michael@0: a later call to png_set_tRNS.
michael@0: 
michael@0: Querying the info structure
michael@0: 
michael@0: Functions are used to get the information from the info_ptr once it
michael@0: has been read.  Note that these fields may not be completely filled
michael@0: in until png_read_end() has read the chunk data following the image.
michael@0: 
michael@0:     png_get_IHDR(png_ptr, info_ptr, &width, &height,
michael@0:        &bit_depth, &color_type, &interlace_type,
michael@0:        &compression_type, &filter_method);
michael@0: 
michael@0:     width          - holds the width of the image
michael@0:                      in pixels (up to 2^31).
michael@0: 
michael@0:     height         - holds the height of the image
michael@0:                      in pixels (up to 2^31).
michael@0: 
michael@0:     bit_depth      - holds the bit depth of one of the
michael@0:                      image channels.  (valid values are
michael@0:                      1, 2, 4, 8, 16 and depend also on
michael@0:                      the color_type.  See also
michael@0:                      significant bits (sBIT) below).
michael@0: 
michael@0:     color_type     - describes which color/alpha channels
michael@0:                          are present.
michael@0:                      PNG_COLOR_TYPE_GRAY
michael@0:                         (bit depths 1, 2, 4, 8, 16)
michael@0:                      PNG_COLOR_TYPE_GRAY_ALPHA
michael@0:                         (bit depths 8, 16)
michael@0:                      PNG_COLOR_TYPE_PALETTE
michael@0:                         (bit depths 1, 2, 4, 8)
michael@0:                      PNG_COLOR_TYPE_RGB
michael@0:                         (bit_depths 8, 16)
michael@0:                      PNG_COLOR_TYPE_RGB_ALPHA
michael@0:                         (bit_depths 8, 16)
michael@0: 
michael@0:                      PNG_COLOR_MASK_PALETTE
michael@0:                      PNG_COLOR_MASK_COLOR
michael@0:                      PNG_COLOR_MASK_ALPHA
michael@0: 
michael@0:     interlace_type - (PNG_INTERLACE_NONE or
michael@0:                      PNG_INTERLACE_ADAM7)
michael@0: 
michael@0:     compression_type - (must be PNG_COMPRESSION_TYPE_BASE
michael@0:                      for PNG 1.0)
michael@0: 
michael@0:     filter_method  - (must be PNG_FILTER_TYPE_BASE
michael@0:                      for PNG 1.0, and can also be
michael@0:                      PNG_INTRAPIXEL_DIFFERENCING if
michael@0:                      the PNG datastream is embedded in
michael@0:                      a MNG-1.0 datastream)
michael@0: 
michael@0:     Any or all of interlace_type, compression_type, or
michael@0:     filter_method can be NULL if you are
michael@0:     not interested in their values.
michael@0: 
michael@0:     Note that png_get_IHDR() returns 32-bit data into
michael@0:     the application's width and height variables.
michael@0:     This is an unsafe situation if these are 16-bit
michael@0:     variables.  In such situations, the
michael@0:     png_get_image_width() and png_get_image_height()
michael@0:     functions described below are safer.
michael@0: 
michael@0:     width            = png_get_image_width(png_ptr,
michael@0:                          info_ptr);
michael@0: 
michael@0:     height           = png_get_image_height(png_ptr,
michael@0:                          info_ptr);
michael@0: 
michael@0:     bit_depth        = png_get_bit_depth(png_ptr,
michael@0:                          info_ptr);
michael@0: 
michael@0:     color_type       = png_get_color_type(png_ptr,
michael@0:                          info_ptr);
michael@0: 
michael@0:     interlace_type   = png_get_interlace_type(png_ptr,
michael@0:                          info_ptr);
michael@0: 
michael@0:     compression_type = png_get_compression_type(png_ptr,
michael@0:                          info_ptr);
michael@0: 
michael@0:     filter_method    = png_get_filter_type(png_ptr,
michael@0:                          info_ptr);
michael@0: 
michael@0:     channels = png_get_channels(png_ptr, info_ptr);
michael@0: 
michael@0:     channels       - number of channels of info for the
michael@0:                      color type (valid values are 1 (GRAY,
michael@0:                      PALETTE), 2 (GRAY_ALPHA), 3 (RGB),
michael@0:                      4 (RGB_ALPHA or RGB + filler byte))
michael@0: 
michael@0:     rowbytes = png_get_rowbytes(png_ptr, info_ptr);
michael@0: 
michael@0:     rowbytes       - number of bytes needed to hold a row
michael@0: 
michael@0:     signature = png_get_signature(png_ptr, info_ptr);
michael@0: 
michael@0:     signature      - holds the signature read from the
michael@0:                      file (if any).  The data is kept in
michael@0:                      the same offset it would be if the
michael@0:                      whole signature were read (i.e. if an
michael@0:                      application had already read in 4
michael@0:                      bytes of signature before starting
michael@0:                      libpng, the remaining 4 bytes would
michael@0:                      be in signature[4] through signature[7]
michael@0:                      (see png_set_sig_bytes())).
michael@0: 
michael@0: These are also important, but their validity depends on whether the chunk
michael@0: has been read.  The png_get_valid(png_ptr, info_ptr, PNG_INFO_<chunk>) and
michael@0: png_get_<chunk>(png_ptr, info_ptr, ...) functions return non-zero if the
michael@0: data has been read, or zero if it is missing.  The parameters to the
michael@0: png_get_<chunk> are set directly if they are simple data types, or a
michael@0: pointer into the info_ptr is returned for any complex types.
michael@0: 
michael@0: The colorspace data from gAMA, cHRM, sRGB, iCCP, and sBIT chunks
michael@0: is simply returned to give the application information about how the
michael@0: image was encoded.  Libpng itself only does transformations using the file
michael@0: gamma when combining semitransparent pixels with the background color, and,
michael@0: since libpng-1.6.0, when converting between 8-bit sRGB and 16-bit linear pixels
michael@0: within the simplified API.  Libpng also uses the file gamma when converting
michael@0: RGB to gray, beginning with libpng-1.0.5, if the application calls
michael@0: png_set_rgb_to_gray()).
michael@0: 
michael@0:     png_get_PLTE(png_ptr, info_ptr, &palette,
michael@0:                      &num_palette);
michael@0: 
michael@0:     palette        - the palette for the file
michael@0:                      (array of png_color)
michael@0: 
michael@0:     num_palette    - number of entries in the palette
michael@0: 
michael@0:     png_get_gAMA(png_ptr, info_ptr, &file_gamma);
michael@0:     png_get_gAMA_fixed(png_ptr, info_ptr, &int_file_gamma);
michael@0: 
michael@0:     file_gamma     - the gamma at which the file is
michael@0:                      written (PNG_INFO_gAMA)
michael@0: 
michael@0:     int_file_gamma - 100,000 times the gamma at which the
michael@0:                      file is written
michael@0: 
michael@0:     png_get_cHRM(png_ptr, info_ptr,  &white_x, &white_y, &red_x,
michael@0:                      &red_y, &green_x, &green_y, &blue_x, &blue_y)
michael@0:     png_get_cHRM_XYZ(png_ptr, info_ptr, &red_X, &red_Y, &red_Z,
michael@0:                      &green_X, &green_Y, &green_Z, &blue_X, &blue_Y,
michael@0:                      &blue_Z)
michael@0:     png_get_cHRM_fixed(png_ptr, info_ptr, &int_white_x,
michael@0:                      &int_white_y, &int_red_x, &int_red_y,
michael@0:                      &int_green_x, &int_green_y, &int_blue_x,
michael@0:                      &int_blue_y)
michael@0:     png_get_cHRM_XYZ_fixed(png_ptr, info_ptr, &int_red_X, &int_red_Y,
michael@0:                      &int_red_Z, &int_green_X, &int_green_Y,
michael@0:                      &int_green_Z, &int_blue_X, &int_blue_Y,
michael@0:                      &int_blue_Z)
michael@0: 
michael@0:     {white,red,green,blue}_{x,y}
michael@0:                      A color space encoding specified using the
michael@0:                      chromaticities of the end points and the
michael@0:                      white point. (PNG_INFO_cHRM)
michael@0: 
michael@0:     {red,green,blue}_{X,Y,Z}
michael@0:                      A color space encoding specified using the
michael@0:                      encoding end points - the CIE tristimulus
michael@0:                      specification of the intended color of the red,
michael@0:                      green and blue channels in the PNG RGB data.
michael@0:                      The white point is simply the sum of the three
michael@0:                      end points. (PNG_INFO_cHRM)
michael@0: 
michael@0:     png_get_sRGB(png_ptr, info_ptr, &srgb_intent);
michael@0: 
michael@0:     file_srgb_intent - the rendering intent (PNG_INFO_sRGB)
michael@0:                      The presence of the sRGB chunk
michael@0:                      means that the pixel data is in the
michael@0:                      sRGB color space.  This chunk also
michael@0:                      implies specific values of gAMA and
michael@0:                      cHRM.
michael@0: 
michael@0:     png_get_iCCP(png_ptr, info_ptr, &name,
michael@0:        &compression_type, &profile, &proflen);
michael@0: 
michael@0:     name             - The profile name.
michael@0: 
michael@0:     compression_type - The compression type; always
michael@0:                        PNG_COMPRESSION_TYPE_BASE for PNG 1.0.
michael@0:                        You may give NULL to this argument to
michael@0:                        ignore it.
michael@0: 
michael@0:     profile          - International Color Consortium color
michael@0:                        profile data. May contain NULs.
michael@0: 
michael@0:     proflen          - length of profile data in bytes.
michael@0: 
michael@0:     png_get_sBIT(png_ptr, info_ptr, &sig_bit);
michael@0: 
michael@0:     sig_bit        - the number of significant bits for
michael@0:                      (PNG_INFO_sBIT) each of the gray,
michael@0:                      red, green, and blue channels,
michael@0:                      whichever are appropriate for the
michael@0:                      given color type (png_color_16)
michael@0: 
michael@0:     png_get_tRNS(png_ptr, info_ptr, &trans_alpha,
michael@0:                      &num_trans, &trans_color);
michael@0: 
michael@0:     trans_alpha    - array of alpha (transparency)
michael@0:                      entries for palette (PNG_INFO_tRNS)
michael@0: 
michael@0:     num_trans      - number of transparent entries
michael@0:                      (PNG_INFO_tRNS)
michael@0: 
michael@0:     trans_color    - graylevel or color sample values of
michael@0:                      the single transparent color for
michael@0:                      non-paletted images (PNG_INFO_tRNS)
michael@0: 
michael@0:     png_get_hIST(png_ptr, info_ptr, &hist);
michael@0:                      (PNG_INFO_hIST)
michael@0: 
michael@0:     hist           - histogram of palette (array of
michael@0:                      png_uint_16)
michael@0: 
michael@0:     png_get_tIME(png_ptr, info_ptr, &mod_time);
michael@0: 
michael@0:     mod_time       - time image was last modified
michael@0:                     (PNG_VALID_tIME)
michael@0: 
michael@0:     png_get_bKGD(png_ptr, info_ptr, &background);
michael@0: 
michael@0:     background     - background color (of type
michael@0:                      png_color_16p) (PNG_VALID_bKGD)
michael@0:                      valid 16-bit red, green and blue
michael@0:                      values, regardless of color_type
michael@0: 
michael@0:     num_comments   = png_get_text(png_ptr, info_ptr,
michael@0:                      &text_ptr, &num_text);
michael@0: 
michael@0:     num_comments   - number of comments
michael@0: 
michael@0:     text_ptr       - array of png_text holding image
michael@0:                      comments
michael@0: 
michael@0:     text_ptr[i].compression - type of compression used
michael@0:                  on "text" PNG_TEXT_COMPRESSION_NONE
michael@0:                            PNG_TEXT_COMPRESSION_zTXt
michael@0:                            PNG_ITXT_COMPRESSION_NONE
michael@0:                            PNG_ITXT_COMPRESSION_zTXt
michael@0: 
michael@0:     text_ptr[i].key   - keyword for comment.  Must contain
michael@0:                          1-79 characters.
michael@0: 
michael@0:     text_ptr[i].text  - text comments for current
michael@0:                          keyword.  Can be empty.
michael@0: 
michael@0:     text_ptr[i].text_length - length of text string,
michael@0:                  after decompression, 0 for iTXt
michael@0: 
michael@0:     text_ptr[i].itxt_length - length of itxt string,
michael@0:                  after decompression, 0 for tEXt/zTXt
michael@0: 
michael@0:     text_ptr[i].lang  - language of comment (empty
michael@0:                          string for unknown).
michael@0: 
michael@0:     text_ptr[i].lang_key  - keyword in UTF-8
michael@0:                          (empty string for unknown).
michael@0: 
michael@0:     Note that the itxt_length, lang, and lang_key
michael@0:     members of the text_ptr structure only exist when the
michael@0:     library is built with iTXt chunk support.  Prior to
michael@0:     libpng-1.4.0 the library was built by default without
michael@0:     iTXt support. Also note that when iTXt is supported,
michael@0:     they contain NULL pointers when the "compression"
michael@0:     field contains PNG_TEXT_COMPRESSION_NONE or
michael@0:     PNG_TEXT_COMPRESSION_zTXt.
michael@0: 
michael@0:     num_text       - number of comments (same as
michael@0:                      num_comments; you can put NULL here
michael@0:                      to avoid the duplication)
michael@0: 
michael@0:     Note while png_set_text() will accept text, language,
michael@0:     and translated keywords that can be NULL pointers, the
michael@0:     structure returned by png_get_text will always contain
michael@0:     regular zero-terminated C strings.  They might be
michael@0:     empty strings but they will never be NULL pointers.
michael@0: 
michael@0:     num_spalettes = png_get_sPLT(png_ptr, info_ptr,
michael@0:        &palette_ptr);
michael@0: 
michael@0:     num_spalettes  - number of sPLT chunks read.
michael@0: 
michael@0:     palette_ptr    - array of palette structures holding
michael@0:                      contents of one or more sPLT chunks
michael@0:                      read.
michael@0: 
michael@0:     png_get_oFFs(png_ptr, info_ptr, &offset_x, &offset_y,
michael@0:        &unit_type);
michael@0: 
michael@0:     offset_x       - positive offset from the left edge
michael@0:                      of the screen (can be negative)
michael@0: 
michael@0:     offset_y       - positive offset from the top edge
michael@0:                      of the screen (can be negative)
michael@0: 
michael@0:     unit_type      - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER
michael@0: 
michael@0:     png_get_pHYs(png_ptr, info_ptr, &res_x, &res_y,
michael@0:        &unit_type);
michael@0: 
michael@0:     res_x          - pixels/unit physical resolution in
michael@0:                      x direction
michael@0: 
michael@0:     res_y          - pixels/unit physical resolution in
michael@0:                      x direction
michael@0: 
michael@0:     unit_type      - PNG_RESOLUTION_UNKNOWN,
michael@0:                      PNG_RESOLUTION_METER
michael@0: 
michael@0:     png_get_sCAL(png_ptr, info_ptr, &unit, &width,
michael@0:        &height)
michael@0: 
michael@0:     unit        - physical scale units (an integer)
michael@0: 
michael@0:     width       - width of a pixel in physical scale units
michael@0: 
michael@0:     height      - height of a pixel in physical scale units
michael@0:                  (width and height are doubles)
michael@0: 
michael@0:     png_get_sCAL_s(png_ptr, info_ptr, &unit, &width,
michael@0:        &height)
michael@0: 
michael@0:     unit        - physical scale units (an integer)
michael@0: 
michael@0:     width       - width of a pixel in physical scale units
michael@0:                   (expressed as a string)
michael@0: 
michael@0:     height      - height of a pixel in physical scale units
michael@0:                  (width and height are strings like "2.54")
michael@0: 
michael@0:     num_unknown_chunks = png_get_unknown_chunks(png_ptr,
michael@0:        info_ptr, &unknowns)
michael@0: 
michael@0:     unknowns          - array of png_unknown_chunk
michael@0:                         structures holding unknown chunks
michael@0: 
michael@0:     unknowns[i].name  - name of unknown chunk
michael@0: 
michael@0:     unknowns[i].data  - data of unknown chunk
michael@0: 
michael@0:     unknowns[i].size  - size of unknown chunk's data
michael@0: 
michael@0:     unknowns[i].location - position of chunk in file
michael@0: 
michael@0:     The value of "i" corresponds to the order in which the
michael@0:     chunks were read from the PNG file or inserted with the
michael@0:     png_set_unknown_chunks() function.
michael@0: 
michael@0:     The value of "location" is a bitwise "or" of
michael@0: 
michael@0:          PNG_HAVE_IHDR  (0x01)
michael@0:          PNG_HAVE_PLTE  (0x02)
michael@0:          PNG_AFTER_IDAT (0x08)
michael@0: 
michael@0: The data from the pHYs chunk can be retrieved in several convenient
michael@0: forms:
michael@0: 
michael@0:     res_x = png_get_x_pixels_per_meter(png_ptr,
michael@0:        info_ptr)
michael@0: 
michael@0:     res_y = png_get_y_pixels_per_meter(png_ptr,
michael@0:        info_ptr)
michael@0: 
michael@0:     res_x_and_y = png_get_pixels_per_meter(png_ptr,
michael@0:        info_ptr)
michael@0: 
michael@0:     res_x = png_get_x_pixels_per_inch(png_ptr,
michael@0:        info_ptr)
michael@0: 
michael@0:     res_y = png_get_y_pixels_per_inch(png_ptr,
michael@0:        info_ptr)
michael@0: 
michael@0:     res_x_and_y = png_get_pixels_per_inch(png_ptr,
michael@0:        info_ptr)
michael@0: 
michael@0:     aspect_ratio = png_get_pixel_aspect_ratio(png_ptr,
michael@0:        info_ptr)
michael@0: 
michael@0:     Each of these returns 0 [signifying "unknown"] if
michael@0:        the data is not present or if res_x is 0;
michael@0:        res_x_and_y is 0 if res_x != res_y
michael@0: 
michael@0:     Note that because of the way the resolutions are
michael@0:        stored internally, the inch conversions won't
michael@0:        come out to exactly even number.  For example,
michael@0:        72 dpi is stored as 0.28346 pixels/meter, and
michael@0:        when this is retrieved it is 71.9988 dpi, so
michael@0:        be sure to round the returned value appropriately
michael@0:        if you want to display a reasonable-looking result.
michael@0: 
michael@0: The data from the oFFs chunk can be retrieved in several convenient
michael@0: forms:
michael@0: 
michael@0:     x_offset = png_get_x_offset_microns(png_ptr, info_ptr);
michael@0: 
michael@0:     y_offset = png_get_y_offset_microns(png_ptr, info_ptr);
michael@0: 
michael@0:     x_offset = png_get_x_offset_inches(png_ptr, info_ptr);
michael@0: 
michael@0:     y_offset = png_get_y_offset_inches(png_ptr, info_ptr);
michael@0: 
michael@0:     Each of these returns 0 [signifying "unknown" if both
michael@0:        x and y are 0] if the data is not present or if the
michael@0:        chunk is present but the unit is the pixel.  The
michael@0:        remark about inexact inch conversions applies here
michael@0:        as well, because a value in inches can't always be
michael@0:        converted to microns and back without some loss
michael@0:        of precision.
michael@0: 
michael@0: For more information, see the
michael@0: PNG specification for chunk contents.  Be careful with trusting
michael@0: rowbytes, as some of the transformations could increase the space
michael@0: needed to hold a row (expand, filler, gray_to_rgb, etc.).
michael@0: See png_read_update_info(), below.
michael@0: 
michael@0: A quick word about text_ptr and num_text.  PNG stores comments in
michael@0: keyword/text pairs, one pair per chunk, with no limit on the number
michael@0: of text chunks, and a 2^31 byte limit on their size.  While there are
michael@0: suggested keywords, there is no requirement to restrict the use to these
michael@0: strings.  It is strongly suggested that keywords and text be sensible
michael@0: to humans (that's the point), so don't use abbreviations.  Non-printing
michael@0: symbols are not allowed.  See the PNG specification for more details.
michael@0: There is also no requirement to have text after the keyword.
michael@0: 
michael@0: Keywords should be limited to 79 Latin-1 characters without leading or
michael@0: trailing spaces, but non-consecutive spaces are allowed within the
michael@0: keyword.  It is possible to have the same keyword any number of times.
michael@0: The text_ptr is an array of png_text structures, each holding a
michael@0: pointer to a language string, a pointer to a keyword and a pointer to
michael@0: a text string.  The text string, language code, and translated
michael@0: keyword may be empty or NULL pointers.  The keyword/text
michael@0: pairs are put into the array in the order that they are received.
michael@0: However, some or all of the text chunks may be after the image, so, to
michael@0: make sure you have read all the text chunks, don't mess with these
michael@0: until after you read the stuff after the image.  This will be
michael@0: mentioned again below in the discussion that goes with png_read_end().
michael@0: 
michael@0: Input transformations
michael@0: 
michael@0: After you've read the header information, you can set up the library
michael@0: to handle any special transformations of the image data.  The various
michael@0: ways to transform the data will be described in the order that they
michael@0: should occur.  This is important, as some of these change the color
michael@0: type and/or bit depth of the data, and some others only work on
michael@0: certain color types and bit depths.
michael@0: 
michael@0: Transformations you request are ignored if they don't have any meaning for a
michael@0: particular input data format.  However some transformations can have an effect
michael@0: as a result of a previous transformation.  If you specify a contradictory set of
michael@0: transformations, for example both adding and removing the alpha channel, you
michael@0: cannot predict the final result.
michael@0: 
michael@0: The color used for the transparency values should be supplied in the same
michael@0: format/depth as the current image data.  It is stored in the same format/depth
michael@0: as the image data in a tRNS chunk, so this is what libpng expects for this data.
michael@0: 
michael@0: The color used for the background value depends on the need_expand argument as
michael@0: described below.
michael@0: 
michael@0: Data will be decoded into the supplied row buffers packed into bytes
michael@0: unless the library has been told to transform it into another format.
michael@0: For example, 4 bit/pixel paletted or grayscale data will be returned
michael@0: 2 pixels/byte with the leftmost pixel in the high-order bits of the
michael@0: byte, unless png_set_packing() is called.  8-bit RGB data will be stored
michael@0: in RGB RGB RGB format unless png_set_filler() or png_set_add_alpha()
michael@0: is called to insert filler bytes, either before or after each RGB triplet.
michael@0: 16-bit RGB data will be returned RRGGBB RRGGBB, with the most significant
michael@0: byte of the color value first, unless png_set_scale_16() is called to
michael@0: transform it to regular RGB RGB triplets, or png_set_filler() or
michael@0: png_set_add alpha() is called to insert filler bytes, either before or
michael@0: after each RRGGBB triplet.  Similarly, 8-bit or 16-bit grayscale data can
michael@0: be modified with png_set_filler(), png_set_add_alpha(), png_set_strip_16(),
michael@0: or png_set_scale_16().
michael@0: 
michael@0: The following code transforms grayscale images of less than 8 to 8 bits,
michael@0: changes paletted images to RGB, and adds a full alpha channel if there is
michael@0: transparency information in a tRNS chunk.  This is most useful on
michael@0: grayscale images with bit depths of 2 or 4 or if there is a multiple-image
michael@0: viewing application that wishes to treat all images in the same way.
michael@0: 
michael@0:     if (color_type == PNG_COLOR_TYPE_PALETTE)
michael@0:         png_set_palette_to_rgb(png_ptr);
michael@0: 
michael@0:     if (png_get_valid(png_ptr, info_ptr,
michael@0:         PNG_INFO_tRNS)) png_set_tRNS_to_alpha(png_ptr);
michael@0: 
michael@0:     if (color_type == PNG_COLOR_TYPE_GRAY &&
michael@0:         bit_depth < 8) png_set_expand_gray_1_2_4_to_8(png_ptr);
michael@0: 
michael@0: The first two functions are actually aliases for png_set_expand(), added
michael@0: in libpng version 1.0.4, with the function names expanded to improve code
michael@0: readability.  In some future version they may actually do different
michael@0: things.
michael@0: 
michael@0: As of libpng version 1.2.9, png_set_expand_gray_1_2_4_to_8() was
michael@0: added.  It expands the sample depth without changing tRNS to alpha.
michael@0: 
michael@0: As of libpng version 1.5.2, png_set_expand_16() was added.  It behaves as
michael@0: png_set_expand(); however, the resultant channels have 16 bits rather than 8.
michael@0: Use this when the output color or gray channels are made linear to avoid fairly
michael@0: severe accuracy loss.
michael@0: 
michael@0:    if (bit_depth < 16)
michael@0:       png_set_expand_16(png_ptr);
michael@0: 
michael@0: PNG can have files with 16 bits per channel.  If you only can handle
michael@0: 8 bits per channel, this will strip the pixels down to 8-bit.
michael@0: 
michael@0:     if (bit_depth == 16)
michael@0: #if PNG_LIBPNG_VER >= 10504
michael@0:        png_set_scale_16(png_ptr);
michael@0: #else
michael@0:        png_set_strip_16(png_ptr);
michael@0: #endif
michael@0: 
michael@0: (The more accurate "png_set_scale_16()" API became available in libpng version
michael@0: 1.5.4).
michael@0: 
michael@0: If you need to process the alpha channel on the image separately from the image
michael@0: data (for example if you convert it to a bitmap mask) it is possible to have
michael@0: libpng strip the channel leaving just RGB or gray data:
michael@0: 
michael@0:     if (color_type & PNG_COLOR_MASK_ALPHA)
michael@0:        png_set_strip_alpha(png_ptr);
michael@0: 
michael@0: If you strip the alpha channel you need to find some other way of dealing with
michael@0: the information.  If, instead, you want to convert the image to an opaque
michael@0: version with no alpha channel use png_set_background; see below.
michael@0: 
michael@0: As of libpng version 1.5.2, almost all useful expansions are supported, the
michael@0: major ommissions are conversion of grayscale to indexed images (which can be
michael@0: done trivially in the application) and conversion of indexed to grayscale (which
michael@0: can be done by a trivial manipulation of the palette.)
michael@0: 
michael@0: In the following table, the 01 means grayscale with depth<8, 31 means
michael@0: indexed with depth<8, other numerals represent the color type, "T" means
michael@0: the tRNS chunk is present, A means an alpha channel is present, and O
michael@0: means tRNS or alpha is present but all pixels in the image are opaque.
michael@0: 
michael@0:   FROM  01  31   0  0T  0O   2  2T  2O   3  3T  3O  4A  4O  6A  6O
michael@0:    TO
michael@0:    01    -  [G]  -   -   -   -   -   -   -   -   -   -   -   -   -
michael@0:    31   [Q]  Q  [Q] [Q] [Q]  Q   Q   Q   Q   Q   Q  [Q] [Q]  Q   Q
michael@0:     0    1   G   +   .   .   G   G   G   G   G   G   B   B  GB  GB
michael@0:    0T    lt  Gt  t   +   .   Gt  G   G   Gt  G   G   Bt  Bt GBt GBt
michael@0:    0O    lt  Gt  t   .   +   Gt  Gt  G   Gt  Gt  G   Bt  Bt GBt GBt
michael@0:     2    C   P   C   C   C   +   .   .   C   -   -  CB  CB   B   B
michael@0:    2T    Ct  -   Ct  C   C   t   +   t   -   -   -  CBt CBt  Bt  Bt
michael@0:    2O    Ct  -   Ct  C   C   t   t   +   -   -   -  CBt CBt  Bt  Bt
michael@0:     3   [Q]  p  [Q] [Q] [Q]  Q   Q   Q   +   .   .  [Q] [Q]  Q   Q
michael@0:    3T   [Qt] p  [Qt][Q] [Q]  Qt  Qt  Qt  t   +   t  [Qt][Qt] Qt  Qt
michael@0:    3O   [Qt] p  [Qt][Q] [Q]  Qt  Qt  Qt  t   t   +  [Qt][Qt] Qt  Qt
michael@0:    4A    lA  G   A   T   T   GA  GT  GT  GA  GT  GT  +   BA  G  GBA
michael@0:    4O    lA GBA  A   T   T   GA  GT  GT  GA  GT  GT  BA  +  GBA  G
michael@0:    6A    CA  PA  CA  C   C   A   T  tT   PA  P   P   C  CBA  +   BA
michael@0:    6O    CA PBA  CA  C   C   A  tT   T   PA  P   P  CBA  C   BA  +
michael@0: 
michael@0: Within the matrix,
michael@0:      "+" identifies entries where 'from' and 'to' are the same.
michael@0:      "-" means the transformation is not supported.
michael@0:      "." means nothing is necessary (a tRNS chunk can just be ignored).
michael@0:      "t" means the transformation is obtained by png_set_tRNS.
michael@0:      "A" means the transformation is obtained by png_set_add_alpha().
michael@0:      "X" means the transformation is obtained by png_set_expand().
michael@0:      "1" means the transformation is obtained by
michael@0:          png_set_expand_gray_1_2_4_to_8() (and by png_set_expand()
michael@0:          if there is no transparency in the original or the final
michael@0:          format).
michael@0:      "C" means the transformation is obtained by png_set_gray_to_rgb().
michael@0:      "G" means the transformation is obtained by png_set_rgb_to_gray().
michael@0:      "P" means the transformation is obtained by
michael@0:          png_set_expand_palette_to_rgb().
michael@0:      "p" means the transformation is obtained by png_set_packing().
michael@0:      "Q" means the transformation is obtained by png_set_quantize().
michael@0:      "T" means the transformation is obtained by
michael@0:          png_set_tRNS_to_alpha().
michael@0:      "B" means the transformation is obtained by
michael@0:          png_set_background(), or png_strip_alpha().
michael@0: 
michael@0: When an entry has multiple transforms listed all are required to cause the
michael@0: right overall transformation.  When two transforms are separated by a comma
michael@0: either will do the job.  When transforms are enclosed in [] the transform should
michael@0: do the job but this is currently unimplemented - a different format will result
michael@0: if the suggested transformations are used.
michael@0: 
michael@0: In PNG files, the alpha channel in an image
michael@0: is the level of opacity.  If you need the alpha channel in an image to
michael@0: be the level of transparency instead of opacity, you can invert the
michael@0: alpha channel (or the tRNS chunk data) after it's read, so that 0 is
michael@0: fully opaque and 255 (in 8-bit or paletted images) or 65535 (in 16-bit
michael@0: images) is fully transparent, with
michael@0: 
michael@0:     png_set_invert_alpha(png_ptr);
michael@0: 
michael@0: PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as
michael@0: they can, resulting in, for example, 8 pixels per byte for 1 bit
michael@0: files.  This code expands to 1 pixel per byte without changing the
michael@0: values of the pixels:
michael@0: 
michael@0:     if (bit_depth < 8)
michael@0:        png_set_packing(png_ptr);
michael@0: 
michael@0: PNG files have possible bit depths of 1, 2, 4, 8, and 16.  All pixels
michael@0: stored in a PNG image have been "scaled" or "shifted" up to the next
michael@0: higher possible bit depth (e.g. from 5 bits/sample in the range [0,31]
michael@0: to 8 bits/sample in the range [0, 255]).  However, it is also possible
michael@0: to convert the PNG pixel data back to the original bit depth of the
michael@0: image.  This call reduces the pixels back down to the original bit depth:
michael@0: 
michael@0:     png_color_8p sig_bit;
michael@0: 
michael@0:     if (png_get_sBIT(png_ptr, info_ptr, &sig_bit))
michael@0:        png_set_shift(png_ptr, sig_bit);
michael@0: 
michael@0: PNG files store 3-color pixels in red, green, blue order.  This code
michael@0: changes the storage of the pixels to blue, green, red:
michael@0: 
michael@0:     if (color_type == PNG_COLOR_TYPE_RGB ||
michael@0:         color_type == PNG_COLOR_TYPE_RGB_ALPHA)
michael@0:        png_set_bgr(png_ptr);
michael@0: 
michael@0: PNG files store RGB pixels packed into 3 or 6 bytes. This code expands them
michael@0: into 4 or 8 bytes for windowing systems that need them in this format:
michael@0: 
michael@0:     if (color_type == PNG_COLOR_TYPE_RGB)
michael@0:        png_set_filler(png_ptr, filler, PNG_FILLER_BEFORE);
michael@0: 
michael@0: where "filler" is the 8 or 16-bit number to fill with, and the location is
michael@0: either PNG_FILLER_BEFORE or PNG_FILLER_AFTER, depending upon whether
michael@0: you want the filler before the RGB or after.  This transformation
michael@0: does not affect images that already have full alpha channels.  To add an
michael@0: opaque alpha channel, use filler=0xff or 0xffff and PNG_FILLER_AFTER which
michael@0: will generate RGBA pixels.
michael@0: 
michael@0: Note that png_set_filler() does not change the color type.  If you want
michael@0: to do that, you can add a true alpha channel with
michael@0: 
michael@0:     if (color_type == PNG_COLOR_TYPE_RGB ||
michael@0:        color_type == PNG_COLOR_TYPE_GRAY)
michael@0:        png_set_add_alpha(png_ptr, filler, PNG_FILLER_AFTER);
michael@0: 
michael@0: where "filler" contains the alpha value to assign to each pixel.
michael@0: This function was added in libpng-1.2.7.
michael@0: 
michael@0: If you are reading an image with an alpha channel, and you need the
michael@0: data as ARGB instead of the normal PNG format RGBA:
michael@0: 
michael@0:     if (color_type == PNG_COLOR_TYPE_RGB_ALPHA)
michael@0:        png_set_swap_alpha(png_ptr);
michael@0: 
michael@0: For some uses, you may want a grayscale image to be represented as
michael@0: RGB.  This code will do that conversion:
michael@0: 
michael@0:     if (color_type == PNG_COLOR_TYPE_GRAY ||
michael@0:         color_type == PNG_COLOR_TYPE_GRAY_ALPHA)
michael@0:        png_set_gray_to_rgb(png_ptr);
michael@0: 
michael@0: Conversely, you can convert an RGB or RGBA image to grayscale or grayscale
michael@0: with alpha.
michael@0: 
michael@0:     if (color_type == PNG_COLOR_TYPE_RGB ||
michael@0:         color_type == PNG_COLOR_TYPE_RGB_ALPHA)
michael@0:        png_set_rgb_to_gray(png_ptr, error_action,
michael@0:           double red_weight, double green_weight);
michael@0: 
michael@0:     error_action = 1: silently do the conversion
michael@0: 
michael@0:     error_action = 2: issue a warning if the original
michael@0:                       image has any pixel where
michael@0:                       red != green or red != blue
michael@0: 
michael@0:     error_action = 3: issue an error and abort the
michael@0:                       conversion if the original
michael@0:                       image has any pixel where
michael@0:                       red != green or red != blue
michael@0: 
michael@0:     red_weight:       weight of red component
michael@0: 
michael@0:     green_weight:     weight of green component
michael@0:                       If either weight is negative, default
michael@0:                       weights are used.
michael@0: 
michael@0: In the corresponding fixed point API the red_weight and green_weight values are
michael@0: simply scaled by 100,000:
michael@0: 
michael@0:     png_set_rgb_to_gray(png_ptr, error_action,
michael@0:        png_fixed_point red_weight,
michael@0:        png_fixed_point green_weight);
michael@0: 
michael@0: If you have set error_action = 1 or 2, you can
michael@0: later check whether the image really was gray, after processing
michael@0: the image rows, with the png_get_rgb_to_gray_status(png_ptr) function.
michael@0: It will return a png_byte that is zero if the image was gray or
michael@0: 1 if there were any non-gray pixels.  Background and sBIT data
michael@0: will be silently converted to grayscale, using the green channel
michael@0: data for sBIT, regardless of the error_action setting.
michael@0: 
michael@0: The default values come from the PNG file cHRM chunk if present; otherwise, the
michael@0: defaults correspond to the ITU-R recommendation 709, and also the sRGB color
michael@0: space, as recommended in the Charles Poynton's Colour FAQ,
michael@0: <http://www.poynton.com/>, in section 9:
michael@0: 
michael@0:    <http://www.poynton.com/notes/colour_and_gamma/ColorFAQ.html#RTFToC9>
michael@0: 
michael@0:     Y = 0.2126 * R + 0.7152 * G + 0.0722 * B
michael@0: 
michael@0: Previous versions of this document, 1998 through 2002, recommended a slightly
michael@0: different formula:
michael@0: 
michael@0:     Y = 0.212671 * R + 0.715160 * G + 0.072169 * B
michael@0: 
michael@0: Libpng uses an integer approximation:
michael@0: 
michael@0:     Y = (6968 * R + 23434 * G + 2366 * B)/32768
michael@0: 
michael@0: The calculation is done in a linear colorspace, if the image gamma
michael@0: can be determined.
michael@0: 
michael@0: The png_set_background() function has been described already; it tells libpng to
michael@0: composite images with alpha or simple transparency against the supplied
michael@0: background color.  For compatibility with versions of libpng earlier than
michael@0: libpng-1.5.4 it is recommended that you call the function after reading the file
michael@0: header, even if you don't want to use the color in a bKGD chunk, if one exists.
michael@0: 
michael@0: If the PNG file contains a bKGD chunk (PNG_INFO_bKGD valid),
michael@0: you may use this color, or supply another color more suitable for
michael@0: the current display (e.g., the background color from a web page).  You
michael@0: need to tell libpng how the color is represented, both the format of the
michael@0: component values in the color (the number of bits) and the gamma encoding of the
michael@0: color.  The function takes two arguments, background_gamma_mode and need_expand
michael@0: to convey this information; however, only two combinations are likely to be
michael@0: useful:
michael@0: 
michael@0:     png_color_16 my_background;
michael@0:     png_color_16p image_background;
michael@0: 
michael@0:     if (png_get_bKGD(png_ptr, info_ptr, &image_background))
michael@0:        png_set_background(png_ptr, image_background,
michael@0:            PNG_BACKGROUND_GAMMA_FILE, 1/*needs to be expanded*/, 1);
michael@0:     else
michael@0:        png_set_background(png_ptr, &my_background,
michael@0:            PNG_BACKGROUND_GAMMA_SCREEN, 0/*do not expand*/, 1);
michael@0: 
michael@0: The second call was described above - my_background is in the format of the
michael@0: final, display, output produced by libpng.  Because you now know the format of
michael@0: the PNG it is possible to avoid the need to choose either 8-bit or 16-bit
michael@0: output and to retain palette images (the palette colors will be modified
michael@0: appropriately and the tRNS chunk removed.)  However, if you are doing this,
michael@0: take great care not to ask for transformations without checking first that
michael@0: they apply!
michael@0: 
michael@0: In the first call the background color has the original bit depth and color type
michael@0: of the PNG file.  So, for palette images the color is supplied as a palette
michael@0: index and for low bit greyscale images the color is a reduced bit value in
michael@0: image_background->gray.
michael@0: 
michael@0: If you didn't call png_set_gamma() before reading the file header, for example
michael@0: if you need your code to remain compatible with older versions of libpng prior
michael@0: to libpng-1.5.4, this is the place to call it.
michael@0: 
michael@0: Do not call it if you called png_set_alpha_mode(); doing so will damage the
michael@0: settings put in place by png_set_alpha_mode().  (If png_set_alpha_mode() is
michael@0: supported then you can certainly do png_set_gamma() before reading the PNG
michael@0: header.)
michael@0: 
michael@0: This API unconditionally sets the screen and file gamma values, so it will
michael@0: override the value in the PNG file unless it is called before the PNG file
michael@0: reading starts.  For this reason you must always call it with the PNG file
michael@0: value when you call it in this position:
michael@0: 
michael@0:    if (png_get_gAMA(png_ptr, info_ptr, &file_gamma))
michael@0:       png_set_gamma(png_ptr, screen_gamma, file_gamma);
michael@0: 
michael@0:    else
michael@0:       png_set_gamma(png_ptr, screen_gamma, 0.45455);
michael@0: 
michael@0: If you need to reduce an RGB file to a paletted file, or if a paletted
michael@0: file has more entries then will fit on your screen, png_set_quantize()
michael@0: will do that.  Note that this is a simple match quantization that merely
michael@0: finds the closest color available.  This should work fairly well with
michael@0: optimized palettes, but fairly badly with linear color cubes.  If you
michael@0: pass a palette that is larger than maximum_colors, the file will
michael@0: reduce the number of colors in the palette so it will fit into
michael@0: maximum_colors.  If there is a histogram, libpng will use it to make
michael@0: more intelligent choices when reducing the palette.  If there is no
michael@0: histogram, it may not do as good a job.
michael@0: 
michael@0:    if (color_type & PNG_COLOR_MASK_COLOR)
michael@0:    {
michael@0:       if (png_get_valid(png_ptr, info_ptr,
michael@0:           PNG_INFO_PLTE))
michael@0:       {
michael@0:          png_uint_16p histogram = NULL;
michael@0: 
michael@0:          png_get_hIST(png_ptr, info_ptr,
michael@0:              &histogram);
michael@0:          png_set_quantize(png_ptr, palette, num_palette,
michael@0:             max_screen_colors, histogram, 1);
michael@0:       }
michael@0: 
michael@0:       else
michael@0:       {
michael@0:          png_color std_color_cube[MAX_SCREEN_COLORS] =
michael@0:             { ... colors ... };
michael@0: 
michael@0:          png_set_quantize(png_ptr, std_color_cube,
michael@0:             MAX_SCREEN_COLORS, MAX_SCREEN_COLORS,
michael@0:             NULL,0);
michael@0:       }
michael@0:    }
michael@0: 
michael@0: PNG files describe monochrome as black being zero and white being one.
michael@0: The following code will reverse this (make black be one and white be
michael@0: zero):
michael@0: 
michael@0:    if (bit_depth == 1 && color_type == PNG_COLOR_TYPE_GRAY)
michael@0:       png_set_invert_mono(png_ptr);
michael@0: 
michael@0: This function can also be used to invert grayscale and gray-alpha images:
michael@0: 
michael@0:    if (color_type == PNG_COLOR_TYPE_GRAY ||
michael@0:        color_type == PNG_COLOR_TYPE_GRAY_ALPHA)
michael@0:       png_set_invert_mono(png_ptr);
michael@0: 
michael@0: PNG files store 16-bit pixels in network byte order (big-endian,
michael@0: ie. most significant bits first).  This code changes the storage to the
michael@0: other way (little-endian, i.e. least significant bits first, the
michael@0: way PCs store them):
michael@0: 
michael@0:     if (bit_depth == 16)
michael@0:        png_set_swap(png_ptr);
michael@0: 
michael@0: If you are using packed-pixel images (1, 2, or 4 bits/pixel), and you
michael@0: need to change the order the pixels are packed into bytes, you can use:
michael@0: 
michael@0:     if (bit_depth < 8)
michael@0:        png_set_packswap(png_ptr);
michael@0: 
michael@0: Finally, you can write your own transformation function if none of
michael@0: the existing ones meets your needs.  This is done by setting a callback
michael@0: with
michael@0: 
michael@0:     png_set_read_user_transform_fn(png_ptr,
michael@0:         read_transform_fn);
michael@0: 
michael@0: You must supply the function
michael@0: 
michael@0:     void read_transform_fn(png_structp png_ptr, png_row_infop
michael@0:         row_info, png_bytep data)
michael@0: 
michael@0: See pngtest.c for a working example.  Your function will be called
michael@0: after all of the other transformations have been processed.  Take care with
michael@0: interlaced images if you do the interlace yourself - the width of the row is the
michael@0: width in 'row_info', not the overall image width.
michael@0: 
michael@0: If supported, libpng provides two information routines that you can use to find
michael@0: where you are in processing the image:
michael@0: 
michael@0:    png_get_current_pass_number(png_structp png_ptr);
michael@0:    png_get_current_row_number(png_structp png_ptr);
michael@0: 
michael@0: Don't try using these outside a transform callback - firstly they are only
michael@0: supported if user transforms are supported, secondly they may well return
michael@0: unexpected results unless the row is actually being processed at the moment they
michael@0: are called.
michael@0: 
michael@0: With interlaced
michael@0: images the value returned is the row in the input sub-image image.  Use
michael@0: PNG_ROW_FROM_PASS_ROW(row, pass) and PNG_COL_FROM_PASS_COL(col, pass) to
michael@0: find the output pixel (x,y) given an interlaced sub-image pixel (row,col,pass).
michael@0: 
michael@0: The discussion of interlace handling above contains more information on how to
michael@0: use these values.
michael@0: 
michael@0: You can also set up a pointer to a user structure for use by your
michael@0: callback function, and you can inform libpng that your transform
michael@0: function will change the number of channels or bit depth with the
michael@0: function
michael@0: 
michael@0:     png_set_user_transform_info(png_ptr, user_ptr,
michael@0:         user_depth, user_channels);
michael@0: 
michael@0: The user's application, not libpng, is responsible for allocating and
michael@0: freeing any memory required for the user structure.
michael@0: 
michael@0: You can retrieve the pointer via the function
michael@0: png_get_user_transform_ptr().  For example:
michael@0: 
michael@0:     voidp read_user_transform_ptr =
michael@0:         png_get_user_transform_ptr(png_ptr);
michael@0: 
michael@0: The last thing to handle is interlacing; this is covered in detail below,
michael@0: but you must call the function here if you want libpng to handle expansion
michael@0: of the interlaced image.
michael@0: 
michael@0:     number_of_passes = png_set_interlace_handling(png_ptr);
michael@0: 
michael@0: After setting the transformations, libpng can update your png_info
michael@0: structure to reflect any transformations you've requested with this
michael@0: call.
michael@0: 
michael@0:     png_read_update_info(png_ptr, info_ptr);
michael@0: 
michael@0: This is most useful to update the info structure's rowbytes
michael@0: field so you can use it to allocate your image memory.  This function
michael@0: will also update your palette with the correct screen_gamma and
michael@0: background if these have been given with the calls above.  You may
michael@0: only call png_read_update_info() once with a particular info_ptr.
michael@0: 
michael@0: After you call png_read_update_info(), you can allocate any
michael@0: memory you need to hold the image.  The row data is simply
michael@0: raw byte data for all forms of images.  As the actual allocation
michael@0: varies among applications, no example will be given.  If you
michael@0: are allocating one large chunk, you will need to build an
michael@0: array of pointers to each row, as it will be needed for some
michael@0: of the functions below.
michael@0: 
michael@0: Remember: Before you call png_read_update_info(), the png_get_*()
michael@0: functions return the values corresponding to the original PNG image.
michael@0: After you call png_read_update_info the values refer to the image
michael@0: that libpng will output.  Consequently you must call all the png_set_
michael@0: functions before you call png_read_update_info().  This is particularly
michael@0: important for png_set_interlace_handling() - if you are going to call
michael@0: png_read_update_info() you must call png_set_interlace_handling() before
michael@0: it unless you want to receive interlaced output.
michael@0: 
michael@0: Reading image data
michael@0: 
michael@0: After you've allocated memory, you can read the image data.
michael@0: The simplest way to do this is in one function call.  If you are
michael@0: allocating enough memory to hold the whole image, you can just
michael@0: call png_read_image() and libpng will read in all the image data
michael@0: and put it in the memory area supplied.  You will need to pass in
michael@0: an array of pointers to each row.
michael@0: 
michael@0: This function automatically handles interlacing, so you don't
michael@0: need to call png_set_interlace_handling() (unless you call
michael@0: png_read_update_info()) or call this function multiple times, or any
michael@0: of that other stuff necessary with png_read_rows().
michael@0: 
michael@0:    png_read_image(png_ptr, row_pointers);
michael@0: 
michael@0: where row_pointers is:
michael@0: 
michael@0:    png_bytep row_pointers[height];
michael@0: 
michael@0: You can point to void or char or whatever you use for pixels.
michael@0: 
michael@0: If you don't want to read in the whole image at once, you can
michael@0: use png_read_rows() instead.  If there is no interlacing (check
michael@0: interlace_type == PNG_INTERLACE_NONE), this is simple:
michael@0: 
michael@0:     png_read_rows(png_ptr, row_pointers, NULL,
michael@0:         number_of_rows);
michael@0: 
michael@0: where row_pointers is the same as in the png_read_image() call.
michael@0: 
michael@0: If you are doing this just one row at a time, you can do this with
michael@0: a single row_pointer instead of an array of row_pointers:
michael@0: 
michael@0:     png_bytep row_pointer = row;
michael@0:     png_read_row(png_ptr, row_pointer, NULL);
michael@0: 
michael@0: If the file is interlaced (interlace_type != 0 in the IHDR chunk), things
michael@0: get somewhat harder.  The only current (PNG Specification version 1.2)
michael@0: interlacing type for PNG is (interlace_type == PNG_INTERLACE_ADAM7);
michael@0: a somewhat complicated 2D interlace scheme, known as Adam7, that
michael@0: breaks down an image into seven smaller images of varying size, based
michael@0: on an 8x8 grid.  This number is defined (from libpng 1.5) as
michael@0: PNG_INTERLACE_ADAM7_PASSES in png.h
michael@0: 
michael@0: libpng can fill out those images or it can give them to you "as is".
michael@0: It is almost always better to have libpng handle the interlacing for you.
michael@0: If you want the images filled out, there are two ways to do that.  The one
michael@0: mentioned in the PNG specification is to expand each pixel to cover
michael@0: those pixels that have not been read yet (the "rectangle" method).
michael@0: This results in a blocky image for the first pass, which gradually
michael@0: smooths out as more pixels are read.  The other method is the "sparkle"
michael@0: method, where pixels are drawn only in their final locations, with the
michael@0: rest of the image remaining whatever colors they were initialized to
michael@0: before the start of the read.  The first method usually looks better,
michael@0: but tends to be slower, as there are more pixels to put in the rows.
michael@0: 
michael@0: If, as is likely, you want libpng to expand the images, call this before
michael@0: calling png_start_read_image() or png_read_update_info():
michael@0: 
michael@0:     if (interlace_type == PNG_INTERLACE_ADAM7)
michael@0:        number_of_passes
michael@0:            = png_set_interlace_handling(png_ptr);
michael@0: 
michael@0: This will return the number of passes needed.  Currently, this is seven,
michael@0: but may change if another interlace type is added.  This function can be
michael@0: called even if the file is not interlaced, where it will return one pass.
michael@0: You then need to read the whole image 'number_of_passes' times.  Each time
michael@0: will distribute the pixels from the current pass to the correct place in
michael@0: the output image, so you need to supply the same rows to png_read_rows in
michael@0: each pass.
michael@0: 
michael@0: If you are not going to display the image after each pass, but are
michael@0: going to wait until the entire image is read in, use the sparkle
michael@0: effect.  This effect is faster and the end result of either method
michael@0: is exactly the same.  If you are planning on displaying the image
michael@0: after each pass, the "rectangle" effect is generally considered the
michael@0: better looking one.
michael@0: 
michael@0: If you only want the "sparkle" effect, just call png_read_rows() as
michael@0: normal, with the third parameter NULL.  Make sure you make pass over
michael@0: the image number_of_passes times, and you don't change the data in the
michael@0: rows between calls.  You can change the locations of the data, just
michael@0: not the data.  Each pass only writes the pixels appropriate for that
michael@0: pass, and assumes the data from previous passes is still valid.
michael@0: 
michael@0:     png_read_rows(png_ptr, row_pointers, NULL,
michael@0:         number_of_rows);
michael@0: 
michael@0: If you only want the first effect (the rectangles), do the same as
michael@0: before except pass the row buffer in the third parameter, and leave
michael@0: the second parameter NULL.
michael@0: 
michael@0:     png_read_rows(png_ptr, NULL, row_pointers,
michael@0:         number_of_rows);
michael@0: 
michael@0: If you don't want libpng to handle the interlacing details, just call
michael@0: png_read_rows() PNG_INTERLACE_ADAM7_PASSES times to read in all the images.
michael@0: Each of the images is a valid image by itself; however, you will almost
michael@0: certainly need to distribute the pixels from each sub-image to the
michael@0: correct place.  This is where everything gets very tricky.
michael@0: 
michael@0: If you want to retrieve the separate images you must pass the correct
michael@0: number of rows to each successive call of png_read_rows().  The calculation
michael@0: gets pretty complicated for small images, where some sub-images may
michael@0: not even exist because either their width or height ends up zero.
michael@0: libpng provides two macros to help you in 1.5 and later versions:
michael@0: 
michael@0:    png_uint_32 width = PNG_PASS_COLS(image_width, pass_number);
michael@0:    png_uint_32 height = PNG_PASS_ROWS(image_height, pass_number);
michael@0: 
michael@0: Respectively these tell you the width and height of the sub-image
michael@0: corresponding to the numbered pass.  'pass' is in in the range 0 to 6 -
michael@0: this can be confusing because the specification refers to the same passes
michael@0: as 1 to 7!  Be careful, you must check both the width and height before
michael@0: calling png_read_rows() and not call it for that pass if either is zero.
michael@0: 
michael@0: You can, of course, read each sub-image row by row.  If you want to
michael@0: produce optimal code to make a pixel-by-pixel transformation of an
michael@0: interlaced image this is the best approach; read each row of each pass,
michael@0: transform it, and write it out to a new interlaced image.
michael@0: 
michael@0: If you want to de-interlace the image yourself libpng provides further
michael@0: macros to help that tell you where to place the pixels in the output image.
michael@0: Because the interlacing scheme is rectangular - sub-image pixels are always
michael@0: arranged on a rectangular grid - all you need to know for each pass is the
michael@0: starting column and row in the output image of the first pixel plus the
michael@0: spacing between each pixel.  As of libpng 1.5 there are four macros to
michael@0: retrieve this information:
michael@0: 
michael@0:    png_uint_32 x = PNG_PASS_START_COL(pass);
michael@0:    png_uint_32 y = PNG_PASS_START_ROW(pass);
michael@0:    png_uint_32 xStep = 1U << PNG_PASS_COL_SHIFT(pass);
michael@0:    png_uint_32 yStep = 1U << PNG_PASS_ROW_SHIFT(pass);
michael@0: 
michael@0: These allow you to write the obvious loop:
michael@0: 
michael@0:    png_uint_32 input_y = 0;
michael@0:    png_uint_32 output_y = PNG_PASS_START_ROW(pass);
michael@0: 
michael@0:    while (output_y < output_image_height)
michael@0:    {
michael@0:       png_uint_32 input_x = 0;
michael@0:       png_uint_32 output_x = PNG_PASS_START_COL(pass);
michael@0: 
michael@0:       while (output_x < output_image_width)
michael@0:       {
michael@0:          image[output_y][output_x] =
michael@0:              subimage[pass][input_y][input_x++];
michael@0: 
michael@0:          output_x += xStep;
michael@0:       }
michael@0: 
michael@0:       ++input_y;
michael@0:       output_y += yStep;
michael@0:    }
michael@0: 
michael@0: Notice that the steps between successive output rows and columns are
michael@0: returned as shifts.  This is possible because the pixels in the subimages
michael@0: are always a power of 2 apart - 1, 2, 4 or 8 pixels - in the original
michael@0: image.  In practice you may need to directly calculate the output coordinate
michael@0: given an input coordinate.  libpng provides two further macros for this
michael@0: purpose:
michael@0: 
michael@0:    png_uint_32 output_x = PNG_COL_FROM_PASS_COL(input_x, pass);
michael@0:    png_uint_32 output_y = PNG_ROW_FROM_PASS_ROW(input_y, pass);
michael@0: 
michael@0: Finally a pair of macros are provided to tell you if a particular image
michael@0: row or column appears in a given pass:
michael@0: 
michael@0:    int col_in_pass = PNG_COL_IN_INTERLACE_PASS(output_x, pass);
michael@0:    int row_in_pass = PNG_ROW_IN_INTERLACE_PASS(output_y, pass);
michael@0: 
michael@0: Bear in mind that you will probably also need to check the width and height
michael@0: of the pass in addition to the above to be sure the pass even exists!
michael@0: 
michael@0: With any luck you are convinced by now that you don't want to do your own
michael@0: interlace handling.  In reality normally the only good reason for doing this
michael@0: is if you are processing PNG files on a pixel-by-pixel basis and don't want
michael@0: to load the whole file into memory when it is interlaced.
michael@0: 
michael@0: libpng includes a test program, pngvalid, that illustrates reading and
michael@0: writing of interlaced images.  If you can't get interlacing to work in your
michael@0: code and don't want to leave it to libpng (the recommended approach), see
michael@0: how pngvalid.c does it.
michael@0: 
michael@0: Finishing a sequential read
michael@0: 
michael@0: After you are finished reading the image through the
michael@0: low-level interface, you can finish reading the file.  If you are
michael@0: interested in comments or time, which may be stored either before or
michael@0: after the image data, you should pass the separate png_info struct if
michael@0: you want to keep the comments from before and after the image
michael@0: separate.
michael@0: 
michael@0:     png_infop end_info = png_create_info_struct(png_ptr);
michael@0: 
michael@0:     if (!end_info)
michael@0:     {
michael@0:        png_destroy_read_struct(&png_ptr, &info_ptr,
michael@0:            (png_infopp)NULL);
michael@0:        return (ERROR);
michael@0:     }
michael@0: 
michael@0:    png_read_end(png_ptr, end_info);
michael@0: 
michael@0: If you are not interested, you should still call png_read_end()
michael@0: but you can pass NULL, avoiding the need to create an end_info structure.
michael@0: 
michael@0:    png_read_end(png_ptr, (png_infop)NULL);
michael@0: 
michael@0: If you don't call png_read_end(), then your file pointer will be
michael@0: left pointing to the first chunk after the last IDAT, which is probably
michael@0: not what you want if you expect to read something beyond the end of
michael@0: the PNG datastream.
michael@0: 
michael@0: When you are done, you can free all memory allocated by libpng like this:
michael@0: 
michael@0:    png_destroy_read_struct(&png_ptr, &info_ptr,
michael@0:        &end_info);
michael@0: 
michael@0: or, if you didn't create an end_info structure,
michael@0: 
michael@0:    png_destroy_read_struct(&png_ptr, &info_ptr,
michael@0:        (png_infopp)NULL);
michael@0: 
michael@0: It is also possible to individually free the info_ptr members that
michael@0: point to libpng-allocated storage with the following function:
michael@0: 
michael@0:     png_free_data(png_ptr, info_ptr, mask, seq)
michael@0: 
michael@0:     mask - identifies data to be freed, a mask
michael@0:            containing the bitwise OR of one or
michael@0:            more of
michael@0:              PNG_FREE_PLTE, PNG_FREE_TRNS,
michael@0:              PNG_FREE_HIST, PNG_FREE_ICCP,
michael@0:              PNG_FREE_PCAL, PNG_FREE_ROWS,
michael@0:              PNG_FREE_SCAL, PNG_FREE_SPLT,
michael@0:              PNG_FREE_TEXT, PNG_FREE_UNKN,
michael@0:            or simply PNG_FREE_ALL
michael@0: 
michael@0:     seq  - sequence number of item to be freed
michael@0:            (-1 for all items)
michael@0: 
michael@0: This function may be safely called when the relevant storage has
michael@0: already been freed, or has not yet been allocated, or was allocated
michael@0: by the user and not by libpng,  and will in those cases do nothing.
michael@0: The "seq" parameter is ignored if only one item of the selected data
michael@0: type, such as PLTE, is allowed.  If "seq" is not -1, and multiple items
michael@0: are allowed for the data type identified in the mask, such as text or
michael@0: sPLT, only the n'th item in the structure is freed, where n is "seq".
michael@0: 
michael@0: The default behavior is only to free data that was allocated internally
michael@0: by libpng.  This can be changed, so that libpng will not free the data,
michael@0: or so that it will free data that was allocated by the user with png_malloc()
michael@0: or png_calloc() and passed in via a png_set_*() function, with
michael@0: 
michael@0:     png_data_freer(png_ptr, info_ptr, freer, mask)
michael@0: 
michael@0:     freer  - one of
michael@0:                PNG_DESTROY_WILL_FREE_DATA
michael@0:                PNG_SET_WILL_FREE_DATA
michael@0:                PNG_USER_WILL_FREE_DATA
michael@0: 
michael@0:     mask   - which data elements are affected
michael@0:              same choices as in png_free_data()
michael@0: 
michael@0: This function only affects data that has already been allocated.
michael@0: You can call this function after reading the PNG data but before calling
michael@0: any png_set_*() functions, to control whether the user or the png_set_*()
michael@0: function is responsible for freeing any existing data that might be present,
michael@0: and again after the png_set_*() functions to control whether the user
michael@0: or png_destroy_*() is supposed to free the data.  When the user assumes
michael@0: responsibility for libpng-allocated data, the application must use
michael@0: png_free() to free it, and when the user transfers responsibility to libpng
michael@0: for data that the user has allocated, the user must have used png_malloc()
michael@0: or png_calloc() to allocate it.
michael@0: 
michael@0: If you allocated your row_pointers in a single block, as suggested above in
michael@0: the description of the high level read interface, you must not transfer
michael@0: responsibility for freeing it to the png_set_rows or png_read_destroy function,
michael@0: because they would also try to free the individual row_pointers[i].
michael@0: 
michael@0: If you allocated text_ptr.text, text_ptr.lang, and text_ptr.translated_keyword
michael@0: separately, do not transfer responsibility for freeing text_ptr to libpng,
michael@0: because when libpng fills a png_text structure it combines these members with
michael@0: the key member, and png_free_data() will free only text_ptr.key.  Similarly,
michael@0: if you transfer responsibility for free'ing text_ptr from libpng to your
michael@0: application, your application must not separately free those members.
michael@0: 
michael@0: The png_free_data() function will turn off the "valid" flag for anything
michael@0: it frees.  If you need to turn the flag off for a chunk that was freed by
michael@0: your application instead of by libpng, you can use
michael@0: 
michael@0:     png_set_invalid(png_ptr, info_ptr, mask);
michael@0: 
michael@0:     mask - identifies the chunks to be made invalid,
michael@0:            containing the bitwise OR of one or
michael@0:            more of
michael@0:              PNG_INFO_gAMA, PNG_INFO_sBIT,
michael@0:              PNG_INFO_cHRM, PNG_INFO_PLTE,
michael@0:              PNG_INFO_tRNS, PNG_INFO_bKGD,
michael@0:              PNG_INFO_hIST, PNG_INFO_pHYs,
michael@0:              PNG_INFO_oFFs, PNG_INFO_tIME,
michael@0:              PNG_INFO_pCAL, PNG_INFO_sRGB,
michael@0:              PNG_INFO_iCCP, PNG_INFO_sPLT,
michael@0:              PNG_INFO_sCAL, PNG_INFO_IDAT
michael@0: 
michael@0: For a more compact example of reading a PNG image, see the file example.c.
michael@0: 
michael@0: Reading PNG files progressively
michael@0: 
michael@0: The progressive reader is slightly different from the non-progressive
michael@0: reader.  Instead of calling png_read_info(), png_read_rows(), and
michael@0: png_read_end(), you make one call to png_process_data(), which calls
michael@0: callbacks when it has the info, a row, or the end of the image.  You
michael@0: set up these callbacks with png_set_progressive_read_fn().  You don't
michael@0: have to worry about the input/output functions of libpng, as you are
michael@0: giving the library the data directly in png_process_data().  I will
michael@0: assume that you have read the section on reading PNG files above,
michael@0: so I will only highlight the differences (although I will show
michael@0: all of the code).
michael@0: 
michael@0: png_structp png_ptr;
michael@0: png_infop info_ptr;
michael@0: 
michael@0:  /*  An example code fragment of how you would
michael@0:      initialize the progressive reader in your
michael@0:      application. */
michael@0:  int
michael@0:  initialize_png_reader()
michael@0:  {
michael@0:     png_ptr = png_create_read_struct
michael@0:         (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
michael@0:          user_error_fn, user_warning_fn);
michael@0: 
michael@0:     if (!png_ptr)
michael@0:         return (ERROR);
michael@0: 
michael@0:     info_ptr = png_create_info_struct(png_ptr);
michael@0: 
michael@0:     if (!info_ptr)
michael@0:     {
michael@0:        png_destroy_read_struct(&png_ptr,
michael@0:           (png_infopp)NULL, (png_infopp)NULL);
michael@0:        return (ERROR);
michael@0:     }
michael@0: 
michael@0:     if (setjmp(png_jmpbuf(png_ptr)))
michael@0:     {
michael@0:        png_destroy_read_struct(&png_ptr, &info_ptr,
michael@0:           (png_infopp)NULL);
michael@0:        return (ERROR);
michael@0:     }
michael@0: 
michael@0:     /* This one's new.  You can provide functions
michael@0:        to be called when the header info is valid,
michael@0:        when each row is completed, and when the image
michael@0:        is finished.  If you aren't using all functions,
michael@0:        you can specify NULL parameters.  Even when all
michael@0:        three functions are NULL, you need to call
michael@0:        png_set_progressive_read_fn().  You can use
michael@0:        any struct as the user_ptr (cast to a void pointer
michael@0:        for the function call), and retrieve the pointer
michael@0:        from inside the callbacks using the function
michael@0: 
michael@0:           png_get_progressive_ptr(png_ptr);
michael@0: 
michael@0:        which will return a void pointer, which you have
michael@0:        to cast appropriately.
michael@0:      */
michael@0:     png_set_progressive_read_fn(png_ptr, (void *)user_ptr,
michael@0:         info_callback, row_callback, end_callback);
michael@0: 
michael@0:     return 0;
michael@0:  }
michael@0: 
michael@0:  /* A code fragment that you call as you receive blocks
michael@0:    of data */
michael@0:  int
michael@0:  process_data(png_bytep buffer, png_uint_32 length)
michael@0:  {
michael@0:     if (setjmp(png_jmpbuf(png_ptr)))
michael@0:     {
michael@0:        png_destroy_read_struct(&png_ptr, &info_ptr,
michael@0:            (png_infopp)NULL);
michael@0:        return (ERROR);
michael@0:     }
michael@0: 
michael@0:     /* This one's new also.  Simply give it a chunk
michael@0:        of data from the file stream (in order, of
michael@0:        course).  On machines with segmented memory
michael@0:        models machines, don't give it any more than
michael@0:        64K.  The library seems to run fine with sizes
michael@0:        of 4K. Although you can give it much less if
michael@0:        necessary (I assume you can give it chunks of
michael@0:        1 byte, I haven't tried less then 256 bytes
michael@0:        yet).  When this function returns, you may
michael@0:        want to display any rows that were generated
michael@0:        in the row callback if you don't already do
michael@0:        so there.
michael@0:      */
michael@0:     png_process_data(png_ptr, info_ptr, buffer, length);
michael@0: 
michael@0:     /* At this point you can call png_process_data_skip if
michael@0:        you want to handle data the library will skip yourself;
michael@0:        it simply returns the number of bytes to skip (and stops
michael@0:        libpng skipping that number of bytes on the next
michael@0:        png_process_data call).
michael@0:     return 0;
michael@0:  }
michael@0: 
michael@0:  /* This function is called (as set by
michael@0:     png_set_progressive_read_fn() above) when enough data
michael@0:     has been supplied so all of the header has been
michael@0:     read.
michael@0:  */
michael@0:  void
michael@0:  info_callback(png_structp png_ptr, png_infop info)
michael@0:  {
michael@0:     /* Do any setup here, including setting any of
michael@0:        the transformations mentioned in the Reading
michael@0:        PNG files section.  For now, you _must_ call
michael@0:        either png_start_read_image() or
michael@0:        png_read_update_info() after all the
michael@0:        transformations are set (even if you don't set
michael@0:        any).  You may start getting rows before
michael@0:        png_process_data() returns, so this is your
michael@0:        last chance to prepare for that.
michael@0: 
michael@0:        This is where you turn on interlace handling,
michael@0:        assuming you don't want to do it yourself.
michael@0: 
michael@0:        If you need to you can stop the processing of
michael@0:        your original input data at this point by calling
michael@0:        png_process_data_pause.  This returns the number
michael@0:        of unprocessed bytes from the last png_process_data
michael@0:        call - it is up to you to ensure that the next call
michael@0:        sees these bytes again.  If you don't want to bother
michael@0:        with this you can get libpng to cache the unread
michael@0:        bytes by setting the 'save' parameter (see png.h) but
michael@0:        then libpng will have to copy the data internally.
michael@0:      */
michael@0:  }
michael@0: 
michael@0:  /* This function is called when each row of image
michael@0:     data is complete */
michael@0:  void
michael@0:  row_callback(png_structp png_ptr, png_bytep new_row,
michael@0:     png_uint_32 row_num, int pass)
michael@0:  {
michael@0:     /* If the image is interlaced, and you turned
michael@0:        on the interlace handler, this function will
michael@0:        be called for every row in every pass.  Some
michael@0:        of these rows will not be changed from the
michael@0:        previous pass.  When the row is not changed,
michael@0:        the new_row variable will be NULL.  The rows
michael@0:        and passes are called in order, so you don't
michael@0:        really need the row_num and pass, but I'm
michael@0:        supplying them because it may make your life
michael@0:        easier.
michael@0: 
michael@0:        If you did not turn on interlace handling then
michael@0:        the callback is called for each row of each
michael@0:        sub-image when the image is interlaced.  In this
michael@0:        case 'row_num' is the row in the sub-image, not
michael@0:        the row in the output image as it is in all other
michael@0:        cases.
michael@0: 
michael@0:        For the non-NULL rows of interlaced images when
michael@0:        you have switched on libpng interlace handling,
michael@0:        you must call png_progressive_combine_row()
michael@0:        passing in the row and the old row.  You can
michael@0:        call this function for NULL rows (it will just
michael@0:        return) and for non-interlaced images (it just
michael@0:        does the memcpy for you) if it will make the
michael@0:        code easier.  Thus, you can just do this for
michael@0:        all cases if you switch on interlace handling;
michael@0:      */
michael@0: 
michael@0:         png_progressive_combine_row(png_ptr, old_row,
michael@0:           new_row);
michael@0: 
michael@0:     /* where old_row is what was displayed for
michael@0:        previously for the row.  Note that the first
michael@0:        pass (pass == 0, really) will completely cover
michael@0:        the old row, so the rows do not have to be
michael@0:        initialized.  After the first pass (and only
michael@0:        for interlaced images), you will have to pass
michael@0:        the current row, and the function will combine
michael@0:        the old row and the new row.
michael@0: 
michael@0:        You can also call png_process_data_pause in this
michael@0:        callback - see above.
michael@0:     */
michael@0:  }
michael@0: 
michael@0:  void
michael@0:  end_callback(png_structp png_ptr, png_infop info)
michael@0:  {
michael@0:     /* This function is called after the whole image
michael@0:        has been read, including any chunks after the
michael@0:        image (up to and including the IEND).  You
michael@0:        will usually have the same info chunk as you
michael@0:        had in the header, although some data may have
michael@0:        been added to the comments and time fields.
michael@0: 
michael@0:        Most people won't do much here, perhaps setting
michael@0:        a flag that marks the image as finished.
michael@0:      */
michael@0:  }
michael@0: 
michael@0: 
michael@0: 
michael@0: IV. Writing
michael@0: 
michael@0: Much of this is very similar to reading.  However, everything of
michael@0: importance is repeated here, so you won't have to constantly look
michael@0: back up in the reading section to understand writing.
michael@0: 
michael@0: Setup
michael@0: 
michael@0: You will want to do the I/O initialization before you get into libpng,
michael@0: so if it doesn't work, you don't have anything to undo. If you are not
michael@0: using the standard I/O functions, you will need to replace them with
michael@0: custom writing functions.  See the discussion under Customizing libpng.
michael@0: 
michael@0:     FILE *fp = fopen(file_name, "wb");
michael@0: 
michael@0:     if (!fp)
michael@0:        return (ERROR);
michael@0: 
michael@0: Next, png_struct and png_info need to be allocated and initialized.
michael@0: As these can be both relatively large, you may not want to store these
michael@0: on the stack, unless you have stack space to spare.  Of course, you
michael@0: will want to check if they return NULL.  If you are also reading,
michael@0: you won't want to name your read structure and your write structure
michael@0: both "png_ptr"; you can call them anything you like, such as
michael@0: "read_ptr" and "write_ptr".  Look at pngtest.c, for example.
michael@0: 
michael@0:     png_structp png_ptr = png_create_write_struct
michael@0:        (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
michael@0:         user_error_fn, user_warning_fn);
michael@0: 
michael@0:     if (!png_ptr)
michael@0:        return (ERROR);
michael@0: 
michael@0:     png_infop info_ptr = png_create_info_struct(png_ptr);
michael@0:     if (!info_ptr)
michael@0:     {
michael@0:        png_destroy_write_struct(&png_ptr,
michael@0:            (png_infopp)NULL);
michael@0:        return (ERROR);
michael@0:     }
michael@0: 
michael@0: If you want to use your own memory allocation routines,
michael@0: define PNG_USER_MEM_SUPPORTED and use
michael@0: png_create_write_struct_2() instead of png_create_write_struct():
michael@0: 
michael@0:     png_structp png_ptr = png_create_write_struct_2
michael@0:        (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
michael@0:         user_error_fn, user_warning_fn, (png_voidp)
michael@0:         user_mem_ptr, user_malloc_fn, user_free_fn);
michael@0: 
michael@0: After you have these structures, you will need to set up the
michael@0: error handling.  When libpng encounters an error, it expects to
michael@0: longjmp() back to your routine.  Therefore, you will need to call
michael@0: setjmp() and pass the png_jmpbuf(png_ptr).  If you
michael@0: write the file from different routines, you will need to update
michael@0: the png_jmpbuf(png_ptr) every time you enter a new routine that will
michael@0: call a png_*() function.  See your documentation of setjmp/longjmp
michael@0: for your compiler for more information on setjmp/longjmp.  See
michael@0: the discussion on libpng error handling in the Customizing Libpng
michael@0: section below for more information on the libpng error handling.
michael@0: 
michael@0:     if (setjmp(png_jmpbuf(png_ptr)))
michael@0:     {
michael@0:     png_destroy_write_struct(&png_ptr, &info_ptr);
michael@0:        fclose(fp);
michael@0:        return (ERROR);
michael@0:     }
michael@0:     ...
michael@0:     return;
michael@0: 
michael@0: If you would rather avoid the complexity of setjmp/longjmp issues,
michael@0: you can compile libpng with PNG_NO_SETJMP, in which case
michael@0: errors will result in a call to PNG_ABORT() which defaults to abort().
michael@0: 
michael@0: You can #define PNG_ABORT() to a function that does something
michael@0: more useful than abort(), as long as your function does not
michael@0: return.
michael@0: 
michael@0: Checking for invalid palette index on write was added at libpng
michael@0: 1.5.10.  If a pixel contains an invalid (out-of-range) index libpng issues
michael@0: a benign error.  This is enabled by default because this condition is an
michael@0: error according to the PNG specification, Clause 11.3.2, but the error can
michael@0: be ignored in each png_ptr with
michael@0: 
michael@0:    png_set_check_for_invalid_index(png_ptr, 0);
michael@0: 
michael@0: If the error is ignored, or if png_benign_error() treats it as a warning,
michael@0: any invalid pixels are written as-is by the encoder, resulting in an
michael@0: invalid PNG datastream as output.  In this case the application is
michael@0: responsible for ensuring that the pixel indexes are in range when it writes
michael@0: a PLTE chunk with fewer entries than the bit depth would allow.
michael@0: 
michael@0: Now you need to set up the output code.  The default for libpng is to
michael@0: use the C function fwrite().  If you use this, you will need to pass a
michael@0: valid FILE * in the function png_init_io().  Be sure that the file is
michael@0: opened in binary mode.  Again, if you wish to handle writing data in
michael@0: another way, see the discussion on libpng I/O handling in the Customizing
michael@0: Libpng section below.
michael@0: 
michael@0:     png_init_io(png_ptr, fp);
michael@0: 
michael@0: If you are embedding your PNG into a datastream such as MNG, and don't
michael@0: want libpng to write the 8-byte signature, or if you have already
michael@0: written the signature in your application, use
michael@0: 
michael@0:     png_set_sig_bytes(png_ptr, 8);
michael@0: 
michael@0: to inform libpng that it should not write a signature.
michael@0: 
michael@0: Write callbacks
michael@0: 
michael@0: At this point, you can set up a callback function that will be
michael@0: called after each row has been written, which you can use to control
michael@0: a progress meter or the like.  It's demonstrated in pngtest.c.
michael@0: You must supply a function
michael@0: 
michael@0:     void write_row_callback(png_structp png_ptr, png_uint_32 row,
michael@0:        int pass);
michael@0:     {
michael@0:       /* put your code here */
michael@0:     }
michael@0: 
michael@0: (You can give it another name that you like instead of "write_row_callback")
michael@0: 
michael@0: To inform libpng about your function, use
michael@0: 
michael@0:     png_set_write_status_fn(png_ptr, write_row_callback);
michael@0: 
michael@0: When this function is called the row has already been completely processed and
michael@0: it has also been written out.  The 'row' and 'pass' refer to the next row to be
michael@0: handled.  For the
michael@0: non-interlaced case the row that was just handled is simply one less than the
michael@0: passed in row number, and pass will always be 0.  For the interlaced case the
michael@0: same applies unless the row value is 0, in which case the row just handled was
michael@0: the last one from one of the preceding passes.  Because interlacing may skip a
michael@0: pass you cannot be sure that the preceding pass is just 'pass-1', if you really
michael@0: need to know what the last pass is record (row,pass) from the callback and use
michael@0: the last recorded value each time.
michael@0: 
michael@0: As with the user transform you can find the output row using the
michael@0: PNG_ROW_FROM_PASS_ROW macro.
michael@0: 
michael@0: You now have the option of modifying how the compression library will
michael@0: run.  The following functions are mainly for testing, but may be useful
michael@0: in some cases, like if you need to write PNG files extremely fast and
michael@0: are willing to give up some compression, or if you want to get the
michael@0: maximum possible compression at the expense of slower writing.  If you
michael@0: have no special needs in this area, let the library do what it wants by
michael@0: not calling this function at all, as it has been tuned to deliver a good
michael@0: speed/compression ratio. The second parameter to png_set_filter() is
michael@0: the filter method, for which the only valid values are 0 (as of the
michael@0: July 1999 PNG specification, version 1.2) or 64 (if you are writing
michael@0: a PNG datastream that is to be embedded in a MNG datastream).  The third
michael@0: parameter is a flag that indicates which filter type(s) are to be tested
michael@0: for each scanline.  See the PNG specification for details on the specific
michael@0: filter types.
michael@0: 
michael@0: 
michael@0:     /* turn on or off filtering, and/or choose
michael@0:        specific filters.  You can use either a single
michael@0:        PNG_FILTER_VALUE_NAME or the bitwise OR of one
michael@0:        or more PNG_FILTER_NAME masks.
michael@0:      */
michael@0:     png_set_filter(png_ptr, 0,
michael@0:        PNG_FILTER_NONE  | PNG_FILTER_VALUE_NONE |
michael@0:        PNG_FILTER_SUB   | PNG_FILTER_VALUE_SUB  |
michael@0:        PNG_FILTER_UP    | PNG_FILTER_VALUE_UP   |
michael@0:        PNG_FILTER_AVG   | PNG_FILTER_VALUE_AVG  |
michael@0:        PNG_FILTER_PAETH | PNG_FILTER_VALUE_PAETH|
michael@0:        PNG_ALL_FILTERS);
michael@0: 
michael@0: If an application wants to start and stop using particular filters during
michael@0: compression, it should start out with all of the filters (to ensure that
michael@0: the previous row of pixels will be stored in case it's needed later),
michael@0: and then add and remove them after the start of compression.
michael@0: 
michael@0: If you are writing a PNG datastream that is to be embedded in a MNG
michael@0: datastream, the second parameter can be either 0 or 64.
michael@0: 
michael@0: The png_set_compression_*() functions interface to the zlib compression
michael@0: library, and should mostly be ignored unless you really know what you are
michael@0: doing.  The only generally useful call is png_set_compression_level()
michael@0: which changes how much time zlib spends on trying to compress the image
michael@0: data.  See the Compression Library (zlib.h and algorithm.txt, distributed
michael@0: with zlib) for details on the compression levels.
michael@0: 
michael@0:     #include zlib.h
michael@0: 
michael@0:     /* Set the zlib compression level */
michael@0:     png_set_compression_level(png_ptr,
michael@0:         Z_BEST_COMPRESSION);
michael@0: 
michael@0:     /* Set other zlib parameters for compressing IDAT */
michael@0:     png_set_compression_mem_level(png_ptr, 8);
michael@0:     png_set_compression_strategy(png_ptr,
michael@0:         Z_DEFAULT_STRATEGY);
michael@0:     png_set_compression_window_bits(png_ptr, 15);
michael@0:     png_set_compression_method(png_ptr, 8);
michael@0:     png_set_compression_buffer_size(png_ptr, 8192)
michael@0: 
michael@0:     /* Set zlib parameters for text compression
michael@0:      * If you don't call these, the parameters
michael@0:      * fall back on those defined for IDAT chunks
michael@0:      */
michael@0:     png_set_text_compression_mem_level(png_ptr, 8);
michael@0:     png_set_text_compression_strategy(png_ptr,
michael@0:         Z_DEFAULT_STRATEGY);
michael@0:     png_set_text_compression_window_bits(png_ptr, 15);
michael@0:     png_set_text_compression_method(png_ptr, 8);
michael@0: 
michael@0: Setting the contents of info for output
michael@0: 
michael@0: You now need to fill in the png_info structure with all the data you
michael@0: wish to write before the actual image.  Note that the only thing you
michael@0: are allowed to write after the image is the text chunks and the time
michael@0: chunk (as of PNG Specification 1.2, anyway).  See png_write_end() and
michael@0: the latest PNG specification for more information on that.  If you
michael@0: wish to write them before the image, fill them in now, and flag that
michael@0: data as being valid.  If you want to wait until after the data, don't
michael@0: fill them until png_write_end().  For all the fields in png_info and
michael@0: their data types, see png.h.  For explanations of what the fields
michael@0: contain, see the PNG specification.
michael@0: 
michael@0: Some of the more important parts of the png_info are:
michael@0: 
michael@0:     png_set_IHDR(png_ptr, info_ptr, width, height,
michael@0:        bit_depth, color_type, interlace_type,
michael@0:        compression_type, filter_method)
michael@0: 
michael@0:     width          - holds the width of the image
michael@0:                      in pixels (up to 2^31).
michael@0: 
michael@0:     height         - holds the height of the image
michael@0:                      in pixels (up to 2^31).
michael@0: 
michael@0:     bit_depth      - holds the bit depth of one of the
michael@0:                      image channels.
michael@0:                      (valid values are 1, 2, 4, 8, 16
michael@0:                      and depend also on the
michael@0:                      color_type.  See also significant
michael@0:                      bits (sBIT) below).
michael@0: 
michael@0:     color_type     - describes which color/alpha
michael@0:                      channels are present.
michael@0:                      PNG_COLOR_TYPE_GRAY
michael@0:                         (bit depths 1, 2, 4, 8, 16)
michael@0:                      PNG_COLOR_TYPE_GRAY_ALPHA
michael@0:                         (bit depths 8, 16)
michael@0:                      PNG_COLOR_TYPE_PALETTE
michael@0:                         (bit depths 1, 2, 4, 8)
michael@0:                      PNG_COLOR_TYPE_RGB
michael@0:                         (bit_depths 8, 16)
michael@0:                      PNG_COLOR_TYPE_RGB_ALPHA
michael@0:                         (bit_depths 8, 16)
michael@0: 
michael@0:                      PNG_COLOR_MASK_PALETTE
michael@0:                      PNG_COLOR_MASK_COLOR
michael@0:                      PNG_COLOR_MASK_ALPHA
michael@0: 
michael@0:     interlace_type - PNG_INTERLACE_NONE or
michael@0:                      PNG_INTERLACE_ADAM7
michael@0: 
michael@0:     compression_type - (must be
michael@0:                      PNG_COMPRESSION_TYPE_DEFAULT)
michael@0: 
michael@0:     filter_method  - (must be PNG_FILTER_TYPE_DEFAULT
michael@0:                      or, if you are writing a PNG to
michael@0:                      be embedded in a MNG datastream,
michael@0:                      can also be
michael@0:                      PNG_INTRAPIXEL_DIFFERENCING)
michael@0: 
michael@0: If you call png_set_IHDR(), the call must appear before any of the
michael@0: other png_set_*() functions, because they might require access to some of
michael@0: the IHDR settings.  The remaining png_set_*() functions can be called
michael@0: in any order.
michael@0: 
michael@0: If you wish, you can reset the compression_type, interlace_type, or
michael@0: filter_method later by calling png_set_IHDR() again; if you do this, the
michael@0: width, height, bit_depth, and color_type must be the same in each call.
michael@0: 
michael@0:     png_set_PLTE(png_ptr, info_ptr, palette,
michael@0:        num_palette);
michael@0: 
michael@0:     palette        - the palette for the file
michael@0:                      (array of png_color)
michael@0:     num_palette    - number of entries in the palette
michael@0: 
michael@0:     png_set_gAMA(png_ptr, info_ptr, file_gamma);
michael@0:     png_set_gAMA_fixed(png_ptr, info_ptr, int_file_gamma);
michael@0: 
michael@0:     file_gamma     - the gamma at which the image was
michael@0:                      created (PNG_INFO_gAMA)
michael@0: 
michael@0:     int_file_gamma - 100,000 times the gamma at which
michael@0:                      the image was created
michael@0: 
michael@0:     png_set_cHRM(png_ptr, info_ptr,  white_x, white_y, red_x, red_y,
michael@0:                      green_x, green_y, blue_x, blue_y)
michael@0:     png_set_cHRM_XYZ(png_ptr, info_ptr, red_X, red_Y, red_Z, green_X,
michael@0:                      green_Y, green_Z, blue_X, blue_Y, blue_Z)
michael@0:     png_set_cHRM_fixed(png_ptr, info_ptr, int_white_x, int_white_y,
michael@0:                      int_red_x, int_red_y, int_green_x, int_green_y,
michael@0:                      int_blue_x, int_blue_y)
michael@0:     png_set_cHRM_XYZ_fixed(png_ptr, info_ptr, int_red_X, int_red_Y,
michael@0:                      int_red_Z, int_green_X, int_green_Y, int_green_Z,
michael@0:                      int_blue_X, int_blue_Y, int_blue_Z)
michael@0: 
michael@0:     {white,red,green,blue}_{x,y}
michael@0:                      A color space encoding specified using the chromaticities
michael@0:                      of the end points and the white point.
michael@0: 
michael@0:     {red,green,blue}_{X,Y,Z}
michael@0:                      A color space encoding specified using the encoding end
michael@0:                      points - the CIE tristimulus specification of the intended
michael@0:                      color of the red, green and blue channels in the PNG RGB
michael@0:                      data.  The white point is simply the sum of the three end
michael@0:                      points.
michael@0: 
michael@0:     png_set_sRGB(png_ptr, info_ptr, srgb_intent);
michael@0: 
michael@0:     srgb_intent    - the rendering intent
michael@0:                      (PNG_INFO_sRGB) The presence of
michael@0:                      the sRGB chunk means that the pixel
michael@0:                      data is in the sRGB color space.
michael@0:                      This chunk also implies specific
michael@0:                      values of gAMA and cHRM.  Rendering
michael@0:                      intent is the CSS-1 property that
michael@0:                      has been defined by the International
michael@0:                      Color Consortium
michael@0:                      (http://www.color.org).
michael@0:                      It can be one of
michael@0:                      PNG_sRGB_INTENT_SATURATION,
michael@0:                      PNG_sRGB_INTENT_PERCEPTUAL,
michael@0:                      PNG_sRGB_INTENT_ABSOLUTE, or
michael@0:                      PNG_sRGB_INTENT_RELATIVE.
michael@0: 
michael@0: 
michael@0:     png_set_sRGB_gAMA_and_cHRM(png_ptr, info_ptr,
michael@0:        srgb_intent);
michael@0: 
michael@0:     srgb_intent    - the rendering intent
michael@0:                      (PNG_INFO_sRGB) The presence of the
michael@0:                      sRGB chunk means that the pixel
michael@0:                      data is in the sRGB color space.
michael@0:                      This function also causes gAMA and
michael@0:                      cHRM chunks with the specific values
michael@0:                      that are consistent with sRGB to be
michael@0:                      written.
michael@0: 
michael@0:     png_set_iCCP(png_ptr, info_ptr, name, compression_type,
michael@0:                        profile, proflen);
michael@0: 
michael@0:     name             - The profile name.
michael@0: 
michael@0:     compression_type - The compression type; always
michael@0:                        PNG_COMPRESSION_TYPE_BASE for PNG 1.0.
michael@0:                        You may give NULL to this argument to
michael@0:                        ignore it.
michael@0: 
michael@0:     profile          - International Color Consortium color
michael@0:                        profile data. May contain NULs.
michael@0: 
michael@0:     proflen          - length of profile data in bytes.
michael@0: 
michael@0:     png_set_sBIT(png_ptr, info_ptr, sig_bit);
michael@0: 
michael@0:     sig_bit        - the number of significant bits for
michael@0:                      (PNG_INFO_sBIT) each of the gray, red,
michael@0:                      green, and blue channels, whichever are
michael@0:                      appropriate for the given color type
michael@0:                      (png_color_16)
michael@0: 
michael@0:     png_set_tRNS(png_ptr, info_ptr, trans_alpha,
michael@0:        num_trans, trans_color);
michael@0: 
michael@0:     trans_alpha    - array of alpha (transparency)
michael@0:                      entries for palette (PNG_INFO_tRNS)
michael@0: 
michael@0:     num_trans      - number of transparent entries
michael@0:                      (PNG_INFO_tRNS)
michael@0: 
michael@0:     trans_color    - graylevel or color sample values
michael@0:                      (in order red, green, blue) of the
michael@0:                      single transparent color for
michael@0:                      non-paletted images (PNG_INFO_tRNS)
michael@0: 
michael@0:     png_set_hIST(png_ptr, info_ptr, hist);
michael@0: 
michael@0:     hist           - histogram of palette (array of
michael@0:                      png_uint_16) (PNG_INFO_hIST)
michael@0: 
michael@0:     png_set_tIME(png_ptr, info_ptr, mod_time);
michael@0: 
michael@0:     mod_time       - time image was last modified
michael@0:                      (PNG_VALID_tIME)
michael@0: 
michael@0:     png_set_bKGD(png_ptr, info_ptr, background);
michael@0: 
michael@0:     background     - background color (of type
michael@0:                      png_color_16p) (PNG_VALID_bKGD)
michael@0: 
michael@0:     png_set_text(png_ptr, info_ptr, text_ptr, num_text);
michael@0: 
michael@0:     text_ptr       - array of png_text holding image
michael@0:                      comments
michael@0: 
michael@0:     text_ptr[i].compression - type of compression used
michael@0:                  on "text" PNG_TEXT_COMPRESSION_NONE
michael@0:                            PNG_TEXT_COMPRESSION_zTXt
michael@0:                            PNG_ITXT_COMPRESSION_NONE
michael@0:                            PNG_ITXT_COMPRESSION_zTXt
michael@0:     text_ptr[i].key   - keyword for comment.  Must contain
michael@0:                  1-79 characters.
michael@0:     text_ptr[i].text  - text comments for current
michael@0:                          keyword.  Can be NULL or empty.
michael@0:     text_ptr[i].text_length - length of text string,
michael@0:                  after decompression, 0 for iTXt
michael@0:     text_ptr[i].itxt_length - length of itxt string,
michael@0:                  after decompression, 0 for tEXt/zTXt
michael@0:     text_ptr[i].lang  - language of comment (NULL or
michael@0:                          empty for unknown).
michael@0:     text_ptr[i].translated_keyword  - keyword in UTF-8 (NULL
michael@0:                          or empty for unknown).
michael@0: 
michael@0:     Note that the itxt_length, lang, and lang_key
michael@0:     members of the text_ptr structure only exist when the
michael@0:     library is built with iTXt chunk support.  Prior to
michael@0:     libpng-1.4.0 the library was built by default without
michael@0:     iTXt support. Also note that when iTXt is supported,
michael@0:     they contain NULL pointers when the "compression"
michael@0:     field contains PNG_TEXT_COMPRESSION_NONE or
michael@0:     PNG_TEXT_COMPRESSION_zTXt.
michael@0: 
michael@0:     num_text       - number of comments
michael@0: 
michael@0:     png_set_sPLT(png_ptr, info_ptr, &palette_ptr,
michael@0:        num_spalettes);
michael@0: 
michael@0:     palette_ptr    - array of png_sPLT_struct structures
michael@0:                      to be added to the list of palettes
michael@0:                      in the info structure.
michael@0:     num_spalettes  - number of palette structures to be
michael@0:                      added.
michael@0: 
michael@0:     png_set_oFFs(png_ptr, info_ptr, offset_x, offset_y,
michael@0:         unit_type);
michael@0: 
michael@0:     offset_x  - positive offset from the left
michael@0:                      edge of the screen
michael@0: 
michael@0:     offset_y  - positive offset from the top
michael@0:                      edge of the screen
michael@0: 
michael@0:     unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER
michael@0: 
michael@0:     png_set_pHYs(png_ptr, info_ptr, res_x, res_y,
michael@0:         unit_type);
michael@0: 
michael@0:     res_x       - pixels/unit physical resolution
michael@0:                   in x direction
michael@0: 
michael@0:     res_y       - pixels/unit physical resolution
michael@0:                   in y direction
michael@0: 
michael@0:     unit_type   - PNG_RESOLUTION_UNKNOWN,
michael@0:                   PNG_RESOLUTION_METER
michael@0: 
michael@0:     png_set_sCAL(png_ptr, info_ptr, unit, width, height)
michael@0: 
michael@0:     unit        - physical scale units (an integer)
michael@0: 
michael@0:     width       - width of a pixel in physical scale units
michael@0: 
michael@0:     height      - height of a pixel in physical scale units
michael@0:                   (width and height are doubles)
michael@0: 
michael@0:     png_set_sCAL_s(png_ptr, info_ptr, unit, width, height)
michael@0: 
michael@0:     unit        - physical scale units (an integer)
michael@0: 
michael@0:     width       - width of a pixel in physical scale units
michael@0:                   expressed as a string
michael@0: 
michael@0:     height      - height of a pixel in physical scale units
michael@0:                  (width and height are strings like "2.54")
michael@0: 
michael@0:     png_set_unknown_chunks(png_ptr, info_ptr, &unknowns,
michael@0:        num_unknowns)
michael@0: 
michael@0:     unknowns          - array of png_unknown_chunk
michael@0:                         structures holding unknown chunks
michael@0:     unknowns[i].name  - name of unknown chunk
michael@0:     unknowns[i].data  - data of unknown chunk
michael@0:     unknowns[i].size  - size of unknown chunk's data
michael@0:     unknowns[i].location - position to write chunk in file
michael@0:                            0: do not write chunk
michael@0:                            PNG_HAVE_IHDR: before PLTE
michael@0:                            PNG_HAVE_PLTE: before IDAT
michael@0:                            PNG_AFTER_IDAT: after IDAT
michael@0: 
michael@0: The "location" member is set automatically according to
michael@0: what part of the output file has already been written.
michael@0: You can change its value after calling png_set_unknown_chunks()
michael@0: as demonstrated in pngtest.c.  Within each of the "locations",
michael@0: the chunks are sequenced according to their position in the
michael@0: structure (that is, the value of "i", which is the order in which
michael@0: the chunk was either read from the input file or defined with
michael@0: png_set_unknown_chunks).
michael@0: 
michael@0: A quick word about text and num_text.  text is an array of png_text
michael@0: structures.  num_text is the number of valid structures in the array.
michael@0: Each png_text structure holds a language code, a keyword, a text value,
michael@0: and a compression type.
michael@0: 
michael@0: The compression types have the same valid numbers as the compression
michael@0: types of the image data.  Currently, the only valid number is zero.
michael@0: However, you can store text either compressed or uncompressed, unlike
michael@0: images, which always have to be compressed.  So if you don't want the
michael@0: text compressed, set the compression type to PNG_TEXT_COMPRESSION_NONE.
michael@0: Because tEXt and zTXt chunks don't have a language field, if you
michael@0: specify PNG_TEXT_COMPRESSION_NONE or PNG_TEXT_COMPRESSION_zTXt
michael@0: any language code or translated keyword will not be written out.
michael@0: 
michael@0: Until text gets around a few hundred bytes, it is not worth compressing it.
michael@0: After the text has been written out to the file, the compression type
michael@0: is set to PNG_TEXT_COMPRESSION_NONE_WR or PNG_TEXT_COMPRESSION_zTXt_WR,
michael@0: so that it isn't written out again at the end (in case you are calling
michael@0: png_write_end() with the same struct).
michael@0: 
michael@0: The keywords that are given in the PNG Specification are:
michael@0: 
michael@0:     Title            Short (one line) title or
michael@0:                      caption for image
michael@0: 
michael@0:     Author           Name of image's creator
michael@0: 
michael@0:     Description      Description of image (possibly long)
michael@0: 
michael@0:     Copyright        Copyright notice
michael@0: 
michael@0:     Creation Time    Time of original image creation
michael@0:                      (usually RFC 1123 format, see below)
michael@0: 
michael@0:     Software         Software used to create the image
michael@0: 
michael@0:     Disclaimer       Legal disclaimer
michael@0: 
michael@0:     Warning          Warning of nature of content
michael@0: 
michael@0:     Source           Device used to create the image
michael@0: 
michael@0:     Comment          Miscellaneous comment; conversion
michael@0:                      from other image format
michael@0: 
michael@0: The keyword-text pairs work like this.  Keywords should be short
michael@0: simple descriptions of what the comment is about.  Some typical
michael@0: keywords are found in the PNG specification, as is some recommendations
michael@0: on keywords.  You can repeat keywords in a file.  You can even write
michael@0: some text before the image and some after.  For example, you may want
michael@0: to put a description of the image before the image, but leave the
michael@0: disclaimer until after, so viewers working over modem connections
michael@0: don't have to wait for the disclaimer to go over the modem before
michael@0: they start seeing the image.  Finally, keywords should be full
michael@0: words, not abbreviations.  Keywords and text are in the ISO 8859-1
michael@0: (Latin-1) character set (a superset of regular ASCII) and can not
michael@0: contain NUL characters, and should not contain control or other
michael@0: unprintable characters.  To make the comments widely readable, stick
michael@0: with basic ASCII, and avoid machine specific character set extensions
michael@0: like the IBM-PC character set.  The keyword must be present, but
michael@0: you can leave off the text string on non-compressed pairs.
michael@0: Compressed pairs must have a text string, as only the text string
michael@0: is compressed anyway, so the compression would be meaningless.
michael@0: 
michael@0: PNG supports modification time via the png_time structure.  Two
michael@0: conversion routines are provided, png_convert_from_time_t() for
michael@0: time_t and png_convert_from_struct_tm() for struct tm.  The
michael@0: time_t routine uses gmtime().  You don't have to use either of
michael@0: these, but if you wish to fill in the png_time structure directly,
michael@0: you should provide the time in universal time (GMT) if possible
michael@0: instead of your local time.  Note that the year number is the full
michael@0: year (e.g. 1998, rather than 98 - PNG is year 2000 compliant!), and
michael@0: that months start with 1.
michael@0: 
michael@0: If you want to store the time of the original image creation, you should
michael@0: use a plain tEXt chunk with the "Creation Time" keyword.  This is
michael@0: necessary because the "creation time" of a PNG image is somewhat vague,
michael@0: depending on whether you mean the PNG file, the time the image was
michael@0: created in a non-PNG format, a still photo from which the image was
michael@0: scanned, or possibly the subject matter itself.  In order to facilitate
michael@0: machine-readable dates, it is recommended that the "Creation Time"
michael@0: tEXt chunk use RFC 1123 format dates (e.g. "22 May 1997 18:07:10 GMT"),
michael@0: although this isn't a requirement.  Unlike the tIME chunk, the
michael@0: "Creation Time" tEXt chunk is not expected to be automatically changed
michael@0: by the software.  To facilitate the use of RFC 1123 dates, a function
michael@0: png_convert_to_rfc1123_buffer(png_ptr, buffer, png_timep) is provided to
michael@0: convert from PNG time to an RFC 1123 format string.  The caller must provide
michael@0: a writeable buffer of at least 29 bytes.
michael@0: 
michael@0: Writing unknown chunks
michael@0: 
michael@0: You can use the png_set_unknown_chunks function to queue up private chunks
michael@0: for writing.  You give it a chunk name, location, raw data, and a size.  You
michael@0: also must use png_set_keep_unknown_chunks() to ensure that libpng will
michael@0: handle them.  That's all there is to it.  The chunks will be written by the
michael@0: next following png_write_info_before_PLTE, png_write_info, or png_write_end
michael@0: function, depending upon the specified location.  Any chunks previously
michael@0: read into the info structure's unknown-chunk list will also be written out
michael@0: in a sequence that satisfies the PNG specification's ordering rules.
michael@0: 
michael@0: Here is an example of writing two private chunks, prVt and miNE:
michael@0: 
michael@0:     #ifdef PNG_WRITE_UNKNOWN_CHUNKS_SUPPORTED
michael@0:     /* Set unknown chunk data */
michael@0:     png_unknown_chunk unk_chunk[2];
michael@0:     strcpy((char *) unk_chunk[0].name, "prVt";
michael@0:     unk_chunk[0].data = (unsigned char *) "PRIVATE DATA";
michael@0:     unk_chunk[0].size = strlen(unk_chunk[0].data)+1;
michael@0:     unk_chunk[0].location = PNG_HAVE_IHDR;
michael@0:     strcpy((char *) unk_chunk[1].name, "miNE";
michael@0:     unk_chunk[1].data = (unsigned char *) "MY CHUNK DATA";
michael@0:     unk_chunk[1].size = strlen(unk_chunk[0].data)+1;
michael@0:     unk_chunk[1].location = PNG_AFTER_IDAT;
michael@0:     png_set_unknown_chunks(write_ptr, write_info_ptr,
michael@0:         unk_chunk, 2);
michael@0:     /* Needed because miNE is not safe-to-copy */
michael@0:     png_set_keep_unknown_chunks(png, PNG_HANDLE_CHUNK_ALWAYS,
michael@0:        (png_bytep) "miNE", 1);
michael@0:     # if PNG_LIBPNG_VER < 10600
michael@0:       /* Deal with unknown chunk location bug in 1.5.x and earlier */
michael@0:       png_set_unknown_chunk_location(png, info, 0, PNG_HAVE_IHDR);
michael@0:       png_set_unknown_chunk_location(png, info, 1, PNG_AFTER_IDAT);
michael@0:     # endif
michael@0:     # if PNG_LIBPNG_VER < 10500
michael@0:       /* PNG_AFTER_IDAT writes two copies of the chunk prior to libpng-1.5.0,
michael@0:        * one before IDAT and another after IDAT, so don't use it; only use
michael@0:        * PNG_HAVE_IHDR location.  This call resets the location previously
michael@0:        * set by assignment and png_set_unknown_chunk_location() for chunk 1.
michael@0:        */
michael@0:       png_set_unknown_chunk_location(png, info, 1, PNG_HAVE_IHDR);
michael@0:     # endif
michael@0:     #endif
michael@0: 
michael@0: The high-level write interface
michael@0: 
michael@0: At this point there are two ways to proceed; through the high-level
michael@0: write interface, or through a sequence of low-level write operations.
michael@0: You can use the high-level interface if your image data is present
michael@0: in the info structure.  All defined output
michael@0: transformations are permitted, enabled by the following masks.
michael@0: 
michael@0:     PNG_TRANSFORM_IDENTITY      No transformation
michael@0:     PNG_TRANSFORM_PACKING       Pack 1, 2 and 4-bit samples
michael@0:     PNG_TRANSFORM_PACKSWAP      Change order of packed
michael@0:                                 pixels to LSB first
michael@0:     PNG_TRANSFORM_INVERT_MONO   Invert monochrome images
michael@0:     PNG_TRANSFORM_SHIFT         Normalize pixels to the
michael@0:                                 sBIT depth
michael@0:     PNG_TRANSFORM_BGR           Flip RGB to BGR, RGBA
michael@0:                                 to BGRA
michael@0:     PNG_TRANSFORM_SWAP_ALPHA    Flip RGBA to ARGB or GA
michael@0:                                 to AG
michael@0:     PNG_TRANSFORM_INVERT_ALPHA  Change alpha from opacity
michael@0:                                 to transparency
michael@0:     PNG_TRANSFORM_SWAP_ENDIAN   Byte-swap 16-bit samples
michael@0:     PNG_TRANSFORM_STRIP_FILLER        Strip out filler
michael@0:                                       bytes (deprecated).
michael@0:     PNG_TRANSFORM_STRIP_FILLER_BEFORE Strip out leading
michael@0:                                       filler bytes
michael@0:     PNG_TRANSFORM_STRIP_FILLER_AFTER  Strip out trailing
michael@0:                                       filler bytes
michael@0: 
michael@0: If you have valid image data in the info structure (you can use
michael@0: png_set_rows() to put image data in the info structure), simply do this:
michael@0: 
michael@0:     png_write_png(png_ptr, info_ptr, png_transforms, NULL)
michael@0: 
michael@0: where png_transforms is an integer containing the bitwise OR of some set of
michael@0: transformation flags.  This call is equivalent to png_write_info(),
michael@0: followed the set of transformations indicated by the transform mask,
michael@0: then png_write_image(), and finally png_write_end().
michael@0: 
michael@0: (The final parameter of this call is not yet used.  Someday it might point
michael@0: to transformation parameters required by some future output transform.)
michael@0: 
michael@0: You must use png_transforms and not call any png_set_transform() functions
michael@0: when you use png_write_png().
michael@0: 
michael@0: The low-level write interface
michael@0: 
michael@0: If you are going the low-level route instead, you are now ready to
michael@0: write all the file information up to the actual image data.  You do
michael@0: this with a call to png_write_info().
michael@0: 
michael@0:     png_write_info(png_ptr, info_ptr);
michael@0: 
michael@0: Note that there is one transformation you may need to do before
michael@0: png_write_info().  In PNG files, the alpha channel in an image is the
michael@0: level of opacity.  If your data is supplied as a level of transparency,
michael@0: you can invert the alpha channel before you write it, so that 0 is
michael@0: fully transparent and 255 (in 8-bit or paletted images) or 65535
michael@0: (in 16-bit images) is fully opaque, with
michael@0: 
michael@0:     png_set_invert_alpha(png_ptr);
michael@0: 
michael@0: This must appear before png_write_info() instead of later with the
michael@0: other transformations because in the case of paletted images the tRNS
michael@0: chunk data has to be inverted before the tRNS chunk is written.  If
michael@0: your image is not a paletted image, the tRNS data (which in such cases
michael@0: represents a single color to be rendered as transparent) won't need to
michael@0: be changed, and you can safely do this transformation after your
michael@0: png_write_info() call.
michael@0: 
michael@0: If you need to write a private chunk that you want to appear before
michael@0: the PLTE chunk when PLTE is present, you can write the PNG info in
michael@0: two steps, and insert code to write your own chunk between them:
michael@0: 
michael@0:     png_write_info_before_PLTE(png_ptr, info_ptr);
michael@0:     png_set_unknown_chunks(png_ptr, info_ptr, ...);
michael@0:     png_write_info(png_ptr, info_ptr);
michael@0: 
michael@0: After you've written the file information, you can set up the library
michael@0: to handle any special transformations of the image data.  The various
michael@0: ways to transform the data will be described in the order that they
michael@0: should occur.  This is important, as some of these change the color
michael@0: type and/or bit depth of the data, and some others only work on
michael@0: certain color types and bit depths.  Even though each transformation
michael@0: checks to see if it has data that it can do something with, you should
michael@0: make sure to only enable a transformation if it will be valid for the
michael@0: data.  For example, don't swap red and blue on grayscale data.
michael@0: 
michael@0: PNG files store RGB pixels packed into 3 or 6 bytes.  This code tells
michael@0: the library to strip input data that has 4 or 8 bytes per pixel down
michael@0: to 3 or 6 bytes (or strip 2 or 4-byte grayscale+filler data to 1 or 2
michael@0: bytes per pixel).
michael@0: 
michael@0:     png_set_filler(png_ptr, 0, PNG_FILLER_BEFORE);
michael@0: 
michael@0: where the 0 is unused, and the location is either PNG_FILLER_BEFORE or
michael@0: PNG_FILLER_AFTER, depending upon whether the filler byte in the pixel
michael@0: is stored XRGB or RGBX.
michael@0: 
michael@0: PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as
michael@0: they can, resulting in, for example, 8 pixels per byte for 1 bit files.
michael@0: If the data is supplied at 1 pixel per byte, use this code, which will
michael@0: correctly pack the pixels into a single byte:
michael@0: 
michael@0:     png_set_packing(png_ptr);
michael@0: 
michael@0: PNG files reduce possible bit depths to 1, 2, 4, 8, and 16.  If your
michael@0: data is of another bit depth, you can write an sBIT chunk into the
michael@0: file so that decoders can recover the original data if desired.
michael@0: 
michael@0:     /* Set the true bit depth of the image data */
michael@0:     if (color_type & PNG_COLOR_MASK_COLOR)
michael@0:     {
michael@0:        sig_bit.red = true_bit_depth;
michael@0:        sig_bit.green = true_bit_depth;
michael@0:        sig_bit.blue = true_bit_depth;
michael@0:     }
michael@0: 
michael@0:     else
michael@0:     {
michael@0:        sig_bit.gray = true_bit_depth;
michael@0:     }
michael@0: 
michael@0:     if (color_type & PNG_COLOR_MASK_ALPHA)
michael@0:     {
michael@0:        sig_bit.alpha = true_bit_depth;
michael@0:     }
michael@0: 
michael@0:     png_set_sBIT(png_ptr, info_ptr, &sig_bit);
michael@0: 
michael@0: If the data is stored in the row buffer in a bit depth other than
michael@0: one supported by PNG (e.g. 3 bit data in the range 0-7 for a 4-bit PNG),
michael@0: this will scale the values to appear to be the correct bit depth as
michael@0: is required by PNG.
michael@0: 
michael@0:     png_set_shift(png_ptr, &sig_bit);
michael@0: 
michael@0: PNG files store 16-bit pixels in network byte order (big-endian,
michael@0: ie. most significant bits first).  This code would be used if they are
michael@0: supplied the other way (little-endian, i.e. least significant bits
michael@0: first, the way PCs store them):
michael@0: 
michael@0:     if (bit_depth > 8)
michael@0:        png_set_swap(png_ptr);
michael@0: 
michael@0: If you are using packed-pixel images (1, 2, or 4 bits/pixel), and you
michael@0: need to change the order the pixels are packed into bytes, you can use:
michael@0: 
michael@0:     if (bit_depth < 8)
michael@0:        png_set_packswap(png_ptr);
michael@0: 
michael@0: PNG files store 3 color pixels in red, green, blue order.  This code
michael@0: would be used if they are supplied as blue, green, red:
michael@0: 
michael@0:     png_set_bgr(png_ptr);
michael@0: 
michael@0: PNG files describe monochrome as black being zero and white being
michael@0: one. This code would be used if the pixels are supplied with this reversed
michael@0: (black being one and white being zero):
michael@0: 
michael@0:     png_set_invert_mono(png_ptr);
michael@0: 
michael@0: Finally, you can write your own transformation function if none of
michael@0: the existing ones meets your needs.  This is done by setting a callback
michael@0: with
michael@0: 
michael@0:     png_set_write_user_transform_fn(png_ptr,
michael@0:        write_transform_fn);
michael@0: 
michael@0: You must supply the function
michael@0: 
michael@0:     void write_transform_fn(png_structp png_ptr, png_row_infop
michael@0:        row_info, png_bytep data)
michael@0: 
michael@0: See pngtest.c for a working example.  Your function will be called
michael@0: before any of the other transformations are processed.  If supported
michael@0: libpng also supplies an information routine that may be called from
michael@0: your callback:
michael@0: 
michael@0:    png_get_current_row_number(png_ptr);
michael@0:    png_get_current_pass_number(png_ptr);
michael@0: 
michael@0: This returns the current row passed to the transform.  With interlaced
michael@0: images the value returned is the row in the input sub-image image.  Use
michael@0: PNG_ROW_FROM_PASS_ROW(row, pass) and PNG_COL_FROM_PASS_COL(col, pass) to
michael@0: find the output pixel (x,y) given an interlaced sub-image pixel (row,col,pass).
michael@0: 
michael@0: The discussion of interlace handling above contains more information on how to
michael@0: use these values.
michael@0: 
michael@0: You can also set up a pointer to a user structure for use by your
michael@0: callback function.
michael@0: 
michael@0:     png_set_user_transform_info(png_ptr, user_ptr, 0, 0);
michael@0: 
michael@0: The user_channels and user_depth parameters of this function are ignored
michael@0: when writing; you can set them to zero as shown.
michael@0: 
michael@0: You can retrieve the pointer via the function png_get_user_transform_ptr().
michael@0: For example:
michael@0: 
michael@0:     voidp write_user_transform_ptr =
michael@0:        png_get_user_transform_ptr(png_ptr);
michael@0: 
michael@0: It is possible to have libpng flush any pending output, either manually,
michael@0: or automatically after a certain number of lines have been written.  To
michael@0: flush the output stream a single time call:
michael@0: 
michael@0:     png_write_flush(png_ptr);
michael@0: 
michael@0: and to have libpng flush the output stream periodically after a certain
michael@0: number of scanlines have been written, call:
michael@0: 
michael@0:     png_set_flush(png_ptr, nrows);
michael@0: 
michael@0: Note that the distance between rows is from the last time png_write_flush()
michael@0: was called, or the first row of the image if it has never been called.
michael@0: So if you write 50 lines, and then png_set_flush 25, it will flush the
michael@0: output on the next scanline, and every 25 lines thereafter, unless
michael@0: png_write_flush() is called before 25 more lines have been written.
michael@0: If nrows is too small (less than about 10 lines for a 640 pixel wide
michael@0: RGB image) the image compression may decrease noticeably (although this
michael@0: may be acceptable for real-time applications).  Infrequent flushing will
michael@0: only degrade the compression performance by a few percent over images
michael@0: that do not use flushing.
michael@0: 
michael@0: Writing the image data
michael@0: 
michael@0: That's it for the transformations.  Now you can write the image data.
michael@0: The simplest way to do this is in one function call.  If you have the
michael@0: whole image in memory, you can just call png_write_image() and libpng
michael@0: will write the image.  You will need to pass in an array of pointers to
michael@0: each row.  This function automatically handles interlacing, so you don't
michael@0: need to call png_set_interlace_handling() or call this function multiple
michael@0: times, or any of that other stuff necessary with png_write_rows().
michael@0: 
michael@0:     png_write_image(png_ptr, row_pointers);
michael@0: 
michael@0: where row_pointers is:
michael@0: 
michael@0:     png_byte *row_pointers[height];
michael@0: 
michael@0: You can point to void or char or whatever you use for pixels.
michael@0: 
michael@0: If you don't want to write the whole image at once, you can
michael@0: use png_write_rows() instead.  If the file is not interlaced,
michael@0: this is simple:
michael@0: 
michael@0:     png_write_rows(png_ptr, row_pointers,
michael@0:        number_of_rows);
michael@0: 
michael@0: row_pointers is the same as in the png_write_image() call.
michael@0: 
michael@0: If you are just writing one row at a time, you can do this with
michael@0: a single row_pointer instead of an array of row_pointers:
michael@0: 
michael@0:     png_bytep row_pointer = row;
michael@0: 
michael@0:     png_write_row(png_ptr, row_pointer);
michael@0: 
michael@0: When the file is interlaced, things can get a good deal more complicated.
michael@0: The only currently (as of the PNG Specification version 1.2, dated July
michael@0: 1999) defined interlacing scheme for PNG files is the "Adam7" interlace
michael@0: scheme, that breaks down an image into seven smaller images of varying
michael@0: size.  libpng will build these images for you, or you can do them
michael@0: yourself.  If you want to build them yourself, see the PNG specification
michael@0: for details of which pixels to write when.
michael@0: 
michael@0: If you don't want libpng to handle the interlacing details, just
michael@0: use png_set_interlace_handling() and call png_write_rows() the
michael@0: correct number of times to write all the sub-images
michael@0: (png_set_interlace_handling() returns the number of sub-images.)
michael@0: 
michael@0: If you want libpng to build the sub-images, call this before you start
michael@0: writing any rows:
michael@0: 
michael@0:     number_of_passes = png_set_interlace_handling(png_ptr);
michael@0: 
michael@0: This will return the number of passes needed.  Currently, this is seven,
michael@0: but may change if another interlace type is added.
michael@0: 
michael@0: Then write the complete image number_of_passes times.
michael@0: 
michael@0:     png_write_rows(png_ptr, row_pointers, number_of_rows);
michael@0: 
michael@0: Think carefully before you write an interlaced image.  Typically code that
michael@0: reads such images reads all the image data into memory, uncompressed, before
michael@0: doing any processing.  Only code that can display an image on the fly can
michael@0: take advantage of the interlacing and even then the image has to be exactly
michael@0: the correct size for the output device, because scaling an image requires
michael@0: adjacent pixels and these are not available until all the passes have been
michael@0: read.
michael@0: 
michael@0: If you do write an interlaced image you will hardly ever need to handle
michael@0: the interlacing yourself.  Call png_set_interlace_handling() and use the
michael@0: approach described above.
michael@0: 
michael@0: The only time it is conceivable that you will really need to write an
michael@0: interlaced image pass-by-pass is when you have read one pass by pass and
michael@0: made some pixel-by-pixel transformation to it, as described in the read
michael@0: code above.  In this case use the PNG_PASS_ROWS and PNG_PASS_COLS macros
michael@0: to determine the size of each sub-image in turn and simply write the rows
michael@0: you obtained from the read code.
michael@0: 
michael@0: Finishing a sequential write
michael@0: 
michael@0: After you are finished writing the image, you should finish writing
michael@0: the file.  If you are interested in writing comments or time, you should
michael@0: pass an appropriately filled png_info pointer.  If you are not interested,
michael@0: you can pass NULL.
michael@0: 
michael@0:     png_write_end(png_ptr, info_ptr);
michael@0: 
michael@0: When you are done, you can free all memory used by libpng like this:
michael@0: 
michael@0:     png_destroy_write_struct(&png_ptr, &info_ptr);
michael@0: 
michael@0: It is also possible to individually free the info_ptr members that
michael@0: point to libpng-allocated storage with the following function:
michael@0: 
michael@0:     png_free_data(png_ptr, info_ptr, mask, seq)
michael@0: 
michael@0:     mask  - identifies data to be freed, a mask
michael@0:             containing the bitwise OR of one or
michael@0:             more of
michael@0:               PNG_FREE_PLTE, PNG_FREE_TRNS,
michael@0:               PNG_FREE_HIST, PNG_FREE_ICCP,
michael@0:               PNG_FREE_PCAL, PNG_FREE_ROWS,
michael@0:               PNG_FREE_SCAL, PNG_FREE_SPLT,
michael@0:               PNG_FREE_TEXT, PNG_FREE_UNKN,
michael@0:             or simply PNG_FREE_ALL
michael@0: 
michael@0:     seq   - sequence number of item to be freed
michael@0:             (-1 for all items)
michael@0: 
michael@0: This function may be safely called when the relevant storage has
michael@0: already been freed, or has not yet been allocated, or was allocated
michael@0: by the user  and not by libpng,  and will in those cases do nothing.
michael@0: The "seq" parameter is ignored if only one item of the selected data
michael@0: type, such as PLTE, is allowed.  If "seq" is not -1, and multiple items
michael@0: are allowed for the data type identified in the mask, such as text or
michael@0: sPLT, only the n'th item in the structure is freed, where n is "seq".
michael@0: 
michael@0: If you allocated data such as a palette that you passed in to libpng
michael@0: with png_set_*, you must not free it until just before the call to
michael@0: png_destroy_write_struct().
michael@0: 
michael@0: The default behavior is only to free data that was allocated internally
michael@0: by libpng.  This can be changed, so that libpng will not free the data,
michael@0: or so that it will free data that was allocated by the user with png_malloc()
michael@0: or png_calloc() and passed in via a png_set_*() function, with
michael@0: 
michael@0:     png_data_freer(png_ptr, info_ptr, freer, mask)
michael@0: 
michael@0:     freer  - one of
michael@0:                PNG_DESTROY_WILL_FREE_DATA
michael@0:                PNG_SET_WILL_FREE_DATA
michael@0:                PNG_USER_WILL_FREE_DATA
michael@0: 
michael@0:     mask   - which data elements are affected
michael@0:              same choices as in png_free_data()
michael@0: 
michael@0: For example, to transfer responsibility for some data from a read structure
michael@0: to a write structure, you could use
michael@0: 
michael@0:     png_data_freer(read_ptr, read_info_ptr,
michael@0:        PNG_USER_WILL_FREE_DATA,
michael@0:        PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST)
michael@0: 
michael@0:     png_data_freer(write_ptr, write_info_ptr,
michael@0:        PNG_DESTROY_WILL_FREE_DATA,
michael@0:        PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST)
michael@0: 
michael@0: thereby briefly reassigning responsibility for freeing to the user but
michael@0: immediately afterwards reassigning it once more to the write_destroy
michael@0: function.  Having done this, it would then be safe to destroy the read
michael@0: structure and continue to use the PLTE, tRNS, and hIST data in the write
michael@0: structure.
michael@0: 
michael@0: This function only affects data that has already been allocated.
michael@0: You can call this function before calling after the png_set_*() functions
michael@0: to control whether the user or png_destroy_*() is supposed to free the data.
michael@0: When the user assumes responsibility for libpng-allocated data, the
michael@0: application must use
michael@0: png_free() to free it, and when the user transfers responsibility to libpng
michael@0: for data that the user has allocated, the user must have used png_malloc()
michael@0: or png_calloc() to allocate it.
michael@0: 
michael@0: If you allocated text_ptr.text, text_ptr.lang, and text_ptr.translated_keyword
michael@0: separately, do not transfer responsibility for freeing text_ptr to libpng,
michael@0: because when libpng fills a png_text structure it combines these members with
michael@0: the key member, and png_free_data() will free only text_ptr.key.  Similarly,
michael@0: if you transfer responsibility for free'ing text_ptr from libpng to your
michael@0: application, your application must not separately free those members.
michael@0: For a more compact example of writing a PNG image, see the file example.c.
michael@0: 
michael@0: V. Simplified API
michael@0: 
michael@0: The simplified API, which became available in libpng-1.6.0, hides the details
michael@0: of both libpng and the PNG file format itself.
michael@0: It allows PNG files to be read into a very limited number of
michael@0: in-memory bitmap formats or to be written from the same formats.  If these
michael@0: formats do not accommodate your needs then you can, and should, use the more
michael@0: sophisticated APIs above - these support a wide variety of in-memory formats
michael@0: and a wide variety of sophisticated transformations to those formats as well
michael@0: as a wide variety of APIs to manipulate ancilliary information.
michael@0: 
michael@0: To read a PNG file using the simplified API:
michael@0: 
michael@0:   1) Declare a 'png_image' structure (see below) on the
michael@0:      stack and memset() it to all zero.
michael@0: 
michael@0:   2) Call the appropriate png_image_begin_read... function.
michael@0: 
michael@0:   3) Set the png_image 'format' member to the required
michael@0:      format and allocate a buffer for the image.
michael@0: 
michael@0:   4) Call png_image_finish_read to read the image into
michael@0:      your buffer.
michael@0: 
michael@0: There are no restrictions on the format of the PNG input itself; all valid
michael@0: color types, bit depths, and interlace methods are acceptable, and the
michael@0: input image is transformed as necessary to the requested in-memory format
michael@0: during the png_image_finish_read() step.
michael@0: 
michael@0: To write a PNG file using the simplified API:
michael@0: 
michael@0:   1) Declare a 'png_image' structure on the stack and memset()
michael@0:      it to all zero.
michael@0: 
michael@0:   2) Initialize the members of the structure that describe the
michael@0:      image, setting the 'format' member to the format of the
michael@0:      image in memory.
michael@0: 
michael@0:   3) Call the appropriate png_image_write... function with a
michael@0:      pointer to the image to write the PNG data.
michael@0: 
michael@0: png_image is a structure that describes the in-memory format of an image
michael@0: when it is being read or define the in-memory format of an image that you
michael@0: need to write.  The "png_image" structure contains the following members:
michael@0: 
michael@0:    png_uint_32  version Set to PNG_IMAGE_VERSION
michael@0:    png_uint_32  width   Image width in pixels (columns)
michael@0:    png_uint_32  height  Image height in pixels (rows)
michael@0:    png_uint_32  format  Image format as defined below
michael@0:    png_uint_32  flags   A bit mask containing informational flags
michael@0:    png_controlp opaque  Initialize to NULL, free with png_image_free
michael@0:    png_uint_32  colormap_entries; Number of entries in the color-map
michael@0:    png_uint_32  warning_or_error;
michael@0:    char         message[64];
michael@0: 
michael@0: In the event of an error or warning the following field warning_or_error
michael@0: field will be set to a non-zero value and the 'message' field will contain
michael@0: a '\0' terminated string with the libpng error or warning message.  If both
michael@0: warnings and an error were encountered, only the error is recorded.  If there
michael@0: are multiple warnings, only the first one is recorded.
michael@0: 
michael@0: The upper 30 bits of this value are reserved; the low two bits contain
michael@0: a two bit code such that a value more than 1 indicates a failure in the API
michael@0: just called:
michael@0: 
michael@0:    0 - no warning or error
michael@0:    1 - warning
michael@0:    2 - error
michael@0:    3 - error preceded by warning
michael@0: 
michael@0: The pixels (samples) of the image have one to four channels whose components
michael@0: have original values in the range 0 to 1.0:
michael@0: 
michael@0:   1: A single gray or luminance channel (G).
michael@0:   2: A gray/luminance channel and an alpha channel (GA).
michael@0:   3: Three red, green, blue color channels (RGB).
michael@0:   4: Three color channels and an alpha channel (RGBA).
michael@0: 
michael@0: The channels are encoded in one of two ways:
michael@0: 
michael@0:   a) As a small integer, value 0..255, contained in a single byte.  For the
michael@0: alpha channel the original value is simply value/255.  For the color or
michael@0: luminance channels the value is encoded according to the sRGB specification
michael@0: and matches the 8-bit format expected by typical display devices.
michael@0: 
michael@0: The color/gray channels are not scaled (pre-multiplied) by the alpha
michael@0: channel and are suitable for passing to color management software.
michael@0: 
michael@0:   b) As a value in the range 0..65535, contained in a 2-byte integer.  All
michael@0: channels can be converted to the original value by dividing by 65535; all
michael@0: channels are linear.  Color channels use the RGB encoding (RGB end-points) of
michael@0: the sRGB specification.  This encoding is identified by the
michael@0: PNG_FORMAT_FLAG_LINEAR flag below.
michael@0: 
michael@0: When an alpha channel is present it is expected to denote pixel coverage
michael@0: of the color or luminance channels and is returned as an associated alpha
michael@0: channel: the color/gray channels are scaled (pre-multiplied) by the alpha
michael@0: value.
michael@0: 
michael@0: When a color-mapped image is used as a result of calling
michael@0: png_image_read_colormap or png_image_write_colormap the channels are encoded
michael@0: in the color-map and the descriptions above apply to the color-map entries.
michael@0: The image data is encoded as small integers, value 0..255, that index the
michael@0: entries in the color-map.  One integer (one byte) is stored for each pixel.
michael@0: 
michael@0: PNG_FORMAT_*
michael@0: 
michael@0: The #defines to be used in png_image::format.  Each #define identifies a
michael@0: particular layout of channel data and, if present, alpha values.  There are
michael@0: separate defines for each of the two channel encodings.
michael@0: 
michael@0: A format is built up using single bit flag values.  Not all combinations are
michael@0: valid: use the bit flag values below for testing a format returned by the
michael@0: read APIs, but set formats from the derived values.
michael@0: 
michael@0: When reading or writing color-mapped images the format should be set to the
michael@0: format of the entries in the color-map then png_image_{read,write}_colormap
michael@0: called to read or write the color-map and set the format correctly for the
michael@0: image data.  Do not set the PNG_FORMAT_FLAG_COLORMAP bit directly!
michael@0: 
michael@0: NOTE: libpng can be built with particular features disabled, if you see
michael@0: compiler errors because the definition of one of the following flags has been
michael@0: compiled out it is because libpng does not have the required support.  It is
michael@0: possible, however, for the libpng configuration to enable the format on just
michael@0: read or just write; in that case you may see an error at run time.  You can
michael@0: guard against this by checking for the definition of:
michael@0: 
michael@0:    PNG_SIMPLIFIED_{READ,WRITE}_{BGR,AFIRST}_SUPPORTED
michael@0: 
michael@0:    PNG_FORMAT_FLAG_ALPHA    0x01 format with an alpha channel
michael@0:    PNG_FORMAT_FLAG_COLOR    0x02 color format: otherwise grayscale
michael@0:    PNG_FORMAT_FLAG_LINEAR   0x04 png_uint_16 channels else png_byte
michael@0:    PNG_FORMAT_FLAG_COLORMAP 0x08 libpng use only
michael@0:    PNG_FORMAT_FLAG_BGR      0x10 BGR colors, else order is RGB
michael@0:    PNG_FORMAT_FLAG_AFIRST   0x20 alpha channel comes first
michael@0: 
michael@0: Supported formats are as follows.  Future versions of libpng may support more
michael@0: formats; for compatibility with older versions simply check if the format
michael@0: macro is defined using #ifdef.  These defines describe the in-memory layout
michael@0: of the components of the pixels of the image.
michael@0: 
michael@0: First the single byte formats:
michael@0: 
michael@0:    PNG_FORMAT_GRAY 0
michael@0:    PNG_FORMAT_GA   PNG_FORMAT_FLAG_ALPHA
michael@0:    PNG_FORMAT_AG   (PNG_FORMAT_GA|PNG_FORMAT_FLAG_AFIRST)
michael@0:    PNG_FORMAT_RGB  PNG_FORMAT_FLAG_COLOR
michael@0:    PNG_FORMAT_BGR  (PNG_FORMAT_FLAG_COLOR|PNG_FORMAT_FLAG_BGR)
michael@0:    PNG_FORMAT_RGBA (PNG_FORMAT_RGB|PNG_FORMAT_FLAG_ALPHA)
michael@0:    PNG_FORMAT_ARGB (PNG_FORMAT_RGBA|PNG_FORMAT_FLAG_AFIRST)
michael@0:    PNG_FORMAT_BGRA (PNG_FORMAT_BGR|PNG_FORMAT_FLAG_ALPHA)
michael@0:    PNG_FORMAT_ABGR (PNG_FORMAT_BGRA|PNG_FORMAT_FLAG_AFIRST)
michael@0: 
michael@0: Then the linear 2-byte formats.  When naming these "Y" is used to
michael@0: indicate a luminance (gray) channel.  The component order within the pixel
michael@0: is always the same - there is no provision for swapping the order of the
michael@0: components in the linear format.
michael@0: 
michael@0:    PNG_FORMAT_LINEAR_Y PNG_FORMAT_FLAG_LINEAR
michael@0:    PNG_FORMAT_LINEAR_Y_ALPHA
michael@0:       (PNG_FORMAT_FLAG_LINEAR|PNG_FORMAT_FLAG_ALPHA)
michael@0:    PNG_FORMAT_LINEAR_RGB
michael@0:       (PNG_FORMAT_FLAG_LINEAR|PNG_FORMAT_FLAG_COLOR)
michael@0:    PNG_FORMAT_LINEAR_RGB_ALPHA
michael@0:       (PNG_FORMAT_FLAG_LINEAR|PNG_FORMAT_FLAG_COLOR|
michael@0:       PNG_FORMAT_FLAG_ALPHA)
michael@0: 
michael@0: Color-mapped formats are obtained by calling png_image_{read,write}_colormap,
michael@0: as appropriate after setting png_image::format to the format of the color-map
michael@0: to be read or written.  Applications may check the value of
michael@0: PNG_FORMAT_FLAG_COLORMAP to see if they have called the colormap API.  The
michael@0: format of the color-map may be extracted using the following macro.
michael@0: 
michael@0:    PNG_FORMAT_OF_COLORMAP(fmt) ((fmt) & ~PNG_FORMAT_FLAG_COLORMAP)
michael@0: 
michael@0: PNG_IMAGE macros
michael@0: 
michael@0: These are convenience macros to derive information from a png_image
michael@0: structure.  The PNG_IMAGE_SAMPLE_ macros return values appropriate to the
michael@0: actual image sample values - either the entries in the color-map or the
michael@0: pixels in the image.  The PNG_IMAGE_PIXEL_ macros return corresponding values
michael@0: for the pixels and will always return 1 after a call to
michael@0: png_image_{read,write}_colormap.  The remaining macros return information
michael@0: about the rows in the image and the complete image.
michael@0: 
michael@0: NOTE: All the macros that take a png_image::format parameter are compile time
michael@0: constants if the format parameter is, itself, a constant.  Therefore these
michael@0: macros can be used in array declarations and case labels where required.
michael@0: Similarly the macros are also pre-processor constants (sizeof is not used) so
michael@0: they can be used in #if tests.
michael@0: 
michael@0: First the information about the samples.
michael@0: 
michael@0:   PNG_IMAGE_SAMPLE_CHANNELS(fmt)
michael@0:     Returns the total number of channels in a given format: 1..4
michael@0: 
michael@0:   PNG_IMAGE_SAMPLE_COMPONENT_SIZE(fmt)
michael@0:     Returns the size in bytes of a single component of a pixel or color-map
michael@0:     entry (as appropriate) in the image.
michael@0: 
michael@0:   PNG_IMAGE_SAMPLE_SIZE(fmt)
michael@0:     This is the size of the sample data for one sample.  If the image is
michael@0:     color-mapped it is the size of one color-map entry (and image pixels are
michael@0:     one byte in size), otherwise it is the size of one image pixel.
michael@0: 
michael@0:   PNG_IMAGE_COLORMAP_SIZE(fmt)
michael@0:    The size of the color-map required by the format; this is the size of the
michael@0:    color-map buffer passed to the png_image_{read,write}_colormap APIs, it is
michael@0:    a fixed number determined by the format so can easily be allocated on the
michael@0:    stack if necessary.
michael@0: 
michael@0: #define PNG_IMAGE_MAXIMUM_COLORMAP_COMPONENTS(fmt)\
michael@0:    (PNG_IMAGE_SAMPLE_CHANNELS(fmt) * 256)
michael@0:    /* The maximum size of the color-map required by the format expressed in a
michael@0:     * count of components.  This can be used to compile-time allocate a
michael@0:     * color-map:
michael@0:     *
michael@0:     * png_uint_16 colormap[PNG_IMAGE_MAXIMUM_COLORMAP_COMPONENTS(linear_fmt)];
michael@0:     *
michael@0:     * png_byte colormap[PNG_IMAGE_MAXIMUM_COLORMAP_COMPONENTS(sRGB_fmt)];
michael@0:     *
michael@0:     * Alternatively use the PNG_IMAGE_COLORMAP_SIZE macro below to use the
michael@0:     * information from one of the png_image_begin_read_ APIs and dynamically
michael@0:     * allocate the required memory.
michael@0:     */
michael@0: 
michael@0: 
michael@0: Corresponding information about the pixels
michael@0: 
michael@0:   PNG_IMAGE_PIXEL_(test,fmt)
michael@0: 
michael@0:   PNG_IMAGE_PIXEL_CHANNELS(fmt)
michael@0:    The number of separate channels (components) in a pixel; 1 for a
michael@0:    color-mapped image.
michael@0: 
michael@0:   PNG_IMAGE_PIXEL_COMPONENT_SIZE(fmt)\
michael@0:    The size, in bytes, of each component in a pixel; 1 for a color-mapped
michael@0:    image.
michael@0: 
michael@0:   PNG_IMAGE_PIXEL_SIZE(fmt)
michael@0:    The size, in bytes, of a complete pixel; 1 for a color-mapped image.
michael@0: 
michael@0: Information about the whole row, or whole image
michael@0: 
michael@0:   PNG_IMAGE_ROW_STRIDE(image)
michael@0:    Returns the total number of components in a single row of the image; this
michael@0:    is the minimum 'row stride', the minimum count of components between each
michael@0:    row.  For a color-mapped image this is the minimum number of bytes in a
michael@0:    row.
michael@0: 
michael@0:   PNG_IMAGE_BUFFER_SIZE(image, row_stride)
michael@0:     Returns the size, in bytes, of an image buffer given a png_image and a row
michael@0:     stride - the number of components to leave space for in each row.
michael@0: 
michael@0:   PNG_IMAGE_FLAG_COLORSPACE_NOT_sRGB == 0x01
michael@0:     This indicates the the RGB values of the in-memory bitmap do not
michael@0:     correspond to the red, green and blue end-points defined by sRGB.
michael@0: 
michael@0:   PNG_IMAGE_FLAG_COLORMAP == 0x02
michael@0:     The PNG is color-mapped.  If this flag is set png_image_read_colormap
michael@0:     can be used without further loss of image information.  If it is not set
michael@0:     png_image_read_colormap will cause significant loss if the image has any
michael@0: 
michael@0: READ APIs
michael@0: 
michael@0:    The png_image passed to the read APIs must have been initialized by setting
michael@0:    the png_controlp field 'opaque' to NULL (or, better, memset the whole thing.)
michael@0: 
michael@0:    int png_image_begin_read_from_file( png_imagep image,
michael@0:      const char *file_name)
michael@0: 
michael@0:      The named file is opened for read and the image header
michael@0:      is filled in from the PNG header in the file.
michael@0: 
michael@0:    int png_image_begin_read_from_stdio (png_imagep image,
michael@0:      FILE* file)
michael@0: 
michael@0:       The PNG header is read from the stdio FILE object.
michael@0: 
michael@0:    int png_image_begin_read_from_memory(png_imagep image,
michael@0:       png_const_voidp memory, png_size_t size)
michael@0: 
michael@0:       The PNG header is read from the given memory buffer.
michael@0: 
michael@0:    int png_image_finish_read(png_imagep image,
michael@0:       png_colorp background, void *buffer,
michael@0:       png_int_32 row_stride, void *colormap));
michael@0: 
michael@0:       Finish reading the image into the supplied buffer and
michael@0:       clean up the png_image structure.
michael@0: 
michael@0:       row_stride is the step, in png_byte or png_uint_16 units
michael@0:       as appropriate, between adjacent rows.  A positive stride
michael@0:       indicates that the top-most row is first in the buffer -
michael@0:       the normal top-down arrangement.  A negative stride
michael@0:       indicates that the bottom-most row is first in the buffer.
michael@0: 
michael@0:       background need only be supplied if an alpha channel must
michael@0:       be removed from a png_byte format and the removal is to be
michael@0:       done by compositing on a solid color; otherwise it may be
michael@0:       NULL and any composition will be done directly onto the
michael@0:       buffer.  The value is an sRGB color to use for the
michael@0:       background, for grayscale output the green channel is used.
michael@0: 
michael@0:       For linear output removing the alpha channel is always done
michael@0:       by compositing on black.
michael@0: 
michael@0:    void png_image_free(png_imagep image)
michael@0: 
michael@0:       Free any data allocated by libpng in image->opaque,
michael@0:       setting the pointer to NULL.  May be called at any time
michael@0:       after the structure is initialized.
michael@0: 
michael@0: When the simplified API needs to convert between sRGB and linear colorspaces,
michael@0: the actual sRGB transfer curve defined in the sRGB specification (see the
michael@0: article at http://en.wikipedia.org/wiki/SRGB) is used, not the gamma=1/2.2
michael@0: approximation used elsewhere in libpng.
michael@0: 
michael@0: WRITE APIS
michael@0: 
michael@0: For write you must initialize a png_image structure to describe the image to
michael@0: be written:
michael@0: 
michael@0:    version: must be set to PNG_IMAGE_VERSION
michael@0:    opaque: must be initialized to NULL
michael@0:    width: image width in pixels
michael@0:    height: image height in rows
michael@0:    format: the format of the data you wish to write
michael@0:    flags: set to 0 unless one of the defined flags applies; set
michael@0:       PNG_IMAGE_FLAG_COLORSPACE_NOT_sRGB for color format images
michael@0:       where the RGB values do not correspond to the colors in sRGB.
michael@0:    colormap_entries: set to the number of entries in the color-map (0 to 256)
michael@0: 
michael@0:    int png_image_write_to_file, (png_imagep image,
michael@0:       const char *file, int convert_to_8bit, const void *buffer,
michael@0:       png_int_32 row_stride, const void *colormap));
michael@0: 
michael@0:       Write the image to the named file.
michael@0: 
michael@0:    int png_image_write_to_stdio(png_imagep image, FILE *file,
michael@0:       int convert_to_8_bit, const void *buffer,
michael@0:       png_int_32 row_stride, const void *colormap)
michael@0: 
michael@0:       Write the image to the given (FILE*).
michael@0: 
michael@0: With all write APIs if image is in one of the linear formats with
michael@0: (png_uint_16) data then setting convert_to_8_bit will cause the output to be
michael@0: a (png_byte) PNG gamma encoded according to the sRGB specification, otherwise
michael@0: a 16-bit linear encoded PNG file is written.
michael@0: 
michael@0: With all APIs row_stride is handled as in the read APIs - it is the spacing
michael@0: from one row to the next in component sized units (float) and if negative
michael@0: indicates a bottom-up row layout in the buffer.
michael@0: 
michael@0: Note that the write API does not support interlacing, sub-8-bit pixels,
michael@0: and indexed (paletted) images.
michael@0: 
michael@0: VI. Modifying/Customizing libpng
michael@0: 
michael@0: There are two issues here.  The first is changing how libpng does
michael@0: standard things like memory allocation, input/output, and error handling.
michael@0: The second deals with more complicated things like adding new chunks,
michael@0: adding new transformations, and generally changing how libpng works.
michael@0: Both of those are compile-time issues; that is, they are generally
michael@0: determined at the time the code is written, and there is rarely a need
michael@0: to provide the user with a means of changing them.
michael@0: 
michael@0: Memory allocation, input/output, and error handling
michael@0: 
michael@0: All of the memory allocation, input/output, and error handling in libpng
michael@0: goes through callbacks that are user-settable.  The default routines are
michael@0: in pngmem.c, pngrio.c, pngwio.c, and pngerror.c, respectively.  To change
michael@0: these functions, call the appropriate png_set_*_fn() function.
michael@0: 
michael@0: Memory allocation is done through the functions png_malloc(), png_calloc(),
michael@0: and png_free().  The png_malloc() and png_free() functions currently just
michael@0: call the standard C functions and png_calloc() calls png_malloc() and then
michael@0: clears the newly allocated memory to zero; note that png_calloc(png_ptr, size)
michael@0: is not the same as the calloc(number, size) function provided by stdlib.h.
michael@0: There is limited support for certain systems with segmented memory
michael@0: architectures and the types of pointers declared by png.h match this; you
michael@0: will have to use appropriate pointers in your application.  Since it is
michael@0: unlikely that the method of handling memory allocation on a platform
michael@0: will change between applications, these functions must be modified in
michael@0: the library at compile time.  If you prefer to use a different method
michael@0: of allocating and freeing data, you can use png_create_read_struct_2() or
michael@0: png_create_write_struct_2() to register your own functions as described
michael@0: above.  These functions also provide a void pointer that can be retrieved
michael@0: via
michael@0: 
michael@0:     mem_ptr=png_get_mem_ptr(png_ptr);
michael@0: 
michael@0: Your replacement memory functions must have prototypes as follows:
michael@0: 
michael@0:     png_voidp malloc_fn(png_structp png_ptr,
michael@0:        png_alloc_size_t size);
michael@0: 
michael@0:     void free_fn(png_structp png_ptr, png_voidp ptr);
michael@0: 
michael@0: Your malloc_fn() must return NULL in case of failure.  The png_malloc()
michael@0: function will normally call png_error() if it receives a NULL from the
michael@0: system memory allocator or from your replacement malloc_fn().
michael@0: 
michael@0: Your free_fn() will never be called with a NULL ptr, since libpng's
michael@0: png_free() checks for NULL before calling free_fn().
michael@0: 
michael@0: Input/Output in libpng is done through png_read() and png_write(),
michael@0: which currently just call fread() and fwrite().  The FILE * is stored in
michael@0: png_struct and is initialized via png_init_io().  If you wish to change
michael@0: the method of I/O, the library supplies callbacks that you can set
michael@0: through the function png_set_read_fn() and png_set_write_fn() at run
michael@0: time, instead of calling the png_init_io() function.  These functions
michael@0: also provide a void pointer that can be retrieved via the function
michael@0: png_get_io_ptr().  For example:
michael@0: 
michael@0:     png_set_read_fn(png_structp read_ptr,
michael@0:         voidp read_io_ptr, png_rw_ptr read_data_fn)
michael@0: 
michael@0:     png_set_write_fn(png_structp write_ptr,
michael@0:         voidp write_io_ptr, png_rw_ptr write_data_fn,
michael@0:         png_flush_ptr output_flush_fn);
michael@0: 
michael@0:     voidp read_io_ptr = png_get_io_ptr(read_ptr);
michael@0:     voidp write_io_ptr = png_get_io_ptr(write_ptr);
michael@0: 
michael@0: The replacement I/O functions must have prototypes as follows:
michael@0: 
michael@0:     void user_read_data(png_structp png_ptr,
michael@0:         png_bytep data, png_size_t length);
michael@0: 
michael@0:     void user_write_data(png_structp png_ptr,
michael@0:         png_bytep data, png_size_t length);
michael@0: 
michael@0:     void user_flush_data(png_structp png_ptr);
michael@0: 
michael@0: The user_read_data() function is responsible for detecting and
michael@0: handling end-of-data errors.
michael@0: 
michael@0: Supplying NULL for the read, write, or flush functions sets them back
michael@0: to using the default C stream functions, which expect the io_ptr to
michael@0: point to a standard *FILE structure.  It is probably a mistake
michael@0: to use NULL for one of write_data_fn and output_flush_fn but not both
michael@0: of them, unless you have built libpng with PNG_NO_WRITE_FLUSH defined.
michael@0: It is an error to read from a write stream, and vice versa.
michael@0: 
michael@0: Error handling in libpng is done through png_error() and png_warning().
michael@0: Errors handled through png_error() are fatal, meaning that png_error()
michael@0: should never return to its caller.  Currently, this is handled via
michael@0: setjmp() and longjmp() (unless you have compiled libpng with
michael@0: PNG_NO_SETJMP, in which case it is handled via PNG_ABORT()),
michael@0: but you could change this to do things like exit() if you should wish,
michael@0: as long as your function does not return.
michael@0: 
michael@0: On non-fatal errors, png_warning() is called
michael@0: to print a warning message, and then control returns to the calling code.
michael@0: By default png_error() and png_warning() print a message on stderr via
michael@0: fprintf() unless the library is compiled with PNG_NO_CONSOLE_IO defined
michael@0: (because you don't want the messages) or PNG_NO_STDIO defined (because
michael@0: fprintf() isn't available).  If you wish to change the behavior of the error
michael@0: functions, you will need to set up your own message callbacks.  These
michael@0: functions are normally supplied at the time that the png_struct is created.
michael@0: It is also possible to redirect errors and warnings to your own replacement
michael@0: functions after png_create_*_struct() has been called by calling:
michael@0: 
michael@0:     png_set_error_fn(png_structp png_ptr,
michael@0:         png_voidp error_ptr, png_error_ptr error_fn,
michael@0:         png_error_ptr warning_fn);
michael@0: 
michael@0:     png_voidp error_ptr = png_get_error_ptr(png_ptr);
michael@0: 
michael@0: If NULL is supplied for either error_fn or warning_fn, then the libpng
michael@0: default function will be used, calling fprintf() and/or longjmp() if a
michael@0: problem is encountered.  The replacement error functions should have
michael@0: parameters as follows:
michael@0: 
michael@0:     void user_error_fn(png_structp png_ptr,
michael@0:         png_const_charp error_msg);
michael@0: 
michael@0:     void user_warning_fn(png_structp png_ptr,
michael@0:         png_const_charp warning_msg);
michael@0: 
michael@0: The motivation behind using setjmp() and longjmp() is the C++ throw and
michael@0: catch exception handling methods.  This makes the code much easier to write,
michael@0: as there is no need to check every return code of every function call.
michael@0: However, there are some uncertainties about the status of local variables
michael@0: after a longjmp, so the user may want to be careful about doing anything
michael@0: after setjmp returns non-zero besides returning itself.  Consult your
michael@0: compiler documentation for more details.  For an alternative approach, you
michael@0: may wish to use the "cexcept" facility (see http://cexcept.sourceforge.net),
michael@0: which is illustrated in pngvalid.c and in contrib/visupng.
michael@0: 
michael@0: Beginning in libpng-1.4.0, the png_set_benign_errors() API became available.
michael@0: You can use this to handle certain errors (normally handled as errors)
michael@0: as warnings.
michael@0: 
michael@0:     png_set_benign_errors (png_ptr, int allowed);
michael@0: 
michael@0:     allowed: 0: treat png_benign_error() as an error.
michael@0:              1: treat png_benign_error() as a warning.
michael@0: 
michael@0: As of libpng-1.6.0, the default condition is to treat benign errors as
michael@0: warnings while reading and as errors while writing.
michael@0: 
michael@0: Custom chunks
michael@0: 
michael@0: If you need to read or write custom chunks, you may need to get deeper
michael@0: into the libpng code.  The library now has mechanisms for storing
michael@0: and writing chunks of unknown type; you can even declare callbacks
michael@0: for custom chunks.  However, this may not be good enough if the
michael@0: library code itself needs to know about interactions between your
michael@0: chunk and existing `intrinsic' chunks.
michael@0: 
michael@0: If you need to write a new intrinsic chunk, first read the PNG
michael@0: specification. Acquire a first level of understanding of how it works.
michael@0: Pay particular attention to the sections that describe chunk names,
michael@0: and look at how other chunks were designed, so you can do things
michael@0: similarly.  Second, check out the sections of libpng that read and
michael@0: write chunks.  Try to find a chunk that is similar to yours and use
michael@0: it as a template.  More details can be found in the comments inside
michael@0: the code.  It is best to handle private or unknown chunks in a generic method,
michael@0: via callback functions, instead of by modifying libpng functions. This
michael@0: is illustrated in pngtest.c, which uses a callback function to handle a
michael@0: private "vpAg" chunk and the new "sTER" chunk, which are both unknown to
michael@0: libpng.
michael@0: 
michael@0: If you wish to write your own transformation for the data, look through
michael@0: the part of the code that does the transformations, and check out some of
michael@0: the simpler ones to get an idea of how they work.  Try to find a similar
michael@0: transformation to the one you want to add and copy off of it.  More details
michael@0: can be found in the comments inside the code itself.
michael@0: 
michael@0: Configuring for 16-bit platforms
michael@0: 
michael@0: You will want to look into zconf.h to tell zlib (and thus libpng) that
michael@0: it cannot allocate more then 64K at a time.  Even if you can, the memory
michael@0: won't be accessible.  So limit zlib and libpng to 64K by defining MAXSEG_64K.
michael@0: 
michael@0: Configuring for DOS
michael@0: 
michael@0: For DOS users who only have access to the lower 640K, you will
michael@0: have to limit zlib's memory usage via a png_set_compression_mem_level()
michael@0: call.  See zlib.h or zconf.h in the zlib library for more information.
michael@0: 
michael@0: Configuring for Medium Model
michael@0: 
michael@0: Libpng's support for medium model has been tested on most of the popular
michael@0: compilers.  Make sure MAXSEG_64K gets defined, USE_FAR_KEYWORD gets
michael@0: defined, and FAR gets defined to far in pngconf.h, and you should be
michael@0: all set.  Everything in the library (except for zlib's structure) is
michael@0: expecting far data.  You must use the typedefs with the p or pp on
michael@0: the end for pointers (or at least look at them and be careful).  Make
michael@0: note that the rows of data are defined as png_bytepp, which is
michael@0: an "unsigned char far * far *".
michael@0: 
michael@0: Configuring for gui/windowing platforms:
michael@0: 
michael@0: You will need to write new error and warning functions that use the GUI
michael@0: interface, as described previously, and set them to be the error and
michael@0: warning functions at the time that png_create_*_struct() is called,
michael@0: in order to have them available during the structure initialization.
michael@0: They can be changed later via png_set_error_fn().  On some compilers,
michael@0: you may also have to change the memory allocators (png_malloc, etc.).
michael@0: 
michael@0: Configuring for compiler xxx:
michael@0: 
michael@0: All includes for libpng are in pngconf.h.  If you need to add, change
michael@0: or delete an include, this is the place to do it.
michael@0: The includes that are not needed outside libpng are placed in pngpriv.h,
michael@0: which is only used by the routines inside libpng itself.
michael@0: The files in libpng proper only include pngpriv.h and png.h, which
michael@0: in turn includes pngconf.h and, as of libpng-1.5.0, pnglibconf.h.
michael@0: As of libpng-1.5.0, pngpriv.h also includes three other private header
michael@0: files, pngstruct.h, pnginfo.h, and pngdebug.h, which contain material
michael@0: that previously appeared in the public headers.
michael@0: 
michael@0: Configuring zlib:
michael@0: 
michael@0: There are special functions to configure the compression.  Perhaps the
michael@0: most useful one changes the compression level, which currently uses
michael@0: input compression values in the range 0 - 9.  The library normally
michael@0: uses the default compression level (Z_DEFAULT_COMPRESSION = 6).  Tests
michael@0: have shown that for a large majority of images, compression values in
michael@0: the range 3-6 compress nearly as well as higher levels, and do so much
michael@0: faster.  For online applications it may be desirable to have maximum speed
michael@0: (Z_BEST_SPEED = 1).  With versions of zlib after v0.99, you can also
michael@0: specify no compression (Z_NO_COMPRESSION = 0), but this would create
michael@0: files larger than just storing the raw bitmap.  You can specify the
michael@0: compression level by calling:
michael@0: 
michael@0:     #include zlib.h
michael@0:     png_set_compression_level(png_ptr, level);
michael@0: 
michael@0: Another useful one is to reduce the memory level used by the library.
michael@0: The memory level defaults to 8, but it can be lowered if you are
michael@0: short on memory (running DOS, for example, where you only have 640K).
michael@0: Note that the memory level does have an effect on compression; among
michael@0: other things, lower levels will result in sections of incompressible
michael@0: data being emitted in smaller stored blocks, with a correspondingly
michael@0: larger relative overhead of up to 15% in the worst case.
michael@0: 
michael@0:     #include zlib.h
michael@0:     png_set_compression_mem_level(png_ptr, level);
michael@0: 
michael@0: The other functions are for configuring zlib.  They are not recommended
michael@0: for normal use and may result in writing an invalid PNG file.  See
michael@0: zlib.h for more information on what these mean.
michael@0: 
michael@0:     #include zlib.h
michael@0:     png_set_compression_strategy(png_ptr,
michael@0:         strategy);
michael@0: 
michael@0:     png_set_compression_window_bits(png_ptr,
michael@0:         window_bits);
michael@0: 
michael@0:     png_set_compression_method(png_ptr, method);
michael@0: 
michael@0:     png_set_compression_buffer_size(png_ptr, size);
michael@0: 
michael@0: As of libpng version 1.5.4, additional APIs became
michael@0: available to set these separately for non-IDAT
michael@0: compressed chunks such as zTXt, iTXt, and iCCP:
michael@0: 
michael@0:     #include zlib.h
michael@0:     #if PNG_LIBPNG_VER >= 10504
michael@0:     png_set_text_compression_level(png_ptr, level);
michael@0: 
michael@0:     png_set_text_compression_mem_level(png_ptr, level);
michael@0: 
michael@0:     png_set_text_compression_strategy(png_ptr,
michael@0:         strategy);
michael@0: 
michael@0:     png_set_text_compression_window_bits(png_ptr,
michael@0:         window_bits);
michael@0: 
michael@0:     png_set_text_compression_method(png_ptr, method);
michael@0:     #endif
michael@0: 
michael@0: Controlling row filtering
michael@0: 
michael@0: If you want to control whether libpng uses filtering or not, which
michael@0: filters are used, and how it goes about picking row filters, you
michael@0: can call one of these functions.  The selection and configuration
michael@0: of row filters can have a significant impact on the size and
michael@0: encoding speed and a somewhat lesser impact on the decoding speed
michael@0: of an image.  Filtering is enabled by default for RGB and grayscale
michael@0: images (with and without alpha), but not for paletted images nor
michael@0: for any images with bit depths less than 8 bits/pixel.
michael@0: 
michael@0: The 'method' parameter sets the main filtering method, which is
michael@0: currently only '0' in the PNG 1.2 specification.  The 'filters'
michael@0: parameter sets which filter(s), if any, should be used for each
michael@0: scanline.  Possible values are PNG_ALL_FILTERS and PNG_NO_FILTERS
michael@0: to turn filtering on and off, respectively.
michael@0: 
michael@0: Individual filter types are PNG_FILTER_NONE, PNG_FILTER_SUB,
michael@0: PNG_FILTER_UP, PNG_FILTER_AVG, PNG_FILTER_PAETH, which can be bitwise
michael@0: ORed together with '|' to specify one or more filters to use.
michael@0: These filters are described in more detail in the PNG specification.
michael@0: If you intend to change the filter type during the course of writing
michael@0: the image, you should start with flags set for all of the filters
michael@0: you intend to use so that libpng can initialize its internal
michael@0: structures appropriately for all of the filter types.  (Note that this
michael@0: means the first row must always be adaptively filtered, because libpng
michael@0: currently does not allocate the filter buffers until png_write_row()
michael@0: is called for the first time.)
michael@0: 
michael@0:     filters = PNG_FILTER_NONE | PNG_FILTER_SUB
michael@0:               PNG_FILTER_UP | PNG_FILTER_AVG |
michael@0:               PNG_FILTER_PAETH | PNG_ALL_FILTERS;
michael@0: 
michael@0:     png_set_filter(png_ptr, PNG_FILTER_TYPE_BASE,
michael@0:        filters);
michael@0:               The second parameter can also be
michael@0:               PNG_INTRAPIXEL_DIFFERENCING if you are
michael@0:               writing a PNG to be embedded in a MNG
michael@0:               datastream.  This parameter must be the
michael@0:               same as the value of filter_method used
michael@0:               in png_set_IHDR().
michael@0: 
michael@0: It is also possible to influence how libpng chooses from among the
michael@0: available filters.  This is done in one or both of two ways - by
michael@0: telling it how important it is to keep the same filter for successive
michael@0: rows, and by telling it the relative computational costs of the filters.
michael@0: 
michael@0:     double weights[3] = {1.5, 1.3, 1.1},
michael@0:        costs[PNG_FILTER_VALUE_LAST] =
michael@0:        {1.0, 1.3, 1.3, 1.5, 1.7};
michael@0: 
michael@0:     png_set_filter_heuristics(png_ptr,
michael@0:        PNG_FILTER_HEURISTIC_WEIGHTED, 3,
michael@0:        weights, costs);
michael@0: 
michael@0: The weights are multiplying factors that indicate to libpng that the
michael@0: row filter should be the same for successive rows unless another row filter
michael@0: is that many times better than the previous filter.  In the above example,
michael@0: if the previous 3 filters were SUB, SUB, NONE, the SUB filter could have a
michael@0: "sum of absolute differences" 1.5 x 1.3 times higher than other filters
michael@0: and still be chosen, while the NONE filter could have a sum 1.1 times
michael@0: higher than other filters and still be chosen.  Unspecified weights are
michael@0: taken to be 1.0, and the specified weights should probably be declining
michael@0: like those above in order to emphasize recent filters over older filters.
michael@0: 
michael@0: The filter costs specify for each filter type a relative decoding cost
michael@0: to be considered when selecting row filters.  This means that filters
michael@0: with higher costs are less likely to be chosen over filters with lower
michael@0: costs, unless their "sum of absolute differences" is that much smaller.
michael@0: The costs do not necessarily reflect the exact computational speeds of
michael@0: the various filters, since this would unduly influence the final image
michael@0: size.
michael@0: 
michael@0: Note that the numbers above were invented purely for this example and
michael@0: are given only to help explain the function usage.  Little testing has
michael@0: been done to find optimum values for either the costs or the weights.
michael@0: 
michael@0: Removing unwanted object code
michael@0: 
michael@0: There are a bunch of #define's in pngconf.h that control what parts of
michael@0: libpng are compiled.  All the defines end in _SUPPORTED.  If you are
michael@0: never going to use a capability, you can change the #define to #undef
michael@0: before recompiling libpng and save yourself code and data space, or
michael@0: you can turn off individual capabilities with defines that begin with
michael@0: PNG_NO_.
michael@0: 
michael@0: In libpng-1.5.0 and later, the #define's are in pnglibconf.h instead.
michael@0: 
michael@0: You can also turn all of the transforms and ancillary chunk capabilities
michael@0: off en masse with compiler directives that define
michael@0: PNG_NO_READ[or WRITE]_TRANSFORMS, or PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS,
michael@0: or all four,
michael@0: along with directives to turn on any of the capabilities that you do
michael@0: want.  The PNG_NO_READ[or WRITE]_TRANSFORMS directives disable the extra
michael@0: transformations but still leave the library fully capable of reading
michael@0: and writing PNG files with all known public chunks. Use of the
michael@0: PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS directive produces a library
michael@0: that is incapable of reading or writing ancillary chunks.  If you are
michael@0: not using the progressive reading capability, you can turn that off
michael@0: with PNG_NO_PROGRESSIVE_READ (don't confuse this with the INTERLACING
michael@0: capability, which you'll still have).
michael@0: 
michael@0: All the reading and writing specific code are in separate files, so the
michael@0: linker should only grab the files it needs.  However, if you want to
michael@0: make sure, or if you are building a stand alone library, all the
michael@0: reading files start with "pngr" and all the writing files start with "pngw".
michael@0: The files that don't match either (like png.c, pngtrans.c, etc.)
michael@0: are used for both reading and writing, and always need to be included.
michael@0: The progressive reader is in pngpread.c
michael@0: 
michael@0: If you are creating or distributing a dynamically linked library (a .so
michael@0: or DLL file), you should not remove or disable any parts of the library,
michael@0: as this will cause applications linked with different versions of the
michael@0: library to fail if they call functions not available in your library.
michael@0: The size of the library itself should not be an issue, because only
michael@0: those sections that are actually used will be loaded into memory.
michael@0: 
michael@0: Requesting debug printout
michael@0: 
michael@0: The macro definition PNG_DEBUG can be used to request debugging
michael@0: printout.  Set it to an integer value in the range 0 to 3.  Higher
michael@0: numbers result in increasing amounts of debugging information.  The
michael@0: information is printed to the "stderr" file, unless another file
michael@0: name is specified in the PNG_DEBUG_FILE macro definition.
michael@0: 
michael@0: When PNG_DEBUG > 0, the following functions (macros) become available:
michael@0: 
michael@0:    png_debug(level, message)
michael@0:    png_debug1(level, message, p1)
michael@0:    png_debug2(level, message, p1, p2)
michael@0: 
michael@0: in which "level" is compared to PNG_DEBUG to decide whether to print
michael@0: the message, "message" is the formatted string to be printed,
michael@0: and p1 and p2 are parameters that are to be embedded in the string
michael@0: according to printf-style formatting directives.  For example,
michael@0: 
michael@0:    png_debug1(2, "foo=%d", foo);
michael@0: 
michael@0: is expanded to
michael@0: 
michael@0:    if (PNG_DEBUG > 2)
michael@0:       fprintf(PNG_DEBUG_FILE, "foo=%d\n", foo);
michael@0: 
michael@0: When PNG_DEBUG is defined but is zero, the macros aren't defined, but you
michael@0: can still use PNG_DEBUG to control your own debugging:
michael@0: 
michael@0:    #ifdef PNG_DEBUG
michael@0:        fprintf(stderr, ...
michael@0:    #endif
michael@0: 
michael@0: When PNG_DEBUG = 1, the macros are defined, but only png_debug statements
michael@0: having level = 0 will be printed.  There aren't any such statements in
michael@0: this version of libpng, but if you insert some they will be printed.
michael@0: 
michael@0: Prepending a prefix to exported symbols
michael@0: 
michael@0: Starting with libpng-1.6.0, you can configure libpng (when using the
michael@0: "configure" script) to prefix all exported symbols by means of the
michael@0: configuration option "--with-libpng-prefix=FOO_", where FOO_ can be any
michael@0: string beginning with a letter and containing only uppercase
michael@0: and lowercase letters, digits, and the underscore (i.e., a C language
michael@0: identifier).  This creates a set of macros in pnglibconf.h, so this is
michael@0: transparent to applications; their function calls get transformed by
michael@0: the macros to use the modified names.
michael@0: 
michael@0: VII.  MNG support
michael@0: 
michael@0: The MNG specification (available at http://www.libpng.org/pub/mng) allows
michael@0: certain extensions to PNG for PNG images that are embedded in MNG datastreams.
michael@0: Libpng can support some of these extensions.  To enable them, use the
michael@0: png_permit_mng_features() function:
michael@0: 
michael@0:    feature_set = png_permit_mng_features(png_ptr, mask)
michael@0: 
michael@0:    mask is a png_uint_32 containing the bitwise OR of the
michael@0:         features you want to enable.  These include
michael@0:         PNG_FLAG_MNG_EMPTY_PLTE
michael@0:         PNG_FLAG_MNG_FILTER_64
michael@0:         PNG_ALL_MNG_FEATURES
michael@0: 
michael@0:    feature_set is a png_uint_32 that is the bitwise AND of
michael@0:       your mask with the set of MNG features that is
michael@0:       supported by the version of libpng that you are using.
michael@0: 
michael@0: It is an error to use this function when reading or writing a standalone
michael@0: PNG file with the PNG 8-byte signature.  The PNG datastream must be wrapped
michael@0: in a MNG datastream.  As a minimum, it must have the MNG 8-byte signature
michael@0: and the MHDR and MEND chunks.  Libpng does not provide support for these
michael@0: or any other MNG chunks; your application must provide its own support for
michael@0: them.  You may wish to consider using libmng (available at
michael@0: http://www.libmng.com) instead.
michael@0: 
michael@0: VIII.  Changes to Libpng from version 0.88
michael@0: 
michael@0: It should be noted that versions of libpng later than 0.96 are not
michael@0: distributed by the original libpng author, Guy Schalnat, nor by
michael@0: Andreas Dilger, who had taken over from Guy during 1996 and 1997, and
michael@0: distributed versions 0.89 through 0.96, but rather by another member
michael@0: of the original PNG Group, Glenn Randers-Pehrson.  Guy and Andreas are
michael@0: still alive and well, but they have moved on to other things.
michael@0: 
michael@0: The old libpng functions png_read_init(), png_write_init(),
michael@0: png_info_init(), png_read_destroy(), and png_write_destroy() have been
michael@0: moved to PNG_INTERNAL in version 0.95 to discourage their use.  These
michael@0: functions will be removed from libpng version 1.4.0.
michael@0: 
michael@0: The preferred method of creating and initializing the libpng structures is
michael@0: via the png_create_read_struct(), png_create_write_struct(), and
michael@0: png_create_info_struct() because they isolate the size of the structures
michael@0: from the application, allow version error checking, and also allow the
michael@0: use of custom error handling routines during the initialization, which
michael@0: the old functions do not.  The functions png_read_destroy() and
michael@0: png_write_destroy() do not actually free the memory that libpng
michael@0: allocated for these structs, but just reset the data structures, so they
michael@0: can be used instead of png_destroy_read_struct() and
michael@0: png_destroy_write_struct() if you feel there is too much system overhead
michael@0: allocating and freeing the png_struct for each image read.
michael@0: 
michael@0: Setting the error callbacks via png_set_message_fn() before
michael@0: png_read_init() as was suggested in libpng-0.88 is no longer supported
michael@0: because this caused applications that do not use custom error functions
michael@0: to fail if the png_ptr was not initialized to zero.  It is still possible
michael@0: to set the error callbacks AFTER png_read_init(), or to change them with
michael@0: png_set_error_fn(), which is essentially the same function, but with a new
michael@0: name to force compilation errors with applications that try to use the old
michael@0: method.
michael@0: 
michael@0: Support for the sCAL, iCCP, iTXt, and sPLT chunks was added at libpng-1.0.6;
michael@0: however, iTXt support was not enabled by default.
michael@0: 
michael@0: Starting with version 1.0.7, you can find out which version of the library
michael@0: you are using at run-time:
michael@0: 
michael@0:    png_uint_32 libpng_vn = png_access_version_number();
michael@0: 
michael@0: The number libpng_vn is constructed from the major version, minor
michael@0: version with leading zero, and release number with leading zero,
michael@0: (e.g., libpng_vn for version 1.0.7 is 10007).
michael@0: 
michael@0: Note that this function does not take a png_ptr, so you can call it
michael@0: before you've created one.
michael@0: 
michael@0: You can also check which version of png.h you used when compiling your
michael@0: application:
michael@0: 
michael@0:    png_uint_32 application_vn = PNG_LIBPNG_VER;
michael@0: 
michael@0: IX.  Changes to Libpng from version 1.0.x to 1.2.x
michael@0: 
michael@0: Support for user memory management was enabled by default.  To
michael@0: accomplish this, the functions png_create_read_struct_2(),
michael@0: png_create_write_struct_2(), png_set_mem_fn(), png_get_mem_ptr(),
michael@0: png_malloc_default(), and png_free_default() were added.
michael@0: 
michael@0: Support for the iTXt chunk has been enabled by default as of
michael@0: version 1.2.41.
michael@0: 
michael@0: Support for certain MNG features was enabled.
michael@0: 
michael@0: Support for numbered error messages was added.  However, we never got
michael@0: around to actually numbering the error messages.  The function
michael@0: png_set_strip_error_numbers() was added (Note: the prototype for this
michael@0: function was inadvertently removed from png.h in PNG_NO_ASSEMBLER_CODE
michael@0: builds of libpng-1.2.15.  It was restored in libpng-1.2.36).
michael@0: 
michael@0: The png_malloc_warn() function was added at libpng-1.2.3.  This issues
michael@0: a png_warning and returns NULL instead of aborting when it fails to
michael@0: acquire the requested memory allocation.
michael@0: 
michael@0: Support for setting user limits on image width and height was enabled
michael@0: by default.  The functions png_set_user_limits(), png_get_user_width_max(),
michael@0: and png_get_user_height_max() were added at libpng-1.2.6.
michael@0: 
michael@0: The png_set_add_alpha() function was added at libpng-1.2.7.
michael@0: 
michael@0: The function png_set_expand_gray_1_2_4_to_8() was added at libpng-1.2.9.
michael@0: Unlike png_set_gray_1_2_4_to_8(), the new function does not expand the
michael@0: tRNS chunk to alpha. The png_set_gray_1_2_4_to_8() function is
michael@0: deprecated.
michael@0: 
michael@0: A number of macro definitions in support of runtime selection of
michael@0: assembler code features (especially Intel MMX code support) were
michael@0: added at libpng-1.2.0:
michael@0: 
michael@0:     PNG_ASM_FLAG_MMX_SUPPORT_COMPILED
michael@0:     PNG_ASM_FLAG_MMX_SUPPORT_IN_CPU
michael@0:     PNG_ASM_FLAG_MMX_READ_COMBINE_ROW
michael@0:     PNG_ASM_FLAG_MMX_READ_INTERLACE
michael@0:     PNG_ASM_FLAG_MMX_READ_FILTER_SUB
michael@0:     PNG_ASM_FLAG_MMX_READ_FILTER_UP
michael@0:     PNG_ASM_FLAG_MMX_READ_FILTER_AVG
michael@0:     PNG_ASM_FLAG_MMX_READ_FILTER_PAETH
michael@0:     PNG_ASM_FLAGS_INITIALIZED
michael@0:     PNG_MMX_READ_FLAGS
michael@0:     PNG_MMX_FLAGS
michael@0:     PNG_MMX_WRITE_FLAGS
michael@0:     PNG_MMX_FLAGS
michael@0: 
michael@0: We added the following functions in support of runtime
michael@0: selection of assembler code features:
michael@0: 
michael@0:     png_get_mmx_flagmask()
michael@0:     png_set_mmx_thresholds()
michael@0:     png_get_asm_flags()
michael@0:     png_get_mmx_bitdepth_threshold()
michael@0:     png_get_mmx_rowbytes_threshold()
michael@0:     png_set_asm_flags()
michael@0: 
michael@0: We replaced all of these functions with simple stubs in libpng-1.2.20,
michael@0: when the Intel assembler code was removed due to a licensing issue.
michael@0: 
michael@0: These macros are deprecated:
michael@0: 
michael@0:     PNG_READ_TRANSFORMS_NOT_SUPPORTED
michael@0:     PNG_PROGRESSIVE_READ_NOT_SUPPORTED
michael@0:     PNG_NO_SEQUENTIAL_READ_SUPPORTED
michael@0:     PNG_WRITE_TRANSFORMS_NOT_SUPPORTED
michael@0:     PNG_READ_ANCILLARY_CHUNKS_NOT_SUPPORTED
michael@0:     PNG_WRITE_ANCILLARY_CHUNKS_NOT_SUPPORTED
michael@0: 
michael@0: They have been replaced, respectively, by:
michael@0: 
michael@0:     PNG_NO_READ_TRANSFORMS
michael@0:     PNG_NO_PROGRESSIVE_READ
michael@0:     PNG_NO_SEQUENTIAL_READ
michael@0:     PNG_NO_WRITE_TRANSFORMS
michael@0:     PNG_NO_READ_ANCILLARY_CHUNKS
michael@0:     PNG_NO_WRITE_ANCILLARY_CHUNKS
michael@0: 
michael@0: PNG_MAX_UINT was replaced with PNG_UINT_31_MAX.  It has been
michael@0: deprecated since libpng-1.0.16 and libpng-1.2.6.
michael@0: 
michael@0: The function
michael@0:     png_check_sig(sig, num)
michael@0: was replaced with
michael@0:     !png_sig_cmp(sig, 0, num)
michael@0: It has been deprecated since libpng-0.90.
michael@0: 
michael@0: The function
michael@0:     png_set_gray_1_2_4_to_8()
michael@0: which also expands tRNS to alpha was replaced with
michael@0:     png_set_expand_gray_1_2_4_to_8()
michael@0: which does not. It has been deprecated since libpng-1.0.18 and 1.2.9.
michael@0: 
michael@0: X.  Changes to Libpng from version 1.0.x/1.2.x to 1.4.x
michael@0: 
michael@0: Private libpng prototypes and macro definitions were moved from
michael@0: png.h and pngconf.h into a new pngpriv.h header file.
michael@0: 
michael@0: Functions png_set_benign_errors(), png_benign_error(), and
michael@0: png_chunk_benign_error() were added.
michael@0: 
michael@0: Support for setting the maximum amount of memory that the application
michael@0: will allocate for reading chunks was added, as a security measure.
michael@0: The functions png_set_chunk_cache_max() and png_get_chunk_cache_max()
michael@0: were added to the library.
michael@0: 
michael@0: We implemented support for I/O states by adding png_ptr member io_state
michael@0: and functions png_get_io_chunk_name() and png_get_io_state() in pngget.c
michael@0: 
michael@0: We added PNG_TRANSFORM_GRAY_TO_RGB to the available high-level
michael@0: input transforms.
michael@0: 
michael@0: Checking for and reporting of errors in the IHDR chunk is more thorough.
michael@0: 
michael@0: Support for global arrays was removed, to improve thread safety.
michael@0: 
michael@0: Some obsolete/deprecated macros and functions have been removed.
michael@0: 
michael@0: Typecasted NULL definitions such as
michael@0:    #define png_voidp_NULL            (png_voidp)NULL
michael@0: were eliminated.  If you used these in your application, just use
michael@0: NULL instead.
michael@0: 
michael@0: The png_struct and info_struct members "trans" and "trans_values" were
michael@0: changed to "trans_alpha" and "trans_color", respectively.
michael@0: 
michael@0: The obsolete, unused pnggccrd.c and pngvcrd.c files and related makefiles
michael@0: were removed.
michael@0: 
michael@0: The PNG_1_0_X and PNG_1_2_X macros were eliminated.
michael@0: 
michael@0: The PNG_LEGACY_SUPPORTED macro was eliminated.
michael@0: 
michael@0: Many WIN32_WCE #ifdefs were removed.
michael@0: 
michael@0: The functions png_read_init(info_ptr), png_write_init(info_ptr),
michael@0: png_info_init(info_ptr), png_read_destroy(), and png_write_destroy()
michael@0: have been removed.  They have been deprecated since libpng-0.95.
michael@0: 
michael@0: The png_permit_empty_plte() was removed. It has been deprecated
michael@0: since libpng-1.0.9.  Use png_permit_mng_features() instead.
michael@0: 
michael@0: We removed the obsolete stub functions png_get_mmx_flagmask(),
michael@0: png_set_mmx_thresholds(), png_get_asm_flags(),
michael@0: png_get_mmx_bitdepth_threshold(), png_get_mmx_rowbytes_threshold(),
michael@0: png_set_asm_flags(), and png_mmx_supported()
michael@0: 
michael@0: We removed the obsolete png_check_sig(), png_memcpy_check(), and
michael@0: png_memset_check() functions.  Instead use !png_sig_cmp(), memcpy(),
michael@0: and memset(), respectively.
michael@0: 
michael@0: The function png_set_gray_1_2_4_to_8() was removed. It has been
michael@0: deprecated since libpng-1.0.18 and 1.2.9, when it was replaced with
michael@0: png_set_expand_gray_1_2_4_to_8() because the former function also
michael@0: expanded any tRNS chunk to an alpha channel.
michael@0: 
michael@0: Macros for png_get_uint_16, png_get_uint_32, and png_get_int_32
michael@0: were added and are used by default instead of the corresponding
michael@0: functions. Unfortunately,
michael@0: from libpng-1.4.0 until 1.4.4, the png_get_uint_16 macro (but not the
michael@0: function) incorrectly returned a value of type png_uint_32.
michael@0: 
michael@0: We changed the prototype for png_malloc() from
michael@0:     png_malloc(png_structp png_ptr, png_uint_32 size)
michael@0: to
michael@0:     png_malloc(png_structp png_ptr, png_alloc_size_t size)
michael@0: 
michael@0: This also applies to the prototype for the user replacement malloc_fn().
michael@0: 
michael@0: The png_calloc() function was added and is used in place of
michael@0: of "png_malloc(); memset();" except in the case in png_read_png()
michael@0: where the array consists of pointers; in this case a "for" loop is used
michael@0: after the png_malloc() to set the pointers to NULL, to give robust.
michael@0: behavior in case the application runs out of memory part-way through
michael@0: the process.
michael@0: 
michael@0: We changed the prototypes of png_get_compression_buffer_size() and
michael@0: png_set_compression_buffer_size() to work with png_size_t instead of
michael@0: png_uint_32.
michael@0: 
michael@0: Support for numbered error messages was removed by default, since we
michael@0: never got around to actually numbering the error messages. The function
michael@0: png_set_strip_error_numbers() was removed from the library by default.
michael@0: 
michael@0: The png_zalloc() and png_zfree() functions are no longer exported.
michael@0: The png_zalloc() function no longer zeroes out the memory that it
michael@0: allocates.  Applications that called png_zalloc(png_ptr, number, size)
michael@0: can call png_calloc(png_ptr, number*size) instead, and can call
michael@0: png_free() instead of png_zfree().
michael@0: 
michael@0: Support for dithering was disabled by default in libpng-1.4.0, because
michael@0: it has not been well tested and doesn't actually "dither".
michael@0: The code was not
michael@0: removed, however, and could be enabled by building libpng with
michael@0: PNG_READ_DITHER_SUPPORTED defined.  In libpng-1.4.2, this support
michael@0: was re-enabled, but the function was renamed png_set_quantize() to
michael@0: reflect more accurately what it actually does.  At the same time,
michael@0: the PNG_DITHER_[RED,GREEN_BLUE]_BITS macros were also renamed to
michael@0: PNG_QUANTIZE_[RED,GREEN,BLUE]_BITS, and PNG_READ_DITHER_SUPPORTED
michael@0: was renamed to PNG_READ_QUANTIZE_SUPPORTED.
michael@0: 
michael@0: We removed the trailing '.' from the warning and error messages.
michael@0: 
michael@0: XI.  Changes to Libpng from version 1.4.x to 1.5.x
michael@0: 
michael@0: From libpng-1.4.0 until 1.4.4, the png_get_uint_16 macro (but not the
michael@0: function) incorrectly returned a value of type png_uint_32.
michael@0: The incorrect macro was removed from libpng-1.4.5.
michael@0: 
michael@0: Checking for invalid palette index on write was added at libpng
michael@0: 1.5.10.  If a pixel contains an invalid (out-of-range) index libpng issues
michael@0: a benign error.  This is enabled by default because this condition is an
michael@0: error according to the PNG specification, Clause 11.3.2, but the error can
michael@0: be ignored in each png_ptr with
michael@0: 
michael@0:    png_set_check_for_invalid_index(png_ptr, allowed);
michael@0: 
michael@0:       allowed  - one of
michael@0:                  0: disable benign error (accept the
michael@0:                     invalid data without warning).
michael@0:                  1: enable benign error (treat the
michael@0:                     invalid data as an error or a
michael@0:                     warning).
michael@0: 
michael@0: If the error is ignored, or if png_benign_error() treats it as a warning,
michael@0: any invalid pixels are decoded as opaque black by the decoder and written
michael@0: as-is by the encoder.
michael@0: 
michael@0: Retrieving the maximum palette index found was added at libpng-1.5.15.
michael@0: This statement must appear after png_read_png() or png_read_image() while
michael@0: reading, and after png_write_png() or png_write_image() while writing.
michael@0: 
michael@0:    int max_palette = png_get_palette_max(png_ptr, info_ptr);
michael@0: 
michael@0: This will return the maximum palette index found in the image, or "-1" if
michael@0: the palette was not checked, or "0" if no palette was found.  Note that this
michael@0: does not account for any palette index used by ancillary chunks such as the
michael@0: bKGD chunk; you must check those separately to determine the maximum
michael@0: palette index actually used.
michael@0: 
michael@0: A. Changes that affect users of libpng
michael@0: 
michael@0: There are no substantial API changes between the non-deprecated parts of
michael@0: the 1.4.5 API and the 1.5.0 API; however, the ability to directly access
michael@0: members of the main libpng control structures, png_struct and png_info,
michael@0: deprecated in earlier versions of libpng, has been completely removed from
michael@0: libpng 1.5.
michael@0: 
michael@0: We no longer include zlib.h in png.h.  The include statement has been moved
michael@0: to pngstruct.h, where it is not accessible by applications. Applications that
michael@0: need access to information in zlib.h will need to add the '#include "zlib.h"'
michael@0: directive.  It does not matter whether this is placed prior to or after
michael@0: the '"#include png.h"' directive.
michael@0: 
michael@0: The png_sprintf(), png_strcpy(), and png_strncpy() macros are no longer used
michael@0: and were removed.
michael@0: 
michael@0: We moved the png_strlen(), png_memcpy(), png_memset(), and png_memcmp()
michael@0: macros into a private header file (pngpriv.h) that is not accessible to
michael@0: applications.
michael@0: 
michael@0: In png_get_iCCP, the type of "profile" was changed from png_charpp
michael@0: to png_bytepp, and in png_set_iCCP, from png_charp to png_const_bytep.
michael@0: 
michael@0: There are changes of form in png.h, including new and changed macros to
michael@0: declare parts of the API.  Some API functions with arguments that are
michael@0: pointers to data not modified within the function have been corrected to
michael@0: declare these arguments with PNG_CONST.
michael@0: 
michael@0: Much of the internal use of C macros to control the library build has also
michael@0: changed and some of this is visible in the exported header files, in
michael@0: particular the use of macros to control data and API elements visible
michael@0: during application compilation may require significant revision to
michael@0: application code.  (It is extremely rare for an application to do this.)
michael@0: 
michael@0: Any program that compiled against libpng 1.4 and did not use deprecated
michael@0: features or access internal library structures should compile and work
michael@0: against libpng 1.5, except for the change in the prototype for
michael@0: png_get_iCCP() and png_set_iCCP() API functions mentioned above.
michael@0: 
michael@0: libpng 1.5.0 adds PNG_ PASS macros to help in the reading and writing of
michael@0: interlaced images.  The macros return the number of rows and columns in
michael@0: each pass and information that can be used to de-interlace and (if
michael@0: absolutely necessary) interlace an image.
michael@0: 
michael@0: libpng 1.5.0 adds an API png_longjmp(png_ptr, value).  This API calls
michael@0: the application-provided png_longjmp_ptr on the internal, but application
michael@0: initialized, longjmp buffer.  It is provided as a convenience to avoid
michael@0: the need to use the png_jmpbuf macro, which had the unnecessary side
michael@0: effect of resetting the internal png_longjmp_ptr value.
michael@0: 
michael@0: libpng 1.5.0 includes a complete fixed point API.  By default this is
michael@0: present along with the corresponding floating point API.  In general the
michael@0: fixed point API is faster and smaller than the floating point one because
michael@0: the PNG file format used fixed point, not floating point.  This applies
michael@0: even if the library uses floating point in internal calculations.  A new
michael@0: macro, PNG_FLOATING_ARITHMETIC_SUPPORTED, reveals whether the library
michael@0: uses floating point arithmetic (the default) or fixed point arithmetic
michael@0: internally for performance critical calculations such as gamma correction.
michael@0: In some cases, the gamma calculations may produce slightly different
michael@0: results.  This has changed the results in png_rgb_to_gray and in alpha
michael@0: composition (png_set_background for example). This applies even if the
michael@0: original image was already linear (gamma == 1.0) and, therefore, it is
michael@0: not necessary to linearize the image.  This is because libpng has *not*
michael@0: been changed to optimize that case correctly, yet.
michael@0: 
michael@0: Fixed point support for the sCAL chunk comes with an important caveat;
michael@0: the sCAL specification uses a decimal encoding of floating point values
michael@0: and the accuracy of PNG fixed point values is insufficient for
michael@0: representation of these values. Consequently a "string" API
michael@0: (png_get_sCAL_s and png_set_sCAL_s) is the only reliable way of reading
michael@0: arbitrary sCAL chunks in the absence of either the floating point API or
michael@0: internal floating point calculations.  Starting with libpng-1.5.0, both
michael@0: of these functions are present when PNG_sCAL_SUPPORTED is defined.  Prior
michael@0: to libpng-1.5.0, their presence also depended upon PNG_FIXED_POINT_SUPPORTED
michael@0: being defined and PNG_FLOATING_POINT_SUPPORTED not being defined.
michael@0: 
michael@0: Applications no longer need to include the optional distribution header
michael@0: file pngusr.h or define the corresponding macros during application
michael@0: build in order to see the correct variant of the libpng API.  From 1.5.0
michael@0: application code can check for the corresponding _SUPPORTED macro:
michael@0: 
michael@0: #ifdef PNG_INCH_CONVERSIONS_SUPPORTED
michael@0:    /* code that uses the inch conversion APIs. */
michael@0: #endif
michael@0: 
michael@0: This macro will only be defined if the inch conversion functions have been
michael@0: compiled into libpng.  The full set of macros, and whether or not support
michael@0: has been compiled in, are available in the header file pnglibconf.h.
michael@0: This header file is specific to the libpng build.  Notice that prior to
michael@0: 1.5.0 the _SUPPORTED macros would always have the default definition unless
michael@0: reset by pngusr.h or by explicit settings on the compiler command line.
michael@0: These settings may produce compiler warnings or errors in 1.5.0 because
michael@0: of macro redefinition.
michael@0: 
michael@0: Applications can now choose whether to use these macros or to call the
michael@0: corresponding function by defining PNG_USE_READ_MACROS or
michael@0: PNG_NO_USE_READ_MACROS before including png.h.  Notice that this is
michael@0: only supported from 1.5.0; defining PNG_NO_USE_READ_MACROS prior to 1.5.0
michael@0: will lead to a link failure.
michael@0: 
michael@0: Prior to libpng-1.5.4, the zlib compressor used the same set of parameters
michael@0: when compressing the IDAT data and textual data such as zTXt and iCCP.
michael@0: In libpng-1.5.4 we reinitialized the zlib stream for each type of data.
michael@0: We added five png_set_text_*() functions for setting the parameters to
michael@0: use with textual data.
michael@0: 
michael@0: Prior to libpng-1.5.4, the PNG_READ_16_TO_8_ACCURATE_SCALE_SUPPORTED
michael@0: option was off by default, and slightly inaccurate scaling occurred.
michael@0: This option can no longer be turned off, and the choice of accurate
michael@0: or inaccurate 16-to-8 scaling is by using the new png_set_scale_16_to_8()
michael@0: API for accurate scaling or the old png_set_strip_16_to_8() API for simple
michael@0: chopping.  In libpng-1.5.4, the PNG_READ_16_TO_8_ACCURATE_SCALE_SUPPORTED
michael@0: macro became PNG_READ_SCALE_16_TO_8_SUPPORTED, and the PNG_READ_16_TO_8
michael@0: macro became PNG_READ_STRIP_16_TO_8_SUPPORTED, to enable the two
michael@0: png_set_*_16_to_8() functions separately.
michael@0: 
michael@0: Prior to libpng-1.5.4, the png_set_user_limits() function could only be
michael@0: used to reduce the width and height limits from the value of
michael@0: PNG_USER_WIDTH_MAX and PNG_USER_HEIGHT_MAX, although this document said
michael@0: that it could be used to override them.  Now this function will reduce or
michael@0: increase the limits.
michael@0: 
michael@0: Starting in libpng-1.5.10, the user limits can be set en masse with the
michael@0: configuration option PNG_SAFE_LIMITS_SUPPORTED.  If this option is enabled,
michael@0: a set of "safe" limits is applied in pngpriv.h.  These can be overridden by
michael@0: application calls to png_set_user_limits(), png_set_user_chunk_cache_max(),
michael@0: and/or png_set_user_malloc_max() that increase or decrease the limits.  Also,
michael@0: in libpng-1.5.10 the default width and height limits were increased
michael@0: from 1,000,000 to 0x7ffffff (i.e., made unlimited).  Therefore, the
michael@0: limits are now
michael@0:                                default      safe
michael@0:    png_user_width_max        0x7fffffff    1,000,000
michael@0:    png_user_height_max       0x7fffffff    1,000,000
michael@0:    png_user_chunk_cache_max  0 (unlimited)   128
michael@0:    png_user_chunk_malloc_max 0 (unlimited) 8,000,000
michael@0: 
michael@0: The png_set_option() function (and the "options" member of the png struct) was
michael@0: added to libpng-1.5.15.
michael@0: 
michael@0: B. Changes to the build and configuration of libpng
michael@0: 
michael@0: Details of internal changes to the library code can be found in the CHANGES
michael@0: file and in the GIT repository logs.  These will be of no concern to the vast
michael@0: majority of library users or builders; however, the few who configure libpng
michael@0: to a non-default feature set may need to change how this is done.
michael@0: 
michael@0: There should be no need for library builders to alter build scripts if
michael@0: these use the distributed build support - configure or the makefiles -
michael@0: however, users of the makefiles may care to update their build scripts
michael@0: to build pnglibconf.h where the corresponding makefile does not do so.
michael@0: 
michael@0: Building libpng with a non-default configuration has changed completely.
michael@0: The old method using pngusr.h should still work correctly even though the
michael@0: way pngusr.h is used in the build has been changed; however, library
michael@0: builders will probably want to examine the changes to take advantage of
michael@0: new capabilities and to simplify their build system.
michael@0: 
michael@0: B.1 Specific changes to library configuration capabilities
michael@0: 
michael@0: The library now supports a complete fixed point implementation and can
michael@0: thus be used on systems that have no floating point support or very
michael@0: limited or slow support.  Previously gamma correction, an essential part
michael@0: of complete PNG support, required reasonably fast floating point.
michael@0: 
michael@0: As part of this the choice of internal implementation has been made
michael@0: independent of the choice of fixed versus floating point APIs and all the
michael@0: missing fixed point APIs have been implemented.
michael@0: 
michael@0: The exact mechanism used to control attributes of API functions has
michael@0: changed.  A single set of operating system independent macro definitions
michael@0: is used and operating system specific directives are defined in
michael@0: pnglibconf.h
michael@0: 
michael@0: As part of this the mechanism used to choose procedure call standards on
michael@0: those systems that allow a choice has been changed.  At present this only
michael@0: affects certain Microsoft (DOS, Windows) and IBM (OS/2) operating systems
michael@0: running on Intel processors.  As before, PNGAPI is defined where required
michael@0: to control the exported API functions; however, two new macros, PNGCBAPI
michael@0: and PNGCAPI, are used instead for callback functions (PNGCBAPI) and
michael@0: (PNGCAPI) for functions that must match a C library prototype (currently
michael@0: only png_longjmp_ptr, which must match the C longjmp function.)  The new
michael@0: approach is documented in pngconf.h
michael@0: 
michael@0: Despite these changes, libpng 1.5.0 only supports the native C function
michael@0: calling standard on those platforms tested so far (__cdecl on Microsoft
michael@0: Windows).  This is because the support requirements for alternative
michael@0: calling conventions seem to no longer exist.  Developers who find it
michael@0: necessary to set PNG_API_RULE to 1 should advise the mailing list
michael@0: (png-mng-implement) of this and library builders who use Openwatcom and
michael@0: therefore set PNG_API_RULE to 2 should also contact the mailing list.
michael@0: 
michael@0: A new test program, pngvalid, is provided in addition to pngtest.
michael@0: pngvalid validates the arithmetic accuracy of the gamma correction
michael@0: calculations and includes a number of validations of the file format.
michael@0: A subset of the full range of tests is run when "make check" is done
michael@0: (in the 'configure' build.)  pngvalid also allows total allocated memory
michael@0: usage to be evaluated and performs additional memory overwrite validation.
michael@0: 
michael@0: Many changes to individual feature macros have been made. The following
michael@0: are the changes most likely to be noticed by library builders who
michael@0: configure libpng:
michael@0: 
michael@0: 1) All feature macros now have consistent naming:
michael@0: 
michael@0: #define PNG_NO_feature turns the feature off
michael@0: #define PNG_feature_SUPPORTED turns the feature on
michael@0: 
michael@0: pnglibconf.h contains one line for each feature macro which is either:
michael@0: 
michael@0: #define PNG_feature_SUPPORTED
michael@0: 
michael@0: if the feature is supported or:
michael@0: 
michael@0: /*#undef PNG_feature_SUPPORTED*/
michael@0: 
michael@0: if it is not.  Library code consistently checks for the 'SUPPORTED' macro.
michael@0: It does not, and libpng applications should not, check for the 'NO' macro
michael@0: which will not normally be defined even if the feature is not supported.
michael@0: The 'NO' macros are only used internally for setting or not setting the
michael@0: corresponding 'SUPPORTED' macros.
michael@0: 
michael@0: Compatibility with the old names is provided as follows:
michael@0: 
michael@0: PNG_INCH_CONVERSIONS turns on PNG_INCH_CONVERSIONS_SUPPORTED
michael@0: 
michael@0: And the following definitions disable the corresponding feature:
michael@0: 
michael@0: PNG_SETJMP_NOT_SUPPORTED disables SETJMP
michael@0: PNG_READ_TRANSFORMS_NOT_SUPPORTED disables READ_TRANSFORMS
michael@0: PNG_NO_READ_COMPOSITED_NODIV disables READ_COMPOSITE_NODIV
michael@0: PNG_WRITE_TRANSFORMS_NOT_SUPPORTED disables WRITE_TRANSFORMS
michael@0: PNG_READ_ANCILLARY_CHUNKS_NOT_SUPPORTED disables READ_ANCILLARY_CHUNKS
michael@0: PNG_WRITE_ANCILLARY_CHUNKS_NOT_SUPPORTED disables WRITE_ANCILLARY_CHUNKS
michael@0: 
michael@0: Library builders should remove use of the above, inconsistent, names.
michael@0: 
michael@0: 2) Warning and error message formatting was previously conditional on
michael@0: the STDIO feature. The library has been changed to use the
michael@0: CONSOLE_IO feature instead. This means that if CONSOLE_IO is disabled
michael@0: the library no longer uses the printf(3) functions, even though the
michael@0: default read/write implementations use (FILE) style stdio.h functions.
michael@0: 
michael@0: 3) Three feature macros now control the fixed/floating point decisions:
michael@0: 
michael@0: PNG_FLOATING_POINT_SUPPORTED enables the floating point APIs
michael@0: 
michael@0: PNG_FIXED_POINT_SUPPORTED enables the fixed point APIs; however, in
michael@0: practice these are normally required internally anyway (because the PNG
michael@0: file format is fixed point), therefore in most cases PNG_NO_FIXED_POINT
michael@0: merely stops the function from being exported.
michael@0: 
michael@0: PNG_FLOATING_ARITHMETIC_SUPPORTED chooses between the internal floating
michael@0: point implementation or the fixed point one.  Typically the fixed point
michael@0: implementation is larger and slower than the floating point implementation
michael@0: on a system that supports floating point; however, it may be faster on a
michael@0: system which lacks floating point hardware and therefore uses a software
michael@0: emulation.
michael@0: 
michael@0: 4) Added PNG_{READ,WRITE}_INT_FUNCTIONS_SUPPORTED.  This allows the
michael@0: functions to read and write ints to be disabled independently of
michael@0: PNG_USE_READ_MACROS, which allows libpng to be built with the functions
michael@0: even though the default is to use the macros - this allows applications
michael@0: to choose at app buildtime whether or not to use macros (previously
michael@0: impossible because the functions weren't in the default build.)
michael@0: 
michael@0: B.2 Changes to the configuration mechanism
michael@0: 
michael@0: Prior to libpng-1.5.0 library builders who needed to configure libpng
michael@0: had either to modify the exported pngconf.h header file to add system
michael@0: specific configuration or had to write feature selection macros into
michael@0: pngusr.h and cause this to be included into pngconf.h by defining
michael@0: PNG_USER_CONFIG. The latter mechanism had the disadvantage that an
michael@0: application built without PNG_USER_CONFIG defined would see the
michael@0: unmodified, default, libpng API and thus would probably fail to link.
michael@0: 
michael@0: These mechanisms still work in the configure build and in any makefile
michael@0: build that builds pnglibconf.h, although the feature selection macros
michael@0: have changed somewhat as described above.  In 1.5.0, however, pngusr.h is
michael@0: processed only once, when the exported header file pnglibconf.h is built.
michael@0: pngconf.h no longer includes pngusr.h, therefore pngusr.h is ignored after the
michael@0: build of pnglibconf.h and it is never included in an application build.
michael@0: 
michael@0: The rarely used alternative of adding a list of feature macros to the
michael@0: CFLAGS setting in the build also still works; however, the macros will be
michael@0: copied to pnglibconf.h and this may produce macro redefinition warnings
michael@0: when the individual C files are compiled.
michael@0: 
michael@0: All configuration now only works if pnglibconf.h is built from
michael@0: scripts/pnglibconf.dfa.  This requires the program awk.  Brian Kernighan
michael@0: (the original author of awk) maintains C source code of that awk and this
michael@0: and all known later implementations (often called by subtly different
michael@0: names - nawk and gawk for example) are adequate to build pnglibconf.h.
michael@0: The Sun Microsystems (now Oracle) program 'awk' is an earlier version
michael@0: and does not work; this may also apply to other systems that have a
michael@0: functioning awk called 'nawk'.
michael@0: 
michael@0: Configuration options are now documented in scripts/pnglibconf.dfa.  This
michael@0: file also includes dependency information that ensures a configuration is
michael@0: consistent; that is, if a feature is switched off dependent features are
michael@0: also removed.  As a recommended alternative to using feature macros in
michael@0: pngusr.h a system builder may also define equivalent options in pngusr.dfa
michael@0: (or, indeed, any file) and add that to the configuration by setting
michael@0: DFA_XTRA to the file name.  The makefiles in contrib/pngminim illustrate
michael@0: how to do this, and a case where pngusr.h is still required.
michael@0: 
michael@0: XII.  Changes to Libpng from version 1.5.x to 1.6.x
michael@0: 
michael@0: A "simplified API" has been added (see documentation in png.h and a simple
michael@0: example in contrib/examples/pngtopng.c).  The new publicly visible API
michael@0: includes the following:
michael@0: 
michael@0:    macros:
michael@0:      PNG_FORMAT_*
michael@0:      PNG_IMAGE_*
michael@0:    structures:
michael@0:      png_control
michael@0:      png_image
michael@0:    read functions
michael@0:      png_image_begin_read_from_file()
michael@0:      png_image_begin_read_from_stdio()
michael@0:      png_image_begin_read_from_memory()
michael@0:      png_image_finish_read()
michael@0:      png_image_free()
michael@0:    write functions
michael@0:      png_image_write_to_file()
michael@0:      png_image_write_to_stdio()
michael@0: 
michael@0: Starting with libpng-1.6.0, you can configure libpng to prefix all exported
michael@0: symbols, using the PNG_PREFIX macro.
michael@0: 
michael@0: We no longer include string.h in png.h.  The include statement has been moved
michael@0: to pngpriv.h, where it is not accessible by applications.  Applications that
michael@0: need access to information in string.h must add an '#include <string.h>'
michael@0: directive.  It does not matter whether this is placed prior to or after
michael@0: the '#include "png.h"' directive.
michael@0: 
michael@0: The following API are now DEPRECATED:
michael@0:    png_info_init_3()
michael@0:    png_convert_to_rfc1123() which has been replaced
michael@0:      with png_convert_to_rfc1123_buffer()
michael@0:    png_data_freer()
michael@0:    png_malloc_default()
michael@0:    png_free_default()
michael@0:    png_reset_zstream()
michael@0: 
michael@0: The following have been removed:
michael@0:    png_get_io_chunk_name(), which has been replaced
michael@0:      with png_get_io_chunk_type().  The new
michael@0:      function returns a 32-bit integer instead of
michael@0:      a string.
michael@0:    The png_sizeof(), png_strlen(), png_memcpy(), png_memcmp(), and
michael@0:      png_memset() macros are no longer used in the libpng sources and
michael@0:      have been removed.  These had already been made invisible to applications
michael@0:      (i.e., defined in the private pngpriv.h header file) since libpng-1.5.0.
michael@0: 
michael@0: The signatures of many exported functions were changed, such that
michael@0:    png_structp became png_structrp or png_const_structrp
michael@0:    png_infop became png_inforp or png_const_inforp
michael@0: where "rp" indicates a "restricted pointer".
michael@0: 
michael@0: Error detection in some chunks has improved; in particular the iCCP chunk
michael@0: reader now does pretty complete validation of the basic format.  Some bad
michael@0: profiles that were previously accepted are now accepted with a warning or
michael@0: rejected, depending upon the png_set_benign_errors() setting, in particular the
michael@0: very old broken Microsoft/HP 3144-byte sRGB profile.  The PNG spec requirement
michael@0: that only grayscale profiles may appear in images with color type 0 or 4 and
michael@0: that even if the image only contains gray pixels, only RGB profiles may appear
michael@0: in images with color type 2, 3, or 6, is now enforced.  The sRGB chunk
michael@0: is allowed to appear in images with any color type.
michael@0: 
michael@0: Prior to libpng-1.6.0 a warning would be issued if the iTXt chunk contained
michael@0: an empty language field or an empty translated keyword.  Both of these
michael@0: are allowed by the PNG specification, so these warnings are no longer issued.
michael@0: 
michael@0: The library now issues an error if the application attempts to set a
michael@0: transform after it calls png_read_update_info() or if it attempts to call
michael@0: both png_read_update_info() and png_start_read_image() or to call either
michael@0: of them more than once.
michael@0: 
michael@0: The default condition for benign_errors is now to treat benign errors as
michael@0: warnings while reading and as errors while writing.
michael@0: 
michael@0: The library now issues a warning if both background processing and RGB to
michael@0: gray are used when gamma correction happens. As with previous versions of
michael@0: the library the results are numerically very incorrect in this case.
michael@0: 
michael@0: There are some minor arithmetic changes in some transforms such as
michael@0: png_set_background(), that might be detected by certain regression tests.
michael@0: 
michael@0: Unknown chunk handling has been improved internally, without any API change.
michael@0: This adds more correct option control of the unknown handling, corrects
michael@0: a pre-existing bug where the per-chunk 'keep' setting is ignored, and makes
michael@0: it possible to skip IDAT chunks in the sequential reader.
michael@0: 
michael@0: The machine-generated configure files are no longer included in branches
michael@0: libpng16 and later of the GIT repository.  They continue to be included
michael@0: in the tarball releases, however.
michael@0: 
michael@0: Libpng-1.6.0 through 1.6.2 used the CMF bytes at the beginning of the IDAT
michael@0: stream to set the size of the sliding window for reading instead of using the
michael@0: default 32-kbyte sliding window size.  It was discovered that there are
michael@0: hundreds of PNG files in the wild that have incorrect CMF bytes that caused
michael@0: libpng to issue a "too far back" error and reject the file.  Libpng-1.6.3 and
michael@0: later calculate their own safe CMF from the image dimensions, provide a way
michael@0: to revert to the libpng-1.5.x behavior (ignoring the CMF bytes and using a
michael@0: 32-kbyte sliding window), by using
michael@0: 
michael@0:     png_set_option(png_ptr, PNG_MAXIMUM_INFLATE_WINDOW,
michael@0:         PNG_OPTION_ON);
michael@0: 
michael@0: and provide a tool (contrib/tools/pngfix) for optimizing the CMF bytes
michael@0: correctly.
michael@0: 
michael@0: Libpng-1.6.0 and libpng-1.6.1 wrote uncompressed iTXt chunks with the wrong
michael@0: length, which resulted in PNG files that cannot be read beyond the bad iTXt
michael@0: chunk.  This error was fixed in libpng-1.6.3, and a tool (called
michael@0: contrib/tools/png-fix-itxt) has been added to the libpng distribution.
michael@0: 
michael@0: XIII.  Detecting libpng
michael@0: 
michael@0: The png_get_io_ptr() function has been present since libpng-0.88, has never
michael@0: changed, and is unaffected by conditional compilation macros.  It is the
michael@0: best choice for use in configure scripts for detecting the presence of any
michael@0: libpng version since 0.88.  In an autoconf "configure.in" you could use
michael@0: 
michael@0:     AC_CHECK_LIB(png, png_get_io_ptr, ...
michael@0: 
michael@0: XV. Source code repository
michael@0: 
michael@0: Since about February 2009, version 1.2.34, libpng has been under "git" source
michael@0: control.  The git repository was built from old libpng-x.y.z.tar.gz files
michael@0: going back to version 0.70.  You can access the git repository (read only)
michael@0: at
michael@0: 
michael@0:     git://git.code.sf.net/p/libpng/code
michael@0: 
michael@0: or you can browse it with a web browser by selecting the "code" button at
michael@0: 
michael@0:     https://sourceforge.net/projects/libpng
michael@0: 
michael@0: Patches can be sent to glennrp at users.sourceforge.net or to
michael@0: png-mng-implement at lists.sourceforge.net or you can upload them to
michael@0: the libpng bug tracker at
michael@0: 
michael@0:     http://libpng.sourceforge.net
michael@0: 
michael@0: We also accept patches built from the tar or zip distributions, and
michael@0: simple verbal discriptions of bug fixes, reported either to the
michael@0: SourceForge bug tracker, to the png-mng-implement at lists.sf.net
michael@0: mailing list, or directly to glennrp.
michael@0: 
michael@0: XV. Coding style
michael@0: 
michael@0: Our coding style is similar to the "Allman" style, with curly
michael@0: braces on separate lines:
michael@0: 
michael@0:     if (condition)
michael@0:     {
michael@0:        action;
michael@0:     }
michael@0: 
michael@0:     else if (another condition)
michael@0:     {
michael@0:        another action;
michael@0:     }
michael@0: 
michael@0: The braces can be omitted from simple one-line actions:
michael@0: 
michael@0:     if (condition)
michael@0:        return (0);
michael@0: 
michael@0: We use 3-space indentation, except for continued statements which
michael@0: are usually indented the same as the first line of the statement
michael@0: plus four more spaces.
michael@0: 
michael@0: For macro definitions we use 2-space indentation, always leaving the "#"
michael@0: in the first column.
michael@0: 
michael@0:     #ifndef PNG_NO_FEATURE
michael@0:     #  ifndef PNG_FEATURE_SUPPORTED
michael@0:     #    define PNG_FEATURE_SUPPORTED
michael@0:     #  endif
michael@0:     #endif
michael@0: 
michael@0: Comments appear with the leading "/*" at the same indentation as
michael@0: the statement that follows the comment:
michael@0: 
michael@0:     /* Single-line comment */
michael@0:     statement;
michael@0: 
michael@0:     /* This is a multiple-line
michael@0:      * comment.
michael@0:      */
michael@0:     statement;
michael@0: 
michael@0: Very short comments can be placed after the end of the statement
michael@0: to which they pertain:
michael@0: 
michael@0:     statement;    /* comment */
michael@0: 
michael@0: We don't use C++ style ("//") comments. We have, however,
michael@0: used them in the past in some now-abandoned MMX assembler
michael@0: code.
michael@0: 
michael@0: Functions and their curly braces are not indented, and
michael@0: exported functions are marked with PNGAPI:
michael@0: 
michael@0:  /* This is a public function that is visible to
michael@0:   * application programmers. It does thus-and-so.
michael@0:   */
michael@0:  void PNGAPI
michael@0:  png_exported_function(png_ptr, png_info, foo)
michael@0:  {
michael@0:     body;
michael@0:  }
michael@0: 
michael@0: The prototypes for all exported functions appear in png.h,
michael@0: above the comment that says
michael@0: 
michael@0:     /* Maintainer: Put new public prototypes here ... */
michael@0: 
michael@0: We mark all non-exported functions with "/* PRIVATE */"":
michael@0: 
michael@0:  void /* PRIVATE */
michael@0:  png_non_exported_function(png_ptr, png_info, foo)
michael@0:  {
michael@0:     body;
michael@0:  }
michael@0: 
michael@0: The prototypes for non-exported functions (except for those in
michael@0: pngtest) appear in
michael@0: pngpriv.h
michael@0: above the comment that says
michael@0: 
michael@0:   /* Maintainer: Put new private prototypes here ^ */
michael@0: 
michael@0: We put a space after the "sizeof" operator and we omit the
michael@0: optional parentheses around its argument when the argument
michael@0: is an expression, not a type name, and we always enclose the
michael@0: sizeof operator, with its argument, in parentheses:
michael@0: 
michael@0:   (sizeof (png_uint_32))
michael@0:   (sizeof array)
michael@0: 
michael@0: Prior to libpng-1.6.0 we used a "png_sizeof()" macro, formatted as
michael@0: though it were a function.
michael@0: 
michael@0: To avoid polluting the global namespace, the names of all exported
michael@0: functions and variables begin with "png_", and all publicly visible C
michael@0: preprocessor macros begin with "PNG".  We request that applications that
michael@0: use libpng *not* begin any of their own symbols with either of these strings.
michael@0: 
michael@0: We put a space after each comma and after each semicolon
michael@0: in "for" statements, and we put spaces before and after each
michael@0: C binary operator and after "for" or "while", and before
michael@0: "?".  We don't put a space between a typecast and the expression
michael@0: being cast, nor do we put one between a function name and the
michael@0: left parenthesis that follows it:
michael@0: 
michael@0:     for (i = 2; i > 0; --i)
michael@0:        y[i] = a(x) + (int)b;
michael@0: 
michael@0: We prefer #ifdef and #ifndef to #if defined() and #if !defined()
michael@0: when there is only one macro being tested.  We always use parentheses
michael@0: with "defined".
michael@0: 
michael@0: We prefer to express integers that are used as bit masks in hex format,
michael@0: with an even number of lower-case hex digits (e.g., 0x00, 0xff, 0x0100).
michael@0: 
michael@0: We prefer to use underscores in variable names rather than camelCase, except
michael@0: for a few type names that we inherit from zlib.h.
michael@0: 
michael@0: We do not use the TAB character for indentation in the C sources.
michael@0: 
michael@0: Lines do not exceed 80 characters.
michael@0: 
michael@0: Other rules can be inferred by inspecting the libpng source.
michael@0: 
michael@0: XVI. Y2K Compliance in libpng
michael@0: 
michael@0: February 6, 2014
michael@0: 
michael@0: Since the PNG Development group is an ad-hoc body, we can't make
michael@0: an official declaration.
michael@0: 
michael@0: This is your unofficial assurance that libpng from version 0.71 and
michael@0: upward through 1.6.9 are Y2K compliant.  It is my belief that earlier
michael@0: versions were also Y2K compliant.
michael@0: 
michael@0: Libpng only has two year fields.  One is a 2-byte unsigned integer
michael@0: that will hold years up to 65535.  The other, which is deprecated,
michael@0: holds the date in text format, and will hold years up to 9999.
michael@0: 
michael@0: The integer is
michael@0:     "png_uint_16 year" in png_time_struct.
michael@0: 
michael@0: The string is
michael@0:     "char time_buffer[29]" in png_struct.  This is no longer used
michael@0: in libpng-1.6.x and will be removed from libpng-1.7.0.
michael@0: 
michael@0: There are seven time-related functions:
michael@0: 
michael@0:     png_convert_to_rfc_1123() in png.c
michael@0:       (formerly png_convert_to_rfc_1152() in error)
michael@0:     png_convert_from_struct_tm() in pngwrite.c, called
michael@0:       in pngwrite.c
michael@0:     png_convert_from_time_t() in pngwrite.c
michael@0:     png_get_tIME() in pngget.c
michael@0:     png_handle_tIME() in pngrutil.c, called in pngread.c
michael@0:     png_set_tIME() in pngset.c
michael@0:     png_write_tIME() in pngwutil.c, called in pngwrite.c
michael@0: 
michael@0: All appear to handle dates properly in a Y2K environment.  The
michael@0: png_convert_from_time_t() function calls gmtime() to convert from system
michael@0: clock time, which returns (year - 1900), which we properly convert to
michael@0: the full 4-digit year.  There is a possibility that applications using
michael@0: libpng are not passing 4-digit years into the png_convert_to_rfc_1123()
michael@0: function, or that they are incorrectly passing only a 2-digit year
michael@0: instead of "year - 1900" into the png_convert_from_struct_tm() function,
michael@0: but this is not under our control.  The libpng documentation has always
michael@0: stated that it works with 4-digit years, and the APIs have been
michael@0: documented as such.
michael@0: 
michael@0: The tIME chunk itself is also Y2K compliant.  It uses a 2-byte unsigned
michael@0: integer to hold the year, and can hold years as large as 65535.
michael@0: 
michael@0: zlib, upon which libpng depends, is also Y2K compliant.  It contains
michael@0: no date-related code.
michael@0: 
michael@0: 
michael@0:    Glenn Randers-Pehrson
michael@0:    libpng maintainer
michael@0:    PNG Development Group