[libpng15] Updated commentary about new API
diff --git a/png.h b/png.h
index 61c92d4..1d4bb5f 100644
--- a/png.h
+++ b/png.h
@@ -1,7 +1,7 @@
/* png.h - header file for PNG reference library
*
- * libpng version 1.5.7beta02 - November 8, 2011
+ * libpng version 1.5.7beta02 - November 9, 2011
* Copyright (c) 1998-2011 Glenn Randers-Pehrson
* (Version 0.96 Copyright (c) 1996, 1997 Andreas Dilger)
* (Version 0.88 Copyright (c) 1995, 1996 Guy Eric Schalnat, Group 42, Inc.)
@@ -11,7 +11,7 @@
* Authors and maintainers:
* libpng versions 0.71, May 1995, through 0.88, January 1996: Guy Schalnat
* libpng versions 0.89c, June 1996, through 0.96, May 1997: Andreas Dilger
- * libpng versions 0.97, January 1998, through 1.5.7beta02 - November 8, 2011: Glenn
+ * libpng versions 0.97, January 1998, through 1.5.7beta02 - November 9, 2011: Glenn
* See also "Contributing Authors", below.
*
* Note about libpng version numbers:
@@ -195,7 +195,7 @@
*
* This code is released under the libpng license.
*
- * libpng versions 1.2.6, August 15, 2004, through 1.5.7beta02, November 8, 2011, are
+ * libpng versions 1.2.6, August 15, 2004, through 1.5.7beta02, November 9, 2011, are
* Copyright (c) 2004, 2006-2011 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:
@@ -307,7 +307,7 @@
* Y2K compliance in libpng:
* =========================
*
- * November 8, 2011
+ * November 9, 2011
*
* Since the PNG Development group is an ad-hoc body, we can't make
* an official declaration.
@@ -373,7 +373,7 @@
/* Version information for png.h - this should match the version in png.c */
#define PNG_LIBPNG_VER_STRING "1.5.7beta02"
#define PNG_HEADER_VERSION_STRING \
- " libpng version 1.5.7beta02 - November 8, 2011\n"
+ " libpng version 1.5.7beta02 - November 9, 2011\n"
#define PNG_LIBPNG_VER_SONUM 15
#define PNG_LIBPNG_VER_DLLNUM 15
@@ -2622,8 +2622,8 @@
/*******************************************************************************
* SIMPLIFIED API
- ******************************************************************************/
-/*
+ *******************************************************************************
+ *
* Please read the documentation in libpng-manual.txt if you don't understand
* what follows.
*
@@ -2644,6 +2644,11 @@
* 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.
@@ -2655,7 +2660,9 @@
* 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:
+ *
*/
+
typedef struct png_control *png_controlp;
typedef struct
{
@@ -2667,14 +2674,21 @@
/* In the event of an error or warning the following field will be set to a
* non-zero value and the 'message' field will contain a '\0' terminated
- * string with the libpng error message.
+ * 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.
+ *
+ * As of libpng-1.5.7 the values are
+ * 0 - no warning or error
+ * 1 - error
+ * 2 - warning
*/
png_uint_32 warning_or_error;
char message[64];
} png_image, *png_imagep;
-/* The pixels (samples) of the image have one to four channels in the range 0 to
- * 1.0:
+/* 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).
@@ -2699,7 +2713,8 @@
*
* 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) the alpha value.
+ * channel: the color/gray channels are scaled (pre-multiplied) by the alpha
+ * value.
*/
/* PNG_FORMAT_*
@@ -2716,8 +2731,8 @@
* 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 will may see an error at run time. You
- * can guard against this by checking for the definition of:
+ * 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
*/
@@ -2751,8 +2766,8 @@
#define PNG_FORMAT_ABGR (PNG_FORMAT_BGRA|PNG_FORMAT_FLAG_AFIRST)
/* Then the linear (png_uint_16) formats. When naming these "Y" is used to
- * indicate a luminance channel. The component order within the pixel is
- * always the same - there is no provision for swapping the order of the
+ * 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.
*/
#define PNG_FORMAT_LINEAR_Y PNG_FORMAT_FLAG_LINEAR
@@ -2810,8 +2825,8 @@
#ifdef PNG_STDIO_SUPPORTED
PNG_EXPORT(234, int, png_image_begin_read_from_file, (png_imagep image,
const char *file_name));
- /* The named file is opened for read and the image filled in from the PNG
- * header in the file.
+ /* The named file is opened for read and the image header is filled in
+ * from the PNG header in the file.
*/
PNG_EXPORT(235, int, png_image_begin_read_from_stdio, (png_imagep image,
@@ -2839,7 +2854,7 @@
* 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 an alpha channel is always done by compositing
+ * For linear output removing the alpha channel is always done by compositing
* on black.
*/
@@ -2880,6 +2895,9 @@
* 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.
*/
#endif /* PNG_SIMPLIFIED_WRITE_SUPPORTED */
/*******************************************************************************
diff --git a/pngerror.c b/pngerror.c
index ab16eeb..74f8cc8 100644
--- a/pngerror.c
+++ b/pngerror.c
@@ -1,7 +1,7 @@
/* pngerror.c - stub functions for i/o and memory allocation
*
- * Last changed in libpng 1.5.6 [November 3, 2011]
+ * Last changed in libpng 1.5.7 [(PENDING RELEASE)]
* Copyright (c) 1998-2011 Glenn Randers-Pehrson
* (Version 0.96 Copyright (c) 1996, 1997 Andreas Dilger)
* (Version 0.88 Copyright (c) 1995, 1996 Guy Eric Schalnat, Group 42, Inc.)
@@ -716,7 +716,7 @@
{
png_imagep image = png_ptr->error_ptr;
- /* A warning is just logged if there is no warning or error. */
+ /* A warning is only logged if there is no prior warning or error. */
if (image->warning_or_error == 0)
{
png_safecat(image->message, sizeof image->message, 0, warning_message);
diff --git a/pngread.c b/pngread.c
index 18ed042..76344ad 100644
--- a/pngread.c
+++ b/pngread.c
@@ -1404,7 +1404,7 @@
{
/* gamma is irrelevant because libpng does gamma correction, what
* matters is if the cHRM chunk doesn't match or, in the absence of
- * cRHM, if the iCCP profile looks to have different end points.
+ * cRHM, if the iCCP profile appears to have different end points.
*/
if (info_ptr->valid & PNG_INFO_cHRM)
{
@@ -1792,7 +1792,7 @@
else /* compose on row: implemented below. */
{
do_local_compose = 1;
- /* This leaves the alpha channel in the output, it has to be
+ /* This leaves the alpha channel in the output, so it has to be
* removed by the code below. Set the encoding to the 'OPTIMIZE'
* one so the code only has to hack on the pixels that require
* composition.
@@ -1804,7 +1804,7 @@
else /* output needs an alpha channel */
{
/* This is tricky because it happens before the swap operation has
- * been accomplished however the swap does *not* swap the added
+ * been accomplished; however, the swap does *not* swap the added
* alpha channel (weird API), so it must be added in the correct
* place.
*/
@@ -1857,7 +1857,7 @@
# ifdef PNG_FORMAT_BGR_SUPPORTED
if (change & PNG_FORMAT_FLAG_BGR)
{
- /* Check only the output format; PNG is never BGR, don't do this if
+ /* Check only the output format; PNG is never BGR; don't do this if
* the output is gray, but fix up the 'format' value in that case.
*/
if (format & PNG_FORMAT_FLAG_COLOR)
@@ -1904,7 +1904,7 @@
png_error(png_ptr, "png_read_image: unsupported transformation");
}
- /* Update the 'info' structure and make sure the result is as required, first
+ /* Update the 'info' structure and make sure the result is as required; first
* make sure to turn on the interlace handling if it will be required
* (because it can't be turned on *after* the call to png_read_update_info!)
*/
