From 5a956a7a58e22933e7dd550ff13ff35b45ba7e86 Mon Sep 17 00:00:00 2001 From: Glenn Randers-Pehrson Date: Thu, 22 Dec 2011 14:23:37 -0600 Subject: [PATCH] [libpng16] Began a manual section about libpng15 to libpng16 differences. --- libpng-manual.txt | 47 ++++++++++++++++++++++++++++++++++++----------- libpng.3 | 47 ++++++++++++++++++++++++++++++++++++----------- png.h | 4 ++-- 3 files changed, 74 insertions(+), 24 deletions(-) diff --git a/libpng-manual.txt b/libpng-manual.txt index 408cf5cfd..f3bcd03c3 100644 --- a/libpng-manual.txt +++ b/libpng-manual.txt @@ -4145,19 +4145,20 @@ function) incorrectly returned a value of type png_uint_32. A. Changes that affect users of libpng There are no substantial API changes between the non-deprecated parts of -the 1.4.5 API and the 1.5.0 API, however the ability to directly access -the main libpng control structures, png_struct and png_info, deprecated -in earlier versions of libpng, has been completely removed from +the 1.4.5 API and the 1.5.0 API; however the ability to directly access +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. We moved the png_strcpy(), png_strncpy(), png_strlen(), png_memcpy(), png_memcmp(), png_sprintf, and png_memcpy() macros into a private -header file (pngpriv.h) that is not accessible to applications. +header file (pngpriv.h) that is not accessible by applications. In png_get_iCCP, the type of "profile" was changed from png_charpp to png_bytepp, and in png_set_iCCP, from png_charp to png_const_bytep. @@ -4426,7 +4427,31 @@ 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. -XI. Detecting libpng +XI. Changes to Libpng from version 1.5.x to 1.6.x + +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_malloc_default() + png_free_default() + +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. + +A "simplified API" has been added (see documentation in png.h and a simple +example in contrib/examples/pngtopng.c) + +XII. 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 @@ -4435,7 +4460,7 @@ libpng version since 0.88. In an autoconf "configure.in" you could use AC_CHECK_LIB(png, png_get_io_ptr, ... -XII. Source code repository +XIII. 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 @@ -4459,7 +4484,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. -XIII. Coding style +XV. Coding style Our coding style is similar to the "Allman" style, with curly braces on separate lines: @@ -4571,7 +4596,7 @@ Lines do not exceed 80 characters. Other rules can be inferred by inspecting the libpng source. -XIV. Y2K Compliance in libpng +XV. Y2K Compliance in libpng December 22, 2011 diff --git a/libpng.3 b/libpng.3 index 7e1af1526..178796f7e 100644 --- a/libpng.3 +++ b/libpng.3 @@ -5153,19 +5153,20 @@ function) incorrectly returned a value of type png_uint_32. A. Changes that affect users of libpng There are no substantial API changes between the non-deprecated parts of -the 1.4.5 API and the 1.5.0 API, however the ability to directly access -the main libpng control structures, png_struct and png_info, deprecated -in earlier versions of libpng, has been completely removed from +the 1.4.5 API and the 1.5.0 API; however the ability to directly access +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. We moved the png_strcpy(), png_strncpy(), png_strlen(), png_memcpy(), png_memcmp(), png_sprintf, and png_memcpy() macros into a private -header file (pngpriv.h) that is not accessible to applications. +header file (pngpriv.h) that is not accessible by applications. In png_get_iCCP, the type of "profile" was changed from png_charpp to png_bytepp, and in png_set_iCCP, from png_charp to png_const_bytep. @@ -5434,7 +5435,31 @@ 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 XI. Changes to Libpng from version 1.5.x to 1.6.x + +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_malloc_default() + png_free_default() + +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. + +A "simplified API" has been added (see documentation in png.h and a simple +example in contrib/examples/pngtopng.c) + +.SH XII. 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 @@ -5443,7 +5468,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 XIII. 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 @@ -5467,7 +5492,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: @@ -5579,7 +5604,7 @@ Lines do not exceed 80 characters. Other rules can be inferred by inspecting the libpng source. -.SH XIV. Y2K Compliance in libpng +.SH XV. Y2K Compliance in libpng December 22, 2011 diff --git a/png.h b/png.h index b85e6a6d6..2c7bb3e20 100644 --- a/png.h +++ b/png.h @@ -2596,8 +2596,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. + * Please read the documentation in libpng-manual.txt (TODO: write said + * documentation) if you don't understand what follows. * * The simplified API 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