diff options
Diffstat (limited to 'Build/source/libs/libpng/libpng-src/libpng-manual.txt')
-rw-r--r-- | Build/source/libs/libpng/libpng-src/libpng-manual.txt | 100 |
1 files changed, 64 insertions, 36 deletions
diff --git a/Build/source/libs/libpng/libpng-src/libpng-manual.txt b/Build/source/libs/libpng/libpng-src/libpng-manual.txt index 57ebbda4c8b..6cde89ab024 100644 --- a/Build/source/libs/libpng/libpng-src/libpng-manual.txt +++ b/Build/source/libs/libpng/libpng-src/libpng-manual.txt @@ -1,9 +1,9 @@ libpng-manual.txt - A description on how to use and modify libpng - libpng version 1.6.29 - March 16, 2017 + libpng version 1.6.30 - June 28, 2017 Updated and distributed by Glenn Randers-Pehrson <glennrp at users.sourceforge.net> - Copyright (c) 1998-2016 Glenn Randers-Pehrson + Copyright (c) 1998-2017 Glenn Randers-Pehrson This document is released under the libpng license. For conditions of distribution and use, see the disclaimer @@ -11,9 +11,9 @@ libpng-manual.txt - A description on how to use and modify libpng Based on: - libpng versions 0.97, January 1998, through 1.6.29 - March 16, 2017 + libpng versions 0.97, January 1998, through 1.6.30 - June 28, 2017 Updated and distributed by Glenn Randers-Pehrson - Copyright (c) 1998-2016 Glenn Randers-Pehrson + Copyright (c) 1998-2017 Glenn Randers-Pehrson libpng 1.0 beta 6 - version 0.96 - May 28, 1997 Updated and distributed by Andreas Dilger @@ -66,17 +66,17 @@ file format in application programs. The PNG specification (second edition), November 2003, is available as a W3C Recommendation and as an ISO Standard (ISO/IEC 15948:2004 (E)) at -<http://www.w3.org/TR/2003/REC-PNG-20031110/ +<https://www.w3.org/TR/2003/REC-PNG-20031110/ The W3C and ISO documents have identical technical content. The PNG-1.2 specification is available at -<http://png-mng.sourceforge.net/pub/png/spec/1.2/>. +<https://png-mng.sourceforge.io/pub/png/spec/1.2/>. It is technically equivalent to the PNG specification (second edition) but has some additional material. -The PNG-1.0 specification is available as RFC 2083 -<http://png-mng.sourceforge.net/pub/png/spec/1.0/> and as a -W3C Recommendation <http://www.w3.org/TR/REC-png-961001>. +The PNG-1.0 specification is available as RFC 2083 +<https://png-mng.sourceforge.io/pub/png/spec/1.0/> and as a +W3C Recommendation <https://www.w3.org/TR/REC-png-961001>. Some additional chunks are described in the special-purpose public chunks documents at <http://www.libpng.org/pub/png/spec/register/> @@ -101,7 +101,7 @@ majority of the needs of its users. Libpng uses zlib for its compression and decompression of PNG files. Further information about zlib, and the latest version of zlib, can -be found at the zlib home page, <http://zlib.net/>. +be found at the zlib home page, <https://zlib.net/>. The zlib compression utility is a general purpose utility that is useful for more than PNG files, and can be used without libpng. See the documentation delivered with zlib for more details. @@ -1190,7 +1190,20 @@ row_pointers prior to calling png_read_png() with png_set_rows(png_ptr, info_ptr, &row_pointers); Alternatively you could allocate your image in one big block and define -row_pointers[i] to point into the proper places in your block. +row_pointers[i] to point into the proper places in your block, but first +be sure that your platform is able to allocate such a large buffer: + + /* Guard against integer overflow */ + if (height > PNG_SIZE_MAX/(width*pixel_size)) { + png_error(png_ptr,"image_data buffer would be too large"); + } + + png_bytep buffer=png_malloc(png_ptr,height*width*pixel_size); + + for (int i=0; i<height, i++) + row_pointers[i]=buffer+i*width*pixel_size; + + png_set_rows(png_ptr, info_ptr, &row_pointers); If you use png_set_rows(), the application is responsible for freeing row_pointers (and row_pointers[i], if they were separately allocated). @@ -2146,6 +2159,16 @@ are allocating one large chunk, you will need to build an array of pointers to each row, as it will be needed for some of the functions below. +Be sure that your platform can allocate the buffer that you'll need. +libpng internally checks for oversize width, but you'll need to +do your own check for number_of_rows*width*pixel_size if you are using +a multiple-row buffer: + + /* Guard against integer overflow */ + if (number_of_rows > PNG_SIZE_MAX/(width*pixel_size)) { + png_error(png_ptr,"image_data buffer would be too large"); + } + Remember: Before you call png_read_update_info(), the png_get_*() functions return the values corresponding to the original PNG image. After you call png_read_update_info the values refer to the image @@ -3824,7 +3847,7 @@ PNG_FORMAT_FLAG_LINEAR flag below. When the simplified API needs to convert between sRGB and linear colorspaces, the actual sRGB transfer curve defined in the sRGB specification (see the -article at http://en.wikipedia.org/wiki/SRGB) is used, not the gamma=1/2.2 +article at https://en.wikipedia.org/wiki/SRGB) is used, not the gamma=1/2.2 approximation used elsewhere in libpng. When an alpha channel is present it is expected to denote pixel coverage @@ -4088,7 +4111,7 @@ READ APIs When the simplified API needs to convert between sRGB and linear colorspaces, the actual sRGB transfer curve defined in the sRGB specification (see the -article at http://en.wikipedia.org/wiki/SRGB) is used, not the gamma=1/2.2 +article at https://en.wikipedia.org/wiki/SRGB) is used, not the gamma=1/2.2 approximation used elsewhere in libpng. WRITE APIS @@ -4246,8 +4269,6 @@ functions after png_create_*_struct() has been called by calling: png_voidp error_ptr, png_error_ptr error_fn, png_error_ptr warning_fn); - png_voidp error_ptr = png_get_error_ptr(png_ptr); - If NULL is supplied for either error_fn or warning_fn, then the libpng default function will be used, calling fprintf() and/or longjmp() if a problem is encountered. The replacement error functions should have @@ -4259,6 +4280,11 @@ parameters as follows: void user_warning_fn(png_structp png_ptr, png_const_charp warning_msg); +Then, within your user_error_fn or user_warning_fn, you can retrieve +the error_ptr if you need it, by calling + + png_voidp error_ptr = png_get_error_ptr(png_ptr); + The motivation behind using setjmp() and longjmp() is the C++ throw and catch exception handling methods. This makes the code much easier to write, as there is no need to check every return code of every function call. @@ -4266,7 +4292,7 @@ However, there are some uncertainties about the status of local variables after a longjmp, so the user may want to be careful about doing anything after setjmp returns non-zero besides returning itself. Consult your compiler documentation for more details. For an alternative approach, you -may wish to use the "cexcept" facility (see http://cexcept.sourceforge.net), +may wish to use the "cexcept" facility (see https://cexcept.sourceforge.io/), which is illustrated in pngvalid.c and in contrib/visupng. Beginning in libpng-1.4.0, the png_set_benign_errors() API became available. @@ -4494,7 +4520,7 @@ in a MNG datastream. As a minimum, it must have the MNG 8-byte signature and the MHDR and MEND chunks. Libpng does not provide support for these or any other MNG chunks; your application must provide its own support for them. You may wish to consider using libmng (available at -http://www.libmng.com) instead. +https://www.libmng.com/) instead. VIII. Changes to Libpng from version 0.88 @@ -4917,18 +4943,14 @@ PNG_USER_WIDTH_MAX and PNG_USER_HEIGHT_MAX, although this document said that it could be used to override them. Now this function will reduce or increase the limits. -Starting in libpng-1.5.10, the user limits can be set en masse with the -configuration option PNG_SAFE_LIMITS_SUPPORTED. If this option is enabled, -a set of "safe" limits is applied in pngpriv.h. These can be overridden by -application calls to png_set_user_limits(), png_set_user_chunk_cache_max(), -and/or png_set_user_malloc_max() that increase or decrease the limits. Also, -in libpng-1.5.10 the default width and height limits were increased -from 1,000,000 to 0x7fffffff (i.e., made unlimited). Therefore, the -limits are now - default safe +Starting in libpng-1.5.22, default user limits were established. These +can be overridden by application calls to png_set_user_limits(), +png_set_user_chunk_cache_max(), and/or png_set_user_malloc_max(). +The limits are now + max possible default png_user_width_max 0x7fffffff 1,000,000 png_user_height_max 0x7fffffff 1,000,000 - png_user_chunk_cache_max 0 (unlimited) 128 + png_user_chunk_cache_max 0 (unlimited) 1000 png_user_chunk_malloc_max 0 (unlimited) 8,000,000 The png_set_option() function (and the "options" member of the png struct) was @@ -5194,27 +5216,33 @@ control. The git repository was built from old libpng-x.y.z.tar.gz files going back to version 0.70. You can access the git repository (read only) at - git://git.code.sf.net/p/libpng/code + https://github.com/glennrp/libpng or + https://git.code.sf.net/p/libpng/code.git -or you can browse it with a web browser by selecting the "code" button at +or you can browse it with a web browser at - https://sourceforge.net/projects/libpng + https://github.com/glennrp/libpng or + https://sourceforge.net/p/libpng/code/ci/libpng16/tree/ Patches can be sent to glennrp at users.sourceforge.net or to png-mng-implement at lists.sourceforge.net or you can upload them to the libpng bug tracker at - http://libpng.sourceforge.net + https://libpng.sourceforge.io/ + +or as a "pull request" to + + https://github.com/glennrp/libpng/pulls We also accept patches built from the tar or zip distributions, and 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. +mailing list, as github issues, or directly to glennrp. XV. Coding style Our coding style is similar to the "Allman" style -(See http://en.wikipedia.org/wiki/Indent_style#Allman_style), with curly +(See https://en.wikipedia.org/wiki/Indent_style#Allman_style), with curly braces on separate lines: if (condition) @@ -5315,7 +5343,7 @@ Prior to libpng-1.6.0 we used a "png_sizeof()" macro, formatted as though it were a function. Control keywords if, for, while, and switch are always followed by a space -to distinguish them from function calls, which have no trailing space. +to distinguish them from function calls, which have no trailing space. We put a space after each comma and after each semicolon in "for" statements, and we put spaces before and after each @@ -5341,7 +5369,7 @@ for a few type names that we inherit from zlib.h. We prefer "if (something != 0)" and "if (something == 0)" over "if (something)" and if "(!something)", respectively, and for pointers -we prefer "if (some_pointer != NULL)" or "if (some_pointer == NULL)". +we prefer "if (some_pointer != NULL)" or "if (some_pointer == NULL)". We do not use the TAB character for indentation in the C sources. @@ -5355,7 +5383,7 @@ Since the PNG Development group is an ad-hoc body, we can't make an official declaration. This is your unofficial assurance that libpng from version 0.71 and -upward through 1.6.29 are Y2K compliant. It is my belief that earlier +upward through 1.6.30 are Y2K compliant. It is my belief that earlier versions were also Y2K compliant. Libpng only has two year fields. One is a 2-byte unsigned integer |