[libpng15] Updated commentary about new API
This commit is contained in:
Glenn Randers-Pehrson
parent
e6fb691c49
commit
84b0da9c94
54
png.h
54
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 */
|
||||
/*******************************************************************************
|
||||
|
||||
@ -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);
|
||||
|
||||
10
pngread.c
10
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!)
|
||||
*/
|
||||
|
||||
Loading…
Reference in New Issue
Block a user