[master] Imported from libpng-1.6.0.tar

1 files changed, 624 insertions, 86 deletions

diff --git a/libpng.3 b/libpng.3
index 089e5186f..11da8ceac 100644
--- a/libpng.3
+++ b/libpng.3
@@ -1,6 +1,6 @@
-.TH LIBPNG 3 "January 24, 2013"
+.TH LIBPNG 3 "February 14, 2013"
 .SH NAME
-libpng \- Portable Network Graphics (PNG) Reference Library 1.5.14
+libpng \- Portable Network Graphics (PNG) Reference Library 1.6.0
 .SH SYNOPSIS
 \fB
 #include <png.h>\fP
@@ -111,8 +111,6 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.5.14
 
 \fBpng_byte png_get_interlace_type (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
 
-\fBpng_const_bytep png_get_io_chunk_name (png_structp \fIpng_ptr\fP\fB);\fP
-
 \fBpng_uint_32 png_get_io_chunk_type (png_const_structp \fIpng_ptr\fP\fB);\fP
 
 \fBpng_voidp png_get_io_ptr (png_structp \fIpng_ptr\fP\fB);\fP
@@ -217,6 +215,20 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.5.14
 
 \fBint png_handle_as_unknown (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fIchunk_name\fP\fB);\fP
 
+\fBint png_image_begin_read_from_file (png_imagep \fP\fIimage\fP\fB, const char \fI*file_name\fP\fB);\fP
+
+\fBint png_image_begin_read_from_stdio (png_imagep \fP\fIimage\fP\fB, FILE* \fIfile\fP\fB);\fP
+
+\fBint, png_image_begin_read_from_memory (png_imagep \fP\fIimage\fP\fB, png_const_voidp \fP\fImemory\fP\fB, png_size_t \fIsize\fP\fB);\fP
+
+\fBint png_image_finish_read (png_imagep \fP\fIimage\fP\fB, png_colorp \fP\fIbackground\fP\fB, void \fP\fI*buffer\fP\fB, png_int_32 \fP\fIrow_stride\fP\fB, void \fI*colormap\fP\fB);\fP
+
+\fBvoid png_image_free (png_imagep \fIimage\fP\fB);\fP
+
+\fBint png_image_write_to_file (png_imagep \fP\fIimage\fP\fB, const char \fP\fI*file\fP\fB, int \fP\fIconvert_to_8bit\fP\fB, const void \fP\fI*buffer\fP\fB, png_int_32 \fP\fIrow_stride\fP\fB, void \fI*colormap\fP\fB);\fP
+
+\fBint png_image_write_to_stdio (png_imagep \fP\fIimage\fP\fB, FILE \fP\fI*file\fP\fB, int \fP\fIconvert_to_8_bit\fP\fB, const void \fP\fI*buffer\fP\fB, png_int_32 \fP\fIrow_stride\fP\fB, void \fI*colormap)\fP\fB);\fP
+
 \fBvoid png_info_init_3 (png_infopp \fP\fIinfo_ptr\fP\fB, png_size_t \fIpng_info_struct_size\fP\fB);\fP
 
 \fBvoid png_init_io (png_structp \fP\fIpng_ptr\fP\fB, FILE \fI*fp\fP\fB);\fP
@@ -490,12 +502,12 @@ the Portable Network Graphics (PNG) format image files.  It uses the
 compression library.
 Following is a copy of the libpng-manual.txt file that accompanies libpng.
 .SH LIBPNG.TXT
-Libpng-manual.txt - A description on how to use and modify libpng
+libpng-manual.txt - A description on how to use and modify libpng
 
- libpng version 1.5.14 - January 24, 2013
+ libpng version 1.6.0 - February 14, 2013
  Updated and distributed by Glenn Randers-Pehrson
  <glennrp at users.sourceforge.net>
- Copyright (c) 1998-2012 Glenn Randers-Pehrson
+ Copyright (c) 1998-2013 Glenn Randers-Pehrson
 
  This document is released under the libpng license.
  For conditions of distribution and use, see the disclaimer
@@ -503,9 +515,9 @@ Libpng-manual.txt - A description on how to use and modify libpng
 
  Based on:
 
- libpng versions 0.97, January 1998, through 1.5.14 - January 24, 2013
+ libpng versions 0.97, January 1998, through 1.6.0 - February 14, 2013
  Updated and distributed by Glenn Randers-Pehrson
- Copyright (c) 1998-2012 Glenn Randers-Pehrson
+ Copyright (c) 1998-2013 Glenn Randers-Pehrson
 
  libpng 1.0 beta 6  version 0.96 May 28, 1997
  Updated and distributed by Andreas Dilger
@@ -520,6 +532,25 @@ Libpng-manual.txt - A description on how to use and modify libpng
  Copyright (c) 1995, 1996 Frank J. T. Wojcik
  December 18, 1995 & January 20, 1996
 
+ TABLE OF CONTENTS
+
+    I. Introduction
+   II. Structures
+  III. Reading
+   IV. Writing
+    V. Simplified API
+   VI. Modifying/Customizing libpng
+  VII. MNG support
+ VIII. Changes to Libpng from version 0.88
+   IX. Changes to Libpng from version 1.0.x to 1.2.x
+    X. Changes to Libpng from version 1.0.x/1.2.x to 1.4.x
+   XI. Changes to Libpng from version 1.4.x to 1.5.x
+  XII. Changes to Libpng from version 1.5.x to 1.6.x
+ XIII. Detecting libpng
+  XIV. Source code repository
+   XV. Coding style
+  XVI. Y2K Compliance in libpng
+
 .SH I. Introduction
 
 This file describes how to use and modify the PNG reference library
@@ -1045,6 +1076,7 @@ chunk types. To change this, you can call:
 
     png_set_keep_unknown_chunks(png_ptr, keep,
         chunk_list, num_chunks);
+
     keep       - 0: default unknown chunk handling
                  1: ignore; do not keep
                  2: keep only if safe-to-copy
