From 2be8b64af2e0e1fd172886685ab944019f7d739b Mon Sep 17 00:00:00 2001 From: Glenn Randers-Pehrson Date: Thu, 29 Jul 2010 19:09:18 -0500 Subject: [PATCH] [devel] Update documentation --- Makefile.am | 5 + Makefile.in | 5 + libpng-1.5.0beta36.txt | 115 ++++++++++++++++++----- libpng.3 | 205 +++++++++++++++++++++++++++++++++-------- libpngpf.3 | 138 ++++++++++++++++++++++++++- png.h | 13 +-- pngerror.c | 4 +- pngpriv.h | 12 +-- pngrutil.c | 18 +++- scripts/pngwin.def | 1 + scripts/symbols.def | 1 + 11 files changed, 433 insertions(+), 84 deletions(-) diff --git a/Makefile.am b/Makefile.am index bfdb97037..e38dac441 100644 --- a/Makefile.am +++ b/Makefile.am @@ -105,6 +105,11 @@ scripts/pnglibconf.h: @echo "a new one simply make 'scripts/pnglibconf.out' and copy that" >&2 @exit 1 +# The following is necessary to ensure that the local pnglibconf.h is used, not +# an installed one (this can happen immediately after on a clean system if +# 'make test' is the first thing the user does.) +pngvalid.o pngtest.o: pnglibconf.h + SYMBOL_CFLAGS = -DPNGLIB_LIBNAME='PNG@PNGLIB_MAJOR@@PNGLIB_MINOR@_0'\ -DPNGLIB_VERSION='@PNGLIB_VERSION@'\ -DSYMBOL_PREFIX='$(SYMBOL_PREFIX)' diff --git a/Makefile.in b/Makefile.in index a08fb7354..63255b8f9 100644 --- a/Makefile.in +++ b/Makefile.in @@ -1289,6 +1289,11 @@ scripts/pnglibconf.h: @echo "a new one simply make 'scripts/pnglibconf.out' and copy that" >&2 @exit 1 +# The following is necessary to ensure that the local pnglibconf.h is used, not +# an installed one (this can happen immediately after on a clean system if +# 'make test' is the first thing the user does.) +pngvalid.o pngtest.o: pnglibconf.h + .dfn.out: rm -f $@ dfn.c dfn?.out test -d scripts || mkdir scripts diff --git a/libpng-1.5.0beta36.txt b/libpng-1.5.0beta36.txt index eabe1de4a..6c8e5ea3f 100644 --- a/libpng-1.5.0beta36.txt +++ b/libpng-1.5.0beta36.txt @@ -1,6 +1,6 @@ libpng.txt - A description on how to use and modify libpng - libpng version 1.5.0beta36 - July 29, 2010 + libpng version 1.5.0beta36 - July 30, 2010 Updated and distributed by Glenn Randers-Pehrson Copyright (c) 1998-2010 Glenn Randers-Pehrson @@ -11,7 +11,7 @@ libpng.txt - A description on how to use and modify libpng Based on: - libpng versions 0.97, January 1998, through 1.5.0beta36 - July 29, 2010 + libpng versions 0.97, January 1998, through 1.5.0beta36 - July 30, 2010 Updated and distributed by Glenn Randers-Pehrson Copyright (c) 1998-2010 Glenn Randers-Pehrson @@ -99,34 +99,68 @@ same instance of a structure. II. Structures There are two main structures that are important to libpng, png_struct -and png_info. The first, png_struct, is an internal structure that -will not, for the most part, be used by a user except as the first -variable passed to every libpng function call. +and png_info. Both are internal structures that are no longer exposed +in the libpng interface (as of libpng 1.5.0). The png_info structure is designed to provide information about the PNG file. At one time, the fields of png_info were intended to be directly accessible to the user. However, this tended to cause problems with applications using dynamically loaded libraries, and as a result a set of interface functions for png_info (the png_get_*() and png_set_*() -functions) was developed. The fields of png_info are still available for -older applications, but it is suggested that applications use the new -interfaces if at all possible. +functions) was developed. -Applications that do make direct access to the members of png_struct (except -for png_ptr->jmpbuf) must be recompiled whenever the library is updated, -and applications that make direct access to the members of png_info must -be recompiled if they were compiled or loaded with libpng version 1.0.6, -in which the members were in a different order. In version 1.0.7, the -members of the png_info structure reverted to the old order, as they were -in versions 0.97c through 1.0.5. Starting with version 2.0.0, both -structures are going to be hidden, and the contents of the structures will -only be accessible through the png_get/png_set functions. +The png_struct structure is the object used by the library to decode a +single image. As of 1.5.0 this structure is also not exposed. + +Almost all libpng APIs require a pointer to a png_struct as the first argument. +Many (in particular the png_set and png_get APIs) also require a pointer +to png_info as the second argument. Some application visible macros +defined in png.h designed for basic data access (reading and writing +integers in the PNG format) break this rule, but it's almost always safe +to assume that a (png_struct*) has to be passed to call an API function. The png.h header file is an invaluable reference for programming with libpng. And while I'm on the topic, make sure you include the libpng header file: #include +Types + +The png.h header file defines a number of integral types used by the +APIs. Most of these are fairly obvious; for example types corresponding +to integers of particular sizes and types for passing color values. + +One exception is how non-integral numbers are handled. For application +convenience most APIs that take such numbers have C (double) arguments, +however internally PNG, and libpng, use 32 bit signed integers and encode +the value by multiplying by 100,000. As of libpng 1.5.0 a convenience +macro PNG_FP_1 is defined in png.h along with a type (png_fixed_point) +which is simply (png_int_32). + +All APIs that take (double) arguments also have an matching API that +takes the corresponding fixed point integer arguments. The fixed point +API has the same name as the floating point one with _fixed appended. +The actual range of values permitted in the APIs is frequently less than +the full range of (png_fixed_point) (-21474 to +21474). When APIs require +a non-negative argument the type is recorded as png_uint_32 above. Consult +the header file and the text below for more information. + +Configuration + +The main header file function declarations are frequently protected by C +preprocessing directives of the form: + + #ifdef PNG_feature_SUPPORTED + declare-function + #endif + +The library can be built without support for these APIs, although a +standard build will have all implemented APIs. Application programs +should check the feature macros before using an API for maximum +portability. From libpng 1.5.0 the feature macros set during the build +of libpng are recorded in the header file "pnglibconf.h" and this file +is always included by png.h. + III. Reading We'll now walk you through the possible functions to call when reading @@ -1152,7 +1186,8 @@ a slightly smaller exponent is better. guess for Mac systems */ } -The png_set_gamma() function handles gamma transformations of the data. +The functions png_set_gamma() and its fixed point equivalent +png_set_gamma_fixed() handle gamma transformations of the data. Pass both the file gamma and the current screen_gamma. If the file does not have a gamma value, you can pass one anyway if you have an idea what it is (usually 0.45455 is a good guess for GIF images on PCs). Note @@ -1356,6 +1391,26 @@ while the sixth pass will be 1/2 as wide and 1/2 as high as the original wide as the original, and 1/2 as high, containing all of the odd numbered scanlines. Phew! +If you want to retrieve the separate images you must pass the correct +number of rows to each successive call of png_read_rows(). +Calculating the number isn't quite as straightforward as the previous +paragraph might suggest; think about what happens with an image with a odd +number of rows, which passes get the extra row? To help you libpng 1.5.0 +implements a function to return the number of rows and columns in the current +pass: + + int number_of_rows = png_get_num_rows(png_ptr); + int number_of_cols = png_get_num_cols(png_ptr); + +Simply call that before each call to png_read_rows(). You must call +png_start_read_image() (or png_read_update_info) before the first call to +ensure that the number libpng holds internally has been updated. + +For very small interlaced images the number of rows or columns in a pass +can be zero. +You don't need to call png_read_rows() in this case, libpng will simply +skip to the next pass. + If you want libpng to expand the images, call this before calling png_start_read_image() or png_read_update_info(): @@ -1368,6 +1423,14 @@ is seven, but may change if another interlace type is added. This function can be called even if the file is not interlaced, where it will return one pass. +If you need to get the number of passes later (for example after the call +to png_start_read_image()) just call: + + number_of_passes = png_get_num_passes(png_ptr); + +This function just returns the number - it doesn't make any changes to the +libpng state. + If you are not going to display the image after each pass, but are going to wait until the entire image is read in, use the sparkle effect. This effect is faster and the end result of either method @@ -2529,9 +2592,11 @@ these functions, call the appropriate png_set_*_fn() function. Memory allocation is done through the functions png_malloc(), png_calloc(), and png_free(). These currently just call the standard C functions. -png_calloc() calls png_malloc() and then png_memset() to clear the newly -allocated memory to zero. If your pointers can't access more then 64K -at a time, you will want to set MAXSEG_64K in zlib.h. Since it is +png_calloc() calls png_malloc() and then clears the newly +allocated memory to zero. There is limited support for certain systems +with segmented memory architectures and the types of pointers declared by +png.h match this; you will have to use appropriate pointers in your +application. Since it is unlikely that the method of handling memory allocation on a platform will change between applications, these functions must be modified in the library at compile time. If you prefer to use a different method @@ -3118,8 +3183,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 @@ -3134,7 +3199,7 @@ to This also applies to the prototype for the user replacement malloc_fn(). The png_calloc() function was added and is used in place of -of "png_malloc(); png_memset();" except in the case in png_read_png() +of "png_malloc(); memset();" except in the case in png_read_png() where the array consists of pointers; in this case a "for" loop is used after the png_malloc() to set the pointers to NULL, to give robust. behavior in case the application runs out of memory part-way through @@ -3301,7 +3366,7 @@ Other rules can be inferred by inspecting the libpng source. XIII. Y2K Compliance in libpng -July 29, 2010 +July 30, 2010 Since the PNG Development group is an ad-hoc body, we can't make an official declaration. diff --git a/libpng.3 b/libpng.3 index 09e0bf6b0..c281f96a0 100644 --- a/libpng.3 +++ b/libpng.3 @@ -1,4 +1,4 @@ -.TH LIBPNG 3 "July 29, 2010" +.TH LIBPNG 3 "July 30, 2010" .SH NAME libpng \- Portable Network Graphics (PNG) Reference Library 1.5.0beta36 .SH SYNOPSIS @@ -200,6 +200,18 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.5.0beta36 \fI\fB +\fBint png_get_num_cols (png_structp \fIpng_ptr\fP\fB);\fP + +\fI\fB + +\fBint png_get_num_passes (png_structp \fIpng_ptr\fP\fB);\fP + +\fI\fB + +\fBint png_get_num_rows (png_structp \fIpng_ptr\fP\fB);\fP + +\fI\fB + \fBpng_uint_32 png_get_oFFs (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fI*offset_x\fP\fB, png_uint_32 \fP\fI*offset_y\fP\fB, int \fI*unit_type\fP\fB);\fP \fI\fB @@ -216,6 +228,10 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.5.0beta36 \fI\fB +\fBpng_fixed_point png_get_pixel_aspect_ratio_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP + +\fI\fB + \fBpng_uint_32 png_get_pixels_per_meter (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP \fI\fB @@ -242,6 +258,18 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.5.0beta36 \fI\fB +\fBvoid png_get_sCAL (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int* \fP\fIunit\fP\fB, double* \fP\fIwidth\fP\fB, double* \fIheight\fP\fB);\fP + +\fI\fB + +\fBvoid png_get_sCAL_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int* \fP\fIunit\fP\fB, png_fixed_pointp \fP\fIwidth\fP\fB, png_fixed_pointp \fIheight\fP\fB);\fP + +\fI\fB + +\fBvoid png_get_sCAL_s (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int* \fP\fIunit\fP\fB, png_charpp \fP\fIwidth\fP\fB, \fIpng_charppheight\fP\fB);\fP + +\fI\fB + \fBpng_bytep png_get_signature (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP \fI\fB @@ -306,6 +334,14 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.5.0beta36 \fI\fB +\fBfloat png_get_x_offset_inches (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP + +\fI\fB + +\fBpng_fixed_point png_get_x_offset_inches_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP + +\fI\fB + \fBpng_int_32 png_get_x_offset_microns (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP \fI\fB @@ -318,6 +354,14 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.5.0beta36 \fI\fB +\fBfloat png_get_y_offset_inches (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP + +\fI\fB + +\fBpng_fixed_point png_get_y_offset_inches_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP + +\fI\fB + \fBpng_int_32 png_get_y_offset_microns (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP \fI\fB @@ -350,14 +394,6 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.5.0beta36 \fI\fB -\fBvoidp png_memcpy (png_voidp \fP\fIs1\fP\fB, png_voidp \fP\fIs2\fP\fB, png_size_t \fIsize\fP\fB);\fP - -\fI\fB - -\fBvoidp png_memset (png_voidp \fP\fIs1\fP\fB, int \fP\fIvalue\fP\fB, png_size_t \fIsize\fP\fB);\fP - -\fI\fB - \fBvoid png_process_data (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_bytep \fP\fIbuffer\fP\fB, png_size_t \fIbuffer_size\fP\fB);\fP \fI\fB @@ -414,6 +450,10 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.5.0beta36 \fI\fB +\fBvoid png_set_background_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_color_16p \fP\fIbackground_color\fP\fB, int \fP\fIbackground_gamma_code\fP\fB, int \fP\fIneed_expand\fP\fB, png_uint_32 \fIbackground_gamma\fP\fB);\fP + +\fI\fB + \fBvoid png_set_bgr (png_structp \fIpng_ptr\fP\fB);\fP \fI\fB @@ -482,6 +522,10 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.5.0beta36 \fI\fB +\fBvoid png_set_filter_heuristics_fixed (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fIheuristic_method\fP\fB, int \fP\fInum_weights\fP\fB, png_fixed_point_p \fP\fIfilter_weights\fP\fB, png_fixed_point_p \fIfilter_costs\fP\fB);\fP + +\fI\fB + \fBvoid png_set_flush (png_structp \fP\fIpng_ptr\fP\fB, int \fInrows\fP\fB);\fP \fI\fB @@ -490,6 +534,10 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.5.0beta36 \fI\fB +\fBvoid png_set_gamma_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fP\fIscreen_gamma\fP\fB, png_uint_32 \fIdefault_file_gamma\fP\fB);\fP + +\fI\fB + \fBvoid png_set_gAMA (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, double \fIfile_gamma\fP\fB);\fP \fI\fB @@ -602,7 +650,7 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.5.0beta36 \fI\fB -\fBvoid png_set_rgb_to_gray_fixed (png_structp \fP\fIpng_ptr\fP\fB, int error_action png_fixed_point \fP\fIred\fP\fB, png_fixed_point \fIgreen\fP\fB);\fP +\fBvoid png_set_rgb_to_gray_fixed (png_structp \fP\fIpng_ptr\fP\fB, int error_action png_uint_32 \fP\fIred\fP\fB, png_uint_32 \fIgreen\fP\fB);\fP \fI\fB @@ -614,7 +662,21 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.5.0beta36 \fI\fB -\fBvoid png_set_sCAL (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_charp \fP\fIunit\fP\fB, double \fP\fIwidth\fP\fB, double \fIheight\fP\fB);\fP +\fBvoid png_set_sCAL (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fP\fIunit\fP\fB, double \fP\fIwidth\fP\fB, double \fIheight\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_sCAL_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fP\fIunit\fP\fB, png_fixed_point \fP\fIwidth\fP\fB, png_fixed_point \fIheight\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_sCAL_s (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fP\fIunit\fP\fB, png_charp \fP\fIwidth\fP\fB, png_charp \fIheight\fP\fB);\fP + +\fI\fB + +\fI\fB + +\fI\fB \fI\fB @@ -789,7 +851,7 @@ Following is a copy of the libpng.txt file that accompanies libpng. .SH LIBPNG.TXT libpng.txt - A description on how to use and modify libpng - libpng version 1.5.0beta36 - July 29, 2010 + libpng version 1.5.0beta36 - July 30, 2010 Updated and distributed by Glenn Randers-Pehrson Copyright (c) 1998-2010 Glenn Randers-Pehrson @@ -800,7 +862,7 @@ libpng.txt - A description on how to use and modify libpng Based on: - libpng versions 0.97, January 1998, through 1.5.0beta36 - July 29, 2010 + libpng versions 0.97, January 1998, through 1.5.0beta36 - July 30, 2010 Updated and distributed by Glenn Randers-Pehrson Copyright (c) 1998-2010 Glenn Randers-Pehrson @@ -888,34 +950,68 @@ same instance of a structure. .SH II. Structures There are two main structures that are important to libpng, png_struct -and png_info. The first, png_struct, is an internal structure that -will not, for the most part, be used by a user except as the first -variable passed to every libpng function call. +and png_info. Both are internal structures that are no longer exposed +in the libpng interface (as of libpng 1.5.0). The png_info structure is designed to provide information about the PNG file. At one time, the fields of png_info were intended to be directly accessible to the user. However, this tended to cause problems with applications using dynamically loaded libraries, and as a result a set of interface functions for png_info (the png_get_*() and png_set_*() -functions) was developed. The fields of png_info are still available for -older applications, but it is suggested that applications use the new -interfaces if at all possible. +functions) was developed. -Applications that do make direct access to the members of png_struct (except -for png_ptr->jmpbuf) must be recompiled whenever the library is updated, -and applications that make direct access to the members of png_info must -be recompiled if they were compiled or loaded with libpng version 1.0.6, -in which the members were in a different order. In version 1.0.7, the -members of the png_info structure reverted to the old order, as they were -in versions 0.97c through 1.0.5. Starting with version 2.0.0, both -structures are going to be hidden, and the contents of the structures will -only be accessible through the png_get/png_set functions. +The png_struct structure is the object used by the library to decode a +single image. As of 1.5.0 this structure is also not exposed. + +Almost all libpng APIs require a pointer to a png_struct as the first argument. +Many (in particular the png_set and png_get APIs) also require a pointer +to png_info as the second argument. Some application visible macros +defined in png.h designed for basic data access (reading and writing +integers in the PNG format) break this rule, but it's almost always safe +to assume that a (png_struct*) has to be passed to call an API function. The png.h header file is an invaluable reference for programming with libpng. And while I'm on the topic, make sure you include the libpng header file: #include +.SS Types + +The png.h header file defines a number of integral types used by the +APIs. Most of these are fairly obvious; for example types corresponding +to integers of particular sizes and types for passing color values. + +One exception is how non-integral numbers are handled. For application +convenience most APIs that take such numbers have C (double) arguments, +however internally PNG, and libpng, use 32 bit signed integers and encode +the value by multiplying by 100,000. As of libpng 1.5.0 a convenience +macro PNG_FP_1 is defined in png.h along with a type (png_fixed_point) +which is simply (png_int_32). + +All APIs that take (double) arguments also have an matching API that +takes the corresponding fixed point integer arguments. The fixed point +API has the same name as the floating point one with _fixed appended. +The actual range of values permitted in the APIs is frequently less than +the full range of (png_fixed_point) (-21474 to +21474). When APIs require +a non-negative argument the type is recorded as png_uint_32 above. Consult +the header file and the text below for more information. + +.SS Configuration + +The main header file function declarations are frequently protected by C +preprocessing directives of the form: + + #ifdef PNG_feature_SUPPORTED + declare-function + #endif + +The library can be built without support for these APIs, although a +standard build will have all implemented APIs. Application programs +should check the feature macros before using an API for maximum +portability. From libpng 1.5.0 the feature macros set during the build +of libpng are recorded in the header file "pnglibconf.h" and this file +is always included by png.h. + .SH III. Reading We'll now walk you through the possible functions to call when reading @@ -1941,7 +2037,8 @@ a slightly smaller exponent is better. guess for Mac systems */ } -The png_set_gamma() function handles gamma transformations of the data. +The functions png_set_gamma() and its fixed point equivalent +png_set_gamma_fixed() handle gamma transformations of the data. Pass both the file gamma and the current screen_gamma. If the file does not have a gamma value, you can pass one anyway if you have an idea what it is (usually 0.45455 is a good guess for GIF images on PCs). Note @@ -2145,6 +2242,26 @@ while the sixth pass will be 1/2 as wide and 1/2 as high as the original wide as the original, and 1/2 as high, containing all of the odd numbered scanlines. Phew! +If you want to retrieve the separate images you must pass the correct +number of rows to each successive call of png_read_rows(). +Calculating the number isn't quite as straightforward as the previous +paragraph might suggest; think about what happens with an image with a odd +number of rows, which passes get the extra row? To help you libpng 1.5.0 +implements a function to return the number of rows and columns in the current +pass: + + int number_of_rows = png_get_num_rows(png_ptr); + int number_of_cols = png_get_num_cols(png_ptr); + +Simply call that before each call to png_read_rows(). You must call +png_start_read_image() (or png_read_update_info) before the first call to +ensure that the number libpng holds internally has been updated. + +For very small interlaced images the number of rows or columns in a pass +can be zero. +You don't need to call png_read_rows() in this case, libpng will simply +skip to the next pass. + If you want libpng to expand the images, call this before calling png_start_read_image() or png_read_update_info(): @@ -2157,6 +2274,14 @@ is seven, but may change if another interlace type is added. This function can be called even if the file is not interlaced, where it will return one pass. +If you need to get the number of passes later (for example after the call +to png_start_read_image()) just call: + + number_of_passes = png_get_num_passes(png_ptr); + +This function just returns the number - it doesn't make any changes to the +libpng state. + If you are not going to display the image after each pass, but are going to wait until the entire image is read in, use the sparkle effect. This effect is faster and the end result of either method @@ -3318,9 +3443,11 @@ these functions, call the appropriate png_set_*_fn() function. Memory allocation is done through the functions png_malloc(), png_calloc(), and png_free(). These currently just call the standard C functions. -png_calloc() calls png_malloc() and then png_memset() to clear the newly -allocated memory to zero. If your pointers can't access more then 64K -at a time, you will want to set MAXSEG_64K in zlib.h. Since it is +png_calloc() calls png_malloc() and then clears the newly +allocated memory to zero. There is limited support for certain systems +with segmented memory architectures and the types of pointers declared by +png.h match this; you will have to use appropriate pointers in your +application. Since it is unlikely that the method of handling memory allocation on a platform will change between applications, these functions must be modified in the library at compile time. If you prefer to use a different method @@ -3907,8 +4034,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 @@ -3923,7 +4050,7 @@ to This also applies to the prototype for the user replacement malloc_fn(). The png_calloc() function was added and is used in place of -of "png_malloc(); png_memset();" except in the case in png_read_png() +of "png_malloc(); memset();" except in the case in png_read_png() where the array consists of pointers; in this case a "for" loop is used after the png_malloc() to set the pointers to NULL, to give robust. behavior in case the application runs out of memory part-way through @@ -4090,7 +4217,7 @@ Other rules can be inferred by inspecting the libpng source. .SH XIII. Y2K Compliance in libpng -July 29, 2010 +July 30, 2010 Since the PNG Development group is an ad-hoc body, we can't make an official declaration. @@ -4332,7 +4459,7 @@ possible without all of you. Thanks to Frank J. T. Wojcik for helping with the documentation. -Libpng version 1.5.0beta36 - July 29, 2010: +Libpng version 1.5.0beta36 - July 30, 2010: Initially created in 1995 by Guy Eric Schalnat, then of Group 42, Inc. Currently maintained by Glenn Randers-Pehrson (glennrp at users.sourceforge.net). @@ -4355,7 +4482,7 @@ this sentence. This code is released under the libpng license. -libpng versions 1.2.6, August 15, 2004, through 1.5.0beta36, July 29, 2010, are +libpng versions 1.2.6, August 15, 2004, through 1.5.0beta36, July 30, 2010, 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 @@ -4454,7 +4581,7 @@ certification mark of the Open Source Initiative. Glenn Randers-Pehrson glennrp at users.sourceforge.net -July 29, 2010 +July 30, 2010 .\" end of man page diff --git a/libpngpf.3 b/libpngpf.3 index 3fd06631e..415032991 100644 --- a/libpngpf.3 +++ b/libpngpf.3 @@ -1,4 +1,4 @@ -.TH LIBPNGPF 3 "July 29, 2010" +.TH LIBPNGPF 3 "July 30, 2010" .SH NAME libpng \- Portable Network Graphics (PNG) Reference Library 1.5.0beta36 (private functions) @@ -7,9 +7,15 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.5.0beta36 \fI\fB -\fBvoid png_64bit_product (long \fP\fIv1\fP\fB, long \fP\fIv2\fP\fB, unsigned long \fI*hi_product, +\fBvoid png_64bit_product (long \fP\fIv1\fP\fB, long \fP\fIv2\fP\fB, unsigned long \fP\fI*hi_product\fP\fB, unsigned long \fI*lo_product\fP\fB);\fP -\fBunsigned long \fI*lo_product\fP\fB);\fP +\fI\fB + +\fI\fB + +\fBvoid png_ascii_from_fp (png_structp \fP\fIpng_ptr\fP\fB, png_charp \fP\fIascii\fP\fB, png_size_t \fP\fIsize\fP\fB, double \fP\fIfp\fP\fB, unsigned \fIprecision\fP\fB);\fP + +\fI\fB \fI\fB @@ -43,6 +49,30 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.5.0beta36 \fI\fB +\fBint png_check_fp_number (png_charp \fP\fIstring\fP\fB, png_size_t \fP\fIsize\fP\fB, int* \fP\fIstatep\fP\fB, png_size_tp \fIwhereami\fP\fB);\fP + +\fI\fB + +\fI\fB + +\fI\fB + +\fI\fB + +\fI\fB + +\fBint png_check_fp_string (png_charp \fP\fIstring\fP\fB, png_size_t \fIsize\fP\fB);\fP + +\fI\fB + +\fI\fB + +\fI\fB + +\fI\fB + +\fI\fB + \fBpng_size_t png_check_keyword (png_structp \fP\fIpng_ptr\fP\fB, png_charp \fP\fIkey\fP\fB, png_charpp \fInew_key\fP\fB);\fP \fI\fB @@ -281,7 +311,21 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.5.0beta36 \fI\fB -\fBvoid *png_far_to_near (png_structp png_ptr,png_voidp \fP\fIptr\fP\fB, int \fIcheck\fP\fB);\fP +\fBvoid *png_far_to_near (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIptr\fP\fB, int \fIcheck\fP\fB);\fP + +\fI\fB + +\fI\fB + +\fI\fB + +\fI\fB + +\fI\fB + +\fBvoid png_fixed_error (png_structp \fP\fIpng_ptr\fP\fB, \fIpng_const_charp + +\fBname, double \fIvalue\fP\fB);\fP \fI\fB @@ -293,6 +337,42 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.5.0beta36 \fI\fB +\fBint png_gamma_significant (png_fixed_point \fIgamma\fP\fB);\fP + +\fI\fB + +\fI\fB + +\fI\fB + +\fI\fB + +\fI\fB + +\fBpng_uint_16 png_gamma_16bit_correct (png_structp \fP\fIpng_ptr\fP\fB, unsigned \fP\fIvalue\fP\fB, png_fixed_point \fIgamma\fP\fB);\fP + +\fI\fB + +\fI\fB + +\fI\fB + +\fI\fB + +\fI\fB + +\fBpng_byte png_gamma_8bit_correct (png_structp \fP\fIpng_ptr\fP\fB, unsigned \fP\fIvalue\fP\fB, png_fixed_point \fIgamma\fP\fB);\fP + +\fI\fB + +\fI\fB + +\fI\fB + +\fI\fB + +\fI\fB + \fBvoid png_handle_bKGD (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fIlength\fP\fB);\fP \fI\fB @@ -437,6 +517,30 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.5.0beta36 \fI\fB +\fBint png_muldiv (png_fixed_point_p \fP\fIres\fP\fB, png_fixed_point \fP\fIa\fP\fB, png_int_32 \fP\fItimes\fP\fB, png_int_32 \fIdiv\fP\fB);\fP + +\fI\fB + +\fI\fB + +\fI\fB + +\fI\fB + +\fI\fB + +\fBpng_fixed_point png_muldiv_warn (png_structp \fP\fIpng_ptr\fP\fB, png_fixed_point \fP\fIa\fP\fB, png_int_32 \fP\fItimes\fP\fB, png_int_32 \fIdiv\fP\fB);\fP + +\fI\fB + +\fI\fB + +\fI\fB + +\fI\fB + +\fI\fB + \fBvoid png_process_IDAT_data (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fP\fIbuffer\fP\fB, png_size_t \fIbuffer_length\fP\fB);\fP \fI\fB @@ -601,6 +705,30 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.5.0beta36 \fI\fB +\fBpng_fixed_point png_reciprocal (png_fixed_point \fIa\fP\fB);\fP + +\fI\fB + +\fI\fB + +\fI\fB + +\fI\fB + +\fI\fB + +\fBpng_fixed_point png_reciprocal2 (png_fixed_point \fP\fIa\fP\fB, png_fixed_point \fIb\fP\fB);\fP + +\fI\fB + +\fI\fB + +\fI\fB + +\fI\fB + +\fI\fB + \fBvoid png_reset_crc (png_structp \fIpng_ptr\fP\fB);\fP \fI\fB @@ -812,7 +940,7 @@ The functions listed above are used privately by libpng and are not recommended for use by applications. They are not "exported" to applications using shared libraries. They are listed alphabetically here as an aid to libpng maintainers. -See png.h for more information on these functions. +See pngpriv.h for more information on these functions. .SH SEE ALSO .BR "png"(5), " libpng"(3), " zlib"(3), " deflate"(5), " " and " zlib"(5) diff --git a/png.h b/png.h index ccc9e992c..fd4e76a16 100644 --- a/png.h +++ b/png.h @@ -1,7 +1,7 @@ /* png.h - header file for PNG reference library * - * libpng version 1.5.0beta36 - July 29, 2010 + * libpng version 1.5.0beta36 - July 30, 2010 * Copyright (c) 1998-2010 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.0beta36 - July 29, 2010: Glenn + * libpng versions 0.97, January 1998, through 1.5.0beta36 - July 30, 2010: Glenn * See also "Contributing Authors", below. * * Note about libpng version numbers: @@ -172,7 +172,7 @@ * * This code is released under the libpng license. * - * libpng versions 1.2.6, August 15, 2004, through 1.5.0beta36, July 29, 2010, are + * libpng versions 1.2.6, August 15, 2004, through 1.5.0beta36, July 30, 2010, are * Copyright (c) 2004, 2006-2010 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: @@ -284,7 +284,7 @@ * Y2K compliance in libpng: * ========================= * - * July 29, 2010 + * July 30, 2010 * * Since the PNG Development group is an ad-hoc body, we can't make * an official declaration. @@ -348,7 +348,7 @@ /* Version information for png.h - this should match the version in png.c */ #define PNG_LIBPNG_VER_STRING "1.5.0beta36" #define PNG_HEADER_VERSION_STRING \ - " libpng version 1.5.0beta36 - July 29, 2010\n" + " libpng version 1.5.0beta36 - July 30, 2010\n" #define PNG_LIBPNG_VER_SONUM 15 #define PNG_LIBPNG_VER_DLLNUM 15 @@ -1092,6 +1092,7 @@ PNG_EXPORT(int,png_set_interlace_handling,(png_structp png_ptr),,45); */ PNG_EXPORT(int,png_get_num_passes,(png_structp png_ptr),,215); PNG_EXPORT(png_uint_32,png_get_num_rows,(png_structp png_ptr),,216); +PNG_EXPORT(png_uint_32,png_get_num_cols,(png_structp png_ptr),,218); #endif #if defined(PNG_READ_INVERT_SUPPORTED) || defined(PNG_WRITE_INVERT_SUPPORTED) @@ -2055,7 +2056,7 @@ PNG_EXPORT(void,png_save_uint_16,(png_bytep buf, unsigned int i),,207); * use is one more than this.) */ #ifdef PNG_EXPORT_LAST_ORDINAL - PNG_EXPORT_LAST_ORDINAL(217); + PNG_EXPORT_LAST_ORDINAL(218); #endif #ifdef __cplusplus diff --git a/pngerror.c b/pngerror.c index 7f1f7b195..363460eb2 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.0 [July 29, 2010] + * Last changed in libpng 1.5.0 [July 30, 2010] * Copyright (c) 1998-2010 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.) @@ -256,7 +256,7 @@ png_fixed_error(png_structp png_ptr, png_const_charp name, double value) msg[fixed_message_ln + iin] = 0; /* To discover 'value' put a breakpoint here: */ png_error(png_ptr, msg); - value = value; png_ptr = png_ptr; /* Quiet the compiler */ + value = value; /* Quiet the compiler */ } #endif #endif diff --git a/pngpriv.h b/pngpriv.h index 68f031b26..b2ebf0d53 100644 --- a/pngpriv.h +++ b/pngpriv.h @@ -1,7 +1,7 @@ /* pngpriv.h - private declarations for use inside libpng * - * libpng version 1.5.0beta36 - July 29, 2010 + * libpng version 1.5.0beta36 - July 30, 2010 * For conditions of distribution and use, see copyright notice in png.h * Copyright (c) 1998-2010 Glenn Randers-Pehrson * (Version 0.96 Copyright (c) 1996, 1997 Andreas Dilger) @@ -1042,8 +1042,8 @@ PNG_EXTERN void png_fixed_error PNGARG((png_structp png_ptr, * maximum ridiculous exponent. */ #define PNG_sCAL_MAX_DIGITS (PNG_sCAL_PRECISION+1/*.*/+1/*E*/+10/*exponent*/) -PNG_EXTERN void png_ascii_from_fp(png_structp png_ptr, png_charp ascii, - png_size_t size, double fp, unsigned precision); +PNG_EXTERN void png_ascii_from_fp PNGARG((png_structp png_ptr, png_charp ascii, + png_size_t size, double fp, unsigned precision)); #endif /* READ_sCAL && FLOATING_POINT */ #if defined(PNG_sCAL_SUPPORTED) || defined(PNG_pCAL_SUPPORTED) @@ -1110,13 +1110,13 @@ PNG_EXTERN void png_ascii_from_fp(png_structp png_ptr, png_charp ascii, * that omits the last character (i.e. set the size to the index of * the problem character.) This has not been tested within libpng. */ -PNG_EXTERN int png_check_fp_number(png_charp string, png_size_t size, - int *statep, png_size_tp whereami); +PNG_EXTERN int png_check_fp_number PNGARG((png_charp string, png_size_t size, + int *statep, png_size_tp whereami)); /* This is the same but it checks a complete string and returns true * only if it just contains a floating point number. */ -PNG_EXTERN int png_check_fp_string(png_charp string, png_size_t size); +PNG_EXTERN int png_check_fp_string PNGARG((png_charp string, png_size_t size)); #endif /* pCAL || sCAL */ #if defined(PNG_READ_GAMMA_SUPPORTED) || defined(PNG_INCH_CONVERSIONS_SUPPORTED) diff --git a/pngrutil.c b/pngrutil.c index 3ae466f59..880da9a94 100644 --- a/pngrutil.c +++ b/pngrutil.c @@ -1,7 +1,7 @@ /* pngrutil.c - utilities to read a PNG file * - * Last changed in libpng 1.4.1 [July 29, 2010] + * Last changed in libpng 1.4.1 [July 30, 2010] * Copyright (c) 1998-2010 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.) @@ -3485,5 +3485,21 @@ png_get_num_rows(png_structp png_ptr) /* Here on error */ return 0; } + +png_uint_32 PNGAPI +png_get_num_cols(png_structp png_ptr) +{ + if (png_ptr != NULL) + { + if (png_ptr->flags & PNG_FLAG_ROW_INIT) + return png_ptr->iwidth; + else + png_error(png_ptr, "Call png_start_read_image or png_read_update_info " + "before png_get_num_cols"); + } + + /* Here on error */ + return 0; +} #endif /* SEQUENTIAL READ */ #endif /* PNG_READ_SUPPORTED */ diff --git a/scripts/pngwin.def b/scripts/pngwin.def index 020d69ba6..05f4aef75 100644 --- a/scripts/pngwin.def +++ b/scripts/pngwin.def @@ -227,3 +227,4 @@ EXPORTS png_get_num_passes @215 png_get_num_rows @216 png_set_background_fixed @217 + png_get_num_cols @218 diff --git a/scripts/symbols.def b/scripts/symbols.def index c449c3bee..1530414dc 100644 --- a/scripts/symbols.def +++ b/scripts/symbols.def @@ -223,3 +223,4 @@ EXPORTS png_get_num_passes @215 png_get_num_rows @216 png_set_background_fixed @217 + png_get_num_cols @218