From 84b0da9c94899290467f760976bfc7f440bf0ee5 Mon Sep 17 00:00:00 2001 From: Glenn Randers-Pehrson Date: Thu, 10 Nov 2011 06:32:19 -0600 Subject: [PATCH] [libpng15] Updated commentary about new API --- png.h | 54 ++++++++++++++++++++++++++++++++++++------------------ pngerror.c | 4 ++-- pngread.c | 10 +++++----- 3 files changed, 43 insertions(+), 25 deletions(-) diff --git a/png.h b/png.h index 61c92d48e..1d4bb5f0b 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 @@ PNG_EXPORT(207, void, png_save_uint_16, (png_bytep buf, unsigned int i)); /******************************************************************************* * SIMPLIFIED API - ******************************************************************************/ -/* + ******************************************************************************* + * * Please read the documentation in libpng-manual.txt if you don't understand * what follows. * @@ -2644,6 +2644,11 @@ PNG_EXPORT(207, void, png_save_uint_16, (png_bytep buf, unsigned int i)); * 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_EXPORT(207, void, png_save_uint_16, (png_bytep buf, unsigned int i)); * 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 @@ typedef struct /* 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 @@ typedef struct * * 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 @@ typedef struct * 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 @@ typedef struct #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 @@ typedef struct #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 @@ PNG_EXPORT(237, int, png_image_finish_read, (png_imagep image, * 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 @@ PNG_EXPORT(240, int, png_image_write_to_stdio, (png_imagep image, FILE *file, * 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 ab16eebf5..74f8cc845 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_safe_warning(png_structp png_ptr, png_const_charp warning_message) { 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 18ed0420d..76344ad72 100644 --- a/pngread.c +++ b/pngread.c @@ -1404,7 +1404,7 @@ png_image_read_header(png_voidp argument) { /* 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 @@ png_image_read_end(png_voidp argument) 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 @@ png_image_read_end(png_voidp argument) 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 @@ png_image_read_end(png_voidp argument) # 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_image_read_end(png_voidp argument) 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!) */