@@ -1058,11 +1090,16 @@ chunk types. To change this, you can call:
 
     chunk_list - list of chunks affected (a byte string,
                  five bytes per chunk, NULL or '\0' if
-                 num_chunks is 0)
+                 num_chunks is positive; ignored if
+                 numchunks <= 0).
 
     num_chunks - number of chunks affected; if 0, all
-                 unknown chunks are affected.  If nonzero,
-                 only the chunks in the list are affected
+                 unknown chunks are affected.  If positive,
+                 only the chunks in the list are affected,
+                 and if negative all unknown chunks and
+                 all known chunks except for the IHDR,
+                 PLTE, tRNS, IDAT, and IEND chunks are
+                 affected.
 
 Unknown chunks declared in this way will be saved as raw data onto a
 list of png_unknown_chunk structures.  If a chunk that is normally
@@ -1178,7 +1215,8 @@ assumes that the PNG data matches your system, to keep this default call:
 
 or you can use the fixed point equivalent:
 
-   png_set_gamma_fixed(png_ptr, PNG_FP_1*screen_gamma, PNG_FP_1/screen_gamma);
+   png_set_gamma_fixed(png_ptr, PNG_FP_1*screen_gamma,
+      PNG_FP_1/screen_gamma);
 
 If you don't know the gamma for your system it is probably 2.2 - a good
 approximation to the IEC standard for display systems (sRGB).  If images are
@@ -1190,12 +1228,15 @@ display driver, a few systems, including older Macs, change the response by
 default.  As of 1.5.4 three special values are available to handle common
 situations:
 
-   PNG_DEFAULT_sRGB: Indicates that the system conforms to the IEC 61966-2-1
-                     standard.  This matches almost all systems.
-   PNG_GAMMA_MAC_18: Indicates that the system is an older (pre Mac OS 10.6)
-                     Apple Macintosh system with the default settings.
-   PNG_GAMMA_LINEAR: Just the fixed point value for 1.0 - indicates that the
-                     system expects data with no gamma encoding.
+   PNG_DEFAULT_sRGB: Indicates that the system conforms to the
+                     IEC 61966-2-1 standard.  This matches almost
+                     all systems.
+   PNG_GAMMA_MAC_18: Indicates that the system is an older
+                     (pre Mac OS 10.6) Apple Macintosh system with
+                     the default settings.
+   PNG_GAMMA_LINEAR: Just the fixed point value for 1.0 - indicates
+                     that the system expects data with no gamma
+                     encoding.
 
 You would use the linear (unencoded) value if you need to process the pixel
 values further because this avoids the need to decode and reencode each
@@ -1212,11 +1253,11 @@ Libpng only supports composing onto a single color (using png_set_background;
 see below).  Otherwise you must do the composition yourself and, in this case,
 you may need to call png_set_alpha_mode:
 
-    #if PNG_LIBPNG_VER >= 10504
-       png_set_alpha_mode(png_ptr, mode, screen_gamma);
-    #else
-       png_set_gamma(png_ptr, screen_gamma, 1.0/screen_gamma);
-    #endif
+   #if PNG_LIBPNG_VER >= 10504
+      png_set_alpha_mode(png_ptr, mode, screen_gamma);
+   #else
+      png_set_gamma(png_ptr, screen_gamma, 1.0/screen_gamma);
+   #endif
 
 The screen_gamma value is the same as the argument to png_set_gamma; however,
 how it affects the output depends on the mode.  png_set_alpha_mode() sets the
@@ -1622,7 +1663,11 @@ pointer into the info_ptr is returned for any complex types.
 The colorspace data from gAMA, cHRM, sRGB, iCCP, and sBIT chunks
 is simply returned to give the application information about how the
 image was encoded.  Libpng itself only does transformations using the file
-gamma when combining semitransparent pixels with the background color.
+gamma when combining semitransparent pixels with the background color, and,
+since libpng-1.6.0, when converting between 8-bit sRGB and 16-bit linear pixels
+within the simplified API.  Libpng also uses the file gamma when converting
+RGB to gray, beginning with libpng-1.0.5, if the application calls
+png_set_rgb_to_gray()).
 
     png_get_PLTE(png_ptr, info_ptr, &palette,
                      &num_palette);
@@ -1635,7 +1680,7 @@ gamma when combining semitransparent pixels with the background color.
     png_get_gAMA(png_ptr, info_ptr, &file_gamma);
     png_get_gAMA_fixed(png_ptr, info_ptr, &int_file_gamma);
 
-    file_gamma     - the gamma at which the file was
+    file_gamma     - the gamma at which the file is
                      written (PNG_INFO_gAMA)
 
     int_file_gamma - 100,000 times the gamma at which the
@@ -1643,14 +1688,17 @@ gamma when combining semitransparent pixels with the background color.
 
     png_get_cHRM(png_ptr, info_ptr,  &white_x, &white_y, &red_x,
                      &red_y, &green_x, &green_y, &blue_x, &blue_y)
-    png_get_cHRM_XYZ(png_ptr, info_ptr, &red_X, &red_Y, &red_Z, &green_X,
-                     &green_Y, &green_Z, &blue_X, &blue_Y, &blue_Z)
-    png_get_cHRM_fixed(png_ptr, info_ptr, &int_white_x, &int_white_y,
-                     &int_red_x, &int_red_y, &int_green_x, &int_green_y,
-                     &int_blue_x, &int_blue_y)
+    png_get_cHRM_XYZ(png_ptr, info_ptr, &red_X, &red_Y, &red_Z,
+                     &green_X, &green_Y, &green_Z, &blue_X, &blue_Y,
+                     &blue_Z)
+    png_get_cHRM_fixed(png_ptr, info_ptr, &int_white_x,
+                     &int_white_y, &int_red_x, &int_red_y,
+                     &int_green_x, &int_green_y, &int_blue_x,
+                     &int_blue_y)
     png_get_cHRM_XYZ_fixed(png_ptr, info_ptr, &int_red_X, &int_red_Y,
-                     &int_red_Z, &int_green_X, &int_green_Y, &int_green_Z,
-                     &int_blue_X, &int_blue_Y, &int_blue_Z)
+                     &int_red_Z, &int_green_X, &int_green_Y,
+                     &int_green_Z, &int_blue_X, &int_blue_Y,
+                     &int_blue_Z)
 
     {white,red,green,blue}_{x,y}
                      A color space encoding specified using the
@@ -1658,11 +1706,12 @@ gamma when combining semitransparent pixels with the background color.
                      white point. (PNG_INFO_cHRM)
 
     {red,green,blue}_{X,Y,Z}
-                     A color space encoding specified using the encoding end
-                     points - the CIE tristimulus specification of the intended
-                     color of the red, green and blue channels in the PNG RGB
-                     data.  The white point is simply the sum of the three end
-                     points. (PNG_INFO_cHRM)
+                     A color space encoding specified using the
+                     encoding end points - the CIE tristimulus
+                     specification of the intended color of the red,
+                     green and blue channels in the PNG RGB data.
+                     The white point is simply the sum of the three
+                     end points. (PNG_INFO_cHRM)
 
     png_get_sRGB(png_ptr, info_ptr, &srgb_intent);
 
@@ -3019,6 +3068,20 @@ You can #define PNG_ABORT() to a function that does something
 more useful than abort(), as long as your function does not
 return.
 
+Checking for invalid palette index on write was added at libpng
+1.5.10.  If a pixel contains an invalid (out-of-range) index libpng issues
+a benign error.  This is enabled by default because this condition is an
+error according to the PNG specification, Clause 11.3.2, but the error can
+be ignored in each png_ptr with
+
+   png_set_check_for_invalid_index(png_ptr, 0);
+
+If the error is ignored, or if png_benign_error() treats it as a warning,
+any invalid pixels are written as-is by the encoder, resulting in an
+invalid PNG datastream as output.  In this case the application is
+responsible for ensuring that the pixel indexes are in range when it writes
+a PLTE chunk with fewer entries than the bit depth would allow.
+
 Now you need to set up the output code.  The default for libpng is to
 use the C function fwrite().  If you use this, you will need to pass a
 valid FILE * in the function png_init_io().  Be sure that the file is
@@ -3521,8 +3584,9 @@ tEXt chunk use RFC 1123 format dates (e.g. "22 May 1997 18:07:10 GMT"),
 although this isn't a requirement.  Unlike the tIME chunk, the
 "Creation Time" tEXt chunk is not expected to be automatically changed
 by the software.  To facilitate the use of RFC 1123 dates, a function
-png_convert_to_rfc1123(png_ptr, png_timep) is provided to convert
-from PNG time to an RFC 1123 format string.
+png_convert_to_rfc1123_buffer(png_ptr, buffer, png_timep) is provided to
+convert from PNG time to an RFC 1123 format string.  The caller must provide
+a writeable buffer of at least 29 bytes.
 
 .SS Writing unknown chunks
 
@@ -3930,7 +3994,364 @@ if you transfer responsibility for free'ing text_ptr from libpng to your
 application, your application must not separately free those members.
 For a more compact example of writing a PNG image, see the file example.c.
 
-.SH V. Modifying/Customizing libpng:
+.SH V. Simplified API
+
+The simplified API, which became available in libpng-1.6.0, hides the details
+of both libpng and the PNG file format itself.
+It allows PNG files to be read into a very limited number of
+in-memory bitmap formats or to be written from the same formats.  If these
+formats do not accomodate your needs then you can, and should, use the more
+sophisticated APIs above - these support a wide variety of in-memory formats
+and a wide variety of sophisticated transformations to those formats as well
+as a wide variety of APIs to manipulate ancilliary information.
+
+To read a PNG file using the simplified API:
+
+  1) Declare a 'png_image' structure (see below) on the
+     stack and memset() it to all zero.
+
+  2) Call the appropriate png_image_begin_read... function.
+
+  3) Set the png_image 'format' member to the required
+     format and allocate a buffer for the image.
+
+  4) Call png_image_finish_read to read the image into
+     your buffer.
+
+There are no restrictions on the format of the PNG input itself; all valid
+color types, bit depths, and interlace methods are acceptable, and the
+input image is transformed as necessary to the requested in-memory format
+during the png_image_finish_read() step.
+
+To write a PNG file using the simplified API:
+
+  1) Declare a 'png_image' structure on the stack and memset()
+     it to all zero.
+
+  2) Initialize the members of the structure that describe the
+     image, setting the 'format' member to the format of the
+     image in memory.
+
+  3) Call the appropriate png_image_write... function with a
+     pointer to the image to write the PNG data.
+
+png_image is a structure that describes the in-memory format of an image
+when it is being read or define the in-memory format of an image that you
+need to write.  The "png_image" structure contains the following members:
+
+   png_uint_32  version Set to PNG_IMAGE_VERSION
+   png_uint_32  width   Image width in pixels (columns)
+   png_uint_32  height  Image height in pixels (rows)
+   png_uint_32  format  Image format as defined below
+   png_uint_32  flags   A bit mask containing informational flags
+   png_controlp opaque  Initialize to NULL, free with png_image_free
+   png_uint_32  colormap_entries; Number of entries in the color-map
+   png_uint_32  warning_or_error;
+   char         message[64];
+
+In the event of an error or warning the following field warning_or_error
+field will be set to a non-zero value and the 'message' field will contain
+a '\0' terminated string with the libpng error or warning message.  If both
+warnings and an error were encountered, only the error is recorded.  If there
+are multiple warnings, only the first one is recorded.
+
+The upper 30 bits of this value are reserved; the low two bits contain
+a two bit code such that a value more than 1 indicates a failure in the API
+just called:
+
+   0 - no warning or error
+   1 - warning
+   2 - error
+   3 - error preceded by warning
+
+The pixels (samples) of the image have one to four channels whose components
+have original values in the range 0 to 1.0:
+
+  1: A single gray or luminance channel (G).
+  2: A gray/luminance channel and an alpha channel (GA).
+  3: Three red, green, blue color channels (RGB).
+  4: Three color channels and an alpha channel (RGBA).
+
+The channels are encoded in one of two ways:
+
+  a) As a small integer, value 0..255, contained in a single byte.  For the
+alpha channel the original value is simply value/255.  For the color or
+luminance channels the value is encoded according to the sRGB specification
+and matches the 8-bit format expected by typical display devices.
+
+The color/gray channels are not scaled (pre-multiplied) by the alpha
+channel and are suitable for passing to color management software.
+
+  b) As a value in the range 0..65535, contained in a 2-byte integer.  All
+channels can be converted to the original value by dividing by 65535; all
+channels are linear.  Color channels use the RGB encoding (RGB end-points) of
+the sRGB specification.  This encoding is identified by the
+PNG_FORMAT_FLAG_LINEAR flag below.
+
+When an alpha channel is present it is expected to denote pixel coverage
+of the color or luminance channels and is returned as an associated alpha
+channel: the color/gray channels are scaled (pre-multiplied) by the alpha
+value.
+
+When a color-mapped image is used as a result of calling
+png_image_read_colormap or png_image_write_colormap the channels are encoded
+in the color-map and the descriptions above apply to the color-map entries.
+The image data is encoded as small integers, value 0..255, that index the
+entries in the color-map.  One integer (one byte) is stored for each pixel.
+
+PNG_FORMAT_*
+
+The #defines to be used in png_image::format.  Each #define identifies a
+particular layout of channel data and, if present, alpha values.  There are
+separate defines for each of the two channel encodings.
+
+A format is built up using single bit flag values.  Not all combinations are
+valid: use the bit flag values below for testing a format returned by the
+read APIs, but set formats from the derived values.
+
+When reading or writing color-mapped images the format should be set to the
+format of the entries in the color-map then png_image_{read,write}_colormap
+called to read or write the color-map and set the format correctly for the
+image data.  Do not set the PNG_FORMAT_FLAG_COLORMAP bit directly!
+
+NOTE: libpng can be built with particular features disabled, if you see
+compiler errors because the definition of one of the following flags has been
+compiled out it is because libpng does not have the required support.  It is
+possible, however, for the libpng configuration to enable the format on just
+read or just write; in that case you may see an error at run time.  You can
+guard against this by checking for the definition of:
+
+   PNG_SIMPLIFIED_{READ,WRITE}_{BGR,AFIRST}_SUPPORTED
+
+   PNG_FORMAT_FLAG_ALPHA    0x01 format with an alpha channel
+   PNG_FORMAT_FLAG_COLOR    0x02 color format: otherwise grayscale
+   PNG_FORMAT_FLAG_LINEAR   0x04 png_uint_16 channels else png_byte
+   PNG_FORMAT_FLAG_COLORMAP 0x08 libpng use only
+   PNG_FORMAT_FLAG_BGR      0x10 BGR colors, else order is RGB
+   PNG_FORMAT_FLAG_AFIRST   0x20 alpha channel comes first
+
+Supported formats are as follows.  Future versions of libpng may support more
+formats; for compatibility with older versions simply check if the format
+macro is defined using #ifdef.  These defines describe the in-memory layout
+of the components of the pixels of the image.
+
+First the single byte formats:
+
+   PNG_FORMAT_GRAY 0
+   PNG_FORMAT_GA   PNG_FORMAT_FLAG_ALPHA
+   PNG_FORMAT_AG   (PNG_FORMAT_GA|PNG_FORMAT_FLAG_AFIRST)
+   PNG_FORMAT_RGB  PNG_FORMAT_FLAG_COLOR
+   PNG_FORMAT_BGR  (PNG_FORMAT_FLAG_COLOR|PNG_FORMAT_FLAG_BGR)
+   PNG_FORMAT_RGBA (PNG_FORMAT_RGB|PNG_FORMAT_FLAG_ALPHA)
+   PNG_FORMAT_ARGB (PNG_FORMAT_RGBA|PNG_FORMAT_FLAG_AFIRST)
+   PNG_FORMAT_BGRA (PNG_FORMAT_BGR|PNG_FORMAT_FLAG_ALPHA)
+   PNG_FORMAT_ABGR (PNG_FORMAT_BGRA|PNG_FORMAT_FLAG_AFIRST)
+
+Then the linear 2-byte formats.  When naming these "Y" is used to
+indicate a luminance (gray) channel.  The component order within the pixel
+is always the same - there is no provision for swapping the order of the
+components in the linear format.
+
+   PNG_FORMAT_LINEAR_Y PNG_FORMAT_FLAG_LINEAR
+   PNG_FORMAT_LINEAR_Y_ALPHA
+      (PNG_FORMAT_FLAG_LINEAR|PNG_FORMAT_FLAG_ALPHA)
+   PNG_FORMAT_LINEAR_RGB
+      (PNG_FORMAT_FLAG_LINEAR|PNG_FORMAT_FLAG_COLOR)
+   PNG_FORMAT_LINEAR_RGB_ALPHA
+      (PNG_FORMAT_FLAG_LINEAR|PNG_FORMAT_FLAG_COLOR|
+      PNG_FORMAT_FLAG_ALPHA)
+
+Color-mapped formats are obtained by calling png_image_{read,write}_colormap,
+as appropriate after setting png_image::format to the format of the color-map
+to be read or written.  Applications may check the value of
+PNG_FORMAT_FLAG_COLORMAP to see if they have called the colormap API.  The
+format of the color-map may be extracted using the following macro.
+
+   PNG_FORMAT_OF_COLORMAP(fmt) ((fmt) & ~PNG_FORMAT_FLAG_COLORMAP)
+
+PNG_IMAGE macros
+
+These are convenience macros to derive information from a png_image
+structure.  The PNG_IMAGE_SAMPLE_ macros return values appropriate to the
+actual image sample values - either the entries in the color-map or the
+pixels in the image.  The PNG_IMAGE_PIXEL_ macros return corresponding values
+for the pixels and will always return 1 after a call to
+png_image_{read,write}_colormap.  The remaining macros return information
+about the rows in the image and the complete image.
+
+NOTE: All the macros that take a png_image::format parameter are compile time
+constants if the format parameter is, itself, a constant.  Therefore these
+macros can be used in array declarations and case labels where required.
+Similarly the macros are also pre-processor constants (sizeof is not used) so
+they can be used in #if tests.
+
+First the information about the samples.
+
+  PNG_IMAGE_SAMPLE_CHANNELS(fmt)
+    Returns the total number of channels in a given format: 1..4
+
+  PNG_IMAGE_SAMPLE_COMPONENT_SIZE(fmt)
+    Returns the size in bytes of a single component of a pixel or color-map
+    entry (as appropriate) in the image.
+
+  PNG_IMAGE_SAMPLE_SIZE(fmt)
+    This is the size of the sample data for one sample.  If the image is
+    color-mapped it is the size of one color-map entry (and image pixels are
+    one byte in size), otherwise it is the size of one image pixel.
+
+  PNG_IMAGE_COLORMAP_SIZE(fmt)
+   The size of the color-map required by the format; this is the size of the
+   color-map buffer passed to the png_image_{read,write}_colormap APIs, it is
+   a fixed number determined by the format so can easily be allocated on the
+   stack if necessary.
+
+#define PNG_IMAGE_MAXIMUM_COLORMAP_COMPONENTS(fmt)\
+   (PNG_IMAGE_SAMPLE_CHANNELS(fmt) * 256)
+   /* The maximum size of the color-map required by the format expressed in a
+    * count of components.  This can be used to compile-time allocate a
+    * color-map:
+    *
+    * png_uint_16 colormap[PNG_IMAGE_MAXIMUM_COLORMAP_COMPONENTS(linear_fmt)];
+    *
+    * png_byte colormap[PNG_IMAGE_MAXIMUM_COLORMAP_COMPONENTS(sRGB_fmt)];
+    *
+    * Alternatively use the PNG_IMAGE_COLORMAP_SIZE macro below to use the
+    * information from one of the png_image_begin_read_ APIs and dynamically
+    * allocate the required memory.
+    */
+
+
+Corresponding information about the pixels
+
+  PNG_IMAGE_PIXEL_(test,fmt)
+
+  PNG_IMAGE_PIXEL_CHANNELS(fmt)
+   The number of separate channels (components) in a pixel; 1 for a
+   color-mapped image.
+
+  PNG_IMAGE_PIXEL_COMPONENT_SIZE(fmt)\
+   The size, in bytes, of each component in a pixel; 1 for a color-mapped
+   image.
+
+  PNG_IMAGE_PIXEL_SIZE(fmt)
+   The size, in bytes, of a complete pixel; 1 for a color-mapped image.
+
+Information about the whole row, or whole image
+
+  PNG_IMAGE_ROW_STRIDE(image)
+   Returns the total number of components in a single row of the image; this
+   is the minimum 'row stride', the minimum count of components between each
+   row.  For a color-mapped image this is the minimum number of bytes in a
+   row.
+
+  PNG_IMAGE_BUFFER_SIZE(image, row_stride)
+    Returns the size, in bytes, of an image buffer given a png_image and a row
+    stride - the number of components to leave space for in each row.
+
+  PNG_IMAGE_FLAG_COLORSPACE_NOT_sRGB == 0x01
+    This indicates the the RGB values of the in-memory bitmap do not
+    correspond to the red, green and blue end-points defined by sRGB.
+
+  PNG_IMAGE_FLAG_COLORMAP == 0x02
+    The PNG is color-mapped.  If this flag is set png_image_read_colormap
+    can be used without further loss of image information.  If it is not set
+    png_image_read_colormap will cause significant loss if the image has any
+
+READ APIs
+
+   The png_image passed to the read APIs must have been initialized by setting
+   the png_controlp field 'opaque' to NULL (or, better, memset the whole thing.)
+
+   int png_image_begin_read_from_file( png_imagep image,
+     const char *file_name)
+
+     The named file is opened for read and the image header
+     is filled in from the PNG header in the file.
+
+   int png_image_begin_read_from_stdio (png_imagep image,
+     FILE* file)
+
+      The PNG header is read from the stdio FILE object.
+
+   int png_image_begin_read_from_memory(png_imagep image,
+      png_const_voidp memory, png_size_t size)
+
+      The PNG header is read from the given memory buffer.
+
+   int png_image_finish_read(png_imagep image,
+      png_colorp background, void *buffer,
+      png_int_32 row_stride, void *colormap));
+
+      Finish reading the image into the supplied buffer and
+      clean up the png_image structure.
+
+      row_stride is the step, in png_byte or png_uint_16 units
+      as appropriate, between adjacent rows.  A positive stride
+      indicates that the top-most row is first in the buffer -
+      the normal top-down arrangement.  A negative stride
+      indicates that the bottom-most row is first in the buffer.
+
+      background need only be supplied if an alpha channel must
+      be removed from a png_byte format and the removal is to be
+      done by compositing on a solid color; otherwise it may be
+      NULL and any composition will be done directly onto the
+      buffer.  The value is an sRGB color to use for the
+      background, for grayscale output the green channel is used.
+
+      For linear output removing the alpha channel is always done
+      by compositing on black.
+
+   void png_image_free(png_imagep image)
+
+      Free any data allocated by libpng in image->opaque,
+      setting the pointer to NULL.  May be called at any time
+      after the structure is initialized.
+
+When the simplified API needs to convert between sRGB and linear colorspaces,
+the actual sRGB transfer curve defined in the sRGB specification (see the
+article at http://en.wikipedia.org/wiki/SRGB) is used, not the gamma=1/2.2
+approximation used elsewhere in libpng.
+
+WRITE APIS
+
+For write you must initialize a png_image structure to describe the image to
+be written:
+
+   version: must be set to PNG_IMAGE_VERSION
+   opaque: must be initialized to NULL
+   width: image width in pixels
+   height: image height in rows
+   format: the format of the data you wish to write
+   flags: set to 0 unless one of the defined flags applies; set
+      PNG_IMAGE_FLAG_COLORSPACE_NOT_sRGB for color format images
+      where the RGB values do not correspond to the colors in sRGB.
+   colormap_entries: set to the number of entries in the color-map (0 to 256)
+
+   int png_image_write_to_file, (png_imagep image,
+      const char *file, int convert_to_8bit, const void *buffer,
+      png_int_32 row_stride, const void *colormap));
+
+      Write the image to the named file.
+
+   int png_image_write_to_stdio(png_imagep image, FILE *file,
+      int convert_to_8_bit, const void *buffer,
+      png_int_32 row_stride, const void *colormap)
+
+      Write the image to the given (FILE*).
+
+With all write APIs if image is in one of the linear formats with
+(png_uint_16) data then setting convert_to_8_bit will cause the output to be
+a (png_byte) PNG gamma encoded according to the sRGB specification, otherwise
+a 16-bit linear encoded PNG file is written.
+
+With all APIs row_stride is handled as in the read APIs - it is the spacing
+from one row to the next in component sized units (float) and if negative
+indicates a bottom-up row layout in the buffer.
+
+Note that the write API does not support interlacing, sub-8-bit pixels,
+and indexed (paletted) images.
+
+.SH VI. Modifying/Customizing libpng
 
 There are two issues here.  The first is changing how libpng does
 standard things like memory allocation, input/output, and error handling.
@@ -4064,6 +4485,15 @@ compiler documentation for more details.  For an alternative approach, you
 may wish to use the "cexcept" facility (see http://cexcept.sourceforge.net),
 which is illustrated in pngvalid.c and in contrib/visupng.
 
+Beginning in libpng-1.4.0, the png_set_benign_errors() API became available.
+You can use this to handle certain errors (normally handled as errors)
+as warnings.
+
+    png_set_benign_errors (png_ptr, int allowed);
+
+    allowed: 0: (default) treat png_benign_error() an error.
+             1: treat png_benign_error() as a warning.
+
 .SS Custom chunks
 
 If you need to read or write custom chunks, you may need to get deeper
@@ -4353,7 +4783,18 @@ When PNG_DEBUG = 1, the macros are defined, but only png_debug statements
 having level = 0 will be printed.  There aren't any such statements in
 this version of libpng, but if you insert some they will be printed.
 
-.SH VI.  MNG support
+.SS Prepending a prefix to exported symbols
+
+Starting with libpng-1.6.0, you can configure libpng (when using the
+"configure" script) to prefix all exported symbols by means of the
+configuration option "--with-libpng-prefix=FOO_", where FOO_ can be any
+string beginning with a letter and containing only uppercase
+and lowercase letters, digits, and the underscore (i.e., a C language
+identifier).  This creates a set of macros in pnglibconf.h, so this is
+transparent to applications; their function calls get transformed by
+the macros to use the modified names.
+
+.SH VII.  MNG support
 
 The MNG specification (available at http://www.libpng.org/pub/mng) allows
 certain extensions to PNG for PNG images that are embedded in MNG datastreams.
@@ -4380,7 +4821,7 @@ or any other MNG chunks; your application must provide its own support for
 them.  You may wish to consider using libmng (available at
 http://www.libmng.com) instead.
 
-.SH VII.  Changes to Libpng from version 0.88
+.SH VIII.  Changes to Libpng from version 0.88
 
 It should be noted that versions of libpng later than 0.96 are not
 distributed by the original libpng author, Guy Schalnat, nor by
@@ -4432,7 +4873,7 @@ application:
 
    png_uint_32 application_vn = PNG_LIBPNG_VER;
 
-.SH VIII.  Changes to Libpng from version 1.0.x to 1.2.x
+.SH IX.  Changes to Libpng from version 1.0.x to 1.2.x
 
 Support for user memory management was enabled by default.  To
 accomplish this, the functions png_create_read_struct_2(),
@@ -4529,7 +4970,7 @@ which also expands tRNS to alpha was replaced with
     png_set_expand_gray_1_2_4_to_8()
 which does not. It has been deprecated since libpng-1.0.18 and 1.2.9.
 
-.SH IX.  Changes to Libpng from version 1.0.x/1.2.x to 1.4.x
+.SH X.  Changes to Libpng from version 1.0.x/1.2.x to 1.4.x
 
 Private libpng prototypes and macro definitions were moved from
 png.h and pngconf.h into a new pngpriv.h header file.
@@ -4584,8 +5025,8 @@ png_get_mmx_bitdepth_threshold(), png_get_mmx_rowbytes_threshold(),
 png_set_asm_flags(), and png_mmx_supported()
 
 We removed the obsolete png_check_sig(), png_memcpy_check(), and
-png_memset_check() functions.  Instead use !png_sig_cmp(), png_memcpy(),
-and png_memset(), respectively.
+png_memset_check() functions.  Instead use !png_sig_cmp(), memcpy(),
+and memset(), respectively.
 
 The function png_set_gray_1_2_4_to_8() was removed. It has been
 deprecated since libpng-1.0.18 and 1.2.9, when it was replaced with
@@ -4639,20 +5080,41 @@ was renamed to PNG_READ_QUANTIZE_SUPPORTED.
 
 We removed the trailing '.' from the warning and error messages.
 
-.SH X.  Changes to Libpng from version 1.4.x to 1.5.x
+.SH XI.  Changes to Libpng from version 1.4.x to 1.5.x
 
 From libpng-1.4.0 until 1.4.4, the png_get_uint_16 macro (but not the
 function) incorrectly returned a value of type png_uint_32.
 
 Checking for invalid palette index on read or write was added at libpng
 1.5.10.  When an invalid index is found, libpng issues a benign error.
-This is enabled by default but can be disabled in each png_ptr with
+This is enabled by default because this condition is an error according
+to the PNG specification, Clause 11.3.2, but the error can be ignored in
+each png_ptr with
 
    png_set_check_for_invalid_index(png_ptr, allowed);
 
       allowed  - one of
-                 0: disable
-                 1: enable
+                 0: disable benign error (accept the
+                    invalid data without warning).
+                 1: enable benign error (treat the
+                    invalid data as an error or a
+                    warning).
+
+If the error is ignored, or if png_benign_error() treats it as a warning,
+any invalid pixels are decoded as opaque black by the decoder and written
+as-is by the encoder.
+
+Retrieving the maximum palette index found was added at libpng-1.5.15.
+This statement must appear after png_read_png() or png_read_image() while
+reading, and after png_write_png() or png_write_image() while writing.
+
+   int max_palette = png_get_palette_max(png_ptr, info_ptr);
+
+This will return the maximum palette index found in the image, or "-1" if
+the palette was not checked, or "0" if no palette was found.  Note that this
+does not account for any palette index used by ancillary chunks such as the
+bKGD chunk; you must check those separately to determine the maximum
+palette index actually used.
 
 A. Changes that affect users of libpng
 
@@ -4662,9 +5124,10 @@ members of the main libpng control structures, png_struct and png_info,
 deprecated in earlier versions of libpng, has been completely removed from
 libpng 1.5.
 
-We no longer include zlib.h in png.h.  Applications that need access
-to information in zlib.h will need to add the '#include "zlib.h"'
-directive.  It does not matter whether it is placed prior to or after
+We no longer include zlib.h in png.h.  The include statement has been moved
+to pngstruct.h, where it is not accessible by applications. Applications that
+need access to information in zlib.h will need to add the '#include "zlib.h"'
+directive.  It does not matter whether this is placed prior to or after
 the '"#include png.h"' directive.
 
 The png_sprintf(), png_strcpy(), and png_strncpy() macros are no longer used
@@ -4955,7 +5418,83 @@ pngusr.h a system builder may also define equivalent options in pngusr.dfa
 DFA_XTRA to the file name.  The makefiles in contrib/pngminim illustrate
 how to do this, and a case where pngusr.h is still required.
 
-.SH XI. Detecting libpng
+.SH XII.  Changes to Libpng from version 1.5.x to 1.6.x
+
+A "simplified API" has been added (see documentation in png.h and a simple
+example in contrib/examples/pngtopng.c).  The new publicly visible API
+includes the following:
+
+   macros:
+     PNG_FORMAT_*
+     PNG_IMAGE_*
+   structures:
+     png_control
+     png_image
+   read functions
+     png_image_begin_read_from_file()
+     png_image_begin_read_from_stdio()
+     png_image_begin_read_from_memory()
+     png_image_finish_read()
+     png_image_free()
+   write functions
+     png_image_write_to_file()
+     png_image_write_to_stdio()
+
+Starting with libpng-1.6.0, you can configure libpng to prefix all exported
+symbols, using the PNG_PREFIX macro.
+
+We no longer include string.h in png.h.  The include statement has been moved
+to pngpriv.h, where it is not accessible by applications.  Applications that
+need access to information in string.h must add an '#include "string.h"'
+directive.  It does not matter whether this is placed prior to or after
+the '"#include png.h"' directive.
+
+The following API are now DEPRECATED:
+   png_info_init_3()
+   png_convert_to_rfc1123() which has been replaced
+     with png_convert_to_rfc1123_buffer()
+   png_data_freer()
+   png_malloc_default()
+   png_free_default()
+   png_reset_zstream()
+
+The following has been removed:
+   png_get_io_chunk_name(), which has been replaced
+     with png_get_io_chunk_type().  The new
+     function returns a 32-bit integer instead of
+     a string.
+   The png_sizeof(), png_strlen(), png_memcpy(), png_memcmp(), and
+     png_memset() macros are no longer used in the libpng sources and
+     have been removed.  These had already been made invisible to applications
+     (i.e., defined in the private pngpriv.h header file) since libpng-1.5.0.
+
+The signatures of many exported functions were changed, such that
+   png_structp became png_structrp or png_const_structrp
+   png_infop became png_inforp or png_const_inforp
+where "rp" indicates a "restricted pointer".
+
+Error detection in some chunks has improved; in particular the iCCP chunk
+reader now does pretty complete validation of the basic format.  Some bad
+profiles that were previously accepted are now rejected, in particular the
+very old broken Microsoft/HP sRGB profile.
+
+The library now issues a warning if both background processing and RGB to
+gray are used when gamma correction happens. As with previous versions of
+the library the results are numerically very incorrect in this case.
+
+There are some minor arithmetic changes in some transforms such as
+png_set_background(), that might be detected by certain regression tests.
+
+Unknown chunk handling has been improved internally, without any API change.
+This adds more correct option control of the unknown handling, corrects
+a pre-existing bug where the per-chunk 'keep' setting is ignored, and makes
+it possible to skip IDAT chunks in the sequential reader.
+
+The machine-generated configure files are no longer included in branches
+libpng16 and later of the GIT repository.  They continue to be included
+in the tarball releases, however.
+
+.SH XIII.  Detecting libpng
 
 The png_get_io_ptr() function has been present since libpng-0.88, has never
 changed, and is unaffected by conditional compilation macros.  It is the
@@ -4964,7 +5503,7 @@ libpng version since 0.88.  In an autoconf "configure.in" you could use
 
     AC_CHECK_LIB(png, png_get_io_ptr, ...
 
-.SH XII. Source code repository
+.SH XV. Source code repository
 
 Since about February 2009, version 1.2.34, libpng has been under "git" source
 control.  The git repository was built from old libpng-x.y.z.tar.gz files
@@ -4988,7 +5527,7 @@ simple verbal discriptions of bug fixes, reported either to the
 SourceForge bug tracker, to the png-mng-implement at lists.sf.net
 mailing list, or directly to glennrp.
 
-.SH XIII. Coding style
+.SH XV. Coding style
 
 Our coding style is similar to the "Allman" style, with curly
 braces on separate lines:
@@ -5073,6 +5612,17 @@ above the comment that says
 
   /* Maintainer: Put new private prototypes here ^ */
 
+We put a space after the "sizeof" operator and we omit the
+optional parentheses around its argument when the argument
+is an expression, not a type name, and we always enclose the
+sizeof operator, with its argument, in parentheses:
+
+  (sizeof (png_uint_32))
+  (sizeof array)
+
+Prior to libpng-1.6.0 we used a "png_sizeof()" macro, formatted as
+though it were a function.
+
 To avoid polluting the global namespace, the names of all exported
 functions and variables begin with "png_", and all publicly visible C
 preprocessor macros begin with "PNG".  We request that applications that
@@ -5094,33 +5644,36 @@ when there is only one macro being tested.
 We prefer to express integers that are used as bit masks in hex format,
 with an even number of lower-case hex digits (e.g., 0x00, 0xff, 0x0100).
 
+We prefer to use underscores in variable names rather than camelCase, except
+for a few type names that we inherit from zlib.h.
+
 We do not use the TAB character for indentation in the C sources.
 
 Lines do not exceed 80 characters.
 
 Other rules can be inferred by inspecting the libpng source.
 
-.SH XIV. Y2K Compliance in libpng
+.SH XVI. Y2K Compliance in libpng
 
-January 24, 2013
+February 14, 2013
 
 Since the PNG Development group is an ad-hoc body, we can't make
 an official declaration.
 
 This is your unofficial assurance that libpng from version 0.71 and
-upward through 1.5.14 are Y2K compliant.  It is my belief that earlier
+upward through 1.6.0 are Y2K compliant.  It is my belief that earlier
 versions were also Y2K compliant.
 
-Libpng only has two year fields.  One is a 2-byte unsigned integer that
-will hold years up to 65535.  The other holds the date in text
-format, and will hold years up to 9999.
+Libpng only has two year fields.  One is a 2-byte unsigned integer
+that will hold years up to 65535.  The other, which is deprecated,
+holds the date in text format, and will hold years up to 9999.
 
 The integer is
     "png_uint_16 year" in png_time_struct.
 
 The string is
-    "char time_buffer[29]" in png_struct.  This will no
-longer be used in libpng-1.6.x and will be removed from libpng-1.7.0.
+    "char time_buffer[29]" in png_struct.  This is no longer used
+in libpng-1.6.x and will be removed from libpng-1.7.0.
 
 There are seven time-related functions:
 
@@ -5313,24 +5866,9 @@ the first widely used release:
  1.5.7beta01-05      15    10507  15.so.15.7[.0]
  1.5.7rc01-03        15    10507  15.so.15.7[.0]
  1.5.7               15    10507  15.so.15.7[.0]
- 1.5.8beta01         15    10508  15.so.15.8[.0]
- 1.5.8rc01           15    10508  15.so.15.8[.0]
- 1.5.8               15    10508  15.so.15.8[.0]
- 1.5.9beta01-02      15    10509  15.so.15.9[.0]
- 1.5.9rc01           15    10509  15.so.15.9[.0]
- 1.5.9               15    10509  15.so.15.9[.0]
- 1.5.10beta01-05     15    10510  15.so.15.10[.0]
- 1.5.10              15    10510  15.so.15.10[.0]
- 1.5.11beta01        15    10511  15.so.15.11[.0]
- 1.5.11rc01-05       15    10511  15.so.15.11[.0]
- 1.5.11              15    10511  15.so.15.11[.0]
- 1.5.12              15    10512  15.so.15.12[.0]
- 1.5.13beta01-02     15    10513  15.so.15.13[.0]
- 1.5.13rc01          15    10513  15.so.15.13[.0]
- 1.5.13              15    10513  15.so.15.13[.0]
- 1.5.14beta01-08     15    10514  15.so.15.14[.0]
- 1.5.14rc01-03       15    10514  15.so.15.14[.0]
- 1.5.14              15    10514  15.so.15.14[.0]
+ 1.6.0beta01-40      16    10600  16.so.16.0[.0]
+ 1.6.0rc01-08        16    10600  16.so.16.0[.0]
+ 1.6.0               16    10600  16.so.16.0[.0]
 
 Henceforth the source version will match the shared-library minor
 and patch numbers; the shared-library major version number will be
@@ -5387,7 +5925,7 @@ possible without all of you.
 
 Thanks to Frank J. T. Wojcik for helping with the documentation.
 
-Libpng version 1.5.14 - January 24, 2013:
+Libpng version 1.6.0 - February 14, 2013:
 Initially created in 1995 by Guy Eric Schalnat, then of Group 42, Inc.
 Currently maintained by Glenn Randers-Pehrson (glennrp at users.sourceforge.net).
 
@@ -5410,7 +5948,7 @@ this sentence.
 
 This code is released under the libpng license.
 
-libpng versions 1.2.6, August 15, 2004, through 1.5.14, January 24, 2013, are
+libpng versions 1.2.6, August 15, 2004, through 1.6.0, February 14, 2013, are
 Copyright (c) 2004,2006-2007 Glenn Randers-Pehrson, and are
 distributed according to the same disclaimer and license as libpng-1.2.5
 with the following individual added to the list of Contributing Authors
@@ -5509,7 +6047,7 @@ certification mark of the Open Source Initiative.
 
 Glenn Randers-Pehrson
 glennrp at users.sourceforge.net
-January 24, 2013
+February 14, 2013
 
 .\" end of man page